Fluxo Simplificado: Criação de Ordens de Envio (Outbound) com Taxa Contratada / Simplified Outbound Order Flow with Contracted Rate¶

Visão Geral / Overview¶

O Fluxo Simplificado de Ordens de Envio (Outbound) permite a parceiros integrados criar transferências internacionais de forma otimizada através da plataforma de Parceiros. Este processo utiliza um sistema de taxa contratada que oferece cotações em tempo real com valores previamente negociados, permitindo a criação de ordens parciais que são posteriormente completadas com os dados do beneficiário. The Simplified Outbound Order Flow allows partners to create optimized international transfers. It uses a contracted rate system offering real-time quotes, allowing the creation of partial orders later completed with beneficiary data.

Este fluxo segue as regulamentações do Banco Central do Brasil e implementa as melhores práticas de compliance para operações de câmbio. This flow follows Central Bank of Brazil regulations and implements best compliance practices.

Autenticação / Authentication¶

Todos os endpoints desta API requerem os seguintes headers obrigatórios: All API endpoints 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) / Unique partner GUID.
Accept-Language: Idioma de resposta (pt-br, en-us ou es-es) / Response language.

[!IMPORTANT] IMPORTANTE / IMPORTANT

Todos os headers acima são obrigatórios em todas as requisições. A falta de qualquer um deles resultará em erro de autenticação. All headers above are mandatory. Failure to provide any 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 rate limiting to ensure service stability and availability.

[!INFO] INFORMAÇÃO / INFORMATION

Os limites são aplicados por endereço IP. Cada IP possui contadores independentes. 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	3 requisições	Proteção contra picos / Spike protection
1 minuto	30 requisições	Uso normal / Normal use
15 minutos	100 requisições	Operações em lote / Batch operations
1 hora	300 requisições	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 / Status of all rules
`X-RateLimit-Limit`	Limite da regra mais restritiva (compatibilidade) / Most restrictive limit
`X-RateLimit-Remaining`	Requisições restantes da regra mais restritiva / Remaining requests
`Retry-After`	Segundos para aguardar antes de tentar novamente (apenas em 429) / Retry wait time

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

[!INFO] 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

Endpoints Auxiliares / Auxiliary Endpoints¶

Antes de iniciar o fluxo, você precisará obter informações de referência através dos seguintes endpoints: Before starting the flow, you will need to obtain reference information through the following endpoints:

Endpoint	Método / Method	Descrição / Description
`/v1/partner/public/countries/get-all`	GET	Lista de países disponíveis (retorna `id` e `description`) / Available countries list
`/v1/partner/public/currencies/get-all`	GET	Lista de moedas disponíveis (retorna `id`, `code` e `description`) / Available currencies list
`/v1/partner/public/finalities/get-all/{clientType?}/{remittanceType?}`	GET	Lista de finalidades por tipo de cliente (0=PF, 1=PJ) e tipo de remessa (1=Outbound) / Purposes list by client and remittance type
`/v1/partner/public/clients/get-filtered`	GET	Buscar clientes cadastrados (opcional - se não tiver `ClientId`) / Search registered clients

[!TIP] DICA / TIP

Salve estas informações em cache no seu frontend para evitar múltiplas chamadas. Os IDs retornados devem ser usados nos campos correspondentes das ordens. Cache this information on your frontend to avoid multiple calls. Returned IDs must be used in the corresponding order fields.

📋 Importante: Naturezas de Operação (Finalities) / Important: Nature of Operation¶

O que são Finalidades? / What are Purposes?¶

As finalidades (finalities) representam as naturezas de operação regulamentadas pelo Banco Central do Brasil. Cada operação de câmbio deve ser classificada segundo sua finalidade (ex: importação de mercadorias, pagamento de serviços, transferência para manutenção de residentes, etc.). The finalities represent the nature of operation regulated by the Central Bank of Brazil. Each FX operation must be classified according to its purpose.

Como Funcionam os IDs / How IDs Work¶

Os finalityId utilizados nesta API são identificadores internos da plataforma. Cada finalidade disponível está devidamente cadastrada e aprovada para uso em operações de câmbio. The finalityId used in this API are internal identifiers. Each available purpose is duly registered and approved.

[!CAUTION] LIMITAÇÃO IMPORTANTE / IMPORTANT LIMITATION

Apenas as finalidades retornadas pelo endpoint /finalities/get-all (documentado acima) podem ser utilizadas nas operações via API. Se a operação do seu cliente possui uma natureza que não consta na lista, a ordem não poderá ser processada diretamente pela API. Only purposes returned by the /finalities/get-all endpoint can be used. If your client's operation nature is not on the list, it cannot be processed via API.

Operações com Naturezas Não Listadas / Operations with Unlisted Natures¶

Se você precisa processar uma operação cuja natureza não está disponível na lista: If you need to process an operation whose nature is not available in the list:

1. Via API (Automático) / Automatic * ❌ Não será possível processar diretamente / Cannot be processed directly * A validação impedirá a criação da ordem / Validation will prevent order creation

2. Processo Manual (Exceções) / Manual Process (Exceptions) * ✅ Entre em contato com a equipe de suporte/compliance / Contact support/compliance team * ✅ Informe a natureza específica da operação / Inform the specific nature of the operation * ✅ Aguarde análise e cadastro da nova finalidade no sistema / Wait for analysis and registration * ✅ Após aprovação, a finalidade estará disponível via API / Once approved, it will be available via API

Enquadramento de Operações / Operation Framework¶

Tipo / Type	Quando Ocorre / When it Occurs	Como Funciona / How it Works
Automático	Finalidade já cadastrada no sistema	Sistema valida e enquadra automaticamente ao criar a ordem / Automatic validation
Manual	Finalidade não cadastrada ou casos especiais	Requer intervenção da equipe de compliance para análise e aprovação / Requires compliance team

[!INFO] BOA PRÁTICA / BEST PRACTICE

Sempre consulte o endpoint de finalidades antes de iniciar o fluxo de criação de ordens. Isso evita: Always consult the finalities endpoint before starting the flow. This avoids:

Erros de validação durante a criação da ordem / Validation errors

Retrabalho por usar IDs inválidos / Rework due to invalid IDs

Problemas de conformidade regulatória / Regulatory compliance issues

Etapa 1: Obtenção das Taxas / Step 1: Obtaining Rates¶

Endpoint: `GET /v1/partner/public/orders/outbound/rate-quotation`¶

🔗 Dependências Específicas deste Endpoint / Endpoint Dependencies¶

Antes de obter a cotação, você DEVE consultar os seguintes endpoints: Before obtaining the quote, you MUST consult the following endpoints:

Ordem / Order	Endpoint	Campo Relacionado / Field	Obrigatório / Mandatory	Descrição / Description
1️⃣	`GET /v1/partner/public/currencies/get-all`	`currencyId`	✅	Obter ID da moeda estrangeira / Foreign currency ID
2️⃣	`GET /v1/partner/public/countries/get-all`	`countryId`	❌	Obter ID do país de destino (opcional) / Destination country ID
3️⃣	`GET /v1/partner/public/finalities/get-all/{clientType?}/{remittanceType?}`	`finalityId`	❌	Obter ID da finalidade (opcional) / Purpose ID

Esta etapa opcional permite obter as taxas antes de criar a ordem. É útil para calcular valores em tempo real, comparar cenários e validar a viabilidade da operação. This optional step allows getting rates before creating the order. Useful for real-time calculations and scenario comparison.

Dados / Data¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`currencyId`	int	✅	> 0	ID da moeda estrangeira / Foreign currency ID
`tariff`	decimal	✅	≥ 0	Valor da tarifa a ser aplicada / Applied tariff value
`amount`	decimal	⚠️ *	> 0	Valor em moeda estrangeira / Foreign currency amount
`amountNC`	decimal	⚠️ *	> 0	Valor em moeda nacional (BRL) / National currency amount
`spread`	decimal	⚠️ **	0-1	Spread percentual (0-100%) / Percentage spread
`contractedRate`	decimal	⚠️ **	> 0	Taxa de câmbio contratada fixa / Fixed contracted rate
`finalityId`	long	❌	> 0	ID da finalidade da operação / Operation purpose ID
`countryId`	long	❌	> 0	ID do país de destino / Destination country ID

* Você deve fornecer UM DOS DOIS: amount (moeda estrangeira) OU amountNC (BRL). / Provide ONE OF THE TWO: amount OR amountNC.

* Você deve fornecer UM DOS DOIS: spread OU contractedRate (Taxa Contratada - mutuamente exclusivos). / Provide ONE OF THE TWO: spread OR contractedRate.*

[!IMPORTANT] IMPORTANTE / IMPORTANT

