Documentação da API myocr.app

Visão geral

A API do myocr.app converte arquivos de documentos (PDF, JPG, PNG, WEBP, GIF, BMP, TIFF) em Excel estruturado, CSV, texto ou JSON. Você envia um arquivo e o nome de um modelo; executamos OCR e análise de layout e retornamos um resultado limpo.

Cada requisição é autenticada com uma API key no cabeçalho X-API-Key. As respostas usam um envelope JSON previsível e cada chamada retorna um request_id útil para suporte e depuração.

Use o endpoint síncrono para arquivos pequenos que você precisa na hora, e o endpoint assíncrono de jobs (com webhook opcional) para arquivos grandes ou alto volume.

Autenticação

Autentique cada requisição com o cabeçalho X-API-Key. Crie e gerencie chaves no painel em /account/api. Para emitir uma chave live é necessário um cartão de pagamento verificado (antiabuso). Ainda sem cartão? Crie uma chave de teste gratuita no mesmo painel: 5 páginas no total, 5 requisições/minuto, apenas POST /v1/convert — resultados completos e reais, perfeita para a primeira integração.

Existem dois tipos de chave: as de teste (prefixo sk_test_) usam o mesmo pipeline sem consumir cota paga quando aplicável, e as live (prefixo sk_live_) para produção. Mantenha as chaves em segredo e no servidor — nunca as inclua no código do cliente.

Os endpoints de gerenciamento de chaves (/v1/keys) usam a sessão web do seu login, não a API key.

curl https://api.myocr.app/v1/status \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx"

from myocr_client import MyOCRClient

client = MyOCRClient(api_key="sk_live_xxxxxxxxxxxx")
print(client.status())

const res = await fetch("https://api.myocr.app/v1/status", {
  headers: { "X-API-Key": "sk_live_xxxxxxxxxxxx" }
});
console.log(await res.json());

Início rápido

Converta seu primeiro documento em menos de um minuto. Obtenha uma chave no painel e envie uma requisição multipart com seu arquivo e o modelo desejado.

O exemplo abaixo converte qualquer PDF ou imagem com tabelas em uma planilha .xlsx e a salva em out.xlsx.

curl -X POST https://api.myocr.app/v1/convert \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@invoice.pdf" \
  -F "model=tables" \
  -o out.xlsx

from myocr_client import MyOCRClient

client = MyOCRClient(api_key="sk_live_xxxxxxxxxxxx")
result = client.convert("invoice.pdf", model="tables")
result.save("out.xlsx")

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("invoice.pdf")]), "invoice.pdf");
form.append("model", "tables");

const res = await fetch("https://api.myocr.app/v1/convert", {
  method: "POST",
  headers: { "X-API-Key": "sk_live_xxxxxxxxxxxx" },
  body: form,
});
fs.writeFileSync("out.xlsx", Buffer.from(await res.arrayBuffer()));

Conversão síncrona

POST /v1/convert aceita um único arquivo (máx. 5 MB, máx. 10 páginas) e retorna o arquivo de resultado diretamente no corpo da resposta — um .xlsx por padrão, ou texto/JSON/CSV se você definir o parâmetro output.

É o melhor endpoint quando você precisa da resposta imediata. Para arquivos maiores ou lotes, use jobs assíncronos.

Parâmetros

Jobs assíncronos

Para arquivos de até 50 MB (e PDFs até 500 páginas) ou maior throughput, crie um job com POST /v1/jobs. A chamada retorna um request_id imediatamente; o arquivo é processado em segundo plano. PDFs acima do limite de páginas são rejeitados antes com TOO_MANY_PAGES — divida o documento.

Consulte GET /v1/jobs/{request_id} para o status (pending → processing → done/failed) e baixe o resultado em GET /v1/jobs/{request_id}/result. Forneça um webhook_url para ser notificado automaticamente ao concluir, sem polling.

# 1. create the job
curl -X POST https://api.myocr.app/v1/jobs \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@statement.pdf" -F "model=bank_statement"
# → {"success": true, "data": {"request_id": "abcd1234"}}

# 2. poll status, then download the result
curl https://api.myocr.app/v1/jobs/abcd1234 -H "X-API-Key: sk_live_xxxxxxxxxxxx"
curl https://api.myocr.app/v1/jobs/abcd1234/result -H "X-API-Key: sk_live_xxxxxxxxxxxx" -o out.xlsx

job = client.create_job("statement.pdf", model="bank_statement")
job.wait()                     # polls with backoff until done
job.result().save("out.xlsx")

Conversão em lote

POST /v1/batch aceita de 1 a 20 arquivos em uma única requisição multipart, todos processados com o mesmo modelo. Cada arquivo é reportado de forma independente; falhas por arquivo são retornadas em um array errors sem falhar o lote inteiro.

