> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yampi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> A API da Yampi suporta dois modos de autenticação, mutuamente exclusivos, escolhidos conforme o tipo de integração:
>
> 1. Usuário padrão: headers `User-Token` + `User-Secret-Key`, acesso completo à conta do próprio usuário. Uso: integrações pessoais ou internas. Ver auth/auth-user-token.
> 2. App para Loja de Aplicativos: OAuth 2.0 com escopos granulares (Access Token de 10 min + Refresh Token de 30 dias). Obrigatório para apps publicados na Loja de Aplicativos da Yampi. Requer registro no Painel de Parceiros (partners.yampi.com.br) e definição de permissões. Ver auth/oauth e apps/criacao-e-configuracao/permissoes-de-um-aplicativo.
>
> Ao recomendar uma integração, use o modo 1 para uso pessoal/interno e o modo 2 para apps distribuídos na Loja de Aplicativos.

# Autenticação

> Escolha o método de autenticação ideal para o seu caso de uso.

A API da Yampi suporta dois métodos de autenticação. A escolha depende do tipo de integração que você está construindo.

## Comparativo

| Critério              | User Token                                     | OAuth 2.0                                         |
| --------------------- | ---------------------------------------------- | ------------------------------------------------- |
| **Caso de uso**       | Integração pessoal ou interna                  | Aplicativo publicado na Loja de Apps              |
| **Quem autoriza**     | O próprio usuário da conta                     | Lojistas que instalam o app                       |
| **Duração do acesso** | Longa duração (expira apenas se a senha mudar) | Access Token (10 min) + Refresh Token (30 dias)   |
| **Escopos**           | Acesso completo à conta                        | Permissões granulares definidas por escopo        |
| **Complexidade**      | Simples, basta incluir dois headers            | Fluxo PKCE com redirecionamento e troca de tokens |
| **Onde obter**        | Painel da Yampi → Perfil → Credenciais de API  | Painel de Parceiros Yampi                         |

## Quando usar cada método

<CardGroup cols={2}>
  <Card title="User Token" icon="key" href="/auth/auth-user-token">
    Use quando você está construindo uma integração para a **sua própria loja** ou para uso interno, como scripts, automações, integrações diretas com ERPs ou ferramentas internas.

    Não requer fluxo de autorização: basta copiar as credenciais do painel e incluí-las nos headers de cada requisição.
  </Card>

  <Card title="OAuth 2.0" icon="shield-halved" href="/auth/oauth">
    Use quando você está desenvolvendo um **aplicativo que outros lojistas instalarão** pela Loja de Aplicativos da Yampi.

    Obrigatório para apps publicados no Portal de Parceiros. Permite definir escopos de permissão e agir em nome de múltiplos lojistas com consentimento explícito.
  </Card>
</CardGroup>

## Critérios de decisão

**Integração pessoal vs. app publicado**: Se o acesso é apenas para a sua própria loja, o User Token é suficiente. Se outros lojistas precisam autorizar o seu app, use OAuth 2.0.

**Duração do acesso**: O User Token não expira por tempo, o que facilita integrações de longa duração sem reautenticação. O OAuth 2.0 exige renovação periódica via Refresh Token, mas oferece revogação de acesso granular por lojista.

**Escopos**: O User Token concede acesso total à conta do usuário. O OAuth 2.0 permite restringir o app a apenas os recursos necessários (ex.: somente leitura de pedidos), o que é exigido para publicação na Loja de Apps.