> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Componer y enviar un mensaje STR curado > Superficie de composición de mensajes curada, restringida por catálogo, enrutada por maker-checker y por tipo. El capabilityId elegido debe estar en la lista de permitidos de composición (STR0004/STR0005/STR0006/STR0007/STR0008/STR0053), resolverse en el catálogo y ser PUBLICLY_SUBMITTABLE; de lo contrario la solicitud se rechaza con SPB-0003 (HTTP 400). El mensaje se construye a través del pipeline de composición compartido y hereda la compuerta de emisión de alçada: un monto por encima de su banda queda retenido en PENDING_APPROVAL (visible en GET /v1/str/emission-approvals, con emissionApprovalId establecido) y se despacha al alcanzar el quórum; por debajo de la banda queda SUBMITTED. Idempotente: reenviar la misma clave X-Idempotency devuelve la misma emisión. El monto declarado se reenvía de forma literal; no se suma ninguna posición. ## OpenAPI ````yaml es/openapi/v3-current/spb.yaml post /v1/str/messages/compose openapi: 3.1.0 info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: >- Interfaz OpenAPI 3.1 de Lerian SPB, la integración directa entre la institución y el Sistema de Pagos Brasileño (SPB) sobre la Red del Sistema Financiero Nacional (RSFN). Cubre el Sistema de Transferencia de Reservas (STR): registro de mensajes y catálogo de capacidades, ciclo de vida de las operaciones (transferencias bancarias, repasses IBS, transferencias de liquidez, devoluciones y cancelaciones), consultas de cuenta de reservas y de horarios, gobernanza de alçada, conciliación y entrega de eventos. license: name: Lerian Studio General License title: Lerian SPB API version: 1.0.0 servers: - url: https://spb.sandbox.lerian.net security: [] tags: - description: >- Rastros inmutables de registros de auditoría para operaciones STR y eventos de ciclo de vida. name: Audit - description: >- Catálogo de capacidades STR que describe los tipos de mensaje admitidos y sus restricciones. name: Capabilities - description: >- Inventario de certificados ICP-Brasil con rotación y activación recargables en caliente. name: Certificates - description: >- Cola de aprobación maker-checker para emisiones retenidas por encima de su banda de alçada: listar pendientes, firmar (aprobar) y denegar. name: EmissionApprovals - description: >- Registros de entrega de eventos por webhook con control de reintentos para despachos fallidos. name: EventDeliveries - description: >- Catálogo de eventos de operación que enumera los tipos de evento de dominio emitidos. name: Events - description: >- Registro de avisos entrantes de la familia GEN (GEN0001 eco de conectividad, GEN0004 error de transmisión, GEN0005 aviso administrativo). name: GenNotices - description: >- Gobernanza de alçada del SPB: la tabla de bandas de valor y los requisitos de firma por tipo de mensaje, recargados en caliente en tiempo de ejecución. name: Governance - description: >- Estado crudo de los mensajes STR: listar los mensajes y leer un mensaje individual por NUOp. name: Messages - description: Resúmenes y métricas operativas agregadas de las operaciones STR. name: OperationalIntelligence - description: >- Ciclo de vida de las operaciones STR para transferencias bancarias y repasses IBS, incluyendo devoluciones y cancelaciones. name: Operations - description: >- Estado de disponibilidad del servicio que abarca las autopruebas de arranque y la salud de las dependencias. name: Readiness - description: >- Casos de conciliación y las acciones que resuelven las discrepancias de operación. name: Reconciliation - description: >- Suite de reportes STR: reportes agregados síncronos por rango de fechas (movimiento financiero, transacciones rechazadas, volumetria) sobre el propio registro de transmisión de Lerian SPB. name: Reports - description: >- Consultas de saldo de cuenta de reservas STR0013 y de extrato STR0014 (modo mensaje) y sus resultados asíncronos. name: ReserveQueries - description: >- Lista de responsáveis del participante GEN0019: actualizaciones de reemplazo total anunciadas a BACEN. name: Responsibles - description: >- Programación de ventanas de operación del STR que rige cuándo pueden enviarse las operaciones. name: Schedule - description: >- Consultas de horarios STR0001 de parte única (consulta de horários do STR) y sus resultados de grilla STR0001R1 asíncronos. name: ScheduleQueries - description: >- Ajustes de configuración del SPB en tiempo de ejecución para la integración STR. name: Settings - description: Registro y gestión de endpoints de webhook para la entrega de eventos. name: Webhooks - description: >- Flujo (orden obligatorio): certificado → disponibilidad → prueba-de-conectividad → envío. Activa un certificado, confirma que el rail reporta listo, pasa una prueba de conectividad y luego envía una operación. Cada paso es su propio recurso; no debes intentar un envío antes de que la disponibilidad pase. name: onboarding - description: >- Flujo (orden obligatorio): operación padre SETTLED → devolución/cancelación. Una devolución o cancelación es un sub-recurso de una operación padre liquidada; el segmento de ruta {operationId}/{endToEndID} impone el padre estructuralmente. name: lifecycle paths: /v1/str/messages/compose: post: tags: - Messages summary: Componer y enviar un mensaje STR curado description: >- Superficie de composición de mensajes curada, restringida por catálogo, enrutada por maker-checker y por tipo. El capabilityId elegido debe estar en la lista de permitidos de composición (STR0004/STR0005/STR0006/STR0007/STR0008/STR0053), resolverse en el catálogo y ser PUBLICLY_SUBMITTABLE; de lo contrario la solicitud se rechaza con SPB-0003 (HTTP 400). El mensaje se construye a través del pipeline de composición compartido y hereda la compuerta de emisión de alçada: un monto por encima de su banda queda retenido en PENDING_APPROVAL (visible en GET /v1/str/emission-approvals, con emissionApprovalId establecido) y se despacha al alcanzar el quórum; por debajo de la banda queda SUBMITTED. Idempotente: reenviar la misma clave X-Idempotency devuelve la misma emisión. El monto declarado se reenvía de forma literal; no se suma ninguna posición. operationId: composeStrMessage parameters: - description: >- Bearer JWT token (the maker subject is derived from it for the alçada gate). in: header name: Authorization schema: description: >- Bearer JWT token (the maker subject is derived from it for the alçada gate). type: string - description: Idempotency key (canonical; legacy alias X-Idempotency-Key). in: header name: X-Idempotency schema: description: Idempotency key (canonical; legacy alias X-Idempotency-Key). type: string - description: Idempotency key (legacy alias). in: header name: X-Idempotency-Key schema: description: Idempotency key (legacy alias). type: string - description: Idempotency key TTL in seconds. in: header name: X-TTL schema: description: Idempotency key TTL in seconds. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ComposeMessageRequest' responses: '202': content: application/json: schema: $ref: '#/components/schemas/ComposeMessageResponse' description: Accepted default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: ComposeMessageRequest: additionalProperties: false properties: amount: description: >- Transfer amount as a decimal string in BRL, minor-unit precision (two decimal places). Forwarded VERBATIM into the submit DTO and the alçada gate — Lerian SPB performs NO arithmetic on it. examples: - '150000.00' pattern: ^[0-9]+(\.[0-9]+)?$ type: string capabilityId: description: >- STR capability code to compose. Must resolve in the catalog, be PUBLICLY_SUBMITTABLE, and be in the compose allowlist (STR0004/STR0005/STR0006/STR0007/STR0008/STR0053). examples: - STR0008 type: string description: description: >- Optional free-text description; mandatory when purposeCode or finlddCli is 99999 (RSTR0034). Serialized into the STR Hist element. examples: - Wire transfer for invoice 2026-Q2-A47 type: string finlddCli: description: >- Optional client-level purpose code (5 digits) carried on STR0004/STR0008. When 99999 the description is required (RSTR0034). examples: - '00001' pattern: ^[0-9]{5}$ type: string metadata: additionalProperties: {} description: >- Opaque client-side metadata forwarded verbatim to the submit DTO (NOT sent to BACEN). Do not include sensitive fields. type: object purposeCode: description: >- BACEN STR purpose code (finalidade), exactly 5 digits. When 99999 (Outros) a description is mandatory (RSTR0034). examples: - '00001' pattern: ^[0-9]{5}$ type: string recipient: $ref: '#/components/schemas/ComposeParticipantAccount' description: Crediting (creditor) participant account receiving the transfer. sender: $ref: '#/components/schemas/ComposeParticipantAccount' description: Debiting (debtor) participant account originating the transfer. required: - capabilityId - sender - recipient - amount - purposeCode type: object ComposeMessageResponse: additionalProperties: false properties: controlNumber: description: >- 14-digit STR control number identifying the message on the SPB network. examples: - '20260621000001' type: string correlationId: description: >- Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. examples: - req-7a3f9c2e type: string emissionApprovalId: description: >- Set ONLY when the emission parked: the maker-checker queue id (equal to messageId). Poll GET /v1/str/emission-approvals to track it. Empty when SUBMITTED immediately. examples: - 6f2c8a1e-... type: string messageId: description: >- Internal outbound-message id assigned at persistence time; the key for the approval queue when parked. examples: - 6f2c8a1e-... type: string nuOp: description: >- 23-digit STR operation number stamped on the composed message (protocol correlation). examples: - '12345678202606210000001' type: string requiredSignatures: description: >- N-of-M distinct-actor quorum the parked emission must collect (the alçada band requirement). Omitted/0 when SUBMITTED immediately. examples: - 2 format: int64 type: integer status: description: >- Emission status: SUBMITTED (dispatched / liquidatable) or PENDING_APPROVAL (parked awaiting maker-checker quorum). examples: - PENDING_APPROVAL type: string required: - messageId - status - nuOp - controlNumber - correlationId type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 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 type: object ComposeParticipantAccount: additionalProperties: false properties: account: description: Optional traditional bank account number. examples: - '123456' type: string accountType: description: >- Optional account type: CC (checking/conta corrente) or PP (payment account/conta de pagamento). examples: - CC type: string branch: description: Optional bank branch (agência) number. examples: - '0001' type: string document: description: >- Holder document (CPF/CNPJ, digits only). Carried on the client codes STR0007/STR0008. examples: - '12345678901' type: string ispb: description: Participant ISPB, the 8-digit BACEN institution identifier. examples: - '12345678' maxLength: 8 minLength: 8 pattern: ^[0-9]{8}$ type: string name: description: Holder name. Carried on the client codes STR0007/STR0008. examples: - João da Silva type: string paymentAccount: description: >- Optional payment account identifier (conta de pagamento). Required when accountType is PP. examples: - '00000000123456' type: string required: - ispb type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````