> ## 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.

# Conversão de Moedas em Massa

A API de Conversão de Moedas em Massa permite que você execute transações de câmbio (FX) individuais ou múltiplas de forma programática, com taxas otimizadas e eficiência de processamento.

## Pré-requisitos

Antes de criar câmbio de moedas, certifique-se de ter:

* **Credenciais de API válidas** com permissões de câmbio de moeda.
* **Números de contas ativas** para as moedas de origem e de destino.
* **Saldo suficiente** em sua conta na moeda de origem.

> [!WARNING]
>
> **Importante**
>
> Você pode gerar previamente cotações de taxa de câmbio usando nossa [API de Cotação de Câmbio](https://docs.localpayment.com/pt-br/docs/quote-currency-conversion.md) e fixar as taxas incluindo o `exchangeRateToken` em sua solicitação em massa.

***

## Endpoint da API

Para criar conversões em massa, envie uma solicitação `POST` para o endpoint [Criar conversão de câmbio em massa](https://docs.localpayment.com/pt-br/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
```

### Autenticação

Inclua seu token de acesso em todas as solicitações da API:

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

### Parâmetros-chave da solicitação

| Parâmetro | Tipo | Descrição |
| - | - | - |
| `externalId` | string | Identificador único para sua transação |
| `country` | string | código de país ISO |
| `currency` | string | Código da moeda base |
| `account.debited` | object | Detalhes da conta de origem |
| `account.credited` | object | Detalhes da conta de destino |

### Exemplo de solicitação (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}}"
         }
       }
     }'
```

***

## Tratamento de Respostas

### Resposta bem-sucedida

Uma transação de câmbio bem-sucedida retorna os seguintes detalhes:

```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 resposta principais

| Campo | Descrição |
| - | - |
| `internalId` | ID de transação gerado pelo sistema para rastreamento |
| `status.code` | Código de status da transação atual |
| `account.appliedFx` | Taxa de câmbio aplicada à conversão |
| `account.credited.amount` | Valor final convertido |

***

### Resposta de erro

#### Fundos 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"
  }
}
```

***

## Rastreamento do status da transação

Monitore suas conversões de moeda por meio de múltiplos canais:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Ciclo de vida do status

| Código | Status | Descrição |
| :- | :- | :- |
| `103` | `APPROVED` | A conversão de moeda foi aprovada. |
| `200` | `COMPLETED` | A operação de câmbio foi concluída. |
| `303` | `REJECTED` | Este token de taxa de câmbio expirou. |
| | | |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Recursos avançados

### Utilizando cotações de taxas de câmbio

Garanta taxas vantajosas gerando orçamentos antecipadamente:

1. **Gerar cotação**: Chame a [API de cotação de câmbio](https://docs.localpayment.com/pt-br/reference/currency-exchange-quote.md)
2. **Obter token**: Extraia o `exchangeRateToken` da resposta
3. **Aplicar Token**: Inclua o token em sua solicitação de troca em massa.

```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
  }
}
```

### Dicas de processamento em massa

**Otimização de desempenho**

* **Solicitações em lote**: Agrupe várias trocas em chamadas de API únicas sempre que possível.
* **Limitação de taxa**: Implemente um mecanismo de recuo exponencial para processamento de alto volume.
* **Tratamento de webhooks**: Utilize webhooks em vez de sondar o status por meio de polling.
* **Lógica de repetição em caso de erro**: Implemente mecanismos inteligentes de repetição para falhas temporárias.

***

## Testes e Validação

### Ambiente de Sandbox

Teste sua integração em nosso ambiente de sandbox:

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

### Cenários de teste

Valide esses cenários antes de entrar em produção:

* Câmbio de moeda bem-sucedido com contas válidas
* Tratamento de erros por insuficiência de fundos
* expiração do token de taxa de câmbio
* Tratamento de números de conta inválidos
* cenários de tempo limite de rede
* Processamento de notificações de webhook

***

## Recursos e próximos passos

Maximize o sucesso da sua integração com estes recursos essenciais.

> [card] [Integração de Webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure notificações em tempo real para atualizações do status das transações.

> [card] [Relatórios do Business Portal](https://docs.localpayment.com/pt-br/docs/balance-report.md)
>
> Acesse análises detalhadas, ferramentas de geração de relatórios e recursos de conciliação.

> [card] [Monitoramento de transações](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes)
>
> Aprenda a consultar o status das transações e a implementar um rastreamento abrangente.

> [card] [Referência da API](https://docs.localpayment.com/pt-br/reference/exchange-bulk.md)
>
> Documentação completa dos endpoints com exemplos interativos.

> [!NOTE]
>
> **Dica profissional**
>
> Sempre teste seu fluxo de trabalho em nosso ambiente de sandbox antes de implantá-lo em produção. Isso garante que o tratamento de erros, o processamento de webhooks e o rastreamento de status funcionem corretamente em todos os cenários.

***

> [!NOTE]
>
> **Precisa de ajuda?**
>
> Entre em contato com nossa [equipe de suporte](mailto:support@localpayment.com) caso encontre algum problema ou precise de ajuda com a integração.


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