DealerPublicInventoryListingResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/dealermax-app/json-schema/dealermax-app-dealer-public-inventory-listing-response-schema.json",
  "title": "DealerPublicInventoryListingResponse",
  "description": "A paginated page of dealer inventory items for a single service.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/dealermax-app-openapi.json#/components/schemas/DealerPublicInventoryListingResponse",
  "type": "object",
  "required": [
    "service",
    "page",
    "page_size",
    "total",
    "has_next",
    "items"
  ],
  "properties": {
    "service": {
      "type": "string",
      "enum": [
        "REWIND",
        "NOS",
        "NLT"
      ],
      "description": "Inventory service this page belongs to (REWIND, NOS or NLT)."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "Current 1-based page number."
    },
    "page_size": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Number of items per page."
    },
    "total": {
      "type": "integer",
      "minimum": 0,
      "description": "Total number of items across all pages."
    },
    "has_next": {
      "type": "boolean",
      "description": "True if a further page exists after this one."
    },
    "items": {
      "type": "array",
      "description": "Inventory items on this page.",
      "items": {
        "$ref": "#/$defs/DealerPublicInventoryItem"
      }
    }
  },
  "$defs": {
    "DealerPublicInventoryItem": {
      "type": "object",
      "additionalProperties": true,
      "description": "One item in a dealer inventory listing. The shape is a union across the three services (selected by `service`): REWIND/NOS items carry `id_auto`, NLT items carry `id_offerta`.",
      "required": [
        "service",
        "nome_canonico",
        "marca",
        "modello"
      ],
      "properties": {
        "id_auto": {
          "type": "string",
          "format": "uuid",
          "description": "Vehicle UUID — present for REWIND/NOS used-vehicle items; absent for NLT offer items."
        },
        "id_offerta": {
          "type": "integer",
          "description": "NLT offer id — present for NLT items; absent for REWIND/NOS vehicle items."
        },
        "service": {
          "type": "string",
          "enum": [
            "REWIND",
            "NOS",
            "NLT"
          ],
          "description": "Inventory service this item belongs to: REWIND (used vehicles for sale), NOS (used vehicles for rent), or NLT (long-term rental offers)."
        },
        "nome_canonico": {
          "type": "string",
          "description": "Canonical display name (brand + model + trim), ready to show to end users."
        },
        "marca": {
          "type": "string",
          "description": "Vehicle brand / make (e.g. 'BMW')."
        },
        "modello": {
          "type": "string",
          "description": "Vehicle model (e.g. 'Serie 1')."
        },
        "modello_base": {
          "type": [
            "string",
            "null"
          ],
          "description": "Model family from the Motornet catalog, without generation or series year (e.g. 'Fiorino' for 'Fiorino III 2016', 'Daily' for 'Daily V 70.16 2019'). Null when the catalog has no family for the model. `modello` is unchanged. REWIND/NOS items only; absent on NLT items."
        },
        "allestimento": {
          "type": "string",
          "description": "Trim / version of the model."
        },
        "catalog_type": {
          "type": "string",
          "enum": [
            "auto",
            "vcom",
            "vind",
            "moto"
          ],
          "description": "Authoritative Motornet vehicle catalog: auto (cars), vcom (light commercial), vind (industrial), moto (motorcycles and scooters)."
        },
        "immatricolata_autocarro": {
          "type": "boolean",
          "description": "True when a car (catalog_type 'auto') is registered as an N1 light commercial vehicle. The catalog stays 'auto' — the technical sheet is the car's — but the listing filter treats them as commercial vehicles: catalog_type=vcom selects them, catalog_type=auto does not."
        },
        "quality_program": {
          "anyOf": [
            {
              "type": "object",
              "additionalProperties": true,
              "required": [
                "slug",
                "name"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Program id."
                },
                "slug": {
                  "type": "string",
                  "pattern": "^[a-z0-9-]{2,60}$",
                  "description": "Stable program slug; the value accepted by the `program` listing filter."
                },
                "name": {
                  "type": "string",
                  "description": "Program name as shown to end users (e.g. 'Arval AutoSelect')."
                },
                "brand": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Brand the program belongs to, when any (e.g. 'Audi')."
                },
                "claim": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "One-line program claim."
                },
                "logo_url": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "uri",
                  "description": "Program logo URL."
                },
                "warranty_months": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 1,
                  "maximum": 120,
                  "description": "Warranty duration declared by the program, in months."
                },
                "oem_code": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Canonical manufacturer program code, when any."
                }
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "National used-vehicle quality program the vehicle belongs to (e.g. a manufacturer or leasing selected-used program), or null. A vehicle belongs to at most one program."
        },
        "professional_upfits": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/DealerPublicProfessionalUpfit"
          },
          "description": "All public professional upfits on a VIND vehicle."
        },
        "primary_professional_upfit": {
          "anyOf": [
            {
              "$ref": "#/$defs/DealerPublicProfessionalUpfit"
            },
            {
              "type": "null"
            }
          ],
          "description": "Primary professional upfit, when present."
        },
        "prezzo_vendita": {
          "type": "number",
          "description": "Sale price in EUR, VAT included (REWIND). May be absent for non-sale services."
        },
        "previous_owner_count": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Technical previous-owner count when available. Active used stock is normalized by Core; legacy and historical snapshots may retain zero."
        },
        "previous_owner_count_source": {
          "type": [
            "string",
            "null"
          ],
          "description": "Additive provenance of previous_owner_count. A default_fallback value is not verified owner-history evidence."
        },
        "previous_owner_count_is_fallback": {
          "type": "boolean",
          "description": "True only when previous_owner_count is Core's technical default rather than a factual owner-history claim."
        },
        "cover_url": {
          "type": "string",
          "format": "uri",
          "description": "Cover image URL for the item."
        },
        "has_podcast": {
          "type": "boolean",
          "description": "True if a DealerMAX-generated audio podcast is available for this item."
        },
        "has_video": {
          "type": "boolean",
          "description": "True if a DealerMAX-generated video is available for this item."
        }
      }
    },
    "DealerPublicProfessionalUpfit": {
      "type": "object",
      "additionalProperties": false,
      "description": "One professional body/upfit associated with a VIND industrial vehicle. A non-empty selection contains exactly one primary item.",
      "required": [
        "code",
        "slug",
        "label",
        "display_label",
        "family",
        "is_primary"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable DealerMAX master-data code."
        },
        "slug": {
          "type": "string",
          "description": "Canonical URL/filter slug, for example `gru`."
        },
        "label": {
          "type": "string",
          "description": "Canonical taxonomy label; `Altro` stays one facet."
        },
        "display_label": {
          "type": "string",
          "description": "User-facing label. For `Altro` this is the dealer alias; it never creates a separate facet."
        },
        "family": {
          "type": "string",
          "description": "Display/filter family for the upfit."
        },
        "is_primary": {
          "type": "boolean",
          "description": "True for the single primary upfit of the vehicle."
        }
      }
    }
  }
}