Referencia de la API de Dureach: autenticación, endpoints, paginación y webhooks

Esta página documenta la superficie de API de Dureach para clientes que es segura para integrar: gestión de claves, gestión de webhooks e historial de entregas, y endpoints versionados de adquisición de contactos. Explica autenticación, campos, respuestas, paginación por cursor, filtros, límites y errores que debes gestionar en producción.

Start with the supported boundary

Crea una clave en Settings -> Integrations con el menor privilegio disponible. Guárdala en el servidor, envíala en el encabezado Authorization y limita cada solicitud al workspace previsto. La aplicación del navegador, el runner privado y las rutas no documentadas /api/v1/ o /api/v2/ no son automáticamente endpoints de la API para clientes.

Los ejemplos usan https://app.dureach.com. Sustituye YOUR_OAUTH_ACCESS_TOKEN y los UUID por tus valores. Nunca pongas una clave activa en un bundle del navegador, URL, captura, registro o ticket de soporte.

Guides

• Autenticación y primeros pasos de API
• Límites de acceso a la API de Dureach
• Conectar un cliente de IA mediante MCP
• Referencia de herramientas MCP
• Aprobaciones, políticas y cuotas de MCP
• Lector SQL de MCP
• Solución de problemas de MCP
• Webhooks de API
• Configuración y supervisión de entregas de webhooks

Authentication

Envía la clave como token bearer en cada solicitud:

curl --fail-with-body \
  'https://app.dureach.com/api/v2/webhooks?limit=25' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  -H 'Accept: application/json'

Las claves pertenecen al workspace activo que las creó y no pueden cruzar ese límite. Si una solicitud devuelve 401, revoca la clave si pudo filtrarse, crea un reemplazo y actualiza el secreto del servidor.

OAuth service-account endpoints

Todos los endpoints de claves están bajo /oauth/service-accounts y requieren el alcance OAuth business scopes correspondiente (o all:*).

POST /oauth/service-accounts

Crea una clave. La solicitud requiere un name no vacío (máximo 255 caracteres) y un array scopes no vacío. Los nombres deben ser válidos y no repetirse. El valor completo de key solo se devuelve en esta respuesta.

{
  "name": "Reporting integration",
  "scopes": ["campaigns:read", "campaigns:create"]
}

{
  "id": "0199f372-efec-7c2d-af53-85ab8eab7c73",
  "name": "Reporting integration",
  "scopes": ["campaigns:read", "campaigns:create"],
  "key": "dureach_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "workspace_id": "0199f372-efef-73e5-b1ed-e2d1fbe4654d",
  "timestamp_created": "2025-10-17T18:33:40.079Z",
  "timestamp_updated": "2025-10-17T18:33:40.079Z"
}

GET /oauth/service-accounts

Lista las claves del workspace activo. Parámetros:

La respuesta contiene items y, si hay otra página, next_starting_after. Una lectura posterior devuelve solo un prefijo seguro, nunca el secreto original.

DELETE /oauth/service-accounts/{id}

Revoca una clave. La respuesta contiene sus metadatos y un prefijo seguro. Trata la eliminación correcta como permanente y elimina la clave del gestor de secretos.

Webhook endpoints

Los endpoints de webhook están bajo /api/v2 y requieren webhooks:* (o all:*) y un plan que incluya webhooks.

GET /api/v2/webhooks

Lista destinos de webhook. Los filtros admitidos son campaign (UUID de campaña) y event_type. Usa limit y starting_after para paginar. El tamaño permitido es 1-100 y el valor predeterminado es 25. La respuesta es:

{
  "items": [
    {
      "id": "0199f372-efec-7c2d-af53-85ab8eab7c73",
      "campaign": "0199f372-efef-73e5-b1ed-e2d1fbe4654d",
      "name": "Interested lead receiver",
      "target_hook_url": "https://example.com/dureach-hook",
      "event_type": "lead.interested",
      "custom_interest_value": null,
      "timestamp_created": "2025-10-17T18:33:40.079Z"
    }
  ],
  "next_starting_after": "0199f372-efec-7c2d-af53-85ab8eab7c73"
}

POST /api/v2/webhooks

Crea un destino. Envía target_hook_url, name, event_type y, cuando el evento sea una etiqueta de interés personalizada, custom_interest_value. campaign es opcional para eventos del workspace.

GET /api/v2/webhooks/{id}, PATCH /api/v2/webhooks/{id}, DELETE /api/v2/webhooks/{id}

Lee, actualiza o elimina un destino. PATCH acepta los mismos campos y solo cambia los enviados. Confirma el destino tras actualizarlo; eliminarlo no borra los eventos históricos.

GET /api/v2/webhooks/event-types

Devuelve tipos estándar y eventos de etiquetas personalizados disponibles en el workspace. Usa el id devuelto como event_type; no fijes una etiqueta que pueda renombrarse.

POST /api/v2/webhooks/{id}/test

