Integración paso a paso

Esta guía te lleva a través del proceso completo de configuración de tu sistema con fiskaly SIGN DE, usando una combinación del fiskaly HUB, la Management API y la API SIGN DE. Al finalizar, tendráss una organización gestionada completamente aprovisionada con un TSS y un cliente listos para firmar transacciones.

Antes de comenzar la configuración, esto es lo que configurará:

🏢

Cuenta y grupo

Su Cuenta es la entidad de nivel superior creada al registrarte en el HUB — representa tu empresa como proveedor de TPV o comerciante. Un Grupo es una capa intermedia dentro de la Cuenta que se utiliza para agrupar organizaciones gestionadas de forma lógica (p. ej., un Grupo por país).

🔑

Clave API y token

Credenciales generadas en el HUB y tokens obtenidos de la Management API y SIGN DE, usados para autenticar todas las solicitudes posteriores.

🏬

Organización gestionada

Representa una única ubicación física (p. ej., una tienda o restaurante), llamada Unit en el HUB. Creada a través de la Management API y vinculada a un Grupo dentro de su Cuenta.

🛡️

TSS (Sistema de seguridad técnica)

El componente de firma principal. Debe crearse, configurarse con un PIN de administrador e inicializarse antes de poder firmar transacciones.

💻

Cliente

Representa un terminal de punto de venta o una aplicación que crea transacciones contra un TSS.

🧾

Transacción

Un registro fiscal firmado. Una vez que su TSS y Cliente estén listos, puede iniciar y finalizar transacciones para generar firmas criptográficas.

Requisitos previos

📘Antes de comenzar

Necesita una cuenta fiskaly y acceso al fiskaly HUB. Si todavía no tiene una cuenta, regístrese aquí. También necesitará una herramienta para realizar solicitudes HTTP — por ejemplo cURL, Postman o su propio código de aplicación.

Flujo de trabajo de integración

El diagrama a continuación muestra los diez pasos de la integración de SIGN DE. Haz clic en cualquier mosaico para ir al paso de configuración correspondiente.

Configuración paso a paso

Registrarse en el HUB
Ve a hub.fiskaly.com y crea tu cuenta fiskaly. Recibirá un correo electrónico de confirmación — haz clic en el enlaza para verificar su dirección y activar tu cuenta.
Crear Cuenta y Grupo
Cuando inicia sesión en el HUB por primera vez, se te pide que configura su Cuenta — la entidad de nivel superior que representa tu empresa (proveedor de TPV o comerciante). El HUB también te guiará para crear un Grupo, una capa intermedia dentro de su Cuenta para agrupar organizaciones gestionadas de forma lógica (por ejemplo, un Grupo por país).
💡¿Aún no está listo para producción?
Para propósitos de prueba, no necesita completar todos los campos. Puede dejar la dirección de facturación vacía y completarla más tarde.
Después de completar la configuración, el HUB mostrará su resumen actual — inicialmente con 0 TSS y 0 clientes.
Crear clave API
Navega a la sección Claves API en el fiskaly HUB y crea una nueva clave API para su Cuenta.
Recibirá una Clave API y un Secreto API. Guárdelos de forma segura — los necesitará para todas las solicitudes API posteriores.
⚠️Almacene tus credenciales de forma segura
El Secreto API solo se muestra una vez. Asegúrate de copiarlo y almacenarlo en un lugar seguro antes de cerrar el diálogo.

Crear token (Management API)

Use la Clave API y el Secreto del paso anterior para obtener un token de acceso a la Management API.

curl -X POST https://dashboard.fiskaly.com/api/v0/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
  }'

const response = await fetch(
  "https://dashboard.fiskaly.com/api/v0/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();

Ejemplo de respuesta (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TEST",
    "organization_id": "00000000-0000-0000-0000-000000000000"
  },
  "access_token_expires_in": 300,
  "access_token_expires_at": 1577833200,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 300,
  "refresh_token_expires_at": 1577833200
}

Use el access_token como token Bearer en el encabezado Authorization para todas las solicitudes de la Management API.

Crear organización(es) gestionada(s)

Crea una o más organizaciones gestionadas (también llamadas Units en el HUB) bajo su Grupo. Cada Unit generalmente representa una única ubicación física como una tienda o restaurante.

curl -X POST "https://dashboard.fiskaly.com/api/v0/organizations" \
  -H "Authorization: Bearer ${MANAGEMENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Store Berlin",
    "managed_by_organization_id": "your-group-id",
    "address_line1": "Unter den Linden 1",
    "zip": "10117",
    "town": "Berlin",
    "country_code": "DEU"
  }'

