Autenticación

Todas las APIs de fiskaly utilizan autenticación basada en JWT. Esta guía cubre los diferentes patrones de autenticación según el producto.

Flujo de autenticación

API Key + Secret  →  POST /auth (o /tokens)  →  access_token + refresh_token
                                                       │
                                                       ├─ Usar en el encabezado Authorization
                                                       │
                                                       └─ En 401 → actualizar o re-autenticar

SIGN DE, SIGN AT, DSFINVK DE, RECEIPT

Estos productos utilizan un endpoint de autenticación sencillo:

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET"
  }'

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: "YOUR_API_KEY",
      api_secret: "YOUR_API_SECRET",
    }),
  }
);
const { access_token, refresh_token } = await response.json();

import requests

response = requests.post(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    json={"api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET"},
)
tokens = response.json()
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]

Respuesta

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token_expires_in": 172800
}

Campo	Descripción
`access_token`	Token JWT válido por 24 horas — incluir como `Authorization: Bearer <token>`
`refresh_token`	Token válido por 48 horas — usar para obtener un nuevo token de acceso

SIGN ES

SIGN ES envuelve la solicitud de autenticación en un sobre content:

curl -X POST https://test.es.sign.fiskaly.com/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "api_key": "YOUR_API_KEY",
      "api_secret": "YOUR_API_SECRET"
    }
  }'

const response = await fetch(
  "https://test.es.sign.fiskaly.com/api/v1/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      content: {
        api_key: "YOUR_API_KEY",
        api_secret: "YOUR_API_SECRET",
      },
    }),
  }
);
const { access_token } = await response.json();

response = requests.post(
    "https://test.es.sign.fiskaly.com/api/v1/auth",
    json={"content": {"api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET"}},
)
access_token = response.json()["access_token"]

SIGN IT, SIGN FR, E-Invoice

Estas APIs más recientes utilizan /tokens con el discriminador content.type y requieren encabezados adicionales:

curl -X POST https://test.api.fiskaly.com/tokens \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -d '{
    "content": {
      "type": "API_KEY",
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/tokens",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
    },
    body: JSON.stringify({
      content: {
        type: "API_KEY",
        key: "YOUR_API_KEY",
        secret: "YOUR_API_SECRET",
      },
    }),
  }
);
const { access_token } = await response.json();

response = requests.post(
    "https://test.api.fiskaly.com/tokens",
    headers={"X-Api-Version": "2026-02-03"},
    json={"content": {"type": "API_KEY", "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET"}},
)
access_token = response.json()["access_token"]

Autenticación con alcance

Para limitar las solicitudes a una organización UNIT específica, incluye el encabezado X-Scope-Identifier:

Authorization: Bearer <access_token>
X-Api-Version: 2026-02-03
X-Scope-Identifier: <organization_unit_id>

Actualización de token

Cuando el token de acceso expira, use el token de actualización en lugar de re-autenticarse con las credenciales:

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ refresh_token: refreshToken }),
  }
);
const { access_token } = await response.json();

response = requests.post(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    json={"refresh_token": refresh_token},
)
access_token = response.json()["access_token"]

Mejores prácticas

💡Almacene los tokens en caché

Los tokens de acceso son válidos por 24 horas. Almacene el token en caché y actualícelo solo al recibir respuestas 401. Re-autenticarse en cada solicitud desperdicia ~100ms por llamada.

⚠️Nunca exponga los secrets

Almacene los secrets de API en variables de entorno o un gestor de secrets
Nunca incluye secrets en el código fuente
Nunca incluye secrets en código del lado del cliente
Rote las API keys si un secret se ve comprometido

Estrategia recomendada para tokens

Autentíquese una vez al iniciar la aplicación
Almacene el access_token y refresh_token en memoria
En respuesta 401, intente actualizar usando el refresh_token
Si la actualización falla (token expirado), re-autentíquese con API key + secret
Si la re-autenticación falla, muestre el error al operador

Relacionados

URLs base y entornos

Todos los endpoints de API y detalles de entornos

Códigos de error

Códigos de error de autenticación y solución de problemas

Conceptos básicos

Organizaciones, entornos y modelo de recursos

Was this page helpful?