Guía de integración de RECEIPT

Guía de integración de RECEIPT

Esta guía le explica cómo integrar la API de fiskaly RECEIPT para reemplazar los recibos en papel con recibos digitales legalmente conformes en todos los países de la UE.

📘Especificación detallada de la API

Para la referencia completa de la API, incluyendo todos los endpoints, esquemas y parámetros, consulta la documentación de la API RECEIPT. Esta guía cubre el flujo de integración conceptual.

Requisitos previos

Antes de comenzar, asegúrese de tener:

• Una organización de fiskaly con RECEIPT activado (contacte a sales@fiskaly.com o tu gestor de cuenta)
• Credenciales de API (clave de API y secreto) para el servicio RECEIPT
• Un sistema de caja o aplicación capaz de realizar solicitudes HTTPS

Descripción general de la integración

El flujo de RECEIPT funciona en tres fases:

1. Crear — Tu sistema de caja envía datos de transacción a la API RECEIPT
2. Entregar — La API genera un recibo digital y devuelve un mecanismo de entrega (código QR, enlaza, etc.)
3. Presentar — El cliente recibe el recibo a través de su canal preferido

Integración paso a paso

1. Autenticarse

   Obt�n un token de acceso usando tus credenciales de la API RECEIPT:

   curl -X POST https://receipt.fiskaly.com/api/v1/auth \
     -H "Content-Type: application/json" \
     -d '{
       "api_key": "YOUR_API_KEY",
       "api_secret": "YOUR_API_SECRET"
     }'

   La respuesta incluye un access_token válido por 24 horas. Inclúyalo como token Bearer en todas las solicitudes posteriores.

2. Configurar el perfil del comerciante

   Configura la información de tu comerciante que aparecerá en todos los recibos generados:

   • Nombre de la empresa y forma legal
   • Dirección e información de contacto
   • Números de identificación fiscal
   • Logotipo (opcional)
   • Preferencias de personalización de recibos
3. Crear un recibo

   Después de cada transacción, envíe los datos del recibo a la API RECEIPT:

   curl -X POST https://receipt.fiskaly.com/api/v1/receipts \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "items": [
         {
           "description": "Product A",
           "quantity": 2,
           "unit_price": 1299,
           "vat_rate": "19.00"
         }
       ],
       "payment": {
         "method": "card",
         "amount": 2598
       }
     }'

   Los importes se expresan en la unidad monetaria más pequeña (céntimos).

4. Presentar el recibo al cliente

   La respuesta de la API incluye opciones de entrega:

   • Código QR — Mostrar en la pantalla del sistema de caja o imprimir un pequeño código QR para que el cliente lo escanea
   • Código estático — Un código persistente vinculado al comerciante para clientes habituales
   • Enlaza directo — Una URL que el cliente puede abrir en cualquier navegador

   El cliente ve tu recibo en receipt.fiskaly.com — no se requiere descarga de aplicación.

5. Conectar con fiskaly SIGN (opcional)

   Si utiliza fiskaly SIGN para el cumplimiento fiscal, RECEIPT puede vincular automáticamente los recibos con las transacciones firmadas. Esto proporciona:

   • Inclusión automática de datos de firma fiscal en el recibo digital
   • Soporte de validación de código QR
   • Cadena de auditoría completa desde la transacción hasta la entrega del recibo

Canales de entrega

Canal	Cómo funciona	Mejor para
Código QR	El cliente escanea un código QR mostrado en pantalla o impreso	Sistema de caja en tienda, servicio rápido
Código estático	Código QR persistente vinculado a la ubicación del comerciante	Displays en mostrador, cartas de mesa
Correo electrónico	Recibo enviado directamente al correo del cliente	Comercio electrónico, reservas
Enlaza	URL compartible al recibo alojado	Cualquier canal de entrega

💡No se requiere aplicación

RECEIPT funciona completamente a través de la web. Los clientes ven los recibos en su navegador en receipt.fiskaly.com — sin descarga de aplicación, creación de cuenta o registro necesario.

Cumplimiento normativo

Los recibos digitales generados por RECEIPT cumplen las normativas en todos los países de la UE:

• Cumple los requisitos de documentos electrónicos según la Directiva IVA de la UE
• Conforme con las obligaciones de recibos específicas de cada país (Alemania, Austria, Francia, etc.)
• Seguridad de datos garantizada por la certificación ISO 27001 de fiskaly
• Los recibos son inmutables una vez creados — se mantiene la cadena de auditoría completa

Pruébelo ahora

Crea un recibo de demostración para ver la experiencia del cliente antes de integrar.

Recursos

Para información técnica más detallada, descarga la guía de integración completa:

• Guía de integración (PDF) — Referencia completa de la API con ejemplos de solicitud/respuesta
• Referencia de la API RECEIPT — Especificación OpenAPI completa
• Inicio rápido — Configuración mínima para crear su primer recibo
• FAQ — Preguntas frecuentes sobre RECEIPT