API de Taxas de Câmbio / Exchange Rates API¶

Visão Geral / Overview¶

A API de Taxas de Câmbio permite que parceiros obtenham informações detalhadas sobre taxas cambiais para ordens específicas, incluindo cálculos completos de conversão, impostos, tarifas e valores finais. Este endpoint é essencial para exibir cotações e simulações antes da confirmação de operações de câmbio.

The Exchange Rates API allows partners to obtain detailed information about exchange rates for specific orders, including full conversion calculations, taxes, fees, and final values. This endpoint is essential for displaying quotes and simulations before confirming exchange operations.

O que é uma Taxa de Câmbio? / What is an Exchange Rate?¶

Uma taxa de câmbio (ou exchange rate) é o valor pelo qual uma moeda pode ser trocada por outra. Ela é composta por: An exchange rate is the value at which one currency can be exchanged for another. It consists of:

Taxa Base: Taxa do mercado interbancário / Interbank market rate
Spread: Margem aplicada sobre a taxa base / Margin applied over the base rate
Taxa Comercial: Taxa base + Spread / Commercial Rate: Base rate + Spread
VET (Valor Efetivo Total): Taxa final incluindo TODOS os custos / Total Effective Value: Final rate including ALL costs

Autenticação / Authentication¶

Todos os endpoints desta API requerem os seguintes headers obrigatórios: All endpoints of this API require the following mandatory headers:

Authorization: Bearer {seu_jwt_token}
Role: ADMIN_PARTNER
x-api-key: {guid_individualizado_do_parceiro}
Accept-Language: {pt-br|en-us|es-es}

Descrição dos Headers / Headers Description:¶

Authorization: Token JWT válido com role ADMIN_PARTNER / Valid JWT token with ADMIN_PARTNER role
x-api-key: GUID individualizado fornecido ao parceiro / Individualized GUID provided to the partner
Accept-Language: Idioma de resposta (pt-br, en-us ou es-es) / Response language

[!IMPORTANT] IMPORTANTE / IMPORTANT

Todos os headers acima são obrigatórios em todas as requisições. A falta de qualquer um deles resultará em erro de autenticação.

All headers above are mandatory for all requests. The absence of any of them will result in an authentication error.

Endpoint: Obter Taxa de Câmbio / Endpoint: Get Exchange Rate¶

GET /v1/partner/public/stocks/get-order-rate

Obtém a taxa de câmbio e cálculos completos para uma ordem específica, incluindo impostos, tarifas e valor total. Obtains the exchange rate and full calculations for a specific order, including taxes, fees, and total value.

Para que serve? / What is it for?¶

Este endpoint permite: / This endpoint allows:

🧊 Obter taxa de câmbio em tempo real para uma ordem
Get real-time exchange rate for an order
💰 Calcular todos os custos (IOF, IR, tarifas)
Calculate all costs (IOF, IR, fees)
🗓️ Simular diferentes fluxos de liquidação (D0, D+1, D+2)
Simulate different settlement flows (D0, D+1, D+2)
📊 Exibir VET (Valor Efetivo Total) para o cliente
Display VET (Total Effective Value) to the customer
🔐 Gerar token de segurança para cotação
Generate a security token for quoting

Quando Usar / When to Use¶

✅ Use este endpoint quando: / Use this endpoint when:

Exibir simulação de câmbio para o cliente / Displaying exchange simulation to the customer
Calcular valor total antes de confirmar operação / Calculating total value before confirming operation
Comparar custos entre diferentes fluxos de liquidação / Comparing costs between different settlement flows
Obter token para criar cotação oficial / Obtaining a token to create an official quote

❌ Não use para: / Do not use for:

Criar cotações oficiais (use endpoint /quotation) / Creating official quotes (use /quotation endpoint)
Consultar taxas históricas / Consulting historical rates
Obter taxas sem ordem associada / Obtaining rates without an associated order

