Autenticación

La API de Semantico autentica las peticiones con un bearer token en la cabecera Authorization:

Authorization: Bearer <token>

Hay dos tipos de token. Para integraciones, scripts y acceso entre servidores, usa un token de API de larga duración. Para sesiones interactivas, usa un JWT estándar obtenido al iniciar sesión.

Tokens de API (recomendados para integraciones)

Un token de API es una credencial de larga duración, sin caducidad, asociada a tu espacio de trabajo.

• Acceso completo a los endpoints de productos de tu espacio de trabajo.
• Sin caducidad: sigue siendo válido hasta que se revoque.
• Revocable en cualquier momento.

Obtener un token

Los tokens de API los emite Semantico. Ponte en contacto con tu gestor de cuenta o con soporte para solicitar uno. Por seguridad, el valor completo del token solo se muestra una vez, al crearlo: guárdalo en un lugar seguro de inmediato.

Usar un token

Envíalo como bearer token en cada petición:

# List products
curl -H "Authorization: Bearer <your-api-token>" \
  https://api.semantico.ai/api/v1/products/

# Create a product
curl -X POST \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"sku": "PROD-123"}' \
  "https://api.semantico.ai/api/v1/products/?locale=en-US"

En Python:

import requests

API_TOKEN = "<your-api-token>"
BASE_URL = "https://api.semantico.ai/api/v1"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json",
}

# Get products
products = requests.get(f"{BASE_URL}/products/", headers=headers).json()

# Create a product
data = {"sku": "NEW-SKU", "name": "Acme water bottle 750ml"}
response = requests.post(f"{BASE_URL}/products/", json=data, headers=headers)

Mantener los tokens a salvo

• Guarda los tokens en variables de entorno o en un gestor de secretos, nunca en el control de versiones.
• Usa siempre HTTPS.
• Si un token queda expuesto, pídenos que lo revoquemos de inmediato y que emitamos uno nuevo.
• Solicita tokens con el acceso mínimo que necesite tu integración.

Tokens de inicio de sesión (JWT)

Si trabajas con una sesión interactiva en lugar de una integración de servidor, puedes obtener un JWT de corta duración iniciando sesión con las credenciales de un usuario.

Inicia sesión para recibir un token access y un token refresh:

POST /api/v1/login/
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Usa el token access como bearer token. Los tokens de acceso son válidos durante 7 días; cuando uno caduque, intercambia el token refresh (válido durante 14 días) por un nuevo token de acceso:

POST /api/v1/refresh/
Content-Type: application/json

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Para la mayoría de las integraciones, un token de API de larga duración es más sencillo y es la opción recomendada.