Cotação de Ordens / Order Quotation¶

Visão Geral / Overview¶

A Cotação de Ordens é o processo que permite obter taxas de câmbio e custos aplicáveis para ordens previamente criadas na plataforma Partner Hub. Este processo fornece informações precisas sobre custos totais, taxas e prazos de liquidação.

The Order Quotation is the process that allows obtaining exchange rates and applicable costs for orders previously created on the Partner Hub platform. This process provides accurate information about total costs, rates, and settlement terms.

Autenticação / Authentication¶

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

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

Descrição dos Headers / Headers Description:¶

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

[!IMPORTANT] IMPORTANTE / IMPORTANT

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

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

Processo de Cotação / Quotation Process¶

Endpoint: `POST /v1/partner/public/orders/quotation`¶

Após criar uma ordem outbound, você deve solicitar uma cotação para obter as taxas de câmbio e custos aplicáveis. After creating an outbound order, you must request a quotation to obtain the exchange rates and applicable costs.

Dados Obrigatórios / Required Data¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`orderId`	long	✅	> 0	ID da ordem criada previamente Order ID previously created
`token`	string	✅	Max 2000 chars	Token de autenticação obrigatório Authentication token (required)

Dados Opcionais (Configurações Avançadas) / Optional Data (Advanced Settings)¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`spread`	decimal?	❌	$0 \le valor \le 1$	Spread personalizado (0-100%) *Custom spread*
`tariff`	decimal?	❌	$\ge 0$	Tarifa personalizada *Custom fee*
`settlementFlow`	enum?	❌	1-6	Fluxo de liquidação *Settlement flow*
`deliveryOption`	enum?	❌	1-2	Opção de entrega *Delivery option*

Opções de Settlement Flow / Settlement Flow Options¶

Valor / Value	Descrição / Description	Tipo / Type
1	D0 - Liquidação no mesmo dia / Same-day settlement	Pronta / Spot
2	D+1 - Liquidação no próximo dia útil / Next business day	Pronta / Spot
3	D+2 - Liquidação em dois dias úteis / Two business days	Pronta / Spot
4	Termo D0 - Liquidação a termo no mesmo dia	Termo / Forward
5	Termo D1 - Liquidação a termo no próximo dia	Termo / Forward
6	Termo D2 - Liquidação a termo em dois dias	Termo / Forward

Opções de Delivery / Delivery Options¶

Valor / Value	Descrição / Description	Rede / Network
1	SWIFT - Rede SWIFT tradicional / Traditional SWIFT	Internacional
2	NIUM - Rede NIUM (mais rápida) / NIUM Network (faster)	Digital

Exemplo de Requisição / Request Example¶

JSON

