Integrar API

Configuración Inicial

Obtener una API Key

1. Iniciá sesión en la plataforma web de TheEye Reconciliations

2. Navegá a Ajustes → API

3. Hacé clic en Generar Nueva API Key

4. Seleccioná los permisos según las operaciones que necesite tu integración

5. Copiá la API Key generada y guardala en un lugar seguro — solo se muestra una vez

Permisos disponibles

• Archivos
  • Subir archivos — necesario para enviar los archivos a conciliar
  • Leer archivos — necesario para consultar o descargar archivos ya subidos
  • Eliminar archivos — necesario para eliminar archivos del sistema
• Templates
  • Consultar templates — necesario para obtener el ID del template a utilizar
• Conciliaciones
  • Consultar progreso y descargar reportes — necesario para monitorear el estado y obtener los resultados
  • Ejecutar todos los tipos de reconciliación — necesario para lanzar conciliaciones
  • Eliminar reconciliaciones — necesario para eliminar conciliaciones del sistema
• Autenticación
  • Todos los requests a la API deben incluir el header x-api-key con tu API Key como valor. La API Key no se envía como Authorization: Bearer. Siempre usá el header x-api-key.

Flujo de Integración

El proceso de conciliación sigue cinco pasos en orden:

1. Obtener el ID del template a utilizar
2. Subir los archivos a conciliar
3. Ejecutar la conciliación
4. Consultar el progreso
5. Descargar el reporte

Paso 1 — Obtener el ID del Template

Antes de ejecutar una conciliación necesitás el identificador único (UUID) del template configurado en la plataforma. Los templates definen las reglas de matching y la configuración de la conciliación.

Endpoint: GET /reconciliation-templates/list

Podés filtrar los resultados por nombre usando el parámetro opcional search.

La respuesta devuelve un listado donde cada template incluye su id (el UUID que necesitás en el Paso 3) y su name tal como aparece en la plataforma.

Ejemplo de respuesta:

[
{ "id": "uuid-del-template", "name": "Template Mensual" },
{ "id": "otro-uuid", "name": "Template Bancario" }
]

Paso 2 — Subir los Archivos

Subís los dos archivos que vas a conciliar. Podés subirlos en un mismo request o por separado.

Endpoint: POST /customer-files/upload-files

Formato del request: multipart/form-data con el campo file

• Formatos de archivo soportados:
  • PDF (extractos bancarios y tarjetas de crédito)
  • Excel (.xlsx, .xls)
  • CSV
• Límites:
  • Máximo 10 archivos por request
  • Máximo 50 MB por archivo

La respuesta devuelve un array con la información de cada archivo subido. El dato más importante es el id_file de cada archivo, que es el UUID que vas a usar para lanzar la conciliación. Guardá el id_file de cada archivo antes de continuar.

Ejemplo de respuesta:

[
{
"file_name": "extracto_banco.pdf",
"status": "uploaded",
"error": false,
"id_file": "uuid-archivo-a",
"msg": "New file uploaded, but not parsed yet"
}
]

Paso 3 — Ejecutar la Conciliación

Existen tres tipos de conciliación según el caso de uso:

Paso 4 — Consultar el Progreso

La conciliación es un proceso asincrónico. Luego de ejecutarla debés consultar su estado hasta que llegue a completed.

Endpoint: GET /reconciliations/progress

Parámetros requeridos:

• filter[where][process_key] — clave del proceso
• filter[where][version] — número de versión
• filter[where][version_key] — clave de la versión

Estados posibles:

• initializing — preparando el proceso
• validating — validando archivos y parámetros
• normalizing — normalizando los datos
• matching — ejecutando el algoritmo de matching
• generating — generando el reporte de resultados
• completed — proceso finalizado correctamente
• error — ocurrió un error durante el proceso

La respuesta también incluye progress_percentage con el porcentaje de avance de 0 a 100. Se recomienda consultar el progreso cada 5 a 10 segundos hasta obtener el estado completed.

Por ejemplo:

GET {{base_url}}/reconciliations/progress
?filter[where][process_key]=PROCESS_KEY
&filter[where][version]=1
&filter[where][version_key]=VERSION_KEY
x-api-key: TU_API_KEY

Respuesta:
{
"id": "reconciliation_id_123",
"recon_progress": {
"current_stage": "matching",
"progress_percentage": 75,
"stages_completed": ["validation", "normalization"],
"estimated_time_remaining": 30,
"error_details": null
}
}

Paso 5 — Descargar el Reporte

Una vez que el estado es completed podés descargar los resultados.

Endpoint: GET /reconciliations/{RECONCILIATION_ID}/download

Parámetro format:

• excel — archivo Excel descargable, recomendado para uso manual
• json — datos estructurados en el body del response, recomendado para integración programática

Parámetro level:

• 0 — solo conciliación completa
• 1 — hasta nivel 1 de detalle
• 2 — hasta nivel 2 de detalle

El reporte en formato JSON incluye los registros que conciliaron correctamente (matched), los registros del archivo A sin coincidencia (unmatched_A), los registros del archivo B sin coincidencia (unmatched_B), y la fecha y hora de generación (generated_at).

Por ejemplo:

En formato Excel (binario)

GET {{base_url}}/reconciliations/{RECONCILIATION_ID}/download?level=0&format=excel
x-api-key: TU_API_KEY

En formato JSON (para procesamiento programático)

