components: headers: XRequestId: description: "Echo of the request X-Request-Id: the value that the client sent, or the UUID that the platform generated when the client sent none. Present in every response, success or error." schema: format: uuid type: string parameters: XRequestId: description: "Correlation identifier of this request (UUID). Optional: when you omit it, or when the value is not a well-formed UUID, the platform creates a UUID and returns it in the X-Request-Id header of the response. The resolved identifier goes to the logs, spans, and audit events of this request. Keep it to open a support ticket." in: header name: X-Request-Id schema: format: uuid type: string schemas: CancelTransferRequest: additionalProperties: false description: Optional body of the cancellation. The reason is recorded. When the cancellation is sent to the STR, the reason goes with the history of the entry. properties: reason: description: Reason (goes to the cancellation description in the STR, when applicable) maxLength: 140 type: string type: object CloseHeldReturnRequest: additionalProperties: false properties: ledgerTransactionId: description: "Ledger transaction that evidences the closure: the one that credited the sender or, if the TED Lerian transfer that carries the return ended REJECTED or CANCELLED, the one that released the sender's hold (nothing to credit)." format: uuid type: string required: - ledgerTransactionId type: object description: "Evidence of the closure of a held return: the ledger transaction that credited the sender or, when the TED Lerian transfer ended `REJECTED`/`CANCELLED`, the one that released the sender's hold." ClosingBalance: additionalProperties: false description: The day's closing balance reported by the STR and the number of transfers still pending or rejected at closing. properties: closingBalance: description: Closing balance reported by the STR (BRL). examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string date: description: Close date (YYYY-MM-DD). format: date type: string pendingAtClose: description: Transfers still pending at the close. format: int64 type: integer rejectedAtClose: description: Transfers rejected at the close. format: int64 type: integer reportedAt: description: Timestamp (UTC) when the STR reported the closing. format: date-time type: string required: - date - reportedAt type: object CreateTransferRequestBody: additionalProperties: false description: "Request to send a TED or an internal transfer. The debited account does NOT go in the body: the `X-Account-Id` header identifies it. The recipient's bank decides the path (TED or INTERNAL): another institution → TED through the STR; your own institution → internal transfer settled in the ledger." properties: amount: description: "Amount in BRL as a decimal string, not a JSON number: digits only, with a dot as the decimal separator, up to 16 significant integer digits and at most 2 significant decimal places, with no sign or exponent. Leading and trailing spaces are ignored (e.g., \"1500.00\"; \"1500.000\" is equal to 1500.00)." examples: - "1500.00" type: string clientReference: description: Requester reference (up to 64 characters). Queries and events return it, and you can use it as a filter in GET /v1/transfers?client_reference=. examples: - PED-2026-000123 maxLength: 64 type: string description: description: Transfer description (up to 140 characters). Required when purposeCode=99999 (other). examples: - Supplier payment maxLength: 140 type: string metadata: additionalProperties: {} description: Free key-value pairs from the requester, returned verbatim in queries and events. Never sent to the STR or to other external systems. type: object purposeCode: description: "Purpose code of the TED: a 5-digit code. A code that is unknown, or not in force on the date of the request, in the BACEN FinlddCli Domain Dictionary is refused with TED-0003." examples: - "00001" pattern: ^[0-9]{5}$ type: string recipient: $ref: "#/components/schemas/RecipientBody" description: "Recipient: bank (ISPB or COMPE), branch, account, account type, name, and document." required: - amount - purposeCode - recipient type: object Detail: additionalProperties: true description: Standard error body (RFC 9457, `application/problem+json`) for every `/v1` operation. Use `code` (TED-NNNN) to handle the error in code, `detail` for the readable message, and `errors` for the invalid fields of a 422. The `X-Request-Id` of the response identifies the occurrence for support. 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 ErrorDetail: additionalProperties: false description: "An invalid field inside a validation error: where it is (`location`), what is wrong (`message`), and the value received." 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 FeeQuote: additionalProperties: false description: "Quote result: the fee estimate and the total of the request at this instant, and whether the operating window is open. The quote does not hold balance or limit." properties: amount: description: Amount sent, in BRL. examples: - "1500.00" pattern: ^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$ type: string feeAmount: description: Fee estimate, in BRL (0.00 when the estimate prices no fee). examples: - "3.25" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string feePackageId: description: Identifier of the fee package applied in the ledger type: string nextWindowOpensAt: description: Next opening of the effective window (UTC), given when the window is closed at this moment. format: date-time type: string quotedAt: description: Time (UTC) of the quote. format: date-time type: string totalAmount: description: "Amount + fee estimate." examples: - "1503.25" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string type: description: "Path the send would take: TED (another institution, through the STR) or INTERNAL (your own institution, in the ledger)." enum: - TED - INTERNAL type: string windowOpen: description: Whether the effective window is open at this moment. Missing when the window could not be read — it never means closed. type: boolean required: - type - amount - feeAmount - totalAmount - quotedAt type: object FeeQuoteRequest: additionalProperties: false description: "Quote request: the same financial fields as a send request (recipient, amount, and purpose code), with no effect." properties: amount: description: "Amount in BRL as a decimal string, not a JSON number: digits only, with a dot as the decimal separator, up to 16 significant integer digits and at most 2 significant decimal places, with no sign or exponent. Leading and trailing spaces are ignored (e.g., \"1500.00\"; \"1500.000\" is equal to 1500.00)." examples: - "1500.00" type: string purposeCode: description: "Purpose code of the TED: a 5-digit code. A code that is unknown, or not in force on the date of the request, in the BACEN FinlddCli Domain Dictionary is refused with TED-0003." examples: - "00001" pattern: ^[0-9]{5}$ type: string recipient: $ref: "#/components/schemas/RecipientBody" description: Recipient, exactly as it would be sent in the transfer request. required: - recipient - amount - purposeCode type: object HeldReturnListDTO: additionalProperties: false properties: items: description: Open held returns, oldest first. items: $ref: "#/components/schemas/HeldReturnResponse" type: array required: - items type: object description: Open held returns, oldest first, without pagination. HeldReturnResponse: additionalProperties: false properties: amount: description: Returned amount. type: string closedAt: description: Instant (UTC) of the closure. format: date-time type: string closedBy: description: Operator who closed the return. type: string id: description: Identifier of the held return. format: uuid type: string ledgerTransactionId: description: "Ledger transaction that evidences the closure: the one that credited the sender or, with transferStatus REJECTED or CANCELLED, the one that released the sender's hold (nothing to credit)." format: uuid type: string originalNumCtrlStr: description: NumCtrlSTR of the returned TED (NumCtrlSTROr). type: string returnCode: description: Official return reason (CodDevTransf). type: string returnedAt: description: Instant of the return at the STR. format: date-time type: string transferId: description: 'TED Lerian transfer that carries the NumCtrlSTR of the returned TED. Null while no transfer carries it: TED Lerian did not send the TED, or its TED did not receive a NumCtrlSTR from a rail fact (in any status, SUBMITTED included).' format: uuid type: - string - "null" transferStatus: description: 'Current status of that transfer; null without it. REJECTED or CANCELLED: the sender was never debited and there is nothing to credit. Never credit the sender; close the return with evidence.' type: - string - "null" required: - id - originalNumCtrlStr - amount - returnCode - returnedAt - transferId - transferStatus type: object description: 'Held return: a return (STR0010R2) received from the STR for a TED that no `SETTLED` transfer of this institution carries by `NumCtrlSTR`, waiting for the operator. `transferId`/`transferStatus` say whether a TED Lerian transfer carries it; `closedBy`, `closedAt`, and `ledgerTransactionId` exist only after the closure.' HolidayCalendar: additionalProperties: false description: National bank holiday calendar of a year. On a holiday there is no operating window. properties: holidays: description: Full list of holidays for the year — the operation replaces the previous list. items: $ref: "#/components/schemas/HolidayDTO" type: - array - "null" updatedAt: description: Instant (UTC) of the last write. Ignored on write. format: date-time type: string year: description: Year of the calendar. All dates must belong to it. format: int64 maximum: 2100 minimum: 2000 type: integer required: - year - holidays type: object HolidayDTO: additionalProperties: false description: A national bank holiday. properties: date: description: Date of the holiday (YYYY-MM-DD), within the calendar year. examples: - "2026-01-01" format: date type: string name: description: Name of the holiday. examples: - Confraternização Universal maxLength: 100 type: string scope: default: NATIONAL description: Scope. Only NATIONAL (national bank holidays). enum: - NATIONAL type: string required: - date - name type: object IncomingPartyResponse: additionalProperties: false description: One of the parties of the incoming TED. For the recipient, `accountId` is only filled in after the account is found in the institution. Until then, only the bank data received from the STR is available. properties: accountId: description: Account in the institution's own ledger. Present only when the recipient was already found. format: uuid type: string agency: description: Branch. type: string bankAccount: description: Account number. type: string bankAccountType: description: "Account type: CACC (checking), SVGS (savings), SLRY (salary), or TRAN (payment)." enum: - CACC - SVGS - SLRY - TRAN type: string bankId: description: ISPB of the institution (8 digits). Always present. Empty string when unknown. pattern: ^[0-9]{8}$ type: string document: description: CPF (11 digits) or CNPJ (14 digits), digits only. examples: - "12345678909" pattern: ^([0-9]{11}|[0-9]{14})$ type: string name: description: Name of the party, not truncated. type: string required: - bankId type: object IncomingTimelineDTO: additionalProperties: false description: "Timeline of an incoming TED: each entry is a status transition with origin, timestamp, and related reference." properties: entries: description: Transitions in chronological order. items: $ref: "#/components/schemas/IncomingTimelineEntryDTO" type: array resourceId: description: Identifier of the incoming TED. format: uuid type: string required: - resourceId - entries type: object IncomingTimelineEntryDTO: additionalProperties: false description: A status transition of the incoming TED. `origin` tells you what caused it (API, rail, STR, ledger, worker, operator, or system). properties: actor: description: Operator identity when origin=OPERATOR. type: string at: description: Instant (UTC) of the transition. format: date-time type: string fromStatus: description: IncomingTransferStatus value; absent in the first transition. type: string origin: enum: - API - RAIL - STR - LEDGER - WORKER - OPERATOR - SYSTEM type: string reason: description: Official reason for the transition, verbatim. type: string reference: description: Related identifier (nuop, numCtrlStr, event id). type: string toStatus: description: IncomingTransferStatus value. type: string required: - at - toStatus - origin type: object IncomingTransferPageDTO: additionalProperties: false description: Page of incoming TEDs with cursor pagination. Follow `next_cursor` until it is `null`. properties: items: description: Incoming TEDs in the page. items: $ref: "#/components/schemas/IncomingTransferResponse" type: array limit: description: Actual page size, already capped at the contract maximum — not necessarily the requested value. format: int64 type: integer next_cursor: description: Token of the next page; null when there is none. type: - string - "null" prev_cursor: description: Token of the previous page; null when there is none. type: - string - "null" required: - items - limit - next_cursor - prev_cursor type: object IncomingTransferResponse: additionalProperties: false description: "An incoming TED from another institution: amount, parties, regulatory credit deadline, and the state of the credit to the recipient. `status=MANUAL_REVIEW` with `reviewReason` indicates that the operation needs a human decision; outside `MANUAL_REVIEW` the `reviewReason` is not emitted, and the history of reasons is on the timeline." properties: amount: description: Amount in BRL as a decimal string with two decimal places. examples: - "1500.00" pattern: ^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$ type: string createdAt: description: Time (UTC) when this service recorded the TED. format: date-time type: string creditedAmount: description: Amount actually credited to the recipient (amount − feeAmount), in BRL. Present from CREDITED onward. examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string creditedAt: description: Time (UTC) of the credit to the recipient. format: date-time type: string description: description: Description given by the sender. type: string feeAmount: description: Fee applied to the credit, in BRL (0.00 when exempt). examples: - "0.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string incomingTransferId: description: Identifier of the incoming TED. Use it in queries and actions. format: uuid type: string interbankSettledAt: description: Interbank settlement reported by the STR (start of the 60-min deadline) format: date-time type: string kind: description: Credit to a customer or to the institution's own account enum: - CLIENT - INSTITUTION type: string numCtrlStr: description: "Control number of the credit assigned by the STR (NumCtrlSTR of the R2 message, 20 alphanumeric characters). It can be absent: the rail did not send the number, or sent a value that is not 20 alphanumeric characters. Correlate by nuop in that case." pattern: ^[A-Za-z0-9]{20}$ type: string nuop: description: Unique operation number on the rail (ISPB[8]+AAAAMMDD[8]+SEQ[7]) pattern: ^[0-9]{23}$ type: string organizationId: description: Organization resolved through the ISPB→organization binding format: uuid type: string purposeCode: description: Purpose code sent by the sender (FinlddCli, 5 digits). examples: - "00010" pattern: ^[0-9]{5}$ type: string recipient: $ref: "#/components/schemas/IncomingPartyResponse" description: Recipient in your own institution; accountId is present when the account was found. returnCode: description: Official return reason (CodDevTransf) of the active return, when there is one. examples: - "3" pattern: ^[0-9]{1,2}$ type: string returnedAt: description: Instant (UTC) when the STR confirmed the return. format: date-time type: string reviewReason: description: "Reason for the manual review. Present only when status=MANUAL_REVIEW; the timeline keeps the history of reasons. From the credit decision: ISPB_BINDING_UNRESOLVED, ACCOUNT_NOT_FOUND, ACCOUNT_INACTIVE, HOLDER_MISMATCH, ACCOUNT_TYPE_INCOMPATIBLE, ENRICHMENT_INCOMPLETE, RAIL_INDETERMINATE, LEDGER_INDETERMINATE, REGISTRY_INDETERMINATE. From the return cycle: RETURN_REFUSED_BY_STR, RETURN_REQUEST_MALFORMED, RETURN_CODE_UNMAPPED, RETURN_REJECTED_BY_STR. From the reversal that an operator requested: LEDGER_REVERT_REFUSED (the ledger refused the reversal; the credit was kept) and LEDGER_REVERT_INDETERMINATE (the outcome of the reversal is unknown; the credit may be reversed)." type: string sender: $ref: "#/components/schemas/IncomingPartyResponse" description: Sender, at another institution. slaDeadlineAt: description: "Regulatory deadline to credit or return: interbankSettledAt + 60 min (UTC)." format: date-time type: string status: description: "Current state: RECEIVED (received from the STR, credit decision in progress) → CREDITED (credited to the customer), RECORDED (the institution's own account, terminal), or MANUAL_REVIEW (waits for an operator; see reviewReason); RETURN_REQUESTED (return sent to the STR) → RETURNED (confirmed, terminal). If the STR refuses a return, the TED goes back to MANUAL_REVIEW with reviewReason filled in." enum: - RECEIVED - CREDITED - RECORDED - RETURN_REQUESTED - RETURNED - MANUAL_REVIEW type: string updatedAt: description: Timestamp (UTC) of the last update to the record. format: date-time type: string required: - incomingTransferId - status - nuop - amount - sender - recipient - interbankSettledAt - slaDeadlineAt - createdAt - updatedAt type: object InconsistencyFinding: additionalProperties: false description: A mismatch between what the ledger records and what the rail (STR) reported for the same resource. It stays OPEN while it is observed and changes to CLEARED when it is no longer observed. properties: amount: description: Amount (BRL). examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string check: description: Consistency check that created the finding. enum: - RETURN_WITHOUT_REFUND - ORPHAN_HOLD - SETTLED_WITHOUT_COMMIT - RESERVED_AFTER_RELEASE - LEDGER_STATUS_CONTRADICTION - CREDIT_WITHOUT_FACT - CREDIT_STATUS_CONTRADICTION - RETURN_WITHOUT_REVERT type: string clearedAt: description: Time when the service stopped observing the inconsistency; absent while OPEN. format: date-time type: string detail: description: Description of the observed inconsistency. type: string firstDetectedAt: description: First detection. Sort key of the list (oldest first). format: date-time type: string id: description: Identifier of the finding. format: uuid type: string lastDetectedAt: description: Last detection. format: date-time type: string nuop: description: Unique operation number on the rail (ISPB[8]+AAAAMMDD[8]+SEQ[7]) pattern: ^[0-9]{23}$ type: string observedStatus: description: Status of the resource at the last detection. type: string organizationId: description: Organization of the resource. Missing when not resolved. format: uuid type: string reopenedAt: description: Last reopening of a finding that was already resolved. Missing if it was never reopened. format: date-time type: string resourceId: description: Identifier of the resource (transferId or incomingTransferId). format: uuid type: string resourceType: description: "Type of the inconsistent resource: sent TED (TRANSFER) or incoming TED (INCOMING_TRANSFER)." enum: - TRANSFER - INCOMING_TRANSFER type: string status: description: OPEN while the inconsistency continues; CLEARED when it is no longer observed. enum: - OPEN - CLEARED type: string required: - id - check - resourceType - resourceId - status - observedStatus - detail - firstDetectedAt - lastDetectedAt type: object InconsistencyFindingPage: additionalProperties: false description: Page of inconsistency findings, with the count of open findings per check for the whole tenant. properties: items: description: Findings on the page. items: $ref: "#/components/schemas/InconsistencyFinding" type: array limit: description: Actual page size, already limited to the contract maximum. format: int64 type: integer next_cursor: description: Token of the next page; null when there is none. type: - string - "null" openByCheck: additionalProperties: format: int64 type: integer description: OPEN findings per check for the whole tenant, regardless of the filter. Always includes the eight checks. type: object prev_cursor: description: "Always null: the list only moves forward." type: - string - "null" required: - items - limit - openByCheck type: object IspbBindingDTO: additionalProperties: false description: An ISPB → organization/ledger binding. Among bindings of the same ISPB, the lowest `priority` wins. properties: ispb: description: ISPB (8 digits) the institution uses to operate on the STR. examples: - "00000000" pattern: ^[0-9]{8}$ type: string ledgerId: description: Ledger (Midaz) of this organization where the credits are posted. format: uuid type: string organizationId: description: Organization (Midaz) that receives the TEDs addressed to this ISPB. format: uuid type: string priority: description: Order of preference between bindings of the same ISPB (1 = highest priority). It cannot repeat for the same ISPB. format: int64 minimum: 1 type: integer required: - ispb - organizationId - ledgerId - priority type: object IspbBindingsBody: additionalProperties: false description: Bindings between the ISPBs the institution operates through and the organizations/ledgers that receive the TEDs addressed to each one. properties: bindings: description: Full list of bindings. The operation replaces the previous list. items: $ref: "#/components/schemas/IspbBindingDTO" type: array updatedAt: description: Instant (UTC) of the last write. Ignored on write. format: date-time type: string required: - bindings type: object OperatingWindow: additionalProperties: false description: "Effective operating window of a day: the official STR schedule, narrowed by the institution cut-off and the holiday calendar. Outside it, send requests are refused with `TED-0020`/`TED-0021`." properties: clientCutoffTime: description: Cut-off configured by the institution (HH:MM, local time). Missing when there is no cut-off. type: string configured: description: "true when a stored window configuration (of the organization, or the institution default) decided this window; false when no configuration exists and the window follows the official STR schedule with no cut-off." type: boolean date: description: Calendar day that this window describes (YYYY-MM-DD). format: date type: string effectiveClosesAt: description: "Effective close (UTC): the earlier of the official STR close and the institution cut-off." format: date-time type: string effectiveOpensAt: description: Effective opening of the window in the day (UTC). format: date-time type: string isBusinessDay: description: false on a weekend or national holiday. type: boolean isOpen: description: If the window is open at the time of the query. type: boolean officialClosesAt: description: Official close of the STR (UTC). Missing on a day with no published schedule (weekend, holiday). format: date-time type: string source: description: "What decided the response: OFFICIAL_SCHEDULE (official schedule), OFFICIAL_SCHEDULE_WITH_CUTOFF (schedule narrowed by the cut-off), HOLIDAY, or WEEKEND." enum: - OFFICIAL_SCHEDULE - OFFICIAL_SCHEDULE_WITH_CUTOFF - HOLIDAY - WEEKEND type: string required: - date - isBusinessDay - isOpen - effectiveOpensAt - effectiveClosesAt - source - configured type: object OperatingWindowCutoff: additionalProperties: false description: Cut-off time after which the institution stops accepting transfers for the day. Always equal to or earlier than the official close of the STR. properties: clientCutoffTime: description: Institution cut-off in HH:MM (local time). It cannot be later than the STR's official closing for the day. examples: - "17:00" pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ type: string timezone: description: "IANA time zone of the cut-off. Default: the institution's time zone." examples: - America/Sao_Paulo type: string required: - clientCutoffTime type: object OperationsQueueSummary: additionalProperties: false description: Number of items in each operations queue at this instant. properties: awaitingReconciliation: description: Outgoing TEDs in AWAITING_RECONCILIATION. format: int64 type: integer exhausted: description: Outgoing TEDs in EXHAUSTED. format: int64 type: integer manualReview: description: Incoming TEDs in MANUAL_REVIEW. format: int64 type: integer pendingStr: description: Sent TEDs in PENDING_STR. format: int64 type: integer type: object OperationsSummary: additionalProperties: false description: "Daily aggregates for the operations dashboard: operating window, outgoing TEDs, incoming TEDs, and open queues." properties: date: description: Reference date (YYYY-MM-DD). format: date type: string generatedAt: description: Time (UTC) when the summary was generated. format: date-time type: string inbound: $ref: "#/components/schemas/OperationsSummaryInbound" description: Incoming TEDs. outbound: $ref: "#/components/schemas/OperationsSummaryOutbound" description: Outgoing TEDs (internal transfers excluded). queue: $ref: "#/components/schemas/OperationsQueueSummary" description: Operations queues now. Absent for a past date. window: $ref: "#/components/schemas/OperatingWindow" required: - date - window - outbound - inbound type: object OperationsSummaryInbound: additionalProperties: false description: "Totals of incoming TEDs for the day: count, total amount, breakdown by status, and returns by code." properties: amount: description: Sum of the amounts received in the day (BRL). examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string byStatus: additionalProperties: format: int64 type: integer description: Count by current status. type: object count: description: Number of incoming TEDs in the day. format: int64 type: integer returnsByCode: additionalProperties: format: int64 type: integer description: Number of returns by official code (CodDevTransf). type: object type: object OperationsSummaryOutbound: additionalProperties: false description: "Aggregates of the outgoing TEDs of the day: count, total amount, distribution by status, and rejections by code." properties: amount: description: Sum of the amounts sent in the day (BRL). examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string byStatus: additionalProperties: format: int64 type: integer description: Count by current status. type: object count: description: Number of outgoing TEDs in the day. format: int64 type: integer rejectionsByCode: additionalProperties: format: int64 type: integer description: Number of rejections by code (rejection.code). type: object type: object Participant: additionalProperties: false description: Institution that participates in the STR, with its ISPB, COMPE code, and access type. properties: accessType: description: Method of access to the STR enum: - RSFN - INTERNET - UNKNOWN type: string compe: description: COMPE code of the bank (3 digits) examples: - "001" pattern: ^[0-9]{3}$ type: string ispb: description: Identifier of the participant in the SPB (8 digits) examples: - "00000000" pattern: ^[0-9]{8}$ type: string name: description: Name of the institution. type: string updatedAt: description: Last update of the record (UTC). format: date-time type: string required: - ispb - name type: object ParticipantPage: additionalProperties: false description: Page of STR participants with cursor pagination. properties: items: description: Participants on the page. items: $ref: "#/components/schemas/Participant" type: array limit: description: Actual page size, already limited to the contract maximum. format: int64 type: integer next_cursor: description: Token of the next page; null when there is none. type: - string - "null" prev_cursor: description: "Always null: the list only moves forward." type: - string - "null" required: - items - limit type: object PartyResponse: additionalProperties: false description: One of the parties to the transfer (sender or recipient). `accountId` exists only for the party that belongs to your institution. For the counterparty at another bank, the API returns the bank details that were sent. properties: accountId: description: Account in your own institution; present only for the party that belongs to it. format: uuid type: string agency: description: Branch. type: string bankAccount: description: Account number. type: string bankAccountType: description: "Account type: CACC (checking), SVGS (savings), SLRY (salary), or TRAN (payment)." enum: - CACC - SVGS - SLRY - TRAN type: string bankCode: description: COMPE code (3 digits), when known. pattern: ^[0-9]{3}$ type: string bankId: description: ISPB of the institution (8 digits). Always present. Empty string when unknown. pattern: ^[0-9]{8}$ type: string document: description: CPF (11 digits) or CNPJ (14 digits), digits only. examples: - "12345678909" pattern: ^([0-9]{11}|[0-9]{14})$ type: string name: description: Name of the party, not truncated. type: string required: - bankId type: object RailFactReviewPageDTO: additionalProperties: false description: Page of rail fact reviews, from oldest to newest, with cursor pagination. properties: items: description: Reviews on the page. items: $ref: "#/components/schemas/RailFactReviewResponse" type: array limit: description: Actual page size, already limited to the contract maximum. format: int64 type: integer next_cursor: description: Token of the next page; null when there is none. type: - string - "null" required: - items - limit - next_cursor type: object RailFactReviewResponse: additionalProperties: false description: 'Pending review of a fact received from the rail (STR) that the system could not apply on its own. Examples: a fact without a matching transfer, or a ledger effect that stayed pending.' properties: createdAt: description: Timestamp (UTC) when the review was opened. format: date-time type: string detail: description: Description of the review for the operator type: string eventKey: description: Key of the event that created the review type: string id: description: Review identifier format: uuid type: string nuop: description: NumCtrlIF of the fact, when known type: string occurredAt: description: Time (UTC) of the fact in the rail. format: date-time type: string reason: description: Review reason type: string resolvedAt: description: Time (UTC) of the resolution. format: date-time type: string resolvedBy: description: Operator who resolved the review type: string status: description: PENDING waits for an operator decision; RESOLVED is already closed. enum: - PENDING - RESOLVED type: string transferId: description: Associated transfer. Missing when the fact was not correlated format: uuid type: string required: - id - status - reason - eventKey - detail - occurredAt - createdAt type: object RecipientBody: additionalProperties: false description: Recipient of the transfer. Identify the bank by `bankId` (ISPB, 8 digits) OR by `bankCode` (COMPE, 3 digits), never both. Use `GET /v1/participants` to resolve one from the other. The other fields identify the account and the holder exactly as they appear at the destination bank. properties: agency: description: Branch of the destination account, without the check digit (up to 4 characters). examples: - "1234" maxLength: 4 type: string bankAccount: description: Destination account number, in the format that the destination bank accepts (up to 20 characters). examples: - "0001234567" maxLength: 20 type: string bankAccountType: description: "Type of the destination account: CACC (checking), SVGS (savings), SLRY (salary), or TRAN (payment)." enum: - CACC - SVGS - SLRY - TRAN type: string bankCode: description: COMPE code of the destination institution (3 digits). Send bankId OR bankCode, never both. pattern: ^[0-9]{3}$ type: string bankId: description: ISPB of the destination institution (8 digits). Send bankId OR bankCode, never both. pattern: ^[0-9]{8}$ type: string document: description: CPF (11 digits) or CNPJ (14 digits), digits only, with valid check digits. An alphanumeric CNPJ is not accepted. A value of another length or with letters is refused with TED-0002. A well-formed CPF or CNPJ with invalid check digits is refused with TED-0007, on the send and on the quote. pattern: ^([0-9]{11}|[0-9]{14})$ type: string name: description: Full name or legal name of the holder of the destination account (up to 200 characters). examples: - Maria da Silva maxLength: 200 type: string required: - agency - bankAccount - bankAccountType - name - document type: object ReconciliationQueueItem: additionalProperties: false description: "Operations queue item: an outgoing transfer or an incoming TED that waits for confirmation, reconciliation, or a human decision, with its age and regulatory deadline for prioritization." properties: ageSeconds: description: "Age of the item, in seconds. When a regulatory deadline runs, the age counts from the start of that deadline: the debit hold (debit → send) or the interbank settlement in the STR (settlement → credit / return). When no deadline runs, the age counts from the entry into the current status (the last transition to it; createdAt if there is none). It is never negative. It is also the sort key of the queue (oldest first)." format: int64 minimum: 0 type: integer amount: description: Amount (BRL). examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string attempts: description: Automatic reconciliation attempts already made. format: int64 minimum: 0 type: integer createdAt: description: Timestamp (UTC) of the resource creation. format: date-time type: string kind: description: Queue of the item; IN_FLIGHT for an at-risk item that is not in any queue (RESERVED, RECEIVED, RETURN_REQUESTED). enum: - PENDING_STR - AWAITING_RECONCILIATION - EXHAUSTED - MANUAL_REVIEW - IN_FLIGHT type: string lastAttemptAt: description: Time (UTC) of the last attempt. format: date-time type: string nuop: description: Unique operation number on the rail (ISPB[8]+AAAAMMDD[8]+SEQ[7]) pattern: ^[0-9]{23}$ type: string resourceId: description: Identifier of the resource (transferId or incomingTransferId). format: uuid type: string resourceType: description: TRANSFER (outgoing TED) or INCOMING_TRANSFER (incoming TED). enum: - TRANSFER - INCOMING_TRANSFER type: string slaDeadlineAt: description: Current regulatory deadline (UTC), when there is one. format: date-time type: string status: description: TransferStatus (resourceType=TRANSFER) or IncomingTransferStatus (resourceType=INCOMING_TRANSFER). type: string required: - kind - resourceType - resourceId - status - ageSeconds - createdAt type: object ReconciliationQueuePage: additionalProperties: false description: Page of the operations queue, from oldest to newest item, with cursor pagination. properties: items: description: Items in the page. items: $ref: "#/components/schemas/ReconciliationQueueItem" type: array limit: description: Actual page size, already limited to the contract maximum. format: int64 type: integer next_cursor: description: Token of the next page; null when there is none. type: - string - "null" prev_cursor: description: Token of the previous page; null when there is none. type: - string - "null" required: - items - limit type: object ReconciliationRunResponse: additionalProperties: false description: Reconciliation run scheduled on demand. Processing is asynchronous; track the effects in the queues and in the affected resources. properties: requestedAt: description: Timestamp (UTC) of the request. format: date-time type: string runId: description: Identifier of the scheduled cycle. format: uuid type: string status: description: Status of the cycle at the moment of the response. enum: - SCHEDULED - RUNNING - COMPLETED type: string required: - runId - status - requestedAt type: object RejectionResponse: additionalProperties: false description: "Reason for a transfer in `status=REJECTED`. Validation and policy refusals NEVER appear here: they occur before the service creates any resource, and they return as 4xx/503 without a transfer body." properties: code: description: "Rejection code, by source: LEDGER → TED-0031 (insufficient balance) or TED-1001; RAIL → TED-1010 (the STR connector could not reach the STR and stored nothing), TED-1011, TED-1013 (the rail closed the TED without an STR decision), or the rail's own refusal code; STR → SitLancSTR code or SFN error (example: STR0015 at the day close); OPERATOR → the code given in the unblock." examples: - TED-1011 type: string reason: description: Rejection reason, as recorded on the transfer. Always present. Empty string when no text was recorded. type: string source: description: "Source of the rejection, and when it can appear. LEDGER is decided SYNCHRONOUSLY: it can already be filled in the response of POST /v1/transfers. RAIL can also be there, or it can arrive later through reconciliation when the rail closed the TED without an STR decision (approval denied or expired; code TED-1013). STR and OPERATOR are always ASYNCHRONOUS: they never appear in the creation response. They are only visible in a later query." enum: - LEDGER - RAIL - STR - OPERATOR type: string required: - code - reason - source type: object ResolveReconciliationReviewRequest: additionalProperties: false description: "Operator decision on a rail fact review: close it as analyzed, or re-run the pending ledger effect." properties: action: description: ACKNOWLEDGE closes the review; RETRY_LEDGER_EFFECT runs the pending ledger effect again (only LEDGER_EFFECT_PENDING). enum: - ACKNOWLEDGE - RETRY_LEDGER_EFFECT type: string justification: description: Operator justification. maxLength: 500 minLength: 10 type: string required: - action - justification type: object ResolveReconciliationReviewResponse: additionalProperties: false description: "Result of the resolution: the updated review, the action applied, and, for a re-run, the outcome." properties: action: description: Action applied. enum: - ACKNOWLEDGE - RETRY_LEDGER_EFFECT type: string outcome: description: Result of the retry (RETRY_LEDGER_EFFECT only) type: string review: $ref: "#/components/schemas/RailFactReviewResponse" description: The review after the resolution. required: - review - action type: object ResolveReviewRequestBody: additionalProperties: false description: "Operator decision on an incoming TED in manual review: credit it, return it, or record a credit already applied in the ledger." properties: accountId: description: Destination account when the operator resolves the location (usually with action=CREDIT). format: uuid type: string action: description: CREDIT makes the credit; RETURN returns (requires returnCode); CONFIRM_CREDITED records a credit already confirmed in the ledger, with evidence. enum: - CREDIT - RETURN - CONFIRM_CREDITED type: string evidence: description: "Required when action=CONFIRM_CREDITED: the identifier (UUID) of the Midaz transaction for the credit already applied (TED-0065 if missing or invalid)." maxLength: 64 type: string justification: description: Operator justification. maxLength: 500 minLength: 10 type: string returnCode: description: Required when action=RETURN (TED-0066 if absent); not allowed in the other actions. examples: - "3" pattern: ^[0-9]{1,2}$ type: string required: - action - justification type: object ReturnIncomingTransferRequestBody: additionalProperties: false description: Request for the full return of an incoming TED that is already credited, with the official reason (CodDevTransf) and the operator's justification. properties: justification: description: Operator justification. maxLength: 500 minLength: 10 type: string returnCode: description: Official return reason (CodDevTransf, SFN Domain Dictionary). examples: - "3" pattern: ^[0-9]{1,2}$ type: string required: - returnCode - justification type: object SlaMetric: additionalProperties: false description: Distribution of a regulatory deadline in the day (percentiles in seconds), the number of violations, and the open items at risk. properties: atRisk: description: Open items close to the deadline or already overdue. items: $ref: "#/components/schemas/ReconciliationQueueItem" type: array breaches: description: Items past the deadline. format: int64 type: integer limitSeconds: description: Regulatory deadline, in seconds. format: int64 type: integer p50Seconds: description: 50th percentile of elapsed time, in seconds. format: double type: number p95Seconds: description: 95th percentile of elapsed time, in seconds. format: double type: number p99Seconds: description: 99th percentile of elapsed time, in seconds. format: double type: number sampleCount: description: Number of completed items measured in the day. format: int64 type: integer required: - limitSeconds - sampleCount - p50Seconds - p95Seconds - p99Seconds - breaches - atRisk type: object SlaReport: additionalProperties: false description: "Report of the three regulatory deadlines of the day: debit → submission to the STR (30 min), settlement → credit to the customer (60 min), and settlement → return (60 min), with the time distribution, violations, and items at risk." properties: date: description: Reference date (YYYY-MM-DD). format: date type: string debitToSubmit: $ref: "#/components/schemas/SlaMetric" description: Debit → submission to the STR (30 min). generatedAt: description: Time (UTC) when the report was generated. format: date-time type: string settlementToCredit: $ref: "#/components/schemas/SlaMetric" description: Settlement → credit to the customer (60 min). settlementToReturn: $ref: "#/components/schemas/SlaMetric" description: Settlement → return (60 min). required: - date - debitToSubmit - settlementToCredit - settlementToReturn - generatedAt type: object TimelineDTO: additionalProperties: false description: "Timeline of a transfer: each entry is a status transition with its origin, instant, and related reference." properties: entries: description: Transitions in chronological order. items: $ref: "#/components/schemas/TimelineEntryDTO" type: array resourceId: description: Identifier of the transfer. format: uuid type: string required: - resourceId - entries type: object TimelineEntryDTO: additionalProperties: false description: One status transition of the transfer. `origin` tells you who caused it (API, rail, STR, ledger, worker, operator, or system). properties: actor: description: Operator identity when origin=OPERATOR. type: string at: description: Instant (UTC) of the transition. format: date-time type: string fromStatus: description: TransferStatus value. Missing in the first transition and in entries rebuilt from a point in time. type: string origin: enum: - API - RAIL - STR - LEDGER - WORKER - OPERATOR - SYSTEM type: string reason: description: Official reason for the transition, verbatim. type: string reference: description: Related identifier (nuop, numCtrlStr, event id). type: string toStatus: description: TransferStatus value. type: string required: - at - toStatus - origin type: object TransferPageDTO: additionalProperties: false description: Page of transfers with cursor pagination. Follow `next_cursor` until it is `null`. properties: items: description: Transfers on the page. items: $ref: "#/components/schemas/TransferResponse" type: array limit: description: Actual page size, already capped at the contract maximum — not necessarily the requested value. format: int64 type: integer next_cursor: description: Token of the next page; null when there is none. type: - string - "null" prev_cursor: description: Token of the previous page; null when there is none. type: - string - "null" required: - items - limit - next_cursor - prev_cursor type: object TransferResponse: additionalProperties: false description: Representation of an outgoing (TED) or internal transfer. The create, query, and list operations return it, and so do the cancel and unblock actions. Track the lifecycle through the `status` field and the instants `reservedAt`/`submittedAt`/`settledAt`. When `status=REJECTED`, `rejection` tells you who refused it and why. properties: amount: description: Amount in BRL as a decimal string with two decimal places. examples: - "1500.00" pattern: ^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$ type: string clientReference: description: Requester reference sent with the transfer request. maxLength: 64 type: string createdAt: description: Time (UTC) of creation. format: date-time type: string description: description: Description given in the send request. maxLength: 140 type: string feeAmount: description: "Fee, in BRL. After the hold, or after the settlement of an internal transfer, it is the fee that Midaz charged the sender. Before that, it is the estimate." examples: - "0.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string metadata: additionalProperties: {} description: Free-form key-value pairs from the requester, kept verbatim. Never sent to external systems. maxProperties: 50 type: object numCtrlStr: description: "Identifier of the entry assigned by the STR (20 characters, XXXAAAAMMDDnnnnnnnnn), present after the STR settles the entry. It can be absent even with status=SETTLED, on a TED settled by reconciliation when the rail query does not give the number. Correlate by nuop in that case. A settlement fact that arrives later fills the field." pattern: ^[A-Za-z0-9]{20}$ type: string nuop: description: "SPB identifier of the operation, 23 digits. It can be absent even in status=SUBMITTED. In that case, correlate by railOperationId." pattern: ^[0-9]{23}$ type: string purposeCode: description: Purpose code given in the send request (FinlddCli, 5 digits). examples: - "00001" pattern: ^[0-9]{5}$ type: string railOperationId: description: Identifier of the operation in the rail (after acceptance). format: uuid type: string recipient: $ref: "#/components/schemas/PartyResponse" description: Recipient sent when the transfer was created. In an internal transfer it includes accountId. rejection: $ref: "#/components/schemas/RejectionResponse" description: Present only when status=REJECTED. reservedAt: description: Instant (UTC) when the amount and fee were put on hold in the source account. Start of the 30-min regulatory deadline for submission. format: date-time type: string returned: $ref: "#/components/schemas/TransferReturnSummary" description: Return received for this outgoing TED (credit back to the sender). Requires status=SETTLED and a LATER return from the recipient institution. For this reason it never appears in the creation response or in the list items, only in GET /v1/transfers/{transferId}. sender: $ref: "#/components/schemas/PartyResponse" description: Source account, always in your own institution (includes accountId). settledAt: description: Instant of settlement. Exists only from status=SETTLED. format: date-time type: string status: description: "Current state (published as a free string: handle unknown values with tolerance). Current values: CREATED, RESERVED, SUBMITTED, PENDING_STR, SETTLED, REJECTED, CANCELLED, AWAITING_RECONCILIATION, EXHAUSTED. TED: CREATED → RESERVED (amount + fee on hold) → SUBMITTED (sent to the STR) → SETTLED | REJECTED; PENDING_STR when the STR keeps the entry pending; AWAITING_RECONCILIATION and EXHAUSTED when the outcome could not be confirmed automatically; CANCELLED on a cancellation before submission or of a confirmed pending entry. INTERNAL: CREATED → SETTLED | REJECTED in the same call, or it stays CREATED when the ledger response was undetermined (the reconciliation worker resolves it). Terminal: SETTLED, REJECTED, CANCELLED." type: string submittedAt: description: Timestamp (UTC) when the rail accepted the TED for sending to the STR. format: date-time type: string totalAmount: description: "Amount + fee: the total debited (on hold) from the source account, in BRL." examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string transferId: description: Transfer identifier. Use it in queries and actions. format: uuid type: string type: description: TED (another institution, through the STR) or INTERNAL (same institution, settled in the ledger). enum: - TED - INTERNAL type: string updatedAt: description: "Time (UTC) of the last write to the record. This is not always a status change. ⚠️ An INTERNAL transfer can stay in CREATED because the ledger response was undetermined. In that case, the reprocessor uses updatedAt as the queue position on each new attempt, and it moves a transfer whose resend window expired one hour ahead: updatedAt CAN BE IN THE FUTURE (up to 1 h after the current time). Do not use it as a transition time." format: date-time type: string required: - transferId - type - status - amount - feeAmount - totalAmount - purposeCode - sender - recipient - createdAt - updatedAt type: object TransferReturnSummary: additionalProperties: false description: "Return received for a TED that this institution sent: the recipient institution returned the amount, and it was (or is being) credited back to the sender. Only appears in `GET /v1/transfers/{transferId}`, never in the creation response." properties: amount: description: Returned amount in BRL as a decimal string with two decimal places. The return is always in full, so it is always equal to the amount of the original transfer. examples: - "1500.00" pattern: ^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$ type: string feeRefunded: description: If the fee charged at sending was also reversed. Absent means false. type: boolean numCtrlStr: description: "Identifier of the return entry assigned by the STR (20 characters). It can be absent." pattern: ^[A-Za-z0-9]{20}$ type: string receivedAt: description: Instant when the return was recorded. format: date-time type: string refundedAt: description: Instant of the credit back to the sender. Exists only from status=REFUNDED. format: date-time type: string returnCode: description: Official return reason (CodDevTransf, SFN Domain Dictionary). examples: - "5" pattern: ^[0-9]{1,2}$ type: string status: description: "State of the return: RECEIVED (recorded), REFUNDED (re-credit settled in the ledger), or MANUAL_REVIEW (stopped for analysis)." enum: - RECEIVED - REFUNDED - MANUAL_REVIEW type: string required: - returnCode - amount - status - receivedAt type: object UnblockTransferEvidence: additionalProperties: false description: Evidence from the STR that supports the outcome given in the unblock (control identifier, statement, or query). properties: kind: description: "Evidence type: NUM_CTRL_STR (control identifier of the entry in the STR), STR_STATEMENT (STR statement), STR_PENDING_QUERY (query of pending entries), or OTHER." enum: - NUM_CTRL_STR - STR_STATEMENT - STR_PENDING_QUERY - OTHER type: string reference: description: STR control identifier, statement reference, or query reference maxLength: 64 type: string rejectionCode: description: Required when outcome=REJECTED. It becomes Rejection.code (source=OPERATOR) on the transfer. type: string settledAt: description: Recommended when outcome=SETTLED. If absent, the service uses the time of the unblock. format: date-time type: string required: - kind - reference type: object UnblockTransferRequestBody: additionalProperties: false description: Outcome that the operator decides for a transfer whose status in the STR could not be confirmed automatically. It always comes with evidence and a justification. properties: evidence: $ref: "#/components/schemas/UnblockTransferEvidence" description: Evidence from the STR that supports the outcome. justification: description: Operator justification. maxLength: 500 minLength: 10 type: string outcome: description: Outcome applied by the operator. enum: - SETTLED - REJECTED type: string required: - outcome - evidence - justification type: object Upstream: additionalProperties: false description: Error reported by an upstream system (ledger or rail), when the service chooses to expose it. Absent in most errors. 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 UsageLimits: additionalProperties: false description: "Usage limits of the institution per account: maximum amount per transfer, per calendar day (Brasília time), and per month. A missing limit sets no cap." properties: dailyMax: description: Maximum amount (BRL, two decimal places) per source account per calendar day (Brasília time). Absent = no cap. examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string enabled: description: If the limits apply. With false, the service does not count or refuse send requests. type: boolean monthlyMax: description: Maximum amount (BRL, two decimal places) for each source account per calendar month (Brasília time). Missing = no ceiling. examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string perTransactionMax: description: Maximum amount (BRL, two decimal places) of one transfer, fee included. Absent = no cap. examples: - "1500.00" pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$ type: string updatedAt: description: Instant (UTC) of the last write. Ignored on write. format: date-time readOnly: true type: string updatedBy: description: Who wrote it last. Ignored on write; it comes from the authenticated identity. readOnly: true type: string required: - enabled type: object securitySchemes: BearerAuth: bearerFormat: JWT description: "JWT token that the Lerian Access Manager issues for your institution. Send it in `Authorization: Bearer ` on every call (except the public health probes). The tenant never comes from the body, the query, or the path. Each operation requires a role with the matching permission (see the API overview). Without it, 403 `TED-0071`. Missing, invalid, or expired token: 401 `TED-0070`." scheme: bearer type: http info: description: |- API of **TED Lerian**, the interface over Lerian SPB. Your institution uses it to send TEDs, make internal transfers, track incoming TEDs, and operate returns, queues, and policy on its Midaz ledger. The [API overview](/pt/reference/interfaces/ted-lerian/ted-lerian-api-overview) gives the concepts, the roles, and the conventions. title: TED Lerian API version: v1.0.0 openapi: 3.1.0 paths: /v1/incoming-transfers: get: description: |- Lists the TEDs received from other institutions, newest first by default, with cursor pagination. Filters: receipt period (`start_date`/`end_date`, `YYYY-MM-DD`), `status`, recipient account (`account_id`), and `nuop` (the unique operation number; use it to find a TED from the sender's receipt). Use `status=MANUAL_REVIEW` for the queue of pending reviews on your side. Each item has the same shape as `GET /v1/incoming-transfers/{incomingTransferId}`. Follow `next_cursor` until it is `null`. This list also gives `prev_cursor`. operationId: listIncomingTransfers x-mint: href: /pt/reference/interfaces/ted-lerian/list-incoming-teds parameters: - description: Maximum items per page explode: false in: query name: limit schema: default: 20 description: Maximum items per page format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor returned in next_cursor/prev_cursor explode: false in: query name: cursor schema: description: Opaque cursor returned in next_cursor/prev_cursor maxLength: 512 type: string - description: "Order by receipt date: desc (newest first, default) or asc." explode: false in: query name: sort_order schema: default: desc description: "Order by receipt date: desc (newest first, default) or asc." enum: - asc - desc type: string - description: Received on or after (YYYY-MM-DD) explode: false in: query name: start_date schema: description: Received on or after (YYYY-MM-DD) type: string - description: Received on or before (YYYY-MM-DD) explode: false in: query name: end_date schema: description: Received on or before (YYYY-MM-DD) type: string - description: Filters by current status (MANUAL_REVIEW lists the pending reviews). explode: false in: query name: status schema: description: Filters by current status (MANUAL_REVIEW lists the pending reviews). enum: - RECEIVED - CREDITED - RECORDED - RETURN_REQUESTED - RETURNED - MANUAL_REVIEW type: string - description: Recipient account (UUID) explode: false in: query name: account_id schema: description: Recipient account (UUID) format: uuid type: string - description: Unique number of the operation in the rail (23 digits) explode: false in: query name: nuop schema: description: Unique number of the operation in the rail (23 digits) pattern: ^[0-9]{23}$ type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: items: - amount: "1500.00" createdAt: "2026-10-22T14:10:03Z" creditedAmount: "1500.00" creditedAt: "2026-10-22T14:10:09Z" description: Supplier payment feeAmount: "0.00" incomingTransferId: a7d3e9f1-2b4c-4d6e-8f0a-1b3c5d7e9f0a interbankSettledAt: "2026-10-22T14:10:03Z" kind: CLIENT numCtrlStr: STR20261022000000123 nuop: "87654321202610220000123" organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110 purposeCode: "00010" recipient: accountId: 3c5e7a9b-1d2f-4a6c-8e0b-2d4f6a8c0e1f agency: "0001" bankAccount: "0001111222" bankAccountType: CACC bankId: "12345678" document: "98765432100" name: João Pereira sender: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankId: "87654321" document: "12345678909" name: Maria da Silva slaDeadlineAt: "2026-10-22T15:10:03Z" status: CREDITED updatedAt: "2026-10-22T14:10:09Z" limit: 20 next_cursor: prev_cursor: schema: $ref: "#/components/schemas/IncomingTransferPageDTO" description: Page of incoming TEDs. Follow `next_cursor` until it is `null`. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: 'Invalid query parameter: cursor, date range, status, or filter in the wrong format (`TED-0001`).' headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Organization scope not configured for this installation (`TED-0080`): the read fails closed until the configuration exists." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: List incoming TEDs (cursor pagination) tags: - Incoming Transfers /v1/incoming-transfers/{incomingTransferId}: get: description: |- Returns the current state of an incoming TED: `status`, the amount received and credited, the sender, the recipient (with `recipient.accountId` when the account was found), the regulatory deadline (`slaDeadlineAt`, 60 minutes after `interbankSettledAt`), and, when applicable, the manual review reason (`reviewReason`) or the return code (`returnCode`). `reviewReason` is emitted only while `status=MANUAL_REVIEW`. After the TED leaves the review, the timeline keeps the history of reasons. States: `RECEIVED` (decision in progress), `CREDITED` (credited to the customer), `RECORDED` (the institution's own account), `MANUAL_REVIEW` (waits for an operator), `RETURN_REQUESTED` (return sent to the STR), and `RETURNED` (return confirmed). If the STR refuses a return, the TED goes back to `MANUAL_REVIEW` with `reviewReason` filled in. A reversal that an operator requested and that does not complete also goes back to `MANUAL_REVIEW`: `LEDGER_REVERT_REFUSED` when the ledger refused the reversal (the credit was kept), and `LEDGER_REVERT_INDETERMINATE` when the outcome is unknown (the credit may be reversed). You only see TEDs that your institution received. For the sequence of transitions, use `GET /v1/incoming-transfers/{incomingTransferId}/timeline`. operationId: getIncomingTransfer x-mint: href: /pt/reference/interfaces/ted-lerian/get-an-incoming-ted parameters: - description: Identifier of the incoming TED in: path name: incomingTransferId required: true schema: description: Identifier of the incoming TED format: uuid type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: amount: "1500.00" createdAt: "2026-10-22T14:10:03Z" creditedAmount: "1500.00" creditedAt: "2026-10-22T14:10:09Z" description: Supplier payment feeAmount: "0.00" incomingTransferId: a7d3e9f1-2b4c-4d6e-8f0a-1b3c5d7e9f0a interbankSettledAt: "2026-10-22T14:10:03Z" kind: CLIENT numCtrlStr: STR20261022000000123 nuop: "87654321202610220000123" organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110 purposeCode: "00010" recipient: accountId: 3c5e7a9b-1d2f-4a6c-8e0b-2d4f6a8c0e1f agency: "0001" bankAccount: "0001111222" bankAccountType: CACC bankId: "12345678" document: "98765432100" name: João Pereira sender: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankId: "87654321" document: "12345678909" name: Maria da Silva slaDeadlineAt: "2026-10-22T15:10:03Z" status: CREDITED updatedAt: "2026-10-22T14:10:09Z" schema: $ref: "#/components/schemas/IncomingTransferResponse" description: Incoming TED found, in its current status. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Organization scope not configured for this installation (`TED-0080`): the read fails closed until the configuration exists." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Get incoming TED tags: - Incoming Transfers /v1/incoming-transfers/{incomingTransferId}/resolve-review: post: description: |- **Operator** action that decides an incoming TED in `MANUAL_REVIEW` (in any other state, 409 `TED-0060`). - `CREDIT` credits the recipient in the account you send in `accountId` (or in the account already on record). It applies the same validations as the automatic credit: holder, account type, and complete registration (422 `TED-0002` if they fail). - `RETURN` returns the full amount to the sender. It requires `returnCode` (422 `TED-0066`). - `CONFIRM_CREDITED` records a credit already made directly in the ledger. `evidence` is the UUID of the Midaz transaction (422 `TED-0065`). Each TED has at most one credit (key `credit:`). A TED older than the idempotency window of the ledger does not accept `CREDIT` (409 `TED-0060`): reconcile it in the ledger and record it with `CONFIRM_CREDITED`. Requires `X-Idempotency` and a justification. A repeat with the **same** `X-Idempotency` returns the original response (2xx or 4xx) with `X-Idempotency-Replayed: true`. A 5xx response is not stored: a repeat with the same key runs the action again and, if the decision is already applied, responds 409 `TED-0060`. A **new** key on a decision that is already applied responds 409 `TED-0060`: `CREDIT` on a TED that the review already credited, or `RETURN` on a TED already in `RETURN_REQUESTED` or `RETURNED`. On `RETURN`, if the STR refuses the return, or the request is malformed or cannot be sent, the response is 422 `TED-1011`: no money left, and the TED goes to `MANUAL_REVIEW` with `reviewReason=RETURN_REFUSED_BY_STR` or `RETURN_REQUEST_MALFORMED`. The `detail` says if the review is already recorded. If the record fails, the TED stays in `RETURN_REQUESTED` until the routine for stuck TEDs moves it to the review. If the answer of the STR is unknown, the response is 503 `TED-1010`: the return stays requested and is reconciled or sent to manual review. On `CREDIT`, if the ledger refuses, the response is 422 `TED-1001` and nothing changes. If the ledger outcome is unknown, the response is 503 `TED-1000` and the TED stays in manual review. operationId: resolveIncomingTransferReview x-mint: href: /pt/reference/interfaces/ted-lerian/resolve-an-incoming-ted-review parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: Identifier of the incoming TED in: path name: incomingTransferId required: true schema: description: Identifier of the incoming TED format: uuid type: string - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: confirm-credited: summary: Record a credit already applied in the ledger value: action: CONFIRM_CREDITED evidence: e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b justification: Credit posted manually in the ledger after an incident. credit: summary: Credit to the account the operator found value: accountId: 3c5e7a9b-1d2f-4a6c-8e0b-2d4f6a8c0e1f action: CREDIT justification: Account found manually by the recipient's CPF. return: summary: Return to the sender value: action: RETURN justification: The recipient has no account at this institution. returnCode: "2" schema: $ref: "#/components/schemas/ResolveReviewRequestBody" required: true responses: "200": content: application/json: example: amount: "1500.00" createdAt: "2026-10-22T14:10:03Z" creditedAmount: "1500.00" creditedAt: "2026-10-22T14:10:09Z" description: Supplier payment feeAmount: "0.00" incomingTransferId: a7d3e9f1-2b4c-4d6e-8f0a-1b3c5d7e9f0a interbankSettledAt: "2026-10-22T14:10:03Z" kind: CLIENT numCtrlStr: STR20261022000000123 nuop: "87654321202610220000123" organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110 purposeCode: "00010" recipient: accountId: 3c5e7a9b-1d2f-4a6c-8e0b-2d4f6a8c0e1f agency: "0001" bankAccount: "0001111222" bankAccountType: CACC bankId: "12345678" document: "98765432100" name: João Pereira sender: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankId: "87654321" document: "12345678909" name: Maria da Silva slaDeadlineAt: "2026-10-22T15:10:03Z" status: CREDITED updatedAt: "2026-10-22T14:10:09Z" schema: $ref: "#/components/schemas/IncomingTransferResponse" description: "Review resolved. The incoming TED returns in the state that results from the action. If `X-Idempotency-Replayed: true`, this is the replay of a previous resolution." headers: X-Idempotency-Replayed: description: "`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state." schema: type: boolean X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Incoming TED not in `MANUAL_REVIEW`, or a credit older than the ledger idempotency window (`TED-0060`); or a request with the same `X-Idempotency` is still in progress (`TED-0013`; try again after `Retry-After`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "`returnCode` missing with `action=RETURN` (`TED-0066`) or invalid (`TED-0064`); evidence missing or invalid with `CONFIRM_CREDITED` (`TED-0065`); credit validation failed: holder mismatch, incompatible account type, or incomplete registration (`TED-0002`); the ledger refused the credit or its reversal (`TED-1001`); return refused by the STR (`TED-1011`); idempotency key reused with a different body (`TED-0012`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The audit trail cannot record the decision (`TED-9002`): the operator decision is refused before any effect, and nothing changed. Retry with the same `X-Idempotency` once the audit trail is back. Or the account registry is unavailable (`TED-1020`) or the institution configuration is missing (`TED-0080`): no credit was made. Ledger outcome unknown (`TED-1000`): the credit, or the reversal of the credit for `action=RETURN`, can already be recorded. Do not credit the customer by other means. A new `CREDIT` does not credit the customer twice. STR answer unknown on `RETURN` (`TED-1010`): the return stays requested until it is reconciled or sent to manual review." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Resolve manual review of an incoming TED (operator) tags: - Incoming Transfers /v1/incoming-transfers/{incomingTransferId}/return: post: description: |- **Operator** action that returns the full amount of an incoming TED that was already credited. The credit is reversed, and the return goes to the STR with the official reason in `returnCode`. Applies only in `CREDITED`. In `RECEIVED` it responds 409 `TED-0062` (the credit can be in progress). In `MANUAL_REVIEW`, 409 `TED-0062`: resolve it with `POST .../resolve-review` and `action=RETURN`. Returns are always for the full amount. Returns 202 with `status=RETURN_REQUESTED`. The confirmation (`RETURNED`) arrives through a query or an event. Requires `X-Idempotency` and a justification. A repeat with the **same** `X-Idempotency` returns the original response (2xx or 4xx) with `X-Idempotency-Replayed: true`. A 5xx response is not stored: a repeat with the same key runs the action again and, if the return is already in place, responds 409 `TED-0060`. The response is 409 `TED-0060`, whatever the `returnCode`, when an active return is already sent to the STR, already reversed, `AUTOMATIC`, or `RETURNED`. The action is already applied and no new 202 is emitted. If the STR refuses the return, or the request is malformed or cannot be sent, the response is 422 `TED-1011`. The reversal is already done: the credit of the customer **was** reversed, no money left the institution, and the TED goes to `MANUAL_REVIEW` with `reviewReason=RETURN_REFUSED_BY_STR` or `RETURN_REQUEST_MALFORMED`. The `detail` says if the review is already recorded. If the record fails, the TED stays in `RETURN_REQUESTED` until the routine for stuck TEDs moves it to the review. If the answer of the STR is unknown, the response is 503 `TED-1010`: the return stays requested and is reconciled or sent to manual review. If the ledger refuses the reversal, the response is 422 `TED-1001`: the credit is kept and the TED goes to `MANUAL_REVIEW`. If that record fails, the TED stays in `RETURN_REQUESTED` and the return can resume. If the ledger outcome is unknown, the response is 503 `TED-1000`. operationId: returnIncomingTransfer x-mint: href: /pt/reference/interfaces/ted-lerian/return-an-incoming-ted parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: Identifier of the incoming TED in: path name: incomingTransferId required: true schema: description: Identifier of the incoming TED format: uuid type: string - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: default: summary: Full return due to holder mismatch value: justification: The account holder does not match the recipient sent. returnCode: "5" schema: $ref: "#/components/schemas/ReturnIncomingTransferRequestBody" required: true responses: "202": content: application/json: example: amount: "1500.00" createdAt: "2026-10-22T14:10:03Z" creditedAmount: "1500.00" creditedAt: "2026-10-22T14:10:09Z" description: Supplier payment feeAmount: "0.00" incomingTransferId: a7d3e9f1-2b4c-4d6e-8f0a-1b3c5d7e9f0a interbankSettledAt: "2026-10-22T14:10:03Z" kind: CLIENT numCtrlStr: STR20261022000000123 nuop: "87654321202610220000123" organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110 purposeCode: "00010" recipient: accountId: 3c5e7a9b-1d2f-4a6c-8e0b-2d4f6a8c0e1f agency: "0001" bankAccount: "0001111222" bankAccountType: CACC bankId: "12345678" document: "98765432100" name: João Pereira returnCode: "5" sender: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankId: "87654321" document: "12345678909" name: Maria da Silva slaDeadlineAt: "2026-10-22T15:10:03Z" status: RETURN_REQUESTED updatedAt: "2026-10-22T16:20:00Z" schema: $ref: "#/components/schemas/IncomingTransferResponse" description: "Return requested: the incoming TED moves to `RETURN_REQUESTED`. The confirmation (`RETURNED`) arrives through a query or an event. If `X-Idempotency-Replayed: true`, this is the replay of an earlier return." headers: X-Idempotency-Replayed: description: "`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state." schema: type: boolean X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The state does not allow a return (`TED-0062`): still `RECEIVED` (credit in progress) or in `MANUAL_REVIEW` (resolve with `action=RETURN` in the review). Or the return is already applied (`TED-0060`). Or a request with the same `X-Idempotency` is still in processing (`TED-0013`; retry after `Retry-After`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "`returnCode` outside the official domain (`TED-0064`), a partial amount sent (the return is always for the full amount; see the error catalog), invalid fields (`TED-0002`), or an idempotency key reused with a different body (`TED-0012`). With `TED-1001`, the customer's account cannot cover the reversal of the credit: the credit is kept, no return was sent, and the TED moves to `MANUAL_REVIEW`. With `TED-1011`, the STR refused the return: the credit was already reversed." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The audit trail cannot record the decision (`TED-9002`): the operator decision is refused before any effect, and nothing changed. Retry with the same `X-Idempotency` once the audit trail is back. Or the institution configuration is missing (`TED-0080`): nothing was done. Ledger outcome unknown (`TED-1000`): the reversal of the credit can already be recorded, and no return was sent to the STR. Read the TED status: if it is `MANUAL_REVIEW`, resolve it with `POST .../resolve-review`. STR answer unknown (`TED-1010`): the credit is already reversed, and the return stays requested until it is reconciled or sent to manual review." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Request a full return of an incoming TED (operator) tags: - Incoming Transfers /v1/incoming-transfers/{incomingTransferId}/timeline: get: description: |- Returns the timeline of an incoming TED: one entry for each status transition, in chronological order. Each entry has the time, the source and target states, who caused the transition (`origin`), and the related identifier (for example, the `nuop` or the rail event ID). Use it for customer support and audit, especially to explain why a TED went to manual review or was returned. For the current state, `GET /v1/incoming-transfers/{incomingTransferId}` is enough. operationId: getIncomingTransferTimeline x-mint: href: /pt/reference/interfaces/ted-lerian/get-an-incoming-ted-timeline parameters: - description: Identifier of the incoming TED in: path name: incomingTransferId required: true schema: description: Identifier of the incoming TED format: uuid type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: entries: - at: "2026-10-22T14:10:03Z" origin: RAIL reference: "87654321202610220000123" toStatus: RECEIVED - at: "2026-10-22T14:10:09Z" fromStatus: RECEIVED origin: LEDGER toStatus: CREDITED resourceId: a7d3e9f1-2b4c-4d6e-8f0a-1b3c5d7e9f0a schema: $ref: "#/components/schemas/IncomingTimelineDTO" description: Timeline in chronological order, from receipt to the current status. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Organization scope not configured for this installation (`TED-0080`): the read fails closed until the configuration exists." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Timeline of the incoming TED transitions tags: - Incoming Transfers /v1/operations/closing-balance: get: description: |- Returns the day close: the closing balance that the STR reported (`closingBalance`) and, computed by this service in the closing sweep, how many transfers were still pending when the cycle ended (`pendingAtClose`) and how many were rejected in it (`rejectedAtClose`). Use it for the daily check between what the institution sent and what the STR settled. Give `date` (`YYYY-MM-DD`). Without `date`, the service uses today in the institution time zone. While the STR has not closed the cycle for the date, the response is 404 `TED-0010`. operationId: getClosingBalance x-mint: href: /pt/reference/interfaces/ted-lerian/get-the-closing-balance parameters: - description: Reference date (YYYY-MM-DD); default = today in the institution time zone. explode: false in: query name: date schema: description: Reference date (YYYY-MM-DD); default = today in the institution time zone. type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: closingBalance: "1250000.00" date: "2026-10-22" pendingAtClose: 0 rejectedAtClose: 1 reportedAt: "2026-10-22T21:05:00Z" schema: $ref: "#/components/schemas/ClosingBalance" description: Close of the requested date. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Invalid reference date (`TED-0001`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The STR reported no close for the date (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Institution configuration missing (`TED-0080`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Closing balance reported by the STR and items pending at closing tags: - Operations /v1/operations/sla: get: description: |- Report of the three regulatory deadlines of the day: | Metric | Measures | Limit | |---|---|---| | `debitToSubmit` | Debit hold → send to the STR (outgoing TEDs) | 30 min | | `settlementToCredit` | Interbank settlement → credit to the customer (incoming TEDs) | 60 min | | `settlementToReturn` | Interbank settlement → send of the return | 60 min | For each metric: the 50/95/99 percentiles, the violations, and, for today, the open items at risk (`atRisk`, up to 100). Give `date` for a past day. operationId: getSlaReport x-mint: href: /pt/reference/interfaces/ted-lerian/get-the-sla-report parameters: - description: Reference date (YYYY-MM-DD); default = today in the institution time zone. explode: false in: query name: date schema: description: Reference date (YYYY-MM-DD); default = today in the institution time zone. type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: date: "2026-10-22" debitToSubmit: atRisk: - ageSeconds: 1260 amount: "1500.00" attempts: 3 createdAt: "2026-10-22T13:05:12Z" kind: AWAITING_RECONCILIATION lastAttemptAt: "2026-10-22T13:24:40Z" nuop: "87654321202610220000123" resourceId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b resourceType: TRANSFER slaDeadlineAt: "2026-10-22T13:35:13Z" status: AWAITING_RECONCILIATION breaches: 0 limitSeconds: 1800 p50Seconds: 1.8 p95Seconds: 4.2 p99Seconds: 9.5 sampleCount: 128 generatedAt: "2026-10-22T13:26:12Z" settlementToCredit: atRisk: [] breaches: 0 limitSeconds: 3600 p50Seconds: 5.1 p95Seconds: 12 p99Seconds: 40.3 sampleCount: 330 settlementToReturn: atRisk: [] breaches: 0 limitSeconds: 3600 p50Seconds: 95 p95Seconds: 95 p99Seconds: 95 sampleCount: 2 schema: $ref: "#/components/schemas/SlaReport" description: Report of the regulatory deadlines for the requested date. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Invalid reference date (`TED-0001`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Institution configuration missing (`TED-0080`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: "Regulatory deadlines (30/60/60 min): distribution and items at risk" tags: - Operations /v1/operations/summary: get: description: |- Daily summary for the operations dashboard: the operating window of the date, the aggregates of outgoing TEDs (count, amount, distribution by status, rejections by code) and of incoming TEDs (count, amount, status, returns by code), and, for the current day, the number of items in each operations queue. Internal transfers are not part of `outbound`. Send `date` (`YYYY-MM-DD`) for a past day. Without `date`, the service uses today in the institution's time zone. For a past date, `queue` is not returned. operationId: getOperationsSummary x-mint: href: /pt/reference/interfaces/ted-lerian/get-the-daily-summary parameters: - description: Reference date (YYYY-MM-DD); default = today in the institution time zone. explode: false in: query name: date schema: description: Reference date (YYYY-MM-DD); default = today in the institution time zone. type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: date: "2026-10-22" generatedAt: "2026-10-22T18:00:00Z" inbound: amount: "987120.10" byStatus: CREDITED: 330 MANUAL_REVIEW: 4 RECORDED: 6 RETURNED: 2 count: 342 returnsByCode: "2": 1 "5": 1 outbound: amount: "412350.75" byStatus: AWAITING_RECONCILIATION: 1 REJECTED: 2 SETTLED: 120 SUBMITTED: 5 count: 128 rejectionsByCode: STR0015: 1 TED-0031: 1 queue: awaitingReconciliation: 1 exhausted: 0 manualReview: 4 pendingStr: 0 window: clientCutoffTime: "17:00" configured: true date: "2026-10-22" effectiveClosesAt: "2026-10-22T20:00:00Z" effectiveOpensAt: "2026-10-22T09:30:00Z" isBusinessDay: true isOpen: true officialClosesAt: "2026-10-22T20:30:00Z" source: OFFICIAL_SCHEDULE_WITH_CUTOFF schema: $ref: "#/components/schemas/OperationsSummary" description: Operations summary of the requested date. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Invalid reference date (`TED-0001`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Institution configuration missing (`TED-0080`), or the operating window cannot be determined (`TED-0022`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Totals for the day (volumes, amounts, statuses, window) tags: - Operations /v1/participants: get: description: |- STR participant list. Use it to resolve the COMPE code (3 digits, the "bank number" that the customer knows) to the ISPB (8 digits) that identifies the institution in the SPB, and the reverse. Use `compe=` or `ispb=` for an exact search, and `name=` for a search by name prefix (not case-sensitive). When you send a TED, you can give `bankCode` (COMPE) directly. The service does the same resolution, and a bank that is not in this list returns 422 `TED-0006`. The list is sorted by ISPB, with cursor pagination; this list only moves forward. operationId: listStrParticipants x-mint: href: /pt/reference/interfaces/ted-lerian/list-str-participants parameters: - description: Maximum items per page explode: false in: query name: limit schema: default: 20 description: Maximum items per page format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor returned in next_cursor explode: false in: query name: cursor schema: description: Opaque cursor returned in next_cursor maxLength: 512 type: string - description: COMPE code (3 digits) explode: false in: query name: compe schema: description: COMPE code (3 digits) pattern: ^[0-9]{3}$ type: string - description: ISPB (8 digits) explode: false in: query name: ispb schema: description: ISPB (8 digits) pattern: ^[0-9]{8}$ type: string - description: Search by name (prefix, case-insensitive) explode: false in: query name: name schema: description: Search by name (prefix, case-insensitive) maxLength: 100 type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: items: - accessType: RSFN compe: "001" ispb: "00000000" name: BANCO DO BRASIL S.A. updatedAt: "2026-10-01T03:00:00Z" limit: 20 next_cursor: prev_cursor: schema: $ref: "#/components/schemas/ParticipantPage" description: Page of STR participants. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: 'Invalid query parameter: cursor, date range, status, or filter in the wrong format (`TED-0001`).' headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: STR participant list (COMPE ↔ ISPB resolution) tags: - Participants /v1/policy/holidays: put: description: |- Replaces the full national bank holiday calendar of a year. A loaded year covers every date in it. On a holiday there is no operating window (transfer creation responds 422 `TED-0021`). On a date whose year is not loaded, the window is undetermined (503 `TED-0022`). An empty list removes the year. Load the next year before 1 December. A repeat call with the same dates is harmless. A transfer on a date of a year that is not loaded responds 503 `TED-0022` with this detail: "The holiday calendar has no entries for the year of the requested date. Load that year with PUT /v1/policy/holidays." The next request after the load is accepted, with no restart. All dates must belong to the `year` you send. The change is audited. Editor operation. Requires `X-Idempotency`. If the audit trail cannot record the change, TED Lerian refuses it with 503 `TED-9002` and changes nothing: only the audit trail keeps the previous value. Reads stay available. operationId: replaceHolidays x-mint: href: /pt/reference/interfaces/ted-lerian/replace-the-holidays-of-a-year parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: default: summary: Calendar of one year value: holidays: - date: "2026-01-01" name: Confraternização Universal scope: NATIONAL - date: "2026-04-21" name: Tiradentes scope: NATIONAL - date: "2026-12-25" name: Natal scope: NATIONAL year: 2026 schema: $ref: "#/components/schemas/HolidayCalendar" required: true responses: "200": content: application/json: example: holidays: - date: "2026-01-01" name: Confraternização Universal scope: NATIONAL - date: "2026-04-21" name: Tiradentes scope: NATIONAL - date: "2026-12-25" name: Natal scope: NATIONAL updatedAt: "2026-10-22T12:00:00Z" year: 2026 schema: $ref: "#/components/schemas/HolidayCalendar" description: Calendar of the year replaced and audited. The body returns the current calendar. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" X-Idempotency-Replayed: description: '`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state.' schema: type: boolean "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Dates outside the given year, or invalid fields (`TED-0002`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The audit trail cannot record the change (`TED-9002`). Nothing changed. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Replace the holidays of a year (editor; audited) tags: - Policy /v1/policy/ispb-bindings: get: description: Returns the bindings between the ISPBs that the institution uses to operate in the STR and the organizations/ledgers that receive the TEDs addressed to each one. This table decides in which organization an **incoming** TED is credited. If there is no binding for the credited ISPB, the TED goes to manual review (`ISPB_BINDING_UNRESOLVED`). operationId: listIspbBindings x-mint: href: /pt/reference/interfaces/ted-lerian/list-ispb-bindings parameters: - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: bindings: - ispb: "12345678" ledgerId: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110 priority: 1 updatedAt: "2026-10-01T12:00:00Z" schema: $ref: "#/components/schemas/IspbBindingsBody" description: Current bindings of the institution. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Any other error, in the same `application/problem+json` envelope with a `TED-NNNN` code. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: ISPB → organization/ledger bindings of the institution tags: - Policy put: description: |- Replaces all ISPB → organization/ledger bindings of the institution. Each binding points an ISPB to the organization and the ledger (Midaz) where the TEDs received through it are credited. Among bindings of the same ISPB, the lowest `priority` wins, and a priority cannot repeat. Invalid bindings, a duplicate priority, or the same ISPB bound twice to the same organization and ledger respond 422 `TED-0002`. A binding to an organization or ledger other than the ones where this installation credits incoming TEDs also responds 422 `TED-0002`. The list must have at least one binding: an empty or `null` list responds 422 `TED-0002` and nothing changes. Configure them before you receive the first TED. With the ledger and the CRM integrations on, TED Lerian refuses a binding with 422 `TED-0002` when something a TED needs is missing, and the message names each item: the organization in Midaz, the BRL asset on the ledger (account `@external/BRL`), and the institution's holder, found by the organization's CNPJ, with an account in the CRM. If Midaz or the CRM does not answer, the response is 503 (`TED-1000` or `TED-1020`) and nothing is written. The change is audited. Editor operation. Requires `X-Idempotency`. If the audit trail cannot record the change, TED Lerian refuses it with 503 `TED-9002` and changes nothing: only the audit trail keeps the previous value. Reads stay available. operationId: replaceIspbBindings x-mint: href: /pt/reference/interfaces/ted-lerian/replace-ispb-bindings parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: default: summary: An ISPB bound to an organization value: bindings: - ispb: "12345678" ledgerId: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110 priority: 1 schema: $ref: "#/components/schemas/IspbBindingsBody" required: true responses: "200": content: application/json: example: bindings: - ispb: "12345678" ledgerId: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110 priority: 1 updatedAt: "2026-10-22T12:00:00Z" schema: $ref: "#/components/schemas/IspbBindingsBody" description: Configuration saved and audited; the body returns the current configuration. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" X-Idempotency-Replayed: description: '`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state.' schema: type: boolean "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Empty list, invalid ISPB or organization binding, repeated priority for the same ISPB, or repeated binding (`TED-0002`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Midaz (`TED-1000`) or the CRM (`TED-1020`) does not answer the setup check, or the audit trail cannot record the change (`TED-9002`). Nothing changed. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Replace ISPB → organization bindings (editor; audited) tags: - Policy /v1/policy/limits: get: description: |- Returns the current usage limits of the institution: if they are active, and the caps per transfer, per day, and per month (per source account, fee included). A missing cap means no limit. While no limit is set with `PUT /v1/policy/limits`, the response is 503 `TED-0080`. Send requests also return this error, because this configuration is required before the first TED. operationId: getUsageLimits x-mint: href: /pt/reference/interfaces/ted-lerian/get-usage-limits parameters: - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: dailyMax: "200000.00" enabled: true monthlyMax: "1000000.00" perTransactionMax: "50000.00" updatedAt: "2026-10-01T12:00:00Z" updatedBy: admin@instituicao.example schema: $ref: "#/components/schemas/UsageLimits" description: Current limits of the institution. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Limits are not configured yet for the institution (`TED-0080`): set them with `PUT /v1/policy/limits` before the first transfer." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Get the institution's usage limits tags: - Policy put: description: |- Sets the usage limits for each source account, fee included: `perTransactionMax`, `dailyMax` (calendar day, Brasília time), and `monthlyMax`, with `perTransactionMax ≤ dailyMax ≤ monthlyMax`. An omitted ceiling sets no limit. `enabled=false` turns off the count. Required before the first transfer. Usage is put on hold when you create a transfer and released if the transfer is rejected or cancelled. If a limit is exceeded, 422 `TED-0030`. Audited. Requires `X-Idempotency`. If the audit trail cannot record the change, TED Lerian refuses it with 503 `TED-9002` and changes nothing: only the audit trail keeps the previous value. Reads stay available. operationId: updateUsageLimits x-mint: href: /pt/reference/interfaces/ted-lerian/set-usage-limits parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: default: summary: Limits per transfer, day, and month value: dailyMax: "200000.00" enabled: true monthlyMax: "1000000.00" perTransactionMax: "50000.00" schema: $ref: "#/components/schemas/UsageLimits" required: true responses: "200": content: application/json: example: dailyMax: "200000.00" enabled: true monthlyMax: "1000000.00" perTransactionMax: "50000.00" updatedAt: "2026-10-22T12:00:00Z" updatedBy: admin@instituicao.example schema: $ref: "#/components/schemas/UsageLimits" description: Configuration saved and audited; the body returns the current configuration. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" X-Idempotency-Replayed: description: '`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state.' schema: type: boolean "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Invalid fields (`TED-0002`, see `errors`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The audit trail cannot record the change (`TED-9002`). Nothing changed. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Set usage limits (editor; audited) tags: - Policy /v1/policy/window: get: description: |- Returns the operating window of a day, that is, when the institution accepts TED send requests. It combines the official STR schedule, the institution cut-off, and the holiday calendar. `isOpen` tells if the window is open now. `source` tells what decided the result (schedule, schedule with cut-off, holiday, or weekend). Outside the window, a send request returns 422 `TED-0020`. On a non-business day, it returns 422 `TED-0021`. If the schedule is unavailable, or the holiday calendar does not cover the date, it returns 503 `TED-0022`. When the STR has not published the customer-transfer schedule for the date, `TED-0022` carries the detail "The STR has not published the customer-transfer schedule for the requested date, so the operating window cannot be determined." When the schedule could not be read from the rail, it carries "The STR schedule could not be read from the rail, so the operating window cannot be determined. Retry later; if it persists, the institution's rail connection needs operator attention." Give `date` for another day; times are in UTC. operationId: getOperatingWindow x-mint: href: /pt/reference/interfaces/ted-lerian/get-the-operating-window parameters: - description: "Reference date (YYYY-MM-DD). Default: today in the institution time zone." explode: false in: query name: date schema: description: "Reference date (YYYY-MM-DD). Default: today in the institution time zone." format: date type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: clientCutoffTime: "17:00" configured: true date: "2026-10-22" effectiveClosesAt: "2026-10-22T20:00:00Z" effectiveOpensAt: "2026-10-22T09:30:00Z" isBusinessDay: true isOpen: true officialClosesAt: "2026-10-22T20:30:00Z" source: OFFICIAL_SCHEDULE_WITH_CUTOFF schema: $ref: "#/components/schemas/OperatingWindow" description: Effective window for the requested date (today by default). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Invalid reference date (`TED-0001`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Official schedule or configuration unavailable, or a holiday calendar that does not cover the date, so the window is undetermined (`TED-0022`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Get the effective window (official schedule ⊕ cut-off ⊕ calendar) and the configured cut-off tags: - Policy put: description: |- Sets the institution cut-off: the local time (`HH:MM`) after which the institution stops accepting send requests for the day. The cut-off is always equal to or more conservative than the official STR close. A cut-off later than the official close is refused with 422 `TED-0081`. Optionally, give `timezone` (IANA); the default is the institution time zone. The change applies immediately, and the service audits it with the caller's identity. The response returns today's effective window, already recalculated. Editor operation; `X-Idempotency` is required. If the audit trail cannot record the change, TED Lerian refuses it with 503 `TED-9002` and changes nothing: only the audit trail keeps the previous value. Reads stay available. operationId: updateOperatingWindowCutoff x-mint: href: /pt/reference/interfaces/ted-lerian/set-the-cut-off parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: default: summary: Cut-off at 17:00 Brasília time value: clientCutoffTime: "17:00" timezone: America/Sao_Paulo schema: $ref: "#/components/schemas/OperatingWindowCutoff" required: true responses: "200": content: application/json: example: clientCutoffTime: "17:00" configured: true date: "2026-10-22" effectiveClosesAt: "2026-10-22T20:00:00Z" effectiveOpensAt: "2026-10-22T09:30:00Z" isBusinessDay: true isOpen: true officialClosesAt: "2026-10-22T20:30:00Z" source: OFFICIAL_SCHEDULE_WITH_CUTOFF schema: $ref: "#/components/schemas/OperatingWindow" description: Cut-off saved and audited. The body returns today's effective window, already recalculated. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" X-Idempotency-Replayed: description: '`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state.' schema: type: boolean "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Cut-off later than the official close of the STR (`TED-0081`), or invalid fields (`TED-0002`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Operating window undetermined (`TED-0022`), or the audit trail cannot record the change (`TED-9002`). Nothing changed. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Set the institution's cut-off (always equal to or more conservative than the official schedule) tags: - Policy /v1/reconciliation/held-returns: get: description: "**Operator** action that lists the open held returns: returns (STR0010R2) received from the STR for TEDs that no `SETTLED` transfer of this institution carries by `NumCtrlSTR`. Nobody has been refunded yet. Oldest first, without pagination.\n\nEach item says whether a TED Lerian transfer carries the returned `NumCtrlSTR` (`transferId` and `transferStatus`) or not (`null`: no TED Lerian transfer carries it). Decide by `transferStatus`: `REJECTED` or `CANCELLED` means the sender was never debited, so there is nothing to credit and you must never credit the sender. A transfer that can still settle is refunded by TED Lerian itself when it settles. Close the others with `POST /v1/reconciliation/held-returns/{heldReturnId}/close`, giving the ledger transaction that evidences the outcome." operationId: listHeldReturns parameters: - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: schema: $ref: "#/components/schemas/HeldReturnListDTO" example: items: - amount: '1500.00' id: 0d3f8c1a-6b2e-4a7c-9d5f-1e2a3b4c5d6e originalNumCtrlStr: STR20261022000000123 returnCode: '1' returnedAt: '2026-10-22T14:10:05Z' transferId: transferStatus: - amount: '250.00' id: 7a9c2e4f-1b3d-4c5e-8f6a-2d4b6c8e0a1f originalNumCtrlStr: STR20261022000000456 returnCode: '2' returnedAt: '2026-10-22T14:12:30Z' transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b transferStatus: REJECTED description: Open held returns, oldest first. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: 'Not authenticated: token missing, invalid, or expired (`TED-0070`).' headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Institution configuration missing (`TED-0080`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: List held returns with no settled original TED (operator) tags: - Reconciliation x-mint: href: /pt/reference/interfaces/ted-lerian/list-held-returns /v1/reconciliation/held-returns/{heldReturnId}/close: post: description: |- **Operator** action that closes a held return with the ledger transaction that evidences it (`ledgerTransactionId`), recording the operator and the time. TED Lerian does not move money: the credit to the sender, when due, is made in the ledger beforehand, and only recorded here. Which transaction to send: - No TED Lerian transfer carries the `NumCtrlSTR` (`transferId` null): the transaction that credited the sender. If the TED was a TED Lerian transfer that ended `REJECTED` or `CANCELLED`, the sender was never debited: never credit the sender, and send the transaction that released the sender's hold. - `transferStatus` `REJECTED` or `CANCELLED`: the STR settled a TED that TED Lerian recorded as failed, and the return reverses that settlement. The sender was never debited, so there is nothing to credit, and the sender must never be credited. The evidence is the transaction that released the sender's hold. The response shows that `transferStatus`. A closed return is never refunded by TED Lerian, even if the original TED settles later. Repeating the closure with the same transaction returns the existing record. With another transaction, the response is 409 `TED-0060`: the recorded transaction stays the closure, and the sender may have been credited twice, so reverse only the credit made for this attempt. If TED Lerian already took the return when the TED settled (it refunded the sender or parked the return for review), the response is also 409 `TED-0060`: when the transfer shows this return refunded, reverse any ledger credit made for it. If the TED Lerian transfer can still settle, the response is 409 `TED-0067`: TED Lerian refunds the sender when it settles, so reverse the credit as well. Requires `X-Idempotency`; always check `X-Idempotency-Replayed`. operationId: closeHeldReturn parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: Identifier of the held return. in: path name: heldReturnId required: true schema: description: Identifier of the held return. format: uuid type: string - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: schema: $ref: "#/components/schemas/CloseHeldReturnRequest" examples: credited: summary: 'TED not sent through TED Lerian: sender credited in the ledger' value: ledgerTransactionId: c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f released: summary: 'TED Lerian transfer ended REJECTED: hold released, nothing to credit' value: ledgerTransactionId: e8f9a0b1-c2d3-4e4f-8a5b-6c7d8e9f0a1b required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/HeldReturnResponse" example: amount: '250.00' closedAt: '2026-10-22T15:02:00Z' closedBy: operator@instituicao.example id: 7a9c2e4f-1b3d-4c5e-8f6a-2d4b6c8e0a1f ledgerTransactionId: e8f9a0b1-c2d3-4e4f-8a5b-6c7d8e9f0a1b originalNumCtrlStr: STR20261022000000456 returnCode: '2' returnedAt: '2026-10-22T14:12:30Z' transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b transferStatus: REJECTED description: 'Held return closed. If `X-Idempotency-Replayed: true`, this is the replay of a previous closure.' headers: X-Idempotency-Replayed: description: "`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state." schema: type: boolean X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: 'Not authenticated: token missing, invalid, or expired (`TED-0070`).' headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The held return does not exist in this institution (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Return closed with another ledger transaction, or already taken by TED Lerian when its TED settled (`TED-0060`); a transfer that can still settle carries the return (`TED-0067`); or a request with the same `X-Idempotency` is still processing (`TED-0013`; retry after `Retry-After`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "A validation or business rule failed: invalid fields (`TED-0002`, see `errors`), or `X-Idempotency` reused with a different body (`TED-0012`). Refusals specific to the operation are in its description." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Institution configuration missing (`TED-0080`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Close a held return with ledger evidence (operator) tags: - Reconciliation x-mint: href: /pt/reference/interfaces/ted-lerian/close-a-held-return /v1/reconciliation/inconsistencies: get: description: |- Lists the differences found between the ledger and what the STR reported for the same resource. Example: a return received without the matching re-credit. A finding stays `OPEN` while the difference continues, and changes to `CLEARED` when the service no longer observes it. By default, the list shows the `OPEN` findings, from oldest to newest. Filter by `check`, `status`, and resource type. `openByCheck` gives the count of open findings per check for the whole tenant, for the dashboard. Findings are informational: you make the fix in the resources they point to. operationId: listInconsistencyFindings x-mint: href: /pt/reference/interfaces/ted-lerian/list-inconsistency-findings parameters: - description: Checks to list, separated by commas. Missing = all. explode: false in: query name: check schema: description: Checks to list, separated by commas. Missing = all. items: enum: - RETURN_WITHOUT_REFUND - ORPHAN_HOLD - SETTLED_WITHOUT_COMMIT - RESERVED_AFTER_RELEASE - LEDGER_STATUS_CONTRADICTION - CREDIT_WITHOUT_FACT - CREDIT_STATUS_CONTRADICTION - RETURN_WITHOUT_REVERT type: string type: array - description: "State of the findings: OPEN (default) or CLEARED." explode: false in: query name: status schema: default: OPEN description: "State of the findings: OPEN (default) or CLEARED." enum: - OPEN - CLEARED type: string - description: Resource type. Missing = both. explode: false in: query name: resource_type schema: description: Resource type. Missing = both. enum: - TRANSFER - INCOMING_TRANSFER type: string - description: Maximum items per page explode: false in: query name: limit schema: default: 20 description: Maximum items per page format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor returned in next_cursor explode: false in: query name: cursor schema: description: Opaque cursor returned in next_cursor maxLength: 512 type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: items: - amount: "1500.00" check: SETTLED_WITHOUT_COMMIT detail: SETTLED transfer with no ledger_commit_id recorded. firstDetectedAt: "2026-10-22T13:10:00Z" id: d0a6b2c4-5e7f-4a91-8c3d-4e6f8a0b2c3d lastDetectedAt: "2026-10-22T13:40:00Z" nuop: "87654321202610220000123" observedStatus: SETTLED organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110 resourceId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b resourceType: TRANSFER status: OPEN limit: 20 next_cursor: openByCheck: CREDIT_STATUS_CONTRADICTION: 0 CREDIT_WITHOUT_FACT: 0 LEDGER_STATUS_CONTRADICTION: 0 ORPHAN_HOLD: 0 RESERVED_AFTER_RELEASE: 0 RETURN_WITHOUT_REFUND: 0 RETURN_WITHOUT_REVERT: 0 SETTLED_WITHOUT_COMMIT: 1 prev_cursor: schema: $ref: "#/components/schemas/InconsistencyFindingPage" description: Page of findings and, in `openByCheck`, the count of open findings per check across the whole tenant. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: 'Invalid query parameter: cursor, date range, status, or filter in the wrong format (`TED-0001`).' headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Institution configuration missing (`TED-0080`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Inconsistency findings between ledger and rail (open or resolved), with a count per check tags: - Reconciliation /v1/reconciliation/queue: get: description: |- Lists the items that need attention from operations, from oldest to newest: outgoing TEDs in `PENDING_STR`, `AWAITING_RECONCILIATION`, and `EXHAUSTED`, and incoming TEDs in `MANUAL_REVIEW`. Each item has `ageSeconds` and `slaDeadlineAt`, so you can prioritize by regulatory deadline. Filter by `kind` and minimum age. The action depends on the queue: `AWAITING_RECONCILIATION` and `EXHAUSTED` → `POST /v1/transfers/{id}/unblock` with evidence from the STR; `PENDING_STR` → wait for the STR outcome (or request the cancellation of the pending entry with `POST /v1/transfers/{id}/cancel`); `MANUAL_REVIEW` → `POST /v1/incoming-transfers/{id}/resolve-review`. operationId: listReconciliationQueue x-mint: href: /pt/reference/interfaces/ted-lerian/list-the-operations-queue parameters: - description: Maximum items per page explode: false in: query name: limit schema: default: 20 description: Maximum items per page format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor returned in next_cursor explode: false in: query name: cursor schema: description: Opaque cursor returned in next_cursor maxLength: 512 type: string - description: Queue to list; missing = all. A return that the STR refused appears with kind=MANUAL_REVIEW. explode: false in: query name: kind schema: description: Queue to list; missing = all. A return that the STR refused appears with kind=MANUAL_REVIEW. enum: - PENDING_STR - AWAITING_RECONCILIATION - EXHAUSTED - MANUAL_REVIEW type: string - description: Minimum age of the item, in seconds, measured as ageSeconds (from the start of the current regulatory deadline, otherwise from entry into the current status) explode: false in: query name: min_age_seconds schema: description: Minimum age of the item, in seconds, measured as ageSeconds (from the start of the current regulatory deadline, otherwise from entry into the current status) format: int64 minimum: 0 type: integer - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: items: - ageSeconds: 1260 amount: "1500.00" attempts: 3 createdAt: "2026-10-22T13:05:12Z" kind: AWAITING_RECONCILIATION lastAttemptAt: "2026-10-22T13:24:40Z" nuop: "87654321202610220000123" resourceId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b resourceType: TRANSFER slaDeadlineAt: "2026-10-22T13:35:13Z" status: AWAITING_RECONCILIATION limit: 20 next_cursor: prev_cursor: schema: $ref: "#/components/schemas/ReconciliationQueuePage" description: Page of the operations queue, from the oldest item to the newest. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: 'Invalid query parameter: cursor, date range, status, or filter in the wrong format (`TED-0001`).' headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Institution configuration missing (`TED-0080`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Operations queue (pending in the STR, awaiting reconciliation, exhausted, manual review) tags: - Reconciliation /v1/reconciliation/reviews: get: description: |- Lists, oldest first, the `PENDING` reviews of rail (STR) facts that need an operator decision: facts that arrived with no matching transfer, facts with a contradictory state, or facts whose ledger effect stayed pending. Filter by `reason`, `transfer_id`, or `nuop`. `NUM_CTRL_STR_UNUSABLE` reviews have no associated transfer, and you can only find them by `nuop`. Cursor pagination (`next_cursor`). This list only moves forward. Each review has `detail` in operations language and `eventKey`, the key of the event that created it. Resolve it with `POST /v1/reconciliation/reviews/{reviewId}/resolve`. operationId: listReconciliationReviews x-mint: href: /pt/reference/interfaces/ted-lerian/list-rail-fact-reviews parameters: - description: "Review reason. UNKNOWN_SIT_LANC_STR: the STR sent a SitLancSTR outside the BACEN domain for an in-flight TED (read of a pending entry). EMPTY_SIT_LANC_STR: reserved; not produced." explode: false in: query name: reason schema: description: "Review reason. UNKNOWN_SIT_LANC_STR: the STR sent a SitLancSTR outside the BACEN domain for an in-flight TED (read of a pending entry). EMPTY_SIT_LANC_STR: reserved; not produced." enum: - EMPTY_SIT_LANC_STR - UNKNOWN_SIT_LANC_STR - UNHANDLED_FACT_KIND - NUM_CTRL_STR_UNUSABLE - TRANSFER_NOT_FOUND - AMBIGUOUS_CORRELATION - UNEXPECTED_SOURCE_STATE - TERMINAL_CONTRADICTION - LEDGER_EFFECT_PENDING - RETURN_NOT_APPLICABLE type: string - description: Related transfer (UUID) explode: false in: query name: transfer_id schema: description: Related transfer (UUID) format: uuid type: string - description: NumCtrlIF (23 digits) — NUM_CTRL_STR_UNUSABLE reviews have no associated transfer and can only be found by this value explode: false in: query name: nuop schema: description: NumCtrlIF (23 digits) — NUM_CTRL_STR_UNUSABLE reviews have no associated transfer and can only be found by this value pattern: ^[0-9]{23}$ type: string - description: Maximum items per page explode: false in: query name: limit schema: default: 20 description: Maximum items per page format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor returned in next_cursor explode: false in: query name: cursor schema: description: Opaque cursor returned in next_cursor maxLength: 512 type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: items: - createdAt: "2026-10-22T13:06:00Z" detail: Settlement confirmed by the STR, but the hold commit in the ledger is not recorded yet. eventKey: settlement.settled id: b8e4f0a2-3c5d-4e7f-9a1b-2c4d6e8f0a1b nuop: "87654321202610220000123" occurredAt: "2026-10-22T13:05:41Z" reason: LEDGER_EFFECT_PENDING status: PENDING transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b limit: 20 next_cursor: schema: $ref: "#/components/schemas/RailFactReviewPageDTO" description: Page of pending reviews, from oldest to newest. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: 'Invalid query parameter: cursor, date range, status, or filter in the wrong format (`TED-0001`).' headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Institution configuration missing (`TED-0080`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: List pending rail fact reviews (operator) tags: - Reconciliation /v1/reconciliation/reviews/{reviewId}/resolve: post: description: |- **Operator** action that closes a review of a rail fact. - `ACKNOWLEDGE` closes a review that you already analyzed. It is refused (409 `TED-0060`) for `LEDGER_EFFECT_PENDING`, because a financial effect is still not applied. - `RETRY_LEDGER_EFFECT` runs the pending ledger effect again with the original key. If the ledger still does not record it, the response is 503 `TED-1000` and the review stays pending. When you resolve the review of a `PENDING_STR` TED that the daily close held, the next cycle of the reconciliation step releases the TED. This happens after `reconciliation_due_sec` (default 900 s) has passed since the TED entered `PENDING_STR` or since its cancellation request was recorded. For a TED that the close held, this is usually about one minute after the resolution. If the STR refuses it, the TED becomes `REJECTED`, or `CANCELLED` when a cancellation was requested, and the hold is released once. The resolution itself does not change the TED. The service does not resend a refund that is older than the ledger idempotency window (409 `TED-0060`): reconcile it manually in the ledger. A review that is already resolved returns 409 `TED-0060`. `X-Idempotency` and a justification are required. operationId: resolveReconciliationReview x-mint: href: /pt/reference/interfaces/ted-lerian/resolve-a-rail-fact-review parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: Review identifier in: path name: reviewId required: true schema: description: Review identifier format: uuid type: string - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: acknowledge: summary: Close a review that was already analyzed value: action: ACKNOWLEDGE justification: Duplicate rail fact, already reflected in the transfer. retry: summary: Run the pending ledger effect again value: action: RETRY_LEDGER_EFFECT justification: The ledger is back online; re-running the pending commit. schema: $ref: "#/components/schemas/ResolveReconciliationReviewRequest" required: true responses: "200": content: application/json: example: action: RETRY_LEDGER_EFFECT outcome: COMMITTED review: createdAt: "2026-10-22T13:06:00Z" detail: Settlement confirmed by the STR, but the hold commit in the ledger is not recorded yet. eventKey: settlement.settled id: b8e4f0a2-3c5d-4e7f-9a1b-2c4d6e8f0a1b nuop: "87654321202610220000123" occurredAt: "2026-10-22T13:05:41Z" reason: LEDGER_EFFECT_PENDING resolvedAt: "2026-10-22T13:40:00Z" resolvedBy: operator@instituicao.example status: RESOLVED transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b schema: $ref: "#/components/schemas/ResolveReconciliationReviewResponse" description: "Review resolved; `review` already shows the new state. If `X-Idempotency-Replayed: true`, this is the replay of a previous resolution." headers: X-Idempotency-Replayed: description: "`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state." schema: type: boolean X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The review does not exist in this institution (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Review already resolved, action not compatible with the review reason, or refund older than the ledger's idempotency window (`TED-0060`); or a request with the same `X-Idempotency` is still processing (`TED-0013`; retry after `Retry-After`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "A validation or business rule failed: invalid fields (`TED-0002`, see `errors`), or `X-Idempotency` reused with a different body (`TED-0012`). Refusals specific to the operation are in its description." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The audit trail cannot record the decision (`TED-9002`): the operator decision is refused before any effect, and nothing changed. Retry with the same `X-Idempotency` once the audit trail is back. Or the ledger effect is still not recorded after the re-run (`TED-1000`; the review stays pending), or the institution configuration is missing (`TED-0080`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Resolve a review of a rail fact (operator) tags: - Reconciliation /v1/reconciliation/runs: post: description: |- Starts a reconciliation cycle on demand. This is the same cycle that the worker runs periodically: it queries the rail about the transfers in `AWAITING_RECONCILIATION` and applies the conclusive outcomes. Use it after a rail outage, or when operations do not want to wait for the next cycle. The response is 202 with the `runId` of the scheduled cycle. Processing is asynchronous, and its effects appear in the transfers and in the operations queue. Only one cycle runs at a time: if a cycle is already running, the response is 409 `TED-0015`. `X-Idempotency` is required (no body). Check `X-Idempotency-Replayed` in the response to tell a new cycle from a replay. operationId: triggerReconciliationRun x-mint: href: /pt/reference/interfaces/ted-lerian/start-a-reconciliation-run parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" responses: "202": content: application/json: example: requestedAt: "2026-10-22T13:30:00Z" runId: c9f5a1b3-4d6e-4f80-9b2c-3d5e7f9a1b2c status: SCHEDULED schema: $ref: "#/components/schemas/ReconciliationRunResponse" description: "Run scheduled. `runId` identifies the cycle. If `X-Idempotency-Replayed: true`, this is the replay of an earlier trigger." headers: X-Idempotency-Replayed: description: "`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state." schema: type: boolean X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "`X-Idempotency` missing or in the wrong format (`TED-0011`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: A reconciliation cycle is already running (`TED-0015`), or a request with the same `X-Idempotency` is still in progress (`TED-0013`; try again after `Retry-After`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "A validation or business rule failed: invalid fields (`TED-0002`, see `errors`), or `X-Idempotency` reused with a different body (`TED-0012`). Refusals specific to the operation are in its description." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Institution configuration missing (`TED-0080`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Trigger an on-demand reconciliation run tags: - Reconciliation /v1/transfers: get: description: |- Lists the outgoing (TED) and internal transfers of the institution, newest first by default, with cursor pagination. Filters: creation period (`start_date`/`end_date`, `YYYY-MM-DD`), `status`, `type` (`TED` or `INTERNAL`), source account (`account_id`), and the requester reference (`client_reference`) you sent when you created the transfer. Use it to find the transfer for one of your orders. Combine `sort_order=asc` with `start_date` to reprocess a period in chronological order. Each item has the same shape as `GET /v1/transfers/{transferId}`, except `returned` (returns received), which only appears in the single-transfer query. Follow `next_cursor` until it is `null`. This list also gives `prev_cursor`. To track a specific transfer, use the single-transfer query or the events. Use the list for screens, statements, and reconciliation on your side. operationId: listTransfers x-mint: href: /pt/reference/interfaces/ted-lerian/list-transfers parameters: - description: Maximum items per page explode: false in: query name: limit schema: default: 20 description: Maximum items per page format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor returned in next_cursor/prev_cursor explode: false in: query name: cursor schema: description: Opaque cursor returned in next_cursor/prev_cursor maxLength: 512 type: string - description: "Order by creation date: desc (newest first, default) or asc." explode: false in: query name: sort_order schema: default: desc description: "Order by creation date: desc (newest first, default) or asc." enum: - asc - desc type: string - description: Created on or after (YYYY-MM-DD) explode: false in: query name: start_date schema: description: Created on or after (YYYY-MM-DD) type: string - description: Created on or before (YYYY-MM-DD) explode: false in: query name: end_date schema: description: Created on or before (YYYY-MM-DD) type: string - description: Filters by current state. explode: false in: query name: status schema: description: Filters by current state. enum: - CREATED - RESERVED - SUBMITTED - PENDING_STR - SETTLED - REJECTED - CANCELLED - AWAITING_RECONCILIATION - EXHAUSTED type: string - description: "Filters by path: TED (another institution) or INTERNAL (your own institution)." explode: false in: query name: type schema: description: "Filters by path: TED (another institution) or INTERNAL (your own institution)." enum: - TED - INTERNAL type: string - description: Source account (UUID) explode: false in: query name: account_id schema: description: Source account (UUID) format: uuid type: string - description: Filters by the requester reference sent when the transfer was created (clientReference). explode: false in: query name: client_reference schema: description: Filters by the requester reference sent when the transfer was created (clientReference). maxLength: 64 type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: items: - amount: "1500.00" clientReference: PED-2026-000123 createdAt: "2026-10-22T13:05:12Z" description: Supplier payment feeAmount: "3.25" metadata: channel: mobile orderId: PED-2026-000123 numCtrlStr: STR20261022000000123 nuop: "87654321202610220000123" purposeCode: "00010" railOperationId: 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b recipient: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankCode: "001" bankId: "87654321" document: "12345678909" name: Maria da Silva reservedAt: "2026-10-22T13:05:13Z" sender: accountId: 0a2f4c6e-8b1d-4e3f-9a5b-7c9d1e3f5a7b agency: "0001" bankAccount: "0001111222" bankAccountType: CACC bankId: "12345678" document: "98765432100" name: João Pereira settledAt: "2026-10-22T13:05:41Z" status: SETTLED submittedAt: "2026-10-22T13:05:14Z" totalAmount: "1503.25" transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b type: TED updatedAt: "2026-10-22T13:05:41Z" limit: 20 next_cursor: eyJzYyI6ImNyZWF0ZWRfYXQiLCJzdiI6IjIwMjYtMTAtMjJUMTM6MDU6MTJaIiwiaSI6IjZmMWMuLi4iLCJwbiI6MX0 prev_cursor: schema: $ref: "#/components/schemas/TransferPageDTO" description: Page of transfers. Follow `next_cursor` until it is `null`. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: 'Invalid query parameter: cursor, date range, status, or filter in the wrong format (`TED-0001`).' headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Organization scope not configured for this installation (`TED-0080`): the read fails closed until the configuration exists." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: List outgoing/internal transfers (cursor pagination) tags: - Transfers post: description: |- Sends a TED to another institution or, if the recipient is in your own institution, an internal transfer. The recipient's bank (`recipient.bankId` or `recipient.bankCode`) decides the path. Send `X-Account-Id` with the debited account and `X-Idempotency` with a new key for each payment. The service validates the request and applies the institution policy (window and usage limits). Then it holds the amount in Midaz, where the fee packages of the institution add their fee to the hold, and sends the TED to the STR. Settlement is asynchronous: track it with `GET /v1/transfers/{transferId}` or with the `transfer.*` events. | `status` in the 201 response | Meaning | |---|---| | `SUBMITTED` | The rail accepted the TED and sent it to the STR. Wait for `SETTLED` or `REJECTED` | | `SETTLED` | Internal transfer (`type=INTERNAL`) already settled in the ledger, with `recipient.accountId` filled in | | `REJECTED` | Synchronous refusal from the ledger or the rail; the hold was released. Example: insufficient balance, `rejection.code=TED-0031` | | `AWAITING_RECONCILIATION` / `CREATED` | Undetermined outcome (no conclusive response from the rail or the ledger); automatic reconciliation resolves it. Do not resend with another key | Validation and policy refusals return 4xx/503 **without creating a resource**: fix the request and resend it with a new key. A purpose code (`purposeCode`) that is unknown, or not in force on the date of the request, in the BACEN FinlddCli Domain Dictionary returns 422 `TED-0003`. TED Lerian checks the check digits of the recipient's CPF or CNPJ (`recipient.document`): an invalid document returns 422 `TED-0007` (an alphanumeric CNPJ is not accepted). If the internal recipient is not in the organization's registry, the response is 422 `TED-1021`. A materially identical request that arrives with another key in the anti-duplication window returns 409 `TED-0014`. A usage limit that is exceeded returns 422 `TED-0030` with `fields.limit` naming which one (`PER_TRANSACTION`, `DAILY`, or `MONTHLY`). Decide by `fields.limit`, never by the text of `detail`. **Retry.** On a timeout or a network error, send the same request again with the same `X-Idempotency`, at any time. Within `X-TTL`, the original response comes back, byte for byte. After it, the response is `201` with `X-Idempotency-Replayed: true` and the transfer in its current state (for example, already `SETTLED`), with no new hold, debit, or send to the STR. This replay answers only if the request still passes validation. A refusal on a retry with a used key does not show that nothing was created: retry the same key later, or look up the transfer with `GET /v1/transfers` filtered by `client_reference` (the `clientReference` you sent), or by `account_id` and a `start_date`/`end_date` range (UTC) that covers the first attempt. Do not use a new key. The `metadata` is part of the request: the same key with another request, also with only another `metadata`, returns 422 `TED-0012`, before or after `X-TTL`. operationId: createTransfer x-mint: href: /pt/reference/interfaces/ted-lerian/send-a-ted parameters: - description: "Identifier (UUID) of the customer account in your own institution that starts the operation: the debited account in a send request or a quote. It goes in the header, never in the body. The account must belong to the organization that the token resolves. A missing or malformed value returns 400 `TED-0008`; an account from another organization returns 403 `TED-0009`." in: header name: X-Account-Id required: true schema: format: uuid type: string - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: internal: summary: Internal transfer (recipient in the institution's own ISPB) value: amount: "250.00" description: Transfer between accounts purposeCode: "00010" recipient: agency: "0001" bankAccount: "0007654321" bankAccountType: CACC bankId: "12345678" document: "12345678909" name: Maria da Silva ted: summary: TED to another institution (bank by COMPE) value: amount: "1500.00" clientReference: PED-2026-000123 description: Supplier payment metadata: channel: mobile orderId: PED-2026-000123 purposeCode: "00010" recipient: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankCode: "001" document: "12345678909" name: Maria da Silva schema: $ref: "#/components/schemas/CreateTransferRequestBody" required: true responses: "201": content: application/json: example: amount: "1500.00" clientReference: PED-2026-000123 createdAt: "2026-10-22T13:05:12Z" description: Supplier payment feeAmount: "3.25" metadata: channel: mobile orderId: PED-2026-000123 nuop: "87654321202610220000123" purposeCode: "00010" railOperationId: 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b recipient: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankCode: "001" bankId: "87654321" document: "12345678909" name: Maria da Silva reservedAt: "2026-10-22T13:05:13Z" sender: accountId: 0a2f4c6e-8b1d-4e3f-9a5b-7c9d1e3f5a7b agency: "0001" bankAccount: "0001111222" bankAccountType: CACC bankId: "12345678" document: "98765432100" name: João Pereira status: SUBMITTED submittedAt: "2026-10-22T13:05:14Z" totalAmount: "1503.25" transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b type: TED updatedAt: "2026-10-22T13:05:14Z" schema: $ref: "#/components/schemas/TransferResponse" description: "Transfer recorded. Read `status`: `SUBMITTED` (TED accepted by the rail; settlement through the STR is asynchronous), `SETTLED` (internal transfer settled), `REJECTED` (synchronous refusal from the ledger or the rail; see `rejection`), `AWAITING_RECONCILIATION` (TED) or `CREATED` (internal transfer): undetermined outcome; automatic reconciliation resolves it. If `X-Idempotency-Replayed: true`, this is the replay of an earlier transfer creation." headers: X-Idempotency-Replayed: description: "`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state." schema: type: boolean X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`), `X-Account-Id` missing/malformed (`TED-0008`), or `X-Idempotency` missing/in the wrong format (`TED-0011`). Nothing was created. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`); or the account in `X-Account-Id` does not belong to the organization (`TED-0009`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Holder of the source account not found in the registry (`TED-0010`). Nothing was created. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Materially identical request within the duplicate protection window (`TED-0014`; query the existing transfer), or a request with the same `X-Idempotency` is still processing (`TED-0013`; retry after `Retry-After`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Refused before any effect, so this request created nothing. Invalid fields, purpose code (unknown, or not in force on the date of the request, in the BACEN FinlddCli Domain Dictionary), bank, or document, including the check digits of the recipient's CPF or CNPJ (`TED-0002` to `TED-0007`); internal recipient not found (`TED-1021`); outside the window or non-business day (`TED-0020`/`TED-0021`); limit exceeded (`TED-0030`; `fields.limit` names which one: `PER_TRANSACTION`, `DAILY`, or `MONTHLY`); idempotency key already used with another request (`TED-0012`). With `TED-0012`, a transfer can already exist for this key, so look it up with `GET /v1/transfers` before you use a new key." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Unexpected failure (`TED-9000`). The transfer can already exist: look for it with `GET /v1/transfers` (for example, by `client_reference`) before you send it again. If it continues, contact support and give the `X-Request-Id` of the response." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Window cannot be determined (`TED-0022`; if the year of the date has no holiday calendar, load it with `PUT /v1/policy/holidays`), fee estimate (`TED-0040`) or registry (`TED-1020`) unavailable, or institution without configuration (`TED-0080`). For `TED-0080`, the transfer can already exist: look for it with `GET /v1/transfers` before you send it again." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Send a TED (or internal transfer) tags: - Transfers /v1/transfers/fee-quotes: post: description: |- Estimates the fee and the total that the transfer creation of this request would hold now. The quote has no effect (it does not hold balance or limit). Send the same fields as the transfer creation and `X-Account-Id` with the source account. The response tells you the path (`type` = `TED` or `INTERNAL`) and, if the window is closed, when it opens again (`nextWindowOpensAt`). The quote reflects the policy at the time of the query; the transfer creation estimates again. Does not require `X-Idempotency`. **With `fee.package_id` empty and the Midaz grants below in place, the quoted fee is the charged fee, except for a sender with an active account plan.** The fee comes from the fee packages of the institution's ledger (Midaz). With the `fee.package_id` runtime setting empty (the default and the recommended setting), the quote selects the package exactly as the posting of the transfer creation will, for `TED` and `INTERNAL`: among the enabled fee packages of the ledger, it keeps those with no route, with no segment or the segment of the source account, with no `metadataSelector` or one that matches the tags of the posting (`tedOperation` = `ted_sent` or `ted_internal`, and `tedPurposeCode`), and whose amount range (bounds included) contains `amount`; the most specific one wins. When no package applies, `feeAmount` is `0` and the posting charges no fee either. With `fee.package_id` set, the quote prices that package and the guarantee above no longer holds: `TED` and `INTERNAL` are priced with the same package, and a disabled package is still priced. The plugin's Midaz credential needs the `packages:get` and `estimates:post` permissions for the quote to match the charge. Without them, and with `fee.package_id` empty, `feeAmount` is `0`. If the fee cannot be determined, the quote answers 503 `TED-0040` with no effect, and the transfer creation refuses the same way. The `detail` gives the reason in fixed text: | Reason | `detail` | |---|---| | The package set in `fee.package_id` does not exist in the ledger | `The fee package configured in fee.package_id does not exist in the ledger. Fix fee.package_id or clear it so the fee package is selected automatically.` | | More than one equally specific package applies | `More than one fee package of the ledger matches this transfer, so its fee cannot be determined. Narrow the fee packages so that exactly one applies.` | | Ledger unavailable or unusable answer | `The transfer fee could not be quoted, so nothing was reserved or posted. Retry later.` | operationId: quoteTransferFee x-mint: href: /pt/reference/interfaces/ted-lerian/quote-a-transfer-fee parameters: - description: "Identifier (UUID) of the customer account in your own institution that starts the operation: the debited account in a send request or a quote. It goes in the header, never in the body. The account must belong to the organization that the token resolves. A missing or malformed value returns 400 `TED-0008`; an account from another organization returns 403 `TED-0009`." in: header name: X-Account-Id required: true schema: format: uuid type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: ted: summary: Quote for a TED value: amount: "1500.00" purposeCode: "00010" recipient: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankCode: "001" document: "12345678909" name: Maria da Silva schema: $ref: "#/components/schemas/FeeQuoteRequest" required: true responses: "200": content: application/json: example: amount: "1500.00" feeAmount: "3.25" feePackageId: 7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e quotedAt: "2026-10-22T13:05:12Z" totalAmount: "1503.25" type: TED windowOpen: true schema: $ref: "#/components/schemas/FeeQuote" description: "Fee estimate: the `feeAmount` and `totalAmount` that the transfer creation of this request would hold now, priced from the same ledger fee package that the posting will charge (`feeAmount` is `0` when no package applies). That parity holds with `fee.package_id` empty, the Midaz grants `packages:get` and `estimates:post` in place, and a sender with no active account plan (Midaz charges an account-plan sender from the plan, and the quote does not read the plan): with `fee.package_id` set, the quote prices that package, which can differ from the one the posting charges; without the grants, `feeAmount` is `0` even if the posting charges a fee. No financial effect." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Account-Id` missing/malformed (`TED-0008`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`); or the account in `X-Account-Id` does not belong to the organization (`TED-0009`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Invalid fields or amount (`TED-0002`), purpose code unknown, or not in force on the date of the request, in the BACEN FinlddCli Domain Dictionary (`TED-0003`), purpose code `99999` (the quote takes no description, `TED-0004`), recipient bank missing or duplicated (`TED-0005`), invalid recipient document, including the check digits of the CPF or CNPJ (`TED-0007`, as on the send), or bank unknown to the STR (`TED-0006`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No effect. Fee cannot be determined (`TED-0040`; the `detail` gives the reason: the package in `fee.package_id` does not exist in the ledger, more than one package applies, or the ledger is unavailable), account registry unavailable (`TED-1020`), or institution configuration missing (`TED-0080`). Fix the fee packages or retry later." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Quote the fee and total of a TED with no financial effect tags: - Transfers /v1/transfers/{transferId}: get: description: |- Returns the current state of an outgoing or internal transfer: `status`, amounts (`amount`, `feeAmount`, `totalAmount`), parties, SPB identifiers (`nuop`, `numCtrlStr`), and the time of each step (`reservedAt`, `submittedAt`, `settledAt`). This is the simplest way to track a TED you just sent: poll until `status` reaches a terminal state (`SETTLED`, `REJECTED`, or `CANCELLED`). If it reaches `EXHAUSTED`, stop polling and contact operations: only a manual unblock (`POST .../unblock`) takes the transfer out of that status. In `REJECTED`, `rejection` tells who refused the transfer (`source`) and why (`code`, `reason`). After `SETTLED`, a return made by the recipient institution appears in `returned`, and the `status` does not change. You can see only the transfers of your institution. An identifier from another institution returns 404, as if it did not exist. For the full sequence of transitions, use `GET /v1/transfers/{transferId}/timeline`. operationId: getTransfer x-mint: href: /pt/reference/interfaces/ted-lerian/get-a-transfer parameters: - description: Transfer identifier in: path name: transferId required: true schema: description: Transfer identifier format: uuid type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: amount: "1500.00" clientReference: PED-2026-000123 createdAt: "2026-10-22T13:05:12Z" description: Supplier payment feeAmount: "3.25" metadata: channel: mobile orderId: PED-2026-000123 numCtrlStr: STR20261022000000123 nuop: "87654321202610220000123" purposeCode: "00010" railOperationId: 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b recipient: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankCode: "001" bankId: "87654321" document: "12345678909" name: Maria da Silva reservedAt: "2026-10-22T13:05:13Z" sender: accountId: 0a2f4c6e-8b1d-4e3f-9a5b-7c9d1e3f5a7b agency: "0001" bankAccount: "0001111222" bankAccountType: CACC bankId: "12345678" document: "98765432100" name: João Pereira settledAt: "2026-10-22T13:05:41Z" status: SETTLED submittedAt: "2026-10-22T13:05:14Z" totalAmount: "1503.25" transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b type: TED updatedAt: "2026-10-22T13:05:41Z" schema: $ref: "#/components/schemas/TransferResponse" description: Transfer found, in its current state. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Organization scope not configured for this installation (`TED-0080`): the read fails closed until the configuration exists." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Get a transfer tags: - Transfers /v1/transfers/{transferId}/cancel: post: description: |- Cancels a transfer that is not yet sent to the STR, or asks the STR to cancel a pending entry. | Current state | Result | |---|---| | `CREATED`, `RESERVED` | Cancels immediately and releases the hold: 200, `status=CANCELLED` | | `PENDING_STR` | Asks the STR to cancel: 202 (503 `TED-1012` if the rail of this institution does not cancel a pending entry, see below) | | `CANCELLED` | 200, with no new effect | | `SUBMITTED`, `SETTLED`, `REJECTED` | Not cancelable: 409 `TED-0061`. A settled TED comes back only through a return from the recipient institution | | `AWAITING_RECONCILIATION`, `EXHAUSTED` | Not cancelable: 409 `TED-0061`. Operations use `POST .../unblock` with evidence | `TED-1012` is a fixed refusal, not a failure: the rail of this institution does not cancel a pending entry at the STR. A retry gets the same answer, and nothing went to the STR. The TED follows its normal STR outcome: track it with `GET /v1/transfers/{transferId}`. The body is optional (`reason`). `X-Idempotency` is required; `X-Idempotency-Replayed: true` indicates a replay. operationId: cancelTransfer x-mint: href: /pt/reference/interfaces/ted-lerian/cancel-a-transfer parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: Transfer identifier in: path name: transferId required: true schema: description: Transfer identifier format: uuid type: string - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: default: summary: Cancellation with a reason value: reason: Requested by the customer before sending schema: $ref: "#/components/schemas/CancelTransferRequest" responses: "200": content: application/json: example: amount: "1500.00" clientReference: PED-2026-000123 createdAt: "2026-10-22T13:05:12Z" description: Supplier payment feeAmount: "3.25" metadata: channel: mobile orderId: PED-2026-000123 purposeCode: "00010" recipient: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankCode: "001" bankId: "87654321" document: "12345678909" name: Maria da Silva reservedAt: "2026-10-22T13:05:13Z" sender: accountId: 0a2f4c6e-8b1d-4e3f-9a5b-7c9d1e3f5a7b agency: "0001" bankAccount: "0001111222" bankAccountType: CACC bankId: "12345678" document: "98765432100" name: João Pereira status: CANCELLED totalAmount: "1503.25" transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b type: TED updatedAt: "2026-10-22T13:06:02Z" schema: $ref: "#/components/schemas/TransferResponse" description: "Transfer cancelled and hold released (`status=CANCELLED`). If `X-Idempotency-Replayed: true`, or if it was already cancelled, no new effect occurred." headers: X-Idempotency-Replayed: description: "`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state." schema: type: boolean X-Request-Id: $ref: "#/components/headers/XRequestId" "202": content: application/json: schema: $ref: "#/components/schemas/TransferResponse" description: Cancellation of the pending entry requested from the STR. Track it by query or event. headers: X-Idempotency-Replayed: description: "`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state." schema: type: boolean X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Cannot be cancelled in the current status (`TED-0061`): already sent, settled, rejected, or awaiting reconciliation/exhausted (use unblock with evidence); or a request with the same `X-Idempotency` is still processing (`TED-0013`; retry after `Retry-After`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "A validation or business rule failed: invalid fields (`TED-0002`, see `errors`), or `X-Idempotency` reused with a different body (`TED-0012`). Refusals specific to the operation are in its description." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The STR connector of this institution does not cancel a pending entry (`TED-1012`: a fixed refusal, so a retry does not help; the transfer follows its STR outcome). Or its answer is unknown (`TED-1010`): the cancellation request stays recorded, so retry with the same `X-Idempotency` and `reason`. Or the institution configuration is missing (`TED-0080`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Cancel a transfer (before sending) or a pending entry in the STR tags: - Transfers /v1/transfers/{transferId}/timeline: get: description: |- Returns the timeline of a transfer: one entry for each status transition, in chronological order. Each entry has the instant, the source and target states, who caused the transition (`origin`: API, rail, STR, ledger, worker, operator, or system), the official reason, and the related identifier (for example, the `nuop` assigned at submission). When the transition has a milestone on the transfer (`reservedAt`, `submittedAt`, `settledAt`, and the others), the instant of the entry is that milestone, unless it would fall before the previous entry. In that case, the entry shows when TED Lerian recorded the transition, and the milestone stays on the transfer. This happens, for example, on a TED settled by reconciliation, whose `settledAt` is the instant the rail reported. So no entry shows before the entries that came before it. Use it for audit, customer support ("what happened to TED X?"), and to debug integrations. For the current state, `GET /v1/transfers/{transferId}` is enough. operationId: getTransferTimeline x-mint: href: /pt/reference/interfaces/ted-lerian/get-a-transfer-timeline parameters: - description: Transfer identifier in: path name: transferId required: true schema: description: Transfer identifier format: uuid type: string - $ref: "#/components/parameters/XRequestId" responses: "200": content: application/json: example: entries: - at: "2026-10-22T13:05:12Z" origin: API toStatus: CREATED - at: "2026-10-22T13:05:13Z" fromStatus: CREATED origin: LEDGER toStatus: RESERVED - at: "2026-10-22T13:05:14Z" fromStatus: RESERVED origin: RAIL reference: "87654321202610220000123" toStatus: SUBMITTED - at: "2026-10-22T13:05:41Z" fromStatus: SUBMITTED origin: STR reference: STR20261022000000123 toStatus: SETTLED resourceId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b schema: $ref: "#/components/schemas/TimelineDTO" description: Timeline in chronological order, from creation to the current state. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Parameter outside the declared format (for example, a `date` that is not YYYY-MM-DD): a framework validation refusal (`TED-0002`, see `errors`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Organization scope not configured for this installation (`TED-0080`): the read fails closed until the configuration exists." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Timeline of the transfer transitions tags: - Transfers /v1/transfers/{transferId}/unblock: post: description: |- **Operator** action to close a transfer in `AWAITING_RECONCILIATION` or `EXHAUSTED` (in another state, 409 `TED-0060`). You give the outcome that you verified in the STR: `outcome=SETTLED` confirms the hold; `outcome=REJECTED` releases it and requires `evidence.rejectionCode` (422 `TED-0065` if it is missing). `evidence` gives the type and the reference of the proof (STR control identifier, statement, or pending-entry query). The service audits the action with the operator identity; `X-Idempotency` is required. operationId: unblockTransfer x-mint: href: /pt/reference/interfaces/ted-lerian/unblock-a-transfer parameters: - description: "Replay window of the idempotency key, in seconds. Default 300 (5 minutes) when missing or invalid; values outside 30 s to 7 days are adjusted to these limits. Only the value of the FIRST request for a key counts. A change to X-TTL on retries has no effect. Within the window, the original response is replayed byte for byte." in: header name: X-TTL schema: minimum: 1 type: integer - description: Transfer identifier in: path name: transferId required: true schema: description: Transfer identifier format: uuid type: string - description: "Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with `X-Idempotency-Replayed: true` and no new effect. Same key + different body responds 422 `TED-0012`. Same key still in processing responds 409 `TED-0013` (retry after `Retry-After`). Missing or in the wrong format: 400 `TED-0011`." in: header name: X-Idempotency required: true schema: type: string - $ref: "#/components/parameters/XRequestId" requestBody: content: application/json: examples: rejected: summary: Rejected, proven by the STR statement value: evidence: kind: STR_STATEMENT reference: EXTRATO-2026-10-22-0007 rejectionCode: '5' justification: The entry appears as rejected (SitLancSTR 5) in the STR statement. outcome: REJECTED settled: summary: Settled, proven by the STR control identifier value: evidence: kind: NUM_CTRL_STR reference: STR20261022000000123 settledAt: "2026-10-22T13:05:41Z" justification: Checked against the STR statement by the operator on duty. outcome: SETTLED schema: $ref: "#/components/schemas/UnblockTransferRequestBody" required: true responses: "200": content: application/json: example: amount: "1500.00" clientReference: PED-2026-000123 createdAt: "2026-10-22T13:05:12Z" description: Supplier payment feeAmount: "3.25" metadata: channel: mobile orderId: PED-2026-000123 numCtrlStr: STR20261022000000123 nuop: "87654321202610220000123" purposeCode: "00010" railOperationId: 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b recipient: agency: "1234" bankAccount: "0001234567" bankAccountType: CACC bankCode: "001" bankId: "87654321" document: "12345678909" name: Maria da Silva reservedAt: "2026-10-22T13:05:13Z" sender: accountId: 0a2f4c6e-8b1d-4e3f-9a5b-7c9d1e3f5a7b agency: "0001" bankAccount: "0001111222" bankAccountType: CACC bankId: "12345678" document: "98765432100" name: João Pereira settledAt: "2026-10-22T13:05:41Z" status: SETTLED submittedAt: "2026-10-22T13:05:14Z" totalAmount: "1503.25" transferId: 6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b type: TED updatedAt: "2026-10-22T15:02:10Z" schema: $ref: "#/components/schemas/TransferResponse" description: "Outcome applied: the transfer returns in `SETTLED`, or in `REJECTED` with `rejection.source=OPERATOR`. If `X-Idempotency-Replayed: true`, this is the replay of a previous unblock." headers: X-Idempotency-Replayed: description: "`true` when this response is the replay of a previous request with the same `X-Idempotency` (no new effect occurred). Absent when the request produced a new effect. Always check this header: the HTTP status and the body shape are the same in both cases. Within `X-TTL`, the replayed body is the original response, byte for byte; on `POST /v1/transfers`, a replay after `X-TTL` returns the transfer in its current state." schema: type: boolean X-Request-Id: $ref: "#/components/headers/XRequestId" "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Malformed JSON (`TED-0001`) or `X-Idempotency` missing/in the wrong format (`TED-0011`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not authenticated: token missing, invalid, or expired (`TED-0070`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "No permission: the token's role does not authorize this action (`TED-0071`)." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Resource does not exist in this institution, or the identifier is not in UUID format (`TED-0010`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Transfer not in `AWAITING_RECONCILIATION`/`EXHAUSTED` (`TED-0060`), or a request with the same `X-Idempotency` is still processing (`TED-0013`; retry after `Retry-After`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Missing or invalid evidence, or `rejectionCode` missing with `outcome=REJECTED` (`TED-0065`); invalid fields (`TED-0002`); idempotency key reused with a different body (`TED-0012`). headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unexpected failure (`TED-9000`). Retry with the SAME `X-Idempotency`. If it continues, contact support and give the `X-Request-Id` of the response. headers: X-Request-Id: $ref: "#/components/headers/XRequestId" "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The audit trail cannot record the decision (`TED-9002`): the operator decision is refused before any effect, and nothing changed. Retry with the same `X-Idempotency` once the audit trail is back. Or the institution configuration is missing (`TED-0080`): nothing was done." headers: X-Request-Id: $ref: "#/components/headers/XRequestId" summary: Unblock a transfer in reconciliation with STR evidence (operator) tags: - Reconciliation security: - BearerAuth: [] servers: - url: https://api.example.com description: Replace the example host with the URL provided during environment onboarding. tags: - description: "Outgoing TEDs and internal transfers: fee quote, creation, query, timeline, and cancellation. Every integration starts here." name: Transfers - description: "Incoming TEDs from other institutions: query, timeline, and operator actions (full return and manual review resolution)." name: Incoming Transfers - description: STR participant list, to resolve COMPE code ↔ ISPB and validate the destination bank before you create a transfer. name: Participants - description: "Back office: operations queue, inconsistency findings between the ledger and the STR, reviews of rail facts, held returns, and manual unblock with evidence." name: Reconciliation - description: "Operations dashboard: daily aggregates, regulatory deadlines (30/60/60 min), and the closing balance that the STR reported." name: Operations - description: "Institution configuration (editor): operating window and cut-off, usage limits, holiday calendar, and ISPB → organization bindings." name: Policy x-tagGroups: - name: Integration tags: - Transfers - Incoming Transfers - Participants - name: Back office and operations tags: - Reconciliation - Operations - Policy