Openi DeveloperDeveloper
Guia de integração

Jobs e revisão

Execução de jobs, acompanhamento, dry run, cancelamento, revert, consulta de matches e revisão.

Criar um job

Um job executa um ruleset sobre um par de datasets (ou um workflow sobre os datasets de entrada) e grava os matches. Escopo write.

curl -s -X POST https://nexus-v2.openi.com.br/v1/jobs \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "ruleset_id": "<ruleset_id>",
    "left_dataset_id": "<notas_id>",
    "right_dataset_id": "<pagamentos_id>",
    "lookback_days": 90
  }'
AtributoUso
ruleset_id, left_dataset_id, right_dataset_idRuleset e par de datasets (diferentes entre si)
ruleset_versionOpcional. Padrão: a versão mais recente
workflow_id, inputs, workflow_versionEm vez do ruleset, um workflow e os datasets de cada entrada
dry_runCalcula tudo e devolve as estatísticas sem gravar matches
lookback_daysSó carrega registros ingeridos nos últimos N dias (1 a 3660). Meses mais antigos nem são lidos

Antes de enfileirar, a API compila o ruleset contra os schemas dos dois datasets. Campo inexistente, tipo incompatível ou expressão inválida devolve 422 com os erros por item, e nenhum job é criado. Se passar, a resposta é 202 com o job em queued.

Ciclo de vida

statusSignificado
queuedNa fila
runningEm execução; phase mostra a fase: compiling, loading, matching ou persisting (em workflows, com o nome da etapa)
completedTerminou e gravou os resultados; veja stats
failedFalhou; error explica o motivo e o que fazer
cancelledCancelado antes de gravar
  • Dois jobs nunca rodam ao mesmo tempo sobre o mesmo dataset: o segundo espera na fila.
  • Tenants com menos jobs em execução são atendidos primeiro.
  • Jobs grandes (size_class: "large") rodam num motor sob demanda e podem levar mais para começar.
  • Se a execução for interrompida (queda de máquina, por exemplo), o job volta para a fila e retoma da primeira etapa não gravada. attempts conta as tentativas.

Acompanhe com GET /v1/jobs/{id} ou pelos eventos job.completed, job.failed e job.cancelled. GET /v1/jobs lista os jobs, mais recentes primeiro, com filtros por status, ruleset_id, workflow_id, dataset_id, origin (api ou trigger), dry_run e período de criação.

Estatísticas

{
  "id": "0199a3f3-1b20-7a8e-9c4d-3e5f7a9b1c22",
  "status": "completed",
  "ruleset_id": "0199a3f2-9c10-7f3a-a1b2-c3d4e5f6a7b8",
  "ruleset_version": 3,
  "left_dataset_id": "0199a3f2-8a40-7e55-b1c3-4d2e6f8a9b01",
  "right_dataset_id": "0199a3f2-8b12-7c66-92d4-5e3f7a8b9c02",
  "dataset_ids": ["0199a3f2-8a40-7e55-b1c3-4d2e6f8a9b01", "0199a3f2-8b12-7c66-92d4-5e3f7a8b9c02"],
  "dry_run": false,
  "size_class": "small",
  "attempts": 1,
  "stats": {
    "matched": 1284,
    "possible": 37,
    "steps": [
      {
        "name": "main",
        "left_dataset_id": "0199a3f2-8a40-7e55-b1c3-4d2e6f8a9b01",
        "right_dataset_id": "0199a3f2-8b12-7c66-92d4-5e3f7a8b9c02",
        "left_records": 1500,
        "right_records": 1622,
        "matched": 1284,
        "possible": 37,
        "candidates": 4210,
        "evaluated": 3988,
        "eval_errors": 0,
        "truncated_keys": 0,
        "skipped_known": 4,
        "passes": [
          { "name": "documento", "candidates": 3900, "evaluated": 3710, "matched": 1201, "possible": 30 },
          { "name": "raiz-cnpj", "candidates": 310, "evaluated": 278, "matched": 52, "possible": 7 }
        ],
        "composite": { "groups": 41, "skipped_groups": 0, "targets": 58, "searches_exhausted": 0, "matched": { "1:N": 31 }, "possible": {}, "duration_ms": 12 },
        "load_strategy": "full",
        "load_ms": 310,
        "match_ms": 840,
        "dedupe_ms": 6,
        "persist_ms": 402
      }
    ]
  },
  "created_at": "2026-10-08T14:10:00.004Z",
  "started_at": "2026-10-08T14:10:00.391Z",
  "finished_at": "2026-10-08T14:10:02.118Z"
}
Campo da etapaSignificado
left_records, right_recordsRegistros abertos carregados de cada lado
candidates, evaluatedPares encontrados pelo blocking e pares pontuados
passesOs mesmos números por passada de blocking
compositeGrupos analisados, alvos, grupos pulados por tamanho, buscas esgotadas e matches por modo
truncated_keysChaves de blocking puladas por excesso de candidatos (ver Blocking)
skipped_knownResultados não gravados porque os mesmos registros já tinham sido rejeitados ou já aguardavam revisão como possible
eval_errorsAvaliações de expressão que falharam e contaram como 0

