API de Ordens de Recebimento (Inbound Orders) / Inbound Orders API¶

Visão Geral / Overview¶

A API de Ordens de Recebimento (Inbound Orders) permite a parceiros integrados criar, gerenciar e consultar ordens de recebimento de moeda estrangeira através da plataforma de Parceiros. Este processo segue as regulamentações do Banco Central do Brasil e implementa as melhores práticas de compliance para operações de câmbio de recebimento.

The Inbound Orders API allows integrated partners to create, manage, and consult foreign currency inbound orders through the Partner platform. This process follows the regulations of the Central Bank of Brazil and implements the best compliance practices for inbound exchange operations.

Este documento cobre o fluxo completo de ordens inbound, incluindo: This document covers the complete inbound orders flow, including:

✅ Criação da ordem / Order creation
✅ Atualização de finalidade / Purpose update
✅ Criação de cotação / Quotation creation
✅ Cadastro de conta bancária (Operação 6) / Bank account registration (Operation 6)
✅ Consulta e listagem / Consultation and listing

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

Rate Limiting / 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.

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 / requests	Proteção contra picos / Spike protection
1 minuto / 1 minute	30 requisições / requests	Uso normal / Normal use
15 minutos	100 requisições / requests	Operações em lote / Batch operations
1 hora / 1 hour	300 requisições / 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 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 retrying (429 only)

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

Ciclo de Vida de uma Ordem / Order Life Cycle¶

Etapas do Processo / Process Steps¶

1️⃣ Parceiro: Criar Ordem / Partner: Create Order¶

Endpoint: POST /v1/partner/public/orders/inbound/create
Status: PENDING_DOCUMENTATION (1)
Ação / Action: Informar dados básicos (cliente, pagador, moeda, valor) / Provide basic data (customer, payer, currency, amount)

2️⃣ Admin Interno: Análise e Aprovação / Internal Admin: Review and Approval¶

Status: PROCESSING (2)
Duração / Duration: 1-3 dias úteis / 1-3 business days
Ação / Action: Sistema realiza validações de compliance, sanções e documentos / System performs compliance, sanctions, and document validations

3️⃣ Resultado da Análise: / Analysis Result:¶

Aprovado / Approved → Status: AVAILABLE_QUOTATION (7)
- Ordem pronta para o parceiro adicionar finalidade e documentos / Order ready for the partner to add purpose and documents
Reprovado com Correção / Rejected with Correction → Status: REPROVED_WITH_CORRECTION (3)
- Parceiro pode corrigir e reenviar documentação / Partner can correct and resubmit documentation
Reprovado sem Correção / Rejected without Correction → Status: REPROVED_WITHOUT_CORRECTION (8)
- Ordem rejeitada definitivamente / Order definitively rejected

4️⃣ Parceiro: Atualizar Finalidade e Documentos / Partner: Update Purpose and Documents¶

Endpoint: PUT /v1/partner/public/orders/inbound/{orderId}/update-finality
Quando / When: Após aprovação (status 7) / After approval (status 7)
Ação / Action: Adicionar finalidade, modalidade (se mercadoria) e anexos / Add purpose, modality (if goods), and attachments

5️⃣ Parceiro: Criar Cotação / Partner: Create Quotation¶

Quando / When: Após atualização da finalidade e ordem estar em status AVAILABLE_QUOTATION (7) / After purpose update and order is in status 7
Endpoint: POST /v1/partner/public/orders/quotation
Ação / Action: Solicitar cotação com taxas e custos da operação / Request quotation with rates and operation costs

6️⃣ Parceiro: Salvar Conta Bancária / Partner: Save Bank Account¶

Quando / When: Após criar a cotação (Etapa 5) / After creating the quotation (Step 5)
Endpoint: POST /v1/partner/public/bank-account/{orderId}/create
Ação / Action: Informar dados da conta bancária brasileira onde o dinheiro será depositado / Provide details of the Brazilian bank account where the money will be deposited
Obrigatório / Mandatory: Nome do titular, número da conta, agência e código do banco / Account holder name, account number, agency, and bank code

[!CAUTION] SEQUÊNCIA OBRIGATÓRIA / MANDATORY SEQUENCE

Esta operação deve ser executada APÓS a cotação e ANTES do envio do comprovante de pagamento. É a última etapa de configuração da ordem inbound.

This operation must be performed AFTER quotation and BEFORE sending the payment proof. It is the final step of the inbound order setup.

Status da Ordem / Order Status¶

Status Principais / Main Statuses¶

Código / Code	Nome / Name	Descrição / Description	Ação do Parceiro / Partner Action
1	`PENDING_DOCUMENTATION`	Aguardando documentação / Waiting for docs	Aguardar análise interna / Wait for internal review
2	`PROCESSING`	Em processamento/análise / Processing/Review	Aguardar resultado da análise (1-3 dias) / Wait 1-3 days
3	`REPROVED_WITH_CORRECTION`	Reprovada com correção / Rejected with correction	Corrigir e reenviar via `update-finality` / Correct and resubmit
7	`AVAILABLE_QUOTATION`	Aprovada para cotação / Approved for quotation	Atualizar finalidade e criar cotação / Update finality and quote
8	`REPROVED_WITHOUT_CORRECTION`	Reprovada definitivamente / Definitively rejected	Criar nova se necessário / Create new if necessary
4	`CANCELED`	Cancelada / Canceled	Ordem cancelada pelo sistema ou cliente / Canceled by system/user
5	`CLOSED`	Finalizada / Finished	Operação concluída com sucesso / Operation successful
6	`PAID`	Paga / Paid	Pagamento confirmado e processado / Payment confirmed/processed

Status Complementares / Additional Statuses¶

Código / Code	Nome / Name	Descrição / Description
9	`AVAILABLE_PAYMENT`	Disponível para pagamento / Available for payment
10	`PENDING_INVOICE_INFORMATION`	Aguardando informações da fatura / Waiting for invoice info
11	`PENDING_INVOICE_ATTACHMENT`	Aguardando anexo da fatura / Waiting for invoice attachment
12	`IDENTIFYING_PAYMENT`	Identificando pagamento / Identifying payment
13	`IDENTIFIED_PAYMENT`	Pagamento identificado / Payment identified
14	`IDENTIFYING_PAYMENT_ABROAD`	Identificando pagamento exterior / Identifying payment abroad
15	`IDENTIFIED_PAYMENT_ABROAD`	Pagamento exterior identificado / Payment abroad identified
16	`PENDING_PAYMENT_INFORMATION`	Aguardando informações de pagamento / Waiting for payment info
17	`PAYMENT_REPROVED`	Pagamento reprovado / Payment rejected
18	`PENDING_ORDER_INFORMATION`	Aguardando informações da ordem / Waiting for order info

[!INFO] INFORMAÇÃO / INFORMATION

Fluxo típico / Typical flow: 1 (PENDING_DOCUMENTATION) → 2 (PROCESSING) → 7 (AVAILABLE_QUOTATION) → 9 (AVAILABLE_PAYMENT) → 13 (IDENTIFIED_PAYMENT) → 5 (CLOSED)

Operação 1: Criação da Ordem de Recebimento / Operation 1: Creating the Inbound Order¶

Endpoint: `POST /v1/partner/public/orders/inbound/create`¶

Cria uma nova ordem de recebimento no sistema com todos os dados necessários. Creates a new inbound order in the system with all the necessary data.

Campos da Requisição / Request Fields¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`id`	long?	❌	ReadOnly	ID da ordem (opcional, somente leitura) Order ID (optional, read-only)
`clientId`	string (GUID)	✅	Formato GUID válido	ID público do cliente (User ID) Public Client ID (User ID)
`sender`	object	✅	-	Dados completos do pagador no exterior *Full details of the overseas payer*
`sender.id`	long?	❌	ReadOnly	ID do pagador (opcional, somente leitura) Payer ID (optional, read-only)
`sender.companyName`	string	✅	Max 255 chars	Nome da empresa pagadora *Paying company name*
`sender.countryId`	long	✅	> 0	ID do país do pagador *Payer's country ID*
`sender.email`	string	⚠️	Email RFC 5322, Max 255 chars	Email do pagador (validado se preenchido) Payer's email (validated if filled)
`sender.sendEmail`	boolean	✅	true/false	Se deve enviar notificação por email *Whether to send email notification*
`currencyId`	long	✅	> 0	ID da moeda de origem *Source currency ID*
`amount`	string	✅	Decimal válido > 0	Valor do recebimento em moeda estrangeira Inbound amount in foreign currency

[!INFO] LEGENDA / LEGEND

✅ Obrigatório / Mandatory | ❌ Opcional / Optional | ⚠️ Opcional mas validado quando preenchido / Optional but validated when filled

Exemplo de Requisição / Request Example¶

cURL

POST [https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/create](https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/create)
Content-Type: multipart/form-data
Authorization: Bearer {token}
x-api-key: {your-api-key}
Accept-Language: pt-br

Resposta de Sucesso / Success Response¶

JSON

{
  "success": true,
  "data": {
    "id": 789123,
    "clientId": "62c45798-3500-47c9-8d0f-4b22effbc70e",
    "clientType": 0,
    "sender": {
      "id": 456,
      "companyName": "Global Trading Inc.",
      "country": {
        "id": 840,
        "description": "United States"
      },
      "email": "payments@globaltrading.com",
      "sendEmail": true
    },
    "currencyId": 1,
    "amount": "50000.00"
  }
}

[!IMPORTANT] IMPORTANTE / IMPORTANT

Guarde o id da ordem retornado! Ele será usado nas próximas operações.

Save the returned order id! It will be used in the next operations.

Possíveis Erros / Possible Errors¶

Dados Obrigatórios Ausentes (400 Bad Request) / Missing Mandatory Data¶

JSON

{
  "success": false,
  "errors": [
    "O ID do cliente é obrigatório",
    "O tipo de cliente é obrigatório",
    "Os dados do pagador são obrigatórios",
    "O ID da moeda é obrigatório",
    "O valor é obrigatório"
  ]
}

Validação do Pagador (400 Bad Request) / Payer Validation¶

JSON

{
  "success": false,
  "errors": [
    "O nome da empresa do pagador é obrigatório",
    "O campo 'Código SWIFT/BIC' é obrigatório para contas bancárias do país: Estados Unidos",
    "O país do pagador é obrigatório",
    "Email inválido"
  ]
}

Validação de Valor (400 Bad Request) / Amount Validation¶

JSON

{
  "success": false,
  "errors": [
    "O valor deve ser um decimal válido",
    "O valor deve ser maior que zero"
  ]
}

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

Antes de criar uma ordem inbound, você DEVE consultar os seguintes endpoints para obter os dados necessários: Before creating an inbound order, you MUST consult the following endpoints to obtain the necessary data:

Ordem / Order	Endpoint	Campo Relacionado / Related Field	Obrigatório / Mandatory	Descrição / Description
1️⃣	`GET /v1/partner/public/clients/get-filtered`	`clientId`	✅	Buscar o cliente cadastrado (PF ou PJ) / Search for registered client
2️⃣	`GET /v1/partner/public/currencies/get-all`	`currencyId`	✅	Obter ID da moeda estrangeira (USD, EUR, etc.) / Get foreign currency ID
3️⃣	`GET /v1/partner/public/countries/get-all`	`sender.countryId`	✅	Obter ID do país de origem do pagador / Get payer's country ID

Quando usar estes endpoints: / When to use these endpoints: * ✅ Antes de criar qualquer ordem de recebimento / Before creating any inbound order * ✅ Cache as listas de moedas, países e clientes no frontend / Cache lists on the frontend * ✅ Atualize o cache periodicamente / Update cache periodically

[!TIP] DICA / TIP

A finalidade (finalityId) não é obrigatória na criação, mas será necessária na operação update-finality após aprovação. The purpose (finalityId) is not mandatory during creation but will be required in the update-finality operation after approval.

Operação 2: Consultar Detalhes da Ordem / Operation 2: Get Order Details¶

Endpoint: `GET /v1/partner/public/orders/inbound/get-detail/{orderId}`¶

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

Este endpoint não requer consultas prévias. Você só precisa ter o orderId da ordem que deseja consultar. This endpoint does not require prior queries. You only need the orderId of the order you wish to consult.

Pré-requisito / Prerequisite	Como Obter / How to Obtain	Obrigatório / Mandatory
`orderId`	Retornado na criação da ordem (`POST /inbound/create`)	✅
OU `orderId`	Obtido via listagem (`GET /inbound/get-filtered`)	✅

Quando usar este endpoint: / When to use this endpoint: * ✅ Para monitorar o status de uma ordem específica / To monitor a specific order's status * ✅ Para obter detalhes completos incluindo cotações e anexos / To get full details including quotes and attachments * ✅ Para verificar se a ordem foi aprovada/reprovada / To check if the order was approved/rejected * ✅ Para consultar o motivo de reprovação (reprovedMsg) / To check the rejection reason

Obtém informações detalhadas de uma ordem de recebimento específica, incluindo histórico, anexos, cotações e dados de liquidação. Obtains detailed information for a specific inbound order, including history, attachments, quotes, and settlement data.

Parâmetros da URL / URL Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`orderId`	long	✅	ID único da ordem de recebimento *Unique Inbound Order ID*

Exemplo de Requisição / Request Example¶

cURL

GET [https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/get-detail/789123](https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/get-detail/789123)
Authorization: Bearer {token}
x-api-key: {your-api-key}
Accept-Language: pt-br

Resposta de Sucesso / Success Response¶

JSON

{
  "success": true,
  "data": {
    "id": 789123,
    "clientType": 0,
    "clientId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "name": "João Silva Santos",
    "typeDocument": "CPF",
    "document": "12345678901",
    "createdDateClient": "2024-01-01T10:00:00Z",
    "createdDate": "2024-01-15T14:30:00Z",
    "status": 13,
    "reprovedMsg": null,
    "finality": {
      "id": 2,
      "description": "Prestação de serviços",
      "code": "SERVICES"
    },
    "receiver": null,
    "currency": {
      "id": 1,
      "description": "USD - United States Dollar",
      "code": "USD"
    },
    "amount": 50000.00,
    "protocolDI": null,
    "numberDI": null,
    "protocolDUE": "DUE123456789",
    "numberDUE": "987654321",
    "eSettlementFlow": 1,
    "bankCurrencyTreasury": "Chase Bank",
    "levelingRateTreasury": 5.2850,
    "eSettlementFlowTreasury": 1,
    "modality": 2,
    "orderAttachments": [
      {
        "id": 1001,
        "orderId": 789123,
        "fileName": "comprovante_servicos.pdf",
        "file": "base64_encoded_file",
        "uploadDate": "2024-01-15T15:30:00Z"
      }
    ],
    "quotations": [
      {
        "id": 5001,
        "orderId": 789123,
        "rate": 5.3000,
        "amount": 50000.00,
        "totalBRL": 265000.00,
        "createdDate": "2024-01-15T15:00:00Z"
      }
    ],
    "orderSettlement": {
      "id": 3001,
      "orderId": 789123,
      "status": "completed",
      "settlementDate": "2024-01-17T10:00:00Z",
      "totalAmountBRL": 265000.00,
      "exchangeRate": 5.3000
    }
  }
}

Informações dos Campos de Resposta / Response Fields Information¶

Campos Principais / Main Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	long	ID único da ordem / Unique Order ID
`clientType`	int	Tipo de cliente (0=PF, 1=PJ) / Client type
`clientId`	string (GUID)	ID público do cliente no formato GUID / Public Client ID
`name`	string	Nome do cliente/beneficiário / Client/beneficiary name
`typeDocument`	string	Tipo do documento (CPF/CNPJ) / Document type
`document`	string	Número do documento / Document number
`createdDate`	datetime	Data de criação da ordem / Order creation date
`createdDateClient`	datetime	Data de cadastro do cliente / Client registration date
`status`	int	Status atual da ordem / Current order status
`reprovedMsg`	string	Mensagem de reprovação (se houver) / Rejection message (if any)

Campos de Finalidade / Purpose Fields¶

Campo / Field	Descrição / Description
`finality.id`	ID da finalidade / Purpose ID
`finality.description`	Descrição da finalidade / Purpose description
`finality.code`	Código da finalidade / Purpose code

Campos de Moeda / Currency Fields¶

Campo / Field	Descrição / Description
`currency.id`	ID da moeda / Currency ID
`currency.description`	Descrição completa da moeda / Full currency description
`currency.code`	Código ISO da moeda (USD, EUR, etc.) / ISO currency code

Campos de Valores / Value Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`amount`	decimal	Valor em moeda estrangeira *Foreign currency amount*
`levelingRateTreasury`	decimal	Taxa de nivelamento da tesouraria *Treasury leveling rate*
`eSettlementFlow`	int?	Fluxo de liquidação (1=D0, 2=D+1, 3=D+2, 4=Termo D0, 5=Termo D1, 6=Termo D2) - Opcional/Nullable *Settlement flow*
`modality`	int?	Modalidade da ordem (2=Antecipado, 3=À Prazo) - Apenas valores 2-3 para Inbound - Opcional/Nullable *Order modality*

Campos de Documentos / Document Fields¶

Campo / Field	Descrição / Description
`protocolDUE`	Protocolo da Declaração Única de Exportação *Single Export Declaration Protocol*
`numberDUE`	Número da DUE *DUE Number*
`protocolDI`	Protocolo da Declaração de Importação *Import Declaration Protocol*
`numberDI`	Número da DI *DI Number*

Status da Ordem / Order Status¶

Valor / Value	Status	Descrição / Description
1	`PENDING_DOCUMENTATION`	Aguardando documentação / Waiting for documentation
2	`PROCESSING`	Em processamento / Processing
3	`REPROVED_WITH_CORRECTION`	Reprovada com possibilidade de correção / Rejected with correction
4	`CANCELED`	Cancelada / Canceled
5	`CLOSED`	Finalizada / Closed
6	`PAID`	Paga / Paid
7	`AVAILABLE_QUOTATION`	Disponível para cotação / Available for quotation
8	`REPROVED_WITHOUT_CORRECTION`	Reprovada definitivamente / Definitively rejected
9	`AVAILABLE_PAYMENT`	Disponível para pagamento / Available for payment
10	`PENDING_INVOICE_INFORMATION`	Aguardando informações da fatura / Waiting for invoice info
11	`PENDING_INVOICE_ATTACHMENT`	Aguardando anexo da fatura / Waiting for invoice attachment
12	`IDENTIFYING_PAYMENT`	Identificando pagamento / Identifying payment
13	`IDENTIFIED_PAYMENT`	Pagamento identificado / Payment identified
14	`IDENTIFYING_PAYMENT_ABROAD`	Identificando pagamento exterior / Identifying foreign payment
15	`IDENTIFIED_PAYMENT_ABROAD`	Pagamento exterior identificado / Foreign payment identified
16	`PENDING_PAYMENT_INFORMATION`	Aguardando informações de pagamento / Waiting for payment info
17	`PAYMENT_REPROVED`	Pagamento reprovado / Payment rejected
18	`PENDING_ORDER_INFORMATION`	Aguardando informações da ordem / Waiting for order info

Modalidades de Operação / Operation Modalities¶

Valor / Value	Modalidade / Modality	Válido para Inbound? / Valid for Inbound?	Descrição / Description
1	À Vista (`AT_SIGHT`)	❌ NÃO / NO	Não permitido para ordens de recebimento / Not allowed for inbound orders
2	Antecipado (`ANTICIPATED`)	✅ SIM / YES	Liquidação antecipada antes do recebimento efetivo / Early settlement before receipt
3	À Prazo (`IN_INSTALLMENTS`)	✅ SIM / YES	Liquidação futura conforme acordo comercial / Future settlement per agreement

[!IMPORTANT] IMPORTANTE / IMPORTANT

⚠️ Para ordens de recebimento (Inbound), a modalidade 1 (À Vista) NÃO é válida. Use apenas: For inbound orders, modality 1 (At Sight) is NOT valid. Use only:

2 (Antecipado) - para liquidação antecipada / for early settlement

