Ir al contenido

Integración Paso a Paso

Para comenzar el proceso de integración, consulta las instrucciones detalladas paso a paso que se proporcionan aquí.

El diagrama adjunto ilustra el flujo de trabajo y destaca los pasos esenciales necesarios para completar con éxito tu integración, para la cual necesitará utilizar nuestra SIGN IT.

SIGN IT workflow

Paso 1: Registrarse en el Dashboard

Sección titulada «Paso 1: Registrarse en el Dashboard»

Comienza registrándote en el Dashboard.

Register on the Dashboard

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

Paso 2: Crear la primera organización

Sección titulada «Paso 2: Crear la primera organización»

Continúa creando tu primera organización utilizando el Dashboard. Esta organización representará al proveedor de POS o al comerciante con tu propio sistema de POS.

Paso 3: Crear una API Key

Sección titulada «Paso 3: Crear una API Key»

El siguiente paso es generar una API Key para tu organización a través del Dashboard. Este par de clave y secreto API es necesario para crear su primer Asset de tipo UNIT (Paso 5).

Ten en cuenta que las API Keys generadas en el entorno TEST crearán recursos TEST, mientras que las del entorno LIVE crearán recursos LIVE. Para más detalles, consulta nuestro artículo sobre entornos TEST y LIVE.

A partir del siguiente paso, utilizará nuestra API SIGN IT. Puede descargar nuestra colección Postman para SIGN IT, que puede facilitar tu integración en los pasos siguientes.

Paso 4: MANAGEMENT - Crear Token

Sección titulada «Paso 4: MANAGEMENT - Crear Token»

Comienza a utilizar la API SIGN IT a través del endpoint createToken. Deberás crear un token para autenticarte en los pasos siguientes.

Paso 5: MANAGEMENT - Crear Asset UNIT

Sección titulada «Paso 5: MANAGEMENT - Crear Asset UNIT»

Continúa creando un Asset de tipo UNIT a través del endpoint createAsset. Deberás crear un Asset UNIT para cada una de sus representaciones de contribuyentes.

Al crear su primer Asset de tipo UNIT, asegúrate de que esté asociado al UUID de la primera organización que creó a través del Dashboard. Para ello, utiliza el token generado a partir de las API Keys creadas en la primera organización. Esto refleja la estructura jerárquica donde el UNIT está anidado bajo la primera organización.

Paso 6: MANAGEMENT - Crear Subject (Clave API)

Sección titulada «Paso 6: MANAGEMENT - Crear Subject (Clave API)»

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

Paso 7: MANAGEMENT - Crear nuevo Token

Sección titulada «Paso 7: MANAGEMENT - Crear nuevo Token»

A continuación, crea un token que se utilizará para crear recursos dentro del Asset UNIT correspondiente.

Paso 8: OPERATION - Crear Entity COMPANY o INDIVIDUAL

Sección titulada «Paso 8: OPERATION - Crear Entity COMPANY o INDIVIDUAL»

Ahora está listo para empezar a crear las partes operativas necesarias para la fiscalización en Italia. Para ello, utiliza el endpoint createEntity para crear la representación de un Contribuyente de la siguiente manera:

  • Deberás establecer el Contribuyente como una Entity de tipo Company (persona jurídica) o Individual (persona física). En ambos casos, se deben proporcionar el name y la address.
  • Dentro de la información fiscalization italiana, se deben proporcionar los siguientes datos del contribuyente:
    • tax_id_number: Código Fiscal italiano (Codice fiscale),
    • vat_id_number: Número de IVA italiano (Partita IVA),
    • credentials: pin y contraseña necesarios para acceder a los servicios de AdE. Para más información, consulta nuestra sección de Credenciales.

Una vez que crea una Entity, ya sea de tipo Company o Individual, su state se establecerá en ACQUIRED. Para que sea totalmente funcional, el estado debe actualizarse a COMMISSIONED utilizando el endpoint updateEntity.

Paso 9: OPERATION - Crear Entity LOCATION

Sección titulada «Paso 9: OPERATION - Crear Entity LOCATION»

Para cada ubicación de negocio operativa, debe crear una Entity de tipo Location a través del endpoint createEntity.

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

Paso 10: OPERATION - Crear System

Sección titulada «Paso 10: OPERATION - Crear System»

El endpoint createSystem te permite crear una abstracción de cada dispositivo que utiliza para emitir recibos. Esto significa que cada caja registradora o punto de venta debe proporcionarse como un nuevo System en la API SIGN IT. Para ello, se debe seleccionar el tipo de Sistema FISCAL_DEVICE.

  • Un System se conectará a una Entity ya creada (ya sea de tipo Company o Individual, o una Location específica si es diferente a la dirección legal).
  • Para cada dispositivo, deberás proporcionar información del producto como MPN, marca y la fecha de inicio de uso, junto con el nombre y la versión del software instalado en el dispositivo. Esta información garantiza el seguimiento correcto del dispositivo que realiza las transacciones fiscales.

Cuando crea un System, su estado inicial se establece en ACQUIRED. Para crear Registros, su state debe actualizarse a COMMISSIONED utilizando el endpoint updateSystem.

Paso 11: OPERATION - Crear Registro

Sección titulada «Paso 11: OPERATION - Crear Registro»
PARTE A) Intention

Para cada operación comercial realizada en la caja registradora o POS, se utilizará el endpoint createRecord de la API SIGN IT en dos llamadas: la primera para registrar la intención de iniciar una transacción, y la segunda para proporcionar los datos de la transacción.

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

  • Asociación con un System que llevará a cabo la transacción.
  • Operación de tipo Transaction: Esto significa que la operación que el System pretende realizar es registrar una transacción.
Parte B) Transaction

El paso final para emitir un recibo conforme en Italia es realizar otra llamada al endpoint createRecord, indicando un Registro de tipo Transaction.

Cualquier documento de Transaction estará asociado al identificador interno de un Registro de tipo Intention ya creado, y puede contener detalles para fines de formación (documentos emitidos en modo de formación o prueba).

La Transaction puede utilizarse para llevar a cabo una de las siguientes operaciones en Italia:

  • RECEIPT: Esta operación contiene toda la información necesaria para la creación de un Documento comercial de ventas en Italia:
    • Información del documento como número, código de actividad (si procede), fecha de la transacción e importes totales del documento (con y sin IVA)
    • Información de cada entrada o línea de artículo vendido en la operación:
      • Identificación de una Venta
      • Descripción
      • Indicación de si es un bien o servicio
  • CORRECTION: Este tipo de operación se utiliza para representar cualquier proceso de devolución realizado. Contiene los mismos datos que una operación de tipo RECEIPT, y adicionalmente:
    • id de referencia a un recibo ya creado (documento de transacción original)
  • CANCELLATION: Esta operación se utiliza para invalidar una transacción completa. Para ello, se debe proporcionar el id de un registro previamente creado.

En todos los casos, una vez que la transacción se registra correctamente y la información del documento comercial se transmite con éxito al portal web de AdE, la respuesta conforme de la creación del registro indicará el número progresivo asignado por AdE al documento comercial y el Código de Lotería del consumidor (si se proporcionó en el payload transmitido).

Was this page helpful?