Proceso de integración paso a paso

Esta guía te lleva a través del proceso de integración completo de fiskaly SIGN ES, desde el registro de la cuenta hasta la emisión de tu primera factura firmada. Al final, tendrás un contribuyente, un firmante y un cliente configurados y listos para crear facturas fiscalmente conformes para España.

📘¿Ya utiliza SIGN DE?

Si ya estás integrado con fiskaly SIGN DE, el flujo del proceso fue diseñado para ser coherente entre ambas APIs. Consulta la guía para clientes de SIGN DE para una comparación detallada de diferencias y similitudes entre las dos APIs.

Descripción general

Antes de comenzar con la configuración, esto es lo que necesitará:

🏢

Organización

Su entidad de nivel superior en fiskaly. Las organizaciones gestionadas representan comerciantes individuales.

🔑

Clave API y secreto

Credenciales generadas en HUB, utilizadas para autenticar todas las solicitudes API posteriores.

🧾

Contribuyente

La entidad obligada por las normativas de TicketBAI o Verifactu, con número fiscal y territorio.

🔏

Firmante

Responsable de la firma electrónica de las facturas. Los certificados se gestionan automáticamente.

💻

Cliente

Representa un terminal TPV o dispositivo de facturación que crea facturas a través de un firmante.

📄

Factura

Un registro fiscal firmado. Una vez completada tu configuración, podrás crear facturas conformes.

Requisitos previos

📘Antes de comenzar

Necesitas una cuenta de fiskaly y acceso al fiskaly HUB. Si aún no tienes una cuenta, regístrate aquí.

Para utilizar SIGN ES, necesitarás la siguiente información:

Para el contribuyente obligado por las normativas de TicketBAI o Verifactu:
- Nombre legal
- Número fiscal español (NIF)
- Territorio
- Correo electrónico y dirección
- Adicionalmente, información del representante para empresas
El contenido del documento de factura, incluyendo:
- El detalle de las líneas para todas las transacciones, incluidos los tipos de IVA, cantidad y precio
- La información del destinatario (nombre legal, número de identificación español o internacional, y dirección) para transacciones B2B o B2C enriquecidas

También necesitarás una herramienta para realizar solicitudes HTTP, como cURL (línea de comandos), Postman o su propio código de aplicación.

Flujo de trabajo de integración

El diagrama a continuación ilustra el flujo de trabajo y destaca los pasos esenciales necesarios para completar con éxito tu integración. Cada bloque enlaza directamente con el paso de configuración correspondiente a continuación.

Configuración paso a paso

Registrarse en HUB
Comienza registrándote en fiskaly HUB. Crear una cuenta es el primer paso, tras el cual podrás proceder con la configuración de la estructura organizacional de tu empresa dentro de nuestro sistema.
💡¿No estás listo para producción?
Puedes comenzar con el entorno TEST para explorar la API sin afectar a datos reales. Las claves API generadas en el entorno TEST crearán recursos TEST, mientras que las del entorno LIVE crearán recursos LIVE.
📘Note
De forma predeterminada, tu cuenta comienza en el entorno TEST. Para pasar a producción, contacta con nuestro equipo de ventas para activar el entorno LIVE para tu primera organización. Los recursos creados en el entorno TEST no se transfieren al entorno LIVE. Una vez que tengas al menos una organización LIVE, puedes cambiar organizaciones adicionales a LIVE sin contactar con Ventas. El entorno TEST permanece disponible en todo momento.
Crear la primera organización
Continúa creando tu primera organización a través de HUB. Esta organización representará al proveedor de TPV o al comerciante con tu propio sistema TPV. Deberás incluir una dirección de facturación en esta etapa. Esta dirección solo se utiliza para los fines de facturación de fiskaly. En HUB, esta organización se denomina Group.
Una organización principal representa a un proveedor de TPV o comerciante con tu propio sistema TPV. Una organización gestionada representa a un comerciante. Por ejemplo, si la organización principal es un proveedor de TPV, cada organización gestionada representa a un comerciante individual (contribuyente) con su propio NIF y territorio fiscal.
📘Note
El territorio fiscal relevante está determinado por la dirección legal en la que está registrada la empresa, no por la ubicación física de una tienda.

