Para programas e assistentes

A API do registo

Formato holdmark-expediente/1.0 · versão v1

Tudo o que a holdmark publica sobre uma loja pode ser lido a partir de um programa: sem chaves, sem registo e gratuitamente. É a mesma informação que qualquer pessoa vê na página dessa loja, num formato pensado para ser compreendido por uma máquina.

Como se usa

Um pedido, uma loja, através do seu domínio:

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

O domínio pode ser indicado com www. ou sem, em maiúsculas ou minúsculas: a resposta é a mesma. Para saber o que está disponível e como se chama cada coisa, a própria API descreve-se:

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

O que devolve

O processo completo da loja. Cada facto traz a sua resposta, a sua fonte e o período a 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"
}

Como ler os números

• O arredondamento é sempre contra a loja: o favorável por defeito e o desfavorável por excesso. Uma loja nunca aparece melhor do que é.
• Volume por escalões: nunca o número exato de encomendas, apenas o escalão («mais de 50 000»).
• Cada número com o seu período: as contestações junto do banco olham para encomendas até doze meses; os reembolsos, para uma janela mais curta. Está indicado em cada facto.
• O que não se mede é dito: apoio ao cliente, qualidade do produto e opiniões ficam de fora, e o campo not_measured declara-o.
• Sem dados não há afirmação: se uma loja não tiver dados suficientes, o facto responde not_measured com o respetivo motivo, e não «não».

Limites e erros

• Até 120 pedidos por minuto a partir do mesmo endereço. Acima desse limite, 429.
• 404 com tienda_no_registrada se essa loja não estiver no registo.
• 400 com dominio_no_valido se o que se pede não for um domínio.
• Pode ser chamada a partir do navegador: a API permite qualquer origem.
• As respostas podem ser guardadas em cache durante cinco minutos. Os dados são recalculados uma vez por dia.

O que a API não faz

Não há lista de lojas nem forma de saber quantas são: consulta-se uma a uma, por domínio. É propositado, para proteger a informação comercial das lojas registadas.

Também não há escrita: ninguém pode alterar um processo a partir de fora, nem pagando. Os factos resultam do que a transportadora e o processador de pagamentos registam.

Condições de utilização

Pode usar e citar estes dados indicando a fonte, holdmark.org, e ligando ao processo da loja. O que não pode fazer é apresentá-los como algo diferente do que são: são factos medidos num período, não uma recomendação nem uma garantia sobre uma compra concreta.

Se construir alguma coisa com isto e precisar de mais volume do que o limite permite, escreva-nos para equipo@holdmark.org.