Dados de Referência

📌 Visão Geral / Overview¶

A API de Dados de Referência fornece acesso a informações essenciais necessárias para criar e processar operações de câmbio. Estes endpoints retornam dados de catálogo que devem ser utilizados em outras operações, como criar ordens de câmbio, validar informações bancárias e configurar transações.

The Reference Data API provides access to essential information needed to create and process foreign exchange operations. These endpoints return catalog data that must be used in other operations, such as creating exchange orders, validating banking information, and configuring transactions.

❓ O que são Dados de Referência? / What is Reference Data?¶

Dados de referência são informações estáticas ou semi-estáticas que servem como base para operações mais complexas:

Reference data is static or semi-static information that serves as a basis for more complex operations:

📊 Dados Gerais / General Data¶

Finalidades: Propósitos válidos para transações cambiais
Purposes: Valid purposes for foreign exchange transactions
Países: Lista de países suportados para operações internacionais
Countries: List of supported countries for international operations
Moedas: Moedas disponíveis para operações
Currencies: Available currencies for operations

🏦 Dados Bancários / Banking Data¶

Canais Bancários: Contas e bancos por moeda
Bank Channels: Accounts and banks by currency
Lista de Bancos: Instituições bancárias disponíveis (COMPE)
Bank List: Available banking institutions (COMPE)
Beneficiários: Contas bancárias internacionais cadastradas (Account Banks)
Beneficiaries: Registered international bank accounts (Account Banks)

💱 Dados Cambiais / Exchange Data¶

Taxas de Câmbio: Simulação de taxas para ordens
Exchange Rates: Rate simulation for orders

Estes dados geralmente mudam pouco frequentemente e devem ser cacheados no frontend para melhorar performance.

This data generally changes infrequently and should be cached on the frontend to improve performance.

🔐 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 (ex: 62c45798-3500-47c9-8d0f-4b22effbc70e)
Individualized GUID provided to the partner (e.g.: 62c45798-3500-47c9-8d0f-4b22effbc70e)
Accept-Language: Idioma de resposta (pt-br, en-us ou es-es)
Response language (pt-br, en-us or es-es)

[!WARNING] 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 the above headers are mandatory in all requests. Missing any of them will result in an authentication error.

⚡ Rate Limiting¶

As APIs Públicas possuem limitação de taxa de requisições para garantir estabilidade e disponibilidade do serviço.

Public APIs have request rate limiting to ensure service stability and availability.

[!NOTE] INFORMAÇÃO / INFORMATION

Os limites são aplicados por endereço IP. Cada IP possui contadores independentes.

The limits are applied per IP address. Each IP has independent counters.

Limites Aplicados / Applied Limits¶

Período / Period	Limite / Limit	Descrição / Description
1 segundo / 1 second	3 requisições / 3 requests	Proteção contra picos / Spike protection
1 minuto / 1 minute	30 requisições / 30 requests	Uso normal / Normal use
15 minutos / 15 minutes	100 requisições / 100 requests	Operações em lote / Batch operations
1 hora / 1 hour	300 requisições / 300 requests	Limite por hora / Hourly limit

Headers de Resposta / Response Headers¶

Header	Descrição / Description
`X-RateLimit-Status`	JSON array com status de todas as regras JSON array with the status of all rules
`X-RateLimit-Limit`	Limite da regra mais restritiva (compatibilidade) Limit of the most restrictive rule (compatibility)
`X-RateLimit-Remaining`	Requisições restantes da regra mais restritiva Remaining requests of the most restrictive rule
`Retry-After`	Segundos para aguardar antes de tentar novamente (apenas em 429) Seconds to wait before trying again (only on 429)

Exemplo do Header X-RateLimit-Status / X-RateLimit-Status Header Example¶

JSON

[
  {"period": "1s", "remaining": 2, "limit": 3},
  {"period": "1m", "remaining": 29, "limit": 30},
  {"period": "15m", "remaining": 99, "limit": 100},
  {"period": "1h", "remaining": 299, "limit": 300}
]

Resposta de Limite Excedido (429) / Rate Limit Exceeded Response (429)¶

JSON

{
  "success": false,
  "errors": ["Rate limit exceeded. Retry after X seconds."]
}

[!TIP] BOAS PRÁTICAS / BEST PRACTICES

Implemente retry com exponential backoff

Implement retry with exponential backoff

Distribua requisições ao longo do tempo

Distribute requests over time

Cache dados de referência localmente

Cache reference data locally

Monitore os headers de rate limit nas respostas

Monitor rate limit headers in responses

[!TIP] DICA DE CACHE / CACHE TIP

Os dados de referência (países, moedas, finalidades) mudam raramente. Implemente cache local para reduzir requisições e evitar limites de rate.

Reference data (countries, currencies, purposes) changes rarely. Implement local cache to reduce requests and avoid rate limits.

Endpoint 1: Listar Finalidades / Endpoint 1: List Finalities¶

GET /v1/partner/public/finalities/get-all/{clientType?}/{remmitanceType?}

Obtém a lista de todas as finalidades (propósitos de transação) disponíveis para operações de câmbio, filtradas opcionalmente por tipo de cliente e tipo de remessa.

Retrieves the list of all finalities (transaction purposes) available for foreign exchange operations, optionally filtered by client type and remittance type.

O que é uma Finalidade? / What is a Finality?¶

Uma finalidade define o propósito ou natureza de uma transação cambial. É obrigatória por regulamentação do Banco Central do Brasil e determina:

A finality defines the purpose or nature of a foreign exchange transaction. It is mandatory by the Central Bank of Brazil regulations and determines:

Qual documentação é necessária
What documentation is required
Se há necessidade de emissão de nota fiscal
Whether an invoice needs to be issued
Quais validações de compliance serão aplicadas
Which compliance validations will be applied
Limites e restrições aplicáveis
Applicable limits and restrictions

Parâmetros da URL / URL Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`clientType`	int?	❌	Filtra finalidades por tipo de cliente: 0 = PF (Pessoa Física), 1 = PJ (Pessoa Jurídica). Se omitido, retorna todas. Filters finalities by client type: 0 = PF (Individual), 1 = PJ (Corporate). If omitted, returns all.
`remmitanceType`	int?	❌	Filtra finalidades por tipo de remessa: 0 = INBOUND (Recebimento), 1 = OUTBOUND (Envio), 2 = BOTH (Ambos). Se omitido, retorna todas. Filters finalities by remittance type: 0 = INBOUND (Receiving), 1 = OUTBOUND (Sending), 2 = BOTH (Both). If omitted, returns all.

Exemplo de Requisição / Request Example¶

Obter TODAS as finalidades / Get ALL finalities

cURL

GET /v1/partner/public/finalities/get-all
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

Obter finalidades para Pessoa Jurídica (PJ) / Get finalities for Corporate (PJ)

cURL

GET /v1/partner/public/finalities/get-all/1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

Obter finalidades para operações INBOUND (Recebimento) / Get finalities for INBOUND operations (Receiving)

cURL

GET /v1/partner/public/finalities/get-all/null/0
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

Obter finalidades para operações OUTBOUND (Envio) / Get finalities for OUTBOUND operations (Sending)

cURL

GET /v1/partner/public/finalities/get-all/null/1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

Obter finalidades para PJ com operações INBOUND / Get finalities for Corporate (PJ) with INBOUND operations

cURL

GET /v1/partner/public/finalities/get-all/1/0
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

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

JSON

{
  "success": true,
  "data": [
    {
      "id": 1,
      "description": "Exportação de Mercadorias",
      "invoiceNeed": true,
      "fullDescription": "Recebimento de valores referentes à exportação de bens ou mercadorias para o exterior",
      "personType": 1
    },
    {
      "id": 2,
      "description": "Prestação de Serviços",
      "invoiceNeed": true,
      "fullDescription": "Recebimento de valores referentes à prestação de serviços para empresas ou pessoas no exterior",
      "personType": 0
    },
    {
      "id": 3,
      "description": "Aluguel de Imóveis no Exterior",
      "invoiceNeed": false,
      "fullDescription": "Pagamento de aluguel de propriedades imobiliárias localizadas fora do Brasil",
      "personType": 0
    },
    {
      "id": 4,
      "description": "Manutenção de Residentes",
      "invoiceNeed": false,
      "fullDescription": "Envio de recursos para manutenção de familiares ou dependentes residindo no exterior",
      "personType": 0
    },
    {
      "id": 5,
      "description": "Importação de Mercadorias",
      "invoiceNeed": true,
      "fullDescription": "Pagamento referente à importação de bens ou mercadorias do exterior",
      "personType": 1
    }
  ]
}

Campos da Resposta / Response Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	long	ID único da finalidade - Use este valor ao criar ordens Unique finality ID - Use this value when creating orders
`description`	string	Descrição resumida da finalidade Short description of the finality
`invoiceNeed`	boolean	Indica se requer nota fiscal - `true` = nota fiscal obrigatória, `false` = não requer Indicates if an invoice is required - `true` = mandatory invoice, `false` = not required
`fullDescription`	string	Descrição completa e detalhada da finalidade Complete and detailed description of the finality
`personType`	int (enum)	Tipo de pessoa - `0` = PF (Individual), `1` = PJ (Corporativo) Person type - `0` = PF (Individual), `1` = PJ (Corporate)

[!NOTE] TIPO ENUM / ENUM TYPE

O campo personType é um enum EPersonType que serializa como inteiro no JSON.

The personType field is an EPersonType enum that serializes as an integer in the JSON.

Finalidades Comuns / Common Finalities¶

Para Pessoa Física (PF - personType: 0) / For Individuals (PF - personType: 0)

ID	Finalidade / Finality	Nota Fiscal? / Invoice?	Uso Comum / Common Use
2	Prestação de Serviços Service Provision	✅ Sim / Yes	Freelancers, consultores Freelancers, consultants
3	Aluguel de Imóveis Real Estate Rent	❌ Não / No	Propriedades no exterior Properties abroad
4	Manutenção de Residentes Resident Maintenance	❌ Não / No	Familiares no exterior Family members abroad
6	Educação Education	❌ Não / No	Mensalidades, cursos Tuition, courses
7	Turismo/Viagens Tourism/Travel	❌ Não / No	Gastos em viagens Travel expenses
8	Investimentos Investments	❌ Não / No	Aplicações financeiras Financial investments

Para Pessoa Jurídica (PJ - personType: 1) / For Corporate (PJ - personType: 1)

ID	Finalidade / Finality	Nota Fiscal? / Invoice?	Uso Comum / Common Use
1	Exportação de Mercadorias Export of Goods	✅ Sim / Yes	Venda de produtos Sale of products
5	Importação de Mercadorias Import of Goods	✅ Sim / Yes	Compra de produtos Purchase of products
9	Serviços Técnicos Technical Services	✅ Sim / Yes	Consultorias, TI Consulting, IT
10	Royalties Royalties	✅ Sim / Yes	Licenças, patentes Licenses, patents
11	Fretes Internacionais International Freight	✅ Sim / Yes	Transporte de cargas Cargo transport
12	Empréstimos/Financiamentos Loans/Financing	❌ Não / No	Operações de crédito Credit operations

