> ## 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.

# Preparar Payload de Firma de Transferencia

> Utilice este endpoint para congelar el payload canónico STR0008 de una transferencia TED OUT previamente iniciada y obtener los bytes exactos que deben ser firmados antes de llamar a Process Transfer. La respuesta incluye un `signingArtifactId` y un `transferId` reservado. El `transferId` reservado no se puede consultar hasta que Process Transfer tenga éxito.

Use el header `X-Idempotency` para deduplicación garantizada. Las llamadas repetidas con la misma clave reproducen la respuesta en caché.



## OpenAPI

````yaml es/openapi/v3-current/ted.yaml post /v1/transfers/signing/prepare
openapi: 3.0.3
info:
  title: API del Plugin de Transferencia Bancaria (TED)
  description: >-
    API completa para transferencias bancarias brasileñas (TED OUT, TED IN, P2P)
    a través de la plataforma Lerian, incluyendo iniciación de transferencias,
    procesamiento, seguimiento de estado y cancelación.
  version: 1.1.9
servers:
  - url: https://plugin-br-bank-transfer.sandbox.lerian.net
    description: Sandbox (marcador de posición — aún no disponible para acceso público)
security:
  - BearerAuth: []
tags:
  - name: Transfers API
    description: Endpoints para iniciar, procesar, rastrear y cancelar transferencias.
  - name: Webhooks
    description: >-
      Endpoints para registrar y gestionar suscripciones de webhooks con alcance
      al tenant para eventos de transferencia.
  - name: Webhook DLQ
    description: >-
      Endpoints para inspeccionar y reintentar mensajes de la dead-letter queue
      de webhooks.
