Documentação

API Parceiro V1

Interface REST para sistemas integrados gerenciarem a operação comercial — usuários, hierarquia, parceiros, produção, agenda e prospecções — diretamente no Painel Comercial.

Produto

A API Parceiro V1 expõe todos os recursos do Painel Comercial como endpoints REST com autenticação JWT e controle hierárquico de acesso. Há um único produto integrado:

🏢

Gestão Comercial

Usuários, estrutura hierárquica, parceiros, produção mensal, agenda de visitas e prospecções — CRUD completo e importação bulk via JSON ou planilha.

Disponível

Como usar a API

Siga a sequência abaixo para integrar corretamente:

1. Obtenha o token de acesso

Toda requisição à API requer autenticação JWT. Antes de qualquer chamada, faça login em POST /auth/login para obter o token. Envie-o em todas as requisições subsequentes via cabeçalho Authorization: Bearer <token> ou cookie app_token.

Ver Autenticação →

2. Entenda a hierarquia comercial

A API aplica controle de escopo automático em todos os endpoints: cada usuário só enxerga e modifica dados dentro da sua hierarquia. Os níveis são:

Role	Escopo
`admin`	Acesso total — todos os dados
`superintendente`	Dados da sua superintendência
`regional`	Dados da sua regional
`gestor_comercial`	Apenas os próprios dados

Ver Estrutura Comercial →

3. Fluxo sugerido para ingestão de dados

Para carga inicial ou sincronização de sistemas externos, recomenda-se a seguinte ordem para garantir integridade referencial:

Usuários — POST /gc/usuarios/json — cria gestores e define a hierarquia
Estrutura Comercial — POST /gc/estrutura/json — cria regionais e superintendências
Parceiros — POST /parceiros/json — vincula parceiros às estruturas
Produção — POST /producao/json — insere histórico de produção mensal

Use o parâmetro ?replace=true nos endpoints bulk para substituição completa da base. Sem ele, os registros são atualizados via upsert (inserção ou atualização pelo identificador único).

Base URL

Produção https://seu-dominio.com/api

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

Autenticação

A API usa JWT (JSON Web Token). Você obtém o token via login e o envia em todas as requisições subsequentes.

1. Obter o token

Faça um POST para /auth/login com suas credenciais. O token é retornado no corpo da resposta e definido como cookie HttpOnly (app_token).

curl

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

Resposta 200

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

2. Enviar o token

Via header Authorization (recomendado para APIs)

curl

curl https://seu-dominio.com/api/usuarios \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Via cookie (para browsers)

Se você usou -c cookies.txt no curl de login, o cookie app_token é enviado automaticamente. Em browsers, o cookie HttpOnly é gerenciado automaticamente após o login.

Validade do token

O token expira em 24 horas por padrão (configurável via JWT_HOURS). Após expiração, repita o login. Requisições com token expirado retornam 401.

Segurança: nunca exponha o token em logs, URLs ou código-fonte. Use variáveis de ambiente para armazená-lo em integrações automatizadas.

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 formato consistente com o campo ok indicando sucesso ou falha.

Formato de sucesso

JSON

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

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

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

Formato de erro

JSON

{ "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
429	Too Many Requests	Rate limit atingido — aguarde e tente novamente
500	Server Error	Erro inesperado no servidor

Paginação

Endpoints com grandes volumes de dados usam paginação por offset. Passe page (padrão: 1) e per_page (padrão: 50). A resposta inclui sempre total, page, per_page e pages (ou total_pages). Endpoints com volumes menores (usuários, estrutura) retornam todos os registros visíveis ao actor autenticado sem paginação.

Ambientes

A API opera em dois ambientes. Use o de desenvolvimento para testar integrações antes de ir para produção.

Ambiente	Base URL	Descrição
Produção	`https://seu-dominio.com/api`	Dados reais. Requer credenciais de produção.
Desenvolvimento	`http://localhost:8080/api`	Banco local. Credenciais padrão: login `admin`, senha definida em `ADMIN_PASSWORD`.

Variáveis de ambiente chave: DATABASE_URL aponta para o banco, JWT_SECRET assina os tokens, ADMIN_PASSWORD define a senha do admin na inicialização. Veja o .env.example do repositório para a lista completa.

Headers recomendados

HTTP

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

Rate Limits

O servidor limita requisições por usuário autenticado — não por IP — para proteger o banco de ingestões abusivas.

Perfis de limite

Perfil	Limite	Chave	Quais endpoints
Padrão	300 / min · 10 / s	IP de origem	Todos os endpoints não listados abaixo
Bulk	6 / min	Login autenticado	`POST /json` (estrutura, usuários, parceiros, produção)
Heavy	2 / min	Login autenticado	`POST /json?replace=true` · `DELETE /parceiros/:cod`

A chave de rate limit dos endpoints bulk é o login do usuário autenticado, não o IP. Times num escritório compartilhando um único IP não sofrem interferência mútua.

Resposta 429

HTTP

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "ok": false, "erro": "Rate limit excedido. Tente novamente em instantes." }

Mapa por endpoint

Endpoint	Perfil	Limite
`POST /api/estrutura-comercial/json`	Bulk	6 / min
`POST /api/usuarios/json`	Bulk	6 / min
`POST /api/parceiros/json`	Bulk	6 / min
`POST /api/parceiros/json?replace=true`	Heavy	2 / min
`PUT /api/parceiros/:cod`	Bulk	6 / min
`DELETE /api/parceiros/:cod`	Heavy	2 / min
`POST /api/producao-parceiro/json`	Bulk	6 / min
`POST /api/producao-parceiro/json?replace=true`	Heavy	2 / min

Dica para ingestões grandes: divida payloads em lotes menores (ex: 5 000 parceiros por requisição) e aguarde cerca de 10 segundos entre cada lote.

Produto

Gestão Comercial

Gerencie a estrutura da sua equipe comercial: criação de usuários com controle hierárquico e montagem da árvore superintendente → regional → gestor comercial.

Recursos disponíveis

👤

Usuários

CRUD completo e importação bulk via JSON — criar, listar, buscar, atualizar e desativar com respeito à hierarquia de acesso.

🏛️

Estrutura Comercial

Gestão dos nós da hierarquia (superintendente / regional / comercial) — criação individual, upload Excel ou importação bulk via JSON.

Sobre a hierarquia

O modelo de acesso segue uma pirâmide: cada role só enxerga e gerencia o que está abaixo dela. Ao criar um usuário com role superintendente, regional ou gestor_comercial, a linha correspondente na Estrutura Comercial é criada ou atualizada automaticamente.

Role	Campos hierárquicos obrigatórios
`admin`	Nenhum — acesso total
`superintendente`	Nenhum (é o topo da hierarquia)
`regional`	`superintendente`
`gestor_comercial`	`superintendente` + `regional`

Usuários Gestão Comercial

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 único usuário pelo login. Respeita a hierarquia — você só pode buscar usuários no seu escopo.

Parâmetros de path

Parâmetro	Tipo	Descrição
login	string	Login único do usuário (ex: `joao.silva`)

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",
  "situacao":            "ativo",
  "estrutura_id":        12
}

Erros possíveis

404 Usuário não encontrado 403 Fora do seu 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. O campo must_change_password é sempre true na criação.

Os campos superintendente, regional e comercial devem conter os nomes exatos que estão nos outros usuários da mesma hierarquia — eles são usados como chave de vínculo.

Body — application/json

JSON

{
  "login":  "joao.silva",          // obrigatório, único
  "senha":  "SenhaForte123!",     // obrigatório
  "nome":   "João Silva",          // obrigatório
  "role":   "gestor_comercial",    // obrigatório

  // Hierarquia — obrigatório conforme role
  "superintendente": "Carlos Motta",
  "regional":        "Ana Lima",
  "comercial":       "João Silva",

  // Opcionais
  "email":                  "joao@empresa.com",
  "celular":                "(11) 99999-0000",
  "situacao":               "ativo",
  "acesso_gestao_acessos":  false,
  "permissoes_dashboards":  {}
}

Roles válidas

admin · diretor · superintendente · regional · gestor_comercial

Resposta 200

JSON

{ "ok": true }

400 Campos obrigatórios ausentes ou 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. Se alterar hierarquia, re-sincroniza estrutura_id automaticamente.

Campos atualizáveis

