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

get

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

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de rota

stakeholder_idstringObrigatório

UUID do stakeholder

Respostas

200

Indicadores financeiros retornados com sucesso

application/json

401

Não autorizado

application/json

404

Stakeholder não encontrado

get

/stakeholders/{stakeholder_id}/financeiro_notas_fiscais

GET /api/v2/stakeholders/{stakeholder_id}/financeiro_notas_fiscais HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "financeiro_notas_fiscais": {
    "valor_nota_nfe": 125000.5,
    "total_devolucoes": 2500,
    "valor_pedido_liquido": 122500.5,
    "total_faturado": 120000,
    "total_liquidado": 100000,
    "falta_faturar": 2500.5,
    "falta_liquidar": 20000
  }
}

Lista stakeholders

get

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

Autorizações

AuthorizationstringObrigatório

Parâmetros de consulta

tipostring · enumOpcional

Filtrar por tipo de stakeholder

Example: clienteValores possíveis:

ultima_modificacaostring · datetimeOpcional

Stakeholders modificados a partir desta data/hora

Example: 2023-12-01T00:00:00Z

pageinteger · mín: 1Opcional

Número da página para paginação (padrão: 1)

Example: 1

Respostas

200

Lista de stakeholders retornada com sucesso

401

Não autorizado

application/json

get

/stakeholders

GET /api/v2/stakeholders HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "value": {
    "stakeholders": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "tipos": [
          "cliente"
        ],
        "cnpj": "12345678000190",
        "razao_social": "Empresa ABC LTDA",
        "nome_fantasia": "ABC",
        "inscricao_estadual": "123456789",
        "indicador_ie": 1,
        "cep": "01234567",
        "endereco": "Rua das Flores",
        "numero": "123",
        "bairro": "Centro",
        "municipio": "São Paulo",
        "uf": "São Paulo",
        "contatos": [
          {
            "id": 1,
            "nome": "João",
            "email": "joao@abc.com",
            "cargo": "Compras",
            "ddd": "11",
            "telefone": "999887766",
            "principal": true
          }
        ]
      }
    ],
    "pagination": {
      "total": 1,
      "count": 1,
      "previous_page": null,
      "next_page": null
    }
  }
}

Cria stakeholder

post

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

Autorizações

AuthorizationstringObrigatório

Corpo

razao_socialstringOpcional

Razão social ou nome completo

Example: Empresa ABC LTDA

nome_fantasiastringOpcional

Nome fantasia

Example: ABC

nomestringOpcional

Nome (alternativa a razao_social)

Example: João Silva

cnpjstringOpcional

CNPJ (14 dígitos)

Example: 12345678000190

cpfstringOpcional

CPF (11 dígitos)

Example: 12345678901

tiposstring[]Obrigatório

Array de tipos do stakeholder

Example: ["cliente"]

inscricao_estadualstringOpcional

Inscrição estadual

Example: 123456789

inscricao_suframastringOpcional

Inscrição SUFRAMA

Example: 123456

indicador_iestringOpcional

Indicador de IE (1=Contribuinte, 2=Isento, 9=Não contribuinte)

Example: 1

cepstringOpcional

CEP

Example: 01234567

enderecostringOpcional

Logradouro

Example: Rua das Flores

numerostringOpcional

Número

Example: 123

complementostringOpcional

Complemento

Example: Apto 45

bairrostringOpcional

Bairro

Example: Centro

municipiostringOpcional

Código IBGE ou nome do município

Example: 3550308

ufstringOpcional

Nome ou sigla da UF

Example: São Paulo

emailstring · emailOpcional

Example: contato@empresa.com

dddstringOpcional

DDD

Example: 11

telefonestringOpcional

Telefone

Example: 987654321

Respostas

401

Não autorizado

application/json

post

/stakeholders

POST /api/v2/stakeholders HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 427

{
  "razao_social": "Empresa ABC LTDA",
  "nome_fantasia": "ABC",
  "nome": "João Silva",
  "cnpj": "12345678000190",
  "cpf": "12345678901",
  "tipos": [
    "cliente"
  ],
  "inscricao_estadual": "123456789",
  "inscricao_suframa": "123456",
  "indicador_ie": 1,
  "cep": "01234567",
  "endereco": "Rua das Flores",
  "numero": "123",
  "complemento": "Apto 45",
  "bairro": "Centro",
  "municipio": "3550308",
  "uf": "São Paulo",
  "email": "contato@empresa.com",
  "ddd": "11",
  "telefone": "987654321"
}

401

Não autorizado

{
  "error": "Chave de API inválida"
}

Exibe stakeholder

get

Retorna detalhes de um stakeholder específico

Autorizações

AuthorizationstringObrigatório

Parâmetros de rota

idstringObrigatório

UUID do stakeholder

Respostas

200

Stakeholder encontrado

application/json

401

Não autorizado

application/json

get

/stakeholders/{id}

GET /api/v2/stakeholders/{id} HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "stakeholder": {
    "id": "text",
    "tipos": [
      "text"
    ],
    "cnpj": "text",
    "razao_social": "text",
    "nome_fantasia": "text",
    "inscricao_estadual": "text",
    "indicador_ie": "text",
    "inscricao_suframa": "text",
    "cep": "text",
    "endereco": "text",
    "numero": "text",
    "complemento": "text",
    "bairro": "text",
    "municipio": "text",
    "uf": "text",
    "pendencias_nfe": [
      "text"
    ],
    "transportadora": {
      "documento": "text",
      "razao_social": "text",
      "nome_fantasia": "text",
      "inscricao_estadual": "text",
      "endereco": "text",
      "numero": "text",
      "complemento": "text",
      "cep": "text",
      "bairro": "text",
      "municipio": "text",
      "email": "text",
      "ddd": "text",
      "telefone": "text"
    },
    "representante": {
      "nome": "text",
      "email": "text"
    }
  }
}

Anterior01. 🔐 Autenticação Próximo04. 👨‍💼 Representantes

Atualizado há 26 dias