Proceso de integración paso a paso

Facturación electrónica B2B

Emita y reciba facturas electrónicas B2B legalmente conformes en las redes compatibles.

Compatibilidad con múltiples países

Bélgica, Alemania e Italia con el cumplimiento normativo específico de cada país integrado.

Unified API

Una única integración para la facturación electrónica en todos los países compatibles con endpoints coherentes.

Requisitos previos

Antes de comenzar, asegúrese de contar con:

• Acceso al HUB de fiskaly (entorno TEST)
• Conocimientos básicos de las API REST y los flujos de autenticación
• Los datos de registro de su empresa para la configuración del Taxpayer

📘Note

Si ya ha integrado SIGN IT o SIGN FR, los pasos iniciales de configuración de esta guía probablemente le resulten familiares y es posible que ya los haya completado. En ese caso, puede pasar directamente al Paso 10 para revisar los pasos adicionales necesarios.

Flujo de integración

📘Importante

Los pasos marcados en amarillo deben completarse directamente en HUB, mientras que los pasos restantes deben gestionarse a través de la API. Realizar cada acción en el contexto correcto es un paso importante para lograr una integración exitosa.

* Step required for BE 🇧🇪 and DE 🇩🇪
* Not required for IT 🇮🇹

Configuración paso a paso

1. Paso 1: Regístrese en HUB

   Comience registrándose en el HUB de fiskaly.

   
2. Paso 2: Cree una Account y una GROUP de organización

   Crear una Account de fiskaly es el primer paso, tras el cual podrá continuar con la configuración de la primera estructura organizativa de su empresa y la generación de su API Key.

   La Account representa al proveedor de PoS o a un minorista que opera su propio sistema PoS. Es la organización de nivel superior de la estructura.

   Después de crear su Account de fiskaly, accederá al Selector de organizaciones, donde podrá crear su Group. Un Group es un nivel intermedio dentro de una Account que le ayuda a organizar múltiples Units en agrupaciones lógicas.

