Documentação

API Parceiro V2

Interface REST para sistemas integrados gerenciarem parceiros, usuários, hierarquia comercial e dados de produção no Painel Comercial.

O que você pode fazer

A API Parceiro V2 expõe os recursos do Painel Comercial como endpoints REST autenticados por JWT. Você pode cadastrar e gerenciar parceiros, montar a estrutura comercial da equipe, criar e administrar usuários com controle hierárquico e submeter dados de produção mensal e diária.

🤝

Parceiros

Cadastro, atualização, perfil e importação em bulk de parceiros com vinculação automática à estrutura comercial.

Disponível

👤

Usuários

CRUD completo de usuários com respeito à hierarquia de acesso por role.

Disponível

📊

Produção

Ingestão de dados mensais e diários de produção por parceiro e produto via JSON ou planilha Excel.

Disponível

🔍

Prospecções

Registro e consulta de leads e prospects vinculados a gestores comerciais.

Disponível

📅

Agenda

Eventos de agenda comercial — criação, listagem e remoção com suporte a Google Meet.

Disponível

Base URL

Produção https://sua-instancia.dominio.com.br/api

Todos os endpoints retornam Content-Type: application/json. Requisições com corpo devem usar Content-Type: application/json, exceto uploads de arquivo que usam multipart/form-data.

Autenticação

A API usa JWT (JSON Web Token). Obtenha o token via login e envie-o em todas as requisições subsequentes.

1. Obter o token

POST /api/auth/login Autenticar e obter JWT ▶

curl

curl -X POST https://sua-instancia.dominio.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login":"seu_login","senha":"sua_senha"}'

Resposta 200

JSON

{
  "ok":    true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "login": "seu_login",
  "nome":  "Seu Nome",
  "role":  "admin"
}

2. Enviar o token

Inclua o token no header Authorization de toda requisição autenticada:

HTTP

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Alternativamente, browsers podem usar o cookie app_token definido automaticamente pelo login.

Validade: o token expira em 24 horas. Requisições com token expirado retornam 401. Repita o login para obter um novo token.

Outros endpoints de auth

GET /api/auth/me Retorna dados do usuário autenticado ▶

JSON

{
  "ok": true,
  "login": "seu_login",
  "nome":  "Seu Nome",
  "role":  "admin",
  "permissoes_dashboards": {}
}

POST /api/auth/logout Invalida o cookie de sessão ▶

Limpa o cookie app_token. O JWT em si permanece válido até expirar — para invalidação imediata, descarte o token no cliente.

200 {"ok": true}

POST /api/auth/change-password Altera a senha do usuário autenticado ▶

JSON

{
  "senha_atual": "SenhaAtual",
  "nova_senha":  "NovaSenha123!"
}

200 {"ok": true} 401 Senha atual incorreta

Níveis de acesso

Role	O que pode fazer
`admin`	Acesso total — leitura e escrita em todos os recursos
`diretor`	Leitura total, sem criação/edição de usuários
`superintendente`	Gerencia usuários e estrutura da sua área
`regional`	Gerencia gestores comerciais da sua regional
`gestor_comercial`	Acesso de leitura aos dados da sua carteira

Respostas & Erros

Todas as respostas seguem um envelope consistente com o campo ok indicando sucesso ou falha.

Formato padrão

JSON

// Operação de escrita
{ "ok": true }

// Criação com ID gerado
{ "ok": true, "id": 42 }

// Listagem
{ "ok": true, "data": [ /* array */ ] }

// Erro
{ "ok": false, "erro": "Descrição do problema" }

Códigos HTTP

Código	Significado	Quando ocorre
200	OK	Operação bem-sucedida
201	Created	Recurso criado com sucesso
400	Bad Request	Campos obrigatórios ausentes ou inválidos
401	Unauthorized	Token ausente, inválido ou expirado
403	Forbidden	Role sem permissão para esta operação
404	Not Found	Recurso não encontrado
409	Conflict	Login ou registro já existe
500	Server Error	Erro inesperado no servidor

Headers recomendados

HTTP

Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

Parceiros

Cadastro e gestão de parceiros com vinculação à estrutura comercial. Base: /api/parceiros

Recurso/api/parceiros

GET /api/parceiros Lista parceiros ▶

Retorna os parceiros visíveis ao actor autenticado, filtrados pela hierarquia. Suporta filtros opcionais via query string.

Query params opcionais

Parâmetro	Tipo	Descrição
superintendente	string	Filtra por nome do superintendente
regional	string	Filtra por nome do regional
comercial	string	Filtra por nome do gestor comercial
situacao	string	`ativo` ou `inativo`

Resposta 200

JSON

[
  {
    "cod":              1001,
    "nome":             "Parceiro Exemplo",
    "cpf_cnpj":        "00.000.000/0001-00",
    "situacao":        "ativo",
    "superintendente":  "Carlos Motta",
    "regional":        "Ana Lima",
    "comercial":       "João Silva",
    "estrutura_id":    12,
    "uf":              "SP",
    "municipio":       "São Paulo",
    "data_inicio":     "2024-01-15"
  }
]

GET /api/parceiros/:cod Busca parceiro específico ▶

Retorna um parceiro pelo código numérico. Inclui dados completos de perfil.

404 Parceiro não encontrado 403 Fora do escopo hierárquico

GET /api/parceiros/:cod/contexto Dados completos do parceiro (perfil + produção + agenda) ▶

Retorna o contexto completo de um parceiro: dados cadastrais, histórico de produção resumido e próximos eventos de agenda.

Resposta 200

JSON

{
  "parceiro": { /* dados cadastrais */ },
  "producao": [ /* últimos meses */ ],
  "agenda":   [ /* próximos eventos */ ]
}

PUT /api/parceiros/:cod Atualiza parceiro ▶

Aceita qualquer subconjunto de campos. Apenas os campos enviados são atualizados.

Campos atualizáveis

Campo	Tipo
nome	string
cpf_cnpj	string
situacao	`ativo` \| `inativo`
superintendente	string (nome exato)
regional	string (nome exato)
comercial	string (nome exato)
uf	string (sigla)
municipio	string
data_inicio	string (YYYY-MM-DD)
data_fim	string (YYYY-MM-DD)

200 {"ok": true}

PATCH /api/parceiros/:cod/perfil Atualiza campos de perfil do parceiro ▶

Atualiza campos de perfil (dados de contato, notas) sem alterar vínculos hierárquicos. Aceita qualquer combinação de campos.

JSON

{
  "telefone": "11999990000",
  "email":    "contato@parceiro.com",
  "notas":   "observação livre"
}

200 {"ok": true}

DELETE /api/parceiros/:cod Remove parceiro ▶

Prefira desativar. Use PUT {"situacao": "inativo"} na maioria dos casos para preservar o histórico. A exclusão é permanente e remove toda produção vinculada.

200 {"ok": true} 404 Não encontrado

POST /api/parceiros/importar Importa parceiros via planilha Excel (bulk) ▶

Importa ou atualiza parceiros em massa. O campo cod é a chave de upsert — se o código já existir, os campos são atualizados; se não, um novo parceiro é criado.

Requisição — multipart/form-data

Campo	Tipo	Req?	Descrição
arquivo	file .xlsx	✓	Planilha com os dados dos parceiros

Colunas aceitas

Coluna	Req?
COD / CÓDIGO	✓
NOME	✓
CPF / CNPJ	opcional
SITUAÇÃO / SITUACAO / STATUS	opcional
SUPERINTENDENTE / SUPER	opcional
REGIONAL / GESTOR REGIONAL	opcional
COMERCIAL / GESTOR COMERCIAL	opcional
UF	opcional
MUNICÍPIO / MUNICIPIO	opcional
DATA INICIO / DT INICIO	opcional

Resposta 200

JSON

{
  "ok":         true,
  "importados": 150,
  "atualizados": 12,
  "erros":       0
}

POST /api/parceiros/json Importa parceiros via JSON (bulk) ▶

Equivalente ao endpoint de importação via planilha, mas aceita um array JSON. Útil para integrações programáticas sem geração de arquivo.

JSON

[
  {
    "cod":             1001,
    "nome":            "Parceiro Exemplo",
    "cpf_cnpj":       "00.000.000/0001-00",
    "situacao":       "ativo",
    "superintendente": "Carlos Motta",
    "regional":       "Ana Lima",
    "comercial":      "João Silva",
    "uf":             "SP",
    "municipio":      "São Paulo"
  }
]

Resposta 200

JSON

{ "ok": true, "importados": 150, "atualizados": 12 }

GET /api/parceiros/resumo Resumo estatístico da carteira ▶

Retorna contagens e sumários da carteira do actor autenticado: total de parceiros, por situação, por UF.

JSON

{
  "total":        320,
  "ativos":       280,
  "inativos":     40,
  "por_uf": { "SP": 120, "RJ": 60 }
}

GET /api/parceiros/autocomplete Busca parceiros por texto (autocompletar) ▶

Query params

Parâmetro	Req?	Descrição
q	✓	Texto para busca (nome ou código)

