Central de Ajuda › Conectar sua loja
Chaves de API e webhook
Para quem envia as vendas do próprio sistema (ERP, loja sob medida): gerar e revogar a chave de API, o segredo do webhook, o que a venda precisa trazer, a Documentação da API e por que uma chave Sandbox concede licença de verdade.
API Push e Webhook são os caminhos de quem tem um sistema próprio — um ERP, uma loja feita sob medida. Em vez de o Folhear buscar a venda na loja, o seu sistema avisa o Folhear a cada venda paga. Os dois pedem alguém que programe do seu lado; a diferença é a credencial.
| Método | Para onde o seu sistema envia | Credencial |
|---|---|---|
| API Push | A URL base da API da sua conta, em /vendas (e /vendas/reembolso) | Uma chave de API, no cabeçalho X-Api-Key |
| Webhook | O endereço exclusivo da integração (e o mesmo endereço com /reembolso) | O segredo da integração, no cabeçalho X-Folhear-Signature |
Gerar uma chave de API
Abra API e clique em “Gerar nova chave”
Dê um Nome que diga onde ela vai ser usada (“ERP da loja”, por exemplo), escolha o Ambiente e clique em “Gerar chave”.
Copie a chave na hora
A chave completa aparece uma única vez, na janela “Chave gerada”. Copie e guarde antes de clicar em “Entendi, já copiei” — depois disso a lista mostra só o começo dela, a data de criação e o último uso.
Use no cabeçalho X-Api-Key
Toda chamada da API Push leva a chave no cabeçalho
X-Api-Key. Nunca use o login de um usuário do portal no lugar dela.
Uma chave Sandbox também concede licença de verdade. A opção Ambiente só muda o começo da chave (sk_test_ em vez de sk_live_): a venda enviada com uma chave Sandbox é processada como qualquer outra — a licença é concedida, o convite sai para o e-mail informado e o repasse é debitado da carteira. Para testar, use um livro seu e um e-mail seu.
No menu da linha, “Revogar” desliga a chave na hora: qualquer integração que a use para de funcionar. Para trocar de chave sem parar as vendas, gere a nova, troque no seu sistema e só então revogue a antiga.
O segredo do webhook
O webhook não usa chave de API. Crie uma integração com o método “Webhook” em Integrações › “Adicionar integração”: ela ganha um endereço exclusivo e um segredo, mostrados na janela “Segredo do webhook” — o segredo completo, só nessa hora. Depois, em “Ver detalhes”, o endereço continua visível (Endpoint), e o ícone “Regenerar segredo” gera outro; o anterior deixa de funcionar assim que o novo é gerado.
O que a venda precisa trazer
| Campo | Obrigatório | O que é |
|---|---|---|
numero | Sim | Número do pedido no seu sistema. É por ele que o reembolso encontra a venda depois. |
clienteEmail | Sim | E-mail de quem comprou. Sem conta no Folhear, ela é criada e o convite sai. |
livroId ou codigoProduto | Um dos dois | O id do livro no Folhear, ou o código do produto (SKU) já mapeado em Integrações › Mapeamento de produtos. |
valor | Não | Base do repasse. Sem ele, a venda entra com valor zero. |
clienteNome | Não | O nome no convite de acesso. |
chaveIdempotencia | Sim | Uma chave única por evento. Reenviar com a mesma chave nunca duplica licença. |
O reembolso leva o mesmo numero da venda, uma chave de idempotência nova e, se quiser, o motivo: a licença daquele pedido é revogada e o repasse dele volta para a carteira.
Os exemplos prontos
Abaixo das chaves, na mesma tela, “Documentação da API” traz os exemplos de chamada com a URL da sua conta, nas abas API Push e Webhook: confirmar uma venda, registrar um reembolso e as respostas. Na aba API Push, o exemplo usa o começo da chave escolhida em “Usar a chave”; na aba Webhook, o endereço da integração escolhida.
Quando a resposta não é 200
| Resposta | O que quer dizer |
|---|---|
| 400 | Faltou um dado ou ele veio errado. O motivo vem em { "mensagem": "…" }. |
| 401 | Na API Push: chave ausente, inválida ou revogada (cabeçalho X-Api-Key). No webhook: segredo ausente ou errado (cabeçalho X-Folhear-Signature). |
| 403 | Webhook de uma integração pausada. |
| 404 | Endereço de webhook que não existe, ou que não é de uma integração com o método Webhook. |
| 422 | A venda chegou, mas não pôde ser processada — o código ainda não está mapeado, por exemplo. Ela não se perde: fica na Fila de eventos, em Integrações. |
| 429 | Requisições demais. Espere o tempo do cabeçalho Retry-After e tente de novo. |