Guía para nuevos clientes

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 y solicitudes API. Al finalizar, tendráss un TSS completamente funcional con un cliente listo para firmar transacciones.

Descripción general

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

🏢

Organización

Su entidad de nivel superior en fiskaly. Las organizaciones gestionadas representan ubicaciones físicas individuales.

🔑

Clave API y secreto

Credenciales generadas en HUB, usadas para autenticar todas las solicitudes API posteriores.

🔐

Autenticación

Use tu clave API y secreto para generar un token de acceso utilizado en todas las llamadas API posteriores.

🛡️

TSS (Sistema de seguridad técnica)

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

💻

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 crear y firmar transacciones.

Eche un vistazo a nuestro tutorial en vídeo para una explicación visual del proceso de configuración.

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 (línea de comandos), Postman o su propio código de aplicación.

Configuración paso a paso

Crear una organización
Cuando inicia sesión en HUB por primera vez, se te pide que crea una organización. Esta es su organización principal, y todas las organizaciones gestionadas se crean bajo ella.
En general, cada organización gestionada corresponde a una ubicación física (p. ej., una tienda o restaurante).
💡¿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 crear tu organización, HUB mostrará tu configuración actual — inicialmente con 0 TSS y 0 clientes.
Generar una clave API y un secreto
Navega a la sección Claves API en el fiskaly HUB y crea una nueva clave API.
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.
Nuestro tutorial en vídeo demuestra el proceso de generación de una clave y secreto API.

Autenticarse con la API

Use tu clave y secreto de API para obtener un token de acceso. Este token es necesario para todas las solicitudes posteriores.

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();

Ejemplo de respuesta (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TESTING",
    "organization_id": "your-org-id"
  },
  "access_token_expires_in": 86400,
  "access_token_expires_at": "2026-03-02T12:00:00Z",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 172800,
  "refresh_token_expires_at": "2026-03-03T12:00:00Z"
}

La respuesta contiene un access_token que debe incluir como token Bearer en el encabezado Authorization de todas las solicitudes siguientes.

Crear un TSS

Crea un nuevo Sistema de Seguridad Técnica (TSS) enviando una solicitud PUT con un ID de TSS único (UUID).

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": "My first TSS"
  }'

const tssId = crypto.randomUUID();

const response = 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",
    }),
  }
);

Ejemplo de respuesta (200 OK)

{
  "_id": "your-tss-id",
  "_type": "TSS",
  "_env": "TESTING",
  "_version": 1,
  "admin_puk": "initial-puk-from-creation",
  "state": "CREATED",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "serial_number": "a1b2c3d4e5f6...",
  "public_key": "BHxw...",
  "signature_algorithm": "ECDSA",
  "signature_timestamp_format": "ISO8601",
  "transaction_data_encoding": "UTF-8",
  "max_number_registered_clients": 100,
  "max_number_active_transactions": 1000,
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

Después de la creación, necesita inicializar el TSS. Esto implica tres subpasos:

a) Cambiar el PIN de administrador

El TSS se crea en un estado UNINITIALIZED. Debe establecer un nuevo PIN de administrador antes de la inicializació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": "initial-puk-from-creation",
    "new_admin_pin": "your-secure-admin-pin"
  }'

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/admin`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      admin_puk: "initial-puk-from-creation",
      new_admin_pin: "your-secure-admin-pin",
    }),
  }
);

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

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/admin/auth`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      admin_pin: "your-secure-admin-pin",
    }),
  }
);

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

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "INITIALIZED",
    }),
  }
);

Ejemplo de respuesta (200 OK)

{
  "_id": "your-tss-id",
  "_type": "TSS",
  "_env": "TESTING",
  "_version": 2,
  "state": "INITIALIZED",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "serial_number": "a1b2c3d4e5f6...",
  "public_key": "BHxw...",
  "signature_algorithm": "ECDSA",
  "signature_timestamp_format": "ISO8601",
  "transaction_data_encoding": "UTF-8",
  "max_number_registered_clients": 100,
  "max_number_active_transactions": 1000,
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

Crear un 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",
  "_env": "TESTING",
  "_version": 1,
  "serial_number": "POS-001",
  "state": "REGISTERED",
  "tss_id": "your-tss-id",
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

Crear una transacción

Ahora puede crear tu primera transacción firmada. Las transacciones siguen un ciclo de vida: iniciar la transacción y luego finalizarla.

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

Ejemplo de respuesta (200 OK)

{
  "_id": "your-tx-id",
  "_type": "TRANSACTION",
  "_env": "TESTING",
  "_version": 1,
  "number": 1,
  "state": "ACTIVE",
  "client_id": "your-client-id",
  "client_serial_number": "POS-001",
  "tss_id": "your-tss-id",
  "tss_serial_number": "a1b2c3d4e5f6...",
  "time_start": "2026-03-01T10:00:00Z",
  "revision": 1,
  "latest_revision": 1,
  "log": {
    "operation": "START",
    "timestamp": "2026-03-01T10:00:00Z",
    "timestamp_format": "ISO8601"
  },
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:00:00Z",
    "timestamp_format": "ISO8601",
    "serial_number": "a1b2c3d4e5f6..."
  },
  "metadata": {}
}

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",
  "_env": "TESTING",
  "_version": 2,
  "number": 1,
  "state": "FINISHED",
  "client_id": "your-client-id",
  "client_serial_number": "POS-001",
  "tss_id": "your-tss-id",
  "tss_serial_number": "a1b2c3d4e5f6...",
  "time_start": "2026-03-01T10:00:00Z",
  "time_end": "2026-03-01T10:05:00Z",
  "revision": 2,
  "latest_revision": 2,
  "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" }
        ]
      }
    }
  },
  "qr_code_data": "V0;955002-00;Kassenbeleg-V1;...",
  "log": {
    "operation": "FINISH",
    "timestamp": "2026-03-01T10:05:00Z",
    "timestamp_format": "ISO8601"
  },
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:05:00Z",
    "timestamp_format": "ISO8601",
    "serial_number": "a1b2c3d4e5f6..."
  },
  "metadata": {}
}

La respuesta incluye los datos de transacción firmados con una firma criptográfica del TSS.

Cerrar la sesión del administrador
Una vez completada la configuración, cierra la sesión del usuario administrador en el TSS.
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \ -H "Authorization: Bearer ${ACCESS_TOKEN}"

💡Automatizar la configuración

Esta secuencia completa de solicitudes puede integrarse en una solución de aprovisionamiento de “un clic” que no requiere ninguna interacción manual del usuario. Los detalles de implementación dependen de ti.

Colección de Postman

También puede ejecutar estas solicitudes usando Postman. Descarga los archivos de colección y entorno para comenzar rápidamente:

Descargar colección de Postman

Descargar entorno de Postman

Consulta el tutorial de Postman para obtener instrucciones detalladas.

Próximos pasos

Documentación de la API SIGN DE

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

Guía de HUB

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

Was this page helpful?

Guía para nuevos clientes

Descripción general

Organización

Clave API y secreto

Autenticación

TSS (Sistema de seguridad técnica)

Cliente

Transacción

Requisitos previos

Configuración paso a paso

Crear una organización

Generar una clave API y un secreto

Autenticarse con la API

Crear un TSS

Crear un cliente

Crear una transacción

Cerrar la sesión del administrador

Colección de Postman

Próximos pasos

Documentación de la API SIGN DE

Guía de HUB