Referencia de API para conectar DobroDesk con Zapier

URL base y claves de acceso

La integración con Zapier usa la API HTTPS de producción en https://dobrodesk.com/api/v1. Incluye una clave de acceso activa de DobroDesk en el encabezado Authorization de cada solicitud.

Crea una clave para iniciar automatizaciones y otra para añadir notas internas. La clave del disparador puede leer metadatos de conversaciones de todo el espacio de trabajo, incluidos identificadores, bandeja de entrada, estado, canal de origen y marcas de tiempo. No puede leer el texto de los mensajes de clientes ni los archivos adjuntos. El filtro de bandeja de entrada limita los eventos entregados, pero no el acceso a los metadatos. La clave de notas puede añadir una nota interna a cualquier conversación del espacio de trabajo.

Las claves de Zapier con un propósito asignado son la opción recomendada para la conexión de autoservicio. La clave del disparador usa conversations:read y funciona en los endpoints de disparador descritos y en la comprobación de conexión. La clave de notas usa conversations:write y funciona en el endpoint de notas internas y en la comprobación de conexión. Las claves con propósito se rechazan en otros endpoints de la API con HTTP 403 y el código api_token_purpose_forbidden. También se acepta una clave REST API genérica activa en estos endpoints de Zapier según sus ámbitos habituales: la comprobación de conexión no requiere ámbito, las rutas de lectura y suscripción requieren conversations:read y añadir una nota requiere conversations:write. Las claves genéricas conservan su acceso REST API habitual. Para aplicar el mínimo privilegio, usa las claves con propósito.

Trata una clave de acceso como una contraseña. No la incluyas en una URL, código del navegador, registros compartidos ni en la URL de destino de un webhook de Zapier.

Authorization: Bearer dd_live_<dedicated-access-key>

Comprobar la conexión

GET /zapier/connection comprueba una clave REST API activa e identifica su espacio de trabajo y conexión. Acepta claves genéricas y cualquiera de las claves Zapier con propósito asignado. No requiere un ámbito adicional. Si la solicitud se procesa correctamente, devuelve HTTP 200.

El objeto data contiene workspaceId, tokenId, scopes, workspaceName y connectionName. El endpoint no devuelve la clave de acceso.

GET https://dobrodesk.com/api/v1/zapier/connection
Authorization: Bearer dd_live_<dedicated-access-key>

{
  "data": {
    "workspaceId": "<workspaceId>",
    "tokenId": "<tokenId>",
    "scopes": ["conversations:read"],
    "workspaceName": "<workspaceName>",
    "connectionName": "<connectionName>"
  }
}

Consultar bandejas de entrada y ejemplos de conversaciones

GET /zapier/inboxes?page=0&limit=100 devuelve una página de opciones de bandeja de entrada en data. Cada elemento contiene id y name. page es un entero de 0 a 10.000 y su valor predeterminado es 0. limit es un entero de 1 a 100 y su valor predeterminado es 100.

GET /zapier/conversations?limit=3&inboxId=<inboxId> devuelve metadatos de conversaciones para probar el paso en el editor de Zapier. inboxId es opcional y, si se envía, debe ser una cadena no vacía. limit es un entero de 1 a 100 y su valor predeterminado es 10. Cada resultado contiene id, workspaceId, conversationId, status, sourceChannel y createdAt, además de inboxId cuando existe. id coincide con el ID de conversación. No se devuelven textos de mensajes de clientes ni archivos adjuntos.

Ambos endpoints requieren conversations:read. Usa la clave del disparador con propósito asignado o una clave REST API genérica activa con ese ámbito. En la salida del disparador activo, eventId identifica el evento y occurredAt indica cuándo ocurrió. El ID de conversación sigue siendo el identificador estable de la conversación.

GET /api/v1/zapier/inboxes?page=0&limit=100
GET /api/v1/zapier/conversations?limit=3&inboxId=<inboxId>

Crear una suscripción New Conversation

POST /zapier/subscriptions registra el destino REST Hook de Zapier y requiere conversations:read. Usa la clave del disparador con propósito asignado o una clave REST API genérica activa con ese ámbito. El cuerpo JSON requiere targetUrl y puede incluir inboxId como cadena. Si omites inboxId, la suscripción recibe conversaciones nuevas de todas las bandejas. Un espacio de trabajo puede tener hasta 100 suscripciones webhook activas entre Zapier y otras integraciones de webhooks. Si la solicitud se procesa correctamente, devuelve HTTP 200 con el ID de la suscripción en data.id.

DobroDesk solo acepta destinos HTTPS con el host exacto hooks.zapier.com. No incluyas credenciales, un puerto explícito ni un fragmento de URL. Zapier proporciona la ruta y los parámetros de consulta. La URL completa de destino es un secreto. Guárdala de forma segura. El filtro de bandeja solo cambia qué eventos se entregan. La clave del disparador sigue teniendo acceso a los metadatos de todo el espacio de trabajo.

Para cada conversación nueva, DobroDesk envía un POST a la URL de destino con los encabezados X-DobroDesk-Delivery y X-DobroDesk-Event: conversation.created y un cuerpo JSON con deliveryId. El callback no lleva una firma HMAC. El disparador de Zapier comprueba que el ID de entrega del encabezado X-DobroDesk-Delivery coincida con deliveryId en el cuerpo de la solicitud y después obtiene el evento canónico de DobroDesk con su clave autenticada.