📌 Filtro por Tipo de Remessa / Remittance Type Filter¶

O parâmetro remmitanceType permite filtrar as finalidades de acordo com o tipo de operação cambial:

The remmitanceType parameter allows filtering finalities according to the type of foreign exchange operation:

Valor / Value	Tipo / Type	Descrição / Description	Quando Usar / When to Use
0	INBOUND	Recebimento (do exterior para o Brasil) Receiving (from abroad to Brazil)	Para ordens de recebimento de valores do exterior For orders receiving funds from abroad
1	OUTBOUND	Envio (do Brasil para o exterior) Sending (from Brazil to abroad)	Para ordens de envio de valores para o exterior For orders sending funds abroad
2	BOTH	Ambos os tipos Both types	Finalidades que se aplicam tanto para recebimento quanto envio Finalities that apply to both receiving and sending

💡 Exemplos Práticos: / Practical Examples:¶

Cenário 1: Sistema de Exportação / Scenario 1: Export System

cURL

# Buscar apenas finalidades para empresas que estão RECEBENDO do exterior
# Fetch only finalities for companies that are RECEIVING from abroad
GET /v1/partner/public/finalities/get-all/1/0

Retornará finalidades como "Exportação de Mercadorias", "Prestação de Serviços para o Exterior", etc.

Will return finalities like "Export of Goods", "Service Provision Abroad", etc.

Cenário 2: Sistema de Importação / Scenario 2: Import System

cURL

# Buscar apenas finalidades para empresas que estão ENVIANDO para o exterior
# Fetch only finalities for companies that are SENDING abroad
GET /v1/partner/public/finalities/get-all/1/1

Retornará finalidades como "Importação de Mercadorias", "Pagamento de Serviços", etc.

Will return finalities like "Import of Goods", "Payment for Services", etc.

Cenário 3: Sistema Multi-propósito / Scenario 3: Multi-purpose System

cURL

# Buscar todas as finalidades disponíveis para pessoa física
# Fetch all available finalities for individuals
GET /v1/partner/public/finalities/get-all/0

Retornará todas as finalidades de PF, independente do tipo de remessa.

Will return all PF finalities, regardless of remittance type.

⚠️ Notas Importantes: / Important Notes:¶

Finalidades Específicas: Algumas finalidades são exclusivas para INBOUND ou OUTBOUND, enquanto outras podem ser usadas em ambos os cenários (BOTH).
Specific Finalities: Some finalities are exclusive to INBOUND or OUTBOUND, while others can be used in both scenarios (BOTH).
Validação no Backend: Mesmo que uma finalidade seja retornada na listagem, o sistema ainda validará se ela é apropriada para a operação específica que você está criando.
Backend Validation: Even if a finality is returned in the list, the system will still validate whether it is appropriate for the specific operation you are creating.
Otimização de Performance: Use os filtros para reduzir a quantidade de dados retornados e melhorar a experiência do usuário no front-end.
Performance Optimization: Use the filters to reduce the amount of returned data and improve the user experience on the front-end.

Erros Possíveis / Possible Errors¶

Cliente Type Inválido (400 Bad Request) / Invalid Client Type (400 Bad Request)

JSON

{
  "success": false,
  "errors": [
    "Tipo de cliente inválido. Use 0 para PF ou 1 para PJ."
  ]
}

Remittance Type Inválido (400 Bad Request) / Invalid Remittance Type (400 Bad Request)

JSON

{
  "success": false,
  "errors": [
    "Tipo de remessa inválido. Use 0 para INBOUND, 1 para OUTBOUND ou 2 para BOTH."
  ]
}

Erro do Servidor (500 Internal Server Error) / Server Error (500 Internal Server Error)

JSON

{
  "success": false,
  "errors": [
    "An error occurred while retrieving finalities.",
    "Detalhes do erro..."
  ]
}

Endpoint 2: Listar Países / Endpoint 2: List Countries¶

GET /v1/partner/public/countries/get-all

Obtém a lista de todos os países disponíveis para operações de câmbio internacional.

Retrieves the list of all available countries for international foreign exchange operations.

Para que serve? / What is it for?¶

A lista de países é essencial para:

The country list is essential to:

Identificar origem/destino de pagamentos internacionais
Identify the origin/destination of international payments
Validar contas bancárias (cada país tem requisitos específicos)
Validate bank accounts (each country has specific requirements)
Aplicar regras de compliance e sanções
Apply compliance rules and sanctions
Determinar taxas e tarifas aplicáveis
Determine applicable rates and fees

Parâmetros / Parameters¶

Nenhum parâmetro é necessário. O endpoint retorna todos os países cadastrados.

No parameters are required. The endpoint returns all registered countries.

Exemplo de Requisição / Request Example¶

cURL

GET /v1/partner/public/countries/get-all
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

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

JSON

{
  "success": true,
  "data": [
    {
      "id": 840,
      "description": "United States"
    },
    {
      "id": 124,
      "description": "Canada"
    },
    {
      "id": 826,
      "description": "United Kingdom"
    },
    {
      "id": 276,
      "description": "Germany"
    },
    {
      "id": 250,
      "description": "France"
    },
    {
      "id": 392,
      "description": "Japan"
    },
    {
      "id": 156,
      "description": "China"
    },
    {
      "id": 36,
      "description": "Australia"
    },
    {
      "id": 380,
      "description": "Italy"
    },
    {
      "id": 724,
      "description": "Spain"
    }
  ]
}

Campos da Resposta / Response Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	long	Código ISO 3166-1 numérico do país - Use este valor ao criar ordens Numeric ISO 3166-1 code of the country - Use this value when creating orders
`description`	string	Nome do país em inglês *Country name in English*

[!TIP] DICA / TIP

O id corresponde ao código ISO 3166-1 numérico internacional. Por exemplo: The id corresponds to the international numeric ISO 3166-1 code. For example:

840 = United States (US)

124 = Canada (CA)

826 = United Kingdom (GB)

276 = Germany (DE)

Principais Países por Região / Main Countries by Region¶

América do Norte / North America * 840 - United States * 124 - Canada * 484 - Mexico

Europa / Europe * 826 - United Kingdom * 276 - Germany * 250 - France * 380 - Italy * 724 - Spain * 528 - Netherlands * 756 - Switzerland

Ásia / Asia * 392 - Japan * 156 - China * 344 - Hong Kong * 702 - Singapore * 410 - South Korea

Oceania / Oceania * 36 - Australia * 554 - New Zealand

América do Sul / South America * 32 - Argentina * 152 - Chile * 170 - Colombia * 858 - Uruguay * 600 - Paraguay

Erros Possíveis / Possible Errors¶

Erro do Servidor (500 Internal Server Error) / Server Error (500 Internal Server Error)

JSON

{
  "success": false,
  "errors": [
    "An error occurred while retrieving countries.",
    "Detalhes do erro..."
  ]
}

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

JSON

{
  "success": true,
  "data": [
    {
      "id": 1,
      "description": "USD"
    },
    {
      "id": 2,
      "description": "EUR"
    },
    {
      "id": 3,
      "description": "GBP"
    },
    {
      "id": 4,
      "description": "CHF"
    },
    {
      "id": 5,
      "description": "AUD"
    },
    {
      "id": 6,
      "description": "CAD"
    },
    {
      "id": 7,
      "description": "NZD"
    },
    {
      "id": 8,
      "description": "JPY"
    },
    {
      "id": 9,
      "description": "ZAR"
    },
    {
      "id": 10,
      "description": "DKK"
    }
  ]
}

Endpoint 3: Listar Moedas / Endpoint 3: List Currencies¶

GET /v1/partner/public/currencies/get-all

Obtém a lista de todas as moedas disponíveis para operações de câmbio.

Retrieves the list of all available currencies for foreign exchange operations.

Para que serve? / What is it for?¶

A lista de moedas define:

The currency list defines:

Quais moedas estão disponíveis para negociação
Which currencies are available for trading
Códigos ISO para cada moeda
ISO codes for each currency
IDs únicos para usar ao criar ordens
Unique IDs to use when creating orders

Parâmetros / Parameters¶

Nenhum parâmetro é necessário. O endpoint retorna todas as moedas cadastradas.

No parameters are required. The endpoint returns all registered currencies.

Exemplo de Requisição / Request Example¶

cURL

GET /v1/partner/public/currencies/get-all
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

Campos da Resposta / Response Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	long	ID único da moeda - Use este valor ao criar ordens Unique currency ID - Use this value when creating orders
`description`	string	Código ISO 4217 da moeda (USD, EUR, GBP, etc.) ISO 4217 code of the currency (USD, EUR, GBP, etc.)

Moedas Disponíveis / Available Currencies¶

ID	Código / Code	Nome Completo / Full Name	Região / Region
1	USD	Dólar Americano US Dollar	Estados Unidos United States
2	EUR	Euro Euro	União Europeia European Union
3	GBP	Libra Esterlina British Pound	Reino Unido United Kingdom
4	CHF	Franco Suíço Swiss Franc	Suíça Switzerland
5	AUD	Dólar Australiano Australian Dollar	Austrália Australia
6	CAD	Dólar Canadense Canadian Dollar	Canadá Canada
7	NZD	Dólar Neozelandês New Zealand Dollar	Nova Zelândia New Zealand
8	JPY	Iene Japonês Japanese Yen	Japão Japan
9	ZAR	Rand Sul-Africano South African Rand	África do Sul South Africa
10	DKK	Coroa Dinamarquesa Danish Krone	Dinamarca Denmark
11	NOK	Coroa Norueguesa Norwegian Krone	Noruega Norway
12	SEK	Coroa Sueca Swedish Krona	Suécia Sweden
13	MXN	Peso Mexicano Mexican Peso	México Mexico

Moedas Mais Negociadas / Most Traded Currencies¶

USD (ID: 1) - Aproximadamente 90% das operações
USD (ID: 1) - Approximately 90% of operations
EUR (ID: 2) - Segunda moeda mais negociada
EUR (ID: 2) - Second most traded currency
GBP (ID: 3) - Popular para operações com UK
GBP (ID: 3) - Popular for operations with the UK
CAD (ID: 6) - Comum para América do Norte
CAD (ID: 6) - Common for North America
JPY (ID: 8) - Operações com Ásia
JPY (ID: 8) - Operations with Asia

Erros Possíveis / Possible Errors¶

Erro do Servidor (500 Internal Server Error) / Server Error (500 Internal Server Error)

JSON

{
  "success": false,
  "errors": [
    "An error occurred while retrieving currencies.",
    "Detalhes do erro..."
  ]
}

Endpoint 4: Obter Canais Bancários por Moeda / Endpoint 4: Get Bank Channels by Currency¶

GET /v1/partner/public/currencies/bank-channels

