Matching

Disparar matching de um rule set específico

POST /v1/rule-sets/{ruleSetId}/run

Sem corpo. Pega todos os registros do dataset left e enfileira em lotes.

Response 202:

{
  "status": "queued",
  "rule_set_id": "f0b1c2d3-...",
  "rule_set_name": "Conciliação banco x ERP",
  "dataset": "transacoes_banco_x",
  "records_total": 1284,
  "batches": 2,
  "jobGroupId": "a1b2c3d4-...",
  "totalBatches": 2
}

Disparar matching de um dataset (todos os rule sets aplicáveis)

POST /v1/matching-jobs/run

{
  "dataset": "transacoes_banco_x",
  "recordIds": ["uuid-opcional-1", "uuid-opcional-2"]
}

dataset é obrigatório — é o name do dataset alvo. Se omitido ou vazio, retorna 400 VALIDATION_ERROR (dataset is required).
recordIds é opcional. Se omitido, processa todos os registros do dataset.
Response 202: { status: "queued", batches, jobGroupId, totalBatches }.

Listar / consultar jobs

GET /v1/matching-jobs?dataset=&status=&from=&to=&page=&limit=
GET /v1/matching-jobs/{id}
POST /v1/matching-jobs/{id}/cancel

GET /v1/matching-jobs/{id} retorna um detalhe completo com a quebra por rule set:

{
  "id": "...",
  "dataset_name": "transacoes_banco_x",
  "job_group_id": "a1b2c3d4-...",
  "batches_expected": 2,
  "batches_completed": 2,
  "status": "completed",
  "records_total": 1284,
  "rule_sets_total": 1,
  "pairs_total": 3210,
  "pairs_processed": 3210,
  "decision_counts": { "MATCH": 412, "POSSIBLE": 88, "NO_MATCH": 2710 },
  "current_rule_set_id": null,
  "current_rule_set_name": null,
  "created_at": "2026-05-06T14:04:58.000Z",
  "started_at": "2026-05-06T14:05:00.000Z",
  "finished_at": "2026-05-06T14:05:42.000Z",
  "rule_sets": [ /* breakdown por rule set */ ],
  "average_score": 0.7821
}

Notas:

current_rule_set_id / current_rule_set_name indicam o rule set em execução enquanto o job está running; tornam‑se null ao fim.
batches_expected / batches_completed permitem montar uma barra de progresso enquanto o job não terminou.
average_score é calculado a partir dos matches gerados no job; pode ser null se nenhum match foi emitido.

Listar matches

GET /v1/matches

Query params:

Param	Descrição
`recordId`	filtra por registros (left ou right)
`dataset`	filtra por nome do dataset (qualquer dos lados)
`jobId`	filtra por job (UUID de um `matching_job`)
`decision`	`MATCH` \| `POSSIBLE` \| `NO_MATCH`
`minScore`	número (0..1)
`from`,`to`	data‑hora ISO 8601 (ignorados se `jobId` for informado)
`sortBy`	`score` \| `decision` \| `createdAt` (default `createdAt`)
`sortOrder`	`asc` \| `desc` (default `desc`)
`page`	default `1`
`limit`	1..100 (default `25`)

Response:

{
  "items": [
    {
      "id": "match-uuid",
      "left_record_id": "rec-left-uuid",
      "right_record_id": "rec-right-uuid",
      "rule_set_id": "rs-uuid",
      "score": 0.97,
      "decision": "MATCH",
      "explanation": { /* features retornadas pelo JSONata */ },
      "created_at": "2026-05-06T14:05:30.123Z"
    }
  ],
  "page": 1,
  "limit": 25,
  "total": 412
}

Detalhe individual: GET /v1/matches/{id}.

Exportação CSV (streaming): POST /v1/matches/export.csv com body { leftFields:[...], rightFields:[...], filters:{...} }.

Quando um record precisa ser conciliado contra um grupo de records do outro lado, use matching composicional. Ele cria resultados em /v1/composite-matches, mantém contadores separados (COMPOSITE_MATCH/COMPOSITE_POSSIBLE) e pode trabalhar com parciais que são completados conforme novos records chegam.

Veja o guia completo em Matching composicional.

Disparar matching de um rule set específico

Disparar matching de um dataset (todos os rule sets aplicáveis)

Listar / consultar jobs

Listar matches

Matching composicional

On this page