Até agora, um backend que enviava compras ao Provedly usava uma chave por widget, gerada na aba Data daquele widget. Isso funciona para um widget. Para um negócio com vários sites ou vários widgets, significava vários segredos para guardar e trocar. A Records API agora também aceita uma chave de API da conta, a mesma chave provedly_ usada pela API REST e pelo servidor MCP, então um único segredo pode cobrir todos os widgets da conta.
Este artigo explica quando migrar, como, e o que não muda. A referência completa dos campos continua no guia da Records API.
O que mudou e o que não mudou
O endpoint é o mesmo:
POST https://provedly.app/api/v1/widgets/{token}/records
Authorization: Bearer <widget key or account key>
Content-Type: application/json
Os campos são os mesmos: name, city, state, country, product_name, price, avatar_url, external_id, occurred_at e visitor. Valores de external_id duplicados continuam sendo rejeitados por widget, então novas tentativas seguem seguras.
O que mudou foi o cabeçalho. Agora você pode enviar uma chave da conta com o nível de acesso Read and write em vez da chave do próprio widget. Uma chave de conta somente leitura é recusada neste endpoint, porque adicionar um registro é uma escrita.
As chaves de widget continuam funcionando. Nada quebra se você deixar uma integração existente como está.
Quando usar cada chave
Mantenha a chave do widget quando a integração só escreve em um widget e você gosta do escopo restrito. Uma chave de widget vazada só consegue adicionar registros àquele widget.
Use uma chave de conta quando um serviço escreve em vários widgets, por exemplo um serviço de checkout que atende três vitrines, cada uma com seu próprio widget. Um segredo no ambiente, e o widget escolhido pelo token na URL.
Se migrar, crie uma chave dedicada para o serviço em Settings, em API keys, e dê a ela o nome do serviço: "Checkout service, production". Não reutilize a chave que você deu ao seu assistente de IA. Chaves separadas permitem revogar uma sem quebrar a outra.
Um exemplo prático
Um serviço que processa pedidos pagos de duas vitrines poderia ser, em linhas gerais, assim:
const WIDGETS = {
'shop-eu': 'pp_eu_widget_token',
'shop-us': 'pp_us_widget_token',
};
async function sendRecord(order) {
const token = WIDGETS[order.storefront];
const res = await fetch(
`https://provedly.app/api/v1/widgets/${token}/records`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PROVEDLY_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: order.customerFirstName,
city: order.city,
country: order.countryCode,
product_name: order.productName,
price: order.displayPrice,
external_id: order.id,
occurred_at: order.paidAt,
visitor: order.provedlyVisitorId,
}),
},
);
if (res.status === 422) return; // duplicate external_id or invalid data
if (!res.ok) throw new Error(`Provedly ${res.status}`);
}
Chame-o depois que o pagamento for confirmado, nunca na criação do pedido. Um registro de um checkout que depois falhou é uma notificação sobre uma compra que não aconteceu.
O campo visitor leva o id de visitante do Provedly que vem do navegador, e é isso que permite que o pedido conte como pedido assistido por prova social nas suas estatísticas. Sem ele, o registro continua aparecendo, e a métrica de atribuição simplesmente o deixa de fora. Veja medindo pedidos assistidos por prova social.
Como esses registros aparecem
Registros enviados pela API mantêm a origem API, seja qual for a chave usada. Eles aparecem no widget com o rótulo visível "Imported" e sem a marca Verified, e a página de verificação pública os conta em "Site owner's backend (API)".
Se os seus pedidos passam pelo Stripe, Shopify ou WooCommerce, a conexão por webhook assinado é o melhor caminho: esses registros chegam verificados sem nenhum código do seu lado. A Records API é para tudo que essas conexões não cobrem. Por que o seu assistente não consegue verificar uma compra explica por que uma chamada de API, seja qual for a autenticação, não consegue gerar um registro verificado.
Conferindo pelo seu assistente
A mesma conta fica visível para o seu assistente de IA pelo servidor MCP, com uma chave separada. Depois de publicar a mudança, você pode perguntar:
Liste meus widgets e me mostre as estatísticas do último dia.
e comparar a resposta com o seu próprio registro de pedidos. O livro de receitas de prompts tem mais exemplos. Se quiser testar a integração manualmente antes, o assistente pode chamar add_record para um único pedido real, o que é um jeito rápido de ver exatamente como um registro é exibido.
Perguntas frequentes
Uma chave de conta me deixa enviar para um widget de outra conta?
Não. Uma chave de conta só funciona para widgets que pertencem à própria conta. Um token de outra conta é recusado.
Devo trocar minhas chaves de widget agora?
Só se você estiver migrando para uma chave de conta. Quando o serviço já estiver usando a nova chave, gere uma nova chave de widget na aba Data do widget para que a antiga pare de funcionar.
Existe um endpoint em lote para o histórico?
Não. Para pedidos antigos, use a importação de CSV na aba Data do widget, descrita em importando pedidos antigos por CSV. A API é para o fluxo em tempo real.
A Records API e as chaves de conta estão disponíveis no plano Free: crie uma conta.