La API de PaperOffice para desarrolladores: la guía completa

Dónde reside la especificación

La especificación del punto de conexión se genera en tiempo real a partir del catálogo de APIs. Utilice estos archivos en lugar de copiar listas de puntos de conexión de artículos:

• Índice compacto para clientes de IA: https://api.paperoffice.ai/latest/docs/llms.txt
• Referencia completa: https://api.paperoffice.ai/latest/docs/llms-full.txt
• OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
• Habilidad de agente: https://api.paperoffice.ai/latest/docs/skill.md
• Colección de Postman: https://api.paperoffice.ai/latest/docs/postman

Las rutas de documentación son públicas y no requieren token. Importe la URL de Postman en Postman, VS Code o Bruno, y descárguela nuevamente cuando cambie la versión de la documentación. La dirección base de producción es https://api.paperoffice.ai/latest; utilice /dev únicamente para desarrollo.

Un inicio rápido con un asistente de codificación por IA: proporcione la dirección de llms-full.txt y describa la función que necesita, por ejemplo, una función que envíe una imagen y devuelva el texto reconocido.

Autenticación y tipos de token

La mayoría de los puntos de conexión del producto requieren un token portador en el encabezado Authorization. Usted crea tokens en la aplicación PaperOffice bajo Cuenta → API.

• Clave del sistema (po_sk_): integración de servidor a servidor con acceso completo a la API. Nunca la utilice en un navegador.
• Token de usuario (po_ut_): el alcance es de un solo usuario, por ejemplo, para MCP. Los derechos siguen al usuario y a la licencia.
• Token de grupo (po_gt_): hereda los derechos y la lista blanca de espacios de trabajo de un grupo de usuarios.
• Clave publicable (po_pk_): para su uso en un navegador. Cada solicitud necesita un origen que el propietario de la clave haya ingresado, un presupuesto de por vida limita el consumo, y se bloquean la eliminación, la administración de la cuenta, la gestión de claves y los cambios de pago. No está permitido para MCP.

Sin un token, solo son accesibles los puntos de conexión de infraestructura como la especificación, la comprobación de estado y la prueba de conectividad. Una solicitud de producto sin token recibe la respuesta HTTP 403 y el código TIER_RESTRICTED, no con HTTP 401.

Trabajos: espera, sondeo y resultados

El procesamiento se ejecuta como trabajos. Las rutas de los trabajos siguen el patrón handler___command con tres guiones bajos, por ejemplo POST /job/add/paperoffice_aiocr___generate para el reconocimiento de texto. La notación de puntos se rechaza con JOB_CONFIG_INVALID.

• Por defecto, la solicitud mantiene la conexión durante un tiempo. Si el trabajo finaliza a tiempo, obtiene el resultado directamente. De lo contrario, obtiene HTTP 202 con un ID de trabajo y una dirección de sondeo, y el trabajo continúa ejecutándose.
• HTTP 202 es un éxito, no un error. Consulte GET /job/get/{job_id} cada 5 a 10 segundos hasta que el estado sea completado. El resultado se encuentra entonces en job_result.
• Con client_wait=false, obtiene el ID del trabajo inmediatamente y realiza el sondeo desde el inicio.
• Todas las respuestas son JSON. Los clientes deben leer el campo de código estable, no el texto del mensaje localizado.

Usted ve los trabajos de API en cola, en ejecución y completados en la aplicación bajo Cuenta → API → Cola de jobs. La lista completa de códigos de error se encuentra en la especificación; los casos típicos son parámetros faltantes o inválidos (400), un token faltante o inválido (401), fondos insuficientes de Credits (402), una acción prohibida (403) y demasiadas solicitudes (429, respetar Retry-After).

SLA de inicio: cuándo comienza un trabajo

El campo opcional processing_lane controla cuándo comienza un trabajo en la cola, no cuándo finaliza. client_wait controla si la conexión espera el resultado; los dos campos son independientes.

Sin processing_lane, se aplica el valor predeterminado del espacio de trabajo; de lo contrario, es mejor esfuerzo. Todos los planes incluyen mejor esfuerzo sin recargo. Los carriles de inicio más rápidos son opcionales y cuestan más. Los carriles actuales y sus precios están disponibles en tiempo real a través de la lista de precios de la API; los detalles se encuentran en la documentación de la API.

Webhooks

Los puntos de conexión de webhook reciben eventos de trabajos y cuentas, por ejemplo job.completed, job.failed, job.progress y eventos para documentos, espacios de trabajo y tareas. Los avisos de cuenta como una billetera vacía o una clave revocada no son eventos de webhook.

• Las cargas útiles se firman con HMAC-SHA256 en el encabezado X-Paperoffice-Signature. Calcule la firma sobre el cuerpo de la solicitud sin procesar con su secreto de webhook y rechace la solicitud si no coincide.
• Los webhooks se registran, listan, actualizan, prueban y eliminan a través de la API.

Facturación y uso

Las llamadas a la API consumen Credits del grupo compartido de la organización, el mismo grupo que la aplicación. Algunas consultas de estado y salud no se cobran; los detalles están en la documentación de la API. Las llamadas rechazadas debido a una entrada inválida también se cobran; las llamadas limitadas por velocidad no se cobran.

Puede ver las llamadas con sus Credits en API & Desarrolladores → Uso de la API: el registro en vivo muestra cada solicitud, el historial muestra el uso por fecha, controlador y acción. Cuando se agoten los Credits, las llamadas se rechazarán hasta que se recargue el saldo o surta efecto la recarga automática. Los límites de velocidad dependen de su plan; los límites actuales y los encabezados de respuesta se describen en la documentación de la API. Más sobre Credits: Facturación y Credits en PaperOffice AI.

MCP: conectar asistentes de IA

MCP conecta asistentes de IA como Claude, ChatGPT, Grok y Cursor directamente a PaperOffice. La autenticación es OAuth 2.1 o un token de usuario o grupo; las claves de sistema y las claves publicables están bloqueadas para MCP. El host de producción es https://mcp.paperoffice.ai, con perfiles como /claude, /chatgpt, /grok, /cursor y /dms. Configuración, permisos y flujo de datos: Uso de PaperOffice con Claude, ChatGPT, Grok y Cursor.

Preguntas frecuentes

• ¿Dónde encuentro todos los puntos finales? En llms.txt, llms-full.txt y el archivo OpenAPI. Se generan en tiempo real.
• ¿Qué token debe usar mi servidor? Una clave de sistema, nunca en un navegador. Para un navegador, utilice una clave publicable con un origen y un presupuesto.
• ¿Es HTTP 202 un error? No. El trabajo aún se está ejecutando; consulte el resultado mediante sondeo.
• ¿Los carriles de inicio más rápidos cuestan más? Sí. El mejor esfuerzo no tiene recargo; los precios actuales están en la lista de precios de la API.
• ¿Se cobran las llamadas rechazadas? Las llamadas rechazadas debido a una entrada inválida se cobran; las llamadas limitadas por velocidad no se cobran.