3 (À Prazo) - para liquidação futura / for future settlement

Possíveis Erros / Possible Errors¶

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

JSON

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

Operação 3: Listar Ordens com Filtros / Operation 3: List Orders with Filters¶

Endpoint: `GET /v1/partner/public/orders/inbound/get-filtered`¶

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

Este endpoint não requer consultas prévias obrigatórias, mas pode usar dados de outros endpoints para filtros mais específicos: This endpoint does not require mandatory prior queries, but can use data from other endpoints for specific filters:

Endpoint Auxiliar / Auxiliary Endpoint	Uso nos Filtros / Filter Use	Obrigatório / Mandatory	Benefício / Benefit
`GET /v1/partner/public/clients/get-filtered`	`clientId` no filtro	❌	Filtrar ordens de um cliente específico / Filter by specific client
`GET /v1/partner/public/currencies/get-all`	`currencyId` no filtro	❌	Filtrar ordens por moeda / Filter orders by currency

Filtros disponíveis sem dependências: / Available filters without dependencies:

✅ status - Filtrar por status da ordem (valores 1-18) / Filter by order status
✅ startDate / endDate - Filtrar por período / Filter by date range
✅ page / pageSize - Paginação / Pagination
✅ Ordenação - OrderBy / IsDescendent / Sorting

Quando usar este endpoint: / When to use this endpoint:

✅ Para listar todas as ordens do parceiro / To list all partner orders
✅ Para buscar ordens por status / To search orders by status
✅ Para relatórios e exportações / For reports and exports
✅ Para obter orderId antes de consultar detalhes / To get orderId before checking details

Obtém uma lista paginada de ordens de recebimento com capacidade de filtros avançados. Obtains a paginated list of inbound orders with advanced filtering capabilities.

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 / Customer name to filter
`document`	string	❌	CPF/CNPJ para filtrar / Tax ID (CPF/CNPJ) to 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 (formato: YYYY-MM-DD ou ISO 8601) / Start date
`createdDateFinal`	datetime	❌	Data final de criação (formato: 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

Filtros Disponíveis por Status / Available Status Filters¶

Status / Code	Código / Code Name	Descrição Completa / Full Description
1	`PENDING_DOCUMENTATION`	Aguardando documentação obrigatória / Waiting for mandatory docs
2	`PROCESSING`	Sendo processada pelo sistema / Being processed by the system
3	`REPROVED_WITH_CORRECTION`	Reprovada, mas pode ser corrigida / Rejected, but can be corrected
4	`CANCELED`	Cancelada pelo cliente ou sistema / Canceled by client or system
5	`CLOSED`	Finalizada com sucesso / Successfully finished
6	`PAID`	Pagamento confirmado / Payment confirmed
7	`AVAILABLE_QUOTATION`	Pronta para cotação / Ready for quotation
8	`REPROVED_WITHOUT_CORRECTION`	Reprovada definitivamente / Definitively rejected
9	`AVAILABLE_PAYMENT`	Pronta para pagamento / Ready for payment
10	`PENDING_INVOICE_INFORMATION`	Aguardando informações da fatura / Waiting for invoice info
11	`PENDING_INVOICE_ATTACHMENT`	Aguardando documentos da fatura / Waiting for invoice documents
12	`IDENTIFYING_PAYMENT`	Identificando pagamento / Identifying payment
13	`IDENTIFIED_PAYMENT`	Pagamento identificado / Payment identified
14	`IDENTIFYING_PAYMENT_ABROAD`	Identificando pagamento exterior / Identifying foreign payment
15	`IDENTIFIED_PAYMENT_ABROAD`	Pagamento exterior identificado / Foreign payment identified
16	`PENDING_PAYMENT_INFORMATION`	Aguardando informações de pagamento / Waiting for payment info
17	`PAYMENT_REPROVED`	Pagamento reprovado / Payment rejected
18	`PENDING_ORDER_INFORMATION`	Aguardando informações da ordem / Waiting for order info

Filtros Disponíveis por Moeda / Available Currency Filters¶

ID	Código / Code	Descrição / Description
1	USD	Dólar Americano / US Dollar
2	EUR	Euro
3	GBP	Libra Esterlina / British Pound
4	CHF	Franco Suíço / Swiss Franc
5	AUD	Dólar Australiano / Australian Dollar
6	CAD	Dólar Canadense / Canadian Dollar
7	NZD	Dólar Neozelandês / New Zealand Dollar
8	JPY	Iene Japonês / Japanese Yen
9	ZAR	Rand Sul-Africano / South African Rand
10	DKK	Coroa Dinamarquesa / Danish Krone
11	NOK	Coroa Norueguesa / Norwegian Krone
12	SEK	Coroa Sueca / Swedish Krona
13	MXN	Peso Mexicano / Mexican Peso

Exemplo de Requisição / Request Example¶

cURL

GET [https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/get-filtered?page=0&rowsPerPage=50](https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/get-filtered?page=0&rowsPerPage=50)
Authorization: Bearer {token}
x-api-key: {your-api-key}
Accept-Language: pt-br

Resposta de Sucesso / Success Response¶

JSON

{
  "success": true,
  "data": {
    "total": 95,
    "page": 0,
    "rowsPerPage": 50,
    "totalPages": 2,
    "data": [
      {
        "id": 789123,
        "clientType": 0,
        "name": "João Silva Santos",
        "typeDocument": "CPF",
        "document": "123.456.789-01",
        "createdDate": "2024-01-15T14:30:00Z",
        "finality": "Prestação de serviços",
        "sender": "Global Trading Inc.",
        "currency": "USD",
        "amount": 50000.00,
        "status": 13,
        "statusDescription": "Pagamento identificado"
      },
      {
        "id": 789124,
        "clientType": 1,
        "name": "Empresa XYZ Ltda",
        "typeDocument": "CNPJ",
        "document": "12.345.678/0001-95",
        "createdDate": "2024-01-14T16:45:00Z",
        "finality": "Exportação de mercadorias",
        "sender": "International Corp",
        "currency": "EUR",
        "amount": 25000.00,
        "status": 5,
        "statusDescription": "Finalizada"
      }
    ]
  }
}

[!TIP] DICA DE PERFORMANCE / PERFORMANCE TIP

Para grandes volumes de dados, utilize sempre os parâmetros de paginação e filtros específicos para reduzir o tempo de resposta.

For large data volumes, always use pagination parameters and specific filters to reduce response time.

Possíveis Erros / Possible Errors¶

Parâmetros de Paginação Inválidos (400 Bad Request) / Invalid Pagination Parameters¶

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",
    "O número máximo de itens por página é 100"
  ]
}

Operação 4: Atualizar Finalidade da Ordem / Operation 4: Update Order Purpose¶

Endpoint: `PUT /v1/partner/public/orders/inbound/{orderId}/update-finality`¶

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

Antes de atualizar a finalidade, você DEVE consultar os seguintes endpoints: Before updating the purpose, you MUST consult the following endpoints:

Ordem / Order	Endpoint	Campo Relacionado / Related Field	Obrigatório / Mandatory	Descrição / Description
1️⃣	`GET /v1/partner/public/orders/inbound/get-detail/{orderId}`	`orderId`	✅ Recomendado	Verificar status atual da ordem antes de atualizar / Check order status
2️⃣	`GET /v1/partner/public/finalities/get-all/{clientType}`	`finalityId`	✅	Obter ID da finalidade desejada (filtrado por tipo de cliente) / Get Purpose ID

Quando usar este endpoint: / When to use this endpoint: * ✅ Após a ordem ser aprovada (status AVAILABLE_QUOTATION) / After order approval * ✅ Quando precisar corrigir finalidade reprovada (status REPROVED_WITH_CORRECTION) / To correct a rejected purpose * ✅ Para adicionar documentos comprobatórios à ordem / To add supporting documents to the order

📋 Importante: Naturezas de Operação (Finalities) / Important: Purpose 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: exportação de mercadorias, recebimento por serviços prestados, transferências de não residentes, etc.). The finalities represent the nature of operation regulated by the Central Bank of Brazil. Every 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 for use.

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

