Ir al contenido

Integrar una aplicación

Esta sección es para quien desarrolla una aplicación —un editor de textos de escritorio, un complemento para un procesador de textos, una herramienta de escritura— que quiere trabajar con la cuenta de una persona: subir sus obras, publicar versiones nuevas, pedir correcciones, traer las correcciones que recibe y consultar su saldo de créditos.

Si lo que buscas es cómo autorizar o desconectar una aplicación como usuario, lo cuenta Aplicaciones conectadas.

Para Con el permiso Página
Saber a qué cuenta está conectada (cualquiera) Referencia de la API
Listar y leer las obras de la persona works:read Obras y versiones
Crear obras y publicar versiones nuevas works:write Obras y versiones
Pedir correcciones works:write Obras y versiones
Leer correcciones y cuestionarios feedback:read Referencia de la API
Consultar el saldo de créditos credits:read Referencia de la API

Lo que no puede hacer ninguna aplicación, con ningún permiso: ver la contraseña o la sesión de la persona, mover créditos, publicar una obra sin que se le pida expresamente, ni leer obras o correcciones de otras personas.

OAuth 2.0 con Authorization Code y PKCE (S256), el flujo estándar para aplicaciones nativas y alojadas en la web (RFC 6749, RFC 7636, RFC 8252). La aplicación abre el navegador, la persona entra en la plataforma y autoriza, y la aplicación recibe un código que cambia por sus propios tokens. Con ellos llama a la API. Todo el detalle está en Autorización.

  • Un client_id: el identificador público de tu aplicación. No hay secreto de cliente: todas las aplicaciones son clientes públicos y lo que protege el flujo es PKCE.
  • Las direcciones de retorno registradas, que acordamos contigo:
    • para una aplicación de escritorio, una o varias rutas (por ejemplo /callback) en http://127.0.0.1:{puerto}, con el puerto que tu aplicación elija cada vez;
    • para una aplicación alojada en la web, una o varias URIs https completas, que se comparan exactamente.
  • Los permisos que tu aplicación puede llegar a pedir.
  • La especificación OpenAPI completa, si la quieres para generar un cliente.
Qué Dirección
Base de la API https://api.lectoresbeta.com/api/v1
Inicio de autorización https://api.lectoresbeta.com/api/v1/oauth/authorize
Tokens https://api.lectoresbeta.com/api/v1/oauth/token
Revocación https://api.lectoresbeta.com/api/v1/oauth/revoke
Recursos https://api.lectoresbeta.com/api/v1/connect/…
  • JSON en UTF-8 en todas las peticiones y respuestas de /connect. Los endpoints de /oauth/token y /oauth/revoke reciben formulario (application/x-www-form-urlencoded), como exige OAuth.
  • Los identificadores son UUID en minúsculas (0192f8a1-4c3b-7e2a-9f10-6b5d2c8e4a71). Trátalos como cadenas opacas.
  • Las fechas van en ISO 8601 con zona (2026-11-05T10:00:00+00:00).
  • El texto de los capítulos es HTML saneado. Ver Obras y versiones.
  • Los errores siguen RFC 9457 (application/problem+json) con un code estable, salvo en /oauth/token y /oauth/revoke, que siguen el formato de OAuth. Ver Errores.
  • Un campo que no conozcas en una respuesta ignóralo: añadir campos no se considera un cambio incompatible.
  1. Autorización: el flujo completo, los tokens y su renovación.
  2. Permisos: qué pide cada operación.
  3. Obras y versiones: crear, sincronizar y pedir correcciones sin pisar el trabajo de nadie.
  4. Referencia de la API: cada endpoint, con ejemplos.
  5. Errores: qué significa cada respuesta y qué hacer.

Lista de comprobación antes de publicar tu integración

Sección titulada «Lista de comprobación antes de publicar tu integración»
  • Abres la autorización en el navegador del sistema, no en una vista web incrustada.
  • Generas un code_verifier y un state nuevos en cada intento, y compruebas el state al volver.
  • Guardas los tokens en el almacén seguro del sistema operativo (Keychain, Credential Manager, libsecret) o, en la web, en el servidor, nunca en el navegador.
  • Guardas el nuevo token de refresco cada vez que renuevas, y nunca renuevas dos veces a la vez con el mismo.
  • Ante un 401 renuevas una vez; si la renovación da invalid_grant, vuelves a pedir autorización.
  • Al publicar una versión envías baseRevision, y ante un 409 vuelves a leer la obra y dejas decidir a la persona.
  • Al cerrar sesión en tu aplicación llamas a /oauth/revoke.
  • No registras tokens, códigos ni verificadores en logs ni en informes de errores.

Última actualización: