A API PaperOffice para desenvolvedores: o guia completo

Onde a especificação está localizada

A especificação do endpoint é gerada em tempo real a partir do catálogo da API. Utilize estes arquivos em vez de copiar listas de endpoints de artigos:

• Índice compacto para clientes de IA: https://api.paperoffice.ai/latest/docs/llms.txt
• Referência completa: https://api.paperoffice.ai/latest/docs/llms-full.txt
• OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
• Habilidade de agente: https://api.paperoffice.ai/latest/docs/skill.md
• Coleção Postman: https://api.paperoffice.ai/latest/docs/postman

As rotas de documentação são públicas e não exigem token. Importe a URL do Postman no Postman, VS Code ou Bruno, e baixe-a novamente quando a versão da documentação for alterada. O endereço base de produção é https://api.paperoffice.ai/latest; utilize /dev apenas para desenvolvimento.

Um início rápido com um assistente de codificação por IA: forneça a ele o endereço de llms-full.txt e descreva a função necessária, por exemplo, uma função que envia uma imagem e retorna o texto reconhecido.

Autenticação e tipos de token

A maioria dos endpoints do produto requer um token bearer no cabeçalho Authorization. Você cria tokens no aplicativo PaperOffice em Conta → API.

• Chave do sistema (po_sk_): integração de servidor para servidor com acesso total à API. Nunca a utilize em um navegador.
• Token de usuário (po_ut_): o escopo de um único usuário, por exemplo, para MCP. Os direitos seguem o usuário e a licença.
• Token de grupo (po_gt_): herda os direitos e a lista branca de espaços de trabalho de um grupo de usuários.
• Chave publicável (po_pk_): para uso em um navegador. Cada solicitação precisa de uma origem que o proprietário da chave inseriu, um orçamento de vida útil limita o consumo, e exclusões, administração da conta, gerenciamento de chaves e alterações de pagamento permanecem bloqueados. Não é permitido para MCP.

Sem um token, apenas endpoints de infraestrutura como a especificação, o teste de saúde e o teste de conectividade são acessíveis. Uma solicitação de produto sem token é respondida com HTTP 403 e o código TIER_RESTRICTED, não com HTTP 401.

Trabalhos: espera, polling e resultados

O processamento ocorre como trabalhos. Os caminhos dos trabalhos usam o padrão handler___command com três underscores, por exemplo POST /job/add/paperoffice_aiocr___generate para reconhecimento de texto. A notação de ponto é rejeitada com JOB_CONFIG_INVALID.

• Por padrão, a solicitação mantém a conexão por um tempo. Se o trabalho for concluído dentro do prazo, você recebe o resultado diretamente. Caso contrário, você recebe HTTP 202 com um ID de trabalho e um endereço de polling, e o trabalho continua em execução.
• HTTP 202 é um sucesso, não um erro. Faça polling GET /job/get/{job_id} a cada 5 a 10 segundos até que o status seja concluído. O resultado estará então em job_result.
• Com client_wait=false, você recebe o ID do trabalho imediatamente e faz polling desde o início.
• Todas as respostas são JSON. Os clientes devem ler o campo de código estável, não o texto da mensagem localizado.

Você vê trabalhos de API em fila, em execução e concluídos no aplicativo em Conta → API → Fila de jobs. A lista completa dos códigos de erro está na especificação; casos típicos são parâmetros ausentes ou inválidos (400), token ausente ou inválido (401), Credits insuficiente (402), ação proibida (403) e muitas solicitações (429, respeitar Retry-After).

SLA de início: quando um trabalho começa

O campo opcional processing_lane controla quando um trabalho começa na fila, não quando termina. client_wait controla se a conexão espera pelo resultado; os dois campos são independentes.

Sem processing_lane, o padrão do espaço de trabalho se aplica, caso contrário, melhor esforço. Todo plano inclui melhor esforço sem taxa adicional. Faixas de início mais rápidas são opcionais e custam mais. As faixas atuais e seus preços estão disponíveis em tempo real através da lista de preços da API; os detalhes estão na documentação da API.

Webhooks

Os endpoints de webhook recebem eventos de trabalho e conta, por exemplo job.completed, job.failed, job.progress e eventos para documentos, espaços de trabalho e tarefas. Notificações de conta como uma carteira vazia ou uma chave revogada não são eventos de webhook.

• Os payloads são assinados com HMAC-SHA256 no cabeçalho X-Paperoffice-Signature. Calcule a assinatura sobre o corpo bruto da solicitação com o segredo do webhook e rejeite a solicitação se não corresponder.
• Os webhooks são registrados, listados, atualizados, testados e excluídos por meio da API.

Faturamento e uso

As chamadas de API consomem Credits do pool compartilhado da organização, o mesmo pool do aplicativo. Algumas consultas de status e saúde não são cobradas; os detalhes estão na documentação da API. Chamadas rejeitadas devido a entrada inválida também são cobradas; chamadas limitadas por taxa não são.

Você vê as chamadas com seus Credits em API e Desenvolvedor → Uso da API: o registro ao vivo mostra cada solicitação, o histórico mostra o uso por data, manipulador e ação. Quando Credits se esgotam, as chamadas são rejeitadas até que o saldo seja recarregado ou a recarga automática seja acionada. Os limites de taxa dependem do seu plano; os limites atuais e os cabeçalhos de resposta são descritos na documentação da API. Mais sobre Credits: Faturamento e Credits em PaperOffice AI.

MCP: conectar assistentes de IA

O MCP conecta assistentes de IA como Claude, ChatGPT, Grok e Cursor diretamente ao PaperOffice. A autenticação é OAuth 2.1 ou um token de usuário ou grupo; chaves de sistema e chaves publicáveis são bloqueadas para MCP. O host de produção é https://mcp.paperoffice.ai, com perfis como /claude, /chatgpt, /grok, /cursor e /dms. Configuração, permissões e fluxo de dados: Usando PaperOffice com Claude, ChatGPT, Grok e Cursor.

Perguntas frequentes

• Onde encontro todos os endpoints? Em llms.txt, llms-full.txt e no arquivo OpenAPI. Eles são gerados em tempo real.
• Qual token o servidor deve usar? Uma chave de sistema, nunca em um navegador. Para um navegador, use uma chave publicável com uma origem e um orçamento.
• HTTP 202 é um erro? Não. O trabalho ainda está em execução; consulte o resultado.
• As faixas de início mais rápidas custam mais? Sim. O melhor esforço não tem sobretaxa; os preços atuais estão na lista de preços da API.
• As chamadas rejeitadas são cobradas? Chamadas rejeitadas devido a entrada inválida são cobradas; chamadas limitadas por taxa não são.