Apenas as finalidades retornadas pelo endpoint /finalities/get-all/{clientType} (conforme tabela de dependências 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 the purposes returned by the /finalities/get-all/{clientType} endpoint can be used in API operations. If your customer's operation has a nature that is not on the list, the order cannot be processed directly 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) / Via API (Automatic) * ❌ Não será possível processar diretamente / Cannot be processed directly * A validação impedirá a atualização da ordem / Validation will prevent order update

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 Classification¶

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 atualizar a ordem / Automatic classification
Manual	Finalidade não cadastrada ou casos especiais	Requer intervenção da equipe de compliance para análise e aprovação / Requires manual review

[!TIP] BOA PRÁTICA / BEST PRACTICE

Sempre consulte o endpoint de finalidades antes de atualizar a ordem com a finalidade. Isso evita: Always consult the finalities endpoint before updating the order. This avoids:

Erros de validação durante a atualização / Validation errors

Retrabalho por usar IDs inválidos / Rework from using invalid IDs

Problemas de conformidade regulatória / Regulatory compliance issues

[!IMPORTANT] IMPORTANTE / IMPORTANT

Este endpoint só pode ser chamado UMA ÚNICA VEZ por ordem. Uma vez que a finalidade foi definida, não é possível alterá-la novamente. Se precisar de uma finalidade diferente, será necessário criar uma nova ordem.

This endpoint can only be called ONCE per order. Once the purpose is defined, it cannot be changed. If a different purpose is needed, a new order must be created.

[!WARNING] AVISO / NOTICE

Esta operação só funciona se a ordem estiver em status que permita edição: AVAILABLE_QUOTATION ou REPROVED_WITH_CORRECTION.

This operation only works if the order is in a status that allows editing: AVAILABLE_QUOTATION or REPROVED_WITH_CORRECTION.

Atualiza a finalidade e anexos de uma ordem de recebimento específica após aprovação. Updates the purpose and attachments of a specific inbound order after approval.

[!CAUTION] ATENÇÃO - OPERAÇÃO DE USO ÚNICO / ATTENTION - SINGLE-USE OPERATION

Este endpoint só pode ser executado UMA ÚNICA VEZ por ordem. Após a finalidade ser definida, qualquer nova tentativa de atualização resultará em erro.

This endpoint can only be executed ONCE per order. After the purpose is defined, any further update attempt will result in an error.

Recomendações: / Recommendations: * ✅ Verifique cuidadosamente a finalidade antes de enviar / Carefully check the purpose before sending * ✅ Certifique-se de que todos os dados estão corretos / Ensure all data is correct * ✅ Se errar, será necessário criar uma nova ordem / If an error occurs, a new order must be created

Campos da Requisição / Request Fields¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`orderId`	long	✅	> 0	ID da ordem (na URL) / Order ID (in URL)
`finalityId`	long	✅	> 0	ID da finalidade da operação / Purpose ID
`modality`	int?	⚠️	2-3 ou null	Modalidade (2=Antecipado, 3=À Prazo) - Obrigatório apenas para finalidade "Mercadoria" / Modality (Mandatory for "Goods" only)
`orderAttachments`	array	✅	Não nulo	Lista de anexos (pode estar vazia) / Attachment list
`orderAttachments[].id`	long?	❌	-	ID do anexo (opcional) / Attachment ID (optional)
`orderAttachments[].orderId`	long?	❌	-	ID da ordem (opcional) / Order ID (optional)
`orderAttachments[].file`	IFormFile	✅	-	Arquivo do anexo / Attachment file
`orderAttachments[].fileName`	string	❌	Max 255 chars	Nome do arquivo / File name

[!INFO] LEGENDA / LEGEND

✅ Obrigatório / Mandatory | ❌ Opcional / Optional | ⚠️ Condicional (obrigatório apenas para finalidade tipo "Mercadoria") / Conditional

Regras de Modalidade para Inbound / Inbound Modality Rules¶

Valor / Value	Modalidade / Modality	Válido? / Valid?	Quando Usar / When to Use
1	À Vista	❌ NÃO / NO	Não permitido para recebimentos / Not allowed for inbound
2	Antecipado	✅ SIM / YES	Liquidação antes do recebimento efetivo / Settlement before receipt
3	À Prazo	✅ SIM / YES	Liquidação futura conforme contrato / Future settlement per contract

[!WARNING] AVISO / NOTICE

Modalidade é obrigatória apenas quando a finalidade for "Mercadoria" (MERCADORIA_RECEBIMENTO_PF ou MERCADORIA_RECEBIMENTO_PJ). Para outras finalidades, omita o campo ou envie null.

Modality is mandatory only when the purpose is "Goods" (MERCADORIA_RECEBIMENTO_PF or MERCADORIA_RECEBIMENTO_PJ). For other purposes, omit the field or send null.

Formatos de Arquivo Aceitos / Accepted File Formats¶

Imagens / Images: JPG, JPEG, PNG
Documentos / Documents: PDF, DOC, DOCX

Exemplo de Requisição / Request Example¶

Exemplo 1: Atualização com Modalidade (Finalidade de Mercadoria) / Example 1: Update with Modality (Goods Purpose)¶

cURL

PUT [https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/789123/update-finality](https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/789123/update-finality)
Content-Type: multipart/form-data
Authorization: Bearer {token}
x-api-key: {your-api-key}
Accept-Language: pt-br

Exemplo 2: Atualização sem Modalidade (Finalidade de Serviços) / Example 2: Update without Modality (Services Purpose)¶

cURL

PUT [https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/789124/update-finality](https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/789124/update-finality)
Content-Type: multipart/form-data
Authorization: Bearer {token}
x-api-key: {your-api-key}
Accept-Language: pt-br

Resposta de Sucesso / Success Response¶

JSON

{
  "success": true,
  "data": {
    "orderId": 789123,
    "finalityId": 5,
    "modality": 2,
    "orderAttachments": [
      {
        "id": 1001,
        "orderId": 789123,
        "fileName": "nota_fiscal_exportacao.pdf",
        "file": "base64_encoded_file",
        "uploadDate": "2024-01-15T15:30:00Z"
      },
      {
        "id": 1002,
        "orderId": 789123,
        "fileName": "due_comprovante.pdf",
        "file": "base64_encoded_file",
        "uploadDate": "2024-01-15T15:30:00Z"
      }
    ]
  }
}

[!IMPORTANT] IMPORTANTE / IMPORTANT

Finalidade / Purpose: Este endpoint só pode ser chamado uma única vez. Após a finalidade ser definida, não é possível alterá-la. / This endpoint can only be called once. Once defined, the purpose cannot be changed.

Anexos / Attachments: Novos anexos são adicionados à ordem. Os anexos anteriores são mantidos a menos que sejam explicitamente removidos. / New attachments are added to the order. Previous ones are kept unless explicitly removed.

Regras de Validação da Modalidade / Modality Validation Rules¶

A validação do campo modality segue regras específicas baseadas na finalidade escolhida: The validation of the modality field follows specific rules based on the chosen purpose:

✅ Cenário 1: Finalidade = "Mercadoria" / Scenario 1: Purpose = "Goods"¶

(MERCADORIA_RECEBIMENTO_PF ou MERCADORIA_RECEBIMENTO_PJ)

Modalidade é OBRIGATÓRIA / Modality is MANDATORY
Valores aceitos: Apenas 2 (Antecipado) ou 3 (À Prazo) / Accepted values: 2 (Anticipated) or 3 (Term)
Erro se: / Error if:
- Campo for null → "A modalidade é obrigatória para finalidade de mercadoria"
- Valor for 1 → "Modalidade inválida. Permitido apenas: 2 (Antecipado) ou 3 (À Prazo)"
- Valor for < 2 ou > 3 → "Modalidade inválida"

✅ Cenário 2: Finalidade ≠ "Mercadoria" / Scenario 2: Purpose ≠ "Goods"¶

(Serviços, Investimento, etc.)

Modalidade deve ser NULL ou omitida / Modality must be NULL or omitted
Erro se: / Error if:
- Campo tiver qualquer valor (1, 2 ou 3) → "Modalidade não é permitida para finalidades que não sejam mercadoria"

Possíveis Erros / Possible Errors¶

Dados Obrigatórios da Atualização (400 Bad Request) / Missing Mandatory Update Data¶

JSON

{
  "success": false,
  "errors": [
    "O ID da ordem é obrigatório",
    "O ID da finalidade é obrigatório",
    "A lista de anexos não pode ser nula"
  ]
}

Finalidade Já Definida (400 Bad Request) / Purpose Already Defined¶

JSON

{
  "success": false,
  "errors": [
    "A finalidade da ordem já foi definida e não pode ser alterada."
  ]
}

[!IMPORTANT] IMPORTANTE / IMPORTANT

Este erro ocorre quando você tenta chamar o endpoint update-finality uma segunda vez para a mesma ordem. Cada ordem só pode ter sua finalidade definida uma única vez. Se precisar de uma finalidade diferente, será necessário criar uma nova ordem.

This error occurs when you call the update-finality endpoint a second time for the same order. Each order can only have its purpose defined once. If a different purpose is needed, a new order must be created.

Validação de Modalidade (400 Bad Request) / Modality Validation¶

JSON

{
  "success": false,
  "errors": [
    "A modalidade é obrigatória para finalidades do tipo Mercadoria",
    "A modalidade informada é inválida. Valores aceitos: 1 (À Vista), 2 (Antecipado), 3 (À Prazo)"
  ]
}

[!INFO] IMPORTANTE / IMPORTANT

O erro de modalidade obrigatória só ocorre quando a finalidade selecionada for do tipo MERCADORIA_RECEBIMENTO_PF ou MERCADORIA_RECEBIMENTO_PJ. Para outras finalidades, o campo modality pode ser omitido.

The mandatory modality error only occurs when the selected purpose is of type MERCADORIA_RECEBIMENTO_PF or MERCADORIA_RECEBIMENTO_PJ. For other purposes, the modality field may be omitted.

Validação de Anexos (400 Bad Request) / Attachment Validation¶

JSON

{
  "success": false,
  "errors": [
    "Arquivo obrigatório",
    "Formato de arquivo não suportado"
  ]
}

[!INFO] INFORMAÇÃO / INFORMATION

Formatos aceitos / Accepted formats: PDF, DOC, DOCX, JPG, JPEG, PNG

Operação 5: Criar Cotação da Ordem / Operation 5: Create Order Quotation¶

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

Após a ordem ser aprovada e a finalidade atualizada, você deve criar uma cotação para definir as taxas de câmbio e custos da operação. After the order is approved and the purpose updated, you must create a quotation to define exchange rates and operation costs.

O que é uma Cotação? / What is a Quotation?¶

Uma cotação (quotation) é a proposta de taxa de câmbio e custos associados para a operação de câmbio. Ela inclui: A quotation is the proposal for the exchange rate and associated costs. It includes:

Taxa de câmbio (Exchange Rate): Valor de conversão entre as moedas / Conversion value between currencies
Spread: Margem de lucro aplicada sobre a taxa base (0% a 100%) / Profit margin applied to the base rate
Tarifa (Tariff): Custo fixo da operação / Fixed operation cost
IOF (Imposto sobre Operações Financeiras): Imposto obrigatório / Mandatory tax
Valor Total: Valor final da operação / Final operation value

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

Para criar uma cotação, você precisa ter completado as operações anteriores: To create a quotation, you must have completed the previous operations:

Ordem / Order	Endpoint	Campo Relacionado / Related Field	Obrigatório / Mandatory	Descrição / Description
1️⃣	`POST /v1/partner/public/orders/inbound/create`	`orderId`	✅	Ordem inbound criada / Inbound order created
2️⃣	`PUT /v1/partner/public/orders/inbound/{orderId}/update-finality`	Finalidade atualizada	✅	Finalidade e documentos anexados / Purpose and docs attached
3️⃣	`GET /v1/partner/public/stocks/get-order-rate`	Taxa atual	⚠️ Opcional	Consultar taxa antes de cotar / Consult rate before quoting

Validações antes de cotar: / Pre-quotation validations:

✅ Ordem deve estar em status AVAILABLE_QUOTATION (7) / Order must be in status 7
✅ Finalidade deve estar preenchida / Purpose must be filled
✅ Documentos obrigatórios anexados / Mandatory documents attached

Campos da Requisição / Request Fields¶

Campos Obrigatórios / Mandatory Fields¶

Campo / Field	Tipo / Type	Descrição / Description	Validação / Validation
`orderId`	long	✅ ID da ordem criada / Created Order ID	Deve ser > 0 e ordem válida
`token`	string	✅ Token de segurança para validação / Security token	Max 2000 caracteres

Campos Opcionais (Personalizações) / Optional Fields (Customization)¶

Campo / Field	Tipo / Type	Descrição / Description	Validação / Validation
`spread`	decimal?	❌ Spread personalizado (margem de lucro) / Custom spread	0.0 a 1.0 (0% a 100%)
`tariff`	decimal?	❌ Tarifa personalizada / Custom tariff	>= 0
`settlementFlow`	int?	❌ Fluxo de liquidação / Settlement flow	1 a 6 (ver tabela abaixo)
`deliveryOption`	int?	❌ Opção de entrega / Delivery option	1 ou 2 (ver tabela abaixo)

[!INFO] INFORMAÇÃO / INFORMATION

Campos opcionais: Se não informados, o sistema utilizará os valores padrão configurados para o parceiro. Optional fields: If not provided, the system will use the default values configured for the partner.

Opções de Settlement Flow (Fluxo de Liquidação) / Settlement Flow Options¶

Valor / Value	Descrição / Description	Tipo / Type	Quando Usar / When to Use
1	D0 - Liquidação no mesmo dia / Same day	Pronta	Operações urgentes / Urgent operations
2	D+1 - Liquidação no próximo dia útil / Next day	Pronta	Operações normais / Normal operations
3	D+2 - Liquidação em dois dias úteis / Two days	Pronta	Planejamento financeiro / Financial planning
4	Termo D0 - Liquidação a termo no mesmo dia	Termo	Hedge cambial / Currency hedge
5	Termo D1 - Liquidação a termo no próximo dia	Termo	Proteção de taxa / Rate protection
6	Termo D2 - Liquidação a termo em dois dias	Termo	Estratégia de taxa / Rate strategy

Opções de Delivery (Entrega) / Delivery Options¶

Valor / Value	Descrição / Description	Rede / Network	Características / Features
1	SWIFT - Rede SWIFT tradicional	Internacional	Padrão global, 2-5 dias / Global standard, 2-5 days
2	NIUM - Rede NIUM digital	Digital	Mais rápida, custos menores / Faster, lower costs

Exemplo de Requisição / Request Example¶

Cotação Simples (usando valores padrão) / Simple Quotation (using defaults)¶

cURL

POST /v1/partner/public/orders/quotation
Authorization: Bearer {token}
Role: ADMIN_PARTNER
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Content-Type: application/json

Cotação Personalizada (com spread, tarifa e opções) / Custom Quotation (with spread, tariff, and options)¶

cURL

POST /v1/partner/public/orders/quotation
Authorization: Bearer {token}
Role: ADMIN_PARTNER
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Content-Type: application/json

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

JSON

{
  "success": true,
  "data": {
    "orderId": 12345,
    "spread": 0.02,
    "tariff": 50.00,
    "settlementFlow": 2,
    "deliveryOption": 1,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "exchangeRate": 5.2850,
    "commercialValue": 10000.00,
    "totalAmount": 52850.00,
    "fees": {
      "spreadAmount": 105.00,
      "tariffAmount": 50.00,
      "iofAmount": 1695.00,
      "totalFees": 1850.00
    },
    "quotationValidUntil": "2024-01-15T15:30:00Z",
    "quotationDate": "2024-01-15T14:00:00Z"
  }
}

Campos da Resposta / Response Fields¶

Campo / Field	Tipo / Type	Descrição / Description
`orderId`	long	ID da ordem cotada / Quoted order ID
`exchangeRate`	decimal	Taxa de câmbio aplicada / Applied exchange rate
`commercialValue`	decimal	Valor comercial (em moeda estrangeira) / Commercial value (foreign currency)
`totalAmount`	decimal	Valor total em BRL (com todos os custos) / Total amount in BRL (including all costs)
`fees.spreadAmount`	decimal	Valor do spread aplicado / Applied spread amount
`fees.tariffAmount`	decimal	Valor da tarifa / Tariff amount
`fees.iofAmount`	decimal	Valor do IOF / IOF amount
`fees.totalFees`	decimal	Soma de todos os custos / Total fees sum
`quotationValidUntil`	datetime	Data/hora de expiração da cotação / Quotation expiration date/time
`quotationDate`	datetime	Data/hora de criação da cotação / Quotation creation date/time

⏱️ Validade da Cotação / Quotation Validity¶

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

A cotação possui validade de 1 minuto a partir do momento em que é realizada. O campo quotationValidUntil indica exatamente até quando a cotação é válida. The quotation is valid for 1 minute. The quotationValidUntil field indicates the expiration time.

O que acontece após a expiração: / What happens after expiration: * ❌ A cotação não poderá mais ser utilizada para processar a ordem / Quotation can no longer be used * ❌ Será necessário realizar nova cotação com valores atualizados / A new quotation with updated values is required * ✅ Solução: Solicite uma nova cotação via POST /v1/partner/public/orders/quotation / Request a new quote

Por que a cotação expira? / Why does it 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.

Boas Práticas: / Best Practices: * ✅ Utilize o campo quotationValidUntil para monitorar a validade / Monitor validity using the field * ✅ Processe a ordem imediatamente após a cotação (dentro de 1 minuto) / Process immediately * ✅ Se expirar, obtenha nova taxa via GET /v1/partner/public/stocks/get-order-rate e crie nova cotação / Get new rate and re-quote

Conceitos Importantes / Important Concepts¶

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

O spread é a margem de lucro aplicada sobre a taxa de câmbio base: The spread is the profit margin applied to the base exchange rate:

Valor / Value: 0.0 a 1.0 (representando 0% a 100%)
Exemplo / Example: spread: 0.02 = 2% de margem
Cálculo / Calculation: $$\text{Taxa final} = \text{Taxa base} \times (1 + \text{spread})$$

Exemplo prático: / Practical example: * Taxa base: 5.20 BRL/USD * Spread: 0.02 (2%) * Taxa final: $5.20 \times 1.02 = 5.304 \text{ BRL/USD}$

💰 Tarifa (Custo Fixo) / Tariff (Fixed Cost)¶

A tarifa é um valor fixo cobrado pela operação: The tariff is a fixed amount charged for the operation:

Valor / Value: Decimal positivo em BRL
Exemplo / Example: tariff: 50.00 = R$ 50,00 de taxa fixa
Aplicação / Application: Somado ao valor total da operação / Added to the total operation value

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

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

Alíquota: Definida pelo governo federal / Defined by federal government
Cálculo: Automático pelo sistema / Automatic calculation
Inbound: Geralmente 1.1% sobre o valor da operação / Usually 1.1% over operation value
Transparência: Sempre exibido separadamente na cotação / Always shown separately

Erros Possíveis na Cotação / Possible Quotation Errors¶

Ordem Não Disponível para Cotação (400 Bad Request) / Order Not Available for Quotation¶

JSON

{
  "success": false,
  "errors": [
    "Ordem não está disponível para cotação.",
    "Status atual: PENDING_DOCUMENTATION"
  ]
}

Causa / Cause: Ordem ainda não foi aprovada ou finalidade não foi atualizada. / Order not approved or purpose not updated.

Solução / Solution: 1. Verificar status da ordem via GET /get-detail/{orderId} / Check order status 2. Aguardar aprovação interna / Wait for internal approval 3. Completar atualização de finalidade / Complete purpose update

Token Inválido (401 Unauthorized) / Invalid Token¶

JSON

{
  "success": false,
  "errors": [
    "Token de segurança inválido ou expirado."
  ]
}

Causa / Cause: Token de autenticação inválido ou expirado. / Invalid or expired auth token.

Solução / Solution: Obter novo token de autenticação. / Get a new authentication token.

Spread Inválido (400 Bad Request) / Invalid Spread¶

JSON

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

Causa / Cause: Valor de spread fora do intervalo permitido. / Spread value out of allowed range.

Solução / Solution: Ajustar spread para valores entre 0.0 e 1.0. / Adjust spread to values between 0.0 and 1.0.

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

JSON

{
  "success": false,
  "errors": [
    "Fluxo de liquidação inválido. Valores aceitos: 1-6."
  ]
}

Operação 6: Salvar Conta Bancária do Beneficiário / Operation 6: Save Beneficiary Bank Account¶

Endpoint: `POST /v1/partner/public/bank-account/{orderId}/create`¶

Após criar a cotação, você deve informar os dados da conta bancária brasileira onde o dinheiro será depositado. Esta é a última etapa de configuração antes de aguardar o comprovante de pagamento internacional. After creating the quotation, you must provide the Brazilian bank account details where the money will be deposited. This is the final setup step before waiting for the international payment proof.

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

Pré-requisitos obrigatórios: / Mandatory prerequisites:

Ordem / Order	Operação Prévia / Previous Operation	Endpoint	Status Necessário / Required Status	Obrigatório / Mandatory
1️⃣	Criar Ordem	`POST /v1/partner/public/orders/inbound/create`	Aprovada / Approved	✅
2️⃣	Atualizar Finalidade	`PUT /v1/partner/public/orders/inbound/{orderId}/update-finality`	Finalidade definida / Purpose defined	✅
3️⃣	Criar Cotação	`POST /v1/partner/public/orders/quotation`	Cotação criada / Quotation created	✅

Sequência obrigatória: / Mandatory sequence:

Operação 1 (Criar) → Operação 4 (Finalidade) → Operação 5 (Cotação) → Operação 6 (Conta Bancária)

[!IMPORTANT] IMPORTANTE / IMPORTANT

Você NÃO PODE salvar a conta bancária sem antes ter criado a cotação. A ordem deve estar com cotação válida. You CANNOT save the bank account without first creating a quotation. The order must have a valid quote.

O que é a Conta Bancária do Beneficiário? / What is the Beneficiary Bank Account?¶

A conta bancária do beneficiário (receiver) é a conta bancária no Brasil onde o valor recebido do exterior será depositado. É essencial fornecer: The beneficiary's bank account is the account in Brazil where the funds from abroad will be deposited. You must provide:

Nome do titular (deve coincidir com o beneficiário cadastrado) / Account holder name
Número da conta / Account number
Agência / Branch/Agency
Código do banco / Bank code

[!IMPORTANT] Esta etapa é obrigatória e deve ser executada APÓS a criação da cotação e ANTES de enviar o comprovante de pagamento internacional. Sem estes dados, o sistema não saberá onde depositar o dinheiro. This step is mandatory and must be performed AFTER quotation and BEFORE sending the payment proof.

Quando Executar Esta Operação / When to Execute This Operation¶

✅ Execute quando: / Execute when:¶

A cotação já foi criada (Operação 5 concluída) / Quotation is created
Você tem os dados bancários completos do beneficiário brasileiro / You have full Brazilian bank details
A ordem está em status adequado para receber conta bancária / Order is in the correct status
Antes de solicitar/enviar o comprovante de pagamento / Before requesting/sending payment proof

❌ NÃO execute: / DO NOT execute:¶

Antes de criar a cotação / Before creating the quotation
Se os dados bancários estão incompletos / If bank details are incomplete
Após o pagamento já ter sido processado / After payment has been processed
Para ordens do tipo outbound (remessas) / For outbound orders

Parâmetros da URL / URL Parameters¶

Parâmetro / Parameter	Tipo / Type	Obrigatório / Mandatory	Descrição / Description
`orderId`	long	✅	ID único da ordem inbound para qual a conta bancária será associada / Unique Inbound Order ID

Dados Obrigatórios (Body) / Mandatory Data¶

Campo / Field	Tipo / Type	Obrigatório / Mandatory	Validação / Validation	Descrição / Description
`name`	string	✅	Max 255 chars	Nome do titular da conta (deve corresponder ao beneficiário) / Account holder name
`number`	string	✅	Max 50 chars	Número da conta bancária / Bank account number
`agency`	string	✅	Max 20 chars	Agência/Branch do banco / Bank branch
`code`	string	✅	Max 20 chars	Código do banco (ex: 001 para BB, 341 para Itaú) / Bank code (COMPE)

Exemplo de Requisição / Request Example¶

cURL

POST /v1/partner/public/bank-account/789123/create
Authorization: Bearer {token}
Role: ADMIN_PARTNER
x-api-key: 62c45798-3500-47c9-8d0f-4b22effbc70e
Accept-Language: pt-br
Content-Type: application/json

Onde: / Where:

orderId = 789123 (ID da ordem inbound) / Inbound order ID
name = Nome completo do titular (deve ser o mesmo do beneficiário) / Full name of the holder
number = Número da conta com dígito verificador / Account number with check digit
agency = Código da agência (com ou sem dígito) / Branch code
code = Código COMPE do banco (001 = Banco do Brasil) / Bank COMPE code

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

JSON

{
  "success": true,
  "data": {
    "id": 789123,
    "amount": 10000.00,
    "status": 7,
    "remittanceType": 1,
    "createdDate": "2024-01-15T10:00:00Z",
    "currency": {
      "id": 1,
      "description": "USD - United States Dollar",
      "code": "USD"
    },
    "individualAccount": {
      "id": 12345,
      "name": "Maria Silva Santos",
      "document": "12345678901"
    },
    "receiver": {
      "id": 5001,
      "name": "Maria Silva Santos",
      "countryId": 76,
      "country": {
        "id": 76,
        "description": "Brazil"
      },
      "receiverAccount": {
        "id": 3001,
        "name": "Maria Silva Santos",
        "number": "123456-7",
        "agency": "4567",
        "swift": "001",
        "countryId": 76
      }
    },
    "quotations": [
      {
        "id": 5001,
        "rate": 5.20,
        "amount": 10000.00,
        "totalBRL": 54850.00,
        "createdDate": "2024-01-15T14:00:00Z"
      }
    ]
  }
}

Campos Retornados Principais: / Main Returned Fields:¶

Campo / Field	Tipo / Type	Descrição / Description
`id`	long	ID da ordem / Order ID
`amount`	decimal	Valor da ordem em moeda estrangeira / Order amount (foreign currency)
`status`	int	Status da ordem (código numérico) / Order status (numeric code)
`receiver`	object	Dados completos do beneficiário / Beneficiary full data
`receiver.receiverAccount`	object	Conta bancária cadastrada / Registered bank account
`receiver.receiverAccount.name`	string	Nome do titular / Account holder name
`receiver.receiverAccount.number`	string	Número da conta / Account number
`receiver.receiverAccount.agency`	string	Agência / Branch
`receiver.receiverAccount.swift`	string	Código do banco (SWIFT/COMPE) / Bank code
`quotations`	array	Lista de cotações da ordem / Order quotations list

[!IMPORTANT] A resposta retorna o objeto completo da ordem (OrderDto) incluindo todos os dados do receiver e sua receiverAccount. O campo swift na conta bancária armazena o código do banco (COMPE para Brasil, SWIFT para outros países). The response returns the full order object. The swift field stores COMPE for Brazil and SWIFT for other countries.

Possíveis Erros / Possible Errors¶

Dados Obrigatórios Ausentes (400 Bad Request) / Missing Mandatory Data¶

JSON

{
  "success": false,
  "errors": [
    "O nome do titular da conta é obrigatório",
    "O número da conta é obrigatório",
    "A agência é obrigatória",
    "O código do banco é obrigatório"
  ]
}

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

JSON

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

Ordem Não é Inbound (422 Unprocessable Entity) / Order is Not Inbound¶

JSON

{
  "success": false,
  "errors": [
    "Este endpoint é apenas para ordens inbound (recebimentos do exterior)",
    "A ordem informada é do tipo outbound (remessa) e usa outro fluxo"
  ]
}

Conta Bancária Já Cadastrada (409 Conflict) / Bank Account Already Registered¶

JSON

{
  "success": false,
  "errors": [
    "Esta ordem já possui uma conta bancária cadastrada",
    "Para atualizar, entre em contato com o suporte"
  ]
}

Código de Banco Inválido (400 Bad Request) / Invalid Bank Code¶

JSON

{
  "success": false,
  "errors": [
    "Código do banco inválido",
    "Use códigos COMPE válidos de bancos brasileiros"
  ]
}

Próximos Passos / Next Steps¶

Após salvar a conta bancária com sucesso: After successfully saving the bank account:

✅ Ordem está pronta para receber pagamento / Order is ready for payment
📩 Aguardar comprovante de pagamento internacional / Wait for international payment proof
📤 Enviar comprovante quando disponível (via endpoint específico) / Send proof when available
⏳ Aguardar liquidação pela equipe interna / Wait for settlement by the internal team
✅ Dinheiro será depositado na conta informada / Funds will be deposited into the provided account

[!CAUTION] ATENÇÃO / ATTENTION

Sem a conta bancária cadastrada, o sistema não poderá processar o depósito do valor recebido. Esta é uma etapa obrigatória no fluxo de ordens inbound. Without a registered bank account, the system cannot process the deposit. This is a mandatory step in the inbound flow.

Erros de Autenticação (Todos os Endpoints) / Authentication Errors (All Endpoints)¶

Estes erros podem ocorrer em qualquer endpoint da API: These errors can occur on any API endpoint:

Token Inválido ou Expirado (401 Unauthorized) / Invalid or Expired Token¶

JSON

{
  "success": false,
  "errors": ["Token de autenticação inválido ou expirado"]
}

API Key Inválida (403 Forbidden) / Invalid API Key¶

JSON

{
  "success": false,
  "errors": ["API Key inválida ou não autorizada"]
}

Permissão Insuficiente (403 Forbidden) / Insufficient Permission¶

JSON

{
  "success": false,
  "errors": ["Usuário não possui permissão ADMIN_PARTNER necessária"]
}

Considerações Importantes / Important Considerations¶

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

Cliente cadastrado obrigatório no sistema / Registered client required
Pagador válido no exterior obrigatório com dados completos / Valid foreign payer required
País do pagador deve ser válido e diferente do Brasil / Payer country must be valid and not Brazil
Moeda suportada para recebimentos internacionais / Supported currency for international receipts
Email válido quando preenchido (formato RFC 5322) / Valid email format
Valor positivo obrigatório (maior que zero) / Positive value required
Finalidade válida para o tipo de cliente (PF ou PJ) / Valid purpose for client type
Anexos não nulos (a lista pode estar vazia, mas não pode ser null) / Attachments list cannot be null
Documentos DUE opcionais, mas recomendados para exportações / DUE documents recommended for exports

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

ID do cliente: Número inteiro positivo - OBRIGATÓRIO / Client ID (Mandatory)
Tipo de cliente: 0 (PF) ou 1 (PJ) - OBRIGATÓRIO / Client Type (Mandatory)
Nome do pagador: Máximo 255 caracteres - OBRIGATÓRIO / Payer Name (Mandatory)
País do pagador: ID válido de país cadastrado - OBRIGATÓRIO / Payer Country ID (Mandatory)
Email: Formato RFC 5322 quando preenchido / RFC 5322 Email format
Valor: Formato decimal com até 2 casas decimais - OBRIGATÓRIO / Amount (Mandatory)
Lista de anexos: Não pode ser nula (pode estar vazia) / Attachment list cannot be null
Arquivos anexados: Formatos aceitos (PDF, imagens, documentos Office) - OBRIGATÓRIO / Attached files (Mandatory)
Compliance: Validação automática de sanções internacionais e PEP / Automatic sanctions and PEP check
Campos bancários: Validação específica por país (SWIFT, IBAN, ABA, etc.) / Country-specific bank field validation

📋 Estados de Processamento / Processing States¶

Criação: Ordem criada com dados básicos do recebimento / Creation
Documentação: Adição de finalidade, DUE e anexos comprobatórios / Documentation
Análise: Verificação de compliance e sanções internacionais / Analysis
Aprovação: Validação manual pelos analistas de compliance / Approval
Identificação: Identificação do pagamento recebido do exterior / Identification
Liquidação: Conversão cambial e crédito na conta do cliente / Settlement
Finalização: Conclusão da operação com geração de documentos fiscais / Finalization

🔐 Segurança e Compliance / Security and Compliance¶

Todas as operações são logadas para auditoria / Audit logging
Validação automática contra listas de sanções (OFAC, ONU, UE) / Sanctions lists validation
Verificação de Pessoas Politicamente Expostas (PEP) / PEP verification
Monitoramento de operações suspeitas (AML) / Anti-Money Laundering monitoring
Criptografia end-to-end para dados sensíveis / End-to-end encryption
Rate limiting por parceiro para prevenir abuso / Rate limiting per partner

Exemplos de Uso Completo / Complete Usage Examples¶

Cenário 1: Criar Ordem de Recebimento Simples (PF) / Scenario 1: Create Simple Inbound Order (Individual)¶

JavaScript

// 1. Obter lista de países
const countries = await fetch('https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/countries/get-all');

// 2. Obter moedas disponíveis
const currencies = await fetch('https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/currencies/bank-channels?currency=USD&clientId=12345&clientType=0');

// 3. Obter finalidades para Pessoa Física
const finalities = await fetch('https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/finalities/get-all/0');

// 4. Criar a ordem
const order = await fetch('https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer token',
    'x-api-key': 'your-guid',
    'Accept-Language': 'pt-br'
  },
  body: JSON.stringify({
    clientId: "62c45798-3500-47c9-8d0f-4b22effbc70e",
    sender: {
      companyName: 'Global Trading Inc.',
      countryId: 840,
      email: 'payments@globaltrading.com',
      sendEmail: true
    },
    currencyId: 1,
    amount: '50000.00'
  })
});

