kroz docs
Referência de API
Visão das capacidades da API operacional do piloto incorporadoras.
Base: https://app.kroz.co
Formato: JSON
Estágio: v0, piloto interno, sem versionamento público /v1
O que a API cobre
A API orquestra a mesa de operação, não substitui a UI para o dia a dia do CFO, mas permite integrar ERP, relatórios e automações controladas.
| Domínio | Capacidades |
|---|---|
| Auth | Login, verificação e encerramento de sessão |
| Contratos | Consultar contrato comercial e matriz de rateio vigente |
| Pagadoria | Gerar cobrança com split na origem (dry-run e execução real) |
| Recebedores | Subcontas e cadastro de pagador no parceiro BaaS |
| Conciliação | Listar sugestões e registrar decisão do DF |
| Rule Engine | Simular regra (dry-run) antes de liquidar |
| Auditoria | Registrar e exportar eventos da trilha |
| Webhooks | Receber liquidações do parceiro BaaS (inbound) |
| Relatórios | Captabilidade e health operacional |
Autenticação (resumo)
| Contexto | Mecanismo |
|---|---|
| Browser | Sessão após login no app |
| Integração | Token de sessão no header Authorization |
| Webhook BaaS | Credencial dedicada (não usa sessão de operador) |
Ver Autenticação.
Erros comuns
| Status | Significado típico |
|---|---|
| 400 | Payload inválido |
| 401 | Sessão expirada ou ausente |
| 403 | Freio operacional · escrita real bloqueada |
| 404 | Contrato ou recurso não encontrado |
| 409 | Operação já processada (idempotência) |
| 502 / 504 | Parceiro BaaS indisponível ou timeout |
Respostas seguem envelope { ok, error?, message?, details? }.
Execução real vs dry-run
Por padrão, a plataforma opera em dry-run: simula payloads e validações sem efeito financeiro.
Escritas reais (cobrança, subconta, transferência) exigem:
- Confirmação tipada na UI ou no body da API
- Flags de ambiente habilitadas pelo time kroz
- Header de idempotência em operações mutáveis
Isso evita acidentes em piloto. O checklist exato é compartilhado no onboarding técnico.
SDK da UI
O app usa um cliente interno (platform-api.js) para contratos, pagadoria, conciliação e relatórios. Integradores externos podem espelhar os mesmos fluxos via HTTP, a spec detalhada descreve os contratos.