API SnapCost

Uma API REST limpa para recibos, faturas e relatórios prontos para o fisco. JSON na entrada, JSON na saída. Auth com token Bearer. Construída para contadores, integrações ERP e suas próprias automações.

URL base

https://snapcost.app/api

Formato

Corpos de requisição e resposta em JSON, UTF-8.

Autenticação

HTTP Bearer com uma chave API.

Plano

O acesso à API requer o plano Business.

Autenticação

Cada requisição deve incluir um cabeçalho Authorization com sua chave API.

Authorization: Bearer sk_live_••••••••••••••••••••••••••••••••

As chaves API estão vinculadas a uma única conta SnapCost e herdam suas permissões e limites de plano. Comportam-se de forma idêntica a uma sessão de usuário logado — hoje não existe um sistema de escopos separado.

Trate as chaves como senhas. Nunca commite no controle de versão nem exponha em código do navegador. Rotacione imediatamente se uma chave puder ter vazado.

Gerenciamento de chaves API

Gere, liste e revogue chaves no painel do SnapCost, ou use os endpoints de gestão abaixo (exigem um JWT logado, não uma chave API, para evitar escalada de privilégios).

GET/api/keysListar suas chaves

POST/api/keysCriar uma nova chave

DELETE/api/keys/:idRevogar uma chave

Criar uma chave

POST /api/keys
Content-Type: application/json

{ "name": "Zapier production" }

Resposta

{
  "id":        "9c1f…",
  "name":      "Zapier production",
  "prefix":    "sk_live_AbC",
  "plaintext": "sk_live_AbCDeFGhIJKlMnOPqRsTUVwxYZ0123456789…",
  "createdAt": "2026-04-21T10:42:18.000Z",
  "note":      "Store this key now — the full value will not be shown again."
}

A chave completa em texto plano é retornada apenas uma vez, na criação. O SnapCost armazena um hash SHA-256 e não pode recuperar o valor original. Limite: 10 chaves ativas por conta.

Início rápido

curl https://snapcost.app/api/receipts \
  -H "Authorization: Bearer $SNAPCOST_API_KEY"

const res = await fetch('https://snapcost.app/api/receipts', {
  headers: { Authorization: `Bearer ${process.env.SNAPCOST_API_KEY}` },
});
const { receipts } = await res.json();

import os, requests

r = requests.get(
    "https://snapcost.app/api/receipts",
    headers={"Authorization": f"Bearer {os.environ['SNAPCOST_API_KEY']}"},
)
receipts = r.json()["receipts"]

Recibos

Recibos são despesas escaneadas ou inseridas manualmente.

GET/api/receiptsListar recibos

GET/api/receipts/:idBuscar um recibo

POST/api/receiptsCriar um recibo

PUT/api/receipts/:idAtualizar um recibo

DELETE/api/receipts/:idExcluir um recibo

Criar um recibo

Campo	Tipo		Notas
`merchant`	string	obrigatório	Nome do fornecedor
`amount`	number	obrigatório	Total em `currency`
`currency`	string	opcional	ISO 4217, padrão: moeda da sua conta
`date`	string	obrigatório	Data ISO (`AAAA-MM-DD`)
`category`	string	opcional	ex. `travel`, `meals`
`notes`	string	opcional	Memo livre

Faturas

Faturas e orçamentos que você emite aos clientes. Contas Pro+ também acessam os endpoints Factur-X / PDP / e-reporting.

GET/api/invoicesListar faturas & orçamentos

POST/api/invoicesCriar uma fatura ou orçamento

GET/api/invoices/:idBuscar um

PUT/api/invoices/:idAtualizar

DELETE/api/invoices/:idExcluir

GET/api/invoices/:id/facturx-pdfBaixar PDF Factur-X (Pro+)

POST/api/invoices/:id/pdp/sendEnviar para PDP (Pro+)

Relatórios

Gere resumos prontos para o fisco para qualquer intervalo de datas.

GET/api/reportsListar relatórios salvos

POST/api/reportsGerar um relatório

GET/api/reports/:idBuscar um relatório

Erros

O SnapCost usa códigos HTTP padrão. Falhas sempre retornam JSON com um campo error, às vezes uma message e, ocasionalmente, uma upgradeUrl quando um plano pago é necessário.

Status	Significado
400	Requisição malformada — parâmetros ausentes ou inválidos
401	Chave API / token ausente, inválido ou revogado
402	Cota do plano gratuito esgotada — upgrade necessário
403	Endpoint requer um plano superior (ex. Pro+)
404	Recurso não encontrado ou não pertencente à sua conta
429	Muitas requisições — veja os limites de taxa abaixo
5xx	Erro transitório do servidor — seguro tentar novamente com backoff

Limites de taxa

Limite padrão: 100 requisições por minuto por IP, aplicado a todos os endpoints /api/*. Endpoints de auth são mais estritos. Se precisar de mais, contate o suporte com seu caso de uso.

Versionamento

A API hoje é sem versão e estritamente aditiva — adicionamos campos e endpoints sem quebrar clientes existentes. Qualquer mudança incompatível sairá sob um novo prefixo /api/v2/… com janela de depreciação de pelo menos 6 meses.