Autenticación (API Key)

Descripción

Todos los endpoints de esta documentación se autentican con una API Key. Es un mecanismo para integraciones servidor a servidor: envías tu clave en el header x-api-key en cada solicitud, sin login previo ni tokens que renovar.

Cada API Key pertenece a una organización de Orion. El servidor resuelve tu organización, tu saldo y tu catálogo a partir de la clave, así que no envías identificadores de cliente en ninguna petición.

---

Cómo se usa

GET /api/v1/tae/balance HTTP/1.1
Host: api-orion.example.com
x-api-key: ctc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

curl -s "$ORION_API/api/v1/tae/balance" \
  -H "x-api-key: $ORION_API_KEY"

Las claves tienen el formato ctc_ seguido de 43 caracteres (base64url).

---

Rotación recomendada

1. Crea una clave nueva con los mismos permisos.
2. Despliégala en tu sistema.
3. Verifica que tus peticiones funcionan con la nueva clave.
4. Revoca la clave anterior.

---

Límite de peticiones (rate limit)

Alcance	Límite	Ventana	Se cuenta por
Toda la API (/api/v1/*)	500 peticiones	1 minuto	IP de origen
POST /tae/do-transaction	1000 ventas	1 minuto	Organización (todas sus claves y usuarios)

Al superar un límite se recibe 429. Las respuestas incluyen los encabezados estándar RateLimit y RateLimit-Policy, por ejemplo:

RateLimit-Policy: 500;w=60
RateLimit: limit=500, remaining=487, reset=42

---

Respuestas de error de autenticación

Código HTTP	message	Causa
401	Token requerido	No se envió el header x-api-key.
401	API key inválida	La clave no existe, fue revocada o expiró.
403	Organización o canal API no disponible	Tu organización está suspendida o no tiene el canal API habilitado.
403	Permiso insuficiente	La clave no tiene el permiso que requiere el endpoint.
429	Rate-limit superado, debe esperar	Superaste el límite global de peticiones.

Ejemplo:

{
  "error": true,
  "message": "API key inválida",
  "data": [],
  "results": 0
}

---

Probar autenticación

Prueba tu clave contra el catálogo de productos (no genera cargos):

GEThttps://api.faxil.mx/api/v1/tae/productsEnviar

Ingresa tu x-api-key para validar el acceso.

Headers+ Agregar

×

×