Obtém informações detalhadas sobre os canais bancários disponíveis para uma moeda específica, incluindo dados de contas bancárias que podem ser usadas para operações.

Retrieves detailed information about the bank channels available for a specific currency, including bank account data that can be used for operations.

Para que serve? / What is it for?¶

Este endpoint fornece:

This endpoint provides:

Contas bancárias disponíveis para receber/enviar a moeda específica
Available bank accounts to receive/send the specific currency
Informações bancárias completas (nome, número, SWIFT, etc.)
Complete banking information (name, number, SWIFT, etc.)
Taxas e tarifas específicas por canal
Specific fees and rates per channel
Dados contextualizados por cliente (quando clientId é fornecido)
Contextualized data per client (when clientId is provided)

Parâmetros de Query / Query Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`currency`	string	✅	Código ISO da moeda (USD, EUR, GBP, etc.) ISO code of the currency (USD, EUR, GBP, etc.)
`clientId`	string (GUID)	❌	ID público do cliente no formato GUID (para obter canais específicos do cliente) Public client ID in GUID format (to get client-specific channels)
`clientType`	int?	❌	Tipo de cliente: 0 = PF, 1 = PJ Client type: 0 = PF (Individual), 1 = PJ (Corporate)

Exemplo de Requisição / Request Example¶

Obter canais para USD (sem contexto de cliente) / Get channels for USD (without client context)

cURL

GET /v1/partner/public/currencies/bank-channels?currency=USD
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

Obter canais para EUR com contexto de cliente PF / Get channels for EUR with Individual (PF) client context

cURL

GET /v1/partner/public/currencies/bank-channels?currency=EUR&clientId=a1b2c3d4-5678-90ab-cdef-1234567890ab&clientType=0
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

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

JSON

{
  "success": true,
  "data": {
    "id": 1,
    "description": "USD",
    "beneficiaries": [
      {
        "id": 101,
        "account": "1234567890",
        "reference": "REF001",
        "clientName": "XaviPay HomeBroker LLC"
      }
    ],
    "beneficiaryBankChannels": [
      {
        "id": 201,
        "bank": "Chase Bank",
        "swift": "CHASUS33XXX",
        "address": "270 Park Avenue, New York, NY 10017, USA"
      },
      {
        "id": 202,
        "bank": "Bank of America",
        "swift": "BOFAUS3NXXX",
        "address": "100 North Tryon Street, Charlotte, NC 28255, USA"
      }
    ],
    "intermediaryBankChannels": [
      {
        "id": 301,
        "bank": "Citibank",
        "swift": "CITIUS33XXX",
        "account": "9876543210",
        "address": "388 Greenwich Street, New York, NY 10013, USA"
      }
    ]
  }
}

Campos da Resposta Principal / Main Response Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	long	ID único da moeda no sistema Unique currency ID in the system
`description`	string	Código ISO da moeda (USD, EUR, etc.) ISO code of the currency (USD, EUR, etc.)
`beneficiaries`	array	Lista de beneficiários associados à moeda *List of beneficiaries associated with the currency*
`beneficiaryBankChannels`	array	Lista de canais bancários dos beneficiários *List of beneficiary bank channels*
`intermediaryBankChannels`	array	Lista de canais bancários intermediários *List of intermediary bank channels*

Campos de Beneficiary / Beneficiary Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	long	ID único do beneficiário Unique ID of the beneficiary
`account`	string	Número da conta do beneficiário Beneficiary's account number
`reference`	string	Referência do beneficiário Beneficiary reference
`clientName`	string	Nome do cliente beneficiário Beneficiary client name

Campos de Beneficiary Bank Channel / Beneficiary Bank Channel Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	long	ID único do canal bancário do beneficiário Unique ID of the beneficiary bank channel
`bank`	string	Nome do banco do beneficiário Beneficiary bank name
`swift`	string	Código SWIFT/BIC do banco Bank's SWIFT/BIC code
`address`	string	Endereço completo do banco Complete bank address

Campos de Intermediary Bank Channel / Intermediary Bank Channel Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	long	ID único do canal bancário intermediário Unique ID of the intermediary bank channel
`bank`	string	Nome do banco intermediário Intermediary bank name
`swift`	string	Código SWIFT/BIC do banco intermediário Intermediary bank's SWIFT/BIC code
`account`	string	Conta do banco intermediário Intermediary bank account
`address`	string	Endereço do banco intermediário Intermediary bank address

[!NOTE] SOBRE BENEFICIÁRIOS E CANAIS BANCÁRIOS / ABOUT BENEFICIARIES AND BANK CHANNELS

Beneficiaries: Contêm informações sobre as contas de destino para operações

Contain information about destination accounts for operations

Beneficiary Bank Channels: Bancos dos beneficiários com códigos SWIFT para transferências

Beneficiary banks with SWIFT codes for transfers

Intermediary Bank Channels: Bancos intermediários quando necessário para roteamento internacional

Intermediary banks when necessary for international routing

Quando Usar este Endpoint / When to Use this Endpoint¶

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

Precisar exibir contas bancárias para o usuário escolher
You need to display bank accounts for the user to choose
Calcular taxas e tarifas antes de criar uma ordem
Calculating fees and rates before creating an order
Validar se uma moeda tem canais disponíveis
Validating if a currency has available channels
Obter informações bancárias para instruções de pagamento
Obtaining banking information for payment instructions

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

Listar apenas códigos de moedas (use /currencies/get-all)
Listing only currency codes (use /currencies/get-all)
Operações que não precisam de dados bancários detalhados
Operations that do not require detailed banking data

Erros Possíveis / Possible Errors¶

Moeda Não Encontrada (404 Not Found) / Currency Not Found (404 Not Found)

JSON

{
  "success": false,
  "errors": [
    "Moeda não encontrada ou não disponível para operações.",
    "Código da moeda: XYZ"
  ]
}

Sem Canais Disponíveis (404 Not Found) / No Channels Available (404 Not Found)

JSON

{
  "success": false,
  "errors": [
    "Nenhum canal bancário disponível para a moeda solicitada."
  ]
}

Parâmetro Inválido (400 Bad Request) / Invalid Parameter (400 Bad Request)

JSON

{
  "success": false,
  "errors": [
    "Código de moeda inválido. Use códigos ISO 4217 válidos (USD, EUR, GBP, etc.)."
  ]
}

Erro do Servidor (500 Internal Server Error) / Server Error (500 Internal Server Error)

JSON

{
  "success": false,
  "errors": [
    "An error occurred while retrieving bank channels.",
    "Detalhes do erro..."
  ]
}

Endpoint 5: Listar Bancos Disponíveis / Endpoint 5: List Available Banks¶

GET /v1/partner/public/dashboard-integration/get-bank-list

Retorna a lista completa de todos os bancos disponíveis no sistema através da integração com o Dashboard do Banco Central.

Returns the complete list of all available banks in the system through integration with the Central Bank Dashboard.

Para que serve? / What is it for?¶

A lista de bancos é essencial para:

The bank list is essential to:

Criar contas bancárias para ordens outbound
Create bank accounts for outbound orders
Validar informações bancárias de beneficiários
Validate beneficiary banking information
Apresentar opções de bancos aos usuários
Present bank options to users
Identificar instituições pelo código COMPE
Identify institutions by COMPE code

Parâmetros / Parameters¶

Nenhum parâmetro é necessário. O endpoint retorna todos os bancos cadastrados e ativos.

No parameters are required. The endpoint returns all registered and active banks.

Exemplo de Requisição / Request Example¶

cURL

GET /v1/partner/public/dashboard-integration/get-bank-list
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Role: ADMIN_PARTNER
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

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

Erro do Servidor (500 Internal Server Error) / Server Error (500 Internal Server Error)

JSON

{
  "success": false,
  "errors": [
    "An error occurred while retrieving bank channels.",
    "Detalhes do erro..."
  ]
}

Endpoint 5: Listar Bancos Disponíveis / Endpoint 5: List Available Banks¶

GET /v1/partner/public/dashboard-integration/get-bank-list

Retorna a lista completa de todos os bancos disponíveis no sistema através da integração com o Dashboard do Banco Central.

Returns the complete list of all available banks in the system through integration with the Central Bank Dashboard.

Para que serve? / What is it for?¶

A lista de bancos é essencial para:

The bank list is essential to:

Criar contas bancárias para ordens outbound
Create bank accounts for outbound orders
Validar informações bancárias de beneficiários
Validate beneficiary banking information
Apresentar opções de bancos aos usuários
Present bank options to users
Identificar instituições pelo código COMPE
Identify institutions by COMPE code

Parâmetros / Parameters¶

Nenhum parâmetro é necessário. O endpoint retorna todos os bancos cadastrados e ativos.

No parameters are required. The endpoint returns all registered and active banks.

Exemplo de Requisição / Request Example¶

cURL

GET /v1/partner/public/dashboard-integration/get-bank-list
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Role: ADMIN_PARTNER
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

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

Campos da Resposta / Response Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	integer	Identificador único do banco no sistema Unique identifier of the bank in the system
`code`	string	Código COMPE - Código oficial do banco no Brasil COMPE Code - Official bank code in Brazil
`name`	string	Nome oficial completo da instituição bancária Full official name of the banking institution
`shortName`	string	Nome abreviado ou popular do banco Abbreviated or popular name of the bank

[!NOTE] SOBRE O CÓDIGO COMPE / ABOUT THE COMPE CODE

O código retornado no campo code é o código COMPE (Código do Sistema de Operações Monetárias e Compensação de Outros Papéis), padrão oficial brasileiro para identificação de instituições bancárias.

The code returned in the code field is the COMPE code (Code of the System of Monetary Operations and Compensation of Other Papers), the official Brazilian standard for identifying banking institutions.

Principais Bancos Brasileiros / Main Brazilian Banks¶

Código / Code	Nome / Name	Nome Curto / Short Name
001	Banco do Brasil S.A.	BB
104	Caixa Econômica Federal	CEF
237	Banco Bradesco S.A.	Bradesco
341	Itaú Unibanco S.A.	Itaú
033	Banco Santander (Brasil) S.A.	Santander
260	Nu Pagamentos S.A.	Nubank
077	Banco Inter S.A.	Inter
212	Banco Original S.A.	Original
422	Banco Safra S.A.	Saf

Erros Possíveis / Possible Errors¶

Erro do Servidor (500 Internal Server Error) / Server Error (500 Internal Server Error)

JSON

{
  "success": false,
  "errors": [
    "An error occurred while retrieving bank list.",
    "Detalhes do erro..."
  ]
}

Endpoint 6: Obter Taxas de Câmbio Atuais / Endpoint 6: Get Current Exchange Rates¶

GET /v1/partner/public/stocks

Retorna as taxas de câmbio em tempo real para uma ou todas as moedas disponíveis. Este endpoint é ideal para exibir cotações atualizadas aos seus clientes.

Returns real-time exchange rates for one or all available currencies. This endpoint is ideal for displaying up-to-date quotes to your clients.

Para que serve? / What is it for?¶

Este endpoint permite:

This endpoint allows:

💱 Consultar taxas em tempo real para todas as moedas ou uma moeda específica
💱 Consult real-time rates for all currencies or a specific currency
📊 Exibir cotações atualizadas em dashboards e interfaces
📊 Display updated quotes on dashboards and interfaces
🔍 Filtrar por moeda (USD, EUR, GBP, etc.)
🔍 Filter by currency (USD, EUR, GBP, etc.)
📈 Aplicar spread bancário opcionalmente
📈 Apply bank spread optionally

Quando Usar / When to Use¶

✅ Este endpoint deve ser usado para: / This endpoint should be used to:

Exibir taxas de câmbio em tempo real para clientes
Display real-time exchange rates for clients
Dashboards com cotações atualizadas
Dashboards with updated quotes
Calculadoras de câmbio
Exchange calculators
Comparação de taxas entre moedas
Rate comparison between currencies

❌ Este endpoint não pode ser usado para: / This endpoint cannot be used to:

Criar cotações oficiais (use endpoint /quotation)
Create official quotes (use endpoint /quotation)
Calcular valores totais com impostos (use /get-order-rate)
Calculate total values with taxes (use /get-order-rate)
Obter taxas históricas
Obtain historical rates

Parâmetros de Query / Query Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`symbol`	string	❌	Símbolo da moeda (USD, EUR, GBP, etc.). Se omitido, retorna todas as moedas. Currency symbol (USD, EUR, GBP, etc.). If omitted, returns all currencies.
`useSpread`	boolean	❌	Se deve aplicar spread bancário às taxas. Padrão: `false` Whether to apply bank spread to the rates. Default: `false`

[!NOTE] CACHE

As taxas são cacheadas por 1 minuto no servidor. Requisições dentro deste período retornam os mesmos valores.

Rates are cached for 1 minute on the server. Requests within this period return the same values.

Exemplo de Requisição / Request Example¶

Exemplo 1: Obter todas as moedas (sem spread) / Example 1: Get all currencies (no spread)

cURL

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

Exemplo 2: Obter apenas USD (sem spread) / Example 2: Get only USD (no spread)

cURL

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

Exemplo 3: Obter EUR com spread bancário aplicado / Example 3: Get EUR with bank spread applied

cURL

GET /v1/partner/public/stocks?symbol=EUR&useSpread=true
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

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

Resposta para todas as moedas: / Response for all currencies:

JSON

{
  "success": true,
  "data": [
    {
      "ask": "5.9250",
      "bid": "5.9150",
      "askCurrencyPair": "USD.BRL",
      "bidCurrencyPair": "BRL.USD",
      "valueDate": "2025-12-15T14:30:00Z",
      "type": "SPOT",
      "tradeDescription": "USD to BRL Spot Rate",
      "symbol": "USD",
      "expiresIn": "60"
    },
    {
      "ask": "6.4820",
      "bid": "6.4720",
      "askCurrencyPair": "EUR.BRL",
      "bidCurrencyPair": "BRL.EUR",
      "valueDate": "2025-12-15T14:30:00Z",
      "type": "SPOT",
      "tradeDescription": "EUR to BRL Spot Rate",
      "symbol": "EUR",
      "expiresIn": "60"
    },
    {
      "ask": "7.3510",
      "bid": "7.3410",
      "askCurrencyPair": "GBP.BRL",
      "bidCurrencyPair": "BRL.GBP",
      "valueDate": "2025-12-15T14:30:00Z",
      "type": "SPOT",
      "tradeDescription": "GBP to BRL Spot Rate",
      "symbol": "GBP",
      "expiresIn": "60"
    }
  ]
}

Resposta para moeda específica (USD): / Response for specific currency (USD):

JSON

{
  "success": true,
  "data": [
    {
      "ask": "5.9250",
      "bid": "5.9150",
      "askCurrencyPair": "USD.BRL",
      "bidCurrencyPair": "BRL.USD",
      "valueDate": "2025-12-15T14:30:00Z",
      "type": "SPOT",
      "tradeDescription": "USD to BRL Spot Rate",
      "symbol": "USD",
      "expiresIn": "60"
    }
  ]
}

Campos da Resposta / Response Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`ask`	string	Taxa de compra (Ask) - Use esta taxa quando o cliente compra moeda estrangeira Buy rate (Ask) - Use this rate when the client buys foreign currency
`bid`	string	Taxa de venda (Bid) - Use esta taxa quando o cliente vende moeda estrangeira Sell rate (Bid) - Use this rate when the client sells foreign currency
`askCurrencyPair`	string	Par de moedas para Ask (ex: USD.BRL = comprar USD com BRL) Currency pair for Ask (e.g., USD.BRL = buy USD with BRL)
`bidCurrencyPair`	string	Par de moedas para Bid (ex: BRL.USD = vender USD por BRL) Currency pair for Bid (e.g., BRL.USD = sell USD for BRL)
`valueDate`	string	Data de validade da taxa (ISO 8601) Expiration date of the rate (ISO 8601)
`type`	string	Tipo de taxa (SPOT = à vista, SPREAD = com margem aplicada) Rate type (SPOT = cash/spot, SPREAD = with margin applied)
`tradeDescription`	string	Descrição da operação *Operation description*
`symbol`	string	Símbolo da moeda (USD, EUR, GBP, etc.) Currency symbol (USD, EUR, GBP, etc.)
`expiresIn`	string	Tempo de expiração em segundos (geralmente 60s) Expiration time in seconds (usually 60s)

Conceitos Importantes / Important Concepts¶

⚖️ Ask vs Bid¶

Ask (Compra): Taxa quando você compra moeda estrangeira
Ask (Buy):* Rate when you buy* foreign currency
- Exemplo: Cliente quer enviar dinheiro para o exterior (compra USD com BRL)
- Example: Client wants to send money abroad (buys USD with BRL)
- Use ask para operações outbound
- Use ask for outbound operations
Bid (Venda): Taxa quando você vende moeda estrangeira
Bid (Sell):* Rate when you sell* foreign currency
- Exemplo: Cliente recebe dinheiro do exterior (vende USD por BRL)
- Example: Client receives money from abroad (sells USD for BRL)
- Use bid para operações inbound
- Use bid for inbound operations

📊 Spread Bancário / Bank Spread¶

Quando useSpread=true: * O sistema aplica a margem bancária sobre a taxa base * The system applies the bank margin over the base rate * O valor retornado já inclui o spread * The returned value already includes the spread * Campo type muda para "SPREAD" * The type field changes to "SPREAD"

Quando useSpread=false (padrão / default): * Retorna a taxa pura do mercado * Returns the pure market rate * Sem margem aplicada * No margin applied * Campo type é "SPOT" * The type field is "SPOT"

Erros Possíveis / Possible Errors¶

Moeda Não Encontrada (404 Not Found) / Currency Not Found (404 Not Found)

JSON

{
  "success": false,
  "errors": [
    "Moeda não encontrada ou não disponível",
    "Símbolo informado: XYZ"
  ]
}

Causa: Símbolo de moeda inválido ou não suportado. Cause: Invalid or unsupported currency symbol.

Solução: Use apenas moedas válidas. Consulte /currencies/get-all para ver moedas disponíveis. Solution: Use only valid currencies. Check /currencies/get-all to see available currencies.

Símbolo Inválido (400 Bad Request) / Invalid Symbol (400 Bad Request)

JSON

{
  "success": false,
  "errors": [
    "Simbolo de moeda inválido"
  ]
}

Erro do Servidor (500 Internal Server Error) / Server Error (500 Internal Server Error)

JSON

{
  "success": false,
  "errors": [
    "An error occurred while retrieving exchange rates.",
    "Detalhes do erro..."
  ]
}

Endpoint 7: Obter Taxa de Câmbio para Ordem Específica (Simulação) / Endpoint 7: Get Exchange Rate for Specific Order (Simulation)¶

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. Este é um endpoint de simulação que não cria cotação oficial.

Obtains the exchange rate and complete calculations for a specific order, including taxes, fees, and total amount. This is a simulation endpoint that does not create an official quote.

Para que serve? / What is it for?¶

Este endpoint permite:

This endpoint allows:

💱 Simular taxa de câmbio em tempo real para uma ordem
💱 Simulate exchange rate in real-time for an order
💰 Calcular todos os custos (IOF, IR, tarifas)
💰 Calculate all costs (IOF, IR, fees)
📊 Exibir VET (Valor Efetivo Total) para o cliente
📊 Display VET (Total Effective Value) to the customer
🔐 Gerar token de segurança para criar cotação oficial depois
🔐 Generate a security token to create an official quote later

Quando Usar / When to Use¶

✅ Este endpoint deve ser usado para: / This endpoint should be used to:

Exibir simulação de câmbio para o cliente antes de confirmar
Display exchange simulation to the customer before confirming
Calcular valor total antes de criar cotação oficial
Calculate total value before creating an official quote
Obter token para usar no endpoint /quotation
Obtain a token to use in the /quotation endpoint

❌ Este endpoint não pode ser usado para: / This endpoint cannot be used to:

Criar cotações oficiais (use endpoint /quotation)
Create official quotes (use endpoint /quotation)
Consultar taxas históricas
Consult historical rates
Obter taxas sem ordem associada
Obtain 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 order ID* for which the rate will be calculated
`eSettlementFlow`	int (enum)?	❌	Fluxo de liquidação (opcional): 1 = D0, 2 = D+1, 3 = D+2 Settlement flow* (optional): 1 = D0, 2 = D+1, 3* = D+2

[!NOTE] SOBRE SETTLEMENT FLOW / ABOUT SETTLEMENT FLOW

Este parâmetro é opcional. Quando não informado, o sistema usa o fluxo padrão configurado para a ordem.

This parameter is optional. When not provided, the system uses the default flow configured for the order.

Exemplo de Requisição / Request Example¶

Exemplo 1: Sem especificar Settlement Flow (usa padrão da ordem) / Example 1: Without specifying Settlement Flow (uses order default)

cURL

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

Exemplo 2: Especificando D+1 Settlement Flow / Example 2: Specifying D+1 Settlement Flow

cURL

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

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": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "taxId": 15,
    "settlementFlow": 2,
    "currency": "USD"
  }
}

Campos da Resposta / Response Fields¶

Valores Principais / Main Values¶

Campo / Field	Tipo / Type	Descrição / Description
`amount`	decimal	Valor em moeda estrangeira *Foreign currency amount*
`amountNC`	decimal	Valor em moeda nacional (BRL) - valor final National currency amount (BRL) - final value
`currency`	string	Código ISO da moeda *ISO currency code*

Taxa de Câmbio / Exchange Rate¶

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

Impostos e Taxas / Taxes and Fees¶

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

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 (enum)	Fluxo de liquidação: 1=D0, 2=D+1, 3=D+2 Settlement flow: 1=D0, 2=D+1, 3=D+2
`commercial`	decimal	Valor comercial (amount × rate) Commercial value (amount × rate)
`total`	decimal	Valor total final (igual a amountNC) Final total value (same as amountNC)

[!IMPORTANT] 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.

[!WARNING] SIMULAÇÃO VS COTAÇÃO OFICIAL / SIMULATION VS OFFICIAL QUOTE

Este endpoint retorna uma simulação da taxa. Para garantir a taxa, você deve criar uma cotação oficial usando o endpoint POST /orders/quotation com o token retornado.

This endpoint returns a simulation of the rate. To guarantee the rate, you must create an official quote using the POST /orders/quotation endpoint with the returned token.

Conceitos Importantes / Important Concepts¶

♻️ VET (Valor Efetivo Total)¶

O VET é a taxa real que inclui TODOS os custos: The VET is the actual 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 unidade da moeda estrangeira. VET is the rate the customer actually pays for each unit of foreign currency.

Cálculo do VET / VET Calculation: $$VET = amountNC \div amount = 53500 \div 10000 = 5.35 \text{ BRL/USD}$$

📊 Spread (Margem de Lucro) / Spread (Profit Margin)¶

O spread é a margem de lucro aplicada sobre a taxa base: The spread is the profit margin applied over the base rate:

Valor: 0.0 a 1.0 (representando 0% a 100%)
Value: 0.0 to 1.0 (representing 0% to 100%)
Exemplo: spread: 0.02 = 2% de margem
Example: spread: 0.02 = 2% margin
Cálculo: Taxa final = Taxa base $\times$ (1 + spread)
Calculation: Final rate = Base rate $\times$ (1 + spread)

🏛️ IOF (Imposto sobre Operações Financeiras) / IOF (Tax on Financial Operations)¶

O IOF é um imposto federal obrigatório: The IOF is a mandatory federal tax:

Inbound (Recebimento): Geralmente 0.38%
Inbound (Receipt): Usually 0.38%
Outbound (Envio): Geralmente 1.1%
Outbound (Sending): Usually 1.1%
Cálculo: Automático pelo sistema
Calculation: Automatic by the system
Importante: O percentual pode ser alterado pelo governo
Important: The percentage can be changed by the government

🗓️ Settlement Flow (Fluxo de Liquidação) / Settlement Flow¶

O Settlement Flow define quando a operação será liquidada: The Settlement Flow defines when the operation will be settled:

D0 (1): Liquidação no mesmo dia da operação
D0 (1): Settlement on the same day as the operation
D+1 (2): Liquidação no dia útil seguinte
D+1 (2): Settlement on the next business day
D+2 (3): Liquidação em dois dias úteis
D+2 (3): Settlement in two business days

[!TIP] IMPORTANTE / IMPORTANT

Fluxos com liquidação mais rápida (D0) podem ter taxas diferentes devido ao custo operacional e risco cambial.

Faster settlement flows (D0) may have different rates due to operational costs and exchange risk.

Erros Possíveis / Possible Errors¶

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

JSON

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

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

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"
  ]
}

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

JSON

{
  "success": false,
  "errors": [
    "Settlement Flow inválido",
    "Valores válidos: 1 (D0), 2 (D+1), 3 (D+2)"
  ]
}

Estratégia de Caching Recomendada / Recommended Caching Strategy¶

Dados Estáticos (Cache Longo) / Static Data (Long Cache)¶

Endpoint	TTL Sugerido / Suggested TTL	Quando Invalidar / When to Invalidate
`/finalities/get-all`	24 horas / 24 hours	Mudanças regulatórias (raro) Regulatory changes (rare)
`/countries/get-all`	7 dias / 7 days	Novos países adicionados (muito raro) New countries added (very rare)
`/currencies/get-all`	24 horas / 24 hours	Novas moedas disponíveis (raro) New currencies available (rare)
`/dashboard-integration/get-bank-list`	7 dias / 7 days	Novos bancos cadastrados (raro) New banks registered (rare)

Dados Semi-Dinâmicos (Cache Médio) / Semi-Dynamic Data (Medium Cache)¶

Endpoint	TTL Sugerido / Suggested TTL	Quando Invalidar / When to Invalidate
`/currencies/bank-channels`	1 hora / 1 hour	Mudanças em contas bancárias Changes in bank accounts
`/account-banks/receiver` (query `userId`)	5 minutos / 5 minutes	Após criar/atualizar/deletar beneficiário After creating/updating/deleting beneficiary

Dados Dinâmicos (Sem Cache ou Cache Muito Curto) / Dynamic Data (No Cache or Very Short Cache)¶

Endpoint	TTL Sugerido / Suggested TTL	Quando Invalidar / When to Invalidate
`/stocks/get-order-rate`	Não cachear / Do not cache	Taxas mudam em tempo real Rates change in real-time

Implementação de Cache / Cache Implementation¶

JavaScript

// Exemplo de implementação com cache em memória
class ReferenceDataService {
  constructor() {
    this.cache = {
      finalities: { data: null, expiry: 0 },
      countries: { data: null, expiry: 0 },
      currencies: { data: null, expiry: 0 },
      bankChannels: {}
    };
  }

  async getFinalities(clientType = null, remmitanceType = null) {
    const cacheKey = `finalities_${clientType}_${remmitanceType}`;
    const now = Date.now();

    // Verificar cache
    if (this.cache.finalities[cacheKey] && 
        this.cache.finalities[cacheKey].expiry > now) {
      return this.cache.finalities[cacheKey].data;
    }

    // Construir URL com parâmetros opcionais
    let url = '/v1/partner/public/finalities/get-all';

    if (clientType !== null || remmitanceType !== null) {
      const clientTypeParam = clientType !== null ? clientType : 'null';
      const remmitanceTypeParam = remmitanceType !== null ? remmitanceType : 'null';
      url = `/v1/partner/public/finalities/get-all/${clientTypeParam}/${remmitanceTypeParam}`;
    }

    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'x-api-key': this.apiKey,
        'Accept-Language': 'pt-br'
      }
    });

    const data = await response.json();

    // Cachear por 24 horas
    this.cache.finalities[cacheKey] = {
      data: data.data,
      expiry: now + (24 * 60 * 60 * 1000)
    };

    return data.data;
  }

  async getCountries() {
    const now = Date.now();

    if (this.cache.countries.data && this.cache.countries.expiry > now) {
      return this.cache.countries.data;
    }

    const response = await fetch('/v1/partner/public/countries/get-all', {
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'x-api-key': this.apiKey,
        'Accept-Language': 'pt-br'
      }
    });

    const data = await response.json();

    // Cachear por 7 dias
    this.cache.countries = {
      data: data.data,
      expiry: now + (7 * 24 * 60 * 60 * 1000)
    };

    return data.data;
  }

  async getCurrencies() {
    const now = Date.now();

    if (this.cache.currencies.data && this.cache.currencies.expiry > now) {
      return this.cache.currencies.data;
    }

    const response = await fetch('/v1/partner/public/currencies/get-all', {
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'x-api-key': this.apiKey,
        'Accept-Language': 'pt-br'
      }
    });

    const data = await response.json();

    // Cachear por 24 horas
    this.cache.currencies = {
      data: data.data,
      expiry: now + (24 * 60 * 60 * 1000)
    };

    return data.data;
  }

  async getBankChannels(currency, clientId = null, clientType = null) {
    const cacheKey = `${currency}_${clientId}_${clientType}`;
    const now = Date.now();

    if (this.cache.bankChannels[cacheKey] && 
        this.cache.bankChannels[cacheKey].expiry > now) {
      return this.cache.bankChannels[cacheKey].data;
    }

    let url = `/v1/partner/public/currencies/bank-channels?currency=${currency}`;
    if (clientId) url += `&clientId=${clientId}`;
    if (clientType !== null) url += `&clientType=${clientType}`;

    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'x-api-key': this.apiKey,
        'Accept-Language': 'pt-br'
      }
    });

    const data = await response.json();

    // Cachear por 1 hora
    this.cache.bankChannels[cacheKey] = {
      data: data.data,
      expiry: now + (60 * 60 * 1000)
    };

    return data.data;
  }

  // Método para limpar cache manualmente
  clearCache() {
    this.cache = {
      finalities: { data: null, expiry: 0 },
      countries: { data: null, expiry: 0 },
      currencies: { data: null, expiry: 0 },
      bankChannels: {}
    };
  }
}

Integração Completa / Complete Integration¶

Exemplo: Carregar Dados ao Iniciar Aplicação / Example: Loading Data on Application Startup¶

JavaScript

class AppInitializer {
  constructor(referenceDataService) {
    this.refData = referenceDataService;
  }

  async initialize() {
    console.log('Carregando dados de referência...');
    // Loading reference data...

    try {
      // Carregar em paralelo para melhor performance
      // Load in parallel for better performance
      const [finalities, countries, currencies] = await Promise.all([
        this.refData.getFinalities(),
        this.refData.getCountries(),
        this.refData.getCurrencies()
      ]);

      console.log(`✅ ${finalities.length} finalidades carregadas`);
      console.log(`✅ ${countries.length} países carregados`);
      console.log(`✅ ${currencies.length} moedas carregadas`);

      // Armazenar no estado global da aplicação
      // Store in the application's global state
      this.app.state.referenceData = {
        finalities,
        countries,
        currencies,
        loadedAt: new Date()
      };

      return true;
    } catch (error) {
      console.error('❌ Erro carregando dados de referência:', error);
      // Error loading reference data
      return false;
    }
  }
}

Exemplo: Usar Dados em Formulário / Example: Using Data in a Form¶

JavaScript

class OrderFormComponent {
  async loadFormData(clientType, remmitanceType) {
    // Obter finalidades filtradas por tipo de cliente e tipo de remessa
    const finalities = await refDataService.getFinalities(clientType, remmitanceType);

    // Obter países
    const countries = await refDataService.getCountries();

    // Obter moedas
    const currencies = await refDataService.getCurrencies();

    // Popular dropdowns
    this.populateFinalitiesDropdown(finalities);
    this.populateCountriesDropdown(countries);
    this.populateCurrenciesDropdown(currencies);
  }

  populateFinalitiesDropdown(finalities) {
    const select = document.getElementById('finality-select');

    finalities.forEach(finality => {
      const option = document.createElement('option');
      option.value = finality.id;
      option.textContent = finality.description;

      // Adicionar badge visual se requer nota fiscal
      if (finality.invoiceNeed) {
        option.textContent += ' 📄 (Requer NF)';
      }

      select.appendChild(option);
    });
  }

  async onCurrencySelected(currencyCode, clientId, clientType) {
    // Quando usuário seleciona uma moeda, carregar canais bancários
    const bankData = await refDataService.getBankChannels(
      currencyCode, 
      clientId, 
      clientType
    );

    // Exibir beneficiários e canais bancários
    this.displayBeneficiaries(bankData.beneficiaries);
    this.displayBeneficiaryBankChannels(bankData.beneficiaryBankChannels);
    this.displayIntermediaryBankChannels(bankData.intermediaryBankChannels);
  }
}

// Exemplo de uso para formulário de EXPORTAÇÃO (PJ, INBOUND)
const exportForm = new OrderFormComponent();
await exportForm.loadFormData(1, 0); // PJ, INBOUND

// Exemplo de uso para formulário de IMPORTAÇÃO (PJ, OUTBOUND)
const importForm = new OrderFormComponent();
await importForm.loadFormData(1, 1); // PJ, OUTBOUND

// Exemplo de uso para formulário genérico (mostra todas)
const genericForm = new OrderFormComponent();
await genericForm.loadFormData(1, null); // PJ, todas as remessas

Códigos de Status HTTP / HTTP Status Codes¶

Código / Code	Descrição / Description	Quando Ocorre / When it Occurs
200	OK	Dados retornados com sucesso Data returned successfully
400	Bad Request	Parâmetros inválidos Invalid parameters
401	Unauthorized	Token JWT ausente, inválido ou expirado Missing, invalid, or expired JWT token
403	Forbidden	Usuário sem permissão ADMIN_PARTNER ou API Key inválida User without ADMIN_PARTNER permission or invalid API Key
404	Not Found	Moeda, país ou dados não encontrados Currency, country, or data not found
500	Internal Server Error	Erro interno do servidor Internal server error

Perguntas Frequentes (FAQ) / Frequently Asked Questions¶

1. Com que frequência devo atualizar os dados de referência? How often should I update the reference data?

R: Recomendamos: / A: We recommend: * Finalidades: A cada 24 horas ou ao detectar mudanças regulatórias * Finalities: Every 24 hours or upon detecting regulatory changes * Países: A cada 7 dias (mudam raramente) * Countries: Every 7 days (rarely change) * Moedas: A cada 24 horas * Currencies: Every 24 hours * Canais Bancários: A cada 1 hora * Bank Channels: Every 1 hour

2. Posso cachear estes dados no navegador? Can I cache this data in the browser?

R: Sim! Recomendamos usar localStorage ou sessionStorage com timestamps de expiração para melhorar a performance. A: Yes! We recommend using localStorage or sessionStorage with expiration timestamps to improve performance.

3. O que fazer se uma finalidade exigir nota fiscal? What to do if a finality requires an invoice?

R: Quando invoiceNeed = true, você deve: / A: When invoiceNeed = true, you must: 1. Solicitar upload de nota fiscal do usuário * Request invoice upload from the user 2. Validar se a nota fiscal está anexada antes de permitir prosseguir * Validate if the invoice is attached before allowing to proceed 3. Incluir a nota fiscal nos documentos da ordem * Include the invoice in the order documents

4. O que são os diferentes tipos de canais bancários? What are the different types of bank channels?

R: O endpoint de bank-channels retorna três tipos de informações: A: The bank-channels endpoint returns three types of information:

Beneficiaries: Contas de destino para operações (contém account, reference, clientName)
Beneficiaries: Destination accounts for operations (contains account, reference, clientName)
Beneficiary Bank Channels: Informações dos bancos dos beneficiários (bank, swift, address)
Beneficiary Bank Channels: Information from the beneficiaries' banks (bank, swift, address)
Intermediary Bank Channels: Bancos intermediários para roteamento internacional (bank, swift, account, address)
Intermediary Bank Channels: Intermediary banks for international routing (bank, swift, account, address)

5. Por que o clientId é opcional em bank-channels? Why is clientId optional in bank-channels?

R: O clientId é usado para obter canais específicos ou taxas diferenciadas para determinados clientes (ex: clientes VIP). Sem ele, o sistema retorna os canais padrão. A: clientId is used to obtain specific channels or differentiated rates for certain customers (e.g., VIP customers). Without it, the system returns the default channels.

[!IMPORTANT] IMPORTANTE / IMPORTANT

Dados de referência são fundamentais para operações corretas. Cache-os adequadamente, mas implemente mecanismos de atualização para garantir que mudanças regulatórias ou operacionais sejam refletidas em tempo hábil.

Reference data is critical for correct operations. Cache them appropriately, but implement update mechanisms to ensure that regulatory or operational changes are reflected in a timely manner.

[!INFO] SUPORTE TÉCNICO / TECHNICAL SUPPORT

Para dúvidas sobre integração, caching ou uso dos dados de referência, consulte a documentação geral ou entre em contato com nossa equipe de suporte técnico.

For questions about integration, caching, or the use of reference data, please refer to the general documentation or contact our technical support team.

📎 Recursos Auxiliares: Download de Anexos / Auxiliary Resources: Download Attachments¶

Endpoint 7: Download de Anexo por Nome / Endpoint 7: Download Attachment by Name¶

GET /v1/partner/public/attachments/{nameDocument}/download

Faz o download de um anexo específico pelo nome do arquivo. Este é um endpoint genérico que pode ser usado para baixar qualquer tipo de anexo do sistema (documentos de clientes, anexos de ordens, etc.).

Downloads a specific attachment by filename. This is a generic endpoint that can be used to download any type of attachment from the system (customer documents, order attachments, etc.).

O que é este Endpoint? / What is this Endpoint?¶

Este é um recurso auxiliar de propósito geral que permite baixar arquivos individuais quando você já conhece o nome completo do arquivo. Ele é usado em conjunto com outros endpoints que retornam nomes de arquivos (como listagem de documentos de ordens, clientes, etc.).

This is a general-purpose auxiliary resource that allows downloading individual files when you already know the full filename. It is used in conjunction with other endpoints that return filenames (such as order document listings, customers, etc.).

Quando Usar Este Endpoint? / When to Use This Endpoint?¶

✅ Use quando: / Use when:

Já possui o nome completo do arquivo (incluindo extensão)
You already have the full filename (including extension)
Quer fazer o download de um único arquivo específico
You want to download a single specific file
Precisa baixar um documento individual de cliente
You need to download an individual customer document
Precisa baixar um anexo específico de uma ordem
You need to download a specific attachment from an order

❌ Não use quando: / Do not use when:

Quer baixar todos os anexos de uma ordem → Use /orders/attachments/{orderId}/download (documentado nos fluxos de orders)
You want to download all attachments from an order → Use /orders/attachments/{orderId}/download (documented in order flows)
Não sabe o nome exato do arquivo
You do not know the exact filename

Parâmetros da URL / URL Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`nameDocument`	string	✅	Nome completo do arquivo incluindo extensão. Exemplo: `invoice-12345.pdf` Full filename including extension. Example: `invoice-12345.pdf`

Exemplo de Requisição / Request Example¶

cURL

curl --location '/v1/partner/public/attachments/invoice-12345.pdf/download' \
--header 'Authorization: Bearer {seu_token}' \
--header 'x-api-key: {seu_api_key}' \
--header 'Accept-Language: pt-br'

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

JSON

{
  "success": true,
  "data": {
    "fileName": "invoice-12345.pdf",
    "contentType": "application/pdf",
    "content": "JVBERi0xLjQKJelz9MK..."
  },
  "errors": null
}

Campos da Resposta / Response Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`fileName`	string	Nome do arquivo com extensão Filename with extension
`contentType`	string	Tipo MIME do arquivo (e.g., `application/pdf`, `image/jpeg`) MIME type of the file (e.g., `application/pdf`, `image/jpeg`)
`content`	byte[]	Conteúdo do arquivo codificado em Base64 File content encoded in Base64

Códigos de Status HTTP / HTTP Status Codes¶

Código / Code	Descrição / Description
200 OK	Arquivo encontrado e retornado com sucesso File found and returned successfully
401 Unauthorized	Token inválido ou ausente Invalid or missing token
404 Not Found	Arquivo não encontrado ou sem permissão de acesso File not found or no access permission
500 Internal Server Error	Erro interno ao processar a requisição Internal error while processing the request

Para casos de uso específicos, consulte também: For specific use cases, please also see:

Endpoint	Quando Usar / When to Use	Documentação / Documentation
`GET /orders/attachments/{orderId}/download`	Baixar todos os anexos de uma ordem específica Download all attachments for a specific order	Orders Outbound / Orders Inbound

💳 Gestão de Beneficiários (Account Banks) / Beneficiary Management (Account Banks)¶

Base da API: / API Base: /v1/partner/public/account-banks

Visão Geral / Overview¶

Os beneficiários (Account Banks) são contas bancárias internacionais cadastradas que podem ser reutilizadas em múltiplas ordens outbound. Este sistema permite:

Beneficiaries (Account Banks) are registered international bank accounts that can be reused across multiple outbound orders. This system allows you to:

🔄 Reutilizar dados bancários em múltiplas operações
🔄 Reuse banking details across multiple operations
✅ Reduzir erros de digitação
✅ Reduce typing errors**
📊 Rastrear uso de cada beneficiário
📊 Track the usage of each beneficiary
⚡ Agilizar o processo de criação de ordens
⚡ Speed up the order creation process

[!NOTE] IDENTIFICAÇÃO DO CLIENTE / CUSTOMER IDENTIFICATION

Em criar, atualizar e listar (GET .../receiver), use userId como string — o ID do usuário no mesmo formato usado nas ordens outbound. Não envie personType no body: o backend resolve PJ se existir conta corporativa vinculada ao usuário; caso contrário, usa a conta individual (PF).

In create, update, and list (GET .../receiver), use userId as a string — the user ID in the same format used in outbound orders. Do not send personType in the body: the backend resolves to PJ (corporate) if there is a corporate account linked to the user; otherwise, it uses the individual (PF) account.

Contratos de resposta (tipos) / Response Contracts (types)¶

Método / Method	Caminho / Path	`data`	DTO (C#)
`GET`	`.../account-banks/receiver`	Array de beneficiários Array of beneficiaries	`AccountBankDto`
`POST`	`.../account-banks`	Um beneficiário criado A created beneficiary	`AccountBankPublicDto`
`PUT`	`.../account-banks/{id}`	Um beneficiário atualizado An updated beneficiary	`AccountBankPublicDto`

[!TIP] Os nomes no JSON seguem camelCase (ex.: countryId, usageCount). Por configuração da API, propriedades com valor null costumam ser omitidas do JSON — não confunda "ausência da chave" com "valor nulo"; a tabela abaixo lista todos os campos do contrato quando a API os serializa.

JSON names follow camelCase (e.g., countryId, usageCount). By API configuration, properties with a null value are usually omitted from the JSON — do not confuse "missing key" with "null value"; the table below lists all contract fields when the API serializes them.

Endpoint 8: Listar Beneficiários de um Cliente / Endpoint 8: List a Customer's Beneficiaries¶

GET /v1/partner/public/account-banks/receiver

Retorna todos os beneficiários cadastrados para o usuário informado (userId em AspNetUsers), ordenados por frequência de uso (beneficiários mais usados aparecem primeiro). O backend resolve automaticamente conta corporativa ou individual (mesma regra do create/update: prioriza PJ se existir).

Returns all registered beneficiaries for the provided user (userId in AspNetUsers), sorted by usage frequency (most used beneficiaries appear first). The backend automatically resolves corporate or individual accounts (same rule as create/update: prioritizes corporate if it exists).

Para que serve? / What is it for?¶

Este endpoint permite: This endpoint allows:

🔍 Consultar beneficiários já cadastrados para um cliente
Consult already registered beneficiaries for a customer
📝 Preencher automaticamente dados bancários em formulários
Automatically pre-fill banking data in forms
📊 Identificar beneficiários mais frequentes através do usageCount
Identify more frequent beneficiaries through usageCount
⚡ Facilitar a criação de ordens outbound
Facilitate the creation of outbound orders

Parâmetros (query string) / Parameters (query string)¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`userId`	string	✅	ID do usuário na tabela AspNetUsers (Identity) User ID in the AspNetUsers table (Identity)
`countryId`	long	❌	Filtro opcional por país da conta bancária Optional filter by bank account country

Exemplo de Requisição / Request Example¶

cURL

GET /v1/partner/public/account-banks/receiver?userId=GUID-DO-USUARIO-ASP-NET-USERS&countryId=1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

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

JSON

{
  "success": true,
  "data": [
    {
      "id": 42,
      "corporateAccount": null,
      "individualAccount": null,
      "country": {
        "id": 840,
        "description": "United States",
        "code": "US"
      },
      "currency": {
        "id": 1,
        "description": "USD - United States Dollar",
        "code": 1
      },
      "city": "New York",
      "name": "Chase Bank",
      "swift": "CHASUS33",
      "number": "1234567890",
      "aba": "021000021",
      "iban": null,
      "code": null,
      "agency": null,
      "bank": "Chase Bank",
      "institutionNumber": null,
      "transit": null,
      "address": null,
      "cbu": null,
      "cable": null,
      "blz": null,
      "cuit": null,
      "bsb": null,
      "sortCode": null,
      "fcc": null,
      "isDefault": false,
      "type": 0,
      "senderReceiverName": null,
      "email": null,
      "usageCount": 15
    }
  ]
}

Campos da resposta (`data[]` — `AccountBankDto`) / Response Fields¶

Cada item do array segue o DTO AccountBankDto. Campos string/objeto podem vir omitidos no JSON quando são null. Each array item follows the AccountBankDto. String/object fields may be omitted from the JSON when they are null.

Campo (JSON) / Field	Tipo / Type	Descrição / Description
`id`	long	ID único do beneficiário (use em `beneficiaryAccountBankId` nas ordens) *Unique beneficiary ID*
`corporateAccount`	object \| omitido	Conta corporativa vinculada (Stutura `CorporateAccountDto`)
`individualAccount`	object \| omitido	Conta individual vinculada (Estrutura `IndividualAccountDto`)
`country`	object \| omitido	País: `id` (long), `description` (string), `code` (string)
`currency`	object \| omitido	Moeda: `id` (long), `description` (string), `code` (long)
`city`	string	Cidade do banco / Bank city
`name`	string	Nome do banco / Bank name
`swift`	string	SWIFT/BIC
`number`	string	Número da conta / Account number
`aba`	string	ABA
`iban`	string	IBAN
`code`	string	Código do banco / Bank code
`agency`	string	Agência / Agency
`bank`	string	Somente leitura: espelho de `name` (nome amigável)
`institutionNumber`	string	Institution Number
`transit`	string	Transit
`address`	string	Endereço / Address
`cbu`	string	CBU
`cable`	string	CABLE
`blz`	string	BLZ
`cuit`	string	CUIT
`bsb`	string	BSB
`sortCode`	string	Sort Code
`fcc`	string	FCC (cadastro do beneficiário)
`isDefault`	bool	Beneficiário padrão / Default beneficiary
`type`	number (enum)	Tipo de conta (`EAccountBankType`; ex.: recebedora)
`senderReceiverName`	string	Nome do beneficiário final (quando aplicável)
`email`	string	E-mail
`usageCount`	int	Quantidade de usos deste beneficiário Usage count of this beneficiary

[!IMPORTANT] ORDENAÇÃO / SORTING usageCount decrescente, depois name alfabético. usageCount descending, then alphabetical name.

Quando Usar / When to Use¶

✅ Use este endpoint para: / Use this endpoint to:

Carregar lista de beneficiários em formulários de ordem
Implementar autocomplete/dropdown de beneficiários
Exibir histórico de beneficiários usados
Preencher automaticamente dados bancários

Erros Possíveis / Possible Errors¶

userId ausente (400 Bad Request) / Missing userId

{
  "success": false,
  "errors": ["O ID do usuário é obrigatório"]
}

Cliente / conta não resolvível para o userId (404 / erro de negócio) JSON

{
  "success": false,
  "errors": ["Cliente não encontrado"]
}

Endpoint 9: Criar Beneficiário / Endpoint 9: Create Beneficiary¶

POST /v1/partner/public/account-banks

Cria um novo beneficiário (conta bancária internacional) para o usuário informado em userId (AspNetUsers). O vínculo PF/PJ é inferido no servidor (prioriza conta corporativa).

Creates a new beneficiary (international bank account) for the user specified in userId. The individual/corporate link is inferred on the server (prioritizes corporate account).

Validação na API pública (body) / Public API Validation (body)¶

Campo / Field	Tipo / Type	Obrigatório	Descrição / Description
`userId`	string	✅	ID do usuário em AspNetUsers (Identity), ex: GUID
`countryId`	long	✅	Deve ser > 0 / Must be > 0
`currencyId`	long	Opcional	0 ou omitido = sem moeda no cadastro.

[!IMPORTANT] OBRIGATORIEDADE DE CAMPOS / MANDATORY FIELDS

Além dos limites abaixo, o backend aplica regras por país (countryId) — certos países exigem combinações mínimas (ex.: banco + SWIFT + IBAN). Consulte a tabela de requisitos por país na documentação de ordens outbound quando for montar o payload.

In addition to the limits below, the backend applies country-specific rules — certain countries require minimum combinations (e.g., bank + SWIFT + IBAN). Refer to the country requirements table in the outbound orders documentation when building the payload.

Regras dos campos bancários quando enviados (tamanho / formato) / Bank field rules when sent (size / format)¶

Se o campo vier no JSON, não pode ser só espaços e deve respeitar o tamanho máximo: If the field is present in the JSON, it cannot be just whitespace and must respect the maximum size:

Campo (JSON) / Field	Máx. / Max	Observação / Note
`name`	100	Nome do banco / Bank name
`swift`	100	Recomenda-se 8 ou 11 caracteres (padrão BIC/SWIFT); a API valida o formato conforme o país
`city`	100	Cidade do banco / Bank city
`number`	100	Número da conta / Account number
`aba`	100	ABA (EUA)
`iban`	100	IBAN
`code`	100	Código do banco / Bank code
`agency`	100	Agência / Agency
`institutionNumber`	50	Institution Number
`transit`	50	Transit Number
`address`	255	Endereço do banco / Bank address
`cbu`	50	CBU
`cable`	50	CABLE
`blz`	50	Bankleitzahl
`cuit`	50	CUIT
`bsb`	50	BSB
`sortCode`	50	Sort Code
`fcc`	255	Federal Code Country; na ordem outbound prevalece o do payload da ordem
`senderReceiverName`	255	Nome do beneficiário final (quando aplicável)
`email`	100	Deve ser e-mail válido se informado / Must be a valid email if provided

Campo / Field	Tipo / Type	Descrição / Description
`isDefault`	boolean	Se é o beneficiário padrão / Whether it is the default beneficiary
`type`	enum	Tipo de conta (padrão: conta bancária) / Account type (default: bank account)

[!NOTE] FCC EM ORDENS OUTBOUND / FCC IN OUTBOUND ORDERS

Em ordens outbound, ao usar beneficiaryAccountBankId, o FCC utilizado na operação é o enviado no JSON da ordem (receiver.receiverAccount.fcc), não o valor apenas cadastrado no favorito.

In outbound orders, when using beneficiaryAccountBankId, the FCC used in the operation is the one sent in the order JSON, not just the value registered in favorites.

Estrutura completa de `data` na resposta (POST e PUT — `AccountBankPublicDto`) / Complete structure of `data` in the response¶

O corpo de sucesso usa o DTO AccountBankPublicDto. Chaves com valor null podem ser omitidas no JSON real; a tabela lista o contrato completo. The success body uses the AccountBankPublicDto DTO. Keys with null values may be omitted in the actual JSON; the table lists the complete contract.

Campo (JSON) / Field	Tipo / Type	Descrição / Description
`id`	long	ID do beneficiário criado/atualizado Beneficiary ID created/updated
`userId`	string	ID em AspNetUsers (Identity) ID in AspNetUsers (Identity)
`countryId`	long	ID do país (0 se não aplicável) Country ID (0 if not applicable)
`currencyId`	long	ID da moeda (0 se não houver moeda vinculada) Currency ID (0 if no linked currency)
`city`	string	Cidade / City
`name`	string	Nome do banco / Bank name
`swift`	string	SWIFT/BIC
`number`	string	Número da conta / Account number
`aba`	string	ABA
`iban`	string	IBAN
`code`	string	Código do banco / Bank code
`agency`	string	Agência / Agency
`institutionNumber`	string	Institution Number
`transit`	string	Transit
`address`	string	Endereço / Address
`cbu`	string	CBU
`cable`	string	CABLE
`blz`	string	BLZ
`cuit`	string	CUIT
`bsb`	string	BSB
`sortCode`	string	Sort Code
`fcc`	string	FCC
`isDefault`	bool	Beneficiário padrão / Default beneficiary
`type`	number (enum)	`EAccountBankType` (ex.: recebedora)
`senderReceiverName`	string	Nome do beneficiário final / Final beneficiary name
`email`	string	E-mail

[!NOTE] PUT retorna o mesmo conjunto de campos no objeto data. PUT* returns the same set of fields* in the data object.

Exemplo de Requisição / Request Example¶

cURL

POST /v1/partner/public/account-banks
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

{
  "userId": "57dfa30c-78f0-4607-8a36-436b08a0c18a",
  "name": "Chase Bank",
  "swift": "CHASUS33",
  "number": "1234567890",
  "aba": "021000021",
  "city": "New York",
  "countryId": 840,
  "isDefault": false
}

[!NOTE] O campo currencyId é opcional. Neste exemplo foi omitido; quando informado, deve ser o ID numérico da moeda (> 0). The currencyId field is optional. In this example, it was omitted; when provided, it must be the numeric ID of the currency (> 0).

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

Exemplo ilustrando todos os campos do AccountBankPublicDto (valores null na prática podem ser omitidos do JSON): Example illustrating all fields of AccountBankPublicDto (null values may be omitted from the actual JSON):

JSON

{
  "success": true,
  "data": {
    "id": 42,
    "userId": "57dfa30c-78f0-4607-8a36-436b08a0c18a",
    "countryId": 840,
    "currencyId": 0,
    "city": "New York",
    "name": "Chase Bank",
    "swift": "CHASUS33",
    "number": "1234567890",
    "aba": "021000021",
    "iban": null,
    "code": null,
    "agency": null,
    "institutionNumber": null,
    "transit": null,
    "address": null,
    "cbu": null,
    "cable": null,
    "blz": null,
    "cuit": null,
    "bsb": null,
    "sortCode": null,
    "fcc": null,
    "isDefault": false,
    "type": 0,
    "senderReceiverName": null,
    "email": null
  }
}

Erros Possíveis / Possible Errors¶

Os textos abaixo são exemplos; a API localiza as mensagens conforme o header Accept-Language. The texts below are examples; the API localizes messages according to the Accept-Language header.

Dados obrigatórios ausentes ou IDs inválidos (400 Bad Request) / Missing required data or invalid IDs¶

Ex.: userId vazio ou countryId menor ou igual a zero. Para currencyId, 0 é aceito (opcional); valores < 0 ou, quando informado um ID diferente de zero, ≤ 0 disparam a validação da moeda.

E.g.: empty userId or countryId less than or equal to zero. For currencyId, 0 is accepted (optional); values < 0 or, when a non-zero ID is provided, ≤ 0 trigger currency validation.

JSON

{
  "success": false,
  "errors": [
    "O ID do usuário é obrigatório",
    "O ID do país deve ser maior que zero"
  ]
}

Validações de tamanho / formato dos campos bancários (400 Bad Request) / Bank fields size / format validations¶

Quando algum campo enviado viola as regras da API pública (tamanho máximo, só espaços, e-mail inválido, etc.): When a submitted field violates public API rules (max size, whitespace only, invalid email, etc.):

JSON

{
  "success": false,
  "errors": [
    "O nome do banco deve ter no máximo 100 caracteres",
    "O código SWIFT deve ter no máximo 100 caracteres"
  ]
}

[!NOTE] Além disso, a validação por país (countryId) pode exigir campos ou formatos específicos e retornar outras mensagens na mesma estrutura errors[]. Additionally, country-specific validation may require specific fields or formats and return other messages in the same errors[] structure.

Cliente não encontrado para o `userId` (erro de negócio) / Customer not found for `userId` (business error)¶

Não foi possível resolver conta corporativa ou individual para o usuário informado: Could not resolve corporate or individual account for the provided user:

JSON

{
  "success": false,
  "errors": ["Cliente não encontrado"]
}

País ou moeda não encontrados (404 Not Found / erro de negócio) / Country or currency not found¶

JSON

{
  "success": false,
  "errors": [
    "País informado não existe",
    "Moeda informada não existe"
  ]
}

Não autorizado (401 Unauthorized) / Unauthorized (401 Unauthorized) Token ausente, inválido ou sem permissão. Missing, invalid, or unauthorized token.

Erro interno (500 Internal Server Error) / Internal Server Error (500 Internal Server Error)

Endpoint 10: Atualizar Beneficiário / Endpoint 10: Update Beneficiary¶

PUT /v1/partner/public/account-banks/{id}

Atualiza os dados de um beneficiário existente. O userId no body é obrigatório (mesma validação da criação): o servidor resolve de novo a conta PF/PJ a partir dele e aplica as regras de país.

Updates the data of an existing beneficiary. The userId in the body is mandatory (same validation as creation): the server re-resolves the individual/corporate account based on it and applies country rules.

Para que serve? / What is it for?¶

Permite modificar informações de beneficiários já cadastrados, como dados bancários, país, moeda, etc. Allows modifying information of already registered beneficiaries, such as banking details, country, currency, etc.

Parâmetros da URL / URL Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`id`	long	✅	ID único do beneficiário a ser atualizado Unique ID of the beneficiary to be updated

Corpo da requisição / Request Body¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`userId`	string	✅	AspNetUsers — deve ser o mesmo contexto de cliente da operação
`countryId`	long	✅	> 0
`currencyId`	long	Opcional	Mesma regra do POST (0/omitido ou > 0 válido)
Demais campos	—	Conforme preenchimento	Mesmos campos e mesmas regras de tamanho do POST

Exemplo de Requisição / Request Example¶

cURL

PUT /v1/partner/public/account-banks/42
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

{
  "userId": "57dfa30c-78f0-4607-8a36-436b08a0c18a",
  "name": "Chase Bank - Updated",
  "swift": "CHASUS33",
  "city": "Los Angeles",
  "number": "9876543210",
  "countryId": 840,
  "isDefault": false
}

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

Mesmo contrato de data do POST (AccountBankPublicDto). Exemplo com todos os campos do DTO: Same data contract as POST (AccountBankPublicDto). Example with all DTO fields:

JSON

{
  "success": true,
  "data": {
    "id": 42,
    "userId": "57dfa30c-78f0-4607-8a36-436b08a0c18a",
    "countryId": 840,
    "currencyId": 0,
    "city": "Los Angeles",
    "name": "Chase Bank - Updated",
    "swift": "CHASUS33",
    "number": "9876543210",
    "aba": null,
    "iban": null,
    "code": null,
    "agency": null,
    "institutionNumber": null,
    "transit": null,
    "address": null,
    "cbu": null,
    "cable": null,
    "blz": null,
    "cuit": null,
    "bsb": null,
    "sortCode": null,
    "fcc": null,
    "isDefault": false,
    "type": 0,
    "senderReceiverName": null,
    "email": null
  }
}

Erros Possíveis / Possible Errors¶

Mensagens exemplificadas em pt-BR; use Accept-Language para o idioma desejado. Example messages in pt-BR; use Accept-Language for the desired language.

Beneficiário não encontrado (404 Not Found) / Beneficiary not found¶

JSON

{
  "success": false,
  "errors": ["Beneficiário não encontrado"]
}

ID inválido ou inconsistente com o corpo (400 Bad Request) / Invalid or inconsistent ID¶

Ex.: id da URL inexistente, zero, ou divergente do esperado pela regra de negócio. E.g.: id from URL does not exist, is zero, or differs from business rule expectations.

JSON

{
  "success": false,
  "errors": ["ID inválido."]
}

Validação do body — mesmas regras do POST (400 Bad Request) / Body validation — same rules as POST¶

userId e countryId obrigatórios na API pública; currencyId opcional (mesma regra do POST); tamanhos/formatos dos campos bancários conforme tabela do Endpoint 9; validação adicional por país.

userId and countryId mandatory in the public API; currencyId optional (same rule as POST); bank field sizes/formats according to Endpoint 9 table; additional country validation.

JSON

{
  "success": false,
  "errors": [
    "O ID do usuário é obrigatório",
    "O código SWIFT deve ter no máximo 100 caracteres"
  ]
}

Endpoint 11: Deletar Beneficiário / Endpoint 11: Delete Beneficiary¶

DELETE /v1/partner/public/account-banks/{id}

Remove um beneficiário do sistema. Removes a beneficiary from the system.

Para que serve? / What is it for?¶

Permite excluir beneficiários que não são mais necessários ou que foram cadastrados incorretamente. Allows deleting beneficiaries that are no longer needed or were incorrectly registered.

Parâmetros da URL / URL Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`id`	long	✅	ID único do beneficiário a ser deletado Unique ID of the beneficiary to be deleted

Exemplo de Requisição / Request Example¶

cURL

DELETE /v1/partner/public/account-banks/42
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br

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

JSON

{
  "success": true,
  "data": null
}

[!CAUTION] ATENÇÃO / WARNING

A exclusão é permanente e não pode ser desfeita. Certifique-se de que o beneficiário não está em uso antes de deletar.

Deletion is permanent and cannot be undone. Make sure the beneficiary is not in use before deleting.

Erros Possíveis / Possible Errors¶

Beneficiário Não Encontrado (404 Not Found) / Beneficiary Not Found

JSON

{
  "success": false,
  "errors": ["Beneficiário não encontrado"]
}

Beneficiário em Uso (409 Conflict) / Beneficiary in Use

JSON

{
  "success": false,
  "errors": [
    "Não é possível deletar o beneficiário",
    "Este beneficiário está sendo usado em ordens ativas"
  ]
}

[!NOTE] Os textos exatos podem variar com Accept-Language e com a regra de negócio vigente. Exact texts may vary with Accept-Language and current business rules.

Não autorizado (401 Unauthorized) / Unauthorized Token ausente, inválido ou sem permissão. Missing, invalid, or unauthorized token.

Erro interno (500 Internal Server Error) / Internal Server Error

💡 Como Usar Beneficiários nas Ordens / How to Use Beneficiaries in Orders¶

Integração com Ordens Outbound / Integration with Outbound Orders¶

Ao criar ou atualizar uma ordem outbound, você pode referenciar um beneficiário através do campo beneficiaryAccountBankId: When creating or updating an outbound order, you can reference a beneficiary through the beneficiaryAccountBankId field:

JSON

{
  "receiver": {
    "name": "John Smith",
    "receiverAccount": {
      "beneficiaryAccountBankId": 42,
      "name": "Chase Bank",
      "swift": "CHASUS33",
      "countryId": 840,
      "city": "New York",
      "number": "1234567890",
      "aba": "021000021"
    }
  }
}

[!IMPORTANT] IMPORTANTE / IMPORTANT

Mesmo ao informar o beneficiaryAccountBankId, você deve enviar todos os dados bancários completos. O campo serve apenas para rastreamento e vínculo com o beneficiário cadastrado.

Even when providing the beneficiaryAccountBankId, you must send all complete banking details. The field is only for tracking and linking to the registered beneficiary.

FCC: O código FCC (Federal Code Country) efetivo na ordem é sempre o enviado no payload (receiver.receiverAccount.fcc na API de ordens). O valor de FCC cadastrado no beneficiário não substitui o informado na criação ou atualização da ordem — use o payload para o FCC específico da operação.

FCC:* The effective FCC (Federal Code Country) in the order is always the one sent in the payload. The FCC value registered in the beneficiary does not replace* the one provided during order creation or update — use the payload for the operation-specific FCC.

Vantagens de Usar Beneficiários / Advantages of Using Beneficiaries¶

Vantagem / Advantage	Descrição / Description
⚡ Agilidade	Preenchimento automático de campos na interface Automatic field filling in the interface
✅ Precisão	Dados já validados em operações anteriores Data already validated in previous operations
🔄 Reutilização	Reuso de beneficiários em múltiplas ordens Reuse of beneficiaries in multiple orders
📊 Rastreabilidade	Campo `beneficiaryAccountBankId` permite análises de uso `beneficiaryAccountBankId` field allows usage analysis
📈 Inteligência	Lista ordenada por `usageCount` facilita seleção List sorted by `usageCount` facilitates selection

Para mais informações sobre como usar beneficiários ao criar ordens, consulte: For more information on how to use beneficiaries when creating orders, see:

Documentação / Documentation	Descrição / Description
Orders Outbound	Fluxo completo de criação de ordens com beneficiários Full order creation flow with beneficiaries
Orders Outbound Simplified	Fluxo simplificado com taxa contratada Simplified flow with contracted rate