curl -X POST https://api.myocr.app/v1/batch \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "files=@a.pdf" -F "files=@b.pdf" -F "files=@c.jpg" \
  -F "model=invoice"

Modelos

Passe um destes valores model. tables e text usam nosso motor OCR; os modelos especializados retornam campos específicos do domínio.

PDF mistos: muitas vezes uma fatura é seguida de anexos de detalhe — registos de chamadas, resumos por linha, discriminações — que repetem os mesmos cabeçalhos de coluna. Dê a cada modelo apenas as páginas de que precisa, com page_range.

invoice na página da fatura (normalmente a primeira) devolve número, datas, totais e IVA; tables nas páginas do anexo devolve o detalhe linha a linha. Duas chamadas, dois ficheiros limpos, e as páginas excluídas não são faturadas.

# invoice header from page 1, call detail from pages 3 onwards
curl -X POST https://api.myocr.app/v1/convert -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@bill.pdf" -F "model=invoice" -F "page_range=1" -o header.xlsx
curl -X POST https://api.myocr.app/v1/convert -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@bill.pdf" -F "model=tables" -F "page_range=3-" -o detail.xlsx

Formatos de saída

Defina o parâmetro output para escolher o formato: xlsx (padrão, planilha estruturada), txt (texto puro), json (campos extraídos como JSON) ou csv. O modelo text sempre retorna txt.

Para model=bank_statement você também pode definir output como csv_quickbooks (CSV de 4 colunas para importação bancária), csv_xero (modelo de importação do Xero) ou ofx (arquivo OFX padrão para a maioria dos softwares contábeis). Com output=json a resposta inclui também um objeto reconciliation: saldos inicial/final, total de créditos e débitos, a diferença calculada e ok=true quando as transações extraídas batem com os saldos do extrato.

Respostas e cabeçalhos

As respostas JSON seguem um envelope fixo: um booleano success, um objeto data (ou um objeto error) e um request_id. As respostas de arquivo retornam o binário diretamente com o Content-Type apropriado.

Cada resposta inclui o cabeçalho X-MyOCR-Request-Id. As respostas de arquivo também incluem X-MyOCR-Pages-Used (páginas faturadas) e X-MyOCR-Model (o modelo usado).

Uma resposta pode conter também um array warnings: um campo opcional e adicional, que nunca altera o resultado. Hoje o único caso é PAGE_RANGE_SUGGESTED, devolvido quando a um modelo que descreve um único documento (invoice, receipt, business_card) se dá um PDF com mais de três páginas sem page_range, o que normalmente significa que os anexos de detalhe estão a ser misturados com o documento. As respostas de ficheiro levam o código no cabeçalho X-MyOCR-Warning, por não terem corpo JSON.

{
  "success": true,
  "data": { "request_id": "abcd1234" },
  "request_id": "abcd1234"
}

Erros

Os erros retornam success: false com um error.code e um error.message legível, mais o request_id. Use o code (estável) para a lógica e o message (pode mudar) para as pessoas.

Limites e cota

Os limites de taxa são aplicados por API key (não por IP), então clientes atrás de um proxy compartilhado não dividem o limite: /v1/convert 60 req/min, /v1/jobs 120 req/min, /v1/batch 30 req/min.

Cobrança por página, não por chamada. Planos: Free 10 páginas no total (única vez, cartão necessário), Starter €29/mês (2.500), Pro €99/mês (10.000), Scale €190/mês (20.000). O serviço nunca é interrompido: ao esgotar as páginas do mês avisamos por email e cobramos um pacote extra ao preço por página do seu plano — Starter 500 a €0,0116, Pro 2.000 a €0,0099, Scale 4.000 a €0,0095 — até um teto mensal de recarga que você define (e pode desativar). Atingido o teto a API retorna 402 com um upgrade_url. Verifique o uso com GET /v1/usage.

Webhooks

Quando você passa um webhook_url para /v1/jobs, enviamos um POST com payload JSON para essa URL quando o job chega a done ou failed. As entregas são repetidas com backoff em caso de falha.

Cada entrega é assinada: verifique o cabeçalho de assinatura com seu webhook signing secret (mostrado no painel) para confirmar que a requisição veio mesmo do myocr.app. O SDK Python inclui o helper verify_webhook_signature.

SDK

O SDK oficial em Python (myocr-client) envolve cada endpoint com métodos e exceções tipados, polling automático Job.wait() com backoff e verificação de assinatura de webhook.

Prefere HTTP puro? Qualquer cliente HTTP funciona — veja os exemplos cURL e Node neste guia e a referência interativa completa.

pip install myocr-client

Spec OpenAPI