2328 Documentation

Bienvenido a la documentación de la API de 2328.io. Esta referencia describe cómo integrar el procesamiento de pagos con 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 tu UUID de proyecto y clave de API desde la configuración del proyecto
3. Genera una clave de API de pagos separada si planeas usar retiros
4. Lee la sección Autenticación para aprender cómo firmar las solicitudes
5. Realiza tu primera llamada a Crear pago

URL base

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

https://api.2328.io/api

Todas las solicitudes deben realizarse a través de HTTPS. Las solicitudes sin HTTPS están bloqueadas.

Lo que puedes hacer

Con la API de 2328.io puedes:

• Aceptar pagos con criptomonedas — crear sesiones de pago y redirigir a los clientes a un checkout alojado o a una MiniApp de Telegram
• Retirar fondos — enviar pagos programáticamente desde tu saldo de comerciante a cualquier dirección de blockchain
• Consultar saldos — ver los saldos de la cuenta de comerciante por moneda, equivalentes en USD y montos bloqueados por AML
• Usar billeteras estáticas — generar direcciones de depósito permanentes vinculadas a un usuario o pedido
• Obtener tipos de cambio — consultar tasas en tiempo real para pares de monedas fiduciarias y criptomonedas
• Recibir webhooks — recibir notificaciones instantáneas 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 — retrocede y reintenta.

Elige el patrón de integración adecuado

Requisito	Patrón recomendado	Por qué
Deja que el cliente elija cómo pagar	Checkout alojado	Crea un pago y redirige a result.url; 2328.io presenta las direcciones disponibles actualmente.
Mantén al cliente dentro de tu propio checkout	Factura H2H de dirección directa	Envía to_currency y network al crear el pago; muestra los address, payer_amount y qr devueltos.
Cobra exactamente 25 USDT o 0.001 BTC	Factura denominada en criptomoneda	Coloca la criptomoneda en currency y el monto decimal exacto en amount.
Dale a cada usuario una dirección de depósito reutilizable	Billetera estática	La dirección es permanente y puede recibir muchos depósitos independientes.
Normaliza los activos entrantes a una moneda de saldo	Conversión automática	Configura las reglas del proyecto en el panel y consume el resultado de convert cuando se complete la conversión.
Intercambia un saldo de comerciante existente	Conversión manual	Previsualiza con /v1/convert/price, luego ejecuta con /v1/convert.
Envía fondos a una dirección de blockchain	Pago	Usa la clave de API de pagos separada, calcula primero y concilia el estado del pago.

El checkout alojado y H2H son dos presentaciones de la misma API de pagos. H2H no crea un pago más débil o sin firmar: el backend aún crea la factura, 2328.io sigue siendo el propietario de la dirección y el estado, y los webhooks firmados siguen siendo la autoridad para la liquidación.

Invariantes de integración

Estas reglas se aplican a cada integración en producción:

• Solo backend — mantén las claves de API fuera de navegadores, aplicaciones móviles, registros, análisis y capturas de pantalla de soporte.
• Cadenas decimales — envía y almacena el dinero como cadenas. Nunca redondees criptomonedas o tipos de cambio con aritmética de punto flotante binaria.
• Claves de idempotencia inmutables — genera order_id antes de la primera solicitud y persiste la solicitud completa con ella. Un reintento con el mismo order_id puede devolver el objeto original en lugar de aplicar campos modificados.
• Liquidación basada en webhooks primero — las redirecciones, el sondeo del cliente, los hashes de transacción proporcionados por los usuarios y los tiempos de espera HTTP no son prueba de pago.
• Verifica, deduplica, luego muta — verifica el HMAC, reclama un registro de idempotencia atómicamente, actualiza el pedido/saldo una vez y devuelve HTTP 200 rápidamente.
• Conciliación — consulta periódicamente el estado de pagos, billeteras estáticas y pagos para que un webhook perdido no deje un desacuerdo permanente.
• Disponibilidad dinámica — valida los pares de moneda/red con /v1/directions; un activo compatible aún puede tener una dirección de depósito o retiro temporalmente deshabilitada.
• Política de estado explícita — decide cómo tu producto maneja el pago parcial, el sobrepago, la expiración, el bloqueo AML, el respaldo de conversión y los tiempos de espera ambiguos del proveedor antes de salir a producción.

Datos recomendados para persistir

Para pagos, almacena como mínimo uuid, order_id, el cuerpo de la solicitud original, amount, currency, payer_currency, payer_amount, network, address, expires_at, el último payment_status, txid, payment_amount, merchant_amount, el bloque opcional convert y la carga útil del webhook verificada sin procesar.

Para billeteras estáticas, mantén la uuid de la billetera, la dirección, la moneda, la red, la referencia de cliente/cuenta, el estado y la URL de callback por separado de los registros de depósito. Cada depósito necesita su propia transacción uuid, txid, estado, monto recibido, monto del comerciante y resultado de conversión.