Pular para o conteúdo principal

Introdução

Você que é dev, divirta-se! ✨

A API do Financeiro Inteligente é REST sobre HTTPS, com JSON e autenticação Bearer. Tudo o que as telas fazem com contas a pagar, contas a receber, lançamentos, cadastros e conciliações está disponível para os seus sistemas — no mesmo isolamento por espaço de trabalho do produto.

Primeiros passos​

  1. Gere um token na plataforma, em Integrações → Token de API — ver Autenticação.

  2. Faça a primeira chamada:

    export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

    curl -H "Authorization: Bearer $KOBANA_TOKEN" \
      -H 'User-Agent: Meu Sistema (contato@minhaempresa.com.br)' \
      'https://api.finance.kobana.com.br/v1/financial-accounts'

  3. Explore os recursos — a categoria Recursos, na barra lateral, documenta cada endpoint com exemplos. Ou importe a especificação OpenAPI / a coleção do Postman.

dica

Prefira o sandbox (https://api.finance.sandbox.kobana.com.br/v1) para desenvolver — ver Endpoints.

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 campoFormato
DateTimeFormato ISO8601. Exemplos — Data: 2026-01-24. Data e Hora: 2026-01-24T10:07Z
MoneyString decimal com 2 casas e ponto como separador, em BRL. Ex.: "100.00". Sempre enviado/recebido como string (nunca número), para preservar a precisão dos centavos; até 13 dígitos inteiros. Lançamentos e títulos são sempre positivos — a direção (débito/crédito, custo/receita) vai em type/polaridade, nunca no sinal. Saldos de conta podem ser negativos
UUIDIdentificadores de recursos no formato UUID v4

Convenções​

Convenções usadas nesta documentação:

ConvençãoDescrição
:variableNome de variável que precisa ser substituída em uma URL.
#{variable}Nome de variável que precisa ser substituída por valores da sua conta.
...Conteúdo da resposta truncado para facilitar a leitura.
$KOBANA_TOKENToken de acesso. Para testes em linha de comando, exporte-o: export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx e cole os comandos da documentação no terminal.

Códigos de retorno​

A API retorna códigos HTTP padrão:

CódigoDescrição
✅200 OKRequisição bem-sucedida com corpo de resposta.
✅201 CreatedRecurso criado com sucesso.
✅204 No ContentRequisição bem-sucedida, sem corpo de resposta.
❌400 Bad RequestRequisição inválida, em geral conteúdo mal formado.
❌401 UnauthorizedToken de acesso ausente ou inválido.
❌403 ForbiddenAcesso à API bloqueado ou usuário sem permissão.
❌404 Not FoundEndereço acessado não existe.
❌409 ConflictConflito com o estado atual do recurso — p.ex. reuso de X-Idempotency-Key com outro corpo.
❌422 Unprocessable EntityRequisição válida, mas os dados enviados não são.
❌429 Too Many RequestsLimite de requisições atingido.
❌500 Internal Server ErrorErro interno no processamento. Consulte o status dos servidores.

O envelope e o vocabulário estável de códigos de erro estão em Erros.

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 — as requisições e seus IDs podem ser consultadas no painel do sistema. 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 do Financeiro Inteligente 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. Mais informações: HTTP Cache Docs.

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. Status dos servidores: https://status.kobana.com.br.

Próximos passos​