> ## 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. # Crear una programación Pix > Crea una instrucción Pix programada de disparo único. La programación se crea con estado SCHEDULED y se despacha automáticamente como un cashout en su horario de disparo programado. **Notas:** - El destino se toma de una iniciación de pago existente referenciada por `initiationId`. Llama primero a `POST /v1/transfers/cashout/initiate` para obtener ese id. - Proporciona un encabezado `X-Idempotency` nuevo para garantizar una creación a lo sumo una vez por cuenta. - `scheduledFor` debe estar al menos 60 segundos en el futuro y dentro de la ventana de 180 días. - Al momento del disparo, la programación siempre se ejecuta como un cashout manual usando el destino capturado. - Las programaciones en estado terminal (EXECUTED, FAILED, CANCELLED) son inmutables. ## OpenAPI ````yaml es/openapi/v3-current/indirect-pix.yaml POST /v1/schedules openapi: 3.0.3 info: title: Plugin BR Pix Indirect - API completa description: | API completa para el sistema de pagos instantáneos Pix de Brasil, que incluye operaciones del diccionario de claves Pix, generación/decodificación de códigos QR, transacciones y límites transaccionales. version: 1.7.6 servers: - url: https://plugin-pix-indirect.api.lerian.net security: - bearerAuth: [] paths: /v1/schedules: post: tags: - Schedules API summary: Crear una programación Pix description: >- Crea una instrucción Pix programada de disparo único. La programación se crea con estado SCHEDULED y se despacha automáticamente como un cashout en su horario de disparo programado. **Notas:** - El destino se toma de una iniciación de pago existente referenciada por `initiationId`. Llama primero a `POST /v1/transfers/cashout/initiate` para obtener ese id. - Proporciona un encabezado `X-Idempotency` nuevo para garantizar una creación a lo sumo una vez por cuenta. - `scheduledFor` debe estar al menos 60 segundos en el futuro y dentro de la ventana de 180 días. - Al momento del disparo, la programación siempre se ejecuta como un cashout manual usando el destino capturado. - Las programaciones en estado terminal (EXECUTED, FAILED, CANCELLED) son inmutables. parameters: - $ref: '#/components/parameters/XAccountId' - name: X-Idempotency in: header description: >- Clave de idempotencia (se recomienda UUID v4); las repeticiones devuelven la respuesta 201 en caché. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateScheduleInput' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ScheduleOutput' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' security: - bearerAuth: [] components: parameters: XAccountId: name: X-Account-Id in: header description: Identificador único de la cuenta del Ledger de Midaz (formato UUID). required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string schemas: CreateScheduleInput: properties: amount: description: >- Amount es el monto de la transferencia en BRL con 2 decimales (p. ej. "100.50"). El formato y los límites se validan cuando se dispara la programación. example: '100.50' type: string description: description: >- Description es el mensaje de transferencia opcional legible para humanos: opcional, máximo 140 caracteres; se rechaza contenido HTML o de scripts. Opcional a nivel de Pix / BACEN (informacoesEntreUsuarios). example: Recurring charge installment 03/12 maxLength: 140 type: string endToEndId: description: >- EndToEndID es el identificador end-to-end de BACEN opcional, generado por quien llama, para el Pix programado. No está ligado a un encabezado ni es obligatorio, por lo que los clientes HTTP genéricos lo omiten. Los clientes recurrentes (Pix Automático) que generan por adelantado el id end-to-end del cashout lo proporcionan para que el disparo programado reutilice el mismo identificador. Su formato se valida cuando se procesa el pago. example: E1234567820260815060012345678901 type: string initiationId: description: >- InitiationID ancla la programación a una iniciación de pago existente que ya contiene la instantánea del destino validada por DICT. La programación copia los campos de destino de esa iniciación y guarda la referencia como ancla de auditoría (nunca se reutiliza al momento del disparo). Debe existir una iniciación antes de crear la programación. example: 550e8400-e29b-41d4-a716-446655440010 type: string maxAttempts: description: >- MaxAttempts limita la cantidad de intentos de disparo permitidos para esta programación. El pagador de Pix Automático usa 2 (primer intento a las 06:00 BRT, reintento por INSUFFICIENT_FUNDS a las 18:00 BRT). Cero u omitido recae en el valor predeterminado del servicio. example: 2 maximum: 2 minimum: 1 type: integer recurrenceId: description: >- RecurrenceID es un ancla de correlación genérica que agrupa varias programaciones creadas por el mismo flujo de origen (pago recurrente, suscripción, plan de cuotas, ciclo de facturación, etc.). Opcional. La capa de programación NO interpreta este valor: es metadato opaco que se refleja en GET / LIST y en los webhooks salientes schedule.* para que el consumidor de origen pueda reagrupar. Nil para programaciones puntuales sin grupo padre. example: 01988a7c-1234-7abc-8def-111122223333 type: string scheduledFor: description: >- ScheduledFor es la fecha de disparo en horario de reloj, en ISO 8601 con zona horaria. El momento de ejecución real se resuelve a partir de este valor más la hora de ejecución predeterminada del servicio (BRT). Los clientes recurrentes deben ajustarlo a >= D-1 de la fecha de vencimiento. example: '2026-08-15T00:00:00Z' format: date-time type: string required: - amount - initiationId - scheduledFor type: object ScheduleOutput: properties: accountId: description: >- AccountID refleja el AccountID de entrada para correlación de auditoría / logs. example: 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string amount: description: Amount es el monto en BRL con 2 decimales. example: '100.50' type: string attemptCount: description: >- AttemptCount es la cantidad de intentos de disparo realizados hasta ahora. example: 0 type: integer attempts: description: >- Attempts es la lista cronológica de intentos de disparo previos fallidos. El intento exitoso no se incluye aquí; queda registrado en la propia programación mediante su TransferID y EndToEndID. Arreglo vacío cuando no se registró ningún fallo. items: $ref: '#/components/schemas/ScheduleAttemptOutput' type: array cancelledAt: description: >- CancelledAt es el momento en que la programación llegó a CANCELLED. Ausente para filas que no están en CANCELLED. example: '2026-05-19T09:15:33Z' format: date-time type: string createdAt: description: CreatedAt es la marca de tiempo de persistencia (ISO 8601 UTC). example: '2026-05-26T12:30:00Z' format: date-time type: string description: description: >- Description es el mensaje de transferencia opcional legible para humanos. example: Recurring charge installment 03/12 type: string destination: allOf: - $ref: '#/components/schemas/ScheduleDestination' description: >- Destination es la instantánea del destino capturada en la programación. endToEndId: description: >- EndToEndID es el identificador end-to-end de BACEN de la transferencia liquidada (resuelto mediante TransferID). Ausente para estados que no son EXECUTED. example: E1234567820260815060012345678901 type: string executedAt: description: >- ExecutedAt es el momento en que la programación llegó a EXECUTED. Ausente para filas que no están en EXECUTED. example: '2026-08-15T06:00:04Z' format: date-time type: string failedAt: description: >- FailedAt es el momento en que la programación llegó al estado terminal FAILED. Ausente para filas que no están en FAILED. Simétrico con ExecutedAt / CancelledAt. example: '2026-08-15T06:00:04Z' format: date-time type: string failureMessage: description: >- FailureMessage es la descripción de fallo legible para humanos, en texto libre (saneada de PII). Ausente para filas que no están en FAILED. type: string failureReason: description: >- FailureReason categoriza un fallo terminal. Instantánea del FailureReason de la última entrada de Attempts[]. Ausente para filas que no están en FAILED. enum: - INSUFFICIENT_FUNDS - BTG_REJECTED - MIDAZ_REJECTED - VALIDATION_FAILED - SCHEDULE_STALE_TIMEOUT - SCHEDULE_RETRIES_EXHAUSTED example: INSUFFICIENT_FUNDS type: string firedAt: description: >- FiredAt es el instante de despacho más reciente. Ausente hasta que la programación empieza a procesarse (PROCESSING / EXECUTED / FAILED). example: '2026-08-15T06:00:04Z' format: date-time type: string id: description: >- ID es el identificador único de la programación (UUID v7, generado por la aplicación). example: 01989f9e-6508-79f8-9540-835be49fbd0d type: string initiationId: description: >- InitiationID es la iniciación de pago referenciada al momento de creación (ancla de auditoría). Nunca se reutiliza al momento del disparo; cada intento de disparo usa su propia iniciación, expuesta por intento como Attempts[].InitiationID. example: 550e8400-e29b-41d4-a716-446655440010 type: string initiationType: description: >- InitiationType registra cómo se capturó el destino (MANUAL, KEY, QR_CODE). enum: - MANUAL - KEY - QR_CODE example: MANUAL type: string maxAttempts: description: >- MaxAttempts es el tope de reintentos por fila aceptado al momento de creación. example: 2 type: integer recurrenceId: description: >- RecurrenceID refleja el ancla de la recurrencia padre cuando la programación se creó a partir de un flujo recurrente. Vacío para llamadas directas a POST /v1/schedules. example: 01988a7c-1234-7abc-8def-111122223333 type: string scheduledFor: description: >- ScheduledFor es el momento de disparo en horario de reloj (ISO 8601 UTC). example: '2026-08-15T09:00:00Z' format: date-time type: string status: description: >- Status es el estado del ciclo de vida de la programación. Siempre SCHEDULED al crear. Ciclo de vida: SCHEDULED -> PROCESSING -> EXECUTED | FAILED | CANCELLED. enum: - SCHEDULED - PROCESSING - EXECUTED - FAILED - CANCELLED example: SCHEDULED type: string transferId: description: >- TransferID es el identificador de la transferencia liquidada. Se completa solo en EXECUTED. example: c8d27e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f type: string updatedAt: description: >- UpdatedAt es la marca de tiempo de la última transición de estado (ISO 8601 UTC). example: '2026-05-26T12:30:00Z' format: date-time type: string type: object ErrorFormat: type: object description: El mensaje de error de la respuesta. required: - code - title - message properties: code: type: string description: Un identificador único y estable para el error. title: type: string description: Un breve resumen del problema. message: type: string description: Orientación detallada para resolver el error. ScheduleAttemptOutput: properties: attemptedAt: description: >- AttemptedAt es el instante de despacho de este intento (ISO 8601 UTC). example: '2026-08-15T06:00:02Z' format: date-time type: string endToEndId: description: >- EndToEndID es el identificador end-to-end de BACEN del mensaje SPI del intento. Presente junto con TransferID. example: E1234567820260815060011111111111 type: string failureMessage: description: FailureMessage es el detalle legible para humanos (saneado de PII). example: 'Midaz error: balance below required (06:00 BRT attempt)' type: string failureReason: description: FailureReason categoriza el fallo. enum: - INSUFFICIENT_FUNDS - BTG_REJECTED - MIDAZ_REJECTED - VALIDATION_FAILED - SCHEDULE_STALE_TIMEOUT example: INSUFFICIENT_FUNDS type: string initiationId: description: >- InitiationID es la iniciación de pago usada para este intento (creada al momento del disparo, no la iniciación del momento de creación). Ausente cuando el intento fue rechazado antes de registrarse una liquidación. example: a1111111-1111-4111-8111-111111111111 type: string transferId: description: >- TransferID es el identificador de la transferencia producida por el disparo fallido. Ausente cuando el cashout fue rechazado antes de registrarse una liquidación. example: f1a2b3c4-1111-4d5e-9f6a-7b8c9d0e1f23 type: string type: object ScheduleDestination: properties: account: allOf: - $ref: '#/components/schemas/ScheduleDestinationAccount' description: >- Account contiene agencia / número / ISPB del participante / tipo de cuenta. key: description: >- Key es la clave Pix asociada al destino al momento de la iniciación, cuando el usuario pagó mediante KEY o QR_CODE. Solo una instantánea; no se usa al momento del disparo. example: john.doe@example.com type: string owner: allOf: - $ref: '#/components/schemas/ScheduleDestinationOwner' description: >- Owner contiene el documento, el nombre y el nombre comercial opcional del titular de la cuenta de destino. type: object ScheduleDestinationAccount: properties: branch: description: >- Branch es el código de la agencia bancaria (normalmente 4 dígitos, con ceros a la izquierda). example: '0001' type: string number: description: Number es el número de cuenta en la institución de destino. example: '123456789' type: string participant: description: Participant es el ISPB de 8 dígitos de la institución de destino. example: '12345678' type: string type: description: 'Type es el tipo de cuenta: CACC, SVGS, TRAN, OTHR.' enum: - CACC - SVGS - TRAN - OTHR example: CACC type: string type: object ScheduleDestinationOwner: properties: document: description: Document es el CPF (11 dígitos) o CNPJ (14 dígitos) del titular. example: '12345678901' type: string name: description: >- Name es el nombre completo o la razón social del titular del destino. example: John Doe type: string tradeName: description: >- TradeName es el nombre comercial opcional del negocio (solo personas jurídicas). example: John's Business type: string type: object securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````