PF e PJ

Entenda o tipo de pessoa do cliente e troque entre pessoa física e jurídica com prévia, histórico e desfazer.

Todo cliente é pessoa física (PF, F) ou pessoa jurídica (PJ, J). O tipo decide quais campos fazem sentido (CPF ou CNPJ, nome ou razão social) e o que o formulário da loja pede. Esta página explica como o tipo é definido e como trocá-lo com segurança, porque uma troca pode apagar os dados do tipo anterior.

A troca em si é feita com PUT /api/v1/admin/users/{id} e o campo person_type (Alterar cliente). As três rotas abaixo existem para tornar a troca segura: ver o que seria apagado antes, listar o que já foi trocado e desfazer.

Como o tipo é definido

Declarado. Alguém (você, pela API, ou o cliente, no cadastro) informou F ou J. Em GET, person_type_declared vem true.
Deduzido. Ninguém declarou. O tipo é calculado pelo documento: com CNPJ é J, sem CNPJ é F. person_type_declared vem false. A plataforma não grava um tipo que ninguém escolheu.
Na criação, mandar cnpj sem person_type cria uma PJ.

A forma canônica de PJ

Campo	Em uma PJ
`cnpj`	O documento da empresa (14 caracteres, sem máscara).
`legal_name`	Razão social. É o nome oficial.
`trade_name`	Nome fantasia (opcional). É o que `display_name` mostra, quando existe.
`first_name`	Espelho da razão social inteira. Você não precisa preencher.
`last_name`	Sempre vazio.
`state_reg`	Inscrição estadual (opcional).
`responsible_name`, `responsible_cpf`	Quem opera a conta, em campos de perfil.

O espelho garante que as notas fiscais, os e-mails e as integrações que leem first_name continuem vendo o nome da empresa. Ao tornar PJ um cliente que era PF, o nome da pessoa que estava em first_name e last_name vai para responsible_name antes de o espelho ser aplicado, para não se perder.

O que a troca apaga

A loja decide, por configuração, se a troca limpa os dados do tipo anterior. Por padrão a limpeza fica desligada: o tipo muda e os dados antigos ficam guardados, só fora do formulário. Quando ligada, a troca apaga:

as colunas do tipo anterior (cnpj, legal_name, trade_name, state_reg ao sair de PJ; cpf ao sair de PF);
os campos de perfil que pertencem só ao tipo anterior.

Endereços e dados comuns (nome da pessoa, e-mail, telefone, senha) e os dados do responsável (responsible_name, responsible_cpf) nunca são apagados. Tudo o que foi apagado fica registrado para poder ser restaurado.

POST/api/v1/admin/users/{id}/person-type/previewAdmin

Preview a person type change

Ensaio da troca: devolve, sem escrever nada, a lista do que seria apagado e se a limpeza está ligada na loja. Mostre essa lista a quem vai confirmar. Exige manage_users.

Path parameters

iduuidobrigatório

Id do usuário.

Corpo da requisição

person_typestringobrigatório

FPFJPJ

Tipo de destino.

Exemplo de requisição (prévia)

bash

curl -X POST "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f/person-type/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"person_type": "PF"}'

Resposta (prévia)

200O que seria apagado

json

{
  "cleanup_enabled": false,
  "cleared": [
    { "kind": "column", "name": "cnpj", "label": "CNPJ", "value": "11222333000181" },
    { "kind": "column", "name": "legal_name", "label": "Razão Social", "value": "Padaria Pão Doce Ltda" },
    { "kind": "column", "name": "trade_name", "label": "Nome Fantasia", "value": "Pão Doce Centro" },
    { "kind": "profile_field", "name": "company_name", "field_id": "1bf6d0a9-56a9-495d-a51a-160c39bcd2f9", "label": "Razão Social", "value": "Padaria Pão Doce Ltda" }
  ]
}

Campos da resposta

cleanup_enabledboolean

Se false, a troca não apaga nada: cleared mostra o que seria apagado caso a limpeza estivesse ligada. Se true, a troca apaga exatamente esta lista.

clearedarray

Valores afetados.

cleared[].kindstring

columnprofile_field

column é um campo do cadastro; profile_field é um campo de perfil.

cleared[].namestring

Nome do campo.

cleared[].field_iduuid

Id do campo de perfil (só em profile_field).

cleared[].labelstring

Rótulo para mostrar a uma pessoa.

