Per programmi e assistenti

L'API del registro

Formato holdmark-expediente/1.0 · versione v1

Tutto ciò che holdmark pubblica su un negozio si può leggere da un programma: senza chiavi, senza registrazione e gratis. Sono le stesse informazioni che chiunque vede sulla pagina di quel negozio, in un formato pensato perché lo capisca una macchina.

Come si usa

Una richiesta, un negozio, tramite il suo dominio:

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

Il dominio può essere indicato con www. o senza, in maiuscolo o minuscolo: la risposta è la stessa. Per sapere cosa è disponibile e come si chiama ogni cosa, l'API si descrive da sé:

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

L’elenco del registro

Tutti i negozi del registro, con un riassunto delle loro cifre e il link al fascicolo completo di ciascuno:

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

Si può filtrare e ordinare. Per esempio, quelli che rispettano i limiti pubblicati, dalla consegna migliore alla peggiore:

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

• category: la categoria che dichiara il commerciante.
• meets_limits: se il negozio rispetta o no i limiti pubblicati.
• sort: per dominio, per anzianità nel registro o per una qualsiasi delle cifre.
• order: crescente o decrescente.
• limit e offset: quanti e da quale, fino a cento per richiesta.

holdmark non ordina i negozi. Pubblica gli stessi fatti di tutti, calcolati con la stessa regola, e ordina chi chiede. Non c’è voto né posizione, e l’ordine predefinito è alfabetico di proposito: un ordine predefinito per qualità sarebbe già un’opinione nostra. E appena la posizione muovesse vendite, la cifra smetterebbe di misurare per diventare un obiettivo che si insegue cancellando gli ordini difficili.

La categoria la dichiara il commerciante e non la verifichiamo: decidere di cosa si occupa un negozio è un giudizio, e il registro non dà giudizi. Per questo ogni negozio la porta marcata come dichiarata, mai come verificata.

Cosa restituisce

Il fascicolo completo del negozio. Ogni fatto riporta la sua risposta, la sua fonte e il periodo a cui si riferisce:

{
  "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"
}

Come leggere i numeri

• L'arrotondamento va sempre a sfavore del negozio: il favorevole per difetto e lo sfavorevole per eccesso. Un negozio non appare mai migliore di quello che è.
• Volume a fasce: mai il numero esatto di ordini, solo la fascia («oltre 50.000»).
• Ogni numero con il suo periodo: le contestazioni bancarie guardano ordini fino a dodici mesi; i rimborsi, una finestra più breve. È indicato su ogni fatto.
• Ciò che non si misura viene dichiarato: assistenza clienti, qualità dei prodotti e opinioni restano fuori, e il campo not_measured lo dichiara.
• Senza dati non si afferma nulla: se un negozio non ha dati sufficienti, il fatto risponde not_measured con la sua motivazione, non «no».

Limiti ed errori

• Fino a 120 richieste al minuto dallo stesso indirizzo. Superato quel limite, 429.
• 404 con not_in_registry se quel negozio non è nel registro. Non esserci non è un giudizio su di lui: il registro ha solo negozi che hanno collegato i propri dati.
• 400 con invalid_domain se ciò che si richiede non è un dominio.
• 400 con invalid_parameter se un filtro o un ordine dell’elenco non è valido. La risposta dice quale e cosa si accetta.
• Si può chiamare dal browser: l'API consente qualsiasi origine.
• Le risposte possono essere messe in cache per cinque minuti. I dati vengono ricalcolati una volta al giorno.

Quello che l'API non fa

Non ordina i negozi, non dà voti e non ne raccomanda nessuno. Restituisce fatti con la loro fonte e il loro periodo, e chi chiede decide cosa gli importa. E non pubblica quanti ordini ha ogni negozio: il volume va per fasce, mai la cifra esatta.

Non c'è nemmeno scrittura: nessuno può modificare un fascicolo dall'esterno, neanche pagando. I fatti derivano da ciò che registrano il corriere e il gestore dei pagamenti.

Condizioni d'uso

Puoi usare e citare questi dati indicando la fonte, holdmark.org, e collegandoti al fascicolo del negozio. Quello che non puoi fare è presentarli come qualcosa di diverso da ciò che sono: sono fatti misurati in un periodo, non una raccomandazione né una garanzia su un acquisto specifico.

Se costruisci qualcosa con questi dati e ti serve più volume di quanto consenta il limite, scrivici a equipo@holdmark.org.