Conceitos
Visão geral
A Saq é uma API REST com 29 endpoints divididos em 7 grupos. Toda a comunicação acontece em JSON, sobre HTTPS, com Bearer token. Valores monetários estão sempre em reais (BRL), não em centavos.
Os 7 grupos de endpoints
| Grupo | Endpoints | O que faz |
|---|---|---|
| Cobranças Pix | 4 | Criar e consultar cobranças Pix (depósitos), QR Code, comprovante. |
| Saques | 6 | Enviar Pix por chave ou QR Code, consulta DICT, leitura de QR. |
| Transferência interna | 2 | Mover saldo entre contas Saq, instantâneo. |
| Conta | 2 | Perfil, permissões, limites e saldo. |
| Relatórios | 6 | Listar transações, gerar CSV assíncrono. |
| Callbacks | 4 | Inspecionar e reenviar webhooks. |
| Infrações (MED) | 5 | Disputas Pix iniciadas pelo pagador e submissão de defesa. |
Modelo de transação
Toda movimentação na Saq é representada por uma transação. Independente de ser cobrança, saque ou transferência interna, a estrutura básica é a mesma.
Campos principais
| Campo | Tipo | Para que serve |
|---|---|---|
id | string | Identificador único da transação na Saq. |
type | string | DEPOSIT, WITHDRAW ou INTERNAL_TRANSFER. |
status | string | Estado atual. Os mais comuns: PENDING, COMPLETED, REFUNDED, EXPIRED, ERROR. |
amount | number | Valor em reais (BRL), não em centavos. Ex: 10.90 é R$ 10,90. |
clientReference | string | Seu identificador externo. Volta em todo callback. Use para idempotência e lookup. |
virtualAccount | string | Subconta virtual (até 50 chars). Use para multi-tenant (lojas, filiais, marketplaces). |
callbackUrl | string | URL para receber atualizações de status via webhook. |
endToEndId | string | Identificador único da operação no Bacen. Útil para rastrear em disputas. |
Todos os campos detalhados no Glossário.
Ciclo de vida típico
Estados completos por tipo na referência de cada endpoint. Tabela rápida no Glossário · Status de transação.
Convenções da API
| Item | Valor |
|---|---|
| Base URL | https://api.saq.processamento.com/v1 |
| Autenticação | Authorization: Bearer SEU_TOKEN |
| Content-Type | application/json (obrigatório em toda chamada) |
| Valores | Em reais (BRL), nunca em centavos |
| Datas | ISO 8601 (2025-11-23T10:46:26.986Z) |
| Encoding | UTF-8 |
| Paginação | page + limit com flag hasNextPage |
| Webhooks | POST em callbackUrl, retry até 72x |