// 5. Guardar ID da ordem para próximas operações
const orderId = order.data.id;

Cenário 2: Listar e Consultar Ordens / Scenario 2: List and Consult Orders¶

JavaScript

// 1. Listar ordens pendentes
const pendingOrders = await fetch('https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/get-filtered?status=1&page=1&rowsPerPage=20', {
  headers: {
    'Authorization': 'Bearer token',
    'x-api-key': 'your-guid',
    'Accept-Language': 'pt-br'
  }
});

// 2. Obter detalhes de uma ordem específica
const orderDetail = await fetch(`https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/get-detail/${orderId}`, {
  headers: {
    'Authorization': 'Bearer token',
    'x-api-key': 'your-guid',
    'Accept-Language': 'pt-br'
  }
});

Cenário 3: Atualizar Ordem com Finalidade e Documentos / Scenario 3: Update Order with Purpose and Documents¶

Exemplo A: Finalidade de Serviços (sem modalidade) / Example A: Services Purpose (no modality)¶

JavaScript

// 1. Preparar FormData com arquivos para finalidade de serviços
const formData = new FormData();
formData.append('orderId', orderId);
formData.append('finalityId', 3); // Finalidade: Prestação de Serviços

// 2. Adicionar arquivos
formData.append('orderAttachments[0].file', fileInput1.files[0]);
formData.append('orderAttachments[0].fileName', 'comprovante.pdf');
formData.append('orderAttachments[1].file', fileInput2.files[0]);
formData.append('orderAttachments[1].fileName', 'contrato.pdf');

