Perguntas frequentes

Qual URL base devo usar?

https://app.principia.services/checkout/v4 em produção e https://app-staging.principia.services/checkout/v4 em homologação. Os endereços ms-checkout.provi.com.br continuam funcionando para integrações antigas. Veja Ambientes.

O token é por usuário ou por empresa?

O Api-Token identifica a sua empresa (parceiro): tudo o que é criado com ele fica no seu cadastro. Use GET /seller para conferir a quem o token pertence.

Preciso cadastrar cursos e turmas antes de criar a venda?

Não. POST /sales cadastra produtos (cursos) e variações (turmas) automaticamente pelos SKUs. Veja as regras em Checkout.

Posso configurar mais de uma URL de webhook?

Sim. Cada configuração tem a sua URL e os seus eventos. Só não cadastre a mesma URL em duas configurações: cada cadastro é independente, e o mesmo evento chega uma vez por configuração. Veja Webhooks.

E se o meu endpoint de webhook falhar?

São 4 tentativas no total: o envio original (cerca de 15 segundos depois do evento) e mais 3 reenvios, 2, 5 e 15 minutos depois de cada falha. Um envio só conta como sucesso com resposta 2XX. Veja Reenvio.

Dá para consultar o histórico de envios de webhook?

Ainda não, nem pelo painel nem pela API. O histórico é guardado do nosso lado; guarde também os eventos que você recebe.

Como sei se a venda foi paga?

Pelo evento purchaseConfirmed no seu webhook. Você também pode consultar a venda com GET /sales/purchase/{saleId} e olhar o status.

Qual a diferença entre /webhooks e /webhook?

/webhooks é o sistema atual, documentado em Webhooks. As rotas /webhook/... são do sistema antigo, marcadas como legado nas Rotas da API. Para novas integrações, use /webhooks. Os dois sistemas funcionam em paralelo: se a sua conta tiver configurações nos dois, cada venda gera envios nos dois formatos. Ao migrar, inative as configurações antigas.

O comprador volta para o meu site depois de pagar?

Só com o checkout embutido em um iframe e o parâmetro redirectUrl. O campo returnUrl de POST /sales é aceito, mas não é usado hoje. De qualquer forma, confirme o pagamento pelos webhooks.

As datas do webhook estão em UTC?

Não. Elas vêm com o sufixo Z, mas o valor está no horário de Brasília (UTC-3). Veja Datas.