Alterar cliente
Corrige dados de um usuário, muda o status e aprova ou recusa cadastros pendentes.
Use estas operações para manter o cadastro em dia: um ERP que corrige o telefone, um atendimento que troca o e-mail, uma rotina que desativa quem saiu da carteira, ou a fila de aprovação de novos clientes B2B. Só os campos enviados mudam; o resto fica como está.
Mudar o status ou o user_type de um usuário derruba as sessões abertas dele: o token em uso deixa de valer e a pessoa precisa entrar de novo. Mudar o e-mail é possível, mas o novo e-mail precisa estar livre.
Para trocar a senha, não use estas rotas: veja Acesso e senha. Para trocar entre PF e PJ com prévia e desfazer, veja PF e PJ.
/api/v1/admin/users/{id}AdminAtualiza um usuário
Exige manage_users. Devolve o usuário completo, com os campos de Consultar cliente.
Regras que surpreendem:
- Um administrador não altera o próprio
user_typenem o própriostatus(400), para não se trancar fora. Os demais campos são livres. is_root(dono da loja) só pode ser alterado por quem já é dono; o último dono não pode ser rebaixado.- Texto vazio (
"") apaga o campo nos documentos (cpf,cnpj,state_reg) e nos nomes de empresa (legal_name,trade_name); omitir o campo não mexe. - Campos desconhecidos são ignorados e a resposta é 200; confira o objeto devolvido para ter certeza do que mudou.
passwordé recusado com 400, em vez de ser ignorado.- Se
person_typevier no corpo, a troca segue as regras de PF e PJ, incluindo o registro no histórico.
Path parameters
iduuidobrigatórioCorpo da requisição
first_namestringlast_namestringemailstringemail already in use.phonestringuser_typestringcustomervendoradminroot_admininvalid user_type.statusstringADPinvalid status.cpfstring"" apaga.cnpjstring"" apaga.state_regstringperson_typestringFPFJPJlegal_namestringfirst_name.trade_namestringresponsible_namestringresponsible_cpfstringlanguagestringpt-BRenesinvalid language.currencystringBRL).timezonestringAmerica/Sao_Paulo).whatsapp_phonestringwhatsapp_opt_inbooleanmarketing_opt_inbooleantrue grava a data de agora, false apaga.notify_on_ordersbooleanis_rootbooleanExemplo de requisição
curl -X PUT "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"trade_name": "Pão Doce Centro", "phone": "11 97777-6666"}'Resposta
{
"id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
"email": "contato@paodoce.example.com",
"user_type": "customer",
"status": "A",
"first_name": "Padaria Pão Doce Ltda",
"phone": "+5511977776666",
"legal_name": "Padaria Pão Doce Ltda",
"trade_name": "Pão Doce Centro",
"person_type": "J",
"display_name": "Pão Doce Centro",
"updated_at": "2026-10-11T20:56:18.510829Z"
}/api/v1/admin/users/{id}/statusAdminAltera o status de um usuário
Muda só o status, com um corpo mínimo. Exige manage_users. Quando o status realmente muda, as sessões do usuário são encerradas. Ao desativar (D), os números de WhatsApp ligados à conta também são soltos (WhatsApp).
Path parameters
iduuidobrigatórioCorpo da requisição
statusstringobrigatórioADPactivedisabledpending{ "message": "user status updated", "status": "disabled" }O campo status da resposta repete o que você enviou (letra ou palavra), não a letra gravada.
/api/v1/admin/users/{id}/approveAdminAprova um usuário pendente
Aprova um cadastro pendente: o status vira A. Serve à fila de lojas que revisam novos clientes (por exemplo, B2B por CNPJ) antes de liberar o acesso. Se a loja configurou um grupo para clientes aprovados, o usuário entra nele. É idempotente: aprovar quem já é ativo devolve o usuário, sem novo evento. Exige manage_users. Não há corpo.
A rota não confere se o usuário estava pendente: aprovar uma conta desativada a reativa.
Path parameters
iduuidobrigatório{
"id": "ed7a3fbc-86f7-4b56-84de-67c583efbc3f",
"email": "carlos.lima@example.com",
"user_type": "customer",
"status": "A",
"first_name": "Carlos",
"last_name": "Lima",
"person_type": "F"
}/api/v1/admin/users/{id}/rejectAdminRejeita um usuário pendente
Recusa um cadastro pendente: o status vira D. O motivo é opcional e é enviado no evento de recusa, que a loja pode usar para avisar o cliente. Exige manage_users.
Path parameters
iduuidobrigatórioCorpo da requisição
reasonstring{
"id": "ed7a3fbc-86f7-4b56-84de-67c583efbc3f",
"email": "carlos.lima@example.com",
"user_type": "customer",
"status": "D",
"first_name": "Carlos",
"last_name": "Lima"
}Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo que não é JSON | {"error":"invalid request body","detail":"..."} |
| 400 | status inválido | {"error":"invalid status: zzz (must be active, disabled, or pending)"} |
| 400 | user_type inválido | {"error":"invalid user_type: god"} |
| 400 | person_type inválido | {"error":"invalid person_type: X (want F/PF or J/PJ)"} |
| 400 | CPF ou CNPJ com dígito verificador errado | {"error":"invalid CPF"} ou {"error":"invalid CNPJ"} |
| 400 | E-mail já usado por outro usuário | {"error":"email already in use"} |
| 400 | Administrador mexendo no próprio papel ou status | {"error":"cannot change your own user type"} ou {"error":"cannot change your own status"} |
| 400 | Rebaixar o último dono | {"error":"cannot demote the last ..."} |
| 400 | password no corpo | {"error":"password_not_updatable","detail":"este endpoint não troca senha: ... Use POST /api/v1/admin/users/{id}/set-password."} |
| 400 | Usuário inexistente em PATCH .../status, approve e reject | {"error":"user ... not found"} |
| 401 | Sem credenciais ou token expirado | {"error":"invalid or expired token"} |
| 403 | Falta manage_users, ou is_root enviado por quem não é dono | {"error":"insufficient privileges","required":"manage_users"} ou {"error":"only root admins can modify the root flag"} |
| 404 | PUT /api/v1/admin/users/{id} com id inexistente | {"error":"user not found"} |
Mensagens da API em inglês voltam como estão.