> ## Documentation Index
> Fetch the complete documentation index at: https://storekit.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoints de polling

> Récupérez les événements webhook storekit par lots via un endpoint de polling GET, sans exposer d'URL HTTPS publique. Validez l'offset après chaque lot.

Un endpoint de polling vous fournit le même flux d'événements qu'un endpoint webhook, mais vous les récupérez avec une requête GET au lieu que storekit ne les pousse vers une URL publique. Chaque requête de polling renvoie un lot de messages dans l'ordre où ils ont été reçus ; vous traitez le lot, validez la position atteinte, et la requête suivante reprend à partir de là.

## Quand utiliser le polling

Le polling convient aux cas où un endpoint HTTPS public est peu pratique ou inutile :

* **Développement local**, interrogez depuis votre ordinateur portable sans ngrok ni tunnel
* **Réseaux privés**, le service consommateur ne doit pas être accessible depuis Internet
* **Traitement par lots**, vous voulez tous les événements de la journée en une seule fois, par exemple pour archiver les commandes à des fins de conformité ou pour rapprocher les paiements durant la nuit
* **Systèmes qui ne peuvent pas recevoir de HTTP**, une tâche cron, un pipeline de données ou un script

Si vous avez besoin des événements en quelques secondes après leur survenue, utilisez un endpoint webhook classique. Les endpoints de polling et les endpoints webhook peuvent coexister sur le même compte, filtrés sur les mêmes types d'événements ou sur des types différents.

## Créer un endpoint de polling

1. Ouvrez la page des webhooks (**Settings** → **Developers** → **Manage Webhooks**)
2. Dans le portail webhooks intégré, ajoutez un nouvel endpoint et choisissez le type d'endpoint de polling
3. Sélectionnez les types d'événements que vous souhaitez recevoir
4. Enregistrez l'endpoint

Le portail affiche alors deux éléments dont vous avez besoin pour chaque requête :

| Valeur | Exemple | Description |
| - | - | - |
| URL de polling | `https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/{consumer_id}` | Unique à cet endpoint. Copiez-la exactement telle qu'affichée (l'hôte dépend de la région) et remplacez `{consumer_id}` par votre propre identifiant |
| Clé API | `sk_poll_*****` | Envoyée en tant que Bearer token. Affichée une seule fois, conservez-la de manière sécurisée |

> [!WARNING]
>
> La clé API accorde un accès en lecture à tous les événements auxquels l'endpoint est abonné, y compris les noms des clients et les coordonnées de contact dans les payloads de commandes. Traitez-la comme n'importe quel autre secret de production.

## Interroger les événements

Envoyez une requête GET à l'URL de polling avec votre clé API :

```bash theme={null}
curl -X GET "https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/kitchen-archive" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer sk_poll_*****"
```

La réponse est un lot de messages. Le `payload` de chaque message correspond exactement au corps JSON qu'un endpoint webhook recevrait, l'enveloppe `{ event, data }` du [format de payload](/docs/fr/developers/webhooks/payload-format), enrichi de métadonnées de message et d'un `offset` :

```json theme={null}
{
  "data": [
    {
      "id": "msg_2K2N9Qk...",
      "eventType": "order.created",
      "payload": {
        "event": "order.created",
        "data": {
          "id": 123456,
          "status": "created",
          "venue": { "id": 789, "name": "Pizza Palace" },
          "total": 2450
        }
      },
      "timestamp": "2025-01-17T12:00:00.000Z",
      "offset": 0
    }
  ],
  "done": true
}
```

| Champ | Description |
| - | - |
| `data` | Messages dans l'ordre où ils ont été reçus. Vide lorsqu'il n'y a rien de nouveau |
| `data[].payload` | Le corps du webhook : `payload.event` nomme l'événement, `payload.data` contient les données de l'événement |
| `data[].offset` | Position du message dans le flux. Validez cette valeur une fois le message traité |
| `done` | `true` lorsque ce lot a atteint la fin du flux ; `false` signifie qu'il faut à nouveau interroger immédiatement pour obtenir la suite |

La vérification de signature ne s'applique pas, la requête est authentifiée par votre clé API plutôt que par une livraison signée.

## Valider votre position

Après avoir traité un lot, validez l'`offset` du dernier message que vous avez traité :

```bash theme={null}
curl -X POST "https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/kitchen-archive/commit" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_poll_*****" \
  -d '{ "offset": 0 }'
```

Tant que vous ne validez pas, les mêmes messages sont redistribués une fois leur bail expiré. C'est délibéré : si votre worker plante en plein milieu d'un lot, rien n'est perdu. Cela signifie aussi que votre gestionnaire doit être idempotent, voir [Idempotence](/docs/fr/developers/webhooks/advanced/idempotency).

## IDs de consommateur

Le `{consumer_id}` dans l'URL est une chaîne que vous choisissez. Chaque ID de consommateur suit sa propre position dans le flux, ainsi deux consommateurs qui lisent le même endpoint reçoivent chacun tous les événements.

* Utilisez un ID **stable** par worker (`kitchen-archive`, `finance-reconciliation`) pour que la progression survive aux redémarrages
* Ne partagez jamais un même ID de consommateur entre plusieurs clients qui s'exécutent en même temps. Deux processus qui interrogent avec le même ID de consommateur se désynchronisent dans le flux et l'API renvoie des erreurs

> [!NOTE]
>
> Le flux démarre au moment où l'endpoint de polling est créé. Les événements envoyés avant cela ne sont pas inclus.

## Une boucle de polling typique

```javascript theme={null}
const URL = process.env.STOREKIT_POLL_URL;   // includes your consumer id
const KEY = process.env.STOREKIT_POLL_KEY;

async function pollOnce() {
  let done = false;
  while (!done) {
    const res = await fetch(URL, {
      headers: { Accept: 'application/json', Authorization: `Bearer ${KEY}` },
    });
    const body = await res.json();

    for (const msg of body.data) {
      await handleEvent(msg.payload.event, msg.payload.data);
    }

    if (body.data.length > 0) {
      const last = body.data[body.data.length - 1];
      const commit = await fetch(`${URL}/commit`, {
        method: 'POST',
        headers: {
          Accept: 'application/json',
          'Content-Type': 'application/json',
          Authorization: `Bearer ${KEY}`,
        },
        body: JSON.stringify({ offset: last.offset }),
      });
      if (!commit.ok) throw new Error(`Commit failed: ${commit.status}`);
    }

    done = body.done;
  }
}
```

Exécutez `pollOnce()` selon le rythme qui vous convient, toutes les quelques secondes pour du quasi temps réel, ou une fois par nuit pour un export quotidien.

## Transférer vers un service privé

Si vous préférez conserver une livraison HTTP de type webhook mais que votre service se trouve sur un réseau privé, exécutez [Svix Bridge](https://github.com/svix/svix-webhooks/tree/main/bridge) à l'intérieur de ce réseau. Il interroge l'endpoint et transfère chaque message vers une URL interne, RabbitMQ ou Kafka, avec des nouvelles tentatives lorsque l'un ou l'autre côté est temporairement inaccessible. La page de l'endpoint de polling dans le portail intégré inclut une configuration Bridge de démarrage avec l'ID d'application et l'ID d'endpoint pré-remplis.

## Ressources associées

> **[Configurer les webhooks](/docs/fr/developers/webhooks/setting-up-webhooks)**
>
> Livraison push vers un endpoint HTTPS public

> **[Idempotence](/docs/fr/developers/webhooks/advanced/idempotency)**
>
> Gérer sans risque plusieurs livraisons du même événement

> **[Événements webhook](/docs/fr/developers/webhooks/webhook-events)**
>
> Tous les types d'événements auxquels vous pouvez vous abonner

> **[Tester les webhooks](/docs/fr/developers/webhooks/testing-webhooks)**
>
> Inspectez les livraisons et envoyez des événements de test


## Related topics

- [Politique de nouvelle tentative](/docs/fr/developers/webhooks/retry-policy.md)
- [Endpoint MCP](/docs/fr/developers/agents/ordering/mcp-endpoint.md)
- [Ticket de cuisine personnalisé sur une imprimante cloud Star](/docs/fr/guides/build/recipes/custom-kitchen-ticket.md)
- [Commandes en échec : caisse endormie](/docs/fr/guides/integrations/pos/syrve/till-offline.md)
- [Limitation de débit](/docs/fr/developers/webhooks/advanced/rate-limiting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.