Agregar un contacto a un dataset

POST/v1/datasets/{id}/contacts

Para desarrolladores

Descripción

Registra un contacto en un dataset. Es la vía para alimentar un dataset desde su propio sistema, contacto a contacto; la otra es un formulario de Fidelizador vinculado a ese dataset.

La respuesta es 202 Accepted, no 201 Created. El contacto se valida al recibirlo y se guarda después, así que puede tardar hasta un minuto en aparecer en GET /v1/datasets/{id}/records. No asuma que está disponible al recibir el 202. Si necesita confirmarlo, búsquelo en ese listado.

Cuatro reglas deciden qué se acepta:

• Solo columnas que el dataset declara. Una clave que el dataset no declara se rechaza con 409, no se ignora. Así un error de su integración no pasa inadvertido.
• Las columnas obligatorias no pueden faltar. Un contacto sin una columna que el dataset marca como obligatoria se rechaza con 409.
• El identificador es obligatorio. Cada dataset reconoce a un contacto por uno de tres identificadores: correo, teléfono o código único. Se elige al crear el dataset. Sin ese valor, el contacto no se puede buscar, actualizar ni suprimir, y se duplicaría en cada reenvío.
• Cada valor cumple las reglas de su campo. Son las mismas que aplica un formulario: opciones permitidas, largo, patrón y rango, según cómo esté configurado el campo en el catálogo (GET /v1/fields). El correo debe tener forma de correo. El teléfono se guarda sin espacios, guiones, puntos ni paréntesis (+56 9 1234-5678 queda +56912345678). Así escrito, debe ser un + opcional seguido de 6 a 15 dígitos, y el patrón de su campo se revisa sobre ese valor. Un valor que no las cumple se rechaza con 422.

Las columnas que el dataset no marca como obligatorias pueden faltar. Por ejemplo, en un dataset que identifica por correo y no exige el teléfono, un contacto puede entrar sin teléfono, y el teléfono puede llegar después.

Qué ocurre cuando el contacto ya existe lo decide la política de colisión del dataset, configurada en el panel:

Política	Qué hace con el contacto que ya estaba
Descartar	El contacto queda como estaba. No se guarda nada de lo enviado, ni siquiera los datos que le faltaban.
Completar	Se guardan solo los datos que el contacto no tenía. Los que ya tenían valor no cambian, aunque se envíen distintos.
Actualizar	Los datos enviados reemplazan a los anteriores. Los no enviados se conservan.
Reemplazar	El contacto queda solo con los datos enviados. Todo lo demás se borra.

Actualizar y Reemplazar se diferencian en lo que pasa con los datos que no se envían. Si un contacto tenía doce campos y la llamada trae tres, Actualizar conserva los otros nueve y Reemplazar los borra.

Reenviar el mismo contacto no crea un duplicado: se reconoce por su identificador y se le aplica la política del dataset.

Antes de la primera carga, tenga en cuenta dos comportamientos:

• Completar es el valor por defecto y no sobrescribe. Un dataset en Completar conserva lo guardado y solo escribe en los datos vacíos. Si su sistema debe ser la fuente de verdad, configure el dataset en Actualizar.
• Un valor vacío equivale a no enviar la clave. {"PHONE": ""} no borra el teléfono guardado. Así, un dato que no recolectó no borra uno que ya tenía valor. No hay una forma de borrar un dato puntual por la API: la única es Reemplazar, que borra todo lo que no venga en la llamada. Desde el panel sí puede vaciar una columna de un contacto.

Cada dataset admite contactos a una tasa propia, que se informa en ingest_rate de GET /v1/datasets, en contactos por minuto. La comparten esta API, los formularios vinculados al dataset y la copia de una lista. Puede enviar seguidos, sin esperar, tantos contactos como la tasa admite en 10 segundos. Si agota ese margen, la respuesta es 429 con Retry-After. Si hay una copia de lista en curso, esta API tiene prioridad: la copia usa solo lo que la API deja libre.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope dataset:write. Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Request

Path params:

idintegerobligatorio

Identificador del dataset.

Body:

valuesobjectobligatorio

Valores del contacto, indexados por la field_key del campo (GET /v1/fields). Al menos una clave. Cada valor se guarda con el tipo de su campo.

Cómo se envía y cómo se guarda cada tipo de campo:

Tipo de campo	Se puede enviar como	Se guarda como
Sí/no	true/false, o el texto true/false, 1/0, sí/no, verdadero/falso	true / false
Selección múltiple	Una lista (["NUNOA","PROVIDENCIA"]) o texto separado por comas ("NUNOA,PROVIDENCIA")	Lista de opciones
Número	Un número (42) o texto que lo sea ("42")	Número
Fecha	Texto YYYY-MM-DD	Texto YYYY-MM-DD
Los demás	Texto	Texto

Un valor que no corresponde a su tipo se rechaza con 422, igual que uno que no cumple las reglas de su campo.

Response

202 AcceptedDevuelve un objeto con los campos que siguen.

Errores

Código	code	Cuándo
404	dataset_not_found	El dataset no existe.
409	dataset_column_not_declared	values trae una clave que el dataset no declara.
409	dataset_required_column_missing	Falta una columna que el dataset declara obligatoria.
409	dataset_identity_value_missing	Falta el identificador por el que el dataset reconoce a un contacto.
422	validation_error	Uno o más valores no cumplen las reglas o el tipo de su campo. errors trae un elemento por columna, con pointer /values/<field_key> y code field_value_invalid, y se informan todos a la vez.
429	rate_limit_exceeded	Se superó la tasa de ingreso del dataset y no admite más contactos por ahora. El body trae además limit_scope dataset. El contacto no se recibe: reenvíelo pasado Retry-After.
503	service_unavailable	La plataforma no pudo recibir el contacto en este momento. Reintente.

La respuesta 429 trae los headers Retry-After (segundos hasta poder reintentar), X-RateLimit-Limit (cuántos contactos admite el dataset seguidos, sin esperar), X-RateLimit-Remaining y X-RateLimit-Reset (segundo Unix en que el cupo vuelve a estar completo).

El catálogo completo está en Respuestas de error.

Notas

• Los rechazos 409 y 422 se responden antes del 202. Por eso un 202 indica que el contacto pasó la validación, no solo que llegó.
• El correo se guarda normalizado: Ana@Ejemplo.cl y ana@ejemplo.cl son el mismo contacto.
• Un contacto guardado se puede quitar con DELETE /v1/datasets/{id}/contacts/{identifier}. Para corregirlo, edítelo en el panel o, si el dataset usa la política Actualizar, vuelva a enviarlo con los datos corregidos.
• El mismo correo en dos datasets corresponde a dos contactos distintos. Cada dataset guarda sus contactos por separado.

Request

curl -X POST "https://$API_HOST/v1/datasets/7/contacts" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-Instance-Slug: <slug>" \
-H "Content-Type: application/json" \
-d '{
  "values": {
    "EMAIL": "ana@ejemplo.cl",
    "FIRST_NAME": "Ana",
    "LAST_NAME": "Pérez"
  }
}'

Response

Sin cuerpo: la respuesta no trae contenido.