Proceso de integración paso a paso

Facturación electrónica B2B

Emita facturas electrónicas legalmente conformes a través de la red PEPPOL para transacciones B2B.

Soporte multipaís

Bélgica, Alemania, Italia, Francia y Polonia con cumplimiento normativo específico por país integrado.

API Unificada

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

Requisitos previos

Antes de comenzar, asegúrate de tener:

• Acceso al HUB de fiskaly (entorno TEST)
• Comprensión básica de las APIs REST y los flujos de autenticación
• Los datos de registro de tu empresa para la configuración del contribuyente

📘Note

Si ya ha integrado SIGN IT o SIGN FR, los pasos iniciales de configuración en esta guía probablemente te resultarán familiares y es posible que ya estén completados. En ese caso, puede pasar directamente al Paso 10 para revisar los pasos adicionales necesarios.

Flujo de trabajo de integración

📘Importante

Los pasos marcados en amarillo deben completarse directamente en el 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 hacia una integración exitosa.

Configuración paso a paso

1. Paso 1: Registrarse en el HUB

   Comienza registrándote en el HUB de fiskaly.

   
2. Paso 2: Crear cuenta y GRUPO de organización

   Crear una cuenta de fiskaly es el primer paso, tras el cual puede proceder a configurar la primera estructura organizativa de tu empresa y generar tu clave de API.

   La Cuenta representa al proveedor del sistema de caja o a un comerciante que opera tu propio sistema de caja. Es la organización de nivel superior en la estructura.

   Después de crear tu cuenta de fiskaly, se te llevará al Selector de organización, donde puede crear su Grupo. Un Grupo es un nivel intermedio dentro de una Cuenta que te ayuda a organizar múltiples Unidades en grupos lógicos.

3. Paso 3: Crear clave de API

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

   💡Entornos TEST vs. LIVE

   Las claves de API 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 — Crear token

   Comienza a usar la API E-INVOICE a través del endpoint createToken. Deberás crear un token para autenticarte en los pasos siguientes.

2. Paso 5: MANAGEMENT — Crear una UNIDAD de organización

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

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

3. Paso 6: MANAGEMENT — Crear Subject (clave de API)

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

4. Paso 7: MANAGEMENT — Crear nuevo token

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

5. Paso 8: OPERATION — Crear contribuyente

   Ya está listo para crear los Contribuyentes necesarios para la facturación electrónica. Para ello, utiliza el endpoint createTaxpayer. Deberás establecer el Contribuyente de tipo COMPANY.

   Dependiendo del país, la configuración de fiscalización requerida y los datos del contribuyente necesarios pueden diferir, así que consulta las guías de país específicas:

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

   Una vez que crea un Contribuyente de tipo COMPANY, su state se establecerá en ACQUIRED. Para ser completamente funcional, el estado debe actualizarse a COMMISSIONED utilizando el endpoint updateTaxpayer.

   Al llamar al endpoint createTaxpayer, se crea automáticamente una Ubicación de tipo HEAD_OFFICE. Puede confirmarlo a través del endpoint listLocations.

6. Paso 9: OPERATION — Crear ubicación

   Los nuevos clientes que integran solo facturación electrónica pueden omitir este paso.

   Para la fiscalización de recibos, debe crear una Ubicación de tipo BRANCH a través del endpoint createLocation para cada ubicación de negocio.

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

7. Paso 10: OPERATION — Crear sistema

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

   Dependiendo de tu configuración, se aplica lo siguiente:

   • Nuevos clientes que usan solo facturación electrónica: crea un único Sistema E_INVOICE_SERVICE (solo uno por Contribuyente) y vincúlelo a la Ubicación HEAD_OFFICE que se creó automáticamente para ti en el paso 8.

   • Nuevos clientes que usan fiscalización de recibos y facturación electrónica: crea Sistemas FISCAL_DEVICE para recibos y un Sistema E_INVOICE_SERVICE adicional (uno por Contribuyente). Vincula el Sistema E_INVOICE_SERVICE a la Ubicación de tipo HEAD_OFFICE, y vincula los Sistemas FISCAL_DEVICE a una Ubicación de tipo BRANCH.

   • Clientes existentes con dispositivos fiscales comisionados que añaden facturación electrónica: crea un Sistema E_INVOICE_SERVICE adicional y vincúlelo a la Ubicación de tipo HEAD_OFFICE. Cuando se crea un Contribuyente, se genera automáticamente una Ubicación de tipo HEAD_OFFICE con el mismo ID. Esto puede verificarse listando sus Ubicaciones.

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

   ⚠️Importante

   Tras una solicitud de puesta en servicio exitosa, el Sistema está en estado COMMISSIONED e inicialmente en modo DEGRADED hasta que el Paso 11 se completa por completo.

8. Paso 11: OPERATION — Cargar prueba de propiedad

   Cargue el PDF de la Prueba de propiedad a través del endpoint createRecord, utilizando un Registro de tipo INTENTION y una operación de tipo UPLOAD. El documento enviado es revisado y verificado, lo que puede tardar hasta 72 horas. Una vez completada la verificación, el Sistema pasa automáticamente del modo DEGRADED al modo OPERATIVE.

   Más detalles sobre el contenido requerido del documento se encuentran en la sección Prueba de propiedad.

9. Paso 12: OPERATION — Crear registro

   ⚠️Importante

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

   💡Nota

   Crear un Registro en la API E-INVOICE siempre requerirá 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

   PARTE A) Intención

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

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

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

   Parte B) Transacción

   A continuación, llama nuevamente al endpoint createRecord para crear un Registro de tipo TRANSACTION asociado con el identificador interno de un Registro de tipo INTENTION ya creado. El tipo de operación determina el documento emitido.

   Los siguientes tipos de operación son compatibles:

   • INVOICE: Emite una factura electrónica estándar.

   Una vez que la Transacción se procesa correctamente, la factura electrónica se crea y 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 completarse, de lo contrario la factura electrónica no puede transmitirse. El método de entrega y los campos obligatorios del bloque invoicing varían según el país — consulte los guías de país dedicados a continuación.

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

   • CORRECTION con data.type = INVOICE: Emite una nota de crédito que hace referencia a una factura previamente transmitida. La transacción debe incluir una referencia al documento precedente a la factura original, y el destinatario debe coincidir con el original. Consulte la guía de nota de crédito para obtener flujos de trabajo y reglas detallados.

   💡Nota

   Los Registros CORRECTION::INVOICE solo son aceptados desde un sistema E_INVOICE_SERVICE.

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.

Prueba de propiedad

Conozca el proceso de verificación de documentos.

Referencia de la API

Documentación completa de la API E-INVOICE.