Quem acessa
customers.read lista e visualiza. customers.manage cria, edita, importa, registra eventos e exclui.
Rota /customers
Carteira e relacionamento com clientes.
Cliente representa o contratante, pessoa física ou jurídica. A rota reúne cadastro, carteira pesquisável, Cliente 360, contatos empresariais, importação, diário e o radar operacional FARO.
Escopo seguro
Todas as consultas usam tenant e escopo efetivo do usuário; sem tenant selecionado, a API bloqueia a operação.
Relação com contratos
Um cliente pode ter vários contratos. Criar cliente não cria contrato automaticamente; a navegação apenas conecta as jornadas.
Carteira operacional
Localizar, analisar e agir
Busca e filtros
Pesquisa por nomes, CPF/CNPJ, código externo, segmento e gestor; filtros por PF/PJ, status, origem, qualidade cadastral e nível FARO.
Cliente 360
Mantém o cliente selecionado na URL e reúne resumo cadastral, contratos, planos e vidas acessíveis ao usuário.
Operação em lote
Permite atualizar status, segmento ou account manager em até 500 clientes que estejam dentro do escopo do usuário.
Exportação filtrada
Gera CSV com os mesmos filtros da carteira, respeitando tenant, acesso do usuário e limite operacional de 50 mil registros.
Treinamento visual
Passo a passo pela interface
As imagens abaixo foram produzidas com registros de demonstração e formulários vazios. Nenhum dado de cliente real ou informação pessoal de acesso aparece neste material público.
1. Carteira e Cliente 360
Comece pelos indicadores do topo. Depois use busca e filtros para localizar o cliente e selecione uma linha para abrir seu resumo 360, contratos, vidas e qualidade cadastral.
2. Cadastrar um cliente
Em Novo Cliente, escolha PF ou PJ antes do preenchimento. Informe identificação, canais, origem e segmento; adicione os contatos empresariais nos respectivos departamentos.
3. Importar uma carteira
Identifique o sistema de origem, selecione o CSV, XLS ou XLSX e execute Analisar sem importar. Revise o mapeamento e a prévia antes de confirmar qualquer gravação.
Campos do formulário
O que preencher
| Campo | Regra | API | Uso operacional |
|---|---|---|---|
| Tipo de cliente | Obrigatório | personType | COMPANY para pessoa jurídica ou INDIVIDUAL para pessoa física. |
| Razão social / Nome completo | Obrigatório | name | Razão social para PJ; nome completo para PF. |
| Nome fantasia | Opcional | legalName | Nome comercial da pessoa jurídica. |
| Nome preferencial / social | Opcional | preferredName / socialName | Formas alternativas de identificação sem substituir o nome principal. |
| CPF / CNPJ | Opcional | document | A API valida o documento, normaliza para somente dígitos e evita repetição no tenant. |
| Origem comercial | Obrigatório na tela | acquisitionSource | Canal de aquisição usado no relacionamento e na atribuição comercial. |
| Cliente indicador | Condicional | referredByCustomerId | Obrigatório em indicação; deve pertencer ao mesmo tenant e não pode ser o próprio cliente. |
| Código externo | Opcional | externalCode | Referência única dentro do tenant quando informada. |
| Segmento | Opcional | segmentId | Selecionado no catálogo isolado do tenant. |
| Account manager | Opcional | accountManager | Pessoa responsável pela gestão da conta. |
| Nascimento / Fundação | Opcional | birthDate / foundationDate | A data aplicável varia conforme PF ou PJ. |
| Cliente desde | Opcional | relationshipStartedAt | Início do relacionamento comercial com a corretora. |
| Contatos da empresa | Opcional | businessContacts | Pessoas responsáveis, áreas, cargos e canais agrupados por contato. |
| Canais gerais | Opcional | contactPoints | E-mails, telefones institucionais e presença digital sem responsável identificado. |
| Endereço | Opcional | addresses | Logradouro, número, complemento, bairro, cidade, UF e CEP. |
| Perfil complementar | Opcional | profile | Dados cadastrais e características adicionais do contratante. |
| Grupo de produção | Opcional | commercialAssignments | Atribuição comercial atual com preservação do histórico. |
| Status | Obrigatório | status | ACTIVE para operar ou INACTIVE para preservar o histórico sem excluir. |
| Observações | Opcional | notes | Anotações internas sobre o cliente. |
Fluxo de uso
Da entrada à gestão contínua
Importar carteira
Envie CSV, XLS ou XLSX. A análise sugere mapeamentos e mostra prévia de novos, existentes e duplicados antes da confirmação.
Criar
Escolha PF ou PJ, informe o nome principal e a origem comercial. O tenant é obtido da sessão autenticada.
Editar
Atualize cadastro, contatos, origem, segmento e responsáveis sem trocar o escopo do cliente.
Abrir Cliente 360
Selecione uma linha para analisar contratos, planos e vidas e seguir para as jornadas relacionadas.
Consultar ficha e diário
A ficha completa separa cadastro, contatos, canais gerais, FARO e histórico do relacionamento.
Inativar antes de excluir
A exclusão é reservada a cadastros criados por engano e sem vínculos operacionais; nos demais casos, use INACTIVE.
Regras de sistema
Validações importantes
Identificadores únicos
CPF/CNPJ normalizado e código externo não podem se repetir dentro do mesmo tenant.
Indicação segura
O indicador deve estar no mesmo tenant e o cliente não pode indicar a si próprio.
Importação com prévia
A análise não cria clientes. O lote só é aplicado depois da revisão e confirmação.
Mapeamentos supervisionados
Heurísticas e inteligência auxiliam o mapeamento, mas a correção do analista governa o resultado aplicado.
Exclusão bloqueada
Contratos, pessoas, documentos, importações, cobrança e outros vínculos operacionais impedem exclusão; prefira inativar.
Histórico preservado
Contatos retirados, diário e eventos FARO preservam rastreabilidade em vez de apagar contexto operacional.
Contatos da empresa
Quem responde por cada área e canal
Pessoas responsáveis ficam separadas dos canais gerais da empresa. Assim, RH, Financeiro e outras áreas podem ter contatos próprios sem perder os e-mails e telefones institucionais legados.
Cada contato representa uma pessoa responsável e mantém nome, departamento, cargo e canais agrupados.
Nome e pelo menos um canal entre e-mail, telefone ou WhatsApp são obrigatórios por contato.
E-mail precisa conter @; telefone e WhatsApp precisam ter pelo menos oito dígitos.
Há no máximo 50 contatos ativos por cliente e exatamente um contato principal quando a lista não está vazia.
Contatos removidos na edição são inativados, não apagados, preservando o histórico cadastral.
IDs enviados na edição precisam pertencer ao mesmo cliente e tenant.
FARO
Farol de Atenção e Relacionamento Operacional
Radar determinístico baseado em eventos manuais e sinais de movimentações, conciliação e faturamento. Não é análise emocional e não depende de LLM.
| Score | Nível | Cor | Leitura operacional |
|---|---|---|---|
| 0–19 | Normal | Verde | Sem pressão operacional relevante no momento. |
| 20–39 | Atenção | Amarelo | Há sinais que merecem acompanhamento. |
| 40–69 | Atrito | Laranja | Leia o histórico antes de falar com o cliente. |
| 70–100 | Crítico | Vermelho | Prioridade operacional elevada e ação coordenada. |
Atribuição
O alerta pode ser assumido ou atribuído a um usuário ativo do tenant.
Ciclo de vida
Eventos passam por aberto, acompanhamento, resolvido ou descartado.
Sem apagar histórico
Resolver ou descartar exige justificativa e mantém as atividades para auditoria.
API e permissões
Contratos principais da rota
| Endpoint | Permissão | Responsabilidade |
|---|---|---|
| GET /customers | customers.read | Carteira paginada, busca, filtros, ordenação, resumo e FARO. |
| GET /customers/:id | customers.read | Ficha completa do cliente no escopo autorizado. |
| POST /customers | customers.manage | Criação de cliente. |
| PATCH /customers/:id | customers.manage | Edição do cadastro e das relações normalizadas. |
| PATCH /customers/bulk | customers.manage | Atualização em lote de até 500 clientes. |
| GET /customers/export | customers.read | CSV filtrado com limite de 50 mil registros. |
| POST /customers/imports/analyze | customers.manage | Análise de arquivo de até 15 MB sem aplicar os registros. |
| POST /customers/imports/:id/apply | customers.manage | Aplicação do lote revisado. |
| GET /customers/:id/journal | customers.read | Histórico e diário do cliente. |
| POST /customers/:id/journal | customers.manage | Nova anotação no diário. |
| GET /customers/:id/faro | customers.read | Resumo e eventos do FARO. |
| POST /customers/:id/faro | customers.manage | Registro manual de alerta FARO. |
| DELETE /customers/:id | customers.manage | Exclusão apenas quando não existem vínculos bloqueadores. |
Checklist operacional
Antes de salvar ou agir
O tipo de cliente foi selecionado corretamente: pessoa jurídica ou pessoa física.
Razão social ou nome completo está claro, sem criar duplicidade na carteira.
CPF/CNPJ foi conferido quando disponível e a origem comercial foi registrada.
Em caso de indicação, o cliente indicador correto foi selecionado.
Segmento, account manager e status representam a situação operacional atual.
Contatos da empresa identificam a pessoa, sua área e ao menos um canal válido.
O contato principal foi escolhido e canais institucionais permaneceram separados.
O FARO e o diário foram consultados antes de uma interação sensível com o cliente.
Antes de excluir, foi considerada a inativação para preservar vínculos e histórico.