Section navigation

Referencia de API

Esta página es la referencia central para todos los endpoints, URLs base, autenticación y límites de velocidad de la API de fiskaly. Úsala como punto de partida para cualquier integración de producto.

fiskaly proporciona dos arquitecturas de API. Consulta La Unified API para la comparación completa.

Unified API

La Unified API utiliza URLs base compartidas y un modelo de recursos común entre países. Actualmente cubre SIGN FR, SIGN IT, SIGN PT, SIGN SE y SIGN CZ (preview).

	Detalles
URL base TEST	`https://test.api.fiskaly.com`
URL base LIVE	`https://live.api.fiskaly.com`
Headers requeridos	`X-Api-Version` (fecha, p. ej. `2026-02-03`), `X-Idempotency-Key` (UUID, en POST/PATCH), `X-Scope-Identifier` (alcance de recursos)
IDs de recursos	Generados por el servidor (usa `X-Idempotency-Key` para idempotencia)
Gestión de org.	Integrada en la API del producto (sin Management API separada)

Producto	Última versión de API	Docs
SIGN FR	2026-06-01	Docs
SIGN IT	2026-06-01	Docs
SIGN PT	2026-06-01	Docs
SIGN SE	2026-06-01	Docs actuales
SIGN CZ (preview)	2026-06-01	Docs

APIs especializadas

Cada API especializada tiene su propia URL base y modelo de recursos, diseñada para un país específico. Utiliza la Management API para la gestión de organizaciones.

Producto	Versión API	URL base (TEST)	URL base (LIVE)	Docs
SIGN DE	v2	`kassensichv-middleware.fiskaly.com/api/v2`	`kassensichv.fiskaly.com/api/v2`	Docs interactivos
SIGN AT	v1	`rksv-middleware.fiskaly.com/api/v1`	`rksv.fiskaly.com/api/v1`	Docs
SIGN ES	v1	Contactar a fiskaly para endpoints	Contactar a fiskaly para endpoints	Docs
Management	v0	`dashboard.fiskaly.com/api/v0`	`dashboard.fiskaly.com/api/v0`	Docs interactivos

APIs de productos complementarios

Estos productos trabajan junto a SIGN y no están vinculados a una arquitectura de API específica:

Producto	URL base (TEST)	URL base (LIVE)	Docs
DSFinV-K (Alemania)	`dsfinvk-middleware.fiskaly.com/api/v1`	`dsfinvk.fiskaly.com/api/v1`	Docs
SUBMIT DE (Alemania)	A través del middleware SIGN DE	A través de producción SIGN DE	Docs
SAFE	Contactar a fiskaly para endpoints	Contactar a fiskaly para endpoints	Docs
E-Invoice	Contactar a fiskaly para endpoints	Contactar a fiskaly para endpoints	Docs
eReceipt	`receipt.fiskaly.com/api/v1`	`receipt.fiskaly.com/api/v1`	Docs interactivos

📘Disponibilidad de endpoints

Algunos productos más nuevos aún no han publicado públicamente sus URLs base. Contacta a tu gestor de cuenta o sales@fiskaly.com para acceder a los endpoints de SIGN FR, SIGN ES, SIGN IT, SIGN PT, SIGN CZ, SAFE y E-Invoice.

Autenticación

Todas las APIs de fiskaly utilizan el mismo patrón de autenticación con Bearer token:

POST /auth con tu api_key y api_secret
Recibe un access_token (24h) y un refresh_token (48h)
Incluye el token como Authorization: Bearer <token> en todas las solicitudes posteriores
Ante un 401, vuelve a autenticarte — no reintentes con el mismo token expirado

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 } = await response.json();

Luego incluye el token en las solicitudes posteriores:

curl -X GET https://kassensichv-middleware.fiskaly.com/api/v2/tss \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

⚠️Mantén tus secrets seguros

Nunca confirmes API secrets en el control de versiones ni los expongas en código del lado del cliente. Almacénalos en variables de entorno o en un gestor de secrets.

💡Cachea tu token

El access token es válido durante 24 horas. Volver a autenticarse en cada solicitud añade latencia innecesaria. Cachea el token y solo renuévalo ante un 401.

Entornos

Cada producto tiene un entorno TEST (sandbox) y un entorno LIVE (producción):

	TEST (Sandbox)	LIVE (Producción)
Propósito	Desarrollo y pruebas de integración	Transacciones reales, datos relevantes para auditoría
Datos	Efímeros — seguro para experimentar, puede restablecerse	Permanentes — registros legalmente vinculantes
Facturación	Gratuito	Por contrato
Por defecto	Todas las organizaciones nuevas empiezan aquí	Activar via HUB
Prefijo URL base	Normalmente incluye `middleware`	Dominio directo del producto

⚠️TEST y LIVE están separados

Los recursos creados en TEST no existen en LIVE. Al pasar a producción, debes re-provisionar todos los recursos (TSS, clientes, signing units, etc.).

Límites de velocidad

Los límites de velocidad de la API varían según el producto y el plan de suscripción. Pautas generales:

