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/course-modalities?country=ES' \
  -H 'x-api-key: TU_CLAVE_DE_SERVIDOR'

La respuesta es { "modalities": [...] }. Cada elemento contiene modalityId, modalityKey, 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 modalityId para asociar una consulta a un grupo. Si modalities está vacío, ningún grupo visible coincide con los filtros.

Estas rutas no matriculan estudiantes ni dan acceso al curso. Envía a los compradores a la oferta pública del grupo o sigue Acceso de estudiantes para añadir a alguien desde Taskpipe.

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 modalityId	No	Como máximo uno. Un grupo debe estar publicado y abierto a matrículas 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, modalityId (texto o null), courseId (texto o null) y status (captured, contacted, converted o discarded). Por ejemplo:

{ "leadId": "id_del_contacto", "modalityId": 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 modalityId ya asociado puede seguir en la ficha aunque el grupo deje de estar publicado; para asignar otro grupo, ese grupo sí debe estar publicado y abierto a matrículas.

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.

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	lead_target_not_found	Revisa la organización y el destino; las nuevas asignaciones de contactos necesitan un grupo publicado con matrículas abiertas.
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. Otros datos pueden actualizar una ficha; no los cambies solo para reintentar. Consulta Integraciones para crear claves.