Exportações e disputas

Este guia aborda dois fluxos de trabalho de operador que terminam em um artefato para download ou resolvido: jobs de exportação (enfileire um relatório, consulte seu status até que ele seja concluído e baixe o arquivo) e disputas (abra uma disputa contra uma exceção, anexe evidências e depois encerre-a como ganha ou perdida). Ambos são delimitados por tenant a partir do JWT.

Jobs de exportação

As exportações são assíncronas. Você cria um job delimitado a um contexto, consulta seu status por ID e baixa o arquivo assim que ele atinge SUCCEEDED. Os status são QUEUED, RUNNING, SUCCEEDED, FAILED, EXPIRED e CANCELED.

Criar um job de exportação

POST para a coleção export-jobs do contexto. Responde 202 Accepted com o ID do job e uma 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 — um de MATCHED, UNMATCHED, VARIANCE, EXCEPTIONS (os aliases MATCHES e UNMATCHED_TRANSACTIONS são normalizados).
format — CSV, JSON ou XML (normalizado para maiúsculas).
dateFrom / dateTo — YYYY-MM-DD opcional; dateFrom assume por padrão 30 dias antes de dateTo, e dateTo assume por padrão amanhã (UTC).
sourceId — filtro de fonte opcional.

SUMMARY e PDF não são suportados para jobs de exportação assíncronos e são rejeitados com 400. A janela de datas também tem um limite máximo de intervalo (uma requisição fora do intervalo é rejeitada em vez de ser silenciosamente ajustada).

Consultar o status do job

Leia a rota de nível superior do job (a statusUrl da criação).

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 apenas quando status é FAILED; downloadUrl aparece somente depois que o job atinge SUCCEEDED e o arquivo ainda está disponível. Você pode listar os jobs de um contexto com GET /v1/contexts/{contextId}/export-jobs, listar todos os jobs com GET /v1/export-jobs e cancelar um job enfileirado ou em execução com POST /v1/export-jobs/{jobId}/cancel.

Baixar o arquivo

Retorna uma URL pré-assinada, o nome de arquivo original, um checksum SHA-256 e o tempo de vida restante da URL em 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
}

Os arquivos de exportação são removidos após expiresAt (7 dias por padrão). Assim que um job está EXPIRED, o arquivo não pode mais ser baixado — execute a exportação novamente para regenerá-lo.

Disputas

Uma disputa é aberta contra uma exceção específica quando uma divergência de reconciliação precisa ser contestada. Seu ciclo de vida começa em DRAFT → OPEN. A partir de OPEN, uma disputa pode passar para PENDING_EVIDENCE (e voltar para OPEN) ou fechar diretamente como WON / LOST. Apenas WON é terminal — uma disputa LOST pode ser reaberta para OPEN.

Abrir uma disputa

POST para a coleção disputes da exceção.

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 é um de BANK_FEE_ERROR, UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION ou OTHER. O principal que abre a disputa é registrado em openedBy.

Enviar evidência por URL

Anexe uma referência a um arquivo de evidência já hospedado mais um comentário descritivo.

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

Fazer upload de um arquivo de evidência

Transmita os bytes brutos do arquivo diretamente para o armazenamento de objetos delimitado por tenant — o comentário viaja como parâmetro de consulta e o arquivo como corpo da requisição. Responde 201 Created com a disputa atualizada. Os tipos de conteúdo permitidos são application/pdf, image/png, image/jpeg e text/csv; o corpo tem um limite 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

Cada item de evidência armazenado é retornado no array evidence da disputa:

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

O endpoint de upload falha de forma segura com 503 quando o armazenamento de objetos não está configurado, rejeita corpos de tamanho excessivo com 413 e rejeita tipos de conteúdo fora da lista de permitidos com 415. O tenant e a disputa são sempre resolvidos a partir do JWT e do caminho — nunca a partir do corpo.

Encerrar uma disputa

Registre o resultado. won define o estado como WON (terminal) ou LOST (reabrível), com uma nota resolution obrigatória.

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

Você pode listar disputas com GET /v1/disputes (filtre por state, category, intervalo de datas; ordene e pagine por cursor) e obter uma com GET /v1/disputes/{disputeId}.

Códigos de resposta

Status	Significado
`200`	Dados de exportação/disputa retornados
`201`	Arquivo de evidência enviado
`202`	Job de exportação aceito
`400`	Entrada inválida (tipo/formato de relatório não suportado, intervalo de datas incorreto, categoria inválida)
`404`	Contexto, job de exportação, exceção ou disputa não encontrados
`409`	Transição de estado de disputa inválida
`413`	O arquivo de evidência excede o limite de 10 MiB
`415`	Tipo de conteúdo de evidência não está na lista de permitidos
`422`	Campo malformado
`503`	Armazenamento de exportação ou evidência não configurado

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Exportações e disputas

Jobs de exportação

Criar um job de exportação

Consultar o status do job

Baixar o arquivo

Disputas

Abrir uma disputa

Enviar evidência por URL

Fazer upload de um arquivo de evidência

Encerrar uma disputa

Códigos de resposta

​Jobs de exportação

​Criar um job de exportação

​Consultar o status do job

​Baixar o arquivo

​Disputas

​Abrir uma disputa

​Enviar evidência por URL

​Fazer upload de um arquivo de evidência

​Encerrar uma disputa

​Códigos de resposta

Jobs de exportação

Criar um job de exportação

Consultar o status do job

Baixar o arquivo

Disputas

Abrir uma disputa

Enviar evidência por URL

Fazer upload de um arquivo de evidência

Encerrar uma disputa

Códigos de resposta