Parâmetros de Query / Query Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`orderId`	long	✅	ID único da ordem para qual a taxa será calculada *Unique ID of the order*
`eSettlementFlow`	int?	❌	Fluxo de liquidação: 1 = D0, 2 = D+1, 3 = D+2. Se omitido, usa padrão (geralmente D+1).

[!IMPORTANT] IMPORTANTE / IMPORTANT

O parâmetro eSettlementFlow afeta diretamente o custo da operação: The eSettlementFlow parameter directly affects the operation cost:

D0 (1): Mais caro (liquidação imediata) / More expensive (immediate settlement)

D+1 (2): Padrão (equilíbrio custo/tempo) / Standard (cost/time balance)

D+2 (3): Mais barato (liquidação em 2 dias) / Cheaper (settlement in 2 days)

Exemplos de Requisição / Request Examples¶

Exemplo 1: Taxa Padrão (D+1) / Example 1: Standard Rate (D+1)

GET /v1/partner/public/stocks/get-order-rate?orderId=789123
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

Resultado: Taxa calculada com liquidação D+1 (próximo dia útil). Result: Rate calculated with D+1 settlement (next business day).

Exemplo 2: Taxa com Liquidação D0 (Urgente) / Example 2: Rate with D0 Settlement (Urgent)

GET /v1/partner/public/stocks/get-order-rate?orderId=789123&eSettlementFlow=1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

Resultado: Taxa calculada com liquidação D0 (mesmo dia) - geralmente mais cara. Result:* Rate calculated with D0 settlement (same day) - usually more expensive*.

Exemplo 3: Taxa com Liquidação D+2 (Econômica) / Example 3: Rate with D+2 Settlement (Economic)

GET /v1/partner/public/stocks/get-order-rate?orderId=789123&eSettlementFlow=3
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

Resultado: Taxa calculada com liquidação D+2 (dois dias úteis) - geralmente mais barata. Result:* Rate calculated with D+2 settlement (two business days) - usually cheaper*.

Resposta de Sucesso (200 OK) / Success Response (200 OK)¶

JSON

{
  "success": true,
  "data": {
    "amount": 10000.00,
    "amountNC": 53500.00,
    "rate": 5.2500,
    "commercial": 52500.00,
    "iof": 577.50,
    "iofPercentage": 1.10,
    "tariff": 150.00,
    "ir": 0.00,
    "irPercentage": 0.00,
    "vet": 5.3500,
    "total": 53500.00,
    "spread": 0.02,
    "token": "eyJhbGciOiJSVzI1NiIsInR5cC6IkpXVCJ9...",
    "taxId": 15,
    "settlementFlow": 2,
    "currency": "USD"
  }
}

Campos da Resposta Detalhados / Detailed Response Fields¶

Valores Principais / Main Values¶

Campo / Field	Tipo / Type	Descrição / Description	Exemplo / Example
`amount`	decimal	Valor em moeda estrangeira *Foreign currency amount*	USD 10,000.00
`amountNC`	decimal	Valor em moeda nacional (BRL) - valor final que o cliente paga/recebe National currency amount (BRL) - final value the customer pays/receives	R$ 53,500.00
`currency`	string	Código ISO da moeda *ISO currency code*	"USD"

Taxa de Câmbio / Exchange Rate¶

Campo / Field	Tipo / Type	Descrição / Description	Exemplo / Example
`rate`	double	Taxa de câmbio comercial (base + spread) Commercial exchange rate (base + spread)	5.2500
`spread`	decimal	Spread aplicado (margem em decimal, ex: 0.02 = 2%) Applied spread (margin in decimal, e.g., 0.02 = 2%)	0.02
`vet`	decimal	VET (Valor Efetivo Total) - taxa real incluindo TODOS os custos VET (Total Effective Value) - actual rate including ALL costs	5.3500

Cálculo da Taxa: / Rate Calculation:

