{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/asap-cool/json-schema/asap-cool-document-view-schema.json",
  "title": "DocumentView",
  "description": "Public projection of a [`Document`]. `content_hash`/`prev_hash` are\nsurfaced as lowercase hex so clients can verify the NF203 seal.",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/asap-cool-openapi.json#/components/schemas/DocumentView",
  "type": "object",
  "required": [
    "id",
    "contact_id",
    "type",
    "status",
    "issue_date",
    "total_ht",
    "total_tva",
    "total_ttc",
    "payment_plan_kind",
    "render_status",
    "transmission_status",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "acompte_percentage": {
      "type": [
        "string",
        "null"
      ],
      "description": "Deposit share as a percentage of the parent quote."
    },
    "avoir_for_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Invoice this credit note offsets (1 max per invoice)."
    },
    "client_snapshot": {
      "description": "Frozen billable client snapshot (set at finalization)."
    },
    "contact_id": {
      "type": "string",
      "format": "uuid",
      "description": "Logical reference to a contact."
    },
    "contact_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Displayable contact name (R5): the frozen client snapshot for a\nfinalized document, or a live join on the contact for a draft. `None`\nwhen the contact no longer exists."
    },
    "content_hash": {
      "type": [
        "string",
        "null"
      ],
      "description": "NF203 content hash (hex), set only at finalization."
    },
    "converted_from_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Source quote when this invoice was converted from one."
    },
    "created_at": {
      "type": "string",
      "description": "RFC3339 creation timestamp."
    },
    "credit_reason_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "Structured reason code for a credit note (`avoir`); `None` when absent."
    },
    "credit_reason_text": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-text detail accompanying the credit-note reason."
    },
    "delivery_address": {
      "description": "Delivery address (JSONB)."
    },
    "deposit_request_percentage": {
      "type": [
        "string",
        "null"
      ],
      "description": "Deposit requested at order time, percentage (decimal token).\nQuote-oriented mention."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Long description."
    },
    "discount_terms": {
      "type": [
        "string",
        "null"
      ],
      "description": "Early-settlement discount mention (art. L441-9)."
    },
    "due_date": {
      "type": [
        "string",
        "null"
      ],
      "description": "Due date (`YYYY-MM-DD`)."
    },
    "execution_timeline": {
      "type": [
        "string",
        "null"
      ],
      "description": "Delivery / execution timeline (free-form). Quote-oriented mention."
    },
    "finalized_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Finalization timestamp; non-null means the document is immutable."
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Stable identifier."
    },
    "issue_date": {
      "type": "string",
      "description": "Issue date (`YYYY-MM-DD`)."
    },
    "items": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/DocumentItemView"
      },
      "description": "Line items (present on `get`/`create`/`finalize`, omitted on `list`)."
    },
    "lifecycle_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "RFC3339 timestamp of the last lifecycle update."
    },
    "lifecycle_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable reason for a negative lifecycle status."
    },
    "lifecycle_status": {
      "type": [
        "string",
        "null"
      ],
      "description": "Last observed regulatory lifecycle token."
    },
    "notes": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-form notes."
    },
    "number": {
      "type": [
        "string",
        "null"
      ],
      "description": "Sequential number, set only at finalization."
    },
    "operation_nature": {
      "type": [
        "string",
        "null"
      ],
      "description": "Operation nature."
    },
    "parent_devis_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Parent quote for a deposit invoice."
    },
    "payment_method": {
      "type": [
        "string",
        "null"
      ],
      "description": "Payment method."
    },
    "payment_plan_config": {
      "description": "Payment-plan JSON payload (`{\"percentage\":\"30\"}`/`{\"count\":3}`), `null`\nfor the `none` plan."
    },
    "payment_plan_kind": {
      "type": "string",
      "description": "Quote payment-plan discriminant (`none`/`deposit_then_balance`/\n`installments`) driving post-signature auto-billing."
    },
    "payment_terms": {
      "type": [
        "string",
        "null"
      ],
      "description": "Payment terms."
    },
    "prev_hash": {
      "type": [
        "string",
        "null"
      ],
      "description": "NF203 previous-link hash (hex)."
    },
    "render_status": {
      "type": "string",
      "description": "Factur-X render lifecycle (`pending`/`rendering`/`ready`/`failed`).\nThe PDF is downloadable via `GET /v1/invoices/{id}/pdf` only when\nthis is `ready` (R8)."
    },
    "sent_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "RFC3339 timestamp of the effective transition to `sent`, read-only;\n`None` before any send."
    },
    "service_date": {
      "type": [
        "string",
        "null"
      ],
      "description": "Service/delivery date (`YYYY-MM-DD`)."
    },
    "status": {
      "type": "string",
      "description": "Lifecycle status."
    },
    "title": {
      "type": [
        "string",
        "null"
      ],
      "description": "Title."
    },
    "total_ht": {
      "type": "integer",
      "format": "int64",
      "description": "Total excluding VAT, in cents."
    },
    "total_ttc": {
      "type": "integer",
      "format": "int64",
      "description": "Total including VAT, in cents."
    },
    "total_tva": {
      "type": "integer",
      "format": "int64",
      "description": "Total VAT, in cents."
    },
    "transmission_error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why the last transmission failed (the platform's reason), when it did."
    },
    "transmission_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "PA-assigned transmission id, set once the invoice is transmitted."
    },
    "transmission_status": {
      "type": "string",
      "description": "E-invoicing transmission status toward the recipient's PA\n(`not_required`/`pending`/`sending`/`sent`/`failed`)."
    },
    "type": {
      "type": "string",
      "description": "Document kind (`devis`/`facture`/`avoir`/`acompte`)."
    },
    "updated_at": {
      "type": "string",
      "description": "RFC3339 last-update timestamp."
    },
    "validity_date": {
      "type": [
        "string",
        "null"
      ],
      "description": "Validity date (`YYYY-MM-DD`)."
    },
    "vat_exigibility": {
      "type": [
        "string",
        "null"
      ],
      "description": "VAT chargeability basis."
    }
  },
  "$defs": {
    "DocumentItemView": {
      "type": "object",
      "description": "Public projection of a [`DocumentItem`].",
      "required": [
        "id",
        "description",
        "quantity",
        "unit_price",
        "vat_rate",
        "total_ht",
        "total_ttc",
        "position",
        "kind"
      ],
      "properties": {
        "description": {
          "type": "string",
          "description": "Line description."
        },
        "details": {
          "type": [
            "string",
            "null"
          ],
          "description": "Long description printed under the label. `None` when the line has none."
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Stable identifier."
        },
        "kind": {
          "type": "string",
          "description": "`product` (a billed line) or `discount` (a discount netted off the\ndocument). A discount always reads back with `quantity = \"-1\"` and a\npositive `unit_price`."
        },
        "position": {
          "type": "integer",
          "format": "int32",
          "description": "Ordering position within the document."
        },
        "quantity": {
          "type": "string",
          "description": "Quantity (decimal token)."
        },
        "total_ht": {
          "type": "integer",
          "format": "int64",
          "description": "Line total excluding VAT, in cents."
        },
        "total_ttc": {
          "type": "integer",
          "format": "int64",
          "description": "Line total including VAT, in cents."
        },
        "unit": {
          "type": [
            "string",
            "null"
          ],
          "description": "Unit-of-measure code (UN/ECE Rec 20, e.g. `C62`). `None` for legacy\nrows."
        },
        "unit_price": {
          "type": "integer",
          "format": "int64",
          "description": "Unit price excluding VAT, in cents."
        },
        "vat_rate": {
          "type": "string",
          "description": "VAT rate as a percentage token."
        }
      }
    }
  }
}