Campos de perfil
Leia e grave os campos de perfil definidos pela loja para cada cliente.
Além dos dados fixos da conta (e-mail, nome, telefone, documento), cada loja define campos de perfil: informações extras que ela quer saber do cliente, como "ramo de atividade", "nome do responsável" ou "inscrição municipal". A loja cria esses campos no painel e escolhe quais são obrigatórios no cadastro e se valem para PF, para PJ ou para os dois.
Cada campo tem um field_id (UUID) e um field_name (o nome técnico). Estas rotas leem e gravam o valor de cada campo para um cliente específico. As definições dos campos (criar, renomear, tornar obrigatório) ficam em outras rotas da API de administração e não fazem parte desta seção.
Alguns campos são nativos e estão ligados a uma coluna da conta: first_name, last_name, email, phone e cpf. Gravar um deles por aqui altera a conta de verdade, com a mesma validação das rotas de Alterar cliente (formato, dígitos verificadores e unicidade). Os demais campos guardam o valor à parte.
/api/v1/admin/users/{id}/field-valuesAdminConsulta os valores dos campos de perfil de um usuário
Exige view_users, manage_users ou manage_profile_fields.
Path parameters
iduuidobrigatório{
"total": 3,
"values": [
{ "id": "b3ffbf33-336d-4af2-9d9b-f61702ff143b", "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f", "field_id": "1a471dda-49aa-489a-a6a1-c4db20930489", "field_name": "trade_name", "value": "Pão Doce Centro" },
{ "id": "959300b8-34eb-420e-b7a4-572a569f8036", "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f", "field_id": "19d6bcb8-9d1f-4750-aa10-1e2feba51366", "field_name": "responsible_name", "value": "João Pereira" },
{ "id": "", "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f", "field_id": "b7d6a164-ef12-4f83-8011-c9cb27e1e6be", "field_name": "email", "value": "contato@paodoce.example.com" }
]
}Campos da resposta
valuesarraynull quando o usuário não existe (esta rota não devolve 404).values[].iduuidvalues[].field_iduuidvalues[].field_namestringvalues[].valuestringtotalinteger/api/v1/admin/users/{id}/field-valuesAdminGrava os valores dos campos de perfil de um usuário
Grava os valores enviados e não mexe nos demais campos. Exige manage_profile_fields. A chave de cada valor é o field_id ou o field_name.
Path parameters
iduuidobrigatórioCorpo da requisição
valuesobjectobrigatóriofield_id (UUID) ou o field_name; o valor é sempre texto. Chave que não corresponde a nenhum campo é ignorada em silêncio.Exemplo de requisição (gravar)
curl -X PUT "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f/field-values" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"values": {"responsible_name": "João P. Pereira"}}'Resposta (gravar)
{ "message": "field values updated" }Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | values ausente ou corpo inválido, ou valor recusado por um campo nativo | {"error":"invalid request body","detail":"..."} ou {"error":"failed to save field values","detail":"invalid CPF"} |
| 400 | Valor de campo nativo já em uso por outra conta | {"error":"failed to save field values","detail":"email already in use"} ou "CPF already registered by another user" |
| 401 | Sem credenciais ou token expirado | {"error":"invalid or expired token"} |
| 403 | Falta o privilégio manage_profile_fields | {"error":"insufficient privileges","required":"manage_profile_fields"} |
| 404 | Usuário inexistente na gravação | {"error":"user not found"} |