Agregar un contacto a un dataset
/v1/datasets/{id}/contactsPara 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, y el teléfono, formato internacional con+(+56912345678). Un valor que no las cumple se rechaza con422.
Los demás datos pueden faltar: un contacto que solo trae el identificador es válido. Por ejemplo, en un dataset que identifica por correo, 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.
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_keydel 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
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. |
503 | service_unavailable | La plataforma no pudo recibir el contacto en este momento. Reintente. |
El catálogo completo está en Respuestas de error.
- Los rechazos
409y422se responden antes del202. Por eso un202indica que el contacto pasó la validación, no solo que llegó. - El correo se guarda normalizado:
[email protected]y[email protected]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.
curl -X POST "https://cl1api.fidelizador.com/v1/datasets/7/contacts" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-Instance-Slug: <slug>" \
-H "Content-Type: application/json" \
-d '{
"values": {
"EMAIL": "[email protected]",
"FIRST_NAME": "Ana",
"LAST_NAME": "Pérez"
}
}'
{
"type": "https://docs.fidelizador.com/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Authentication required.",
"code": "unauthorized",
"trace_id": "dbb56202f13e1c15473bc6044ede8539"
}