poai_ Servidor a Servidor Chave de API
- Direitos da conta que a cria (admin: conta inteira)
- Nunca entregar no código do navegador
- Sem necessidade de cabeçalho Origin
- Bloqueado para MCP
- Pode ser limitada a endereços IP
Autenticação e Chaves
Um token Bearer. Cada endpoint.
Cada endpoint do produto PaperOffice-API espera o cabeçalho Authorization: Bearer. Sem fluxo OAuth, sem atualização (refresh).
Dois tipos de token, permissões claras, limites de taxa documentados.
Um cabeçalho Sem fluxo OAuth Revogável a qualquer momento
- Infraestrutura própria da UE Seus dados permanecem na Europa.
- ISO/IEC 27001 certificado Segurança certificada.
- Mais de 24 anos de experiência Comprovado. Estável. Preparado para o futuro.
curl -X POST "https://api.paperoffice.ai/latest/job/add/workflow" \ -H "Authorization: Bearer po_ut_YOUR_API_KEY" \ -F "file_1=@invoice.pdf" \ -F "idp_collection=invoice" \ -F "model=basic-pro-max"import requestsresponse = requests.post( "https://api.paperoffice.ai/latest/job/add/workflow", headers={"Authorization": "Bearer po_ut_YOUR_API_KEY"}, files={"file_1": open("invoice.pdf", "rb")}, data={"idp_collection": "invoice", "model": "basic-pro-max"},)print(response.json())const form = new FormData();form.append("file_1", new Blob([await readFile("invoice.pdf")]), "invoice.pdf");form.append("idp_collection", "invoice");form.append("model", "basic-pro-max");const response = await fetch("https://api.paperoffice.ai/latest/job/add/workflow", { method: "POST", headers: { Authorization: "Bearer po_ut_YOUR_API_KEY" }, body: form,});console.log(await response.json());Primeira chamada
Definir cabeçalho, escolher pipeline, enviar
O caminho após /latest/job/add/ é o nome da operação: geralmente na forma handler___command (por exemplo paperoffice_aiocr___generate), e para IDP estruturado, a pipeline dedicada workflow.
- Um cabeçalho
Authorization: Bearer po_ut_… — um endpoint de produto não precisa de mais nada. poai_ e po_ut_ não enviam o cabeçalho Origin.
- Pipeline no caminho
handler___command com três underscores; workflow é a exceção com seu próprio slug. A notação por pontos responde à API com HTTP 400 JOB_CONFIG_INVALID.
- Resultado ou job_id
client_wait é true por padrão: O API mantém a conexão e entrega o resultado inline. Se a janela de tempo não for suficiente, retorna HTTP 202 com job_id e poll_url para GET /latest/job/get/{job_id}.
Para idp_collection=invoice, basic-pro-max é o modelo recomendado. O modelo efetivamente utilizado é retornado no campo de resposta 'model' e pode diferir do solicitado.
Tipos de token
Dois tipos de token, claramente separados
Ambos devem ser enviados ao servidor. Eles são criados, rotacionados e revogados no aplicativo em Conta → API.
po_ut_ Relacionado ao usuário User Token
- Carrega os direitos do seu usuário
- Nunca entregar no código do navegador
- Nenhum cabeçalho Origin necessário
- Autorizado para MCP
Chamadas diretas do navegador não passam por esses dois tokens, mas sim pela chave publicável po_pk_ — vinculada à origem, com limite de orçamento e taxa. Ver Chaves Publicáveis
Permissões
O que um User Token pode fazer
Um User Token possui exatamente os direitos do seu usuário nestas áreas. Áreas individuais não podem ser atribuídas durante a criação; para delimitar, utiliza-se um token de grupo (po_gt_) com os direitos de um grupo de usuários.
- Documentos
documentsUpload, Download, Processamento
- Workspaces
workspacesGerenciar pastas e estrutura
- Trabalhos de IA
ai_jobsOCR, IDP, Extração
- Faturamento
billingLer uso e saldo da conta
- Usuários
usersGerenciar membros da equipe
- Webhooks
webhooksReceber eventos
- Base de Conhecimento
knowledge_baseBase de dados de conhecimento e FAQ
- Agentes
agentsConfigurar agentes IDP
- Fluxos de trabalho
workflowsCriar automações
- Conformidade
complianceAuditoria, GDPR, arquivamento
Limites de taxa
O que o API conta
A contagem é feita por token; sem Bearer, por endereço IP. Os valores a seguir são os mínimos documentados que se aplicam a cada tarifa.
- 5
- Requisições por segundo
- 30
- Requisições por minuto
- 100
- Requisições por hora
- 500
- Requisições por dia
- Valores restantes estão no cabeçalho da resposta
Os cabeçalhos RateLimit-* e X-RateLimit-* de cada resposta indicam quanto ainda está disponível no período atual.
- Exceder o limite: HTTP 429
A API responde com RATE_LIMIT_EXCEEDED. Repita a chamada após o tempo indicado no cabeçalho Retry-After.
- Tarifas superiores aumentam os valores
As tarifas pagas estão acima desses valores mínimos. Qual tarifa tem qual escopo está na página de preços.
Segurança
O que protege uma chave
Seis mecanismos que entram em operação — cada um com um código de status verificável ou um local no aplicativo.
- Rotação e revogação
As chaves são criadas, listadas, rotacionadas e revogadas no aplicativo em Conta → API. Um token revogado responde com HTTP 401 TOKEN_NOT_FOUND.
- Expiração e validade
Tokens expirados retornam HTTP 401 BEARERTOKEN_EXPIRED, tokens inválidos retornam HTTP 401 INVALID_TOKEN. Publishable Keys são válidos por 180 dias a partir da criação.
- Limites por token
No plano Free, aplicam-se limites de taxa por token. Em planos pagos, conta a conta; enquanto houver Credits disponíveis, não há limites de taxa aplicáveis.
- Vinculação de origem no navegador
Chaves Publicáveis exigem um Origin da Allowlist em cada requisição; caso contrário, a API responde com 403 ORIGIN_HEADER_REQUIRED ou DOMAIN_NOT_ALLOWED.
- Rastreamento de uso
Cada resposta faturada contém um bloco _billing; a avaliação por chamada fornece GET /latest/billing/usage-detail.
- Bloqueios rígidos
Login de conta, gerenciamento de chaves, OAuth, administração de parceiros, mutação de pagamento e cracking de senha estão bloqueados para chaves do navegador. O produto APIs, incluindo leitura de faturamento e webhooks, é permitido. Excluir Workspace, esvaziar a lixeira e liberar o Legal Hold só podem ser feitos no aplicativo (403 UI_ONLY_ENDPOINT).
Começar
Criar chave, definir cabeçalho, enviar
Defina a chave no aplicativo em Conta → API. A primeira chamada é descrita passo a passo na Primeira Chamada API.
Operações e confiança
O que as equipes empresariais verificam antes da primeira chamada
Contratos, segurança, suporte e limites, todos vinculados em um só lugar.
- Segurança e Conformidade ISO/IEC 27001 certificado, infraestrutura própria na UE.
- SLA de 99,9% Disponibilidade por mês civil, garantida contratualmente.
- Processamento de Dados em Nome de Terceiros (DPA) Contrato de processamento de dados nos termos do art. 28 do GDPR.
- Sem subprocessadores Um fornecedor para motor, armazenamento e processamento.
- Suporte Técnico Acesso direto à equipe de suporte, via ticket.
- Limites de taxa e cabeçalhos Valores mínimos documentados por token, cabeçalho de limite de taxa em cada resposta.
- Preços e Credits Preços transparentes de Credits por chamada.
Próxima parada
Como prosseguir
O próximo passo recomendado no funil do desenvolvedor e dois desvios adequados.
