Cuando los documentos nacen en otro sistema

La pregunta que surge en la segunda reunión: «¿se integran con nuestro sistema?». Hasta ahora la respuesta honesta era que no. Ahora la respuesta es esta: tienes un portal, un CRM o un sistema contable donde la operación ya existe, y DocuTract puede funcionar como una parte de él.

La sexta función de esta oleada es la vía de salida. Un token con el que tu sistema nos llama, una dirección a la que escribimos por iniciativa propia y una descripción abierta de todo lo que hay entre medias.

Un token que no podemos enseñarte dos veces

Un token se crea en la pantalla Integraciones: un nombre que reconozcas más adelante, para saber qué sistema lo usa, y una lista de lo que puede hacer. Después se muestra una sola vez.

No es un olvido, es como tiene que funcionar un producto que guarda la llave de otro. Solo guardamos un hash: mostrar el token una segunda vez es algo que ni siquiera nosotros podemos hacer, lo que significa que no se nos puede robar. La lista conserva los primeros caracteres, los permisos y la fecha del último uso, para que se vea qué token está vivo y si alguien lo sigue usando.

Revocar lo desactiva al instante. Su registro se conserva: que existió y cuándo dejó de funcionar forma parte del historial del espacio de trabajo, no es basura.

Los permisos se comprueban en cada dirección por separado. Un token que solo puede leer plantillas recibe un claro «falta el permiso documents:write» cuando intenta crear un documento, no un escueto «no encontrado». Damos por hecho que una persona de carne y hueso está montando la integración, y una respuesta que no explica nada le cuesta una tarde.

Qué puede hacer la API

Todo lo que puedes hacer en la pantalla, solo que sin pantalla: abrir un expediente y subir escaneos a él, crear un documento a partir de una plantilla con los valores ya rellenados, preguntar en qué fase está, obtener todos los valores junto con el escaneo del que se leyó cada uno y conseguir un enlace de corta duración al archivo terminado.

Esa última parte es lo que hace que esta integración sea distinta de las demás. Tu sistema no recibe solo un archivo relleno, sino cada valor con su procedencia: el escaneo, el campo, la fiabilidad de la lectura. La misma fuente que ve una persona en la pantalla de revisión está disponible para el código.

La descripción de cada dirección y campo se genera a partir del propio código y se publica abiertamente, sin token: /api/v1/openapi.json. Una documentación que primero hay que pedir es una documentación que nadie lee.

Webhooks y un registro honesto

No tienes que preguntarnos si un documento está listo. Danos una dirección y marca los eventos: documento listo, documento fallido, expediente listo, discrepancia encontrada, un cliente ha enviado un archivo.

Cada solicitud va firmada, y el secreto que verifica la firma se muestra una sola vez, como el token. Si tu servidor respondió otra cosa, o no respondió, lo volvemos a intentar: al cabo de un minuto, de cinco, de media hora, de dos horas y de diez. Después paramos, porque una integración que nadie mantiene no debería consumir los recursos de nadie eternamente.

Y luego, la parte para la que se escribió todo esto. Cuando la otra parte dice «nuestro sistema no ha recibido nada», la respuesta está en la pantalla: el evento, la hora, cuántos intentos, qué código de respuesta volvió y el principio del cuerpo de la respuesta. Se ve que respondió 500 cinco veces. No es una ayuda de depuración para nosotros, es una respuesta para tu ingeniero.

Al lado, dos botones para cuando una integración todavía se está configurando. Enviar prueba envía ahora mismo una solicitud de prueba, sin esperar a un evento real, para poder comprobar el receptor antes de que pase trabajo real por él. Reintentar, junto a una entrega fallida, hace un intento más de inmediato y no reinicia el historial: los cuatro intentos fallidos se quedan en el registro, porque esa es la verdad sobre lo que ha costado esta notificación.

Los límites que nos imponemos

Un webhook solo va a https y solo a una dirección pública: una dirección dentro de una red privada se rechaza tanto al guardarla como antes de cada intento, porque un nombre de host que ayer apuntaba hacia fuera puede apuntar hoy hacia dentro. El límite de frecuencia se cuenta por token y no por dirección, de modo que un vecino del mismo servidor no consume tu cuota, y quien lo supera recibe un honesto «vuelve dentro de tantos segundos».

La API y los webhooks forman parte del plan Team. Si un espacio de trabajo pasa a otro plan, lo ya creado sigue visible y se puede revocar: unas claves a las que nadie puede llegar son peores que una función de pago.

Lo que no incluye esta versión

El planteamiento de esta fase describía dos partes más: exportar un documento terminado a Google Drive, OneDrive o Dropbox, y enviarlo a firma mediante DocuSign o Dropbox Sign. Ambas necesitan credenciales de esos proveedores, que ahora mismo no tenemos, y escribir una integración que no se puede probar en ningún sitio es hacer pasar por terminado un código sin escribir. Siguen en el plan como versiones propias.

Qué viene después

La séptima y última función de esta oleada es la generación por lotes: una lista de cincuenta filas o un archivo comprimido de escaneos en lugar de cincuenta rellenos idénticos a mano, con el progreso a la vista y la opción de repetir solo los que no han funcionado.

La lista completa está en qué estamos construyendo ahora, y las instrucciones paso a paso de las integraciones, en el centro de ayuda.