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"
}
]
}
}| Atributo | Regra |
|---|---|
inputs | Nomes 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 |
steps | De 1 a 20 etapas, executadas em ordem. Nomes únicos, no mesmo formato das entradas |
steps[].ruleset_id | Ruleset 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[].project | Opcional. 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
projectpodem ser usadas como$steps.<etapa>.matched, e só por etapas seguintes. - O derivado aparece em
GET /v1/datasetscomkind: "derived"esource_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_daysvale para todas as etapas.phasedo job traz o nome da etapa em andamento, estats.stepstem uma entrada por etapa.- Cada match tem
step, o índice da etapa que o produziu, e os eventosmatches.createdematches.possibletrazem 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.

