Pessoa jurídicaPronto

Eu, como usuário do sistema AgroDigital, quero buscar pessoa jurídica, listar pessoas jurídicas, cadastrar pessoa jurídica, visualizar pessoa jurídica e editar pessoa jurídica para gerenciar pessoas jurídicas.

1. Buscar pessoa jurídica

Dado que estou na tela inicial para usuários autenticados
Quando acesso o menu Pessoa Jurídica
Então o sistema exibe a tela de busca com os campos abaixo.

Campo	Tipo	Obrigatório	Validações	Exemplo	Valor padrão
CNPJ ou Razão Social	Texto curto	Não	Tamanho máximo = 255 caracteres.	56.338.814/0001-95	Vazio
Estado	Seleção simples	Não	Refere-se ao endereço de correspondência. Valores = lista de estados brasileiros.	Minas Gerais	Vazio
Município	Seleção pesquisável	Não	Disponível se Estado estiver preenchido. Refere-se ao endereço de correspondência. Valores = municípios do estado selecionado.	Esmeraldas	Vazio
Situação do Cadastro	Seleção simples	Não	Valores = Ativo, Inativo.	Ativo	Vazio

O sistema exibe as ações comuns das telas de busca (AC001): Inicial, Adicionar Novo e Pesquisar. Antes da primeira pesquisa, deve solicitar o preenchimento de pelo menos um campo.

2. Listar pessoas jurídicas

Dado que estou na tela de busca
E o campo de busca ou pelo menos um filtro foi preenchido corretamente
Quando realizo a ação Pesquisar
Então o sistema retorna os registros compatíveis.

Campo	Tipo	Ordenável	Descrição	Exemplo
CNPJ	Texto	Sim	Exibe o CNPJ.	56.338.814/0001-95
Razão Social	Texto	Sim	Exibe a razão social.	Queijaria São José Ltda.
Estado	Texto	Sim	Exibe o estado do endereço de correspondência.	Minas Gerais
Município	Texto	Sim	Exibe o município do endereço de correspondência.	Esmeraldas
Situação	Texto	Não	Exibe a situação do cadastro.	Ativo

Para cada resultado, o sistema exibe as ações comuns de listagem (AC002): Visualizar e Editar.

Cenários alternativos

• Se nenhum campo de busca ou filtro válido for preenchido, o sistema não realiza a busca, informa os problemas encontrados e destaca os campos com erro.
• Se não houver registros compatíveis, o sistema exibe a mensagem “Nenhum resultado foi encontrado”.
• Em caso de falha técnica, aplica-se CA003 — Notificar erro ao usuário devido a falha técnica.

3. Cadastrar pessoa jurídica

Dado que estou na tela de cadastro
Então o sistema exibe o formulário descrito a seguir.

Campos indicados com * são obrigatórios.

Informações básicas

Campo	Tipo	Obrigatório	Validações	Exemplo	Valor padrão
CNPJ	CNPJ	Sim	Tamanho = 14 dígitos. Formato = XX.XXX.XXX/XXXX-XX. Validação de dígito verificador.	56.338.814/0001-95	Vazio
Razão Social	Texto curto	Sim	Consulta à API de CNPJ. Tamanho máximo = 255 caracteres.	Botica Comercial Farmacêutica Ltda.	Valor obtido pela API de CNPJ
Nome Fantasia	Texto curto	Não	Consulta à API de CNPJ. Tamanho máximo = 255 caracteres.	O Boticário	Valor obtido pela API de CNPJ

Representantes legais (um ou mais)

Campo	Tipo	Obrigatório	Validações	Exemplo	Valor padrão
Representante Legal	Seleção de entidade	Sim	Valores = pessoas físicas cadastradas no sistema (US042). Pesquisa por nome ou CPF.	José Aarão Neto	Vazio
CPF	CPF	Sim	Disponível quando Representante Legal estiver preenchido. Somente leitura. Corresponde à pessoa selecionada em Representante Legal.	555.009.956-40	Vazio
Documento de Vínculo	Arquivo	Sim	Tipos aceitos = PNG, JPG, PDF. Tamanho máximo = 50 MB.	procuracao.pdf	Vazio

Informações de localização

Endereço de correspondência

Campo	Tipo	Obrigatório	Validações	Exemplo	Valor padrão
Zona	Seleção simples	Sim	Somente leitura. Valor = Urbana.	Urbana	Urbana
Localidade	Seleção pesquisável	Não	Disponível se Zona = Rural. Valores = localidades cadastradas no sistema (US005). Pré-filtrado pelo município.	Vila dos Técnicos	Vazio
CEP	Texto curto	Sim	Disponível se Zona = Urbana. Tamanho = 8 dígitos. Formato = XXXXX-XXX.	37060-400	Vazio
Estado (via CEP)	Texto curto	Sim	Disponível se Zona = Urbana e CEP estiver preenchido. Consulta à API de CEP. Somente leitura.	Minas Gerais	Valor obtido pela API de CEP
Município (via CEP)	Texto curto	Sim	Disponível se Zona = Urbana e CEP estiver preenchido. Consulta à API de CEP. Somente leitura.	Timóteo	Valor obtido pela API de CEP
Bairro	Texto curto	Sim	Disponível se Zona = Urbana. Consulta à API de CEP.	Centro	Valor obtido pela API de CEP, quando disponível
Endereço	Texto curto	Sim	Disponível se Zona = Urbana. Consulta à API de CEP.	Avenida JK	Valor obtido pela API de CEP, quando disponível
Número	Texto curto	Sim	Disponível se Zona = Urbana. Tamanho máximo = 20 caracteres.	10	Vazio
Complemento	Texto curto	Não	Disponível se Zona = Urbana. Tamanho máximo = 255 caracteres.	Apto 02	Vazio
Distrito (zona urbana)	Seleção pesquisável	Não	Disponível se Zona = Urbana. Valores = distritos cadastrados no sistema (US005). Pré-filtrado pelo município.	Cachoeira do Vale	Vazio
Formato da Geolocalização	Seleção simples	Sim	Valores = DMS (graus, minutos, segundos), DD (decimal).	DMS (graus, minutos, segundos)	DMS (graus, minutos, segundos)
Latitude	Decimal	Sim	Disponível para zonas rural e urbana. Pode ser informada manualmente ou selecionada no mapa, com consulta à API do Google Maps. Pré-estimada pelos dados de endereço. Máscara definida pelo formato de geolocalização (RN010).	-19.165827719338893	Vazio
Longitude	Decimal	Sim	Disponível para zonas rural e urbana. Pode ser informada manualmente ou selecionada no mapa, com consulta à API do Google Maps. Pré-estimada pelos dados de endereço. Máscara definida pelo formato de geolocalização (RN010).	-44.362871253967285	Vazio

Campo	Tipo	Obrigatório	Validações	Exemplo	Valor padrão
O endereço de correspondência é também o endereço da sede?	Seleção simples	Sim	Valores = Sim, Não.	Sim	Sim

Endereço da sede

Disponível se O endereço de correspondência é também o endereço da sede? = Não.

Campo	Tipo	Obrigatório	Validações	Exemplo	Valor padrão
Zona	Seleção simples	Sim	Valores = Rural, Urbana.	Rural	Rural
Estado (zona rural)	Seleção simples	Sim	Disponível se Zona = Rural. Valores = lista de todos os estados brasileiros.	Minas Gerais	Vazio
Município (zona rural)	Seleção pesquisável	Sim	Disponível se Zona = Rural e Estado estiver preenchido. Valores = municípios brasileiros correspondentes ao estado selecionado.	Lavras	Vazio
Nome da estrada e quilômetro de referência	Texto curto	Sim	Disponível se Zona = Rural.	Estrada de chão no Km 12	Vazio
Localidade	Seleção pesquisável	Não	Disponível se Zona = Rural. Valores = localidades cadastradas no sistema (US005). Pré-filtrado pelo município.	Vila dos Técnicos	Vazio
Distrito (zona rural)	Seleção pesquisável	Não	Disponível se Zona = Rural. Valores = distritos cadastrados no sistema (US005). Pré-filtrado pelo município.	Cachoeira do Vale	Vazio
CEP	Texto curto	Sim	Disponível se Zona = Urbana. Tamanho = 8 dígitos. Formato = XXXXX-XXX.	37060-400	Vazio
Estado (via CEP)	Texto curto	Sim	Disponível se Zona = Urbana e CEP estiver preenchido. Consulta à API de CEP. Somente leitura.	Minas Gerais	Valor obtido pela API de CEP
Município (via CEP)	Texto curto	Sim	Disponível se Zona = Urbana e CEP estiver preenchido. Consulta à API de CEP. Somente leitura.	Timóteo	Valor obtido pela API de CEP
Bairro	Texto curto	Sim	Disponível se Zona = Urbana. Consulta à API de CEP.	Centro	Valor obtido pela API de CEP, quando disponível
Endereço	Texto curto	Sim	Disponível se Zona = Urbana. Consulta à API de CEP.	Avenida JK	Valor obtido pela API de CEP, quando disponível
Número	Texto curto	Sim	Disponível se Zona = Urbana. Tamanho máximo = 20 caracteres.	10	Vazio
Complemento	Texto curto	Não	Disponível se Zona = Urbana. Tamanho máximo = 255 caracteres.	Apto 02	Vazio
Distrito (zona urbana)	Seleção pesquisável	Não	Disponível se Zona = Urbana. Valores = distritos cadastrados no sistema (US005). Pré-filtrado pelo município.	Cachoeira do Vale	Vazio
Formato da Geolocalização	Seleção simples	Sim	Valores = DMS (graus, minutos, segundos), DD (decimal).	DMS (graus, minutos, segundos)	DMS (graus, minutos, segundos)
Latitude	Decimal	Sim	Disponível para zonas rural e urbana. Pode ser informada manualmente ou selecionada no mapa, com consulta à API do Google Maps. Pré-estimada pelos dados de endereço. Máscara definida pelo formato de geolocalização (RN010).	-19.165827719338893	Vazio
Longitude	Decimal	Sim	Disponível para zonas rural e urbana. Pode ser informada manualmente ou selecionada no mapa, com consulta à API do Google Maps. Pré-estimada pelos dados de endereço. Máscara definida pelo formato de geolocalização (RN010).	-44.362871253967285	Vazio

Informações de contato

Campo	Tipo	Obrigatório	Validações	Exemplo	Valor padrão
Tipo de Contato (E-mail)	Texto	Sim	Somente leitura.	E-mail	E-mail
E-mail	Texto curto	Sim	Formato = e-mail válido.	joaquim@email.com	Vazio
Observação do e-mail	Texto longo	Não	Tamanho máximo = 1.500 caracteres.	Meu e-mail	Vazio
Tipo de Contato (Telefone)	Texto	Sim	Somente leitura.	Telefone	Telefone
Número	Texto numérico	Sim	Tamanho = 11 dígitos. Formato = (XX) XXXXX-XXXX.	(35) 99999-1111	Vazio
Observação do telefone	Texto longo	Não	Tamanho máximo = 1.500 caracteres.	Meu telefone	Vazio
Tipo de Contato (outros)	Seleção simples	Sim	Valores = E-mail, Telefone.	Telefone	E-mail
E-mail (outros)	Texto curto	Sim	Disponível se Tipo de Contato = E-mail. Formato = e-mail válido.	joaquim_junior@email.com	Vazio
Número (outros)	Texto numérico	Sim	Disponível se Tipo de Contato = Telefone. Tamanho = 11 dígitos. Formato = (XX) XXXXX-XXXX.	(35) 99999-1111	Vazio
Observação (outros)	Texto longo	Não	Tamanho máximo = 1.500 caracteres.	Contato do meu filho	Vazio

Anexos e observações

Campo	Tipo	Obrigatório	Validações	Exemplo	Valor padrão
Documento	Arquivo	Sim	Tipos aceitos = PNG, JPG, PDF. Tamanho máximo = 50 MB.	documento.png	Vazio
Descrição	Texto curto	Não	Disponível quando Documento for informado. Tamanho máximo = 255 caracteres.	Documento de identidade com foto	Vazio
Observação	Texto longo	Não	Tamanho máximo = 1.500 caracteres.	Informações adicionais sobre a pessoa.	Vazio

Ações e resultado

O cadastro usa as ações comuns AC003 e AC006:

• Todas as pessoas jurídicas: volta para a busca.
• Adicionar: valida e salva o cadastro.
• Ver item: abre o representante legal selecionado.
• Adicionar/Remover item: gerencia representantes, outros contatos e anexos.
• Baixar documento: baixa o documento de vínculo ou anexo.

Em caso de sucesso, o sistema exibe uma mensagem e as ações Voltar e Visualizar. Em caso de erro de validação, mantém o formulário e apresenta os erros nos respectivos campos.

4. Visualizar pessoa jurídica

Dado que estou na tela de visualização
Então o sistema exibe todos os campos do cadastro como somente leitura, com seus valores preenchidos.

Campo	Tipo	Descrição	Exemplo
Situação do Cadastro	Texto	Exibe a situação atual conforme CAC001.	Ativo

O sistema exibe as ações Todas as pessoas jurídicas, Editar e Histórico de Alterações (AC004), além de Ver item e Baixar documento (AC006).

5. Editar pessoa jurídica

Dado que estou na tela de edição
Então o sistema exibe os campos do cadastro preenchidos e editáveis, exceto os campos da seção Informações básicas e os demais campos definidos como somente leitura. A Situação do Cadastro também é somente leitura.

O sistema exibe as ações Salvar, Visualizar pessoa jurídica, Ativar/Inativar e Histórico de Alterações (AC005), além das ações de formulário (AC006).

Ao acionar Salvar, o sistema abre a confirmação da edição. Cancelar retorna à edição; Salvar valida os dados, persiste as alterações e retorna à visualização.

6. Critérios comuns

• CA001 — Salvar cadastro de uma entidade.
• CA002 — Ativar/Inativar cadastro de uma entidade.
• CA003 — Notificar erro ao usuário devido a falha técnica.

Regras de negócio específicas

RNE001 — Unicidade

O cadastro deve ser único no sistema pelo CNPJ.

RNE002 — Disponibilidade da API de CNPJ

Se a API de CNPJ estiver inacessível, o sistema deve impedir o cadastro da pessoa jurídica.

RNE003 — Endereços

O endereço de correspondência deve ser urbano. Pode ser informado um endereço da sede diferente, urbano ou rural.

RNE004 — Itens repetíveis

O cadastro deve conter um ou mais representantes legais e pode conter outros itens repetíveis:

• um ou mais representantes legais, cada qual formado por Representante Legal, CPF e Documento de Vínculo;
• zero ou mais outros contatos, cada qual formado por Tipo de Contato, E-mail ou Número e Observação;
• zero ou mais anexos, cada qual formado por Documento e Descrição.

Regras comuns relacionadas

• RN001 — Situação do cadastro de uma entidade.
• RN002 — Ativação/desativação de cadastros de uma entidade.
• RN003 — Controle de alterações em uma entidade.
• RN005 — Comportamento quando o CEP não for validado.

Histórico das fontes

Versão	Data	Alteração
US044 v2.0	10/02/2026	Torna Nome Fantasia não obrigatório.
US044 v1.0	10/10/2025	Primeira versão da história de gerenciamento.
US045 v2.0	10/02/2026	Substitui Nome Fantasia por Razão Social na busca e nos resultados.
US045 v1.0	10/10/2025	Primeira versão da história de busca.

Histórias relacionadas

• US005 — Cadastro e edição de divisão municipal.
• US042 — Gerenciar pessoa física.
• US045 — Buscar pessoa jurídica, consolidada nesta página.