Exportaciones y disputas

Esta guía cubre dos workflows del operador que terminan en un artefacto descargable o resuelto. Con los trabajos de exportación, pones un informe en cola, consultas su estado hasta que se complete y descargas el archivo. Con las disputas, abres una disputa contra una excepción, adjuntas evidencia y luego la cierras como ganada o perdida. Ambos están delimitados por tenant a partir del JWT.

Trabajos de exportación

Las exportaciones son asíncronas. Creas un trabajo delimitado a un contexto, consultas su estado por ID y descargas el archivo una vez que alcanza SUCCEEDED. Los estados son QUEUED, RUNNING, SUCCEEDED, FAILED, EXPIRED y CANCELED.

Crea un trabajo de exportación

POST a la colección export-jobs del contexto. Responde 202 Accepted con el ID del trabajo y una URL de consulta.

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/export-jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reportType": "MATCHED",
    "format": "CSV",
    "dateFrom": "2025-01-01",
    "dateTo": "2025-01-31",
    "sourceId": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "QUEUED",
  "statusUrl": "/v1/export-jobs/550e8400-e29b-41d4-a716-446655440001"
}

reportType: uno de MATCHED, UNMATCHED, VARIANCE, EXCEPTIONS (los alias MATCHES y UNMATCHED_TRANSACTIONS se normalizan a estos valores).
format: CSV, JSON o XML (normalizado a mayúsculas).
dateFrom / dateTo: YYYY-MM-DD opcional. dateFrom toma por defecto 30 días antes de dateTo, y dateTo toma por defecto mañana (UTC).
sourceId: filtro de fuente opcional.

Los trabajos de exportación asíncronos no admiten SUMMARY ni PDF. Una solicitud de cualquiera de los dos devuelve 400. La ventana de fechas también tiene un intervalo máximo. Una solicitud que exceda el rango devuelve un error en lugar de recortar la ventana silenciosamente.

Consulta el estado del trabajo

Lee la ruta de nivel superior del trabajo (el statusUrl de la creación).

curl -X GET "https://api.matcher.example.com/v1/export-jobs/{jobId}" \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reportType": "MATCHED",
  "format": "CSV",
  "status": "SUCCEEDED",
  "recordsWritten": 4250,
  "bytesWritten": 524288,
  "fileName": "matched_report_2025-01-31.csv",
  "createdAt": "2025-01-15T10:30:00Z",
  "startedAt": "2025-01-15T10:30:05Z",
  "finishedAt": "2025-01-15T10:35:00Z",
  "expiresAt": "2025-01-16T10:30:00Z",
  "downloadUrl": "https://storage.example.com/exports/matched_report.csv?token=abc"
}

error está presente solo cuando status es FAILED. downloadUrl aparece solo una vez que el trabajo alcanzó SUCCEEDED y el archivo sigue disponible. Puedes listar los trabajos de un contexto con GET /v1/contexts/{contextId}/export-jobs, listar todos los trabajos con GET /v1/export-jobs, y cancelar un trabajo en cola o en ejecución con POST /v1/export-jobs/{jobId}/cancel.

Descarga el archivo

Devuelve una URL prefirmada, el nombre del archivo original, una suma de verificación SHA-256 y el tiempo de vida restante de la URL en segundos.

curl -X GET "https://api.matcher.example.com/v1/export-jobs/{jobId}/download" \
  -H "Authorization: Bearer $TOKEN"

{
  "downloadUrl": "https://storage.example.com/exports/report.csv?token=abc",
  "fileName": "matched_report.csv",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "expiresIn": 3600
}

Los archivos de exportación se purgan después de expiresAt (7 días de forma predeterminada). Una vez que un trabajo está en EXPIRED, el archivo ya no se puede descargar. Vuelve a ejecutar la exportación para regenerarlo.

Disputas

Abres una disputa contra una excepción específica cuando necesitas impugnar una discrepancia de conciliación. Su ciclo de vida empieza en DRAFT → OPEN. Desde OPEN, una disputa puede pasar a PENDING_EVIDENCE (y volver a OPEN) o cerrarse directamente como WON / LOST. Solo WON es terminal. Puedes reabrir una disputa LOST a OPEN.

