Quick Start

fiskaly proporciona APIs de cumplimiento fiscal en toda Europa. Elige su país a continuación para saltar directamente a la guía de integración, o desplázate hacia abajo para ver un ejemplo práctico de SIGN DE.

Elige su país

Live

Alemania(SIGN DE)

KassenSichV — TSS, Client, Transaction

Live

Austria(SIGN AT)

RKSV — SCU, Cash Register, Receipt

Live

Francia(SIGN FR)

NF 525 — Organization, System, Record

Live

Italia(SIGN IT)

Cumplimiento RT — Taxpayer, Location, System, Record

Live

España(SIGN ES)

TicketBAI y Verifactu — Taxpayer, Signer, Invoice

Live

Portugal(SIGN PT)

AT — Taxpayer, System, Document

Live

Bélgica(E-Invoice)

Facturación electrónica B2B Peppol a través de la API Unificada

Live

Suecia(SIGN SE)

InfraSec TCS — códigos de control basados en certificados

💡¿Despliegue multi-país?

Francia, Italia y Bélgica comparten la API Unificada — una integración cubre las tres. Consulta Planificación de integración para estimaciones de esfuerzo y cronogramas de despliegue.

Práctica: SIGN DE en 5 minutos

El siguiente ejemplo usa Alemania (SIGN DE) como ejemplo concreto. El flujo es: autenticar → crear un TSS → firmar una transacción.

📘Este ejemplo usa la API Especializada de SIGN DE

Alemania, Austria y España tienen cada una una API Especializada dedicada. Francia e Italia usan la API Unificada con un modelo de recursos compartido. Elige su país arriba para la guía correcta.

Tiempo de realización: ~5 minutos con cURL, ~15 minutos si lo está incorporando en código de aplicación.

Requisitos previos

Necesita tres cosas antes de empezar:

Una cuenta de fiskaly — regístrese gratis en hub.fiskaly.com
Credenciales de API — genera un API Key y un secret en el HUB bajo tu organización
Un cliente HTTP — cURL, Postman o la biblioteca HTTP de su lenguaje

⚠️Tu API Secret se muestra solo una vez

Copia el secret inmediatamente cuando se genera. Si lo pierde, tendrá que generar un nuevo par de claves. Almacene las credenciales en variables de entorno o un gestor de secrets — nunca en el control de código fuente.

Entorno

Esta guía usa el entorno sandbox (TEST). Todas las nuevas organizaciones comienzan aquí. No se crean datos fiscales reales y no se te facturará.

	Sandbox (TEST)	Producción (LIVE)
URL base	`https://kassensichv-middleware.fiskaly.com/api/v2`	`https://kassensichv.fiskaly.com/api/v2`
Datos	Efímeros — seguro para experimentar	Permanentes — relevantes para auditoría
Facturación	Gratuito	Por contrato
Cambio	Predeterminado para nuevas orgs	Habilitar a través del HUB

Paso 1: Autenticar

Intercambia tu API Key y secret por un token Bearer.

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",
    },
)

data = response.json()
access_token = data["access_token"]
refresh_token = data["refresh_token"]

Respuesta esperada (200 OK):

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

El access_token es válido durante 24 horas. El refresh_token es válido durante 48 horas. Incluye el token de acceso como Authorization: Bearer <token> en todas las solicitudes posteriores.

💡No vuelvas a autenticarte en cada solicitud

Almacene el token en caché y solo renuévelo cuando reciba una respuesta 401. Volver a autenticarse por solicitud añade latencia innecesaria a su flujo de pago.

Paso 2: Crear e inicializar un TSS

Un TSS (Technical Security System) es el recurso de firma certificado. Necesita uno por ubicación física. Crear un TSS implica tres subpasos: crear, establecer el PIN de administrador e inicializar.

a) Crear el TSS

TSS_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Mi primer TSS"
  }'

const tssId = crypto.randomUUID();

const tssResponse = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "My first TSS",
    }),
  }
);

const tss = await tssResponse.json();
// Guarda tss.admin_puk — lo necesita para establecer el PIN de administrador

Respuesta esperada (200 OK) — note el campo admin_puk:

