Skip to content

Campos adicionais

📖 Visão Geral

O recurso de campos adicionais aumenta a flexibilidade das entidades da plataforma Uappi. Através dele, é possível criar campos extras para registrar novas informações sem a necessidade de desenvolvimento no backend.

🔑 Nota: Ao criar um campo adicional, um código único é gerado com base no nome definido. Este código é o identificador usado para ler e atualizar a informação nos demais recursos da API.

🛠️ Tipos de Campos Adicionais

O tipo define a natureza da informação, como ela será recebida, validada e como poderá ser filtrada.

📝 Tipo text

Permite armazenar qualquer valor textual.

Exemplo: 

1"nome-do-responsavel": "Fulano de Tal"

🔢 Tipo numeric

Permite armazenar valores numéricos, suportando inteiros ou decimais.

Exemplo: 

1"quantidade-de-filhos": 2,
2"peso-estimado": 75.5

✅ Tipo boolean

Permite armazenar um valor lógico: true (verdadeiro) ou false (falso).

Exemplo: 

1"possui-intolerancia-a-lactose": false

🔘 Tipo enum

Permite escolher uma única opção entre uma lista pré-definida. Exemplo: Se as opções forem "Cachorro" ou "Gato":

Exemplo: 

1"voce-prefere": "Cachorro"

🗂️ Tipo array

Permite selecionar múltiplas opções entre as disponíveis na lista pré-definida. Exemplo: Se as opções de interesses forem "Moda", "Tecnologia", "Casa e Decoração" e "Esportes":

Exemplo: 

1"interesses-de-compra": ["Moda", "Tecnologia"]

📅 Tipo date

Armazena datas no padrão ISO (Ano-Mês-Dia). Formatado como: {AAAA}-{MM}-{DD}.

Exemplo: 

1"data-de-nascimento-da-mae": "1952-12-03"

🕒 Tipo datetime

Armazena data e hora exata. Formatado como: {AAAA}-{MM}-{DD} {HH}:{MM}:{SS}.

Exemplo: 

1"ultimo-acesso-confirmado": "1952-12-03 13:01:22"

📤 Tipo upload

Permite o envio de arquivos convertidos para uma string em Base64.

⚠️ Limites e Regras:

  • Tamanho Máximo: 2048 KB (2 MB).
  • Formatos Aceitos: image/jpeg, image/png, image/webp, image/heic, image/heif, application/pdf.

    • Exemplo: 

    1"foto-do-rg": "iVBORw0KGgoAAAANSUhEUgAAA..."

    🔗 Tipo link

    Armazena URLs válidas, sendo obrigatório o uso do protocolo (http/https).

    Exemplo: 

    1"link-do-github": "https://github.com/fulano-de-tal"

    📧 Tipo email

    Permite armazenar um endereço de e-mail válido.

    Exemplo: 

    1"email-secundario": "fulano@exemplo.com.br"

    🆔 Tipo cpf

    Permite armazenar o Cadastro de Pessoa Física (CPF), validando o formato e os dígitos verificadores. Também é possível informar esse valor sem a máscara de CPF.

    Exemplo: 

    1"cpf-do-conjuge": "123.456.789-00"

    🏢 Tipo cnpj

    Permite armazenar o Cadastro Nacional da Pessoa Jurídica (CNPJ), validando o formato e os dígitos verificadores. Também é possível informar esse valor sem a máscara de CNPJ.

    Exemplo: 

    1"cnpj-do-fornecedor": "12.345.678/0001-99"

    📞 Tipo phone

    Permite armazenar números de telefone. O valor deve obrigatoriamente seguir o formato internacional (E.164), iniciando com o símbolo + seguido de 7 a 15 dígitos.

    Exemplo: 

    1"telefone-de-recado": "+5511999998888"

    👥 Entidades Envolvidas

    Atualmente, o suporte para campos adicionais está disponível para a seguinte entidade:

  • Cliente (Customer)

    • Notas e Considerações

    Filtrando campos adicionais em listagens

    Em diversas rotas da API será possível filtrar os campos adicionais preenchidos nas entidades (exemplo: listagem de clientes). No entanto, para que essa filtagem funcione de fato será necessário enviar a query de uma forma um pouco diferente.

    Para filtrar informações com operadores como: "=", ">", "<", "!=", "like", etc é necessário enviar o conteúdo do campo value no formato: "{código do campo adicional}:{valor desejado para filtragem}".

    Exemplo: 

    1{
    2  "field": "{nome da condition pode variar entre as listagem}",
    3  "value": "nome-do-responsavel:Fulano de Tal",
    4  "operator": "like"
    5}

    Já no caso de filtrar informações com operadores como: "in","notIn","beteween", é necessário enviar o conteúdo do campo value como um array onde o primeiro item é o código do campo e os demais itens são os valores desejados para filtragens.

    Exemplo: 

    1{
    2  "field": "{nome da condition pode variar entre as listagem}",
    3  "value": ["interesses-de-compra", "Moda", "Esportes"],
    4  "operator": "in"
    5}

    ⚠️ Observações:

  • Como os campos adicionais do tipo upload armazenam os arquivos em string Base64, não será possível filtrar por eles.
  • Para filtragem de campos do tipo array é recomendando o uso do operador like pois o valor desse tipo de campo é armazenado como uma string JSON.

Listagem de campos adicionais

GET /common/additional-fields/{commonAdditionalFieldEntity}

Listagem de campos adicionais

Descrição

Endpoint responsável por listar todos os campos adicionais criados para uma entidade específica (atualmente apenas customer é suportado).

Parâmetros

Parâmetros de Rota

ParâmetroTipoObrigatórioDescrição
commonAdditionalFieldEntitystringSimIdentificador da entidade alvo (Ex: customer)

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Campos de Condição Disponíveis

CampoTipoDescrição
idintegerID do campo adicional.
namestringNome do campo adicional.
codestringCódigo do campo adicional.
typestringTipo do campo adicional.
requiredbooleanFiltro por obrigatoriedade.
createdAtdatetimeData de criação.
updatedAtdatetimeData de atualização.

Campos de Ordenação Disponíveis

CampoDescrição
idID do campo adicional.
createdAtData de criação.
updatedAtData de atualização.

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/common/additional-fields/customer \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6	"fields": [],
7	"order": [
8    { "field": "id", "order": "ASC" }
9  ],
10	"condition": {
11		"type": "AND",
12		"conditions": []
13	}
14}'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "name": "Interesses de Compra",
8        "code": "interesses-de-compra",
9        "type": "array",
10        "required": false,
11        "options": [
12          "Moda",
13          "Tecnologia",
14          "Casa e Decoração",
15          "Esportes"
16        ],
17        "createdAt": "2026-03-19 14:00:00",
18        "updatedAt": "2026-03-19 14:00:00"
19      },
20      {
21        "id": 2,
22        "name": "Data de Nascimento da Mãe",
23        "code": "data-de-nascimento-da-mae",
24        "type": "date",
25        "required": true,
26        "options": null,
27        "createdAt": "2026-03-19 14:05:00",
28        "updatedAt": "2026-03-19 14:05:00"
29      }
30    ],
31    "pagination": {
32      "limit": 10,
33      "offset": 0,
34      "pages": 1,
35      "registers": 2
36    }
37  }
38}

⚠️ Possíveis erros

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código internoCódigo HttpDescrição
UAPPI_API_COMMON_ADDITIONAL_FIELD_INVALID_ENTITY400A entidade informada na rota não é suportada pela plataforma.

Detalhe do campo adicional

GET /common/additional-fields/{commonAdditionalFieldEntity}/{commonAdditionalFieldId}

Detalhe do campo adicional

Descrição

Endpoint responsável por retornar os detalhes de um campo adicional específico através do seu ID.

Parâmetros

Parâmetros de Rota

ParâmetroTipoObrigatórioDescrição
commonAdditionalFieldEntitystringSimIdentificador da entidade alvo (Ex: customer)
commonAdditionalFieldIdintegerSimID do campo adicional que deseja detalhar.

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/common/additional-fields/customer/1 \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "name": "Interesses de Compra",
6    "code": "interesses-de-compra",
7    "type": "array",
8    "required": false,
9    "options": [
10      "Moda",
11      "Tecnologia",
12      "Casa e Decoração",
13      "Esportes"
14    ],
15    "createdAt": "2026-03-19 14:00:00",
16    "updatedAt": "2026-03-19 14:00:00"
17  }
18}

⚠️ Possíveis erros

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código internoCódigo HttpDescrição
UAPPI_CORE_COMMON_ADDITIONAL_FIELD_NOT_FOUND404O ID do campo adicional informado não foi encontrado para esta entidade.
UAPPI_API_COMMON_ADDITIONAL_FIELD_INVALID_ENTITY400A entidade informada na rota não é suportada pela plataforma.

Cadastro de campo adicional

POST /common/additional-fields/{commonAdditionalFieldEntity}

Cadastro de campo adicional

Descrição

Endpoint responsável por criar um novo campo adicional para uma entidade específica (atualmente apenas customer é suportado).

Ao cadastrar um campo, a plataforma gera automaticamente um código único (code) baseado no nome informado, que será utilizado para identificar este campo em outras operações da API.

Parâmetros

Parâmetros de Rota

ParâmetroTipoObrigatórioDescrição
commonAdditionalFieldEntitystringSimIdentificador da entidade alvo (Ex: customer)

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Parâmetros de corpo

CampoTipoObrigatórioDescrição
namestringSimNome amigável do campo (ex: "Interesses de Compra").
typestringSimTipo do dado. Veja os tipos suportados aqui.
requiredbooleanSimDefine se o preenchimento deste campo será obrigatório nas entidades.
optionsarray ou nullNãoObrigatório apenas para os tipos enum e array. Determina as opções disponíveis no preenchimento do campo nas entidades.

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/common/additional-fields/customer \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6	"name": "Interesses de Compra",
7	"type": "array",
8	"required": false,
9	"options": [
10		"Moda",
11		"Tecnologia",
12		"Casa e Decoração",
13		"Esportes"
14	]
15}'

