Desarrolla sobre Eyivo con una API estructurada.

1. Descripción general

La API REST de Eyivo permite administrar sitios web estructurados mediante programación. Usa HTTPS y JSON, está versionada en /api/v1 y aplica las mismas reglas de propiedad, límites del plan, validación y auditoría que el panel.

Versionado: Los cambios que rompen el contrato requieren una nueva versión base. Pueden añadirse campos a los objetos JSON existentes; los clientes deben ignorar los que no reconocen.

2. Inicio rápido

1. 1
   Crea un token.

   Inicia sesión en la aplicación, abre Tokens de API, elige los ámbitos mínimos necesarios y copia el ey_ secreto cuando aparezca.

2. 2
   Lista tus sitios.

   Confirma la autenticación y obtén el ID numérico del sitio que usan los endpoints dependientes.

3. 3
   Envía solicitudes de escritura idempotentes.

   Asigna a cada solicitud POST, PATCH y DELETE una clave Idempotency-Key.

curl --request GET \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token'

Una respuesta correcta a una consulta de colección agrupa los registros en data:

{
  "data": [
    {
      "id": 42,
      "platform_subdomain_key": "7kr9mp2x",
      "template_key": "corporate-01",
      "status": "active",
      "native_locale": "en",
      "english_enabled": false,
      "content_version": 1,
      "search_visibility": "platform_noindex"
    }
  ]
}

3. Autenticación

Todas las solicitudes a /api/v1 requieren un token de acceso:

Authorization: Bearer <token>

Flujo de autorización PKCE

1. Crea un code_verifier de alta entropía y su code_challenge SHA-256.
2. Redirige al usuario a /oauth/authorize con response_type=code, el client_id público, el redirect_uri registrado exacto, los ámbitos solicitados en scope separados por espacios, state, code_challenge y code_challenge_method=S256.
3. Comprueba state tras la redirección y canjea el código de autorización en /oauth/token usando el code_verifier original.
4. Guarda de forma segura los tokens de acceso y renovación. Renuévalos antes de que caduquen y sustituye de forma atómica las credenciales rotadas.

4. Ámbitos

Cada solicitud necesita el ámbito indicado a continuación. Un token personal con * supera todas las comprobaciones de ámbito, pero las aplicaciones deben solicitar solo los permisos necesarios.

REST requiere el permiso del endpoint, no mcp:use. Los endpoints multimedia usan media:read o media:write.

5. Escrituras idempotentes

Envía Idempotency-Key en las modificaciones JSON para repetir la misma solicitud de forma segura. Las cargas multipart y la emisión de tickets quedan excluidas; verifica el resultado antes de reintentar.

Idempotency-Key: site-42-page-create-01J7M6Y8RRF3ZE6WB4Z0Y9XJXC

Para comparar solicitudes se tienen en cuenta el método HTTP, la ruta y el cuerpo bruto exacto. Al reintentarlo, utiliza el mismo JSON serializado.

6. Respuestas y estructura de los recursos

Las operaciones de contenido devuelven un envoltorio data. MCP devuelve structuredContent y una copia JSON en texto; REST devuelve JSON. Consulta los esquemas para IDs, preparación y paginación. Blogs, archivos y envíos incluyen información de páginas.

{ "data": { "id": 42, "status": "active" } }

{ "data": [{ "id": 42 }, { "id": 43 }] }

Las colecciones tienen formatos distintos. Sigue los metadatos de paginación de cada endpoint; no supongas que todas son listas simples o sin paginar.

7. Sitios

Crear un sitio

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: site-create-01J7M6Y8' \
  --data '{
    "display_name": "Northstar Studio",
    "template_key": "corporate-01",
    "native_locale": "en"
  }'

Respuesta: 201 Created con un recurso de sitio. Durante la asignación inicial, el estado puede no ser todavía activo. Si se supera un límite de sitios o del plan, se devuelve 422.

Campos del recurso de sitio: id, platform_subdomain_key, template_key, status, native_locale, english_enabled, content_version, search_visibility, runtime opcional y marcas de tiempo.

8. Páginas

Crear una página

{
  "type": "page",
  "sort_order": 300,
  "locale": "en",
  "slug": "our-story",
  "title": "Our story",
  "body": "<p>How the company began.</p>",
  "meta_title": "Our story | Northstar Studio",
  "meta_description": "Learn about Northstar Studio."
}

Respuesta al crear: 201. Respuesta al actualizar: 200. Respuesta al eliminar: 204, sin cuerpo.

Guarda un borrador, comprueba si está listo y publica ese elemento e idioma cuando el usuario quiera hacerlo visible. Los demás borradores no se publican.

9. Elementos del catálogo

Crear un elemento del catálogo

