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.
- Read the halt reason in the channel list.
- Check with JD if the read removed a message that the Courier did not receive.
- Lift the halt with a note of 10 to 500 characters about what you checked.
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.
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.
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
updatedAtof the finding, as you read it. If a cycle found the finding again after you read it, the close answers409 JDC-0008. Read the finding again.
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.
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.
