Información general

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
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 para aprender a firmar las solicitudes
5. Realiza tu primera llamada Create Payment

URL base

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

https://api.2328.io/api

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

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.