Visão geral para desenvolvedores
O que dá para integrar com o Vipter hoje (webhooks assinados, parâmetros de URL do checkout, script de UTMs e esta documentação em Markdown), o que não existe e por onde começar.
Esta seção é para quem vai ligar uma loja do Vipter a um sistema próprio: um ERP, um CRM, uma área de membros feita em casa ou um banco de dados de relatórios. As páginas vão direto ao formato, aos números e ao código. Para os passos no painel, cada página aponta para a versão escrita para o lojista.
O que existe hoje
| Recurso | Direção | Para que serve | Referência |
|---|---|---|---|
| Webhooks de saída | Vipter → seu servidor | Um POST em JSON, assinado com HMAC SHA-256, a cada venda, reembolso, mudança de assinatura, cliente novo ou checkout abandonado. São 20 tipos de evento, com novas tentativas automáticas. | Catálogo de eventos, envelope, assinatura, tentativas |
| Parâmetros de URL do checkout | Seu site → checkout | Montar links que já abrem com pacote, cupom, vendedor, idioma, moeda, dados do comprador e origem da campanha. | Parâmetros de URL |
Script t.js | Sua página de vendas → checkout | Levar UTMs, IDs de clique, cookies de anúncio e o código do vendedor da sua página até o link do checkout. | Script t.js |
| Documentação em Markdown | Docs → você ou uma IA | Toda página desta central existe em Markdown: acrescente .md ao endereço. https://docs.vipter.com/llms.txt lista todas as páginas, em todos os idiomas, com o link do Markdown. | Esta página em Markdown: https://docs.vipter.com/pt-br/developers/overview.md |
O que não existe
- API REST pública e chaves de API para lojistas. Não dá para consultar pedidos, criar clientes, gerar cobranças nem mudar assinaturas por API. A comunicação é de mão única: o Vipter avisa o seu sistema por webhook, e o que precisa de uma ação é feito no painel.
- Gerenciar endpoints por código. Endpoints de webhook são criados, ligados, desligados e removidos só no painel.
- Buscar eventos antigos. Um endpoint recebe os eventos criados enquanto ele existe e está ativo. Não há como pedir o histórico nem reenviar eventos em lote. O painel reenvia uma entrega por vez, entre as mais recentes. Veja Tentativas, desativação e reenvio.
- Eventos fora do catálogo. Só os 20 tipos do catálogo saem por webhook. Não há evento para PIX gerado, pedido pendente ou carrinho em andamento.
Por onde começar
- Crie um endpoint
https://em GeralIntegraçõesAutomaçõesWebhooks e guarde o segredowhsec_…, que aparece uma vez só. O passo a passo com prints está em Receber eventos no seu sistema. - No seu servidor, leia o corpo cru da requisição e verifique a assinatura antes de qualquer outra coisa.
- Responda com um código 2xx em até 10 segundos e processe o evento depois, numa fila. Resposta lenta conta como falha e gera novas tentativas.
- Guarde o
idde cada evento e ignore os que já foram processados. A entrega é "pelo menos uma vez": o mesmo evento pode chegar mais de uma vez. Veja idempotência. - Clique em Enviar evento de teste no painel e confira se o seu sistema aceitou a entrega em Entregas recentes.
Um endpoint por finalidade
Cada endpoint tem o seu segredo, a sua lista de eventos e a sua fila de entregas. Uma falha num endpoint não atrasa os outros. Se dois sistemas recebem eventos, crie um endpoint para cada.
O que fazer a seguir
- Veja o que vem em cada evento no catálogo de eventos.
- Monte links de checkout com os parâmetros de URL.
- Leve a origem das vendas da sua página até o checkout com o script t.js.
Falar com o vendedor
Para quem comprou numa loja que usa o Vipter. Onde encontrar o contato da loja e por que dúvidas sobre o produto, a entrega e o reembolso são com ela.
Catálogo de eventos
Os 20 tipos de evento que o Vipter envia por webhook, quando cada um dispara e o que vem em data.object, com um exemplo completo de pedido, assinatura, cliente e checkout abandonado.