Autenticación

Dos formas de autenticarse con la API de Vecnet — la llave de API de tu comercio para integraciones y el JWT de operador para el panel.

La API de Vecnet acepta dos esquemas de autenticación. Elige el que corresponde a quién hace la petición.

Llave de API del comercio

El checkout alojado, las ligas de pago y las integraciones servidor a servidor usan una llave vk_….

JWT de operador

Los usuarios del panel inician sesión y envían un token Bearer.

Quién llama	Encabezado	Dónde se usa
Tu integración (llave de API)	`Authorization: Token <llave>` o `X-API-Key: <llave>`	Checkout alojado, ligas de pago y llamadas servidor a servidor.
Un operador del panel (JWT)	`Authorization: Bearer <jwt>` + `X-Merchant-Id: mrc_…`	Recursos administrativos desde el panel.

La única ruta que no necesita autenticación es la verificación de estado:

curl https://api.vecnet.io/health

1. Llave de API del comercio (integraciones)

Las integraciones servidor a servidor y el flujo de checkout alojado se autentican con una llave de API del comercio (vk_live_… en producción, vk_test_… en sandbox). Se aceptan dos formas de encabezado; usa la que mejor encaje con tu stack. La forma Authorization: Token es la que esperan los endpoints de checkout alojado.

# Esquema Token
curl https://api.vecnet.io/checkout/v1/sessions/cs_a1b2c3d4e5 \
  -H "Authorization: Token vk_live_1a2b3c4d5e6f7a8b9c0d"

# Esquema X-API-Key
curl https://api.vecnet.io/checkout/v1/sessions/cs_a1b2c3d4e5 \
  -H "X-API-Key: vk_live_1a2b3c4d5e6f7a8b9c0d"

Crear una llave

Crea una llave desde el panel o con POST /api/api-keys. El valor en claro se devuelve una sola vez, al crearla: guárdalo de inmediato, porque no se puede recuperar después.

curl -X POST https://api.vecnet.io/api/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Merchant-Id: mrc_3f9a2c1b" \
  -H "Content-Type: application/json" \
  -d '{"name": "checkout-prod"}'

{
  "id": "key_4f0c1a9b",
  "name": "checkout-prod",
  "key": "vk_live_1a2b3c4d5e6f7a8b9c0d",
  "merchant_id": "mrc_3f9a2c1b"
}

El campo key (vk_live_…) solo aparece en esta respuesta de creación. Si lo pierdes, crea una llave nueva. Ten en cuenta que key_… es el ID del registro de la llave, mientras que vk_live_… es el secreto que envías.

2. JWT de operador (panel)

Los usuarios del panel inician sesión y envían el JWT resultante como token Bearer. El servidor verifica el token y resuelve al usuario.

curl https://api.vecnet.io/api/transactions \
  -H "Authorization: Bearer <jwt>"

Roles

Hay dos categorías de usuario:

Categoría	Alcance
Operador	Trabaja a través de varios comercios desde el panel.
Usuario de comercio (`client`)	Anclado únicamente a su propio comercio.

Un usuario de comercio está anclado a la organización a la que pertenece: no puede leer ni escribir datos de otro comercio.

Alcance por comercio para operadores

Como los operadores trabajan a través de varios comercios, deben indicarle a la API a qué comercio apunta cada petición. Pasa el ID del comercio en el encabezado X-Merchant-Id (o en el parámetro de consulta merchant_id) en los recursos del comercio.

curl https://api.vecnet.io/api/transactions \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Merchant-Id: mrc_3f9a2c1b"

La forma con parámetro de consulta es equivalente:

curl "https://api.vecnet.io/api/transactions?merchant_id=mrc_3f9a2c1b" \
  -H "Authorization: Bearer <jwt>"

Los usuarios de comercio nunca envían X-Merchant-Id: ya están anclados a su propio comercio y el valor se ignora. El encabezado solo importa para operadores.

Errores

Las fallas de autenticación devuelven un objeto JSON con un solo campo error.

{
  "error": "unauthorized"
}

Códigos de estado comunes:

401: credenciales faltantes o inválidas.
403: autenticado, pero sin permiso (por ejemplo, un usuario de comercio intentando alcanzar otro comercio).

Las llaves de API (vk_…) y los secretos de firma de webhooks (whsec_…) son secretos. Nunca los expongas en código del navegador, los subas a un repositorio ni los escribas en logs. Si una llave se filtra, rótala de inmediato.