Convenções da API

Regras válidas para todos os endpoints sob /v1/*. Cada endpoint individual pode acrescentar regras específicas, mas nunca contradiz o que está aqui.

URL base e versionamento

https://api.sacador.com.br/v1/<recurso>

A versão (v1) está no path. Quebras de contrato → nova versão (v2); adições retrocompatíveis (novos campos, novos endpoints) entram na v1 sem aviso.

Autenticação

Todas as requisições exigem header:

Authorization: Bearer sct_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Detalhes do token, criação e revogação: ver authentication.md.

Content type

• Requisições com corpo (POST/PATCH/PUT): envie Content-Type: application/json ou application/x-www-form-urlencoded. Os dois são aceitos.
• Respostas: sempre application/json; charset=utf-8.

Status codes

Formato de erro

Toda resposta 4xx retorna JSON em um destes dois formatos:

Erros de validação ou autorização lógica (422):

{
  "status": 422,
  "errors": [
    "Descrição não pode ficar em branco",
    "CPF inválido"
  ]
}

errors é sempre um array de strings (já localizadas em português). Cada string é uma mensagem independente e exibível ao usuário final.

Erros de autenticação, autorização e roteamento (401, 403, 404):

{
  "status": 401,
  "message": "Unauthorized"
}

Rate limit (429):

{
  "error": "Excedido o limite de requisições. Por favor, tente novamente mais tarde."
}

Acompanhado do header Retry-After: .

Paginação

Todos os endpoints GET /v1/ (listagens) são paginados. Os parâmetros de paginação são query params — não use headers.

Query params

Exemplo:

GET /v1/contacts?page=2&per_page=50

Response headers

Toda listagem retorna os mesmos quatro headers:

Os totais consideram apenas os registros da sua conta — o isolamento é aplicado antes da contagem.

Estratégia recomendada

1. Inicialize page = 1
2. Faça GET com page atual
3. Processe os items
4. Se page >= X-Total-Pages → fim
5. Senão page += 1 e volte a 2

Para sincronizações periódicas, prefira combinar paginação com os filtros de data (start_created_at / end_created_at quando disponíveis) para limitar a varredura ao intervalo novo.

Rate limit

• 60 requisições por minuto, por IP de origem (não por token).
• Inclui todas as rotas /v1/*.
• Quando excedido: 429 com header Retry-After em segundos. Espere e retente — não há janela deslizante, o contador zera no início do próximo minuto-cheio.
• Se múltiplos sistemas integrados saem do mesmo IP, o limite é compartilhado. Para volumes maiores, distribua a integração em IPs distintos ou abra um canal com o Sacador.

Filtros e busca

Endpoints de listagem que aceitam s (search) interpretam a string como LIKE substring do lado do servidor. Não há sintaxe especial — s=joão retorna registros contendo "joão" no campo indexado para busca daquele recurso. Veja cada endpoint para saber em qual campo a busca é aplicada.

Multi-tenancy

Toda requisição é automaticamente restrita à conta dona do token. Você não consegue:

• Ler, criar, atualizar ou apagar registros de outra conta.
• Atribuir account_id em POST/PATCH — esse parâmetro é silenciosamente ignorado e sempre forçado para a conta autenticada.
• Referenciar IDs de outra conta em FKs (contact_id, group_id, bank_rule_id, bank_account_id). Tentativas retornam 422 com erro de associação.

Recursos de outra conta acessados por ID direto retornam 404, idêntico ao caso de ID inexistente.

Boas práticas

• Idempotência: as APIs não implementam chaves de idempotência. Em caso de timeout, antes de retentar um POST, consulte o GET correspondente (busque pelo your_code que você gerou, por exemplo) para detectar criação duplicada.
• Backoff em 5xx e 429: use exponencial com jitter. Em 429, respeite o Retry-After.
• Não dependa de campos não documentados. Campos não listados na referência podem mudar formato ou ser removidos sem aviso.
• Versione seus payloads. O Sacador pode adicionar campos nas respostas. Faça parsing tolerante a chaves desconhecidas.
• Use your_code como chave de correlação com o seu sistema, e busque por ele depois — é um campo livre indexável (até 20 chars).