En-têtes de réponse

Chaque réponse de l'API FourA inclut un petit ensemble d'en-têtes personnalisés. Ils sont utiles pour le traçage, le support, le rapprochement de facturation et l'analyse a posteriori.

En-têtes définis par FourA

X-Foura-Request-Id

Chaque appel vers POST /api/auto/, POST /api/single/, POST /api/proxy/ ou POST /api/browser/ est marqué d'un UUID. L'en-tête est défini même en cas d'échec de l'authentification, afin que vous puissiez également corréler les appels mal configurés.

curl -i -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'

HTTP/1.1 200 OK
X-Foura-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
X-FourA-Credits: 2
Content-Type: application/json
...

Quand l'utiliser

• Tickets de support : incluez l'ID de la requête et nous pourrons retrouver l'appel exact dans nos registres.
• Vos propres journaux : stockez-le à côté de la ligne de journal de votre application. Si un client signale que "les données étaient incorrectes à 14:32", vous pouvez rejouer la requête exacte.
• Traçage du tableau de bord : le même ID apparaît dans le flux d'activité pour les clés que vous gérez, vous permettant d'ouvrir la ligne correspondante et d'inspecter la requête et la réponse capturées.

Exemple : journalisation de votre côté

import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    resp = requests.post(
        "https://eu.api.foura.ai/api/single/",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json={"method": "GET", "url": url},
    )
    request_id = resp.headers.get("X-Foura-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()

async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-Foura-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}

X-FourA-Credits

X-FourA-Credits signale le coût en crédits de l'appel que vous venez d'effectuer. Il s'agit d'un compteur, pas d'une facture : l'en-tête reflète ce que le travail a dépensé indépendamment du résultat. La couche de facturation du tableau de bord ne comptabilise que les résultats facturables sur votre forfait (voir Résultats des requêtes pour savoir quels résultats sont facturables).

Référence des coûts

/api/auto/ n'ajoute pas de ligne facturable distincte. Son coût en crédits est la somme des sous-appels qu'il a effectués en interne (un simple replay sur une cible chaude peut se terminer à 2, une résolution à froid sur un site complexe peut coûter beaucoup plus). La valeur X-FourA-Credits de la réponse automatique est égale à meta.credits dans le corps et suit le coût total du processus.

Pourquoi un en-tête et un champ dans le corps ?

L'en-tête est pratique : vous pouvez le lire avant d'analyser le corps, l'enregistrer à côté de votre ligne de requête, ou l'additionner sur de nombreux appels sans analyse JSON. Le meta.credits (Auto) du corps ou les métadonnées par moteur (tableaux de bord Single, Proxy, Browser) contiennent le même nombre, mais lisible à l'intérieur de l'enveloppe de réponse.

Comportement du cache

L'API ne définit pas Cache-Control ni ETag sur les réponses. Chaque appel atteint le backend. Si vous avez besoin d'un cache, ajoutez-le de votre côté.

En-têtes de réponse de la cible

Les en-têtes renvoyés par le site cible ne se trouvent pas dans la réponse de l'API FourA. Ils sont renvoyés dans l'enveloppe JSON via le champ headers. Pour les endpoints Single et Proxy, il s'agit d'un tableau d'objets d'en-têtes par saut (une entrée par étape de redirection). Pour l'endpoint Browser, il s'agit d'un objet plat des en-têtes de la réponse finale.

{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}

Si vous avez besoin d'un en-tête cible spécifique, lisez-le dans le champ headers de l'enveloppe, et non dans la réponse HTTP de l'appel d'API lui-même.

Articles associés

• Endpoints de l'API : Formats des enveloppes de requête et de réponse
• Erreurs de l'API : Comment les réponses d'erreur sont structurées
• Résultats des requêtes : Quels résultats sont facturables
• Journal d'activité : Historique par requête indexé par l'ID de la requête