# Optlyx Partner API — Autofatture Estere

> REST API che converte il PDF di una fattura estera nell'XML FatturaPA dell'autofattura italiana (TD17/TD18/TD19 + companion TD01). Optlyx fa OCR, AI, riconoscimento, validazione e generazione XML; il partner (Recivu) firma e invia a SDI. Optlyx non tocca SDI né la conservazione.

Base URL: `https://europe-west1-playground-optlyx.cloudfunctions.net/partnerApi/v1`
Auth: header `Authorization: Bearer pk_live_…` (prod) / `pk_test_…` (sandbox). Lo studio target va nel campo `studioId` del body.
Idempotenza: header opzionale `Idempotency-Key`. Rate limit: 60/min per key.
Soglia confidenza: `< 0.95` o `blockingIssues` ⇒ `status: "needs_review"`, nessun XML.

## Specifica

- [OpenAPI 3.1 (YAML)](./openapi.yaml): specifica macchina-leggibile completa, con esempi e code samples.
- [Riferimento completo (markdown)](./llms-full.txt): tutta la documentazione in un unico file, pensato per essere ingerito da un LLM.

## Endpoint disponibili

- [POST /v1/documents:recognize](./llms-full.txt): PDF → dati estratti + confidence + TD suggerito (nessun XML).
- [POST /v1/autofatture:process](./llms-full.txt): PDF → autofattura con XML FatturaPA pronto all'invio (l'intero motore).
- [POST /v1/autofatture](./llms-full.txt): dati strutturati → XML, senza ripassare dall'OCR.

## Altri endpoint disponibili

- GET /v1/autofatture, GET /v1/autofatture/{id}, GET /v1/autofatture/{id}/courtesy-pdf, POST /v1/webhooks (eventi autofattura.created firmati HMAC).
- Pianificato: POST /v1/autofatture/{id}:corrections (learning).

## Note per agenti/LLM

- L'XML restituito è **non firmato**; firma (CAdES .p7m) e invio a SDI sono del partner.
- I codici errore (`error.code`) sono stabili: gestirli programmaticamente, non parsare `message`.
- Codici TD: TD17 (servizi extra/UE, reverse charge, obbligatoria), TD18 (acquisto intra-UE beni), TD19 (beni ex art.17 c.2), TD01 (companion contabile).