Ir al contenido

Referencia de la API

Base: https://api.lectoresbeta.com/api/v1. Todas las peticiones llevan Authorization: Bearer <access_token> y, las que tienen cuerpo, Content-Type: application/json. Los ejemplos están resumidos: una respuesta puede traer más campos, que debes ignorar si no los usas.

A quién representa tu aplicación. Vale cualquier token válido, sea cual sea su permiso.

{
"userId": "0192f8a1-4c3b-7e2a-9f10-6b5d2c8e4a71",
"username": "beatriz",
"name": "Beatriz Ramos",
"avatarUrl": "https://…/avatar.webp"
}

name y avatarUrl pueden ser null. No se expone el correo ni el resto del perfil.

Las obras propias, paginadas.

Parámetro Valores Por defecto
status DRAFT, PUBLISHED, IN_CORRECTION todas
format CHAPTERED, SINGLE_TEXT todos
sort recent, oldest, rated, read recent
page desde 1 1
perPage de 1 a 50 20
{
"total": 3,
"totalPages": 1,
"page": 1,
"perPage": 20,
"works": [
{
"workId": "0192f8a2-0000-7000-9000-000000000001",
"title": "El cuaderno de bitácora",
"synopsis": null,
"status": "DRAFT",
"format": "CHAPTERED",
"wordCount": 1300,
"chapterCount": 2,
"genres": ["SCIENCE_FICTION"],
"beingCorrected": false,
"archived": false,
"createdAt": "2026-11-05T10:00:00+00:00",
"updatedAt": "2026-11-05T10:20:00+00:00"
}
]
}

El listado no trae la revision ni el texto: para eso, la obra entera.

Crea una obra con sus capítulos, en borrador.

{
"title": "El cuaderno de bitácora",
"synopsis": "Una travesía contada por quien no quería ir.",
"genres": ["SCIENCE_FICTION"],
"format": "CHAPTERED",
"chapters": [
{ "title": "Uno", "contentHtml": "<p>Primer capítulo…</p>" },
{ "title": "Dos", "contentHtml": "<p>Segundo capítulo…</p>" }
]
}
Campo Obligatorio Notas
title Sí Hasta 180 caracteres
synopsis No
genres No Hasta 3 códigos (SCIENCE_FICTION, CRIME…) del catálogo público GET /api/v1/genres, que no necesita token
format No CHAPTERED (por defecto) o SINGLE_TEXT, que admite un solo capítulo
chapters Sí En orden. title opcional; contentHtml con texto (ver el contenido de un capítulo)

Respuesta 201:

{
"workId": "0192f8a2-0000-7000-9000-000000000001",
"revision": 3,
"chapterIds": ["0192f8a3-…-01", "0192f8a3-…-02"]
}

La obra entera, con el texto de cada capítulo y la revisión actual.

{
"workId": "0192f8a2-0000-7000-9000-000000000001",
"title": "El cuaderno de bitácora",
"synopsis": null,
"status": "DRAFT",
"format": "CHAPTERED",
"revision": 3,
"chapters": [
{
"chapterId": "0192f8a3-…-01",
"position": 1,
"title": "Uno",
"status": "IN_CORRECTION",
"version": 1,
"wordCount": 900,
"blocked": false,
"contentHtml": "<p>Primer capítulo…</p>"
}
]
}

POST /connect/works/{workId}/revisions — works:write

Sección titulada «POST /connect/works/{workId}/revisions — works:write»

Una versión nueva de la obra entera, escrita sobre baseRevision. Las reglas están en Publicar una versión nueva.

{
"baseRevision": 3,
"chapters": [
{ "chapterId": "0192f8a3-…-02", "title": "Dos", "contentHtml": "<p>…</p>" },
{ "chapterId": "0192f8a3-…-01", "title": "Uno, revisado", "contentHtml": "<p>…</p>" },
{ "title": "Tres", "contentHtml": "<p>…</p>" }
],
"removedChapterIds": []
}

Respuesta 201, con los capítulos en su orden final:

{
"workId": "0192f8a2-0000-7000-9000-000000000001",
"revision": 6,
"chapterIds": ["0192f8a3-…-02", "0192f8a3-…-01", "0192f8a3-…-03"]
}

Errores propios: 409 WORK_REVISION_CONFLICT (con currentRevision), 422 CHAPTER_OMITTED, 422 CHAPTER_NOT_IN_WORK, 422 CHAPTER_LISTED_TWICE, 422 EMPTY_CHAPTER, 409 CHAPTER_HAS_CORRECTIONS, 409 CHAPTER_BLOCKED, 409 SINGLE_TEXT_HAS_ONE_CHAPTER, 409 WORK_NEEDS_A_CHAPTER.

GET /connect/works/{workId}/status — works:read

Sección titulada «GET /connect/works/{workId}/status — works:read»

Dónde está la obra.

{
"workId": "0192f8a2-0000-7000-9000-000000000001",
"status": "IN_CORRECTION",
"revision": 6,
"beingCorrected": true,
"chapters": [
{
"chapterId": "0192f8a3-…-02",
"position": 1,
"status": "PUBLISHED",
"version": 1,
"correctable": false,
"hasBeenCorrected": false
},
{
"chapterId": "0192f8a3-…-01",
"position": 2,
"status": "IN_CORRECTION",
"version": 2,
"correctable": true,
"hasBeenCorrected": true
}
]
}
  • beingCorrected: alguien está corrigiendo la obra ahora mismo. No dice quién.
  • correctable: la obra y el capítulo están abiertos a corrección y el capítulo no está bloqueado.
  • hasBeenCorrected: algún lector empezó a corregir este capítulo alguna vez.

POST /connect/works/{workId}/correction-opening — works:write

Sección titulada «POST /connect/works/{workId}/correction-opening — works:write»

Pedir correcciones: abre la obra y los capítulos indicados. Ver Pedir correcciones.

{ "chapterIds": ["0192f8a3-…-01"], "publishIfDraft": false }

Respuesta 200 con la misma forma que /status. Errores propios: 409 ILLEGAL_WORK_TRANSITION (obra en borrador sin publishIfDraft), 422 CHAPTER_NOT_IN_WORK, 409 CHAPTER_BLOCKED.

Las correcciones entregadas a la persona, de la más reciente a la más antigua.

Parámetro Valores Por defecto
workId Solo las de esta obra todas
chapterId Solo las de este capítulo todos
unread true: solo las que la autora no ha abierto false
hidden true: solo las que la autora apartó false
limit de 1 a 100 50
offset desde 0 0
{
"corrections": [
{
"correctionId": "0192f8a4-…",
"workId": "0192f8a2-…",
"workTitle": "El cuaderno de bitácora",
"chapterId": "0192f8a3-…-01",
"chapterTitle": "Uno",
"chapterPosition": 2,
"readerId": "0192f8a1-…",
"anonymous": false,
"authorLabel": "@lectora",
"origin": "BETA_READER",
"visibility": "VISIBLE",
"questionnaireVersion": 2,
"submittedAt": "2026-11-05T12:00:00+00:00",
"read": false,
"stars": null,
"replied": false,
"betweenWritingBuddies": false
}
]
}
  • anonymous: quien corrigió pidió no ser identificado; readerId llega null y authorLabel dice cómo nombrarlo.
  • origin: BETA_READER (lector con cuenta) o PUBLIC_LINK (alguien sin cuenta, por un enlace público).
  • visibility: VISIBLE, LOCKED (retenida por saldo negativo: sin contenido hasta que se recupere) o HIDDEN_BY_AUTHOR.

GET /connect/corrections/{correctionId} — feedback:read

Sección titulada «GET /connect/corrections/{correctionId} — feedback:read»

Una corrección con las respuestas a su cuestionario. Abrirla la marca como leída (salvo que esté LOCKED).

{
"correctionId": "0192f8a4-…",
"chapterId": "0192f8a3-…-01",
"visibility": "VISIBLE",
"questionnaireVersion": 2,
"submittedAt": "2026-11-05T12:00:00+00:00",
"answers": [
{
"questionId": "0192f8a5-…",
"position": 1,
"statement": "¿Cómo funciona el ritmo?",
"type": "TEXT",
"text": "El arranque es lento, pero…",
"wordCount": 64,
"value": null,
"chosen": []
},
{
"questionId": "0192f8a5-…",
"position": 2,
"statement": "¿Te ha enganchado?",
"type": "YES_NO",
"text": "",
"wordCount": 0,
"value": true,
"chosen": []
}
]
}
  • statement es el enunciado tal como estaba cuando se respondió, aunque la autora haya cambiado el cuestionario después.
  • type es TEXT, SCALE, SINGLE_CHOICE, MULTIPLE_CHOICE o YES_NO. La respuesta está en text (TEXT), value (SCALE o YES_NO) o chosen (las de opciones, con la etiqueta de cada opción marcada).
  • Con visibility: LOCKED, answers llega vacío.

GET /connect/corrections/{correctionId}/chapter-text — feedback:read

Sección titulada «GET /connect/corrections/{correctionId}/chapter-text — feedback:read»

El texto exacto sobre el que se hizo la corrección.

{
"correctionId": "0192f8a4-…",
"chapterId": "0192f8a3-…-01",
"title": "Uno",
"contentHtml": "<p>Primer capítulo…</p>",
"wordCount": 900,
"version": 1,
"isCurrentVersion": false
}

isCurrentVersion: false significa que el capítulo se ha reescrito desde entonces: útil para enseñar la corrección junto al texto que la motivó.

GET /connect/credits/balance — credits:read

Sección titulada «GET /connect/credits/balance — credits:read»
{ "balance": 12 }

El saldo puede ser negativo. Solo se puede leer: ninguna aplicación puede mover créditos.

GET /connect/works/{workId}/correction-affordability — credits:read

Sección titulada «GET /connect/works/{workId}/correction-affordability — credits:read»

Si el saldo alcanza para recibir una corrección de cada capítulo de una obra propia.

{
"workId": "0192f8a2-…",
"balance": 12,
"chapters": [
{ "chapterId": "0192f8a3-…-01", "price": 4, "affordable": true },
{ "chapterId": "0192f8a3-…-02", "price": 15, "affordable": false }
]
}

Usa affordable tal cual: lo decide la plataforma, con reglas que no se ven desde fuera (por ejemplo, el descubierto concedido). Un capítulo recién creado puede tardar un momento en tener precio; una obra sin ningún capítulo con precio responde 404 WORK_NOT_FOUND.

Endpoint Para qué
GET /api/v1/genres El catálogo de temáticas (code, name). Público, sin token
GET /api/v1/oauth/authorize, POST /api/v1/oauth/token, POST /api/v1/oauth/revoke Ver Autorización

Última actualización: