Processus d'intégration étape par étape

Ce guide vous accompagne tout au long du processus d’intégration complet de fiskaly SIGN ES, de l’enregistrement du compte à l’émission de votre première facture signée. À la fin, vous aurez configuré un contribuable, un signataire et un client prêts à créer des factures fiscalement conformes pour l’Espagne.

📘Déjà intégré avec SIGN DE ?

Si vous êtes déjà intégré avec fiskaly SIGN DE, le flux du processus a été conçu pour être cohérent entre les deux APIs. Consultez le guide pour les clients SIGN DE pour une comparaison détaillée des différences et similitudes entre les deux APIs.

Vue d’ensemble

Avant de commencer la configuration, voici ce dont vous aurez besoin :

🏢

Organisation

Votre entité de niveau supérieur chez fiskaly. Les organisations gérées représentent des commerçants individuels.

🔑

Clé API et secret

Identifiants générés dans HUB, utilisés pour authentifier toutes les requêtes API suivantes.

🧾

Contribuable

L'entité soumise aux réglementations TicketBAI ou Verifactu, avec numéro fiscal et territoire.

🔏

Signataire

Responsable de la signature électronique des factures. Les certificats sont gérés automatiquement.

💻

Client

Représente un terminal de point de vente ou un appareil de facturation qui crée des factures via un signataire.

📄

Facture

Un enregistrement fiscal signé. Une fois votre configuration terminée, vous pouvez créer des factures conformes.

Prérequis

📘Avant de commencer

Vous avez besoin d’un compte fiskaly et d’un accès au fiskaly HUB. Si vous n’avez pas encore de compte, inscrivez-vous ici.

Pour utiliser SIGN ES, vous aurez besoin des informations suivantes :

Pour le contribuable soumis aux réglementations TicketBAI ou Verifactu :
- Raison sociale
- Numéro fiscal espagnol (NIF)
- Territoire
- Email et adresse
- En outre, les informations du représentant pour les sociétés
Le contenu du document de facture, notamment :
- Le détail des lignes pour toutes les transactions, y compris les taux de TVA, la quantité et le prix
- Les informations sur le destinataire (raison sociale, numéro d’identification espagnol ou international, et adresse) pour les transactions B2B ou B2C enrichies

Vous aurez également besoin d’un outil pour effectuer des requêtes HTTP, par exemple cURL (ligne de commande), Postman ou votre propre code d’application.

Flux de travail d’intégration

Le diagramme ci-dessous illustre le flux de travail et met en évidence les étapes essentielles nécessaires pour réussir votre intégration. Chaque case renvoie directement à l’étape de configuration correspondante ci-dessous.

Configuration étape par étape

S'inscrire sur HUB
Commencez par vous inscrire sur fiskaly HUB. La création d’un compte est la première étape, après laquelle vous pouvez procéder à la configuration de la structure organisationnelle de votre entreprise dans notre système.
💡Pas encore prêt pour la production ?
Vous pouvez commencer avec l’environnement TEST pour explorer l’API sans affecter les données réelles. Les clés API générées dans l’environnement TEST créeront des ressources TEST, tandis que celles de l’environnement LIVE créeront des ressources LIVE.
📘Note
Par défaut, votre compte démarre dans l’environnement TEST. Pour passer en production, contactez notre équipe commerciale pour activer l’environnement LIVE pour votre première organisation. Les ressources créées dans l’environnement TEST ne sont pas transférées vers l’environnement LIVE. Une fois que vous avez au moins une organisation LIVE, vous pouvez basculer d’autres organisations en LIVE sans contacter les Ventes. L’environnement TEST reste disponible en permanence.
Créer la première organisation
Continuez en créant votre première organisation via HUB. Cette organisation représentera le fournisseur de point de vente ou le commerçant avec son propre système de point de vente. Vous devrez inclure une adresse de facturation à ce stade. Cette adresse est uniquement utilisée à des fins de facturation par fiskaly. Dans HUB, cette organisation est appelée Group.
Une organisation principale représente un fournisseur de point de vente ou un commerçant avec son propre système de point de vente. Une organisation gérée représente un commerçant. Par exemple, si l’organisation principale est un fournisseur de point de vente, chaque organisation gérée représente un commerçant individuel (contribuable) avec son propre NIF et territoire fiscal.
📘Note
Le territoire fiscal pertinent est déterminé par l’adresse légale à laquelle l’entreprise est enregistrée, et non par l’emplacement physique d’un magasin.