Os parâmetros spread e contractedRate são mutuamente exclusivos. Forneça apenas um deles. O mesmo vale para amount e amountNC. The parameters spread and contractedRate are mutually exclusive. Provide only one. The same applies to amount and amountNC.

Modos de Cálculo / Calculation Modes¶

Modo 1: Usando Spread / Mode 1: Using Spread¶

cURL

GET /v1/partner/public/orders/outbound/rate-quotation?currencyId=1&amount=10000&tariff=50&spread=0.02

O sistema calculará baseado em: Taxa de Mercado + Spread The system will calculate based on: Market Rate + Spread**

Modo 2: Usando Taxa Contratada / Mode 2: Using Contracted Rate¶

cURL

GET /v1/partner/public/orders/outbound/rate-quotation?currencyId=1&amount=10000&tariff=50&contractedRate=5.30

O sistema utilizará a taxa de câmbio contratada fixa fornecida (R$ 5,30 por dólar). Este modo é ideal para parceiros com taxas pré-negociadas. The system will use the fixed contracted exchange rate provided. Ideal for partners with pre-negotiated rates.

Modo 3: Convertendo de BRL para Moeda Estrangeira / Mode 3: Converting BRL to Foreign Currency¶

cURL

GET /v1/partner/public/orders/outbound/rate-quotation?currencyId=1&amountNC=53000&tariff=50&spread=0.02

O sistema calculará quanto em moeda estrangeira você pode comprar com o valor em BRL fornecido. The system will calculate how much foreign currency can be purchased with the provided BRL amount.

Exemplo de Requisição / Request Example¶

cURL

GET /v1/partner/public/orders/outbound/rate-quotation?amount=10000&currencyId=1&finalityId=18&countryId=840&tariff=50&spread=0.02

Resposta de Sucesso / Success Response¶

JSON

{
  "success": true,
  "data": {
    "amount": 10000.00,
    "amountNC": 53050.00,
    "rate": 5.2850,
    "commercial": 52850.00,
    "iof": 6.50,
    "iofPercentage": 0.0038,
    "tariff": 50.00,
    "ir": 0.00,
    "irPercentage": 0.00,
    "vet": 52906.50,
    "total": 53050.00,
    "spread": 0.02,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "taxId": 12345,
    "settlementFlow": 2,
    "currency": "USD"
  }
}

Descrição dos Campos Retornados / Description of Returned Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`amount`	decimal	Valor total calculado em moeda estrangeira / Total amount in foreign currency
`amountNC`	decimal	Valor total calculado em moeda nacional (BRL) / Total amount in BRL
`rate`	double	Taxa de câmbio utilizada no cálculo / Exchange rate used
`commercial`	decimal	Valor comercial calculado / Calculated commercial value
`iof`	decimal	Valor do IOF calculado / Calculated IOF (Tax on Financial Operations)
`iofPercentage`	decimal	Percentual do IOF aplicado / Applied IOF percentage
`tariff`	decimal	Valor da tarifa aplicada / Applied tariff value
`ir`	decimal	Valor do IR (Imposto de Renda) calculado / Calculated Income Tax
`irPercentage`	decimal	Percentual do IR aplicado / Applied Income Tax percentage
`vet`	decimal	VET (Valor Efetivo Total) calculado / Calculated Total Effective Value
`total`	decimal	Valor total em BRL que o cliente pagará / Total BRL amount to be paid
`spread`	decimal	Spread aplicado no cálculo / Spread applied in calculation
`token`	string	Token obrigatório para a próxima etapa / Mandatory token for the next step
`taxId`	long	Identificador único do imposto / Unique tax identifier
`settlementFlow`	int	Fluxo de liquidação da ordem (D+0=1, D+1=2, D+2=3) / Settlement flow
`currency`	string	Código da moeda da operação / Operation currency code

[!IMPORTANT] IMPORTANTE / IMPORTANT

Guarde o token retornado! Ele será obrigatório na próxima etapa para validar a cotação. Save the returned token! It is mandatory for the next step to validate the quotation.

⏱️ Validade do Token de Cotação / Quotation Token Validity¶

[!CAUTION] ATENÇÃO: TOKEN COM VALIDADE LIMITADA! / ATTENTION: LIMITED VALIDITY TOKEN!

O token de cotação retornado possui validade de 1 minuto. Após esse período, o token expira e você precisará solicitar uma nova cotação. The returned quotation token is valid for 1 minute. After this period, it expires and you must request a new quote.

O que acontece após a expiração: / What happens after expiration:

❌ O token não será mais aceito na criação da ordem / Token will no longer be accepted
❌ Será retornado erro: "O token fornecido é inválido ou expirou" / Error: "The provided token is invalid or expired"
✅ Solução: Solicite uma nova cotação via GET /v1/partner/public/orders/outbound/rate-quotation / Solution: Request a new quote

Por que o token expira? / Why does the token expire?¶

As taxas de câmbio são voláteis e podem variar em curtos períodos. A validade de 1 minuto garante que a taxa utilizada reflete as condições atuais do mercado e está conforme as regulamentações do Banco Central. Exchange rates are volatile. The 1-minute validity ensures the rate reflects current market conditions and Central Bank regulations.

Boas Práticas: / Best Practices: * Use o token imediatamente após obtê-lo / Use the token immediately * Se o token expirar, solicite uma nova cotação com os mesmos parâmetros / If expired, request a new quote * Garanta que o processo de criação da ordem ocorra dentro de 1 minuto / Ensure order creation happens within 1 minute

Etapa 2: Criação de Ordem Parcial com Cotação / Step 2: Partial Order Creation with Quotation¶

Endpoint: `POST /v1/partner/public/orders/outbound/create-partial-order-quotation`¶

🔗 Dependências Específicas deste Endpoint / Endpoint Dependencies¶

Ordem / Order	Endpoint	Campo Relacionado / Field	Obrigatório / Mandatory	Descrição / Description
1️⃣	`GET /v1/partner/public/clients/get-filtered`	`clientId`	✅	Buscar o cliente cadastrado (PF ou PJ) - Opcional / Search registered client
2️⃣	`GET /v1/partner/public/currencies/get-all`	`currencyId`	✅	Obter ID da moeda estrangeira / Foreign currency ID
3️⃣	`GET /v1/partner/public/countries/get-all`	`countryId`	✅	Obter ID do país de destino / Destination country ID
4️⃣	`GET /v1/partner/public/finalities/get-all/{clientType?}/{remittanceType?}`	`finalityId`	✅	Obter ID da finalidade da operação / Operation purpose ID
5️⃣	`GET /v1/partner/public/orders/outbound/rate-quotation`	`token`	✅	Obter token da cotação / Obtain quotation token

Esta é a etapa principal do fluxo simplificado. Aqui você cria uma ordem parcial já com a cotação calculada e validada. A ordem é criada no status PENDING_ORDER_INFORMATION (18), aguardando os dados do beneficiário. This is the main step of the simplified flow. Here you create a partial order with a calculated and validated quotation. The order is created with the status PENDING_ORDER_INFORMATION (18).

Dados / Data¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`currencyId`	long	✅	> 0	ID da moeda estrangeira / Foreign currency ID
`amount`	decimal	✅	> 0	Valor em moeda estrangeira / Foreign currency amount
`finalityId`	long	✅	> 0	ID da finalidade da operação / Operation purpose ID
`countryId`	long	✅	> 0	ID do país de destino / Destination country ID
`eSettlementFlow`	int	✅	1-6	Fluxo de liquidação (D0=1, D+1=2, D+2=3, etc.) / Settlement flow
`eDeliveryOption`	int	✅	1-2	Opção de entrega (SWIFT=1, NIUM=2) / Delivery option
`tariff`	decimal	✅	≥ 0	Valor da tarifa / Tariff value
`token`	string	✅	Max 2000 chars	Token obtido na Etapa 1 / Token from Step 1
`clientId`	string	✅	Max 450 chars	ID do cliente (opcional) / Client ID (optional)
`spread`	decimal	✅	0-1	Spread percentual (0-100%) / Percentage spread

[!CAUTION] ATENÇÃO / ATTENTION

O token obtido na Etapa 1 é obrigatório. Certifique-se de fornecer APENAS spread OU contractedRate, nunca ambos. The token from Step 1 is mandatory. Ensure you provide ONLY spread OR contractedRate, never both.

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

Define quando a liquidação financeira ocorrerá para a transação: Defines when the financial settlement will occur for the transaction:

Valor / Value	Nome / Name	Descrição / Description
1	D0	Liquidação no mesmo dia / Same day settlement
2	D+1	Liquidação no próximo dia útil / Next business day settlement
3	D+2	Liquidação dois dias úteis depois / Two business days settlement
4	Termo D0	Liquidação a termo no mesmo dia / Forward same day settlement
5	Termo D1	Liquidação a termo no próximo dia útil / Forward next business day settlement
6	Termo D2	Liquidação a termo dois dias úteis depois / Forward two business days settlement

