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.

​
Engines

Register each engine once, through the engine API. An engine has an ID, a display name, its participant ISPBs, and, for Pix, the address where it receives Pix calls. 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.

​
The ownership map

Assign each account to its engine before the Courier receives messages for it. A message for an account without an owner stays retained. On Pix Automático, also assign the CNPJ of each charger that your institution serves. Each engine claims its own recurrences. 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, the messages for that key stay retained. The Courier does not credit them and does not return them to BACEN.

​
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 stay with the engine that holds the block or the schedule.

​
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.

​
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.