> ## 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.

# Boas práticas

> Como usar webhooks e outras estratégias para evitar atingir o rate limit da API Yampi.

## Usando webhooks para reduzir requisições

Em vez de consultar a API repetidamente, você pode utilizar **webhooks** para receber notificações em tempo real sempre que um evento ocorrer na plataforma. Isso reduz significativamente o volume de requisições e o risco de atingir o rate limit.

**Eventos recomendados para substituir consultas recorrentes:**

| Caso de uso                        | Evento do webhook           |
| ---------------------------------- | --------------------------- |
| Monitorar novos pedidos            | `order.created`             |
| Acompanhar pagamentos aprovados    | `order.paid`                |
| Atualização de status de pedidos   | `order.status.updated`      |
| Notificação de carrinho abandonado | `cart.reminder`             |
| Atualização de estoque             | `product.inventory.updated` |
| Novo cliente criado                | `customer.created`          |

Para saber como configurar e validar webhooks, consulte a [documentação de Webhooks](https://docs.yampi.com.br/api-reference/webhooks/introduction).

***

## Boas práticas

<AccordionGroup>
  <Accordion title="Implemente um retry after">
    Ao receber um `HTTP 429`, aguarde antes de reenviar a requisição. Utilize uma política de retry que se adapte as regras da rota.
  </Accordion>

  <Accordion title="Evite consultas desnecessárias">
    Não consulte a API em intervalos fixos e curtos apenas para verificar se houve alterações. Prefira webhooks para ser notificado proativamente sobre eventos relevantes.
  </Accordion>

  <Accordion title="Centralize e reutilize respostas">
    Implemente cache local para respostas GET que não precisam ser atualizadas a cada requisição. Utilize o parâmetro `skipCache=true` somente quando realmente necessário.
  </Accordion>

  <Accordion title="Processe em lote quando possível">
    Prefira endpoints que suportam operações em massa (batch) em vez de fazer chamadas individuais para cada item. Exemplo: use o endpoint de atualização em lote de SKUs.
  </Accordion>

  <Accordion title="Monitore os headers de rate limit">
    Verifique sempre os headers `X-RateLimit-Remaining` nas respostas. Ao detectar que a cota está próxima de zero, reduza proativamente a frequência das requisições.
  </Accordion>

  <Accordion title="Distribua requisições ao longo do tempo">
    Evite realizar muitas requisições simultaneamente. Use filas e distribua as chamadas ao longo do tempo, especialmente em integrações de sincronização de dados.
  </Accordion>
</AccordionGroup>

***

## Como evitar que o limite seja atingido

1. **Utilize webhooks** no lugar de consultas para eventos assíncronos.
2. **Implemente cache** para dados que mudam com pouca frequência (ex.: categorias, variações).
3. **Use includes** para reduzir chamadas encadeadas: `?include=skus,images` retorna tudo em uma única requisição.
4. **Processe em fila**: enfileire requisições e controle a taxa de envio pela sua aplicação.
5. **Monitore ativamente** os headers de rate limit e ajuste a frequência de chamadas antes de atingir o limite.
6. **Evite sincronizações completas** em horários de pico — prefira sincronizações incrementais baseadas em eventos.