Riferimento API

Riepilogo di tutti gli endpoint pubblici della piattaforma.

Endpoint disponibili

Metodo	Path	Descrizione	Autenticazione
`POST`	`/ingest`	Invia uno o più PDF per l'elaborazione asincrona	`X-API-Key`
`GET`	`/ingest/ping`	Probe di validità della API key	`X-API-Key`
`GET`	`/batches/{batch_id}`	Stato aggregato di tutti i documenti di un batch	`X-API-Key`
`GET`	`/orders/{pipeline_id}/csv`	Download CSV schema-driven del documento	`X-API-Key`
`GET`	`/orders/{pipeline_id}/json`	Download JSON schema-driven del documento	`X-API-Key`
`GET`	`/health`	Health check del servizio	Nessuna

POST /ingest

Accetta uno o più PDF in base64 e li inserisce nella coda di elaborazione.

Vedi la documentazione completa: Ingest API — POST /ingest

GET /ingest/ping

Verifica rapida della validità della API key. Non tocca DB.

curl https://<base-url>/ingest/ping -H "X-API-Key: <api-key>"

200 {"status":"ok"} se valida · 401 altrimenti.

GET /batches/{batch_id}

Restituisce lo stato di tutti i documenti appartenenti a un batch.

Vedi la documentazione completa: Ingest API — GET /batches

GET /orders/{pipeline_id}/csv

Download del documento completato in formato CSV.

curl https://<base-url>/orders/<pipeline_id>/csv \
  -H "X-API-Key: <api-key>" \
  -O -J

Caratteristiche:

Encoding UTF-8 con BOM (compatibile Excel su Windows)
Header CSV incluso (prima riga = nomi colonna canonici dallo schema)
Filename nel Content-Disposition derivato dal nome originale del PDF, con suffisso parte_N_di_M per i documenti split

La shape del CSV dipende dall'exporter configurato sullo schema (default default_csv: header denormalizzato su ogni riga line-item). Schemi con exporter dedicati (es. legami_warning_csv) producono layout diversi — vedi Schemi documento → Tab Output.

Risposte:

Codice	Significato
`200`	File CSV nel body
`404`	Pipeline inesistente, eliminata, o non appartenente al tenant
`404`	Pipeline in attesa di revisione manuale (scaricabile solo dopo approvazione)
`422`	Schema o dati incoerenti — errore di serializzazione

GET /orders/{pipeline_id}/json

Stessa semantica di .../csv ma output JSON strutturato:

{
  "pipeline_id": "p-uuid-...",
  "pdf_filename": "ordine-001.pdf",
  "customer_name": "GOTTARDO SPA",
  "header": {
    "customer_name": "GOTTARDO SPA",
    "order_number_original": "OC-2026-0421",
    "order_date": "2026-04-08",
    "delivery_date": "2026-04-22"
  },
  "lines": [
    { "product_code": "AB123", "quantity": 10, "unit_price": 4.5, "...": "..." },
    { "product_code": "CD456", "quantity": 3,  "unit_price": 12.0, "...": "..." }
  ]
}

Le chiavi corrispondono ai field.name canonici definiti nello schema — stabili e indipendenti dall'etichetta usata nel PDF originale.

GET /health

Verifica che il servizio sia operativo. Non richiede autenticazione.

curl https://<base-url>/health

Risposta 200:

{"status": "ok", "version": "0.1.0"}

Questo endpoint è usato da Docker per l'health check del container. Non espone informazioni sensibili e può essere chiamato senza credenziali per verificare la disponibilità del servizio.