Quem acessa
customers.read lista e visualiza clientes. customers.manage cria, edita e exclui.
Rota /customers
Cadastro de clientes.
Cliente representa a pessoa fisica ou juridica contratante dos beneficios gerenciados pelo tenant. Pessoas vinculadas ao cliente continuam em CustomerPerson; todo cadastro de contratante usa Customer.
Escopo seguro
Sem tenant no contexto, a API bloqueia a consulta antes de retornar dados.
Relacao com contratos
Um cliente pode ter varios contratos. Criar cliente nao cria contrato automaticamente.
Campos do formulario
O que preencher
| Campo | Regra | API | Uso operacional |
|---|---|---|---|
| Tipo de cliente | Obrigatorio | personType | COMPANY (pessoa juridica) por padrao ou INDIVIDUAL (pessoa fisica). |
| Razao social / Nome completo | Obrigatorio | name | Razao social para PJ; nome completo para PF. |
| Nome fantasia | Opcional | legalName | Nome comercial usado pela pessoa juridica. |
| Nome preferencial | Opcional | preferredName | Forma de tratamento preferida pelo cliente. |
| Nome social | Opcional | socialName | Disponivel para pessoa fisica sem substituir o nome civil. |
| CPF / CNPJ | Opcional | document | CPF com 11 digitos para PF ou CNPJ com 14 digitos para PJ; a API valida o documento. |
| Documento normalizado | Sistema | normalizedDocument | Somente digitos, preenchido pela API e unico por tenant quando houver. |
| Origem comercial | Obrigatorio na tela | acquisitionSource | Canal de aquisicao usado para atribuicao de marketing e relacionamento; dados legados podem permanecer nulos. |
| Cliente indicador | Condicional | referredByCustomerId | Obrigatorio quando a origem for CUSTOMER_REFERRAL; deve pertencer ao mesmo tenant. |
| Codigo Externo | Opcional | externalCode | Unico dentro do tenant quando informado. |
| Segmento | Opcional | segmentId | Selecionado no catalogo do tenant; a API mantem segment como texto compativel para integracoes legadas. |
| Account Manager | Opcional | accountManager | Responsavel pela conta. |
| Nascimento / Fundacao | Opcional | birthDate / foundationDate | A data aplicavel varia conforme PF ou PJ. |
| Cliente desde | Opcional | relationshipStartedAt | Inicio do relacionamento comercial com a corretora. |
| Contatos | Opcional | contactPoints | E-mails e telefones normalizados, com principal, desatualizado e consentimento promocional. |
| Endereco | Opcional | addresses | Endereco de correspondencia estruturado em logradouro, numero, complemento, bairro, cidade, UF e CEP. |
| Perfil complementar | Opcional | profile | RG/IE, documento, profissao, indicadores PF/PJ, dados legados e caracteristicas da origem. |
| Grupo de producao | Opcional | commercialAssignments | Mantem a atribuicao comercial atual e seu historico. |
| Status | Obrigatorio | status | ACTIVE por padrao; tambem aceita INACTIVE. |
| Observacoes | Opcional | notes | Anotacoes internas do cliente. |
Fluxo de uso
Importar, criar, editar e excluir
Importar carteira
Envie CSV, XLS ou XLSX de qualquer sistema. A IA sugere aliases, o analista revisa o mapeamento e a previa mostra novos, existentes e duplicados antes da confirmacao.
Criar
Clique em Novo Cliente, escolha Pessoa juridica ou Pessoa fisica, preencha o nome principal e salve. O tenant vem do usuario autenticado.
Editar
Abra Editar cliente, ajuste os campos e envie PATCH /api/v1/customers/:id.
Excluir
Exclua somente clientes sem contratos vinculados e criados por engano.
Regras de sistema
Validacoes importantes
Codigo externo unico
tenantId + externalCode nao pode repetir dentro do mesmo tenant.
Documento unico
A API valida CPF/CNPJ, salva a versao normalizada com apenas digitos e impede repeticao no mesmo tenant.
Indicacao segura
Uma indicacao exige um cliente indicador do mesmo tenant e nao permite autoindicacao.
Catalogo de segmentos
O catalogo e isolado por tenant, possui uma base inicial e reaproveita segmentos legados sem perder os clientes existentes.
Importacao com previa
O arquivo nao cria clientes durante a analise. A aplicacao exige confirmacao e preserva identificadores, ficha complementar, contatos, enderecos e grupo comercial em tabelas normalizadas.
Aliases aprendidos
Heuristicas, IA e memoria Pinecone sugerem os campos canonicos. Correcoes confirmadas pelo analista sao reaproveitadas por tenant e sistema de origem.
Dados financeiros protegidos
Dados bancarios, cartoes e credenciais nao entram no cadastro de clientes. Documentos cadastrais, inclusive CNH quando informada, ficam na ficha 360 do contratante.
Exclusao bloqueada
Clientes com contratos vinculados nao podem ser excluidos.
Campos vazios
A API remove espacos extras e salva campos opcionais vazios como null.
Checklist operacional
Antes de salvar
O tipo de cliente foi selecionado corretamente: Pessoa juridica ou Pessoa fisica.
Razao social para PJ ou nome completo para PF esta claro e padronizado.
CPF ou CNPJ foi conferido e preenchido no formato esperado, quando houver.
A origem comercial foi registrada e, em caso de indicacao, o cliente indicador foi selecionado.
Codigo Externo foi usado apenas se existir referencia confiavel.
Segmento foi selecionado no catalogo e Account Manager foi preenchido quando ajuda a operacao.
Status esta coerente: ACTIVE para operar, INACTIVE para preservar historico.
Foi conferido se o cliente ja possui contratos antes de tentar excluir.