Versión 1.0.0 · openapi.json · API antigua

API v1 de Be CRM

Para conectar tu plataforma mediante login y selección de workspace, sigue los pasos de BeCRM Connect. Tu servidor obtiene tokens OAuth para consumir esta API con los permisos autorizados.

Para enviar y recibir mensajes, consulta la guía de WhatsApp y SMS: ventana de 24 horas, plantillas, botones, enlaces, idempotencia y webhooks.

URL base https://crm.begraffic.com/api/v1. JSON en peticiones y respuestas. Solo de servidor a servidor: la API no tiene CORS y la clave nunca debe llegar a un navegador.

Autenticación. Authorization: Bearer bcrm_… con una clave de Ajustes → API o un token de acceso de BeCRM Connect. Cada credencial tiene alcances (solo puede lo que marcaste), puede caducar y se puede revocar o rotar. Las claves antiguas (bmkt_…) no sirven aquí, ni las v1 en las rutas antiguas.

Respuestas. Un recurso: { data }. Una lista: { data: [ … ], nextCursor } (pasa cursor=nextCursor para la página siguiente; null al final). Un error: { error: { code, message, details? }, requestId } (el mismo requestId va en la cabecera X-Request-Id).

Idempotencia. Toda escritura acepta Idempotency-Key: repetir la misma petición con la misma clave devuelve la misma respuesta durante 24 h (cabecera Idempotent-Replayed: true); con otro cuerpo, 422; mientras la primera sigue en curso, 409. Un error 5xx no se guarda.

Límite. 120 llamadas por minuto y clave (cabeceras X-RateLimit-*); al superarlo, 429 con Retry-After. Los envíos (correo, WhatsApp) consumen la cuota del plan y responden 402 al agotarla: reintentar no lo arregla.

Alcances

  • segments:write Segmentos: crear y actualizar segmentos de la integración
  • contacts:read Contactos y etiquetas: leer
  • contacts:write Contactos y etiquetas: crear y editar
  • contacts:delete Contactos y etiquetas: borrar
  • emails:send Correo: enviar (consume cuota)
  • emails:read Correo: leer historial y estado
  • templates:write Plantillas de correo: crear y actualizar las plantillas de la app
  • deals:read Negocios y pipelines: leer
  • deals:write Negocios y pipelines: crear, mover y cerrar
  • activities:read Actividades, notas y tareas: leer
  • activities:write Actividades, notas y tareas: crear y completar
  • conversations:read Conversaciones: leer
  • conversations:write Conversaciones: responder, asignar y cerrar
  • whatsapp_templates:write Plantillas de WhatsApp: crear plantillas (las revisa meta)
  • whatsapp_groups:manage Grupos de WhatsApp: crear y administrar grupos
  • tickets:read Tickets: leer
  • tickets:write Tickets: crear y gestionar
  • meetings:read Reuniones y agenda: leer y ver huecos
  • meetings:write Reuniones y agenda: reservar, mover y cancelar
  • donations:read Donaciones: recibir sus eventos por webhook
  • payments:read Pagos: leer
  • payments:write Pagos: registrar y actualizar
  • sensitive:read Registros restringidos: recibir y leer los pagos restringidos
  • webhooks:manage Webhooks: gestionar destinos

Contactos

post/api/v1/integrations/beschedule/clientscontacts:write

Actualizar la ficha nativa de Be Schedule

Solo OAuth oficial de Be Schedule. Resumen del cliente, totales y hasta 20 citas. Salud requiere visibilidad restringida, sin servicios, profesionales ni expediente clínico. La privacidad es irreversible. No cambia contactos, consentimiento, etiquetas, pipelines ni campañas. Observaciones repetidas o antiguas no revierten datos; una corrección de privacidad retira siempre la ficha pública.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • businessIdstringobligatorio
  • clientIdstringobligatorio
  • businessNamestringobligatorio
  • vertical"general" | "salud"obligatorio
  • visibility"workspace" | "restricted"obligatorio
  • accountState"active" | "inactive" | "unavailable"obligatorio
  • joinedAtstring (date-time) | nullobligatorio
  • observedAtstring (date-time)obligatorio
  • timeZonestringobligatorio
  • totalsobjectobligatorio
    • appointmentsintegerobligatorio
    • heldintegerobligatorio
    • canceledintegerobligatorio
    • noShowintegerobligatorio
  • truncatedbooleanobligatorio
  • appointmentsobject[]obligatorio
    • idstringobligatorio
    • state"booking_pending" | "payment_pending" | "scheduled" | "rescheduled" | "held" | "no_show" | "canceled"obligatorio
    • startAtstring (date-time)obligatorio
    • endAtstring (date-time) | nullobligatorio
    • serviceNamestring | nullobligatorio
    • professionalNamestring | nullobligatorio
    • modality"online" | "in_person" | "unavailable"obligatorio
  • contactIdstringobligatorio

Respuesta 200 · { data }

  • appliedbooleanobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/integrations/beschool/studentscontacts:write

Actualizar la ficha escolar del contacto

Solo OAuth oficial de Be School. Resumen de cuenta y matrículas, sin calificaciones ni expediente. Actualiza la asociación por escuela y estudiante; rechaza snapshots antiguos y contactos eliminados. No cambia consentimiento, etiquetas ni datos personales del contacto.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • schoolIdstringobligatorio
  • studentIdstringobligatorio
  • schoolNamestringobligatorio
  • hasLogobooleanobligatorio
  • accountState"active" | "invited" | "inactive" | "unavailable"obligatorio
  • joinedAtstring (date-time) | nullobligatorio
  • observedAtstring (date-time)obligatorio
  • truncatedbooleanobligatorio
  • enrollmentsobject[]obligatorio
    • idstringobligatorio
    • courseIdstring | nullobligatorio
    • courseNamestringobligatorio
    • periodIdstring | nullobligatorio
    • periodNamestringobligatorio
    • accessState"full" | "upcoming" | "read_only" | "closed"obligatorio
    • enrolledAtstring (date-time) | nullobligatorio
    • startsAtstring (date-time) | nullobligatorio
    • expiresAtstring (date-time) | nullobligatorio
    • readOnlyFromstring (date-time) | nullobligatorio
    • closedAtstring (date-time) | nullobligatorio
  • contactIdstringobligatorio

Respuesta 200 · { data }

  • appliedbooleanobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/integrations/beschool/measurementcontacts:write

Coordinar la medición publicitaria con BeSchool

Solo OAuth oficial de BeSchool. Guarda destinos públicos de medición por escuela para detectar coincidencias. No concede consentimiento ni dispara conversiones. Los pagos conservan su configuración original.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • schoolIdstringobligatorio
  • schoolNamestringobligatorio
  • updatedAtstring (date-time)obligatorio
  • metaPixelId"" | stringobligatorio
  • tiktokPixelId"" | stringobligatorio
  • googleAdsPurchaseDestination"" | stringobligatorio

Respuesta 200 · { data }

  • schoolIdstringobligatorio
  • checkedAtstring (date-time)obligatorio
  • sharedProviders"meta" | "google"[]obligatorio
  • unverifiedProviders"meta" | "google"[]obligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/contacts/lookupcontacts:read

Buscar candidatos por teléfono internacional

Coincidencias exactas en campos de teléfono estándar indexados, verificando país. No autentica al titular, no cubre números históricos con separadores arbitrarios ni habilita crear/mezclar automáticamente. ambiguous obliga a selección humana; si la consulta se trunca, 409 invalid_state con reason lookup_incomplete.

Markdown de este endpoint

Parámetros

  • phoneconsulta · stringobligatorio

    Teléfono internacional E.164 exacto. No comprueba identidad ni cubre formatos históricos arbitrarios.

Respuesta 200 · { data }

  • matchesobject[]obligatorio
    • idstringobligatorio
    • namestring | nullobligatorio
    • secondNamestring | nullobligatorio
    • lastnamestring | nullobligatorio
    • secondLastnamestring | nullobligatorio
    • emailstring | nullobligatorio
    • phoneobject | nullobligatorio
      • phone_codestring | nullobligatorio
      • phonestring | nullobligatorio
    • movilobject | nullobligatorio
      • movil_codestring | nullobligatorio
      • movilstring | nullobligatorio
    • addressobject | nullobligatorio
      • address1string | nullobligatorio
      • address2string | nullobligatorio
      • citystring | nullobligatorio
      • statestring | nullobligatorio
      • countrystring | nullobligatorio
      • zipstring | nullobligatorio
    • genderstring | nullobligatorio
    • birthdatestring (date) | nullobligatorio
    • imagestring | nullobligatorio
    • tagsstring[]obligatorio
    • groupsstring[]obligatorio
    • activebooleanobligatorio
    • ownerEmailstring | nullobligatorio
    • organizationIdstring | nullobligatorio
    • organizationNamestring | nullobligatorio
    • sourcestring | nullobligatorio
    • sourceDetailstring | nullobligatorio
    • stagestring | nullobligatorio
    • externalRefsobjectobligatorio

      `{app: id}`; vacío si no tiene.

    • attributionobject | nullobligatorio

      Primer y último toque de atribución, o `null`.

      • firstobject | nullobligatorio
        • utm_sourcestring
        • utm_mediumstring
        • utm_campaignstring
        • utm_termstring
        • utm_contentstring
        • landingUrlstring
        • referrerstring
        • atstring (date-time) | nullobligatorio
      • lastobject | nullobligatorio
        • utm_sourcestring
        • utm_mediumstring
        • utm_campaignstring
        • utm_termstring
        • utm_contentstring
        • landingUrlstring
        • referrerstring
        • atstring (date-time) | nullobligatorio
    • customFieldsobjectobligatorio

      Campos personalizados del contacto por clave API.

    • createdAtstring (date-time) | nullobligatorio
    • updatedAtstring (date-time) | nullobligatorio
  • ambiguousbooleanobligatorio
  • coverage"indexed_standard_fields"obligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 409 `invalid_state`: Operación no válida en el estado actual.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/contacts/{id}/ownercontacts:write

Asignar responsable de contacto

Valida membresía activa de acceso completo dentro de la transacción. onlyIfUnassigned por defecto conserva al responsable anterior. No cambia campañas ni canales. Los espejos de negocio principal siguen las reglas normales del contacto.

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • ownerEmailstring (email)obligatorio
  • onlyIfUnassignedboolean

Respuesta 200 · { data }

  • idstringobligatorio
  • namestring | nullobligatorio
  • secondNamestring | nullobligatorio
  • lastnamestring | nullobligatorio
  • secondLastnamestring | nullobligatorio
  • emailstring | nullobligatorio
  • phoneobject | nullobligatorio
    • phone_codestring | nullobligatorio
    • phonestring | nullobligatorio
  • movilobject | nullobligatorio
    • movil_codestring | nullobligatorio
    • movilstring | nullobligatorio
  • addressobject | nullobligatorio
    • address1string | nullobligatorio
    • address2string | nullobligatorio
    • citystring | nullobligatorio
    • statestring | nullobligatorio
    • countrystring | nullobligatorio
    • zipstring | nullobligatorio
  • genderstring | nullobligatorio
  • birthdatestring (date) | nullobligatorio
  • imagestring | nullobligatorio
  • tagsstring[]obligatorio
  • groupsstring[]obligatorio
  • activebooleanobligatorio
  • ownerEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • sourcestring | nullobligatorio
  • sourceDetailstring | nullobligatorio
  • stagestring | nullobligatorio
  • externalRefsobjectobligatorio

    `{app: id}`; vacío si no tiene.

  • attributionobject | nullobligatorio

    Primer y último toque de atribución, o `null`.

    • firstobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
    • lastobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
  • customFieldsobjectobligatorio

    Campos personalizados del contacto por clave API.

  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/contactscontacts:read

Listar contactos

Filtros por correo, etiqueta y responsable (combinables), `updatedSince` (solo) o `externalRef` (`app:id`, solo). Orden estable por id, o por `updatedAt` con `updatedSince`. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).

Markdown de este endpoint

Parámetros

  • emailconsulta · string (email)
  • tagconsulta · string
  • ownerEmailconsulta · string (email)
  • updatedSinceconsulta · string (date-time)

    Solo contactos con `updatedAt` posterior (no se combina con otros filtros).

  • externalRefconsulta · string

    Busca por referencia externa: `app:id` (p. ej. `beschedule:client_123`). No se combina con otros filtros.

  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • namestring | nullobligatorio
  • secondNamestring | nullobligatorio
  • lastnamestring | nullobligatorio
  • secondLastnamestring | nullobligatorio
  • emailstring | nullobligatorio
  • phoneobject | nullobligatorio
    • phone_codestring | nullobligatorio
    • phonestring | nullobligatorio
  • movilobject | nullobligatorio
    • movil_codestring | nullobligatorio
    • movilstring | nullobligatorio
  • addressobject | nullobligatorio
    • address1string | nullobligatorio
    • address2string | nullobligatorio
    • citystring | nullobligatorio
    • statestring | nullobligatorio
    • countrystring | nullobligatorio
    • zipstring | nullobligatorio
  • genderstring | nullobligatorio
  • birthdatestring (date) | nullobligatorio
  • imagestring | nullobligatorio
  • tagsstring[]obligatorio
  • groupsstring[]obligatorio
  • activebooleanobligatorio
  • ownerEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • sourcestring | nullobligatorio
  • sourceDetailstring | nullobligatorio
  • stagestring | nullobligatorio
  • externalRefsobjectobligatorio

    `{app: id}`; vacío si no tiene.

  • attributionobject | nullobligatorio

    Primer y último toque de atribución, o `null`.

    • firstobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
    • lastobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
  • customFieldsobjectobligatorio

    Campos personalizados del contacto por clave API.

  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/contactscontacts:write