✅ Resposta de Sucesso (201 Created)

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "name": "Interesses de Compra",
6    "code": "interesses-de-compra",
7    "type": "array",
8    "required": false,
9    "options": [
10      "Moda",
11      "Tecnologia",
12      "Casa e Decoração",
13      "Esportes"
14    ],
15    "createdAt": "2026-03-19 14:00:00",
16    "updatedAt": "2026-03-19 14:00:00"
17  }
18}

⚠️ Respostas de Erro

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código internoCódigo HttpDescrição
UAPPI_CORE_COMMON_ADDITIONAL_FIELD_INVALID_TYPE400O tipo de campo informado não é suportado pela plataforma.
UAPPI_CORE_COMMON_ADDITIONAL_FIELD_MISSING_OPTIONS400O campo options deve conter ao menos um item para os tipos enum ou array.
UAPPI_CORE_COMMON_ADDITIONAL_FIELD_DUPLICATE_NAME400Já existe um campo adicional com este nome para a entidade informada.
UAPPI_API_COMMON_ADDITIONAL_FIELD_INVALID_ENTITY400A entidade informada na rota não é suportada pela plataforma.

Atualização de campo adicional

PUT /common/additional-fields/{commonAdditionalFieldEntity}/{commonAdditionalFieldId}

Atualização de campo adicional

Descrição

Endpoint responsável por atualizar as informações de um campo adicional específico.

⚠️ Atenção: O campo type (tipo do dado) é imutável e não pode ser alterado após o cadastro. Caso você altere o name, o code (slug) do campo também será atualizado automaticamente.

Parâmetros

Parâmetros de Rota

ParâmetroTipoObrigatórioDescrição
commonAdditionalFieldEntitystringSimIdentificador da entidade alvo (Ex: customer)
commonAdditionalFieldIdintegerSimID do campo adicional que deseja atualizar.

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Parâmetros de Corpo

CampoTipoObrigatórioDescrição
namestringSimNovo nome amigável do campo.
requiredbooleanSimAtualiza a obrigatoriedade do campo.
optionsarray ou nullNãoObrigatório apenas para os tipos enum e array. Determina as opções disponíveis no preenchimento do campo nas entidades.

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/common/additional-fields/customer/1 \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6	"name": "Meus Interesses de Compra",
7	"required": true,
8	"options": [
9		"Moda",
10		"Tecnologia",
11		"Games",
12		"Esportes"
13	]
14}'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "name": "Meus Interesses de Compra",
6    "code": "meus-interesses-de-compra",
7    "type": "array",
8    "required": true,
9    "options": [
10      "Moda",
11      "Tecnologia",
12      "Games",
13      "Esportes"
14    ],
15    "createdAt": "2026-03-19 14:00:00",
16    "updatedAt": "2026-03-19 15:30:00"
17  }
18}

⚠️ Respostas de Erro

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código internoCódigo HttpDescrição
UAPPI_CORE_COMMON_ADDITIONAL_FIELD_NOT_FOUND404O ID do campo adicional informado não foi encontrado.
UAPPI_CORE_COMMON_ADDITIONAL_FIELD_MISSING_OPTIONS400O campo options deve conter ao menos um item para os tipos enum ou array.
UAPPI_CORE_COMMON_ADDITIONAL_FIELD_DUPLICATE_NAME400Já existe um campo adicional com este nome para a entidade informada.
UAPPI_API_COMMON_ADDITIONAL_FIELD_INVALID_ENTITY400A entidade informada na rota não é suportada pela plataforma.

Remoção de campo adicional

DELETE /common/additional-fields/{commonAdditionalFieldEntity}

Remoção de campo adicional

Descrição

Endpoint responsável por remover um ou mais campos adicionais de uma entidade específica.

⚠️ Aviso de Impacto: Ao remover um campo adicional, todos os dados e valores associados a ele nas entidades (ex: clientes) também serão excluídos permanentemente.

Parâmetros

Parâmetros de rota

ParâmetroTipoObrigatórioDescrição
commonAdditionalFieldEntitystringSimIdentificador da entidade alvo (Ex: customer)

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Parâmetros de Corpo

CampoTipoObrigatórioDescrição
commonAdditionalFieldsIdsarraySimLista (array) de IDs dos campos que deseja remover.

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/common/additional-fields/customer \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6	"commonAdditionalFieldsIds": [1, 2]
7}'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": true
4}

⚠️ Respostas de Erro

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código internoCódigo HttpDescrição
UAPPI_API_COMMON_ADDITIONAL_FIELD_INVALID_ENTITY400A entidade informada na rota não é suportada pela plataforma.

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;