Para clientes de SIGN ES

Guía de integración de SIGN PT para clientes de SIGN ES

Esta guía ayuda a los equipos que ya han integrado SIGN ES a comprender cómo el mismo flujo de negocio se aplica en SIGN PT utilizando el enfoque API Unificada de fiskaly.

De SIGN ES a SIGN PT

Si ya conoce SIGN ES, muchas partes del flujo te resultarán familiares. Al mismo tiempo, SIGN PT introduce algunas diferencias importantes en la estructura de endpoints, los nombres de recursos y cómo los recursos avanzan en su ciclo de vida.

Resumen comparativo

SIGN ES	SIGN PT / API Unificada	Significado
Organización principal	Organization::GROUP	Representa al integrador (proveedores de software o comerciantes con tu propio sistema de facturación).
Organización gestionada	Organization::UNIT	Representa un NIF (comerciante o contribuyente).
Un contribuyente por organización gestionada	Contribuyente vinculado a uno o más recursos Location::BRANCH	Un contribuyente puede operar desde diferentes ubicaciones comerciales. Location::BRANCH representa ubicaciones individuales de tienda.
signer	gestionado automáticamente	El componente de firma se gestiona automáticamente en el flujo de la API Unificada. El integrador no necesita crear este recurso.
client	System::FISCAL_DEVICE	Los terminales POS/facturación se representan como sistemas en lugar de objetos cliente.
invoice	Record::INTENTION y Record::TRANSACTION	Las facturas o recibos se gestionan como registros, con dos llamadas: INTENTION para indicar la intención de emitir un recibo o factura, y TRANSACTION con el contenido final del recibo o factura.
UUIDs definidos por el cliente	UUIDs asignados automáticamente más X-Idempotency-Key	Ya no se proporcionan UUIDs de recursos directamente; la idempotencia protege contra duplicados.

Antes de comenzar

📘Requisitos previos

Necesita una cuenta de fiskaly y acceso al fiskaly HUB. También necesitará una herramienta para realizar solicitudes HTTP, como cURL, Postman o su propio código de aplicación.

Si ya integró SIGN ES, el flujo de negocio te resultará familiar, pero la configuración es más explícita en SIGN PT y utiliza el modelo de recursos de la API Unificada. Con esta integración, desbloqueará varios países con una sola integración.

Antes de comenzar, es útil pensar en términos de los recursos que configurará:

• Organization — un GROUP para la estructura de nivel superior y una o más organizaciones UNIT para comerciantes o contribuyentes individuales.
• API Key y Token — credenciales creadas en HUB y luego intercambiadas por tokens utilizados en el flujo de la API Unificada.
• Taxpayer — un recurso COMPANY o INDIVIDUAL que representa la entidad legal que emite documentos fiscales.
• Location — un recurso BRANCH para cada tienda física o sitio operativo.
• System — un recurso FISCAL_DEVICE que representa el POS o dispositivo fiscal que emite documentos.
• Record — un flujo fiscal en dos partes que usa INTENTION y TRANSACTION en lugar de crear facturas directamente.

Flujo de integración

Paso	Qué hace	Por qué existe
1. Registrarse en HUB	Crea tu cuenta de fiskaly en HUB	Este es el punto de entrada para configurar tu organización y credenciales de API.
2. Crear tu primera organización	Crea tu primera Organization::GROUP en HUB	Esto representa al proveedor POS o comerciante en el nivel superior. Después de este paso, crea una clave API para esa organización en HUB.
3. Crear una clave API	Genera una clave API y un secreto para el grupo en HUB	Necesita estas credenciales para autenticarte y continuar la configuración.
4. Crear un token	Llamar a createToken	Este token se usa para las siguientes solicitudes de API.
5. Crear una organización UNIT	Crear una Organization::UNIT por contribuyente	Esto reemplaza el antiguo concepto de organización gestionada.
6. Crear una clave API de sujeto	Llamar a createSubject con X-Scope-Identifier	Esto vincula una clave API a la Organization::UNIT correcta.
7. Crear un token con ámbito	Crear un segundo token para el ámbito de la unidad	Este token se usa para recursos a nivel de contribuyente y recursos operativos.
8. Crear el contribuyente	Crear un Taxpayer::COMPANY o Taxpayer::INDIVIDUAL	Esto representa la entidad legal que emite los documentos fiscales.
9. Crear la ubicación	Crear un Location::BRANCH para cada tienda o sitio operativo	Esto hace explícita cada ubicación comercial en el modelo.
10. Crear el sistema	Crear un System::FISCAL_DEVICE y cualquier sistema POS relacionado	Esto reemplaza la configuración de signer y client.
11. Crear el registro fiscal	Crear la operación fiscal como registros	Esto reemplaza el flujo orientado a facturas de SIGN ES.

Traducción práctica

Para una integración SIGN ES existente, la forma más clara de traducir su modelo es:

• managed organization se convierte en Organization::UNIT
• taxpayer tendrá uno o más recursos Location::BRANCH conectados, dependiendo del número de ubicaciones comerciales
• signer es gestionado automáticamente por el flujo de la API Unificada
• client se convierte en System::FISCAL_DEVICE
• invoice se convierte en un Record

Comportamiento de los recursos

Una diferencia importante en comparación con SIGN ES es cómo los recursos operativos se vuelven utilizables.

En SIGN ES, los recursos clave generalmente están listos para usar inmediatamente después de ser creados.

En SIGN PT, recursos como Taxpayer, Location y System siguen un ciclo de vida:

• primero se crean en estado ACQUIRED
• luego deben actualizarse a COMMISSIONED
• solo después están listos para uso operativo

Esto significa que el flujo de configuración incluye un paso de activación explícito para recursos que son inmediatamente utilizables en SIGN ES.

Estados y modos de Record

Un Record atraviesa diferentes estados y modos durante su ciclo de vida. Algunos cambios ocurren cuando llama a la API, y otros ocurren automáticamente mientras el sistema procesa el Record.

SIGN PT

Estados

Estado UAPI	Significado	Equivalente en SIGN ES
Accepted	El Record fue recibido correctamente y está siendo procesado	Factura creada exitosamente (ISSUED) y lista para transmitir — equivalente a una respuesta 200 OK en SIGN ES.
Rejected	El Record falló y no se procesará más	La creación de factura falla, no se almacena ninguna factura — equivalente a una respuesta de error 400 o 500 en SIGN ES.
Completad	El Record fue procesado exitosamente por la autoridad correspondiente	Factura aceptada por la autoridad fiscal — equivalente al estado de registro REGISTERED en SIGN ES.
Failed	El Record no pudo ser procesado por la autoridad correspondiente	Factura enviada pero rechazada o aceptada con errores por la autoridad fiscal — equivalente al estado de registro REQUIRES_INSPECTION o REQUIRES_CORRECTION en SIGN ES.

Modos

Modo UAPI	Significado	Equivalente en SIGN ES
Processing	El Record está siendo procesado (entre la creación y cualquier estado final)	Factura ISSUED y en espera de respuesta de la agencia fiscal — equivalente al estado de registro PENDING en SIGN ES.
Finished	El procesamiento está completo; el estado es ahora Completad, Failed o Rejected	La factura tiene un estado de registro final: REGISTERED, REQUIRES_CORRECTING o REQUIRES_INSPECTION.