> ## 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 Assinatura da Transferência

> Use este endpoint para congelar o payload canônico STR0008 de uma transferência TED OUT previamente iniciada e obter os bytes exatos que devem ser assinados antes de chamar Process Transfer. A resposta inclui um `signingArtifactId` e um `transferId` reservado. O `transferId` reservado não é consultável até que Process Transfer tenha sucesso.

Use o cabeçalho `X-Idempotency` para deduplicação garantida. Chamadas repetidas com a mesma chave reproduzem a resposta em cache.



## OpenAPI

````yaml pt/openapi/v3-current/ted.yaml post /v1/transfers/signing/prepare
openapi: 3.0.3
info:
  title: API do Plugin de Transferência Bancária (TED)
  description: >-
    API completa para transferências bancárias brasileiras (TED OUT, TED IN,
    P2P) através da plataforma Lerian, incluindo iniciação de transferências,
    processamento, acompanhamento de status e cancelamento.
  version: 1.1.9
servers:
  - url: https://plugin-br-bank-transfer.sandbox.lerian.net
    description: Sandbox (placeholder — ainda não disponível para acesso público)
security:
  - BearerAuth: []
tags:
  - name: Transfers API
    description: Endpoints para iniciar, processar, acompanhar e cancelar transferências.
  - name: Webhooks
    description: >-
      Endpoints para registrar e gerenciar assinaturas de webhook com escopo de
      tenant para eventos de transferência.
  - name: Webhook DLQ
    description: >-
      Endpoints para inspecionar e reprocessar mensagens da dead-letter queue de
      webhooks.
paths:
  /v1/transfers/signing/prepare:
    post:
      tags:
        - Transfers API
      summary: Preparar Payload de Assinatura da Transferência
      description: >-
        Use este endpoint para congelar o payload canônico STR0008 de uma
        transferência TED OUT previamente iniciada e obter os bytes exatos que
        devem ser assinados antes de chamar Process Transfer. A resposta inclui
        um `signingArtifactId` e um `transferId` reservado. O `transferId`
        reservado não é consultável até que Process Transfer tenha sucesso.


        Use o cabeçalho `X-Idempotency` para deduplicação garantida. Chamadas
        repetidas com a mesma chave reproduzem a resposta em cache.
      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 assinatura para uma iniciação
                value:
                  initiationId: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b
      responses:
        '200':
          description: >-
            Indica que o payload canônico foi gerado e está pronto para ser
            assinado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrepareSigningResponse'
              examples:
                success:
                  summary: Payload assinável retornado
                  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: >-
        Escopo da organização Midaz para a requisição, usado para chamadas
        downstream ao CRM, Fees e Midaz. Obrigatório nas rotas de transferência
        com escopo de organização em todos os modos de implantação; um valor
        ausente ou que não seja UUID retorna 400. Este não é o identificador do
        tenant — o tenantId é derivado do JWT bearer ou do contexto autenticado,
        nunca deste cabeçalho. Workers em segundo plano (poller de TED IN,
        conciliação) não possuem cabeçalho de requisição e, no modo
        single-tenant, recorrem à variável de ambiente `ORGANIZATION_ID` da
        implantação.
      schema:
        type: string
        format: uuid
      example: 019c96a0-0a98-7287-9a31-786e0809c769
    XIdempotencyKey:
      name: X-Idempotency
      in: header
      required: true
      description: >-
        Chave de idempotência obrigatória para tentativas seguras. Use um UUID
        v4 ou identificador de negócio único. Se a mesma chave for enviada
        novamente e a solicitação original já tiver sido processada, a resposta
        em cache será retornada.


        Consulte [Tentativas e idempotência](/pt/reference/retries-idempotency)
        para detalhes.
      schema:
        type: string
        maxLength: 255
      example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b
  schemas:
    PrepareSigningRequest:
      type: object
      required:
        - initiationId
      properties:
        initiationId:
          type: string
          format: uuid
          description: O ID de iniciação retornado pelo 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 do artefato de assinatura congelado. Passe este valor
            para Process Transfer junto com a assinatura.
          example: 019c96a0-bb10-7def-a1b2-3c4d5e6f7a8b
        transferId:
          type: string
          format: uuid
          description: >-
            O ID de transferência reservado para o eventual TED OUT. Não
            consultável até que Process Transfer tenha sucesso.
          example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d
        controlNumber:
          type: string
          maxLength: 20
          description: O número de controle do JD SPB reservado para esta transferência.
          example: '202602010001'
        algorithm:
          type: string
          enum:
            - RSA_PKCS1_V15_SHA256
          description: >-
            O algoritmo de assinatura. Fixado por contrato do JD SPB; qualquer
            outro valor é rejeitado em Process Transfer.
          example: RSA_PKCS1_V15_SHA256
        payload:
          type: string
          description: >-
            O payload canônico STR0008, exatamente como será submetido ao JD
            SPB.
          example: <STR0008>...</STR0008>
        payloadHash:
          type: string
          description: >-
            Digest SHA-256 codificado em hex do payload. Reenvie este valor em
            Process Transfer para validação de integridade.
          example: 8f0c7f5c1c7b4d9f2f5c7d1a0d4c9a2b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f
        signableContent:
          type: string
          description: >-
            A extração `ConteudoAssinado` para assinadores externos. Presente
            apenas quando um construtor de assinatura externo está configurado.
          example: <ConteudoAssinado>...</ConteudoAssinado>
        expiresAt:
          type: string
          format: date-time
          description: >-
            O momento em que o artefato de assinatura expira. Process Transfer
            deve ser chamado antes desse timestamp.
          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: >-
                O código de erro estável. Erros do plugin usam o formato
                `BTF-XXXX`; rejeições de negócio/autenticação do JD SPB repassam
                o código bruto do fornecedor literalmente (por exemplo, `AAC90`,
                `ACE95`, `DVE01`), e falhas de transporte no nível do JD expõem
                os marcadores sintéticos `TRANSPORT` ou `JD_MISSING_CODE`. Faça
                a correspondência com base neste valor, e não no status HTTP.
              example: BTF-0010
            service:
              type: string
              description: O serviço ou domínio que produziu o erro.
              example: plugin
            category:
              type: string
              description: >-
                Categoria de erro legível por máquina usada para decisões de
                reprocessamento.
              enum:
                - deterministic
                - transient
                - rate_limit
                - plugin
              example: deterministic
            message:
              type: string
              description: Um resumo do erro legível por humanos.
              example: >-
                Transferências só podem ser iniciadas de segunda a sexta entre
                06:30 e 17:00 horário de Brasília
            requestId:
              type: string
              description: O ID de correlação da requisição. Presente mesmo quando vazio.
              example: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
            fields:
              type: object
              additionalProperties: true
              description: >-
                Metadados estruturados de validação ou reprocessamento quando
                disponíveis. Detalhes de validação em nível de campo, cabeçalho,
                caminho e consulta são todos retornados aqui.
              example:
                currentTime: '2026-02-01T18:30:00-03:00'
                operatingHours: Mon-Fri 06:30-17:00 UTC-3
  responses:
    BadRequest:
      description: >-
        Indica que a requisição contém entrada inválida. Verifique os detalhes
        do campo para erros de validação 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 a requisição não possui um token de autenticação 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 o chamador está autenticado mas não tem permissão para esta
        operação, ou o tenant não 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 a iniciação não foi encontrada ou pertence a uma organização
        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 iniciação já foi processada em uma transferência.
      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 a iniciação expirou após 24 horas. Uma nova iniciação deve
        ser criada.
      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 o payload de assinatura não pôde ser preparado devido a uma
        violação de restrição de domínio ou 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 o limite de requisições foi excedido. Tente novamente após o
        número de segundos especificado no cabeçalho Retry-After.
      headers:
        Retry-After:
          description: Segundos até o limite de requisições ser redefinido
          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: >
                As respostas de rate-limit usam o código dedicado `BTF-0429` com
                a categoria `rate_limit`. Os clientes devem aplicar backoff
                usando o status HTTP `429` e o cabeçalho `Retry-After`.
    InternalServerError:
      description: Indica que ocorreu um erro 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 o JD SPB rejeitou a requisição na camada de autenticação ou
        configuração (certificado de assinatura, credenciais ou configuração). O
        código bruto do fornecedor JD (AAC*, AAE*) é repassado literalmente no
        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 um serviço externo (CRM, JD SPB, Midaz ou Fees) está
        temporariamente indisponível.
      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: >-
        Autenticação por token JWT Bearer. O tenantId é derivado do token bearer
        ou do contexto de requisição autenticado e não é fornecido por meio do
        X-Organization-Id.

````