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 conforme. 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.created | Un reçu que vous avez poussé est créé et certifié. |
| receipt.updated | Un champ du reçu change (catégorie, montant, statut de paiement…). |
| receipt.deleted | Le reçu est supprimé. |
| receipt.assigned | Le 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— signaturet=<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 :
- Créez votre compte partenaire : votre clé API sandbox est remise immédiatement, dès l’inscription.
- Poussez un premier reçu de test avec le curl du quickstart (mode simple ou mode structuré).
- Vérifiez la réponse 201 de l’API : montants, ventilation TVA, rattachement client (matched).
- Abonnez un endpoint HTTPS à vos webhooks et vérifiez la signature X-iTick-Signature sur chaque livraison.
- Gérez les réponses d’erreur : 400 (champ requis manquant), 401 (clé invalide), 409 (reçu en double), 429 (ralentissez vos appels).
- 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.
- Documentation interactive : https://api.itick.fr/itick/partner/docs
- Spécification brute (YAML) : https://api.itick.fr/itick/partner/docs/spec.yml
- Version Markdown (pour vos outils et assistants IA) — cette page, en texte brut, ainsi qu'un llms.txt.
Une question ? Écrivez à support@itick.fr — ou créez votre compte partenaire et testez tout de suite en sandbox.