Skip to main content

​
🔎 Qual sua dúvida?

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
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
📬 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
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 aplicativoA 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
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
O Painel do Parceiro está disponível em:🔗 Acessar Painel do ParceiroNo painel, você pode:• Registrar e gerenciar seus aplicativos
• Acompanhar integrações
• Acessar recursos exclusivos para desenvolvedores
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
A documentação oficial da API da Yampi está disponível no link abaixo:🔗 Acessar documentação da APILá você encontrará informações detalhadas sobre:• Autenticação
• Endpoints disponíveis
• Parâmetros
• Exemplos de requisições
• E muito mais!
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 aplicativoEndpoints 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
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
Não, sua conta é totalmente gratuita, mesmo se gerar pedidos!🔗 Ver mais sobre loja de testes
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
  • 🔴 429 Too Many Requests: Limite excedido
  • 🟡 500 Internal Server Error: Erro interno no servidor
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
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.
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.\
  2. Clique em + Nova afiliação.
  3. Selecione a opção Depósito bancário.
  4. Marque a afiliação como ativa e defina um nome (exemplo: Depósito bancário - Loja teste).\
  5. Escolha qualquer banco entre as opções disponíveis.\
  6. Preencha os dados bancários (informações fictícias podem ser utilizadas).\
  7. Clique em Salvar.\
  8. Em seguida, selecione o meio de pagamento configurado e clique em Salvar mais uma vez.
📦 2. Cadastrar um produto de teste
  1. No painel, acesse o menu Produtos.\
  2. Clique em + Novo produto.\
  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)
  1. (Opcional) Informe peso e dimensões.
  2. (Opcional) Adicione uma imagem.
  3. Clique no botão Salvar no topo da tela.\
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.\🧪 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.\✅ 4. Aprovar manualmente o pedido
  • No painel, acesse Vendas -> Pedidos.\
  • Localize e abra o pedido realizado.\
  • Clique em Atualizar status.\
  • Selecione a opção Pagamento aprovado e clique em Atualizar para confirmar.
Concluídas essas etapas, você terá um pedido de teste completo registrado em sua loja.
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:
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:
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!