# Cadastro de cliente pelo app



# Tela de formulário de cadastro de clientes

<table border="1" id="bkmrk-%C2%A0-projeto%2Fsistema%3Age" style="border-collapse: collapse; width: 100.123%; height: 68px;"><tbody><tr style="border-style: solid;"><td rowspan="3" style="width: 26.6667%; height: 68px; border-color: black; border-top-style: hidden; border-left-style: hidden; border-bottom-style: hidden;">  
 ![Softensistemas Logo](https://www.softensistemas.com.br/assets/img/logo.webp)

</td><td style="width: 49.9999%; height: 10px; border-color: black; border-style: solid;"><span style="color: #000000;">**Projeto/Sistema:**</span>  
<span style="color: #000000;">CADASTRO DE CLIENTE PELO APP</span></td><td class="align-center" style="width: 23.3333%; height: 10px; border-color: black; border-style: solid;"><span style="color: #000000;">**Versão do *Template:***</span>  
<span style="color: #000000;">1.2</span></td></tr><tr style="border-style: solid;"><td style="width: 49.9999%; height: 29px; border-color: black; border-style: solid;"><span style="color: #000000;">**Processo:**</span>  
<span style="color: #000000;">Tela de formulário de cadastro de cliente</span></td><td class="align-center" style="width: 23.3333%; height: 29px; border-color: black; border-style: solid;"><span style="color: #000000;">**Versão do Documento:**</span>  
<span style="color: #000000;">1.0</span></td></tr><tr style="border-style: solid;"><td style="width: 49.9999%; height: 29px; border-color: black; border-style: solid;"><span style="color: #000000;">**Responsável(eis):** </span>  
<span style="color: #000000;">Pâmela Munhoz, Jalile Cornachioni, Gustavo Evaristo</span></td><td class="align-center" style="width: 23.3333%; height: 29px; border-color: black; border-style: solid;"><span style="color: #000000;">**Data:** </span>

<span style="color: #000000;">05/09/2025</span>

</td></tr></tbody></table>

##### <span style="color: #000000;">**1. Introdução**</span>

<span style="color: #000000;">O aplicativo mobile é utilizado por representantes de vendas que realizam a visita aos clientes para registro de pedidos. Atualmente o aplicativo sincroniza apenas clientes cadastrados previamente no GerencieAqui (GA), não havendo a possibilidade de realizar cadastros novos durante as visitas.</span>

<span style="color: #000000;">A limitação afeta o processo de prospecção, já que representantes não conseguem abrir carteira de um novo cliente no momento da venda.</span>

##### <span style="color: #000000;">**2. Processo**</span>

[![image-1760527894387.jpg](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/scaled-1680-/image-1760527894387.jpg)](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/image-1760527894387.jpg)

#### **Solução esperada**

A implementação do cadastro de clientes diretamente no **App Mobile** *(Representante de vendas)* possui como maior objetivo a eliminação do processo de dependência de envio manual de cadastro para o responsável pela utilização do **GerencieAqui** *(retaguarda)*, permitindo assim que o representante registre o cliente no momento da venda ou do orçamento, com sincronização posterior para o sistema de retaguarda. O *processo deverá:*

- Permitir cadastrar novos clientes diretamente ao aplicativo mobile, *respeitando a configuração de permissão de cadastro* definida na tela de configurações, com valor padrão inativo para todos os dispositivos.
- Exibir o ícone de adição "➕" para criação de novo cliente *nas tela*s: listagem de clientes, campo de cliente em nova venda e novo orçamento. **Somente quando a configuração estiver habilitada**.
- Ocultar completamente o ícone de adição caso a configuração estiver **desabilitada**.
- Garantir que os clientes importados da retaguarda **não possam** ser editados, permitindo edição apenas para clientes novos recém criados e que ainda **não foram exportados**.
- Exibir ícone de edição na tela de listagem e detalhes somente para clientes novos (não sincronizados).

- - - - - -

#### **Especificação Funcional**

- - - - - -

##### **CADASTRO DE CLIENTE POR NOVO ORÇAMENTO E NOVA VENDA:**

***[Protótipo de tela:](https://www.figma.com/design/CA2GjWd7CVf0Lmn0K14AYo/Fluxo-de-Vendas---Gerencie-Vendas?node-id=2753-15546&p=f&t=NPvNQYFlM1J8K8uH-0)***

[![image-1760621174671.png](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/scaled-1680-/image-1760621174671.png)](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/image-1760621174671.png)

##### **CADASTRO DE CLIENTE POR CLIENTES:**

***[Protótipo de tela:](https://www.figma.com/design/CA2GjWd7CVf0Lmn0K14AYo/Fluxo-de-Vendas---Gerencie-Vendas?node-id=2753-15546&p=f&t=NPvNQYFlM1J8K8uH-0)***

[![image-1760621228766.png](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/scaled-1680-/image-1760621228766.png)](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/image-1760621228766.png)

##### **TELA DE CONFIGURAÇÃO:**

***[Protótipo de tela:](https://www.figma.com/design/CA2GjWd7CVf0Lmn0K14AYo/Fluxo-de-Vendas---Gerencie-Vendas?node-id=2948-3961&t=NPvNQYFlM1J8K8uH-0)***

[![image-1760621292306.png](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/scaled-1680-/image-1760621292306.png)](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/image-1760621292306.png)

##### **TELA DE SINCRONIZAÇÃO:**

***[Protótipo de tela:](https://www.figma.com/design/CA2GjWd7CVf0Lmn0K14AYo/Fluxo-de-Vendas---Gerencie-Vendas?node-id=2753-15550&p=f&t=NPvNQYFlM1J8K8uH-0)***

[![image-1760621350028.png](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/scaled-1680-/image-1760621350028.png)](https://docs.softensistemas.com.br/uploads/images/gallery/2025-10/image-1760621350028.png)

 ***Descrição dos Campos:***

<table border="1" cellpadding="7" cellspacing="0" class="align-center" id="bkmrk-campo-tipo-tamanho-o" style="height: 560px; width: 656px;"><tbody><tr style="height: 35px;" valign="top"><td bgcolor="#acb9ca" style="width: 310px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">**Campo**</span>

</td><td bgcolor="#acb9ca" style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">**Tipo**</span>

</td><td bgcolor="#acb9ca" style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">**Tamanho**</span>

</td><td bgcolor="#acb9ca" style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">**Obrig. ?**</span>

</td></tr><tr style="height: 35px;"><td class="align-left" style="width: 310px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">CPF (Seleção de pessoa física)</span></td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Número</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;">11

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Não</span>

</td></tr><tr style="height: 35px;"><td class="align-left" style="width: 310px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">CNPJ (Seleção de pessoa jurídica)</span></td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Número</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">14</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Não</span>

</td></tr><tr style="height: 35px;"><td style="width: 310px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Nome/Razão Social</span>

</td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Número</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">60</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Sim</span>

</td></tr><tr><td style="width: 310px; border-style: solid; border-color: black;"><span style="color: #000000;">Nome fantasia (Seleção de pessoa jurídica)</span>

</td><td style="width: 139px; border-style: solid; border-color: black;"><span style="color: #000000;">Texto</span>

</td><td style="width: 91px; border-style: solid; border-color: black;"><span style="color: #000000;">60</span>

</td><td style="width: 116px; border-style: solid; border-color: black;"><span style="color: #000000;">Não</span>

</td></tr><tr><td style="width: 310px; border-style: solid; border-color: black;"><span style="color: #000000;">Tipo de Contribuinte</span>

</td><td style="width: 139px; border-style: solid; border-color: black;"><span style="color: #000000;">Dropdown</span>

</td><td style="width: 91px; border-style: solid; border-color: black;"><span style="color: #000000;">-</span>

</td><td style="width: 116px; border-style: solid; border-color: black;"><span style="color: #000000;">Não</span>

</td></tr><tr><td style="width: 310px; border-style: solid; border-color: black;"><span style="color: #000000;">IE (Seleção de pessoa jurídica)</span>

</td><td style="width: 139px; border-style: solid; border-color: black;"><span style="color: #000000;">Número</span>

</td><td style="width: 91px; border-style: solid; border-color: black;">20</td><td style="width: 116px; border-style: solid; border-color: black;"><span style="color: #000000;">Não</span>

</td></tr><tr><td style="width: 310px; border-style: solid; border-color: black;"><span style="color: #000000;">RG (Seleção de pessoa física)</span>

</td><td style="width: 139px; border-style: solid; border-color: black;"><span style="color: #000000;">Número</span>

</td><td style="width: 91px; border-style: solid; border-color: black;"><span style="color: #000000;">9</span>

</td><td style="width: 116px; border-style: solid; border-color: black;"><span style="color: #000000;">Não</span>

</td></tr><tr style="height: 35px;"><td style="width: 310px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">E-mail</span>

</td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Texto</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">100</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Não</span>

</td></tr><tr style="height: 35px;"><td style="width: 310px; border-style: solid; border-color: black; height: 35px;">Telefone (Com DDD)

</td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Número</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">11</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Não</span>

</td></tr><tr style="height: 35px;"><td style="width: 310px; border-style: solid; border-color: black; height: 35px;">CEP

</td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Número</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">8</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Sim</span>

</td></tr><tr style="height: 35px;"><td style="width: 310px; border-style: solid; border-color: black; height: 35px;">Endereço

</td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Texto</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">60</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Sim</span>

</td></tr><tr style="height: 35px;"><td style="width: 310px; border-style: solid; border-color: black; height: 35px;">Número

</td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Número</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">20</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Sim</span>

</td></tr><tr style="height: 35px;"><td style="width: 310px; border-style: solid; border-color: black; height: 35px;">Complemento

</td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Texto</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">50</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Não</span>

</td></tr><tr style="height: 35px;"><td style="width: 310px; border-style: solid; border-color: black; height: 35px;">Bairro

</td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Texto</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">60</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Sim</span>

</td></tr><tr style="height: 35px;"><td style="width: 310px; border-style: solid; border-color: black; height: 35px;">Município e UF

</td><td style="width: 139px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Texto</span>

</td><td style="width: 91px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">50</span>

</td><td style="width: 116px; border-style: solid; border-color: black; height: 35px;"><span style="color: #000000;">Sim</span>

</td></tr><tr><td style="width: 310px; border-style: solid; border-color: black;">Vendedor

</td><td style="width: 139px; border-style: solid; border-color: black;"><span style="color: #000000;">Texto</span>

</td><td style="width: 91px; border-style: solid; border-color: black;"><span style="color: #000000;">-</span>

</td><td style="width: 116px; border-style: solid; border-color: black;"><span style="color: #000000;">Não</span>

</td></tr><tr><td style="width: 310px; border-style: solid; border-color: black;">Observação interna

</td><td style="width: 139px; border-style: solid; border-color: black;"><span style="color: #000000;">Texto</span>

</td><td style="width: 91px; border-style: solid; border-color: black;"><span style="color: #000000;">5000</span>

</td><td style="width: 116px; border-style: solid; border-color: black;"><span style="color: #000000;">Não</span>

</td></tr></tbody></table>

#####  

##### ***Regras de Interface:***

***1. Campo CPF/CNPJ:***

O campo "CNPJ/CPF" deverá ser preenchido corretamente com a quantidade de dígitos necessários.

**Comportamento esperado:**

- - Ao realizar o preenchimento corretamente e após a validação, os campos subsequentes serão liberados para preenchimento dos dados.
    - Validar duplicidade de CPF/CNPJ na base local do aplicativo: 
        - Caso haja registro com o mesmo dado, exibir a mensagem "Já existem registros associados a este CNPJ ou CPF", permitindo ainda assim a criação de mais um cliente com o mesmo documento.
        - Caso não haja duplicidade, seguir normalmente o fluxo de cadastro.

**Cenários negativos e possíveis erros:**

- - Ao digitar um CPF/CNPJ com a quantidade de dígitos inválidos deverá aparecer uma mensagem com o texto sugerido "CPF/CNPJ inválido".

***2. E-mail:***

Embora o campo não seja obrigatório a inclusão de e-mail no cadastro do cliente possibilita o envio de relatórios e pedidos de venda/orçamento, com isso é necessário que o campo possua um endereço de e-mail válido caso tenha sido preenchido.

**Comportamento esperado**

- - Ao realizar o cadastro do e-mail do cliente com formato inválido, ao tentar prosseguir deverá aparecer uma mensagem com o texto sugerido "O e-mail informado não está em um formato válido".

***3. Telefone:***

O campo não é obrigatório e caso preenchido deverá ter um formato válido com DDD. O telefone é um campo obrigatório devido a possibilidade de ser encaminhado relatório de venda/orçamento diretamente pelo WhatsApp do cliente

**Comportamento esperado**

- - Ao realizar o cadastro do telefone do cliente com formato inválido, ao tentar prosseguir deverá aparecer uma mensagem com o texto sugerido "Digite um número de telefone válido".

***4. Campo CEP:***

Os dados serão importados para dentro do banco do APP.

**Comportamento esperado:**

- - Consultar o serviço de CEP já utilizado pelo retaguarda para preencher automaticamente logradouro, município e UF no formulário de cadastro.
    - Caso não seja possível localizar o CEP, o sistema deverá permitir a seleção manual de cidade a partir da base local de município sincronizada com o app.
    - Concatenar os valores de município e UF em um único campo no formulário.

**Cenário negativos e possíveis erros:**

- - Ao realizar o preenchimento com quantidade de dígitos inválida, deverá aparecer uma mensagem "CEP inválido".

- 

##### ***REGRA DE NEGÓCIO TELA DE CADASTRO:***

1. O sistema mobile não deve permitir edição de clientes que já estão cadastrados ou importados na retaguarda.
2. A edição será permitida somente para clientes novos, ainda não exportados. *Regras de exibição*: 
    - Exibir ícone de edição na tela de listagem e de detalhes somente para clientes novos (não sincronizados).
    - Não exibir o ícone de edição para clientes já exportados.
3. Durante o cadastro de um novo cliente: 
    - O sistema deve verificar se já existe um cliente com o mesmo CPF/CNPJ: 
        - Caso exista exibir mensagem: *Já existe registros associados a este CNPJ ou CPF.".* O sistema permitirá a criação mesmo assim.
        - Caso não exista, seguir normalmente o fluxo de cadastro.
4. O sistema deverá consultar o serviço de CEP já utilizado pela retaguarda para preencher automaticamente logradouro, município e UF no formulário de cadastro 
    - Caso CEP não seja encontrado, o sistema deverá permitir que o usuário selecione manualmente a cidade a partir da base local sincronizada de municípios.
5. Os valores de município e UF deverão ser concatenados em um único campo no formulário de cadastro.
6. O Campo vendedor deverá ser preenchido automaticamente e respeitar a configuração de permissão para alteração.
7. O sistema mobile e o retaguarda deverão manter um campo de origem para identificar se o cliente foi cadastrado pelo mobile ou pelo retaguarda.

##### ***REGRA DE NEGÓCIO TELA DE CONFIGURAÇÃO:***

1. O sistema deve oferecer uma configuração para determinar se o usuário poderá ou não realizar cadastro de novos clientes pelo aplicativo mobile. O valor padrão dessa configuração deverá ser **inativo** para todos os dispositivos. 
    - Quando a opção estiver **habilitada**, o sistema deverá: 
        - Exibir o ícone ➕ para criação de novo cliente nas telas de listagem de clientes.
        - Exibir o ícone **➕** no campo cliente das telas de *nova venda* e *novo orçamento,* permitindo o cadastro direto a partir dessas telas.
    - Quando opção estiver **desabilitada**, o sistema deverá: 
        - Ocultar completamente o ícone que permite o cadastro de novos clientes em todas as telas e campos.
        - Impedir o usuário de iniciar o fluxo de cadastro de cliente.
2. A configuração de permissão para alteração de vendedor também deverá ser respeitada: 
    - Se **habilitada**, o usuário poderá alterar o vendedor no cadastro de cliente, venda e orçamento.
    - Se **desabilitada**, o vendedor permanecerá fixo, sem permissão de alteração.

##### ***REGRA DE NEGÓCIO TELA DE SINCRONIZAÇÃO***

1. O sistema retaguarda deverá enviar, durante a sincronização de clientes: 
    - E-mail e telefone dos clientes
    - Vendedor vinculado ao cliente
    - Todos os municípios para atualização da base local de cidades no app, com frequência de sincronização configurável.
2. O sistema deverá permitir sincronização manual de clientes, vendas e orçamentos entre o mobile e o retaguarda.
3. Durante o processo: 
    - A exportação de clientes deverá ser travada como sempre ativa, impedindo que o usuário desmarque essa opção.
    - Caso a permissão de cadastro de cliente esteja desabilitada, o sistema deverá ocultar a opção de exportar clientes para o retaguarda.
    - A sincronização do mobile deverá desconsiderar a data de cadastro e se basear apenas no indicador de cliente exportado da base local.
    - O sistema mobile deverá enviar o cadastro de clientes obrigatoriamente antes da venda ou orçamento.
    - A sincronização deverá ocorrer mesmo que não haja vendas ou orçamentos pendentes.
    - Durante o envio, o sistema deverá atribuir o nome do cliente ao contato padrão no retaguarda e garantir que o vendedor responsável seja incluído no envio.

##### ***Questões Técnicas:***

***Estrutura de Integração Exemplo da estrutura atual do payload de envio do mobile para o retaguarda. Deve ser incluído no Payload tipo de contribuínte, vendedor, e-mail e telefone:***

***{ "originId": 0,  
"name": "name\_a10cbf024d58",  
"tradeName": "tradeName\_26ad41df96b3",  
"personType": "0",  
"cpfCnpj": "999.999.999-99",  
"zipCode": "99999999",  
"ieRg": "ieRg\_bcaf3a4888d2",   
"address": "address\_e78947a13cd5",   
"complement": "complement\_21df26977603",   
"neighborhood": "neighborhood\_be1610630a66",   
"city": "city\_1040a05de6da",   
"sellerOriginId": 0,   
"internalNotes": "internalNotes\_62e1372c5096",   
"image": "image\_1cbed78b9b46"  
"appId": "069d3be4-fbed-4663-a3de-00c9be6af151"  
}  
  
personType: 0-CLIENTE, 1-FORNECEDOR   
imagem: base64   
appId: Novo campo que vai ser criado, para preenchimento do id gerado no aplicativo e vínculo na venda quando for um cadastro novo***

***2. Persistência e Base de Dados:***

- ***Alterações ou novos campos criar um bit para indicar cliente sincronizado;<span class="hiddenVisually_b18fe2">,</span>***
- ***Regras de atualização: “campo sincronizado deve ser atualizado para true após confirmação do servidor”.***

***3. Lógica de Sincronização:***

- ***Fluxo e prioridade de envio: clientes sempre antes de vendas/orçamentos.<span class="hiddenVisually_b18fe2">,</span>***
- ***Tratamento de falhas: caso sincronização não tenha concluído por algum motivo (pode ser timeout, falhas diversas), o sistema deve executar rollback e não atualizar o bit "sincronizado" na tabela local fazendo com que a sync leia esse cliente e tente enviá-lo novamente posteriormente.<span class="hiddenVisually_b18fe2">,</span>***

***4. Testes Técnicos:***

- ***Estratégia de teste automatizado (mock de API, payloads simulados).<span class="hiddenVisually_b18fe2">,</span>***
- ***Cenários de integração (cliente duplicado, falha de rede, permissão desabilitada).***

©SOFTEN SISTEMAS 2025