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

# Collecteur HTTP générique

> Envoyez des logs de requêtes serveur ou edge filtrés à Analytics des crawlers via le point d’ingestion générique.

Utilisez l’API HTTP générique lorsque vous maîtrisez un runtime serveur ou edge et qu’aucun connecteur géré ne correspond à votre stack. Filtrez les requêtes avant la livraison et n’envoyez que les champs nécessaires à l’agrégation des crawlers.

## Avant de commencer

Il vous faut :

* un accès à **Measure > Analytics des crawlers > Paramètres** pour la marque ;
* un runtime côté serveur ou edge capable d’observer les requêtes après le routage ;
* le nom d’hôte configuré pour la marque Qwairy ;
* un coffre de secrets sûr pour la clé du connecteur.

Le collecteur n’accepte que les événements de requêtes `GET` et `HEAD` pour le nom d’hôte configuré de la marque. Un domaine apex et sa forme `www` sont considérés comme équivalents. Les autres sous-domaines nécessitent leur propre périmètre de marque.

## Créer et protéger la clé

1. Dans les paramètres d’Analytics des crawlers, sélectionnez **API HTTP générique**.
2. Sélectionnez **Créer une clé**.
3. Saisissez un nom descriptif et un fuseau horaire analytique IANA, comme `Europe/Paris`.
4. Copiez le secret lorsqu’il apparaît. Qwairy n’en affiche ensuite que le préfixe.
5. Conservez-le comme secret côté serveur. Ne le placez ni dans du code exécuté dans le navigateur, ni dans le gestionnaire de code source, ni dans les URL de requête, ni dans les logs applicatifs.

Pour renouveler la clé, créez une clé de remplacement, mettez à jour le collecteur, confirmez la livraison, puis supprimez l’ancienne clé. Une intégration peut avoir jusqu’à cinq clés actives.

## Envoyer des événements

Envoyez des requêtes `POST` à :

```text theme={null}
https://www.qwairy.co/api/v1/logs/ingest
```

Utilisez ces en-têtes :

```text theme={null}
Content-Type: application/json
X-API-Key: YOUR_CRAWLER_KEY
```

`Authorization: Bearer YOUR_CRAWLER_KEY` est aussi accepté. Préférez `X-API-Key` pour la configuration présentée dans Qwairy.

Chaque événement utilisé pour l’agrégation a besoin de ces champs :

| Champ | Exigence |
| - | - |
| `request_method` | `GET` ou `HEAD` |
| `request_path` | Chemin de la page demandée ; les chaînes de requête et les fragments sont supprimés |
| `hostname` | Nom d’hôte configuré pour la marque, ou son équivalent apex/`www` |
| `user_agent` | User-Agent complet utilisé pour classer le crawler |
| `timestamp` | Heure de l’événement au format ISO 8601 valide |
| `status_code` | Statut de réponse HTTP, facultatif |

L’API accepte un objet, un tableau d’objets, du JSON délimité par des retours à la ligne, ou un objet contenant un tableau `logs`. Un en-tête `Idempotency-Key` stable ou un champ `batch_id` permet de dédupliquer des renvois dont les octets diffèrent.

Filtrez les user agents de crawlers d’IA connus dans votre runtime avant d’appeler le point de terminaison. Qwairy réapplique son registre à la réception et écarte les user agents humains, de recherche traditionnelle et inconnus.

## Tester la livraison

Remplacez le nom d’hôte et la clé avant de lancer ce test synthétique :

```bash theme={null}
event_time=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
curl --request POST "https://www.qwairy.co/api/v1/logs/ingest" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $QWAIRY_CRAWLER_KEY" \
  --data "{\"request_method\":\"GET\",\"request_path\":\"/docs/crawler-check\",\"hostname\":\"www.example.com\",\"user_agent\":\"GPTBot/1.0\",\"timestamp\":\"${event_time}\",\"status_code\":200}"
```

Une requête valide renvoie un accusé de réception JSON. Le connecteur ne quitte l’état en attente qu’après l’acceptation d’un événement par le pipeline d’agrégation dans le périmètre de la marque configurée. Une réponse de santé du point de terminaison ou un événement filtré n’établit pas cette connexion.

## Limites et périmètre de livraison

* Une requête générique peut contenir au plus 1 000 événements et 2 000 000 octets normalisés.
* Les événements livrés avec plus de 72 heures de retard sortent de la fenêtre actuelle d’arrivée tardive.
* Les plafonds partagés sont de 10 000 000 événements par intégration et par jour, et de 200 000 000 événements par équipe facturée et par jour.
* Votre runtime, votre fournisseur réseau ou votre stack d’observabilité peuvent facturer la lecture et la transmission des logs.
* Un filtrage ou un échantillonnage avant la livraison rend les comptes partiels pour ce périmètre.

## Dépannage

* **401 ou 403** : vérifiez que le secret appartient au connecteur HTTP générique de cette marque et qu’il est toujours actif.
* **400** : validez la forme du JSON, le nombre d’enregistrements, la méthode, le chemin, le nom d’hôte, le User-Agent et l’horodatage.
* **413** : réduisez la taille du lot ou du payload encodé.
* **429** : attendez la fin de l’intervalle `Retry-After`, puis renvoyez le même lot idempotent.
* **Accusé de réception mais pas de connexion** : vérifiez que le nom d’hôte correspond à la marque et que le test utilise un User-Agent de crawler d’IA actuellement reconnu et un horodatage récent.
* **Les comptes sont inférieurs aux logs sources** : vérifiez les filtres en amont, l’échantillonnage, les chemins et user agents exclus, les livraisons tardives et les noms d’hôte rejetés.

## Page associée

* [Analytics des crawlers](/fr/documentation/measure/crawler-analytics)


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