Perguntas Frequentes - Yampi Developer Portal

🔎 Qual sua dúvida?

Como funciona a estrutura de webhooks na Yampi?
O que é OAuth2?
Suporte para Parceiros e Desenvolvedores
Como usar a loja de testes?
Como integrar meu aplicativo à Yampi?
Como acessar o Painel do Parceiro?
Como funciona a URL de redirecionamento?
Onde encontro a documentação da API?
Como funciona o rate-limit dos endpoints?
Quais plataformas integramos?
Minha conta de testes tem algum custo?
Quais os principais retornos HTTP da API da Yampi?
Minha autenticação OAuth2 expira por inatividade do Lojista?
É possível adicionar um parâmetro personalizado nos pedidos gerados no checkout da Yampi?
Como fazer um pedido na minha loja de testes?

📡 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:

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:

{
  "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

🔐 O que é OAuth2?

📌 Suporte para Parceiros e Desenvolvedores

🛠️ Como usar a loja de testes?

🔌 Como integrar meu aplicativo à Yampi?

🛠️ Como acessar o Painel do Parceiro?

🔄 Como funciona a URL de redirecionamento?

📚 Onde encontro a documentação da API?

⏱️ Como funciona o rate-limit dos endpoints?

🤝 Quais plataformas integramos?

🧪 Minha conta de testes tem algum custo?

📘 Quais os principais retornos HTTP da API da Yampi?

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

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

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

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

🔗 É 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`:

?metadata[campo1]=valor1&metadata[campo2]=valor2

🧪 Exemplo na URL de compra:

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:

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:

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_syncEsses parâmetros também podem ser consultados da mesma forma que os valores de metadata.

🛒 Como fazer um pedido na loja de testes?

​🔎 Qual sua dúvida?

🔎 Qual sua dúvida?