Visão geral das integrações
A API do COBRES permite conectar sistemas à organização usando as mesmas permissões e regras de escopo aplicadas à equipe. O contrato deve ser confirmado na versão do ambiente integrado; recursos habilitados dependem da configuração e das capacidades disponíveis.
Endereço da API
A API de produção responde em https://api.cobres.com.br. O domínio institucional é cobres.com.br e a documentação fica em docs.cobres.com.br. Ambientes de teste e homologação têm endereço próprio, informado pela equipe COBRES junto com as credenciais de acesso.
Nos exemplos, COBRES_API_URL representa a origem do ambiente integrado (em produção, https://api.cobres.com.br). O desenvolvimento local usa http://localhost:8000.
Convenções
| Item | Convenção |
|---|---|
| Prefixo de equipe e integrações | /api/v1 |
| Prefixo do portal externo | /api/audience/v1 |
| Corpo das operações | JSON, conforme schema da rota |
| Autenticação de integração | Authorization: Bearer com chave da organização |
| Valores monetários de dívida | Inteiros em centavos nos campos terminados em _cents |
| Data civil | YYYY-MM-DD |
| Diagnóstico | Header X-Request-ID e campo request_id dos erros |
| Listagem padrão | Objeto com items e page |
Identificadores
Muitos recursos retornam id como UUID e code como código público. As rotas com resolvedores de código esperam quatro caracteres no caminho, mesmo quando o parâmetro se chama debt_id ou company_id. O alfabeto evita caracteres ambíguos. Exemplo: /api/v1/debts/ABCD.
Associações em corpos JSON continuam seguindo o schema; por exemplo, company_id na criação de dívida é UUID. Não troque automaticamente todos os IDs por códigos. Algumas rotas, como as de cotações, têm contratos próprios.
Descoberta do contrato
Em desenvolvimento, a API disponibiliza Swagger em /docs, ReDoc em /redoc e OpenAPI em /openapi.json. Esses caminhos ficam desligados em produção. Para gerar clientes, utilize o schema da versão validada pela equipe, sem depender de um endpoint público de produção.
Comece por autenticação, API de cobrança e paginação. Planeje tratamento de erros, interrupções de rede e resultados de processamento assíncrono.