Skip to main content
This page is for the operator of your institution who runs the Courier. Each task uses the operator API that the admin role serves. Your own Access Manager application can call the operator API when it holds the Access Manager admin role. An application that is also an engine credential subject gets 403. Tenant readiness and the systemplane routes accept only a person. In single-tenant mode, every operator request acts as the tenant local, whatever tenant the token names, if any. In multi-tenant mode, the tenant comes from the validated token.

Engines


Register each engine once, through the engine API. An engine has an ID, a display name, its participant ISPBs, and the addresses where it receives Pix calls and cross-core TEDs. There is no delete. To stop an engine, disable it with a reason. A disabled engine receives no new deliveries and no new keys. It keeps the keys that it owns, so the new messages for those keys stay retained until you enable the engine again or move the keys. An engine holds one Access Manager application for each product that calls the Courier. The registration binds the first one. Bind each other one, and unbind an application that the engine no longer uses. An unbind revokes nothing: delete a leaked application in your Access Manager. You also issue and revoke the SOAP channel credential and the Pix transit credential of each engine. Registering an engine, binding or unbinding an application, and issuing or revoking a credential require the Access Manager admin role.

The ownership map


An engine can claim the accounts that it opens, the CNPJ of each Pix Automático charger that it serves, and its recurrences. Assign to each engine the keys that it does not claim. A message for an account without an owner stays retained. To find the owner of a key, list the assignments with the key kind and value. To read the changes to a key, use its audit history. When you remove a key, an engine can claim it, and the first claim takes it.

Moving accounts between engines


A migration wave moves accounts from one engine to another. Move each key with a reason. The Courier records the previous owner and the reason in the audit history. After the move, the next lookup answers the new owner. Some messages do not follow the move:
  • On SPB, the reply to a send goes to the engine that made the send.
  • On Pix, a message that an earlier attempt sent to the previous owner stays retained. The Courier does not send it to the new owner.
  • On Pix Automático, a debit, its reversal, and a schedule cancellation status follow their earlier leg. See Which key routes each call.

Retained messages


Check the retained messages every day. For these reasons, fix the cause: When the cause clears, the message leaves by itself at the next re-check. To have it checked first, request a re-evaluation with a reason. You do not choose the engine: the routing rules choose it.

SPB channel halt


The spb-consumer role halts the SPB channel when a read from JD can have removed a message that the Courier did not receive. For example, JD answers with a 5xx status other than 503, or the read times out after the request left. The halt stops the inbound SPB messages for every engine. While the channel is halted, the Courier does not read from JD, does not route, and does not re-check retained SPB messages. A restart does not lift the halt.
  1. Read the halt reason in the channel list.
  2. Check with JD if the read removed a message that the Courier did not receive.
  3. Lift the halt with a note of 10 to 500 characters about what you checked.
The Courier cannot get a removed message again. Ask JD for the message and give it to the team of the engine that owns its account.

SPB read refusals


When JD refuses the JD credential of the Courier, or fails before it reads, the spb-consumer role stores nothing and waits. The rail_spb check of /readyz reports degraded, with the reason vendor_refused for a refused credential and vendor_unavailable for a JD failure. A warning log names the JD code. The next read that JD accepts clears the reason.

Suspend the SPB rail


To stop the Courier from reading the SPB messages, suspend the SPB rail with a reason. JD keeps the messages until you activate the rail again. The history and the retained messages stay. The activation history lists each activation and suspension, with its operator and the reason of each suspension. You cannot suspend the Pix rail. The request answers 422 JDC-0304. To stop Pix, ask JD to stop sending the Pix calls to the Courier.

Indeterminate sends


An indeterminate send is an SPB send that left the Courier without a verdict from JD. A query of the engine with ConsultaNumCtrlIF can settle it. To see the sends that stay open, list the send journal with open=true. When you find the result outside the Courier, for example from the engine or from JD support, close the send by hand. Give a reference to the evidence and a note. The close is a record only:
  • The outcome stays INDETERMINATE.
  • The control number stays blocked for a new send.
  • A later query of the engine still goes to JD.
  • The send no longer counts as an open send.
The Courier has no close as NOT_SENT. If an operator was wrong about a send that “never left”, a second send of the same control number could reach BACEN.

Reconciliation


The admin role runs a reconciliation cycle for each rail every minute. A cycle checks a past time window. The reconciliation report shows these counts:
  • Expected: the outcomes that the messages of the window expect.
  • Completed: the deliveries to the engines, for each engine.
  • Retained: the messages that stay retained.
  • Refused: the messages refused by a delivery mode.
The divergence is the expected count minus the other three. A divergence that is not zero is a possible lost message: investigate it. The report also lists the SPB sends that JD accepted and whose reply did not arrive within the return window. To run a cycle now, trigger one. A rail that already runs a cycle answers 409 JDC-0601. The report gives the open findings of the rail, oldest first. A finding stays open until an operator closes it. After you investigate a finding, close it:
  • Give a note of 10 to 500 characters about what you checked.
  • Give the updatedAt of the finding, as you read it. If a cycle found the finding again after you read it, the close answers 409 JDC-0008. Read the finding again.
A closed finding stays in the history. The report also lists the closed findings, most recent closure first, with who closed each one, when, and the note. To read older closures, pass closedCursor. When a later cycle finds a new divergence, it opens a new finding. A count divergence is one finding for each rail while it is open: each divergent cycle before the close raises the same finding again. To see those cycles, list the cycles of the finding.

Transaction timing export


The Courier gives the instants that only it sees. Export them for a rail and a time window:
  • When the message arrived.
  • When the ownership decision named the engine.
  • On Pix, when the Courier gave the answer to JD.
An instant that the Courier did not see is null. To read one message, also give its endToEndId or its natural key. On Pix, correlate a transaction by its endToEndId. An asynchronous account validation gives one row for each credit.