Ver MarkdownDescargarPara agentes de IA

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

  • 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)
  • 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
  • webhooks:manage Webhooks: gestionar destinos

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.

Markdown de este endpoint

Respuesta 200 · { data }

  • integrationsobjectobligatorio
    • checkedAtstring (date-time)obligatorio
    • source"crm_configuration"obligatorio
    • 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
  • 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
  • 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 registrada

Mismo cuerpo que el panel (`type`: note, task, call, 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`.

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 201 · { data }

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

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

  • leadIdstringobligatorio
  • nextStepTaskIdstring | nullobligatorio
  • alreadyExistedbooleanobligatorio

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 `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.

Contactos

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
    • stagestring | nullobligatorio
    • 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
  • stagestring | 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 `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) o `updatedSince` (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).

  • 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
  • stagestring | 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ó.
  • 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`.

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[]

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
  • stagestring | nullobligatorio
  • 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.
  • 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.
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.

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[]

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
  • stagestring | nullobligatorio
  • 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.
  • 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}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
  • stagestring | 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).
  • 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`. Cambiar `email` al de otro contacto: 409 `conflict` (con su `id` en `details`).

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[]
  • 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
  • stagestring | nullobligatorio
  • 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.
  • 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.
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
  • stagestring | 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.
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.

Etiquetas

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.

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.

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.

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.
  • 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.

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.

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

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.

Negocios

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.

Conversaciones

get/api/v1/messaging/channelsconversations:read

Números e integraciones disponibles para mensajería.

WhatsApp y SMS incluyen números; Telegram incluye bot (sin token) y numbers vacío. canReceive=null significa que la recepción no está verificada. SMS y Telegram admiten texto con enlaces, sin botones nativos.

Markdown de este endpoint

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

  • channel"whatsapp" | "sms" | "telegram"obligatorio
  • configuredbooleanobligatorio
  • botobject
    • usernamestring | nullobligatorio
    • 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.

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
  • tostringobligatorio
  • phoneNumberIdstring
  • leadIdstring
  • messageobject | object | object | object | objectobligatorio
    • type"text"obligatorio
    • textstringobligatorio
    • previewUrlboolean

Respuesta 201 · { data }

  • conversationIdstringobligatorio
  • channel"whatsapp" | "telegram" | "sms" | "email"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. `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.

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. `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». Cabecera solo de texto. El estado definitivo llega con la aprobación de Meta (consúltalo con `GET /api/v1/messaging/whatsapp/templates?name=`).

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"obligatorio
  • descriptionstring
  • phoneNumberIdstring
  • allowCategoryChangeboolean
  • parameterFormat"POSITIONAL" | "NAMED"
  • componentsobject | object | object | object[]obligatorio
    • type"HEADER"obligatorio
    • format"TEXT"obligatorio
    • textstringobligatorio
    • exampleobject
      • header_textstring[]obligatorio

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. `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).

Markdown de este endpoint

Parámetros

  • statusconsulta · "open" | "closed" | "snoozed"
  • channelconsulta · "whatsapp" | "telegram" | "sms" | "email"
  • 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"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

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"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

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
  • replyToMessageIdstring | null
  • interactionobject | null
    • typestringobligatorio
    • idstring | nullobligatorio
    • titlestring | nullobligatorio
    • descriptionstring | nullobligatorio
  • attachmentobject | nullobligatorio
    • kindstringobligatorio
    • urlstring | nullobligatorio
    • 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.
  • 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 (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"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"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

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"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

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"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

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.

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" | "slack" | "web_form" | "chat_ai" | "phone" | "manual" | null
  • categorystring | null
  • tagsstring[]
  • assigneeEmailstring | null
  • conversationIdstring | null
  • originThreadobject | null
    • idstringobligatorio
    • subjectstring
    • channel"email" | "whatsapp" | "telegram" | "sms" | "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" | "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.

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.