Opção de Entrega (eDeliveryOption) / Delivery Option¶

Define o método de entrega da transação financeira: Defines the delivery method of the financial transaction:

Valor / Value	Nome / Name	Descrição / Description
1	SWIFT	Entrega através da rede SWIFT / Delivery via SWIFT network
2	NIUM	Entrega através da rede NIUM / Delivery via NIUM network

Exemplo de Requisição / Request Example¶

cURL

POST /v1/partner/public/orders/outbound/create-partial-order-quotation
Content-Type: application/json

JSON (Consulte a tabela de "Dados" para os campos obrigatórios do body)

Resposta de Sucesso / Success Response¶

JSON

{
  "data": {
    "orderId": 1316,
    "currencyId": 1,
    "amount": 1000.00,
    "finalityId": 18,
    "countryId": 1,
    "clientId": "57dfa30c-78f0-4607-8a36-436b08a0e18a",
    "eSettlementFlow": 1,
    "tariff": 10.50,
    "spread": 0.000170,
    "eOrderRemittanceType": 1,
    "eDeliveryOption": 1
  },
  "success": true
}

[!IMPORTANT] IMPORTANTE / IMPORTANT

Guarde o orderId retornado! Ele será usado na próxima etapa para completar a ordem com os dados do beneficiário. Save the returned orderId! It will be used in the next step to complete the order with beneficiary data.

Etapa 3: Complementação com Dados do Beneficiário / Step 3: Completion with Beneficiary Data¶

Endpoint: `PUT /v1/partner/public/orders/outbound/update/{orderId}`¶

🔗 Dependências Específicas deste Endpoint / Endpoint Dependencies¶

Endpoint	Campo Relacionado / Field	Obrigatório / Mandatory	Descrição / Description
`POST /v1/partner/public/orders/outbound/create-partial-order-quotation`	`orderId`	✅	Ordem parcial já criada / Partial order already created
`GET /v1/partner/public/countries/get-all`	`receiver.receiverAccount.countryId`	✅	País do banco do beneficiário / Beneficiary bank country
`GET /v1/partner/public/countries/get-all`	`receiver.intermediaryAccount.countryId`	⚠️ *	País do banco intermediário (se houver) / Intermediary bank country

* Obrigatório apenas quando hasIntermediaryAccount = true.

Nesta etapa final, você completa a ordem criada anteriormente com todos os dados do beneficiário, contas bancárias e documentos necessários. A ordem deve estar no status PENDING_ORDER_INFORMATION (18). In this final step, you complete the previously created order with all beneficiary data, bank accounts, and required documents.

Dados / Data¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`receiver`	object	✅	-	Dados completos do beneficiário / Beneficiary full data
`modality`	int	⚠️ *	1-3	Modalidade (apenas para mercadorias) - 1 - À VISTA, 2 - ANTECIPADO, 3 - À PRAZO / Modality (goods only)
`protocolDI`	string	❌	Max 50 chars	Protocolo DI / DI Protocol
`numberDI`	string	❌	Max 50 chars	Número DI / DI Number
`orderAttachments`	array	✅	-	Anexos da ordem (Invoice) / Order attachments
`shipmentAttachments`	array	⚠️ **	-	Anexos de embarque (Bill of Lading) / Shipment attachments

* modality é obrigatório apenas quando a finalidade for relacionada a mercadorias (ID = 28 para PF ou ID = 18 para PJ). * shipmentAttachments são obrigatórios apenas se finalidade = Mercadorias E* modality = À Vista (1).

[!CAUTION] ATENÇÃO / ATTENTION

A obrigatoriedade do campo modality e dos shipmentAttachments depende da finalidade da ordem criada na etapa anterior. The requirement for modality and shipmentAttachments depends on the order purpose from the previous step.

Dados do Beneficiário (Receiver) / Beneficiary Data¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`name`	string	✅	Max 100 chars	Nome do beneficiário / Beneficiary name
`receiverAccount`	object	✅	-	Conta bancária do beneficiário / Beneficiary bank account
`hasIntermediaryAccount`	boolean	✅	-	Se tem conta intermediária / Whether it has an intermediary account
`intermediaryAccount`	object	⚠️ *	-	Conta intermediária (se necessária) / Intermediary account (if needed)

* Obrigatório quando hasIntermediaryAccount = true.

Dados da Conta Bancária (receiverAccount) / Bank Account Data¶

💳 Consulta de Beneficiários Cadastrados (Opcional) / Search Registered Beneficiaries¶

Antes de preencher manualmente os dados bancários, você pode consultar os beneficiários já cadastrados para facilitar o preenchimento. Before manually filling bank data, you can consult previously registered beneficiaries.

Endpoint: GET /v1/partner/public/account-banks/receiver?userId={aspNetUserId} (opcional: &countryId=)

Parâmetros: / Parameters:

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`personType`	enum	✅	PF (Pessoa Física = 0) ou PJ (Pessoa Jurídica = 1) / Individual or Corporate
`id`	long	✅	ID do cliente (`individualAccountId` ou `corporateAccountId`) / Client ID

Exemplo: / Example:

cURL

GET /v1/partner/public/account-banks/receiver?userId=GUID-DO-USUARIO

Resposta (resumida): / Response (summary):¶

JSON

{
  "success": true,
  "data": [
    {
      "id": 42,
      "name": "Chase Bank",
      "swift": "CHASUS33",
      "number": "1234567890",
      "aba": "021000021",
      "city": "New York",
      "countryId": 840,
      "usageCount": 15
    }
  ]
}

[!INFO] COMO USAR / HOW TO USE

Os beneficiários são ordenados por usageCount (mais usados primeiro). Use o id retornado no campo beneficiaryAccountBankId abaixo para rastreamento, mas sempre envie todos os dados bancários completos na requisição. Beneficiaries are sorted by usageCount. Use the returned id in the beneficiaryAccountBankId field, but always send full bank data in the request.

FCC: o fcc enviado neste PUT (receiver.receiverAccount.fcc / receiver.intermediaryAccount.fcc) é o que vale na ordem, mesmo com beneficiário referenciado; o FCC do cadastro do favorito não substitui o do payload. The fcc sent in this PUT is what prevails, even with a referenced beneficiary.

Campos Opcionais de Referência e Controle / Optional Reference and Control Fields¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`beneficiaryAccountBankId`	long?	❌	> 0	Referência ao beneficiário cadastrado - Quando informado, os dados bancários serão consultados automaticamente. Uma validação de país é aplicada. / Reference to registered beneficiary.
`registerBeneficiary`	bool	❌	-	Salvar beneficiário como favorito - Quando `true`, os dados serão salvos na lista de favoritos do cliente. / Save beneficiary as favorite.

[!INFO] SOBRE O / ABOUT beneficiaryAccountBankId

Quando você informa este campo, três comportamentos importantes ocorrem: When you provide this field, three important behaviors occur:

Validação de País: O sistema valida que o país do beneficiário cadastrado é o mesmo país da ordem. / Country validation.

Consulta Automática de Dados: Todos os dados bancários (SWIFT, conta, ABA, IBAN, etc.) são consultados automaticamente. Você só precisa informar moeda e valor. / Automatic data lookup.

Rastreabilidade: O sistema registra qual beneficiário cadastrado foi usado. / Traceability.

FCC: O FCC da operação é sempre o informado no payload (receiver.receiverAccount.fcc). / The operation FCC is always the one from the payload.

Sobre o registerBeneficiary: Defina como true para salvar automaticamente este beneficiário na lista de favoritos do cliente. / Set to true to save as favorite.

[!IMPORTANT] IMPORTANTE SOBRE O / IMPORTANT ABOUT beneficiaryAccountBankId

✅ Validação de país é obrigatória: O país do beneficiário deve ser igual ao país da ordem. / Country must match order.

✅ Dados são consultados automaticamente: Não é necessário enviar os dados bancários completos. / Full bank data not required.

✅ Você só precisa informar: Moeda e valor da operação. / Only currency and amount needed.

⚠️ FCC é exceção: o campo fcc enviado na ordem sempre prevalece. / Payload FCC always prevails.

💾 Salvar Beneficiário como Favorito / Save Beneficiary as Favorite¶

Ao completar uma ordem outbound com os dados do beneficiário, você pode salvar automaticamente esses dados bancários na lista de favoritos do cliente usando o campo registerBeneficiary. When completing an outbound order, you can auto-save bank data using the registerBeneficiary field.

Benefícios de Salvar como Favorito: / Benefits of Saving as Favorite:

