Da un PDF estero all'autofattura, via API.

Panoramica

Optlyx Partner API è un motore di conversione: un solo endpoint trasforma un documento estero (es. Anthropic, OpenAI, AWS) nell'autofattura italiana corrispondente — integrazione reverse charge (TD17) o acquisto di beni (TD18/TD19), con eventuale companion TD01 per la contabilizzazione automatica.

Confine di responsabilità

La conservazione potrà arrivare come add-on Optlyx in futuro. In questa versione è fuori scope.

Autenticazione

Ogni richiesta richiede una API key per partner nell'header Authorization. La key è "super-partner": agisce per conto di più aziende; l'azienda target va indicata nel campo studioId del body di ogni chiamata.

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Le key pk_test_… operano in sandbox, le pk_live_… in produzione. Una key non abilitata per lo studioId indicato riceve 403 TENANT_FORBIDDEN.

Ambienti

Host attuale: https://europe-west1-playground-optlyx.cloudfunctions.net/partnerApi/v1. Prima del go-live forniremo un alias di dominio (es. https://api.optlyx.com/v1); i path restano identici.

Idempotenza

Su tutte le POST puoi passare un header Idempotency-Key: ripetere la stessa richiesta con la stessa key restituisce la risposta originale senza rilavorare il documento — sicuro sui retry di rete.

Idempotency-Key: 7f3c2b1a-9e44-4c01-8b2a-1d6f0e9a2c33

Rate limit

60 richieste al minuto per API key. Oltre soglia: 429 RATE_LIMITED con details.retry_after_ms (millisecondi da attendere).

Soglia di confidenza

Se l'OCR ha confidenza < 0.95 (configurabile via options.requireConfidence) o emergono blockingIssues, la risposta ha status: "needs_review" e non viene prodotto un XML autoritativo. Mostra i campi all'operatore per conferma, poi usa POST /v1/autofatture con i dati corretti.

Recognize

Carichi un PDF, ottieni i dati estratti, la confidence e il TD suggerito. Non genera l'XML: è lo step di anteprima e validazione.

{
  "studioId": "azienda-123",
  "fileBase64": "<PDF in base64>",
  "mimeType": "application/pdf",
  "fileName": "anthropic.pdf"
}

{
  "status": "ok",      // "needs_review" se < 0.95
  "confidence": 0.97,
  "suggestedTd": "TD17",
  "extracted": { "supplierName": "Anthropic PBC" },
  "blockingIssues": []
}

Process → XML

Il "fai tutto": carichi il PDF e ottieni l'autofattura con l'XML FatturaPA pronto all'invio. Incapsula l'intero motore. Se non passi cessionario, vengono usati i dati dell'azienda.

{
  "studioId": "azienda-123",
  "fileBase64": "<PDF base64>",
  "mimeType": "application/pdf",
  "cessionario": { "denominazione": "Alfa S.r.l." },
  "options": { "generateTd01": true }
}

{
  "status": "ok",
  "autofatturaId": "AF/2026/00001",
  "td": "TD17",
  "xml": "<?xml …>",          // non firmato
  "companionTd01Xml": "<?xml …>",
  "importoTotaleCents": 12200
}

Create

Se hai già i dati strutturati (estratti da recognize e corretti dall'operatore), generi l'XML senza ripassare dall'OCR.

{
  "studioId": "azienda-123",
  "fatturaData": {
    "tipo": "TD17",
    "fornitoreEstero": { "denominazione": "Anthropic PBC", "paese": "US" },
    "linee": [{ "descrizione": "API usage", "prezzoUnitario": 100, "aliquotaIva": 22 }]
  }
}

Risposta identica a :process (con xml e companionTd01Xml).

Gestione & webhook

Le autofatture create vengono persistite e sono recuperabili; gli eventi sono notificabili via webhook.

Registra un URL HTTPS con POST /v1/webhooks: ricevi un secret e, ad ogni autofattura creata, un evento autofattura.created firmato (header X-Optlyx-Signature = HMAC-SHA256 del body).

Dati dell'azienda cliente (cessionario)

In un'autofattura l'azienda italiana è il CessionarioCommittente; il fornitore estero è il CedentePrestatore (estratto dal PDF, non lo configuri tu). Devi quindi fornire i dati fiscali dell'azienda — gli stessi che metterebbe su una sua fattura.

Due modi: passa l'oggetto cessionario direttamente nella call :process / autofatture (consigliato, nessuna config lato Optlyx), oppure registra l'azienda come tenant studioId con questi campi.

Non serve all'azienda: canale/credenziali SDI (l'invio lo fai tu), firma digitale, dati del fornitore estero (estratti dal PDF), numerazione protocollo (automatica per tenant/anno/tipo; forzabile con numeroOverride).

Esempi JSON completi (società + ditta individuale) e troubleshooting degli scarti SDI tipici: configurazione-azienda.md.

Codici TD gestiti

Errori

Tutte le risposte di errore hanno la forma { "error": { "code", "message", "details?" } }. Il campo code è stabile: gestiscilo programmaticamente, non parsare message.

Esempio completo

Da PDF a XML emettibile in una sola chiamata:

curl -X POST '…/partnerApi/v1/autofatture:process' \
  -H 'Authorization: Bearer pk_test_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3c-...' \
  -d '{
    "studioId": "azienda-123",
    "fileBase64": "'"$(base64 -i anthropic.pdf)"'",
    "mimeType": "application/pdf"
  }'

Ricevi l'XML, lo firmi e lo invii a SDI dal tuo canale. Fine.

Per LLM & agenti

La documentazione è pubblicata anche in formato leggibile dalle macchine: