Integración paso a paso

Para comenzar el proceso de integración, consulta las instrucciones detalladas paso a paso que se proporcionan aquí.

El diagrama adjunto ilustra el flujo de trabajo y destaca los pasos esenciales necesarios para completar la integración con éxito.

Para la integración, deberás utilizar el fiskaly HUB, la Management API y la SIGN AT API.

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

🏢

Organización

Su entidad de nivel superior en fiskaly. Las organizaciones gestionadas representan comerciantes individuales.

🔑

Clave API y Secret

Credenciales generadas en HUB, utilizadas para autenticar todas las solicitudes posteriores de la SIGN AT API.

🇦🇹

Autenticación FON

Credenciales de FinanzOnline proporcionadas por el contribuyente para habilitar la sincronización con la autoridad fiscal austriaca.

🛡️

SCU (Signature Creation Unit)

El componente de firma central. Una SCU por organización gestionada se encarga de la firma criptográfica de los recibos.

💻

Caja registradora

Representa una caja registradora física o virtual. Debe estar registrada en FinanzOnline e inicializada.

🧾

Recibo

Un registro fiscal firmado conforme a la RKSV que contiene datos del código QR y metadatos del recibo.

Requisitos previos

📘Antes de comenzar

Necesita una cuenta de fiskaly y acceso al fiskaly HUB. Si aún 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 el código de su propia aplicación. Puede descargar nuestra colección de Postman, que puede facilitar tu integración.

Flujo de trabajo de integración

El diagrama a continuación ilustra el flujo de trabajo y destaca los pasos esenciales necesarios para completar la integración con éxito. Cada mosaico enlaza directamente con el paso de configuración correspondiente más abajo.

Configuración paso a paso

Registrarse en el Dashboard
Comienza registrándote en el fiskaly HUB. Crear una cuenta es el primer paso, tras el cual podrás proceder con la configuración de la estructura organizativa de tu empresa en nuestro sistema.
💡Empiece rápidamente
HUB ofrece un flujo de incorporación guiado que te lleva a través de la creación de la cuenta y la configuración inicial.
Crear la primera organización
Continúa creando tu primera organización usando HUB. Esta organización representará al proveedor de TPV o al comerciante con tu propio sistema TPV. Es necesario incluir la dirección de facturación en esta etapa. Esta dirección solo se utilizará para los propósitos de facturación de fiskaly.
💡¿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.
Crear organizaciones gestionadas
Tras establecer tu primera organización, procederá a crear organizaciones gestionadas. Cada organización gestionada representa a un comerciante, lo que te permite gestionarlos por separado. Si está pensando en automatizar tu proceso, te recomendamos usar el endpoint createOrganization de la Management API.
💡Automatice a escala
Si gestiona muchos comerciantes, use la Management API para crear organizaciones gestionadas de forma programática en lugar de hacerlo manualmente a través de HUB.
Crear clave API
El siguiente paso es generar una clave API dentro de cada organización gestionada. Esto se puede hacer a través de HUB o el endpoint createApiKey de la Management API. Este par de clave API y secret es necesario para generar un token de acceso, que se utiliza para todas las llamadas API posteriores.
⚠️Guarda tus credenciales de forma segura
El API Secret solo se muestra una vez. Asegúrate de copiarlo y guardarlo en un lugar seguro antes de cerrar el diálogo.
📘TEST vs. LIVE
Las claves API generadas en el entorno TEST crearán recursos TEST, mientras que las del entorno LIVE crearán recursos LIVE. Para más detalles, consulta nuestro artículo sobre entornos TEST y LIVE.
A partir del siguiente paso, utilizará la SIGN AT API.
Autenticarse con la API
Use tu clave API y secret para obtener un token de acceso. Este token es necesario para todas las solicitudes posteriores.
curl -X POST https://rksv.fiskaly.com/api/v1/auth \ -H "Content-Type: application/json" \ -d '{ "api_key": "your_api_key", "api_secret": "your_api_secret" }'
La respuesta contiene un access_token que debe incluir como token Bearer en el encabezado Authorization de todas las solicitudes siguientes.

Autenticar FON

Tras autenticarse con el par de clave API y secret generado anteriormente, es necesario llamar al endpoint authenticateFon una vez por contribuyente.

Para habilitar la sincronización con FinanzOnline, el contribuyente primero debe crear el “Usuario del Servicio Web de Cajas Registradoras” directamente en FinanzOnline y proporcionarle las credenciales de este usuario.

📘Las credenciales de FON son independientes

Las credenciales no corresponden a las credenciales generales de FinanzOnline. Corresponden a las credenciales del Usuario del Servicio Web de Cajas Registradoras dedicado creado por el contribuyente.

curl -X POST https://rksv.fiskaly.com/api/v1/fon/auth \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "fon_participant_id": "your_fon_participant_id",
    "fon_user_id": "your_fon_user_id",
    "fon_user_pin": "your_fon_user_pin"
  }'

