Publicar tu centro de ayuda

POST /help-centers levanta el portal de autoservicio que tus clientes leen por su cuenta, con preguntas frecuentes, políticas y guías de uso. No es la misma biblioteca que cita el agente, pero las dos están conectadas. Publicar un artículo lo sincroniza en la base de conocimiento, y el agente lo empieza a citar con el mismo texto que ve el lector.

Leer pide help_centers:read; escribir, help_centers:write. Un workspace puede tener más de un centro de ayuda.

Crear un centro

curl -X POST https://api.vitrinadev.com/api/v1/help-centers \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Centro de ayuda", "slug": "ayuda" }'

Nace sin publicar (is_published: false). Publícalo con PUT una vez que tenga contenido:

curl -X PUT https://api.vitrinadev.com/api/v1/help-centers/a8a8a8a8-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_published": true, "primary_color": "#0EA5E9" }'

slug es único por workspace y decide la URL del lector. default_locale y supported_locales deciden en qué idiomas existe el portal; eso se arma en Locales.

Secciones

Una sección es una carpeta del árbol de navegación y no lleva texto propio. Su título y su descripción son una traducción, así que crearla pide una desde el principio:

curl -X POST https://api.vitrinadev.com/api/v1/help-centers/a8a8a8a8-0000-4000-8000-000000000001/sections \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "politicas",
    "translation": { "locale": "es", "title": "Políticas", "description": "Reembolsos, cambios y garantías" }
  }'

parent_id anida una sección bajo otra y position decide el orden. POST /help-centers/{id}/sections/reorder reordena de una vez, y es atómico: si un section_id no pertenece a este centro, no se mueve ninguna.

Artículos

curl -X POST https://api.vitrinadev.com/api/v1/help-centers/a8a8a8a8-0000-4000-8000-000000000001/articles \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "translation": { "locale": "es", "title": "" } }'

{
  "data": {
    "id": "b2b2b2b2-0000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "section_id": null,
    "slug": "articulo-nuevo",
    "status": "internal",
    "position": 0,
    "scheduled_publish_at": null,
    "translations": [{ "locale": "es", "title": "", "body": "" }],
    "created_at": "2026-09-22T12:00:00.000Z",
    "updated_at": "2026-09-22T12:00:00.000Z"
  }
}

El artículo puede nacer con el title vacío. Nace internal, y nadie de afuera lo ve hasta que lo publicas. POST /help-centers/{id}/articles/from-file crea uno directo desde un PDF, DOCX o XLSX subido, y extrae el texto en el servidor.

El ciclo de publicación

PUT /help-centers/{id}/articles/{articleId} solo toca estructura y ciclo de vida, o sea sección y posición. Para editar el texto van las rutas de traducción.

Traducciones

curl -X PUT https://api.vitrinadev.com/api/v1/help-centers/a8a8a8a8-0000-4000-8000-000000000001/articles/b2b2b2b2-0000-4000-8000-000000000001/translations/$LOCALE \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Refund policy", "body": "Refunds are issued within 10 business days." }'

Es la ruta por la que autoguarda el editor, y acepta un title vacío mientras la persona sigue escribiendo. Si el artículo ya está publicado, guardar re-sincroniza esa traducción a la base de conocimiento de inmediato.

POST /help-centers/{id}/articles/{articleId}/translations/{locale}/generate traduce un artículo con IA. Es síncrono y sobrescribe lo que hubiera en ese locale.

POST /help-centers/{id}/articles/bulk-translate hace lo mismo para todos los artículos del centro, encolado. min_status elige qué celdas tocar: missing solo llena huecos, y outdated, el valor por defecto, además retraduce las que cambiaron.

curl "https://api.vitrinadev.com/api/v1/help-centers/a8a8a8a8-0000-4000-8000-000000000001/translation-coverage" \
  -H "Authorization: Bearer $VITRINA_KEY"

Devuelve la matriz artículo × locale (up_to_date, outdated, missing, draft) con el mismo cálculo que decide qué toca bulk-translate. Sirve para previsualizar qué haría una corrida antes de lanzarla.

Revisar antes de publicar

POST /help-centers/{id}/articles/{articleId}/preview-link emite un token firmado, válido 24 horas, para leer un artículo sin publicarlo. Con ese enlace alguien revisa el borrador en el portal real.

POST /help-centers/{id}/articles/{articleId}/lock toma el candado de edición para que dos personas no se pisen. Pide una sesión de usuario, así que una API key sin persona detrás no puede tomarlo, y devuelve quién lo tiene aunque pierdas la carrera. DELETE /help-centers/{id}/articles/{articleId}/lock lo libera.

Retroalimentación del lector

curl "https://api.vitrinadev.com/api/v1/help-centers/a8a8a8a8-0000-4000-8000-000000000001/articles/b2b2b2b2-0000-4000-8000-000000000001/feedback" \
  -H "Authorization: Bearer $VITRINA_KEY"

{ "data": { "helpful": 12, "not_helpful": 1, "total": 13 } }

GET /help-centers/{id}/feedback trae el mismo voto agregado por todo el centro.

Locales

curl -X POST https://api.vitrinadev.com/api/v1/help-centers/a8a8a8a8-0000-4000-8000-000000000001/locales \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "locale": "en" }'

Agregar un locale no traduce nada: abre la columna que bulk-translate llena después. POST /help-centers/{id}/locales/{locale}/default cambia cuál ve el lector sin preferencia explícita, y desde cuál traduce bulk-translate. El locale por defecto no se puede quitar con DELETE /help-centers/{id}/locales/{locale}; cambia primero cuál es el default.

Medios

POST /help-centers/{id}/media sube imágenes, video o documentos para los bloques del editor, en multipart y hasta 50 MB. DELETE /help-centers/{id}/media/{mediaId} borra el archivo. Un artículo que todavía lo incrusta no se reescribe, así que su imagen empieza a responder 404.

Borrar

DELETE /help-centers/{id} se lleva secciones, artículos y traducciones con él. Borrar una sección o un artículo es definitivo, y no hay papelera.