API do Financeiro Inteligente
Você que é dev, divirta-se! ✨
Índice da documentação — acesse o índice completo em https://docs.finance.kobana.com.br/llms.txt. Use este arquivo para descobrir todas as páginas disponíveis antes de explorar.
Autenticação
Toda requisição precisa de duas coisas: o token, que diz qual organização você é, e o cabeçalho X-Workspace-Id, que diz em qual espaço de trabalho dela agir.
Authorization: Bearer <token>
X-Workspace-Id: <uuid do espaço de trabalho>
O token
Bearer JWT assinado em RS256 pelo servidor de autorização da Kobana (HS512 apenas contra um servidor de desenvolvimento local).
| Claim | Papel |
|---|---|
org | O tenant. O public_id da organização — é o que decide quais dados o token alcança. |
sub | A pessoa que autorizou. Existe para auditoria e não delimita nada. |
scope | Lista separada por espaços (ex.: finance.payables finance.people.write). Um escopo .write também vale como leitura. |
jti | Identificador do token, usado para revogação. |
iss / aud / exp | Emissor, destinatário e expiração. |
⚠️ O tenant é org, nunca sub. São espaços de identificadores diferentes: um id de pessoa jamais corresponde a uma organização, então um token montado com o valor errado falha em toda requisição.
O cabeçalho X-Workspace-Id
Uma organização pode ter vários espaços de trabalho, e toda rota desta API responde por exatamente um. O token sozinho não diz qual — por isso o cabeçalho é obrigatório em todas as operações.
Ele é um seletor, nunca uma permissão: o espaço informado é conferido contra a organização do token. Um espaço que pertence a outra organização responde exatamente como um que não existe — de propósito, para a resposta não revelar que aquele id é real em outro lugar.
| Situação | Resposta |
|---|---|
| Cabeçalho ausente | 400 WORKSPACE_REQUIRED |
| Espaço de outra organização, inexistente, ou id malformado | 403 UNKNOWN_WORKSPACE |
org não corresponde a nenhuma organização | 403 UNKNOWN_ORGANIZATION |
| Escopo insuficiente para a operação | 403 INSUFFICIENT_SCOPE |
Uma regra de Segurança do espaço barrou a operação (details.reason diz qual) | 403 SECURITY_BLOCKED |
Exemplo
curl https://api.finance.kobana.com.br/v1/payables \
-H "Authorization: Bearer $KOBANA_TOKEN" \
-H "X-Workspace-Id: $KOBANA_WORKSPACE_ID"
Para testes em linha de comando, exporte os dois: export KOBANA_TOKEN=xxxxxxxx e export KOBANA_WORKSPACE_ID=xxxxxxxx, e cole os comandos da documentação no terminal.
Formato
A API aceita apenas o formato JSON. Todas as requisições devem usar Content-Type: application/json. Todas as respostas usam snake_case.
| Tipo de Campo | Formato |
|---|---|
| DateTime | Formato ISO8601. Exemplos — Data: 2026-01-24. Data e Hora: 2026-01-24T10:07:00.000Z |
| Money | Decimal como string com 2 casas ("150.00"). Sempre positivo — direção indicada pelo campo type (debit/credit) ou pelo contexto (payable/receivable). |
| UUID | Identificadores de recursos no formato UUID v4 |
Convenções
Convenções usadas nesta documentação:
| Convenção | Descrição |
|---|---|
:id | Parâmetro de path que deve ser substituído pelo UUID do recurso. |
#{variable} | Valor da sua conta que deve ser substituído no exemplo. |
... | Conteúdo da resposta truncado para facilitar a leitura. |
$KOBANA_TOKEN | Token JWT de acesso. Exporte com export KOBANA_TOKEN=xxxxxxxx. |
$KOBANA_WORKSPACE_ID | UUID do espaço de trabalho, enviado em X-Workspace-Id. Exporte com export KOBANA_WORKSPACE_ID=xxxxxxxx. |
Ambientes
| Ambiente | Base URL |
|---|---|
| Produção | https://api.finance.kobana.com.br/v1 |
| Sandbox | https://api.finance.sandbox.kobana.com.br/v1 |
Códigos de Retorno
A API retorna códigos HTTP padrão:
| Código | Descrição | |
|---|---|---|
| ✅ | 200 OK | Requisição bem-sucedida com corpo de resposta. |
| ✅ | 201 Created | Recurso criado com sucesso. |
| ✅ | 204 No Content | Requisição bem-sucedida, sem corpo de resposta. |
| ❌ | 400 Bad Request | Requisição inválida — conteúdo mal formado, filtro não permitido, ou X-Workspace-Id ausente. |
| ❌ | 401 Unauthorized | Token ausente, inválido ou expirado. |
| ❌ | 403 Forbidden | Escopo insuficiente, organização desconhecida, ou espaço de trabalho fora dela. |
| ❌ | 404 Not Found | Recurso não encontrado ou fora do workspace. |
| ❌ | 422 Unprocessable Entity | Requisição válida, mas os dados enviados não são. |
| ❌ | 429 Too Many Requests | Limite de requisições atingido. |
| ❌ | 500 Internal Server Error | Erro interno no processamento. Consulte o status dos servidores. |
Listagem e Paginação
Todos os endpoints de listagem usam paginação por cursor:
GET /v1/payables?cursor=<opaque_cursor>&limit=25
A resposta inclui meta.next_cursor — passe-o como ?cursor= na próxima requisição para buscar a página seguinte. Quando meta.next_cursor é null, não há mais páginas.
Idempotência
Operações de criação (POST) aceitam o cabeçalho X-Idempotency-Key. Reenvios com a mesma chave retornam o resultado original sem criar duplicatas — seguro para retry em caso de falha de rede.
X-Idempotency-Key: <uuid-v4-gerado-pelo-cliente>
ID das Requisições (Request ID)
Cada requisição possui um identificador associado, disponível no cabeçalho Request-Id da resposta. Esse valor ajuda na depuração e auditoria. O log de requisições fica disponível por 30 dias. Ao abrir um chamado de suporte sobre uma requisição específica, informe o Request-Id para acelerar a investigação.
Segurança
A API usa certificados SSL 2048 bits. Toda requisição deve ser feita via HTTPS — chamadas na porta 80 são redirecionadas para 443.
Os clientes devem suportar TLSv1.2 ou TLSv1.3 com uma das cifras: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-CHACHA20-POLY1305, ECDHE-RSA-AES256-SHA384. TLSv1 e TLSv1.1 não são suportados.
Cache HTTP
Use os cabeçalhos HTTP de cache para reduzir carga e ganhar velocidade. A maioria das respostas inclui ETag e/ou Last-Modified — armazene esses valores e reenvie nas próximas requisições via If-None-Match e If-Modified-Since. Se o recurso não mudou, a resposta será 304 Not Modified, sem corpo e sem reprocessamento.
Tratamento de Erros
Erros 5xx indicam falhas no servidor: 500 Internal Server Error (aplicação indisponível), 502 Bad Gateway, 503 Service Unavailable e 504 Gateway Timeout (falhas pontuais de infraestrutura). Sua aplicação deve identificar esses códigos e reagendar a requisição após alguns minutos com backoff exponencial. Status dos servidores: https://status.kobana.com.br.
Spec OpenAPI
Importe a spec no Postman ou Insomnia para ter uma coleção pronta que sempre reflete a API atual:
- YAML:
/api/v1/openapi.yaml - JSON:
/api/v1/openapi.json