// 3. Enviar atualização
const updated = await fetch(`https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/${orderId}/update-finality`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer token',
    'x-api-key': 'your-guid',
    'Accept-Language': 'pt-br'
  },
  body: formData
});

Exemplo B: Finalidade de Mercadoria (com modalidade obrigatória) / Example B: Goods Purpose (with mandatory modality)¶

JavaScript

// 1. Preparar FormData com arquivos para finalidade de mercadoria
const formData = new FormData();
formData.append('orderId', orderId);
formData.append('finalityId', 5); // Finalidade: MERCADORIA_RECEBIMENTO_PF
formData.append('modality', 2); // Modalidade: 2 (Antecipado) - OBRIGATÓRIO para mercadoria Inbound

// 2. Adicionar arquivos
formData.append('orderAttachments[0].file', fileInput1.files[0]);
formData.append('orderAttachments[0].fileName', 'nota_fiscal.pdf');
formData.append('orderAttachments[1].file', fileInput2.files[0]);
formData.append('orderAttachments[1].fileName', 'due.pdf');

// 3. Enviar atualização
const updated = await fetch(`https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/${orderId}/update-finality`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer token',
    'x-api-key': 'your-guid',
    'Accept-Language': 'pt-br'
  },
  body: formData
});

[!INFO] INFORMAÇÃO / INFORMATION

