ClaixClaixEN

Ventana de Contexto

Ventana de Contexto

Pregunta a un documento persistido tras una extracción con window_context activo.

Ventana de Contexto · Sustituir documento

Sustituir el contenido de un documento

Endpoint

POSThttps://claix.dev/replace-document

Reemplaza el contenido de document_id con el de new_content_document_id mediante un RPC. El documento fuente se elimina. Se incrementa la version del documento destino.

Conserva el mismo document_id (y su espacio, si lo tiene) mientras actualizas el contenido con una nueva extracción.

URL pública: POST https://claix.dev/replace-document. Nunca expongas la URL directa de Supabase.

Esta llamada es gratuita: no se factura ni consume el cupo de extracciones ni de ventana de contexto.

1. Autenticación

Toda petición debe incluir tu API key. Es una credencial de servidor personal, distinta de cualquier token de sesión de usuario.

Opción A — Header dedicado (recomendado):

x-api-key: <TU_API_KEY>

Opción B — Header estándar Authorization:

Authorization: Bearer <TU_API_KEY>

Con uno de los dos es suficiente. Si envías ambos, x-api-key tiene prioridad.

El sistema valida que la key exista y esté activa. Si falla, responde 401. Ambos documentos deben pertenecer a tu cuenta.

2. Formato de la petición

Método: POST · Content-Type: application/json

CampoTipoObligatorioDescripción
document_idstring (uuid)SíDocumento destino cuyo contenido se sustituye. Conserva su id.
new_content_document_idstring (uuid)SíDocumento fuente cuyo contenido se copia. Se elimina tras el swap.

Cuerpo de ejemplo:

{
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "new_content_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c"
}

3. Cómo construir la llamada

  1. Extrae el documento nuevo y guarda su document_id como fuente.
  2. Envía POST con el document_id estable (destino) y new_content_document_id (fuente).
  3. Usa el mismo document_id en consultas posteriores; la version habrá subido.

4. Ejemplos de llamada

Usa el panel de código de la derecha para copiar ejemplos en cURL, JavaScript, Python, etc.

5. Formato de la respuesta exitosa

HTTP 200 — Contenido sustituido; el documento fuente ha sido eliminado.

{
  "success": true,
  "swap_id": "c1e7a4b2-9f0d-4e8a-b3c5-1d2e3f4a5b6c",
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "source_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c",
  "file_name": "factura.pdf",
  "version": 2,
  "swaps_count": 1,
  "message": "Contenido sustituido. El documento fuente ha sido eliminado."
}
CampoTipoDescripción
successbooleanSiempre true en una respuesta 200.
swap_idstring (uuid)Identificador de la operación de swap.
document_idstring (uuid)Documento destino (id estable).
source_document_idstring (uuid)Documento fuente que se eliminó.
file_namestringNombre de archivo del documento destino.
versionnumberVersión incrementada tras el swap.
swaps_countnumberNúmero acumulado de sustituciones.
messagestringMensaje legible de confirmación.

6. Códigos de error

{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos).",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

400 — Body inválido, UUIDs mal formados o la operación no es válida (por ejemplo, ids iguales).

401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta no activa.

404 — Alguno de los dos documentos no existe o no pertenece a tu cuenta.

405 — Método distinto de POST. · 500 — Error interno.

7. Resumen de códigos

CódigoCategoría¿Reintentar?
200Éxito — contenido sustituido—
400Error del cliente (body o IDs inválidos)No, corrige la petición primero
401Error de autenticaciónNo, corrige las credenciales primero
404Documento destino o fuente no encontradoNo, corrige los IDs primero
405Método HTTP incorrectoNo, usa POST
500Error interno del servidorSí, con precaución

8. Buenas prácticas

  • Mantén estable el document_id de negocio; usa extracciones temporales solo como fuente del swap.
  • Tras el swap, el new_content_document_id deja de existir: no lo reutilices.
  • Usa siempre el dominio público claix.dev, no la URL directa de Supabase.
  • No incluyas tu API key en frontend ni repositorios públicos.

Ejemplos de petición

curl -X POST "https://claix.dev/replace-document" \
  -H "x-api-key: <TU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"document_id":"d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b","new_content_document_id":"a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c"}'