{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://download.opter.com/json/opterOrderBookingJsonSchema1.0.json", "title": "Opter TextEDI - order booking", "$comment": "Generated from OpterTextEdi.yaml 1.3.1. Do not edit by hand.", "type": "object", "additionalProperties": false, "description": "Top-level booking request envelope. Contains the common event header\nfields plus an `order` object with all order details.\n\n**NOTE:** OpenAPI 3.0 does not support JSON Schema conditional keywords\n(if/then/else). The following rules are enforced by the JSON Schema\n(`opterOrderBookingJsonSchema1.0.json`) but cannot be expressed here:\n- `new` / `pricerequest`: `addresses` is required, with exactly one\n `pickup` and one `delivery`.\n- `new` / `pricerequest`: if `packages` is empty or absent,\n `orderDimensions` is required.\n- `orderDimensions` and package-level `dimensions` are never sent\n together.\n- `update` / `merge` / `revoke`: `opterOrderReference` or\n `customerOrderReference` is required.\n- `internalVehicleCode` and `resourceCode` are mutually exclusive, and\n either one requires `shipmentId`.\n- Address `zipCode` length depends on `countryCode`: `SE`/`FI`/`EE` = 5\n characters exactly, `DK`/`NO` = 4 characters exactly.\n", "required": [ "schema", "version", "eventCreatedDateTime", "order" ], "properties": { "schema": { "type": "string", "format": "uri", "maxLength": 2048, "description": "JSON Schema URI defining the message structure.\nUse `https://download.opter.com/json/opterOrderBookingJsonSchema1.0.json`\nfor booking requests.\n", "examples": [ "https://download.opter.com/json/opterOrderBookingJsonSchema1.0.json" ] }, "version": { "type": "string", "maxLength": 10, "description": "Schema version. Currently always `\"1.0\"`.", "examples": [ "1.0" ] }, "eventCreatedDateTime": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}$", "description": "Timestamp when this request was created, in local time.\nFormat: `YYYY-MM-DDTHH:MM:SS` (no timezone offset).\n", "examples": [ "2025-04-11T14:13:11" ] }, "eventSender": { "type": [ "string", "null" ], "maxLength": 50, "description": "**Optional free text.** Identifier of the message sender (your system),\nusually agreed with your carrier during integration setup.\nNot validated, not matched against any configuration, and not routed on —\nit exists so messages can be traced back to a system when debugging.\nMay be left empty.\n", "examples": [ "CustomerSystem" ] }, "eventReceiver": { "type": [ "string", "null" ], "maxLength": 50, "description": "**Optional free text.** Identifier of the message receiver (carrier/Opter),\nusually agreed with your carrier during integration setup.\nNot validated, not matched against any configuration, and not routed on —\nit exists so messages can be traced back to a system when debugging.\nMay be left empty.\n", "examples": [ "OpterSystem" ] }, "order": { "type": "object", "additionalProperties": false, "description": "The order payload. Contains all details for the transport order\nincluding addresses, packages, dimensions, and documents.\n", "properties": { "messageType": { "type": "string", "enum": [ "new", "update", "merge", "pricerequest", "revoke" ], "description": "Defines the operation to perform:\n- `new` — Create a new transport order.\n- `update` — Modify an existing order. Requires `opterOrderReference` or `customerOrderReference`.\n- `merge` — Merge packages into an existing order. Requires `opterOrderReference` or `customerOrderReference`. **Requires carrier configuration.**\n- `pricerequest` — Request a price quote. **Requires carrier agreement.**\n- `revoke` — Cancel an existing order. Some carriers prefer manual cancellation via email/phone.\n" }, "customerOrderReference": { "type": "string", "maxLength": 100, "description": "Your own order reference / ID. Used to correlate responses and events\nback to your system. Also usable for updates/revocations if\n`opterOrderReference` is not available. Often the same as freight\nbill number.\n" }, "opterOrderReference": { "type": [ "string", "null" ], "maxLength": 50, "description": "Opter's internal order number, returned in the response after\nsuccessful creation. Use this for `update` or `revoke`\noperations. Preferred over `customerOrderReference` for reliability.\n" }, "shipmentId": { "type": [ "integer", "null" ], "description": "Opter's internal identifier for a **single leg (shipment)** of an\norder. An order may be split into several legs; `shipmentId`\ntargets exactly one of them.\n\nUse it on `messageType: update` when the update must act on one\nspecific leg rather than the whole order — for example assigning\na vehicle or a resource to the correct leg (see `resourceCode`\nand `internalVehicleCode`).\n\n**Not returned by this API.** `shipmentId` values must be read\nfrom the statistics endpoint of the Opter API V1 — a separate API\nwith its own documentation and credentials — which also supplies\n`deliveryId`.\n" }, "payingCustomerCode": { "type": "string", "maxLength": 50, "description": "The code or number of the freight payer in Opter.\n**Must match a valid, pre-configured code in the carrier's Opter instance.**\nContact your carrier to obtain your customer code.\n" }, "serviceMappingCode": { "type": "string", "maxLength": 50, "description": "Maps to a service type configured in Opter (e.g., standard, express, economy).\nMust be pre-agreed and configured with your carrier. Using an unconfigured\ncode will result in an `EXCEPTION_Service type incorrect` error.\n" }, "vehicleMappingCode": { "type": "string", "maxLength": 50, "description": "Maps to a vehicle type configured in Opter (e.g., van, truck, trailer).\nMust be pre-agreed and configured with your carrier. Using an unconfigured\ncode will result in an `EXCEPTION_Vehicle type incorrect` error.\n" }, "resourceCode": { "type": [ "string", "null" ], "maxLength": 50, "description": "Code of the **subcontractor** to assign to the leg identified by\n`shipmentId`, when that leg is bought externally rather than driven\nin-house. Despite the generic name this is a subcontractor code.\n**Requires carrier agreement.**\n\n**Mutually exclusive with `internalVehicleCode` on the same leg** —\na leg is either driven by the carrier's own vehicle or subcontracted,\nnever both. Different legs of the same order may be assigned\ndifferently.\n\nThis is not a mapping code — it is an actual resource code from\nthe carrier's Opter instance, and valid values must be read from\nthe subcontractor/resource endpoint of the Opter API V1 (a\nseparate API with its own documentation and credentials).\nSend together with `shipmentId` so the assignment lands on the\nintended leg.\n" }, "internalVehicleCode": { "type": [ "string", "null" ], "maxLength": 50, "description": "Code of the carrier's own vehicle to assign to the leg identified\nby `shipmentId`. **Requires carrier agreement.**\n\n**Mutually exclusive with `resourceCode` on the same leg** — a leg is\neither driven internally or subcontracted, never both. Send one update\nmessage per leg, each with its own `shipmentId`.\n\nDistinct from `vehicleMappingCode`, which selects a vehicle\n*type* for the order. `internalVehicleCode` points at one concrete\nvehicle in the carrier's Opter instance, and valid values must be\nread from the vehicle endpoint of the Opter API V1 (a separate\nAPI with its own documentation and credentials, the same one that\nserves the statistics and subcontractor endpoints).\n" }, "freightBillNumber": { "type": [ "string", "null" ], "maxLength": 50, "description": "Freight bill / consignment number for this order." }, "customerProject": { "type": "string", "maxLength": 50, "description": "Project name for grouping or reporting purposes." }, "projectNumber": { "type": "string", "maxLength": 50, "description": "Project number for grouping or reporting purposes." }, "sendersReference": { "type": "string", "maxLength": 50, "description": "Sender's own reference for this shipment." }, "receiversReference": { "type": "string", "maxLength": 50, "description": "Receiver's reference for this shipment." }, "goodsType": { "type": "string", "maxLength": 50, "description": "General description of goods type (e.g., \"Electronics\", \"Food\")." }, "officeMessage": { "type": "string", "maxLength": 2048, "description": "Internal message visible to carrier office staff." }, "officeExtraMessage": { "type": "string", "maxLength": 2048, "description": "Additional internal message for carrier office staff." }, "officeExternalMessage": { "type": "string", "maxLength": 2048, "description": "External message (may be visible on documents/notifications)." }, "driverInstructions": { "type": "string", "maxLength": 2048, "description": "General instructions shown to the driver for the entire order." }, "transportDate": { "type": "string", "format": "date", "description": "The planned transport date in `YYYY-MM-DD` format.\nAddress-level time windows provide more precise scheduling.\n", "examples": [ "2025-04-11" ] }, "orderDimensions": { "type": "object", "additionalProperties": false, "description": "**Order-level aggregate dimensions.** Use ONLY when individual\npackage dimensions are not available.\n\n⚠️ **Do NOT use both `orderDimensions` and package-level\n`dimensions` — this will cause calculation errors.**\n", "properties": { "orderPackageQuantity": { "type": "integer", "description": "Total number of packages in the order." }, "orderWeightKgm": { "type": "number", "description": "Total weight in kilograms." }, "orderVolumeCbm": { "type": "number", "description": "Total volume in cubic meters." }, "orderEuropalletSpace": { "type": "number", "description": "Total europallet spaces required." }, "orderLoadmeterMtr": { "type": "number", "description": "Total load meters required." } } }, "transporterSpecificFields": { "type": "object", "additionalProperties": false, "description": "Carrier-specific configuration fields.\n\n⚠️ **ALL fields in this section require prior agreement and\nconfiguration with your carrier.** Fields not listed here are\nrejected by the schema. Unmatched mapping codes\n(`priceitemMappingCode`, `regionMappingCode`, ...) are not\napplied and are reported in `response.warnings`.\n", "properties": { "priceitems": { "type": "array", "description": "Price line items (41 fields). Each `priceitemMappingCode` must be\npre-configured with your carrier. Use `state` to manage the\nlifecycle: `new` to add, `update` to create-or-update,\n`delete` to remove. Path is\n`order.transporterSpecificFields.priceitems` (lower-case `i`).\n", "items": { "type": "object", "additionalProperties": false, "properties": { "priceitemMappingCode": { "type": "string", "maxLength": 50, "description": "Carrier-configured price item code. Unmatched codes are not applied and raise a warning." }, "state": { "type": "string", "enum": [ "new", "update", "delete" ], "maxLength": 50, "description": "Lifecycle state. Defaults to `new` when omitted. `update` acts as create-or-update, matching on `customerReference` + `priceitemMappingCode`; recommended unless you track state yourself." }, "opterId": { "type": [ "string", "null" ], "maxLength": 50, "description": "Opter internal price item ID. Used to target an existing line on `update` or `delete`." }, "customerReference": { "type": "string", "maxLength": 50, "description": "Your reference for this price item line. Use it so the line can be updated later." }, "customerGuid": { "type": [ "string", "null" ], "maxLength": 50, "description": "Your GUID reference for this line, as an alternative to `customerReference`." }, "description": { "type": "string", "maxLength": 1024, "description": "Free-text description of the price item." }, "currencyCode": { "type": "string", "maxLength": 50, "description": "Currency of the amounts on this line. Must be configured in the carrier's Opter instance." }, "resourceCode": { "type": "string", "maxLength": 50, "description": "Resource / subcontractor code the resource-side amounts on this line apply to." }, "quantity": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Quantity. Up to 18 digits, 6 decimals." }, "unit1quantity": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Quantity for the first pricing unit." }, "unit1name": { "type": "string", "maxLength": 50, "description": "Name of the first pricing unit (e.g. \"kg\", \"hour\")." }, "unit2quantity": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Quantity for the second pricing unit." }, "unit2name": { "type": "string", "maxLength": 50, "description": "Name of the second pricing unit." }, "unitPrice": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Customer-side price per unit." }, "unitPriceResource": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Resource-side (cost) price per unit." }, "fixedPrice": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Customer-side fixed price for the line, independent of quantity." }, "fixedPriceResource": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Resource-side (cost) fixed price for the line." }, "discountAmount": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Discount as an absolute amount." }, "discountFactor": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Discount as a factor (e.g. 0.10 for 10%)." }, "kickbackAmount": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Kickback as an absolute amount." }, "kickbackFactor": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Kickback as a factor." }, "invoice": { "type": "boolean", "description": "The line should be included on the customer invoice." }, "credit": { "type": "boolean", "description": "The line is a credit rather than a debit." }, "noFuelExtra": { "type": "boolean", "description": "No fuel surcharge on the customer-side amounts of this line." }, "noFuelExtraResource": { "type": "boolean", "description": "No fuel surcharge on the resource-side amounts of this line." }, "contractorExpectedCost": { "type": [ "number", "null" ], "minimum": -9999999999999999, "maximum": 9999999999999999, "description": "Expected cost from the subcontractor for this line." }, "contractorInvoiceNo": { "type": "string", "maxLength": 50, "description": "Subcontractor's invoice number for this line." }, "contractorInvoiceDate": { "type": "string", "format": "date", "description": "Date of the subcontractor's invoice (YYYY-MM-DD)." }, "contractorInvoiceDone": { "type": "boolean", "description": "Subcontractor invoicing is complete for this line." }, "invoiceNo": { "type": "string", "maxLength": 50, "description": "Invoice number associated with this price item." }, "billNo": { "type": "string", "maxLength": 50, "description": "Bill number associated with this price item." }, "materialSiteName": { "type": "string", "maxLength": 50, "description": "Name of the material site this line relates to (bulk / materials handling)." }, "materialSiteCode": { "type": "string", "maxLength": 50, "description": "Code of the material site. Must be configured in the carrier's Opter instance." }, "extraId1": { "type": "string", "maxLength": 50, "description": "Carrier-defined custom text slot 1. Meaning is defined per carrier." }, "extraId2": { "type": "string", "maxLength": 50, "description": "Carrier-defined custom text slot 2. Meaning is defined per carrier." }, "extraId3": { "type": "string", "maxLength": 50, "description": "Carrier-defined custom text slot 3. Meaning is defined per carrier." }, "extraId4": { "type": "string", "maxLength": 50, "description": "Carrier-defined custom text slot 4. Meaning is defined per carrier." }, "extraId5": { "type": "string", "maxLength": 50, "description": "Carrier-defined custom text slot 5. Meaning is defined per carrier." }, "extraId6": { "type": "string", "maxLength": 50, "description": "Carrier-defined custom text slot 6. Meaning is defined per carrier." }, "extraId7": { "type": "string", "maxLength": 50, "description": "Carrier-defined custom text slot 7. Meaning is defined per carrier." }, "extraId8": { "type": "string", "maxLength": 50, "description": "Carrier-defined custom text slot 8. Meaning is defined per carrier." } } } }, "extraDimension1": { "type": "number", "description": "Carrier-defined extra dimension field 1." }, "extraDimension2": { "type": "number", "description": "Carrier-defined extra dimension field 2." }, "extraDimension3": { "type": "number", "description": "Carrier-defined extra dimension field 3." }, "extraDimension4": { "type": "number", "description": "Carrier-defined extra dimension field 4." }, "extraDimension5": { "type": "number", "description": "Carrier-defined extra dimension field 5." }, "extraId1": { "type": "string", "maxLength": 50, "description": "Carrier-defined extra ID field 1." }, "extraId2": { "type": "string", "maxLength": 50, "description": "Carrier-defined extra ID field 2." }, "extraId3": { "type": "string", "maxLength": 50, "description": "Carrier-defined extra ID field 3." }, "extraId4": { "type": "string", "maxLength": 50, "description": "Carrier-defined extra ID field 4." }, "extraId5": { "type": "string", "maxLength": 50, "description": "Carrier-defined extra ID field 5." }, "regionMappingCode": { "type": "string", "maxLength": 50, "description": "Carrier-configured region code for routing." }, "trailMappingCode": { "type": "string", "maxLength": 50, "description": "Carrier-configured trail/route code." }, "querySetMappingCode": { "type": "string", "maxLength": 50, "description": "Carrier-configured query set code." }, "readyForInvoicing": { "type": "boolean", "description": "Flag: order is ready to be invoiced. Requires carrier config." }, "readyForDispatching": { "type": "boolean", "description": "Flag: order is ready to be dispatched. Requires carrier config." }, "notToBeInvoiced": { "type": "boolean", "description": "Flag: order should not be invoiced. Requires carrier config." }, "hideUntilScanned": { "type": "boolean", "description": "Flag: hide order in dispatch until a package is scanned. Requires carrier config." } } }, "options": { "type": "array", "description": "Service options (e.g., tail-lift, call-before-delivery). Must be pre-configured with carrier.", "items": { "type": "object", "additionalProperties": false, "properties": { "optionMappingCode": { "type": "string", "maxLength": 50, "description": "Carrier-configured option code." }, "selected": { "type": "boolean", "description": "Whether this option is selected for the order." } } } }, "looseItems": { "type": "array", "description": "Loose items counted against the order (for example returnable\nload carriers). Each entry carries a carrier-configured code and\nthe quantity at the start and at the end of the transport.\nMust be pre-configured with your carrier.\n", "items": { "type": "object", "additionalProperties": false, "properties": { "looseItemMappingCode": { "type": "string", "maxLength": 50, "description": "Carrier-configured loose item code." }, "startingQuantity": { "type": "number", "description": "Quantity at the start of the transport." }, "endingQuantity": { "type": "number", "description": "Quantity at the end of the transport." } } } }, "addresses": { "type": "array", "minItems": 2, "maxItems": 2, "description": "**Exactly 2 addresses required:** one `pickup` and one `delivery`.\nMulti-stop routes are not supported — use separate bookings.\nRequired for `new` and `pricerequest` (enforced by the JSON Schema).\n", "items": { "type": "object", "additionalProperties": false, "required": [ "addressType" ], "properties": { "addressType": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "`pickup` = collection address, `delivery` = destination address.\nExactly one of each is required per order.\n" }, "earliestTransportDateTime": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}$", "description": "Earliest acceptable time for pickup/delivery.\nFormat: `YYYY-MM-DDTHH:MM:SS`. Leave empty if no constraint.\n" }, "latestTransportDateTime": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}$", "description": "Latest acceptable time for pickup/delivery.\nFormat: `YYYY-MM-DDTHH:MM:SS`. Leave empty if no constraint.\n" }, "transporterCustomerCode": { "type": "string", "maxLength": 50, "description": "If this address belongs to a known customer in the carrier's Opter\nsystem, provide their customer code here. The system will auto-fill\naddress details.\n" }, "transporterHubMappingCode": { "type": "string", "maxLength": 50, "description": "Carrier-configured hub/terminal code for this address." }, "name": { "type": "string", "maxLength": 50, "description": "Company or person name at this address." }, "careOf": { "type": "string", "maxLength": 50, "description": "Care-of name (c/o) for the address." }, "streetAddress": { "type": "string", "maxLength": 50, "description": "Street name and building number." }, "addressLine2": { "type": "string", "maxLength": 50, "description": "Additional address line (e.g., floor, suite)." }, "addressLine3": { "type": "string", "maxLength": 50, "description": "Additional address line." }, "zipCode": { "type": "string", "maxLength": 50, "description": "Postal / ZIP code. Country-specific length validation applies\n(enforced by the JSON Schema): `SE`/`FI`/`EE` = exactly 5\ncharacters; `DK`/`NO` = exactly 4 characters.\n" }, "city": { "type": "string", "maxLength": 50, "description": "City name." }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code (e.g., `SE`, `NO`, `DK`)." }, "longitude": { "type": [ "number", "null" ], "description": "GPS longitude (WGS 84). Optional but improves routing." }, "latitude": { "type": [ "number", "null" ], "description": "GPS latitude (WGS 84). Optional but improves routing." }, "entreCode": { "type": "string", "maxLength": 50, "description": "Door / entrance code for the driver." }, "phoneNumber": { "type": "string", "maxLength": 50, "description": "Contact phone number at this address. Recommended for driver coordination." }, "emailAddress": { "type": "string", "format": "email", "maxLength": 50, "description": "Contact email address at this address." }, "driverInstructions": { "type": "string", "maxLength": 255, "description": "Address-specific instructions for the driver (e.g., \"Use rear entrance\")." } }, "allOf": [ { "if": { "properties": { "countryCode": { "enum": [ "SE", "FI", "EE" ] } }, "required": [ "countryCode" ] }, "then": { "properties": { "zipCode": { "minLength": 5, "maxLength": 5 } } } }, { "if": { "properties": { "countryCode": { "enum": [ "DK", "NO" ] } }, "required": [ "countryCode" ] }, "then": { "properties": { "zipCode": { "minLength": 4, "maxLength": 4 } } } } ] }, "allOf": [ { "contains": { "properties": { "addressType": { "const": "pickup" } }, "required": [ "addressType" ] }, "minContains": 1, "maxContains": 1 }, { "contains": { "properties": { "addressType": { "const": "delivery" } }, "required": [ "addressType" ] }, "minContains": 1, "maxContains": 1 } ] }, "packages": { "type": "array", "description": "List of packages in the order. When providing packages, include\ndimensions at the package level (preferred). If this array is\nempty/absent, `orderDimensions` must be provided instead.\n", "items": { "type": "object", "additionalProperties": false, "properties": { "customerReference": { "type": "string", "maxLength": 50, "description": "Your reference for this package." }, "barcode": { "type": "string", "maxLength": 50, "description": "Scannable barcode for the package. Used for tracking and terminal scans." }, "packageTypeCode": { "type": "string", "maxLength": 50, "description": "Package type code (e.g., `EUR` for europallet, `PC` for parcel/colli,\n`BOX` for box).\n\n**Free text.** Despite the name this is not a mapping code and Opter\ndoes not validate it. A carrier may map the values you send onto the\npackage types configured in their own setup, but whether that mapping\nexists is entirely up to the carrier — agree the values before relying\non them.\n" }, "text": { "type": "string", "maxLength": 50, "description": "Free-text description of the package contents." }, "goodsType": { "type": "string", "maxLength": 50, "description": "Goods type classification for this package." }, "dimensions": { "type": "object", "additionalProperties": false, "description": "Package-level dimensions. **Preferred over order-level dimensions.**\nDo not use if `orderDimensions` is provided.\n", "properties": { "quantity": { "type": "integer", "enum": [ 1 ], "description": "Always 1 — each physical package is its own object in the array." }, "weightKgm": { "type": "number", "description": "Weight in kilograms." }, "volumeCbm": { "type": "number", "description": "Volume in cubic meters." }, "europalletSpace": { "type": "number", "description": "Europallet spaces consumed." }, "loadmeterMtr": { "type": "number", "description": "Load meters consumed." }, "widthMtr": { "type": "number", "description": "Width in meters." }, "heightMtr": { "type": "number", "description": "Height in meters." }, "depthMtr": { "type": "number", "description": "Depth (length) in meters." } } }, "transporterSpecificFields": { "type": "object", "additionalProperties": false, "description": "Package-level carrier-specific fields.\n⚠️ Requires prior carrier configuration.\n", "properties": { "extraDimension1": { "type": "number" }, "extraDimension2": { "type": "number" }, "extraDimension3": { "type": "number" }, "extraDimension4": { "type": "number" }, "extraDimension5": { "type": "number" }, "extraId1": { "type": "string", "maxLength": 255 }, "extraId2": { "type": "string", "maxLength": 255 }, "extraId3": { "type": "string", "maxLength": 255 }, "extraId4": { "type": "string", "maxLength": 255 }, "extraId5": { "type": "string", "maxLength": 255 } } } } } }, "dangerousGoods": { "type": "array", "description": "Dangerous goods declarations. Required by law when shipping\nhazardous materials. Use official UN numbers and proper shipping names.\n", "items": { "type": "object", "additionalProperties": false, "properties": { "unNumber": { "type": "integer", "minimum": 1, "maximum": 9999, "description": "UN number identifying the hazardous substance (e.g., 1234)." }, "properShippingName": { "type": "string", "maxLength": 50, "description": "Official proper shipping name as per IMDG/ADR regulations." }, "class": { "type": "string", "pattern": "^(?:[1-9](?:\\.[0-9]{1,2})?)$", "maxLength": 50, "description": "Hazard class (e.g., \"1.3\", \"2\", \"3\")." }, "packingGroup": { "type": "string", "enum": [ "I", "II", "III" ], "description": "Packing group indicating danger severity (I = highest)." }, "amount": { "type": "number", "description": "Quantity of the dangerous substance." }, "unit": { "type": "string", "maxLength": 50, "description": "Unit of measure for the amount (e.g., \"kg\", \"liter\")." }, "tunnelRestriction": { "type": "string", "maxLength": 50, "description": "Tunnelrestriction limits" }, "transportIndex": { "type": "string", "maxLength": 50, "description": "transportindex of the dangerous goods" }, "barcodes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true, "description": "Barcodes of packages containing this dangerous goods item." } } } }, "documents": { "type": "array", "description": "Attached documents. Provide content via `dataBase64encoded` (inline)\nOR `url` (external link) — not both.\n", "items": { "type": "object", "additionalProperties": false, "properties": { "documentType": { "type": "string", "enum": [ "edi", "freightbill", "packagelabel" ], "maxLength": 50, "description": "Type of document:\n- `freightbill` — Freight bill / consignment note\n- `packagelabel` — Package label for printing\n- `edi` — EDI file or other electronic document\n" }, "comment": { "type": "string", "maxLength": 255, "description": "Comment or description for the document." }, "fileName": { "type": "string", "maxLength": 50, "description": "File name including extension (e.g., \"freightbill_123.pdf\")." }, "url": { "type": "string", "maxLength": 255, "description": "URL to download the document. Use this OR `dataBase64encoded`." }, "dataBase64encoded": { "type": "string", "description": "Base64-encoded file content. Use this OR `url`." } }, "oneOf": [ { "required": [ "dataBase64encoded" ] }, { "required": [ "url" ] } ] } } }, "required": [ "messageType" ], "allOf": [ { "if": { "properties": { "messageType": { "enum": [ "new", "pricerequest" ] } }, "required": [ "messageType" ] }, "then": { "required": [ "addresses" ] } }, { "if": { "properties": { "messageType": { "enum": [ "new", "pricerequest" ] } }, "required": [ "messageType" ] }, "then": { "anyOf": [ { "required": [ "orderDimensions" ] }, { "required": [ "packages" ], "properties": { "packages": { "minItems": 1 } } } ] } }, { "if": { "properties": { "messageType": { "enum": [ "update", "merge", "revoke" ] } }, "required": [ "messageType" ] }, "then": { "anyOf": [ { "required": [ "opterOrderReference" ], "properties": { "opterOrderReference": { "type": "string", "minLength": 1 } } }, { "required": [ "customerOrderReference" ], "properties": { "customerOrderReference": { "minLength": 1 } } } ] } }, { "not": { "required": [ "orderDimensions", "packages" ], "properties": { "packages": { "contains": { "required": [ "dimensions" ] } } } } }, { "not": { "required": [ "internalVehicleCode", "resourceCode" ], "properties": { "internalVehicleCode": { "type": "string" }, "resourceCode": { "type": "string" } } } }, { "if": { "anyOf": [ { "required": [ "internalVehicleCode" ], "properties": { "internalVehicleCode": { "type": "string" } } }, { "required": [ "resourceCode" ], "properties": { "resourceCode": { "type": "string" } } } ] }, "then": { "required": [ "shipmentId" ], "properties": { "shipmentId": { "type": "integer" } } } } ] } } }