Requisitos Prévios

Antes de interagir com os endpoints da API para gerenciar seus campos personalizados, certifique-se de contar com:

Acesso à API v2: Credenciais de autenticação vigentes para apontar aos endpoints /clients/v2.
Dicionário de Dados: Conhecer as chaves internas (Keys) configuradas para as opções de seus seletores no Atom. A API processa exclusivamente os identificadores do sistema, não os nomes visíveis para o usuário (Labels).

1. Estrutura e Formato de Dados (Payload)

Para que suas requisições HTTP sejam processadas com êxito, os valores enviados no corpo (payload) devem respeitar estritamente seu tipo de dado. O Atom não tentará adivinhar nem converter dados incompatíveis.

Tipo de Campo	Formato Requerido (JSON)	Comportamento do Sistema
Seletor Simples	Cadeia de texto (`string`)	Rejeitará números, booleanos, objetos ou matrizes. Retorna erro `TYPE_MISMATCH`.
Multiseletor	Matriz de textos (`array of strings`)	Rejeitará a requisição se não for uma matriz ou se incluir elementos que não sejam texto.

2. Uso de Chaves Internas (Keys)

O motor da API v2 do Atom realiza uma validação exata dos dados que entram. Para garantir a sincronização:

Use apenas Identificadores: Sempre envie a Key da opção (ex. soporte_premium), não envie o que o cliente lê (ex. "Suporte Premium").
Sensibilidade a Maiúsculas: A validação é case-sensitive (sensível a maiúsculas e minúsculas). O sistema considerará que ecuador é completamente distinto de ECUADOR.

⚠️ Importante: Todo valor enviado deve existir no catálogo do campo dentro do Atom e estar em estado "Ativo". Se enviar uma opção inexistente, o sistema abortará a operação reportando o erro INVALID_OPTION.

3. Regras de Negócio e Persistência de Dados

O Atom aplica uma camada de segurança transacional antes de salvar qualquer registro em sua base de clientes:

Rejeição Atômica Total: Se enviar uma solicitação com múltiplos campos e apenas um falhar (por exemplo, incluir uma opção inválida em um multiseletor), o Atom rejeitará a solicitação completa. Nenhum dado parcial será salvo, mantendo o estado anterior do cliente intacto para evitar corrupção de informações.
Deduplicação Silenciosa: Se enviar valores repetidos dentro de uma matriz multiseletor (ex. ["vip", "vip"]), o Atom os limpará automaticamente e salvará o valor uma única vez (["vip"]), sem interromper a requisição nem gerar erros.
Respeito por Valores Históricos: Se um cliente já tiver atribuída uma opção que foi recentemente desativada em seu catálogo, a plataforma preservará esse valor histórico. Só mudará se enviar uma nova atualização explícita para esse campo.

💡 Dica: Estratégia de Limpeza (JSON Merge Patch): Se omitir um campo em sua requisição, o Atom assume que não há alterações. Se precisar excluir as informações armazenadas em um campo, deve enviar explicitamente null ou "" (vazio) para um Seletor Simples, e uma matriz vazia [] para um Multiseletor.

4. Exemplos Práticos de Requisição e Resposta

Para ilustrar como a informação viaja para o Atom, observe os seguintes cenários:

Payload Bem-sucedido (Criação ou Atualização)

Neste exemplo, tipo_de_cliente é um seletor simples, enquanto servicios_contratados é um multiseletor.

JSON

{
  "name": "Juan Pérez",
  "phone": "+573001234567",
  "optionals": {
    "tipo_de_cliente": "corporativo",
    "servicios_contratados": ["soporte_premium", "api_access"]
  }
}

Resposta Estruturada por Erro (RFC 7807)

Se enviar uma opção que foi desativada por um administrador, o sistema protegerá sua base de dados e retornará um código HTTP 400 Bad Request indicando exatamente onde ocorreu a falha: