# Informações gerais

> Especificação técnica para integração de processamento de pagamentos e saques em criptomoedas com a 2328.io.

Bem-vindo à documentação da API da 2328.io. Esta referência descreve como integrar o processamento de pagamentos e saques em criptomoedas em sua aplicação.

## Primeiros passos

Para começar a integração:

1. Crie uma conta de comerciante e um projeto em [2328.io](https://2328.io)
2. Obtenha o **UUID do projeto** e a **API key** nas configurações do projeto
3. Gere uma **Payout API key** separada caso pretenda usar saques
4. Leia a seção [Authentication](/docs/authentication) para aprender a assinar requisições
5. Faça sua primeira chamada de [Create Payment](/docs/payments)

## URL base

Todas as requisições de API em produção utilizam a seguinte URL base:

```
https://api.2328.io/api
```

> **WARNING:** Todas as requisições devem ser feitas via **HTTPS**. Requisições sem HTTPS são bloqueadas.

## O que você pode fazer

Com a API da 2328.io você pode:

- **Aceitar pagamentos em cripto** — criar sessões de pagamento e redirecionar clientes para um checkout hospedado ou Telegram MiniApp
- **Sacar fundos** — enviar saques programaticamente do saldo do comerciante para qualquer endereço blockchain
- **Consultar saldos** — veja os saldos das contas do comerciante por moeda, equivalentes em USD e valores bloqueados por AML
- **Usar carteiras estáticas** — gerar endereços de depósito permanentes vinculados a um usuário ou pedido
- **Consultar taxas de câmbio** — obter taxas em tempo real para pares de moedas fiduciárias e criptomoedas
- **Receber webhooks** — ser notificado instantaneamente quando o status de um pagamento muda
## Limites de taxa

A API permite até **10 requisições por segundo por projeto**. Requisições acima do limite recebem uma resposta HTTP `429 Too Many Requests` — aguarde e tente novamente.

## Escolha o padrão de integração correto

| Requisito | Padrão recomendado | Por quê |
|-------------|---------------------|-----|
| Deixe o cliente escolher como pagar | Checkout hospedado | Crie um pagamento e redirecione para `result.url`; 2328.io apresenta as direções atualmente disponíveis. |
| Mantenha o cliente dentro do seu próprio checkout | Fatura de endereço direto **H2H** | Envie `to_currency` e `network` ao criar o pagamento; renderize os retornados `address`, `payer_amount` e `qr`. |
| Cobre exatamente `25 USDT` ou `0.001 BTC` | Fatura denominada em criptomoeda | Coloque a criptomoeda em `currency` e o valor decimal exato em `amount`. |
| Dê a cada usuário um endereço de depósito reutilizável | Carteira estática | O endereço é permanente e pode receber vários depósitos independentes. |
| Normalize os ativos recebidos em uma moeda de saldo | Conversão automática | Configure as regras do projeto no painel e use o resultado `convert` quando a conversão for concluída. |
| Troque um saldo de comerciante existente | Conversão manual | Visualize com `/v1/convert/price`, depois execute com `/v1/convert`. |
| Envie fundos para um endereço de blockchain | Pagamento | Use a chave de API de Pagamento separada, calcule primeiro e reconcilie o status do pagamento. |

> **INFO:** Checkout hospedado e H2H são duas apresentações da mesma API de Pagamento. H2H não cria um pagamento mais fraco ou não assinado: o backend ainda cria a fatura, 2328.io ainda possui o endereço e o status, e webhooks assinados permanecem autoritativos para a liquidação.

## Invariantes de integração

Estas regras se aplicam a toda integração em produção:

- **Backend only** — mantenha as chaves de API fora de navegadores, aplicativos móveis, logs, análises e capturas de tela de suporte.
- **Decimal strings** — envie e armazene dinheiro como strings. Nunca arredonde criptomoedas ou taxas de câmbio usando aritmética de ponto flutuante binária.
- **Immutable idempotency keys** — gere `order_id` antes da primeira solicitação e persista a solicitação completa com ele. Uma nova tentativa com o mesmo `order_id` pode retornar o objeto original em vez de aplicar campos alterados.
- **Webhook-first settlement** — redirecionamentos, polling do cliente, hashes de transação fornecidos por usuários e timeouts HTTP não são prova de pagamento.
- **Verify, deduplicate, then mutate** — verifique o HMAC, reivindique um registro de idempotência de forma atômica, atualize o pedido/saldo uma vez e retorne HTTP 200 rapidamente.
- **Reconciliation** — consulte periodicamente o status de pagamento, carteira estática e pagamento para que um webhook perdido não possa deixar um desacordo permanente.
- **Dynamic availability** — valide pares de moeda/rede com `/v1/directions`; um ativo suportado ainda pode ter temporariamente uma das direções de depósito ou retirada desativada.
- **Explicit status policy** — decida como seu produto lida com pagamento parcial, pagamento em excesso, expiração, bloqueio AML, fallback de conversão e timeouts ambíguos de upstream antes de entrar em operação.

## Dados recomendados para persistir

Para pagamentos, armazene no mínimo `uuid`, `order_id`, o corpo da solicitação original, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, o mais recente `payment_status`, `txid`, `payment_amount`, `merchant_amount`, o bloco opcional `convert`, e o payload bruto verificado do webhook.

Para carteiras estáticas, mantenha a carteira `uuid`, endereço, moeda, rede, referência do cliente/conta, status e URL de callback separadamente dos registros de depósito. Cada depósito precisa de sua própria transação `uuid`, `txid`, status, valor recebido, valor do comerciante e resultado da conversão.