const response = await fetch(
  "https://dashboard.fiskaly.com/api/v0/organizations",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${managementToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "My Store Berlin",
      managed_by_organization_id: "your-group-id",
      address_line1: "Unter den Linden 1",
      zip: "10117",
      town: "Berlin",
      country_code: "DEU",
    }),
  }
);

const { _id: orgId } = await response.json();

Ejemplo de respuesta (200 OK)

{
  "_id": "your-managed-org-id",
  "_type": "ORGANIZATION",
  "name": "My Store Berlin",
  "managed_by_organization_id": "your-group-id",
  "address_line1": "Unter den Linden 1",
  "zip": "10117",
  "town": "Berlin",
  "country_code": "DEU",
  "state": "active",
  "time_creation": "2026-03-01T10:00:00Z"
}

Anota el _id de la respuesta — este es su ID de organización gestionada, necesario para el siguiente paso.

💡Dónde encontrar su ID de Grupo

Su ID de Grupo (managed_by_organization_id) es visible en el fiskaly HUB en Configuración → Organización, o puede recuperarlo del campo organization_id en la respuesta del token de la Management API (POST /api/v0/auth).

Crear clave API (organización gestionada)

Genera una clave API dedicada para la organización gestionada. Esta clave se usará para autenticar las solicitudes de la API SIGN DE con alcance limitado a esa organización.

curl -X POST "https://dashboard.fiskaly.com/api/v0/organizations/${ORG_ID}/api-keys" \
  -H "Authorization: Bearer ${MANAGEMENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sign-de-key",
    "status": "enabled",
    "managed_by_organization_id": "your-group-id"
  }'

const response = await fetch(
  `https://dashboard.fiskaly.com/api/v0/organizations/${orgId}/api-keys`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${managementToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "sign-de-key",
      status: "enabled",
      managed_by_organization_id: "your-group-id",
    }),
  }
);

const { key: apiKey, secret: apiSecret } = await response.json();

⚠️Guardar estas credenciales

El secret para la clave API de la organización gestionada solo se muestra una vez. Almacénelo de forma segura antes de continuar.

Ejemplo de respuesta (200 OK)

{
  "_id": "your-api-key-id",
  "_type": "MANAGED_API_KEY",
  "_envs": ["TEST"],
  "name": "sign-de-key",
  "key": "your-api-key",
  "secret": "your-api-secret",
  "status": "enabled",
  "managed_by_organization_id": "your-group-id",
  "created_at": 1577833200
}

Crear token (SIGN DE)

Use la clave y el secreto API de la organización gestionada para obtener un token de acceso a SIGN DE.

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "managed_org_api_key",
    "api_secret": "managed_org_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: "managed_org_api_key",
      api_secret: "managed_org_api_secret",
    }),
  }
);

const { access_token } = await response.json();

Ejemplo de respuesta (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TESTING",
    "organization_id": "your-managed-org-id"
  },
  "access_token_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 172800
}

Use este access_token como token Bearer para todas las solicitudes posteriores a la API SIGN DE.

Crear TSS
Crea un nuevo Sistema de Seguridad Técnica (TSS) enviando una solicitud PUT con un ID de TSS único (UUID). El TSS debe inicializarse antes de poder firmar transacciones.
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 '{"metadata": {}}'
Ejemplo de respuesta (200 OK)
{ "_id": "your-tss-id", "_type": "TSS", "_env": "TEST", "_version": "2.2.2", "admin_puk": "initial-puk-from-creation", "state": "CREATED", "serial_number": "a1b2c3d4e5f6...", "public_key": "MFkwEwYH...", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "signature_algorithm": "ECDSA", "signature_timestamp_format": "unixTime", "transaction_data_encoding": "UTF-8", "max_number_registered_clients": 100, "max_number_active_transactions": 1000, "time_creation": 1577833200, "metadata": {} }
⚠️Usar un tiempo de espera generoso
La creación e inicialización del TSS puede tardar hasta 30 segundos. Establece un tiempo de espera de solicitud de al menos 30 segundos para ambas llamadas para evitar fallos prematuros.
Después de la creación, inicialice el TSS en cuatro subpasos:
a) Personalizar el TSS
Mueva el TSS del estado CREATED al estado UNINITIALIZED antes de cambiar el PIN de administrador:
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": "UNINITIALIZED"}'
b) Cambiar el PIN de administrador
El TSS se crea en un estado UNINITIALIZED. Debe establecer un nuevo PIN de administrador usando el admin_puk de la respuesta de creación.
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": "puk-from-creation-response", "new_admin_pin": "your-secure-admin-pin" }'
c) 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" }'
d) Inicializar el TSS
Actualiza el estado del TSS a INITIALIZED:
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" }'
Ejemplo de respuesta (200 OK)
{ "_id": "your-tss-id", "_type": "TSS", "state": "INITIALIZED", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "serial_number": "a1b2c3d4e5f6...", "signature_algorithm": "ECDSA", "max_number_registered_clients": 100, "max_number_active_transactions": 1000, "time_creation": "2026-03-01T10:00:00Z" }
💡Cerrar la sesión del administrador cuando termine
Una vez inicializado el TSS, cierra la sesión del usuario administrador como buena práctica de seguridad — requerido antes del uso en producción.
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \ -H "Authorization: Bearer ${ACCESS_TOKEN}"