POST /api/v1/zapier/subscriptions
Authorization: Bearer dd_live_<trigger-access-key>
Content-Type: application/json

{
  "targetUrl": "https://hooks.zapier.com/<Zapier-assigned-path>",
  "inboxId": "<inboxId>"
}

{
  "data": {
    "id": "<subscriptionId>"
  }
}

Leer un evento entregado y cancelar la suscripción

GET /zapier/events/<deliveryId> requiere conversations:read y la misma clave que creó la suscripción. Si la suscripción está activa, devuelve HTTP 200 y el evento canónico. La respuesta contiene data.id, data.type, data.workspaceId, data.occurredAt y data.data. El tipo es conversation.created. El objeto data anidado contiene conversationId, inboxId opcional, status, sourceChannel y createdAt.

El disparador activo muestra el ID del evento como eventId y la hora del evento como occurredAt. La API devuelve solo metadatos de la conversación, no textos de mensajes de clientes ni archivos adjuntos.

DELETE /zapier/subscriptions/<subscriptionId> requiere conversations:read y la misma clave que creó la suscripción. Desactiva la suscripción y, si se procesa correctamente, devuelve HTTP 200, data.id y data.disabled en true. Si la suscripción o el evento no existen, están inactivos o no son accesibles con esta clave, se devuelve 404. Desactiva el Zap antes de desconectar la clave para que Zapier pueda cancelar la suscripción correctamente.

GET /api/v1/zapier/events/<deliveryId>
Authorization: Bearer dd_live_<trigger-access-key>

DELETE /api/v1/zapier/subscriptions/<subscriptionId>
Authorization: Bearer dd_live_<trigger-access-key>

Añadir una nota interna

POST /conversations/<conversationId>/notes requiere conversations:write. Usa la clave de notas con una finalidad asignada o una clave REST API genérica activa con ese ámbito. Envía un cuerpo JSON con bodyText. Después de quitar los espacios de los extremos, el texto debe tener entre 1 y 20.000 caracteres. Si la solicitud se procesa correctamente, la API devuelve HTTP 200 con data.id y data.status. Cuando se guarda la nota, data.status tiene el valor saved. Esta acción añade una nota para el equipo y no envía una respuesta al cliente.

Incluye un Idempotency-Key en cada escritura. En la acción de Zapier, asigna Source event or operation ID a un valor estable y no vacío de hasta 1.024 caracteres. El conector aplica SHA-256 y envía una clave con el prefijo zapier-note- seguido de 64 caracteres hexadecimales en minúscula. El valor del encabezado Idempotency-Key debe tener entre 1 y 200 caracteres y usar solo letras y números ASCII, además de `.`, `_`, `:` o `-`. Al reintentar, conserva la misma conexión de Access key, el mismo Idempotency-Key, el mismo conversationId y el mismo texto de la nota. DobroDesk conserva el resultado durante 365 días, asociado al espacio de trabajo y a la identidad de la clave de acceso. Si reutilizas una clave con otro conversationId o con otro texto de nota, la API devuelve HTTP 409 con el código idempotency_conflict. Si un reintento devuelve idempotency_in_progress, espera un momento. Luego, vuelve a intentarlo con el mismo ID de origen, conversationId y texto de la nota. El conector no garantiza reintentos automáticos.

POST /api/v1/conversations/<conversationId>/notes
Authorization: Bearer dd_live_<note-access-key>
Idempotency-Key: zapier-note-<sha256-of-source-reference>
Content-Type: application/json

{
  "bodyText": "Internal update from an approved automation."
}

{
  "data": {
    "id": "<noteId>",
    "status": "saved"
  }
}

Errores y límites de solicitudes

Una clave ausente, no válida, caducada o revocada devuelve HTTP 401. Un propósito de clave no permitido devuelve HTTP 403 con el código api_token_purpose_forbidden. Si falta un ámbito, se devuelve HTTP 403 con el código insufficient_scope y requiredScope.

Las solicitudes de API autorizadas están limitadas a 300 por minuto por clave. Las respuestas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Al superar el límite, DobroDesk devuelve HTTP 429 con el código rate_limit_exceeded y Retry-After. Este límite no garantiza disponibilidad ni tiempo de entrega. Una solicitud válida también puede devolver HTTP 5xx si el servicio no está disponible temporalmente.

• GET /zapier/connection: zapier_connection_unavailable (503).
• GET /zapier/inboxes y GET /zapier/conversations: zapier_query_invalid (400).
• POST /zapier/subscriptions: zapier_subscription_invalid o zapier_target_url_invalid (400), inbox_not_found (404), zapier_subscription_conflict o zapier_subscription_limit_reached (409) y zapier_subscription_unavailable (503). Un conflicto significa que el mismo destino ya está activo con otros ajustes. El límite del espacio de trabajo es de 100 suscripciones webhook activas.
• DELETE /zapier/subscriptions/<subscriptionId>: zapier_subscription_not_found (404).
• GET /zapier/events/<deliveryId>: zapier_event_not_found (404).
• POST /conversations/<conversationId>/notes: conversation_id_required (400), conversation_not_found (404), idempotency_key_required o internal_note_body_invalid (400), e idempotency_conflict o idempotency_in_progress (409). idempotency_in_progress significa que la misma solicitud sigue en proceso.

HTTP 403
data.code = api_token_purpose_forbidden

HTTP 429
data.code = rate_limit_exceeded