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

1. Autenticação: Obtenha token JWT do ecosif-auth
2. Requisição: Use o token em requisições para o ecosif-masterdata
3. Validação: O serviço valida o token e processa a requisição
4. 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:

1. Autenticação: Aprenda a autenticar e obter tokens
2. Uso da API: Saiba como usar a API
3. Exemplos: Veja exemplos práticos
4. 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.