> For the complete documentation index, see [llms.txt](https://changelog.maino.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://changelog.maino.com.br/api-reference-maino/03.-clientes-fornecedores-e-transportadoras.md). # 03. 👥 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":"03. 👥 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":["03. 👥 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":"03. 👥 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":["03. 👥 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":"03. 👥 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":["03. 👥 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":"03. 👥 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":["03. 👥 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"}}}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://changelog.maino.com.br/api-reference-maino/03.-clientes-fornecedores-e-transportadoras.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.