Documentazione API myocr.app

Panoramica

L'API di myocr.app converte file documentali (PDF, JPG, PNG) in Excel strutturato, CSV, testo o JSON. Invii un file e il nome di un modello; eseguiamo OCR e analisi del layout e restituiamo un risultato pulito.

Ogni richiesta è autenticata con una API key passata nell'header X-API-Key. Le risposte usano un envelope JSON prevedibile e ogni chiamata restituisce un request_id utile per supporto e debug.

Usa l'endpoint sincrono per file piccoli che ti servono subito, e l'endpoint asincrono dei job (con webhook opzionale) per file grandi o volumi elevati.

Autenticazione

Autentica ogni richiesta con l'header X-API-Key. Crea e gestisci le chiavi dalla dashboard su /account/api. Per emettere una chiave è richiesta una carta di pagamento verificata (anti-abuso).

Esistono due tipi di chiave: le chiavi di test (prefisso sk_test_) girano sulla stessa pipeline senza consumare quota a pagamento dove applicabile, e le chiavi live (prefisso sk_live_) per la produzione. Tieni le chiavi segrete e lato server — non includerle mai nel codice client.

Gli endpoint di gestione chiavi (/v1/keys) usano la sessione web del tuo login, non la 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());

Quickstart

Converti il tuo primo documento in meno di un minuto. Ottieni una chiave dalla dashboard, poi invia una richiesta multipart con il file e il modello desiderato.

L'esempio qui sotto converte qualsiasi PDF o immagine con tabelle in un foglio .xlsx e lo salva in 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()));

Conversione sincrona

POST /v1/convert accetta un singolo file (max 5 MB, max 10 pagine) e restituisce direttamente il file risultato nel corpo della risposta — un .xlsx di default, oppure testo/JSON/CSV se imposti il parametro output.

È l'endpoint migliore quando ti serve la risposta immediata. Per file più grandi o batch, usa i job asincroni.

Parametri

Job asincroni

Per file fino a 50 MB (e PDF fino a 500 pagine) o throughput più alto, crea un job con POST /v1/jobs. La chiamata restituisce subito un request_id; il file viene elaborato in background. PDF oltre il cap pagine vengono rifiutati subito con TOO_MANY_PAGES — dividi il documento.

Interroga GET /v1/jobs/{request_id} per lo stato (pending → processing → done/failed), poi scarica il risultato da GET /v1/jobs/{request_id}/result. Fornisci un webhook_url per essere notificato automaticamente a fine job, senza 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")

Conversione batch

POST /v1/batch accetta 1–20 file in un'unica richiesta multipart, tutti elaborati con lo stesso modello. Ogni file è riportato in modo indipendente; i fallimenti per singolo file vengono restituiti in un array errors senza far fallire l'intero batch.

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"

Modelli

Passa uno di questi valori model. tables e text girano sul nostro motore OCR; i modelli specializzati restituiscono campi specifici del dominio.

Formati di output

Imposta il parametro output per scegliere il formato della risposta: xlsx (default, foglio strutturato), txt (testo semplice), json (campi estratti come JSON) o csv. Il modello text restituisce sempre txt.

Per model=bank_statement puoi impostare output anche su csv_quickbooks (CSV a 4 colonne per l'import bancario), csv_xero (template di import Xero) o ofx (file OFX standard per la maggior parte dei gestionali). Con output=json la risposta include anche un oggetto reconciliation: saldi iniziale/finale, totale accrediti e addebiti, la differenza calcolata e ok=true quando le transazioni estratte quadrano con i saldi del documento.

Risposte e header

Le risposte JSON seguono un envelope fisso: un booleano success, un oggetto data (oppure un oggetto error) e un request_id. Le risposte file restituiscono il binario direttamente con il Content-Type appropriato.

Ogni risposta include l'header X-MyOCR-Request-Id. Le risposte file includono anche X-MyOCR-Pages-Used (pagine fatturate) e X-MyOCR-Model (il modello usato).

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

Errori

Gli errori restituiscono success: false con un error.code e un error.message leggibile, più il request_id. Usa il code (stabile) per i rami logici, il message (può cambiare) per le persone.

Rate limit e quota

I rate limit sono applicati per API key (non per IP), così i client dietro un proxy condiviso non condividono il limite: /v1/convert 60 req/min, /v1/jobs 120 req/min, /v1/batch 30 req/min.

Fatturazione per pagina, non per chiamata. Piani: Free 10 pagine totali (una-tantum, carta richiesta), Starter €29/mese (2.500), Pro €99/mese (10.000), Scale €190/mese (20.000). Il servizio non si interrompe mai: a pagine del mese esaurite ti avvisiamo via email e addebitiamo un pacchetto extra al costo-pagina del tuo piano — Starter 500 a €0,0116, Pro 2.000 a €0,0099, Scale 4.000 a €0,0095 — fino a un tetto mensile di ricarica che imposti tu (e puoi disattivare). Raggiunto il tetto l'API restituisce 402 con un upgrade_url. Controlla l'uso con GET /v1/usage.

Webhook

Quando passi un webhook_url a /v1/jobs, inviamo una POST con payload JSON a quell'URL quando il job raggiunge done o failed. Le consegne vengono ritentate con backoff in caso di errore.

Ogni consegna è firmata: verifica l'header della firma con il tuo webhook signing secret (mostrato in dashboard) per confermare che la richiesta arrivi davvero da myocr.app. L'SDK Python include l'helper verify_webhook_signature.

SDK

L'SDK Python ufficiale (myocr-client) avvolge ogni endpoint con metodi ed eccezioni tipizzati, polling automatico Job.wait() con backoff e verifica della firma webhook.

Preferisci l'HTTP grezzo? Va bene qualsiasi client HTTP — vedi gli esempi cURL e Node in questa guida e la reference interattiva completa.

pip install myocr-client

Spec OpenAPI