Pular para o conteúdo principal
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 é DRAFT → OPEN → PENDING_EVIDENCE → WON / LOST.

​
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 terminal como WON ou LOST, 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

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