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.
Qué puede hacer una aplicación
Sección titulada «Qué puede hacer una aplicación»| 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.
Cómo funciona, en una frase
Sección titulada «Cómo funciona, en una frase»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.
Lo que te damos al acordar la integración
Sección titulada «Lo que te damos al acordar la integració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) enhttp://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
httpscompletas, que se comparan exactamente.
- para una aplicación de escritorio, una o varias rutas (por ejemplo
- Los permisos que tu aplicación puede llegar a pedir.
- La especificación OpenAPI completa, si la quieres para generar un cliente.
Direcciones
Sección titulada «Direcciones»| 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/… |
Convenciones de la API
Sección titulada «Convenciones de la API»- JSON en UTF-8 en todas las peticiones y respuestas de
/connect. Los endpoints de/oauth/tokeny/oauth/revokereciben 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 uncodeestable, salvo en/oauth/tokeny/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.
Por dónde seguir
Sección titulada «Por dónde seguir»- Autorización: el flujo completo, los tokens y su renovación.
- Permisos: qué pide cada operación.
- Obras y versiones: crear, sincronizar y pedir correcciones sin pisar el trabajo de nadie.
- Referencia de la API: cada endpoint, con ejemplos.
- 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_verifiery unstatenuevos en cada intento, y compruebas elstateal 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
401renuevas una vez; si la renovación dainvalid_grant, vuelves a pedir autorización. - Al publicar una versión envías
baseRevision, y ante un409vuelves 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.