{
  "orderId": 123456,
  "spread": 0.02,
  "tariff": 50.0,
  "settlementFlow": 2,
  "deliveryOption": 1,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Resposta de Sucesso / Success Response¶

JSON

{
  "success": true,
  "data": {
    "orderId": 123456,
    "spread": 0.02,
    "tariff": 50.0,
    "settlementFlow": 2,
    "deliveryOption": 1,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "exchangeRate": 5.285,
    "totalCostBRL": 53050.0,
    "fees": {
      "spreadAmount": 1050.0,
      "tariffAmount": 50.0,
      "totalFees": 1100.0
    },
    "quotationValidUntil": "2024-01-15T15:30:00Z"
  }
}

Possíveis Erros / Possible Errors¶

Dados Obrigatórios da Cotação / Quotation Required Data¶

Mensagens exibidas quando campos essenciais do payload estão ausentes ou inválidos: Messages displayed when essential payload fields are missing or invalid:

JSON

{
  "success": false,
  "errors": [
    "O ID da ordem é obrigatório",
    "O ID da ordem deve ser maior que zero",
    "O token é obrigatório",
    "O token não pode ser nulo",
    "O token deve ter no máximo 2000 caracteres"
  ]
}

Validação de Spread / Spread Validation¶

JSON

{
  "success": false,
  "errors": ["O spread deve estar entre 0 e 1 (0% a 100%)"]
}

Validação de Tarifa / Fee Validation¶

JSON

{
  "success": false,
  "errors": ["A tarifa deve ser maior ou igual a zero"]
}

Ordem Não Encontrada / Order Not Found¶

JSON

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

Considerações Importantes / Important Considerations¶

Limitações e Validações / Limitations and Validations¶

Ordem previamente criada obrigatória no sistema
Previously created order is mandatory in the system
Token de cotação válido obrigatório
Valid quotation token is mandatory
Spread entre 0 e 1 (0% a 100%)
Spread between 0 and 1 (0% to 100%)
Tarifa não negativa obrigatória
Non-negative fee is mandatory
Settlement flow válido (1-6)
Valid settlement flow (1-6)
Delivery option válida (1-2)
Valid delivery option (1-2)

Validações Automáticas / Automatic Validations¶

ID da ordem: Deve ser maior que zero
Order ID: Must be greater than zero
Token: Máximo 2000 caracteres - OBRIGATÓRIO
Token:* Maximum 2000 characters - MANDATORY***
Spread: Entre 0 e 1 quando fornecido
Spread: Between 0 and 1 when provided
Tarifa: Valor não negativo quando fornecido
Fee: Non-negative value when provided
Compliance: Validação automática de sanções e PEP
Compliance: Automatic validation of sanctions and PEP

Integração Recomendada / Recommended Integration¶

Fluxo de Desenvolvimento / Development Workflow¶

1. Ambiente de Sandbox / Sandbox Environment * Teste cotações com ordens fictícias / Test quotations with mock orders * Valide diferentes configurações de spread e tarifa / Validate different spread and fee settings * Teste cenários de erro / Test error scenarios

2. Validações Frontend / Frontend Validations * ID da ordem obrigatório com validação numérica / Mandatory Order ID with numeric validation * Token obrigatório com validação de comprimento / Mandatory Token with length validation * Spread entre 0 e 1 com validação em tempo real / Spread between 0 and 1 with real-time validation * Tarifa não negativa / Fee (non-negative) * Settlement flow e delivery option com dropdowns / Settlement flow and delivery option with dropdowns

3. UX/UI Recomendada / Recommended UX/UI * Formulário de cotação com preview de custos / Quotation form with cost preview * Calculadora de spread visual / Visual **spread calculator * Preview de cotação antes da confirmação / Quotation preview before confirmation * Exibição clara de taxas e prazos / Clear display of rates and terms * Validação de validade da cotação / Validation of quotation expiration

[!WARNING] LEMBRE-SE / REMEMBER

As cotações têm validade limitada. Verifique sempre o campo quotationValidUntil e renove a cotação quando necessário.

Quotations have limited validity. Always check the quotationValidUntil field and renew the quotation when necessary.

[!INFO] SUPORTE / SUPPORT

Em caso de dúvidas sobre cotações, taxas de câmbio ou configurações específicas, entre em contato com nossa equipe de operações através do canal de suporte dedicado.

In case of questions about quotations, exchange rates, or specific settings, please contact our operations team through the dedicated support channel.

Cotação de Ordens / Order Quotation¶

Visão Geral / Overview¶

Autenticação / Authentication¶

Descrição dos Headers / Headers Description:¶

Processo de Cotação / Quotation Process¶

Endpoint: POST /v1/partner/public/orders/quotation¶

Dados Obrigatórios / Required Data¶

Dados Opcionais (Configurações Avançadas) / Optional Data (Advanced Settings)¶

Opções de Settlement Flow / Settlement Flow Options¶

Opções de Delivery / Delivery Options¶

Exemplo de Requisição / Request Example¶

Resposta de Sucesso / Success Response¶

Possíveis Erros / Possible Errors¶

Dados Obrigatórios da Cotação / Quotation Required Data¶

Validação de Spread / Spread Validation¶

Validação de Tarifa / Fee Validation¶

Ordem Não Encontrada / Order Not Found¶

Considerações Importantes / Important Considerations¶

Limitações e Validações / Limitations and Validations¶

Validações Automáticas / Automatic Validations¶

Integração Recomendada / Recommended Integration¶

Fluxo de Desenvolvimento / Development Workflow¶

Endpoint: `POST /v1/partner/public/orders/quotation`¶