Crear un contacto

409 `conflict` (con `details.id`) si ya existe un contacto con ese correo: para crear o actualizar, `POST /api/v1/contacts/upsert`. Campos de integración (`externalRefs`, `sourceDetail`, `attribution`, `customFields`): 403 `forbidden` si un conector escribe la referencia o el origen de otra app; 409 `conflict` si la referencia externa ya es de otro contacto; 422 `unprocessable` si un campo personalizado no existe, no es de su tipo o se vacía siendo obligatorio.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • emailstring (email)
  • namestring
  • secondNamestring
  • lastnamestring
  • secondLastnamestring
  • phoneobject | null
    • phone_codestringobligatorio

      Prefijo del país, p. ej. `+57`.

    • phonestringobligatorio
  • movilobject | null
    • movil_codestringobligatorio

      Prefijo del país, p. ej. `+57`.

    • movilstringobligatorio
  • addressobject | null
    • address1string
    • address2string
    • citystring
    • statestring
    • countrystring
    • zipstring
  • gender"Masculino" | "Femenino" | null
  • birthdatestring (date) | null

    `AAAA-MM-DD`; `null` la borra.

  • imagestring
  • tagsstring[]

    Se COMBINAN con las que ya tenga.

  • groupsstring[]

    Ids de listas; se combinan con las que ya tenga.

  • organizationIdstring | null

    `null` desasigna la organización.

  • organizationNamestring
  • activeboolean
  • noteobject

    Nota que se añade al contacto.

    • titlestringobligatorio
    • contentstring
    • type"note" | "reminder"
    • dueDatestring (date) | string (date-time)
    • reminderAtstring (date) | string (date-time)
    • tagsstring[]
  • externalRefsobject

    Identificadores del contacto en otras apps: `{"<app>": "<id>"}` (app en minúsculas, id ≤ 128). Se COMBINAN con las que ya tenga; `null` quita la de esa app. Un conector oficial solo escribe (y ve) SU app; una app de terceros no escribe ni ve las de los conectores oficiales. Se guardan FUERA del contacto (solo servidor): ningún miembro las ve en la ficha. Un id que ya tiene otro contacto: 409 `conflict`.

  • sourceDetailstring

    Detalle del origen (p. ej. `beschedule:psicobiblia`). Se escribe UNA vez: si el contacto ya tiene uno, se conserva (como `source`). Un conector oficial solo puede usar su app como prefijo y, sin él, al crear se guarda su app.

  • attributionobject

    Toque de atribución. Se guarda como `attribution.last` (siempre, con `at`) y como `attribution.first` solo si el contacto aún no tiene ninguno.

    • utm_sourcestring
    • utm_mediumstring
    • utm_campaignstring
    • utm_termstring
    • utm_contentstring
    • landingUrlstring

      URL http(s) de aterrizaje.

    • referrerstring

      URL http(s) de procedencia.

  • customFieldsobject

    `{"<clave API del campo>": valor}` de Ajustes → Campos personalizados (contactos). Se COMBINAN con los que ya tenga; `null` o `""` vacía el campo (salvo si es obligatorio). Clave desconocida, valor de otro tipo u obligatorio vacío: 422 `unprocessable`.

  • visibility"workspace" | "restricted"

    `restricted` (p. ej. un negocio de salud): el CRM no guarda la identidad de la app en el contacto: ni `sourceDetail` (se ignora si llega) ni el nombre de la conexión como canal (queda `API`). Por defecto `workspace`.

Respuesta 201 · { data }

  • idstringobligatorio
  • namestring | nullobligatorio
  • secondNamestring | nullobligatorio
  • lastnamestring | nullobligatorio
  • secondLastnamestring | nullobligatorio
  • emailstring | nullobligatorio
  • phoneobject | nullobligatorio
    • phone_codestring | nullobligatorio
    • phonestring | nullobligatorio
  • movilobject | nullobligatorio
    • movil_codestring | nullobligatorio
    • movilstring | nullobligatorio
  • addressobject | nullobligatorio
    • address1string | nullobligatorio
    • address2string | nullobligatorio
    • citystring | nullobligatorio
    • statestring | nullobligatorio
    • countrystring | nullobligatorio
    • zipstring | nullobligatorio
  • genderstring | nullobligatorio
  • birthdatestring (date) | nullobligatorio
  • imagestring | nullobligatorio
  • tagsstring[]obligatorio
  • groupsstring[]obligatorio
  • activebooleanobligatorio
  • ownerEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • sourcestring | nullobligatorio
  • sourceDetailstring | nullobligatorio
  • stagestring | nullobligatorio
  • externalRefsobjectobligatorio

    `{app: id}`; vacío si no tiene.

  • attributionobject | nullobligatorio

    Primer y último toque de atribución, o `null`.

    • firstobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
    • lastobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
  • customFieldsobjectobligatorio

    Campos personalizados del contacto por clave API.

  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • noteCreatedIdstring

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida.
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `unprocessable`: El cuerpo no cuadra con la configuración del workspace (p. ej. campos personalizados desconocidos o de otro tipo); `details.issues` dice cuáles. `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/contacts/upsertcontacts:write

Crear o actualizar por correo

Si existe un contacto con ese correo lo actualiza (combina etiquetas y listas; reactiva si estaba de baja salvo `active:false`); si no, lo crea. 201 al crear, 200 al actualizar. Campos de integración (`externalRefs`, `sourceDetail`, `attribution`, `customFields`): 403 `forbidden` si un conector escribe la referencia o el origen de otra app; 409 `conflict` si la referencia externa ya es de otro contacto; 422 `unprocessable` si un campo personalizado no existe, no es de su tipo o se vacía siendo obligatorio.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • emailstring (email)obligatorio
  • namestring
  • secondNamestring
  • lastnamestring
  • secondLastnamestring
  • phoneobject | null
    • phone_codestringobligatorio

      Prefijo del país, p. ej. `+57`.

    • phonestringobligatorio
  • movilobject | null
    • movil_codestringobligatorio

      Prefijo del país, p. ej. `+57`.

    • movilstringobligatorio
  • addressobject | null
    • address1string
    • address2string
    • citystring
    • statestring
    • countrystring
    • zipstring
  • gender"Masculino" | "Femenino" | null
  • birthdatestring (date) | null

    `AAAA-MM-DD`; `null` la borra.

  • imagestring
  • tagsstring[]

    Se COMBINAN con las que ya tenga.

  • groupsstring[]

    Ids de listas; se combinan con las que ya tenga.

  • organizationIdstring | null

    `null` desasigna la organización.

  • organizationNamestring
  • activeboolean
  • noteobject

    Nota que se añade al contacto.

    • titlestringobligatorio
    • contentstring
    • type"note" | "reminder"
    • dueDatestring (date) | string (date-time)
    • reminderAtstring (date) | string (date-time)
    • tagsstring[]
  • externalRefsobject

    Identificadores del contacto en otras apps: `{"<app>": "<id>"}` (app en minúsculas, id ≤ 128). Se COMBINAN con las que ya tenga; `null` quita la de esa app. Un conector oficial solo escribe (y ve) SU app; una app de terceros no escribe ni ve las de los conectores oficiales. Se guardan FUERA del contacto (solo servidor): ningún miembro las ve en la ficha. Un id que ya tiene otro contacto: 409 `conflict`.

  • sourceDetailstring

    Detalle del origen (p. ej. `beschedule:psicobiblia`). Se escribe UNA vez: si el contacto ya tiene uno, se conserva (como `source`). Un conector oficial solo puede usar su app como prefijo y, sin él, al crear se guarda su app.

  • attributionobject

    Toque de atribución. Se guarda como `attribution.last` (siempre, con `at`) y como `attribution.first` solo si el contacto aún no tiene ninguno.

    • utm_sourcestring
    • utm_mediumstring
    • utm_campaignstring
    • utm_termstring
    • utm_contentstring
    • landingUrlstring

      URL http(s) de aterrizaje.

    • referrerstring

      URL http(s) de procedencia.

  • customFieldsobject

    `{"<clave API del campo>": valor}` de Ajustes → Campos personalizados (contactos). Se COMBINAN con los que ya tenga; `null` o `""` vacía el campo (salvo si es obligatorio). Clave desconocida, valor de otro tipo u obligatorio vacío: 422 `unprocessable`.

  • visibility"workspace" | "restricted"

    `restricted` (p. ej. un negocio de salud): el CRM no guarda la identidad de la app en el contacto: ni `sourceDetail` (se ignora si llega) ni el nombre de la conexión como canal (queda `API`). Por defecto `workspace`.

Respuesta 200 · { data }

  • idstringobligatorio
  • namestring | nullobligatorio
  • secondNamestring | nullobligatorio
  • lastnamestring | nullobligatorio
  • secondLastnamestring | nullobligatorio
  • emailstring | nullobligatorio
  • phoneobject | nullobligatorio
    • phone_codestring | nullobligatorio
    • phonestring | nullobligatorio
  • movilobject | nullobligatorio
    • movil_codestring | nullobligatorio
    • movilstring | nullobligatorio
  • addressobject | nullobligatorio
    • address1string | nullobligatorio
    • address2string | nullobligatorio
    • citystring | nullobligatorio
    • statestring | nullobligatorio
    • countrystring | nullobligatorio
    • zipstring | nullobligatorio
  • genderstring | nullobligatorio
  • birthdatestring (date) | nullobligatorio
  • imagestring | nullobligatorio
  • tagsstring[]obligatorio
  • groupsstring[]obligatorio
  • activebooleanobligatorio
  • ownerEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • sourcestring | nullobligatorio
  • sourceDetailstring | nullobligatorio
  • stagestring | nullobligatorio
  • externalRefsobjectobligatorio

    `{app: id}`; vacío si no tiene.

  • attributionobject | nullobligatorio

    Primer y último toque de atribución, o `null`.

    • firstobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
    • lastobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
  • customFieldsobjectobligatorio

    Campos personalizados del contacto por clave API.

  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • noteCreatedIdstring
  • createdbooleanobligatorio
  • reactivatedbooleanobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida.
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `unprocessable`: El cuerpo no cuadra con la configuración del workspace (p. ej. campos personalizados desconocidos o de otro tipo); `details.issues` dice cuáles. `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/contacts/{id}contacts:read

Leer un contacto

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

Respuesta 200 · { data }

  • idstringobligatorio
  • namestring | nullobligatorio
  • secondNamestring | nullobligatorio
  • lastnamestring | nullobligatorio
  • secondLastnamestring | nullobligatorio
  • emailstring | nullobligatorio
  • phoneobject | nullobligatorio
    • phone_codestring | nullobligatorio
    • phonestring | nullobligatorio
  • movilobject | nullobligatorio
    • movil_codestring | nullobligatorio
    • movilstring | nullobligatorio
  • addressobject | nullobligatorio
    • address1string | nullobligatorio
    • address2string | nullobligatorio
    • citystring | nullobligatorio
    • statestring | nullobligatorio
    • countrystring | nullobligatorio
    • zipstring | nullobligatorio
  • genderstring | nullobligatorio
  • birthdatestring (date) | nullobligatorio
  • imagestring | nullobligatorio
  • tagsstring[]obligatorio
  • groupsstring[]obligatorio
  • activebooleanobligatorio
  • ownerEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • sourcestring | nullobligatorio
  • sourceDetailstring | nullobligatorio
  • stagestring | nullobligatorio
  • externalRefsobjectobligatorio

    `{app: id}`; vacío si no tiene.

  • attributionobject | nullobligatorio

    Primer y último toque de atribución, o `null`.

    • firstobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
    • lastobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
  • customFieldsobjectobligatorio

    Campos personalizados del contacto por clave API.

  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
patch/api/v1/contacts/{id}contacts:write

Actualizar un contacto

