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

A lista do registo

Todas as lojas do registo, com um resumo dos seus números e a ligação para o processo completo de cada uma:

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

Pode filtrar-se e ordenar-se. Por exemplo, as que cumprem os limites publicados, da melhor para a pior entrega:

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

• category: a categoria que o comerciante declara.
• meets_limits: se a loja cumpre ou não os limites publicados.
• sort: por domínio, por antiguidade no registo ou por qualquer um dos números.
• order: ascendente ou descendente.
• limit e offset: quantas e a partir de qual, até cem por pedido.

a holdmark não ordena as lojas. Publica os mesmos factos de todas, calculados com a mesma regra, e ordena quem pergunta. Não há nota nem lugar, e a ordem por omissão é alfabética de propósito: uma ordem por omissão por qualidade já seria uma opinião nossa. Além disso, assim que a posição movesse vendas, o número deixaria de medir para se tornar um objetivo que se persegue cancelando as encomendas difíceis.

A categoria é declarada pelo comerciante e não a comprovamos: decidir a que se dedica uma loja é um juízo, e o registo não faz juízos. Por isso cada loja leva-a marcada como declarada, nunca como comprovada.

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 not_in_registry se essa loja não está no registo. Não estar não é um juízo sobre ela: o registo só tem lojas que ligaram os seus dados.
• 400 com invalid_domain se o que se pede não for um domínio.
• 400 com invalid_parameter se um filtro ou uma ordem da lista não é válido. A resposta diz qual e o que se aceita.
• 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 ordena lojas, não as pontua e não recomenda nenhuma. Devolve factos com a sua fonte e o seu período, e quem pergunta decide o que lhe importa. Também não publica quantas encomendas tem cada loja: o volume vai por escalões, nunca o número exato.

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.