GET {{base_url}}/reconciliations/{RECONCILIATION_ID}/download?level=0&format=json
x-api-key: TU_API_KEY

Estructura del JSON para conciliación simple:
{
"reconciliation_id": "uuid",
"version": 1,
"matched": {
"total_reconciliation_rows": 150,
"reconciliation_rows": [ … ]
},
"unmatched_A": {
"total_reconciliation_rows": 5,
"reconciliation_rows": [ … ]
},
"unmatched_B": {
"total_reconciliation_rows": 3,
"reconciliation_rows": [ … ]
},
"generated_at": "2024-01-15T10:30:00.000Z"
}

Metadata Personalizada

Al ejecutar una conciliación podés incluir un campo metadata con cualquier estructura JSON que necesites. Este campo es completamente libre y te permite organizar y buscar conciliaciones según los criterios de tu negocio.

Algunos ejemplos de uso:

• Referencia a proyectos internos: { "proyecto": "PROJ-2024-001", "fase": "cierre-mensual" }
• Integración con sistemas externos: { "erp_id": 12345, "sistema_origen": "SAP" }
• Clasificación operativa: { "periodo": "2024-01", "departamento": "finanzas" }

Buscar conciliaciones por metadata

Endpoint: GET /reconciliations/search-by-metadata

Parámetros disponibles:

• filter[where][metadata.campo] — buscá por un campo específico dentro de metadata
• filter[limit] — cantidad máxima de resultados (por defecto: 50)
• filter[skip] — cantidad de resultados a omitir para paginación
• filter[order] — criterio de ordenamiento, por ejemplo createdAt DESC También podés combinar filtros de metadata con otros como status, id_template o rangos de fecha usando createdAt[gte] y createdAt[lte].

Alertas por Webhook

La plataforma te permite configurar webhooks para recibir notificaciones automáticas sobre eventos relacionados con las conciliaciones. Estos eventos pueden incluir:

• Novedades en el procesamiento de archivos.
• Cambios de estado en una conciliación.
• Finalización de un proceso de conciliación.

De esta manera, tu sistema puede reaccionar automáticamente sin necesidad de consultar la API de forma manual.

Configurar un webhook

1. Ingresa a la pantalla API dentro de la plataforma.
2. Completa los siguientes campos:
   • URL del webhook: endpoint donde recibirás las notificaciones.
   • Método HTTP: puedes elegir entre POST o GET.
   • Headers personalizados (opcional): permite enviar información adicional, como tokens de autenticación.

Webhook Archivo Procesado o file.parsed

Este evento se envía cuando un archivo fue procesado correctamente.

Ejemplo usando POST (JSON en el body)

{
"event_type": "file.parsed",
"entity_id": "67a1b2c3d4e5f6a7b8c9d0e1",
"status": "parsed",
"timestamp": "2026-02-23T14:30:00.000Z"
}

Ejemplo usando GET (query params)

?event_type=file.parsed&entity_id=67a1b2c3d4e5f6a7b8c9d0e1&status=parsed&timestamp=2026-02-23T14:30:00.000Z

Campos enviados

Campo	Tipo	Descripción
event_type	string	Siempre "file.parsed"
entity_id	string	ID del CustomerFile
status	string	Siempre "parsed"
timestamp	string	Fecha en formato ISO 8601 del momento del evento

Webhook Conciliación Finalizada o reconciliation.finished

Este evento se envía cuando una conciliación finaliza.

Ejemplo usando POST (JSON en el body)

{
"event_type": "reconciliation.finished",
"entity_id": "67b2c3d4e5f6a7b8c9d0e1f2",
"status": "finished",
"timestamp": "2026-02-23T15:45:00.000Z"
}

Ejemplo usando GET (query params)

?event_type=reconciliation.finished&entity_id=67b2c3d4e5f6a7b8c9d0e1f2&status=finished&timestamp=2026-02-23T15:45:00.000Z

Campos enviados

Campo	Tipo	Descripción
event_type	string	Siempre "reconciliation.finished"
entity_id	string	ID del ReconJob (ID de la conciliación)
status	string	Siempre "finished"
timestamp	string	Fecha en formato ISO 8601 del momento del evento

Headers enviados en cada request

En todos los webhooks se incluyen los siguientes headers:

• Content-Type: application/json
• Cualquier header personalizado configurado por el usuario
  • Ejemplo: Authorization: Bearer token123

Referencia de Errores

• 401 Unauthorized
  • La API Key es inválida, está expirada o no tiene el scope requerido para esa operación. Verificá que la API Key esté correctamente configurada y que tenga el permiso necesario.
• 403 Forbidden
  • El recurso no pertenece a tu cuenta o tu cuenta no tiene acceso. Verificá que los IDs de archivos, templates y conciliaciones pertenezcan a tu customer.
• 404 Not Found
  • El recurso solicitado no existe. Verificá que el ID en la URL sea correcto y que el recurso exista en la plataforma.
• 400 Bad Request
  • Faltan parámetros obligatorios o tienen formato incorrecto. Errores comunes: omitir type al usar process_key, enviar UUIDs inválidos o superar el límite de tamaño de archivo.
• 500 Internal Server Error
  • Error interno del servidor. Reintentá el request después de unos segundos. Si el error persiste, contactá a soporte.

Para consultas técnicas o para obtener la URL base de tu entorno contactá a soporte@theeye.io