Crear organización(es) gestionada(s)
Tras establecer tu primera organización, crea organizaciones gestionadas. Cada organización gestionada representa a un comerciante, lo que te permite gestionarlos por separado. En HUB, una organización gestionada se denomina Organization UNIT.
💡Automatizar con la Management API
Si planea incorporar muchos comerciantes, utiliza el endpoint createOrganization de la Management API y pasa el ID de la organización principal en el campo managed_by_organization_id para automatizar el proceso.
Crear clave API
Genera una clave API dentro de cada organización gestionada. Esto se puede hacer a través de HUB (Configuración → Claves API → CREAR CLAVE API) o mediante el endpoint createApiKey de la Management API.
⚠️Guarda tus credenciales de forma segura
El secreto API solo se muestra una vez. Asegúrate de copiarlo y guardarlo en un lugar seguro antes de cerrar el diálogo.
Este par de clave API y secreto es necesario para generar un token de acceso, que se utiliza para todas las llamadas posteriores a la API de SIGN ES. Utiliza las credenciales para obtener un token de acceso antes de continuar. Ten en cuenta que todos los cuerpos de solicitud de SIGN ES utilizan un envoltorio content.
curl -X POST https://test.es.sign.fiskaly.com/api/v1/auth \ -H "Content-Type: application/json" \ -d '{ "content": { "api_key": "your_api_key", "api_secret": "your_api_secret" } }'
La respuesta contiene un access_token que debe incluir como token Bearer en el encabezado Authorization de todas las solicitudes siguientes.

Añadir información del contribuyente

Después de autenticarse, añade la información del contribuyente al sistema. El contribuyente representa la entidad obligada por las normativas de TicketBAI o Verifactu.

curl -X PUT https://test.es.sign.fiskaly.com/api/v1/taxpayer \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "issuer": {
        "tax_number": "B12345678",
        "legal_name": "My Company S.L."
      },
      "territory": "SPAIN_OTHER",
      "sii": {
        "state": "ENABLED"
      }
    }
  }'

const response = await fetch(
  "https://test.es.sign.fiskaly.com/api/v1/taxpayer",
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: {
        issuer: {
          tax_number: "B12345678",
          legal_name: "My Company S.L.",
        },
        territory: "SPAIN_OTHER",
        sii: {
          state: "ENABLED",
        },
      },
    }),
  }
);

⚠️El territorio determina la normativa

Asegúrate de que el campo territory coincida con la dirección legal del contribuyente. SIGN ES aplica la legislación correspondiente automáticamente en función de este valor.

Verifactu: SPAIN_OTHER (España peninsular), CANARY_ISLANDS, CEUTA, MELILLA

TicketBAI: ARABA, BIZKAIA, GIPUZKOA

Actualmente no se aplica ninguna normativa fiscal a NAVARRE.

Este es un paso de cumplimiento para garantizar que todas las facturas generadas estén alineadas con las normativas fiscales y contengan todos los datos necesarios del contribuyente.

Crear firmante
Crea un firmante para cada organización gestionada. El firmante es responsable de la firma electrónica de las facturas.
SIGNER_ID=$(uuidgen) curl -X PUT "https://test.es.sign.fiskaly.com/api/v1/signers/${SIGNER_ID}" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "content": {} }'
Cada firmante requiere un certificado. La gestión del certificado depende de la normativa.
Verifactu: Un certificado electrónico gestionado por fiskaly se asigna automáticamente durante la creación del firmante. fiskaly está registrada como colaboradora social ante la AEAT para Verifactu, para lo cual el contribuyente debe firmar un acuerdo de colaboración social con fiskaly. Consulta Colaboración social para más detalles.
TicketBAI: Un certificado de dispositivo se asigna automáticamente durante la creación del firmante, a menos que proporciones tu propio certificado de dispositivo externo. El certificado se puede recuperar de la respuesta de la API. Si tus clientes están ubicados en el País Vasco, asegúrate de enviarles la guía de registro de fiskaly para que puedan registrar correctamente los certificados de dispositivo ante la autoridad tributaria correspondiente.

Crear clientes

Crea un cliente para cada dispositivo TPV o dispositivo de facturación utilizado dentro de tu organización. El cliente debe estar vinculado a un firmante.

CLIENT_ID=$(uuidgen)

curl -X PUT "https://test.es.sign.fiskaly.com/api/v1/clients/${CLIENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "signer_id": "your-signer-id"
    }
  }'

const clientId = crypto.randomUUID();

const response = await fetch(
  `https://test.es.sign.fiskaly.com/api/v1/clients/${clientId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: {
        signer_id: signerId,
      },
    }),
  }
);

Crear facturas

Con todos los pasos anteriores completados, ya estás listo para crear facturas. Este es el paso final donde las facturas se generan y firman. SIGN ES garantiza que todas las facturas sean conformes con TicketBAI en el País Vasco y con Verifactu en el resto del territorio español.

INVOICE_ID=$(uuidgen)

curl -X PUT "https://test.es.sign.fiskaly.com/api/v1/clients/${CLIENT_ID}/invoices/${INVOICE_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "SIMPLIFIED",
      "number": "INV-001",
      "text": "Sales receipt",
      "full_amount": "12.10",
      "items": [
        {
          "text": "Product A",
          "quantity": "1",
          "unit_amount": "10.00",
          "full_amount": "12.10",
          "system": {
            "type": "REGULAR",
            "rate": "21.00"
          }
        }
      ]
    }
  }'

const invoiceId = crypto.randomUUID();

const response = await fetch(
  `https://test.es.sign.fiskaly.com/api/v1/clients/${clientId}/invoices/${invoiceId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: {
        type: "SIMPLIFIED",
        number: "INV-001",
        text: "Sales receipt",
        full_amount: "12.10",
        items: [
          {
            text: "Product A",
            quantity: "1",
            unit_amount: "10.00",
            full_amount: "12.10",
            system: {
              type: "REGULAR",
              rate: "21.00",
            },
          },
        ],
      },
    }),
  }
);

La respuesta incluye los datos de la factura firmada con toda la información conforme requerida por la normativa fiscal aplicable.

📘Importante

Para el cumplimiento con Verifactu, asegúrate de que el contribuyente haya firmado un acuerdo de colaboración social válido antes de comenzar a emitir facturas. Más información en la sección Colaboración social.

Consulta las normativas de facturación en España para obtener información adicional sobre la creación de facturas.

Recibo digital

Después de crear una factura, puedes generar un recibo digital utilizando el endpoint de recibo digital. La URL devuelta puede mostrarse como código QR al consumidor en el momento del pago, sin necesidad de imprimir un recibo físico. Esto reduce costes, favorece el medio ambiente y añade un nuevo punto de contacto con el cliente para el comerciante.

Para saber más sobre los recibos digitales y cómo mejorar la fidelización del cliente a través del ecosistema de socios de fiskaly, ponte en contacto en sales@fiskaly.com. Consulta la guía de recibos digitales para obtener todos los detalles.

💡Automatizar la configuración

Toda esta secuencia de solicitudes puede integrarse en una solución de aprovisionamiento que no requiera ninguna interacción manual del usuario. Los detalles de implementación dependen de ti.

Próximos pasos

Referencia de la API de SIGN ES

Documentación completa de la API para el endpoint SIGN ES v1: todos los recursos, parámetros y respuestas.

Cumplimiento de facturas

Conozca los requisitos de cumplimiento para las facturas de TicketBAI y Verifactu.

Certificados electrónicos

Comprenda la gestión de certificados, los acuerdos de colaboración social y los certificados de dispositivo.

Glosario

Referencia de términos y conceptos clave utilizados en la documentación de SIGN ES.

Was this page helpful?