> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversión de divisas en masa

La API de conversión masiva de divisas te permite realizar transacciones de cambio de divisas (FX) individuales o múltiples de forma programática con tipos de cambio óptimos y una gran eficiencia de procesamiento.

## Requisitos previos

Antes de crear intercambios de divisas, asegúrate de tener:

* **Credenciales API válidas** con permisos de cambio de divisas.
* **Números de cuenta activos** tanto para la moneda de origen como para la de destino.
* **Saldo suficiente** en tu cuenta en la moneda de origen.

> [!WARNING]
>
> **Importante**
>
> Puedes generar de antemano cotizaciones de tipo de cambio con nuestra [API de cotización de cambio de divisas](https://docs.localpayment.com/es/docs/quote-currency-conversion.md) y fijar los tipos de cambio incluyendo el `exchangeRateToken` en tu solicitud masiva.

***

## Endpoint de la API

Para crear intercambios masivos, envía una solicitud `POST` al endpoint [Crear conversión de divisas masiva](https://docs.localpayment.com/es/reference/exchange-bulk.md).

### Endpoint

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST https://api.stage.localpayment.com/currency-exchange
```

### Autenticación

Incluye tu token de acceso en todas las solicitudes a la API:

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
```

### Parámetros clave de la solicitud

| Parámetro | Tipo | Descripción |
| - | - | - |
| `externalId` | string | Identificador único para tu transacción |
| `country` | string | Código de país ISO |
| `currency` | string | Código de moneda base |
| `account.debited` | object | Detalles de la cuenta de origen |
| `account.credited` | object | Detalles de la cuenta de destino |

### Ejemplo de solicitud (Argentina)

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/currency-exchange \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "country": "ARG",
       "currency": "ARS", 
       "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
       "account": {
         "debited": {
           "currency": "ARS",
           "accountNumber": "{{accountNumber}}", 
           "amount": 10000
         },
         "credited": {
           "currency": "EUR",
           "accountNumber": "{{accountNumber}}"
         }
       }
     }'
```

***

## Gestión de respuestas

### Respuesta de éxito

Un cambio de divisas exitoso devuelve los detalles de la transacción:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "CurrencyExchange",
  "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
  "internalId": "8888ad65-aa6e-4643-b9ba-ff62318fd90b", 
  "country": "ARG",
  "currency": "ARS",
  "exchangeRateToken": "",
  "clientCode": "0005",
  "creationDate": "2023-03-21T21:25:14.533+00:00",
  "errors": [],
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "CURRENCY EXCHANGE"
  },
  "account": {
    "debited": {
      "currency": "ARS", 
      "accountNumber": "{{accountNumber}}",
      "amount": 10000
    },
    "credited": {
      "currency": "EUR",
      "accountNumber": "{{accountNumber}}", 
      "amount": 44.52
    },
    "appliedFx": 224.54
  }
}
```

### Campos de respuesta clave

| Campo | Descripción |
| - | - |
| `internalId` | ID de transacción generado por el sistema para seguimiento |
| `status.code` | Código de estado de transacción actual |
| `account.appliedFx` | Tipo de cambio aplicado a la conversión |
| `account.credited.amount` | Importe final convertido |

***

### Respuesta de error

#### Fondos insuficientes

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
  "internalId": "6fc7e955-7704-4558-8a05-6f4a2c3d9b45",
  "errors": [
    {
      "code": "101",
      "detail": "Insufficient funds in source account"
    }
  ],
  "status": {
    "code": "101", 
    "description": "REJECTED",
    "detail": "Insufficient funds in source account"
  }
}
```

***

## Seguimiento del estado de las transacciones

Supervisa tus cambios de divisas a través de múltiples canales:

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando cambie el estado de la transacción. Más eficiente para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado de las transacciones.

### Ciclo de vida del estado

| Código | Estado | Descripción |
| :- | :- | :- |
| `103` | `APPROVED` | El cambio de divisas fue aprobado. |
| `200` | `COMPLETED` | El cambio de divisas había finalizado. |
| `303` | `REJECTED` | Este token de tipo de cambio ha caducado. |
| | | |

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Características avanzadas

### Utilización de cotizaciones de tipo de cambio

Asegura tarifas favorables generando cotizaciones con anticipación:

1. **Generar cotización**: Llamar a la [API de cotización de cambio de divisas](https://docs.localpayment.com/es/reference/currency-exchange-quote.md)
2. **Obtener token**: Extrae el `exchangeRateToken` de la respuesta
3. **Aplicar token**: Incluye el token en tu solicitud de intercambio masivo.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "exchangeRateToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
  "account": {
    // ... rest of request
  }
}
```

### Consejos para el procesamiento a granel

**Optimización del rendimiento**

* **Solicitudes por lotes**: Agrupa varios intercambios en una única llamada a la API siempre que sea posible.
* **Limitación de velocidad**: Implementar retroceso exponencial para el procesamiento de alto volumen.
* **Gestión de webhooks**: Utiliza webhooks en lugar de realizar sondeos para obtener actualizaciones de estado.
* **Lógica de reintento por error**: Implementar mecanismos de reintento inteligentes para fallos temporales.

***

## Pruebas y validación

### Entorno de pruebas

Prueba tu integración en nuestro entorno de pruebas:

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST https://api.sandbox.localpayment.com/currency-exchange
```

### Escenarios de prueba

Valida estos escenarios antes de tu lanzamiento:

* Cambio de divisas exitoso con cuentas válidas
* Gestión de errores por fondos insuficientes
* Vencimiento del token de tipo de cambio
* Manejo de números de cuenta no válidos
* Escenarios de tiempo de espera de red
* Procesamiento de notificaciones de webhook

***

## Recursos y próximos pasos

Maximiza el éxito de tu integración con estos recursos esenciales.

> [card] [Integración de webhooks](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura notificaciones en tiempo real para las actualizaciones del estado de las transacciones.

> [card] [Portal de informes empresariales](https://docs.localpayment.com/es/docs/balance-report.md)
>
> Accede a análisis detallados, herramientas de generación de informes y funciones de conciliación.

> [card] [Monitoreo de transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes)
>
> Aprende a consultar el estado de las transacciones e implementar un seguimiento exhaustivo.

> [card] [Referencia de la API](https://docs.localpayment.com/es/reference/exchange-bulk.md)
>
> Documentación completa del endpoint con ejemplos interactivos.

> [!NOTE]
>
> **Consejo profesional**
>
> Siempre prueba tu flujo de trabajo en nuestro entorno de pruebas antes de implementarlo en producción. Esto garantiza que el manejo de errores, el procesamiento de webhooks y el seguimiento del estado funcionen correctamente en todos los escenarios.

***

> [!NOTE]
>
> **¿Necesitas ayuda?**
>
> Ponte en contacto con nuestro [equipo de soporte](mailto:support@localpayment.com) si experimentas algún problema o necesitas ayuda con la integración.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.