Autenticación de API y primeros pasos

Dureach ofrece recursos de API para clientes en rutas versionadas /api/. La aplicación también tiene rutas internas /api/v1/ y /api/v2/. Una ruta interna no forma parte automáticamente de la API pública; usa solo las rutas indicadas en la referencia de API.

Crear una clave

1. Abre Settings → Integrations en la aplicación.
2. Abre el área de claves de API y crea una clave con el acceso mínimo necesario.
3. Dale un nombre claro, selecciona solo los scopes que necesita la integración, cópiala una vez en un gestor de secretos del servidor y usa YOUR_OAUTH_ACCESS_TOKEN en la documentación y los ejemplos.
4. Si la clave queda expuesta, revócala y crea otra; nunca la pegues en un bundle del navegador, URL, captura, incidencia o registro.

Autenticar

Envía la clave en la cabecera Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN. Mantenla fuera de bundles del navegador, URL, capturas, incidencias y registros. Las solicitudes quedan asociadas al workspace activo que creó la clave.

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

Los recursos para administrar claves de API y webhooks están disponibles en /oauth/service-accounts, /api/v2/webhooks y /api/v2/webhook-events. Comprueba el acceso y los permisos del workspace antes de crear una integración.

Formato de solicitud y respuesta

Crea una clave con un cuerpo JSON que contenga name y un array scopes no vacío. La respuesta de creación incluye id, name, scopes, key, workspace_id, timestamp_created y timestamp_updated. La clave completa se devuelve una sola vez; las lecturas posteriores solo muestran un prefijo seguro.

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

Las respuestas de lista usan un array items y pueden incluir next_starting_after. Conserva el cursor exactamente al solicitar la página siguiente. Los endpoints de listas de claves de API y webhooks tienen 25 registros por defecto; las páginas de webhooks y eventos de webhook están limitadas a 100 registros. Los registros de webhook incluyen campaign, name, target_hook_url, event_type y custom_interest_value; los eventos de webhook incluyen el estado de entrega y campos de reintento.

Lista operativa

1. Usa el método y la ruta documentados exactamente; las rutas privadas de la aplicación y del runner no son endpoints de API para clientes.
2. Mantén los tamaños de página acotados y sigue los campos de cursor o paginación del endpoint.
3. Trata 401 como autenticación no válida o revocada y 403 como un fallo de permisos o de permisos del plan.
4. Reintenta solo fallos transitorios del servidor, con backoff limitado y una estrategia de idempotencia para escrituras. No reintentes a ciegas respuestas 400, 401, 403, 404, 409 o 429.
5. Guarda los ID de solicitud y los códigos de error redactados para soporte, nunca la clave ni el payload privado.

Haz que los consumidores de webhook sean idempotentes: guarda el identificador del evento antes de confirmarlo, valida las firmas cuando estén configuradas y tolera reintentos de entrega.

Errores

Los errores de claves de API usan JSON con statusCode, error y message; los endpoints nuevos también pueden incluir un code legible por máquina. Trata 400 como entrada no válida, 401 como fallo de autenticación, 403 como fallo de autorización o permisos, 404 como recurso desconocido y 429 como límite de frecuencia o uso. No reintentes a ciegas una respuesta 4xx.

Páginas relacionadas

Consulta API webhooks y límites de uso.

Tabla de fallos de autenticación

Verificación segura

Ejecuta primero una solicitud de solo lectura, confirma el workspace de la respuesta y la forma items, y guarda el cursor next_starting_after exactamente como se devuelve. En una escritura, registra solo el estado HTTP, el código de error redactado y el ID de solicitud. Nunca registres la clave bearer ni el payload del webhook.