API Sacador
Documentação para integradores que vão consumir a API e/ou receber webhooks do Sacador.
| Tópico | O que cobre |
|---|---|
| Autenticação | Como criar tokens de API, formato (sct_…), envio em requisições e revogação |
| Convenções | URL base, versionamento, content type, status codes, paginação, rate limit, formato de erro (com o campo code), idempotência e regras de multi-tenancy comuns a todos os endpoints |
| Cobranças | GET/POST/PATCH/DELETE /v1/billings + cancel e pay_off — campos, validações, edibilidade, itens com destruição implícita |
| Boletos bancários | GET/v1/billings/:billing_id/bank_billets — somente leitura. Campos do boleto registrado no banco (barcode, linha digitável, Pix), status, snapshots de pagador/beneficiário |
| Contatos | GET/POST/PATCH/DELETE /v1/contacts: PF vs PJ, normalização aplicada, filtros, busca, campos personalizados da conta, external_id, limite de fiado e saldos do PDV |
| Tags | GET/POST/PATCH/DELETE /v1/tags — etiquetas de clientes, vínculo com contatos e uso na emissão em massa |
| Categorias financeiras | GET/v1/bill_categories — somente leitura. A classificação compartilhada por cobranças, contas a pagar, contas a receber e caixa. É de onde sai o bill_category_id |
| Vendas do PDV | GET/v1/sales e GET/v1/sales/:code: somente leitura. Vendas concluídas com itens, pagamentos, devoluções, fiado em aberto (due_amount) e a parte que foi para o fiado (on_account_amount) |
| Créditos do cliente | POST/GET /v1/store_credits: inclusão idempotente de crédito por reference e extrato de movimentos do contato, usado como meio de pagamento no PDV |
| Baixa de fiado por repasse | GET/v1/receivable_settlements/preview, POST/v1/receivable_settlements e GET/v1/receivable_settlements/:reference: confere e quita, em segundo plano, o fiado até uma data de corte e gera uma conta a receber contra o pagador do repasse |
| Webhooks | Eventos (billing.updated, sale.updated, store_credit.created), headers enviados, deduplicação por X-Sacador-Delivery, esquema de assinatura HMAC-SHA256 e exemplos de validação em Ruby, Node, Python e PHP |
Onde gerenciar credenciais
Tokens de API e endpoints de webhook são gerenciados em /integrations, na aba API e Webhook. Cada conta pode ter múltiplos tokens nomeados e até 3 URLs de webhook (cada uma com seu próprio secret de assinatura).