Referencia de la API

Usa esta ruta para mostrar grupos en tu web. Solo devuelve grupos publicados y visibles en la lista de la organización asociada a la clave. Los filtros son opcionales; si envías varios, el grupo debe cumplirlos todos.

Parámetro	Formato y efecto
courseId	ID del curso original.
startDate	Fecha AAAA-MM-DD; compara la fecha pública de inicio en la zona horaria del grupo.
country	Código de dos letras; se convierte a mayúsculas.
city, venue	Coincidencia exacta.

curl 'https://TU_DOMINIO/api/integrations/v1/cohorts?country=ES' \
  -H 'x-api-key: TU_CLAVE_DE_SERVIDOR'

La respuesta es { "cohorts": [...] }. Cada elemento contiene cohortId, cohortKey, courseId, title, timezone, country, city, venue, hasStorefront, publicDates, seatAvailability, capacity y remainingSeats. El lugar, la capacidad y las fechas pueden ser null. seatAvailability vale available o full. publicDates, si existe, contiene startsAt y endsAt, cada uno null o { "instant": "..." }. Usa cohortKey para dar acceso y cohortId para asociar una consulta a un grupo. Si cohorts está vacío, ningún grupo visible coincide con los filtros.

Llama a esta ruta cuando alguien envíe una consulta desde tu web. Asigna un externalLeadId a cada envío y reutilízalo si tienes que repetir la petición por un fallo de red.

curl 'https://TU_DOMINIO/api/integrations/v1/leads' \
  -H 'x-api-key: TU_CLAVE_DE_SERVIDOR' -H 'Content-Type: application/json' \
  -d '{"externalLeadId":"form-1042","capturedAt":"2026-09-23T10:00:00Z","person":{"name":"Ana Ruiz","email":"ana@example.com"},"source":{"system":"website","form":"course-enquiry","pageUrl":"https://school.example/courses","locale":"es"}}'

Campo	Obligatorio	Regla
externalLeadId	Sí	ID del envío, de 1 a 200 caracteres; mantenlo al reintentar.
capturedAt	Sí	Fecha y hora ISO; no más de cinco minutos en el futuro.
person	Sí	Correo o teléfono internacional; name es opcional.
source	Sí	system, form, pageUrl y locale; URL HTTP o HTTPS.
courseId o cohortId	No	Como máximo uno. Un grupo debe estar publicado al asignarlo.
message	No	Hasta 5.000 caracteres.
customFields	No	Hasta 20 campos con key, label y value; claves únicas.
marketingConsent	No	Registro aparte de la elección sobre comunicaciones comerciales; ver abajo.

source.system y source.form empiezan por letra minúscula y solo admiten minúsculas, números o guiones (máximo 64 caracteres). pageUrl se guarda sin parámetros ni fragmento. Crear un contacto devuelve 201; repetir la petición o actualizar un contacto existente devuelve 200. La respuesta contiene leadId, cohortId (texto o null), courseId (texto o null) y status (captured, converted o discarded). Por ejemplo:

{ "leadId": "id_del_contacto", "cohortId": null, "courseId": null, "status": "captured" }

Si repites los mismos datos una vez normalizados, Taskpipe devuelve el contacto guardado sin tocar los cambios hechos por el equipo. Si cambias los datos con el mismo ID externo, o envías datos de una persona que ya figura en esta organización, la ficha se actualiza. Los campos enviados pueden sustituir valores anteriores. Antes de corregir un envío, consulta lo que ya está guardado. Un cohortId ya asociado puede seguir en la ficha aunque el grupo deje de estar publicado; para asignar otro grupo, ese grupo sí debe estar publicado.

marketingConsent es independiente de la consulta. Envíalo solo si has registrado la elección de la persona. Exige granted (booleano), givenAt (fecha y hora ISO), uiLocation (URL HTTP/S) y userAgent (1–1024 caracteres imprimibles). Puede incluir IP, país, región e idioma; la región exige el país.

Usa esta ruta cuando hayas decidido incorporar a un estudiante a un grupo publicado. isPaid registra si consta como pagado; esta petición no cobra al estudiante.

curl 'https://TU_DOMINIO/api/integrations/v1/cohort-students' \
  -H 'x-api-key: TU_CLAVE_DE_SERVIDOR' -H 'Content-Type: application/json' \
  -d '{"cohortKey":"autumn-2026","student":{"name":"Ana Ruiz","email":"ana@example.com"},"isPaid":false,"joinedAt":"2026-09-23T10:00:00Z"}'

Campo	Obligatorio	Regla
cohortKey	Sí	Clave de un grupo publicado de esta organización.
student.name, student.email	Sí	Nombre no vacío y correo válido.
student.phone	No	Teléfono internacional, al menos cinco caracteres.
joinedAt	Sí	Fecha y hora ISO.
isPaid	No	Vale false por defecto; registra el pago, no cobra una tarjeta.

Al crear una matrícula, la respuesta es 201 y se pone en cola un correo de acceso. Si repites la petición con el mismo grupo, correo y valor de isPaid, recibes 200 con la matrícula existente; no se pone otro correo en cola. Si cambias isPaid, recibes 409 student_access_conflict: esta ruta no cambia el estado de pago de una matrícula existente. Las dos respuestas correctas contienen:

{
  "studentId": "id_del_estudiante",
  "cohortStudentId": "id_de_matricula",
  "cohortId": "id_del_grupo",
  "status": "active",
  "loginPath": "/login"
}

Si se pierde la respuesta, repite la misma petición mientras el grupo siga publicado. Una respuesta 200 confirma que la matrícula existe. Un grupo inexistente, no publicado o ajeno devuelve 404, incluso si una petición anterior pudo haber creado la matrícula; si cambió el estado del grupo, compruébalo en Taskpipe. Un grupo lleno devuelve 409 cohort_full al intentar añadir una matrícula nueva.

Los errores usan { "error": { "code": "...", "message": "..." } }; algunos incluyen requestId o details. No uses el texto del mensaje para tomar decisiones.

Estado	Código habitual	Qué hacer
400	validation_error	Corrige el JSON o los campos.
401	missing_api_key, invalid_api_key	Usa una clave válida con el permiso necesario.
404	cohort_not_found, lead_target_not_found	Revisa la organización y el destino; los grupos deben estar publicados para nuevas matrículas o nuevas asignaciones de contactos.
409	cohort_full, student_access_conflict	Resuelve el límite de plazas o el estado de pago.
413	payload_too_large	El cuerpo de la petición para registrar un contacto supera 32 KiB.
429	rate_limited	Espera los segundos de Retry-After.

Si recibes un error 5xx o se pierde la respuesta, no sabes si la operación se completó. Repite la consulta con el mismo externalLeadId y los mismos datos, o el acceso con el mismo grupo, correo y isPaid. No cambies esos valores solo para reintentar: otros datos pueden actualizar una ficha y otro valor de isPaid puede causar un conflicto. Consulta Integraciones para crear claves.