Para desarrolladores

La API v1 es pública y no necesita clave. Los clientes envían solo el nombre de dominio; las direcciones con ruta, esquema o puerto se rechazan. Las respuestas son JSON en UTF‑8; los errores { "error": "…" }.

Base: https://dvojnik.ystvan.com/api/v1

Puntos de acceso

Método y rutaDescripción
GET /healthestado del servicio, sin caché
GET /blocklistdominios de riesgo confirmados: {version, count, sources[], domains:[[dominio, fuente],…]}. ETag + If-None-Match → 304. El cliente debe mostrar la atribución (sources[].attribution).
GET /known-shopstiendas conocidas para comparar similitud: {version, count, shops:[…]}, ETag como arriba
GET /domain?name=ejemplo.escoincidencia con la lista, tienda conocida, antigüedad del dominio (age.status: found | not-registered | unknown)
POST /reportscuerpo {domain, category, note?}; category: fake-shop | phishing-payment | fake-carrier | other. 201 con id; duplicado en la semana → 200 con el id original; límite 20/día → 429
GET /reports/{id}estado de la denuncia: received | verifying | confirmed | rejected
curl "https://dvojnik.ystvan.com/api/v1/domain?name=alza.cz"

Núcleo compartido

La extensión, la aplicación móvil y la API usan el mismo núcleo (@dvojnik/core): análisis del dominio (punycode, esqueleto para caracteres confundibles), búsqueda de similitud con tiendas conocidas, puntuación y textos. Por eso navegador y teléfono dan el mismo resultado.

Extensión para desarrollo y pruebas

La extensión se puede cargar sin empaquetar: en Chrome/Edge abre chrome://extensions, activa el modo de desarrollador y elige «Cargar descomprimida» con la carpeta de compilación; en Firefox, about:debugging → «Cargar complemento temporal». Las pruebas automatizadas usan Playwright con --load-extension.

Modo de prueba: una dirección que termina en .localhost se evalúa como el dominio anterior a ese sufijo (alza-vyprodej.cz.localhost → alza-vyprodej.cz), así puedes probar sin visitar un sitio de riesgo real.

Normas de uso de la API

  • No envíes direcciones completas ni datos personales; en la nota de la denuncia nada que identifique a una persona.
  • Respeta el ETag y la caché (s-maxage=300 en las listas): basta con actualizar cada pocas horas.
  • Al mostrar la lista de bloqueo, cita la fuente (ČOI) y presenta la inclusión como indicios de riesgo, no como prueba de fraude.