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

# Perguntas Frequentes

> Principais dúvidas da comunidade ao integrar com a Yampi

## 🔎 Qual sua dúvida?

* [ Como funciona a estrutura de webhooks na Yampi?](#como-funciona-a-estrutura-de-webhooks-na-yampi)
* [ O que é OAuth2?](#o-que-é-oauth2)
* [ Suporte para Parceiros Tech e Desenvolvedores](#suporte-para-parceiros-tech-e-desenvolvedores)
* [ Como usar a loja de testes?](#como-usar-a-loja-de-testes)
* [ Como integrar meu aplicativo à Yampi?](#como-integrar-meu-aplicativo-à-yampi)
* [ Como acessar o Painel do Parceiro?](#como-acessar-o-painel-do-parceiro)
* [ Como funciona a URL de redirecionamento?](#como-funciona-a-url-de-redirecionamento)
* [ Onde encontro a documentação da API?](#onde-encontro-a-documentacao-da-api)
* [ Como funciona o rate-limit dos endpoints?](#como-funciona-o-rate-limit-dos-endpoints)
* [ Quais plataformas integramos?](#quais-plataformas-integramos)
* [ Minha conta de testes tem algum custo?](#minha-conta-de-testes-tem-algum-custo)
* [ Quais os principais retornos HTTP da API da Yampi?](#quais-os-principais-retornos-http-da-api-da-yampi)
* [ Minha autenticação OAuth2 expira por inatividade do Lojista?](#minha-autenticacao-oauth2-expira-por-inatividade-do-lojista)
* [ É possível adicionar um parâmetro personalizado nos pedidos gerados no checkout da Yampi?](#e-possivel-adicionar-um-parametro-personalizado-nos-pedidos-gerados-no-checkout-da-yampi)
* [ Como fazer um pedido na minha loja de testes?](#como-fazer-um-pedido-na-loja-de-testes)
* [ Como saber o saldo de cashback de uma cliente?](#como-saber-o-saldo-de-cashback-de-um-cliente)

***

<Accordion title="📡 Como funciona a estrutura de webhooks na Yampi?">
  A estrutura de webhooks da Yampi é flexível e orientada a eventos. Você pode registrar um único webhook para escutar múltiplos eventos, o que simplifica a integração e centraliza o tratamento de notificações.

  Por exemplo, é possível utilizar a mesma URL para lidar com eventos como `order.created` e `cart.reminder`:

  ```bash theme={"system"}
  curl --request POST \
    --url https://api.dooki.com.br/v2/{alias}/webhooks \
    --header 'Content-Type: application/json' \
    --header 'User-Secret-Key: <api-key>' \
    --header 'User-Token: <api-key>' \
    --data '{
      "url": "https://suaurl.com/api/webhooks",
      "events": [
        "order.created",
        "cart.reminder"
      ],
      "name": "Nome do webhook"
    }'
  ```

  Sempre que um evento for disparado, será feita uma requisição `POST` para a URL informada.\
  Sua aplicação deve responder com status `200` ou `201` em até **5 segundos** — esse é o timeout recomendado.

  A estrutura do payload recebido é a seguinte:

  ```json theme={"system"}
  {
    "event": "order.status.updated",
    "time": "2025-05-12 12:11:19",
    "merchant": {
      "id": 109111,
      "alias": "teste-webhook"
    },
    "resource": {
      // Dados específicos do evento
    }
  }
  ```

  O campo `event` identifica o tipo do evento e `resource` contém os dados associados.

  Com essa estrutura, sua integração se torna mais eficiente, escalável e segura.

  🔗 Veja mais em [Webhooks](https://docs.yampi.com.br/api-reference/webhooks/introduction)
</Accordion>

<Accordion title="🔐 O que é OAuth2?">
  OAuth2 é um protocolo de autorização que permite que aplicativos acessem recursos protegidos em nome do usuário, sem expor suas credenciais.

  Na Yampi, utilizamos o OAuth2 para garantir que apenas aplicativos autorizados possam acessar os dados das lojas dos clientes.

  🔗 Ver documentação [OAuth2](https://docs.yampi.com.br/api-reference/oauth)
</Accordion>

<Accordion title="📌 Suporte para Parceiros Tech e Desenvolvedores">
  📬 **Canal principal de suporte**\
  O canal de suporte para parceiros e desenvolvedores é através do e-mail:\
  `integre@yampi.com.br`

  📚 **Base de Conhecimento**\
  Também temos uma base completa de informações, tutoriais e como usar a API em nossa documentação:

  🔗 [Acessar base de conhecimento](https://docs.yampi.com.br/introduction)
</Accordion>

<Accordion title="🛠️ Como usar a loja de testes?">
  Para testar seu aplicativo, você pode criar uma loja de testes no Painel do Parceiro:

  1️⃣ No painel do aplicativo, clique em **'Testar o aplicativo'**\
  2️⃣ Se ainda não tiver uma loja de teste, clique em **'Criar loja teste'**\
  3️⃣ Siga as instruções para configurar a loja e instalar o aplicativo

  A loja de testes permite simular operações sem impactar dados reais, mas possui algumas limitações, como ausência de confirmação de e-mail e de cobrança de comissões.

  🔗 Ver mais sobre [loja de testes](https://docs.yampi.com.br/apps/testes-e-validacao/como-testar-um-aplicativo)
</Accordion>

<Accordion title="🔌 Como integrar meu aplicativo à Yampi?">
  Para integrar seu aplicativo à Yampi, siga estas etapas:

  1️⃣ Acesse o Painel do Parceiro e crie uma conta de parceiro, se ainda não tiver uma\
  2️⃣ No painel, clique em **'Meus aplicativos'** e, em seguida, em **'+ Novo aplicativo'**\
  3️⃣ Preencha as informações solicitadas, como nome e categoria do aplicativo\
  4️⃣ Configure a URL de redirecionamento e as permissões necessárias para o aplicativo\
  5️⃣ Salve as configurações para gerar o **Client ID** do aplicativo\
  6️⃣ Utilize o fluxo de autenticação OAuth2 para obter o token de acesso e consumir os endpoints da API da Yampi

  🔗 Ver [artigo oficial](https://docs.yampi.com.br/apps/intro)
</Accordion>

<Accordion title="🛠️ Como acessar o Painel do Parceiro?">
  O Painel do Parceiro está disponível em:

  🔗 Acessar [Painel do Parceiro](https://partners.yampi.com.br)

  No painel, você pode:

  • Registrar e gerenciar seus aplicativos\
  • Acompanhar integrações\
  • Acessar recursos exclusivos para desenvolvedores
</Accordion>

<Accordion title="🔄 Como funciona a URL de redirecionamento?">
  A URL de redirecionamento é o endereço para onde o usuário será levado assim que autorizar o seu aplicativo. Nesse retorno, a Yampi adiciona um **código temporário** na URL. Esse código é usado pelo seu servidor para pedir o **token de acesso**, que é a chave que permite ao aplicativo usar as APIs em nome do usuário.

  Enquanto você está desenvolvendo, pode usar um endereço `localhost` (exemplo: `http://localhost:3000/callback`). Mas, quando o aplicativo for publicado no catálogo da Yampi, a URL deve obrigatoriamente ser segura, ou seja, começar com **https\://**.

  🔗 Ver [fluxo de autenticação](https://docs.yampi.com.br/api-reference/oauth)
</Accordion>

<Accordion title="📚 Onde encontro a documentação da API?">
  A documentação oficial da API da Yampi está disponível no link abaixo:

  🔗 Acessar [documentação da API](https://docs.yampi.com.br/introduction)

  Lá você encontrará informações detalhadas sobre:

  • Autenticação\
  • Endpoints disponíveis\
  • Parâmetros\
  • Exemplos de requisições\
  • E muito mais!
</Accordion>

<Accordion title="⏱️ Como funciona o rate-limit dos endpoints?">
  A API da Yampi possui limites de requisições para garantir a estabilidade do serviço.

  Se você exceder o número permitido de requisições em um determinado período, receberá uma resposta com o código de status HTTP `429` (Too Many Requests).

  **Para evitar esse problema:**

  • Implemente mecanismos de controle do volume de requisições e consumo saudável (*rate limit*) no seu aplicativo

  **Endpoints mais utilizados e seus limites:**

  * `GET https://api.dooki.com.br/v2/{alias}/orders` → 120 requisições/min
  * `PUT https://api.dooki.com.br/v2/{alias}/orders` → 30 requisições/min
  * `GET https://api.dooki.com.br/v2/{alias}/catalog/products` → 30 requisições/min

  Para visualizar todos os endpoints e seus respectivos rate limits, além de detalhes completos sobre o funcionamento, acesse a [documentação completa de Rate Limit](/api-reference/rate-limit/introduction).
</Accordion>

<Accordion title="🤝 Quais plataformas integramos?">
  A Yampi oferece integração com diversas plataformas e serviços, incluindo:

  • ERPs (como Bling, Tiny, Omie)\
  • Gateways de pagamento (como Mercado Pago, PagSeguro, Pagar.me)\
  • Plataformas de e-commerce (como Shopify, WooCommerce)\
  • Ferramentas de marketing e automação\
  • Aplicativos de logística e frete

  🔗 Ver [integrações disponíveis](https://aplicativos.yampi.com.br)
</Accordion>

<Accordion title="🧪 Minha conta de testes tem algum custo?">
  Não, sua conta é totalmente gratuita, mesmo se gerar pedidos!

  🔗 Ver mais sobre [loja de testes](https://docs.yampi.com.br/apps/testes-e-validacao/como-testar-um-aplicativo)
</Accordion>

<Accordion title="📘 Quais os principais retornos HTTP da API da Yampi?">
  A API da Yampi segue os padrões REST e utiliza códigos HTTP para indicar o resultado das requisições.

  **Principais códigos de resposta:**

  * 🟢 `200 OK`: Requisição bem-sucedida
  * 🟢 `201 Created`: Recurso criado com sucesso
  * 🟢 `204 No Content`: Requisição bem-sucedida, sem corpo
  * 🔴 `400 Bad Request`: Erro no payload
  * 🔴 `401 Unauthorized`: Token ausente ou inválido
  * 🔴 `403 Forbidden`: Acesso negado
  * 🔴 `404 Not Found`: Recurso inexistente
  * 🔴 `422 Unprocessable Entity`: Requisição não atende ao esperado ou dados são inválidos após sanitização e normalização
  * 🔴 `429 Too Many Requests`: Limite excedido
  * 🟡 `500 Internal Server Error`: Erro interno no servidor
</Accordion>

<Accordion title="🔁 Minha autenticação OAuth2 expira por inatividade do Lojista?">
  Não, o `refresh_token` tem validade de **30 dias**. Enquanto estiver válido, você pode usá-lo para renovar o `access_token` sempre que necessário — lembrando que o `access_token` expira após **10 minutos**.

  O processo completo de autenticação só será necessário se o aplicativo não renovar os tokens antes do vencimento do `refresh_token`.

  <Tip>
    Ao atualizar o `access_token`, fazendo a chamada para `/oauth/token`, você também receberá um novo `refresh_token`.
  </Tip>

  Essa chamada de atualização é feita da seguinte forma:

  ```bash theme={"system"}
  POST 'https://auth.yampi.com.br/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'refresh_token=your-refresh-token' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=your-app-client-id'
  ```

  Ao executá-la com sucesso, ambos seus tokens serão atualizados automaticamente.

  🔗 [Atualize os tokens – Yampi API](https://docs.yampi.com.br/api-reference/oauth#5-atualize-os-tokens)
</Accordion>

<Accordion title="🔗 É possível adicionar um parâmetro personalizado nos pedidos gerados no checkout da Yampi?">
  Sim, é possível adicionar informações personalizadas aos pedidos usando o parâmetro `metadata` na **URL de compra** do produto no checkout da Yampi, ou `UTMs` na URL da Loja.

  Esse recurso permite incluir dados customizados — como identificadores de afiliados, campanhas ou qualquer outro valor que você queira rastrear — diretamente na criação do pedido.

  #### ✅ Formato do parâmetro `metadata`:

  ```text theme={"system"}
  ?metadata[campo1]=valor1&metadata[campo2]=valor2
  ```

  #### 🧪 Exemplo na URL de compra:

  ```text theme={"system"}
  https://seguro.loja.com.br/r/66BOKUNV0N?metadata[teste]=baliza&metadata[dentro]=fora
  ```

  > ⚠️ Atenção: o parâmetro `metadata` **só é aceito na URL do checkout**, e **não funciona na URL da loja/vitrine**.

  ***

  ### 🛠️ Como gerar essa URL com metadata?

  Você pode obter o link de compra diretamente pelo painel da Yampi:

  > **Painel > Produtos > Ver todos > Detalhe do produto > Copiar link de compra**

  Depois, basta adicionar os parâmetros `metadata` desejados ao final da URL copiada.

  ***

  ### 🔌 Também é possível obter a URL via API, nas informações do SKU:

  ```http theme={"system"}
  GET /{alias}/catalog/skus/{id}
  ```

  ***

  ### 📤 Onde essas informações aparecem?

  Os dados enviados via `metadata`:

  * São incluídos automaticamente em qualquer **webhook** do tipo `order.*`.
  * Podem ser consultados via API, incluindo `metadata` no parâmetro `include`.

  #### Exemplo de consulta via API:

  ```http theme={"system"}
  GET https://{alias}.dooki.com.br/api/orders/{id}?include=metadata
  ```

  O atributo `metadata` retornará os dados personalizados enviados no momento do checkout.

  ***

  ### 📈 E se eu quiser rastrear algum parâmetro na URL da loja?

  Na **URL da loja**, o ideal é utilizar parâmetros UTM para mapear informações como origem, campanha, meio de divulgação, entre outros.

  As 5 tags UTM disponíveis são:

  * `utm_campaign` (Campanha)
  * `utm_source` (Origem)
  * `utm_medium` (Meio)
  * `utm_content` (Conteúdo)
  * `utm_term` (Termo)

  #### Exemplo:

  `https://loja.com/?utm_source=teste123&utm_medium=product_sync`

  Esses parâmetros também podem ser consultados da mesma forma que os valores de `metadata`.
</Accordion>

<Accordion title="🛒 Como fazer um pedido na loja de testes?">
  Para simular um pedido na loja de testes da Yampi, é necessário ter dois pré-requisitos: um **gateway de pagamento** configurado e ao menos um **produto** cadastrado. Com isso em mãos, você pode simular todo o fluxo de compra.

  ### Passo a passo dos pré-requisitos necessários:

  🪙 **1. Configurar um gateway de pagamento**

  1. Acesse o painel da loja e vá em **Checkout -> Formas de pagamento**.
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/formas-de-pagamento.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=459ed35caf7d9f225948e72aa17c52ad" alt="" width="273" height="605" data-path="images/faq/formas-de-pagamento.png" />
  2. Clique em **+ Nova afiliação**.
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/botao-nova-afiliacao.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=9c191b4ef54461b3dae74e141ff474e6" alt="" width="1115" height="471" data-path="images/faq/botao-nova-afiliacao.png" />
  3. Selecione a opção **Depósito bancário**.
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/deposito-bancario.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=c84731372f638b0416a9be05e76f3bf7" alt="" width="949" height="873" data-path="images/faq/deposito-bancario.png" />
  4. Marque a afiliação como **ativa** e defina um nome (exemplo: *Depósito bancário - Loja teste*).
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/botao-ativar-afiliacao.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=774953d972a9d562b66d3579cea13635" alt="" width="1059" height="347" data-path="images/faq/botao-ativar-afiliacao.png" />
  5. Escolha qualquer banco entre as opções disponíveis.
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/opcoes-bancarias.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=46bbe0f8da2ce1127da3781369e092ae" alt="" width="865" height="689" data-path="images/faq/opcoes-bancarias.png" />
  6. Preencha os dados bancários (informações fictícias podem ser utilizadas).
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/dados-ficticios.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=e317f3a42f35d52d80a5af5af5f7bdc1" alt="" width="789" height="884" data-path="images/faq/dados-ficticios.png" />
  7. Clique em **Salvar**.
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/botao-salvar.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=6ce2c573fc535af0b9a854dba7729400" alt="" width="1449" height="735" data-path="images/faq/botao-salvar.png" />
  8. Em seguida, selecione o meio de pagamento configurado e clique em **Salvar** mais uma vez.
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/selecionando-meio-pagamento.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=c41eedb11618f3b6dc79863dcb7d85e8" alt="" width="913" height="521" data-path="images/faq/selecionando-meio-pagamento.png" />

  📦 **2. Cadastrar um produto de teste**

  1. No painel, acesse o menu **Produtos**.
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/produtos-barra-lateral.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=155c5f3ec909a33296452e089ccd58d7" alt="" width="290" height="552" data-path="images/faq/produtos-barra-lateral.png" />
  2. Clique em **+ Novo produto**.
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/botao-novo-produto.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=b1dd41cc4368704fe8e49c6822939c49" alt="" width="1458" height="613" data-path="images/faq/botao-novo-produto.png" />
  3. Preencha: (a imagem abaixo ilustra cadastro preenchido)

  * Nome do produto
  * Descrição
  * Marca (se for nova, será criada automaticamente)
  * Preço de venda
  * SKU (pode ser gerado automaticamente)
      <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/preenchendo-cadastro.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=4c9d8e5c9fa4bc44af7ea7ee3706160b" alt="" width="1075" height="903" data-path="images/faq/preenchendo-cadastro.png" />

  4. (Opcional) Informe peso e dimensões.
  5. (Opcional) Adicione uma imagem.
  6. Clique no botão **Salvar** no topo da tela.
       <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/salvando-produto.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=1678d952edae9d8d5a7dca43cfb0502d" alt="" width="1349" height="821" data-path="images/faq/salvando-produto.png" />

  Após salvar, no lado direito da tela aparecerá a opção **Copiar link de compra**, que vamos utilizar para acessar o checkout e finalizar a compra.

  <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/link-de-compra.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=71c7d679f5461f5b1d19b19144124a89" alt="" width="1320" height="857" data-path="images/faq/link-de-compra.png" />

  🧪 **3. Realizar o pedido de teste**

  * Com o meio de pagamento ativo e o produto cadastrado, utilize o link de compra e finalize o pedido normalmente pelo checkout da loja.
      <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/checkout-pedido.gif?s=01d7210f12652d467728cfea56716790" alt="" width="1152" height="648" data-path="images/faq/checkout-pedido.gif" />

  ✅ **4. Aprovar manualmente o pedido**

  * No painel, acesse **Vendas -> Pedidos**.
      <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/pagina-de-pedidos.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=667151562c60347c13bc43ee637571a4" alt="" width="1899" height="737" data-path="images/faq/pagina-de-pedidos.png" />
  * Localize e abra o pedido realizado.
      <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/abrindo-pedido.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=b77f0b91cd3e899538a5080d8c36dead" alt="" width="1705" height="907" data-path="images/faq/abrindo-pedido.png" />
  * Clique em **Atualizar status**.
      <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/atualizar-status.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=f7b36caa3aa6000e8ae6aac2ad31efbd" alt="" width="1383" height="585" data-path="images/faq/atualizar-status.png" />
  * Selecione a opção **Pagamento aprovado** e clique em **Atualizar** para confirmar.
      <img src="https://mintcdn.com/yampi/u1tE3DqzZQgOcuhV/images/faq/pagamento-aprovado-atualizar.png?fit=max&auto=format&n=u1tE3DqzZQgOcuhV&q=85&s=d9958011b746947085b971466b2d2b15" alt="" width="719" height="603" data-path="images/faq/pagamento-aprovado-atualizar.png" />

  ***

  Concluídas essas etapas, você terá um pedido de teste completo registrado em sua loja.
</Accordion>

<Accordion title="💰 Como saber o saldo de cashback de um cliente?">
  A forma mais rápida e precisa de consultar essas informações é por meio dos endpoints de consulta da carteira.

  Você pode consultar apenas o saldo atual em:

  ```http theme={"system"}
  GET https://api.dooki.com.br/v2/{alias}/pricing/wallet/{customerID}/balance
  ```

  Também há a possibilidade de consultar o extrato completo, com histórico de pedidos em:

  ```http theme={"system"}
  GET https://api.dooki.com.br/v2/{alias}/pricing/wallet/statement/{customerID}
  ```

  Se precisar de mais informações dessa rota é só acessar a página completa [aqui!](https://docs.yampi.com.br/api-reference/promocoes/carteira/visualizar-balanco-de-cashback-do-cliente)
</Accordion>