API de creación de documentos

El motor de ScripFlow recibe los datos en bruto (petición, archivos ya en texto, notas de voz transcritas y enlaces), los ordena, elige la estructura del tipo de documento y redacta. Cada documento terminado es una sesión de creación y se factura a $0,19.

1. Autenticación

Genera tu llave en Perfil → Claves de API. Se muestra una sola vez y solo guardamos su huella SHA-256. Envíala en la cabecera Authorization.

Authorization: Bearer sf_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Base URL: https://docsmith-ai-studio.lovable.app

La llave del administrador es la llave maestra: puede crear documentos en la cuenta de cualquier usuario de ScripFlow indicando su correo. Una llave normal solo trabaja sobre su propia cuenta.

2. Enlazar un usuario (Telegram)

Syouserv pide el correo al usuario de Telegram y comprueba si ya tiene cuenta en ScripFlow. Si no existe, devolvemos el enlace de registro.

POST /api/public/v1/users
{ "email": "estudiante@correo.com" }

200 → { "ok": true, "exists": true, "user_id": "uuid", "profile": { ... } }
200 → { "ok": true, "exists": false, "signup_url": "https://.../auth?modo=registro" }

3. Crear un documento

POST /api/public/v1/documents
{
  "user_email": "estudiante@correo.com",       // opcional, solo llave maestra
  "instructions": "Necesito un informe de pasantías de 10 páginas sobre...",
  "doc_type": "Informe de pasantías",
  "standard": "APA7",                           // APA7 | IEEE | MLA9 | CHICAGO | VANCOUVER | ISO690
  "language": "es",
  "length": "medio",                            // corto | medio | extenso
  "audience": "tutor académico",
  "context_spec": "Universidad X, cátedra Y, márgenes 3/2.5 cm",
  "documents": [{ "name": "notas.pdf", "kind": "pdf", "text": "texto ya extraído..." }],
  "transcripts": [{ "name": "audio1", "text": "transcripción de la nota de voz" }],
  "links": [{ "url": "https://...", "title": "Fuente", "content": "texto de la página" }],
  "channel": "telegram"
}

200 → {
  "ok": true,
  "document_id": "uuid",
  "title": "Informe de pasantías ...",
  "markdown": "# Introducción\n...",
  "editor_url": "https://.../editor?doc=uuid",
  "billing": { "amount_usd": 0.19, "currency": "USD", "unit": "sesión de creación" }
}

El documento queda guardado en la cuenta del usuario: puede abrirlo en el editor, seguir pidiendo cambios y descargarlo en PDF con portada, índice y normas.

4. Formato del texto

El campo markdown usa el formato interno del motor:

# Sección        ## Subsección        ### Sub-subsección
- viñeta         1. lista numerada     > cita en bloque
| celda | celda |    (tabla; deja una línea libre debajo al maquetar)
[[IMG:1|pie de figura]]   [[FIRMAS:2|Autor;Tutor|horizontal]]   ---  (salto de página)

5. Consumo y facturación

Cada respuesta 200 de /documents registra una sesión de $0,19 a nombre del dueño de la llave. Consulta el acumulado con:

GET /api/public/v1/me
200 → { "ok": true, "master": false, "usage": { "sessions": 42, "amount_usd": 7.98 } }

6. Errores

401 { "error": "Clave de API inválida o revocada" }
403 { "error": "Esta clave solo puede crear documentos en su propia cuenta" }
404 { "error": "No existe un usuario de ScripFlow con ese correo" }
400 { "error": "Solicitud inválida: ..." }
502 { "error": "Error del motor" }