{
  "sort_order": 100,
  "locale": "en",
  "slug": "strategy-advisory",
  "title": "Strategy advisory",
  "summary": "Focused advice for consequential decisions.",
  "body": "Talk to our senior advisory team."
}

Guarda un borrador, comprueba si está listo y publica ese elemento e idioma cuando el usuario quiera hacerlo visible. Los demás borradores no se publican.

Estos son ejemplos por área de contenido. Descubre todos los esquemas y permisos en tools/list o en OpenAPI. Las rutas REST son relativas a /api/v1/sites/{site}.

Capacidades y contrato de edición

Selecciona un sitio y consulta sus capacidades: idiomas activos, campos del tema, esquemas de componentes, menús y paneles de plugins. Lee el recurso content-workflow antes de escribir. Los clientes sin recursos pueden usar get-site-capabilities-tool. Sigue nextCursor de tools/list hasta completar el catálogo.

GET /api/v1/sites/{site}/capabilities
GET /api/v1/sites/{site}/pages/{page_id}/components/schema?locale=en

Usa el idioma solicitado y la version o revision actual. Guardar un blog reemplaza el documento completo y cancela su programación. Los menús usan revision numérica; las asignaciones usan un hash menu_revision independiente. Conserva los elementos de las listas reemplazadas. Ante un conflicto, vuelve a leer y combina los cambios.

La navegación principal sigue siendo automática. Los menús adicionales tienen sus propios borradores y publicación. Guardar contenido prepara sus asignaciones; publicar el elemento las aplica sin publicar otros menús. Publicar un menú nunca publica su contenido enlazado. source_hash rechaza traducciones basadas en texto de origen obsoleto.

El cuerpo de las páginas y los campos richtext aceptan HTML saneado. Usa list-page-links-tool para enlaces estables /__eyivo/pages/{id}, resueltos en el idioma del visitante cuando estén publicados. Los blogs usan document JSON estructurado con media_id del mismo sitio y destinos de página/entrada, no body_html.

{
  "type": "doc",
  "content": [{
    "type": "paragraph",
    "content": [{ "type": "text", "text": "Our story" }]
  }]
}

Cargar imágenes y vídeos

upload-media-tool abre un selector de archivos en clientes MCP Apps como Claude. ChatGPT también puede proporcionar su referencia de adjunto; un adjunto de Claude no es una referencia de archivo OpenAI. No inventes URLs de descarga ni envíes archivos base64 como argumentos.

Codex y Claude Code pueden llamar a prepare-media-upload-tool y enviar el archivo multipart a upload_url con su upload_token de un solo uso en cinco minutos. Mantén el token en secreto. Los clientes REST pueden usar su bearer media:write. Solo una carga completada devuelve el ID del archivo; emitir un ticket no carga nada.

POST /api/v1/sites/{site}/media
Authorization: Bearer <media:write token>
Content-Type: multipart/form-data; boundary=<generated by HTTP client>

file: <original file bytes>

10. Dominios personalizados

Solicitar un dominio

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites/42/domains \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: domain-request-example-com' \
  --data '{"domain":"www.example.com"}'

Un dominio pendiente incluye verification_token. Añade el registro DNS requerido para demostrar la propiedad, espera su propagación y llama al endpoint de activación. Una vez activo, llama al endpoint principal si debe convertirse en el nombre de host público canónico.

Campos del recurso de dominio: id, domain, site_id, is_primary, status, verification_token cuando corresponda y marcas de tiempo. Los límites del plan y los errores de validación de dominio devuelven 422.

11. Errores

Respuesta de validación

{
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."]
  }
}

Respuesta de autenticación o autorización

{
  "message": "Missing required scope [content:write]."
}

12. Límites actuales y lista de verificación de integración

REST v1 expone deliberadamente un conjunto limitado de funciones de Eyivo. Que no exista un endpoint no autoriza a llamar a las API internas.

Antes de pasar a producción

• Usa HTTPS y comprueba que el host esperado sea app.eyivo.com.
• Mantén los tokens de acceso en el servidor y oculta los encabezados de autorización en los registros.
• Solicita solo los ámbitos necesarios y prefiere tokens personales limitados a un sitio cuando sea posible.
• Utiliza una clave de idempotencia única para cada operación de escritura y consérvala en todos los reintentos.
• Considera 401, 403, 404 y 422 errores no transitorios, salvo que cambien la solicitud o las credenciales.
• Usa reintentos con espera exponencial y variación aleatoria ante errores transitorios, y respeta cualquier futuro encabezado Retry-After.
• Las colecciones tienen formatos distintos. Sigue los metadatos de paginación de cada endpoint; no supongas que todas son listas simples o sin paginar.