🔌 Uso de Campos Selector y Multiselector en la API v2 de Clientes

Requisitos Previos

Antes de interactuar con los endpoints de la API para gestionar tus campos personalizados, asegúrate de contar con:

Acceso a la API v2: Credenciales de autenticación vigentes para apuntar a los endpoints /clients/v2.
Diccionario de Datos: Conocer las claves internas (Keys) configuradas para las opciones de tus selectores en Atom. La API procesa exclusivamente los identificadores del sistema, no los nombres visibles para el usuario (Labels).

1. Estructura y Formato de Datos (Payload)

Para que tus peticiones HTTP sean procesadas exitosamente, los valores enviados en el cuerpo (payload) deben respetar estrictamente su tipo de dato. Atom no intentará adivinar ni convertir datos incompatibles.

Tipo de Campo	Formato Requerido (JSON)	Comportamiento del Sistema
Selector Simple	Cadena de texto (`string`)	Rechazará números, booleanos, objetos o arreglos. Retorna error `TYPE_MISMATCH`.
Multiselector	Arreglo de textos (`array of strings`)	Rechazará la petición si no es un arreglo o si incluye elementos que no sean texto.

2. Uso de Claves Internas (Keys)

El motor de la API v2 de Atom realiza una validación exacta de los datos que ingresan. Para asegurar la sincronización:

Usa solo Identificadores: Envía siempre el Key de la opción (ej. soporte_premium), no envíes lo que lee el cliente (ej. "Soporte Premium").
Sensibilidad a Mayúsculas: La validación es case-sensitive (sensible a mayúsculas y minúsculas). El sistema considerará que ecuador es completamente distinto a ECUADOR.

⚠️ Importante: Todo valor enviado debe existir en el catálogo del campo dentro de Atom y estar en estado "Activo". Si envías una opción inexistente, el sistema abortará la operación reportando el error INVALID_OPTION.

3. Reglas de Negocio y Persistencia de Datos

Atom aplica una capa de seguridad transaccional antes de guardar cualquier registro en tu base de clientes:

Rechazo Atómico Total: Si envías una solicitud con múltiples campos y tan solo uno falla (por ejemplo, incluyes una opción inválida en un multiselector), Atom rechazará la solicitud completa. No se guardarán datos parciales, manteniendo el estado anterior del cliente intacto para evitar corrupción de información.
Deduplicación Silenciosa: Si envías valores repetidos dentro de un arreglo multiselector (ej. ["vip", "vip"]), Atom los limpiará automáticamente y guardará el valor una sola vez (["vip"]), sin interrumpir la petición ni generar errores.
Respeto por Valores Históricos: Si un cliente ya tiene asignada una opción que fue recientemente desactivada en tu catálogo, la plataforma preservará ese valor histórico. Solo cambiará si envías una nueva actualización explícita para ese campo.

💡 Tip: Estrategia de Limpieza (JSON Merge Patch): Si omites un campo en tu petición, Atom asume que no hay cambios. Si necesitas borrar la información almacenada en un campo, debes enviar explícitamente null o "" (vacío) para un Selector Simple, y un arreglo vacío [] para un Multiselector.

4. Ejemplos Prácticos de Petición y Respuesta

Para ilustrar cómo viaja la información hacia Atom, observa los siguientes escenarios:

Payload Exitoso (Creación o Actualización)

En este ejemplo, tipo_de_cliente es un selector simple, mientras que servicios_contratados es un multiselector.

JSON

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

Respuesta Estructurada por Error (RFC 7807)

Si envías una opción que fue desactivada por un administrador, el sistema protegerá tu base de datos y retornará un código HTTP 400 Bad Request indicando exactamente dónde ocurrió el fallo:

JSON

{
  "type": "https://api.atomchat.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more fields failed validation.",
  "instance": "/clients/v2",
  "errors": [
    {
      "field": "servicios_contratados",
      "code": "OPTION_DISABLED",
      "detail": "La opción enviada existe pero se encuentra deshabilitada."
    }
  ]
}

Al dominar la estructura y las validaciones de la API v2, tienes la certeza absoluta de que la base de datos de tus clientes estará libre de valores mal escritos o datos corruptos. Aprovecha esta integridad estructural para construir integraciones sólidas y estandarizar la información en todo tu ecosistema tecnológico. ✅