Crear cliente

Con el TSS inicializado, crea un cliente que represente su terminal de punto de venta o aplicación.

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"
  }'

const clientId = crypto.randomUUID();

const response = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/client/${clientId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ serial_number: "POS-001" }),
  }
);

Ejemplo de respuesta (200 OK)

{
  "_id": "your-client-id",
  "_type": "CLIENT",
  "serial_number": "POS-001",
  "state": "REGISTERED",
  "tss_id": "your-tss-id",
  "time_creation": "2026-03-01T10:00:00Z"
}

⚠️serial_number es permanente

El serial_number que asigna a un cliente no puede cambiarse después de su creación. Elige un identificador estable y único para cada terminal TPV (p. ej., un número de serie de hardware o un UUID estable que controle).

💡Automatizar la configuración

Esta secuencia de aprovisionamiento completa (Pasos 1–9) puede integrarse en un flujo de trabajo totalmente automatizado. Una vez implementado, incorporar una nueva ubicación no requiere ninguna interacción manual del usuario.

Operaciones diarias: Crear transacción

Ahora que su TSS y Cliente están aprovisionados, está listo para las operaciones diarias. Las transacciones siguen un ciclo de vida de dos pasos que se corresponde con el flujo de pago real:

Iniciar la transacción (abrir la caja) — envía solo state: "ACTIVE" y client_id. No se requiere ningún esquema de recibo en este momento.
Finalizar la transacción (después de completar el pago) — envía el esquema de recibo completo con importes y tipo de pago para generar 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"
  }'

const txId = crypto.randomUUID();

const startResponse = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/tx/${txId}?tx_revision=1`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "ACTIVE",
      client_id: clientId,
    }),
  }
);

b) Finalizar la transacción

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" }
          ]
        }
      }
    }
  }'

const finishResponse = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/tx/${txId}?tx_revision=2`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "FINISHED",
      client_id: clientId,
      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" },
            ],
          },
        },
      },
    }),
  }
);

Ejemplo de respuesta (200 OK)

{
  "_id": "your-tx-id",
  "_type": "TRANSACTION",
  "state": "FINISHED",
  "client_id": "your-client-id",
  "tss_id": "your-tss-id",
  "time_start": "2026-03-01T10:00:00Z",
  "time_end": "2026-03-01T10:05:00Z",
  "qr_code_data": "V0;955002-00;Kassenbeleg-V1;...",
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:05:00Z",
    "serial_number": "a1b2c3d4e5f6..."
  }
}

La respuesta incluye la transacción firmada con un string qr_code_data para el código QR del recibo y una signature criptográfica del TSS.

Próximos pasos

Referencia API SIGN DE

Documentación completa de la API para el endpoint KassenSichV v2 — todos los recursos, parámetros y respuestas.

Guía para nuevos clientes

Guía detallada del proceso de configuración con descargas de colecciones de Postman y tutoriales en vídeo.

Manual de usuario del HUB

Aprenda a gestionar organizaciones, claves API y TSS a través de la interfaz del fiskaly HUB.

Validación de código QR

Comprenda el formato de datos del código QR en tus recibos y cómo validar las transacciones firmadas.

Was this page helpful?

Integración paso a paso

Cuenta y grupo

Clave API y token

Organización gestionada

TSS (Sistema de seguridad técnica)

Cliente

Transacción

Requisitos previos

Flujo de trabajo de integración

Configuración paso a paso

Registrarse en el HUB

Crear Cuenta y Grupo

Crear clave API

Crear token (Management API)

Crear organización(es) gestionada(s)

Crear clave API (organización gestionada)

Crear token (SIGN DE)

Crear TSS

Crear cliente

Operaciones diarias: Crear transacción

Próximos pasos

Referencia API SIGN DE

Guía para nuevos clientes

Manual de usuario del HUB

Validación de código QR