API atual/Referência completa/Conta do cliente

Campos do perfil

Definição dos campos extras da loja e valores preenchidos pelo cliente.

Cada loja decide que informações pede no cadastro além do básico: inscrição estadual, ramo de atividade, aceite de newsletter, anexos de documentos. Essas perguntas são os campos do perfil. Para montar o formulário, leia a definição dos campos (pública); para preencher e salvar, use os valores do cliente.

GET/api/v1/storefront/profile/fieldsPública

Lista a definição dos campos do perfil

Parâmetros de consulta

profile_typestring

uservendor

Para a vitrine do cliente use user. Sem o filtro vêm também campos do cadastro de sellers (vendor).

sectionstring

CBSV

Bloco do formulário: C contato, B cobrança/empresa, S entrega, V seller.

bash

curl "$BASE_URL/api/v1/storefront/profile/fields?profile_type=user&section=B"

200Campos

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": "Cadastro Nacional de Pessoa Juridica - preencha se a compra for para empresa.",
      "default_value": "",
      "validation": "cnpj",
      "is_system": false,
      "is_mandatory": false
    }
  ],
  "total": 1
}

Campos da resposta

fieldsarray

Só campos ativos (is_enabled), por seção e posição. Não use cache longo: a loja pode ligar ou exigir um campo a qualquer momento e a resposta não é guardada em cache.

iduuid

Id do campo. Pode ser usado como chave em PUT .../field-values.

field_namestring

Nome estável do campo (cpf, cnpj, company_name, state_registration, whatsapp...). Também serve de chave.

field_typestring

ITCSRHDPOAYWF

Tipo do controle: I texto, T área de texto, C caixa de seleção, S lista, R opção única, H título, D data, P telefone, O/A/Y/W país/estado/cidade/bairro, F arquivo.

sectionstring

CBSV

Bloco do formulário.

registration_scopestring

allpfpjnone

Para quem o campo aparece no cadastro: all, pf (só pessoa física), pj (só pessoa jurídica) ou none (só no perfil, fora do cadastro).

requiredboolean

true quando é obrigatório.

labelstring

Rótulo em português; label_en em inglês. placeholder, description (e as versões _en) completam.

validationstring

Regra de validação do valor: cpf, cnpj, email, cep, phone ou uma expressão regular. Pode faltar.

optionsarray

Para listas e opções: [{ "value", "label" }].

is_systemboolean

true em campo padrão da plataforma (nome, e-mail, CPF). Campos de sistema que gravam em colunas da conta (column_binding) atualizam o perfil.

totalinteger

Quantidade de campos.

Status	Quando	Corpo
500	Falha ao ler	`{"error":"failed to list profile fields","detail":"..."}`

GET/api/v1/storefront/profile/field-valuesCliente

Lê os valores dos campos do cliente

bash

curl "$BASE_URL/api/v1/storefront/profile/field-values" \
  -H "Authorization: Bearer $TOKEN"

200Valores

json

{
  "values": [
    { "id": "", "user_id": "264a70c1-9c69-458d-ac73-838543f87da2", "field_id": "78cb20dd-2da3-4327-8f0a-b262523b647c", "field_name": "cpf", "value": "12345678909" },
    { "id": "a75c80a2-5933-4366-80f3-1d2c0b8e6f21", "user_id": "264a70c1-9c69-458d-ac73-838543f87da2", "field_id": "e7ba7b58-88f1-4b4d-9cac-0a651aa25d1a", "field_name": "whatsapp", "value": "11999990000" }
  ],
  "total": 2
}

Campos da resposta

valuesarray

Um item por campo com valor. Os campos de sistema (nome, e-mail, CPF, telefone) vêm da própria conta, com id vazio. value é sempre texto.

totalinteger

Quantidade de valores.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
500	Falha ao ler	`{"error":"failed to get field values","detail":"..."}`

PUT/api/v1/storefront/profile/field-valuesCliente

Grava os valores dos campos do cliente

Grava vários valores de uma vez. Cada chave de values é o id ou o field_name do campo; cada valor é um texto. Campos de sistema ligados a colunas da conta (como phone) atualizam a conta. Os campos que não vierem não mudam.

Corpo da requisição

valuesobjectobrigatório

Mapa { "<id ou nome do campo>": "valor" }.

current_passwordstring

Exigido em lojas que pedem a senha para alterar dados sensíveis do perfil.

bash

curl -X PUT "$BASE_URL/api/v1/storefront/profile/field-values" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "values": {
    "whatsapp": "11999990000",
    "state_registration": "123456789"
  }
}'

200Valores gravados

json

{ "message": "field values updated" }

Status	Quando	Corpo
400	Corpo que não é JSON; campo que não existe ou não é editável pelo cliente; documento de outra conta	`{"error":"field_not_editable","fields":["nope"]}` / `{"error":"document_not_owned"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Senha de confirmação ausente ou errada, quando a loja exige	`{"error":"current_password_required"}` / `{"error":"current_password_invalid"}`
404	Usuário não encontrado	`{"error":"user not found"}`
500	Falha ao gravar	`{"error":"failed to save field values","detail":"..."}`

Veja também

Campos do perfil

Definição dos campos extras da loja e valores preenchidos pelo cliente.

GET/api/v1/storefront/profile/fieldsPública

Lista a definição dos campos do perfil

Parâmetros de consulta

profile_typestring

uservendor

Para a vitrine do cliente use user. Sem o filtro vêm também campos do cadastro de sellers (vendor).

sectionstring

CBSV

Bloco do formulário: C contato, B cobrança/empresa, S entrega, V seller.

bash

curl "$BASE_URL/api/v1/storefront/profile/fields?profile_type=user&section=B"

200Campos

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": "Cadastro Nacional de Pessoa Juridica - preencha se a compra for para empresa.",
      "default_value": "",
      "validation": "cnpj",
      "is_system": false,
      "is_mandatory": false
    }
  ],
  "total": 1
}

Campos da resposta

fieldsarray

Só campos ativos (is_enabled), por seção e posição. Não use cache longo: a loja pode ligar ou exigir um campo a qualquer momento e a resposta não é guardada em cache.

iduuid

Id do campo. Pode ser usado como chave em PUT .../field-values.

field_namestring

Nome estável do campo (cpf, cnpj, company_name, state_registration, whatsapp...). Também serve de chave.

field_typestring

ITCSRHDPOAYWF

Tipo do controle: I texto, T área de texto, C caixa de seleção, S lista, R opção única, H título, D data, P telefone, O/A/Y/W país/estado/cidade/bairro, F arquivo.

sectionstring

CBSV

Bloco do formulário.

registration_scopestring

allpfpjnone

Para quem o campo aparece no cadastro: all, pf (só pessoa física), pj (só pessoa jurídica) ou none (só no perfil, fora do cadastro).

requiredboolean

true quando é obrigatório.

labelstring

Rótulo em português; label_en em inglês. placeholder, description (e as versões _en) completam.

validationstring

Regra de validação do valor: cpf, cnpj, email, cep, phone ou uma expressão regular. Pode faltar.

optionsarray

Para listas e opções: [{ "value", "label" }].

is_systemboolean

true em campo padrão da plataforma (nome, e-mail, CPF). Campos de sistema que gravam em colunas da conta (column_binding) atualizam o perfil.

totalinteger

Quantidade de campos.

Status	Quando	Corpo
500	Falha ao ler	`{"error":"failed to list profile fields","detail":"..."}`

GET/api/v1/storefront/profile/field-valuesCliente

Lê os valores dos campos do cliente

bash

curl "$BASE_URL/api/v1/storefront/profile/field-values" \
  -H "Authorization: Bearer $TOKEN"

200Valores

json

{
  "values": [
    { "id": "", "user_id": "264a70c1-9c69-458d-ac73-838543f87da2", "field_id": "78cb20dd-2da3-4327-8f0a-b262523b647c", "field_name": "cpf", "value": "12345678909" },
    { "id": "a75c80a2-5933-4366-80f3-1d2c0b8e6f21", "user_id": "264a70c1-9c69-458d-ac73-838543f87da2", "field_id": "e7ba7b58-88f1-4b4d-9cac-0a651aa25d1a", "field_name": "whatsapp", "value": "11999990000" }
  ],
  "total": 2
}

Campos da resposta

valuesarray

Um item por campo com valor. Os campos de sistema (nome, e-mail, CPF, telefone) vêm da própria conta, com id vazio. value é sempre texto.

totalinteger

Quantidade de valores.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
500	Falha ao ler	`{"error":"failed to get field values","detail":"..."}`

PUT/api/v1/storefront/profile/field-valuesCliente

Grava os valores dos campos do cliente

Corpo da requisição

valuesobjectobrigatório

Mapa { "<id ou nome do campo>": "valor" }.

current_passwordstring

Exigido em lojas que pedem a senha para alterar dados sensíveis do perfil.

bash

curl -X PUT "$BASE_URL/api/v1/storefront/profile/field-values" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "values": {
    "whatsapp": "11999990000",
    "state_registration": "123456789"
  }
}'

200Valores gravados

json

{ "message": "field values updated" }

Status	Quando	Corpo
400	Corpo que não é JSON; campo que não existe ou não é editável pelo cliente; documento de outra conta	`{"error":"field_not_editable","fields":["nope"]}` / `{"error":"document_not_owned"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Senha de confirmação ausente ou errada, quando a loja exige	`{"error":"current_password_required"}` / `{"error":"current_password_invalid"}`
404	Usuário não encontrado	`{"error":"user not found"}`
500	Falha ao gravar	`{"error":"failed to save field values","detail":"..."}`