ARC/1.0 — Agent-Readable Catalog
Resumen. ARC define cómo una tienda de comercio electrónico expone su
catálogo como una superficie REST legible por máquinas, de solo lectura, que agentes de IA
autónomos pueden descubrir, en la que pueden confiar y que pueden consumir sin scraping,
autenticación ni dependencia de proveedor. Especifica tres señales de descubrimiento, un
documento de descubrimiento autodescriptivo, un contrato de endpoints de catálogo, un objeto
producto normativo, un modelo de consentimiento explícito para la indexación federada, y la
interoperabilidad con UCP (/.well-known/ucp). ARC es neutral respecto a la
plataforma; este documento usa ejemplos de WooCommerce en todo momento.
1. Niveles de conformidad y terminología
Las palabras clave must, must not, should y may deben interpretarse según lo descrito en la RFC 2119.
| Nivel | Nombre | Requisitos |
|---|---|---|
| ARC-READ | Catálogo legible | Al menos una señal de descubrimiento (§2), un documento de descubrimiento válido (§3), y
los endpoints search, products, product y categories
(§4) sirviendo objetos producto (§5). Sin autenticación en ninguna de estas superficies. |
| ARC-TRUST | Catálogo confiable | ARC-READ, más: cuarentena de calidad (§5.6), indicadores de consentimiento explícitos (§6), metadatos de frescura, confianza honesta del stock (§5.4), y las reglas de verificación de precio/total del §5.3. |
| ARC-CHECKOUT | Traspaso de checkout | ARC-TRUST, más sesiones de checkout (§7). El pago must permanecer en la tienda del comerciante; las superficies ARC nunca procesan pagos. |
2. Señales de descubrimiento
Una tienda conforme must publicar al menos una — y should publicarlas todas — de las siguientes señales, cada una resolviendo al documento de descubrimiento:
2.1 Enlace en el head HTML
<link rel="kalicart-agent" type="application/json"
href="https://shop.example.com/wp-json/kalicart/v1/discovery" />La relación rel="kalicart-agent" en el <head> de la tienda
es la señal principal en banda. Los agentes que analizan el HTML de la tienda
should comprobar el head antes de reconstruir un catálogo a partir
del contenido de la página. Las implementaciones may además
mostrar un ancla visible en el body (badge) que apunte a un índice legible por humanos/agentes;
las pruebas de campo muestran que las anclas en el body mejoran notablemente el descubrimiento
por agentes que navegan el DOM.
2.2 Rutas well-known
La tienda should servir /.well-known/agent.json,
/.well-known/agent-catalog y un alias con el nombre de la implementación
(referencia: /.well-known/kalicart-bridge), cada uno con al menos la URL del
documento de descubrimiento y la versión de la implementación.
2.3 Superficies de rastreo
La tienda may anunciar la URL de descubrimiento en
robots.txt (como entrada de comentario/allow) y exponer un sitemap orientado a
agentes que enumere los endpoints del catálogo.
3. El documento de descubrimiento
Un único documento JSON autodescriptivo. Es el contrato: un agente que lo ha leído no necesita documentación fuera de banda. Campos normativos:
| Campo | Req. | Significado |
|---|---|---|
document_kind | MUST | Cadena fija que identifica la familia de documentos (referencia: kalicart_agent_discovery). |
schema_version | MUST | Versión del esquema del documento. |
plugin_version | MUST | Versión de la implementación (semver). |
endpoints{} | MUST | URL absolutas para discovery, search, products, product (con plantilla {id}), categories, meta. |
authentication | MUST | {required:false, scheme:"none"} para todas las superficies públicas del catálogo. |
capabilities{} | MUST | Mapa booleano honesto: search, offers, availability, shipping_policy, coupon_hints, cart, checkout, payments, mutations, read_only. Las capacidades no implementadas must ser false. |
crawler_policy{} / intent_flags{} | MUST (L2) | Modelo de consentimiento — ver §6. |
price_format | MUST | Declaración de codificación del precio — ver §5.3. |
variation_discovery | MUST | Declara el contrato de variantes lista-vs-detalle — ver §5.5. |
freshness | SHOULD (L2) | Si los datos son en vivo o una instantánea, y su límite de antigüedad. |
trust{} | SHOULD | Listas de tareas safe_for[] / not_for[], autoridad de checkout, regla de precio de cupones. |
ucp_profile_url | SHOULD | URL absoluta de /.well-known/ucp — ver §8. |
merchant{}, return_policy, merchant_shipping_policy | SHOULD | Verdades de frontera expuestas como datos estructurados, nunca como consejo en prosa. |
4. Endpoints del catálogo
Todos los endpoints son GET de solo lectura, sin autenticación, JSON. Base
de referencia: /wp-json/kalicart/v1/.
| Endpoint | Contrato |
|---|---|
catalog/search | Filtros: q, category, gender, color, on_sale, in_stock, min_price, max_price. Los filtros aceptados must ser enumerados por catalog/meta. |
catalog/products | Lista paginada. La respuesta must incluir products[], total, page, per_page, total_pages. |
catalog/product/{id} | Producto individual con variants[] completo (ver §5.5). |
catalog/categories | Árbol de categorías con recuento de productos por nodo. Las categorías son la taxonomía propia del comerciante; ARC no impone una taxonomía global. |
catalog/meta | Filtros aceptados y rango de precio del catálogo. |
5. El objeto producto
5.1 Identidad
id, sku, type (simple|variable),
name, slug, url, status,
categories[] (cada una con un path completo como
"Wine > Prosecco"), tags[], barcodes[]
(EAN/GTIN/UPC cuando estén presentes — aditivo, vacío cuando no lo estén).
5.2 Procedencia
metadata.bridge_version (versión de la implementación que emitió el objeto)
y updated_at/created_at must estar
presentes.
5.3 Precio
Los precios del catálogo se codifican como decimal_major_units (ej.
29.99 = 29,99 EUR) y la codificación must declararse
en price_format. price.current es siempre el precio de catálogo del
comerciante; los cupones son ahorros condicionales en el checkout y
must not reemplazarlo. list_price lleva el precio de
lista tachado para la interop UCP. Los agentes must not citar
totales que el checkout del comerciante no haya calculado (regla de verificación del
total).
5.4 Stock
stock.availability_status usa los valores estándar de UCP
(in_stock, out_of_stock, backorder).
stock.confidence declara la precisión honestamente:
numeric_stock_quantity, availability_status_only, o
variant_dependent. Si quantity es null, el agente
must not inventar un inventario numérico.
5.5 Variantes
variants[] es siempre un array, nunca null. En las
respuestas de lista y búsqueda: una única entrada para productos simples, un
array vacío para productos variables — las variantes completas provienen
de catalog/product/{id}. Esta asimetría must
declararse en variation_discovery.list_context_note. Los agentes
must not citar un precio final para un producto variable hasta que
se haya seleccionado una variante.
5.6 Cuarentena de calidad ARC-TRUST
Cada producto lleva quarantine: {in_quarantine, score, flags[]}. La
puntuación comienza en 100 con deducciones por título, descripción, categoría, precio,
imagen, SKU faltantes. Los productos puestos en cuarentena por defectos estructurales
(título/descripción/categoría/precio) must excluirse de
cualquier índice posterior construido sobre el catálogo. El comerciante conserva un panel
de salud privado; la superficie pública solo expone el veredicto.
5.7 Disposición de compra
purchase_readiness: {status, blocking_fields[], can_add_to_cart_directly}
indica al agente si es posible un añadido directo al carrito vía checkout_url
o qué atributos deben seleccionarse primero.
6. Consentimiento y política de rastreo ARC-TRUST
ARC separa la lectura de una tienda individual (siempre permitida en las superficies públicas) de la indexación federada (agregar el catálogo en un índice multi-comerciante). El consentimiento para esto último lo publica el comerciante en el documento de descubrimiento — el modelo robots.txt: la señal vive junto con los datos, y el indexador está obligado a respetarla.
"crawler_policy": {
"allow_llm_training": false,
"allow_live_agent_reads": true,
"allow_global_indexing": true
},
"intent_flags": {
"single_merchant_only": true,
"global_indexable": true,
"federated_search_source": true,
"agent_read_surface": true
}Un indexador federado must leer estos indicadores en el momento
del sondeo, must not ingerir un catálogo cuyo
allow_global_indexing sea false, y must identificarse
con un User-Agent honesto. La implementación de referencia entrega el consentimiento
habilitado por defecto con exclusión voluntaria de un clic en el admin del
comerciante; cualquiera de los valores por defecto es conforme, pero el interruptor
must existir y los indicadores publicados must
reflejarlo dentro del límite de frescura.
7. Sesiones de checkout (opcional) ARC-CHECKOUT
POST checkout/session crea una sesión de carrito para uno o más productos y
devuelve cart_url / checkout_url. El humano completa el pago en la
tienda del comerciante. Las superficies ARC must not capturar
pagos, almacenar credenciales de pago, o requerir OAuth para este traspaso. La capacidad
está desactivada por defecto y su estado must ser visible en
capabilities.checkout_sessions.
8. Interoperabilidad UCP
Una implementación conforme should servir
/.well-known/ucp declarando catalog.search y
catalog.lookup, y enlazarlo mediante ucp_profile_url.
Los contratos availability_status, list_price y variants[]
de ARC están alineados con UCP de modo que un solo catálogo sirva a ambos ecosistemas sin
traducción.
9. Consideraciones de seguridad
Todas las superficies públicas son de solo lectura; capabilities.mutations
must ser false. Sin claves API en las superficies públicas — los
secretos en contextos de agentes se filtran. Los sondeos federados must
aplicar protecciones SSRF (sin literales IP, sin nombres de host internos, redirecciones/tiempos
de espera limitados) y un User-Agent identificativo. Las superficies de admin/salud
must requerir comprobaciones de capacidad de la plataforma. Las
implementaciones must not llamar a servicios de terceros desde el
servidor del comerciante como efecto secundario de servir lecturas del catálogo.
10. Registro de cambios de la especificación
| Versión | Fecha | Notas |
|---|---|---|
ARC/1.0 | 2026-06-10 | Primera versión estable. Codifica el contrato entregado por KaliCart Bridge 1.0.76: tres señales de descubrimiento, documento de descubrimiento, cinco endpoints de catálogo, objeto producto con cuarentena y disposición de compra, modelo de consentimiento de exclusión voluntaria para la indexación federada, sesiones de checkout opcionales, interop UCP. |
Comentarios e informes de implementación: GitHub issues.