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.
Los conceptos
Sección titulada «Los conceptos»- Una obra tiene un título, una sinopsis opcional, hasta tres temáticas, un formato
(
CHAPTERED, por capítulos, oSINGLE_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 enIN_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.
Crear una obra
Sección titulada «Crear una obra»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, larevisiony loschapterIdsen el mismo orden en que enviaste los capítulos. Guárdalos: son la forma de referirte a cada capítulo en adelante.
Leer una obra entera
Sección titulada «Leer una obra entera»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.
Publicar una versión nueva
Sección titulada «Publicar una versión nueva»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:
baseRevisiones 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 es409 WORK_REVISION_CONFLICTcon la revisión actual encurrentRevision.- Un capítulo con
chapterIdes ese capítulo, editado. Conserva su identificador, su estado y sus correcciones. SinchapterIdes un capítulo nuevo, y la respuesta te devuelve su identificador. - El orden de
chapterses el orden final de la obra. - No hay borrados implícitos. Todo capítulo que ya existe tiene que estar en
chapterso enremovedChapterIds. Si falta en los dos, la respuesta es422 CHAPTER_OMITTEDy no se aplica nada. Así un fallo de sincronización nunca borra capítulos. - 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. - Un capítulo que envías sin cambios no se toca.
- Publicar una versión no cambia el estado de la obra ni de ningún capítulo: una obra en borrador sigue en borrador.
- 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.
Qué hacer ante un conflicto
Sección titulada «Qué hacer ante un conflicto»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.
El contenido de un capítulo
Sección titulada «El contenido de un capítulo»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.
Pedir correcciones
Sección titulada «Pedir correcciones»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_CORRECTIONy, 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-affordabilityy fíate de su campoaffordable: 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.
Leer las correcciones recibidas
Sección titulada «Leer las correcciones recibidas»Con feedback:read:
GET /connect/corrections?workId=…lista las correcciones entregadas de una obra (sinworkId, las de todas).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.GET /connect/corrections/{correctionId}/chapter-texttrae 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.
Sincronizar sin malgastar peticiones
Sección titulada «Sincronizar sin malgastar peticiones»- Guarda la
revisionde cada obra. SiGET /connect/works/{workId}/statusdevuelve la misma, no hace falta volver a descargar el texto. - No consultes en bucle. Actualiza cuando la persona abre la obra o lo pide.