> ## 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. # Obter uma Transferência > Use este endpoint para recuperar o status atual e os detalhes de uma transferência, incluindo seu tipo, histórico de status, detalhes do remetente e destinatário, valores e timestamps. Retorna apenas transferências pertencentes à mesma organização. ## OpenAPI ````yaml pt/openapi/v3-current/ted.yaml get /v1/transfers/{transferId} 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://ted.sandbox.lerian.net description: Sandbox (placeholder — ainda não disponível para acesso público) security: - BearerAuth: [] - OAuth2ClientCredentials: - api - OAuth2Password: - api 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/{transferId}: get: tags: - Transfers API summary: Obter uma Transferência description: >- Use este endpoint para recuperar o status atual e os detalhes de uma transferência, incluindo seu tipo, histórico de status, detalhes do remetente e destinatário, valores e timestamps. Retorna apenas transferências pertencentes à mesma organização. operationId: getTransferStatus parameters: - $ref: '#/components/parameters/XOrganizationId' - name: transferId in: path required: true description: O identificador único da transferência. schema: type: string format: uuid responses: '200': description: >- Indica que a transferência foi encontrada e seus detalhes são retornados. content: application/json: schema: $ref: '#/components/schemas/Transfer' examples: tedOutCompleted: summary: TED OUT concluído value: transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d type: TED_OUT status: COMPLETED senderAccountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipient: ispb: '00000000' branch: '0001' account: '1234567890' accountType: CACC holderName: Maria Santos holderDocument: '98765432100' amount: 1000.5 feeAmount: 1.5 totalAmount: 1002 confirmationNumber: '20260201001' controlNumber: '202602010001' createdAt: '2026-02-01T15:30:00-03:00' updatedAt: '2026-02-01T15:35:00-03:00' completedAt: '2026-02-01T15:35:00-03:00' statusHistory: - status: CREATED timestamp: '2026-02-01T15:30:00-03:00' reason: null - status: PENDING timestamp: '2026-02-01T15:30:05-03:00' reason: null - status: PROCESSING timestamp: '2026-02-01T15:30:10-03:00' reason: null - status: COMPLETED timestamp: '2026-02-01T15:35:00-03:00' reason: null tedInReceived: summary: TED IN recebido value: transferId: 019c96a0-ab20-7def-a1b2-1f2a3b4c5d6e type: TED_IN status: COMPLETED senderAccountId: 019c96a0-7e5a-7b3c-9d8e-2f1a0b3c4d5e recipient: ispb: '12345678' branch: '0001' account: '9876543210' accountType: CACC holderName: João Silva holderDocument: '12345678901' amount: 500 feeAmount: 0 totalAmount: 500 confirmationNumber: '20260201002' controlNumber: '202602010002' createdAt: '2026-02-01T16:00:00-03:00' updatedAt: '2026-02-01T16:00:05-03:00' completedAt: '2026-02-01T16:00:05-03:00' statusHistory: - status: RECEIVED timestamp: '2026-02-01T16:00:00-03:00' reason: null - status: COMPLETED timestamp: '2026-02-01T16:00:05-03:00' reason: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/TransferNotFound' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalServerError' '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 schemas: Transfer: type: object required: - transferId - type - status - senderAccountId - recipient - amount - feeAmount - totalAmount - createdAt - updatedAt - statusHistory properties: transferId: type: string format: uuid description: O identificador único da transferência. example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d type: $ref: '#/components/schemas/TransferType' status: $ref: '#/components/schemas/TransferStatus' originalTransferId: type: string format: uuid nullable: true description: >- Para devoluções TED IN, o ID da transferência de entrada original que está sendo devolvida. example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d devolutionCode: type: string nullable: true description: >- Código BACEN do motivo da devolução, presente apenas quando a transferência é uma devolução. example: '18' senderAccountId: type: string format: uuid description: >- UUID da conta do remetente. Sempre presente. Para TED IN, onde o remetente é um banco externo sem conta local, este é um identificador sintético derivado de forma determinística a partir do documento do remetente. example: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipientAccountId: type: string format: uuid nullable: true description: >- UUID da conta do destinatário, quando o destinatário é representado como uma conta Midaz. example: 019c96a0-ac10-7efa-b1c2-2a3b4c5d6e7f recipient: $ref: '#/components/schemas/RecipientDetails' amount: type: number format: decimal description: O valor da transferência sem a tarifa. example: 1000.5 feeAmount: type: number format: decimal description: A tarifa cobrada por esta transferência. example: 1.5 totalAmount: type: number format: decimal description: >- O valor total, calculado como o valor da transferência mais a tarifa. example: 1002 confirmationNumber: type: string nullable: true maxLength: 20 description: O código de confirmação legível, se disponível. example: '20260201001' controlNumber: type: string nullable: true maxLength: 20 description: >- O número de controle do JD SPB, presente para transferências TED OUT e TED IN. example: '202602010001' midazTransactionId: type: string format: uuid nullable: true description: O ID da transação correspondente no ledger Midaz. example: 019c96a0-ac10-7efa-b1c2-2a3b4c5d6e7f description: type: string nullable: true maxLength: 140 description: A finalidade ou descrição da transferência. example: Payment for services metadata: type: object nullable: true additionalProperties: true description: Metadados personalizados como pares chave-valor. createdAt: type: string format: date-time description: O timestamp de quando a transferência foi criada. example: '2026-02-01T15:30:00-03:00' updatedAt: type: string format: date-time description: O timestamp da última atualização de status. example: '2026-02-01T15:35:00-03:00' completedAt: type: string format: date-time nullable: true description: >- O timestamp de quando a transferência foi concluída. Nulo se ainda não concluída. example: '2026-02-01T15:35:00-03:00' statusHistory: type: array description: O histórico de transições de status desta transferência. items: $ref: '#/components/schemas/StatusHistoryEntry' TransferType: type: string enum: - TED_OUT - TED_IN - P2P description: >- O tipo de transferência. TED_OUT é uma transferência de saída para um banco externo via JD SPB. TED_IN é uma transferência de entrada de um banco externo. P2P é uma transferência ponto a ponto dentro da mesma instituição (mesmo ISPB). example: TED_OUT TransferStatus: type: string enum: - CREATED - PENDING - PROCESSING - COMPLETED - REJECTED - FAILED - CANCELLED - RECEIVED description: >- O status atual da transferência. Para TED OUT: CREATED → PENDING → PROCESSING → COMPLETED, REJECTED ou FAILED. Para P2P: CREATED → PROCESSING → COMPLETED ou FAILED (PENDING é um estado específico do SPB e não se aplica a P2P). Transferências podem ser canceladas (CANCELLED) enquanto estiverem com status CREATED ou PENDING. Para TED IN: RECEIVED → PROCESSING → COMPLETED ou FAILED. Um TED IN em status COMPLETED também pode transitar para FAILED em caso de estorno. example: COMPLETED RecipientDetails: type: object required: - ispb - account - holderDocument properties: ispb: type: string pattern: ^[0-9]{8}$ description: O código ISPB de 8 dígitos que identifica o banco do destinatário. example: '00000000' branch: type: string pattern: ^[0-9]{4}$ description: O código da agência de 4 dígitos. example: '0001' account: type: string pattern: ^[0-9]{1,20}$ description: O número da conta, de 1 a 20 dígitos. example: '1234567890' accountType: $ref: '#/components/schemas/AccountType' holderName: type: string minLength: 1 maxLength: 200 description: O nome completo do titular da conta. example: Maria Santos holderDocument: type: string pattern: ^[0-9]{11}$|^[0-9]{14}$ description: >- O número do documento do titular. CPF (11 dígitos) para pessoas físicas ou CNPJ (14 dígitos) para empresas. example: '12345678901' StatusHistoryEntry: type: object required: - status - timestamp properties: status: $ref: '#/components/schemas/TransferStatus' timestamp: type: string format: date-time example: '2026-02-01T15:30:00-03:00' reason: type: string nullable: true maxLength: 500 description: O motivo da mudança de status, se aplicável. example: JD timeout after 3 retries 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 AccountType: type: string description: >- O tipo de conta seguindo os códigos ISO 20022. Os valores conhecidos incluem: CACC é uma conta corrente, SLRY é uma conta salário, SVGS é uma conta poupança, TRAN é uma conta de pagamento, e OTHR é qualquer outro tipo de conta. example: CACC 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 TransferNotFound: description: >- Indica que a transferência não foi encontrada ou pertence a uma organização diferente. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: transferNotFound: summary: Transfer ID invalid value: error: code: BTF-0200 service: plugin category: deterministic message: Transfer not found 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 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. OAuth2ClientCredentials: type: oauth2 flows: clientCredentials: tokenUrl: /v1/login/oauth/access_token scopes: api: Acesso à API de transferências TED OAuth2Password: type: oauth2 flows: password: tokenUrl: /v1/login/oauth/access_token scopes: api: Acesso à API de transferências TED ````