Créer une ou plusieurs organisations gérées
Après avoir établi votre première organisation, créez des organisations gérées. Chaque organisation gérée représente un commerçant, vous permettant de les gérer séparément. Dans HUB, une organisation gérée est appelée Organization UNIT.
💡Automatiser avec la Management API
Si vous prévoyez d’intégrer de nombreux commerçants, utilisez l’endpoint createOrganization de la Management API et passez l’ID de l’organisation principale dans le champ managed_by_organization_id pour automatiser le processus.
Créer une clé API
Générez une clé API au sein de chaque organisation gérée. Cela peut être fait via HUB (Paramètres → Clés API → CRÉER UNE CLÉ API) ou via l’endpoint createApiKey de la Management API.
⚠️Conservez vos identifiants en toute sécurité
Le secret API n’est affiché qu’une seule fois. Assurez-vous de le copier et de le stocker dans un endroit sécurisé avant de fermer la boîte de dialogue.
Cette paire de clé API et secret est nécessaire pour générer un token d’accès, utilisé pour tous les appels API SIGN ES suivants. Utilisez les identifiants pour obtenir un token d’accès avant de continuer. Notez que tous les corps de requête SIGN ES utilisent un wrapper 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 réponse contient un access_token que vous devez inclure comme token Bearer dans l’en-tête Authorization de toutes les requêtes suivantes.

Ajouter les informations du contribuable

Après l’authentification, ajoutez les informations du contribuable dans le système. Le contribuable représente l’entité soumise aux réglementations TicketBAI ou 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",
        },
      },
    }),
  }
);

⚠️Le territoire détermine la réglementation

Assurez-vous que le champ territory correspond à l’adresse légale du contribuable. SIGN ES applique automatiquement la législation correspondante en fonction de cette valeur.

Verifactu : SPAIN_OTHER (Espagne continentale), CANARY_ISLANDS, CEUTA, MELILLA

TicketBAI : ARABA, BIZKAIA, GIPUZKOA

Aucune réglementation fiscale ne s’applique actuellement à NAVARRE.

Il s’agit d’une étape de conformité pour garantir que toutes les factures générées sont conformes aux réglementations fiscales et contiennent toutes les informations nécessaires sur le contribuable.

Créer le signataire
Créez un signataire pour chaque organisation gérée. Le signataire est responsable de la signature électronique des factures.
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": {} }'
Chaque signataire nécessite un certificat. La gestion du certificat dépend de la réglementation.
Verifactu : Un certificat électronique géré par fiskaly est automatiquement attribué lors de la création du signataire. fiskaly est enregistré en tant que collaborateur social auprès de l’AEAT pour Verifactu, ce qui nécessite que le contribuable signe un accord de collaboration sociale avec fiskaly. Voir Collaboration sociale pour plus de détails.
TicketBAI : Un certificat dispositif est automatiquement attribué lors de la création du signataire, sauf si vous fournissez votre propre certificat dispositif externe. Le certificat peut être récupéré depuis la réponse API. Si vos clients sont situés au Pays Basque, assurez-vous de leur envoyer le guide d’enregistrement de fiskaly afin qu’ils puissent enregistrer correctement les certificats dispositifs auprès de l’autorité fiscale compétente.

Créer les clients

Créez un client pour chaque terminal de point de vente ou appareil de facturation utilisé au sein de votre organisation. Le client doit être lié à un signataire.

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,
      },
    }),
  }
);

Créer des factures

Avec toutes les étapes précédentes complétées, vous êtes maintenant prêt à créer des factures. C’est l’étape finale où les factures sont générées et signées. SIGN ES garantit que toutes les factures sont conformes à TicketBAI au Pays Basque et à Verifactu dans le reste du territoire espagnol.

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 réponse inclut les données de la facture signée avec toutes les informations conformes requises par la réglementation fiscale applicable.

📘Important

Pour la conformité avec Verifactu, assurez-vous qu’un accord de collaboration sociale valide est signé par le contribuable avant de commencer à émettre des factures. Plus d’informations dans la section Collaboration sociale.

Veuillez consulter les réglementations de facturation en Espagne pour des informations supplémentaires sur la création de factures.

Reçu numérique

Après avoir créé une facture, vous pouvez générer un reçu numérique en utilisant l’endpoint de reçu numérique. L’URL renvoyée peut être affichée comme code QR au consommateur lors du passage en caisse, sans avoir à imprimer un reçu physique. Cela réduit les coûts, soutient l’environnement et ajoute un nouveau point de contact client pour le commerçant.

Pour en savoir plus sur les reçus numériques et sur la façon d’améliorer la fidélisation des clients grâce à l’écosystème de partenaires fiskaly, contactez-nous à sales@fiskaly.com. Consultez le guide des reçus numériques pour tous les détails.

💡Automatiser la configuration

Toute cette séquence de requêtes peut être intégrée dans une solution de provisionnement ne nécessitant aucune interaction manuelle de l’utilisateur. Les détails d’implémentation vous appartiennent.

Prochaines étapes

Référence API SIGN ES

Documentation API complète pour l'endpoint SIGN ES v1 : toutes les ressources, paramètres et réponses.

Conformité des factures

Découvrez les exigences de conformité pour les factures TicketBAI et Verifactu.

Certificats électroniques

Comprenez la gestion des certificats, les accords de collaboration sociale et les certificats dispositifs.

Glossaire

Référence des termes et concepts clés utilisés dans la documentation SIGN ES.

Was this page helpful?