Entornos y llaves · Compense Docs

El gateway tiene un solo contrato (las mismas rutas, cuerpos y errores) en todos sus despliegues. Lo que cambia entre “probar” y “operar” es la llave con la que llamas.

URL base por entorno #

Entorno	URL base	Python / JS / PHP	.NET	Go
Producción	`https://api.compense.co`	`"production"` (por defecto)	`CompenseEnvironment.Production`	`compense.Production`
Sandbox	`https://sandbox.dev.compense.co/gw`	`"sandbox"`	`CompenseEnvironment.Sandbox`	`compense.Sandbox`
Dev	`https://gateway.dev.compense.co`	`"dev"`	`CompenseEnvironment.Dev`	`compense.Dev`

Todas las rutas empiezan por /v1/gateway/..., así que la URL base nunca incluye /v1. La del sandbox conserva el prefijo /gw de la consola de sandbox: la ruta completa queda https://sandbox.dev.compense.co/gw/v1/gateway/health/.
Producción es la URL que declara el contrato. Aún no hay un despliegue productivo público: la URL definitiva se confirma en el onboarding. Si difiere, pásala como URL base propia (base_url, baseUrl, BaseUrl, WithBaseURL), que siempre gana sobre el entorno.
Dev es el gateway de desarrollo de Compense, útil para pruebas de punta a punta con webhooks reales (con una llave de producción emitida para dev).

La llave decide, no la URL #

Cada llave se emite con un environment:

Llave	Quién responde	Dinero	Webhooks	Simuladores `sandbox.*`
`sandbox`	El motor simulado, determinista: misma petición, misma respuesta.	Ninguno	Simulados (`"simulated": true`)	Permitidos
`prod`	El motor real de tu entidad.	Real	Entregas HTTP firmadas reales	`403`

Una llave de sandbox recibe respuestas simuladas en cualquier URL a la que llames, y una de producción llega al motor real. Por eso un error de configuración (apuntar a la URL de sandbox con una llave de producción) no te protege: separa las llaves por entorno en tu gestor de secretos y en tu CI.

flowchart TD
  R[Tu petición<br/>X-API-Key: cmp_...] --> G{Entorno<br/>de la llave}
  G -- sandbox --> S[Motor simulado<br/>determinista, sin dinero]
  G -- prod --> M[Motor real del tenant]
  S --> E[Mismo contrato:<br/>rutas, sobre y errores]
  M --> E

Lo que el sandbox no simula

La consulta, el cruce y la carga de afiliados leen y escriben el registro real del tenant con cualquier llave. Revisa la tabla de datos de prueba antes de diseñar tus pruebas automatizadas.

Elegir el entorno en el código #

from compense_gateway import CompenseClient

sandbox = CompenseClient(api_key=SANDBOX_KEY, environment="sandbox")
dev = CompenseClient(api_key=DEV_KEY, environment="dev")
prod = CompenseClient(api_key=PROD_KEY)  # "production" es el valor por defecto
otro = CompenseClient(api_key=PROD_KEY, base_url="https://gateway.horizonte.example")

import { CompenseClient } from "@compense/sdk";

const sandbox = new CompenseClient({ apiKey: SANDBOX_KEY, environment: "sandbox" });
const dev = new CompenseClient({ apiKey: DEV_KEY, environment: "dev" });
const prod = new CompenseClient({ apiKey: PROD_KEY }); // "production" por defecto
const otro = new CompenseClient({ apiKey: PROD_KEY, baseUrl: "https://gateway.horizonte.example" });

use Compense\Sdk\CompenseClient;

$sandbox = new CompenseClient(apiKey: $sandboxKey, environment: 'sandbox');
$dev = new CompenseClient(apiKey: $devKey, environment: 'dev');
$prod = new CompenseClient(apiKey: $prodKey); // 'production' por defecto
$otro = new CompenseClient(apiKey: $prodKey, baseUrl: 'https://gateway.horizonte.example');

var sandbox = new CompenseClient(sandboxKey, CompenseEnvironment.Sandbox);
var dev = new CompenseClient(devKey, CompenseEnvironment.Dev);
var prod = new CompenseClient(prodKey, CompenseEnvironment.Production);
var otro = new CompenseClient(new CompenseClientOptions
{
    ApiKey = prodKey,
    BaseUrl = "https://gateway.horizonte.example",
});

sandbox, _ := compense.NewClient(sandboxKey, compense.WithEnvironment(compense.Sandbox))
dev, _ := compense.NewClient(devKey, compense.WithEnvironment(compense.Dev))
prod, _ := compense.NewClient(prodKey) // Production por defecto
otro, _ := compense.NewClient(prodKey, compense.WithBaseURL("https://gateway.horizonte.example"))

curl https://sandbox.dev.compense.co/gw/v1/gateway/health/ -H "X-API-Key: $SANDBOX_KEY"
curl https://gateway.dev.compense.co/v1/gateway/health/ -H "X-API-Key: $DEV_KEY"
curl https://api.compense.co/v1/gateway/health/ -H "X-API-Key: $PROD_KEY"

Del sandbox a producción #

Integra y automatiza tus pruebas contra el sandbox (créditos, billetera, cartera, webhooks simulados, relojes y simuladores).
Prueba de punta a punta en dev con webhooks reales hacia una URL HTTPS pública de tu ambiente de pruebas.
Pide la llave de producción y la URL definitiva en el onboarding; crea tus endpoints de webhooks de producción (el secreto es distinto) y despliega.
Monitorea con client.system.health() y alerta sobre 401/403, 429 y 5xx.