Ambientes y Sandbox

La API de Aloha se sirve desde dos hosts. Sandbox es donde se desarrolla y se prueba, y no mueve dinero; Producción es donde lo mueve. Son dos instalaciones separadas: cada una tiene sus propias cuentas, sus propias Claves API y sus propios endpoints de webhook, y nada de lo que se cree en una aparece en la otra.

Pasar de uno a otro es cambiar el host y la clave: las rutas, los cuerpos y los códigos de error que documenta este sitio valen para los dos.

El playground de esta documentación apunta a Sandbox

Las llamadas que se ejecutan desde estas páginas van contra api.sandbox.aloha.co. Eso significa que la clave que se pegue aquí se escribe en un navegador, y una clave escrita en un navegador es una clave que queda en el historial, en el portapapeles y posiblemente en alguna extensión.

De ahí la única regla no negociable de esta página: una clave de Producción no se pega nunca en un navegador, ni aquí ni en ninguna consola web. Para probar desde estas páginas se usa una clave de Sandbox, que es lo que el playground espera de todos modos.

El Ambiente va escrito en la clave, pero nadie lo elige

El segmento del medio de una clave —pay_<cuenta>_<ambiente>_<secreto>— admite tres valores: dev, test y live. En la práctica solo se ve uno.

El panel no ofrece elegirlo. El diálogo que crea una clave pide un nombre, unos Permisos y unos Orígenes Permitidos, y nada más; el Ambiente lo fija él, siempre en live. Eso vale igual para las dos instalaciones, así que una clave creada en el panel de Sandbox también dice live. No es un error, y no significa que esa clave toque dinero real.

Los otros dos valores existen en la API, que acepta dev, test y live al crear una clave, pero solo se alcanzan llamando a esa operación directamente.

Ese segmento es parte de la clave, así que cambiarlo sería cambiar la clave: editar una clave ya creada no lo admite. Una clave que tiene que pasar a otro Ambiente no se edita, se sustituye — se crea una nueva, se despliega, y después se borra la anterior. Lo que sí se puede cambiar de una clave ya creada es todo lo demás menos el secreto: su nombre, sus Permisos, su Límite de Peticiones, sus Orígenes Permitidos, su fecha de caducidad y si está activa. El secreto tampoco se rota en el sitio — para eso también hay que sustituir la clave.

Ese segmento no enruta nada, y tampoco bloquea nada. Dice para qué Ambiente se creó la clave, no contra qué host responde. Una vez comprobado que dice dev, test o live —cualquier otra cosa es un 401 invalid_key_format—, nada más en la API lo vuelve a mirar: no se compara contra el host, ni contra la cuenta, ni contra la operación. Una clave dev creada en la instalación de Producción mueve dinero real exactamente igual que una live.

Conviene leer el segmento como lo que es —una etiqueta que casi siempre dice lo mismo— y no como una garantía. Lo que decide si una operación toca dinero real es la instalación en la que existen la cuenta y la clave, que es la misma a la que apunta la URL que se llama.

Usar una clave de una instalación contra el host de la otra no llega a ningún sitio: el prefijo se resuelve dentro de la instalación a la que se llamó, y allí no encuentra la cuenta —401 invalid_tenant— o la encuentra y el secreto no verifica —401 invalid_api_key—. Siempre es un 401 ruidoso, nunca un éxito silencioso, y es el único fallo de esta página que se nota solo.

Los precios de Sandbox no son precios

Esta es la parte que sorprende, y la que más caro sale descubrir tarde.

Sandbox no publica los precios de Producción: los suyos se derivan de ellos. Eso los deja bien para comprobar que una cotización devuelve la forma esperada y mal para cualquier otra cosa. El síntoma más visible es también el más incómodo de explicar: en rutas de la misma moneda, Sandbox puede llegar a cotizar que el destinatario recibe más de lo que se envió, que es un resultado que en Producción no ocurre.

De modo que:

• Sirve para validar formas de petición y respuesta, Estados, entregas de webhook, manejo de errores, reintentos y el recorrido completo de un cobro de punta a punta.
• No sirve para comprobar una Tasa de Cambio, una Comisión, un monto mínimo o cuánto acaba acreditándose. Todo eso se confirma contra Producción, con un cobro pequeño y real, y no antes.

Un número que sale de Sandbox no se enseña a nadie ni se usa para fijar un precio.

Conseguir acceso a Sandbox

Las cuentas de Sandbox se piden al equipo de Aloha. Las credenciales llegan dentro de las 24 horas hábiles siguientes. Con ellas se entra al panel de Sandbox y desde ahí se crea la primera Clave API, que es por donde empieza Inicio rápido.

Pasar a Producción

Lo que cambia es corto: el host y la clave. Lo que hay que rehacer es lo que no viaja entre instalaciones:

• La cuenta de Producción se verifica por separado. Verificar Identidad y Verificación Comercial se hacen otra vez ahí, y hasta que las dos estén hechas la creación de cobros se rechaza con un 400, aunque en Sandbox funcionara.
• Los endpoints de webhook se registran otra vez, con una clave de Producción y apuntando al servidor de Producción. Los de Sandbox se quedan donde están.
• El secreto de firma es otro. El que devolvió el registro en Sandbox no sirve para verificar una entrega de Producción.
• La primera operación real se hace pequeña. Es la única forma de ver los precios de verdad, que es justamente lo que Sandbox no podía enseñar.

Seguir por aquí

• Inicio rápido — las cuatro llamadas contra Sandbox, copiables tal cual.
• Autenticación y Claves API — qué lleva una clave y qué contesta cuando falla.
• Verificación de la cuenta — las dos verificaciones que hacen falta para cobrar, y por qué cada Ambiente se verifica por su cuenta.