Integración paso a paso

⚠️Vista previa

SIGN ES (Unified API) está actualmente disponible en el entorno de prueba para el desarrollo y las pruebas iniciales, aunque en esta etapa solo se puede probar un conjunto limitado de opciones. La producción aún no está activada. Para uso en producción, utilice la API Especializada SIGN ES.

Para comenzar el proceso de integración, consulte las instrucciones detalladas paso a paso proporcionadas aquí.

El diagrama adjunto ilustra el flujo de trabajo y destaca los pasos esenciales necesarios para completar con éxito su integración, para los cuales necesitará utilizar nuestra SIGN ES (Unified API).

1. Registrarse en HUB

   Comience registrándose en el fiskaly HUB. Para más orientación sobre cómo empezar, diríjase a nuestra sección HUB - Primeros pasos.

2. Crear Cuenta y Organización GROUP

   Crear una Cuenta fiskaly es el primer paso, tras el cual puede proceder a configurar la primera estructura organizativa para su negocio y generar su Clave de API.

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

   Después de crear su Cuenta fiskaly, accederá al Selector de Organización donde podrá crear su Grupo.

   Un Grupo es un nivel intermedio dentro de una Cuenta que le ayuda a organizar múltiples Units en grupos lógicos.

3. Crear Clave de API

   El siguiente paso es generar una Clave de API para su organización a través del HUB. Este par de Clave de API y Secret es necesario para crear su 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. Crear Token

   A partir de este paso, utilizará la SIGN ES (Unified API).

   Llame al endpoint createToken con la Clave de API y el Secret del paso 3 para obtener un token bearer. Incluya este token en el encabezado Authorization de los pasos 5 y 6.

2. Crear Organización UNIT

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

   El uso del token bearer generado en el Paso 4 con la Clave de API y el Secret creados para su Grupo garantiza que la UNIT quede correctamente anidada bajo ese Grupo en la jerarquía.

3. Crear Subject (Clave de API)

   Cree un Subject de tipo API_KEY para la Organización UNIT a través del endpoint createSubject.

   Para asociar el Subject (Clave de API) con su UNIT, incluya el encabezado X-Scope-Identifier con el id de la Organización UNIT en su solicitud.

4. Crear nuevo Token

   Cree un token usando la Clave de API Subject y el Secret que acaba de generar. Este token bearer se utilizará para todos los pasos posteriores para crear recursos dentro de la Organización UNIT correspondiente.

1. Crear Contribuyente

   Ahora está listo para empezar a crear las partes operativas requeridas para la fiscalización en España.

   Utilice el endpoint createTaxpayer para crear la representación de un contribuyente de la siguiente manera:

   • Establezca el contribuyente como tipo Company (persona jurídica) o Individual (persona física).
   • Proporcione el NIF (Número de Identificación Fiscal) español del contribuyente.
   • El territorio fiscal del contribuyente determina si aplica Verifactu, SII o TicketBAI — consulte la introducción a SIGN ES para ver cómo estas normativas se aplican a los territorios españoles.

   Una vez que crea un Taxpayer, su estado se establece en ACQUIRED de forma predeterminada. Para hacerlo completamente funcional, actualice el estado a COMMISSIONED usando el endpoint updateTaxpayer.

2. Crear Ubicación

   📘Note

   Una ubicación HEAD_OFFICE se crea automáticamente al crear el Taxpayer y comparte el mismo UUID que el Taxpayer. Sin embargo, para fines de fiscalización, recomendamos crear una ubicación separada de tipo BRANCH (puede tener la misma dirección). Si hay múltiples ubicaciones, se debe crear una rama correspondiente para cada una.

   Para cada ubicación comercial operativa, cree una Ubicación de tipo BRANCH a través del endpoint createLocation.

   Una vez creada una Ubicación, su estado se establece en ACQUIRED de forma predeterminada. Actualice el estado a COMMISSIONED usando el endpoint updateLocation antes de continuar.

3. Crear Sistema

   El endpoint createSystem le permite crear una abstracción de cada Sistema de Registro Electrónico utilizado para operaciones fiscales. Cada caja registradora o punto de venta debe proporcionarse como un nuevo Sistema de tipo FISCAL_DEVICE.

   • Un Sistema se conectará a una Ubicación específica, previamente creada, de tipo BRANCH.

   Una vez creado un Sistema, su estado se establece en ACQUIRED de forma predeterminada. Para crear Registros, su estado debe actualizarse a COMMISSIONED usando el endpoint updateSystem.

   📘Nota sobre la facturación

   Para la mayoría de los contratos, los System son las unidades utilizadas para la facturación con fiskaly. Un System pasa a ser relevante para la facturación en cuanto su estado cambia de ACQUIRED a COMMISSIONED en el entorno LIVE. Los recursos en el entorno TEST no se facturan. Para conocer las condiciones exactas de facturación, consulte su contrato con fiskaly.

4. Crear Registro

   Para cada operación comercial realizada en el Sistema, el endpoint createRecord debe llamarse dos veces en secuencia: primero para registrar la intención de iniciar una transacción, y luego para proporcionar los datos de la transacción.

   Parte A) Intention

   Un Record de tipo INTENTION contiene la asociación con el Sistema que llevará a cabo la transacción y una Operation de tipo TRANSACTION, que representa la intención del Sistema de registrar una transacción.

   Parte B) Transaction

   Un Record de tipo TRANSACTION está asociado con la INTENTION creada previamente y contiene los datos de la transacción, que luego se firman y transmiten según la normativa aplicable al contribuyente (Verifactu, SII o TicketBAI).

   📘Note

   Todos los Records creados en el entorno LIVE representan documentos fiscalmente relevantes y siempre deben reflejar transacciones reales. Utilice el entorno TEST designado para las pruebas de integración.