AuraDoc
Iniciar sesiónCrear

Blog

Webhooks y API REST en AuraDoc

Conecta AuraDoc con tus sistemas mediante claves de API con ámbitos, webhooks firmados, registro de entregas y reintentos automáticos.


Tarde o temprano todo equipo quiere que sus documentos hablen con el resto del software: subir un archivo desde un script, iniciar un flujo desde un programador de tareas o enterarse en cuanto un documento termina de procesarse. AuraDoc ofrece dos vías complementarias. La API REST permite que tus sistemas pidan algo a AuraDoc, y los webhooks permiten que AuraDoc avise a tus sistemas de que algo ocurrió. Este artículo recorre ambas y los detalles de seguridad que importan en producción.

Claves de API y ámbitos

Todo empieza con una clave de API. Crea una en Dashboard › Settings › API keys, ponle un nombre y elige sus ámbitos. Los ámbitos limitan lo que la clave puede hacer, así que una clave usada solo para subir archivos no necesita permiso para administrar nada más. Una clave no puede crear otra con ámbitos mayores que los suyos, y los permisos efectivos son siempre los que comparten la clave y el rol de la persona, como se explica en roles y permisos del equipo. Las solicitudes llevan la clave en la cabecera Authorization como token bearer.

La misma página muestra estadísticas de uso de cada clave, para ver qué integración está activa y cuál se ha quedado en silencio. En los planes de pago también puedes fijar un límite de peticiones para una clave concreta, útil cuando un script ruidoso no debe perjudicar a los demás. Si una clave se filtra, elimínala y crea otra; nada más debe cambiar en AuraDoc.

Qué puede hacer la API

La página de integraciones de la documentación indica la dirección base y trae ejemplos listos para copiar. Hoy puedes subir un documento, pedir a AuraDoc que ingiera un documento desde una URL, iniciar la ejecución de un flujo y crear una solicitud de firma, cada una con una sola solicitud autenticada. Son las mismas operaciones que hacen las personas en el panel, así que el resultado creado por la API aparece en la interfaz como cualquier otro.

Si prefieres consultar a recibir llamadas, hay endpoints de disparador que devuelven documentos nuevos, ejecuciones de flujo completadas y firmas completadas, además de un catálogo que los describe. Las herramientas que no reciben webhooks, como complementos de hojas de cálculo o plataformas sin código, pueden consultarlos periódicamente. La referencia completa está en la página de documentación de integraciones.

Webhooks de salida

Para notificaciones en tiempo real, abre Dashboard › Webhooks y añade un endpoint. Eliges los eventos que te interesan de una lista que incluye documento creado, clasificado y eliminado, OCR y traducción completados o fallidos, eventos de flujo, avisos de cuota de almacenamiento y eventos de firma. Al guardar, AuraDoc muestra el secreto de firma una sola vez. Cópialo enseguida en el servicio receptor; si lo pierdes, rota el secreto y se genera uno nuevo, y la rotación queda registrada en la auditoría.

Puedes dar forma al contenido con una plantilla, de hasta unos miles de caracteres, y validarla antes de guardar. Un botón de prueba envía un evento de muestra, marcado con una cabecera de prueba, para confirmar que tu endpoint responde y lee el cuerpo antes de depender de él. Cada webhook se puede desactivar sin eliminarlo, lo que ayuda en ventanas de mantenimiento.

Verificar firmas y gestionar fallos

Cada entrega va firmada. AuraDoc calcula un HMAC-SHA256 sobre la marca de tiempo y el cuerpo sin procesar con tu secreto y envía el resultado en la cabecera de firma, junto con cabeceras del nombre del evento, el id del webhook, el id de la entrega, la marca de tiempo y el número de reintentos. Tu receptor debe recalcular la firma desde el cuerpo sin procesar, compararla en tiempo constante y rechazar solicitudes con una marca de tiempo demasiado antigua. Así nadie puede falsificar un evento hacia tu endpoint, aunque conozca su dirección.

Los endpoints se caen, y AuraDoc lo prevé. Cuando una entrega falla, se reintenta automáticamente con esperas crecientes, de cinco minutos hasta seis horas. La vista de entregas muestra cada intento con su resultado, y puedes lanzar un reintento manual cuando hayas corregido el problema. Como el mismo id de entrega se reutiliza en los reintentos, tu receptor puede ignorar duplicados sin riesgo. Para combinar webhooks con archivos que llegan desde proveedores, consulta almacenamiento en la nube y carpetas vigiladas.

Volver al blog