Autenticación de la API: documentación de CheckoutOS

La API de CheckoutOS usa claves de API para autenticar. Esta guía explica cómo generar claves, autenticar solicitudes y gestionar el acceso de forma segura.

Claves de API

Las claves autentican todas las solicitudes a la API de CheckoutOS. Cada clave pertenece a tu tienda y tiene permisos configurables.

Generar claves de API

Ir a configuración

Ve a CheckoutOS → Settings → API.

Crear una clave

Haz clic en “Create API Key”.

Nombrar la clave

Ponle un nombre descriptivo, como “Servidor de producción”.

Fijar permisos

Elige a qué ámbitos de la API puede acceder.

Copiar la clave

Cópiala de inmediato: no volverá a mostrarse.

Seguridad de las claves

Las claves solo se muestran una vez al crearlas. Guárdalas de forma segura. Si las pierdes, tendrás que generar una nueva.

Métodos de autenticación

Token Bearer, recomendado

Incluye la clave como token Bearer en la cabecera Authorization:

Autenticación con token Bearer

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Cabecera X-API-Key

También puedes usar la cabecera X-API-Key:

Autenticación con X-API-Key

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Permisos de API

Puedes limitar las claves a permisos específicos:

Ámbitos disponibles

{
  "scopes": {
    "read:upsells": "View upsell configurations",
    "write:upsells": "Create and modify upsells",
    "read:bundles": "View bundle configurations",
    "write:bundles": "Create and modify bundles",
    "read:analytics": "Access analytics data",
    "read:orders": "View order data",
    "write:orders": "Modify orders (edits)",
    "read:settings": "View CheckoutOS settings",
    "write:settings": "Modify settings",
    "webhooks:manage": "Create and manage webhooks"
  }
}

Privilegio mínimo

Concede solo los permisos que necesite la integración. Una clave para paneles analíticos no debería poder modificar ventas adicionales.

Límites de solicitudes

Las solicitudes se limitan para asegurar un uso equitativo:

Límites de solicitudes

{
  "rate_limits": {
    "requests_per_minute": 120,
    "requests_per_hour": 3600,
    "burst_limit": 20
  },
  "headers": {
    "X-RateLimit-Limit": "120",
    "X-RateLimit-Remaining": "115",
    "X-RateLimit-Reset": "1640000000"
  }
}

Si alcanzas el límite, recibirás una respuesta 429:

Respuesta por límite alcanzado

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}

Entornos

CheckoutOS ofrece entornos separados de desarrollo y producción:

Entornos de API

{
  "production": {
    "base_url": "https://api.chargezen.com/v1",
    "key_prefix": "live_"
  },
  "sandbox": {
    "base_url": "https://sandbox.api.chargezen.com/v1",
    "key_prefix": "test_"
  }
}

Entorno de pruebas

Usa el entorno de pruebas para desarrollar y probar. Sus datos están separados de producción y se pueden restablecer en cualquier momento.

SDK oficiales

Los SDK oficiales gestionan automáticamente la autenticación:

SDK de Node.js

import { CheckoutOS } from '@chargezen/checkoutos-sdk';

const client = new CheckoutOS({
  apiKey: process.env.CHARGEZEN_API_KEY,
  environment: 'production'
});

const upsells = await client.upsells.list();

SDK de Python

from chargezen import CheckoutOS

client = CheckoutOS(
    api_key=os.environ['CHARGEZEN_API_KEY'],
    environment='production'
)

upsells = client.upsells.list()

Gestionar claves

Buenas prácticas

Usa variables de entorno — Nunca escribas las claves directamente en el código
Rota las claves regularmente — Al menos cada trimestre
Usa claves distintas por entorno — Desarrollo, preproducción y producción
Revoca claves sin uso — Elimina las que ya no necesitas
Supervisa el uso — Busca patrones anómalos
Usa ámbitos mínimos — Concede solo los permisos necesarios

Revocar claves

Ir a configuración de la API

Ve a CheckoutOS → Settings → API.

Encontrar la clave

Localiza la clave que quieres revocar.

Revocar

Haz clic en “Revoke” y confirma.

Efecto inmediato

La revocación es inmediata. Cualquier solicitud con esa clave fallará. Actualiza tus aplicaciones antes de revocarla.

Referencia de la API

Endpoints de la API

Endpoints disponibles

Más información

Webhooks

Notificaciones de eventos en tiempo real

Más información