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 API Unificada para la comparación completa.

API Unificada

La API Unificada utiliza URLs base compartidas y un modelo de recursos común entre países. Actualmente cubre SIGN FR y SIGN IT (SIGN SE próximamente).

	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-05-04	Docs
SIGN IT	2026-05-04	Docs
SIGN SE	TCS (API Unificada próx.)	Docs actuales

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	`management.fiskaly.com/api/v0`	`management.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, 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

API Unificada (SIGN FR, SIGN IT)

La API Unificada utiliza paginación basada en cursor con los parámetros de consulta page[limit] y page[after].

Parámetro	Por defecto	Máximo	Descripción
`page[limit]`	25	100	Número de elementos a devolver por página
`page[after]`	—	—	Cursor opaco del `next_cursor` de una respuesta anterior

La respuesta incluye data (array de resultados), pagination.has_more (booleano) y pagination.next_cursor (string, presente cuando has_more es true).

# Primera página
curl -X GET "https://test.api.fiskaly.com/signing-units?page[limit]=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-05-04"

# Página siguiente (usar next_cursor de la respuesta anterior)
curl -X GET "https://test.api.fiskaly.com/signing-units?page[limit]=25&page[after]=eyJpZCI6ImFiYzEyMyJ9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-05-04"

let cursor = null;
let allItems = [];

do {
  const url = new URL("https://test.api.fiskaly.com/signing-units");
  url.searchParams.set("page[limit]", "25");
  if (cursor) url.searchParams.set("page[after]", cursor);

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

  const { data, pagination } = await response.json();
  allItems.push(...data);
  cursor = pagination.has_more ? pagination.next_cursor : null;
} while (cursor);

💡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 SE (TCS)

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

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/B2G 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.

Was this page helpful?