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

El listado del registro

Todas las tiendas del registro, con un resumen de sus cifras y el enlace al expediente completo de cada una:

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

Se puede filtrar y ordenar. Por ejemplo, las que cumplen los límites publicados, de mayor a menor entrega:

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

• category: la categoría que declara el comerciante.
• meets_limits: si la tienda cumple o no los límites publicados.
• sort: por dominio, por antigüedad en el registro o por cualquiera de las cifras.
• order: ascendente o descendente.
• limit y offset: cuántas y desde cuál, hasta cien por petición.

holdmark no ordena las tiendas. Publica los mismos hechos de todas, calculados con la misma regla, y ordena quien pregunta. No hay nota, no hay puesto, y el orden por defecto es alfabético a propósito: un orden por defecto por calidad ya sería una opinión nuestra. Además, en cuanto la posición moviera ventas, la cifra dejaría de medir para convertirse en un objetivo que se persigue cancelando los pedidos difíciles.

La categoría la declara el comerciante y no la comprobamos: decidir a qué se dedica una tienda es un juicio, y el registro no hace juicios. Por eso cada tienda la lleva marcada como declarada, nunca como comprobada.

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 not_in_registry si esa tienda no está en el registro. No estar no es un juicio sobre ella: el registro solo tiene tiendas que conectaron sus datos.
• 400 con invalid_domain si lo que se pide no es un dominio.
• 400 con invalid_parameter si un filtro u orden del listado no vale. La respuesta dice cuál y qué se admite.
• 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 ordena tiendas, no las puntúa y no recomienda ninguna. Devuelve hechos con su fuente y su periodo, y quien pregunta decide qué le importa. Tampoco publica cuántos pedidos tiene cada tienda: el volumen va por tramos, nunca la cifra exacta.

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.