Taxa Base (mercado) = 5.15
Spread (2%) = 5.15 × 0.02 = 0.10
Taxa Comercial (rate) = 5.15 + 0.10 = 5.25
VET = amountNC ÷ amount = 53500 ÷ 10000 = 5.35

Valores Intermediários / Intermediate Values¶

Campo / Field	Tipo / Type	Descrição / Description	Exemplo / Example
`commercial`	decimal	Valor comercial (amount × rate) *Commercial value*	R$ 52,500.00
`total`	decimal	Valor total final (igual a amountNC) Final total value (equal to amountNC)	R$ 53,500.00

Impostos e Taxas / Taxes and Fees¶

Campo / Field	Tipo / Type	Descrição / Description	Exemplo / Example
`iof`	decimal	Valor do IOF (Imposto sobre Operações Financeiras) *IOF amount*	R$ 577.50
`iofPercentage`	decimal	Percentual de IOF aplicado IOF percentage applied	1.10
`ir`	decimal	Valor do IR (Imposto de Renda) - geralmente R$ 0 para remessas IR amount (Income Tax) - usually R$ 0 for remittances	R$ 0.00
`irPercentage`	decimal	Percentual de IR aplicado IR percentage applied	0.00
`tariff`	decimal	Tarifa fixa da operação Fixed fee of the operation	R$ 150.00

Cálculo dos Custos: / Cost Calculation:

Valor Comercial = 10000 × 5.25 = R$ 52,500.00
IOF (1.1%) = 52500 × 0.011 = R$ 577.50
Tarifa = R$ 150.00
IR = R$ 0.00 (não aplicável para remessas)

Total = 52500 + 577.50 + 150.00 = R$ 53,227.50 ≈ R$ 53,500.00 (arredondado)

Informações de Controle / Control Information¶

Campo / Field	Tipo / Type	Descrição / Description
`token`	string	Token de segurança - use para criar cotação oficial Security token - use to create an official quote
`taxId`	long	ID da tabela de taxas aplicada Tax table ID applied
`settlementFlow`	int	Fluxo de liquidação usado (1=D0, 2=D+1, 3=D+2) Settlement flow used (1=D0, 2=D+1, 3=D+2)

[!INFO] TOKEN DE SEGURANÇA / SECURITY TOKEN

Este token é válido por tempo limitado (geralmente 10-30 minutos) e deve ser usado ao criar uma cotação oficial para garantir que a mesma taxa seja aplicada.

This token is valid for a limited time (usually 10-30 minutes) and must be used when creating an official quote to ensure that the same rate is applied.

Tipos de IOF / IOF Types¶

O IOF (Imposto sobre Operações Financeiras) varia conforme o tipo de operação: The IOF (Tax on Financial Operations) varies according to the type of operation:

Tipo de Operação / Operation Type	Percentual IOF / Percentage	Quando Aplicar / When to Apply
Remessa ao Exterior (Outbound)	1.1%	Envios de dinheiro para fora do Brasil Sending money outside Brazil
Recebimento do Exterior (Inbound)	0.38%	Recebimentos de dinheiro de fora do Brasil Receiving money from outside Brazil
Cartão de Crédito Internacional	6.38%	Compras internacionais com cartão International credit card purchases
Investimentos no Exterior	0% - 1.1%	Varia conforme tipo de investimento Varies by investment type

[!IMPORTANT] IMPORTANTE / IMPORTANT

O percentual de IOF é definido pelo governo brasileiro e pode mudar. O valor retornado pela API sempre reflete a legislação vigente.

The IOF percentage is defined by the Brazilian government and may change. The value returned by the API always reflects current legislation.

Fluxos de Liquidação / Settlement Flows¶

D0 - Liquidação no Mesmo Dia / Same-Day Settlement¶

Características: / Features:

