Schemas — DocumentEnvelope v2

ParseResponse (HTTP envelope)

Field	Type	Description
job_id	string (UUID)	Job identifier
status	"done" | "failed" | "queued"	Parse status
document_type	string	Detected document type (e.g. "invoice", "generic_text")
confidence	float | null	Confidence score 0.0–1.0
provider_used	string	LLM provider name or "fast-path"
prompt_version	string	Prompt template version
cost_usd	float	LLM cost in USD
tokens	integer	Token consumption
content_hash	string	SHA-256 canonical hash
result	DocumentEnvelope | null	Structured result v2 (null on error)
error	string | null	Error message on failure

DocumentEnvelope v2

The structured result inside ParseResponse.result. This is the canonical document model.

{
  "schema_version": "2.0",
  "document_type": "invoice",
  "meta": { ... },
  "payload": { ... }
}

EnvelopeMeta

Field	Type	Default	Description
confidence	float	1.0	Extraction confidence 0.0–1.0
provider	string	""	Provider used
prompt_version	string	""	Prompt version

Payload (discriminated by kind)

The payload field uses Pydantic discriminated union on kind:

• kind: "invoice" → InvoicePayload
• kind: "generic" → GenericPayload

InvoicePayload (kind: “invoice”)

Field	Type	Description
dati_trasmissione	object	Transmission data (sender ID, format)
cedente_prestatore	object	Supplier/seller details
cessionario_committente	object	Customer/buyer details
corpi	array	Document line items
totali	object | null	Tax totals
allegati	object | null	Attachments metadata

GenericPayload (kind: “generic”)

Field	Type	Description
raw_text	string | null	Extracted raw text
parsed_fields	dict | null	Key-value extracted fields
confidence_map	dict | null	Per-field confidence scores

Schema Notes

• The payload field is a discriminated union with kind as discriminator.
• All monetary values are in EUR (€).
• cedente_prestatore and cessionario_committente follow Italian FatturaPA field naming for XML provenance.
• confidence: 1.0 indicates deterministic extraction (FatturaPA XML fast-path, no LLM involved).