Autenticación

Flujo de Autenticación

El API de Zynvo utiliza un sistema de autenticación de dos pasos:

API Key: Identifica tu cuenta de desarrollador
JWT Token: Proporciona acceso temporal a los recursos

Obtener tus API Keys

Zynvo proporciona dos API Keys separadas para cada desarrollador:

Sandbox API Key: Para desarrollo y pruebas
Production API Key: Para operaciones en producción

Las API Keys son específicas del ambiente. No puedes usar una API Key de sandbox en producción ni viceversa.

Cómo obtenerlas:

Inicia sesión en el Dashboard de Zynvo
Navega a Configuración → API Keys
Verás dos secciones:
- Sandbox API Key: Para pruebas
- Production API Key: Para producción
Copia cada key de forma segura (solo se muestra una vez)

Mantén tus API Keys seguras y nunca las compartas públicamente. Trata tus keys como contraseñas.

Paso 1: Obtener un JWT Token

Antes de usar cualquier endpoint, debes obtener un JWT token temporal usando tu API Key:

curl -X POST https://api.zynvo.uy/v1/tokens \
  -H "X-API-Key: tu_sandbox_api_key" \
  -H "X-Sandbox-Mode: true"

curl -X POST https://api.zynvo.uy/v1/tokens \
  -H "X-API-Key: tu_production_api_key" \
  -H "X-Sandbox-Mode: false"

const response = await fetch('https://api.zynvo.uy/v1/tokens', {
  method: 'POST',
  headers: {
    'X-API-Key': 'tu_sandbox_api_key',
    'X-Sandbox-Mode': 'true'
  }
});

const { data } = await response.json();
const accessToken = data.access_token;

import requests

response = requests.post(
    'https://api.zynvo.uy/v1/tokens',
    headers={
        'X-API-Key': 'tu_sandbox_api_key',
        'X-Sandbox-Mode': 'true'
    }
)

data = response.json()['data']
access_token = data['access_token']

Response:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

El token expira en 1 hora (3600 segundos) por defecto.

Paso 2: Usar el Token en Requests

Incluye el token JWT y la API Key en cada solicitud:

curl https://api.zynvo.uy/v1/enterprises/210000000018 \
  -H "X-API-Key: tu_sandbox_api_key" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Sandbox-Mode: true"

const response = await fetch(
  'https://api.zynvo.uy/v1/enterprises/210000000018',
  {
    headers: {
      'X-API-Key': 'tu_sandbox_api_key',
      'Authorization': `Bearer ${accessToken}`,
      'X-Sandbox-Mode': 'true'
    }
  }
);

response = requests.get(
    'https://api.zynvo.uy/v1/enterprises/210000000018',
    headers={
        'X-API-Key': 'tu_sandbox_api_key',
        'Authorization': f'Bearer {access_token}',
        'X-Sandbox-Mode': 'true'
    }
)

Headers Requeridos

Header	Descripción
`X-API-Key`	Tu API Key (sandbox o production)
`Authorization`	JWT token en formato `Bearer {token}`
`X-Sandbox-Mode`	`true` para sandbox, `false` o ausente para production

El ambiente del header X-Sandbox-Mode DEBE coincidir con el ambiente de tu API Key. Si usas una API Key de sandbox, debes enviar X-Sandbox-Mode: true.

Errores de Autenticación

401 Unauthorized

Si el token no es válido o está ausente:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token de autenticación inválido o ausente"
  }
}

403 Forbidden

Si el token es válido pero no tiene permisos para acceder al recurso:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "No tienes permisos para acceder a este recurso"
  }
}

Mejores Prácticas

Rota tus tokens regularmente

Por seguridad, genera nuevos tokens periódicamente y elimina los antiguos desde el dashboard.

Usa variables de entorno

Almacena tu token en variables de entorno, nunca en el código fuente.

export ZYNVO_API_TOKEN="tu_token_de_api"

Tokens por ambiente

Usa diferentes tokens para desarrollo, staging y producción.

Monitorea el uso

Revisa regularmente los logs de uso de tu token en el dashboard para detectar actividad inusual.

Bienvenida

Recursos

Guías

Flujo de Autenticación

Obtener tus API Keys

Cómo obtenerlas:

Paso 1: Obtener un JWT Token

Paso 2: Usar el Token en Requests

Headers Requeridos

Errores de Autenticación

401 Unauthorized

403 Forbidden

Mejores Prácticas

​Flujo de Autenticación

​Obtener tus API Keys

​Cómo obtenerlas:

​Paso 1: Obtener un JWT Token

​Paso 2: Usar el Token en Requests

​Headers Requeridos

​Errores de Autenticación

​401 Unauthorized

​403 Forbidden

​Mejores Prácticas

Flujo de Autenticación

Obtener tus API Keys

Cómo obtenerlas:

Paso 1: Obtener un JWT Token

Paso 2: Usar el Token en Requests

Headers Requeridos

Errores de Autenticación

401 Unauthorized

403 Forbidden

Mejores Prácticas