Introdução para Integradores - ecosif-masterdata¶

Bem-vindo!¶

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

O que é o ecosif-masterdata?¶

O ecosif-masterdata é o serviço central de gerenciamento de dados mestres do ecossistema eCosif. Ele fornece:

APIs REST completas para gerenciar empresas, filiais, planos de contas, documentos, lançamentos
Validações de negócio para garantir consistência dos dados
Multi-tenancy com isolamento por empresa e filial
Integração com APIs externas (CNPJ, CEP)

Por que usar o ecosif-masterdata?¶

✅ API Completa: 100+ endpoints documentados
✅ Bem Documentado: Swagger UI interativo
✅ Validações: Regras de negócio aplicadas automaticamente
✅ Multi-tenancy: Suporte a múltiplas empresas e filiais
✅ Padrões REST: Interface RESTful padrão

Como Funciona¶

Fluxo Básico¶

Autenticação: Obtenha token JWT do ecosif-auth
Requisição: Use o token em requisições para o ecosif-masterdata
Validação: O serviço valida o token e processa a requisição
Resposta: Retorna dados ou resultado da operação

┌─────────┐         ┌──────────────┐         ┌─────────────┐
│ Cliente │────────>│ ecosif-auth  │────────>│   Token     │
│         │  Login  │              │         │    JWT      │
└─────────┘         └──────────────┘         └─────────────┘
     │                                           │
     │         ┌─────────────────────────────────┘
     │         │
     ▼         ▼
┌──────────────────────────────────────┐
│  ecosif-masterdata                   │
│  (valida token e processa requisição)│
└──────────────────────────────────────┘

Endpoints Principais¶

Gestão de Entidades¶

Empresas: /company, /companies
Filiais: /branch, /allbranch/{company}
Plano de Contas: /chartOfAccounts
Documentos: /document, /alldocument/{batchId}
Lançamentos: /entry, /allentry/{documentId}

Configurações¶

Opções de Empresas: /company/options
Configurações de Fechamento: /closuresettings
Configurações de Fundos: /fund/settings

Processamentos¶

Consolidação: /runconsolidation

Veja Lista Completa de Endpoints para todos os endpoints disponíveis.

Autenticação¶

IMPORTANTE: Todos os endpoints (exceto /actuator/** e /swagger-ui/**) requerem autenticação JWT.

O token JWT deve ser obtido do serviço ecosif-auth (porta 8080). Veja Autenticação para mais detalhes.

Base URL¶

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

Multi-Tenancy¶

O sistema suporta isolamento de dados por empresa e filial. Muitos endpoints requerem parâmetros company e branch para identificar o contexto.

Exemplo:

GET /allbranch/{company}
GET /chartOfAccounts/getallcoa/{company}/{branch}

Códigos de Status HTTP¶

200 OK: Requisição bem-sucedida
201 Created: Recurso criado com sucesso
400 Bad Request: Dados inválidos
401 Unauthorized: Não autenticado ou token inválido
403 Forbidden: Não autorizado
404 Not Found: Recurso não encontrado
406 Not Acceptable: Violação de regra de negócio
409 Conflict: Recurso já existe
500 Internal Server Error: Erro interno do servidor

Formato de Respostas¶

Sucesso¶

{
  "id": 1,
  "name": "Minha Empresa",
  "cnpj": "12345678000190"
}

Erro¶

{
  "success": false,
  "message": "Mensagem de erro descritiva"
}

Próximos Passos¶

Para começar a integrar:

Autenticação: Aprenda a autenticar e obter tokens
Uso da API: Saiba como usar a API
Exemplos: Veja exemplos práticos
Erros Comuns: Resolva problemas frequentes

Recursos Adicionais¶

Swagger UI: Interface interativa para testar a API
OpenAPI Spec: Especificação completa da API
Documentação de Endpoints: Lista completa de endpoints

Suporte¶

Para suporte: - Consulte a documentação completa em /docs - Teste endpoints no Swagger UI - Entre em contato com a equipe de desenvolvimento

Versão da API¶

Versão atual: 0.7.01.202511281

A API segue versionamento semântico. Mudanças que quebram compatibilidade serão sinalizadas com antecedência.