Benefício / Benefit	Descrição / Description
⚡ Agilidade	Reutilização rápida em próximas operações / Fast reuse
✅ Precisão	Reduz erros de digitação em futuras transações / Reduces typing errors
🔄 Praticidade	Não precisa digitar os mesmos dados novamente / No need to re-type
📊 Rastreamento	O beneficiário aparece ordenado por frequência de uso / Sorted by usage frequency

Exemplo de Uso: / Usage Example:

JSON

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

Mensagens de Erro Possíveis: / Possible Error Messages:¶

JSON

{
  "success": false,
  "errors": [
    "Não foi possível salvar o beneficiário como favorito."
  ]
}

[!IMPORTANT] IMPORTANTE / IMPORTANT

Se houver erro ao salvar o beneficiário (quando registerBeneficiary = true), a ordem não será criada e um erro será retornado. Corrija o problema e tente novamente. If an error occurs while saving the beneficiary, the order will not be created and an error will be returned.

Campos Obrigatórios / Mandatory Fields¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`name`	string	✅	Max 255 chars	Nome do banco / Bank name
`swift`	string	✅	8-11 chars	Código SWIFT/BIC (8 ou 11 caracteres) / SWIFT code
`countryId`	long	✅	> 0	ID do país do banco / Bank country ID

[!INFO] INFORMAÇÃO / INFORMATION

A obrigatoriedade dos campos adicionais pode variar dependendo do país da conta do beneficiário. Consulte os requisitos bancários específicos do país de destino para garantir que todos os dados necessários sejam fornecidos. Additional fields requirement may vary by country. Consult destination country specific banking requirements.

Campos Opcionais (Específicos por País/Região) / Optional Fields (Country/Region Specific)¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`number`	string	❌	-	Número da conta bancária / Bank account number
`city`	string	❌	Max 100 chars	Cidade do banco / Bank city
`aba`	string	❌	9 dígitos	ABA Routing Number
`iban`	string	❌	-	IBAN
`sortCode`	string	❌	6 dígitos	Sort Code
`bsb`	string	❌	6 dígitos	BSB
`institutionNumber`	string	❌	3 dígitos	Institution Number
`transit`	string	❌	5 dígitos	Transit Number
`cbu`	string	❌	22 dígitos	CBU
`cuit`	string	❌	-	CUIT
`blz`	string	❌	-	Bankleitzahl
`address`	string	❌	-	Endereço completo do banco / Full bank address
`cable`	string	❌	-	Informações CABLE / CABLE information
`fcc`	string	❌	-	Federal Code Country — Valor que prevalece na ordem / Prevalent value on order

Dados da Conta Bancária (intermediaryAccount) / Intermediary Bank Account Data¶

Quando hasIntermediaryAccount for true, os dados da conta intermediária se tornam obrigatórios. When hasIntermediaryAccount is true, intermediary account data becomes mandatory.

Campo Opcional de Referência / Optional Reference Field¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`beneficiaryAccountBankId`	long?	❌	> 0	Referência ao beneficiário cadastrado para conta intermediária / Reference to registered intermediary account

[!INFO] INFORMAÇÃO / INFORMATION

Sobre o beneficiaryAccountBankId: Assim como na conta do beneficiário, este campo é apenas uma referência opcional. Você deve preencher todos os dados bancários mesmo informando o ID. Just like the beneficiary account, this field is an optional reference. You must provide all bank data even if providing the ID.

💡 Dica: Consulte beneficiários cadastrados usando GET /v1/partner/public/account-banks/receiver?userId=... (documentado acima) para facilitar o preenchimento.

Campos Obrigatórios (Intermediário) / Mandatory Fields (Intermediary)¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`name`	string	✅	Max 255 chars	Nome do banco intermediário / Intermediary bank name
`swift`	string	✅	8-11 chars	Código SWIFT/BIC do banco intermediário / Intermediary SWIFT code
`countryId`	long	✅	> 0	ID do país do banco intermediário / Intermediary bank country ID

Campos Opcionais (Específicos por País/Região) / Optional Fields (Country/Region Specific)¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`number`	string	❌	-	Número da conta bancária / Bank account number
`city`	string	❌	Max 100 chars	Cidade do banco intermediário / Intermediary bank city
`aba`	string	❌	9 dígitos	ABA Routing Number
`iban`	string	❌	-	International Bank Account Number (IBAN)
`sortCode`	string	❌	6 dígitos	Sort Code
`bsb`	string	❌	6 dígitos	Bank State Branch (BSB)
`institutionNumber`	string	❌	3 dígitos	Institution Number
`transit`	string	❌	5 dígitos	Transit Number
`cbu`	string	❌	22 dígitos	Clave Bancaria Uniforme (CBU)
`cuit`	string	❌	-	Código Único de Identificação Tributária (CUIT)
`blz`	string	❌	-	Bankleitzahl (BLZ)
`address`	string	❌	-	Endereço completo do banco / Full bank address
`cable`	string	❌	-	Informações de transferência via CABLE / CABLE info
`fcc`	string	❌	-	Federal Code Country — O FCC enviado no payload da ordem é o utilizado na operação / Payload FCC is used

[!INFO] INFORMAÇÃO / INFORMATION

A obrigatoriedade dos campos da conta intermediária também pode variar dependendo do país. Verifique os requisitos específicos. Intermediary account field requirements may also vary by country. Check specific requirements.

Regras de Campos por País / Field Rules by Country¶

A tabela abaixo detalha os campos obrigatórios e opcionais para transferências para países específicos: The table below details mandatory and optional fields for transfers to specific countries:

Sigla / Code	País / Country	Obrigatório (BANCO) / Bank Name	Obrigatório (SWIFT)	Obrigatório (Conta) / Account	Adicional do País - Obrigatório / Country Specific - Mandatory	Opcional (Não obrigatório) / Optional
DE	Alemanha / Germany	NAME	SWIFT	IBAN		BLZ
AR	Argentina	NAME	SWIFT	NUMBER	CBU	CUIT
AU	Austrália / Australia	NAME	SWIFT	NUMBER		BSB
AT	Áustria / Austria	NAME	SWIFT	IBAN
BE	Bélgica / Belgium	NAME	SWIFT	IBAN
CA	Canadá / Canada	NAME	SWIFT	NUMBER	INSTITUTION NUMBER + TRANSIT + ENDEREÇO
GG	Canal, Ilhas do / Channel Islands	NAME	SWIFT	NUMBER
KY	Cayman, Ilhas / Cayman Islands	NAME	SWIFT	NUMBER
CL	Chile	NAME	SWIFT	NUMBER
CN	China, Rep. Popular / China	NAME	SWIFT	NUMBER
CO	Colômbia / Colombia	NAME	SWIFT	NUMBER
KR	Coréia, Rep. da / South Korea	NAME	SWIFT	NUMBER
DK	Dinamarca / Denmark	NAME	SWIFT	IBAN
EAU	Emirados Árabes Unidos / UAE	NAME	SWIFT	IBAN
ES	Espanha / Spain	NAME	SWIFT	IBAN
US	Estados Unidos / USA	NAME	SWIFT	NUMBER		ABA
TW	Formosa (Taiwan)	NAME	SWIFT	NUMBER
FR	França / France	NAME	SWIFT	IBAN
HK	Hong Kong	NAME	SWIFT	NUMBER
IN	Índia / India	NAME	SWIFT	NUMBER
ID	Indonésia / Indonesia	NAME	SWIFT	NUMBER
IE	Irlanda / Ireland	NAME	SWIFT	IBAN
IL	Israel	NAME	SWIFT	IBAN
IT	Itália / Italy	NAME	SWIFT	IBAN
JP	Japão / Japan	NAME	SWIFT	NUMBER
MX	México / Mexico	NAME	SWIFT	NUMBER	CABLE
NL	Países Baixos / Netherlands	NAME	SWIFT	IBAN
PA	Panamá / Panama	NAME	SWIFT	NUMBER
PY	Paraguai / Paraguay	NAME	SWIFT	NUMBER
PE	Peru	NAME	SWIFT	NUMBER
PR	Porto Rico / Puerto Rico	NAME	SWIFT	NUMBER
PT	Portugal	NAME	SWIFT	IBAN
GB	Reino Unido / United Kingdom	NAME	SWIFT	IBAN		SORT CODE
RO	Romênia / Romania	NAME	SWIFT	IBAN
SG	Singapura / Singapore	NAME	SWIFT	NUMBER
CH	Suíça / Switzerland	NAME	SWIFT	IBAN
TH	Tailândia / Thailand	NAME	SWIFT	NUMBER
TR	Turquia / Turkey	NAME	SWIFT	IBAN
UY	Uruguai / Uruguay	NAME	SWIFT	NUMBER

⚠️ Validação Condicional: Modality / Conditional Validation: Modality¶

