API pública Condoa

v1.0.0

OAuth 2.0 client credentials, webhooks assinados, cobranças PIX e boleto em uma única chamada, ledger completo. Tudo escopado por condomínio.

OpenAPI 3.1 (YAML) Coleção Postman Começar agora

Começando

1. Crie seu sandbox para obter um client_id e um client_secret (mostrado uma única vez) vinculados a um condomínio de teste.
2. Troque por um access token em POST /api/v1/oauth/token com grant_type=client_credentials.
3. Envie o header Authorization: Bearer <token> em todas as chamadas seguintes.
4. Em requisições que mudam estado, mande Idempotency-Key: <ulid> para poder repetir com segurança em caso de falha de rede (janela de 24h).

Headers

Headers comuns a toda a API. Authorization e Content-Type são de chamada; os demais a Condoa emite (ou aceita) para te dar correlação de logs e segurança contra dupla cobrança.

Header	Direção	Quando usar
Authorization	Envia	`Bearer <access_token>` em toda chamada autenticada. Tokens valem 1h, renovados em `/oauth/token`.
Content-Type	Envia	`application/json` em requisições com corpo, exceto `multipart/form-data` no upload de extrato bancário.
Idempotency-Key	Envia	Opcional, recomendado em `POST/PUT/PATCH/DELETE`. ULID ou string `[A-Za-z0-9_-]{1,255}`. Janela de 24h. Reuso com corpo diferente retorna `409 idempotency_conflict`.
X-Request-Id	Envia + recebe	Opcional. Caller pode mandar (sanitizado para `[A-Za-z0-9_-]{1,64}`); senão a Condoa gera uma ULID. Sempre ecoado na resposta. Use para correlacionar com nossos logs em caso de incidente.
Idempotency-Replayed	Recebe	`1` quando a resposta veio do cache de idempotência (não executou a operação de novo).
X-RateLimit-Limit	Recebe	Teto da janela atual: 600 req/min por token, 60 req/min por IP sem token.
X-RateLimit-Remaining	Recebe	Quantas requisições ainda cabem na janela.
Retry-After	Recebe	Segundos a esperar antes da próxima tentativa quando vier `429 Too Many Requests`.

Escopos

Cada token é vinculado a um condomínio e a um conjunto de escopos. Peça apenas o que for usar.

Escopo	O que libera
invoices.read / .write	Cobranças, items, payment options, inadimplência, índices monetários
expenses.read / .write	Despesas, parcelas, anexos, dados de pagamento do fornecedor
cadastros.read / .write	Condomínios, blocos, unidades, moradores, veículos, funcionários, fornecedores
bank.read / .write	Contas bancárias, movimentos, conciliação, importação de extrato
plano-de-contas.read / .write	Plano de contas, lançamentos, transferências, períodos
webhooks.manage	Assinaturas de webhooks