# API da ByteMax

Crie ordens pagas em reais e recebidas em yuans, acompanhe cada uma e faça reembolsos. Chamadas HTTPS com JSON.

- URL base: https://bytemax.exchange/api/v1
- [Baixar OpenAPI 3.1](https://bytemax.exchange/api-v1.openapi.json)
- [Página da documentação](https://bytemax.exchange/pt-BR/docs/api)

## Começar

Três passos até a primeira chamada.

1. **Crie a chave de API**
   Na página [API](https://bytemax.exchange/pt-BR/api) do seu painel, crie a chave e guarde no seu servidor: ela aparece uma vez só e dá acesso a toda a sua conta. Ative a lista de IPs permitidos antes de usar.

2. **Envie estes cabeçalhos em toda chamada**
   Ao criar ordens e reembolsos, inclua também `Idempotency-Key`. Veja Valores e idempotência.

   ```http
   Authorization: Bearer <API_KEY>
   Content-Type: application/json
   ```

3. **Faça uma cotação**
   A cotação não cria nada. Use para conferir a chave e ver os valores da conversão.

   ```bash
   curl --request GET "https://bytemax.exchange/api/v1/quote?source_currency=BRL&target_currency=CNY&source_amount_atomic=10000" \
     --header "Authorization: Bearer <API_KEY>"
   ```

   **Resposta 200**

   ```json
   {
     "source_currency": "BRL",
     "source_amount_atomic": "10000",
     "target_currency": "CNY",
     "target_amount_atomic": "12500000000"
   }
   ```

## Fluxo de pagamento

Uma ordem começa aguardando pagamento, é paga pelo link e termina concluída, expirada ou cancelada. Acompanhe por webhook ou por consulta.

1. **Cotação (opcional)**
   `GET /quote` informa quanto o pagador paga e quanto você recebe. A ordem usa a cotação do momento em que é criada.

2. **Crie a ordem**
   `POST /orders` com a moeda paga (BRL), a moeda recebida (CNY) e um dos dois valores: quanto o pagador paga ou quanto você recebe. A resposta traz `payment.url`, o link de pagamento, e `pix_copy_paste` quando disponível.

3. **Envie o pagador para o link**
   Abra `payment.url` para o pagador. Ao concluir ou fechar o pagamento, ele volta para a URL de retorno configurada na página API do seu painel. Sem essa URL, o navegador volta pelo histórico.

4. **Acompanhe a ordem**
   Cadastre um [webhook](https://bytemax.exchange/pt-BR/docs/webhooks) para receber `order.updated` a cada mudança, ou consulte `GET /orders/{id}`.

5. **Reembolse se precisar**
   `POST /orders/{id}/refunds` com o valor em CNY. Se a resposta for 202, o reembolso ainda está em processamento: acompanhe com `GET /orders/{id}/refunds/{refund_id}` e não crie outro.

### Estados da ordem

- `pending_payment`: Aguardando o pagamento. O link de pagamento está ativo.
- `processing`: Pagamento identificado. A ordem está sendo processada.
- `completed`: Concluída. Estado final.
- `expired`: O prazo terminou sem pagamento. Estado final.
- `canceled`: Cancelada. Estado final.
- `on_hold`: Ordem retida. A retomada exige liberação explícita pela ByteMax.

### Estados do reembolso

- `processing`: Em andamento.
- `succeeded`: Concluído. Estado final.
- `failed`: Não foi possível concluir o reembolso. Estado final.
- `pending_reconciliation`: Resultado ainda não confirmado. Consulte até mudar e não crie outro reembolso.

## Valores e idempotência

### Valores

Todo valor é uma string com um inteiro na menor unidade da moeda, sem sinal, ponto ou notação científica. BRL tem 2 casas: `"10000"` é R$ 100,00. CNY tem 8 casas: `"12500000000"` é ¥ 125,00. Informe exatamente um dos dois valores, `source_amount_atomic` ou `target_amount_atomic`. Hoje o único par é BRL → CNY: o pagador paga em reais e você recebe em yuans. O valor máximo por ordem é 1.000.000 unidades da moeda informada.

### Idempotência

Envie `Idempotency-Key` ao criar ordens e reembolsos, com uma chave nova para cada operação nova. Repetir a mesma chave com o mesmo corpo devolve o resultado já criado, com 200: é assim que você repete uma chamada com segurança depois de uma falha de rede. A mesma chave com outro corpo devolve 409. Guarde a chave junto do pedido no seu sistema.

## Referência

Cinco operações. Os exemplos usam `<API_KEY>` e IDs fictícios.

### Cotação

`GET /quote`

Informa os valores de uma conversão sem criar nada. Duas moedas e um dos dois valores na query.

| Parâmetro | Onde | Obrigatório |
| --- | --- | --- |
| `source_currency` | query | Sim |
| `target_currency` | query | Sim |
| `source_amount_atomic` | query | Não |
| `target_amount_atomic` | query | Não |

**Requisição**

```bash
curl --request GET "https://bytemax.exchange/api/v1/quote?source_currency=BRL&target_currency=CNY&source_amount_atomic=10000" \
  --header "Authorization: Bearer <API_KEY>"
```

**Resposta 200**

```json
{
  "source_currency": "BRL",
  "source_amount_atomic": "10000",
  "target_currency": "CNY",
  "target_amount_atomic": "12500000000"
}
```

### Criar ordem

`POST /orders`

Cria a ordem e devolve o link de pagamento. Exige `Idempotency-Key`.

| Parâmetro | Onde | Obrigatório |
| --- | --- | --- |
| `Idempotency-Key` | cabeçalho | Sim |

**Requisição**

```bash
curl --request POST "https://bytemax.exchange/api/v1/orders" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Idempotency-Key: order-8412" \
  --header "Content-Type: application/json" \
  --data '{"source_currency":"BRL","source_amount_atomic":"10000","target_currency":"CNY"}'
```

**Resposta 201**

```json
{
  "id": "ord_example",
  "version": "1",
  "status": "pending_payment",
  "source_currency": "BRL",
  "source_amount_atomic": "10000",
  "target_currency": "CNY",
  "target_amount_atomic": "12500000000",
  "refunded_source_amount_atomic": "0",
  "blocked_source_amount_atomic": "0",
  "payment": {
    "url": "https://bytemax.exchange/pay/example",
    "pix_copy_paste": null
  },
  "created_at": "2026-09-10T13:05:00.000Z"
}
```

### Consultar ordem

`GET /orders/{id}`

Estado atual e valores da ordem.

| Parâmetro | Onde | Obrigatório |
| --- | --- | --- |
| `id` | caminho | Sim |

**Requisição**

```bash
curl --request GET "https://bytemax.exchange/api/v1/orders/ord_example" \
  --header "Authorization: Bearer <API_KEY>"
```

**Resposta 200**

```json
{
  "id": "ord_example",
  "version": "1",
  "status": "pending_payment",
  "source_currency": "BRL",
  "source_amount_atomic": "10000",
  "target_currency": "CNY",
  "target_amount_atomic": "12500000000",
  "refunded_source_amount_atomic": "0",
  "blocked_source_amount_atomic": "0",
  "payment": {
    "url": "https://bytemax.exchange/pay/example",
    "pix_copy_paste": null
  },
  "created_at": "2026-09-10T13:05:00.000Z"
}
```

### Criar reembolso

`POST /orders/{id}/refunds`

Reembolsa parte ou todo o valor recebido, em CNY. Exige `Idempotency-Key`. Responde 202 enquanto o reembolso estiver em processamento.

| Parâmetro | Onde | Obrigatório |
| --- | --- | --- |
| `id` | caminho | Sim |
| `Idempotency-Key` | cabeçalho | Sim |

**Requisição**

```bash
curl --request POST "https://bytemax.exchange/api/v1/orders/ord_example/refunds" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Idempotency-Key: order-8412" \
  --header "Content-Type: application/json" \
  --data '{"target_amount_atomic":"2500000000"}'
```

**Resposta 202**

```json
{
  "id": "ref_example",
  "order_id": "ord_example",
  "version": "1",
  "status": "processing",
  "source_currency": "BRL",
  "source_amount_atomic": "2000",
  "target_currency": "CNY",
  "target_amount_atomic": "2500000000",
  "created_at": "2026-09-10T13:05:00.000Z",
  "updated_at": "2026-09-10T13:05:00.000Z"
}
```

### Consultar reembolso

`GET /orders/{id}/refunds/{refund_id}`

Estado atual do reembolso.

| Parâmetro | Onde | Obrigatório |
| --- | --- | --- |
| `id` | caminho | Sim |
| `refund_id` | caminho | Sim |

**Requisição**

```bash
curl --request GET "https://bytemax.exchange/api/v1/orders/ord_example/refunds/ref_example" \
  --header "Authorization: Bearer <API_KEY>"
```

**Resposta 200**

```json
{
  "id": "ref_example",
  "order_id": "ord_example",
  "version": "1",
  "status": "processing",
  "source_currency": "BRL",
  "source_amount_atomic": "2000",
  "target_currency": "CNY",
  "target_amount_atomic": "2500000000",
  "created_at": "2026-09-10T13:05:00.000Z",
  "updated_at": "2026-09-10T13:05:00.000Z"
}
```

## Erros e limites

Toda resposta de erro traz `code` e `message`, e às vezes `details`. Guarde o cabeçalho `X-Request-Id`: ele identifica a chamada quando você falar com o suporte. Campos desconhecidos e parâmetros repetidos são rejeitados com 400.

```json
{
  "code": "UNSUPPORTED_CURRENCY_PAIR",
  "message": "Unsupported currency pair."
}
```

| Código | Quando acontece |
| --- | --- |
| 400 | Dados inválidos, par de moedas não suportado (`UNSUPPORTED_CURRENCY_PAIR`) ou valor fora das regras. |
| 401 | Chave de API ausente ou inválida. |
| 403 | IP fora da lista permitida ou operação não autorizada para a conta. |
| 404 | Ordem, reembolso ou webhook não encontrado. |
| 409 | Chave de idempotência repetida com outro corpo. |
| 415 | Corpo sem `Content-Type: application/json`. |
| 429 | Limite de chamadas excedido. Espere e repita. |
| 503 | Serviço indisponível. Repita depois de alguns segundos, aumentando a espera a cada tentativa. |

### Limite de chamadas

5 chamadas por segundo e 300 por minuto por chave. Cada resposta informa o limite nos cabeçalhos abaixo. Ao receber 429, espere até o horário de `X-RateLimit-Reset` antes de repetir. Para acompanhar ordens, use webhooks em vez de consultar a cada poucos segundos.

```http
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1757509560
```

Dúvidas na integração? [Fale com o suporte](https://bytemax.exchange/pt-BR/suporte).