Saltar al contenido principal

Introdução

Você que é dev, divirta-se! ✨

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
Money (_cents)Inteiro em centavos (÷100). Ex.: 10000 = R$ 100,00
Money (_subcents)Inteiro em subcentavos (÷10000), usado em precificação. Ex.: 1000000 = R$ 100,00
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.
❌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.

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 da Kobana 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.

Valores monetários​

Valores monetários seguem duas convenções: campos com sufixo _cents (÷100) e campos de precificação com sufixo _subcents (÷10000). Use estas convenções para converter para reais (BRL) antes de exibir ao usuário final.

Próximos passos​