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

La liste du registre

Toutes les boutiques du registre, avec un résumé de leurs chiffres et le lien vers le dossier complet de chacune :

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

On peut la filtrer et la trier. Par exemple, celles qui respectent les limites publiées, de la meilleure à la moins bonne livraison :

curl "https://holdmark.org/api/v1/tiendas?meets_limits=true&sort=delivers_orders&order=desc"

• category: la catégorie que déclare le marchand.
• meets_limits: si la boutique respecte ou non les limites publiées.
• sort: par domaine, par ancienneté dans le registre ou par n’importe lequel des chiffres.
• order: croissant ou décroissant.
• limit et offset : combien et à partir de laquelle, jusqu’à cent par requête.

holdmark ne classe pas les boutiques. Il publie les mêmes faits pour toutes, calculés avec la même règle, et c’est celui qui demande qui classe. Il n’y a ni note ni position, et l’ordre par défaut est alphabétique à dessein : un ordre par défaut selon la qualité serait déjà notre opinion. De plus, dès que la position ferait bouger les ventes, le chiffre cesserait de mesurer pour devenir un objectif que l’on poursuit en annulant les commandes difficiles.

La catégorie est déclarée par le marchand et nous ne la vérifions pas : décider de quoi s’occupe une boutique est un jugement, et le registre ne porte pas de jugements. C’est pourquoi chaque boutique la porte marquée comme déclarée, jamais comme vérifiée.

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 not_in_registry si cette boutique n’est pas dans le registre. Ne pas y être n’est pas un jugement sur elle : le registre ne contient que les boutiques qui ont connecté leurs données.
• 400 avec invalid_domain si ce qui est demandé n'est pas un domaine.
• 400 avec invalid_parameter si un filtre ou un tri de la liste n’est pas valide. La réponse dit lequel et ce qui est accepté.
• 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 ne classe pas les boutiques, ne les note pas et n’en recommande aucune. Il renvoie des faits avec leur source et leur période, et celui qui demande décide de ce qui lui importe. Il ne publie pas non plus le nombre de commandes de chaque boutique : le volume va par tranches, jamais le chiffre exact.

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.