Campo	Tipo	Observação
nome	string
role	string	Ver roles válidas acima
superintendente	string	Nome exato
regional	string	Nome exato
comercial	string	Nome exato
email	string
celular	string	Formatação livre
situacao	string	`ativo` ou `inativo`
senha	string	Se enviado, força `must_change_password=true`
acesso_gestao_acessos	boolean
permissoes_dashboards	object	Chaves livres

Dica: para desativar um usuário sem excluí-lo (recomendado), envie apenas {"situacao": "inativo"}.

Resposta 200

JSON

{ "ok": true, "item": { /* campos atualizados */ } }

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

Prefira desativar. A exclusão remove o histórico de acesso permanentemente. Use PUT {"situacao": "inativo"} na maioria dos casos. 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 ▶

Upsert de até 500 usuários por requisição. Usuários existentes são atualizados; novos são criados. Senha é gerada automaticamente quando omitida. Requer role admin. Limite: 6 requisições / minuto por usuário autenticado.

Body — array de até 500 itens

JSON

[
  {
    "login":           "joao.silva",       // obrigatório
    "nome":            "João Silva",        // obrigatório
    "role":            "gestor_comercial",  // obrigatório
    "senha":           "SenhaForte123!",    // opcional — gerada se omitida
    "superintendente": "Carlos Motta",
    "regional":        "Ana Lima",
    "comercial":       "João Silva",
    "email":           "joao@empresa.com",
    "situacao":        "ativo"
  }
]

Comportamento da senha

Se senha não for enviada: senha temporária gerada e retornada em criados_detalhes.
Se senha for enviada num upsert (usuário existente): a senha armazenada é substituída.
Se senha for omitida num upsert: a senha atual não é alterada.

Resposta 200

JSON

{
  "ok":              true,
  "total":           100,
  "criados":         80,
  "atualizados":     20,
  "erros":           [],
  "criados_detalhes": [
    { "login": "joao.silva", "senha_gerada": "xK7mN2pQ4r" }
  ]
}

Guarde as senhas geradas! Elas aparecem apenas nesta resposta e não podem ser recuperadas depois. Distribua-as aos usuários imediatamente.

Estrutura Comercial Gestão 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 a estrutura visível ▶

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

Resposta 200

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,
      "origem":          "cadastro_usuario"
    }
  ]
}

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

Cria um nó na hierarquia comercial. Se o nó (mesma combinação superintendente/regional/comercial, case-insensitive) já existir, atualiza os campos enviados — seguro chamar de forma idempotente.

Body — application/json

JSON

{
  "superintendente": "Carlos Motta",  // obrigatório
  "regional":        "Ana Lima",     // opcional
  "comercial":       "João Silva",   // opcional
  "situacao":        "ativo",         // "ativo" | "inativo"
  "data_inicio":     "2024-03-01",   // opcional
  "data_fim":        null             // opcional
}

Resposta 201

JSON

{ "ok": true, "id": 42 }

400 superintendente ausente 403 Sem permissão (role != admin)

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

Atualiza campos de um nó específico. Apenas os campos enviados são modificados.

Alterar os campos de nome (superintendente, regional, comercial) pode quebrar o vínculo com usuários e parceiros já associados a este nó. Prefira desativar o nó antigo (situacao=inativo) e criar um novo.

Campos atualizáveis

Campo	Tipo	Observação
situacao	string	`ativo` ou `inativo` — uso mais comum
data_inicio	string	Data de admissão
data_fim	string	Data de desligamento
superintendente	string	⚠ Pode quebrar vínculos
regional	string	⚠ Pode quebrar vínculos
comercial	string	⚠ Pode quebrar vínculos

Resposta 200

JSON

