Para qué sirve#
Permite que un sistema externo (por ejemplo el formulario de suscripción de la página web):
- vea el listado de listas de distribución (listas de distribución de tipo «Correo electrónico» que están activas), y
- suscriba un contacto a una o varias listas en una sola llamada.
Al suscribir se deja la autorización del contacto para recibir correos, así que esta API nace apagada y sus permisos son explícitos: los interruptores «Todas las APIs de lectura / escritura» no la incluyen. Quien integra responde de haber obtenido la autorización de la persona.
Cómo activarla#
- En Configuración → APIs y Webhooks, pulsa Generar API (o edita una credencial): en la tabla de permisos, debajo del nombre de cada API está el interruptor «API habilitada» y enciende «Listas de distribución (ver y suscribir)».
- A la credencial que la usará, márcale de forma explícita Ver las listas de distribución (
listas:leer) y Suscribir contactos a listas de distribución (listas:suscribir).
Ver las listas#
Texto
GET https://crm.tuempresa.com/api/v1/listas?q=curso&pagina=1&limite=25
Authorization: Bearer cnx_TU_LLAVETexto
{ "datos": [ { "id": 1172, "nombre": "DIAN 2025 - Clientes totales", "descripcion": "", "contactos": 993, "creada_at": "…" } ],
"total": 1050, "pagina": 1, "limite": 25, "hay_mas": true }q filtra por nombre (sin distinguir mayúsculas); limite va de 1 a 100.
Suscribir un contacto#
Texto
POST https://crm.tuempresa.com/api/v1/listas/suscribir
Authorization: Bearer cnx_TU_LLAVE
Content-Type: application/json
{ "email": "[email protected]", "listas": [1172, 917], "crear_contacto": true, "nombre": "Ana Pérez" }| Campo | Qué es |
|---|---|
listas | Obligatorio. Los ids de las listas (los de GET /listas), hasta 50. |
email | El correo del contacto (obligatorio si no envías contacto_id). |
contacto_id | Opcional. El id del contacto; el correo, si lo envías, debe ser uno de los suyos. |
crear_contacto | Opcional. true para crear el contacto si no existe uno con ese correo (si no, responde 404). nombre es el nombre del contacto nuevo. |
reactivar_baja | Opcional. true solo si la persona se había dado de baja y volvió a pedir suscribirse. |
Respuesta:
Texto
{ "datos": { "contacto_id": 12, "contacto_creado": false, "se_dio_de_baja": false, "autorizacion_correo": "otorgada",
"listas": [ { "lista_id": 1172, "nombre": "DIAN 2025 - Clientes totales", "estado": "suscrito" },
{ "lista_id": 917, "nombre": "Docente Abierto - Clientes totales", "estado": "ya_estaba" } ] } }Estado de cada lista: suscrito (se agregó ahora), ya_estaba, no_existe (id inválido, no es de correo o está eliminada) y baja_previa (no se suscribió porque el contacto se dio de baja).
Reglas importantes#
- Autorización: al suscribir, el consentimiento de correo del contacto queda otorgado (origen «api», con el nombre de la llave y las listas), y se anota en su actividad.
- Las bajas no se revierten solas: si el contacto se dio de baja de los correos, no se le suscribe (
baja_previa) salvo que envíesreactivar_baja: true. - Idempotente: suscribir dos veces al mismo contacto no lo duplica (
ya_estaba). - El contacto necesita correo; uno sin correo responde 422
contacto_sin_correo.
Errores#
| HTTP | Código | Cuándo |
|---|---|---|
| 404 | \contacto_no_encontrado\ | No hay contacto con ese correo (y no se envió \crear_contacto\). |
| 422 | \dato_invalido\ | Faltan \listas\ o el correo, el correo es inválido o hay más de 50 listas. |
| 422 | \correo_no_pertenece\ | Con \contacto_id\, el correo no es del contacto. |
| 422 | \contacto_sin_correo\ | El contacto no tiene correo electrónico. |
| 503 | \api_deshabilitada\ | La API está apagada. |
| 403 | \sin_permiso\ | La credencial no tiene los permisos explícitos. |
<!-- Fuente: shared/src/Core/Api/ListasApi.php, shared/src/Core/Api/Catalogo.php, shared/src/Core/Consentimiento.php -->