Referência de API
Princípios e recursos da integração entre a kroz e os sistemas autorizados de cada organização.
Disponibilidade
A API é liberada durante o onboarding técnico, de acordo com o escopo contratado e os ambientes aprovados.
Esta documentação pública descreve o modelo de integração. URLs, credenciais, escopos e especificações executáveis são entregues ao responsável técnico em canal controlado.
Para solicitar acesso, fale com contato@kroz.co.
Princípios da integração
| Princípio | Aplicação |
|---|---|
| Servidor para servidor | Credenciais de integração não devem circular no navegador |
| Menor privilégio | Cada credencial recebe somente os recursos necessários |
| Ambientes separados | Homologação e produção usam credenciais e dados distintos |
| Idempotência | Repetições não podem duplicar uma operação financeira |
| Rastreabilidade | Cada solicitação relevante recebe correlação e evidência |
| Falha segura | Ausência de validação impede a execução real |
Recursos do domínio
A superfície de integração é organizada em torno do ciclo operacional:
| Recurso | Responsabilidade |
|---|---|
| Organização | Delimitar o contexto autorizado da operação |
| Contratos e unidades | Referenciar a origem comercial do recebível |
| Recebedores | Identificar as partes habilitadas a receber |
| Matrizes de rateio | Representar regras, versões e condições de distribuição |
| Cobranças | Associar pagador, valor, vencimento e meio de pagamento |
| Liquidações | Confirmar o resultado financeiro informado pelo parceiro financeiro |
| Conciliações | Resolver diferenças entre o esperado e o realizado |
| Evidências | Preservar eventos, decisões e resultados verificáveis |
Nem todos os recursos são liberados para toda integração. O contrato e o desenho de segurança definem o escopo disponível.
Fluxo recomendado
- autentique o sistema no ambiente autorizado;
- envie ou localize as referências do contrato;
- valide recebedores e matriz antes de qualquer cobrança;
- use uma chave idempotente em operações mutáveis;
- registre o identificador de correlação retornado;
- processe confirmações de forma idempotente;
- encaminhe exceções para conciliação e decisão humana;
- preserve a evidência necessária para auditoria.
Autenticação e credenciais
Credenciais programáticas são diferentes da sessão usada por operadores no navegador.
- mantenha segredos em um cofre apropriado;
- não envie credenciais em URLs, logs ou código-fonte;
- restrinja o uso aos ambientes e origens previstos;
- defina responsável, rotação e revogação;
- trate uma suspeita de exposição como incidente.
Consulte Autenticação.
Idempotência
Toda operação capaz de criar ou alterar efeito financeiro deve ser repetível com segurança.
Uma mesma intenção, enviada novamente com a mesma chave idempotente, deve recuperar o resultado anterior ou informar o estado existente. Uma intenção nova deve usar uma chave nova.
Não derive a chave apenas de data e valor. Inclua uma referência estável da intenção de negócio.
Respostas e erros
As integrações recebem respostas estruturadas com:
- resultado da solicitação;
- identificador de correlação;
- estado atual da operação;
- código de erro estável quando houver falha;
- mensagem adequada para diagnóstico, sem revelar configuração interna.
Categorias esperadas incluem validação, autenticação, autorização, conflito, limite de uso, indisponibilidade temporária e timeout.
Clientes devem tratar erros por categoria e código, não por comparação literal da mensagem.
Confirmações e eventos
Confirmações de pagamento e outros eventos podem chegar mais de uma vez ou fora de ordem. O consumidor deve:
- validar a autenticidade da origem;
- deduplicar pelo identificador do evento;
- registrar o recebimento antes de produzir efeitos;
- tolerar reenvio;
- encaminhar diferenças para conciliação.
Consulte Webhooks para o modelo conceitual.
Versionamento
Mudanças incompatíveis são apresentadas em uma nova versão ou coordenadas durante o onboarding. Campos adicionais podem ser introduzidos de forma compatível; consumidores devem ignorar campos desconhecidos quando isso não alterar a regra de negócio.
Especificações detalhadas e exemplos do ambiente contratado prevalecem sobre esta visão pública.
Checklist de integração
- Autenticação e responsável por credenciais definidos
- homologação concluída sem dados ou efeitos de produção
- idempotência validada para operações mutáveis
- correlação e observabilidade implantadas
- reenvio de eventos testado
- procedimento de revogação documentado
- conciliação e evidência incluídas no desenho