API do Faturamento Automático
Você que é dev, divirta-se! ✨
Índice da documentação — acesse o índice completo em https://docs.billing.kobana.com.br/llms.txt. Use este arquivo para descobrir todas as páginas disponíveis antes de explorar.
Atenção às versões da API — você está na documentação da v1.0 da API do Faturamento Automático, que cobre os endpoints de Assinaturas (criação, alteração de plano, pausa, cancelamento, faturamento manual, sincronização de itens) e recursos correlatos. Recursos como Pagamentos, Transferências, Extrato e Recebimento por Pix seguem disponíveis em outras APIs da Kobana — use o seletor de produto no menu superior para acessá-las.
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: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 |
| UUID | Identificadores de recursos no formato UUID v4 |
Convenções
Convenções usadas nesta documentação:
| Convenção | Descrição |
|---|---|
:variable | Nome 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_TOKEN | Token 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ó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 de acesso ausente ou inválido. |
| ❌ | 403 Forbidden | Acesso à API bloqueado ou usuário sem permissão. |
| ❌ | 404 Not Found | Endereço acessado não existe. |
| ❌ | 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. |
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.