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.
/api/v1/admin/profile-fieldsAdminLista todos os campos de perfil
Sem parâmetros.
Exemplo de requisição
Resposta
Campos da resposta
fieldsarraytotalintegerfields[].iduuidfields[].field_namestringcpf, company_name, um identificador seu...).fields[].sectionstringCBSVfields[].profile_typestringuservendorfields[].registration_scopestringallpfpjnonefields[].requiredbooleanfields[].positionintegerfields[].is_enabledbooleanfields[].labelstringfields[].label_enstringfields[].placeholderstringfields[].placeholder_enstringfields[].descriptionstringfields[].description_enstringfields[].default_valuestringfields[].optionsarrayS e R: lista de objetos com value e label.fields[].validationstringcpf, cnpj, email, cep ou uma expressão regular.fields[].is_systembooleanfield_name não muda.fields[].is_mandatorybooleanfields[].column_bindingstringcpf). Ausente nos campos comuns.fields[].created_atstringfields[].updated_atstringErros
| Status | Quando | Corpo |
|---|---|---|
| 401 | Sem token | {"error":"missing authorization header"} |
| 403 | Sem privilégio de leitura | {"error":"insufficient privileges", ...} |
| 500 | Falha 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.
/api/v1/admin/profile-fieldsAdminCria um campo de perfil
Corpo da requisição
field_namestringobrigatórioprofile_type). Duas criações iguais devolvem 400.labelstringobrigatóriofield_typestringobrigatórioITCSRHDPOAYWFprofile_typestringpadrão: useruservendorsectionstringpadrão: CCBSVregistration_scopestringpadrão: allallpfpjnonerequiredbooleanpadrão: falsepositionintegerpadrão: 0is_enabledbooleanpadrão: falsefalse: envie true para o campo funcionar.label_enstringplaceholderstringplaceholder_enstringdescriptionstringdescription_enstringdefault_valuestringoptionsarrayS e R: lista de objetos com value e label.validationstringcpf, cnpj, email, cep ou expressão regular, até 100 caracteres.Exemplo de requisição
Resposta
Os campos são os da lista.
Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo inválido | {"error":"invalid request body","detail":"..."} |
| 400 | Falta field_name, label ou field_type | {"error":"field_name, label, and field_type are required"} |
| 400 | registration_scope fora de all, pf, pj, none | {"error":"invalid registration_scope \"x\" (want all|pf|pj|none)"} |
| 400 | Já existe campo com esse field_name no mesmo público, ou outra falha ao gravar | {"error":"insert profile field: ..."} |
| 403 | Sem manage_profile_fields | {"error":"insufficient privileges", ...} |
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.
/api/v1/admin/profile-fields/{id}AdminAltera um campo de perfil
Parâmetros de caminho
iduuidobrigatórioCorpo da requisição
field_typestringITCSRHDPOAYWFsectionstringCBSVregistration_scopestringallpfpjnonerequiredbooleanpositionintegeris_enabledboolean409) em campo obrigatório do sistema.labelstringlabel_enstringplaceholderstringplaceholder_enstringdescriptionstringdescription_enstringdefault_valuestringoptionsarrayS e R. Substitui a lista inteira.validationstringExemplo de requisição
Resposta
A resposta é o campo completo (exemplo abreviado). Um corpo sem nenhum campo conhecido não altera nada e devolve o campo atual.
Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo que não é JSON | {"error":"invalid request body","detail":"..."} |
| 404 | Campo inexistente | {"error":"profile field not found"} |
| 409 | Desligar um campo obrigatório do sistema | {"error":"profile field is locked","detail":"profile field is mandatory and cannot be disabled or deleted"} |
| 500 | registration_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).
/api/v1/admin/profile-fields/{id}AdminExclui um campo de perfil
Parâmetros de caminho
iduuidobrigatórioExemplo de requisição
Resposta
Erros
| Status | Quando | Corpo |
|---|---|---|
| 404 | Campo inexistente | {"error":"profile field not found"} |
| 409 | Campo de sistema ou obrigatório | {"error":"profile field is locked","detail":"profile field is a system field and cannot be deleted"} |
| 500 | Id que não é UUID ou falha interna | {"error":"failed to delete profile field","detail":"..."} |