{ "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 que referenciam este nó (FK ON DELETE SET NULL). Use apenas para nós criados por engano.

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

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

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

Requisição — multipart/form-data

Campo	Tipo	Req?	Descrição
arquivo	file .xlsx	✓	Planilha com colunas SUPERINTENDENTE, REGIONAL, COMERCIAL

Colunas aceitas na planilha

Coluna	Aliases aceitos	Req?
SUPERINTENDENTE	SUPER	✓
REGIONAL	GESTOR REGIONAL	✓
COMERCIAL	GESTOR COMERCIAL · CONSULTOR	✓
DATA INICIO	DT INICIO · DATA ADMISSAO	opcional
DATA FIM	DT FIM · DATA DESLIGAMENTO	opcional
SITUAÇÃO	SITUACAO DO COLABORADOR NA EMPRESA · STATUS	opcional

Resposta 200

JSON

{
  "ok":       true,
  "linhas":    48,
  "estrutura": [ /* lista completa atualizada */ ]
}

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

Upsert de até 2 000 nós por requisição. Nós existentes (mesma combinação sup/reg/com) são atualizados. Requer role admin. Limite: 6 requisições / minuto por usuário autenticado.

Body — array de até 2 000 itens

JSON

[
  {
    "superintendente": "Carlos Motta",  // obrigatório
    "regional":        "Ana Lima",      // opcional
    "comercial":       "João Silva",    // opcional
    "situacao":        "ativo",
    "data_inicio":     "2024-03-01"
  }
]

Resposta 200

JSON

{
  "ok":          true,
  "total":       200,
  "inseridos":   150,
  "atualizados": 50,
  "erros":       []
}

Parceiros

Cadastro, consulta e atualização de parceiros com vinculação automática à estrutura comercial. Base: /api/parceiros

Hierarquia de ingestão recomendada: importe a Estrutura Comercial antes dos parceiros para que os vínculos sejam resolvidos automaticamente pelos campos superintendente, regional e comercial.

Recurso /api/parceiros

GET /api/parceiros Lista parceiros (paginado) ▶

Retorna parceiros visíveis ao actor autenticado, filtrados em SQL pelo escopo hierárquico. O campo dados_json é omitido da listagem por performance — use o endpoint individual para obtê-lo.

Query params

Parâmetro	Tipo	Default	Descrição
q	string	—	Busca por nome ou código do parceiro
superintendente	string	—	Filtra pelo nome do superintendente
regional	string	—	Filtra pelo nome do regional
comercial	string	—	Filtra pelo nome do gestor comercial
status	string	—	Ex: `Ativo`, `Inativo`
cidade	string	—	Filtra pela cidade
pendente	boolean	—	`true` = parceiros sem vínculo de estrutura
page	int	1	Página atual
per_page	int	50	Itens por página (máx 200)

Resposta 200

JSON

{
  "ok":       true,
  "total":    1230,
  "page":     1,
  "per_page": 50,
  "pages":    25,
  "parceiros": [
    {
      "cod":             1234,
      "nome":            "Fulano de Tal",
      "status":          "Ativo",
      "cidade":          "São Paulo",
      "uf":              "SP",
      "superintendente": "Carlos Motta",
      "regional":        "Ana Lima",
      "comercial":       "João Silva",
      "estrutura_id":    12
    }
  ]
}

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

Retorna o registro completo incluindo dados_json. Respeita o escopo hierárquico do actor autenticado.

Parâmetros de path

Parâmetro	Tipo	Descrição
cod	int	Código numérico do parceiro

Resposta 200

JSON

{
  "ok": true,
  "parceiro": {
    "cod":             1234,
    "nome":            "Fulano de Tal",
    "status":          "Ativo",
    "cidade":          "São Paulo",
    "uf":              "SP",
    "superintendente": "Carlos Motta",
    "regional":        "Ana Lima",
    "comercial":       "João Silva",
    "estrutura_id":    12,
    "dados_json": {
      "cpf_cnpj": "123.456.789-00",
      "email":    "fulano@email.com"
    }
  }
}

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

POST /api/parceiros/json Importa parceiros em bulk via JSON ▶

Upsert de até 5 000 parceiros por requisição. Campos extras (fora do schema base) são armazenados automaticamente em dados_json. Requer role admin. Limite: 6 req/min (sem replace) ou 2 req/min (com replace=true) por usuário autenticado.

Query params

Parâmetro	Tipo	Default	Descrição
replace	boolean	false	Se `true`, parceiros do escopo do actor ausentes do payload são marcados como `Inativo`

Body — array de até 5 000 itens

JSON

[
  {
    "cod":             1234,             // obrigatório, int
    "nome":            "Fulano de Tal",  // obrigatório
    "status":          "Ativo",          // opcional
    "cidade":          "São Paulo",      // opcional
    "uf":              "SP",             // opcional
    "superintendente": "Carlos Motta",  // para vínculo automático
    "regional":        "Ana Lima",
    "comercial":       "João Silva",
    "cpf_cnpj":        "123.456.789-00", // → dados_json
    "email":           "fulano@mail.com"  // → dados_json
  }
]

Resposta 200

JSON

{
  "ok":               true,
  "importados":       4988,
  "erros":            [],
  "pendentes_vinculo": 12
}

pendentes_vinculo indica parceiros importados cujo trio sup/regional/comercial não encontrou correspondência na estrutura ativa. Eles ficam salvos mas sem estrutura_id. Importe a estrutura primeiro ou corrija os nomes.

PUT /api/parceiros/:cod Atualiza parceiro ▶

Atualiza campos do parceiro. Apenas os campos enviados são modificados. Para dados_json, os campos enviados são fundidos (merge) com os existentes — não substituídos. Requer role admin. Limite: 6 req/min.

Campos atualizáveis

Campo	Tipo	Observação
nome	string
status	string	Ex: `Ativo`, `Inativo`
cidade	string
uf	string	Sigla do estado
superintendente	string	Re-resolve vínculo após atualização
regional	string	Re-resolve vínculo após atualização
comercial	string	Re-resolve vínculo após atualização
dados_json	object	Fundido (merge) com os dados existentes, não substituído

Resposta 200

JSON

{ "ok": true }

DELETE /api/parceiros/:cod Remove parceiro ▶

Exclusão permanente. Remove o parceiro e todos os registros de produção vinculados (CASCADE). Prefira atualizar o status para "Inativo" na maioria dos casos. Requer role admin. Limite: 2 req/min.

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

Produção Parceiro

Ingestão e consulta de dados mensais de produção por parceiro, produto e operação. Base: /api/producao-parceiro

Pré-requisito: os registros referenciam parceiros pelo cod. O parceiro deve existir e estar Ativo antes da ingestão. Registros com cod inválido são registrados em erros mas não cancelam o lote inteiro.

Recurso /api/producao-parceiro

POST /api/producao-parceiro/json Ingestão de produção em bulk ▶

Upsert de até 50 000 registros por requisição. Itens com o mesmo (cod, ano, mes, produto, operacao) têm seus valores somados antes do upsert — útil para envios fragmentados da mesma competência. Requer role admin. Limite: 6 req/min (sem replace) ou 2 req/min (com replace=true).

Query params

Parâmetro	Tipo	Default	Descrição
replace	boolean	false	Se `true`, exclui todos os registros existentes das competências presentes no payload antes de inserir

Body — array de até 50 000 itens

JSON

[
  {
    "cod":      1234,   // obrigatório — código do parceiro
    "ano":      "2024", // obrigatório — 2 ou 4 dígitos
    "mes":      "03",   // obrigatório — 1 a 12
    "produto":  "CDC",  // opcional — default "Sem produto"
    "operacao": "Novo", // opcional — default "Sem operacao"
    "valor":    15000.00,
    "qtd":      10,
    "prazo":    24
  }
]

Normalização automática

Ano com 2 dígitos: "24" → "2024"
Mês numérico: 3 → "03"
Duplicatas no mesmo lote (mesmo cod/ano/mes/produto/operacao): valores são somados

Resposta 200

JSON

{
  "ok":          true,
  "inseridos":   49250,
  "erros":       [
    { "cod": 9999, "motivo": "parceiro não encontrado ou inativo" }
  ],
  "competencias": [ "24/03", "24/04" ]
}

competencias lista as competências (AA/MM) processadas — útil para confirmar quais períodos foram inseridos.

GET /api/producao-parceiro Lista registros de produção (paginado) ▶

Retorna registros de produção com o nome do parceiro incluído via JOIN. Qualquer usuário autenticado pode consultar, restrito ao seu escopo hierárquico.

Query params

Parâmetro	Tipo	Default	Descrição
cod	int	—	Filtra pelo código do parceiro
ano	string	—	Filtra pelo ano (4 dígitos)
mes	string	—	Filtra pelo mês (2 dígitos)
mes_ref	string	—	Filtro rápido por competência no formato `AA/MM` (ex: `24/03`)
page	int	1	Página atual
per_page	int	50	Itens por página (máx 500)

Resposta 200

JSON

{
  "ok":        true,
  "total":     5000,
  "page":      1,
  "per_page":  50,
  "pages":     100,
  "registros": [
    {
      "parceiro_cod": 1234,
      "nome":         "Fulano de Tal",
      "ano":          "2024",
      "mes":          "03",
      "produto":      "CDC",
      "operacao":     "Novo",
      "valor":        15000.00,
      "qtd":          10,
      "prazo":        24
    }
  ]
}

Ordem de ingestão recomendada

Para uma carga inicial completa, respeite esta sequência para evitar erros de referência:

Estrutura Comercial — POST /api/estrutura-comercial/json
Usuários — POST /api/usuarios/json
Parceiros — POST /api/parceiros/json
Produção — POST /api/producao-parceiro/json

Agenda

Agendamentos de visitas presenciais, remotas e atividades internas com detecção de conflito de horário. Base: /api/agenda

Cada evento é identificado por um id único gerado pelo cliente (UUID recomendado). O endpoint POST /api/agenda é idempotente — enviar o mesmo id novamente atualiza o evento existente.

Recurso /api/agenda

GET /api/agenda Lista eventos da agenda ▶

Retorna eventos visíveis ao actor autenticado filtrados por escopo hierárquico. Por padrão retorna os eventos dos últimos 90 dias e próximos 90 dias.

Query params

Parâmetro	Tipo	Default	Descrição
inicio	string	hoje − 90 dias	Data inicial no formato `YYYY-MM-DD`
fim	string	hoje + 90 dias	Data final no formato `YYYY-MM-DD`
all	string	—	Passe `all=1` para ignorar o filtro de período e retornar todos os eventos

Visibilidade por role

Role	O que enxerga
`admin` · `diretor`	Todos os eventos
`gestor_comercial`	Apenas os próprios eventos
`superintendente` · `regional`	Eventos da sua hierarquia

Resposta 200

JSON

[
  {
    "id":                  "uuid-do-evento",
    "cod_parceiro":        1234,
    "nome_parceiro":       "Fulano de Tal",
    "titulo":              "Visita de relacionamento",
    "inicio_data":         "2024-03-15",
    "inicio_hora":         "09:00",
    "fim_data":            "2024-03-15",
    "fim_hora":            "10:00",
    "motivo_visita":       "Relacionamento",
    "tipo_visita":         "presencial",
    "status_ag":           "agendado",
    "criado_por":          "joao.silva",
    "meet_link":           "",
    "convidados_json":     []
  }
]

POST /api/agenda Cria ou atualiza evento ▶

Upsert por id. Se o evento já existir, todos os campos enviados são atualizados. O sistema verifica conflito de horário: visitas ao mesmo parceiro com menos de 1 hora de intervalo são rejeitadas com 409.

Body — application/json

JSON

{
  "id":           "uuid-do-evento",   // obrigatório
  "cod_parceiro": 1234,               // opcional
  "nome_parceiro":"Fulano de Tal",    // opcional
  "titulo":       "Visita",           // opcional
  "inicio_data":  "2024-03-15",       // opcional — default hoje
  "inicio_hora":  "09:00",            // opcional — default "09:00"
  "fim_data":     "2024-03-15",       // opcional
  "fim_hora":     "10:00",            // opcional — default "10:00"
  "motivo_visita":"Relacionamento",   // opcional — default "Outros"
  "tipo_visita":  "presencial",       // "presencial" | "remoto"
  "status_ag":    "agendado",         // "agendado" | "realizado" | "desmarcado"
  "local":        "Agência Centro",
  "parecer":      "Reunião produtiva",
  "dia_inteiro":  false,
  "gerar_meet":   false,
  "convidados": [
    { "login": "maria.lima", "nome": "Maria Lima" }
  ],
  "plano_visita": [],
  "perfil_estabelecimento": []
}

Resposta 200

JSON

{ "ok": true, "item": { /* evento salvo */ } }

400 id ausente 409 Conflito de horário no mesmo parceiro

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

Remove um evento pelo seu ID. O gestor_comercial só pode remover eventos que criou. Outros roles respeitam o escopo hierárquico.

Parâmetros de path

Parâmetro	Tipo	Descrição
ev_id	string	ID do evento (mesmo `id` enviado no POST)

200 {"ok": true} 404 Não encontrado 403 Fora do escopo

DELETE /api/agenda Limpa toda a agenda ▶

Operação destrutiva. Remove todos os eventos da agenda de forma irreversível. Exclusivo para role admin.

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

GET /api/agenda/perfis Perfis de estabelecimento por parceiro ▶

Retorna um mapa de cod_parceiro → lista de perfis de estabelecimento registrados historicamente, ordenados por frequência. Usado para pré-preencher o campo no formulário de agendamento.

Resposta 200

JSON

{
  "1234": [ "Loja", "Home Office" ],
  "5678": [ "Escritório" ]
}

Prospecções

Cadastro e gestão de leads comerciais com filtro hierárquico e paginação. Base: /api/prospeccoes

Assim como a Agenda, cada prospecção é identificada por um id gerado pelo cliente. O POST /api/prospeccoes é idempotente — o mesmo id atualiza o registro existente.

Recurso /api/prospeccoes

GET /api/prospeccoes Lista prospecções (paginado) ▶

Retorna prospecções visíveis ao actor autenticado filtradas por escopo hierárquico. Admin e diretor recebem todas. Demais roles recebem apenas as que estão dentro da sua hierarquia ou que criaram.

Query params

Parâmetro	Tipo	Default	Descrição
page	int	1	Página atual
per_page	int	50	Itens por página (máx 2 000)

Resposta 200

JSON

{
  "ok":          true,
  "total":       320,
  "page":        1,
  "per_page":    50,
  "total_pages": 7,
  "items": [
    {
      "id":           "uuid-da-prospeccao",
      "nome":         "João Empreendimentos",
      "cnpj":         "12.345.678/0001-90",
      "responsavel":  "João Souza",
      "cidade_com":   "São Paulo",
      "uf_com":       "SP",
      "status_prosp": "Em andamento",
      "comercial":    "João Silva",
      "regional":     "Ana Lima",
      "superintendente": "Carlos Motta",
      "produtos":     [ "CDC", "Consignado" ],
      "media_producao": 25000.00,
      "criado_por":   "joao.silva",
      "atualizado_em":"2024-03-15T10:30:00Z"
    }
  ]
}

POST /api/prospeccoes Cria ou atualiza prospecção ▶

Upsert por id. Os campos de hierarquia (comercial, regional, superintendente) são preenchidos automaticamente com os valores do usuário autenticado quando omitidos.

Body — application/json

JSON

{
  "id":           "uuid-da-prospeccao", // obrigatório
  "nome":         "João Empreendimentos",
  "cnpj":         "12.345.678/0001-90",
  "responsavel":  "João Souza",

  // Endereço cadastral
  "end_cad":      "Rua das Flores, 100",
  "bairro_cad":   "Centro",
  "cidade_cad":   "São Paulo",
  "uf_cad":       "SP",

  // Endereço comercial
  "end_com":      "Av. Paulista, 1000",
  "cidade_com":   "São Paulo",
  "uf_com":       "SP",

  // Contatos
  "fone1":        "(11) 99999-0000",
  "email":        "joao@empresa.com",

  // Classificação
  "produtos":     [ "CDC", "Consignado" ],
  "media_producao": 25000.00,
  "status_prosp": "Em andamento",
  "motivo_visita":"Prospecção",
  "data_visita":  "2024-03-15",
  "parecer":      "Cliente interessado",

  // Hierarquia — preenchida automaticamente se omitida
  "comercial":    "João Silva",
  "regional":     "Ana Lima",
  "superintendente": "Carlos Motta"
}

Resposta 200

JSON

{ "ok": true, "item": { /* prospecção salva */ } }

400 id ausente

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

Remove uma prospecção pelo seu ID numérico. Qualquer usuário autenticado pode remover registros dentro do seu escopo.

Parâmetros de path

Parâmetro	Tipo	Descrição
id	int	ID numérico da prospecção

200 {"ok": true} 401 Não autenticado

Brand

Endpoint público de configuração de white-label. Retorna as variáveis de marca ativas sem necessidade de autenticação. Base: /api/brand

As variáveis são lidas das variáveis de ambiente do servidor (BRAND_*). Nenhuma autenticação é necessária — este endpoint é chamado pelo frontend na inicialização para aplicar o tema da marca.

Recurso /api/brand

GET /api/brand Configuração de white-label ▶

Retorna as configurações visuais e de identidade da marca configuradas via variáveis de ambiente. Endpoint público — não requer autenticação.

Variáveis de ambiente lidas

Variável	Default	Descrição
BRAND_NAME	`"Painel"`	Nome da marca exibido na aplicação
BRAND_SLOGAN	`""`	Slogan ou subtítulo da marca
BRAND_PRIMARY_COLOR	`"#4F46E5"`	Cor primária (hex)
BRAND_SECONDARY_COLOR	`"#7C3AED"`	Cor secundária (hex)
BRAND_LOGO_URL	`""`	URL do logotipo (opcional)
BRAND_FAVICON_URL	`""`	URL do favicon (opcional)

Resposta 200

JSON

{
  "name":           "Minha Empresa",
  "slogan":         "Soluções financeiras",
  "primaryColor":   "#1D4ED8",
  "secondaryColor": "#1E40AF",
  "logoUrl":        "https://cdn.empresa.com/logo.png",
  "faviconUrl":     "https://cdn.empresa.com/favicon.ico"
}

Admin

Endpoints exclusivos para o role admin. Permitem gerenciar parceiros pendentes de vinculação, diagnosticar a hierarquia e aplicar migrações de banco de dados. Base: /api/admin

Todos os endpoints desta seção exigem role admin. Qualquer outro role recebe 403 Forbidden.

Recurso /api/admin

GET /api/admin/parceiros-pendentes Lista parceiros sem estrutura vinculada ▶

Retorna todos os parceiros com flag pendente_vinculo = TRUE, enriquecidos com totais de efetivação e meses com produção, além da lista de estruturas comerciais disponíveis para vinculação.

Resposta 200

JSON

{
  "ok": true,
  "parceiros": [
    {
      "cod":                1234,
      "nome":               "Fulano de Tal",
      "ef_total":           150000.00,
      "meses_com_producao": 8,
      "pendente_vinculo":   true
    }
  ],
  "estruturas": [
    {
      "id":     10,
      "nome":   "Regional SP Sul",
      "tipo":   "regional"
    }
  ]
}

POST /api/admin/parceiros-pendentes/vincular Vincula parceiro a uma estrutura comercial ▶

Define a estrutura comercial de um parceiro pendente e marca pendente_vinculo = FALSE.

Body — application/json

JSON

{
  "cod":          1234,    // código do parceiro (obrigatório)
  "estrutura_id": 10      // ID da estrutura comercial (obrigatório)
}

Resposta 200

JSON

{ "ok": true }

400 Campos ausentes 404 Parceiro não encontrado

GET /api/admin/diagnostico-hierarquia Diagnóstico de parceiros fora da hierarquia ▶

Retorna parceiros que não possuem estrutura_id definido, agrupados por superintendente, regional e gestor comercial. Útil para identificar registros órfãos após importações em lote.

Resposta 200

JSON

{
  "ok":         true,
  "sem_vinculo": 42,          // total de parceiros sem estrutura_id
  "estrutura": {
    "Carlos Motta": {         // superintendente
      "Ana Lima": {            // regional
        "João Silva": [         // gestor_comercial → lista de parceiros
          { "cod": 1234, "nome": "Fulano de Tal" }
        ]
      }
    }
  }
}

Suporte & Contato

Fale com a desenvolvedora

Dúvidas sobre integração, autenticação ou comportamento da API? Entre em contato diretamente.

MO

Monica Oliveira

Desenvolvedora responsável — API Parceiro V1

Canais de atendimento

Canal	Contato
E-mail	monica.ufop1@gmail.com
WhatsApp	(19) 99846-8664

Desenvolvido por

H

HELVORA

Inteligência para Negócios

A Helvora desenvolve soluções de tecnologia, inteligência artificial e gestão comercial para negócios financeiros.
Saiba mais em www.helvora.com.br