Introdução para Integradores - ecosif-compliance¶

Bem-vindo!¶

Este documento fornece uma visão geral do serviço ecosif-compliance para integradores que desejam utilizar a API.

O que é o ecosif-compliance?¶

O ecosif-compliance é a API de validação de conformidade contábil do ecossistema eCosif. Ele:

Lê saldos e cadastros já persistidos (mesmo banco do eCosif)
Executa regras configuráveis (DSL) associadas a documentos
Registra o resultado de cada regra por processo (filial + documento + mês)
Não altera lançamentos; apenas valida e reporta

Por que usar o ecosif-compliance?¶

API REST documentada em OpenAPI 3 (/v3/api-docs) com UI em /docs/
Regras versionáveis em script (DSL) com teste sem persistência
Isolamento por empresa/filial alinhado aos demais serviços
Autenticação JWT no mesmo padrão do ecosif-masterdata

Como funciona¶

Autenticação: obtenha token JWT no ecosif-auth
Requisição: envie o token no header Authorization
Validação: o middleware valida o token e processa a chamada
Resposta: dados JSON ou mensagem de erro padronizada

┌─────────┐         ┌──────────────┐         ┌─────────────┐
│ Cliente │────────>│ ecosif-auth  │────────>│   Token     │
│         │  Login  │   :8080      │         │    JWT      │
└─────────┘         └──────────────┘         └─────────────┘
     │                                           │
     │         ┌─────────────────────────────────┘
     ▼         ▼
┌──────────────────────────────────────┐
│  ecosif-compliance (:8021)           │
│  (valida token e executa a regra)    │
└──────────────────────────────────────┘

Endpoints principais¶

Regras: /api/compliance/rule/list, /rule/add, /rule/update
Validação: /api/compliance/run, /api/compliance/test
Consultas: /cluetype/list, /document/list, /company/list, /branch/list
Processos: /api/compliance/process/result/list/, /process/result/get/{processid}

Veja a lista completa de endpoints e o OpenAPI.

Autenticação¶

Importante: com auth habilitada (padrão), todos os endpoints de negócio exigem JWT emitido pelo ecosif-auth (porta 8080).

Rotas públicas: /health, /actuator/**, /docs/ e /v3/api-docs (quando o Swagger está ligado).

Detalhes em Autenticação.

Base URL¶

Desenvolvimento: http://localhost:8021
Produção: https://api.ecosif.net.br/ecosif-compliance

Atrás do gateway, o prefixo /ecosif-compliance é aplicado (paridade com os serviços Java).

Isolamento¶

Listagens de processo e a execução de validação respeitam o acesso do usuário à empresa / filial. Não use tenant_id genérico para filtrar dados de negócio.

Códigos de Status HTTP¶

200 OK: requisição bem-sucedida
400 Bad Request: dados inválidos
401 Unauthorized: token ausente, inválido ou expirado
403 Forbidden: autenticado sem permissão
500 Internal Server Error: erro interno
503 Service Unavailable: health check em falha

Formato de respostas¶

Sucesso¶

Corpo JSON específico do endpoint (lista, objeto de processo, etc.).

Erro¶

{
  "response-code": 1,
  "response-message": "Mensagem de erro descritiva",
  "message-mode": "ALERT"
}

Próximos passos¶

Versão da API¶

Versão do artefato: ver app/version (formato 0.7.xx.YYYYMMDDN). O campo info.version do OpenAPI acompanha esse valor em runtime.