components: schemas: ChannelActivation: additionalProperties: false properties: activatedAt: description: When the rail last began carrying inbound traffic. format: date-time type: string activatedBy: description: The operator who last activated or resumed the rail. Absent on an activation that predates the rail audit. maxLength: 128 type: string channelId: enum: - spb - pix type: string registeredAt: format: date-time type: string registeredBy: description: The operator who first activated the rail for the tenant. maxLength: 128 type: string state: description: Only an ACTIVE rail carries the tenant's inbound traffic. enum: - REGISTERED - ACTIVE - SUSPENDED type: string suspendReason: maxLength: 512 type: string suspendedAt: format: date-time type: string suspendedBy: description: The operator who suspended the rail. Absent when not suspended, or suspended before the rail audit. maxLength: 128 type: string tenantId: description: "The caller's tenant: the validated identity's in multi-tenant, local in single-tenant. The identifier an engine's credential path names." maxLength: 255 type: string required: - tenantId - channelId - state - registeredAt - registeredBy type: object ChannelActivationEntry: additionalProperties: false properties: action: enum: - ACTIVATED - SUSPENDED type: string actor: description: The operator who made the change. maxLength: 128 type: string changedAt: format: date-time type: string reason: description: The suspension's reason; absent on an activation. maxLength: 512 type: string required: - action - actor - changedAt type: object ChannelActivationHistoryPage: additionalProperties: false properties: items: items: $ref: "#/components/schemas/ChannelActivationEntry" type: array limit: format: int64 minimum: 1 type: integer page: format: int64 minimum: 1 type: integer required: - items - page - limit type: object ChannelCredential: additionalProperties: false properties: createdAt: format: date-time type: string createdBy: type: string credentialId: description: Id of this credential, for revocation type: string engineId: type: string legacyCode: description: "The value the engine configures as its JD legacy code (TAutenticacao CdLegado): 10 random base62 characters. Returned once." type: string secret: description: "The value the engine configures as its JD password (TAutenticacao Senha): 20 random base62 characters. Returned once." type: string userCode: description: "The value the engine configures as its JD user code (TAutenticacao CdUsuario): 10 random base62 characters." type: string required: - credentialId - engineId - legacyCode - userCode - secret - createdAt - createdBy type: object ChannelDescriptor: additionalProperties: false properties: channelId: enum: - spb - pix type: string consumerTopology: enum: - SINGLE_WRITER - STATELESS type: string deliveryModes: items: enum: - SINGLE_ENGINE - ALL_ENGINES - REFUSE type: string type: array durabilityRule: enum: - PERSIST_BEFORE_DECIDE - PERSIST_BEFORE_ACK type: string financialFamilies: items: maxLength: 64 type: string type: array ingressModel: enum: - DRAIN_PULL - TERMINATED_PUSH type: string moneyBearingFamilies: items: maxLength: 64 type: string type: array ownershipKinds: items: type: string type: array retentionReasons: items: type: string type: array required: - channelId - ingressModel - consumerTopology - durabilityRule - financialFamilies - deliveryModes - ownershipKinds - retentionReasons type: object ChannelLease: additionalProperties: false properties: channelId: type: string consumerState: type: string epoch: format: int64 type: integer heartbeatAt: format: date-time type: string holderId: type: string lastLift: $ref: "#/components/schemas/LeaseLift" required: - channelId - holderId - epoch - consumerState - heartbeatAt type: object ChannelList: additionalProperties: false properties: items: items: $ref: "#/components/schemas/ChannelListItem" type: array required: - items type: object ChannelListItem: additionalProperties: false properties: descriptor: $ref: "#/components/schemas/ChannelDescriptor" state: $ref: "#/components/schemas/ChannelState" required: - descriptor - state type: object ChannelState: additionalProperties: false properties: activation: description: "Null when the rail was never activated for the tenant: it carries none of its inbound traffic." oneOf: - $ref: "#/components/schemas/ChannelActivation" - type: "null" channelId: enum: - spb - pix type: string lastReconciliationAt: format: date-time type: - string - "null" lease: description: Null on a rail with no single-writer consumer, or before its drain first ran. oneOf: - $ref: "#/components/schemas/ConsumerLease" - type: "null" reconciliationRunning: type: boolean required: - channelId type: object ClaimOwnershipKeysRequest: additionalProperties: false properties: keys: items: $ref: "#/components/schemas/OwnershipClaimKey" maxItems: 1000 minItems: 1 type: - array - "null" required: - keys type: object CloseByHandRequest: additionalProperties: false properties: evidenceReference: description: "Where the finding can be checked: the engine's settle or revert, a JD support ticket. Non-blank, at most 512 characters after trimming, without NUL, or 422 JDC-0002." type: string note: description: What the operator established. 10 to 500 characters after trimming, without NUL, or 422 JDC-0002. type: string required: - evidenceReference - note type: object CloseFindingInputBody: additionalProperties: false properties: expectedUpdatedAt: description: "The finding's updatedAt as read. A cycle that re-raised it since answers 409: re-read it." format: date-time type: string note: description: What the operator checked and settled. 10 to 500 characters after trimming, with no NUL. type: string required: - note - expectedUpdatedAt type: object ConsumerLease: additionalProperties: false properties: epoch: format: int64 minimum: 0 type: integer haltReason: maxLength: 64 type: - string - "null" heartbeatAt: description: The holder's last heartbeat. format: date-time type: string held: description: "A holder is recorded and its heartbeat is inside the lease TTL (SPB_LEASE_TTL_SEC, database clock). False on a stale heartbeat: a lease another holder may take over." type: boolean holderId: maxLength: 128 type: - string - "null" lastProgressAt: description: The drain's last completed read of the vendor queue, empty or not. format: date-time type: - string - "null" progressAgeSeconds: format: int64 minimum: 0 type: integer state: enum: - consuming - idle - halted_ambiguous - awaiting_retry type: string required: - held - epoch - heartbeatAt - state type: object CreateOwnershipAssignmentRequest: additionalProperties: false properties: account: description: "ACCOUNT only: the account number, digits with an optional trailing check-digit letter." maxLength: 256 type: string branch: description: "ACCOUNT only: a current account's branch, 1 to 4 digits. Omit it, or send it empty, for a payment account, which has none; empty is never branch 0." maxLength: 256 type: string engineId: pattern: ^[a-z0-9-]{1,32}$ type: string keyKind: enum: - ACCOUNT - DOCUMENT - PIX_KEY_EMAIL - PIX_KEY_PHONE - PIX_KEY_RANDOM - PAYMENT_ID - PIX_RECURRENCE_ID - PIX_RECURRENCE_ID_CHARGER type: string keyValue: description: Raw value, for every kind except ACCOUNT. The Courier normalizes per kind — do not pre-normalize. maxLength: 256 minLength: 1 type: string note: description: Recorded in the audit. Recommended during a wave migration. maxLength: 512 type: string required: - keyKind - engineId type: object CredentialSubjectRequest: additionalProperties: false properties: credentialSubject: description: An Access Manager credential subject, /. maxLength: 256 minLength: 1 type: string required: - credentialSubject type: object Delivery: additionalProperties: false properties: attempts: description: How many times the delivery was reopened after bytes had been handed over or had failed to be. format: int64 type: integer channelId: type: string engineId: type: string messageId: type: string requestedAt: format: date-time type: string state: enum: - PENDING - DELIVERED - REDELIVER_REQUESTED - FAILED type: string required: - messageId - channelId - engineId - state - requestedAt - attempts type: object DeliveryModeRule: additionalProperties: false properties: channelId: enum: - spb - pix type: string declaredAt: format: date-time type: string declaredBy: maxLength: 128 type: string messageCode: pattern: ^[A-Za-z0-9_.-]{1,32}$ type: string mode: enum: - ALL_ENGINES - REFUSE type: string reason: maxLength: 512 type: string revokedAt: description: Non-null means this row is history. format: date-time type: - string - "null" revokedBy: maxLength: 128 type: - string - "null" ruleId: format: uuid type: string required: - ruleId - channelId - messageCode - mode - reason - declaredBy - declaredAt type: object DeliveryModeRulePage: additionalProperties: false properties: items: items: $ref: "#/components/schemas/DeliveryModeRule" type: - array - "null" limit: format: int64 minimum: 1 type: integer page: format: int64 minimum: 1 type: integer required: - items - page - limit type: object Detail: additionalProperties: true properties: code: description: "Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN)." type: string detail: description: A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: "#/components/schemas/ErrorDetail" type: - array - "null" instance: description: A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: "#/components/schemas/Upstream" description: "RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one." type: object Engine: additionalProperties: false properties: createdAt: format: date-time type: string credentialSubjects: description: Every Access Manager credential subject that authenticates as this engine, one per calling product, sorted. items: maxLength: 256 type: string type: array disabledAt: format: date-time type: - string - "null" displayName: maxLength: 128 type: string enabled: type: boolean engineId: pattern: ^[a-z0-9-]{1,32}$ type: string participants: items: pattern: ^[0-9]{8}$ type: string type: array pixDelivery: $ref: "#/components/schemas/PixDeliveryTarget" tedDelivery: $ref: "#/components/schemas/TEDDeliveryTarget" required: - engineId - displayName - enabled - credentialSubjects - participants - createdAt type: object EngineList: additionalProperties: false properties: items: items: $ref: "#/components/schemas/Engine" type: - array - "null" required: - items type: object ErrorDetail: additionalProperties: false properties: location: description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object LeaseLift: additionalProperties: false properties: at: format: date-time type: string by: type: string haltReason: type: string note: type: string required: - by - at - note - haltReason type: object MergedCycle: additionalProperties: false properties: cycleId: maxLength: 64 type: string divergence: description: E − (C + T + R) of that cycle; never zero here. format: int64 type: integer generatedAt: format: date-time type: string required: - cycleId - generatedAt - divergence type: object MergedCyclesPage: additionalProperties: false properties: items: description: Most recent first, at most 1000. items: $ref: "#/components/schemas/MergedCycle" type: array nextCursor: description: Pass as cursor for the older cycles; null on the last page. type: - string - "null" required: - items - nextCursor type: object MissingReturnLeg: additionalProperties: false properties: controlId: type: string engineId: maxLength: 32 type: string required: - engineId - controlId type: object MoveOwnershipRequest: additionalProperties: false properties: reason: description: Required. This is a human decision about where money lands. maxLength: 512 minLength: 1 type: string toEngineId: pattern: ^[a-z0-9-]{1,32}$ type: string required: - toEngineId - reason type: object OwnershipAssignment: additionalProperties: false properties: assignmentId: format: uuid type: string engineId: pattern: ^[a-z0-9-]{1,32}$ type: string keyKind: enum: - ACCOUNT - DOCUMENT - PIX_KEY_EMAIL - PIX_KEY_PHONE - PIX_KEY_RANDOM - PAYMENT_ID - PIX_RECURRENCE_ID - PIX_RECURRENCE_ID_CHARGER type: string keyValue: description: Normalized form. This is what the rails resolve against. ACCOUNT is :, and : for a payment account. maxLength: 256 type: string keyValueRaw: description: Exactly what the operator typed. maxLength: 256 type: string previousEngineId: description: Present after a move. type: - string - "null" updatedAt: format: date-time type: string updatedBy: maxLength: 128 type: string required: - assignmentId - keyKind - keyValue - engineId - updatedAt type: object OwnershipAssignmentPage: additionalProperties: false properties: items: items: $ref: "#/components/schemas/OwnershipAssignment" type: - array - "null" limit: format: int64 minimum: 1 type: integer page: format: int64 minimum: 1 type: integer required: - items - page - limit type: object OwnershipAuditEntry: additionalProperties: false properties: actor: maxLength: 128 type: string changedAt: format: date-time type: string keyKind: enum: - ACCOUNT - DOCUMENT - PIX_KEY_EMAIL - PIX_KEY_PHONE - PIX_KEY_RANDOM - PAYMENT_ID - PIX_RECURRENCE_ID - PIX_RECURRENCE_ID_CHARGER type: string keyValue: maxLength: 256 type: string newEngineId: description: Null when the assignment was removed. type: - string - "null" previousEngineId: description: Null on the first assignment. type: - string - "null" reason: maxLength: 512 type: - string - "null" required: - keyKind - keyValue - actor - changedAt type: object OwnershipAuditPage: additionalProperties: false properties: items: items: $ref: "#/components/schemas/OwnershipAuditEntry" type: - array - "null" limit: format: int64 minimum: 1 type: integer page: format: int64 minimum: 1 type: integer required: - items - page - limit type: object OwnershipClaimKey: additionalProperties: false properties: account: description: "ACCOUNT only: the account number, digits with an optional trailing check-digit letter." maxLength: 256 type: string branch: description: "ACCOUNT only: a current account's branch, 1 to 4 digits. A payment account is claimed WITHOUT a branch: omit it or send it empty, never 0." maxLength: 256 type: string keyKind: enum: - ACCOUNT - DOCUMENT - PIX_RECURRENCE_ID_CHARGER type: string keyValue: description: "DOCUMENT: a Pix Automático charger's CNPJ. PIX_RECURRENCE_ID_CHARGER: the idRecorrencia of a recurrence whose charger the engine holds. As held; do not pre-normalize." maxLength: 256 type: string required: - keyKind type: object OwnershipClaimReport: additionalProperties: false properties: results: items: $ref: "#/components/schemas/OwnershipClaimResult" type: - array - "null" required: - results type: object OwnershipClaimResult: additionalProperties: false properties: outcome: enum: - CLAIMED - ALREADY_OWNED - HELD_ELSEWHERE - INVALID type: string required: - outcome type: object OwnershipLookupRequest: additionalProperties: false properties: account: description: "ACCOUNT only: the account number, digits with an optional trailing check-digit letter." maxLength: 256 type: string branch: description: "ACCOUNT only: a current account's branch, 1 to 4 digits. Omit it, or send it empty, for a payment account, which has none; empty is never branch 0." maxLength: 256 type: string keyKind: description: The kind of key. enum: - ACCOUNT - DOCUMENT - PIX_KEY_EMAIL - PIX_KEY_PHONE - PIX_KEY_RANDOM - PAYMENT_ID - PIX_RECURRENCE_ID - PIX_RECURRENCE_ID_CHARGER type: string keyValue: description: The key as the caller holds it, for every kind except ACCOUNT. Do not pre-normalize. maxLength: 256 minLength: 1 type: string required: - keyKind type: object OwnershipResolution: additionalProperties: false properties: engineId: description: Present only when resolved is true. type: string keyKind: enum: - ACCOUNT - DOCUMENT - PIX_KEY_EMAIL - PIX_KEY_PHONE - PIX_KEY_RANDOM - PAYMENT_ID - PIX_RECURRENCE_ID - PIX_RECURRENCE_ID_CHARGER type: string keyValue: description: The normalized form the Courier resolved against. maxLength: 256 type: string ownedByCaller: description: "Present only when resolved is true: whether the owner is the engine whose credential made this call. Compare on this; an engine never needs its own registry id." type: boolean resolved: type: boolean resolvedAt: format: date-time type: string source: enum: - ASSIGNMENT_MAP type: string required: - resolved - keyKind - keyValue - source - resolvedAt type: object PixCredential: additionalProperties: false properties: clientId: description: "The value the engine configures as its JD client_id: the tenant id, a dot and 20 random base62 characters. Returned once." type: string clientSecret: description: "The value the engine configures as its JD client_secret: 40 random base62 characters. Returned once." type: string createdAt: format: date-time type: string createdBy: type: string credentialId: description: Id of this credential, for revocation type: string engineId: type: string required: - credentialId - engineId - clientId - clientSecret - createdAt - createdBy type: object PixDeliveryTarget: additionalProperties: false properties: baseUrl: description: "The engine's Pix address, absolute http(s). The vendor's route path is appended verbatim. Empty on an update removes the target." maxLength: 2048 type: string credentialRef: description: "A reference to the Courier's own client credential at the engine: the id of a versioned secret under this tenant, jd-courier and this engine, exactly tenants/{environment}/{tenantId}/jd-courier/external/pix-engine-{engineId}/credentials/versions/{uuid}, or 422 JDC-0002. Never the secret itself. Omitted: delivered with no credential." maxLength: 512 type: string required: - baseUrl type: object ReconciliationCycleAccepted: additionalProperties: false properties: channelId: enum: - spb - pix type: string cycleId: maxLength: 64 type: string startedAt: format: date-time type: string required: - cycleId - channelId - startedAt type: object ReconciliationEngineCount: additionalProperties: false properties: delivered: format: int64 minimum: 0 type: integer engineId: maxLength: 32 type: string required: - engineId - delivered type: object ReconciliationFinding: additionalProperties: false properties: channelId: enum: - spb - pix type: string closed: $ref: "#/components/schemas/ReconciliationFindingClosure" description: The operator's close; absent while the finding is open and pages. detail: description: "For COUNT_DIVERGENCE, the first line is the first detection and the latest: line the most recent cycle that still saw it." type: string detectedAt: format: date-time type: string engineIds: description: The engines involved; empty on a divergence. items: type: string type: array findingId: format: uuid type: string subjectReference: description: The send's control identifier for MISSING_RETURN_LEG; reconciliation: for COUNT_DIVERGENCE. type: string type: description: "What pages: a cycle whose E = C + T + R did not hold, or a send with no captured return leg." enum: - COUNT_DIVERGENCE - MISSING_RETURN_LEG type: string updatedAt: description: Moves each time a cycle re-raises the finding. Send it back as expectedUpdatedAt to close. format: date-time type: string required: - findingId - type - channelId - subjectReference - engineIds - detail - detectedAt - updatedAt type: object ReconciliationFindingClosure: additionalProperties: false properties: closedAt: format: date-time type: string closedBy: type: string note: type: string required: - closedBy - closedAt - note type: object ReconciliationReport: additionalProperties: false properties: channelCount: format: int64 minimum: 0 type: integer channelId: enum: - spb - pix type: string closedFindings: description: The findings closed on this channel, whichever cycle is reported, most recent closure first, at most 100, each with who closed it, when and the note. items: $ref: "#/components/schemas/ReconciliationFinding" type: array closedFindingsNextCursor: description: Pass as closedCursor for the older closures; null on the last page. type: - string - "null" cycleId: maxLength: 64 type: string divergence: description: E − (C + T + R). Non-zero is an alert. format: int64 type: integer engineCounts: description: "C per engine: completed deliveries whose engine is in the message's frozen resolved set." items: $ref: "#/components/schemas/ReconciliationEngineCount" type: array expectedOutcomeCount: description: E, summed from each message's own stored expectation, never recomputed. format: int64 minimum: 0 type: integer generatedAt: format: date-time type: string historyUnjudgedBefore: description: "Set on a channel's first cycle when the channel was registered more than a day before reconciliation first ran: nothing captured or sent before this instant was judged, and a divergence older than it is never reconciled automatically. Null when the cycle judged all it could." format: date-time type: - string - "null" missingReturnLegs: description: Sends whose return-leg window closed during this cycle with no captured message echoing their control identifier. Each one pages. items: $ref: "#/components/schemas/MissingReturnLeg" type: array openFindings: description: "The findings open on this channel NOW, whichever cycle is reported, oldest first, at most 1000: what pages until an operator closes it with POST /v1/assurance/findings/{findingId}/close." items: $ref: "#/components/schemas/ReconciliationFinding" type: array openFindingsTruncated: description: True when more findings are open than openFindings lists. type: boolean refusedCount: format: int64 minimum: 0 type: integer retainedCount: format: int64 minimum: 0 type: integer returnLegWindowSeconds: description: A send with no captured return leg older than this pages. format: int64 minimum: 1 type: integer sequenceGapCount: description: "Holes in the channel's own sequence over the cycle, or over the range when from/to are given; null when no sequence was measured: the rail has none, or no key that arrived could be read as one. Counted and exposed, never paged: the vendor numbers the whole cabin in one sequence, so a hole is usually another legacy system's message." format: int64 type: - integer - "null" sequenceGaps: description: The holes, oldest cycle first, each with the cycle that saw it; null when no sequence was measured, as for sequenceGapCount. At most 1000; sequenceGapsTruncated says when there were more. items: $ref: "#/components/schemas/SequenceGap" type: - array - "null" sequenceGapsTruncated: description: "True when sequenceGapCount is larger than the list returned: narrow the range to see the rest." type: boolean sequenceRegressions: description: "Arrivals at or below the sequence before them: a reorder or a reset, never a gap." format: int64 minimum: 0 type: integer windowEnd: format: date-time type: string windowSeconds: description: The declared window. A divergence inside it may be a message in transit; outside it, a loss candidate. format: int64 minimum: 1 type: integer windowStart: description: The capture instants this cycle judged, [windowStart, windowEnd). Consecutive cycles tile time. format: date-time type: string required: - cycleId - channelId - windowSeconds - windowStart - windowEnd - generatedAt - channelCount - expectedOutcomeCount - engineCounts - retainedCount - refusedCount - divergence - historyUnjudgedBefore - sequenceGapCount - sequenceGaps - sequenceGapsTruncated - sequenceRegressions - returnLegWindowSeconds - missingReturnLegs - openFindings - openFindingsTruncated - closedFindings - closedFindingsNextCursor type: object RedeliverInputBody: additionalProperties: false properties: engineId: description: Must be one of the message's frozen resolvedEngineIds. type: string reason: description: Why the message is served again. 1 to 512 characters after trimming, with no NUL. type: string required: - engineId - reason type: object ReevaluateInputBody: additionalProperties: false properties: reason: description: Why the decision should be run again. 1 to 512 characters after trimming, with no NUL. type: string required: - reason type: object ReevaluationRequest: additionalProperties: false properties: pending: description: True until the rail tries the routing decision again, on its next pass; a try that failed also answers the request. type: boolean reason: type: string requestedAt: format: date-time type: string requestedBy: type: string required: - requestedBy - requestedAt - reason - pending type: object RegisterEngineRequest: additionalProperties: false properties: credentialSubject: description: The engine's first Access Manager credential subject; bind more with POST /v1/engines/{engineId}/credential-subjects. A subject binds at most one engine, disabled ones included. maxLength: 256 minLength: 1 type: string displayName: maxLength: 128 type: string engineId: pattern: ^[a-z0-9-]{1,32}$ type: string participants: description: "The direct-participant ISPBs this engine acts as. Omitted or empty is legal, and an ISPB another engine already declares is accepted: a shared ISPB across two cores is the coexistence case itself." items: pattern: ^[0-9]{8}$ type: string type: - array - "null" pixDelivery: $ref: "#/components/schemas/PixDeliveryTarget" description: "Where the Courier delivers the Pix messages the ownership map gives this engine; https in production, and setting it needs the admin grant (engines pix-delivery:write). Omitted: the engine takes none, and such a message is retained." tedDelivery: $ref: "#/components/schemas/TEDDeliveryTarget" description: "Where the Courier relays the cross-core TED the ownership map gives this engine; https in production, and setting it needs the admin grant (engines ted-delivery:write). Omitted: the engine takes none, and a relay to it is refused." required: - engineId - credentialSubject type: object ResumeInputBody: additionalProperties: false properties: note: description: "Why the halt is lifted: what the operator checked about the read that may have lost a message. 10 to 500 characters after trimming, with no NUL." type: string required: - note type: object RetainedMessage: additionalProperties: false properties: channelId: enum: - spb - pix type: string messageId: format: uuid type: string receivedAt: format: date-time type: string reevaluatedAt: description: The last time the rail tried its routing decision again and the message stayed retained, whether the decision ran or failed; null when it never tried. format: date-time type: - string - "null" reevaluation: $ref: "#/components/schemas/ReevaluationRequest" description: The last operator request to re-evaluate it; null when nobody asked. releasable: description: "True when the cause is routing or delivery: no owner in the map, a map that could not answer, an owner disabled or unreachable, no delivery mode declared for its code. Only these are re-checked by themselves once the cause lifts, and only these can be re-evaluated; a Pix retention also clears when the vendor resends it. An UNRECOGNIZED_TYPE of a non-financial code releases once a delivery mode is declared for its code and is not re-checked before that; one of a financial code releases on the re-check after a Courier release reads its destination." type: boolean retainedAt: format: date-time type: string retentionReason: type: string unassignedKey: $ref: "#/components/schemas/UnassignedKey" description: "ACCOUNT_UNASSIGNED only: the key the Courier looked up in the ownership map and found no owner for. Assign it (POST /v1/ownership/assignments) and the message is released on its next re-check: for ACCOUNT, send the text before ':' as branch (empty means a payment account) and the text after it as account; any other kind takes keyValue as shown. A raw key (one the map cannot hold) cannot be assigned; it needs a person. Null for every other reason, and for a Pix leg that waits on an earlier leg of its payment, which no key routes." required: - messageId - channelId - retentionReason - releasable - receivedAt - retainedAt - reevaluatedAt type: object RetainedMessagePage: additionalProperties: false properties: items: items: $ref: "#/components/schemas/RetainedMessage" type: - array - "null" limit: format: int64 minimum: 1 type: integer page: format: int64 minimum: 1 type: integer required: - items - page - limit type: object SendHandClose: additionalProperties: false properties: closedAt: format: date-time type: string closedBy: type: string evidenceReference: type: string note: type: string required: - closedAt - closedBy - evidenceReference - note type: object SendQueryHistory: additionalProperties: false properties: count: format: int64 minimum: 1 type: integer lastAnswer: description: "VENDOR: forwarded, answered by JD. LOCAL_ALN01: the send never left, answered by the Courier." enum: - VENDOR - LOCAL_ALN01 type: string lastQueriedAt: format: date-time type: string required: - count - lastQueriedAt - lastAnswer type: object SendRecord: additionalProperties: false properties: ageSeconds: description: "Present while the outcome is INDETERMINATE: seconds since the send left, growing, for an open send; frozen at closedAt minus sentAt once an operator closed it by hand, because a closed send no longer ages for the alert." format: int64 type: integer channelId: enum: - spb type: string closedByHand: description: "An operator's by-hand close; null unless one was recorded. A record only: the outcome is unchanged." oneOf: - $ref: "#/components/schemas/SendHandClose" - type: "null" controlId: type: string engineId: description: Originating engine; this field routes the SPB return leg. type: string outcome: enum: - DETERMINED - INDETERMINATE - RESOLVED - NOT_SENT type: string queries: description: The engine's ConsultaNumCtrlIF trail for this send; null until the first. oneOf: - $ref: "#/components/schemas/SendQueryHistory" - type: "null" resolution: description: How the vendor's own answer settled an indeterminate send; null until it did. oneOf: - $ref: "#/components/schemas/SendResolution" - type: "null" sentAt: format: date-time type: string vendorCode: type: - string - "null" vendorSequence: type: - string - "null" required: - controlId - engineId - channelId - sentAt - outcome - vendorCode - vendorSequence - resolution - queries - closedByHand type: object SendRecordPage: additionalProperties: false properties: items: items: $ref: "#/components/schemas/SendRecord" type: array limit: format: int64 minimum: 1 type: integer page: format: int64 minimum: 1 type: integer required: - items - page - limit type: object SendResolution: additionalProperties: false properties: actualOutcome: enum: - REACHED_VENDOR - DID_NOT_REACH_VENDOR type: string means: type: string note: type: string resolvedAt: format: date-time type: string resolvedBy: type: string required: - resolvedAt - means - actualOutcome - resolvedBy - note type: object SequenceGap: additionalProperties: false properties: afterKey: type: string beforeKey: type: string cycleId: description: The cycle that saw the hole. maxLength: 64 type: string missingCount: description: "How many sequence numbers are missing, as a decimal string: the vendor's counter is twenty digits." type: string required: - cycleId - afterKey - beforeKey - missingCount type: object SetDeliveryModeRequest: additionalProperties: false properties: mode: enum: - ALL_ENGINES - REFUSE type: string reason: maxLength: 512 minLength: 1 type: string required: - mode - reason type: object SuspendChannelRequest: additionalProperties: false properties: reason: description: Required — a suspension stops the rail's inbound traffic for the tenant. maxLength: 512 minLength: 1 type: string required: - reason type: object TEDDeliveryTarget: additionalProperties: false properties: baseUrl: description: "The engine's TED address, absolute http(s). The cross-core relay's path is appended verbatim. Empty on an update removes the target." maxLength: 2048 type: string credentialRef: description: "A reference to the Courier's own client credential at the engine: the id of a versioned secret under this tenant, jd-courier and this engine, exactly tenants/{environment}/{tenantId}/jd-courier/external/ted-engine-{engineId}/credentials/versions/{uuid}, or 422 JDC-0002. Never the secret itself. Omitted: delivered with no credential." maxLength: 512 type: string required: - baseUrl type: object TransactionTiming: additionalProperties: false properties: ackedAt: description: The latest instant a delivered answer was handed back to the vendor; a vendor resend replaces it. Null until one is handed back, and always on SPB, a drain the Courier answers nothing on. On an asynchronous validation, the instant the Courier made the call durable; its 202 leaves only after that write commits, and a resend does not replace it. format: date-time type: - string - "null" channelId: enum: - spb - pix type: string classification: description: The message's family; null when it could not be classified. PIX_ASYNC_VALIDATION is one credit of an asynchronous validation (JDPI §9.3.4), a row per credit, keyed by naturalKey and endToEndId. type: - string - "null" decidedAt: description: "When the ownership decision named the engine. Null when none did: a retained message, a refusal by declared rule, one still in flight. Never inferred." format: date-time type: - string - "null" endToEndId: description: "Pix: the transaction's own endToEndId, the id each core keys its report on (endToEndIdDevolucao on a return). Null on SPB and on a route that names none." type: - string - "null" messageId: description: The message's id. On an asynchronous validation, the idValidacaoSgct the Courier answered, shared by each of its credits. format: uuid type: string naturalKey: description: "The message's identity on its rail: the vendor sequence on SPB, the route-prefixed key on Pix. Null when the content was too damaged to yield one." type: - string - "null" outcome: description: Where the message stands, so a missing instant can be explained. enum: - CAPTURED - ASSIGNED - RETAINED - REFUSED - CLOSED type: string receivedAt: description: When the vendor's bytes became durable here. format: date-time type: string required: - messageId - channelId - naturalKey - endToEndId - classification - receivedAt - decidedAt - ackedAt - outcome type: object TransactionTimingPage: additionalProperties: false properties: items: items: $ref: "#/components/schemas/TransactionTiming" type: array limit: format: int64 minimum: 1 type: integer nextCursor: description: Pass as cursor for the next page; null on the last one. type: - string - "null" required: - items - limit - nextCursor type: object UnassignedKey: additionalProperties: false properties: keyKind: enum: - ACCOUNT - DOCUMENT - PIX_KEY_EMAIL - PIX_KEY_PHONE - PIX_KEY_RANDOM - PAYMENT_ID - PIX_RECURRENCE_ID - PIX_RECURRENCE_ID_CHARGER type: string keyValue: description: "Normalized, as the map holds it: ACCOUNT is :, and : for a payment account. A TED account the map cannot hold is shown raw, as the message carries it." maxLength: 256 type: string required: - keyKind - keyValue type: object UpdateEngineRequest: additionalProperties: false properties: displayName: maxLength: 128 type: string enabled: type: boolean participants: description: Replaces the engine's participant set. items: pattern: ^[0-9]{8}$ type: string type: array pixDelivery: $ref: "#/components/schemas/PixDeliveryTarget" description: Replaces where the Courier delivers this engine's Pix messages; an empty baseUrl removes it. https in production, and it needs the admin grant (engines pix-delivery:write). reason: description: Recorded on the change. Required for a disable. maxLength: 512 type: string tedDelivery: $ref: "#/components/schemas/TEDDeliveryTarget" description: Replaces where the Courier relays this engine's cross-core TED; an empty baseUrl removes it. https in production, and it needs the admin grant (engines ted-delivery:write). type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http engineCredentials: description: An Access Manager application token whose subject is bound to exactly one engine; an engine may hold several, one per calling product. It reaches only the operations its scopes name; the operator surface refuses it. flows: clientCredentials: scopes: cross-core:send: Send a same-bank payment to the core that owns the payee account ownership:read: Read the ownership map ownership:write: Claim accounts, charger documents or a Pix Automático recurrence, or declare a Pix Automático payment leg, for the calling engine alone tokenUrl: https://access-manager.example.com/v1/login/oauth/access_token type: oauth2 info: contact: email: support@lerian.studio name: Lerian Studio Support description: JD Courier lets several core engines share one JD channel and one ISPB on the SPB and Pix rails. Operators use this API to register the engines, keep the ownership map that decides which engine each message belongs to, activate the rails, re-run the routing of retained messages and reconcile what the channel carried. Engines use it to resolve and claim ownership and to relay a same-bank payment to the core that owns the payee account; their SPB sends and reads go through the Courier's mirror of the vendor's SOAP surface, and their Pix calls through its JDPI transit, not through this API. license: name: Lerian Studio General License title: JD Courier API version: v1.0.0 openapi: 3.1.0 paths: /v1/assurance/findings/{findingId}/close: post: description: "An operator who investigated and settled a finding closes it with a mandatory note and the finding's updatedAt as read. The Courier records who closed it, when and the note; the finding stays in history and stops counting toward jdc_assurance_open_findings, so its alert clears on the next tick. A cycle that re-raised the finding after it was read answers 409 JDC-0008: re-read it, so no window is closed unread. A finding already closed answers 200 with its first closure, never overwritten. A later cycle that sees a new divergence opens a new finding. Idempotent per X-Idempotency: the same key with another body is 409 JDC-0003." operationId: closeAssuranceFinding parameters: - description: The finding, from the reconciliation report's openFindings. Another tenant's finding is a 404. in: path name: findingId required: true schema: description: The finding, from the reconciliation report's openFindings. Another tenant's finding is a 404. type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CloseFindingInputBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReconciliationFinding" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Close a reconciliation finding tags: - assurance x-mint: href: /pt/reference/interfaces/jd-courier/close-a-reconciliation-finding /v1/channels: get: description: "The rail contract, made visible: what each rail declares about itself and its state for the caller's tenant. Listing requires an identified operator holding channels:read, because the listing returns registeredBy, activatedBy and suspendedBy, operator identities: the rail's first registrant and its last activator and suspender." operationId: listChannels responses: "200": content: application/json: schema: $ref: "#/components/schemas/ChannelList" description: OK "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: List the registered rails, their declared properties and their state tags: - channels x-mint: href: /pt/reference/interfaces/jd-courier/list-the-registered-rails-their-declared-properties-and-their-state /v1/channels/{channelId}/activation: delete: description: "Stops a rail drained from a vendor queue (spb) for the tenant: the drain stops reading the queue, which keeps its messages until the rail is activated again. History and retained messages stay. A rail whose vendor pushes keeps nothing while stopped, so suspending it is refused 422 JDC-0304: a Pix stop is a vendor-side repoint, never this operation. A suspension records its operator as suspendedBy and in the rail's history. Idempotent: a rail never activated or already suspended answers 204, records nothing and keeps its first reason and operator. Needs the admin grant (channels activation:write)." operationId: suspendChannel parameters: - description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. in: path name: channelId required: true schema: description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. enum: - spb - pix type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SuspendChannelRequest" required: true responses: "204": description: No Content "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Suspend a rail for the caller's tenant tags: - channels x-mint: href: /pt/reference/interfaces/jd-courier/suspend-a-rail-for-the-caller-s-tenant put: description: "Until a rail is active for a tenant the Courier carries none of its inbound traffic: the Pix ingress resolves no tenant and the SPB drain reads nothing from the vendor. Engine sends, queries and mailbox reads pass regardless; to stop an engine's sends, disable the engine, which also stops its deliveries. Activating spb starts the drain of the vendor queue, whose read is destructive: from then on the Courier, not the engines, consumes it. The tenant is the caller's, the validated identity's in multi-tenant and local in single-tenant, and is returned as tenantId — the identifier an engine's credential path names. The first activation records the operator as registeredBy; every activation that changes the state, first or resume, records it as activatedBy and in the rail's history. Activating a suspended rail resumes it; an active one is returned unchanged and records nothing. A single-tenant Courier carries one tenant per rail: activating a rail another tenant holds active is refused 409 JDC-0117. Needs the admin grant (channels activation:write); channels write is not enough." operationId: activateChannel parameters: - description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. in: path name: channelId required: true schema: description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. enum: - spb - pix type: string - description: Idempotency key; a retry with the same key replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key replays the first answer. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ChannelActivation" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Activate a rail for the caller's tenant tags: - channels x-mint: href: /pt/reference/interfaces/jd-courier/activate-a-rail-for-the-caller-s-tenant /v1/channels/{channelId}/activation-history: get: description: "Every activation and suspension that changed the rail's state for the caller's tenant, most recent first, with its operator and, on a suspension, its reason. Insert-only: audit is data, not a log line. A rail with no history answers an empty page. Needs channels:read." operationId: listChannelActivationHistory parameters: - description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. in: path name: channelId required: true schema: description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. enum: - spb - pix type: string - description: Page, 1-based. explode: false in: query name: page schema: default: 1 description: Page, 1-based. format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 200 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ChannelActivationHistoryPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: A rail's activation history for the caller's tenant tags: - channels x-mint: href: /pt/reference/interfaces/jd-courier/a-rails-activation-history-for-the-callers-tenant /v1/channels/{channelId}/delivery-modes: get: description: "Only the exceptions to single-owner delivery live here; a code with no declaration is delivered to the engine that owns its destination. A financial family can never appear: the rail's own financialFamilies is the authority. Revoked declarations stay readable with includeRevoked=true, newest first." operationId: listDeliveryModes parameters: - description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. in: path name: channelId required: true schema: description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. enum: - spb - pix type: string - description: Page, 1-based. explode: false in: query name: page schema: default: 1 description: Page, 1-based. format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 200 minimum: 1 type: integer - explode: false in: query name: mode schema: enum: - ALL_ENGINES - REFUSE type: string - description: Revoked rules are history, not configuration. explode: false in: query name: includeRevoked schema: default: false description: Revoked rules are history, not configuration. type: boolean responses: "200": content: application/json: schema: $ref: "#/components/schemas/DeliveryModeRulePage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: List the per-code delivery-mode declarations on a rail tags: - channels x-mint: href: /pt/reference/interfaces/jd-courier/list-the-per-code-delivery-mode-declarations-on-a-rail /v1/channels/{channelId}/delivery-modes/{messageCode}: delete: description: "Idempotent. Revocation is not deletion: the row stays readable, and messages already routed under it keep the expected outcome count they were frozen with." operationId: revokeDeliveryMode parameters: - description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. in: path name: channelId required: true schema: description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. enum: - spb - pix type: string - description: The vendor's own message code, verbatim. in: path name: messageCode required: true schema: description: The vendor's own message code, verbatim. type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string responses: "204": description: No Content "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Revoke a code's declaration and restore the single-owner default tags: - channels x-mint: href: /pt/reference/interfaces/jd-courier/revoke-a-code-s-declaration-and-restore-the-single-owner-default put: description: "Declares that a code takes every engine or is refused instead of the single-owner default. The reason is mandatory. Two refusals, both on the write and neither at delivery: 422 JDC-0110 when the rail lists the code among its financial families, and 422 JDC-0112 when the rail does not declare the mode. Deliveries stay one row per (message, engine); the expectation is frozen onto each message at routing. Idempotent per (channelId, messageCode, mode, reason)." operationId: declareDeliveryMode parameters: - description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. in: path name: channelId required: true schema: description: The rail. Closed vocabulary — a value outside it is a 404, never a new rail. enum: - spb - pix type: string - description: The vendor's own message code, verbatim. in: path name: messageCode required: true schema: description: The vendor's own message code, verbatim. type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SetDeliveryModeRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DeliveryModeRule" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Declare the delivery mode for one message code tags: - channels x-mint: href: /pt/reference/interfaces/jd-courier/declare-the-delivery-mode-for-one-message-code /v1/channels/{channelId}/lease/resume: post: description: The SPB drain halts its channel, on the lease row, when a destructive read may have removed a message the Courier never received. Nothing is taken from the vendor until an operator lifts it here; a restart never does. The note is mandatory and, with the operator and the halt it cleared, is kept on the lease row and written to the audit log. Idempotent per X-Idempotency. operationId: resumeChannelLease parameters: - description: The channel whose durable halt is lifted. Only spb holds a lease. in: path name: channelId required: true schema: description: The channel whose durable halt is lifted. Only spb holds a lease. type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ResumeInputBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ChannelLease" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Lift a durable channel halt tags: - channel-leases x-mint: href: /pt/reference/interfaces/jd-courier/lift-a-durable-channel-halt /v1/channels/{channelId}/reconciliation: get: description: "Answers \"did we lose a message?\" by evaluating E(m) = C(m) + T(m) + R(m) per rail over a declared window. What pages: a non-zero divergence, and a send with no captured return leg past the return-leg window. What does not: a hole in the vendor's sequence, which is counted and listed here: the vendor numbers the whole cabin in one sequence, so a hole is usually another legacy system's message. Whichever cycle is reported, it lists the rail's open findings and its closed ones with their closure; closedCursor pages to older closures. The Courier deletes no cycle and no closure: they are audit evidence, and the client defines how long its database keeps them." operationId: getReconciliationReport parameters: - description: The rail. A value outside the vocabulary, or a rail this build does not carry, is a 404. in: path name: channelId required: true schema: description: The rail. A value outside the vocabulary, or a rail this build does not carry, is a 404. type: string - description: A specific cycle. Omitted returns the most recent. explode: false in: query name: cycleId schema: description: A specific cycle. Omitted returns the most recent. maxLength: 64 type: string - description: RFC 3339. With to, lists the sequence gaps of every cycle whose window overlaps [from, to), each with its cycle. One bound alone leaves the other open. Both omitted list the reported cycle's own gaps. explode: false in: query name: from schema: description: RFC 3339. With to, lists the sequence gaps of every cycle whose window overlaps [from, to), each with its cycle. One bound alone leaves the other open. Both omitted list the reported cycle's own gaps. maxLength: 64 type: string - description: RFC 3339; see from. explode: false in: query name: to schema: description: RFC 3339; see from. maxLength: 64 type: string - description: "The closedFindingsNextCursor of a previous report: lists the closures older than its page. Its format is not contract." explode: false in: query name: closedCursor schema: description: "The closedFindingsNextCursor of a previous report: lists the closures older than its page. Its format is not contract." maxLength: 512 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReconciliationReport" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Reconciliation report for a rail tags: - assurance x-mint: href: /pt/reference/interfaces/jd-courier/reconciliation-report-for-a-rail /v1/channels/{channelId}/reconciliation/findings/{findingId}/cycles: get: description: "A COUNT_DIVERGENCE is one finding per rail while it is open: every divergent cycle until an operator closes it re-raises the same finding. This lists those cycles, most recent first, each openable with the report's ?cycleId=, from the detection to the close, or to now while it is open. A cycle that completes while the close commits may also be listed on the finding opened after it." operationId: listFindingMergedCycles parameters: - description: The rail the finding is on. in: path name: channelId required: true schema: description: The rail the finding is on. type: string - description: A COUNT_DIVERGENCE finding, open or closed. Another tenant's, another rail's, or another kind is a 404. in: path name: findingId required: true schema: description: A COUNT_DIVERGENCE finding, open or closed. Another tenant's, another rail's, or another kind is a 404. type: string - description: The nextCursor of the previous page, as returned. Its format is not contract. explode: false in: query name: cursor schema: description: The nextCursor of the previous page, as returned. Its format is not contract. maxLength: 512 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MergedCyclesPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Cycles a count divergence merged tags: - assurance x-mint: href: /pt/reference/interfaces/jd-courier/cycles-a-count-divergence-merged /v1/channels/{channelId}/reconciliation/tick: post: description: Runs one cycle now and answers once it is recorded. A cycle already running on this (tenant, channel) answers 409 JDC-0601 rather than starting a second; a cycle on one rail never blocks the other. operationId: triggerReconciliationCycle parameters: - description: The rail. in: path name: channelId required: true schema: description: The rail. type: string - description: Idempotency key; a retry with the same key replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key replays the first answer. type: string responses: "202": content: application/json: schema: $ref: "#/components/schemas/ReconciliationCycleAccepted" description: Accepted "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Trigger a reconciliation cycle for a rail tags: - assurance x-mint: href: /pt/reference/interfaces/jd-courier/trigger-a-reconciliation-cycle-for-a-rail /v1/cross-core/pix/cash-ins: post: description: "The body crosses byte-verbatim to {address}/v1/cross-core/pix/cash-ins at the owner's Pix address, with the Courier's credential there, Content-Type, Chave-Idempotencia when sent, and X-Courier-Origin-Engine, the caller's engine id read from its credential. One attempt, inside 15 s; the payer resends the identical bytes while the outcome is unknown." operationId: crossCorePixCashIns parameters: - description: The engine id the payer's own map lookup returned for the payee account. in: header name: X-Courier-Expected-Owner required: true schema: type: string - description: The payee's idempotency key, forwarded as sent. in: header name: Chave-Idempotencia schema: type: string requestBody: content: application/json: schema: type: object required: true responses: "400": description: "JDC-0001, not-sent: the body is not a UTF-8 JSON object, or X-Courier-Expected-Owner is missing." "401": description: "JDC-0401, no marker: the credential is not an enabled engine's granted cross-core:send. Nothing was sent." "409": description: "Not-sent. JDC-0118: no engine owns the payee account. JDC-0119: the owner is not X-Courier-Expected-Owner; it moved, and after an earlier unknown attempt the payer parks the item. JDC-0121: the owner is the caller itself." "422": description: "JDC-0104, not-sent: the payee account cannot be read from the body: its account, and its branch unless it is a payment account." "503": description: "Not-sent. JDC-9001: the map or the registry is not readable. JDC-0120: the owner is disabled, declares no address for the rail, could not be reached, redirected or refused the Courier's credential. JDC-0902: the licence is revoked. A call whose request reached the payee and whose answer did not come back within 15 s gets no status at all: its connection is closed." default: description: "The payee engine's answer, status, Content-Type and body as it wrote them, with no X-Send-Outcome: it reached the engine the map names. A payee that redirects or refuses the Courier's credential never took the call, and is the Courier's 503 JDC-0120 instead." security: - engineCredentials: - cross-core:send summary: Relay a cross-core Pix cash-in tags: - cross-core x-mint: href: /pt/reference/interfaces/jd-courier/relay-a-cross-core-pix-cash-in /v1/cross-core/pix/refunds: post: description: "The body crosses byte-verbatim to {address}/v1/cross-core/pix/refunds at the owner's Pix address, with the Courier's credential there, Content-Type, Chave-Idempotencia when sent, and X-Courier-Origin-Engine, the caller's engine id read from its credential. One attempt, inside 15 s; the payer resends the identical bytes while the outcome is unknown." operationId: crossCorePixRefunds parameters: - description: The engine id the payer's own map lookup returned for the payee account. in: header name: X-Courier-Expected-Owner required: true schema: type: string - description: The payee's idempotency key, forwarded as sent. in: header name: Chave-Idempotencia schema: type: string requestBody: content: application/json: schema: type: object required: true responses: "400": description: "JDC-0001, not-sent: the body is not a UTF-8 JSON object, or X-Courier-Expected-Owner is missing." "401": description: "JDC-0401, no marker: the credential is not an enabled engine's granted cross-core:send. Nothing was sent." "409": description: "Not-sent. JDC-0118: no engine owns the payee account. JDC-0119: the owner is not X-Courier-Expected-Owner; it moved, and after an earlier unknown attempt the payer parks the item. JDC-0121: the owner is the caller itself." "422": description: "JDC-0104, not-sent: the payee account cannot be read from the body: its account, and its branch unless it is a payment account." "503": description: "Not-sent. JDC-9001: the map or the registry is not readable. JDC-0120: the owner is disabled, declares no address for the rail, could not be reached, redirected or refused the Courier's credential. JDC-0902: the licence is revoked. A call whose request reached the payee and whose answer did not come back within 15 s gets no status at all: its connection is closed." default: description: "The payee engine's answer, status, Content-Type and body as it wrote them, with no X-Send-Outcome: it reached the engine the map names. A payee that redirects or refuses the Courier's credential never took the call, and is the Courier's 503 JDC-0120 instead." security: - engineCredentials: - cross-core:send summary: Relay a cross-core Pix refund tags: - cross-core x-mint: href: /pt/reference/interfaces/jd-courier/relay-a-cross-core-pix-refund /v1/cross-core/ted/credits: post: description: "The body crosses byte-verbatim to {address}/v1/cross-core/ted/credits at the owner's TED address, with the Courier's credential there, Content-Type, Chave-Idempotencia when sent, and X-Courier-Origin-Engine, the caller's engine id read from its credential. One attempt, inside 15 s; the payer resends the identical bytes while the outcome is unknown." operationId: crossCoreTedCredits parameters: - description: The engine id the payer's own map lookup returned for the payee account. in: header name: X-Courier-Expected-Owner required: true schema: type: string - description: The payee's idempotency key, forwarded as sent. in: header name: Chave-Idempotencia schema: type: string requestBody: content: application/json: schema: type: object required: true responses: "400": description: "JDC-0001, not-sent: the body is not a UTF-8 JSON object, or X-Courier-Expected-Owner is missing." "401": description: "JDC-0401, no marker: the credential is not an enabled engine's granted cross-core:send. Nothing was sent." "409": description: "Not-sent. JDC-0118: no engine owns the payee account. JDC-0119: the owner is not X-Courier-Expected-Owner; it moved, and after an earlier unknown attempt the payer parks the item. JDC-0121: the owner is the caller itself." "422": description: "JDC-0104, not-sent: the payee account cannot be read from the body: its account, and its branch unless it is a payment account." "503": description: "Not-sent. JDC-9001: the map or the registry is not readable. JDC-0120: the owner is disabled, declares no address for the rail, could not be reached, redirected or refused the Courier's credential. JDC-0902: the licence is revoked. A call whose request reached the payee and whose answer did not come back within 15 s gets no status at all: its connection is closed." default: description: "The payee engine's answer, status, Content-Type and body as it wrote them, with no X-Send-Outcome: it reached the engine the map names. A payee that redirects or refuses the Courier's credential never took the call, and is the Courier's 503 JDC-0120 instead." security: - engineCredentials: - cross-core:send summary: Relay a cross-core TED credit tags: - cross-core x-mint: href: /pt/reference/interfaces/jd-courier/relay-a-cross-core-ted-credit /v1/cross-core/ted/returns: post: description: "The body crosses byte-verbatim to {address}/v1/cross-core/ted/returns at the owner's TED address, with the Courier's credential there, Content-Type, Chave-Idempotencia when sent, and X-Courier-Origin-Engine, the caller's engine id read from its credential. One attempt, inside 15 s; the payer resends the identical bytes while the outcome is unknown." operationId: crossCoreTedReturns parameters: - description: The engine id the payer's own map lookup returned for the payee account. in: header name: X-Courier-Expected-Owner required: true schema: type: string - description: The payee's idempotency key, forwarded as sent. in: header name: Chave-Idempotencia schema: type: string requestBody: content: application/json: schema: type: object required: true responses: "400": description: "JDC-0001, not-sent: the body is not a UTF-8 JSON object, or X-Courier-Expected-Owner is missing." "401": description: "JDC-0401, no marker: the credential is not an enabled engine's granted cross-core:send. Nothing was sent." "409": description: "Not-sent. JDC-0118: no engine owns the payee account. JDC-0119: the owner is not X-Courier-Expected-Owner; it moved, and after an earlier unknown attempt the payer parks the item. JDC-0121: the owner is the caller itself." "422": description: "JDC-0104, not-sent: the payee account cannot be read from the body: its account, and its branch unless it is a payment account." "503": description: "Not-sent. JDC-9001: the map or the registry is not readable. JDC-0120: the owner is disabled, declares no address for the rail, could not be reached, redirected or refused the Courier's credential. JDC-0902: the licence is revoked. A call whose request reached the payee and whose answer did not come back within 15 s gets no status at all: its connection is closed." default: description: "The payee engine's answer, status, Content-Type and body as it wrote them, with no X-Send-Outcome: it reached the engine the map names. A payee that redirects or refuses the Courier's credential never took the call, and is the Courier's 503 JDC-0120 instead." security: - engineCredentials: - cross-core:send summary: Relay a cross-core TED return tags: - cross-core x-mint: href: /pt/reference/interfaces/jd-courier/relay-a-cross-core-ted-return /v1/engines: get: description: "Every per-engine behavior iterates this list. Not paginated: an engine registry that needs pagination is an incident, not a scale requirement." operationId: listEngines parameters: - description: Filter by enablement. Omitted returns both. explode: false in: query name: enabled schema: description: Filter by enablement. Omitted returns both. type: boolean responses: "200": content: application/json: schema: $ref: "#/components/schemas/EngineList" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: List the registered engines tags: - Engines x-mint: href: /pt/reference/interfaces/jd-courier/list-the-registered-engines post: description: "Adding an engine is a configuration operation, not a software delivery. credentialSubject is the engine's first credential; bind one per further calling product with bindEngineCredentialSubject. A credential subject binds at most one engine. Admin only (engines credential-subjects:write): a bound credential acts as the engine." operationId: registerEngine parameters: - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterEngineRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/Engine" description: Created "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Register an engine tags: - Engines x-mint: href: /pt/reference/interfaces/jd-courier/register-an-engine /v1/engines/{engineId}: patch: description: There is no delete. A disabled engine receives no new deliveries, cannot receive new ownership assignments, and keeps every row it already owns. A disable requires a reason. operationId: updateEngine parameters: - description: An engine in the registry. in: path name: engineId required: true schema: description: An engine in the registry. type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateEngineRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/Engine" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Enable, disable or rename an engine tags: - Engines x-mint: href: /pt/reference/interfaces/jd-courier/enable-disable-or-rename-an-engine /v1/engines/{engineId}/channel-credential: post: description: "Mints the three TAutenticacao values the engine presents to the Courier's /soap. The secret is returned once. Minting while a credential is live is the rotation: the older credentials keep working for the configured overlap window, then stop. The credential is stored only in the tenant's own database: on a send, the tenant manager lists the tenants and the tenant database that holds the legacy code authenticates; there is no shared index. Admin only (engines credentials:write)." operationId: mintEngineChannelCredential parameters: - in: path name: engineId required: true schema: type: string - description: "Idempotency key. The answer carries a one-time secret and is never stored: a resend under the same key is refused 409, never replayed; a refused mint releases its key." in: header name: X-Idempotency required: true schema: description: "Idempotency key. The answer carries a one-time secret and is never stored: a resend under the same key is refused 409, never replayed; a refused mint releases its key." type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/ChannelCredential" description: Created "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Issue the engine's SOAP channel credential tags: - Engines x-mint: href: /pt/reference/interfaces/jd-courier/issue-the-engine-s-soap-channel-credential /v1/engines/{engineId}/channel-credential/{credentialId}/revoke: post: description: Ends the credential now, inside an overlap window or not. Who revoked it is recorded on the credential. Admin only (engines credentials:write). operationId: revokeEngineChannelCredential parameters: - in: path name: engineId required: true schema: type: string - in: path name: credentialId required: true schema: format: uuid type: string - description: Idempotency key; a retry with the same key replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key replays the first answer. type: string responses: "204": description: No Content "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Revoke one of the engine's SOAP channel credentials tags: - Engines x-mint: href: /pt/reference/interfaces/jd-courier/revoke-one-of-the-engine-s-soap-channel-credentials /v1/engines/{engineId}/credential-subjects: post: description: The subject then authenticates as this engine on the engine surfaces. One engine holds one credential per calling product (the Lerian core's Pix and TED plugins are one engine, each with its own); a subject binds at most one engine, disabled ones included, so a subject another engine holds is 409 JDC-0114. Binding a subject the engine already holds changes nothing. Admin only (engines credential-subjects:write). operationId: bindEngineCredentialSubject parameters: - description: An engine in the registry. in: path name: engineId required: true schema: description: An engine in the registry. type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CredentialSubjectRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/Engine" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Bind one more credential to the engine tags: - Engines x-mint: href: /pt/reference/interfaces/jd-courier/bind-one-more-credential-to-the-engine /v1/engines/{engineId}/credential-subjects/unbind: post: description: "The subject stops authenticating as this engine at once; the engine, what it owns and its other credentials stay as they are. It revokes nothing: an unbound credential holding admin passes the operator surface, so a leaked one is deleted in the Access Manager. A subject this engine does not hold is 404 JDC-0109. Admin only (engines credential-subjects:write)." operationId: unbindEngineCredentialSubject parameters: - description: An engine in the registry. in: path name: engineId required: true schema: description: An engine in the registry. type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CredentialSubjectRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/Engine" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Unbind one of the engine's credentials tags: - Engines x-mint: href: /pt/reference/interfaces/jd-courier/unbind-one-of-the-engines-credentials /v1/engines/{engineId}/pix-credential: post: description: "Mints the client_id and client_secret the engine presents at the Pix transit's JDPI token path (JDPI §8.1.1), where the Courier answers with a bearer of its own, verified in the tenant's database on every call. The secret is returned once. Minting while a Pix credential is live is the rotation: the older ones and their bearers keep working for the configured overlap window, then stop. Admin only (engines credentials:write)." operationId: mintEnginePixCredential parameters: - in: path name: engineId required: true schema: type: string - description: "Idempotency key. The answer carries a one-time secret and is never stored: a resend under the same key is refused 409, never replayed; a refused mint releases its key." in: header name: X-Idempotency required: true schema: description: "Idempotency key. The answer carries a one-time secret and is never stored: a resend under the same key is refused 409, never replayed; a refused mint releases its key." type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/PixCredential" description: Created "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Issue the engine's Pix transit credential tags: - Engines x-mint: href: /pt/reference/interfaces/jd-courier/issue-the-engines-pix-transit-credential /v1/engines/{engineId}/pix-credential/{credentialId}/revoke: post: description: Ends the credential and every bearer it was answered with now, inside an overlap window or not. Who revoked it is recorded on the credential. Admin only (engines credentials:write). operationId: revokeEnginePixCredential parameters: - in: path name: engineId required: true schema: type: string - in: path name: credentialId required: true schema: format: uuid type: string - description: Idempotency key; a retry with the same key replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key replays the first answer. type: string responses: "204": description: No Content "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Revoke one of the engine's Pix transit credentials tags: - Engines x-mint: href: /pt/reference/interfaces/jd-courier/revoke-one-of-the-engines-pix-transit-credentials /v1/messages/{messageId}/redeliver: post: description: "Serves a message again without asking the vendor: the delivery goes to REDELIVER_REQUESTED and the engine's next RecebeMensagem hands it the stored bytes, the vendor's NumCabSeq unchanged, so the engine's sequence index absorbs the repeat. The engine must be one the message was resolved to (JDC-0113 otherwise). The operator and the reason are kept on the delivery row, the most recent request overwriting the one before. SPB rail only. Idempotent per X-Idempotency." operationId: redeliverMessage parameters: - description: The message's surrogate id (UUIDv7). in: path name: messageId required: true schema: description: The message's surrogate id (UUIDv7). format: uuid type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RedeliverInputBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/Delivery" description: Accepted "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Reopen the delivery of a message to an engine tags: - ledger x-mint: href: /pt/reference/interfaces/jd-courier/reopen-the-delivery-of-a-message-to-an-engine /v1/ownership/assignments: get: description: "Offset pagination: the set is bounded by the client's account base, not by time. Filter by keyKind + keyValue to resolve an exact key." operationId: listOwnershipAssignments parameters: - description: Page, 1-based. explode: false in: query name: page schema: default: 1 description: Page, 1-based. format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 200 minimum: 1 type: integer - description: Filter by owning engine. explode: false in: query name: engineId schema: description: Filter by owning engine. type: string - explode: false in: query name: keyKind schema: enum: - ACCOUNT - DOCUMENT - PIX_KEY_EMAIL - PIX_KEY_PHONE - PIX_KEY_RANDOM - PAYMENT_ID - PIX_RECURRENCE_ID - PIX_RECURRENCE_ID_CHARGER type: string - description: Exact match after per-kind normalization, for every kind except ACCOUNT. Requires keyKind. explode: false in: query name: keyValue schema: description: Exact match after per-kind normalization, for every kind except ACCOUNT. Requires keyKind. maxLength: 256 type: string - description: "ACCOUNT only, with account: a current account's branch. Omit it for a payment account." explode: false in: query name: branch schema: description: "ACCOUNT only, with account: a current account's branch. Omit it for a payment account." maxLength: 256 type: string - description: "ACCOUNT only: the account number, with branch for a current account. Alone, it matches the payment account only." explode: false in: query name: account schema: description: "ACCOUNT only: the account number, with branch for a current account. Alone, it matches the payment account only." maxLength: 256 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/OwnershipAssignmentPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: List ownership assignments tags: - ownership x-mint: href: /pt/reference/interfaces/jd-courier/list-ownership-assignments post: description: "A double owner is inexpressible: a key owned by a different engine is refused 409 JDC-0102, which points at the move operation. Re-assigning to the current owner is a no-op answered 200, with no new audit entry." operationId: createOwnershipAssignment parameters: - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateOwnershipAssignmentRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/OwnershipAssignment" description: Already assigned to this engine. No new audit entry. "201": content: application/json: schema: $ref: "#/components/schemas/OwnershipAssignment" description: Created "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Assign a key to an engine tags: - ownership x-mint: href: /pt/reference/interfaces/jd-courier/assign-a-key-to-an-engine /v1/ownership/assignments/{assignmentId}: delete: description: "Idempotent: an absent assignment answers 204 too. Afterwards the key is unassigned, and the first core that claims it at POST /v1/ownership/claims takes it; to keep its traffic retained, move it to the right engine or disable the engine instead. The audit records the removal with the previous owner; read it by the key at POST /v1/ownership/audit/lookup, since this assignment id answers 404 from now on." operationId: deleteOwnershipAssignment parameters: - description: Surrogate identifier of the assignment. Find one by keyKind + keyValue on the collection. in: path name: assignmentId required: true schema: description: Surrogate identifier of the assignment. Find one by keyKind + keyValue on the collection. format: uuid type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string responses: "204": description: No Content "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Unassign a key tags: - ownership x-mint: href: /pt/reference/interfaces/jd-courier/unassign-a-key get: operationId: getOwnershipAssignment parameters: - description: Surrogate identifier of the assignment. Find one by keyKind + keyValue on the collection. in: path name: assignmentId required: true schema: description: Surrogate identifier of the assignment. Find one by keyKind + keyValue on the collection. format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/OwnershipAssignment" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Read one ownership assignment tags: - ownership x-mint: href: /pt/reference/interfaces/jd-courier/read-one-ownership-assignment /v1/ownership/assignments/{assignmentId}/audit: get: description: Insert-only, most recent first, with author, time, previous and new value. Audit is data, not a log line. operationId: listOwnershipAudit parameters: - description: Surrogate identifier of the assignment. Find one by keyKind + keyValue on the collection. in: path name: assignmentId required: true schema: description: Surrogate identifier of the assignment. Find one by keyKind + keyValue on the collection. format: uuid type: string - description: Page, 1-based. explode: false in: query name: page schema: default: 1 description: Page, 1-based. format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 200 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/OwnershipAuditPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Ownership history for one key tags: - ownership x-mint: href: /pt/reference/interfaces/jd-courier/ownership-history-for-one-key /v1/ownership/assignments/{assignmentId}/move: post: description: The migration-wave operation. Records the previous owner and the reason. Once the move commits, the next lookup answers the new owner. On the SPB rail an operation already in flight resolves to the engine that originated it. On the Pix rail a message decided after the move reaches the new owner, and one an earlier attempt already sent to the previous owner is retained for a person, never sent to the new one. A Pix Automático debit, its reversal and a schedule's cancellation status stay with the engine that holds the payment's block or schedule, whoever owns the account after the move. operationId: moveOwnershipAssignment parameters: - description: Surrogate identifier of the assignment. Find one by keyKind + keyValue on the collection. in: path name: assignmentId required: true schema: description: Surrogate identifier of the assignment. Find one by keyKind + keyValue on the collection. format: uuid type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/MoveOwnershipRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/OwnershipAssignment" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Move a key to another engine tags: - ownership x-mint: href: /pt/reference/interfaces/jd-courier/move-a-key-to-another-engine /v1/ownership/audit/lookup: post: description: "The same history as the by-assignment route, addressed by the key sent as held, normalized exactly as the lookup normalizes it. It needs no live assignment, so the history of a removed key — the removal included — stays readable. Most recent first. A read: it changes nothing and takes no X-Idempotency. The key travels in the body because it is personal data; a malformed key is refused 422 JDC-0104 with a fixed sentence that never repeats it." operationId: lookupOwnershipAudit parameters: - description: Page, 1-based. explode: false in: query name: page schema: default: 1 description: Page, 1-based. format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 200 minimum: 1 type: integer requestBody: content: application/json: schema: $ref: "#/components/schemas/OwnershipLookupRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/OwnershipAuditPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Ownership history for one key, addressed by the key tags: - ownership x-mint: href: /pt/reference/interfaces/jd-courier/ownership-history-for-one-key-addressed-by-the-key /v1/ownership/claims: post: description: "Each core claims every account it opens, when it opens it, and before its cutover loads the accounts it already holds the same way, in pages of up to 1000 keys. ACCOUNT takes account, plus branch for a current account. A PAYMENT ACCOUNT IS CLAIMED WITHOUT A BRANCH: omit branch or send it empty, never 0, because the Pix rail looks payment accounts up without one, and a payment account claimed with a branch is a key nothing reads. DOCUMENT takes keyValue, a Pix Automático charger's CNPJ. PIX_RECURRENCE_ID_CHARGER takes keyValue, the idRecorrencia of a recurrence whose charger the caller holds: the charger's side, which takes the schedule cancellations the payer's PSP asked for; the payer's side is claimed at PUT /v1/ownership/recurrences/{recurrenceId}. A key the map does not hold is still retained ACCOUNT_UNASSIGNED. 200 answers one result per key, in request order, never repeating the key: CLAIMED, the key is now the caller's; ALREADY_OWNED, it already was and nothing changed; HELD_ELSEWHERE, the JDC-0102 fact: another engine holds the key, so report it to an operator, because only an operator moves a key; INVALID, the JDC-0104 fact: the key is not usable and nothing was written for it. One key's outcome never fails another. 422 JDC-0002: no key, or more than 1000. 422 JDC-0104: a key carries bytes that are not valid UTF-8, and the whole call is refused. 503, a dropped connection or a timeout: the call may have stopped part-way and some keys may be recorded; send the same call again, it is idempotent. The owner is always the caller." operationId: claimOwnershipKeys requestBody: content: application/json: schema: $ref: "#/components/schemas/ClaimOwnershipKeysRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/OwnershipClaimReport" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable security: - engineCredentials: - ownership:write summary: Claim accounts, charger documents and recurrence charger sides for the calling engine tags: - ownership-query x-mint: href: /pt/reference/interfaces/jd-courier/claim-accounts-charger-documents-and-recurrence-charger-sides-for-the-calling-engine /v1/ownership/lookup: post: description: "Authoritative, never advisory. 200 resolved:true names the owning engine; 200 resolved:false is a decided negative — nobody's key, or another tenant's, indistinguishably; 503 means the Courier cannot answer and the caller fails the payment closed. This operation never answers 404. A POST that reads: the key is personal data and travels in the body, never in a URL. An engine treats ANY status other than 200 and 422 as fail-closed — 404, 405, 429 and every 5xx included — and keys on the code (JDC-9001), never on the detail sentence. The 503 sentence names what could not answer — the ownership map, or the engine credential (registry or tenant database) — and both tell the engine to fail closed." operationId: lookupOwnership requestBody: content: application/json: schema: $ref: "#/components/schemas/OwnershipLookupRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/OwnershipResolution" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable security: - engineCredentials: - ownership:read summary: Resolve which engine owns a key tags: - ownership-query x-mint: href: /pt/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key /v1/ownership/payments/{endToEndId}/legs/{leg}: put: description: "Before the Courier takes over Pix, each engine declares the payments in flight whose earlier leg it already answered yes: the debit block (block) of every payment whose debit or reversal is still to come, and the schedule (schedule) of every schedule whose debit, reversal or cancellation status is still to come; with no accepted block, the debit and its reversal follow the schedule. Those later legs then reach the caller. A later leg that arrived first is retained and is released by the Courier's re-check once its leg is declared. A leg the Courier itself dispatched outranks any declaration unless its engine answered other than yes. 201: the leg now follows the caller. 204: it already did. 409 JDC-0116: the Courier's record gives the leg to another engine, or holds the caller's answer to the block that was not a yes; stop and report it to an operator. 422 JDC-0104: the leg or the endToEndId is not usable. 503: nothing may have been recorded; send the same declaration again, it is idempotent. The holder is always the caller." operationId: declarePixPaymentLeg parameters: - description: The payment's endToEndId as JD sent it. in: path name: endToEndId required: true schema: description: The payment's endToEndId as JD sent it. type: string - description: "block: the debit block a debit and its reversal follow. schedule: the schedule its cancellation status follows, and its debit and reversal when no block was accepted." in: path name: leg required: true schema: description: "block: the debit block a debit and its reversal follow. schedule: the schedule its cancellation status follows, and its debit and reversal when no block was accepted." enum: - block - schedule type: string responses: "201": description: Created "204": description: The leg already followed the caller; nothing changed. "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable security: - engineCredentials: - ownership:write summary: Declare an earlier leg of a Pix Automático payment the calling engine holds tags: - ownership-query x-mint: href: /pt/reference/interfaces/jd-courier/declare-an-earlier-leg-of-a-pix-automatico-payment-the-calling-engine-holds /v1/ownership/recurrences/{recurrenceId}: put: description: "The engine that authorizes a recurrence claims it, and the Courier then routes the recurrence's messages to it. 201: the recurrence is now the caller's. 204: it already was. 409 JDC-0102: another engine holds it; stop and report it to an operator, because only an operator moves a recurrence. 422 JDC-0104: the recurrenceId is not usable. 503: nothing was recorded; send the same claim again, it is idempotent. The owner is always the caller: an engine claims only for itself, and only a key no engine holds." operationId: claimPixRecurrence parameters: - description: The idRecorrencia as JD issued it. in: path name: recurrenceId required: true schema: description: The idRecorrencia as JD issued it. type: string responses: "201": description: Created "204": description: The recurrence already was the caller's; nothing changed. "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable security: - engineCredentials: - ownership:write summary: Claim a Pix Automático recurrence for the calling engine tags: - ownership-query x-mint: href: /pt/reference/interfaces/jd-courier/claim-a-pix-automatico-recurrence-for-the-calling-engine /v1/reporting/transaction-timing: get: description: "Input to a report, never a report: each core composes and submits its own BACEN report; the Courier composes none and submits nothing. What it supplies is the slice of the clock only it saw, per message: when it arrived, when the ownership decision was taken, when the answer was confirmed to the vendor. Correlate a Pix transaction by endToEndId. On Pix, an asynchronous validation reports a row per credit with its call's instants. An absent instant is reported null, never inferred or back-filled. Read-only, served by the admin role off the delivery path, and it never returns original content." operationId: exportTransactionTiming parameters: - description: "The rail. Required: each page then reads one index range per store." explode: false in: query name: channelId required: true schema: description: "The rail. Required: each page then reads one index range per store." enum: - spb - pix type: string - description: RFC 3339. Arrival at or after this instant. explode: false in: query name: from required: true schema: description: RFC 3339. Arrival at or after this instant. maxLength: 64 type: string - description: RFC 3339. Arrival before this instant. explode: false in: query name: to required: true schema: description: RFC 3339. Arrival before this instant. maxLength: 64 type: string - description: One Pix transaction, by its own endToEndId. explode: false in: query name: endToEndId schema: description: One Pix transaction, by its own endToEndId. maxLength: 128 type: string - description: "One message, by its identity on the rail: on SPB, the vendor sequence." explode: false in: query name: naturalKey schema: description: "One message, by its identity on the rail: on SPB, the vendor sequence." maxLength: 256 type: string - description: The nextCursor of the previous page, as returned. Its format is not contract. explode: false in: query name: cursor schema: description: The nextCursor of the previous page, as returned. Its format is not contract. maxLength: 512 type: string - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 200 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransactionTimingPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Export the per-transaction instants the Courier observed tags: - assurance x-mint: href: /pt/reference/interfaces/jd-courier/export-the-per-transaction-instants-the-courier-observed /v1/retained: get: description: "Every message the Courier holds because no engine could receive it, every rail, oldest retention first. Read-only, and it never carries the message's content. A releasable message leaves by itself on the first re-check after its cause lifts — its account enters the ownership map, its owner is enabled again. An UNRECOGNIZED_TYPE of a non-financial code releases once a delivery mode is declared for its code and is not re-checked before that; one of a financial code releases on the re-check after a Courier release reads its destination. Each is re-checked at most once a minute, and within that minute while the tenant holds up to about 6,000 due retentions and its queue is empty, or about 600 while messages keep arriving (re-checks then take at most a tenth of the consumer's time; measured at 10 ms a re-check); above that, less often in proportion. Re-evaluate one to have it re-checked first: within a second while messages arrive, within 10 seconds otherwise. A Pix retention is re-checked at most once a minute. A re-evaluation has it re-checked within about 10 seconds while the engines answer; Pix tenants are re-checked one after another, and a tenant's pass that meets an engine that does not answer takes up to about 75 seconds, which every tenant after it waits out. Its release is a delivery the Courier starts with no vendor waiting: the engine's answer is stored and answers the vendor's next resend." operationId: listRetainedMessages parameters: - description: Page, 1-based. explode: false in: query name: page schema: default: 1 description: Page, 1-based. format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 200 minimum: 1 type: integer - description: Filter by rail. Omitted returns every rail. explode: false in: query name: channelId schema: description: Filter by rail. Omitted returns every rail. enum: - spb - pix type: string - description: Filter by retention reason. explode: false in: query name: reason schema: description: Filter by retention reason. enum: - UNRECOGNIZED_TYPE - ACCOUNT_UNASSIGNED - CLASSIFICATION_FAILED - OWNERSHIP_DECISION_UNAVAILABLE - DELIVERY_FAILED type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RetainedMessagePage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: List retained messages tags: - retained x-mint: href: /pt/reference/interfaces/jd-courier/list-retained-messages /v1/retained/{messageId}/reevaluate: post: description: Records who asked, when and why, and the rail runs the same routing decision a new message gets — send journal, ownership map, declared rules — on its next pass. Engines named release the message to them; a declared refusal refuses it, citing the rule; otherwise it stays retained, under the cause the decision found. The operator never chooses the engine. Only a releasable retention can be re-evaluated (JDC-0204 otherwise), and only while it is still retained (JDC-0202). Idempotent per X-Idempotency. operationId: reevaluateRetainedMessage parameters: - description: The message's surrogate id, from the listing. in: path name: messageId required: true schema: description: The message's surrogate id, from the listing. format: uuid type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ReevaluateInputBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/RetainedMessage" description: Accepted "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Run a retained message's routing decision again tags: - retained x-mint: href: /pt/reference/interfaces/jd-courier/run-a-retained-message-s-routing-decision-again /v1/send-journal: get: description: Answers "is there a send in unknown state?". Every send enters the journal before it leaves, so a send whose answer never came back is here as INDETERMINATE rather than missing. Newest first. SPB rail only. operationId: listSendJournal parameters: - description: Page, 1-based. explode: false in: query name: page schema: default: 1 description: Page, 1-based. format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 200 minimum: 1 type: integer - description: "true keeps exactly what SPBIndeterminateSendStale counts: INDETERMINATE sends nobody closed by hand. false or omitted does not filter." explode: false in: query name: open schema: description: "true keeps exactly what SPBIndeterminateSendStale counts: INDETERMINATE sends nobody closed by hand. false or omitted does not filter." type: boolean - description: Filter by outcome. Omitted returns every outcome. explode: false in: query name: outcome schema: description: Filter by outcome. Omitted returns every outcome. enum: - DETERMINED - INDETERMINATE - RESOLVED - NOT_SENT type: string - description: Filter by originating engine. explode: false in: query name: engineId schema: description: Filter by originating engine. maxLength: 32 type: string - description: Filter by control identifier (exact). explode: false in: query name: controlId schema: description: Filter by control identifier (exact). maxLength: 256 type: string - description: Sends at or after this instant. explode: false in: query name: sentFrom schema: description: Sends at or after this instant. format: date-time type: string - description: Sends before this instant. explode: false in: query name: sentTo schema: description: Sends before this instant. format: date-time type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SendRecordPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: List SPB sends tags: - send-journal x-mint: href: /pt/reference/interfaces/jd-courier/list-spb-sends /v1/send-journal/{controlId}: get: description: The latest send of the control identifier in the caller tenant's journal. 404 JDC-0302 when the journal does not hold it. operationId: getSendRecord parameters: - in: path name: controlId required: true schema: maxLength: 256 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SendRecord" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: One SPB send and its query history tags: - send-journal x-mint: href: /pt/reference/interfaces/jd-courier/one-spb-send-and-its-query-history /v1/send-journal/{controlId}/resolve: post: description: "Records an operator's finding on an INDETERMINATE send — the engine's settle or revert, JD support's written answer — with the evidence and a note, and changes nothing else. It is a record, never a routing decision: the outcome stays INDETERMINATE, a second send of the same control id is still refused, and the engine's ConsultaNumCtrlIF is still forwarded to JD, whose answer may still resolve the row. It never resends and calls no vendor. The Courier offers no by-hand NOT_SENT: an operator wrong about \"never sent\" would release the control id for a second send, and two TEDs would reach BACEN. What the close changes is the alert: a closed send stops aging. 409 JDC-0303 when the send is not INDETERMINATE or was already closed; 404 JDC-0302 when the journal does not hold it. A body missing a field, carrying a non-string or an unexpected property is 400 JDC-0001; a present field whose value breaks a rule (blank evidence, a note outside 10-500 characters after trimming) is 422 JDC-0002." operationId: resolveSendRecord parameters: - in: path name: controlId required: true schema: maxLength: 256 type: string - description: Idempotency key; a retry with the same key and body replays the first answer. in: header name: X-Idempotency required: true schema: description: Idempotency key; a retry with the same key and body replays the first answer. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CloseByHandRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/SendRecord" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Close an indeterminate send by hand tags: - send-journal x-mint: href: /pt/reference/interfaces/jd-courier/close-an-indeterminate-send-by-hand security: - BearerAuth: [] servers: [] tags: - description: "The engine registry: the cores that consume the JD channel through the Courier, each with its participant set" name: Engines - description: "The ownership map: which engine owns each key. Every change is audited." name: ownership - description: "The rails: what each declares about itself, its activation and state per tenant, and its delivery modes" name: channels - description: "The engines' side of the ownership map: resolution for the on-us gate, authoritative and never advisory, the claim of the accounts, charger documents and Pix Automático recurrences the engine holds, and the declaration of a payment leg it holds." name: ownership-query - description: "A same-bank Pix or TED between two cores: the Courier asks the map who owns the payee account, forwards the body byte for byte to that engine's address for the rail, and relays its answer. It stores, retries and posts nothing; bodies are not modelled." name: cross-core - description: "The durable message store: redelivery on demand, without asking the vendor again" name: ledger - description: "Count reconciliation per rail: E(m) = C(m) + T(m) + R(m), the sequence gaps it saw, and the sends whose return leg never arrived" name: assurance - description: "The SPB send journal: every send, written before it leaves, and the sends whose outcome is unknown. A by-hand close records an operator's finding and never resends." name: send-journal - description: "Per-(tenant, channel) state an operator acts on: lifting a durable channel halt" name: channel-leases - description: Messages the Courier holds because no engine could receive them. A routing or delivery retention leaves by itself once its cause lifts, or when an operator asks for its routing decision to be run again. name: retained