⚡ Mais rápido (liquidação no mesmo dia) / Fastest (same-day settlement)
💰 Mais caro (maior spread ou tarifa) / Most expensive (higher spread or fee)
🚨 Ideal para urgências / Ideal for emergencies

Quando Usar: / When to Use:

Cliente precisa do dinheiro urgentemente / Customer needs the money urgently
Prazo de pagamento muito curto / Very short payment deadline
Situações de emergência / Emergency situations

Exemplo de Diferença de Preço: / Price Difference Example:

D0:  Taxa = 5.35 (spread 3%)
D+1: Taxa = 5.25 (spread 2%)
D+2: Taxa = 5.20 (spread 1.5%)

D+1 - Liquidação no Próximo Dia Útil / Next Business Day Settlement¶

Características: / Features:

⚖️ Equilíbrio custo/tempo / Balance between cost and time
👍 Recomendado para maioria dos casos / Recommended for most cases
🗓️ Processamento em 1 dia útil / Processing in 1 business day

Quando Usar: / When to Use:

Operações normais sem urgência / Normal operations without urgency
Melhor custo-benefício / Best cost-benefit ratio
Padrão do mercado / Market standard

D+2 - Liquidação em Dois Dias Úteis / Two Business Days Settlement¶

Características: / Features:

💵 Mais barato (menor spread) / Cheapest (lower spread)
🐢 Mais lento (2 dias úteis) / Slower (2 business days)
📊 Melhor para planejamento / Best for planning

Quando Usar: / When to Use:

Cliente não tem urgência / Customer is not in a hurry
Maximizar economia / Maximize savings
Grandes volumes / Large volumes

Comparação de Custos / Cost Comparison¶

Exemplo Prático: Enviar USD 10.000 / Practical Example: Sending USD 10,000

Settlement	Taxa / Rate	Comercial / Commercial	IOF	Tarifa / Fee	Total BRL	Economia / Savings
D0	5.35	R$ 53,500	R$ 588.50	R$ 200	R$ 54,289	-
D+1	5.25	R$ 52,500	R$ 577.50	R$ 150	R$ 53,228	R$ 1,061
D+2	5.20	R$ 52,000	R$ 572.00	R$ 100	R$ 52,672	R$ 1,617

[!TIP] Diferença D0 vs D+2: Economia de R$ 1,617 (3% do valor) simplesmente esperando mais 2 dias! D0 vs D+2 Difference:* Savings of R$ 1,617* (3% of the amount) simply by waiting 2 more days!

Integração Recomendada / Recommended Integration¶

Exemplo de Implementação Completa / Complete Implementation Example¶

class ExchangeRateService {
  constructor(apiClient) {
    this.api = apiClient;
  }

  async getOrderRate(orderId, settlementFlow = null) {
    try {
      let url = `/v1/partner/public/stocks/get-order-rate?orderId=${orderId}`;

      if (settlementFlow !== null) {
        url += `&eSettlementFlow=${settlementFlow}`;
      }

      const response = await this.api.get(url);
      const data = await response.json();

      if (data.success) {
        console.log('✅ Taxa obtida com sucesso');
        return {
          success: true,
          rate: data.data
        };
      } else {
        return {
          success: false,
          errors: data.errors
        };
      }
    } catch (error) {
      console.error('❌ Erro ao obter taxa:', error);
      return {
        success: false,
        errors: [error.message]
      };
    }
  }

  async compareSettlementFlows(orderId) {
    console.log('Comparando fluxos de liquidação...');

    const [d0, d1, d2] = await Promise.all([
      this.getOrderRate(orderId, 1), // D0
      this.getOrderRate(orderId, 2), // D+1
      this.getOrderRate(orderId, 3)  // D+2
    ]);

    return {
      d0: d0.success ? d0.rate : null,
      d1: d1.success ? d1.rate : null,
      d2: d2.success ? d2.rate : null,
      savings: this.calculateSavings(d0.rate, d1.rate, d2.rate)
    };
  }

  calculateSavings(d0Rate, d1Rate, d2Rate) {
    if (!d0Rate || !d1Rate || !d2Rate) return null;

    return {
      d0_vs_d1: d0Rate.amountNC - d1Rate.amountNC,
      d0_vs_d2: d0Rate.amountNC - d2Rate.amountNC,
      d1_vs_d2: d1Rate.amountNC - d2Rate.amountNC
    };
  }

  formatRate(rateData) {
    return {
      displayRate: `R$ ${rateData.rate.toFixed(4)} / ${rateData.currency}`,
      vet: `R$ ${rateData.vet.toFixed(4)} / ${rateData.currency}`,
      total: `R$ ${rateData.amountNC.toLocaleString('pt-BR', { minimumFractionDigits: 2 })}`,
      breakdown: {
        commercial: `R$ ${rateData.commercial.toLocaleString('pt-BR', { minimumFractionDigits: 2 })}`,
        iof: `R$ ${rateData.iof.toLocaleString('pt-BR', { minimumFractionDigits: 2 })} (${rateData.iofPercentage}%)`,
        tariff: `R$ ${rateData.tariff.toLocaleString('pt-BR', { minimumFractionDigits: 2 })}`,
        ir: `R$ ${rateData.ir.toLocaleString('pt-BR', { minimumFractionDigits: 2 })}`
      },
      settlementFlow: this.getSettlementFlowName(rateData.settlementFlow)
    };
  }

  getSettlementFlowName(flow) {
    const names = {
      1: 'D0 - Mesmo Dia',
      2: 'D+1 - Próximo Dia Útil',
      3: 'D+2 - Dois Dias Úteis'
    };
    return names[flow] || 'Desconhecido';
  }
}

Possíveis Erros / Possible Errors¶

Ordem Não Encontrada (404 Not Found) / Order Not Found¶

JSON

{
  "success": false,
  "errors": [
    "Ordem não encontrada",
    "A ordem informada (ID: 789123) não existe no sistema"
  ]
}

Settlement Flow Inválido (400 Bad Request) / Invalid Settlement Flow¶

JSON

{
  "success": false,
  "errors": [
    "Fluxo de liquidação inválido. Use: 1 (D0), 2 (D+1) ou 3 (D+2)."
  ]
}

Ordem em Status Inválido (422 Unprocessable Entity) / Order in Invalid Status¶

JSON

{
  "success": false,
  "errors": [
    "A ordem não está em um status válido para obter taxa",
    "Apenas ordens prontas para cotação podem ter taxas calculadas"
  ]
}

Moeda Não Disponível (503 Service Unavailable) / Currency Not Available¶

JSON

{
  "success": false,
  "errors": [
    "A moeda da ordem não está disponível para cotação no momento",
    "Tente novamente em alguns instantes"
  ]
}

Códigos de Status HTTP / HTTP Status Codes¶

Código / Code	Descrição / Description	Quando Ocorre / When it Occurs
200	OK	Taxa calculada com sucesso / Rate calculated successfully
400	Bad Request	Parâmetros inválidos / Invalid parameters
401	Unauthorized	Token JWT ausente, inválido ou expirado / Missing, invalid or expired token
403	Forbidden	Usuário sem permissão `ADMIN_PARTNER` ou API Key inválida
404	Not Found	Ordem não encontrada / Order not found
422	Unprocessable Entity	Ordem em status inválido / Order in invalid status
503	Service Unavailable	Serviço de taxas temporariamente indisponível / Rates service unavailable
500	Internal Server Error	Erro interno do servidor / Internal server error

Perguntas Frequentes (FAQ) / Frequently Asked Questions¶

1. A taxa retornada é garantida? Is the returned rate guaranteed? R: A taxa retornada é uma simulação válida no momento da consulta. Para garantir a taxa, você deve criar uma cotação oficial usando o token retornado (válido por 10-30 minutos). A:* The returned rate is a simulation valid at the time of inquiry. To guarantee the rate, you must create an official quote* using the returned token (valid for 10-30 minutes).

2. Posso consultar taxas sem ter uma ordem? Can I check rates without having an order? R: Não. Este endpoint requer um orderId válido. A taxa é calculada baseada nos detalhes da ordem (moeda, valor, cliente, etc.). A: No. This endpoint requires a valid orderId. The rate is calculated based on order details (currency, amount, customer, etc.).

3. O que é VET e por que é diferente da taxa comercial? What is VET and why is it different from the commercial rate? R: VET (Valor Efetivo Total) é a taxa real que inclui TODOS os custos: A:* VET (Total Effective Value) is the real* rate that includes ALL costs:

Taxa Comercial = 5.25 (base + spread)
VET = 5.35 (inclui IOF + tarifas)

O VET é a taxa que o cliente efetivamente paga por cada dólar. VET is the rate the customer actually pays for each dollar.

4. Por que D0 é mais caro? Why is D0 more expensive? R: D0 requer liquidação imediata, o que: A: D0 requires immediate settlement, which: * Reduz o tempo do banco para gerenciar o risco cambial / Reduces bank time to manage FX risk * Exige maior disponibilidade de capital / Requires higher capital availability * Limita as oportunidades de hedge / Limits hedge opportunities Por isso, aplica-se spread maior ou tarifa adicional. / Therefore, a higher spread or additional fee is applied.

5. O IOF pode mudar? Can IOF change? R: Sim. O IOF é definido por lei federal e pode ser alterado pelo governo. O sistema sempre retorna o percentual vigente. A: Yes. IOF is defined by federal law and can be changed by the government. The system always returns the current percentage.

6. Quanto tempo o token de segurança é válido? How long is the security token valid for? R: Geralmente 10-30 minutos. Após esse período, você precisará obter uma nova taxa. A: Generally 10-30 minutes. After this period, you will need to obtain a new rate.

7. Posso obter taxas para múltiplas ordens de uma vez? Can I get rates for multiple orders at once? R: Não diretamente. Você precisa fazer uma requisição por ordem. Porém, pode fazer múltiplas requisições em paralelo. A: Not directly. You need to make one request per order. However, you can make multiple requests in parallel.

8. A taxa muda durante o dia? Does the rate change during the day? R: Sim! Taxas de câmbio são voláteis e mudam constantemente conforme o mercado. Por isso é importante: A: Yes! Exchange rates are volatile and change constantly according to the market. Therefore, it is important to: * Obter taxa atualizada antes de exibir ao cliente / Get an updated rate before displaying it to the customer * Criar cotação oficial rapidamente após cliente aceitar / Create an official quote quickly after the customer accepts * Usar o token de segurança para garantir a taxa / Use the security token to guarantee the rate

[!WARNING] VOLATILIDADE CAMBIAL / EXCHANGE VOLATILITY

Taxas de câmbio são extremamente voláteis e podem mudar significativamente em minutos. Sempre: Exchange rates are extremely volatile and can change significantly in minutes. Always:

Obtenha taxa atualizada antes de exibir ao cliente / Get an updated rate before displaying it to the customer

Informe claramente ao cliente sobre a validade da taxa / Clearly inform the customer about the rate's validity

Crie cotação oficial imediatamente após aprovação / Create an official quote immediately after approval

Não garanta taxas sem cotação formal / Do not guarantee rates without a formal quote

[!TIP] SUPORTE TÉCNICO / TECHNICAL SUPPORT

Para dúvidas sobre cálculos de taxas, composição de custos ou integração, entre em contato com nossa equipe de suporte técnico.

For questions about rate calculations, cost composition, or integration, please contact our technical support team.

Para questões sobre políticas de precificação, spreads ou fluxos de liquidação, consulte a equipe de operações.

For questions about pricing policies, spreads, or settlement flows, consult the operations team.