Preflight the accounting routes of a ledger

Reports whether the plugin can post against one (organization, ledger) of the caller’s tenant, and the state of each canonical flow there: BOLETO_IN, PAYMENT_OUT and DARF_OUT, each complete, absent, incomplete (with the missing route codes), ambiguous (with the repeated codes) or malformed (with the code and the reason).

The routes reported are the ORGANIZATION’s: from Midaz v4.1.0 on, a listing through any ledger of the organization returns every route of it, so two ledgers of one organization report the same flows. validateRoutes and ready are the requested ledger’s.

READ-ONLY. It reads the ledger live, with GET requests only, and bypasses the accounting routes cache: nothing is posted, cached or stored, so it is safe to run right after provisioning and as often as needed.

ready is the verdict on the WHOLE ledger: a flow reported complete in a ledger that is not ready still does not post. reason names the class of the verdict: accounting_routes_not_provisioned (ready: no canonical route, and the ledger does not validate routes), accounting_routes_required_but_absent, accounting_routes_incomplete, accounting_routes_ambiguous, accounting_routes_malformed, accounting_routes_dependency_unavailable, accounting_routes_access_denied or accounting_routes_unreadable. It is absent for a ledger that holds every canonical route.

The ACCOUNTING_ROUTES_ENABLED knob is REPORTED, NOT OBEYED: the verdict is judged as if it were on, because this is what runs before it is turned on, and its current value is in accountingRoutesEnabled.

The organization comes from the X-Organization-Id header (400 PBP-0025) and the ledger from the ledgerId query parameter (400 PBP-0026). An organization or ledger the ledger does not know, for this tenant, is answered 404 without saying which.

GET /v1/admin/accounting-routes/preflight

Preflight the accounting routes of a ledger

cURL

curl --request GET \
  --url https://api.example.com/v1/admin/accounting-routes/preflight \
  --header 'Authorization: Bearer <token>'

200

{
  "accountingRoutesEnabled": true,
  "flows": [
    {
      "ambiguousRoutes": [
        "<string>"
      ],
      "flow": "BOLETO_IN",
      "missingActions": [
        "<string>"
      ],
      "missingRoutes": [
        "<string>"
      ],
      "status": "complete",
      "malformedReason": "<string>",
      "malformedRoute": "<string>"
    }
  ],
  "ledgerId": "<string>",
  "organizationId": "<string>",
  "ready": true,
  "unrecognisedMarkers": 123,
  "validateRoutes": true,
  "reason": "<string>"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Organization-Id · string

Midaz organization of the ledger to inspect. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025.

Parámetros de consulta

ledgerId · string

Midaz ledger to inspect. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026.

Respuesta

200

application/json

OK

accountingRoutesEnabled · boolean · requerido

Whether ACCOUNTING_ROUTES_ENABLED is on in this deployment. Reported, not obeyed: the verdict is judged as if it were on.

flows · object[] · requerido

One entry per canonical flow, in the order BOLETO_IN, PAYMENT_OUT, DARF_OUT. Empty when the route inventory could not be read.

Show child attributes

ledgerId · string · requerido

Ledger the preflight read, in canonical form.

organizationId · string · requerido

Organization the preflight read, in canonical form.

ready · boolean · requerido

Whether the plugin can post against this ledger as far as accounting routes are concerned. It is the verdict on the whole ledger: a complete flow in a ledger that is not ready does not post.

unrecognisedMarkers · integer<int64> · requerido

Ledger routes carrying a plugin marker the contract does not know.

validateRoutes · boolean | null · requerido

The ledger's validateRoutes setting, or null when the settings could not be read.

reason · string

Class of the verdict, from a closed vocabulary of accounting_routes_* reasons. Absent for a ledger that holds every canonical route.