po_sk_ Servidor a Servidor Chave Secreta
- Acesso total no âmbito da conta
- Nunca entregar no código do navegador
- Sem necessidade de cabeçalho Origin
- Bloqueado para MCP
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, dez escopos de permissão, 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 27001 ativo Segurança certificada.
- SOC 2 Tipo II ativo Padrões internacionais de auditoria.
- 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 "[email protected]" \ -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 para /latest/job/add/ é o nome do job da fila: geralmente no formato handler___command (por exemplo, paperoffice_aiocr___generate); para IDP estruturado, use sua própria workflow.
- Um cabeçalho
Authorization: Bearer po_ut_… — um endpoint de produto não precisa de mais nada. po_sk_ 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: OCR-first limita coleções impressas com posições de qualquer maneira a basic-pro-max; um model=premium enviado será retornado como model: basic-pro-max.
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
- Limitável a áreas individuais
- 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
Dez áreas por token de usuário
Um token de usuário contém exatamente as áreas que você atribui durante a criação. Se a área estiver ausente, a resposta será API com HTTP 403.
- Documentos
documentosUpload, Download, Processamento
- Workspaces
espacos_de_trabalhoGerenciar pastas e estrutura
- Trabalhos de IA
ai_jobsOCR, IDP, Extração
- Faturamento
faturamentoLer uso e saldo da conta
- Usuários
utilizadoresGerenciar membros da equipe
- Webhooks
webhooksReceber eventos
- Base de Conhecimento
base_de_conhecimentoBase de dados de conhecimento e FAQ
- Agentes
agentesConfigurar agentes IDP
- Fluxos de trabalho
fluxos de trabalhoCriar automações
- Conformidade
conformidadeAuditoria, LGPD, 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 ou inválidos retornam HTTP 401 INVALID_TOKEN. Chaves Publicáveis expiram no máximo após 365 dias.
- Limites por token
Os limites de taxa contam por token, não por conta. Uma chave comprometida não sobrecarrega toda a operação.
- 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).
Vídeo
Autenticação em ação
Veja como uma chamada com token Bearer funciona na prática — no vídeo.
Aprofunde-se
O que está ao lado
As páginas que cobrem o entorno da autenticação.
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 27001, SOC 2 Tipo II, 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 em conformidade com o RGPD.
- Lista de Subprocessadores Todos os subcontratados listados de forma transparente.
- 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.