⚠️ Atenção: Para ordens de recebimento (Inbound), apenas as modalidades 2 (Antecipado) ou 3 (À Prazo) são válidas. A modalidade 1 (À Vista) NÃO é permitida para recebimentos. For Inbound orders, only modalities 2 (Anticipated) or 3 (Term) are valid. Modality 1 (At Sight) is NOT allowed.

Cenário 4: Fluxo Completo - Da Criação ao Comprovante (6 Operações) / Scenario 4: Full Flow - From Creation to Proof (6 Operations)¶

Este exemplo demonstra o fluxo completo de uma ordem inbound, incluindo todas as 6 operações obrigatórias: This example demonstrates the complete flow of an inbound order, including all 6 mandatory operations:

JavaScript

// ==================================================================
// OPERAÇÃO 1: Criar Ordem de Recebimento
// ==================================================================
const createOrderResponse = await fetch('https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    'Role': 'ADMIN_PARTNER',
    'x-api-key': '62c45798-3500-47c9-8d0f-4b22effbc70e',
    'Accept-Language': 'pt-br',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientId: "PF_abc123def456",
    sender: {
      companyName: 'Global Trading Inc.',
      countryId: 840, // Estados Unidos
      email: 'payments@globaltrading.com',
      sendEmail: true
    },
    currencyId: 1, // USD
    amount: '10000.00'
  })
});

const order = await createOrderResponse.json();
const orderId = order.data.id; // Ex: 789123

console.log(`✅ Ordem criada: ID ${orderId}, Status: PENDING_DOCUMENTATION (1)`);

// ==================================================================
// OPERAÇÃO 2 e 3: Aguardar Aprovação Interna (1-3 dias úteis)
// ==================================================================
// Neste período, a equipe interna analisa a ordem
// Use GET /orders/inbound/get-detail/{orderId} para monitorar o status
// Quando aprovado, status muda para AVAILABLE_QUOTATION (7)

// ==================================================================
// OPERAÇÃO 4: Atualizar Finalidade da Ordem (após aprovação)
// ==================================================================
const formData = new FormData();
formData.append('orderId', orderId);
formData.append('finalityId', 3); // Prestação de Serviços

// Adicionar documentos comprobatórios
formData.append('orderAttachments[0].file', contratoFile);
formData.append('orderAttachments[0].fileName', 'contrato_prestacao_servicos.pdf');
formData.append('orderAttachments[1].file', notaFiscalFile);
formData.append('orderAttachments[1].fileName', 'nota_fiscal.pdf');

const updateFinalityResponse = await fetch(
  `https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/inbound/${orderId}/update-finality`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
      'Role': 'ADMIN_PARTNER',
      'x-api-key': '62c45798-3500-47c9-8d0f-4b22effbc70e',
      'Accept-Language': 'pt-br'
    },
    body: formData
  }
);

console.log(`✅ Finalidade atualizada: Prestação de Serviços`);

// ==================================================================
// OPERAÇÃO 5: Criar Cotação
// ==================================================================
const quotationResponse = await fetch('https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/orders/quotation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    'Role': 'ADMIN_PARTNER',
    'x-api-key': '62c45798-3500-47c9-8d0f-4b22effbc70e',
    'Accept-Language': 'pt-br',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    orderId: orderId,
    spread: 0.02,        // 2% de margem (opcional)
    tariff: 50.00,       // R$ 50,00 de tarifa fixa (opcional)
    settlementFlow: 1,   // SWIFT (opcional)
    deliveryOption: 1    // D+0 (opcional)
  })
});

const quotation = await quotationResponse.json();
console.log(`✅ Cotação criada:`);
console.log(`   - Taxa: ${quotation.data.exchangeRate}`);
console.log(`   - Total BRL: R$ ${quotation.data.fees.totalBRL}`);
console.log(`   - IOF: R$ ${quotation.data.fees.iofAmount}`);

// ==================================================================
// OPERAÇÃO 6: Salvar Conta Bancária (ÚLTIMA ETAPA)
// ==================================================================
const bankAccountResponse = await fetch(
  `https://homebroker-api-dev.ozcambio.com.br/v1/partner/public/bank-account/${orderId}/create`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
      'Role': 'ADMIN_PARTNER',
      'x-api-key': '62c45798-3500-47c9-8d0f-4b22effbc70e',
      'Accept-Language': 'pt-br',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Maria Silva Santos',
      number: '123456-7',
      agency: '4567',
      code: '001' // Banco do Brasil
    })
  }
);

const bankAccount = await bankAccountResponse.json();
console.log(`✅ Conta bancária cadastrada:`);
console.log(`   - Banco: ${bankAccount.data.bankAccount.bankName}`);
console.log(`   - Agência: ${bankAccount.data.bankAccount.agency}`);
console.log(`   - Conta: ${bankAccount.data.bankAccount.number}`);

// ==================================================================
// PRÓXIMOS PASSOS
// ==================================================================
console.log(`\n🎯 Ordem configurada completamente!`);
console.log(`📋 Próximas etapas:`);
console.log(`   1. Aguardar pagamento internacional`);
console.log(`   2. Enviar comprovante de pagamento (quando disponível)`);
console.log(`   3. Aguardar liquidação pela equipe interna`);
console.log(`   4. Dinheiro será depositado na conta cadastrada`);

Resumo do Fluxo / Flow Summary¶

