Para programas y asistentes

La API del registro

Formato holdmark-expediente/1.0 · versión v1

Todo lo que holdmark publica de una tienda se puede leer desde un programa: sin claves, sin registro y gratis. Es la misma información que ve cualquiera en la página de esa tienda, en un formato pensado para que la entienda una máquina.

Cómo se usa

Una petición, una tienda, por su dominio:

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

El dominio puede ir con www. o sin él, y en mayúsculas o minúsculas: la respuesta es la misma. Para saber qué hay disponible y cómo se llama cada cosa, la propia API se describe:

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

Qué devuelve

El expediente completo de la tienda. Cada hecho trae su respuesta, su fuente y el periodo al que corresponde:

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

Cómo leer las cifras

• Redondeo siempre en contra de la tienda: lo favorable hacia abajo y lo desfavorable hacia arriba. Una tienda nunca sale mejor de lo que es.
• Volumen por tramos: nunca la cifra exacta de pedidos, solo el tramo («+50.000»).
• Cada cifra con su periodo: las reclamaciones al banco miran pedidos de hasta doce meses; los reembolsos, una ventana más corta. Va indicado en cada hecho.
• Lo que no se mide se dice: atención al cliente, calidad del producto y opiniones quedan fuera, y el campo not_measured lo declara.
• Sin dato no hay afirmación: si una tienda no tiene datos suficientes, el hecho responde not_measured con su motivo, no «no».

Límites y errores

• Hasta 120 peticiones por minuto desde la misma dirección. Pasado ese límite, 429.
• 404 con tienda_no_registrada si esa tienda no está en el registro.
• 400 con dominio_no_valido si lo que se pide no es un dominio.
• Se puede llamar desde el navegador: la API permite cualquier origen.
• Las respuestas se pueden guardar en caché cinco minutos. Los datos se recalculan una vez al día.

Lo que la API no hace

No hay listado de tiendas ni forma de saber cuántas hay: se consulta una a una, por dominio. Es a propósito, para proteger la información comercial de las tiendas registradas.

Tampoco hay escritura: nadie puede cambiar un expediente desde fuera, ni pagando. Los hechos salen de lo que registran el transportista y la pasarela de pago.

Condiciones de uso

Puedes usar y citar estos datos indicando la fuente, holdmark.org, y enlazando al expediente de la tienda. Lo que no puedes hacer es presentarlos como algo distinto de lo que son: son hechos medidos en un periodo, no una recomendación ni una garantía sobre una compra concreta.

Si construyes algo con esto y necesitas más volumen del que permite el límite, escríbenos a equipo@holdmark.org.