# Información general

> Especificación técnica para integrar el procesamiento de pagos en criptomonedas y los retiros con 2328.io.

Te damos la bienvenida a la documentación de la API de 2328.io. Esta referencia describe cómo integrar el procesamiento de pagos en criptomonedas y los retiros en tu aplicación.

## Primeros pasos

Para comenzar la integración:

1. Crea una cuenta de comerciante y un proyecto en [2328.io](https://2328.io)
2. Obtén el **UUID del proyecto** y la **API key** desde la configuración del proyecto
3. Genera una **Payout API key** independiente si planeas usar retiros
4. Lee la sección [Authentication](/docs/authentication) para aprender a firmar las solicitudes
5. Realiza tu primera llamada [Create Payment](/docs/payments)

## URL base

Todas las solicitudes de la API en producción utilizan la siguiente URL base:

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

> **WARNING:** Todas las solicitudes deben realizarse a través de **HTTPS**. Las solicitudes sin HTTPS son bloqueadas.

## Qué puedes hacer

Con la API de 2328.io puedes:

- **Aceptar pagos en cripto** — crear sesiones de pago y redirigir a los clientes a un checkout alojado o a un Telegram MiniApp
- **Retirar fondos** — enviar retiros mediante programación desde tu saldo de comerciante a cualquier dirección blockchain
- **Consultar saldos** — los saldos de cuentas del comerciante por divisa, sus equivalentes en USD y los montos bloqueados por AML
- **Usar monederos estáticos** — generar direcciones de depósito permanentes vinculadas a un usuario o pedido
- **Obtener tipos de cambio** — consultar tipos de cambio en tiempo real para pares fiat y cripto
- **Recibir webhooks** — recibir notificaciones al instante cuando cambia el estado de un pago
## Límites de tasa

La API permite hasta **10 solicitudes por segundo por proyecto**. Las solicitudes que superen el límite reciben una respuesta HTTP `429 Too Many Requests` — aplica backoff y reintenta.

## Elija el patrón de integración correcto

| Requisito | Patrón recomendado | Por qué |
|-------------|---------------------|-----|
| Permitir al cliente elegir cómo pagar | Hosted checkout | Crear un pago y redirigir a `result.url`; 2328.io presenta las direcciones disponibles actualmente. |
| Mantener al cliente dentro de su propio proceso de pago | Dirección directa **H2H** invoice | Enviar `to_currency` y `network` al crear el pago; renderizar los retornados `address`, `payer_amount` y `qr`. |
| Cobrar exactamente `25 USDT` o `0.001 BTC` | Denominado en criptomoneda invoice | Colocar la criptomoneda en `currency` y la cantidad decimal exacta en `amount`. |
| Dar a cada usuario una dirección de depósito reutilizable | Static wallet | La dirección es permanente y puede recibir muchos depósitos independientes. |
| Normalizar los activos entrantes en una sola moneda de saldo | Auto-convert | Configurar las reglas del proyecto en el panel de control y consumir el resultado `convert` cuando la conversión se complete. |
| Intercambiar un saldo existente merchant | Manual convert | Previsualizar con `/v1/convert/price`, luego ejecutar con `/v1/convert`. |
| Enviar fondos a una dirección de blockchain | Pago | Use la clave API de pago separada, calcule primero y reconcilie el estado del pago. |

> **INFO:** Hosted checkout y H2H son dos presentaciones del mismo API de pago. H2H no crea un pago más débil o sin firmar: el backend aún crea el invoice, 2328.io aún posee la dirección y el estado, y el webhooks firmado sigue siendo autoritativo para settlement.

## Integración de invariantes

Estas reglas se aplican a cada integración production:

- **Solo backend** — mantenga las claves API fuera de navegadores, aplicaciones móviles, registros, análisis y capturas de pantalla de soporte.
- **Cadenas decimales** — envíe y almacene dinero como cadenas. Nunca redondee criptomonedas o tasas de cambio con aritmética de punto flotante binaria.
- **Claves inmutables idempotency** — genere `order_id` antes de la primera solicitud y persista la solicitud completa con ella. Un retry con el mismo `order_id` puede devolver el objeto original en lugar de aplicar campos modificados.
- **Liquidación basada en webhook** — redirecciones, sondeos de cliente, hashes de transacciones proporcionados por usuarios y tiempos de espera HTTP no son prueba de pago.
- **Verificar, deduplicar, luego mutar** — verifique el HMAC, reclame un registro idempotency de manera atómica, actualice el pedido/saldo una vez y devuelva HTTP 200 rápidamente.
- **Reconciliación** — consulte periódicamente el estado del pago, la billetera estática y el pago para que un webhook perdido no deje un desacuerdo permanente.
- **Disponibilidad dinámica** — valide pares de moneda/red con `/v1/directions`; un activo compatible aún puede tener temporalmente una dirección de depósito o retiro deshabilitada.
- Política de estado explícito — decida cómo su producto maneja el pago parcial, el sobrepago, la expiración, el bloqueo AML, la conversión y los tiempos de espera ambiguos aguas arriba antes de entrar en producción.

## Datos recomendados para persistir

Para pagos, almacene como mínimo `uuid`, `order_id`, el cuerpo de la solicitud original, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, el más reciente `payment_status`, `txid`, `payment_amount`, `merchant_amount`, el bloque opcional `convert` y el webhook payload verificado en bruto.

Para static wallets, mantenga la billetera `uuid`, la dirección, la moneda, la red, la referencia del cliente/cuenta, el estado y la URL de callback separadamente de los registros de depósitos. Cada depósito necesita su propia transacción `uuid`, `txid`, estado, monto recibido, monto merchant y resultado de la conversión.