JSON

[{ "cod": 1001, "nome": "Parceiro Exemplo" }]

Usuários

Criação e gestão de usuários com controle de hierarquia. Base: /api/usuarios

Recurso/api/usuarios

GET /api/usuarios Lista usuários ▶

Retorna todos os usuários visíveis ao actor autenticado, filtrado por hierarquia. Admin e diretor recebem a lista completa.

Resposta 200

JSON

[
  {
    "login":                "joao.silva",
    "nome":                 "João Silva",
    "role":                 "gestor_comercial",
    "superintendente":      "Carlos Motta",
    "regional":             "Ana Lima",
    "comercial":            "João Silva",
    "email":               "joao@empresa.com",
    "celular":             "11999990000",
    "situacao":            "ativo",
    "acesso_gestao_acessos": false,
    "must_change_password":  false
  }
]

GET /api/usuarios/:login Busca usuário específico ▶

Retorna um usuário pelo login. Respeita a hierarquia — você só pode buscar usuários no seu escopo.

404 Não encontrado 403 Fora do escopo hierárquico

POST /api/usuarios Cria usuário ▶

Cria o usuário e, se o role for hierárquico, atualiza a estrutura comercial automaticamente.

Os campos superintendente, regional e comercial devem conter os nomes exatos dos usuários da mesma hierarquia — eles são a chave de vínculo.

Body — application/json

JSON

{
  "login":  "joao.silva",
  "senha":  "SenhaForte123!",
  "nome":   "João Silva",
  "role":   "gestor_comercial",
  "superintendente": "Carlos Motta",
  "regional":        "Ana Lima",
  "comercial":       "João Silva",
  "email":   "joao@empresa.com",
  "celular": "(11) 99999-0000",
  "situacao": "ativo"
}

Roles válidas

admin · diretor · superintendente · regional · gestor_comercial

Hierarquia obrigatória por role

Role	Campos obrigatórios
`admin` / `diretor`	Nenhum
`superintendente`	Nenhum (é o topo)
`regional`	`superintendente`
`gestor_comercial`	`superintendente` + `regional`

200 {"ok": true} 400 Hierarquia inválida 409 Login já existe

PUT /api/usuarios/:login Atualiza usuário ▶

Aceita qualquer subconjunto de campos. Apenas os campos enviados são atualizados. Alterar hierarquia re-sincroniza o estrutura_id automaticamente.

Para desativar sem excluir (recomendado): {"situacao": "inativo"}

200 {"ok": true, "item": {...}}

DELETE /api/usuarios/:login Remove usuário ▶

Prefira desativar. A exclusão é permanente. O login admin não pode ser excluído.

200 {"ok": true} 403 Admin protegido 404 Não encontrado

POST /api/usuarios/json Importa usuários em bulk via JSON ▶

Aceita um array de objetos com a mesma estrutura do POST /api/usuarios. Processa cada item com upsert por login.

200 {"ok": true, "importados": N, "erros": []}

Estrutura Comercial

Hierarquia superintendente → regional → comercial. Base: /api/estrutura-comercial

Na maioria dos casos você não precisa deste recurso diretamente. Ao criar/editar usuários com roles hierárquicas, a estrutura é atualizada automaticamente. Use este recurso quando precisar gerenciar a hierarquia independentemente de usuários.

Recurso/api/estrutura-comercial

GET /api/estrutura-comercial Lista estrutura visível ▶

Admin e diretor recebem toda a estrutura ativa. Outros roles recebem apenas os nós abaixo deles.

JSON

{
  "ok": true,
  "estrutura": [
    {
      "id":              12,
      "superintendente": "Carlos Motta",
      "regional":        "Ana Lima",
      "comercial":       "João Silva",
      "situacao":        "ativo",
      "data_inicio":     "2024-03-01",
      "data_fim":        null
    }
  ]
}

POST /api/estrutura-comercial Cria nó na hierarquia ▶

Cria ou atualiza (upsert) um nó. Se a combinação superintendente/regional/comercial já existir, atualiza os campos enviados.

JSON

{
  "superintendente": "Carlos Motta",
  "regional":        "Ana Lima",
  "comercial":       "João Silva",
  "situacao":        "ativo",
  "data_inicio":     "2024-03-01"
}

201 {"ok": true, "id": 42} 400 superintendente ausente

PUT /api/estrutura-comercial/:id Atualiza nó da hierarquia ▶

Alterar os campos de nome pode quebrar vínculos com usuários e parceiros. Prefira desativar o nó (situacao=inativo) e criar um novo.

