VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Cadastro de clientes

Campos de perfil

Lista, cria, altera e exclui os campos personalizados dos formulários de cadastro de clientes e sellers.

Estas quatro operações montam o formulário de cadastro. Ler a lista exige manage_profile_fields, view_users ou manage_users; criar, alterar e excluir exigem manage_profile_fields.

Listar campos

Devolve todos os campos, ligados e desligados, dos dois públicos (user e vendor). Diferente da lista pública do formulário, que só mostra os ligados. Sem paginação e sem filtros: filtre no seu lado por profile_type, section e is_enabled.

GET/api/v1/admin/profile-fieldsAdmin

Lista todos os campos de perfil

Sem parâmetros.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/profile-fields" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Campos retornados
json
{
  "fields": [
    {
      "id": "44d6dba9-1e7e-4106-8124-8f3066b2cc48",
      "field_name": "cnpj",
      "field_type": "I",
      "section": "B",
      "profile_type": "user",
      "registration_scope": "pj",
      "required": false,
      "position": 1,
      "is_enabled": true,
      "label": "CNPJ",
      "label_en": "CNPJ (Business Tax ID)",
      "placeholder": "00.000.000/0000-00",
      "description": "Preencha se a compra for para empresa.",
      "default_value": "",
      "validation": "cnpj",
      "is_system": false,
      "is_mandatory": false,
      "created_at": "2026-03-06T10:07:44.638985Z",
      "updated_at": "2026-07-09T15:18:01.334464Z"
    },
    {
      "id": "7befcbf2-4785-4cb4-9398-5697a551263e",
      "field_name": "tax_regime",
      "field_type": "S",
      "section": "V",
      "profile_type": "vendor",
      "registration_scope": "all",
      "required": false,
      "position": 22,
      "is_enabled": true,
      "label": "Regime tributário",
      "label_en": "Tax Regime",
      "options": [
        { "label": "MEI", "value": "mei" },
        { "label": "Simples Nacional", "value": "simples_nacional" }
      ],
      "is_system": true,
      "is_mandatory": false,
      "column_binding": "tax_regime",
      "created_at": "2026-09-14T15:44:10.349414Z",
      "updated_at": "2026-09-14T15:44:10.349414Z"
    }
  ],
  "total": 52
}

Campos da resposta

fieldsarray
Todos os campos.
totalinteger
Quantidade de campos devolvidos.
fields[].iduuid
Id do campo.
fields[].field_namestring
Nome técnico do campo (cpf, company_name, um identificador seu...).
fields[].field_typestring
ITCSRHDPOAYWF
Tipo. Veja a tabela no índice.
fields[].sectionstring
CBSV
Seção do formulário.
fields[].profile_typestring
uservendor
Para quem é o campo: cliente ou seller.
fields[].registration_scopestring
allpfpjnone
Em qual cadastro o campo aparece.
fields[].requiredboolean
Se o preenchimento é obrigatório.
fields[].positioninteger
Ordem de exibição dentro da seção.
fields[].is_enabledboolean
Se o campo aparece no formulário.
fields[].labelstring
Rótulo em português.
fields[].label_enstring
Rótulo em inglês. Ausente se não houver.
fields[].placeholderstring
Texto de exemplo dentro do campo. Ausente se vazio.
fields[].placeholder_enstring
Texto de exemplo em inglês.
fields[].descriptionstring
Texto de ajuda sob o campo.
fields[].description_enstring
Texto de ajuda em inglês.
fields[].default_valuestring
Valor pré-preenchido.
fields[].optionsarray
Opções de S e R: lista de objetos com value e label.
fields[].validationstring
Validação do valor: cpf, cnpj, email, cep ou uma expressão regular.
fields[].is_systemboolean
Campo da plataforma: não pode ser excluído e field_name não muda.
fields[].is_mandatoryboolean
Campo de identidade sempre exibido: não pode ser desligado nem excluído.
fields[].column_bindingstring
Coluna do cadastro onde o valor é gravado (por exemplo cpf). Ausente nos campos comuns.
fields[].created_atstring
Criação, RFC 3339 em UTC.
fields[].updated_atstring
Última alteração, RFC 3339 em UTC.

Erros

StatusQuandoCorpo
401Sem token{"error":"missing authorization header"}
403Sem privilégio de leitura{"error":"insufficient privileges", ...}
500Falha interna{"error":"failed to list profile fields","detail":"..."}

Criar um campo

Cria um campo novo. Os três primeiros parâmetros são obrigatórios. Os demais têm padrão: público user, seção C, escopo all.

POST/api/v1/admin/profile-fieldsAdmin

Cria um campo de perfil

Corpo da requisição

field_namestringobrigatório
Nome técnico. Único dentro do público (profile_type). Duas criações iguais devolvem 400.
labelstringobrigatório
Rótulo em português mostrado ao usuário.
field_typestringobrigatório
ITCSRHDPOAYWF
Tipo do campo.
profile_typestringpadrão: user
uservendor
Público do campo.
sectionstringpadrão: C
CBSV
Seção do formulário.
registration_scopestringpadrão: all
allpfpjnone
Cadastro em que aparece. Maiúsculas são aceitas.
requiredbooleanpadrão: false
Obrigatório.
positionintegerpadrão: 0
Ordem na seção.
is_enabledbooleanpadrão: false
Se aparece no formulário. Ausente vira false: envie true para o campo funcionar.
label_enstring
Rótulo em inglês.
placeholderstring
Texto de exemplo.
placeholder_enstring
Texto de exemplo em inglês.
descriptionstring
Texto de ajuda.
description_enstring
Texto de ajuda em inglês.
default_valuestring
Valor pré-preenchido.
optionsarray
Para S e R: lista de objetos com value e label.
validationstring
cpf, cnpj, email, cep ou expressão regular, até 100 caracteres.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/profile-fields" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_name": "como_conheceu",
    "label": "Como conheceu a loja?",
    "label_en": "How did you find us?",
    "field_type": "S",
    "profile_type": "user",
    "section": "C",
    "registration_scope": "all",
    "position": 50,
    "is_enabled": true,
    "options": [
      { "value": "google", "label": "Google" },
      { "value": "indicacao", "label": "Indicação" }
    ]
  }'

Resposta

201Campo criado
json
{
  "id": "9c1f0b0a-6a67-4b0a-8d7a-2f6b5e0c1a11",
  "field_name": "como_conheceu",
  "field_type": "S",
  "section": "C",
  "profile_type": "user",
  "registration_scope": "all",
  "required": false,
  "position": 50,
  "is_enabled": true,
  "label": "Como conheceu a loja?",
  "label_en": "How did you find us?",
  "options": [
    { "value": "google", "label": "Google" },
    { "value": "indicacao", "label": "Indicação" }
  ],
  "is_system": false,
  "is_mandatory": false,
  "created_at": "2026-10-11T22:00:00Z",
  "updated_at": "2026-10-11T22:00:00Z"
}

Os campos são os da lista.

Erros

StatusQuandoCorpo
400Corpo inválido{"error":"invalid request body","detail":"..."}
400Falta field_name, label ou field_type{"error":"field_name, label, and field_type are required"}
400registration_scope fora de all, pf, pj, none{"error":"invalid registration_scope \"x\" (want all|pf|pj|none)"}
400Já existe campo com esse field_name no mesmo público, ou outra falha ao gravar{"error":"insert profile field: ..."}
403Sem manage_profile_fields{"error":"insufficient privileges", ...}
Crie já ligado

Se você não enviar is_enabled: true, o campo é criado desligado e não aparece em formulário algum. Quem espera o padrão "ligado" fica sem entender por que o campo sumiu.

Alterar um campo

Atualização parcial: só os campos enviados mudam. Não é possível mudar field_name, profile_type nem column_binding; para isso, crie outro campo. Nos campos de sistema, rótulo, posição, tipo e obrigatoriedade continuam editáveis.

PUT/api/v1/admin/profile-fields/{id}Admin

Altera um campo de perfil

Parâmetros de caminho

iduuidobrigatório
Id do campo.

Corpo da requisição

field_typestring
ITCSRHDPOAYWF
Novo tipo.
sectionstring
CBSV
Nova seção.
registration_scopestring
allpfpjnone
Novo escopo de cadastro.
requiredboolean
Obrigatório ou não.
positioninteger
Nova ordem.
is_enabledboolean
Liga ou desliga o campo. Recusado (409) em campo obrigatório do sistema.
labelstring
Novo rótulo.
label_enstring
Rótulo em inglês.
placeholderstring
Texto de exemplo.
placeholder_enstring
Texto de exemplo em inglês.
descriptionstring
Texto de ajuda.
description_enstring
Texto de ajuda em inglês.
default_valuestring
Valor pré-preenchido.
optionsarray
Novas opções de S e R. Substitui a lista inteira.
validationstring
Nova validação.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/profile-fields/9c1f0b0a-6a67-4b0a-8d7a-2f6b5e0c1a11" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "Como nos conheceu?", "required": true}'

Resposta

200Campo alterado
json
{
  "id": "9c1f0b0a-6a67-4b0a-8d7a-2f6b5e0c1a11",
  "field_name": "como_conheceu",
  "field_type": "S",
  "section": "C",
  "profile_type": "user",
  "registration_scope": "all",
  "required": true,
  "position": 50,
  "is_enabled": true,
  "label": "Como nos conheceu?",
  "is_system": false,
  "is_mandatory": false,
  "created_at": "2026-10-11T22:00:00Z",
  "updated_at": "2026-10-11T22:05:00Z"
}

A resposta é o campo completo (exemplo abreviado). Um corpo sem nenhum campo conhecido não altera nada e devolve o campo atual.

Erros

StatusQuandoCorpo
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
404Campo inexistente{"error":"profile field not found"}
409Desligar um campo obrigatório do sistema{"error":"profile field is locked","detail":"profile field is mandatory and cannot be disabled or deleted"}
500registration_scope inválido, id que não é UUID ou falha interna{"error":"failed to update profile field","detail":"invalid registration_scope \"zzz\" (want all|pf|pj|none)"}

Excluir um campo

Remove o campo e todos os valores que os usuários já preencheram nele. É irreversível. Campos de sistema e obrigatórios não podem ser excluídos; para escondê-los, desligue com is_enabled: false (exceto os obrigatórios).

DELETE/api/v1/admin/profile-fields/{id}Admin

Exclui um campo de perfil

Parâmetros de caminho

iduuidobrigatório
Id do campo.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/profile-fields/9c1f0b0a-6a67-4b0a-8d7a-2f6b5e0c1a11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Campo excluído
json
{ "message": "profile field deleted" }

Erros

StatusQuandoCorpo
404Campo inexistente{"error":"profile field not found"}
409Campo de sistema ou obrigatório{"error":"profile field is locked","detail":"profile field is a system field and cannot be deleted"}
500Id que não é UUID ou falha interna{"error":"failed to delete profile field","detail":"..."}
Os valores preenchidos também são apagados

Excluir um campo remove o que cada cliente respondeu nele, sem desfazer. Se só quer tirar o campo do formulário, desligue com is_enabled: false: os valores ficam guardados.

Veja também

  • Regras por estado
  • Cadastro de clientes: visão geral
Anterior
Cadastro de clientes
Próxima
Regras de grupo por estado
Nesta página
  • Listar campos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar um campo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar um campo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir um campo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também