3. Paso 3: Cree una API Key

   El siguiente paso es generar una API Key para su Organización a través del HUB dentro de su Group. Este par de API Key y Secret es necesario para crear su primera Organización de tipo UNIT (Paso 5).

   💡Entornos TEST y LIVE

   Las API Keys generadas en el entorno TEST (https://test.api.fiskaly.com) crearán recursos TEST, mientras que las del entorno LIVE (https://live.api.fiskaly.com) crearán recursos LIVE.

1. Paso 4: MANAGEMENT - Cree un Token

   Comience a utilizar la API E-INVOICE a través del endpoint createToken. Necesitará crear un token para autenticarse en los siguientes pasos.

2. Paso 5: MANAGEMENT - Cree una Organización UNIT

   Continúe creando una Organización de tipo UNIT a través del endpoint createOrganization. Una UNIT representa una única entidad legal (comerciante). Deberá crear una UNIT por cada representación de Taxpayer que gestione.

   Al crear su primera Organización de tipo UNIT, asegúrese de que esté asociada a su Group creado a través del HUB. Para ello, utilice el token generado a partir de las API keys creadas para su Group. Esto refleja la estructura jerárquica en la que la UNIT está anidada bajo su GROUP, que a su vez se encuentra dentro de su ACCOUNT.

3. Paso 6: MANAGEMENT - Cree un Subject (API Key)

   Cree un Subject de tipo API_KEY a través del endpoint createSubject. La conexión entre la Organización UNIT y la API Key se establece mediante el X-Scope-Identifier (utilizando el id de la Organización recién creada).

4. Paso 7: MANAGEMENT - Cree un nuevo Token

   A continuación, cree un token que se utilizará para crear recursos dentro de la Organización UNIT correspondiente.

5. Paso 8: OPERATION - Cree un Taxpayer

   Ya está listo para crear los Taxpayers necesarios para la facturación electrónica. Para ello, utilice el endpoint createTaxpayer. Deberá configurar el Taxpayer de tipo COMPANY.

   Según el país, la configuración de fiscalización requerida y los datos requeridos del Taxpayer pueden variar, por lo que le recomendamos consultar las guías específicas de cada país:

   • Bélgica
   • Alemania
   • Italia
   • Francia (próximamente)
   • Polonia (próximamente)

   Una vez que cree un Taxpayer de tipo COMPANY, su state se establecerá en ACQUIRED. Para que sea totalmente funcional, el estado debe actualizarse a COMMISSIONED mediante el endpoint updateTaxpayer.

   Al llamar al endpoint createTaxpayer se crea automáticamente una Location de tipo HEAD_OFFICE. Puede confirmarlo mediante el endpoint listLocations.

6. Paso 9: OPERATION - Cree una Location

   Los nuevos clientes que integren únicamente la facturación electrónica pueden omitir este paso.

   Para la fiscalización de recibos, debe crear una Location de tipo BRANCH mediante el endpoint createLocation para cada ubicación comercial.

   Cuando crea una Location de tipo BRANCH, su state se establece inicialmente en ACQUIRED. Para continuar, debe cambiar el estado a COMMISSIONED mediante el endpoint updateLocation.

7. Paso 10: OPERATION - Cree un System

   El endpoint createSystem se utiliza para crear una abstracción de un sistema utilizado para operaciones fiscales.

   Según su configuración, se aplica lo siguiente:

   • Nuevos clientes que utilizan únicamente la facturación electrónica: cree un único System E_INVOICE_SERVICE (solo uno por Taxpayer) y vincúlelo a la Location HEAD_OFFICE que se creó automáticamente en el paso 8.

   • Nuevos clientes que utilizan la fiscalización de recibos y la facturación electrónica: cree Systems FISCAL_DEVICE para los recibos y un System E_INVOICE_SERVICE adicional (uno por Taxpayer). Vincule el System E_INVOICE_SERVICE a la Location de tipo HEAD_OFFICE y vincule el o los Systems FISCAL_DEVICE a una Location de tipo BRANCH.

   • Clientes existentes con dispositivos fiscales puestos en servicio que añaden la facturación electrónica: cree un System E_INVOICE_SERVICE adicional y vincúlelo a la Location de tipo HEAD_OFFICE. Cuando se crea un Taxpayer, se genera automáticamente una Location de tipo HEAD_OFFICE con el mismo ID. Esto puede verificarse listando sus Locations.

   Al crear un System, su estado inicial se establece en ACQUIRED. Para continuar con el proceso de integración de la facturación electrónica, solicite la puesta en servicio del System E_INVOICE_SERVICE mediante updateSystem.

   ⚠️Importante

   Tras una solicitud de puesta en servicio exitosa, el System se encuentra en estado COMMISSIONED e inicialmente en modo DEGRADED hasta que el Paso 11 se complete por completo.

   📘Italia 🇮🇹

   Para los taxpayers italianos, el System E_INVOICE_SERVICE pasa directamente a state=COMMISSIONED, mode=OPERATIVE tras la puesta en servicio — sin carga de Proof of Ownership, por lo que el Paso 11 no aplica, y puede enviar facturas de inmediato. Si el Taxpayer también va a recibir, complete el registro único en la AdE — en cualquier momento, antes o después de la puesta en servicio — consulte la guía de Italia. Luego continúe al Paso 12.

8. Paso 11: OPERATION - Cargue el Proof of Ownership

   Este paso es necesario para las integraciones de E-INVOICE BE 🇧🇪 y E-INVOICE DE 🇩🇪.

   Cargue el PDF del Proof of Ownership mediante el endpoint createRecord, utilizando un Record de tipo INTENTION y una operación de tipo UPLOAD. El documento enviado se revisa y verifica, lo cual puede tardar hasta 72 horas. Una vez completada la verificación, el System pasa automáticamente del modo DEGRADED al modo OPERATIVE.

   Encontrará más detalles sobre el contenido requerido del documento en la sección Proof of Ownership.

   📘Omita este paso para Italia 🇮🇹

   Este paso no aplica a las integraciones de E-INVOICE IT. Continúe directamente al Paso 12.

9. Paso 12: OPERATION - Cree un Record

   ⚠️Importante

   Todos los Records creados en el entorno LIVE son legalmente válidos, por lo que deben representar siempre transacciones comerciales reales y válidas.

   Crear un Record en la API E-INVOICE siempre requiere dos llamadas sucesivas:

   • Parte A) INTENTION — al inicio del proceso de facturación electrónica
   • Parte B) TRANSACTION — una vez que los datos de la factura electrónica estén completos

   📘¿Utiliza también la fiscalización de recibos?

   Si el Taxpayer también utiliza la fiscalización de recibos (por ejemplo, SIGN IT), cree los Records INTENTION y TRANSACTION en su System FISCAL_DEVICE (cualquiera del mismo Taxpayer) — cuando hay un FISCAL_DEVICE en uso, este tiene prioridad. El System E_INVOICE_SERVICE sigue creando y transmitiendo la factura electrónica a partir de esos datos.

   PARTE A) Intention

   Para cada operación de facturación electrónica, primero llame al endpoint createRecord para registrar la intención de emitir una factura electrónica.

   Un Record de tipo INTENTION contendrá la siguiente información:

   • Asociación con el System E_INVOICE_SERVICE que se utilizará para emitir la factura electrónica
   • Operación de tipo TRANSACTION, que indica que el System tiene la intención de realizar una operación de facturación electrónica.

   Parte B) Transaction

   A continuación, llame de nuevo al endpoint createRecord para crear un Record de tipo TRANSACTION asociado al identificador interno de un Record de tipo INTENTION ya creado. El tipo de operación determina el documento emitido.

   Se admiten los siguientes tipos de operación:

   • INVOICE: Emite una factura electrónica estándar.
   • CORRECTION: Emite una nota de crédito. Consulte la guía de notas de crédito para conocer los flujos de trabajo y las reglas detalladas.

   Una vez que la Transaction se procesa correctamente, la factura electrónica se crea y se gestiona de acuerdo con los requisitos de facturación electrónica aplicables.

   📘Importante

   Para E-INVOICE, el destinatario debe ser de tipo BUSINESS y el bloque invoicing debe estar cumplimentado; de lo contrario, la factura electrónica no puede transmitirse. El método de entrega y los campos requeridos dentro del bloque invoicing varían según el país; consulte las guías específicas de cada país a continuación.

   Italia es la excepción: allí también se admiten destinatarios CONSUMER para facturas B2C, con un conjunto distinto de campos obligatorios. Consulte Envío de facturas electrónicas B2C.

   • Bélgica
   • Alemania
   • Italia
   • Francia (próximamente)
   • Polonia (próximamente)

Próximos pasos

Guía de Bélgica

Requisitos específicos para la facturación electrónica belga.

Guía de Alemania

Requisitos específicos para la facturación electrónica alemana.

Proof of Ownership

Conozca el proceso de verificación de documentos.

Referencia de la API

Documentación completa de la API E-INVOICE.