Ir al contenido

Obras y versiones

Esta página explica las reglas. La forma exacta de cada petición y respuesta está en la Referencia de la API.

  • Una obra tiene un título, una sinopsis opcional, hasta tres temáticas, un formato (CHAPTERED, por capítulos, o SINGLE_TEXT, texto corto de un solo capítulo) y un estado:
    • DRAFT — borrador: solo la ve su autora;
    • PUBLISHED — publicada: se puede leer;
    • IN_CORRECTION — abierta a corrección: los lectores beta pueden corregirla.
  • Cada capítulo tiene su propio estado (DRAFT, PUBLISHED, IN_CORRECTION). Un capítulo se puede corregir solo cuando la obra y el capítulo están en IN_CORRECTION.
  • La obra tiene una revisión (revision), un número que sube con cada cambio de su texto: añadir, editar, quitar o reordenar capítulos, venga el cambio de tu aplicación o de la propia plataforma. Cambiar de estado no la mueve.
  • Cada capítulo tiene una versión (version), que sube cuando se reescribe un texto que alguien ya había empezado a corregir. La versión anterior se conserva.

POST /connect/works con el título y los capítulos, todo de una vez:

  • la obra nace siempre en borrador: subir un manuscrito no es publicarlo;
  • todo ocurre en una transacción: o se crea entera o no se crea;
  • la respuesta trae el workId, la revision y los chapterIds en el mismo orden en que enviaste los capítulos. Guárdalos: son la forma de referirte a cada capítulo en adelante.

GET /connect/works/{workId} devuelve la obra con el texto completo de cada capítulo, su estado, su versión y la revision actual. Es lo que tu aplicación necesita para sincronizar. No cuenta como lectura en las estadísticas de la obra.

Solo funciona con obras de la persona que autorizó tu aplicación. La obra de otra persona responde 404, igual que una que no existe.

POST /connect/works/{workId}/revisions envía la obra entera tal como debe quedar:

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

Las reglas:

  1. baseRevision es la revisión sobre la que trabajaste, la que te devolvió la última lectura o la última versión publicada. Si la obra ha cambiado desde entonces —por ejemplo, la autora corrigió una errata desde el navegador— no se aplica nada y la respuesta es 409 WORK_REVISION_CONFLICT con la revisión actual en currentRevision.
  2. Un capítulo con chapterId es ese capítulo, editado. Conserva su identificador, su estado y sus correcciones. Sin chapterId es un capítulo nuevo, y la respuesta te devuelve su identificador.
  3. El orden de chapters es el orden final de la obra.
  4. No hay borrados implícitos. Todo capítulo que ya existe tiene que estar en chapters o en removedChapterIds. Si falta en los dos, la respuesta es 422 CHAPTER_OMITTED y no se aplica nada. Así un fallo de sincronización nunca borra capítulos.
  5. No se puede quitar un capítulo que ya tiene correcciones (409 CHAPTER_HAS_CORRECTIONS) ni uno bloqueado por moderación (409 CHAPTER_BLOCKED). Un capítulo bloqueado se puede enviar sin cambios, pero no editar.
  6. Un capítulo que envías sin cambios no se toca.
  7. Publicar una versión no cambia el estado de la obra ni de ningún capítulo: una obra en borrador sigue en borrador.
  8. Todo ocurre en una transacción: se aplica la versión entera o nada.

La respuesta trae la nueva revision y los chapterIds en su orden final. Guárdala: es la baseRevision de la próxima vez.

Un 409 WORK_REVISION_CONFLICT significa que alguien cambió la obra mientras tu aplicación tenía una copia. No reintentes con la revisión nueva sin más: pisarías ese cambio. Lee la obra de nuevo (GET /connect/works/{workId}), enséñale a la persona qué ha cambiado y deja que decida qué versión se queda.

Lo que pasa con el texto que se estaba corrigiendo

Sección titulada «Lo que pasa con el texto que se estaba corrigiendo»

Si reescribes un capítulo que algún lector ya había empezado a corregir, el texto que corrigió se guarda y el capítulo pasa a la versión siguiente. Su corrección sigue apuntando a lo que leyó, y puedes recuperar ese texto exacto con GET /connect/corrections/{correctionId}/chapter-text. Si nadie lo había empezado a corregir, el texto simplemente se sustituye.

contentHtml es HTML, y se sanea al guardarlo con la misma lista blanca que el editor de la plataforma:

Se conserva Se quita la etiqueta y se conserva el texto
p, br, strong, em, blockquote, h2, h3, hr div, span, b, i, u, a, h1, h4–h6, listas, tablas y similares
  • Ningún atributo se conserva (class, style, href…).
  • Imágenes, scripts y cualquier otra etiqueta se eliminan.
  • Un capítulo que se queda sin texto tras sanear se rechaza (422 EMPTY_CHAPTER).
  • El recuento de palabras lo calcula la plataforma a partir del texto, no se envía.

Si tu aplicación usa otro formato (Markdown, un documento propio), conviértelo a ese HTML antes de enviarlo, y ten en cuenta que lo que vuelvas a leer será la versión saneada.

En la plataforma, las correcciones las escriben los lectores beta. Lo que hace la autora es abrir la obra y los capítulos que quiere que le corrijan. Eso es POST /connect/works/{workId}/correction-opening:

{ "chapterIds": ["0192f8a2-…-01", "0192f8a2-…-02"], "publishIfDraft": false }
  • Pone la obra en IN_CORRECTION y, con ella, los capítulos indicados. Los demás capítulos no cambian.
  • Una obra en borrador se rechaza (409 ILLEGAL_WORK_TRANSITION) salvo que envíes "publishIfDraft": true. Publicar nunca es un efecto secundario: tu aplicación tiene que pedirlo expresamente, y debería hacerlo solo cuando la persona lo haya elegido.
  • En un texto corto (SINGLE_TEXT) el único capítulo sigue a la obra.
  • No mueve créditos. La autora paga cuando recibe cada corrección, con las reglas de siempre. Para saber si su saldo alcanza, usa GET /connect/works/{workId}/correction-affordability y fíate de su campo affordable: no compares saldo y precio por tu cuenta, porque hay reglas (como el descubierto concedido) que tu aplicación no ve.
  • Quién puede corregir (la modalidad de acceso), el cuestionario y las invitaciones a lectores se gestionan en la plataforma, no desde la API.

La respuesta es el estado resultante, con lo mismo que devuelve GET /connect/works/{workId}/status.

Con feedback:read:

  1. GET /connect/corrections?workId=… lista las correcciones entregadas de una obra (sin workId, las de todas).
  2. GET /connect/corrections/{correctionId} trae una con las respuestas a su cuestionario. Abrirla la marca como leída para la autora, igual que en la plataforma.
  3. GET /connect/corrections/{correctionId}/chapter-text trae el texto exacto que se corrigió y te dice si sigue siendo la versión actual (isCurrentVersion).

Si el saldo de la autora es negativo, las correcciones pendientes de pago aparecen con visibility: LOCKED y sin respuestas: existen, pero su contenido se retiene hasta que el saldo se recupere. Enséñalo así en tu aplicación, no como si no hubiera nada.

  • Guarda la revision de cada obra. Si GET /connect/works/{workId}/status devuelve la misma, no hace falta volver a descargar el texto.
  • No consultes en bucle. Actualiza cuando la persona abre la obra o lo pide.

Última actualización: