Cadastro de clientes

Como configurar os campos dos formulários de cadastro e as regras de grupo por estado, com o mapa das rotas.

Cada loja decide o que pergunta a quem se cadastra: CPF, data de nascimento, inscrição estadual, um campo próprio como "Como conheceu a loja?". Essas perguntas são os campos de perfil. Separadamente, a loja pode colocar o cliente automaticamente em um grupo de clientes (para preço, frete ou impostos diferenciados) de acordo com o estado do endereço dele: são as regras de grupo por estado.

Esta seção reúne as duas configurações do administrador. Os valores que cada cliente preenche nos campos são tratados em outro lugar; aqui você define o formulário.

Pontos-chave

Os campos servem a dois públicos: user (cliente) e vendor (seller). O mesmo nome de campo pode existir nos dois.
Campos de sistema (CPF, e-mail, telefone...) nascem com a loja: dá para mudar rótulo, posição e se são obrigatórios, mas não excluí-los. Os obrigatórios do sistema (como o primeiro nome) também não podem ser desligados.
Ao criar um campo, is_enabled ausente vira false: o campo nasce desligado e não aparece no formulário.
As regras de grupo por estado exigem o módulo state-usergroup-rules. Sem ele, a lista e as gravações respondem 403 module_disabled.
Campos: ler exige manage_profile_fields, view_users ou manage_users; gravar exige manage_profile_fields. Regras de estado: ler exige view_vendors ou manage_vendors; gravar exige manage_vendors.
Criar uma regra com auto_assign ligado já aplica o grupo aos clientes existentes daquele estado.

Como funciona

Campos de perfil

Criar o campo→Ligar (is_enabled)→Aparece no formulário→Cliente preenche→Valor guardado no perfil

Cada campo tem:

um nome técnico (field_name), único por público (profile_type);
um tipo (field_type), uma letra que define como o campo é desenhado;
uma seção (section), o bloco do formulário em que aparece;
um escopo de cadastro (registration_scope), que diz em qual fluxo de cadastro (pessoa física, jurídica, ambos) o campo é mostrado.

Alguns campos são vinculados a uma coluna (column_binding): o valor não vai para a tabela de valores personalizados e sim direto no cadastro do usuário (por exemplo, o CPF).

Regras de grupo por estado

Cliente grava um endereço→Estado do endereço→Regras do estado→Grupos atribuídos

Uma regra liga uma sigla de estado (SP) a um grupo de clientes. Quando o cliente grava um endereço naquele estado (ou quando você chama a aplicação retroativa), a plataforma o coloca no grupo. A atribuição é só de entrada: sair do estado, ou excluir a regra, não tira o cliente do grupo.

Conceitos importantes

Tipos de campo

`field_type`	Tipo	Observação
`I`	Texto de uma linha	O mais comum.
`T`	Texto de várias linhas
`C`	Caixa de seleção (sim ou não)
`S`	Lista de opções	Exige `options`.
`R`	Escolha única (botões de rádio)	Exige `options`.
`H`	Título (cabeçalho de grupo)	Não recebe valor.
`D`	Data
`P`	Telefone
`O`	País
`A`	Estado
`Y`	Cidade
`W`	Bairro
`F`	Arquivo (documento)	O cliente envia um arquivo.

Seções

`section`	Onde aparece
`C`	Contato (dados da pessoa).
`B`	Cobrança.
`S`	Entrega.
`V`	Seller (formulário de cadastro de lojista).

Escopo de cadastro

registration_scope controla em que cadastro o campo aparece: all (qualquer), pf (só pessoa física), pj (só pessoa jurídica) ou none (não aparece nos formulários de cadastro novo).

Endpoints

Método e caminho	Para que serve	Auth	Página
`GET /api/v1/admin/profile-fields`	Lista todos os campos, inclusive desligados	admin	Campos de perfil
`POST /api/v1/admin/profile-fields`	Cria um campo	admin	Campos de perfil
`PUT /api/v1/admin/profile-fields/{id}`	Altera um campo	admin	Campos de perfil
`DELETE /api/v1/admin/profile-fields/{id}`	Exclui um campo e os valores já preenchidos	admin	Campos de perfil
`GET /api/v1/admin/state-usergroup-rules`	Lista as regras de estado	admin	Regras por estado
`POST /api/v1/admin/state-usergroup-rules`	Cria ou atualiza uma regra	admin	Regras por estado
`POST /api/v1/admin/state-usergroup-rules/{id}/apply`	Aplica a regra aos clientes existentes	admin	Regras por estado
`DELETE /api/v1/admin/state-usergroup-rules/{id}`	Exclui uma regra	admin	Regras por estado

Erros comuns

Criar o campo e não ver no formulário. is_enabled não enviado vira false. Envie "is_enabled": true.
Tentar mudar o field_name ou o público depois de criado. Não são aceitos no PUT; crie outro campo.
Excluir um campo de sistema. Recebe 409 profile field is locked. Para esconder, desligue (is_enabled: false), exceto os obrigatórios.
Excluir sem pensar nos valores. A exclusão apaga também o que os clientes já preencheram nesse campo.
Enviar S ou R sem options. O campo é criado, mas aparece vazio no formulário.
Esperar que excluir a regra de estado remova os clientes do grupo. A regra só dispara atribuições; nada é retirado.
Passar um id que não é UUID. Nas regras de estado vira 500, nos campos de perfil o servidor devolve 404 ou 500 conforme o ponto da falha.

Próximos passos

Campos de perfil

Criar e manter os campos dos formulários.

Regras por estado

Grupos automáticos pelo estado do endereço.

API atual/Referência completa

Cadastro de clientes

Como configurar os campos dos formulários de cadastro e as regras de grupo por estado, com o mapa das rotas.

Esta seção reúne as duas configurações do administrador. Os valores que cada cliente preenche nos campos são tratados em outro lugar; aqui você define o formulário.

Pontos-chave

Os campos servem a dois públicos: user (cliente) e vendor (seller). O mesmo nome de campo pode existir nos dois.
Campos de sistema (CPF, e-mail, telefone...) nascem com a loja: dá para mudar rótulo, posição e se são obrigatórios, mas não excluí-los. Os obrigatórios do sistema (como o primeiro nome) também não podem ser desligados.
Ao criar um campo, is_enabled ausente vira false: o campo nasce desligado e não aparece no formulário.
As regras de grupo por estado exigem o módulo state-usergroup-rules. Sem ele, a lista e as gravações respondem 403 module_disabled.
Campos: ler exige manage_profile_fields, view_users ou manage_users; gravar exige manage_profile_fields. Regras de estado: ler exige view_vendors ou manage_vendors; gravar exige manage_vendors.
Criar uma regra com auto_assign ligado já aplica o grupo aos clientes existentes daquele estado.

Como funciona

Campos de perfil

Criar o campo→Ligar (is_enabled)→Aparece no formulário→Cliente preenche→Valor guardado no perfil

Cada campo tem:

um nome técnico (field_name), único por público (profile_type);
um tipo (field_type), uma letra que define como o campo é desenhado;
uma seção (section), o bloco do formulário em que aparece;
um escopo de cadastro (registration_scope), que diz em qual fluxo de cadastro (pessoa física, jurídica, ambos) o campo é mostrado.

Alguns campos são vinculados a uma coluna (column_binding): o valor não vai para a tabela de valores personalizados e sim direto no cadastro do usuário (por exemplo, o CPF).

`field_type`	Tipo	Observação
`I`	Texto de uma linha	O mais comum.
`T`	Texto de várias linhas
`C`	Caixa de seleção (sim ou não)
`S`	Lista de opções	Exige `options`.
`R`	Escolha única (botões de rádio)	Exige `options`.
`H`	Título (cabeçalho de grupo)	Não recebe valor.
`D`	Data
`P`	Telefone
`O`	País
`A`	Estado
`Y`	Cidade
`W`	Bairro
`F`	Arquivo (documento)	O cliente envia um arquivo.

Seções

`section`	Onde aparece
`C`	Contato (dados da pessoa).
`B`	Cobrança.
`S`	Entrega.
`V`	Seller (formulário de cadastro de lojista).

Escopo de cadastro

registration_scope controla em que cadastro o campo aparece: all (qualquer), pf (só pessoa física), pj (só pessoa jurídica) ou none (não aparece nos formulários de cadastro novo).

Endpoints

Método e caminho	Para que serve	Auth	Página
`GET /api/v1/admin/profile-fields`	Lista todos os campos, inclusive desligados	admin	Campos de perfil
`POST /api/v1/admin/profile-fields`	Cria um campo	admin	Campos de perfil
`PUT /api/v1/admin/profile-fields/{id}`	Altera um campo	admin	Campos de perfil
`DELETE /api/v1/admin/profile-fields/{id}`	Exclui um campo e os valores já preenchidos	admin	Campos de perfil
`GET /api/v1/admin/state-usergroup-rules`	Lista as regras de estado	admin	Regras por estado
`POST /api/v1/admin/state-usergroup-rules`	Cria ou atualiza uma regra	admin	Regras por estado
`POST /api/v1/admin/state-usergroup-rules/{id}/apply`	Aplica a regra aos clientes existentes	admin	Regras por estado
`DELETE /api/v1/admin/state-usergroup-rules/{id}`	Exclui uma regra	admin	Regras por estado

Erros comuns

Criar o campo e não ver no formulário. is_enabled não enviado vira false. Envie "is_enabled": true.
Tentar mudar o field_name ou o público depois de criado. Não são aceitos no PUT; crie outro campo.
Excluir um campo de sistema. Recebe 409 profile field is locked. Para esconder, desligue (is_enabled: false), exceto os obrigatórios.
Excluir sem pensar nos valores. A exclusão apaga também o que os clientes já preencheram nesse campo.
Enviar S ou R sem options. O campo é criado, mas aparece vazio no formulário.
Esperar que excluir a regra de estado remova os clientes do grupo. A regra só dispara atribuições; nada é retirado.
Passar um id que não é UUID. Nas regras de estado vira 500, nos campos de perfil o servidor devolve 404 ou 500 conforme o ponto da falha.

Próximos passos

Campos de perfil

Criar e manter os campos dos formulários.

Regras por estado

Grupos automáticos pelo estado do endereço.