Solo cambia lo que llega. `tags` y `groups` se combinan; `removeTags` y `removeGroups` quitan; `null` borra `phone`, `movil`, `address`, `gender` y `birthdate`. `externalRefs` y `customFields` se combinan por clave. Cambiar `email` al de otro contacto: 409 `conflict` (con su `id` en `details`). Campos de integración (`externalRefs`, `sourceDetail`, `attribution`, `customFields`): 403 `forbidden` si un conector escribe la referencia o el origen de otra app; 409 `conflict` si la referencia externa ya es de otro contacto; 422 `unprocessable` si un campo personalizado no existe, no es de su tipo o se vacía siendo obligatorio.

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • emailstring (email)
  • namestring
  • secondNamestring
  • lastnamestring
  • secondLastnamestring
  • phoneobject | null
    • phone_codestringobligatorio

      Prefijo del país, p. ej. `+57`.

    • phonestringobligatorio
  • movilobject | null
    • movil_codestringobligatorio

      Prefijo del país, p. ej. `+57`.

    • movilstringobligatorio
  • addressobject | null
    • address1string
    • address2string
    • citystring
    • statestring
    • countrystring
    • zipstring
  • gender"Masculino" | "Femenino" | null
  • birthdatestring (date) | null

    `AAAA-MM-DD`; `null` la borra.

  • imagestring
  • tagsstring[]

    Se COMBINAN con las que ya tenga.

  • groupsstring[]

    Ids de listas; se combinan con las que ya tenga.

  • organizationIdstring | null

    `null` desasigna la organización.

  • organizationNamestring
  • activeboolean
  • noteobject

    Nota que se añade al contacto.

    • titlestringobligatorio
    • contentstring
    • type"note" | "reminder"
    • dueDatestring (date) | string (date-time)
    • reminderAtstring (date) | string (date-time)
    • tagsstring[]
  • externalRefsobject

    Identificadores del contacto en otras apps: `{"<app>": "<id>"}` (app en minúsculas, id ≤ 128). Se COMBINAN con las que ya tenga; `null` quita la de esa app. Un conector oficial solo escribe (y ve) SU app; una app de terceros no escribe ni ve las de los conectores oficiales. Se guardan FUERA del contacto (solo servidor): ningún miembro las ve en la ficha. Un id que ya tiene otro contacto: 409 `conflict`.

  • sourceDetailstring

    Detalle del origen (p. ej. `beschedule:psicobiblia`). Se escribe UNA vez: si el contacto ya tiene uno, se conserva (como `source`). Un conector oficial solo puede usar su app como prefijo y, sin él, al crear se guarda su app.

  • attributionobject

    Toque de atribución. Se guarda como `attribution.last` (siempre, con `at`) y como `attribution.first` solo si el contacto aún no tiene ninguno.

    • utm_sourcestring
    • utm_mediumstring
    • utm_campaignstring
    • utm_termstring
    • utm_contentstring
    • landingUrlstring

      URL http(s) de aterrizaje.

    • referrerstring

      URL http(s) de procedencia.

  • customFieldsobject

    `{"<clave API del campo>": valor}` de Ajustes → Campos personalizados (contactos). Se COMBINAN con los que ya tenga; `null` o `""` vacía el campo (salvo si es obligatorio). Clave desconocida, valor de otro tipo u obligatorio vacío: 422 `unprocessable`.

  • visibility"workspace" | "restricted"

    `restricted` (p. ej. un negocio de salud): el CRM no guarda la identidad de la app en el contacto: ni `sourceDetail` (se ignora si llega) ni el nombre de la conexión como canal (queda `API`). Por defecto `workspace`.

  • removeTagsstring[]
  • removeGroupsstring[]

