API para documentos financieros

Sube extractos bancarios, facturas y recibos desde tu software. Obtén los datos extraídos, revisa los campos dudosos y descarga CSV, Excel o JSON.

Esquema OpenAPI Descargar ejemplo de subida

El esquema OpenAPI incluye los campos, las respuestas y los permisos. El ejemplo lee la clave de una variable de entorno y sube únicamente el archivo que elijas.

Conecta tu espacio de trabajo

En tu espacio, abre Ajustes → Claves API. Crea una clave solo con los permisos que necesites. El identificador del espacio aparece después de /app/ en su URL. Envía la clave en la cabecera Authorization: Bearer a https://rahunko.com/api/v1/workspaces/{workspaceId}.

Abrir Rahunko

Guarda la clave en tu servidor

La clave completa solo se muestra al crearla. Guárdala en un gestor de secretos, nunca en código del navegador, URL, capturas o registros. Cada clave pertenece a un espacio. Crea una clave nueva antes de revocar la anterior en Ajustes.

Descargar ejemplo de subida

Ejecuta el ejemplo descargado con Bun. Configura RAHUNKO_API_KEY y RAHUNKO_WORKSPACE_ID en las variables de entorno. La clave necesita documents:write y jobs:read. Para exportar también necesita exports:read. El ejemplo no confirma la revisión por ti.

bun upload-document.ts ./statement.pdf

Sube el archivo

Crea una subida con el tamaño, el hash SHA-256 y batchId. Divide el archivo según el partSize recibido y envía cada parte a partsUrl/{partNumber}. Incluye su hash y un Idempotency-Key en cada parte. Cuando termines, llama a completeUrl.

Inicia el procesamiento

Tras completar la subida, llama a uploadUrl/finalize. Consulta el estado con el identificador de tarea recibido. El procesamiento y la revisión tienen estados distintos. Una tarea completada todavía puede contener campos que necesiten revisión.

Revisa y exporta

Obtén el resultado de la tarea o el documento. Comprueba o corrige los valores mediante los endpoints review y exporta la revision actual. Si cambia la versión, obtén primero los datos actualizados. No marques una revisión como completada automáticamente solo para permitir una exportación.

Límites y reintentos

Cada archivo admite hasta 50 MiB. La subida caduca después de una hora. Usa el tamaño de parte y las URL recibidos. También se aplican las cuotas de procesamiento del espacio. Reutiliza un Idempotency-Key solo para la misma petición o parte. Ante un 429, respeta Retry-After si está presente y aumenta la espera entre intentos.

Hasta 300 peticiones por clave y 600 por dirección IP en 60 segundos. Se aplican ambos límites. Superar cualquiera devuelve 429 con Retry-After.

Gestiona los errores

400 o 422 indica que debes corregir los datos. 401 o 403 indica acceso denegado. Con 404, el recurso no está disponible en este espacio. 409 indica un conflicto de estado, versión o Idempotency-Key. No repitas estas peticiones sin cambios. Un error 5xx puede ser temporal. Reintenta solo las operaciones que puedan repetirse con seguridad.

Excepción: un resultado de tarea con HTTP 409 y status=waiting sigue procesándose. Continúa consultando el estado con una pausa entre peticiones.

Webhooks

Actualmente, el operador de Rahunko debe configurar la dirección de las notificaciones. La API registra su endpointId, no una URL arbitraria. Verifica la firma sobre los bytes exactos del cuerpo y la marca de tiempo. Rechaza entregas antiguas y no proceses dos veces el mismo identificador de evento. Mientras no haya una dirección configurada, consulta el estado de la tarea.

La cabecera x-rahunko-signature contiene sha256= seguido del HMAC-SHA256 en Base64 de timestamp.eventId.rawBody con el secreto configurado. Lee el identificador de x-rahunko-event-id y el tiempo Unix en segundos de x-rahunko-timestamp. Compara las firmas en tiempo constante antes de procesar el cuerpo.

Endpoints

Generados a partir del contrato versionado de la API. Todos requieren una clave del espacio de trabajo. Las rutas, los campos y los nombres de permisos son iguales en todos los idiomas.

Listar documentosGET /api/v1/workspaces/{workspaceId}/documents: Permiso necesario: documents:read
Obtener un documentoGET /api/v1/workspaces/{workspaceId}/documents/{documentId}: Permiso necesario: documents:read
Eliminar un documentoDELETE /api/v1/workspaces/{workspaceId}/documents/{documentId}: Permiso necesario: documents:write
Cancelar el procesamientoPOST /api/v1/workspaces/{workspaceId}/documents/{documentId}/cancel: Permiso necesario: documents:write
Obtener datos del originalGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/evidence: Permiso necesario: documents:read
Obtener una página del originalGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/evidence/pages/{pageNumber}: Permiso necesario: documents:read
Exportar una versiónGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/export: Permiso necesario: exports:read
Obtener campos de revisiónGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/review: Permiso necesario: documents:read
Corregir camposPATCH /api/v1/workspaces/{workspaceId}/documents/{documentId}/review: Permiso necesario: documents:write
Confirmar la revisión realizadaPOST /api/v1/workspaces/{workspaceId}/documents/{documentId}/review/complete: Permiso necesario: documents:write
Consultar el estado de procesamientoGET /api/v1/workspaces/{workspaceId}/jobs/{jobId}: Permiso necesario: jobs:read
Obtener el resultado y los enlaces de exportaciónGET /api/v1/workspaces/{workspaceId}/jobs/{jobId}/result: Permiso necesario: jobs:read
Consultar la cuota de procesamientoGET /api/v1/workspaces/{workspaceId}/quota: Permiso necesario: documents:read
Crear una subidaPOST /api/v1/workspaces/{workspaceId}/uploads: Permiso necesario: documents:write
Consultar el progreso de subidaGET /api/v1/workspaces/{workspaceId}/uploads/{uploadId}: Permiso necesario: documents:write
Cancelar una subidaPOST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/abort: Permiso necesario: documents:write
Completar las partes subidasPOST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/complete: Permiso necesario: documents:write
Enviar el archivo a procesarPOST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/finalize: Permiso necesario: documents:write
Subir una partePUT /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/parts/{partNumber}: Permiso necesario: documents:write
Listar webhooks registradosGET /api/v1/workspaces/{workspaceId}/webhooks: Permiso necesario: webhooks:read
Registrar un webhook configuradoPOST /api/v1/workspaces/{workspaceId}/webhooks: Permiso necesario: webhooks:write
Desactivar un webhookDELETE /api/v1/workspaces/{workspaceId}/webhooks/{endpointId}: Permiso necesario: webhooks:write