> ## 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. # Iniciar una Transferencia > Utilice este endpoint para iniciar una transferencia validando los datos del remitente, verificando el horario de operación y los límites de uso, detectando duplicados y calculando la tarifa. No se retienen fondos en este paso. El `initiationId` devuelto es válido por 24 horas y debe confirmarse a través del endpoint Procesar Transferencia. Utilice el encabezado `X-Idempotency` para deduplicación garantizada. ## OpenAPI ````yaml es/openapi/v3-current/ted.yaml post /v1/transfers/initiate 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/initiate: post: tags: - Transfers API summary: Iniciar una Transferencia description: >- Utilice este endpoint para iniciar una transferencia validando los datos del remitente, verificando el horario de operación y los límites de uso, detectando duplicados y calculando la tarifa. No se retienen fondos en este paso. El `initiationId` devuelto es válido por 24 horas y debe confirmarse a través del endpoint Procesar Transferencia. Utilice el encabezado `X-Idempotency` para deduplicación garantizada. operationId: initiateTransfer parameters: - $ref: '#/components/parameters/XOrganizationId' - $ref: '#/components/parameters/XIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InitiateTransferRequest' examples: tedOut: summary: TED OUT a banco externo value: senderAccountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipient: ispb: '00000000' branch: '0001' account: '1234567890' accountType: CACC holderName: João Silva holderDocument: '12345678901' amount: 1000.5 description: Payment for services metadata: invoiceId: INV-2024-001 p2p: summary: P2P (misma institución) value: senderAccountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipient: ispb: '12345678' branch: '0001' account: '9876543210' accountType: CACC holderName: Maria Santos holderDocument: '98765432100' amount: 500 description: Transfer to friend responses: '200': description: >- Indica que la transferencia fue iniciada exitosamente y está esperando confirmación. Las llamadas repetidas con la misma clave `X-Idempotency` reproducen la respuesta en caché. Consulte [Reintentos e idempotencia](/es/reference/retries-idempotency) para más detalles. content: application/json: schema: $ref: '#/components/schemas/InitiateTransferResponse' examples: success: summary: Iniciación con tarifa value: initiationId: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b feeAmount: 1.5 totalAmount: 1002 estimatedCompletionAt: '2026-02-01T18:00:00-03:00' expiresAt: '2026-02-02T15:30:00-03:00' status: PENDING_CONFIRMATION freeTransfer: summary: Sin tarifa configurada value: initiationId: 019c96a0-aa20-7bcd-e1f2-9d0e1f2a3b4c feeAmount: 0 totalAmount: 1000.5 estimatedCompletionAt: '2026-02-01T18:00:00-03:00' expiresAt: '2026-02-02T15:30:00-03:00' status: PENDING_CONFIRMATION '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/AccountNotFound' '409': $ref: '#/components/responses/DuplicateTransfer' '422': $ref: '#/components/responses/OperatingHoursViolation' '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: InitiateTransferRequest: type: object required: - senderAccountId - recipient - amount - purpose properties: senderAccountId: type: string format: uuid description: El ID de cuenta Midaz del remitente. example: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipient: $ref: '#/components/schemas/RecipientDetails' amount: type: number format: decimal minimum: 0.01 maximum: 999999.99 description: El monto de la transferencia en BRL. example: 1000.5 purpose: type: string pattern: ^[0-9]{1,4}$ maxLength: 4 description: > Código FinlddCli del SPB BACEN que identifica el propósito de la transferencia. Debe contener entre 1 y 4 dígitos ASCII. Códigos FinlddCli comunes: * `1` — Pagamento de Impostos, Tributos e Taxas * `3` — Pagamentos de Dividendos * `10` — Crédito em Conta * `100` — Depósito Judicial Consulte el _Dicionário de Domínios_ (`FinlddCli`) del BACEN para la tabla completa de códigos activos. **Nota:** el plugin acepta actualmente valores de FinlddCli de hasta 4 dígitos. Códigos de 5 dígitos del catálogo BACEN (como `99999` — _Outros_) aún no están soportados y devolverán un error de validación. example: '10' description: type: string maxLength: 140 description: Descripción en texto libre de la transferencia. example: Payment for services metadata: type: object additionalProperties: true description: Metadatos personalizados como pares clave-valor. example: invoiceId: INV-2024-001 orderId: ORD-2024-123 InitiateTransferResponse: type: object required: - initiationId - feeAmount - totalAmount - estimatedCompletionAt - expiresAt - status properties: initiationId: type: string format: uuid description: >- El ID de iniciación único. Utilice este valor en el endpoint Procesar Transferencia para confirmar la transferencia. example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b feeAmount: type: number format: decimal description: >- El monto de la tarifa calculada. Devuelve 0.00 si las tarifas están deshabilitadas para esta organización. 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 estimatedCompletionAt: type: string format: date-time description: El tiempo estimado en que la transferencia será completada. example: '2026-02-01T18:00:00-03:00' expiresAt: type: string format: date-time description: >- El momento en que esta iniciación expira, 24 horas después de su creación. example: '2026-02-02T15:30:00-03:00' status: $ref: '#/components/schemas/InitiationStatus' feeEntries: type: array description: >- Desglose detallado de comisiones. Cada entrada corresponde a una comisión cobrada durante la transferencia. items: type: object properties: label: type: string description: Identificador de la comisión. example: ted_transfer_fee amount: type: number format: decimal description: Monto de la comisión. example: 1.5 creditAccount: type: string description: Cuenta que recibe el crédito de la comisión. example: platform-fee-account sourceAccount: type: string description: Cuenta debitada por la comisión. example: sender-account isDeductible: type: boolean description: >- Si la comisión se deduce del monto de la transferencia (true) o se agrega encima (false). example: false packageAppliedId: type: string format: uuid nullable: true description: >- ID del paquete de comisiones aplicado a esta transferencia, si corresponde. example: 019c96a0-ad10-7fab-c1d2-3b4c5d6e7f8a 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' InitiationStatus: type: string enum: - PENDING_CONFIRMATION - PROCESSED - EXPIRED description: >- El estado de la iniciación. PENDING_CONFIRMATION indica que la iniciación está esperando confirmación a través del endpoint Procesar Transferencia. PROCESSED indica que se creó una transferencia. EXPIRED indica que la iniciación expiró después de 24 horas. example: PENDING_CONFIRMATION 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 AccountNotFound: description: Indica que la cuenta del remitente no fue encontrada en el CRM. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: accountNotFound: summary: Invalid sender account value: error: code: BTF-0500 service: crm category: deterministic message: Sender account does not exist in CRM requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f DuplicateTransfer: description: >- Indica que se detectó una transferencia idéntica dentro de la ventana de deduplicación de 60 segundos. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: duplicate: summary: Same transfer submitted twice value: error: code: BTF-0012 service: plugin category: deterministic message: Identical transfer submitted 15 seconds ago requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f fields: originalTransferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d detectedAt: '2026-02-01T15:30:15-03:00' OperatingHoursViolation: description: >- Indica que la transferencia fue intentada fuera del horario de operación de BACEN (lunes a viernes, 06:30-17:00 hora de Brasilia). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: outsideHours: summary: After 17:00 value: error: code: BTF-0010 service: plugin category: deterministic message: >- Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f fields: currentTime: '2026-02-01T18:30:00-03:00' nextAvailableTime: '2026-02-03T06:30:00-03:00' 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. 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 ````