Autenticación

La API de Gestiono utiliza autenticación basada en API key para asegurar el acceso a los datos de tu organización. Esta guía cubre todo lo que necesitas saber para autenticar tus solicitudes.

Autenticación con API Key Firmada

Todas las solicitudes deben ser firmadas usando tu par de claves API (pública y privada). La API utiliza firmas HMAC-SHA256 para asegurar la autenticidad de las solicitudes y prevenir manipulación.

Encabezados requeridos

Incluye estos encabezados en cada solicitud:

bash

X-Bitnation-Apikey: TU_CLAVE_PUBLICA
Authorization: FIRMA_CALCULADA
Content-Type: application/json
X-Bitnation-Organization-Id: TU_ID_ORGANIZACION

Proceso de firmado de solicitudes

Preparar datos de solicitud: Combinar todos los parámetros (query y body)
Agregar timestamp y ventana: Incluir timestamp (tiempo actual en ms) y recvWindow opcional (por defecto: 60000ms)
Crear cadena de datos: Convertir los datos combinados a string JSON
Generar firma: Crear hash HMAC-SHA256 usando tu clave privada
Incluir firma: Agregar la firma al encabezado Authorization

Timestamp y ventana de recepción

timestamp: Tiempo actual en milisegundos (requerido)
recvWindow: Edad máxima de solicitud en milisegundos (opcional, por defecto: 60000, máximo: 60000)
Las solicitudes más antiguas que la ventana de recepción serán rechazadas

Obtener tu Par de Claves API

Paso 1: Acceder al panel

Inicia sesión en tu panel de Gestiono
Ve a Configuración → Acceso a API → Automatizaciones
Haz clic en Generar nuevo API Key

Paso 2: Almacenamiento seguro

Copia tanto tu clave pública como privada inmediatamente (la clave privada no se mostrará de nuevo)
Guárdalas de forma segura en la configuración de tu aplicación
Nunca expongas claves privadas en código cliente o repositorios públicos
La clave pública se usa en encabezados, la clave privada se usa para firmar

Las claves API están asociadas con una organización específica. El contexto de organización se determina automáticamente desde tu clave API, pero también puedes especificarlo explícitamente usando el encabezado X-Bitnation-Organization-Id.

Contexto de usuario (Opcional)

Puedes especificar qué usuario debe ejecutar la solicitud usando el encabezado X-Bitnation-User-Email. Si no se proporciona, la solicitud usará el usuario asociado con la clave API.

Buenas prácticas de seguridad

Mantén tus API keys en secreto — Nunca subas API keys al control de versiones; usa variables de entorno; rota las claves periódicamente.
Usa solo HTTPS — Todas las solicitudes deben usar HTTPS.
Implementa manejo de errores adecuado — Maneja los errores de autenticación correctamente; implementa reintentos ante fallos temporales.

Próximos pasos

Una vez configurada la autenticación:

Explora conceptos clave — Modelo de datos de Gestiono
Revisa la referencia — Endpoints disponibles
Prueba ejemplos — Implementaciones prácticas