Guía para desarrolladores · pruebas de integración
Sandbox de API PIX, custodia y criptomonedas
Valida el recorrido financiero de tu producto antes de usar una clave de producción. El sandbox de Lunium simula solicitudes de cobro PIX, saldo BRL, entregas y retiros en criptomonedas, payout y cash-out en la misma API que usa la integración.
Seis recorridos, con criterios de finalización
La credencial lun_test_ selecciona el entorno ficticio. La URL base sigue siendo https://api.luniumpay.com. Pruebas solicitudes, respuestas, estados, saldo y eventos sin pagar PIX ni enviar criptomonedas.
| Recorrido | Cómo crear | Cuándo ha terminado |
|---|---|---|
| PIX → custodia BRL | POST /cashin/charge, destino: "saldo" | paid y sent, con abono en la subcuenta correcta. |
| PIX → criptomonedas | POST /cashin/charge, destino: "cripto" | paid y sent; hash ficticio sandbox:. |
| Custodia → criptomonedas | POST /saldo/sacar-cripto | Entrega sent y débito conciliado, incluida la tarifa. |
| Custodia → PIX | POST /payouts | status=sent, con E2E ficticio y débito en los movimientos. |
| Transferencia interna | POST /saldo/transferir | Débito y abono en las referencias correctas; se conserva el total en custodia. |
| Criptomonedas externas → PIX | POST /cash-outs y aceptación | state=COMPLETED; depósito y PIX simulados. |
El QR contiene SANDBOX:NAO_PAGAVEL:. No es un PIX bancario. La confirmación usa POST /sandbox/cashin/{cashin_id}/pay. No se activa ningún banco, plataforma de intercambio ni blockchain.
Empieza desde el navegador o tu backend
La integración guiada permite elegir el flujo y ejecutar una demostración indicando solo tu correo. Para implementar en tu proyecto, descarga el kit Node y Python, extrae los archivos y ejecuta:
node sandbox.mjs all
# o Python 3.9+, sin dependencias:
python3 sandbox.py allEl kit crea una clave de prueba en memoria con el correo de quien realiza la prueba (define LUNIUM_SANDBOX_EMAIL; sin él, el kit se detiene con un mensaje claro) y verifica GET /keys/me antes de operar. También acepta LUNIUM_API_KEY con una credencial exclusivamente de prueba y rechaza las claves de producción. Usa custody, cashin, payout o cashout en lugar de all para seleccionar un recorrido.
Para realizar las llamadas manualmente
curl --fail-with-body https://api.luniumpay.com/keys/sandbox \
-H 'Content-Type: application/json' \
-d '{"email":"voce@empresa.com","name":"Minha integração"}'El email de quien realiza la prueba es obligatorio: allí enviamos el manual, el diagrama de flujo y la guía de integración paso a paso. Sin él, la respuesta es 400 email_obrigatorio. Guarda el campo api_key en una variable de entorno del backend; no lo pongas en el frontend, en una URL ni en una conversación con IA. Reutiliza la clave: la creación tiene una cuota por IP. Consulta GET /sandbox para conocer las funciones y la matriz actual de escenarios.
Prueba también lo que impide finalizar
| Escenario | Qué debe hacer tu sistema |
|---|---|
delayed / held | Mostrar espera o retención sin crear otra operación. Los escenarios disponibles dependen del flujo. |
expired / payer_mismatch | Cerrar o conciliar la solicitud de cobro sin acreditar un saldo indebido. |
settlement_failed | Distinguir el pago confirmado de una entrega fallida. Comprobar el resultado y los movimientos. |
settlement_uncertain | Conservar la operación original y no dar por hecho que se haya realizado una reversión. Usa la resolución ficticia solo en el sandbox. |
route_unavailable / provider_unavailable | Mostrar un fallo que indique qué hacer, sin anunciar una creación o un débito que no hayan ocurrido. |
| Saldo insuficiente y repetición | Rechazar un gasto sin saldo; repetir la misma referencia y el mismo cuerpo sin duplicar solicitudes de cobro ni retiros. |
Para cash-in, custodia y payout, envía sandbox_scenario solo con una clave de prueba y consulta scenarios_by_flow en GET /sandbox. No todos los escenarios se aplican a todos los recorridos. Una operación incierta puede resolverse mediante POST /sandbox/operations/{operation_id}/resolve con {"outcome":"sent"} o {"outcome":"failed"}.
Cash-out usa desencadenantes en los dos decimales de amount o brl_amount: .00 éxito, .01 retraso, .02 fallo, .03 vencimiento y otros descritos en la guía técnica de escenarios. No apliques estos desencadenantes como reglas de producción.
Webhooks reales para eventos ficticios
Configura una URL HTTPS pública propia y guarda webhook_secret. El evento del sandbox incluye sandbox:true, pero la entrega HTTP y su firma usan la cola real de webhooks. Esto permite probar la validación HMAC, la respuesta de tu servidor, los duplicados y los reenvíos.
| Endpoint | Validación posible |
|---|---|
GET /sandbox/events | Eventos de la simulación, incluso sin un callback configurado. |
GET /webhooks/deliveries | Intentos de entrega, respuesta del receptor y resultado. |
POST /webhooks/deliveries/{event_id}/retry | Reenvío para comprobar el procesamiento idempotente. |
Valida el cuerpo sin procesar, la marca de tiempo y event_id según el contrato de firma. Configura el callback antes de la operación: la simple configuración de la URL no envía eventos antiguos de forma retroactiva.
Qué demuestra la prueba y qué depende de producción
El sandbox demuestra que tu software puede crear, seguir y conciliar los recorridos simulados. Las cotizaciones y los catálogos son instantáneas sintéticas. Debes volver a consultar con la clave real los mínimos, la disponibilidad, los precios, los límites y las retenciones de producción.
Cash-in, custodia, payout y transferencias se guardan de forma aislada del libro financiero real. Cash-out también se guarda, con una retención de dos horas. Hay un límite de 1.000 operaciones por clave para los nuevos recorridos y 1.000 cash-outs. Usa POST /sandbox/reset con {"confirm":true} para borrar el estado ficticio; el historial de webhooks ya encolados permanece.
No se simulan tokens DEX arbitrarios por contrato, lectura bancaria de QR dinámicos, confirmaciones reales de blockchain ni políticas privadas de los proveedores. Las retenciones de prueba tienen tiempos reducidos. Completar la prueba no certifica liquidez ni ejecución bancaria: una prueba piloto con PIX pagado y criptomonedas entregadas es una operación real y requiere un importe y un destinatario autorizados.
Consultas de integración
¿El sandbox solo simula criptomonedas a PIX?
No. Cubre los seis recorridos de la tabla, incluidos PIX a custodia o criptomonedas, retiros y transferencias. El flujo de entrada PIX requiere confirmación explícita mediante la API de simulación.
¿Cómo recibir fondos sin una billetera fija en la prueba?
Envía destino: "saldo" en la solicitud de cobro. El saldo permanece en BRL y la billetera solo se elige al realizar un retiro posterior en criptomonedas.
¿Puedo integrar con ChatGPT u otro agente?
Usa el guía de integración con IA y la descripción de integración de la página guiada. La conexión pública mediante MCP ofrece descubrimiento y demostraciones de sandbox; operar cuentas de producción desde ChatGPT sigue requiriendo la autenticación de esas cuentas.
¿Dónde está el contrato para generar mi integración?
El OpenAPI, el manual y el manifiesto de integración describen los flujos. Pide a la IA que los lea antes de editar tu proyecto y mantén las credenciales fuera del chat.