Envía una entrega de prueba. Una respuesta correcta tiene success: true, status_code: 200, response_time_ms y error: null. Prueba primero con un receptor que no sea de producción.

GET /api/v2/webhook-events

Lista intentos de entrega. Filtra con success=true|false o webhook_url. Usa limit (1-100, por defecto 25) y starting_after. Los eventos incluyen payload, status_code, success, retry_count, will_retry, timestamp_next_retry, error_message, retry_successful, lead_email y response_time_ms. Redacta payload y lead_email antes de escribir logs.

GET /api/v2/webhook-events/{id}

Lee un intento de entrega por UUID.

GET /api/v2/webhook-events/summary and GET /api/v2/webhook-events/summary-by-date

Devuelve la salud agregada de las entregas. El resumen incluye total_events, successful_events, failed_events, success_rate y failure_rate. El resumen por fecha devuelve items con un registro por fecha. Usa estos endpoints para supervisar, no para repetir eventos.

Contact acquisition endpoints

El servicio de adquisición de contactos expone actualmente estos endpoints heredados y medidos por separado bajo /api/v1/leadbank. La disponibilidad depende de los permisos del workspace:

Las respuestas de búsqueda y listas pueden ser grandes. Envía siempre los parámetros de página o límite documentados y detente cuando no haya una página siguiente. Un resultado vacío significa que no hubo coincidencia para esa consulta; no demuestra que una persona o empresa no exista.

Request hygiene

Usa el método y la ruta documentados, valida los campos antes de enviar, sigue los cursores o límites y trata 401, 403, validación, límite y errores del servidor por separado. Haz idempotentes los consumidores de webhook: guarda el identificador antes de confirmar y reintenta de forma segura tras fallos transitorios.

Errors

La gestión de claves devuelve JSON con statusCode, error y message; endpoints nuevos también pueden incluir code. Trata 400 como entrada inválida, 401 como autenticación ausente, inválida o revocada, 403 como fallo de alcance, rol, workspace o plan, 404 como recurso desconocido, 409 como conflicto de estado y 429 como límite de uso. Reintenta solo solicitudes acotadas e idempotentes tras fallos 5xx transitorios; no repitas a ciegas un 4xx.

Troubleshooting checklist

1. Confirma la URL base https://app.dureach.com y la versión correcta.
2. Envía Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN; no uses una clave en la query.
3. Comprueba los alcances, el workspace activo y el plan del endpoint.
4. Valida UUID, campos obligatorios, rango de limit y cursor starting_after.
5. Registra estado, message o code redactados, hora y endpoint para soporte.
6. Revoca y reemplaza una clave expuesta. Nunca envíes la clave ni payloads sin redactar.

Endpoint workflow

1. Crea una clave en Settings → Integrations con los alcances mínimos.
2. Envía una solicitud de solo lectura con Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN y Accept: application/json.
3. Valida la forma de respuesta antes de integrar y conserva items, UUID, enums y next_starting_after.
4. Usa la paginación por cursor tal como se devuelve y detente cuando falte el cursor.
5. Haz idempotente el consumidor guardando el ID del evento antes de confirmar.

Request field rules

Usa valores positivos y acotados para limit, UUID válidos, tipos de evento documentados y todos los campos JSON obligatorios. No pongas claves en queries, bundles del navegador, capturas ni logs.

API de campañas y leads

Estas son las operaciones de campañas y leads admitidas con una clave de API limitada al workspace. Crea la clave en Settings -> Integrations, guárdala cuando se muestre por única vez y consérvala en tu servidor. El plan del workspace debe incluir acceso a la API. Usa https://api.dureach.com para las solicitudes siguientes.

Empieza con una solicitud de solo lectura:

curl --fail-with-body 'https://api.dureach.com/api/v2/campaigns?limit=10' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  -H 'Accept: application/json'

La lista de campañas devuelve items y puede incluir next_starting_after. Envía ese cursor sin cambios en la solicitud siguiente. limit tiene un máximo de 100. Usa un UUID de la respuesta para consultar o actualizar una campaña.

Para agregar un lead, envía este JSON a POST /api/v2/lead/add:

{
  "campaign_id": "CAMPAIGN_UUID",
  "leads": [{"email": "[email protected]", "first_name": "Jane"}]
}

Busca el lead con GET /api/v2/lead/get?email=jane%40example.com&campaign_id=CAMPAIGN_UUID. Para cambiar su estado, envía campaign_id, email y new_status a POST /api/v2/lead/update/status. La creación y actualización de campañas usan JSON; consulta el esquema OpenAPI para los campos obligatorios de programación y secuencias.

La clave pertenece a su workspace. Se rechaza un X-Workspace-ID distinto. Una clave ausente o no válida devuelve 401; los permisos insuficientes o un workspace distinto devuelven 403. Trata por separado los errores de validación y los límites de solicitudes. No pongas la clave en una URL, bundle del navegador, captura ni registro.

El contrato OpenAPI define los campos, las respuestas y la autenticación bearer de estas siete operaciones.