Como usar a Records API para compras do seu próprio backend

Se as suas compras não passam pelo Stripe Checkout, pela Shopify ou pelo WooCommerce, a Records API é como elas chegam à Provedly. Um POST de servidor para servidor por pedido, autenticado com uma chave bearer por widget, e a compra aparece como notificação dentro da janela de retroatividade. Registros criados assim levam um rótulo "Imported" visível e nunca a marca "Verified", e este post explica essa regra além da mecânica.

O endpoint

POST https://provedly.app/api/v1/widgets/{token}/records
Authorization: Bearer <widget api key>
Content-Type: application/json

A chave é gerada por widget na aba Data e pode ser trocada ali. Trate-a como qualquer segredo: variável de ambiente no servidor, nunca em código do lado do cliente. O endpoint é só de servidor para servidor; chamadas feitas a partir de um navegador ficam visíveis para qualquer pessoa com devtools, e uma chave vazada permite que um estranho publique registros no seu widget.

Campos

Envie o que você tiver. Um registro só com name é válido e vai ser exibido com o produto padrão do widget e sem localização.

Um exemplo mínimo

curl -X POST https://provedly.app/api/v1/widgets/pp_your_token/records \
  -H "Authorization: Bearer $PROVEDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "city": "Berlin",
    "country": "DE",
    "product_name": "Pro Plan",
    "price": "€49",
    "external_id": "order_123",
    "occurred_at": "2026-08-12T14:03:00Z"
  }'

Respostas:

201 Created
{ "id": 812, "hash": "9c1e0b7a…", "verified": false, "occurred_at": "2026-08-12T14:03:00+00:00" }

401 Unauthorized   wrong or missing bearer key
422 Unprocessable  validation errors, including a duplicate external_id

Repare no "verified": false na resposta de sucesso. Não é um bug, e não existe nenhuma flag para mudar isso.

Quando chamar

Chame depois que o pagamento for confirmado, não quando o pedido for criado. Um registro de um checkout abandonado ou recusado é uma notificação falsa, que é exatamente o que o sistema foi feito para evitar. Na maioria dos backends, isso significa o handler do callback de sucesso do seu provedor de pagamento ou o job que marca o pedido como pago.

Sempre envie external_id. Callbacks de pagamento são reenviados, filas reentregam e deploys reiniciam workers no meio de um job. Com external_id igual ao ID do seu pedido, a segunda tentativa retorna 422 e você pode tratar isso como sucesso. Sem ele, mais cedo ou mais tarde você vai mostrar a mesma compra duas vezes.

Defina occurred_at como o horário real do pagamento em vez de deixar o padrão. Se uma fila atrasar vinte minutos, a notificação continua dizendo a coisa certa, e o registro cai no lugar certo na página de verificação.

Atribuição

A métrica de pedidos assistidos pela prova no painel conta compradores que viram uma notificação antes de comprar, cruzados pelo ID de visitante dentro de uma janela de 30 dias. Em registros via API, isso só funciona se você enviar o ID.

No cliente, no ponto em que o visitante inicia o checkout:

const visitor = window.Provedly?.visitorId();
// include it in your checkout form or API call

No servidor, repasse-o como visitor no registro. Se o seu checkout fica num domínio diferente do widget, leve o ID na URL ou na sua sessão. A Provedly nunca estima atribuição, então um ID ausente produz uma métrica vazia, e não uma métrica errada. Veja Como medir pedidos assistidos pela prova.

Por que registros via API nunca são "Verified"

A Provedly consegue verificar um webhook do Stripe, da Shopify ou do WooCommerce porque o provedor assina o conteúdo com um segredo e a Provedly confere a assinatura. Um POST do seu servidor leva uma chave bearer, o que prova que quem chama tem a chave, não que um pagamento aconteceu. Um lojista poderia gerar cem registros num loop. A Provedly não consegue distinguir isso de fora, então registros via API nunca recebem a marca de verificado. Eles aparecem no widget com um rótulo "Imported" que nenhuma configuração, plano ou pedido ao suporte consegue remover, e a página de verificação pública os lista em "Site owner's backend (API)".

Essa é uma escolha deliberada, e é o principal motivo de a Provedly existir. A maioria das ferramentas de notificação, em outubro de 2026 e segundo as próprias listagens, aceita lançamentos de compras arbitrários e os apresenta de forma idêntica aos reais. O visitante não tem como saber. Com a Provedly, só pedidos assinados mostram a marca de verificado, e a página de verificação lista todas as fontes. Se você quer a marca de verificado, faça os pagamentos passarem por um provedor com webhook assinado, como descrito em Webhooks do Stripe para compras verificadas.

Preenchimento retroativo

Para o histórico, não rode a API em loop sobre os pedidos do ano passado. Use a importação por CSV na aba Data; ela trata duplicados por nome e cidade dentro de uma hora, define occurred_at por linha e armazena linhas fora da janela de retroatividade sem exibi-las. A API é para o fluxo ao vivo. Veja Como importar pedidos antigos via CSV.

Perguntas frequentes

Existe um limite de requisições?

Publique um registro por pedido conforme ele acontece e você não vai chegar a nenhum limite. Para histórico em massa, use a importação por CSV.

Posso atualizar ou apagar um registro depois de publicá-lo?

Registros podem ser removidos pelo painel. Não existe endpoint de atualização; publique um registro corrigido com um novo external_id e apague o antigo.

Posso enviar um preço numa moeda que o widget não conhece?

Sim. price é texto livre de até 30 caracteres, exibido como você enviar. Formate do seu lado, incluindo o símbolo da moeda.

A API e os webhooks verificados estão incluídos no plano Free: leia a referência completa ou crie um widget.