Respuesta 200 · { data }

  • idstringobligatorio
  • namestring | nullobligatorio
  • secondNamestring | nullobligatorio
  • lastnamestring | nullobligatorio
  • secondLastnamestring | nullobligatorio
  • emailstring | nullobligatorio
  • phoneobject | nullobligatorio
    • phone_codestring | nullobligatorio
    • phonestring | nullobligatorio
  • movilobject | nullobligatorio
    • movil_codestring | nullobligatorio
    • movilstring | nullobligatorio
  • addressobject | nullobligatorio
    • address1string | nullobligatorio
    • address2string | nullobligatorio
    • citystring | nullobligatorio
    • statestring | nullobligatorio
    • countrystring | nullobligatorio
    • zipstring | nullobligatorio
  • genderstring | nullobligatorio
  • birthdatestring (date) | nullobligatorio
  • imagestring | nullobligatorio
  • tagsstring[]obligatorio
  • groupsstring[]obligatorio
  • activebooleanobligatorio
  • ownerEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • sourcestring | nullobligatorio
  • sourceDetailstring | nullobligatorio
  • stagestring | nullobligatorio
  • externalRefsobjectobligatorio

    `{app: id}`; vacío si no tiene.

  • attributionobject | nullobligatorio

    Primer y último toque de atribución, o `null`.

    • firstobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
    • lastobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
  • customFieldsobjectobligatorio

    Campos personalizados del contacto por clave API.

  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • noteCreatedIdstring

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `unprocessable`: El cuerpo no cuadra con la configuración del workspace (p. ej. campos personalizados desconocidos o de otro tipo); `details.issues` dice cuáles. `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
delete/api/v1/contacts/{id}contacts:delete

Borrar un contacto

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Respuesta 200 · { data }

  • idstringobligatorio
  • deletedtrueobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/contacts/{id}/tagscontacts:write

Añadir y quitar etiquetas

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • addstring[]
  • removestring[]

Respuesta 200 · { data }

  • idstringobligatorio
  • namestring | nullobligatorio
  • secondNamestring | nullobligatorio
  • lastnamestring | nullobligatorio
  • secondLastnamestring | nullobligatorio
  • emailstring | nullobligatorio
  • phoneobject | nullobligatorio
    • phone_codestring | nullobligatorio
    • phonestring | nullobligatorio
  • movilobject | nullobligatorio
    • movil_codestring | nullobligatorio
    • movilstring | nullobligatorio
  • addressobject | nullobligatorio
    • address1string | nullobligatorio
    • address2string | nullobligatorio
    • citystring | nullobligatorio
    • statestring | nullobligatorio
    • countrystring | nullobligatorio
    • zipstring | nullobligatorio
  • genderstring | nullobligatorio
  • birthdatestring (date) | nullobligatorio
  • imagestring | nullobligatorio
  • tagsstring[]obligatorio
  • groupsstring[]obligatorio
  • activebooleanobligatorio
  • ownerEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • sourcestring | nullobligatorio
  • sourceDetailstring | nullobligatorio
  • stagestring | nullobligatorio
  • externalRefsobjectobligatorio

    `{app: id}`; vacío si no tiene.

  • attributionobject | nullobligatorio

    Primer y último toque de atribución, o `null`.

    • firstobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
    • lastobject | nullobligatorio
      • utm_sourcestring
      • utm_mediumstring
      • utm_campaignstring
      • utm_termstring
      • utm_contentstring
      • landingUrlstring
      • referrerstring
      • atstring (date-time) | nullobligatorio
  • customFieldsobjectobligatorio

    Campos personalizados del contacto por clave API.

  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/contacts/{id}/notesactivities:read

Notas de un contacto

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • titlestring | nullobligatorio
  • contentstring | nullobligatorio
  • typestring | nullobligatorio
  • tagsstring[]obligatorio
  • createdBystring | nullobligatorio
  • createdAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.

Negocios

post/api/v1/integrations/{app}/processesdeals:write

Sincronizar una inscripción de Be School o una cita de Be Schedule

Solo OAuth oficial de la app indicada. Identidad estable, sin duplicar contactos u oportunidades; rechaza observaciones antiguas. Requiere activar el seguimiento en el CRM. historical:true carga estados sin emitir campañas ni avisos. Las citas restringidas quedan fuera de negocios, etiquetas y segmentación. La aplicación conserva la autoridad de matrículas, citas y pagos.

Markdown de este endpoint

Parámetros

  • appruta · "beschool" | "beschedule"obligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • externalIdstringobligatorio
  • contactIdstringobligatorio
  • instanceIdstringobligatorio
  • instanceNamestringobligatorio
  • subjectIdstring | nullobligatorio
  • offeringIdstring | nullobligatorio
  • offeringNamestringobligatorio
  • offeringsobject[]
    • idstringobligatorio
    • namestringobligatorio
  • periodIdstring | null
  • periodNamestring | null
  • state"started" | "requirements_pending" | "payment_pending" | "payment_processing" | "payment_failed" | "needs_review" | "completed" | "closed" | "inquiry" | "booking_pending" | "scheduled" | "rescheduled" | "held" | "no_show" | "canceled"obligatorio
  • observedAtstring (date-time)obligatorio
  • startedAtstring (date-time) | null
  • amountMinorinteger | null
  • currencystring
  • externalUrlstring (uri) | null
  • historicalboolean
  • visibility"workspace" | "restricted"

Respuesta 200 · { data }

  • appliedbooleanobligatorio
  • dealIdstring | nullobligatorio
  • pendingbooleanobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/dealsdeals:read

Listar negocios

Sin archivados. Por `leadId` (más recientes primero) o por pipeline, estado y responsable (últimos actualizados primero). Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).

Markdown de este endpoint

Parámetros

  • leadIdconsulta · string

    Negocios de un contacto (no se combina con los demás filtros).

  • pipelineIdconsulta · string
  • statusconsulta · "open" | "won" | "lost"
  • ownerEmailconsulta · string (email)
  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • titlestringobligatorio
  • leadIdstringobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • pipelineIdstringobligatorio
  • stageIdstringobligatorio
  • status"open" | "won" | "lost"obligatorio
  • valuenumber | nullobligatorio
  • currencystringobligatorio
  • probabilitynumber | nullobligatorio
  • expectedCloseDatestring (date-time) | nullobligatorio
  • recurrence"none" | "monthly" | "yearly"obligatorio
  • ownerEmailstring | nullobligatorio
  • ownerNamestring | nullobligatorio
  • isPrimarybooleanobligatorio
  • stageEnteredAtstring (date-time) | nullobligatorio
  • lastActivityAtstring (date-time) | nullobligatorio
  • closedAtstring (date-time) | nullobligatorio
  • lostReasonIdstring | nullobligatorio
  • lostReasonLabelstring | nullobligatorio
  • lostNotestring | nullobligatorio
  • customFieldsobjectobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/dealsdeals:write

Crear un negocio

Por defecto, pipeline predeterminado y su primera etapa abierta. Con `Idempotency-Key`, un reintento devuelve el mismo negocio (200).

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • titlestringobligatorio
  • leadIdstringobligatorio
  • pipelineIdstring
  • stageIdstring
  • valuenumber | null
  • currencystring
  • probabilityinteger | null
  • expectedCloseDatestring | null
  • ownerEmailstring | null
  • organizationIdstring | null
  • recurrence"none" | "monthly" | "yearly"
  • customFieldsobject

Respuesta 201 · { data }

  • idstringobligatorio
  • titlestringobligatorio
  • leadIdstringobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • pipelineIdstringobligatorio
  • stageIdstringobligatorio
  • status"open" | "won" | "lost"obligatorio
  • valuenumber | nullobligatorio
  • currencystringobligatorio
  • probabilitynumber | nullobligatorio
  • expectedCloseDatestring (date-time) | nullobligatorio
  • recurrence"none" | "monthly" | "yearly"obligatorio
  • ownerEmailstring | nullobligatorio
  • ownerNamestring | nullobligatorio
  • isPrimarybooleanobligatorio
  • stageEnteredAtstring (date-time) | nullobligatorio
  • lastActivityAtstring (date-time) | nullobligatorio
  • closedAtstring (date-time) | nullobligatorio
  • lostReasonIdstring | nullobligatorio
  • lostReasonLabelstring | nullobligatorio
  • lostNotestring | nullobligatorio
  • customFieldsobjectobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/deals/{id}deals:read

Leer un negocio

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

Respuesta 200 · { data }

  • idstringobligatorio
  • titlestringobligatorio
  • leadIdstringobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • pipelineIdstringobligatorio
  • stageIdstringobligatorio
  • status"open" | "won" | "lost"obligatorio
  • valuenumber | nullobligatorio
  • currencystringobligatorio
  • probabilitynumber | nullobligatorio
  • expectedCloseDatestring (date-time) | nullobligatorio
  • recurrence"none" | "monthly" | "yearly"obligatorio
  • ownerEmailstring | nullobligatorio
  • ownerNamestring | nullobligatorio
  • isPrimarybooleanobligatorio
  • stageEnteredAtstring (date-time) | nullobligatorio
  • lastActivityAtstring (date-time) | nullobligatorio
  • closedAtstring (date-time) | nullobligatorio
  • lostReasonIdstring | nullobligatorio
  • lostReasonLabelstring | nullobligatorio
  • lostNotestring | nullobligatorio
  • customFieldsobjectobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
patch/api/v1/deals/{id}deals:write

Actualizar un negocio

No cambia etapa ni estado (`move`, `close`, `reopen`). 409 `rev_mismatch` con un `expectedRev` viejo.

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • titlestring
  • valuenumber | null
  • currencystring
  • probabilityinteger | null
  • expectedCloseDatestring | null
  • ownerEmailstring | null
  • organizationIdstring | null
  • recurrence"none" | "monthly" | "yearly"
  • customFieldsobject
  • isPrimarytrue
  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • titlestringobligatorio
  • leadIdstringobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • pipelineIdstringobligatorio
  • stageIdstringobligatorio
  • status"open" | "won" | "lost"obligatorio
  • valuenumber | nullobligatorio
  • currencystringobligatorio
  • probabilitynumber | nullobligatorio
  • expectedCloseDatestring (date-time) | nullobligatorio
  • recurrence"none" | "monthly" | "yearly"obligatorio
  • ownerEmailstring | nullobligatorio
  • ownerNamestring | nullobligatorio
  • isPrimarybooleanobligatorio
  • stageEnteredAtstring (date-time) | nullobligatorio
  • lastActivityAtstring (date-time) | nullobligatorio
  • closedAtstring (date-time) | nullobligatorio
  • lostReasonIdstring | nullobligatorio
  • lostReasonLabelstring | nullobligatorio
  • lostNotestring | nullobligatorio
  • customFieldsobjectobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/deals/{id}/movedeals:write

Mover de etapa

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • toStageIdstringobligatorio
  • toPipelineIdstring
  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • titlestringobligatorio
  • leadIdstringobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • pipelineIdstringobligatorio
  • stageIdstringobligatorio
  • status"open" | "won" | "lost"obligatorio
  • valuenumber | nullobligatorio
  • currencystringobligatorio
  • probabilitynumber | nullobligatorio
  • expectedCloseDatestring (date-time) | nullobligatorio
  • recurrence"none" | "monthly" | "yearly"obligatorio
  • ownerEmailstring | nullobligatorio
  • ownerNamestring | nullobligatorio
  • isPrimarybooleanobligatorio
  • stageEnteredAtstring (date-time) | nullobligatorio
  • lastActivityAtstring (date-time) | nullobligatorio
  • closedAtstring (date-time) | nullobligatorio
  • lostReasonIdstring | nullobligatorio
  • lostReasonLabelstring | nullobligatorio
  • lostNotestring | nullobligatorio
  • customFieldsobjectobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/deals/{id}/closedeals:write

Ganar o perder

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • outcome"won" | "lost"obligatorio
  • stageIdstring
  • valuenumber | null
  • closedAtstring
  • lostReasonIdstring | null
  • lostNotestring | null
  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • titlestringobligatorio
  • leadIdstringobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • pipelineIdstringobligatorio
  • stageIdstringobligatorio
  • status"open" | "won" | "lost"obligatorio
  • valuenumber | nullobligatorio
  • currencystringobligatorio
  • probabilitynumber | nullobligatorio
  • expectedCloseDatestring (date-time) | nullobligatorio
  • recurrence"none" | "monthly" | "yearly"obligatorio
  • ownerEmailstring | nullobligatorio
  • ownerNamestring | nullobligatorio
  • isPrimarybooleanobligatorio
  • stageEnteredAtstring (date-time) | nullobligatorio
  • lastActivityAtstring (date-time) | nullobligatorio
  • closedAtstring (date-time) | nullobligatorio
  • lostReasonIdstring | nullobligatorio
  • lostReasonLabelstring | nullobligatorio
  • lostNotestring | nullobligatorio
  • customFieldsobjectobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/deals/{id}/reopendeals:write

Reabrir

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • toStageIdstringobligatorio
  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • titlestringobligatorio
  • leadIdstringobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • organizationIdstring | nullobligatorio
  • organizationNamestring | nullobligatorio
  • pipelineIdstringobligatorio
  • stageIdstringobligatorio
  • status"open" | "won" | "lost"obligatorio
  • valuenumber | nullobligatorio
  • currencystringobligatorio
  • probabilitynumber | nullobligatorio
  • expectedCloseDatestring (date-time) | nullobligatorio
  • recurrence"none" | "monthly" | "yearly"obligatorio
  • ownerEmailstring | nullobligatorio
  • ownerNamestring | nullobligatorio
  • isPrimarybooleanobligatorio
  • stageEnteredAtstring (date-time) | nullobligatorio
  • lastActivityAtstring (date-time) | nullobligatorio
  • closedAtstring (date-time) | nullobligatorio
  • lostReasonIdstring | nullobligatorio
  • lostReasonLabelstring | nullobligatorio
  • lostNotestring | nullobligatorio
  • customFieldsobjectobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/pipelinesdeals:read

Listar pipelines (solo lectura)

Markdown de este endpoint

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • namestringobligatorio
  • kind"sales" | "donation" | "membership" | "enrollment"obligatorio
  • activebooleanobligatorio
  • isDefaultbooleanobligatorio
  • defaultCurrencystringobligatorio
  • requireLostReasonbooleanobligatorio
  • lostReasonsobject[]obligatorio
    • idstringobligatorio
    • labelstringobligatorio
    • activebooleanobligatorio
  • stagesobject[]obligatorio
    • idstringobligatorio
    • namestringobligatorio
    • type"open" | "won" | "lost"obligatorio
    • ordernumberobligatorio
    • probabilitynumberobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.

Etiquetas

post/api/v1/integrations/beschool/periodscontacts:write

Organizar los periodos de Be School

Solo el conector OAuth oficial de Be School. Crea etiquetas estables por escuela y periodo. `createSegment:true` exige además `segments:write` y crea o actualiza un segmento gestionado con cualquiera de las etiquetas; consume un segmento del plan solo al crearlo. Una lista vacía nunca crea un segmento y vacía/pausa el que ya gestionaba. No activa contactos ni envía campañas.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • schoolIdstringobligatorio
  • schoolNamestringobligatorio
  • periodsobject[]obligatorio
    • idstringobligatorio
    • namestringobligatorio
  • createSegmentbooleanobligatorio

Respuesta 200 · { data }

  • periodsobject[]obligatorio
    • idstringobligatorio
    • tagstringobligatorio
  • segmentobject | nullobligatorio
    • idstringobligatorio
    • namestringobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/tagscontacts:read

Listar etiquetas

Markdown de este endpoint

Parámetros

  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • namestringobligatorio
  • totalinteger | nullobligatorio
  • activeinteger | nullobligatorio
  • inactiveinteger | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/tagscontacts:write

Crear una etiqueta

Si ya existe (sin distinguir mayúsculas) devuelve la existente con 200.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • namestringobligatorio

Respuesta 201 · { data }

  • idstringobligatorio
  • namestringobligatorio
  • totalinteger | nullobligatorio
  • activeinteger | nullobligatorio
  • inactiveinteger | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.

Conversaciones

get/api/v1/messaging/whatsapp/groupsconversations:read

Consultar grupos

Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, un `phoneNumberId` fuera del alcance responde 403 `forbidden` con `details.reason: "channel_not_allowed"`.

Markdown de este endpoint

Parámetros

  • phoneNumberIdconsulta · stringobligatorio

Respuesta 200 · { data }

  • groupsobject[]obligatorio
    • groupIdstringobligatorio
    • phoneNumberIdstring | nullobligatorio
    • subjectstringobligatorio
    • descriptionstring | nullobligatorio
    • groupStatus"active" | "suspended" | "deleted"obligatorio
    • participantCountintegerobligatorio
    • inviteLinkstring | nullobligatorio
    • participantsobject[]obligatorio
      • waIdstring | nullobligatorio
      • userIdstring | nullobligatorio
      • leadIdstring | nullobligatorio
      • namestring | nullobligatorio
      • leadNamestring | nullobligatorio
  • deletedobject[]obligatorio
    • groupIdstringobligatorio
    • phoneNumberIdstring | nullobligatorio
    • subjectstringobligatorio
    • descriptionstring | nullobligatorio
    • groupStatus"active" | "suspended" | "deleted"obligatorio
    • participantCountintegerobligatorio
    • inviteLinkstring | nullobligatorio
    • participantsobject[]obligatorio
      • waIdstring | nullobligatorio
      • userIdstring | nullobligatorio
      • leadIdstring | nullobligatorio
      • namestring | nullobligatorio
      • leadNamestring | nullobligatorio
  • requestsobject[]obligatorio
    • requestIdstringobligatorio
    • groupIdstring | nullobligatorio
    • status"pending" | "created" | "failed"obligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/messaging/whatsapp/groupswhatsapp_groups:manage

Crear un grupo

Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, un `phoneNumberId` fuera del alcance responde 403 `forbidden` con `details.reason: "channel_not_allowed"`.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • phoneNumberIdstringobligatorio
  • subjectstringobligatorio
  • descriptionstring
  • joinApprovalMode"auto_approve" | "approval_required"

Respuesta 202 · { data }

  • requestIdstringobligatorio
  • groupIdstring | nullobligatorio
  • status"pending" | "created" | "failed"obligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/messaging/whatsapp/groups/{groupId}conversations:read

Consultar un grupo

Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).

Markdown de este endpoint

Parámetros

  • groupIdruta · stringobligatorio

Respuesta 200 · { data }

  • groupIdstringobligatorio
  • phoneNumberIdstring | nullobligatorio
  • subjectstringobligatorio
  • descriptionstring | nullobligatorio
  • groupStatus"active" | "suspended" | "deleted"obligatorio
  • participantCountintegerobligatorio
  • inviteLinkstring | nullobligatorio
  • participantsobject[]obligatorio
    • waIdstring | nullobligatorio
    • userIdstring | nullobligatorio
    • leadIdstring | nullobligatorio
    • namestring | nullobligatorio
    • leadNamestring | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
patch/api/v1/messaging/whatsapp/groups/{groupId}whatsapp_groups:manage

Cambiar un grupo

Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).

Markdown de este endpoint

Parámetros

  • groupIdruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • subjectstring
  • descriptionstring

Respuesta 202 · { data }

object

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
delete/api/v1/messaging/whatsapp/groups/{groupId}whatsapp_groups:manage

Borrar un grupo

Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).

Markdown de este endpoint

Parámetros

  • groupIdruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Respuesta 202 · { data }

object

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/messaging/whatsapp/groups/{groupId}/invitewhatsapp_groups:manage

Invitar contactos al grupo

Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).

Markdown de este endpoint

Parámetros

  • groupIdruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • leadIdsstring[]obligatorio
  • templateobjectobligatorio
    • namestringobligatorio
    • languagestring

Respuesta 200 · { data }

object

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/messaging/whatsapp/groups/{groupId}/pinswhatsapp_groups:manage

Fijar o desfijar un mensaje

Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).

Markdown de este endpoint

Parámetros

  • groupIdruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • messageIdstringobligatorio
  • operation"pin" | "unpin"obligatorio
  • expirationDaysinteger

Respuesta 200 · { data }

object

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/messaging/channelsconversations:read

Números e integraciones disponibles para mensajería.

WhatsApp y SMS incluyen números; Telegram incluye `bot` (el predeterminado, sin token), `bots` (todos los bots conectados) y numbers vacío. canReceive=null significa que la recepción no está verificada. SMS y Telegram admiten texto con enlaces, sin botones nativos. Con canales limitados, solo los números y bots del alcance.

Markdown de este endpoint

Respuesta 200 · { data: [ … ], nextCursor }

  • channel"whatsapp" | "sms" | "telegram"obligatorio
  • configuredbooleanobligatorio
  • botobject

    Telegram: el bot predeterminado (con canales limitados, el predeterminado del alcance).

    • usernamestring | nullobligatorio
    • canSendbooleanobligatorio
    • canReceiveboolean | nullobligatorio
  • botsobject[]

    Telegram: todos los bots conectados (los del alcance de la credencial).

    • botIdstringobligatorio

      Id numérico del bot (`telegram:{botId}` en los canales).

    • usernamestring | nullobligatorio
    • isDefaultbooleanobligatorio
    • canSendbooleanobligatorio
    • canReceiveboolean | nullobligatorio
  • numbersobject[]obligatorio
    • phoneNumberIdstringobligatorio
    • phoneNumberstring | nullobligatorio
    • wabaIdstring | nullobligatorio
    • isDefaultbooleanobligatorio
    • canSendbooleanobligatorio
    • canReceiveboolean | nullobligatorio
    • reasonstring | nullobligatorio
  • supportedMessageTypesstring[]obligatorio
  • balanceCentsnumber | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/messaging/messagesconversations:write

Enviar por WhatsApp, SMS o una conversación existente de Telegram.

Idempotency-Key obligatoria para evitar duplicados. Sin integración disponible: 403 feature_disabled. WhatsApp requiere plantilla fuera de la ventana. En WhatsApp/SMS el destino debe ser E.164. SMS admite hasta 1600 caracteres y consume saldo. Telegram requiere conversationId del workspace y texto de hasta 4096 caracteres; no admite teléfonos ni inicia chats nuevos, y responde por el bot de esa conversación. Con canales limitados (`key.channelScope`): un número pedido fuera del alcance → 403 `forbidden` con `details.reason: "channel_not_allowed"`; sin pedirlo, el predeterminado del alcance (si no hay ninguno, 403 `feature_disabled` con `details.reason: "channel_not_in_scope"`).

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • channel"whatsapp"obligatorio
  • tostring | string

    Teléfono E.164 o BSUID. Obligatorio salvo que vaya `userId`.

  • userIdstring

    BSUID de WhatsApp: país ISO, punto y alfanuméricos (p. ej. `US.13491208655302741918`).

  • phoneNumberIdstring
  • leadIdstring
  • messageobject | object | object | object | objectobligatorio
    • type"text"obligatorio
    • textstringobligatorio
    • previewUrlboolean

Respuesta 201 · { data }

  • conversationIdstringobligatorio
  • channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
  • messageIdstring | nullobligatorio
  • status"sent" | "queued"obligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla. `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
  • 409 `invalid_state`: Operación no válida en el estado actual. `conflict`: Conflicto con el estado actual (p. ej. ya existe). `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
  • 503 `unavailable`: Servicio no disponible temporalmente.
get/api/v1/messaging/whatsapp/templatesconversations:read

Plantillas de la WABA del número seleccionado.

Espejo local de Meta: incluye status, idioma, componentes y botones, el motivo de rechazo y la calidad, y si se creó por API (y por quién). Filtros exactos `name` y `status`. Solo APPROVED es enviable; Meta valida el estado definitivo. No incluye plantillas legacy cuya WABA no se conoce. Con canales limitados (`key.channelScope`), solo de la WABA de un número del alcance: un `phoneNumberId` fuera del alcance → 403 `forbidden` con `details.reason: "channel_not_allowed"`; sin pedirlo, el predeterminado del alcance (si no hay ninguno, 403 `feature_disabled` con `details.reason: "channel_not_in_scope"`).

Markdown de este endpoint

Parámetros

  • phoneNumberIdconsulta · string
  • nameconsulta · string
  • statusconsulta · string
  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • namestringobligatorio
  • languagestringobligatorio
  • statusstringobligatorio
  • categorystring | nullobligatorio
  • wabaIdstringobligatorio
  • componentsobject[]obligatorio
  • rejectedReasonstring | nullobligatorio
  • qualityRatingstring | nullobligatorio
  • requestedCategorystring | nullobligatorio
  • pendingCategoryobject | nullobligatorio
    • categorystringobligatorio
    • effectiveAtstring | nullobligatorio
  • createdVia"api" | "panel" | nullobligatorio
  • createdBystring | nullobligatorio
  • descriptionstring | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
put/api/v1/messaging/whatsapp/templates/{name}whatsapp_templates:write

Crear una plantilla de WhatsApp

Crea la plantilla `name` (+ `language`) en la WABA del número indicado (o del predeterminado) y la envía a revisión de Meta: 201 con `status` PENDING. Si ya existe con el mismo contenido, 200 con la actual (repetir es seguro); si existe con OTRO contenido, 409 `conflict` (Be CRM no la edita: editar una aprobada la devuelve a revisión). Si Meta la rechaza al crearla, 400 `invalid_request` con su motivo en `message`. Pasa los `example` a Meta: los exige para cada variable del cuerpo y para la parte variable de una URL. Queda visible en el panel como «Creada por API». Admite cabecera de texto, de ubicación o multimedia (IMAGE, VIDEO, DOCUMENT), variables posicionales o con nombre (`parameterFormat: NAMED`), botones de respuesta rápida, URL, teléfono y copiar código (cupón), ofertas por tiempo limitado, carruseles (CAROUSEL, 2–10 tarjetas) y plantillas de autenticación (botón OTP); las reglas de Meta se comprueban antes de llamarla (400 con el motivo). El archivo de ejemplo de una cabecera multimedia (también la de cada tarjeta) va por enlace https público en `example.header_url`: Be CRM lo descarga (sin redirecciones; tipos y tamaños de Meta) y lo sube a Meta; si no se puede descargar o no vale, 400 `invalid_request` con el motivo. El estado definitivo llega con la aprobación de Meta (consúltalo con `GET /api/v1/messaging/whatsapp/templates?name=`). Con canales limitados, solo en la WABA de un número del alcance (403 `channel_not_allowed` si `phoneNumberId` no lo está); la plantilla es de la WABA entera y la pueden usar sus demás números, también los de otras integraciones.

Markdown de este endpoint

Parámetros

  • nameruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • languagestringobligatorio
  • category"UTILITY" | "MARKETING" | "AUTHENTICATION"obligatorio
  • descriptionstring
  • phoneNumberIdstring
  • allowCategoryChangeboolean
  • parameterFormat"POSITIONAL" | "NAMED"
  • messageSendTtlSecondsinteger
  • componentsobject | object | object | object | object | object[]obligatorio
    • type"HEADER"obligatorio
    • format"TEXT" | "LOCATION" | "IMAGE" | "VIDEO" | "DOCUMENT"obligatorio
    • textstring
    • exampleobject
      • header_textstring[]
      • header_text_named_paramsobject[]
        • param_namestringobligatorio
        • examplestringobligatorio
      • header_urlstring

        Enlace https PÚBLICO del archivo de ejemplo (imagen JPG/PNG ≤ 5 MB, vídeo MP4 ≤ 9 MB, documento PDF ≤ 9 MB). Be CRM lo descarga (sin redirecciones, 15 s como mucho) y lo sube a Meta; se propone como cabecera al enviar.

Respuesta 200 · { data }

  • idstringobligatorio
  • namestringobligatorio
  • languagestringobligatorio
  • statusstringobligatorio
  • categorystring | nullobligatorio
  • wabaIdstringobligatorio
  • componentsobject[]obligatorio
  • rejectedReasonstring | nullobligatorio
  • qualityRatingstring | nullobligatorio
  • requestedCategorystring | nullobligatorio
  • pendingCategoryobject | nullobligatorio
    • categorystringobligatorio
    • effectiveAtstring | nullobligatorio
  • createdVia"api" | "panel" | nullobligatorio
  • createdBystring | nullobligatorio
  • descriptionstring | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
  • 503 `unavailable`: Servicio no disponible temporalmente.
get/api/v1/conversations/{id}/capabilitiesconversations:read

Disponibilidad del canal y ventana de respuesta WhatsApp.

Consulta informativa: el envío vuelve a validar integración, ventana, cuota, saldo y proveedor. La ventana abre con el último mensaje del contacto, nunca con un mensaje saliente. SMS y Telegram no requieren plantilla ni ventana.

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

    `{canal}__{id}` (p. ej. `whatsapp__573001234567`).

Respuesta 200 · { data }

  • conversationIdstringobligatorio
  • channel"whatsapp" | "sms" | "telegram"obligatorio
  • checkedAtstring (date-time)obligatorio
  • phoneNumberIdstring | nullobligatorio
  • configuredbooleanobligatorio
  • canSendbooleanobligatorio
  • reasonstring | nullobligatorio
  • canSendDirectbooleanobligatorio
  • canSendTemplatebooleanobligatorio
  • supportedMessageTypesstring[]obligatorio
  • windowobject | nullobligatorio
    • lastInboundAtstring (date-time) | nullobligatorio
    • expiresAtstring (date-time) | nullobligatorio
    • openbooleanobligatorio
    • remainingSecondsintegerobligatorio
    • templateRequiredbooleanobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/conversationsconversations:read

Listar conversaciones

Las del workspace (no los buzones privados), por último mensaje. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar). Con canales limitados, solo las de los recursos del alcance (las de otro canal responden 404 en todas las rutas de conversación); con más de 30 recursos que listar, 400 `invalid_request` con `details.reason: "channel_scope_too_large"`: filtra por `channel`.

Markdown de este endpoint

Parámetros

  • statusconsulta · "open" | "closed" | "snoozed"
  • channelconsulta · "whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"
  • assigneeEmailconsulta · string (email)
  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
  • statusstringobligatorio
  • leadIdstring | nullobligatorio
  • contactNamestring | nullobligatorio
  • contactHandlestring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • lastMessagePreviewstring | nullobligatorio
  • lastMessageBystring | nullobligatorio
  • lastInboundAtstring (date-time) | nullobligatorio
  • awaitingReplybooleanobligatorio
  • unreadCountintegerobligatorio
  • botActivebooleanobligatorio
  • handoffOpenbooleanobligatorio
  • openTicketIdstring | nullobligatorio
  • snoozedUntilstring (date-time) | nullobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • fromUserIdstring | nullobligatorio

    Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.

  • fromUsernamestring | nullobligatorio

    Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/conversations/{id}conversations:read

Leer una conversación

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

    `{canal}__{id}` (p. ej. `whatsapp__573001234567`).

Respuesta 200 · { data }

  • idstringobligatorio
  • channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
  • statusstringobligatorio
  • leadIdstring | nullobligatorio
  • contactNamestring | nullobligatorio
  • contactHandlestring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • lastMessagePreviewstring | nullobligatorio
  • lastMessageBystring | nullobligatorio
  • lastInboundAtstring (date-time) | nullobligatorio
  • awaitingReplybooleanobligatorio
  • unreadCountintegerobligatorio
  • botActivebooleanobligatorio
  • handoffOpenbooleanobligatorio
  • openTicketIdstring | nullobligatorio
  • snoozedUntilstring (date-time) | nullobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • fromUserIdstring | nullobligatorio

    Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.

  • fromUsernamestring | nullobligatorio

    Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/conversations/{id}/messagesconversations:read

Mensajes de una conversación

Del más reciente al más antiguo, sin notas internas.

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

    `{canal}__{id}` (p. ej. `whatsapp__573001234567`).

  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • direction"inbound" | "outbound"obligatorio
  • textstringobligatorio
  • subjectstring | nullobligatorio

    Solo correo.

  • atstring (date-time) | nullobligatorio
  • senderobjectobligatorio
    • type"contact" | "user" | "bot" | "automation" | "api"obligatorio
    • emailstring | nullobligatorio
  • messageTypestring | null
  • deliveryStatusstring | null
  • errorobject | null

    Solo WhatsApp: por qué falló, cuando `deliveryStatus` es `failed` (el mismo `error` que el evento `message.status`); `null` si no hay error.

    • codestring | nullobligatorio

      Código de Meta, p. ej. `131042`.

    • titlestring | nullobligatorio

      Título que da Meta, p. ej. «Business eligibility payment issue».

  • replyToMessageIdstring | null
  • interactionobject | null
    • typestringobligatorio
    • idstring | nullobligatorio
    • titlestring | nullobligatorio
    • descriptionstring | nullobligatorio
  • attachmentobject | nullobligatorio
    • kindstringobligatorio
    • urlstring | nullobligatorio
    • namestring | nullobligatorio
  • templateobject | null

    Solo WhatsApp saliente: la plantilla que se envió y lo que vio el contacto, para pintar la burbuja como el Buzón («Plantilla · nombre» + cuerpo + pie + botones). `null` si el mensaje no es una plantilla. En los mensajes anteriores a guardar la vista de la plantilla solo llegan `name` y `language` (sin cuerpo, cabecera, pie ni botones): el texto sigue en `text`.

    • namestringobligatorio

      Nombre de la plantilla en Meta, p. ej. `be_pedir_resena_v2`.

    • languagestring | nullobligatorio

      Idioma con el que se envió, p. ej. `es`.

    • headerstring | nullobligatorio

      Texto de la cabecera, con sus variables ya sustituidas; `null` si no tiene o no es de texto (imagen, vídeo, documento o ubicación).

    • bodystring | nullobligatorio

      Cuerpo tal como lo vio el contacto, sin cabecera ni pie. `null` si no se guardó: entonces el texto es `text` (que puede llevar cabecera y pie juntos).

    • footerstring | nullobligatorio

      Pie de la plantilla; `null` si no tiene o no se guardó.

    • buttonsobject[]obligatorio

      Botones en su orden. Los de copiar código y OTP salen sin el código (no se expone).

      • kind"url" | "phone" | "quick_reply" | "copy_code" | "otp" | "other"obligatorio
      • labelstringobligatorio

        Texto del botón, p. ej. «Dejar mi opinión».

      • urlstring | nullobligatorio

        Solo `url`: enlace http(s) con su variable ya sustituida; `null` si no se sabe.

      • phonestring | nullobligatorio

        Solo `phone`: teléfono (`+` y dígitos).

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/conversations/{id}/replyconversations:write

Responder

Texto por el canal de la conversación y SIEMPRE desde su recurso (número, buzón o bot; una conversación de otro canal que el de la credencial responde 404) (WhatsApp: dentro de la ventana de 24 h; fuera, `template`). Cuota de cada canal: WhatsApp y correo del plan, SMS del saldo (402). 201 enviado; 202 correo encolado. 409 `unknown_outcome`: el proveedor no respondió y el mensaje pudo salir; con la misma Idempotency-Key se repite esa respuesta sin reenviar. 403 `forbidden` (`sending_paused`): el envío de correo del workspace está pausado. 402 `contact_limit_exceeded`: el workspace superó su límite de contactos (contestar a mano desde el panel sigue permitido).

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

    `{canal}__{id}` (p. ej. `whatsapp__573001234567`).

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • textstring
  • templateobject
    • namestringobligatorio
    • languagestring

      Código exacto de Meta (`es`, `es_MX`…).

    • componentsobject[]
  • messageobject | object | object | object | object

    Solo WhatsApp: texto, plantilla, imagen, audio, botones, lista o enlace CTA.

    • type"text"obligatorio
    • textstringobligatorio
    • previewUrlboolean

Respuesta 201 · { data }

  • conversationIdstringobligatorio
  • channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
  • messageIdstring | nullobligatorio
  • status"sent" | "queued"obligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla). `quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
  • 503 `unavailable`: Servicio no disponible temporalmente.