Etapa / Step	Operação / Operation	Status	Responsável / Responsible	Tempo / Time
1️⃣	Criar Ordem	`PENDING_DOCUMENTATION` (1)	Parceiro	Imediato / Immediate
2️⃣	Análise Interna	`PROCESSING` (2)	Admin Interno	1-3 dias
3️⃣	Aprovação	`AVAILABLE_QUOTATION` (7)	Sistema	Automático
4️⃣	Atualizar Finalidade	`AVAILABLE_QUOTATION` (7)	Parceiro	Imediato
5️⃣	Criar Cotação	`AVAILABLE_QUOTATION` (7)	Parceiro	Imediato
6️⃣	Salvar Conta Bancária	`AVAILABLE_QUOTATION` (7)	Parceiro	Imediato
7️⃣	Aguardar Comprovante	`WAITING_PAYMENT`	Pagador	Variável
8️⃣	Liquidação	`PAID` (6)	Sistema	1-2 dias

[!IMPORTANT] IMPORTANTE / IMPORTANT

Todas as 6 operações devem ser executadas NA ORDEM CORRETA. Não é possível pular etapas ou executá-las fora de sequência. All 6 operations must be executed IN THE CORRECT ORDER. It is not possible to skip steps or execute them out of sequence.

Códigos de Status HTTP / HTTP Status Codes¶

Código / Code	Descrição / Description	Quando Ocorre / When it Occurs
200	OK	Operação realizada com sucesso / Success
400	Bad Request	Dados de entrada inválidos / Invalid input data
401	Unauthorized	Token ausente, inválido ou expirado / Missing or invalid token
403	Forbidden	Usuário sem permissão ADMIN_PARTNER ou API Key inválida / No permission
404	Not Found	Ordem, cliente, moeda ou finalidade não encontrados / Not found
415	Unsupported Media Type	Formato de arquivo não suportado / File format not supported
422	Unprocessable Entity	Validação de negócio falhou / Business validation failed
429	Too Many Requests	Limite de requisições excedido (rate limiting) / Rate limit exceeded
500	Internal Server Error	Erro interno do servidor / Internal server error

📎 Download de Anexos da Ordem / Order Attachments Download¶

Após criar e atualizar uma ordem, você pode fazer o download dos anexos (invoices, fichas de embarque, etc.) através dos seguintes endpoints. After creating and updating an order, you can download the attachments through the following endpoints.

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

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. Returns all attachments associated with a specific order, including file content and document type.

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

Quer baixar todos os documentos de uma ordem de uma vez / Download all documents at once
Precisa listar todos os anexos com seus tipos identificados / List all attachments with their types
Quer saber quais documentos estão associados a uma ordem / Identify which documents are linked to 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 ID

Exemplo de Requisição / Request Example¶

cURL

curl --location '[https://api.xavipay.com.br/v1/partner/public/orders/attachments/789123/download](https://api.xavipay.com.br/v1/partner/public/orders/attachments/789123/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": "contrato_servicos.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJm... ",
      "documentTypeId": 1
    },
    {
      "fileName": "nota_fiscal.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJm...",
      "documentTypeId": 1
    }
  ],
  "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`) / MIME type
`content`	byte[]	Conteúdo do arquivo codificado em Base64 / Base64 encoded content
`documentTypeId`	int?	Identificador do tipo de documento (invoice, contract, etc.) / Doc type ID

Document Type IDs¶

O campo documentTypeId identifica o tipo de documento/anexo: The documentTypeId field identifies the type of document/attachment:

ID	Tipo / Type	Descrição / Description	Contexto / Context
1	Invoice	Nota fiscal, fatura de serviços / Tax invoice	Documentos fiscais da operação / Tax documents
2	Bill of Lading	Ficha de embarque, DUE	Documentos de exportação / Export documents
null	Other	Outros comprovantes / Other proofs	Documentos diversos de suporte / Support docs

[!INFO] INFORMAÇÃO / INFORMATION

Uso do documentTypeId: Este campo ajuda a categorizar e organizar os anexos automaticamente em sua aplicação. Para ordens inbound, os tipos mais comuns são Invoice (1) para notas fiscais de exportação e Bill of Lading (2) para DUE e documentos de embarque. This field helps categorize attachments. Common types for inbound are Invoice (1) and Bill of Lading (2).

[!CAUTION] LEMBRE-SE / REMEMBER

Este é um processo regulamentado de operações de câmbio para recebimentos internacionais. Todos os dados fornecidos devem ser verdadeiros e atualizados. Informações falsas podem resultar em: This is a regulated foreign exchange process. All data must be true and up to date. False info may result in:

Bloqueio permanente da conta do parceiro / Permanent partner account block

Cancelamento de todas as ordens em andamento / Cancellation of all pending orders

Notificação aos órgãos competentes (Banco Central, Receita Federal, COAF) / Reporting to authorities

Responsabilização legal por lavagem de dinheiro ou fraude cambial / Legal liability for fraud/money laundering

[!INFO] INFORMAÇÃO / INFORMATION

Suporte Técnico / Technical Support: Para dúvidas sobre integração, autenticação ou aspectos técnicos da API, consulte a documentação geral ou entre em contato com nossa equipe de suporte técnico. / For technical or API issues, contact tech support.

Suporte Operacional / Operational Support: Para dúvidas sobre regulamentações cambiais, identificação de pagamentos, documentação necessária ou requisitos específicos de compliance, entre em contato com nossa equipe de operações através do canal de suporte dedicado. / For FX regulations or compliance, contact our operations team.

API de Ordens de Recebimento (Inbound Orders) / Inbound Orders API¶

Visão Geral / Overview¶

Documentação Relacionada / Related Documentation¶

Autenticação / Authentication¶

Descrição dos Headers / Headers Description:¶

Rate Limiting / 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)¶

Ciclo de Vida de uma Ordem / Order Life Cycle¶

Etapas do Processo / Process Steps¶

1️⃣ Parceiro: Criar Ordem / Partner: Create Order¶

2️⃣ Admin Interno: Análise e Aprovação / Internal Admin: Review and Approval¶

3️⃣ Resultado da Análise: / Analysis Result:¶

4️⃣ Parceiro: Atualizar Finalidade e Documentos / Partner: Update Purpose and Documents¶

5️⃣ Parceiro: Criar Cotação / Partner: Create Quotation¶

6️⃣ Parceiro: Salvar Conta Bancária / Partner: Save Bank Account¶

Status da Ordem / Order Status¶

Status Principais / Main Statuses¶

Status Complementares / Additional Statuses¶

Operação 1: Criação da Ordem de Recebimento / Operation 1: Creating the Inbound Order¶

Endpoint: POST /v1/partner/public/orders/inbound/create¶

Campos da Requisição / Request Fields¶

Exemplo de Requisição / Request Example¶

Resposta de Sucesso / Success Response¶

Possíveis Erros / Possible Errors¶

Dados Obrigatórios Ausentes (400 Bad Request) / Missing Mandatory Data¶

Validação do Pagador (400 Bad Request) / Payer Validation¶

Validação de Valor (400 Bad Request) / Amount Validation¶

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

Operação 2: Consultar Detalhes da Ordem / Operation 2: Get Order Details¶

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

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

Parâmetros da URL / URL Parameters¶

Exemplo de Requisição / Request Example¶

Resposta de Sucesso / Success Response¶

Informações dos Campos de Resposta / Response Fields Information¶

Campos Principais / Main Fields¶

Campos de Finalidade / Purpose Fields¶

Campos de Moeda / Currency Fields¶

Campos de Valores / Value Fields¶

Campos de Documentos / Document Fields¶

Status da Ordem / Order Status¶

Modalidades de Operação / Operation Modalities¶

Possíveis Erros / Possible Errors¶

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

Operação 3: Listar Ordens com Filtros / Operation 3: List Orders with Filters¶

Endpoint: GET /v1/partner/public/orders/inbound/get-filtered¶

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

Parâmetros de Query / Query Parameters¶

Filtros Disponíveis por Status / Available Status Filters¶

Filtros Disponíveis por Moeda / Available Currency Filters¶

Exemplo de Requisição / Request Example¶

Resposta de Sucesso / Success Response¶

Possíveis Erros / Possible Errors¶

Parâmetros de Paginação Inválidos (400 Bad Request) / Invalid Pagination Parameters¶

Operação 4: Atualizar Finalidade da Ordem / Operation 4: Update Order Purpose¶

Endpoint: PUT /v1/partner/public/orders/inbound/{orderId}/update-finality¶

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

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

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

Enquadramento de Operações / Operation Classification¶

Campos da Requisição / Request Fields¶

Regras de Modalidade para Inbound / Inbound Modality Rules¶

Formatos de Arquivo Aceitos / Accepted File Formats¶

Exemplo de Requisição / Request Example¶

Exemplo 1: Atualização com Modalidade (Finalidade de Mercadoria) / Example 1: Update with Modality (Goods Purpose)¶

Exemplo 2: Atualização sem Modalidade (Finalidade de Serviços) / Example 2: Update without Modality (Services Purpose)¶

Resposta de Sucesso / Success Response¶

Regras de Validação da Modalidade / Modality Validation Rules¶

✅ Cenário 1: Finalidade = "Mercadoria" / Scenario 1: Purpose = "Goods"¶

✅ Cenário 2: Finalidade ≠ "Mercadoria" / Scenario 2: Purpose ≠ "Goods"¶

Possíveis Erros / Possible Errors¶

Dados Obrigatórios da Atualização (400 Bad Request) / Missing Mandatory Update Data¶

Finalidade Já Definida (400 Bad Request) / Purpose Already Defined¶

Validação de Modalidade (400 Bad Request) / Modality Validation¶

Validação de Anexos (400 Bad Request) / Attachment Validation¶

Operação 5: Criar Cotação da Ordem / Operation 5: Create Order Quotation¶

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

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

Endpoint: `POST /v1/partner/public/orders/inbound/create`¶

Endpoint: `GET /v1/partner/public/orders/inbound/get-detail/{orderId}`¶

Endpoint: `GET /v1/partner/public/orders/inbound/get-filtered`¶

Endpoint: `PUT /v1/partner/public/orders/inbound/{orderId}/update-finality`¶

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

Endpoint: `POST /v1/partner/public/bank-account/{orderId}/create`¶