Saltar al contenido principal

FAQ API

Endpoints del dashboard (JWT)​

Ruta base: /api/v1/dashboard/faq. Para escribir y para GET /pending hace falta el rol owner o admin.

CRUD​

  • GET /?entityType=product&entityId=123&locale=en&storeId=... — lista FAQs (limit por defecto 200, máximo 1000; offset)
  • POST / — crear
  • PATCH /:id — actualizar
  • DELETE /:id — borrar

En lote​

  • POST /bulk — array de objetos FAQ
  • POST /import/csv — cuerpo CSV (mira Editor de FAQ)
  • GET /export/csv — exportar. Sin filtros → todas las FAQs de la organización. Con ?entityType=…&entityId=… (y opcionalmente locale, storeId) → filtradas.
  • GET /template — formato JSON de ejemplo para importar. entityId es el id que la propia plataforma da a la entidad (por ejemplo, el id de producto de BigCommerce 112), no el id interno de Clione.

Generación y revisión​

  • POST /generate — FAQs generadas por LLM para una entidad. Se crean aprobadas y visibles, y se descuentan de la cuota de enriquecimiento
  • POST /:id/approve — aprueba una pregunta pendiente enviada desde el storefront (cuerpo: answer, reviewedBy opcional)
  • POST /:id/reject — rechazar
  • GET /pending — preguntas enviadas desde el storefront, pendientes de revisión

Resumen​

  • GET /stats?storeId=… — contadores: preguntas activas y entidades a las que responden
  • GET /entities?storeId=…&entityType=… — entidades con al menos una FAQ

Biblioteca de FAQ​

Ruta base: /api/v1/dashboard/faq-library. Una entrada de la biblioteca es una respuesta canónica, enlazada de forma explícita a las entidades que deben mostrarla.

  • GET / — lista las entradas de la biblioteca
  • POST / — crear una entrada
  • PATCH /:id — actualizar
  • DELETE /:id — borrar
  • GET /:id/links — entidades a las que está enlazada una entrada
  • POST /:id/links — enlaza la entrada a una entidad (entityType, entityId), o, con scope: "store", a todas las entidades de un entityType en una tienda (necesita entityType y storeId)
  • DELETE /:id/links — desenlazar
  • GET /export.csv, POST /import/csv, GET /template.csv — ida y vuelta en CSV

Endpoints públicos (API key)​

Ruta base: /api/v1/public/faq. Los usa el widget de FAQ. Cada llamada necesita una API key con el scope products:read; la organización sale de la key, nunca de una cabecera. Rate limit de 200 peticiones cada 5 minutos por key. La petición también tiene que pasar los allowedDomains y las comprobaciones de navegador de la key; mira Autenticación.

GET /api/v1/public/faq/render?entityType=product&entityId=123&pageUrl=https://shop.example.com/products/foo
X-API-Key: sk_live_...
Origin: https://shop.example.com

Parámetros de query: entityType, entityId (obligatorios), locale, pageUrl, heading, storeId (opcional; por defecto, la tienda de la key).

Respuesta:

{
  "data": {
    "entries": [{ "question": "...", "answer": "..." }],
    "jsonLd": { "@context": "https://schema.org", "@type": "FAQPage", ... },
    "scriptTag": "<script type=\"application/ld+json\">...</script>",
    "htmlBlock": "<div class=\"clione-faq\">...</div>",
    "entryCount": 5,
    "specificCount": 3,
    "libraryCount": 2,
    "tenantPlatformId": "..."
  }
}

entries junta las FAQs propias de la entidad con las entradas de la biblioteca enlazadas a ella, ordenadas por sortOrder. specificCount cuenta las propias y libraryCount las de la biblioteca. Si la entidad no tiene FAQs, la respuesta es { "data": null, "message": "No FAQ entries found for this entity" }.

Otros endpoints públicos:

  • POST /submit — un comprador envía una pregunta (entityType, entityId, question, submittedBy opcional). Se guarda como pending y aparece en GET /api/v1/dashboard/faq/pending. Devuelve 201.
  • GET /ping — confirma que la key es válida; devuelve tenantId, tenantPlatformId, scopes y serverTime.

Tipos de entidad​

product, variant, category, collection, brand, page.

FAQ en los endpoints de señales​

Las FAQs aprobadas y visibles forman parte de los endpoints .jsonld de todos los tipos de entidad. Cuando una entidad las tiene, el @graph incluye un nodo FAQPage junto al nodo de la propia entidad:

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Product", "name": "...", ... },
    { "@type": "FAQPage", "mainEntity": [...] }
  ]
}

Aplica a:

  • GET /api/v1/{platform}/products/:id.jsonld
  • GET /api/v1/shopify/collections/:id.jsonld
  • GET /api/v1/{platform}/categories/:id.jsonld (BigCommerce, WooCommerce)
  • GET /api/v1/{platform}/pages/:id.jsonld

En el storefront, el JSON-LD FAQPage viaja en el grafo server-side que Clione publica a través de la plataforma. El widget (embed.js) pinta el acordeón de FAQ visible, y no añade un segundo FAQPage cuando la página ya lleva uno.