post/api/v1/conversations/{id}/assignconversations:write

Asignar

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

    `{canal}__{id}` (p. ej. `whatsapp__573001234567`).

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • assigneeEmailstring (email) | nullobligatorio

    `null` la deja sin responsable.

  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
  • statusstringobligatorio
  • leadIdstring | nullobligatorio
  • contactNamestring | nullobligatorio
  • contactHandlestring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • lastMessagePreviewstring | nullobligatorio
  • lastMessageBystring | nullobligatorio
  • lastInboundAtstring (date-time) | nullobligatorio
  • awaitingReplybooleanobligatorio
  • unreadCountintegerobligatorio
  • botActivebooleanobligatorio
  • handoffOpenbooleanobligatorio
  • openTicketIdstring | nullobligatorio
  • snoozedUntilstring (date-time) | nullobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • fromUserIdstring | nullobligatorio

    Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.

  • fromUsernamestring | nullobligatorio

    Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/conversations/{id}/closeconversations:write

Cerrar

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

    `{canal}__{id}` (p. ej. `whatsapp__573001234567`).

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
  • statusstringobligatorio
  • leadIdstring | nullobligatorio
  • contactNamestring | nullobligatorio
  • contactHandlestring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • lastMessagePreviewstring | nullobligatorio
  • lastMessageBystring | nullobligatorio
  • lastInboundAtstring (date-time) | nullobligatorio
  • awaitingReplybooleanobligatorio
  • unreadCountintegerobligatorio
  • botActivebooleanobligatorio
  • handoffOpenbooleanobligatorio
  • openTicketIdstring | nullobligatorio
  • snoozedUntilstring (date-time) | nullobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • fromUserIdstring | nullobligatorio

    Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.

  • fromUsernamestring | nullobligatorio

    Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/conversations/{id}/reopenconversations:write