const fonResponse = await fetch(
  "https://rksv.fiskaly.com/api/v1/fon/auth",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      fon_participant_id: "your_fon_participant_id",
      fon_user_id: "your_fon_user_id",
      fon_user_pin: "your_fon_user_pin",
    }),
  }
);

Crear SCU

Continúa creando una SCU a través del endpoint createSignatureCreationUnit. Por organización gestionada, solo se necesita crear una SCU. Una vez creada, el estado de una SCU será CREATED.

SCU_ID=$(uuidgen)

curl -X PUT "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_entity_id": {
      "vat_id": "ATU12345678"
    }
  }'

const scuId = crypto.randomUUID();

const scuResponse = await fetch(
  `https://rksv.fiskaly.com/api/v1/signature-creation-unit/${scuId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      legal_entity_id: {
        vat_id: "ATU12345678",
      },
    }),
  }
);

📘Note

Reemplaza ATU12345678 con el NIF/CIF real del contribuyente.

Crear caja(s) registradora(s)

Continúa creando al menos una caja registradora a través del endpoint createCashRegister. El número de cajas registradoras debe corresponder al número de cajas registradoras utilizadas en una tienda o establecimiento concreto. La creación de una caja registradora establece el estado CREATED.

CASH_REGISTER_ID=$(uuidgen)

curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Main POS Terminal"
  }'

const cashRegisterId = crypto.randomUUID();

const crResponse = await fetch(
  `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "Main POS Terminal",
    }),
  }
);

Actualizar SCU a INITIALIZED

Para firmar recibos, tanto la SCU como la(s) caja(s) registradora(s) deben actualizarse a INITIALIZED. Llama al endpoint updateSignatureCreationUnit y transiciónela al estado INITIALIZED. Esta transición de estado registra automáticamente la SCU en el portal de FinanzOnline.

curl -X PATCH "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "INITIALIZED"
  }'

await fetch(
  `https://rksv.fiskaly.com/api/v1/signature-creation-unit/${scuId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "INITIALIZED",
    }),
  }
);

Actualizar caja(s) registradora(s)

A diferencia de la actualización de la SCU, la(s) caja(s) registradora(s) deben actualizarse dos veces a través de updateCashRegister:

a) Registrar la caja registradora

Primero, cambia el estado de la caja registradora a REGISTERED. Esta transición de estado registra automáticamente la caja registradora en el portal de FinanzOnline.

curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "REGISTERED"
  }'

await fetch(
  `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "REGISTERED",
    }),
  }
);

b) Inicializar la caja registradora

Luego, en una segunda llamada, cambia el estado a INITIALIZED. Esta transición de estado desencadena la creación y validación del recibo inicial en el portal de FinanzOnline.

curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "INITIALIZED"
  }'

await fetch(
  `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "INITIALIZED",
    }),
  }
);

Tanto la SCU como la caja registradora están ahora listas para firmar recibos.

Firmar recibos

Con todos los pasos anteriores completados, ya está listo para firmar recibos a través del endpoint signReceipt.

RECEIPT_ID=$(uuidgen)

curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}/receipt/${RECEIPT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "receipt_type": "NORMAL",
    "schema": {
      "standard_v1": {
        "receipt": {
          "amounts_per_vat_rate": [
            {
              "vat_rate": "STANDARD",
              "amount": "12.00"
            }
          ],
          "amounts_per_payment_type": [
            {
              "payment_type": "CASH",
              "amount": "12.00"
            }
          ]
        }
      }
    }
  }'

const receiptId = crypto.randomUUID();

const receiptResponse = await fetch(
  `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}/receipt/${receiptId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      receipt_type: "NORMAL",
      schema: {
        standard_v1: {
          receipt: {
            amounts_per_vat_rate: [
              { vat_rate: "STANDARD", amount: "12.00" },
            ],
            amounts_per_payment_type: [
              { payment_type: "CASH", amount: "12.00" },
            ],
          },
        },
      },
    }),
  }
);

const signedReceipt = await receiptResponse.json();

SIGN AT garantiza que todos los recibos cumplan con la RKSV. La respuesta contiene toda la información necesaria para completar el recibo final entregado al cliente:

qr_code_data — contiene los datos para el código QR de la RKSV que se mostrará en formato gráfico
receipt_number, time_signature y cash_register_serial_number — información para mostrar en formato textual
Todos los importes brutos sin procesar

💡Automatizar la configuración

Toda esta secuencia de solicitudes puede integrarse en una solución de aprovisionamiento “de un solo clic” que no requiera interacción manual del usuario. Los detalles de implementación dependen de ti.

Próximos pasos

Documentación de la SIGN AT API

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

Datos del recibo

Referencia detallada de los campos del recibo, tipos de IVA y tipos de pago admitidos por SIGN AT.

Glosario

Términos clave y definiciones para el sistema de cumplimiento fiscal austriaco RKSV.

Guía de HUB

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

Was this page helpful?