Openi DeveloperDeveloper
Guia de integração

Workflows

Etapas de conciliação encadeadas num job só, com datasets derivados entre etapas.

Um workflow roda vários rulesets em sequência num job só. Cada etapa concilia dois datasets, e uma etapa pode usar como entrada os matches de uma etapa anterior, transformados num dataset derivado. O caso típico é a conciliação em três pontas: notas contra pagamentos e, depois, os pagamentos conciliados contra o extrato.

Definição

{
  "name": "nf-pagamento-extrato",
  "definition": {
    "inputs": ["notas", "pagamentos", "extrato"],
    "steps": [
      {
        "name": "nf-pagamento",
        "ruleset_id": "<ruleset_nf_pagamento>",
        "left": "$input.notas",
        "right": "$input.pagamentos",
        "project": [
          { "name": "doc", "type": "string", "expr": "lefts[0].doc_tomador" },
          { "name": "valor", "type": "decimal", "scale": 2, "expr": "sum(rights.map(r, r.valor))" },
          { "name": "data_credito", "type": "date", "expr": "max(rights.map(r, r.data_pagamento))" }
        ]
      },
      {
        "name": "pagamento-extrato",
        "ruleset_id": "<ruleset_pagamento_extrato>",
        "ruleset_version": 2,
        "left": "$steps.nf-pagamento.matched",
        "right": "$input.extrato"
      }
    ]
  }
}
AtributoRegra
inputsNomes das entradas (letras minúsculas, dígitos, - e _, começando por letra). Cada job informa um dataset para cada nome. Toda entrada precisa ser usada por alguma etapa
stepsDe 1 a 20 etapas, executadas em ordem. Nomes únicos, no mesmo formato das entradas
steps[].ruleset_idRuleset da etapa. ruleset_version fixa uma versão; sem ele, vale a mais recente quando o job é criado
steps[].left, steps[].right$input.<nome> ou $steps.<etapa>.matched. Os dois lados precisam ser datasets diferentes
steps[].projectOpcional. Transforma os matches da etapa num dataset derivado

Datasets derivados

Uma etapa com project gera um dataset derivado com um registro por match matched da etapa. Cada campo projetado tem nome, tipo (os mesmos tipos de dataset, com scale em decimal) e uma expressão CEL sobre lefts e rights do match. O derivado também tem o campo match_id, que liga cada registro ao match de origem.

  • Só etapas com project podem ser usadas como $steps.<etapa>.matched, e só por etapas seguintes.
  • O derivado aparece em GET /v1/datasets com kind: "derived" e source_job_id, e expira em 30 dias.
  • Workflows com projeção não aceitam dry_run.

Como a conciliação é exclusiva por ruleset, etapas com rulesets diferentes podem usar os mesmos datasets de entrada diretamente, sem derivado. Use project quando a etapa seguinte precisa comparar o resultado agregado (o total pago de uma nota, por exemplo).

Criar e versionar

POST /v1/workflows cria a versão 1, e POST /v1/workflows/{id}/versions publica uma nova versão imutável, como nos rulesets. Escopo admin. A criação confere a estrutura: nomes, referências entre etapas e sintaxe das expressões.

A checagem completa, com os rulesets de cada etapa compilados contra os schemas reais, precisa dos datasets de entrada:

curl -s -X POST https://nexus-v2.openi.com.br/v1/workflows/<workflow_id>/versions/1/validate \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"inputs": {"notas": "<notas_id>", "pagamentos": "<pagamentos_id>", "extrato": "<extrato_id>"}}'

Os erros apontam a etapa e o item: steps[1].ruleset.matchers[0].expr.

Rodar

curl -s -X POST https://nexus-v2.openi.com.br/v1/jobs \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow_id": "<workflow_id>",
    "inputs": {"notas": "<notas_id>", "pagamentos": "<pagamentos_id>", "extrato": "<extrato_id>"},
    "lookback_days": 60
  }'
  • lookback_days vale para todas as etapas.
  • phase do job traz o nome da etapa em andamento, e stats.steps tem uma entrada por etapa.
  • Cada match tem step, o índice da etapa que o produziu, e os eventos matches.created e matches.possible trazem o nome da etapa.
  • Um workflow cancelado no meio mantém o que as etapas anteriores gravaram. Para desfazer tudo, use POST /v1/jobs/{id}/revert.

Gatilhos funcionam só com rulesets. Para workflows, crie o job pela API.

On this page