Reabrir

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

    `{canal}__{id}` (p. ej. `whatsapp__573001234567`).

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
  • statusstringobligatorio
  • leadIdstring | nullobligatorio
  • contactNamestring | nullobligatorio
  • contactHandlestring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • lastMessagePreviewstring | nullobligatorio
  • lastMessageBystring | nullobligatorio
  • lastInboundAtstring (date-time) | nullobligatorio
  • awaitingReplybooleanobligatorio
  • unreadCountintegerobligatorio
  • botActivebooleanobligatorio
  • handoffOpenbooleanobligatorio
  • openTicketIdstring | nullobligatorio
  • snoozedUntilstring (date-time) | nullobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • fromUserIdstring | nullobligatorio

    Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.

  • fromUsernamestring | nullobligatorio

    Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.

Clave

get/api/v1/mecualquier alcance

Comprobar la clave

Devuelve la clave (sin secreto), el workspace y el estado de correo, SMS, WhatsApp y Telegram, con disponibilidad del plan, permisos y enlaces de configuración. Vale con cualquier alcance. Es una foto de la configuración guardada, sin consultar proveedores ni garantizar entrega. `key.channelScope` (y `integrations.channelScope`) dice a qué canales se limita la credencial (`null` = todos); con límite, los recuentos son solo de esos canales.

Markdown de este endpoint

Respuesta 200 · { data }

  • integrationsobjectobligatorio
    • checkedAtstring (date-time)obligatorio
    • source"crm_configuration"obligatorio
    • channelScopestring[] | null

      Canales a los que se limita la credencial (`whatsapp:{phoneNumberId}`, `email:{identityId}`, `sms:{smsNumberId}`, `telegram:{botId}`); null = todos. Los recuentos de cada canal son solo de esos recursos.

    • emailobjectobligatorio
      • availablebooleanobligatorio

        El plan incluye este canal.

      • configuredbooleanobligatorio

        Hay configuración utilizable guardada en BeCRM.

      • activebooleanobligatorio

        Configurado y disponible en el plan; no garantiza entrega del proveedor.

      • status"active" | "not_configured" | "configuration_pending" | "plan_required"obligatorio
      • reasonstring | nullobligatorio
      • canReceiveboolean | nullobligatorio

        null indica recepción sin confirmar.

      • apiCanSendbooleanobligatorio

        Canal activo y permiso de envío autorizado; cuotas y proveedor se validan al enviar.

      • configurationUrlstring (uri)obligatorio
      • verifiedbooleanobligatorio
      • identitiesCountintegerobligatorio
      • verifiedSendersCountintegerobligatorio
      • verifiedDomainsCountintegerobligatorio
    • smsobjectobligatorio
      • availablebooleanobligatorio

        El plan incluye este canal.

      • configuredbooleanobligatorio

        Hay configuración utilizable guardada en BeCRM.

      • activebooleanobligatorio

        Configurado y disponible en el plan; no garantiza entrega del proveedor.

      • status"active" | "not_configured" | "configuration_pending" | "plan_required"obligatorio
      • reasonstring | nullobligatorio
      • canReceiveboolean | nullobligatorio

        null indica recepción sin confirmar.

      • apiCanSendbooleanobligatorio

        Canal activo y permiso de envío autorizado; cuotas y proveedor se validan al enviar.

      • configurationUrlstring (uri)obligatorio
      • numbersCountintegerobligatorio
      • activeNumbersCountintegerobligatorio
    • whatsappobjectobligatorio
      • availablebooleanobligatorio

        El plan incluye este canal.

      • configuredbooleanobligatorio

        Hay configuración utilizable guardada en BeCRM.

      • activebooleanobligatorio

        Configurado y disponible en el plan; no garantiza entrega del proveedor.

      • status"active" | "not_configured" | "configuration_pending" | "plan_required"obligatorio
      • reasonstring | nullobligatorio
      • canReceiveboolean | nullobligatorio

        null indica recepción sin confirmar.

      • apiCanSendbooleanobligatorio

        Canal activo y permiso de envío autorizado; cuotas y proveedor se validan al enviar.

      • configurationUrlstring (uri)obligatorio
      • accountsCountintegerobligatorio
      • numbersCountintegerobligatorio
      • activeNumbersCountintegerobligatorio
    • telegramobjectobligatorio
      • availablebooleanobligatorio

        El plan incluye este canal.

      • configuredbooleanobligatorio

        Hay configuración utilizable guardada en BeCRM.

      • activebooleanobligatorio

        Configurado y disponible en el plan; no garantiza entrega del proveedor.

      • status"active" | "not_configured" | "configuration_pending" | "plan_required"obligatorio
      • reasonstring | nullobligatorio
      • canReceiveboolean | nullobligatorio

        null indica recepción sin confirmar.

      • apiCanSendbooleanobligatorio

        Canal activo y permiso de envío autorizado; cuotas y proveedor se validan al enviar.

      • configurationUrlstring (uri)obligatorio
      • botConnectedbooleanobligatorio
      • webhookRegisteredboolean | nullobligatorio
  • keyobjectobligatorio
    • idstringobligatorio
    • namestringobligatorio
    • prefixstringobligatorio
    • scopesstring[]obligatorio
    • expiresAtstring (date-time) | nullobligatorio
    • createdAtstring (date-time) | nullobligatorio
    • rateLimitPerMinuteintegerobligatorio
    • channelScopestring[] | nullobligatorio

      Canales a los que se limita la credencial (`whatsapp:{phoneNumberId}`, `email:{identityId}`, `sms:{smsNumberId}`, `telegram:{botId}`); null = todos los del workspace.

  • workspaceobjectobligatorio
    • idstringobligatorio
    • namestring | nullobligatorio
    • planstringobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.

Actividades y tareas

get/api/v1/assigneesactivities:read

Responsables activos disponibles

Catálogo paginado del roster: miembros activos con acceso completo y no pausados. email verifica también una membresía legacy; el roster canónico prevalece. Solo devuelve email y nombre.

Markdown de este endpoint

Parámetros

  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

  • emailconsulta · string (email)

Respuesta 200 · { data: [ … ], nextCursor }

  • emailobjetoobligatorio
  • namestring | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/activitiesactivities:read

Línea de tiempo de un contacto o negocio

Llamadas, reuniones registradas e hitos (negocio, ticket, conversación). Las notas, en `GET /api/v1/contacts/{id}/notes`. Por `dealId`, con los negocios apagados: 403 `feature_disabled`.

Markdown de este endpoint

Parámetros

  • leadIdconsulta · string
  • dealIdconsulta · string
  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • typestringobligatorio
  • leadIdstringobligatorio
  • dealIdstring | nullobligatorio
  • titlestringobligatorio
  • bodystring | nullobligatorio
  • occurredAtstring (date-time) | nullobligatorio
  • actorobjectobligatorio
    • typestringobligatorio
    • emailstring | nullobligatorio
    • namestring | nullobligatorio
  • callobject | nullobligatorio
    • directionstringobligatorio
    • outcomestringobligatorio
    • durationSecnumber | nullobligatorio
  • meetingobject | nullobligatorio
    • startAtstring (date-time) | nullobligatorio
    • endAtstring (date-time) | nullobligatorio
    • locationstring | nullobligatorio
    • outcomestringobligatorio
  • externalIdstring | nullobligatorio

    `externalId` de la app que la creó, o `null`.

  • externalUrlstring | nullobligatorio
  • createdAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/activitiesactivities:write

Crear nota, tarea, llamada o reunión (o actualizar la reunión de otra app)

Mismo cuerpo que el panel (`type`: note, task, call, meeting con `meeting:{…}`). Una tarea necesita `assignedToEmail`. Con `Idempotency-Key`, el documento tiene id determinista (un reintento responde 200 con `alreadyExisted`). Con `dealId` y los negocios apagados: 403 `feature_disabled`. Reunión de otra app: forma plana con `contactId`, `startAt`, `endAt`, `outcome` (`scheduled`, `held`, `no_show`, `canceled`, `rescheduled`), `note`, `externalId` y `externalUrl`; repetir con el mismo `externalId` (misma aplicación o clave) actualiza la reunión (200, `updated`) en vez de duplicarla; con otro contacto, 409 `invalid_state`.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • leadIdstringobligatorio
  • dealIdstring | null
  • titlestring
  • bodystring | null
  • type"note"obligatorio
  • pinnedboolean

Respuesta 200 · { data }

  • idstringobligatorio
  • type"note" | "task" | "call" | "meeting"obligatorio
  • storestringobligatorio

    Dónde vive: `activities`, `notes` (del contacto), `reminders` o `restrictedActivities` (reunión restringida).

  • leadIdstringobligatorio
  • nextStepTaskIdstring | nullobligatorio
  • alreadyExistedbooleanobligatorio
  • externalIdstring

    Solo en una reunión con `externalId`.

  • updatedboolean

    Con `externalId` y `alreadyExisted`: si esta llamada cambió algo.

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/tasksactivities:read

Listar tareas

De un contacto (`leadId`) o del workspace: abiertas por vencimiento (`status=open`, con `assignedToEmail` opcional), hechas (`status=done`) o todas.

Markdown de este endpoint

Parámetros

  • leadIdconsulta · string

    Tareas de un contacto.

  • assignedToEmailconsulta · string (email)
  • statusconsulta · "open" | "done"

    Sin él, todas por fecha de vencimiento.

  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • leadIdstringobligatorio
  • leadNamestring | nullobligatorio
  • titlestringobligatorio
  • contentstring | nullobligatorio
  • typestring | nullobligatorio
  • prioritystring | nullobligatorio
  • dueAtstring (date-time) | nullobligatorio
  • doneAtstring (date-time) | nullobligatorio
  • assignedToEmailstring | nullobligatorio
  • assignedToNamestring | nullobligatorio
  • dealIdstring | nullobligatorio
  • createdAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/contacts/{id}/tasks/{taskId}/completeactivities:write

Completar (o reabrir) una tarea

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • taskIdruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • doneboolean

    `false` la reabre. Por defecto `true`.

Respuesta 200 · { data }

  • idstringobligatorio
  • leadIdstringobligatorio
  • leadNamestring | nullobligatorio
  • titlestringobligatorio
  • contentstring | nullobligatorio
  • typestring | nullobligatorio
  • prioritystring | nullobligatorio
  • dueAtstring (date-time) | nullobligatorio
  • doneAtstring (date-time) | nullobligatorio
  • assignedToEmailstring | nullobligatorio
  • assignedToNamestring | nullobligatorio
  • dealIdstring | nullobligatorio
  • createdAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.

Correo

post/api/v1/emailsemails:send

Enviar un correo

Con plantilla (`template.name` = `sesTemplateId`) o con `subject` + `html`/`text`. Consume 1 de la cuota mensual (cc y bcc incluidos) y responde 402 `quota_exceeded` al agotarla; con el workspace bloqueado por el límite de contactos, 402 `contact_limit_exceeded` (antes que la cuota; reintentar no sirve: hay que subir de plan o de tramo). Los errores del remitente, la plantilla y `contactId` (400/404/409) llegan antes que los 402. `contactId` asocia el envío a un contacto que ya existe y cuyo correo es `to` (si no, 400/409): no crea ni cambia contactos. 202: encolado. Con canales limitados, el remitente por defecto es el primero verificado del alcance; un `senderId`/`from` fuera del alcance (una dirección con buzón cuenta como ese buzón aunque su dominio esté en el alcance) → 403 `forbidden` con `details.reason: "channel_not_allowed"`; sin ningún remitente en el alcance, 403 `feature_disabled` (`channel_not_in_scope`).

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • tostring (email)obligatorio

    Un único destinatario.

  • ccstring (email)[]
  • bccstring (email)[]
  • replyTostring (email)[]
  • fromstring (email)

    Remitente: una identidad verificada o una dirección de un dominio verificado.

  • senderIdstring

    Id de la identidad de envío (alternativa a `from`).

  • fromNamestring
  • subjectstring
  • htmlstring
  • textstring
  • templateobject
    • namestringobligatorio

      `sesTemplateId` de la plantilla.

    • dataobject
  • contactIdstring

    Contacto al que se asocia el envío.

  • marketingboolean

    Correo promocional (boletín, aviso masivo, oferta). Con `true`, un contacto dado de baja del correo da 409 `conflict` con `reason: "unsubscribed"` y no se envía; si sale, lleva la baja en un clic. Sin él, transaccional.

