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. Matcher limita los trabajos de exportación y las disputas a tu tenant.

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-446655440000"
}

reportType: uno de MATCHED, UNMATCHED, VARIANCE, EXCEPTIONS (los alias MATCHES y UNMATCHED_TRANSACTIONS se normalizan a estos valores).
format: CSV, JSON o XML, en 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 (400) ni PDF (422). La ventana de fechas abarca como máximo 365 días, y una ventana más larga devuelve 400. La creación del trabajo devuelve 503 cuando las exportaciones asíncronas no están habilitadas para tu entorno.

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",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "reportType": "MATCHED",
  "format": "CSV",
  "status": "SUCCEEDED",
  "recordsWritten": 4250,
  "bytesWritten": 524288,
  "fileName": "MATCHED_550e8400_20250101-20250131.csv",
  "createdAt": "2025-01-15T10:30:00Z",
  "startedAt": "2025-01-15T10:30:05Z",
  "finishedAt": "2025-01-15T10:35:00Z",
  "expiresAt": "2025-01-22T10:30:00Z",
  "downloadUrl": "/v1/export-jobs/550e8400-e29b-41d4-a716-446655440000/download"
}

contextId indica el contexto que exporta el trabajo. error lleva el último motivo de falla del trabajo, cuando tiene uno. downloadUrl es la ruta de descarga de abajo, y 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_550e8400_20250101-20250131.csv",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "expiresIn": 3600
}

Los archivos de exportación se purgan después de expiresAt, 7 días después de la creación del trabajo. Después de eso, 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. Una disputa nueva está en OPEN. Cerrarla establece WON o LOST, y ambos resultados son terminales.

Abre una disputa

POST a la colección de disputas de la excepción. Responde 201 Created.

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",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

category es uno de BANK_FEE_ERROR, UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION, AMOUNT_MISMATCH o OTHER. La respuesta omite evidence hasta que la disputa tenga alguna. El campo openedBy registra el principal que la abrió. Matcher se niega a abrir una disputa con 409 (MTCH-0511) cuando la excepción está en RESOLVED o PENDING_RESOLUTION. Responde 409 (MTCH-0510) mientras hay una liquidación en curso sobre la excepción. Repite esa solicitud cuando la liquidación termine.

Envía evidencia por URL

Adjunta una referencia a un archivo de evidencia ya alojado, junto con un comentario descriptivo. fileUrl debe ser una URL https.

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. Para un archivo cargado, fileUrl guarda la clave del almacenamiento de objetos, no una URL de descarga:

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

El endpoint de carga devuelve 503 cuando el almacenamiento de evidencias no está disponible. Rechaza los cuerpos con exceso de tamaño con 413 y los tipos de contenido fuera de la lista permitida con 415.

Cierra una disputa

Registra el resultado. won: true establece el estado en WON y won: false lo establece en LOST. Una nota resolution es 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`	Disputa abierta o archivo de evidencia cargado
`202`	Trabajo de exportación aceptado
`400`	Entrada inválida (tipo de informe `SUMMARY`, rango de fechas incorrecto, categoría inválida)
`404`	Contexto, trabajo de exportación, excepción o disputa no encontrados
`409`	Trabajo de exportación aún no listo para descarga, o ya en un estado terminal al cancelarlo. Excepción que no acepta una nueva disputa, o con una liquidación en curso
`410`	Archivo de exportación vencido
`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 (incluido un `format` en minúsculas o no admitido), o transición de estado de disputa inválida
`429`	Límite de solicitudes excedido
`503`	Exportaciones asíncronas no habilitadas para tu entorno, o almacenamiento de exportación o evidencia no disponible

Resumen

Guías

Console

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