cleared[].valuestring

Valor atual.

Aplicar a troca

Depois da prévia, aplique com PUT /api/v1/admin/users/{id} (Alterar cliente):

bash

curl -X PUT "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"person_type": "PF"}'

Se person_type já é o tipo declarado do usuário, nada muda e nada é registrado. Ao tornar um cliente PJ, informe também cnpj e legal_name; a loja pode exigir esses documentos.

GET/api/v1/admin/users/{id}/person-type/changesAdmin

Histórico de mudanças do tipo de pessoa

Lista as trocas de tipo já feitas no usuário, da mais recente para a mais antiga, com o que cada uma apagou. Exige view_users ou manage_users.

Path parameters

iduuidobrigatório

Id do usuário.

Query parameters

limitintegerpadrão: 10

Quantidade máxima de registros.

200Histórico

json

{
  "changes": [
    {
      "id": "372e2adb-05c6-4b7c-876b-7977a3832bf7",
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "from_type": "J",
      "to_type": "F",
      "cleared": [],
      "changed_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "created_at": "2026-10-11T20:56:27.268069Z"
    }
  ]
}

Campos da resposta

changes[].iduuid

Id da troca. É o que o desfazer recebe.

changes[].from_typestring

FJ

Tipo anterior. Ausente se o tipo nunca tinha sido declarado.

changes[].to_typestring

FJ

Tipo novo.

changes[].clearedarray

Valores apagados na troca (mesmo formato de cleared na prévia). Vazio quando a limpeza estava desligada.

changes[].changed_byuuid

Quem fez a troca. Ausente quando foi o próprio cliente ou um sistema.

changes[].undone_atstring

Quando foi desfeita (RFC 3339). Ausente se ainda vale.

changes[].created_atstring

Quando a troca aconteceu.

POST/api/v1/admin/users/{id}/person-type/changes/{changeId}/undoAdmin

Undo a person type change

Devolve o tipo anterior e restaura os valores que a troca apagou. Só uma vez por troca: o registro fica marcado como desfeito. Exige manage_users. Não há corpo.

Path parameters

iduuidobrigatório

Id do usuário.

changeIduuidobrigatório

Id da troca, vindo de changes[].id.

200Troca desfeita

json

{
  "ok": true,
  "user": { "id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f", "person_type": "J", "cnpj": "11222333000181" }
}

Erros

Status	Quando	Corpo
400	`person_type` desconhecido	`{"error":"invalid person_type: Q (want F/PF or J/PJ)"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_users` (prévia, desfazer) ou `view_users`/`manage_users` (histórico)	`{"error":"insufficient privileges","required":"manage_users"}`
404	Usuário ou troca inexistente	`{"error":"user not found"}` ou `{"error":"change not found"}`
409	A troca já foi desfeita	`{"error":"this change was already undone"}`

Veja também

API atual/Guia rápido/Clientes

PF e PJ

Entenda o tipo de pessoa do cliente e troque entre pessoa física e jurídica com prévia, histórico e desfazer.

Como o tipo é definido

Declarado. Alguém (você, pela API, ou o cliente, no cadastro) informou F ou J. Em GET, person_type_declared vem true.
Deduzido. Ninguém declarou. O tipo é calculado pelo documento: com CNPJ é J, sem CNPJ é F. person_type_declared vem false. A plataforma não grava um tipo que ninguém escolheu.
Na criação, mandar cnpj sem person_type cria uma PJ.

A forma canônica de PJ

Campo	Em uma PJ
`cnpj`	O documento da empresa (14 caracteres, sem máscara).
`legal_name`	Razão social. É o nome oficial.
`trade_name`	Nome fantasia (opcional). É o que `display_name` mostra, quando existe.
`first_name`	Espelho da razão social inteira. Você não precisa preencher.
`last_name`	Sempre vazio.
`state_reg`	Inscrição estadual (opcional).
`responsible_name`, `responsible_cpf`	Quem opera a conta, em campos de perfil.

O que a troca apaga

as colunas do tipo anterior (cnpj, legal_name, trade_name, state_reg ao sair de PJ; cpf ao sair de PF);
os campos de perfil que pertencem só ao tipo anterior.

POST/api/v1/admin/users/{id}/person-type/previewAdmin

Preview a person type change

Ensaio da troca: devolve, sem escrever nada, a lista do que seria apagado e se a limpeza está ligada na loja. Mostre essa lista a quem vai confirmar. Exige manage_users.

