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 correctamente tu integración, para lo cual deberás utilizar nuestra SIGN IT.

SIGN IT workflow

Paso 1: Registrarse en el Dashboard

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

Comienza por registrarse en el Dashboard.

Register on the Dashboard

Crear una cuenta fiskaly es el primer paso, tras lo 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 mediante el Dashboard. Esta organización representará al proveedor de POS o comerciante con tu propio sistema POS.

Paso 3: Crear la API Key

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

El siguiente paso es generar una API Key para tu organización a través del Dashboard. Este par de API Key y secreto 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 podría facilitar tu integración en los siguientes pasos.

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 siguientes pasos.

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 contribuyente.

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 la UNIT está anidada 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 comenzar a crear las partes operativas requeridas 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 configurar el Contribuyente como una Entity de tipo Company (entidad legal) o Individual (persona física). En ambos casos, se deben proporcionar name y address.
  • Dentro de la información de 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 la AdE. Para más información, consulta nuestra sección de Credenciales.

Una vez que crea una Entity de tipo Company o Individual, su state se establecerá en ACQUIRED. Para que sea completamente 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, debe seleccionarse el tipo de System FISCAL_DEVICE.

  • Un System se conectará a una Entity ya creada (ya sea de tipo Company o Individual, o una Ubicación específica si difiere de la dirección legal).
  • Para cada dispositivo, deberás proporcionar información del producto como MPN, marca y 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 adecuado del dispositivo que realiza transacciones fiscales.

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

Paso 11: OPERATION - Crear Record

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

Para cada operación comercial realizada en la caja registradora o POS, el endpoint createRecord de la API SIGN IT se utilizará 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 Record 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 Record de tipo Transaction.

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

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

  • RECEIPT: Esta operación contiene toda la información requerida para la creación de un documento comercial de Ventas en Italia:
    • Información del documento como número, código de actividad (si aplica), fecha de transacción y montos totales del documento (incluyendo y excluyendo 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 usa 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 usa para invalidar una transacción completa. Para esto, se debe proporcionar el id de un registro previamente creado.

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

Was this page helpful?