Manejo de errores y tiempos de espera

La máxima prioridad al implementar la API fiskaly SIGN DE es mantener el sistema POS en funcionamiento en todo momento.

⚠️No bloquee la caja

No existe ninguna obligación de que la caja deba detener su funcionamiento o verse gravemente afectada en ningún momento. Asegúrate de que tu integración no bloquee a los operadores.

En el caso óptimo, la API se implementa de tal manera que se puede garantizar el funcionamiento fluido de la caja registradora en todo momento. A continuación se explica cómo lograrlo.

Configurar los tiempos de espera correctamente

En caso de que el TSS no esté disponible o esté temporalmente inestable, el proceso de pago no debe interrumpirse. Los tiempos de espera dependen en gran medida de la frecuencia del sistema POS. Como fabricante, debes decidir qué duración de tiempo de espera considera razonable. Ninguna solicitud debe permanecer abierta el tiempo suficiente como para poner en peligro el funcionamiento fluido de la caja registradora.

Valores de tiempo de espera recomendados

Endpoint	Tiempo de espera recomendado	Notas
Endpoints de transacciones	3 - 5 segundos	Los más críticos para el flujo de pago
Creación e inicialización del TSS	Mínimo 30 segundos	Operación de configuración única
Autorización	3 - 4 segundos	Renovación del token, no en cada solicitud
Endpoints DSFinV-K	Hasta 10 minutos	Procesamiento intensivo / exportaciones de datos

💡Hacer los tiempos de espera configurables

Recomendamos crear la posibilidad de configurar los tiempos de espera (p. ej., un valor entre 1,5 - 3 segundos) por parte de un administrador. De esta forma se pueden ahorrar valiosos recursos de desarrollo y se garantiza un funcionamiento fluido del POS.

📘Note

Si parece haber un problema, comprueba status.fiskaly.com y también la página de soporte.

Manejar los errores con elegancia

Cuando una solicitud falla o agota el tiempo de espera, sigue este enfoque:

1. Detectar el fallo

   Establece tiempos de espera apropiados por tipo de endpoint (consulta la tabla anterior). Cuando ocurra un tiempo de espera o un error HTTP, captúrelo con elegancia sin bloquear el pago.

2. Continuar con el pago

   Permite que la transacción continúe incluso sin una firma del TSS. Registra la transacción localmente con todos los datos disponibles.

3. Marcar el recibo

   Añade una nota clara en el recibo como “TSS no disponible” o “Firma del TSS fallida” según lo recomendado por las autoridades fiscales.

4. Registrar en DSFinV-K

   Asegúrate de que la transacción no firmada aparezca en la exportación DSFinV-K usando el campo transactions.security.error_message en lugar de transactions.security.tss_tx_id.

Firmas faltantes

Una firma faltante en el documento no significa que el documento no cumpla con la ley (consulta Punkt 7 AEAO to § 146a). Sin embargo, la API de fiskaly debe implementarse de tal manera que cada transacción solicite una firma. Si no es posible obtener una, se aplican las reglas de DSFinV-K.

⚠️Las transacciones no firmadas aún deben registrarse

Todas las transacciones, incluidas las que no tienen firma, deben aparecer en la exportación DSFinV-K. Para las transacciones sin firma, todos los datos conocidos se transfieren a la exportación DSFinV-K.

DSFinV-K y transacciones

Las autoridades fiscales recomiendan añadir una nota clara en el recibo para las transacciones no firmadas, como:

“TSS no disponible” o “Firma del TSS fallida”

📘Note

Al usar la API DSFinV-K de fiskaly, el campo transactions.security.error_message debe usarse en lugar de transactions.security.tss_tx_id en el endpoint insertCashPointClosing en caso de transacciones no firmadas.

Autorización

La autorización se realiza inicialmente a través de la Clave API y el Secreto API. Recibirá:

Token	Validez
access_token	24 horas
refresh_token	48 horas

Puede usar estos tokens para reautorizarse de forma continua. Si recibe una respuesta 401, simplemente reautorícese a través de la Clave API y el Secreto.

⚠️No reautentique en cada solicitud

La reautorización no debe ocurrir en cada solicitud, ya que esto añadiría una sobrecarga innecesaria al proceso de pago. La validez de los tokens es de varias horas.

💡Resumen de mejores prácticas

1. Establece tiempos de espera apropiados para cada tipo de endpoint
2. Haga los tiempos de espera configurables por un administrador
3. Nunca bloquee la caja — siempre permite que el pago continúe
4. Registra todas las transacciones en la exportación DSFinV-K, incluso las no firmadas
5. Añade una nota clara en los recibos cuando falta una firma
6. Almacene en caché los tokens de autorización y reutilícelos dentro de su período de validez

Páginas relacionadas

Guía para nuevos clientes

Guía completa de configuración, incluyendo autenticación

Soporte

Cómo crear un ticket y contactar con el equipo de soporte