Path parameters

iduuidobrigatório

Id do usuário.

Corpo da requisição

person_typestringobrigatório

FPFJPJ

Tipo de destino.

Exemplo de requisição (prévia)

bash

curl -X POST "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f/person-type/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"person_type": "PF"}'

Resposta (prévia)

200O que seria apagado

json

{
  "cleanup_enabled": false,
  "cleared": [
    { "kind": "column", "name": "cnpj", "label": "CNPJ", "value": "11222333000181" },
    { "kind": "column", "name": "legal_name", "label": "Razão Social", "value": "Padaria Pão Doce Ltda" },
    { "kind": "column", "name": "trade_name", "label": "Nome Fantasia", "value": "Pão Doce Centro" },
    { "kind": "profile_field", "name": "company_name", "field_id": "1bf6d0a9-56a9-495d-a51a-160c39bcd2f9", "label": "Razão Social", "value": "Padaria Pão Doce Ltda" }
  ]
}

Campos da resposta

cleanup_enabledboolean

Se false, a troca não apaga nada: cleared mostra o que seria apagado caso a limpeza estivesse ligada. Se true, a troca apaga exatamente esta lista.

clearedarray

Valores afetados.

cleared[].kindstring

columnprofile_field

column é um campo do cadastro; profile_field é um campo de perfil.

cleared[].namestring

Nome do campo.

cleared[].field_iduuid

Id do campo de perfil (só em profile_field).

cleared[].labelstring

Rótulo para mostrar a uma pessoa.

cleared[].valuestring

Valor atual.

Aplicar a troca

Depois da prévia, aplique com PUT /api/v1/admin/users/{id} (Alterar cliente):

bash

curl -X PUT "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"person_type": "PF"}'

Se person_type já é o tipo declarado do usuário, nada muda e nada é registrado. Ao tornar um cliente PJ, informe também cnpj e legal_name; a loja pode exigir esses documentos.

GET/api/v1/admin/users/{id}/person-type/changesAdmin

Histórico de mudanças do tipo de pessoa

Lista as trocas de tipo já feitas no usuário, da mais recente para a mais antiga, com o que cada uma apagou. Exige view_users ou manage_users.

Path parameters

iduuidobrigatório

Id do usuário.

Query parameters

limitintegerpadrão: 10

Quantidade máxima de registros.

200Histórico

json

{
  "changes": [
    {
      "id": "372e2adb-05c6-4b7c-876b-7977a3832bf7",
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "from_type": "J",
      "to_type": "F",
      "cleared": [],
      "changed_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "created_at": "2026-10-11T20:56:27.268069Z"
    }
  ]
}

Campos da resposta

changes[].iduuid

Id da troca. É o que o desfazer recebe.

changes[].from_typestring

FJ

Tipo anterior. Ausente se o tipo nunca tinha sido declarado.

changes[].to_typestring

FJ

Tipo novo.

changes[].clearedarray

Valores apagados na troca (mesmo formato de cleared na prévia). Vazio quando a limpeza estava desligada.

changes[].changed_byuuid

Quem fez a troca. Ausente quando foi o próprio cliente ou um sistema.

changes[].undone_atstring

Quando foi desfeita (RFC 3339). Ausente se ainda vale.

changes[].created_atstring

Quando a troca aconteceu.

POST/api/v1/admin/users/{id}/person-type/changes/{changeId}/undoAdmin

Undo a person type change

Devolve o tipo anterior e restaura os valores que a troca apagou. Só uma vez por troca: o registro fica marcado como desfeito. Exige manage_users. Não há corpo.

Path parameters

iduuidobrigatório

Id do usuário.

changeIduuidobrigatório

Id da troca, vindo de changes[].id.

200Troca desfeita

json

{
  "ok": true,
  "user": { "id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f", "person_type": "J", "cnpj": "11222333000181" }
}

Erros

Status	Quando	Corpo
400	`person_type` desconhecido	`{"error":"invalid person_type: Q (want F/PF or J/PJ)"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_users` (prévia, desfazer) ou `view_users`/`manage_users` (histórico)	`{"error":"insufficient privileges","required":"manage_users"}`
404	Usuário ou troca inexistente	`{"error":"user not found"}` ou `{"error":"change not found"}`
409	A troca já foi desfeita	`{"error":"this change was already undone"}`