Integración paso a paso

📘Note

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

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 API SIGN PT.

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 API SIGN PT.

   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.

   Los tokens son JWT de corta duración que autentican cada llamada SIGN PT posterior. Se obtienen por ámbito de Cuenta u Organización.

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

   Utilice el endpoint createTaxpayer de la API SIGN PT 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). En ambos casos, se debe proporcionar el nombre y la dirección.
   • Dentro de la información de fiscalización portuguesa, se deben proporcionar al menos los siguientes datos del contribuyente:
     • tax_id_number: el NIF (Número de Identificação Fiscal) portugués del contribuyente. 9 dígitos, sin espacios ni separadores (p. ej. 501234567).
     • credentials: las credenciales de subusuario AT que SIGN PT utilizará para llamar a los servicios web AT en nombre de este contribuyente:
       • Nombre de usuario: el identificador del subusuario en formato <NIF>/<subuser-id> (p. ej. 501234567/5), tal como lo emite el Portal das Finanças.
       • Contraseña: la contraseña establecida para ese subusuario.

   Estas no son las credenciales principales del Portal das Finanças del comerciante. Deben ser un subusuario dedicado creado específicamente para el acceso al servicio web — vea la nota Importante a continuación.

   ⚠️Importante

   El uso de Servicios Web AT a través de SIGN PT requiere una configuración previa en el Portal das Finanças por parte del contribuyente o su representante legal: se debe crear un subusuario dedicado de Servicio Web, se le deben otorgar los permisos requeridos (p. ej. WSE, WFA, WDT) y se deben aceptar los términos y condiciones AT aplicables.

   Para instrucciones paso a paso sobre cómo crear el subusuario, consulte Crear el subusuario en el Portal das Finanças.

   Una vez que crea un Taxpayer, ya sea de tipo Company o Individual, 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 junto con el contribuyente. 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 (ERS) 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 de tipo BRANCH, creada previamente.

   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.

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 puede realizar una de las siguientes operaciones:

   • INVOICE/RECEIPT: Representa la venta de un bien o servicio, incluyendo detalles del documento (número de documento, código de actividad, fecha de transacción, importes totales incl. y excl. IVA) y líneas de artículos (cada línea tiene un entries[].type como SALE, descripción, si es un GOOD o SERVICE, etc.).
   • CORRECTION: Emite un documento correctivo (NC para crédito / ND para débito) haciendo referencia a un INVOICE/RECEIPT creado previamente. Contiene las líneas corregidas y una reference_id al documento original.
   • CANCELLATION: Se utiliza para invalidar una transacción completa. Requiere el id de un record creado previamente.

   Tras enviar el Record TRANSACTION, SIGN PT realiza los pasos de emisión conforme para la operación seleccionada: asigna el siguiente número secuencial de la serie (los números no se preasignan), firma y encadena el documento, y genera los datos necesarios para la representación final orientada al cliente.

   Según la configuración de comunicación del Contribuyente, los mismos datos de transacción se incluyen entonces:

   • en la comunicación/exportación SAF-T (PT) (para envío mensual), y/o
   • comunicados a AT a través de servicios web (p. ej., facturas a través de WFA; documentos de transporte a través de WDT, si corresponde y se otorgaron permisos).

   Una vez finalizado el procesamiento, SIGN PT devuelve (a través de la respuesta del Record y/o artefactos recuperables del Record):

   • el payload de cumplimiento requerido para la impresión (p. ej., ATCUD, contenido del código QR, el fragmento hash y el número de certificado del software)
   • los datos del documento firmado/encadenado necesarios para construir la representación final del recibo/factura, y
   • información de estado de procesamiento del Record (éxito/fallo y detalles de error relevantes).

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