Operación	Límite típico	Notas
Autenticación	10 req/min	Cachea tokens — no autentiques por transacción
Firma de transacciones	200 req/min	No debería ser un cuello de botella para el pago normal
Generación de exports	Límites más bajos	Operaciones pesadas — usa polling asíncrono
Operaciones de gestión	60 req/min	Gestión de organizaciones/API keys

Headers de límites de velocidad

Cada respuesta de API incluye headers para ayudarte a gestionar tu presupuesto de solicitudes:

Header	Descripción
`X-RateLimit-Limit`	Máximo de solicitudes permitidas en la ventana actual
`X-RateLimit-Remaining`	Solicitudes restantes en la ventana actual
`X-RateLimit-Reset`	Timestamp Unix cuando se reinicia la ventana del límite
`Retry-After`	Segundos a esperar antes de reintentar (solo en respuestas 429)

Si recibes un 429 Too Many Requests, espera con retraso exponencial. Consulta la estrategia de reintento para orientación de implementación.

Para límites empresariales o necesidades personalizadas, contacta a tu gestor de cuenta.

Paginación

Las APIs de fiskaly utilizan dos patrones de paginación diferentes según la arquitectura de API.

APIs especializadas (SIGN DE, DSFinV-K)

Las APIs especializadas usan paginación basada en offset con los parámetros de consulta limit y offset.

Parámetro	Por defecto	Máximo	Descripción
`limit`	100	1000	Número de elementos a devolver por página
`offset`	0	—	Número de elementos a omitir desde el inicio

La respuesta incluye count (total de elementos), data (array de resultados), offset y limit.

curl -X GET "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100",
  {
    headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
  }
);

const { count, data, offset, limit } = await response.json();
// count: 250, data: [...50 items], offset: 100, limit: 50

Unified API (SIGN FR, SIGN IT, SIGN PT, SIGN SE, SIGN CZ)

La Unified API utiliza paginación basada en token con los parámetros de consulta limit y token.

Parámetro	Por defecto	Máximo	Descripción
`limit`	10	100	Número de elementos a devolver por página
`token`	—	—	Cursor opaco del `pagination.token` de una respuesta anterior

La respuesta incluye results (array de recursos) y, cuando existen más páginas, un objeto pagination con token (cursor para la página siguiente), next (URL lista para usar de la página siguiente) y limit. En la última página el objeto pagination se omite por completo.

# Primera página
curl -X GET "https://test.api.fiskaly.com/organizations?limit=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-06-01"

# Página siguiente (usar pagination.token de la respuesta anterior)
curl -X GET "https://test.api.fiskaly.com/organizations?limit=25&token=eyJpZCI6ImFiYzEyMyJ9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-06-01"

let token = null;
let allItems = [];

do {
  const url = new URL("https://test.api.fiskaly.com/organizations");
  url.searchParams.set("limit", "25");
  if (token) url.searchParams.set("token", token);

  const response = await fetch(url, {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Version": "2026-06-01",
    },
  });

  const { results, pagination } = await response.json();
  allItems.push(...results);
  token = pagination?.token ?? null;
} while (token);

💡Elige el patrón correcto

Comprueba qué arquitectura de API usa tu producto (Unificada vs. Especializada) para determinar qué patrón de paginación implementar. Consulta las tablas al inicio de esta página.

APIs SIGN

SIGN DE v2

Referencia API interactiva — documentación completa de endpoints con prueba en línea

SIGN AT v1

RKSV austríaca — guía de integración y referencia de endpoints

SIGN FR

NF525 francesa — firma, cierres, archivos, modo offline

SIGN ES v1

TicketBAI y Verifactu españoles — generación XML, firma, envío

SIGN IT

Registratore Telematico italiano — RT en la nube, lotería de tickets

SIGN PT

SAF-T (PT) portugués — firma de documentos certificada con ATCUD

SIGN SE (TCS)

Fiscalización sueca — X.509, API XML, códigos de control

SIGN CZ (preview)

EET 2.0 checa — registro de ventas en tiempo real con confirmación POK

APIs de productos complementarios

DSFinV-K v1

Exportación de datos fiscales alemanes — cierres de caja, exportaciones de auditoría

SUBMIT DE v1

Presentación ELSTER — registro de contribuyentes y envío de declaraciones

SAFE

Archivado fiscal conforme — automatizado o vía API

E-Invoice

Facturación electrónica B2B vía Peppol — Bélgica live, más países próximamente

eReceipt v1

Generación de tickets digitales — entrega por QR, email y enlaza

Management API v0

Gestión de organizaciones, usuarios y API keys

SDKs y herramientas

Colecciones Postman

Solicitudes preconfiguradas para SIGN DE — exploración interactiva de la API

Quick Start

Primera transacción firmada en menos de 5 minutos con ejemplos de código

Códigos de error

Cada código de error, su causa y cómo solucionarlo

📘Sin SDKs de cliente (todavía)

fiskaly no proporciona actualmente SDKs de cliente oficiales. Todas las integraciones son llamadas directas a la API REST. La superficie de la API es lo suficientemente pequeña como para que un wrapper HTTP ligero en tu lenguaje preferido sea normalmente suficiente. Consulta el Changelog para anuncios de SDKs.