Autenticación

Todas las solicitudes de API requieren autenticación a través del header HTTP X-SECRET-KEY:

La llave secreta determina la plataforma y el ambiente (producción o prueba). Sin X-ACCOUNT-ID, los requests operan sobre esa misma cuenta.

Empieza en Sandbox

Para una integración nueva, abre Configuración → Llaves API → Abrir Sandbox y elige Crear mi llave TEST. Sigue Primer pago de prueba. Las llaves TEST solo existen dentro de un Sandbox: tu cuenta de producción tiene únicamente llaves LIVE. GET /test devuelve environment (sandbox o live) y sandbox_id para confirmarlo. No necesitas llave pública.

Cuentas personales y comerciales

Las cuentas personales y comerciales pueden generar llaves TEST y LIVE desde Configuración → Llaves API. El Sandbox de arriba es para cuentas comerciales; una cuenta personal prueba con su llave TEST. Los administradores de la cuenta pueden gestionar las llaves; este cambio no concede acceso a otros roles del equipo.

Ambos tipos pueden ser la plataforma o una cuenta hija existente. Para conectar una cuenta personal existente, usa el enlace de invitación de la plataforma y selecciona explícitamente la cuenta personal. La plataforma utiliza su propia llave con X-ACCOUNT-ID; el destinatario no necesita compartir ni generar una llave.

El acceso a la API no cambia la verificación, los límites de procesamiento, la disponibilidad de cuotas ni los permisos de la llave para mover dinero. Admitir un tipo de cuenta no aprueba automáticamente el caso de uso de una plataforma.

Contexto de una cuenta conectada

Si la llave pertenece a una plataforma, agrega X-ACCOUNT-ID para ejecutar un request dentro de una hija conectada, de la misma forma que Stripe-Account en Stripe Connect:

curl https://app.recurrente.com/api/intents \
  -H "X-SECRET-KEY: sk_live_xyz789..." \
  -H "X-ACCOUNT-ID: ac_hija123"

La plataforma puede listar, consultar y administrar los recursos API que pertenecen a esa hija, sin importar si los creó la plataforma o la hija. El contexto cubre, entre otros, checkouts, clientes, productos, suscripciones, intents, payment intents, reembolsos, balances y transferencias.

Solo se aceptan hijas conectadas directamente a la cuenta dueña de la llave. El acceso no es transitivo hacia cuentas conectadas a la hija. Los endpoints bajo /connected_accounts siguen siendo operaciones de la plataforma y reciben el ID de la hija en el path. Los endpoints que ya aceptan account_id lo conservan como alias compatible. Las capacidades de la llave, la verificación de la cuenta y las restricciones de destinos para mover dinero siguen aplicando dentro del contexto conectado.

Llaves públicas y privadas

La llave privada (también llamada secreta) se envía en X-SECRET-KEY. Las integraciones anteriores usaban una llave pública en X-PUBLIC-KEY; la API actual ya no usa ese header para autenticar. Conserva la llave privada en tu servidor, nunca en código del navegador ni en un repositorio público.

Encontrar Tus Llaves

Para encontrar tus Llaves de API, dentro de tu cuenta de Recurrente, ve a:

Configuración → Llaves API.

1. Inicia sesión en el Panel de Recurrente
2. Ve a Configuración → Llaves API
3. Copia tu llave secreta. Solo se muestra completa al generarla o rotarla.

Producción y Sandbox

Cada cuenta tiene un solo ambiente, y todas sus llaves pertenecen a él:

• Llaves de producción (sk_live_) — Viven en tu cuenta de producción. Se procesan transacciones reales.
• Llaves de prueba (sk_test_) — Viven solo dentro de un Sandbox. No se mueve dinero real.

El endpoint de la API es el mismo para ambos. La llave secreta determina en qué ambiente estás operando.

Antes, las cuentas de producción también tenían una llave TEST propia. Esas llaves se retiraron: una llave sk_test_ que ya no existe responde 401 con un mensaje que te lleva al Sandbox. Los objetos de prueba (live_mode: false) que crearon siguen en la cuenta, pero una llave de producción nunca los lista ni los resuelve (404, o 401 en /customers).

Solicitud de Ejemplo

curl https://app.recurrente.com/api/test \
  -H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY"

Error en la autenticación

Si tus llaves de API no se están enviando o son inválidas, recibirás un código de respuesta HTTP 401 Unauthorized:

{
  "message": "Autenticación Errónea 👀",
  "errors": {
    "authentication": [
      "Las llaves de API son inválidas o no coinciden."
    ]
  }
}

Ambientes