Ir al contenido
Documentación de Connecto
connecto.lat
Guía de usuarioConfiguración general e IA

API: Listas de distribución (ver y suscribir)

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#

  1. 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)».
  2. 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_LLAVE
Texto
{ "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" }
CampoQué es
listasObligatorio. Los ids de las listas (los de GET /listas), hasta 50.
emailEl correo del contacto (obligatorio si no envías contacto_id).
contacto_idOpcional. El id del contacto; el correo, si lo envías, debe ser uno de los suyos.
crear_contactoOpcional. true para crear el contacto si no existe uno con ese correo (si no, responde 404). nombre es el nombre del contacto nuevo.
reactivar_bajaOpcional. 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íes reactivar_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#

HTTPCódigoCuá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 -->

¿Te fue útil esta página?
Última actualización: 14/11/2026