> ## 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. # Obtener una Transferencia > Utilice este endpoint para recuperar el estado actual y los detalles de una transferencia, incluyendo su tipo, historial de estados, detalles del remitente y destinatario, montos y marcas de tiempo. Solo devuelve transferencias que pertenecen a la misma organización. ## OpenAPI ````yaml es/openapi/v3-current/ted.yaml get /v1/transfers/{transferId} 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://ted.sandbox.lerian.net description: Sandbox (marcador de posición — aún no disponible para acceso público) security: - BearerAuth: [] - OAuth2ClientCredentials: - api - OAuth2Password: - api 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/{transferId}: get: tags: - Transfers API summary: Obtener una Transferencia description: >- Utilice este endpoint para recuperar el estado actual y los detalles de una transferencia, incluyendo su tipo, historial de estados, detalles del remitente y destinatario, montos y marcas de tiempo. Solo devuelve transferencias que pertenecen a la misma organización. operationId: getTransferStatus parameters: - $ref: '#/components/parameters/XOrganizationId' - name: transferId in: path required: true description: El identificador único de la transferencia. schema: type: string format: uuid responses: '200': description: >- Indica que la transferencia fue encontrada y se devuelven sus detalles. content: application/json: schema: $ref: '#/components/schemas/Transfer' examples: tedOutCompleted: summary: TED OUT completado 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 recibido 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: >- 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 schemas: Transfer: type: object required: - transferId - type - status - senderAccountId - recipient - amount - feeAmount - totalAmount - createdAt - updatedAt - statusHistory properties: transferId: type: string format: uuid description: El identificador único de la transferencia. 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 devoluciones TED IN, el ID de la transferencia entrante original que se está devolviendo. example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d devolutionCode: type: string nullable: true description: >- Código BACEN de motivo de devolución, presente solo cuando la transferencia es una devolución. example: '18' senderAccountId: type: string format: uuid description: >- UUID de la cuenta del remitente. Siempre presente. Para TED IN, donde el remitente es un banco externo sin cuenta local, este es un identificador sintético derivado de forma determinística del documento del remitente. example: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipientAccountId: type: string format: uuid nullable: true description: >- UUID de la cuenta del destinatario, cuando el destinatario está representado como una cuenta de Midaz. example: 019c96a0-ac10-7efa-b1c2-2a3b4c5d6e7f recipient: $ref: '#/components/schemas/RecipientDetails' amount: type: number format: decimal description: El monto de la transferencia sin la tarifa. example: 1000.5 feeAmount: type: number format: decimal description: La tarifa cobrada por esta transferencia. example: 1.5 totalAmount: type: number format: decimal description: >- El monto total, calculado como el monto de la transferencia más la tarifa. example: 1002 confirmationNumber: type: string nullable: true maxLength: 20 description: El código de confirmación legible, si está disponible. example: '20260201001' controlNumber: type: string nullable: true maxLength: 20 description: >- El número de control JD SPB, presente para transferencias TED OUT y TED IN. example: '202602010001' midazTransactionId: type: string format: uuid nullable: true description: El ID de transacción correspondiente en el libro mayor de Midaz. example: 019c96a0-ac10-7efa-b1c2-2a3b4c5d6e7f description: type: string nullable: true maxLength: 140 description: El propósito o descripción de la transferencia. example: Payment for services metadata: type: object nullable: true additionalProperties: true description: Metadatos personalizados como pares clave-valor. createdAt: type: string format: date-time description: La marca de tiempo de cuando se creó la transferencia. example: '2026-02-01T15:30:00-03:00' updatedAt: type: string format: date-time description: La marca de tiempo de la última actualización de estado. example: '2026-02-01T15:35:00-03:00' completedAt: type: string format: date-time nullable: true description: >- La marca de tiempo de cuando se completó la transferencia. Nulo si aún no se ha completado. example: '2026-02-01T15:35:00-03:00' statusHistory: type: array description: El historial de transiciones de estado de esta transferencia. items: $ref: '#/components/schemas/StatusHistoryEntry' TransferType: type: string enum: - TED_OUT - TED_IN - P2P description: >- El tipo de transferencia. TED_OUT es una transferencia saliente a un banco externo a través de JD SPB. TED_IN es una transferencia entrante de un banco externo. P2P es una transferencia entre pares dentro de la misma institución (mismo ISPB). example: TED_OUT TransferStatus: type: string enum: - CREATED - PENDING - PROCESSING - COMPLETED - REJECTED - FAILED - CANCELLED - RECEIVED description: >- El estado actual de la transferencia. Para TED OUT: CREATED → PENDING → PROCESSING → COMPLETED, REJECTED o FAILED. Para P2P: CREATED → PROCESSING → COMPLETED o FAILED (PENDING es un estado específico de SPB y no se aplica a P2P). Las transferencias pueden ser canceladas (CANCELLED) mientras están en estado CREATED o PENDING. Para TED IN: RECEIVED → PROCESSING → COMPLETED o FAILED. Un TED IN en estado COMPLETED también puede pasar a FAILED en caso de contracargo. example: COMPLETED RecipientDetails: type: object required: - ispb - account - holderDocument properties: ispb: type: string pattern: ^[0-9]{8}$ description: >- El código ISPB de 8 dígitos que identifica el banco del destinatario. example: '00000000' branch: type: string pattern: ^[0-9]{4}$ description: El código de sucursal (agência) de 4 dígitos. example: '0001' account: type: string pattern: ^[0-9]{1,20}$ description: El número de cuenta, de 1 a 20 dígitos. example: '1234567890' accountType: $ref: '#/components/schemas/AccountType' holderName: type: string minLength: 1 maxLength: 200 description: El nombre completo del titular de la cuenta. example: Maria Santos holderDocument: type: string pattern: ^[0-9]{11}$|^[0-9]{14}$ description: >- El número de documento del titular. CPF (11 dígitos) para personas físicas o 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: El motivo del cambio de estado, si corresponde. 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: >- 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 AccountType: type: string description: >- El tipo de cuenta siguiendo los códigos ISO 20022. Los valores conocidos incluyen: CACC es una cuenta corriente (Conta Corrente), SLRY es una cuenta salario (Conta Salário), SVGS es una cuenta de ahorro (Conta Poupança), TRAN es una cuenta transaccional (Conta de Pagamento) y OTHR es cualquier otro tipo de cuenta. example: CACC 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 TransferNotFound: description: >- Indica que la transferencia no fue encontrada o pertenece a una organización 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 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 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. OAuth2ClientCredentials: type: oauth2 flows: clientCredentials: tokenUrl: /v1/login/oauth/access_token scopes: api: Acceso a la API de transferencias TED OAuth2Password: type: oauth2 flows: password: tokenUrl: /v1/login/oauth/access_token scopes: api: Acceso a la API de transferencias TED ````