{
  "_id": "a1b2c3d4-...",
  "description": "My first TSS",
  "state": "UNINITIALIZED",
  "admin_puk": "123456"
}

b) Establecer el PIN de administrador (usando el admin_puk de la respuesta anterior):

curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "admin_puk": "123456",
    "new_admin_pin": "your-secure-admin-pin"
  }'

c) Autenticarse como administrador e inicializar:

# Autenticarse como administrador
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/auth" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "admin_pin": "your-secure-admin-pin" }'

# Inicializar el TSS
curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "state": "INITIALIZED" }'

Tras la inicialización, el state del TSS cambia a INITIALIZED. Ya puede crear clientes y firmar transacciones.

Paso 3: Crear un cliente

Un cliente representa un único terminal POS o instancia de aplicación conectada al TSS.

CLIENT_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/client/${CLIENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "serial_number": "POS-001" }'

Paso 4: Firmar una transacción

Las transacciones tienen un ciclo de vida: iniciar (estado ACTIVE) y luego finalizar (estado FINISHED). La respuesta de finalización contiene la firma criptográfica.

a) Iniciar la transacción:

TX_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "ACTIVE",
    "client_id": "YOUR_CLIENT_ID"
  }'

b) Finalizar la transacción (aquí es donde se genera la firma):

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "FINISHED",
    "client_id": "YOUR_CLIENT_ID",
    "schema": {
      "standard_v1": {
        "receipt": {
          "receipt_type": "RECEIPT",
          "amounts_per_vat_rate": [
            { "vat_rate": "NORMAL", "amount": "10.00" }
          ],
          "amounts_per_payment_type": [
            { "payment_type": "CASH", "amount": "10.00" }
          ]
        }
      }
    }
  }'

Respuesta esperada (200 OK) — los campos clave son signature y qr_code_data:

{
  "_id": "tx-uuid-...",
  "state": "FINISHED",
  "number": 1,
  "time_start": 1700000000,
  "time_end": 1700000001,
  "signature": {
    "value": "dGVzdC1zaWduYXR1cmU=",
    "algorithm": "ecdsa-plain-SHA384",
    "counter": 1,
    "public_key": "BHHz..."
  },
  "qr_code_data": "V0;TSS-ID;TX-NUMBER;..."
}

La cadena qr_code_data es lo que codifica en el código QR impreso en el recibo.

Paso 5: Cerrar sesión del administrador

Tras completar la configuración, cierra la sesión del administrador del TSS:

curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Errores comunes la primera vez

Error	Causa	Solución
`401 Unauthorized`	Token caducado o incorrecto	Vuelve a autenticarte con `/auth`. Verifica que usa la API Key correcta para este entorno.
`400 E_TSS_NOT_INITIALIZED`	Intentó crear un cliente o transacción en un TSS no inicializado	Completa los tres pasos de configuración del TSS: crear, establecer PIN de administrador, inicializar.
`400` con error “admin_puk”	PUK incorrecto al establecer el PIN de administrador	Use el valor `admin_puk` de la respuesta de creación del TSS, no un valor que elegiste.
`409 Conflict`	Reutilizó un UUID que ya existe	Genera un nuevo UUID para cada recurso (TSS, cliente, transacción).
`422 E_TX_INVALID_STATE`	Intentó finalizar una transacción que no está `ACTIVE`	Inicie primero la transacción (revisión 1 con `state: ACTIVE`), luego finalice (revisión 2).

Para la referencia completa de errores, consulta Códigos de error.

Qué construir a continuación

Guía completa de SIGN DE

Configuración completa incluyendo jerarquía de organizaciones, aprovisionamiento en producción y códigos QR del recibo

Manejo de errores

Estrategia de tiempo de espera, lógica de reintentos y qué hacer cuando el TSS no está disponible

Integración de DSFinV-K

Obligatorio para Alemania: genera exportaciones de datos fiscales conformes para auditorías

Referencia de API

Documentación completa de endpoints, todas las URLs base de productos y límites de velocidad

Expandir a otro país

Qué cambia cuando añade Austria, Francia, España, Italia o Suecia

Planificación de integración (PMs)

Estimaciones de esfuerzo, listas de verificación de cumplimiento y cronogramas de despliegue

Was this page helpful?