A obrigatoriedade do campo modality depende da finalidade (finality) da ordem: The requirement for the modality field depends on the order purpose:

Condição / Condition	`modality`	Validação / Validation
Finalidade = Mercadorias (ID 18 ou 28)	✅ OBRIGATÓRIA	Deve ser 1, 2 ou 3 / Must be 1, 2 or 3
Finalidade ≠ Mercadorias	❌ Deve ser NULL	Não pode ser preenchida / Cannot be filled

Valores de Modality: / Modality Values: * 1 = À VISTA (Pagamento imediato) / CASH (Immediate payment) * 2 = ANTECIPADO (Pagamento antecipado) / ADVANCE (Pre-payment) * 3 = À PRAZO (Pagamento parcelado/futuro) / TERM (Installment/Future payment)

⚠️ Validação Condicional: ShipmentAttachments¶

Quando a finalidade é Mercadorias e a modalidade é À Vista (1), os anexos de embarque são obrigatórios: When the purpose is Goods and modality is Cash (1), shipment attachments are mandatory:

Condição / Condition	`shipmentAttachments`	Validação / Validation
Mercadorias E Modality = 1 (À Vista)	✅ OBRIGATÓRIO	Deve conter pelo menos 1 anexo / Must contain at least 1 file
Mercadorias E Modality = 2 ou 3	❌ Opcional	Pode estar vazio `[]` / Can be empty
Finalidade ≠ Mercadorias	❌ Opcional	Pode estar vazio `[]` / Can be empty

[!INFO] POR QUE ESSA REGRA EXISTE? / WHY DOES THIS RULE EXIST?

Para operações de mercadorias à vista, o comprovante de embarque (Bill of Lading) é obrigatório por regulamentação do Banco Central para comprovar o envio da mercadoria. For cash goods operations, the Bill of Lading is required by Central Bank regulations to prove shipment.

Exemplo de Requisição / Request Example¶

Exemplo 1: Com Referência ao Beneficiário (Recomendado) / With Beneficiary Reference (Recommended)

cURL

PUT /v1/partner/public/orders/outbound/update/123456
Content-Type: multipart/form-data

Formato de Envio (multipart/form-data): / Payload Format: (Utilizado para permitir o upload de arquivos e dados JSON em conjunto).

FormData

FormData:
  Receiver.Name: "John Smith"
  Receiver.ReceiverAccount.BeneficiaryAccountBankId: 42  # Referência opcional
  Receiver.ReceiverAccount.Name: "Chase Bank"            # Dados completos obrigatórios
  Receiver.ReceiverAccount.Swift: "CHASUS33"
  Receiver.ReceiverAccount.Number: "1234567890"
  Receiver.ReceiverAccount.CountryId: 840
  Receiver.ReceiverAccount.City: "New York"
  Receiver.ReceiverAccount.Aba: "021000021"
  Receiver.HasIntermediaryAccount: false
  Modality: 1
  ProtocolDI: "DI2024001"
  NumberDI: "24001234567"
  OrderAttachments[0].File: <arquivo_binario_invoice.pdf>
  OrderAttachments[0].FileName: "invoice.pdf"
  OrderAttachments[0].LogicFile: false
  OrderAttachments[0].DocumentTypeId: 1
  ShipmentAttachments[0].File: <arquivo_binario_bill_of_lading.pdf>
  ShipmentAttachments[0].FileName: "bill_of_lading.pdf"

Exemplo 2: Sem Referência ao Beneficiário / Example 2: Without Beneficiary Reference¶

cURL

PUT /v1/partner/public/orders/outbound/update/123456
Content-Type: multipart/form-data

Formato de Envio (multipart/form-data): / Payload Format:

FormData

FormData:
  Receiver.Name: "John Smith"
  Receiver.ReceiverAccount.Name: "Chase Bank"
  Receiver.ReceiverAccount.Swift: "CHASUS33"
  Receiver.ReceiverAccount.Number: "1234567890"
  Receiver.ReceiverAccount.CountryId: 840
  Receiver.ReceiverAccount.City: "New York"
  Receiver.ReceiverAccount.Aba: "021000021"
  Receiver.HasIntermediaryAccount: false
  Modality: 1
  ProtocolDI: "DI2024001"
  NumberDI: "24001234567"
  OrderAttachments[0].File: <arquivo_binario_invoice.pdf>
  OrderAttachments[0].FileName: "invoice.pdf"
  OrderAttachments[0].LogicFile: false
  OrderAttachments[0].DocumentTypeId: 1
  ShipmentAttachments[0].File: <arquivo_binario_bill_of_lading.pdf>
  ShipmentAttachments[0].FileName: "bill_of_lading.pdf"

Estrutura dos Anexos: / Attachments Structure:

Estrutura dos Anexos / Attachments Structure¶

OrderAttachments (Invoice e documentos da ordem)¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`File`	IFormFile	✅	Arquivo binário (PDF, JPEG, JPG, PNG) / Binary file
`FileName`	string	❌	Nome do arquivo (preenchido automaticamente se não fornecido) / Filename

ShipmentAttachments (Bill of Lading e documentos de embarque)¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`File`	IFormFile	✅	Arquivo binário (PDF, JPEG, JPG, PNG) / Binary file
`FileName`	string	❌	Nome do arquivo (preenchido automaticamente se não fornecido) / Filename

[!INFO] INFORMAÇÃO / INFORMATION

Importante: Como esta é uma requisição multipart/form-data, os arquivos devem ser enviados como binários. Os campos podem ser enviados com nomenclatura de array: Since this is a multipart/form-data request, files must be sent as binaries. Use array notation:

OrderAttachments[0].File, OrderAttachments[0].FileName, etc.

ShipmentAttachments[0].File, ShipmentAttachments[0].FileName, etc.

🌍 Exemplo para Diferentes Países / Examples for Different Countries¶

Transferência para o Reino Unido (GB): / Transfer to United Kingdom¶

JSON

"receiverAccount": {
  "name": "Barclays Bank",
  "swift": "BARCGB22",
  "countryId": 826,
  "city": "London",
  "iban": "GB29NWBK60161331926819",
  "sortCode": "200000"
}

Transferência para a Austrália (AU): / Transfer to Australia¶

JSON

"receiverAccount": {
  "name": "Commonwealth Bank",
  "swift": "CTBAAU2S",
  "countryId": 36,
  "city": "Sydney",
  "number": "123456789",
  "bsb": "062000"
}

Transferência para o Canadá (CA): / Transfer to Canada¶

JSON

"receiverAccount": {
  "name": "Royal Bank of Canada",
  "swift": "ROYCCAT2",
  "countryId": 124,
  "city": "Toronto",
  "number": "1234567",
  "institutionNumber": "003",
  "transit": "12345",
  "address": "123 Yonge Street, Toronto, ON, M5E 1W7"
}

ℹ️ Diferença entre OrderAttachments e ShipmentAttachments / Difference between Order and Shipment Attachments¶

Tipo / Type	Uso / Usage	Exemplos de Documentos / Document Examples
orderAttachments	Documentos gerais da ordem / General order documents	Faturas (invoices), contratos, notas fiscais, documentos fiscais / Invoices, contracts, tax docs
shipmentAttachments	Documentos de envio/transporte / Shipping documents	Conhecimento de embarque (Bill of Lading), packing list, certificados de origem / Bill of Lading, packing list

Resposta de Sucesso / Success Response¶

JSON

{
    "data": {
        "receiver": {
            "name": "John Doe",
            "receiverAccount": {
                "name": "Bank of America",
                "swift": "BOFAUS3N",
                "number": "123456789",
                "aba": "026009593",
                "countryId": 1,
                "city": "New York",
                "address": "1234 Main Street",
                "validationGuid": "5521bf0e-5858-4c97-ac2e-94e063982392"
            },
            "hasIntermediaryAccount": false,
            "validationGuid": "57a5b967-c18b-448a-a0b1-21ab144201e7"
        },
        "modality": 2,
        "orderAttachments": [
            {
                "fileName": "teste.png",
                "logicFile": false,
                "file": {
                    "contentDisposition": "form-data; name=\"OrderAttachments[0].File\"; filename=\"teste_cpf.png\"",
                    "contentType": "image/png",
                    "headers": {
                        "content-Disposition": [
                            "form-data; name=\"OrderAttachments[0].File\"; filename=\"teste_cpf.png\""
                        ],
                        "content-Type": [
                            "image/png"
                        ]
                    },
                    "length": 2545415,
                    "name": "OrderAttachments[0].File",
                    "fileName": "teste_cpf.png"
                },
                "validationGuid": "78a7f4d7-bbf6-4299-9b47-9b3cf58278ce",
                "validationResult": {
                    "isValid": true,
                    "errors": [],
                    "ruleSetsExecuted": [
                        "default"
                    ]
                }
            }
        ],
        "shipmentAttachments": [],
        "validationGuid": "ca402668-9eea-4ce8-97fb-23d87897300a",
        "validationResult": {
            "isValid": true,
            "errors": [],
            "ruleSetsExecuted": [
                "default"
            ]
        }
    },
    "success": true
}