paths:
  /v1/transfers/signing/prepare:
    post:
      tags:
        - Transfers API
      summary: Preparar Payload de Firma de Transferencia
      description: >-
        Utilice este endpoint para congelar el payload canónico STR0008 de una
        transferencia TED OUT previamente iniciada y obtener los bytes exactos
        que deben ser firmados antes de llamar a Process Transfer. La respuesta
        incluye un `signingArtifactId` y un `transferId` reservado. El
        `transferId` reservado no se puede consultar hasta que Process Transfer
        tenga éxito.


        Use el header `X-Idempotency` para deduplicación garantizada. Las
        llamadas repetidas con la misma clave reproducen la respuesta en caché.
      operationId: prepareSigning
      parameters:
        - $ref: '#/components/parameters/XOrganizationId'
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrepareSigningRequest'
            examples:
              prepare:
                summary: Preparar firma para una iniciación
                value:
                  initiationId: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b
      responses:
        '200':
          description: >-
            Indica que el payload canónico fue generado y está listo para ser
            firmado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrepareSigningResponse'
              examples:
                success:
                  summary: Payload firmable devuelto
                  value:
                    signingArtifactId: 019c96a0-bb10-7def-a1b2-3c4d5e6f7a8b
                    transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d
                    controlNumber: '202602010001'
                    algorithm: RSA_PKCS1_V15_SHA256
                    payload: <STR0008>...</STR0008>
                    payloadHash: >-
                      8f0c7f5c1c7b4d9f2f5c7d1a0d4c9a2b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f
                    expiresAt: '2026-02-02T15:30:00-03:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/InitiationNotFound'
        '409':
          $ref: '#/components/responses/AlreadyProcessed'
        '410':
          $ref: '#/components/responses/InitiationExpired'
        '422':
          $ref: '#/components/responses/SigningPayloadInvalid'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    XOrganizationId:
      name: X-Organization-Id
      in: header
      required: true
      description: >-
        Alcance de organización Midaz para la solicitud, utilizado para las
        llamadas posteriores a CRM, Fees y Midaz. Es obligatorio en las rutas de
        transferencia con alcance de organización en todos los modos de
        despliegue; un valor faltante o que no sea un UUID devuelve 400. Este no
        es el identificador del tenant — el tenantId se deriva del JWT bearer o
        del contexto autenticado, nunca de este header. Los workers en segundo
        plano (poller de TED IN, conciliación) no tienen header de solicitud y,
        en modo single-tenant, recurren a la variable de entorno
        `ORGANIZATION_ID` del despliegue.
      schema:
        type: string
        format: uuid
      example: 019c96a0-0a98-7287-9a31-786e0809c769
    XIdempotencyKey:
      name: X-Idempotency
      in: header
      required: true
      description: >-
        Clave de idempotencia requerida para reintentos seguros. Utilice un UUID
        v4 o un identificador de negocio único. Si se envía la misma clave
        nuevamente y la solicitud original ya fue procesada, se devuelve la
        respuesta almacenada en caché.


        Consulte [Reintentos e idempotencia](/es/reference/retries-idempotency)
        para más detalles.
      schema:
        type: string
        maxLength: 255
      example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b
  schemas:
    PrepareSigningRequest:
      type: object
      required:
        - initiationId
      properties:
        initiationId:
          type: string
          format: uuid
          description: El ID de iniciación devuelto por el endpoint Initiate Transfer.
          example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b
    PrepareSigningResponse:
      type: object
      required:
        - signingArtifactId
        - transferId
        - controlNumber
        - algorithm
        - payload
        - payloadHash
        - expiresAt
      properties:
        signingArtifactId:
          type: string
          format: uuid
          description: >-
            Identificador del artefacto de firma congelado. Pase este valor a
            Process Transfer junto con la firma.
          example: 019c96a0-bb10-7def-a1b2-3c4d5e6f7a8b
        transferId:
          type: string
          format: uuid
          description: >-
            El ID de transferencia reservado para el eventual TED OUT. No es
            consultable hasta que Process Transfer tenga éxito.
          example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d
        controlNumber:
          type: string
          maxLength: 20
          description: El número de control JD SPB reservado para esta transferencia.
          example: '202602010001'
        algorithm:
          type: string
          enum:
            - RSA_PKCS1_V15_SHA256
          description: >-
            El algoritmo de firma. Fijado por contrato JD SPB; cualquier otro
            valor es rechazado en Process Transfer.
          example: RSA_PKCS1_V15_SHA256
        payload:
          type: string
          description: El payload canónico STR0008, exactamente como será enviado a JD SPB.
          example: <STR0008>...</STR0008>
        payloadHash:
          type: string
          description: >-
            Digest SHA-256 codificado en hex del payload. Reenvíe este valor en
            Process Transfer para validación de integridad.
          example: 8f0c7f5c1c7b4d9f2f5c7d1a0d4c9a2b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f
        signableContent:
          type: string
          description: >-
            La extracción `ConteudoAssinado` para firmadores externos. Presente
            solo cuando un constructor de firma externo está configurado.
          example: <ConteudoAssinado>...</ConteudoAssinado>
        expiresAt:
          type: string
          format: date-time
          description: >-
            El momento en que el artefacto de firma expira. Process Transfer
            debe ser llamado antes de esta marca de tiempo.
          example: '2026-02-02T15:30:00-03:00'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - service
            - category
            - message
            - requestId
          properties:
            code:
              type: string
              description: >-
                El código de error estable. Los errores del plugin usan el
                formato `BTF-XXXX`; los rechazos de negocio/autenticación de JD
                SPB transmiten el código del proveedor sin modificar (p. ej.
                `AAC90`, `ACE95`, `DVE01`), y los fallos de JD a nivel de
                transporte muestran los marcadores sintéticos `TRANSPORT` o
                `JD_MISSING_CODE`. Haga la coincidencia sobre este valor en
                lugar del estado HTTP.
              example: BTF-0010
            service:
              type: string
              description: El servicio o dominio que produjo el error.
              example: plugin
            category:
              type: string
              description: >-
                Categoría de error legible por máquina utilizada para las
                decisiones de reintento.
              enum:
                - deterministic
                - transient
                - rate_limit
                - plugin
              example: deterministic
            message:
              type: string
              description: Un resumen del error legible por humanos.
              example: >-
                Transfers can only be initiated Monday-Friday between 06:30 and
                17:00 Brasília time
            requestId:
              type: string
              description: >-
                El ID de correlación de la solicitud. Presente incluso cuando
                está vacío.
              example: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
            fields:
              type: object
              additionalProperties: true
              description: >-
                Metadatos estructurados de validación o reintento cuando están
                disponibles. Los detalles de validación a nivel de campo,
                encabezado, ruta y consulta se devuelven todos aquí.
              example:
                currentTime: '2026-02-01T18:30:00-03:00'
                operatingHours: Mon-Fri 06:30-17:00 UTC-3
  responses:
    BadRequest:
      description: >-
        Indica que la solicitud contiene datos de entrada inválidos. Verifique
        los detalles del campo para errores de validación específicos.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidInput:
              summary: Validation error
              value:
                error:
                  code: BTF-0001
                  service: plugin
                  category: deterministic
                  message: >-
                    The request contains invalid fields. Check the field details
                    below.
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
                  fields:
                    recipientIspb: must be 8 digits
                    amount: must be positive
    Unauthorized:
      description: Indica que la solicitud no tiene un token de autenticación válido.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              summary: Missing authorization
              value:
                error:
                  code: BTF-0401
                  service: plugin
                  category: deterministic
                  message: Missing or invalid authentication token
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
    Forbidden:
      description: >-
        Indica que el llamador está autenticado pero carece de permiso para esta
        operación, o el tenant no está licenciado para este endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            notLicensed:
              summary: Tenant not licensed
              value:
                error:
                  code: BTF-0403
                  service: plugin
                  category: deterministic
                  message: Tenant is not licensed to use this endpoint
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
            permissionDenied:
              summary: Caller lacks permission
              value:
                error:
                  code: BTF-0405
                  service: plugin
                  category: deterministic
                  message: Caller lacks permission for this resource
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
    InitiationNotFound:
      description: >-
        Indica que la iniciación no fue encontrada o pertenece a una
        organización diferente.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            initiationNotFound:
              summary: Invalid initiation ID
              value:
                error:
                  code: BTF-0201
                  service: plugin
                  category: deterministic
                  message: Initiation not found or belongs to different organization
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
    AlreadyProcessed:
      description: Indica que esta iniciación ya fue procesada en una transferencia.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            alreadyProcessed:
              summary: Initiation used
              value:
                error:
                  code: BTF-0203
                  service: plugin
                  category: deterministic
                  message: This initiation has already been processed
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
                  fields:
                    transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d
    InitiationExpired:
      description: >-
        Indica que la iniciación ha expirado después de 24 horas. Se debe crear
        una nueva iniciación.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            expired:
              summary: Initiation too old
              value:
                error:
                  code: BTF-0202
                  service: plugin
                  category: deterministic
                  message: Initiation expired after 24 hours. Create a new initiation.
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
                  fields:
                    expiresAt: '2026-01-31T15:30:00-03:00'
    SigningPayloadInvalid:
      description: >-
        Indica que el payload de firma no pudo prepararse debido a una violación
        de restricción de dominio o de payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            payloadFieldInvalid:
              summary: Required payload field missing
              value:
                error:
                  code: BTF-0003
                  service: plugin
                  category: deterministic
                  message: STR0008 payload is missing a required field
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
            unsupportedType:
              summary: Unsupported transfer type
              value:
                error:
                  code: BTF-0004
                  service: plugin
                  category: deterministic
                  message: Signing prepare only supports TED_OUT initiations
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
    RateLimitExceeded:
      description: >-
        Indica que se ha excedido el límite de solicitudes. Reintente después
        del número de segundos especificado en el encabezado Retry-After.
      headers:
        Retry-After:
          description: Segundos hasta que se restablezca el límite de solicitudes
          schema:
            type: integer
            example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimitExceeded:
              summary: Too many requests
              value:
                error:
                  code: BTF-0429
                  service: plugin
                  category: rate_limit
                  message: >-
                    Too many requests. Retry after the interval indicated by the
                    `Retry-After` header.
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
              description: >
                Las respuestas de límite de tasa usan el código dedicado
                `BTF-0429` con la categoría `rate_limit`. Los clientes deben
                aplicar backoff usando el estado HTTP `429` y el encabezado
                `Retry-After`.
    InternalServerError:
      description: Indica que ocurrió un error interno inesperado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internalError:
              summary: Internal error
              value:
                error:
                  code: BTF-9000
                  service: plugin
                  category: plugin
                  message: Unexpected error while processing the request
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
    BadGateway:
      description: >-
        Indica que JD SPB rechazó la solicitud en la capa de autenticación o
        configuración (certificado de firma, credenciales o configuración). El
        código del proveedor JD sin modificar (AAC*, AAE*) se transmite tal cual
        en el campo `code`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            jdAuthRejected:
              summary: JD SPB auth rejection
              value:
                error:
                  code: AAC90
                  service: jd_spb
                  category: deterministic
                  message: JD SPB rejected the signing certificate or credentials
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
    ServiceUnavailable:
      description: >-
        Indica que un servicio externo (CRM, JD SPB, Midaz o Fees) no está
        disponible temporalmente.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            crmUnavailable:
              summary: CRM service down
              value:
                error:
                  code: BTF-0502
                  service: crm
                  category: transient
                  message: >-
                    Unable to validate account. The CRM service is temporarily
                    unavailable. Try again later.
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
            jdUnavailable:
              summary: JD SPB unavailable
              value:
                error:
                  code: TRANSPORT
                  service: jd_spb
                  category: transient
                  message: >-
                    Unable to submit transfer. The JD SPB service is temporarily
                    unavailable. Try again later.
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
            midazUnavailable:
              summary: Midaz ledger unavailable
              value:
                error:
                  code: BTF-2000
                  service: midaz
                  category: transient
                  message: >-
                    Unable to process transfer. The Midaz ledger service is
                    temporarily unavailable. Try again later.
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
            feeServiceUnavailable:
              summary: Fee service unavailable (fail-closed mode)
              value:
                error:
                  code: BTF-3000
                  service: fees
                  category: transient
                  message: >-
                    Unable to calculate fee. The fee service is temporarily
                    unavailable. Try again later.
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
            dlqInspectorUnavailable:
              summary: DLQ inspector not configured
              value:
                error:
                  code: BTF-9005
                  service: plugin
                  category: deterministic
                  message: DLQ inspector is not configured
                  requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Autenticación mediante token JWT Bearer. El tenantId se deriva del token
        bearer o del contexto autenticado de la solicitud y no se proporciona a
        través de X-Organization-Id.

````