Pour les programmes et les assistants

L'API du registre

Format holdmark-expediente/1.0 · version v1

Tout ce que holdmark publie sur une boutique peut être lu depuis un programme : sans clé, sans inscription et gratuitement. Ce sont les mêmes informations que celles affichées sur la page de cette boutique, dans un format conçu pour être compris par une machine.

Comment l'utiliser

Une requête, une boutique, par son domaine :

curl https://holdmark.org/api/v1/tiendas/tienda-ejemplo.com

Le domaine peut s'écrire avec www. ou sans, en majuscules ou en minuscules : la réponse est la même. Pour savoir ce qui est disponible et comment chaque chose s'appelle, l'API se décrit elle-même :

curl https://holdmark.org/api/v1

Ce qu'elle renvoie

Le dossier complet de la boutique. Chaque fait indique sa réponse, sa source et la période correspondante :

{
  "format": "holdmark-expediente/1.0",
  "merchant": { "domain": "tienda-ejemplo.com", "platform": "shopify" },
  "facts": {
    "delivers_orders": { "answer": "yes", "value": 0.99, "source": "carrier" },
    "refunds_money":   { "answer": "yes", "source": "payment_processor" },
    "bank_claims":     { "value": 2, "unit": "per_1000_orders" },
    "verified_orders": { "band": "+50.000" }
  },
  "not_measured": ["customer_service", "product_quality", "opinions"],
  "rounding": "against the merchant"
}

Comment lire les chiffres

• L'arrondi se fait toujours au détriment de la boutique : le favorable vers le bas et le défavorable vers le haut. Une boutique n'apparaît jamais meilleure qu'elle ne l'est.
• Volume par paliers : jamais le nombre exact de commandes, seulement le palier (« plus de 50 000 »).
• Chaque chiffre avec sa période : les contestations bancaires portent sur des commandes remontant jusqu'à douze mois ; les remboursements, sur une fenêtre plus courte. C'est indiqué sur chaque fait.
• Ce qui n'est pas mesuré est indiqué : le service client, la qualité des produits et les avis sont hors périmètre, et le champ not_measured le déclare.
• Pas de donnée, pas d'affirmation : si une boutique n'a pas assez de données, le fait répond not_measured avec son motif, et non « non ».

Limites et erreurs

• Jusqu'à 120 requêtes par minute depuis la même adresse. Au-delà de cette limite, 429.
• 404 avec tienda_no_registrada si cette boutique n'est pas dans le registre.
• 400 avec dominio_no_valido si ce qui est demandé n'est pas un domaine.
• Elle peut être appelée depuis le navigateur : l'API autorise toute origine.
• Les réponses peuvent être mises en cache cinq minutes. Les données sont recalculées une fois par jour.

Ce que l'API ne fait pas

Il n'existe ni liste des boutiques ni moyen de savoir combien il y en a : on les interroge une par une, par domaine. C'est délibéré, afin de protéger les informations commerciales des boutiques enregistrées.

Il n'y a pas non plus d'écriture : personne ne peut modifier un dossier de l'extérieur, même en payant. Les faits proviennent de ce qu'enregistrent le transporteur et le prestataire de paiement.

Conditions d'utilisation

Vous pouvez utiliser et citer ces données en indiquant la source, holdmark.org, et en renvoyant au dossier de la boutique. Ce que vous ne pouvez pas faire, c'est les présenter comme autre chose que ce qu'elles sont : des faits mesurés sur une période, ni une recommandation ni une garantie portant sur un achat précis.

Si vous construisez quelque chose avec cela et qu'il vous faut plus de volume que la limite ne le permet, écrivez-nous à equipo@holdmark.org.