Guía de integración SAFE

Guía de integración — fiskaly SAFE

fiskaly SAFE proporciona archivado automático de datos fiscales de los servicios fiskaly conectados (SIGN DE, SIGN AT, DSFinV-K, etc.) sin necesidad de cargas manuales ni llamadas directas a la API. El archivado se configura y gestiona a través del fiskaly HUB.

📘SAFE vs SAFE flex

Esta guía cubre SAFE (archivado automático gestionado por el HUB). Si necesita control total de la API sobre qué se archiva y cuándo, consulta en su lugar la Guía de integración de SAFE flex. Para una comparación, consulta SAFE vs SAFE flex.

Requisitos previos

Antes de comenzar, asegúrate de tener:

• Una organización fiskaly activa con al menos un servicio conectado (p. ej., SIGN DE, DSFinV-K)
• Acceso al fiskaly HUB con permisos de administrador
• Un entorno LIVE o TEST con TSS activo o datos fiscales

Cómo funciona SAFE

SAFE archiva automáticamente las exportaciones de tus servicios fiskaly conectados en función de un calendario que configura en el HUB. El proceso está completamente gestionado:

1. fiskaly genera exportaciones de sus servicios conectados (exportaciones TSE, cierres DSFinV-K, etc.)
2. SAFE archiva los datos en almacenamiento en la nube certificado en la jurisdicción legalmente requerida
3. Los datos permanecen buscables y exportables para auditorías (niveles de acceso Z1, Z2, Z3)

No se necesitan cambios de código en tu integración de TPV — SAFE se conecta a tus servicios fiskaly existentes.

Configuración a través del fiskaly HUB

1. Iniciar sesión en el HUB

   Ve a hub.fiskaly.com e inicia sesión con las credenciales de tu organización. Selecciona la organización para la que desea configurar SAFE.

2. Activar SAFE

   Ve a Servicios > SAFE en la navegación del HUB. Haz clic en Activar SAFE para habilitar el archivado automático para tu organización. Se te pedirá que selecciona tu ubicación de almacenamiento (país) según sus requisitos legales.

3. Configurar el calendario de archivado

   Elige la frecuencia de exportación para el archivado automático:

   Frecuencia	Ideal para
   Diaria	Operaciones de alto volumen que necesitan archivos casi en tiempo real
   Semanal	Operaciones de comercio minorista estándar
   Mensual	Operaciones de bajo volumen o negocios estacionales

   El calendario determina la frecuencia con la que SAFE extrae nuevas exportaciones de sus servicios conectados y las archiva.

4. Seleccionar servicios conectados

   Elige qué servicios fiskaly deben alimentar SAFE:

   • SIGN DE — Archiva exportaciones de transacciones TSE
   • SIGN AT — Archiva exportaciones RKSV/DEP
   • DSFinV-K — Archiva exportaciones de cierre de punto de venta
   • Servicios adicionales a medida que estén disponibles

   Cada servicio se activa de forma independiente. Puede añadir o eliminar servicios en cualquier momento.

5. Verificar el primer archivo

   Después de la primera ejecución programada, consulta la sección SAFE > Archivos en el HUB. Debería ver:

   • Entradas de archivo con marcas de tiempo y servicio de origen
   • Recuentos de archivos y almacenamiento total utilizado
   • Indicadores de estado (Procesado, Pendiente, Fallido)

   Si el primer archivo se completa correctamente, SAFE está completamente operativo.

💡Prueba primero en el entorno de pruebas

Configura y prueba SAFE en tu entorno TEST antes de habilitarlo en LIVE. El comportamiento es idéntico, pero puede verificar el flujo de archivado sin afectar a los datos de producción.

Acceso a los datos archivados

A través del HUB

1. Ve a SAFE > Archivos en el HUB
2. Use filtros para acotar por rango de fechas, servicio o estado del archivo
3. Haz clic en cualquier entrada de archivo para ver los detalles y descargar los archivos
4. Use el botón Exportar para descargar archivos en bloque (formato ZIP)

A través de la API

Los datos archivados también son accesibles a través de la API SAFE para acceso programático:

# Listar archivos de tu organización
curl -X GET "https://safe.fiskaly.com/api/v0/archives" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Descargar un archivo específico
curl -X GET "https://safe.fiskaly.com/api/v0/archives/{archive_id}/download" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o archive.zip

Para la documentación completa de la API, consulta la Referencia de la API SAFE.

Soporte para auditorías

SAFE admite tres niveles de acceso para auditorías tal como los definen las autoridades fiscales alemanas (y requisitos análogos en otros países):

Nivel de acceso	Descripción	Cómo ayuda SAFE
Z1 — Acceso directo	El auditor accede directamente al sistema	Proporcionar acceso de solo lectura al auditor a través del HUB
Z2 — Acceso indirecto	El contribuyente proporciona datos a petición del auditor	Exportar desde SAFE y entregar al auditor
Z3 — Soporte de datos	Exportación legible por máquina en soporte de almacenamiento	Descargar archivos SAFE en formatos estándar

Retención y cumplimiento

• Los datos archivados se almacenan durante el período de retención legalmente requerido (normalmente 10 años en Alemania, 7 años en Austria)
• La ubicación de almacenamiento se determina por el país configurado durante la activación
• Los datos se almacenan de forma inalterable en centros de datos certificados de Google Cloud
• Se mantiene un registro de auditoría completo de todas las operaciones de archivado

⚠️Responsabilidad de retención

Aunque SAFE gestiona el archivado técnico, sigues siendo responsable de garantizar que su calendario de archivado capture todos los datos legalmente requeridos. Consulta a tu asesor fiscal para conocer los requisitos de retención específicos de su jurisdicción.

Solución de problemas

Problema	Causa	Resolución
No aparecen archivos	El calendario aún no se ha activado	Espera a la próxima ejecución programada, o active un archivo manual desde el HUB
Estado del archivo “Fallido”	El servicio de origen no tiene datos nuevos, o la generación de exportación falló	Comprueba el estado del servicio conectado en el HUB; verifica que el TSS esté activo
Datos faltantes en el archivo	El alcance de exportación no incluye el rango de fechas esperado	Verifica que el calendario de archivado cubra el período; comprueba si hay lagunas en los datos de origen

Próximos pasos

Guía SAFE flex

Control total de la API para flujos de archivado personalizados

Detalles de cumplimiento

Requisitos legales de archivado por país

Configuración HUB SAFE

Configuración detallada del HUB para SAFE