Aller au contenu principal
ITICK

PARTENAIRES POS

Documentation d'intégration

Tout ce qu'il faut pour connecter votre solution de caisse à ITICK : une API REST documentée par un contrat OpenAPI public, une clé sandbox remise à l'inscription, des webhooks signés. Aucun frais, aucun abonnement partenaire.

Quickstart : votre premier reçu

Créez votre compte partenaire : votre clé API sandbox est affichée à l'écran dès l'inscription. Elle permet de pousser des reçus de test immédiatement.

Mode simple — un PDF, un email

Vous avez déjà le ticket en PDF ? Envoyez-le tel quel avec l'email du client.

curl -X POST https://api.itick.fr/itick/receipts/providers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer itick_sandbox_VOTRE_CLE" \
  -d '{
    "documentPdf": "JVBERi0xLjQK... (votre PDF encodé en base64)",
    "customerEmail": "client@email.com"
  }'

Mode structuré — ITICK génère la facture

Envoyez les lignes de vente : ITICK produit un document structuré. Dès que items est présent, les champs date, merchantSiret, merchantName, merchantEmail et merchantPhone sont tous requis — l'exemple ci-dessous est complet et accepté tel quel.

curl -X POST https://api.itick.fr/itick/receipts/providers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer itick_sandbox_VOTRE_CLE" \
  -d '{
    "date": "2026-07-03T10:30:00.000Z",
    "merchantSiret": "12345678901234",
    "merchantName": "Boulangerie Dupont",
    "merchantEmail": "contact@boulangerie-dupont.fr",
    "merchantPhone": "+33612345678",
    "customerEmail": "client@email.com",
    "items": [
      { "name": "Baguette tradition", "quantity": 2, "unitPriceHt": 1.14, "vatRate": 5.5 },
      { "name": "Croissant", "quantity": 3, "unitPriceHt": 1.04, "vatRate": 5.5 }
    ]
  }'

Réponse — 201 Created

{
  "receiptId": "8f14e45f-ceea-467f-a1d2-9b6b1c3e5a72",
  "invoiceNumber": "2026-000123",
  "matched": true,
  "totals": {
    "totalHt": 5.40,
    "totalVat": 0.30,
    "totalTtc": 5.70,
    "currency": "EUR",
    "vatBreakdown": [
      { "rate": 5.5, "baseHt": 5.40, "vatAmount": 0.30 }
    ]
  }
}

Authentification

Chaque requête porte votre clé API dans l'en-tête Authorization, au format Bearer :

Authorization: Bearer itick_sandbox_VOTRE_CLE
  • La clé sandbox (préfixe itick_sandbox_) vous est remise une seule fois, à l'inscription. En cas de perte, régénérez-en une depuis votre espace partenaire.
  • La clé de production s'obtient depuis votre espace partenaire, après la checklist de passage en production.
  • Appelez l'API de serveur à serveur uniquement : n'exposez jamais votre clé dans un navigateur ou une application mobile.

Webhooks

Abonnez un endpoint HTTPS depuis votre espace partenaire pour être notifié en temps réel. Quatre événements sont émis :

receipt.createdUn reçu que vous avez poussé est créé dans ITICK.
receipt.updatedUn champ du reçu change (catégorie, montant, statut de paiement…).
receipt.deletedLe reçu est supprimé.
receipt.assignedLe reçu est rattaché à un utilisateur (réclamé via QR ou matché).

En-têtes de livraison

  • X-iTick-Event — type d'événement (ex. receipt.assigned).
  • X-iTick-EventId — identifiant unique de la livraison (idempotence côté receveur).
  • X-iTick-Retry — numéro de la tentative (0 = première).
  • X-iTick-Signature — signature t=<unix>,v1=<hmac> (voir ci-dessous).

Vérifier la signature

Chaque livraison est signée HMAC-SHA256 avec le secret de votre endpoint : la signature couvre `${timestamp}.${corps brut}`. Vérifiez-la avant tout traitement :

const crypto = require('crypto');

// ⚠️ Utilisez le CORPS BRUT de la requête (rawBody), pas l'objet déjà parsé.
function verifyItickWebhook(rawBody, signatureHeader, secret) {
  // Header X-iTick-Signature : "t=<unix>,v1=<hmac>"
  const p = Object.fromEntries(signatureHeader.split(',').map((x) => x.split('=')));
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${p.t}.${rawBody}`)
    .digest('hex');
  const signatureOk = crypto.timingSafeEqual(
    Buffer.from(p.v1), Buffer.from(expected),
  );
  // Rejette les rejeus : le timestamp doit être récent (tolérance 5 min).
  const fresh = Math.abs(Date.now() / 1000 - Number(p.t)) < 300;
  return signatureOk && fresh;
}

En cas d'échec, ITICK réessaie avec un backoff (5 s, 30 s, 2 min, 15 min, 1 h) ; après cinq échecs consécutifs, l'endpoint est désactivé et l'événement marqué en échec définitif (dead-letter), visible avec sa cause dans le journal de votre espace partenaire.

Du sandbox à la production

Le parcours est self-service de bout en bout :

  1. Créez votre compte partenaire : votre clé API sandbox est remise immédiatement, dès l’inscription.
  2. Poussez un premier reçu de test avec le curl du quickstart (mode simple ou mode structuré).
  3. Vérifiez la réponse 201 de l’API : montants, ventilation TVA, rattachement client (matched).
  4. Abonnez un endpoint HTTPS à vos webhooks et vérifiez la signature X-iTick-Signature sur chaque livraison.
  5. Gérez les réponses d’erreur : 400 (champ requis manquant), 401 (clé invalide), 409 (reçu en double), 429 (ralentissez vos appels).
  6. Depuis votre espace partenaire, complétez la checklist « Passer en production » et générez votre clé de production — le passage est self-service.

Contrat OpenAPI & outils

L'API partenaire est décrite par un contrat OpenAPI 3 public. Utilisez-le pour explorer les endpoints ou générer un client dans le langage de votre choix.

Une question ? Écrivez à contact@itick.fr — ou créez votre compte partenaire et testez tout de suite en sandbox.