Respuesta 202 · { data }

  • idstringobligatorio

    Id del envío (`jobId`).

  • status"queued"obligatorio
  • type"template" | "standard"obligatorio
  • queuedAtstring (date-time)obligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla). `quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
  • 503 `unavailable`: Servicio no disponible temporalmente.
get/api/v1/emails/historyemails:read

Recuperar historial de correo compartido

Importación a demanda. Incluye correos del workspace sin hilo o fecha; excluye buzones privados y errores de envío. Orden por ID, no cronológico. limit limita documentos examinados: una página puede estar vacía y tener nextCursor. Recorre hasta nextCursor=null. No descarga HTML externo ni adjuntos. El workspace bloqueado por contactos responde 402. Con canales limitados, solo los correos de los remitentes, buzones (no privados) y dominios del alcance.

Markdown de este endpoint

Parámetros

  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

  • directionconsulta · "inbound" | "outbound" | "all"

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • jobIdstring | nullobligatorio
  • messageIdstring | nullobligatorio
  • threadIdstring | nullobligatorio
  • direction"inbound" | "outbound"obligatorio
  • subjectstring | nullobligatorio
  • bodystringobligatorio
  • atstring (date-time) | nullobligatorio
  • fromstring | nullobligatorio
  • tostring | nullobligatorio
  • htmlAvailablebooleanobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/emails/sendersemails:send

Listar remitentes

Correos y dominios registrados para enviar, verificados o no (`verified`), para elegir el remitente de `POST /api/v1/emails`: el `id` de un correo es su `senderId`; con un dominio verificado vale `from` con cualquier dirección de ese dominio. Solo envían los verificados. Es una foto de la configuración guardada, sin consultar al proveedor. Con canales limitados, solo los del alcance.

Markdown de este endpoint

Respuesta 200 · { data }

  • sendersobject[]obligatorio

    Correos registrados uno a uno. Verificados primero; después, por correo.

    • idstringobligatorio

      Id de la identidad: el `senderId` de `POST /api/v1/emails`.

    • emailstringobligatorio
    • fromNamestring | nullobligatorio
    • verifiedbooleanobligatorio
  • domainsobject[]obligatorio

    Dominios registrados. Con uno verificado, cualquier dirección suya (o de un subdominio) sirve como `from` sin `senderId`. Verificados primero; después, por dominio.

    • idstringobligatorio
    • domainstringobligatorio

      En minúsculas.

    • verifiedbooleanobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/emails/{id}emails:read

Estado de un envío

Con canales limitados, un envío de un remitente fuera del alcance responde 404.

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

Respuesta 200 · { data }

  • idstringobligatorio
  • statusstringobligatorio

    queued, sent, delivered, bounced, complained, failed…

  • tostring | nullobligatorio
  • subjectstring | nullobligatorio
  • contactIdstring | nullobligatorio
  • queuedAtstring (date-time) | nullobligatorio
  • sentAtstring (date-time) | nullobligatorio
  • deliveredAtstring (date-time) | nullobligatorio
  • bouncedAtstring (date-time) | nullobligatorio
  • complainedAtstring (date-time) | nullobligatorio
  • openedAtstring (date-time) | nullobligatorio
  • clickedAtstring (date-time) | nullobligatorio
  • failureReasonstring | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
put/api/v1/emails/templates/{key}templates:write

Crear o actualizar una plantilla de la aplicación

Crea (201) o actualiza (200) la plantilla `key` de la aplicación en el workspace: el dueño es la aplicación OAuth (su cliente) o, con una clave v1, la clave. Repetir la llamada actualiza la MISMA plantilla. Queda publicada y visible en el panel; Be CRM añade el pie obligatorio (empresa y «Darse de baja»). Se envía con `POST /api/v1/emails` y `template.name` = `name` de la respuesta (`sesTemplateId`). No consume cuota. 400 si `key` o alguna `{{variable}}` no son válidas; 409 si ese id pertenece a otra aplicación; 503 si el proveedor de correo falla (no queda ninguna plantilla publicada a medias).

Markdown de este endpoint

Parámetros

  • keyruta · stringobligatorio

    Clave de la plantilla para la aplicación: `^[a-z0-9][a-z0-9._-]{0,63}$` (p. ej. `bechurch.felicitacion`). Una clave inválida responde 400.

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • namestringobligatorio

    Nombre visible en el panel de plantillas.

  • subjectstringobligatorio

    Asunto; admite `{{variables}}`.

  • htmlstringobligatorio

    HTML completo. El pie obligatorio (empresa y «Darse de baja») lo añade Be CRM.

  • textstring

    Versión de texto plano. Sin ella se deriva del HTML.

  • descriptionstring
  • previewTextstring

Respuesta 200 · { data }

  • keystringobligatorio
  • templateIdstringobligatorio

    Id de la plantilla en el workspace.

  • namestringobligatorio

    `sesTemplateId`: el `template.name` de `POST /api/v1/emails` para enviarla.

  • status"published"obligatorio
  • variablesstring[]obligatorio

    Variables de la plantilla (sin las del sistema: companyName, unsubscribeUrl…).

  • updatedAtstring (date-time)obligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
  • 503 `unavailable`: Servicio no disponible temporalmente.

Tickets

get/api/v1/ticketstickets:read

Listar tickets

Por estado, prioridad y responsable (combinables salvo prioridad + responsable) o por `leadId`. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).

Markdown de este endpoint

Parámetros

  • statusconsulta · "open" | "in_progress" | "waiting_customer" | "closed"
  • priorityconsulta · "low" | "medium" | "high" | "urgent"
  • assigneeEmailconsulta · string (email)
  • leadIdconsulta · string

    Tickets de un contacto (no se combina con los demás filtros).

  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • numberinteger | nullobligatorio
  • subjectstringobligatorio
  • descriptionstring | nullobligatorio
  • status"open" | "in_progress" | "waiting_customer" | "closed"obligatorio
  • priority"low" | "medium" | "high" | "urgent"obligatorio
  • channelstring | nullobligatorio
  • categorystring | nullobligatorio
  • tagsstring[]obligatorio
  • leadIdstring | nullobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • conversationIdstring | nullobligatorio
  • sourcestringobligatorio
  • slaDueAtstring (date-time) | nullobligatorio
  • slaBreachedbooleanobligatorio
  • firstResponseAtstring (date-time) | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • resolvedAtstring (date-time) | nullobligatorio
  • reopenCountintegerobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/ticketstickets:write

Crear un ticket

Con `Idempotency-Key`, un reintento devuelve el mismo ticket (200). `conversationId` tiene que ser una conversación del workspace (si no, 404); `originThread` de correo no se admite (400: usa `conversationId`).

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • subjectstringobligatorio
  • descriptionstring
  • leadIdstring | null
  • priority"low" | "medium" | "high" | "urgent"
  • status"open" | "in_progress" | "waiting_customer" | "closed"
  • channel"email" | "whatsapp" | "telegram" | "sms" | "whatsapp_group" | "slack" | "web_form" | "chat_ai" | "phone" | "manual" | null
  • categorystring | null
  • tagsstring[]
  • assigneeEmailstring | null
  • conversationIdstring | null
  • originThreadobject | null
    • idstringobligatorio
    • subjectstring
    • channel"email" | "whatsapp" | "telegram" | "sms" | "whatsapp_group" | "slack" | "web_form" | "chat_ai" | "phone" | "manual"obligatorio
  • attachmentsobject[]
    • namestringobligatorio
    • urlstring (uri)obligatorio
    • sizeinteger | null
    • typestring | null
  • ticketIdstring

Respuesta 201 · { data }

  • idstringobligatorio
  • numberinteger | nullobligatorio
  • subjectstringobligatorio
  • descriptionstring | nullobligatorio
  • status"open" | "in_progress" | "waiting_customer" | "closed"obligatorio
  • priority"low" | "medium" | "high" | "urgent"obligatorio
  • channelstring | nullobligatorio
  • categorystring | nullobligatorio
  • tagsstring[]obligatorio
  • leadIdstring | nullobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • conversationIdstring | nullobligatorio
  • sourcestringobligatorio
  • slaDueAtstring (date-time) | nullobligatorio
  • slaBreachedbooleanobligatorio
  • firstResponseAtstring (date-time) | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • resolvedAtstring (date-time) | nullobligatorio
  • reopenCountintegerobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/tickets/{id}tickets:read

Leer un ticket

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

Respuesta 200 · { data }

  • idstringobligatorio
  • numberinteger | nullobligatorio
  • subjectstringobligatorio
  • descriptionstring | nullobligatorio
  • status"open" | "in_progress" | "waiting_customer" | "closed"obligatorio
  • priority"low" | "medium" | "high" | "urgent"obligatorio
  • channelstring | nullobligatorio
  • categorystring | nullobligatorio
  • tagsstring[]obligatorio
  • leadIdstring | nullobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • conversationIdstring | nullobligatorio
  • sourcestringobligatorio
  • slaDueAtstring (date-time) | nullobligatorio
  • slaBreachedbooleanobligatorio
  • firstResponseAtstring (date-time) | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • resolvedAtstring (date-time) | nullobligatorio
  • reopenCountintegerobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
patch/api/v1/tickets/{id}tickets:write

Actualizar un ticket

`conversationId` tiene que ser una conversación del workspace (si no, 404).

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • subjectstring
  • descriptionstring
  • priority"low" | "medium" | "high" | "urgent"
  • channel"email" | "whatsapp" | "telegram" | "sms" | "whatsapp_group" | "slack" | "web_form" | "chat_ai" | "phone" | "manual" | null
  • categorystring | null
  • tagsstring[]
  • leadIdstring | null
  • conversationIdstring | null
  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • numberinteger | nullobligatorio
  • subjectstringobligatorio
  • descriptionstring | nullobligatorio
  • status"open" | "in_progress" | "waiting_customer" | "closed"obligatorio
  • priority"low" | "medium" | "high" | "urgent"obligatorio
  • channelstring | nullobligatorio
  • categorystring | nullobligatorio
  • tagsstring[]obligatorio
  • leadIdstring | nullobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • conversationIdstring | nullobligatorio
  • sourcestringobligatorio
  • slaDueAtstring (date-time) | nullobligatorio
  • slaBreachedbooleanobligatorio
  • firstResponseAtstring (date-time) | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • resolvedAtstring (date-time) | nullobligatorio
  • reopenCountintegerobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/tickets/{id}/statustickets:write

Cambiar el estado

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • status"open" | "in_progress" | "waiting_customer" | "closed"obligatorio
  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • numberinteger | nullobligatorio
  • subjectstringobligatorio
  • descriptionstring | nullobligatorio
  • status"open" | "in_progress" | "waiting_customer" | "closed"obligatorio
  • priority"low" | "medium" | "high" | "urgent"obligatorio
  • channelstring | nullobligatorio
  • categorystring | nullobligatorio
  • tagsstring[]obligatorio
  • leadIdstring | nullobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • conversationIdstring | nullobligatorio
  • sourcestringobligatorio
  • slaDueAtstring (date-time) | nullobligatorio
  • slaBreachedbooleanobligatorio
  • firstResponseAtstring (date-time) | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • resolvedAtstring (date-time) | nullobligatorio
  • reopenCountintegerobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/tickets/{id}/prioritytickets:write

Cambiar la prioridad

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • priority"low" | "medium" | "high" | "urgent"obligatorio
  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • numberinteger | nullobligatorio
  • subjectstringobligatorio
  • descriptionstring | nullobligatorio
  • status"open" | "in_progress" | "waiting_customer" | "closed"obligatorio
  • priority"low" | "medium" | "high" | "urgent"obligatorio
  • channelstring | nullobligatorio
  • categorystring | nullobligatorio
  • tagsstring[]obligatorio
  • leadIdstring | nullobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • conversationIdstring | nullobligatorio
  • sourcestringobligatorio
  • slaDueAtstring (date-time) | nullobligatorio
  • slaBreachedbooleanobligatorio
  • firstResponseAtstring (date-time) | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • resolvedAtstring (date-time) | nullobligatorio
  • reopenCountintegerobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/tickets/{id}/assigntickets:write

Asignar

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • assigneeEmailstring | nullobligatorio
  • expectedRevinteger

Respuesta 200 · { data }

  • idstringobligatorio
  • numberinteger | nullobligatorio
  • subjectstringobligatorio
  • descriptionstring | nullobligatorio
  • status"open" | "in_progress" | "waiting_customer" | "closed"obligatorio
  • priority"low" | "medium" | "high" | "urgent"obligatorio
  • channelstring | nullobligatorio
  • categorystring | nullobligatorio
  • tagsstring[]obligatorio
  • leadIdstring | nullobligatorio
  • leadNamestring | nullobligatorio
  • leadEmailstring | nullobligatorio
  • assigneeEmailstring | nullobligatorio
  • assigneeNamestring | nullobligatorio
  • conversationIdstring | nullobligatorio
  • sourcestringobligatorio
  • slaDueAtstring (date-time) | nullobligatorio
  • slaBreachedbooleanobligatorio
  • firstResponseAtstring (date-time) | nullobligatorio
  • lastMessageAtstring (date-time) | nullobligatorio
  • resolvedAtstring (date-time) | nullobligatorio
  • reopenCountintegerobligatorio
  • revintegerobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/tickets/{id}/commentstickets:write

Comentar

Nota interna o registro de una respuesta (`kind: reply`); no envía nada al cliente.

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • textstringobligatorio
  • kind"reply" | "internal_note"
  • attachmentsobject[]
    • namestringobligatorio
    • urlstring (uri)obligatorio
    • sizeinteger | null
    • typestring | null

Respuesta 201 · { data }

  • commentIdstringobligatorio
  • ticketobjectobligatorio
    • idstringobligatorio
    • numberinteger | nullobligatorio
    • subjectstringobligatorio
    • descriptionstring | nullobligatorio
    • status"open" | "in_progress" | "waiting_customer" | "closed"obligatorio
    • priority"low" | "medium" | "high" | "urgent"obligatorio
    • channelstring | nullobligatorio
    • categorystring | nullobligatorio
    • tagsstring[]obligatorio
    • leadIdstring | nullobligatorio
    • leadNamestring | nullobligatorio
    • leadEmailstring | nullobligatorio
    • assigneeEmailstring | nullobligatorio
    • assigneeNamestring | nullobligatorio
    • conversationIdstring | nullobligatorio
    • sourcestringobligatorio
    • slaDueAtstring (date-time) | nullobligatorio
    • slaBreachedbooleanobligatorio
    • firstResponseAtstring (date-time) | nullobligatorio
    • lastMessageAtstring (date-time) | nullobligatorio
    • resolvedAtstring (date-time) | nullobligatorio
    • reopenCountintegerobligatorio
    • revintegerobligatorio
    • createdAtstring (date-time) | nullobligatorio
    • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.

Reuniones

get/api/v1/meetingsmeetings:read

Listar reuniones

Las agendadas con el servicio de reservas, por fecha de inicio. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).

Markdown de este endpoint

Parámetros

  • fromconsulta · string (date) | string (date-time)

    Desde (inicio de la reunión).

  • toconsulta · string (date) | string (date-time)

    Hasta (inicio de la reunión).

  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • titlestringobligatorio
  • status"confirmed" | "canceled"obligatorio
  • sourcestringobligatorio
  • startAtstring (date-time) | nullobligatorio
  • endAtstring (date-time) | nullobligatorio
  • timeZonestring | nullobligatorio
  • hostEmailstring | nullobligatorio
  • hostNamestring | nullobligatorio
  • leadIdstring | nullobligatorio
  • dealIdstring | nullobligatorio
  • conversationIdstring | nullobligatorio
  • bookingTypeIdstring | nullobligatorio
  • attendeeobject | nullobligatorio
    • namestring | nullobligatorio
    • emailstring | nullobligatorio
    • phonestring | nullobligatorio
  • meetUrlstring | nullobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • canceledAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/meetings/{id}meetings:read

Leer una reunión

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio

Respuesta 200 · { data }

  • idstringobligatorio
  • titlestringobligatorio
  • status"confirmed" | "canceled"obligatorio
  • sourcestringobligatorio
  • startAtstring (date-time) | nullobligatorio
  • endAtstring (date-time) | nullobligatorio
  • timeZonestring | nullobligatorio
  • hostEmailstring | nullobligatorio
  • hostNamestring | nullobligatorio
  • leadIdstring | nullobligatorio
  • dealIdstring | nullobligatorio
  • conversationIdstring | nullobligatorio
  • bookingTypeIdstring | nullobligatorio
  • attendeeobject | nullobligatorio
    • namestring | nullobligatorio
    • emailstring | nullobligatorio
    • phonestring | nullobligatorio
  • meetUrlstring | nullobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • canceledAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/meetings/{id}/reschedulemeetings:write

Mover

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • startAtstring (date-time)obligatorio

Respuesta 200 · { data }

  • meetingIdstringobligatorio
  • status"confirmed" | "canceled"obligatorio
  • startAtstring (date-time)obligatorio
  • endAtstring (date-time)obligatorio
  • unchangedbooleanobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/meetings/{id}/cancelmeetings:write

Cancelar

Idempotente: cancelar otra vez responde `unchanged: true`.

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • reasonstring | null

Respuesta 200 · { data }

  • meetingIdstringobligatorio
  • status"confirmed" | "canceled"obligatorio
  • startAtstring (date-time)obligatorio
  • endAtstring (date-time)obligatorio
  • unchangedbooleanobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/booking-typesmeetings:read

Tipos de cita

Markdown de este endpoint

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • namestringobligatorio
  • durationMinintegerobligatorio
  • activebooleanobligatorio
  • locationstringobligatorio
  • hostMode"owner" | "fixed"obligatorio
  • windowDaysintegerobligatorio
  • minNoticeMinintegerobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/booking-types/{id}/slotsmeetings:read

Huecos libres

`id` = el tipo de cita o `default`. Hasta 6 huecos del anfitrión del contacto.

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • contactIdconsulta · stringobligatorio

    Contacto que reserva (define el anfitrión si el tipo es «del dueño»).

  • fromconsulta · string (date) | string (date-time)
  • toconsulta · string (date) | string (date-time)
  • localeconsulta · "es" | "en" | "pt"

Respuesta 200 · { data }

  • bookingTypeIdstringobligatorio
  • hostEmailstringobligatorio
  • hostNamestring | nullobligatorio
  • timeZonestringobligatorio
  • durationMinintegerobligatorio
  • slotsobject[]obligatorio
    • slotIdstringobligatorio

      Opaco: se manda tal cual a `book`.

    • startAtstring (date-time)obligatorio
    • endAtstring (date-time)obligatorio
    • labelstringobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
  • 503 `unavailable`: Servicio no disponible temporalmente.
post/api/v1/booking-types/{id}/bookmeetings:write

Reservar

Con un `slotId` de `slots`. 409 `conflict` (con `alternatives`) si el hueco se ocupó. Con `Idempotency-Key`, un reintento devuelve la misma reunión (200). `conversationId`: una conversación del workspace (si no, 404) y del mismo contacto (si no, 400).

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • contactIdstringobligatorio
  • slotIdstringobligatorio
  • attendeeEmailstring (email) | null

    Ausente = el correo del contacto; `null` = sin invitación de Google.

  • notesstring | null
  • conversationIdstring | null
  • locale"es" | "en" | "pt"

Respuesta 201 · { data }

  • meetingIdstringobligatorio
  • alreadyBookedbooleanobligatorio
  • startAtstring (date-time)obligatorio
  • endAtstring (date-time)obligatorio
  • labelstringobligatorio
  • timeZonestringobligatorio
  • hostEmailstringobligatorio
  • hostNamestring | nullobligatorio
  • attendeeEmailstring | nullobligatorio
  • meetUrlstring | nullobligatorio
  • confirmationstringobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
  • 503 `unavailable`: Servicio no disponible temporalmente.

Pagos

post/api/v1/paymentspayments:write

Registrar un pago

Alta o actualización por `(source, externalId)`: 201 la primera vez, 200 si ya existía (solo cambian `status` y `refundedMinor`; si no cambian, no hace nada). Cada transición emite `payment.succeeded`, `payment.failed` o `payment.refunded` (webhook y automatizaciones) y deja un hito en la ficha del contacto. Un conector oficial registra siempre con su `source`.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • externalIdstringobligatorio

    Id del pago en el sistema de origen (p. ej. `pi_…`). Con `source`, identifica el pago: repetir actualiza.

  • source"beschedule" | "beschool" | "besocial" | "stripe" | "other"obligatorio

    Origen. Un conector oficial (Be Schedule, Be School, Be Social) siempre registra con el suyo.

  • contactIdstring

    Contacto existente. Si no, `contact`.

  • contactobject

    Se busca por correo (sin distinguir mayúsculas) y luego por teléfono; si no existe, se crea un contacto pasivo (402 `contact_limit_exceeded` si el workspace está bloqueado).

    • emailstring (email)
    • phoneobject
      • phone_codestring
      • phonestringobligatorio
    • namestring
    • lastnamestring
  • amountMinorintegerobligatorio

    Importe en unidad menor (10,50 USD = 1050).

  • currencystringobligatorio

    ISO 4217 en MAYÚSCULAS.

  • status"succeeded" | "pending" | "failed" | "refunded" | "partially_refunded" | "disputed"obligatorio
  • refundedMinorinteger

    Reembolsado acumulado en unidad menor (por defecto 0).

  • descriptionstring

    Solo el nombre del producto o servicio. Nunca datos clínicos ni el motivo de una consulta.

  • occurredAtstring (date-time)

    Cuándo ocurrió el pago (por defecto, ahora).

  • dealIdstring

    Negocio del mismo contacto al que se asocia.

  • externalUrlstring (uri)

    Enlace al pago en el sistema de origen (https).

  • metadataobject

    Hasta 20 claves; valores de texto de hasta 500.

  • visibility"workspace" | "restricted"

    `restricted` (p. ej. una cita de salud): sin hito en la línea de tiempo, fuera de los «Pagos» del panel salvo para quien tiene el permiso de las notas restringidas, de `GET /api/v1/payments` salvo para la propia app o una clave con `sensitive:read`, y sus webhooks `payment.*` solo salen a destinos con `sensitive:read`. Se fija en el alta y solo puede cerrarse (`workspace` → `restricted`, que borra sus hitos), nunca abrirse. Un contacto nuevo creado por el pago no guarda el nombre de la app. Por defecto `workspace`.

Respuesta 200 · { data }

  • paymentobjectobligatorio
    • idstringobligatorio
    • externalIdstringobligatorio
    • source"beschedule" | "beschool" | "besocial" | "stripe" | "other"obligatorio
    • contactIdstringobligatorio
    • dealIdstring | nullobligatorio
    • amountMinorintegerobligatorio
    • currencystringobligatorio
    • status"succeeded" | "pending" | "failed" | "refunded" | "partially_refunded" | "disputed"obligatorio
    • refundedMinorintegerobligatorio
    • descriptionstring | nullobligatorio
    • occurredAtstring (date-time) | nullobligatorio
    • externalUrlstring | nullobligatorio
    • visibility"workspace" | "restricted"obligatorio
    • createdAtstring (date-time) | nullobligatorio
    • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `invalid_state`: Operación no válida en el estado actual. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/paymentspayments:read

Listar pagos

Más recientes primero; con `contactId`, los de ese contacto. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar).

Markdown de este endpoint

Parámetros

  • contactIdconsulta · string

    Pagos de un contacto (más recientes primero).

  • limitconsulta · string

    Elementos por página (1–100, por defecto 50).

  • cursorconsulta · string

    `nextCursor` de la página anterior (opaco).

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • externalIdstringobligatorio
  • source"beschedule" | "beschool" | "besocial" | "stripe" | "other"obligatorio
  • contactIdstringobligatorio
  • dealIdstring | nullobligatorio
  • amountMinorintegerobligatorio
  • currencystringobligatorio
  • status"succeeded" | "pending" | "failed" | "refunded" | "partially_refunded" | "disputed"obligatorio
  • refundedMinorintegerobligatorio
  • descriptionstring | nullobligatorio
  • occurredAtstring (date-time) | nullobligatorio
  • externalUrlstring | nullobligatorio
  • visibility"workspace" | "restricted"obligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.

Webhooks

get/api/v1/webhookswebhooks:manage

Listar destinos

Markdown de este endpoint

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • namestringobligatorio
  • urlstringobligatorio
  • descriptionstringobligatorio
  • eventsstring[]obligatorio
  • activebooleanobligatorio
  • secretSuffixstringobligatorio

    Últimos 4 caracteres del secreto de firma.

  • failureCountintegerobligatorio
  • lastEventAtstring (date-time) | nullobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/webhookswebhooks:manage

Crear un destino

La URL pasa la guarda SSRF (https en producción). El secreto de firma solo se devuelve aquí. Como mucho 20 destinos por workspace (409 `conflict`). Los eventos de donaciones (`donation.*`, `donation_plan.*`) exigen además el alcance `donations:read` y que quien creó la clave (o aprobó la aplicación) siga viendo las donaciones (403 `insufficient_scope`); cada entrega de esos eventos lo vuelve a comprobar y, si ya no se cumple, la omite.

Markdown de este endpoint

Parámetros

  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • namestringobligatorio
  • urlstring (uri)obligatorio
  • descriptionstring
  • eventsstring[]obligatorio

    Ids del catálogo (`GET /api/v1/webhooks/events`).

  • activeboolean

Respuesta 201 · { data }

  • idstringobligatorio
  • namestringobligatorio
  • urlstringobligatorio
  • descriptionstringobligatorio
  • eventsstring[]obligatorio
  • activebooleanobligatorio
  • secretSuffixstringobligatorio

    Últimos 4 caracteres del secreto de firma.

  • failureCountintegerobligatorio
  • lastEventAtstring (date-time) | nullobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio
  • secretstringobligatorio

    Secreto de firma (HMAC-SHA256). Solo se devuelve aquí.

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
patch/api/v1/webhooks/{id}webhooks:manage

Actualizar un destino

Añadir eventos de donaciones (`donation.*`, `donation_plan.*`), cambiar la URL de un destino que ya los recibe o reactivarlo exige el alcance `donations:read` y que quien creó la clave (o aprobó la aplicación) siga viendo las donaciones (403 `insufficient_scope`).

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Cuerpo

  • namestring
  • urlstring (uri)
  • descriptionstring
  • eventsstring[]
  • activeboolean

Respuesta 200 · { data }

  • idstringobligatorio
  • namestringobligatorio
  • urlstringobligatorio
  • descriptionstringobligatorio
  • eventsstring[]obligatorio
  • activebooleanobligatorio
  • secretSuffixstringobligatorio

    Últimos 4 caracteres del secreto de firma.

  • failureCountintegerobligatorio
  • lastEventAtstring (date-time) | nullobligatorio
  • createdAtstring (date-time) | nullobligatorio
  • updatedAtstring (date-time) | nullobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
delete/api/v1/webhooks/{id}webhooks:manage

Borrar un destino

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Respuesta 200 · { data }

  • idstringobligatorio
  • deletedtrueobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
post/api/v1/webhooks/{id}/testwebhooks:manage

Enviar una prueba

Un evento `webhook.test` firmado, un intento. Queda en el registro de entregas. `error` dice el código HTTP que respondió el destino o que no respondió (nunca el error de red: no sirve para sondear puertos).

Markdown de este endpoint

Parámetros

  • idruta · stringobligatorio
  • Idempotency-Keycabecera · string

    Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.

Respuesta 200 · { data }

  • okbooleanobligatorio
  • statusCodeinteger | nullobligatorio
  • errorstring | nullobligatorio
  • eventIdstringobligatorio

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 404 `not_found`: No existe (o no es de este workspace).
  • 409 `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
  • 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.
get/api/v1/webhooks/eventswebhooks:manage

Catálogo de eventos

Markdown de este endpoint

Respuesta 200 · { data: [ … ], nextCursor }

  • idstringobligatorio
  • groupstringobligatorio
  • labelstringobligatorio
  • descriptionstringobligatorio
  • availablebooleanobligatorio

    `false` = todavía no se emite (próximamente).

Errores

  • 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
  • 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
  • 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
  • 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
  • 500 `internal`: Error interno.