200 {"ok": true}

DELETE /api/estrutura-comercial/:id Remove nó da hierarquia ▶

Prefira PUT {"situacao": "inativo"}. A exclusão desvincula automaticamente todos os usuários e parceiros associados a este nó.

200 {"ok": true} 404 Não encontrado

POST /api/estrutura-comercial/upload Importa estrutura via planilha Excel (bulk) ▶

Substitui toda a estrutura pela planilha enviada. Re-vincula usuários e parceiros automaticamente após o import.

multipart/form-data

Campo	Tipo	Req?	Colunas aceitas
arquivo	file .xlsx	✓	SUPERINTENDENTE, REGIONAL, COMERCIAL, DATA INICIO, DATA FIM, SITUAÇÃO

200 {"ok": true, "linhas": 48, "estrutura": [...]}

POST /api/estrutura-comercial/json Importa estrutura via JSON (bulk) ▶

Equivalente ao upload, mas aceita um array JSON. Cada item deve ter ao menos superintendente.

200 {"ok": true, "importados": N}

Produção

Ingestão e consulta de dados de produção mensal e diária por parceiro. Base: /api/producao

Recurso/api/producao

GET /api/producao/latest Produção mensal mais recente ▶

Retorna a produção mensal do período mais recente carregado, filtrada pelo escopo hierárquico do actor.

Query params opcionais

Parâmetro	Descrição
superintendente	Filtra por nome
regional	Filtra por nome
comercial	Filtra por nome
cod_parceiro	Código numérico do parceiro

JSON

[
  {
    "cod_parceiro":    1001,
    "nome_parceiro":   "Parceiro Exemplo",
    "mes_ref":         "2024-08",
    "valor_bruto":     15000.00,
    "quantidade":      42,
    "produto":         "PRODUTO_A"
  }
]

GET /api/producao/diaria Produção diária ▶

Retorna dados de produção diária com filtros de período.

Query params

Parâmetro	Tipo	Descrição
data_inicio	string	YYYY-MM-DD (padrão: primeiro dia do mês)
data_fim	string	YYYY-MM-DD (padrão: hoje)
cod_parceiro	integer	Filtra por parceiro

GET /api/producao-parceiro Produção mensal por parceiro (visão agrupada) ▶

Retorna dados de produção agrupados por parceiro e mês, com colunas dinâmicas por produto.

POST /api/producao Envia produção mensal via JSON ▶

Insere ou substitui (upsert por cod_parceiro + mes_ref + produto) dados de produção mensal.

JSON

[
  {
    "cod_parceiro": 1001,
    "mes_ref":      "2024-08",
    "produto":     "PRODUTO_A",
    "valor_bruto": 15000.00,
    "quantidade":  42
  }
]

200 {"ok": true, "inseridos": N, "atualizados": M}

POST /api/producao-parceiro/json Envia produção mensal por parceiro (formato bulk) ▶

Formato alternativo para envio em bulk de produção mensal agrupada por parceiro e mês, com múltiplos produtos em um único objeto.

JSON

[
  {
    "cod_parceiro": 1001,
    "mes_ref":      "2024-08",
    "produtos": {
      "PRODUTO_A": { "valor_bruto": 15000.00, "quantidade": 42 },
      "PRODUTO_B": { "valor_bruto": 8000.00,  "quantidade": 20 }
    }
  }
]

200 {"ok": true, "processados": N}

POST /api/producao/upload-excel Envia produção mensal via planilha Excel ▶

Processa uma planilha Excel e insere/atualiza produção mensal. O template da planilha pode ser obtido com o responsável técnico da plataforma.

multipart/form-data

Campo	Tipo	Req?
arquivo	file .xlsx	✓

200 {"ok": true, "processados": N, "erros": []}

POST /api/producao/diaria/upload Envia produção diária via planilha Excel ▶

Insere produção diária a partir de uma planilha. Processa upsert por cod_parceiro + data + produto.

multipart/form-data

Campo	Tipo	Req?
arquivo	file .xlsx	✓

200 {"ok": true, "processados": N}

Prospecções

Registro e consulta de leads e prospects vinculados a gestores comerciais. Base: /api/prospeccoes

Recurso/api/prospeccoes

GET /api/prospeccoes Lista prospecções ▶

Retorna as prospecções visíveis ao actor autenticado, filtradas por hierarquia.

JSON

[
  {
    "id":           "uuid-string",
    "nome":         "Empresa Prospect",
    "cpf_cnpj":    "00.000.000/0001-00",
    "status":       "em_andamento",
    "responsavel":  "joao.silva",
    "data_criacao": "2024-08-01T10:00:00",
    "notas":        "Contato inicial feito"
  }
]

POST /api/prospeccoes Registra nova prospecção ▶

Body — application/json

JSON

{
  "nome":        "Empresa Prospect",
  "cpf_cnpj":   "00.000.000/0001-00",
  "status":      "em_andamento",
  "responsavel": "joao.silva",
  "notas":       "Contato inicial feito"
}

Status válidos

em_andamento · convertido · perdido · sem_interesse

200 {"ok": true, "id": "uuid"} 400 nome ausente

DELETE /api/prospeccoes/:id Remove prospecção ▶

O id é uma string (UUID ou identificador textual). Requer que o actor seja o responsável pela prospecção ou tenha role admin/diretor.

200 {"ok": true} 404 Não encontrada 403 Sem permissão

Agenda

Eventos de agenda comercial — criação, listagem e remoção. Base: /api/agenda

Recurso/api/agenda

GET /api/agenda Lista eventos da agenda ▶

Retorna eventos do actor autenticado e dos usuários abaixo na hierarquia.

Query params opcionais

Parâmetro	Tipo	Descrição
data_inicio	string	YYYY-MM-DD
data_fim	string	YYYY-MM-DD
responsavel	string	Login do responsável
cod_parceiro	integer	Filtra por parceiro vinculado

JSON

[
  {
    "id":           1,
    "titulo":       "Visita ao parceiro",
    "tipo":         "visita",
    "data_hora":    "2024-09-15T10:00:00",
    "responsavel":  "joao.silva",
    "cod_parceiro": 1001,
    "notas":        "Reunião mensal",
    "meet_link":    null
  }
]

POST /api/agenda Cria evento na agenda ▶

Body — application/json

JSON

{
  "titulo":       "Visita ao parceiro",
  "tipo":         "visita",
  "data_hora":    "2024-09-15T10:00:00",
  "cod_parceiro": 1001,
  "notas":        "Reunião mensal",
  "criar_meet":   false
}

Tipos de evento

visita · ligacao · reuniao · outro

Google Meet: se criar_meet: true, cria automaticamente um link de reunião no Google Calendar do actor (requer integração Google configurada na conta).

200 {"ok": true, "id": N} 400 titulo ou data_hora ausente

DELETE /api/agenda/:id Remove evento específico ▶

200 {"ok": true} 404 Não encontrado 403 Sem permissão

DELETE /api/agenda Remove múltiplos eventos ▶

Remove múltiplos eventos em uma única requisição.

JSON

{ "ids": [1, 2, 3] }

200 {"ok": true, "removidos": 3}

GET /api/agenda/perfis Lista perfis de agenda disponíveis ▶

Retorna os tipos de evento e configurações de agenda disponíveis para o actor autenticado.

Fluxograma: Onboarding de Parceiro

Sequência recomendada para cadastrar um novo parceiro e vinculá-lo à estrutura comercial.

Passo a passo

Autentique-se — POST /api/auth/login para obter o JWT.
Consulte a estrutura — GET /api/estrutura-comercial para obter os nomes exatos de superintendente, regional e comercial.
Cadastre o(s) parceiro(s) — use POST /api/parceiros/json (array JSON) ou POST /api/parceiros/importar (planilha .xlsx) para inserção em massa.
Verifique o vínculo — nos dados retornados, confirme que estrutura_id não é null. Se for, revise os campos superintendente, regional e comercial — devem corresponder exatamente aos valores da estrutura.

Correspondência de nomes: os campos superintendente, regional e comercial são comparados sem distinção de maiúsculas/minúsculas, mas devem corresponder exatamente ao nome cadastrado na estrutura. Espaços extras ou variações de grafia causarão falha no vínculo.

Fluxograma: Envio de Produção

Sequência recomendada para enviar dados de produção mensal de parceiros.

Passo a passo

Autentique-se — POST /api/auth/login para obter o JWT.
Escolha o formato:
- JSON simples — array de registros com cod_parceiro, mes_ref, produto, valor_bruto, quantidade. Use POST /api/producao.
- JSON agrupado — cada objeto agrupa múltiplos produtos de um parceiro/mês. Use POST /api/producao-parceiro/json.
- Planilha Excel — envie via POST /api/producao/upload-excel com multipart/form-data.
Verifique a resposta — confirme "ok": true e o campo processados bate com o número de registros enviados.

Upsert: o envio é idempotente. Registros com a mesma chave (cod_parceiro + mes_ref + produto) são atualizados, não duplicados. É seguro re-enviar um período já processado.