Ingest API

L'API di ingest accetta uno o più PDF in base64 e li mette in coda per l'elaborazione asincrona.

POST /ingest

Invia uno o più PDF per l'elaborazione.

Richiesta

POST /ingest
Content-Type: application/json
X-API-Key: <api-key>

Formato multi-file (raccomandato)

{
  "files": [
    { "pdf_base64": "JVBERi0xLj...", "filename": "ordine-001.pdf" },
    { "pdf_base64": "JVBERi0xLj...", "filename": "ordine-002.pdf" }
  ],
  "email_id": "msg-001@gmail.com",
  "sender": "mittente@esempio.it",
  "subject": "Ordini aprile"
}

Formato legacy (single-file)

Mantiene compatibilità con il workflow n8n v1:

{
  "pdf_base64": "JVBERi0xLj...",
  "filename": "ordine-001.pdf",
  "email_id": "msg-001@gmail.com",
  "sender": "mittente@esempio.it",
  "subject": "Ordini aprile"
}

Campi

Campo	Tipo	Richiesto	Default	Descrizione
`files`	array	✅ (new)	—	Lista di `{pdf_base64, filename}`. Alternativa a `pdf_base64`
`pdf_base64`	string	✅ (legacy)	—	PDF codificato base64 (solo formato legacy)
`filename`	string	❌	`"attachment.pdf"`	Nome file (solo formato legacy)
`email_id`	string	❌	`""`	ID univoco dell'email di origine. Usato per il dedup
`sender`	string	❌	`""`	Indirizzo email del mittente
`subject`	string	❌	`""`	Oggetto dell'email

Limiti: max 20 MB per file (raw, pre-base64). I PDF sopra soglia o che non iniziano con %PDF vengono silenziosamente scartati dalla batch con log di warning.

Esempio curl (multi-file):

PDF1=$(base64 -w 0 ordine-001.pdf)
PDF2=$(base64 -w 0 ordine-002.pdf)

curl -X POST https://<base-url>/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <api-key>" \
  -d "{
    \"files\": [
      {\"pdf_base64\": \"$PDF1\", \"filename\": \"ordine-001.pdf\"},
      {\"pdf_base64\": \"$PDF2\", \"filename\": \"ordine-002.pdf\"}
    ],
    \"email_id\": \"msg-001@gmail.com\",
    \"sender\": \"mittente@esempio.it\"
  }"

Risposta 202

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "document_ids": [
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "a87ff679-a2f3-451d-83ae-3b7c79b38fd4"
  ],
  "document_count": 2
}

Il campo document_count riflette solo i PDF effettivamente accettati — PDF scartati per dimensione/formato o duplicati non compaiono nella lista.

Deduplicazione

Quando la deduplicazione è abilitata sul tenant, il sistema calcola un hash su email_id + contenuto PDF. Se combacia con un documento già inviato, il PDF viene silenziosamente saltato: nessun errore, non viene aggiunto a document_ids. La risposta HTTP resta 202.

Se il cliente chiama /ingest con lo stesso payload due volte, la seconda chiamata ritorna 202 con document_count: 0.

GET /ingest/ping

Verifica rapida della validità della API key.

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

Risposte:

200 {"status":"ok"} — chiave valida
401 — chiave mancante o non valida

GET /batches/{batch_id}

Stato di tutti i documenti di un batch.

curl https://<base-url>/batches/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: <api-key>"

Risposta 200

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "document_count": 2,
  "documents": [
    {
      "document_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "pipeline_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "completed",
      "document_type": "ordine_vendita",
      "semaphore": "green"
    },
    {
      "document_id": "a87ff679-a2f3-451d-83ae-3b7c79b38fd4",
      "pipeline_id": null,
      "status": "pending",
      "document_type": null,
      "semaphore": null
    }
  ]
}

Campi:

pipeline_id è null per i documenti non ancora elaborati o per cui il cruncher non ha ancora creato la pipeline
semaphore è null per i documenti non ancora elaborati
document_type è null finché il cruncher non ha classificato/estratto il documento

Polling vs webhook

L'elaborazione è asincrona. Per sapere quando è completa:

Approccio	Quando usarlo
Webhook (raccomandato)	Ricevi `order.processed` / `order.review_summary` via POST — nessun polling
Polling	Chiama `GET /batches/{batch_id}` ogni 2–5 secondi finché tutti i documenti sono in stato terminale (`completed`, `review_pending`, `failed`, `budget_hold`, `split`, `duplicate`)

Prossimi passi

Webhook