[!INFO] INFORMAÇÃO / INFORMATION

Sucesso! A ordem foi completada e está pronta para seguir no fluxo de processamento automático. Success! The order has been completed and is ready for the automatic processing flow.

Etapa 4: Envio de Comprovante de Pagamento (Etapa opcional) / Step 4: Upload Payment Receipt (Optional Step)¶

Endpoint: `POST /v1/partner/public/orders/outbound/{orderId}/upload-receipt`¶

🔗 Dependências Específicas deste Endpoint / Endpoint Dependencies¶

Este endpoint requer que você já tenha completado a ordem com os dados do beneficiário: This endpoint requires that you have already completed the order with beneficiary data:

Ordem / Order	Endpoint	Campo Relacionado / Field	Obrigatório / Mandatory	Descrição / Description
1️⃣	`PUT /v1/partner/public/orders/outbound/update/{orderId}`	`orderId`	✅	Ordem já completada / Order already completed

Validações antes de enviar o comprovante: / Validations before uploading:¶

✅ Ordem deve existir no sistema / Order must exist in the system
✅ Ordem deve estar em status apropriado para receber comprovante / Order must be in appropriate status
✅ Arquivo deve ter formato válido (PDF, JPEG, JPG, PNG) / Valid file format
✅ Arquivo deve ter no máximo 5MB / Maximum file size 5MB

Após completar a ordem com os dados do beneficiário, você deve enviar o comprovante de pagamento que será anexado à ordem para processamento e liquidação. After completing the order, upload the payment receipt to be attached for processing and settlement.

Dados / Data¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`orderId`	long	✅	> 0	ID da ordem criada (via path parameter) / Order ID
`file`	IFormFile	✅	Not null	Arquivo do comprovante de pagamento / Payment receipt file
`fileName`	string	✅	Max 255 chars	Nome customizado para o arquivo / Custom filename

Validações de Arquivo / File Validations¶

Validação / Validation	Regra / Rule	Descrição / Description
Formato	PDF, JPEG, JPG, PNG	Apenas estes formatos são aceitos / Only these formats accepted
Tamanho	Máximo 5MB	O arquivo não pode exceder 5 megabytes / Max file size 5MB
Obrigatoriedade	Não nulo	O arquivo é obrigatório / File is mandatory

[!CAUTION] ATENÇÃO / ATTENTION

O arquivo deve ser enviado como multipart/form-data. Certifique-se de que o Content-Type da requisição está configurado corretamente. The file must be sent as multipart/form-data. Ensure the Content-Type is correctly set.

Exemplo de Requisição / Request Example¶

cURL

POST /v1/partner/public/orders/outbound/{orderId}/upload-receipt
Content-Type: multipart/form-data

FormData:
  File: <arquivo_binario>

Exemplo com cURL Completo / Full cURL Example¶

cURL Completo

curl -X POST "[https://api.xavipay.com/v1/partner/public/orders/outbound/123456/upload-receipt](https://api.xavipay.com/v1/partner/public/orders/outbound/123456/upload-receipt)" \
  -H "Authorization: Bearer {seu_jwt_token}" \
  -H "x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e" \
  -H "Accept-Language: pt-br" \
  -F "File=@/caminho/para/comprovante_pagamento.pdf"

[!INFO] INFORMAÇÃO / INFORMATION

Importante: O campo do arquivo deve ser nomeado como File (com F maiúsculo) conforme esperado pela API. Important: The file field must be named File (capital F) as expected by the API.

Resposta de Sucesso / Success Response¶

JSON

{
  "success": true,
  "data": {
    "fileName": "comprovante_pagamento.pdf",
    "file": {
          "contentDisposition": "form-data; name=\"OrderAttachments[0].File\"; filename=\"teste_cpf.png\"",
          "contentType": "image/png",
          "headers": {
              "content-Disposition": [
                  "form-data; name=\"OrderAttachments[0].File\"; filename=\"teste_cpf.png\""
               ],
               "content-Type": [
                   "image/png"
               ]
          },
          "length": 2545415,
          "name": "example.File",
          "fileName": "teste_cpf.png"
       }  
    }
}

Descrição dos Campos da Resposta / Response Fields Description¶

Campo / Field	Tipo / Type	Descrição / Description
`fileName`	string	Nome do arquivo que foi enviado / Sent filename
`File`	file	Tipo IFormFile com o arquivo enviado / IFormFile type with the sent file

💡 Quando Enviar o Comprovante? / When to Send the Receipt?¶

O comprovante de pagamento pode ser enviado opcionalmente: The payment receipt can be sent optionally:

✅ Após completar a ordem (Etapa 3) / After completing the order (Step 3)
✅ Quando a ordem estiver em status AVAILABLE_PAYMENT (9) / When order is in AVAILABLE_PAYMENT status
✅ Antes da liquidação final da ordem / Before the final settlement of the order

Monitoramento e Consultas / Monitoring and Queries¶

Consultar Detalhes de uma Ordem / Get Order Details¶

Endpoint: GET /v1/partner/public/orders/outbound/get-detail/{orderId}

cURL

GET /v1/partner/public/orders/outbound/get-detail/123456

Resposta / Response¶

JSON

{
  "success": true,
  "data": {
    "id": 123456,
    "clientId": "USR-2024-001-ABC123",
    "name": "João Silva Santos",
    "typeDocument": "CPF",
    "document": "12345678901",
    "createdDateClient": "2024-01-01T10:00:00Z",
    "status": 18,
    "finality": {
      "id": 18,
      "description": "Importação de mercadorias"
    },
    "currency": {
      "id": 1,
      "description": "USD - United States Dollar",
      "code": "USD"
    },
    "amount": 10000.00,
    "modality": 2,
    "createdDate": "2024-01-15T14:30:00Z",
    "receiver": {
      "name": "John Smith",
      "country": "United States",
      "bankAccount": {
        "bankName": "Chase Bank",
        "accountNumber": "1234567890"
      }
    },
    "protocolDI": "DI-2024-001234",
    "numberDI": "24001234567"
  }
}

Listar Ordens com Filtros / List Orders with Filters¶

Endpoint: GET /v1/partner/public/orders/outbound/get-filtered

Parâmetros de Query / Query Parameters:¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`page`	int	❌	Página atual (padrão: 0) / Current page (default: 0)
`rowsPerPage`	int	❌	Itens por página (padrão: 50, máximo: 100) / Items per page
`name`	string	❌	Nome do cliente para filtrar / Client name filter
`document`	string	❌	CPF/CNPJ para filtrar / Tax ID (CPF/CNPJ) filter
`clientType`	int	❌	Tipo de cliente (0=PF, 1=PJ) / Client type
`status`	int	❌	Status da ordem (1-18, veja tabela abaixo) / Order status
`currency`	int	❌	ID da moeda (1=USD, 2=EUR, 3=GBP, etc.) / Currency ID
`createdDateInitial`	datetime	❌	Data inicial de criação (YYYY-MM-DD ou ISO 8601) / Start date
`createdDateFinal`	datetime	❌	Data final de criação (YYYY-MM-DD ou ISO 8601) / End date
`orderBy`	string	❌	Campo para ordenação (ex: `createdDate`, `name`, `value`) / Sort field
`direction`	string	❌	Direção da ordenação (ASC/DESC) / Sort direction

Exemplo de Requisição / Request Example¶

cURL

GET /v1/partner/public/orders/outbound/get-filtered?page=0&rowsPerPage=50&status=18&currency=1&createdDateInitial=2024-01-01

Resposta / Response¶

JSON

{
  "success": true,
  "data": {
    "total": 150,
    "page": 0,
    "rowsPerPage": 50,
    "data": [
      {
        "id": 123456,
        "clientId": "USR-2024-001-ABC123",
        "clientType": 0,
        "name": "João Silva Santos",
        "typeDocument": "CPF",
        "document": "12345678901",
        "createdDate": "2024-01-15T14:30:00Z",
        "beneficiary": "John Smith",
        "currency": "USD",
        "value": 10000.00,
        "status": 18,
        "remmitanceType": 1,
        "modality": 2
      }
    ]
  }
}

📊 Status Possíveis de Ordens / Possible Order Statuses¶

Abaixo está a lista completa de todos os status que uma ordem pode ter durante seu ciclo de vida: Below is the complete list of all statuses an order can have during its lifecycle:

Código / Code	Nome / Name	Descrição / Description	Fase / Phase
1	`PENDING_DOCUMENTATION`	Aguardando documentação obrigatória / Waiting for documentation	⏳ Inicial
2	`PROCESSING`	Ordem sendo processada pelo sistema / System processing	🔄 Processamento
3	`REPROVED_WITH_CORRECTION`	Reprovada, mas pode ser corrigida / Reproved, correction possible	⚠️ Atenção
4	`CANCELED`	Ordem cancelada, não será processada / Order canceled	❌ Finalizada
5	`CLOSED`	Ordem completada e fechada com sucesso / Success closed	✅ Finalizada
6	`PAID`	Pagamento confirmado e processado / Payment confirmed	💰 Finalizada
7	`AVAILABLE_QUOTATION`	Pronta para geração de cotação / Ready for quotation	💎 Cotação
8	`REPROVED_WITHOUT_CORRECTION`	Reprovada permanentemente / Permanently reproved	❌ Finalizada
9	`AVAILABLE_PAYMENT`	Pronta para processamento de pagamento / Ready for payment	💳 Pagamento
10	`PENDING_INVOICE_INFORMATION`	Aguardando detalhes da fatura / Waiting for invoice info	⏳ Documentação
11	`PENDING_INVOICE_ATTACHMENT`	Aguardando anexo da fatura / Waiting for invoice file	⏳ Documentação
12	`IDENTIFYING_PAYMENT`	Sistema identificando o pagamento / Identifying payment	🔍 Pagamento
13	`IDENTIFIED_PAYMENT`	Pagamento identificado com sucesso / Payment identified	✅ Pagamento
14	`IDENTIFYING_PAYMENT_ABROAD`	Identificando pagamento do exterior / Identifying payment abroad	🔍 Pagamento
15	`IDENTIFIED_PAYMENT_ABROAD`	Pagamento do exterior identificado / Abroad payment identified	✅ Pagamento
16	`PENDING_PAYMENT_INFORMATION`	Aguardando informações de pagamento / Waiting for payment info	⏳ Pagamento
17	`PAYMENT_REPROVED`	Pagamento reprovado, precisa reprocessar / Payment reproved	⚠️ Pagamento
18	`PENDING_ORDER_INFORMATION`	Aguardando informações adicionais da ordem / Waiting for order info	⏳ Documentação

Possíveis Erros / Potential Errors¶

Etapa 1 - Simulação de Cotação / Step 1 - Quote Simulation¶

Parâmetros Obrigatórios Ausentes / Missing Mandatory Parameters¶

JSON

{
  "success": false,
  "errors": [
    "O ID da moeda é obrigatório",
    "A tarifa é obrigatória"
  ]
}

Spread e Taxa Contratada Simultâneos / Simultaneous Spread and Contracted Rate¶

JSON

{
  "success": false,
  "errors": [
    "Você deve fornecer APENAS spread OU contractedRate (Taxa Contratada), nunca ambos"
  ]
}

Amount e AmountNC Simultâneos / Simultaneous Amount and AmountNC¶

JSON

{
  "success": false,
  "errors": [
    "Você deve fornecer APENAS amount OU amountNC, nunca ambos"
  ]
}

Etapa 2 - Criação de Ordem Parcial / Step 2 - Partial Order Creation¶

Token Inválido ou Expirado / Invalid or Expired Token¶

JSON

{
  "success": false,
  "errors": [
    "O token fornecido é inválido ou expirou. Por favor, obtenha uma nova cotação."
  ]
}

Dados Obrigatórios Ausentes / Missing Mandatory Data¶

JSON

{
  "success": false,
  "errors": [
    "O ID da moeda é obrigatório",
    "O valor é obrigatório",
    "O ID da finalidade é obrigatório",
    "O ID do país é obrigatório",
    "O fluxo de liquidação é obrigatório",
    "A opção de entrega é obrigatória",
    "O token é obrigatório"
  ]
}

Etapa 3 - Complementação da Ordem / Step 3 - Order Completion¶

Ordem Não Encontrada / Order Not Found¶

JSON

{
  "success": false,
  "errors": ["Ordem não encontrada"]
}

Status da Ordem Inadequado / Inadequate Order Status¶

JSON

{
  "success": false,
  "errors": [
    "A ordem não está no status PENDING_ORDER_INFORMATION. Status atual: AVAILABLE_QUOTATION"
  ]
}

Modality Obrigatória Não Fornecida / Mandatory Modality Not Provided¶

JSON

{
  "success": false,
  "errors": [
    "A modalidade é obrigatória para operações de mercadorias"
  ]
}

Modality Fornecida para Finalidade Inválida / Modality Provided for Invalid Purpose¶

JSON

{
  "success": false,
  "errors": [
    "A modalidade não deve ser informada para finalidades que não sejam mercadorias"
  ]
}

Dados do Beneficiário Incompletos / Incomplete Beneficiary Data¶

JSON

{
  "success": false,
  "errors": [
    "O nome do beneficiário é obrigatório",
    "O país do beneficiário é obrigatório",
    "A conta bancária do beneficiário é obrigatória"
  ]
}

Beneficiário Cadastrado Não Encontrado / Registered Beneficiary Not Found¶

JSON

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

[!INFO] INFORMAÇÃO / INFORMATION

Quando este erro ocorre: Se você informar um beneficiaryAccountBankId que não existe no sistema ou não pertence ao cliente informado. When this error occurs: If you provide a beneficiaryAccountBankId that does not exist in the system or does not belong to the informed client.

País do Beneficiário Diferente do País da Ordem / Beneficiary Country Different from Order Country¶

JSON

{
  "success": false,
  "errors": [
    "O país do beneficiário deve ser o mesmo da ordem."
  ]
}

[!INFO] INFORMAÇÃO / INFORMATION

Quando este erro ocorre: Se você informar um beneficiaryAccountBankId cujo país cadastrado é diferente do país da ordem. Esta validação garante a consistência dos dados da operação. When this error occurs: If you provide a beneficiaryAccountBankId whose registered country is different from the order country. This validation ensures operational data consistency.

Erro ao Salvar Beneficiário como Favorito / Error Saving Beneficiary as Favorite¶

JSON

{
  "success": false,
  "errors": [
    "Não foi possível salvar o beneficiário como favorito."
  ]
}

[!INFO] INFORMAÇÃO / INFORMATION

Quando este erro ocorre: Se você definir registerBeneficiary = true mas ocorrer um erro ao tentar salvar o beneficiário na lista de favoritos (por exemplo, erro de banco de dados, validação falhou, etc.). Quando este erro ocorre, a ordem não é atualizada. When this error occurs: If you set registerBeneficiary = true but an error occurs when trying to save the beneficiary to the favorites list (e.g., database error, validation failed, etc.). When this error occurs, the order is not updated.

Validação de Conta Bancária / Bank Account Validation¶

JSON

{
  "success": false,
  "errors": [
    "O nome do banco é obrigatório",
    "O código SWIFT é obrigatório"
  ]
}

ShipmentAttachments Obrigatórios Ausentes / Missing Mandatory ShipmentAttachments¶

JSON

{
  "success": false,
  "errors": [
    "Para operações de mercadorias à vista, os anexos de embarque são obrigatórios"
  ]
}

Etapa 4 - Envio de Comprovante de Pagamento / Step 4 - Payment Proof Submission¶

Arquivo Não Fornecido / File Not Provided¶

JSON

{
  "success": false,
  "errors": [
    "O arquivo é obrigatório"
  ]
}

Formato de Arquivo Inválido / Invalid File Format¶

JSON

{
  "success": false,
  "errors": [
    "O formato do arquivo é inválido. Formatos aceitos: PDF, JPEG, JPG, PNG"
  ]
}

Tamanho do Arquivo Excedido / File Size Exceeded¶

JSON

{
  "success": false,
  "errors": [
    "O tamanho do arquivo excede o limite de 5MB"
  ]
}

Nome do Arquivo Muito Longo / File Name Too Long¶

JSON

{
  "success": false,
  "errors": [
    "O nome do arquivo deve ter no máximo 255 caracteres"
  ]
}

Status da Ordem Inadequado / Invalid Order Status¶

JSON

{
  "success": false,
  "errors": [
    "A ordem não está em um status que permite o envio de comprovante de pagamento"
  ]
}

Consultas / Queries¶

Ordem Não Encontrada / Order Not Found¶

JSON

{
  "success": false,
  "errors": ["Ordem não encontrada"]
}

Ordem Não Encontrada / Order Not Found¶

JSON

{
  "success": false,
  "errors": [
    "A página deve ser maior que zero",
    "O número de itens por página deve ser maior que zero"
  ]
}

Considerações Importantes / Important Considerations¶

🔒 Limitações e Validações / Limitations & Validations¶

Token de cotação válido: obrigatório na Etapa 2 / Valid quote token: mandatory in Step 2
Ordem em status correto (18): obrigatória na Etapa 3 / Order in correct status (18): mandatory in Step 3
Modalidade condicional: baseada na finalidade / Conditional modality: based on the purpose
Campos bancários: validados por país automaticamente / Bank fields: automatically validated by country
Anexos condicionais: baseados em modalidade e finalidade / Conditional attachments: based on modality and purpose
Spread entre 0 e 1 (0% a 100%) OU Taxa Contratada: (mutuamente exclusivos) / Spread between 0 and 1 OR Contracted Rate (mutually exclusive)
Tarifa não negativa: obrigatória / Non-negative fee: mandatory
Comprovante de pagamento: formato válido (PDF, JPEG, JPG, PNG) / Payment proof: valid format
Tamanho do arquivo: máximo 5MB / File size: maximum 5MB
Nome do arquivo: máximo 255 caracteres / File name: maximum 255 characters

✅ Validações Automáticas / Automatic Validations¶

Token: Validade temporal e integridade / Token: Time validity and integrity
Status da ordem: Verificação automática antes de atualizar ou enviar comprovante / Order status: Automatic check before updating or sending proof
Finalidade vs Modality: Validação da regra de negócio / Purpose vs Modality: Business rule validation
Modality vs ShipmentAttachments: Validação da regra de mercadorias à vista / Modality vs ShipmentAttachments: Validation for spot goods rule
País vs Campos bancários: Validação de campos obrigatórios por país / Country vs Bank fields: Mandatory fields validation by country
Formato do comprovante: Validação automática de extensão (PDF, JPEG, JPG, PNG) / Proof format: Automatic extension validation
Tamanho do comprovante: Validação automática de limite (5MB) / Proof size: Automatic limit validation (5MB)
Compliance: Validação automática de sanções e PEP / Compliance: Automatic sanctions and PEP validation

📎 Download de Anexos da Ordem / Download Order Attachments¶

Após criar e atualizar uma ordem, você pode fazer o download dos anexos (invoices, fichas de embarque, etc.) através dos seguintes endpoints.

Endpoint 1: Download de Todos os Anexos de uma Ordem / Download All Attachments of an Order¶

GET /v1/partner/public/orders/attachments/{orderId}/download

Retorna todos os anexos associados a uma ordem específica, incluindo o conteúdo dos arquivos e o tipo de cada documento.

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

Quer baixar todos os documentos de uma ordem de uma vez / Want to download all order documents at once
Precisa listar todos os anexos com seus tipos identificados / Need to list all attachments with identified types
Quer saber quais documentos estão associados a uma ordem / Want to know which documents are associated with an order

Parâmetros da URL / URL Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`orderId`	long	✅	Identificador único da ordem / Unique order identifier

Exemplo de Requisição / Request Example¶

cURL

curl --location '[https://api.xavipay.com.br/v1/partner/public/orders/attachments/44564/download](https://api.xavipay.com.br/v1/partner/public/orders/attachments/44564/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¶

JSON

Fluxo Simplificado: Criação de Ordens de Envio (Outbound) com Taxa Contratada / Simplified Outbound Order Flow with Contracted Rate¶

Visão Geral / Overview¶

Autenticação / Authentication¶

Descrição dos Headers: / Headers Description:¶

⚡ Rate Limiting¶

Limites Aplicados / Applied Limits¶

Headers de Resposta / Response Headers¶

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

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

Endpoints Auxiliares / Auxiliary Endpoints¶

📋 Importante: Naturezas de Operação (Finalities) / Important: Nature of Operation¶

O que são Finalidades? / What are Purposes?¶

Como Funcionam os IDs / How IDs Work¶

Operações com Naturezas Não Listadas / Operations with Unlisted Natures¶

Enquadramento de Operações / Operation Framework¶

Etapa 1: Obtenção das Taxas / Step 1: Obtaining Rates¶

Endpoint: GET /v1/partner/public/orders/outbound/rate-quotation¶

🔗 Dependências Específicas deste Endpoint / Endpoint Dependencies¶

Dados / Data¶

Modos de Cálculo / Calculation Modes¶

Modo 1: Usando Spread / Mode 1: Using Spread¶

Modo 2: Usando Taxa Contratada / Mode 2: Using Contracted Rate¶

Modo 3: Convertendo de BRL para Moeda Estrangeira / Mode 3: Converting BRL to Foreign Currency¶

Exemplo de Requisição / Request Example¶

Resposta de Sucesso / Success Response¶

Descrição dos Campos Retornados / Description of Returned Fields¶

⏱️ Validade do Token de Cotação / Quotation Token Validity¶

Por que o token expira? / Why does the token expire?¶

Etapa 2: Criação de Ordem Parcial com Cotação / Step 2: Partial Order Creation with Quotation¶

Endpoint: POST /v1/partner/public/orders/outbound/create-partial-order-quotation¶

🔗 Dependências Específicas deste Endpoint / Endpoint Dependencies¶

Dados / Data¶

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

Opção de Entrega (eDeliveryOption) / Delivery Option¶

Exemplo de Requisição / Request Example¶

Resposta de Sucesso / Success Response¶

Etapa 3: Complementação com Dados do Beneficiário / Step 3: Completion with Beneficiary Data¶

Endpoint: PUT /v1/partner/public/orders/outbound/update/{orderId}¶

🔗 Dependências Específicas deste Endpoint / Endpoint Dependencies¶

Dados / Data¶

Dados do Beneficiário (Receiver) / Beneficiary Data¶

Dados da Conta Bancária (receiverAccount) / Bank Account Data¶

💳 Consulta de Beneficiários Cadastrados (Opcional) / Search Registered Beneficiaries¶

Resposta (resumida): / Response (summary):¶

Campos Opcionais de Referência e Controle / Optional Reference and Control Fields¶

💾 Salvar Beneficiário como Favorito / Save Beneficiary as Favorite¶

Mensagens de Erro Possíveis: / Possible Error Messages:¶

Campos Obrigatórios / Mandatory Fields¶

Campos Opcionais (Específicos por País/Região) / Optional Fields (Country/Region Specific)¶

Dados da Conta Bancária (intermediaryAccount) / Intermediary Bank Account Data¶

Campo Opcional de Referência / Optional Reference Field¶

Campos Obrigatórios (Intermediário) / Mandatory Fields (Intermediary)¶

Campos Opcionais (Específicos por País/Região) / Optional Fields (Country/Region Specific)¶

Regras de Campos por País / Field Rules by Country¶

⚠️ Validação Condicional: Modality / Conditional Validation: Modality¶

⚠️ Validação Condicional: ShipmentAttachments¶

Exemplo de Requisição / Request Example¶

Exemplo 2: Sem Referência ao Beneficiário / Example 2: Without Beneficiary Reference¶

Estrutura dos Anexos / Attachments Structure¶

OrderAttachments (Invoice e documentos da ordem)¶

ShipmentAttachments (Bill of Lading e documentos de embarque)¶

🌍 Exemplo para Diferentes Países / Examples for Different Countries¶

Transferência para o Reino Unido (GB): / Transfer to United Kingdom¶

Transferência para a Austrália (AU): / Transfer to Australia¶

Transferência para o Canadá (CA): / Transfer to Canada¶

Transferência para o Canadá (CA): / Transfer to Canada¶

ℹ️ Diferença entre OrderAttachments e ShipmentAttachments / Difference between Order and Shipment Attachments¶

Resposta de Sucesso / Success Response¶

Etapa 4: Envio de Comprovante de Pagamento (Etapa opcional) / Step 4: Upload Payment Receipt (Optional Step)¶

Endpoint: POST /v1/partner/public/orders/outbound/{orderId}/upload-receipt¶

🔗 Dependências Específicas deste Endpoint / Endpoint Dependencies¶

Validações antes de enviar o comprovante: / Validations before uploading:¶

Dados / Data¶

Validações de Arquivo / File Validations¶

Exemplo de Requisição / Request Example¶

Exemplo com cURL Completo / Full cURL Example¶

Resposta de Sucesso / Success Response¶

Descrição dos Campos da Resposta / Response Fields Description¶

💡 Quando Enviar o Comprovante? / When to Send the Receipt?¶

Monitoramento e Consultas / Monitoring and Queries¶

Endpoint: `GET /v1/partner/public/orders/outbound/rate-quotation`¶

Endpoint: `POST /v1/partner/public/orders/outbound/create-partial-order-quotation`¶

Endpoint: `PUT /v1/partner/public/orders/outbound/update/{orderId}`¶

Endpoint: `POST /v1/partner/public/orders/outbound/{orderId}/upload-receipt`¶