Abre una disputa

POST a la colección de disputas de la excepción.

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/disputes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "BANK_FEE_ERROR",
    "description": "Transaction amount differs from invoice"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "exceptionId": "550e8400-e29b-41d4-a716-446655440001",
  "category": "BANK_FEE_ERROR",
  "state": "OPEN",
  "description": "Transaction amount differs from invoice",
  "openedBy": "user@example.com",
  "evidence": [],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

category es uno de BANK_FEE_ERROR, UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION o OTHER. El campo openedBy registra el principal que la abrió.

Envía evidencia por URL

Adjunta una referencia a un archivo de evidencia ya alojado, junto con un comentario descriptivo.

curl -X POST "https://api.matcher.example.com/v1/disputes/{disputeId}/evidence" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Attached bank statement showing correct amount",
    "fileUrl": "https://storage.example.com/evidence/doc123.pdf"
  }'

Sube un archivo de evidencia

Transmite los bytes del archivo sin procesar directamente al almacenamiento de objetos delimitado por tenant. El comentario viaja como parámetro de consulta y el archivo como cuerpo de la solicitud. Responde 201 Created con la disputa actualizada. Los tipos de contenido permitidos son application/pdf, image/png, image/jpeg y text/csv. El cuerpo tiene un límite de 10 MiB.

curl -X POST "https://api.matcher.example.com/v1/disputes/{disputeId}/evidence/upload?comment=Bank%20statement%20showing%20correct%20amount" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @statement.pdf

El arreglo evidence de la disputa lista cada elemento de evidencia almacenado:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "disputeId": "550e8400-e29b-41d4-a716-446655440001",
  "comment": "Bank statement showing correct amount",
  "submittedBy": "user@example.com",
  "fileUrl": "https://storage.example.com/evidence/doc123.pdf",
  "submittedAt": "2025-01-15T10:30:00Z"
}

El endpoint de carga falla de forma cerrada con 503 cuando no configuras el almacenamiento de objetos. Rechaza los cuerpos con exceso de tamaño con 413 y los tipos de contenido fuera de la lista permitida con 415. El tenant siempre proviene del JWT y la disputa de la ruta, nunca del cuerpo.

Cierra una disputa

Registra el resultado. won establece el estado en WON (terminal) o LOST (reabrible), con una nota resolution obligatoria.

curl -X POST "https://api.matcher.example.com/v1/disputes/{disputeId}/close" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "won": true,
    "resolution": "Counterparty acknowledged the error and issued correction"
  }'

Puedes listar disputas con GET /v1/disputes y obtener una con GET /v1/disputes/{disputeId}. El endpoint de listado filtra por state, category y rango de fechas, y admite ordenamiento y paginación por cursor.

Códigos de respuesta

Estado	Significado
`200`	Datos de exportación o disputa devueltos
`201`	Archivo de evidencia cargado
`202`	Trabajo de exportación aceptado
`400`	Entrada inválida (tipo de informe o formato no admitido, rango de fechas incorrecto, categoría inválida)
`404`	Contexto, trabajo de exportación, excepción o disputa no encontrados
`409`	Transición de estado de disputa inválida
`413`	El archivo de evidencia supera el límite de 10 MiB
`415`	Tipo de contenido de evidencia fuera de la lista permitida
`422`	Campo con formato incorrecto
`503`	Almacenamiento de exportación o evidencia no configurado

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Exportaciones y disputas

Trabajos de exportación

Crea un trabajo de exportación

Consulta el estado del trabajo

Descarga el archivo

Disputas

Abre una disputa

Envía evidencia por URL

Sube un archivo de evidencia

Cierra una disputa

Códigos de respuesta

​Trabajos de exportación

​Crea un trabajo de exportación

​Consulta el estado del trabajo

​Descarga el archivo

​Disputas

​Abre una disputa

​Envía evidencia por URL

​Sube un archivo de evidencia

​Cierra una disputa

​Códigos de respuesta

Trabajos de exportación

Crea un trabajo de exportación

Consulta el estado del trabajo

Descarga el archivo

Disputas

Abre una disputa

Envía evidencia por URL

Sube un archivo de evidencia

Cierra una disputa

Códigos de respuesta