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
A API usa Bearer JWT (HS512). Envie o token no cabeçalho de toda requisição:
Authorization: Bearer <token>
Para testes em linha de comando, exporte o token: export KOBANA_TOKEN=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. |
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, em geral conteúdo mal formado. |
| ❌ | 401 Unauthorized | Token ausente, inválido ou expirado. |
| ❌ | 403 Forbidden | Escopo insuficiente para a operação. |
| ❌ | 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