# Documentation d'intégration — API partenaire ITICK (POS)

> Version Markdown de la page https://itick.fr/partenaires/documentation, destinée à vos outils et à vos assistants IA. Même contenu, même source que la page web : les exemples ci-dessous sont ceux de la page, mot pour mot (un test l'impose à chaque changement).

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.

- Créer un compte partenaire : https://itick.fr/partenaires/inscription
- Contrat OpenAPI (documentation interactive) : https://api.itick.fr/itick/partner/docs
- Spécification brute (YAML) : https://api.itick.fr/itick/partner/docs/spec.yml
- Base de l'API : `https://api.itick.fr/itick`

## Quickstart : votre premier reçu

Créez votre compte partenaire (https://itick.fr/partenaires/inscription) : 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.

```bash
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.

Champs requis du mode structuré : `date`, `merchantSiret`, `merchantName`, `merchantEmail`, `merchantPhone`, `items`.

```bash
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

```json
{
  "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 :

| Événement | Description |
| --- | --- |
| `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` — 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 :

```js
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.

- Documentation interactive : https://api.itick.fr/itick/partner/docs
- Spécification brute (YAML) : https://api.itick.fr/itick/partner/docs/spec.yml

### Importer le contrat dans Postman / générer un client

- **Postman** : *Import* → *Link* → collez l'URL de la spécification (`https://api.itick.fr/itick/partner/docs/spec.yml`, OpenAPI 3). Postman crée une collection avec tous les endpoints ; renseignez ensuite l'en-tête `Authorization: Bearer itick_sandbox_VOTRE_CLE` au niveau de la collection.
- **openapi-generator** : générez un client dans votre langage à partir de la même spécification, par exemple :

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://api.itick.fr/itick/partner/docs/spec.yml \
  -g typescript-fetch \
  -o ./itick-client
```

Remplacez `-g typescript-fetch` par le générateur de votre langage (`python`, `php`, `go`, `java`, `csharp`…). Le contrat OpenAPI est la seule référence : ITICK ne fournit ni ne maintient de client généré.

## Contact

Une question ? Écrivez à support@itick.fr (questions techniques) ou à partenaires@itick.fr (partenariats) — ou créez votre compte partenaire (https://itick.fr/partenaires/inscription) et testez tout de suite en sandbox.