Dry run

Com dry_run: true, o job executa tudo e preenche stats, mas não grava nenhum match nem dispara matches.created. Use para calibrar pesos e limiares com dados reais antes de publicar uma versão. Workflows que projetam datasets derivados não aceitam dry run.

Cancelar

POST /v1/jobs/{id}/cancel:

  • Job na fila: cancelado na hora.
  • Job em execução: a resposta traz cancel_requested: true e o job para em poucos segundos, sem gravar nada da etapa em andamento.
  • Se o pedido chegar depois da gravação, ou o job já tiver terminado, a resposta é 409 e o job fica como está.

Reverter

POST /v1/jobs/{id}/revert desfaz todos os matches do job (matched, possible, confirmed e partial viram reverted), e os registros voltam a ficar abertos no ruleset. Vale para jobs completed que gravaram resultados, e para workflows cancelados no meio. A resposta traz quantos matches foram revertidos, e sai o evento job.reverted.

Consultar matches

EndpointUso
GET /v1/jobs/{id}/matchesOs matches de um job, com filtro por status
GET /v1/matchesBusca no tenant inteiro: job_id, ruleset_id, dataset_id, status, kind, strategy, step, score_min, score_max, record (o external_id de um registro em qualquer dataset), created_from, created_to
GET /v1/matches/{id}Um match, com os valores dos registros
GET /v1/datasets/{id}/records/{record_id}Todos os matches de um registro
GET /v1/insightsTotais de matches por ruleset e status, registros conciliados por dataset e jobs por dia nos últimos 14 dias
{
  "id": 552301,
  "ruleset_id": "0199a3f2-9c10-7f3a-a1b2-c3d4e5f6a7b8",
  "status": "matched",
  "kind": "1:1",
  "strategy": "pair",
  "score": 96.4,
  "step": 0,
  "pass": 0,
  "job_id": "0199a3f3-1b20-7a8e-9c4d-3e5f7a9b1c22",
  "breakdown": { "emitida": 1, "valor": 1, "data": 0.88, "nome": 1 },
  "left": [{ "dataset_id": "0199a3f2-8a40-7e55-b1c3-4d2e6f8a9b01", "record_id": 184467, "external_id": "NF-1" }],
  "right": [{ "dataset_id": "0199a3f2-8b12-7c66-92d4-5e3f7a8b9c02", "record_id": 90211, "external_id": "PIX-77812" }],
  "created_at": "2026-10-08T14:10:02.090Z"
}

values de cada registro só vem nas respostas de um match só (GET /v1/matches/{id} e as decisões abaixo). pass é o índice da passada de blocking (-1 na composição e no match manual), e step é a etapa do workflow (0 em jobs de um ruleset).

Revisar

StatusSignificadoAções
matchedConciliado pelo motorundo
possibleAguarda revisãoconfirm, reject
partialParcial aberto (ver Parciais)undo
confirmedpossible aceitoundo
rejectedpossible descartado; o mesmo conjunto de registros não volta a ser sugerido—
revertedDesfeito; os registros voltam a ficar abertos—
curl -s -X POST https://nexus-v2.openi.com.br/v1/matches/<match_id>/confirm \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"note": "Conferido com o extrato"}'
  • confirm, reject e undo aceitam note opcional (até 1.000 caracteres), e o horário da decisão fica em decided_at. Escopo write.
  • Ação que não vale para o status atual devolve 409.
  • Confirmar um possible cujo registro já foi conciliado por outro match do mesmo ruleset devolve 409.

Match manual

Para conciliar registros que o motor não juntou, informe o ruleset e os registros de cada lado (até 100 no total):

curl -s -X POST https://nexus-v2.openi.com.br/v1/matches \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "ruleset_id": "<ruleset_id>",
    "left": [{"dataset_id": "<notas_id>", "record_id": 184467}],
    "right": [
      {"dataset_id": "<pagamentos_id>", "record_id": 90211},
      {"dataset_id": "<pagamentos_id>", "record_id": 90214}
    ],
    "note": "Pagamento em duas partes acordado com o cliente"
  }'

O match nasce confirmed, com strategy: "manual", score 100, sem job_id, e com kind calculado pela quantidade de registros de cada lado. Os registros passam a contar como conciliados naquele ruleset. Registro inexistente devolve 422; registro já conciliado no ruleset devolve 409.

On this page