# 04. 👥 Clientes, Fornecedores e Transportadoras

**Gestão de relacionamentos comerciais** Cadastro e controle de clientes, fornecedores e transportadoras da sua empresa. **Funcionalidades:**

* Cadastrar e consultar clientes comerciais
* Cadastrar e consultar fornecedores
* Cadastrar e consultar transportadoras
* Gestão de contatos e endereços
* Vincular múltiplos tipos a uma mesma pessoa/empresa

## Lista indicadores financeiros de notas fiscais do stakeholder

> \*\*Módulo Financeiro - Indicadores de Notas Fiscais\*\*\
> \
> Retorna resumo financeiro consolidado das notas fiscais de saída aceitas para um stakeholder específico.\
> \
> \*\*📊 Indicadores retornados:\*\*\
> \- \*\*Valor total das NF-es:\*\* Soma dos valores finais de todas as notas\
> \- \*\*Total de devoluções:\*\* Valor total das devoluções realizadas\
> \- \*\*Valor líquido dos pedidos:\*\* Valor dos pedidos descontando devoluções\
> \- \*\*Total faturado:\*\* Valor efetivamente faturado\
> \- \*\*Total liquidado:\*\* Valor já recebido/liquidado\
> \- \*\*Falta faturar:\*\* Valor ainda pendente de faturamento\
> \- \*\*Falta liquidar:\*\* Valor faturado mas não recebido\
> \
> \*\*🎯 Casos de uso:\*\*\
> \- Dashboard financeiro por cliente\
> \- Análise de inadimplência\
> \- Controle de recebíveis por stakeholder\
> \- Relatórios de performance comercial

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"04. 👥 Clientes, Fornecedores e Transportadoras","description":"**Gestão de relacionamentos comerciais**\nCadastro e controle de clientes, fornecedores e transportadoras da sua empresa.\n**Funcionalidades:**\n- Cadastrar e consultar clientes comerciais\n- Cadastrar e consultar fornecedores\n- Cadastrar e consultar transportadoras\n- Gestão de contatos e endereços\n- Vincular múltiplos tipos a uma mesma pessoa/empresa"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/stakeholders/{stakeholder_id}/financeiro_notas_fiscais":{"get":{"summary":"Lista indicadores financeiros de notas fiscais do stakeholder","tags":["04. 👥 Clientes, Fornecedores e Transportadoras"],"description":"**Módulo Financeiro - Indicadores de Notas Fiscais**\n\nRetorna resumo financeiro consolidado das notas fiscais de saída aceitas para um stakeholder específico.\n\n**📊 Indicadores retornados:**\n- **Valor total das NF-es:** Soma dos valores finais de todas as notas\n- **Total de devoluções:** Valor total das devoluções realizadas\n- **Valor líquido dos pedidos:** Valor dos pedidos descontando devoluções\n- **Total faturado:** Valor efetivamente faturado\n- **Total liquidado:** Valor já recebido/liquidado\n- **Falta faturar:** Valor ainda pendente de faturamento\n- **Falta liquidar:** Valor faturado mas não recebido\n\n**🎯 Casos de uso:**\n- Dashboard financeiro por cliente\n- Análise de inadimplência\n- Controle de recebíveis por stakeholder\n- Relatórios de performance comercial","responses":{"200":{"description":"Indicadores financeiros retornados com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"financeiro_notas_fiscais":{"type":"object","description":"Indicadores financeiros consolidados","properties":{"valor_nota_nfe":{"type":"number","format":"decimal","description":"Valor total das notas fiscais eletrônicas"},"total_devolucoes":{"type":"number","format":"decimal","description":"Valor total das devoluções"},"valor_pedido_liquido":{"type":"number","format":"decimal","description":"Valor líquido dos pedidos (sem devoluções)"},"total_faturado":{"type":"number","format":"decimal","description":"Total efetivamente faturado"},"total_liquidado":{"type":"number","format":"decimal","description":"Total já recebido/liquidado"},"falta_faturar":{"type":"number","format":"decimal","description":"Valor ainda pendente de faturamento"},"falta_liquidar":{"type":"number","format":"decimal","description":"Valor faturado mas não recebido"}},"required":["valor_nota_nfe","total_devolucoes","valor_pedido_liquido","total_faturado","total_liquidado","falta_faturar","falta_liquidar"]}},"required":["financeiro_notas_fiscais"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Stakeholder não encontrado"}}}}}}
```

## Lista stakeholders

> \*\*Módulo CRM - Gestão completa de relacionamentos comerciais\*\*\
> \
> Lista todos os stakeholders (parceiros comerciais) cadastrados:\
> \
> \*\*👥 Tipos de stakeholder:\*\*\
> \- \*\*Clientes:\*\* Pessoas ou empresas que compram produtos/serviços\
> \- \*\*Fornecedores:\*\* Empresas que fornecem matérias-primas ou produtos\
> \- \*\*Transportadoras:\*\* Empresas responsáveis pela logística\
> \
> \*\*📈 Informações retornadas:\*\*\
> \- Dados básicos (nome, documento, contato)\
> \- Endereço completo e localização\
> \- Informações fiscais (inscrições, regime tributário)\
> \- Lista de contatos cadastrados

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"04. 👥 Clientes, Fornecedores e Transportadoras","description":"**Gestão de relacionamentos comerciais**\nCadastro e controle de clientes, fornecedores e transportadoras da sua empresa.\n**Funcionalidades:**\n- Cadastrar e consultar clientes comerciais\n- Cadastrar e consultar fornecedores\n- Cadastrar e consultar transportadoras\n- Gestão de contatos e endereços\n- Vincular múltiplos tipos a uma mesma pessoa/empresa"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/stakeholders":{"get":{"summary":"Lista stakeholders","tags":["04. 👥 Clientes, Fornecedores e Transportadoras"],"description":"**Módulo CRM - Gestão completa de relacionamentos comerciais**\n\nLista todos os stakeholders (parceiros comerciais) cadastrados:\n\n**👥 Tipos de stakeholder:**\n- **Clientes:** Pessoas ou empresas que compram produtos/serviços\n- **Fornecedores:** Empresas que fornecem matérias-primas ou produtos\n- **Transportadoras:** Empresas responsáveis pela logística\n\n**📈 Informações retornadas:**\n- Dados básicos (nome, documento, contato)\n- Endereço completo e localização\n- Informações fiscais (inscrições, regime tributário)\n- Lista de contatos cadastrados","parameters":[{"name":"tipo","in":"query","schema":{"type":"string","enum":["cliente","fornecedor","transportadora","fabricante","funcionario"]},"description":"Filtrar por tipo de stakeholder","required":false},{"name":"ultima_modificacao","in":"query","schema":{"type":"string","format":"datetime"},"description":"Stakeholders modificados a partir desta data/hora","required":false},{"name":"page","in":"query","schema":{"type":"integer","minimum":1},"description":"Número da página para paginação (padrão: 1)","required":false}],"responses":{"200":{"description":"Lista de stakeholders retornada com sucesso","content":{"Lista de stakeholders":{},"application/json":{"schema":{"type":"object","properties":{"stakeholders":{"type":"array","description":"Array de stakeholders","items":{"type":"object","properties":{"id":{"type":"string","description":"UUID do stakeholder"},"tipos":{"type":"array","items":{"type":"string"},"description":"Tipos do stakeholder (cliente, fornecedor, etc)"},"cnpj":{"type":"string","nullable":true,"description":"CPF ou CNPJ"},"razao_social":{"type":"string","description":"Razão social ou nome"},"nome_fantasia":{"type":"string","nullable":true,"description":"Nome fantasia"},"inscricao_estadual":{"type":"string","nullable":true,"description":"Inscrição estadual"},"indicador_ie":{"type":"string","nullable":true,"description":"Indicador de IE (1=Contribuinte, 2=Isento, 9=Não contribuinte)"},"inscricao_suframa":{"type":"string","nullable":true,"description":"Inscrição SUFRAMA"},"cep":{"type":"string","nullable":true,"description":"CEP"},"endereco":{"type":"string","nullable":true,"description":"Logradouro"},"numero":{"type":"string","nullable":true,"description":"Número"},"complemento":{"type":"string","nullable":true,"description":"Complemento"},"bairro":{"type":"string","nullable":true,"description":"Bairro"},"municipio":{"type":"string","nullable":true,"description":"Nome do município"},"uf":{"type":"string","nullable":true,"description":"Nome do estado"},"contatos":{"type":"array","nullable":true,"description":"Lista de contatos","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID do contato"},"nome":{"type":"string","description":"Nome do contato"},"email":{"type":"string","nullable":true,"description":"Email"},"cargo":{"type":"string","nullable":true,"description":"Cargo"},"ddi":{"type":"string","nullable":true,"description":"DDI"},"ddd":{"type":"string","nullable":true,"description":"DDD"},"telefone":{"type":"string","nullable":true,"description":"Telefone"},"principal":{"type":"boolean","description":"Se é o contato principal"}}}}},"required":["id","tipos","razao_social"]}},"pagination":{"type":"object","description":"Informações de paginação","properties":{"total":{"type":"integer","description":"Total de páginas"},"count":{"type":"integer","description":"Total de registros na página"},"previous_page":{"type":"string","nullable":true,"description":"URL da página anterior"},"next_page":{"type":"string","nullable":true,"description":"URL da próxima página"}}}},"required":["stakeholders","pagination"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Cria stakeholder

> \*\*Criar ou buscar cliente, fornecedor ou transportadora\*\*\
> \
> Endpoint utilizado para criar um novo stakeholder ou buscar um existente.\
> O sistema busca por CPF/CNPJ ou Razão Social. Se encontrar, retorna o existente.\
> Se não encontrar, cria um novo.\
> \
> \*\*Campos obrigatórios:\*\*\
> \- \`tipos\`: Array com pelo menos um tipo (cliente, fornecedor, transportadora, fabricante, funcionario)\
> \- \`razao\_social\`\
> \
> \*\*Importante:\*\*\
> \- Use \`cnpj\` para empresas (14 dígitos) ou \`cpf\` para pessoas físicas (11 dígitos)\
> \- Se informar CEP, o sistema busca automaticamente o município\
> \- Pode informar código IBGE do município ou nome + UF

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"04. 👥 Clientes, Fornecedores e Transportadoras","description":"**Gestão de relacionamentos comerciais**\nCadastro e controle de clientes, fornecedores e transportadoras da sua empresa.\n**Funcionalidades:**\n- Cadastrar e consultar clientes comerciais\n- Cadastrar e consultar fornecedores\n- Cadastrar e consultar transportadoras\n- Gestão de contatos e endereços\n- Vincular múltiplos tipos a uma mesma pessoa/empresa"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/stakeholders":{"post":{"summary":"Cria stakeholder","tags":["04. 👥 Clientes, Fornecedores e Transportadoras"],"description":"**Criar ou buscar cliente, fornecedor ou transportadora**\n\nEndpoint utilizado para criar um novo stakeholder ou buscar um existente.\nO sistema busca por CPF/CNPJ ou Razão Social. Se encontrar, retorna o existente.\nSe não encontrar, cria um novo.\n\n**Campos obrigatórios:**\n- `tipos`: Array com pelo menos um tipo (cliente, fornecedor, transportadora, fabricante, funcionario)\n- `razao_social`\n\n**Importante:**\n- Use `cnpj` para empresas (14 dígitos) ou `cpf` para pessoas físicas (11 dígitos)\n- Se informar CEP, o sistema busca automaticamente o município\n- Pode informar código IBGE do município ou nome + UF","parameters":[],"responses":{"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"razao_social":{"type":"string","description":"Razão social ou nome completo"},"nome_fantasia":{"type":"string","description":"Nome fantasia"},"nome":{"type":"string","description":"Nome (alternativa a razao_social)"},"cnpj":{"type":"string","description":"CNPJ (14 dígitos)"},"cpf":{"type":"string","description":"CPF (11 dígitos)"},"tipos":{"type":"array","items":{"type":"string"},"description":"Array de tipos do stakeholder"},"inscricao_estadual":{"type":"string","description":"Inscrição estadual"},"inscricao_suframa":{"type":"string","description":"Inscrição SUFRAMA"},"indicador_ie":{"type":"string","description":"Indicador de IE (1=Contribuinte, 2=Isento, 9=Não contribuinte)"},"cep":{"type":"string","description":"CEP"},"endereco":{"type":"string","description":"Logradouro"},"numero":{"type":"string","description":"Número"},"complemento":{"type":"string","description":"Complemento"},"bairro":{"type":"string","description":"Bairro"},"municipio":{"type":"string","description":"Código IBGE ou nome do município"},"uf":{"type":"string","description":"Nome ou sigla da UF"},"email":{"type":"string","format":"email","description":"Email"},"ddd":{"type":"string","description":"DDD"},"telefone":{"type":"string","description":"Telefone"}},"required":["tipos"]}}}}}}}}
```

## Exibe stakeholder

> Retorna detalhes de um stakeholder específico

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"04. 👥 Clientes, Fornecedores e Transportadoras","description":"**Gestão de relacionamentos comerciais**\nCadastro e controle de clientes, fornecedores e transportadoras da sua empresa.\n**Funcionalidades:**\n- Cadastrar e consultar clientes comerciais\n- Cadastrar e consultar fornecedores\n- Cadastrar e consultar transportadoras\n- Gestão de contatos e endereços\n- Vincular múltiplos tipos a uma mesma pessoa/empresa"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/stakeholders/{id}":{"get":{"summary":"Exibe stakeholder","tags":["04. 👥 Clientes, Fornecedores e Transportadoras"],"description":"Retorna detalhes de um stakeholder específico","responses":{"200":{"description":"Stakeholder encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"stakeholder":{"type":"object","properties":{"id":{"type":"string","description":"UUID"},"tipos":{"type":"array","items":{"type":"string"}},"cnpj":{"type":"string","nullable":true},"razao_social":{"type":"string"},"nome_fantasia":{"type":"string","nullable":true},"inscricao_estadual":{"type":"string","nullable":true},"indicador_ie":{"type":"string","nullable":true},"inscricao_suframa":{"type":"string","nullable":true},"cep":{"type":"string","nullable":true},"endereco":{"type":"string","nullable":true},"numero":{"type":"string","nullable":true},"complemento":{"type":"string","nullable":true},"bairro":{"type":"string","nullable":true},"municipio":{"type":"string","nullable":true},"uf":{"type":"string","nullable":true},"pendencias_nfe":{"type":"array","items":{"type":"string"}},"transportadora":{"type":"object","nullable":true,"properties":{"documento":{"type":"string"},"razao_social":{"type":"string"},"nome_fantasia":{"type":"string","nullable":true},"inscricao_estadual":{"type":"string","nullable":true},"endereco":{"type":"string","nullable":true},"numero":{"type":"string","nullable":true},"complemento":{"type":"string","nullable":true},"cep":{"type":"string","nullable":true},"bairro":{"type":"string","nullable":true},"municipio":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"ddd":{"type":"string","nullable":true},"telefone":{"type":"string","nullable":true}}},"representante":{"type":"object","nullable":true,"properties":{"nome":{"type":"string"},"email":{"type":"string","nullable":true}}}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```