Rendered from docs/INTEGRATOR-GUIDE.md. The interactive reference is Swagger UI; the seven request examples are attached there and on the portal's API & integration page.

Freightools GPT — Integrator Guide #

For the developer who connects a forwarder's system to Freightools GPT. You send one JSON per shipment (an import to Israel, an export from Israel or a cross-trade); the service validates it completely, creates or updates the Customer Shipment (CS) and Shipping Order (SO) in Freightools, waits for the external prerequisites, transmits the Israeli customs sub-manifest when you asked for it, and returns the customs feedback. The same information is shown in the customer portal.

This guide is the customer-facing rendering of the approved plan (docs/PLAN-2026-11-04.md §3, §4.6, §4.8, §5, §6). The interactive reference is Swagger UI at /docs (OpenAPI at /openapi.json).

Evidence labels used below, inherited from the plan: VERIFIED (seen in a live read-back, the Swagger or a real customs file), INFERRED (pattern read from samples), UNVERIFIED (assumption), FT-DEPENDENT (only the Freightools backend or a real example can settle it). Where behaviour is FT-DEPENDENT we say so; design your integration so that it tolerates the states in §9 rather than assuming success.

1. Authentication #

Every API call carries an API key as a bearer token:

Authorization: Bearer em_test_<keyId>.<secret>
Authorization: Bearer em_live_<keyId>.<secret>

• Keys are environment-bound. A key is created inside one tenant environment (test or production) and only ever touches that environment's Freightools host. An em_test_… key can never create anything on production and vice versa. The prefix tells you which one you hold; the server checks the binding on every request.
• Shown once. The secret is displayed a single time when the key is generated in the portal (Settings → API keys). We store only a SHA-256 hash. If you lose the secret, generate a new key and revoke the old one (rotation = create + revoke; both keys work during the overlap).
• Scopes. A key carries a subset of: shipments:read, shipments:write, manifest:send, documents:read, documents:write, logs:xml, org:read. A call outside the key's scopes returns 403 with the standard envelope. logs:xml is the only scope that returns raw customs XML and every such read is written to the tenant audit log.
• IP allow-list (optional, per key): requests from other addresses are refused with 403.
• Missing or invalid token: 401 with the JSON envelope (§6), never an HTML page.

The portal (/portal) uses user accounts (e-mail + password, optional TOTP), not API keys. Portal users generate and revoke API keys.

2. The one call: POST /v1/shipments #

POST /v1/shipments
Authorization: Bearer em_test_…
Content-Type: application/json
Prefer: wait=20          (optional, ≤ 20 s, see below)

Body: the shipment JSON (§3). Body limit 1 MiB (413 payload_too_large).

2.1 Responses #

A closed write gate does not change the status: the shipment is validated and recorded (201/202) and the apply stops before the first Freightools call — processing.state is blocked and processing.readiness.checks carries send_gates = blocked with the detail "Freightools writes are disabled for this environment (switched on by Freightools support)". The apply resumes by itself when the gate is opened. 503 gate_closed is answered only by POST …/manifest (§8), never by this POST.

The body of 200/201/202 is the shipment representation (§7). With Prefer: wait=N (N ≤ 20 seconds; larger values are clamped to 20) the server waits up to N seconds for the Freightools apply to finish before answering, so a quick integration can see freightools.customerShipment.code in the first response. Without it, poll GET /v1/shipments/{id}.

2.2 Same shipmentRef = same shipment #

shipmentRef is your key (^[A-Za-z0-9._/-]{1,60}$, unique per tenant environment). Sending the same reference again never creates a second shipment and never returns 409. What happens depends on what changed:

Two simultaneous POSTs for the same reference are serialised: you get either an identical replay or revisions N+1 and N+2, never an error.

Changes that Freightools cannot express as an update return 422 unsupported with unsupported_change — in release 1 that is a change of service variant (FCL ↔ LCL ↔ air). Use a new shipmentRef.

options.dryRun: true runs the full validation and resolution and returns the warnings and known deviations, but writes nothing and creates no revision.

2.3 Free shipments and the payment method #

A company's first 10 production shipments are free (pay as you go, see /pricing). After them, while the company is still on the free trial, a request that would create a new shipment in production answers 402 payment_method_required; nothing is validated or recorded:

{ "type": "payment_method_required", "status": 402, "requestId": "req_01JC…", "shipmentRef": "EXAMPLE-FCL-011",
  "message": "Your first 10 shipments were free. Add a payment method to create more.",
  "errors": [ { "path": "", "code": "payment_method_required", "message": "Your first 10 shipments were free. Add a payment method to create more.",
                "hint": "An owner or admin of your company adds it in the portal: Settings → Usage & billing. https://<portal>/portal/production/settings/usage" } ],
  "settingsUrl": "https://<portal>/portal/production/settings/usage" }

An owner or admin of your company adds the payment method in the portal under Settings → Usage & billing; once Freightools has set it up, send the same body again. Never refused: a new revision or an identical retry of an existing shipmentRef, options.dryRun, the test environment (it never counts), customs sends, decisions and documents. What counts is every production shipment created through this API, the portal forms or the copilot, once; shipments synced from Freightools never count.

3. The shipment JSON #

3.1 Structure #

Common core plus blocks whose shape depends on service. A block of the wrong shape for the mode is 400 not_applicable_for_variant.

shipmentRef, submitManifest?                                  all
service   { mode: ocean|air, load: FCL|LCL (ocean), scope?, lcl?: { arrangement: lineMaster|coload|consolidation, consolidationRef? } }
parties   { shipper?, consignee?, notify?, customer?, customsBroker?, coloader? (co-load only) }
          the customer must be among them: the consignee, the shipper or customer.details (§3.1.1)
dgContact?                                                    when any goods line is dangerous and the tenant has no default
routing   ocean: { pol, pod, placeOfReceipt?, placeOfDelivery?, acceptancePlace?, transshipmentPorts[]? }
                 pod: an import may give master.dischargeSite instead
          air:   { aol, aod, acceptancePlace?, placeOfReceipt?, placeOfDelivery?, transshipmentAirports[]? }
carriage? ocean: { carrier?{scac|name}, vessel?{imo,name}, voyage?, eta?, etd?, booking?, bookingDate?, pickupDate?, cutoffDate?, transshipments[]? }
          air:   { airline?{iata|icao}, flight?{number,date}, eta?, booking?, bookingDate?, pickupDate?, cutoffDate? }
master?   { issuer?: carrier|coloader|self, document?{number?,type?}, loadingPort?, dischargeSite?, goodsReceiptSite?, transactionNumber?, manifestNumber? }
house?    { document?{number?,type?}, placeOfIssue?, transactionNumber? }
commercial?{ incoterm?, freightTerms?, freightCharge? (air) }
cargo     FCL: { containers[]{ number?, isoType, seal?, grossKg?, cbm?, tareKg?, soc?, reefer?, packages?{count,type,marks?}, goods[] }, totalCbm? }
          LCL: { container?{ number?, isoType, seal? }, packages[]{ count, type, grossKg?, cbm?, marks?, goods[] } }
          AIR: { pieces[]{ count, type, grossKg?, cbm?, dimensionsCm?, chargeableKg?, goods[] } }
goods[]   { hs?, description, additionalHs[]?, dangerous?{ unNumber, class, packingGroup?, properShippingName? }, vehicles[]?{vin}, value? }
options   { dryRun? }

A ? marks what may be left out. Unknown fields are rejected (unknown_field) so that a typo never silently drops data. Documents are not part of this JSON (§12).

Variants: F ocean FCL · L ocean LCL under a line master · C ocean LCL co-load under another forwarder's house · K ocean LCL consolidation (gated until Freightools evidence set B1 is in hand: 422 consolidation_unsupported) · A air import house.

3.1.1 Start small #

A shipment does not have to be complete to be created. Five things are enough; everything else can come in later revisions with the same shipmentRef (§2.2):

Nothing else is required to create a shipment (a co-load, variant C, also names parties.coloader). What you do send is validated as always: an import's consignee must be in Israel, a tax id must have the right form, a booking number needs its carriage.etd, dangerous goods need their DG contact.

The smallest FCL import:

{
  "shipmentRef": "EXAMPLE-START-001",
  "service": {
    "mode": "ocean",
    "load": "FCL"
  },
  "parties": {
    "consignee": {
      "name": "Example Imports Ltd",
      "country": "IL"
    }
  },
  "routing": {
    "pol": "CNSZX",
    "pod": "ILASH"
  },
  "cargo": {
    "containers": [
      {
        "isoType": "45G1",
        "goods": [
          {
            "description": "OFFICE FURNITURE"
          }
        ]
      }
    ]
  }
}

The shipment is created (201). The trade is import (discharged in Ashdod), the consignee is the customer, submitManifest left out means false, and the incoterm, the loading port and the place of acceptance are filled in and reported as warnings (§6.3). A consignee that is not yet a Freightools partner is created with - as its address, city and phone (warnings partner_address_placeholder, partner_tel_placeholder) until a revision brings them.

A later revision completes it: the same shipmentRef and the body again, now with what has become known — here the shipper, the carrier and its dates, the weight, the importer's tax id and address, and the customs discharge site:

{
  "shipmentRef": "EXAMPLE-START-001",
  "service": {
    "mode": "ocean",
    "load": "FCL"
  },
  "parties": {
    "shipper": {
      "name": "Example Trading Co., Ltd",
      "address": "12 Harbour Road",
      "city": "Shenzhen",
      "country": "CN"
    },
    "consignee": {
      "name": "Example Imports Ltd",
      "taxId": "510000128",
      "address": "5 Industrial Street",
      "city": "Tel Aviv-Yafo",
      "country": "IL"
    }
  },
  "routing": {
    "pol": "CNSZX",
    "pod": "ILASH"
  },
  "carriage": {
    "carrier": {
      "scac": "MSCU"
    },
    "etd": "2026-12-01",
    "eta": "2026-12-20"
  },
  "master": {
    "dischargeSite": "ILAST"
  },
  "cargo": {
    "containers": [
      {
        "isoType": "45G1",
        "grossKg": 11500,
        "goods": [
          {
            "description": "OFFICE FURNITURE"
          }
        ]
      }
    ]
  }
}

What an import's customs manifest needs is asked later, not at create: the shipment is created and its readiness check manifest_data (§9.2) stays waiting, naming what is still missing — the consignee and its tax id, the shipper, their addresses, the customs discharge site (LCL: also the goods-receipt site), the weights, container numbers, seals, packages, HS codes and the master / house document numbers. Customs receives the Freightools partner's data, so a tax id or an address the shipment's Freightools partner already holds is not asked for again. After the second body above it still names the container number, the seal, the packages, the HS code and the two B/L numbers; they come in further revisions. An export or cross-trade has no Israeli customs manifest and is ready once applied.

3.2 How to read the field tables #

Columns:

• F / L / C / K / A — requirement per variant: R required, O optional, C conditional (the condition is in the Validation column), – not applicable (sending it is not_applicable_for_variant).
• Validation — what is checked before anything is written. Numbers in brackets (e.g. 553, 1023) are the Israeli customs check codes the rule protects you from.
• Freightools receives — the CS/SO/Partner field the value is written to (Freightools is where the manifest XML is generated from).
• Customs receives — whether the value actually reaches the customs manifest today. This is the honest part:
  • YES-V — seen emitted from this field in a real manifest XML.
  • YES-I — emitted, but the source field is inferred rather than seen.
  • NO — not emitted today, or there is no Freightools field for it. The value is stored and may be appended to a description, but that is not transmission. Every such value is listed back to you in knownDeviations[] (§6.4) with the Freightools change request (CR-n) that would fix it.
  • FTD — air: there is no customs tool on the air process in Freightools today, so nothing air reaches customs through this path yet; the customs element the value would feed is named so you know what the data is for.
  • N/A — the field is for Freightools only and has no customs meaning.

3.2.1 Import, export and cross-trade (and the booking stage) #

Every shipment is one of three trades, worked out from the two ends of the main carriage (routing.pol → routing.pod, or routing.aol → routing.aod; an import's master.dischargeSite stands for an Israeli POD):

service.trade may state the trade; when it is given it must agree with the ends (trade_conflict). Both ends in Israel is refused (trade_domestic). A body without service.trade (every body written before this section existed) keeps its meaning: discharged in Israel = import. Freightools receives the trade as ServiceTrade on the customer shipment and the shipping order (0 export, 1 import, 3 cross-trade).

Booking stage. A shipment can be created before its container numbers, seals, packages, HS codes and B/L (AWB) numbers exist — and before its weight, its carrier and its dates (§3.1.1): send the container type and the goods descriptions, and send the rest in a later revision with the same shipmentRef. A booking line numbered later updates its own Freightools goods row. An import's customs manifest needs them: until they are there its readiness check manifest_data stays waiting and names what is missing. An export or cross-trade never waits for them.

Customer and incoterm. The customer is the one party a shipment cannot be created without (Freightools does not save a customer shipment without its customer). It is parties.customer.party when stated (other needs parties.customer.details; details alone means other). Left out, it is the importer (consignee) on an import or cross-trade and the exporter (shipper) on an export — on an import, the environment's default paying party when one is set — when that party is given; otherwise the only one of shipper and consignee that is given. A body whose customer is not there is refused with 422 customer_required, reported at the missing party's name (/parties/consignee/name, /parties/shipper/name or /parties/customer/details/name). commercial.incoterm left out is derived with Freightools' Instant Quote rule and reported as warning incoterm_derived: a customer on the importer side gets EXW with a pickup door (service.scope starting at door), else FOB (air FCA); on the exporter side DAP with a delivery door, else CFR (air CPT). Freight terms follow the incoterm as before.

Tracking. tracking: { "active": true|false, "alerts"?: true|false } switches Freightools tracking and alerts on the shipping order (ActiveTracking / ActiveAlerts; alerts follows active when left out). Left out, a new shipment follows the company setting "Track new shipments" (on unless switched off) and an update leaves Freightools' value alone.

3.3 Header and service #

3.4 Parties #

A party object: { name, address?, city?, country, zip?, phone?, email?, partnerCode?, taxId?, taxIdType? } — a name and a country are enough; the address and the city may come later. Limits: name ≤ 70, address ≤ 70, city ≤ 35, zip ≤ 10, phone ≤ 50 with ≥ 6 digits, e-mail ≤ 100, partnerCode ≤ 50, taxId ≤ 20, taxIdType ∈ vat | company | passport | other. Country is ISO 3166-1 alpha-2. Placeholder addresses (NA, N/A, DD, CC, 000, 0, -, C) are rejected (placeholder_address): leave out an address or a city you do not have.

parties.shipper and parties.consignee are both optional; what a shipment needs is its customer (§3.2.1, customer_required), so each of the two is required only when it is the customer.

Partner matching (how a party becomes a Freightools partner): partnerCode first, then taxId against the tenant's partner mirror, then exact normalised name + country, else a new partner is created. Freightools requires an address, a city and a phone on a partner: a new partner created from a party without them gets "-" in those fields, with warnings partner_address_placeholder and partner_tel_placeholder, until a revision brings them; nothing an existing partner holds (tax id, address, city, phone, postcode, e-mail) is ever overwritten by an empty value. A code that resolves to a partner whose taxId or name differ is 422 party_code_tax_id_mismatch. A match whose address or phone differ produces warning party_details_differ_from_partner — customs receives the Freightools partner data, not your JSON. A partner shared with other Freightools users is never rewritten silently: non-additive differences produce warning partner_data_diverges.

3.4.1 Partner codes #

partnerCode is the party's id in your own system — the code your ERP or accounting system gives the customer, shipper or consignee. Freightools keeps it on the partner as its Internal Identity: the bridge between your system and Freightools.

• A new partner gets your code. A party that matches no Freightools partner is created as a new partner; with partnerCode given, its Internal Identity is that code.
• An existing partner without a code gets yours the first time a shipment names it. A partner that already has another code keeps it (partners are shared with other Freightools users and are only ever filled in, never overwritten); the response then carries warning partner_data_diverges.
• How a party is matched. We keep a copy of your environment's Freightools partners and match every party against it, in this order: partnerCode, then taxId, then the exact name (letters and digits only, any case) together with the country. The first rule that finds a partner decides. Several partners for one rule is 422 partner_ambiguous; a partnerCode that finds a partner with another taxId or name is 422 party_code_tax_id_mismatch.
• When a code starts to count. A code given to a new partner, filled into an existing partner by a shipment, or set on the portal's Partners page matches at once. A code changed directly in Freightools matches after the next sync of the partner list (every night, or Sync from Freightools on the Partners page); until then the partner is still found by its tax id or name.
• One code, one partner. Send the same code for the same partner every time. The portal's Partners page lists every partner with its code and Freightools ID, and operators can set or change a code there — it is written to Freightools, so it needs the environment's Freightools writes switched on, and a code another partner of the environment already has is refused.

"consignee": { "name": "Example Imports Ltd", "taxId": "510000052", "partnerCode": "EXT-CONS-0007", "address": "2 Example Street", "city": "Haifa", "country": "IL" }

3.5 Routing #

3.6 Carriage #

The whole carriage block may be left out: the carrier (air: the airline and the flight) and the dates come with the booking, in a later revision.

Vessel #

The vessel and the voyage are optional for every ocean variant, and a vessel never stops a shipment. When you leave them out, the shipping order is created without them and Freightools fills the vessel, the voyage and the manifest number from the carrier's manifest about 7 days before arrival. When you give them:

• IMO number (preferred). Seven digits, the last a check digit. The IMO is the key: we find the ship in Freightools by it and write it to the shipping order. A name that is not the ship's current or a former name is reported (vessel_conflict) and the IMO is used.
• Name only. Matched in our vessel book first (current and former names, so a renamed ship is still found; M/V, case and punctuation do not matter), then by exact name in Freightools. When the name matches one ship, the warning vessel_matched_by_name tells you which IMO was used.

"carriage": { "carrier": { "scac": "MSCU" }, "vessel": { "imo": "9001019", "name": "EXAMPLE STAR" }, "voyage": "001E", "eta": "2026-12-20" }

A renamed ship. Freightools may hold one vessel record per name under the same IMO. The shipping order gets the record that carries the name you sent; with the IMO alone, the record of the vessel's current name.

Dates already in the past. A pickupDate, cutoffDate, etd or eta that lies before today (Israel) when the shipment is written is stored as done: the shipping order gets the actual date and its stage moves to Pick Up, Cut Off, Departure or Arrival. Only dates this request sets are treated so, and a date of today is not. An arrival is stored only on an order that has its actual departure (from this request or already in Freightools).

Transshipment legs (carriage.transshipments[].vessel) take the same {imo, name}; a leg's IMO with a wrong check digit is reported as vessel_imo_invalid and ignored. The examples in §4 carry a vessel and a voyage because most bookings know them; both may be left out.

3.7 Master and house documents #

3.8 Commercial #

3.9 Cargo — FCL #

One entry per container. One CustomerShipmentGood is written per container with the ISO type always set explicitly (this prevents the Freightools fallback that produced customs error 4852 on a real shipment).

3.10 Cargo — LCL (variants L, C, K) #

LCL is modelled as package goods contained in a container good (VERIFIED on one Freightools LCL shipment). The shared container may come later: without cargo.container the customer shipment is written with its package goods alone, in one write (INFERRED), and when a later revision brings the container, the container good is added and the package goods already there are linked to it.

3.11 Cargo — Air #

Air shipments are created and validated completely. Whether the customs send can follow depends on your Freightools air process template: the readiness check air_manifest_path is blocked while the air process steps carry no customs integration tool (CR-AIR) and ok once they do. This is a fact of your Freightools setup, not a limitation of this API.

3.12 Goods lines (all variants) #

3.13 Duplicate and ambiguous inputs — which one wins #

4. Minimal examples (required fields only) #

"Required" here means required by the customs manifest, not required to create: the import examples 4.1–4.6 are small bodies whose manifest can be sent — each carries everything the readiness check manifest_data asks for, which is more than a shipment needs to be created. The smallest body that creates a shipment, and a revision that completes it, are in §3.1.1 (Start small).

All values below are fictional. The bodies are the files src/api/examples/*.json, reproduced verbatim — the same files /openapi.json carries as request examples and the tests validate against the schemas. Only public reference data is real: UN/LOCODEs, customs site codes, carrier SCACs and names, vessel names and IMO numbers, airline codes, HS codes, UNECE package codes and ISO 6346 size/type codes.

4.1 FCL, single container, dangerous goods #

{
  "shipmentRef": "EXAMPLE-FCL-001",
  "submitManifest": true,
  "service": {
    "mode": "ocean",
    "load": "FCL"
  },
  "parties": {
    "shipper": {
      "name": "Example Trading Co., Ltd",
      "address": "12 Harbour Road",
      "city": "Shenzhen",
      "country": "CN"
    },
    "consignee": {
      "name": "Example Imports Ltd",
      "taxId": "510000128",
      "address": "5 Industrial Street",
      "city": "Tel Aviv-Yafo",
      "country": "IL"
    }
  },
  "dgContact": {
    "company": "Example Forwarding Ltd",
    "person": "Operations desk",
    "phone": "+972500000000",
    "phoneType": "TE"
  },
  "routing": {
    "pol": "CNSZX"
  },
  "carriage": {
    "carrier": {
      "scac": "MSCU"
    },
    "vessel": {
      "imo": "9308584",
      "name": "MSC NINA F"
    },
    "voyage": "001E",
    "eta": "2026-12-20"
  },
  "master": {
    "document": {
      "number": "MSCUEX0000001"
    },
    "loadingPort": "CNSHK",
    "dischargeSite": "ILAST"
  },
  "house": {
    "document": {
      "number": "EXHBL0000001"
    }
  },
  "commercial": {
    "incoterm": "EXW"
  },
  "cargo": {
    "containers": [
      {
        "number": "EXMU0000015",
        "isoType": "45G1",
        "seal": "SEAL000001",
        "grossKg": 11500,
        "packages": {
          "count": 14,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "870310",
            "description": "ELECTRIC VEHICLES",
            "dangerous": {
              "unNumber": "3556",
              "class": "9"
            }
          }
        ]
      }
    ]
  }
}

routing.pod defaults to ILASH from ILAST (warning pod_defaulted_from_site); master.goodsReceiptSite defaults to the discharge site (warning goods_receipt_site_defaulted). dgContact is required because the goods line is dangerous and no tenant default DG contact is assumed.

4.2 FCL, seven 40'HC containers #

{
  "shipmentRef": "EXAMPLE-FCL-007",
  "submitManifest": true,
  "service": {
    "mode": "ocean",
    "load": "FCL"
  },
  "parties": {
    "shipper": {
      "name": "Example Panels S.A.",
      "address": "8 Port Avenue",
      "city": "Constanta",
      "country": "RO"
    },
    "consignee": {
      "name": "Example Imports Ltd",
      "taxId": "510000128",
      "address": "5 Industrial Street",
      "city": "Tel Aviv-Yafo",
      "country": "IL"
    }
  },
  "routing": {
    "pol": "ROCND"
  },
  "carriage": {
    "carrier": {
      "scac": "MSCU"
    },
    "vessel": {
      "imo": "9376141",
      "name": "MSC POLINA"
    },
    "voyage": "002W",
    "eta": "2026-12-22"
  },
  "master": {
    "document": {
      "number": "MSCUEX0000007",
      "type": "waybill"
    },
    "dischargeSite": "ILAST"
  },
  "house": {
    "document": {
      "number": "EXHBL0000007",
      "type": "telex"
    }
  },
  "commercial": {
    "incoterm": "FCA"
  },
  "cargo": {
    "containers": [
      {
        "number": "EXMU0001011",
        "isoType": "45G0",
        "seal": "SEAL000101",
        "grossKg": 27000,
        "packages": {
          "count": 16,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "441011",
            "description": "MELAMINE FACED CHIPBOARDS"
          }
        ]
      },
      {
        "number": "EXMU0001027",
        "isoType": "45G0",
        "seal": "SEAL000102",
        "grossKg": 27100,
        "packages": {
          "count": 16,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "441011",
            "description": "MELAMINE FACED CHIPBOARDS"
          }
        ]
      },
      {
        "number": "EXMU0001032",
        "isoType": "45G0",
        "seal": "SEAL000103",
        "grossKg": 27200,
        "packages": {
          "count": 16,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "441011",
            "description": "MELAMINE FACED CHIPBOARDS"
          }
        ]
      },
      {
        "number": "EXMU0001048",
        "isoType": "45G0",
        "seal": "SEAL000104",
        "grossKg": 27300,
        "packages": {
          "count": 16,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "441011",
            "description": "MELAMINE FACED CHIPBOARDS"
          }
        ]
      },
      {
        "number": "EXMU0001053",
        "isoType": "45G0",
        "seal": "SEAL000105",
        "grossKg": 27400,
        "packages": {
          "count": 16,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "441011",
            "description": "MELAMINE FACED CHIPBOARDS"
          }
        ]
      },
      {
        "number": "EXMU0001069",
        "isoType": "45G0",
        "seal": "SEAL000106",
        "grossKg": 27500,
        "packages": {
          "count": 16,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "441011",
            "description": "MELAMINE FACED CHIPBOARDS"
          }
        ]
      },
      {
        "number": "EXMU0001074",
        "isoType": "45G0",
        "seal": "SEAL000107",
        "grossKg": 27600,
        "packages": {
          "count": 16,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "441011",
            "description": "MELAMINE FACED CHIPBOARDS"
          }
        ]
      }
    ]
  }
}

No dgContact (no dangerous goods). master.loadingPort defaults to routing.pol (warning loading_port_defaulted_from_pol); master.document.type (waybill) and house.document.type (telex) are optional.

4.3 FCL, three 20' containers with class 8 dangerous goods #

{
  "shipmentRef": "EXAMPLE-FCL-DG",
  "submitManifest": true,
  "service": {
    "mode": "ocean",
    "load": "FCL"
  },
  "parties": {
    "shipper": {
      "name": "Example Batteries A.S.",
      "address": "3 Factory Road",
      "city": "Izmit",
      "country": "TR"
    },
    "consignee": {
      "name": "Example Imports Ltd",
      "taxId": "510000128",
      "address": "5 Industrial Street",
      "city": "Tel Aviv-Yafo",
      "country": "IL"
    }
  },
  "dgContact": {
    "company": "Example Forwarding Ltd",
    "person": "Operations desk",
    "phone": "+972500000000",
    "phoneType": "TE"
  },
  "routing": {
    "pol": "TRIZT"
  },
  "carriage": {
    "carrier": {
      "scac": "YMLU"
    },
    "vessel": {
      "imo": "9757230",
      "name": "YM WELLSPRING"
    },
    "voyage": "003E",
    "eta": "2026-12-18"
  },
  "master": {
    "document": {
      "number": "YMLUEX0000003"
    },
    "dischargeSite": "ILASH"
  },
  "house": {
    "document": {
      "number": "EXHBL0000003"
    }
  },
  "commercial": {
    "incoterm": "FOB"
  },
  "cargo": {
    "containers": [
      {
        "number": "EXMU0002018",
        "isoType": "22G0",
        "seal": "SEAL000201",
        "grossKg": 25400,
        "packages": {
          "count": 28,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "850710",
            "description": "BATTERIES, WET, FILLED WITH ACID, ELECTRIC STORAGE",
            "dangerous": {
              "unNumber": "2794",
              "class": "8"
            }
          }
        ]
      },
      {
        "number": "EXMU0002023",
        "isoType": "22G0",
        "seal": "SEAL000202",
        "grossKg": 25350,
        "packages": {
          "count": 28,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "850710",
            "description": "BATTERIES, WET, FILLED WITH ACID, ELECTRIC STORAGE",
            "dangerous": {
              "unNumber": "2794",
              "class": "8"
            }
          }
        ]
      },
      {
        "number": "EXMU0002039",
        "isoType": "22G0",
        "seal": "SEAL000203",
        "grossKg": 25300,
        "packages": {
          "count": 28,
          "type": "PK"
        },
        "goods": [
          {
            "hs": "850710",
            "description": "BATTERIES, WET, FILLED WITH ACID, ELECTRIC STORAGE",
            "dangerous": {
              "unNumber": "2794",
              "class": "8"
            }
          }
        ]
      }
    ]
  }
}

One dgContact covers every dangerous goods line of the shipment. Each container carries exactly one goods line (release 1: multi_hs_per_container_unsupported).

4.4 LCL under a line master #

{
  "shipmentRef": "EXAMPLE-LCL-001",
  "submitManifest": true,
  "service": {
    "mode": "ocean",
    "load": "LCL",
    "lcl": {
      "arrangement": "lineMaster"
    }
  },
  "parties": {
    "shipper": {
      "name": "Example Textiles SAS",
      "address": "21 Quai Example",
      "city": "Le Havre",
      "country": "FR"
    },
    "consignee": {
      "name": "Example Retail Ltd",
      "taxId": "510000342",
      "address": "9 Market Street",
      "city": "Netanya",
      "country": "IL"
    }
  },
  "routing": {
    "pol": "FRLEH"
  },
  "carriage": {
    "carrier": {
      "name": "MEDKON"
    },
    "vessel": {
      "imo": "9366457",
      "name": "MEDKON PERLA"
    },
    "voyage": "004E",
    "eta": "2026-12-15"
  },
  "master": {
    "document": {
      "number": "MEDKEX0000001"
    },
    "dischargeSite": "ILASH",
    "goodsReceiptSite": "ILBXQ"
  },
  "house": {
    "document": {
      "number": "EXHBL0000011",
      "type": "telex"
    }
  },
  "commercial": {
    "incoterm": "FOB"
  },
  "cargo": {
    "container": {
      "number": "EXMU0003014",
      "isoType": "45G1",
      "seal": "SEAL000301"
    },
    "packages": [
      {
        "count": 4,
        "type": "CT",
        "grossKg": 842.5,
        "goods": [
          {
            "hs": "620342",
            "description": "MEN'S COTTON TROUSERS"
          }
        ]
      }
    ]
  }
}

LCL package types are limited to CT, BX, CS, PK in release 1 (lcl_package_type_unsupported, CR-3): pallets (PX) are rejected until Freightools fixes its package-type codes. An LCL import's customs manifest needs master.goodsReceiptSite (a shipment created without it waits on manifest_data), and it should be a terminal: a port is accepted with warning lcl_receipt_site_must_be_terminal. The carrier is given by carrier.name here; a name is accepted when it resolves to exactly one Freightools carrier (carrier_ambiguous otherwise).

4.5 LCL co-load under another forwarder's house #

{
  "shipmentRef": "EXAMPLE-LCL-COLOAD",
  "submitManifest": true,
  "service": {
    "mode": "ocean",
    "load": "LCL",
    "lcl": {
      "arrangement": "coload"
    }
  },
  "parties": {
    "shipper": {
      "name": "Example Chemie GmbH",
      "address": "Hafenstrasse 1",
      "city": "Hamburg",
      "country": "DE"
    },
    "consignee": {
      "name": "Example Chemicals Ltd",
      "taxId": "510000565",
      "address": "14 Science Park",
      "city": "Haifa",
      "country": "IL"
    },
    "coloader": {
      "name": "Example Consolidation GmbH",
      "address": "Speicherstadt 2",
      "city": "Hamburg",
      "country": "DE"
    }
  },
  "dgContact": {
    "company": "Example Forwarding Ltd",
    "person": "Operations desk",
    "phone": "+972500000000",
    "phoneType": "TE"
  },
  "routing": {
    "pol": "DEHAM"
  },
  "carriage": {
    "eta": "2026-12-12"
  },
  "master": {
    "issuer": "coloader",
    "document": {
      "number": "EXCONSOL000001"
    },
    "dischargeSite": "ILASH",
    "goodsReceiptSite": "ILMTS"
  },
  "house": {
    "document": {
      "number": "EXHBL0000021"
    }
  },
  "commercial": {
    "incoterm": "CIF"
  },
  "cargo": {
    "container": {
      "number": "EXMU0004010",
      "isoType": "45G1"
    },
    "packages": [
      {
        "count": 2,
        "type": "CT",
        "grossKg": 1610.4,
        "cbm": 2.75,
        "marks": "EXAMPLE CHEMICALS 1-2",
        "goods": [
          {
            "hs": "330210",
            "description": "ODORIFEROUS MIXTURES",
            "dangerous": {
              "unNumber": "3082",
              "class": "9",
              "packingGroup": "III"
            }
          }
        ]
      }
    ]
  }
}

The master is the co-loader's house B/L (master.issuer: "coloader", parties.coloader required), so no carriage.carrier is given (the carrier, the vessel and the voyage are optional in every variant). Expected at customs: IL2 in house format, condition code 30.

4.6 Air import house #

{
  "shipmentRef": "EXAMPLE-AIR-001",
  "submitManifest": true,
  "service": {
    "mode": "air"
  },
  "parties": {
    "shipper": {
      "name": "Example Garments Co., Ltd",
      "address": "88 Textile Avenue",
      "city": "Shanghai",
      "country": "CN"
    },
    "consignee": {
      "name": "Example Fashion Ltd",
      "taxId": "510000789",
      "address": "15 Kinneret Street",
      "city": "Bnei Brak",
      "country": "IL"
    }
  },
  "routing": {
    "aol": "CNPVG",
    "aod": "ILTLV",
    "acceptancePlace": "SHANGHAI"
  },
  "carriage": {
    "airline": {
      "iata": "EY"
    },
    "flight": {
      "number": "123",
      "date": "2026-12-10"
    }
  },
  "master": {
    "document": {
      "number": "607-12345675"
    },
    "dischargeSite": "ILMMN"
  },
  "house": {
    "document": {
      "number": "EXHAWB000001"
    },
    "placeOfIssue": "SHANGHAI"
  },
  "commercial": {
    "incoterm": "FOB"
  },
  "cargo": {
    "pieces": [
      {
        "count": 33,
        "type": "CT",
        "grossKg": 285,
        "goods": [
          {
            "hs": "611595",
            "description": "KNITTED GARMENTS"
          }
        ]
      }
    ]
  }
}

Creates the CS/SO; the send stays blocked (readiness check air_manifest_path) while the Freightools air process steps carry no customs integration tool (CR-AIR). flight.date is the scheduled departure of the last leg before Israel, not the ETA.

4.7 Everything optional (FCL base of 4.1 with every optional member) #

This is also the OpenAPI example fcl-everything-optional (the file src/api/examples/fcl-everything-optional.json, reproduced here verbatim). Every optional value customs will not receive comes back in knownDeviations[]; options.dryRun: true runs the full validation and resolution without writing anything.

{
  "shipmentRef": "EXAMPLE-FCL-001",
  "submitManifest": true,
  "service": {
    "mode": "ocean",
    "load": "FCL",
    "scope": "door-port"
  },
  "parties": {
    "shipper": {
      "name": "Example Trading Co., Ltd",
      "address": "12 Harbour Road",
      "city": "Shenzhen",
      "country": "CN",
      "zip": "518000",
      "phone": "+8675500000000",
      "email": "export@example-trading.test",
      "partnerCode": "EXT-001",
      "taxId": "IDCN914403000001",
      "taxIdType": "company"
    },
    "consignee": {
      "name": "Example Imports Ltd",
      "taxId": "510000128",
      "address": "5 Industrial Street",
      "city": "Tel Aviv-Yafo",
      "country": "IL",
      "zip": "6701101",
      "phone": "+97230000000",
      "email": "imports@example-imports.test",
      "partnerCode": "EXI-001",
      "taxIdType": "company"
    },
    "notify": {
      "name": "Example Logistics Ltd",
      "address": "2 Port Road",
      "city": "Ashdod",
      "country": "IL",
      "phone": "+97280000000"
    },
    "customer": {
      "party": "consignee",
      "reference": "PO-2026-000123"
    },
    "customsBroker": {
      "name": "Example Customs Brokers Ltd",
      "taxId": "510000904",
      "address": "7 Customs Square",
      "city": "Ashdod",
      "country": "IL"
    }
  },
  "dgContact": {
    "company": "Example Forwarding Ltd",
    "person": "Operations desk",
    "phone": "+972500000000",
    "phoneType": "TE"
  },
  "routing": {
    "pol": "CNSZX",
    "pod": "ILASH",
    "placeOfReceipt": {
      "country": "CN",
      "city": "Dongguan",
      "zip": "523000",
      "address": "1 Example Factory Road"
    },
    "acceptancePlace": "DONGGUAN",
    "transshipmentPorts": [
      "SGSIN"
    ]
  },
  "carriage": {
    "carrier": {
      "scac": "MSCU",
      "name": "MSC"
    },
    "vessel": {
      "imo": "9308584",
      "name": "MSC NINA F"
    },
    "voyage": "001E",
    "eta": "2026-12-20",
    "etd": "2026-11-15",
    "booking": "EXBOOK000001",
    "transshipments": [
      {
        "port": "SGSIN",
        "vessel": {
          "imo": "9376141",
          "name": "MSC POLINA"
        },
        "voyage": "002W",
        "eta": "2026-12-05"
      }
    ]
  },
  "master": {
    "issuer": "carrier",
    "document": {
      "number": "MSCUEX0000001",
      "type": "original"
    },
    "loadingPort": "CNSHK",
    "dischargeSite": "ILAST",
    "goodsReceiptSite": "ILAST"
  },
  "house": {
    "document": {
      "number": "EXHBL0000001",
      "type": "original"
    },
    "placeOfIssue": "SHENZHEN"
  },
  "commercial": {
    "incoterm": "EXW",
    "freightTerms": "collect"
  },
  "cargo": {
    "containers": [
      {
        "number": "EXMU0000015",
        "isoType": "45G1",
        "seal": "SEAL000001",
        "grossKg": 11500,
        "cbm": 68,
        "tareKg": 3900,
        "soc": false,
        "reefer": {
          "active": false
        },
        "packages": {
          "count": 14,
          "type": "PK",
          "marks": "EXAMPLE IMPORTS 1-14"
        },
        "goods": [
          {
            "hs": "870310",
            "description": "ELECTRIC VEHICLES",
            "additionalHs": [
              "870380"
            ],
            "dangerous": {
              "unNumber": "3556",
              "class": "9",
              "packingGroup": "III",
              "properShippingName": "VEHICLE, LITHIUM ION BATTERY POWERED"
            },
            "vehicles": [
              {
                "vin": "1HGBH41JXMN109186"
              }
            ],
            "value": {
              "amount": 42000,
              "currency": "USD"
            }
          }
        ]
      }
    ],
    "totalCbm": 68
  },
  "options": {
    "dryRun": true
  }
}

The overrides master.transactionNumber, master.manifestNumber and house.transactionNumber are deliberately absent: in normal use leave them out — Freightools fills them through its customs lookup and the shipment waits for them (§9).

4.8 FCL export from Israel at booking (no numbers yet, incoterm derived) #

The Israeli exporter is the shipper (here with its tax id, which is optional); no Israeli customs fields; two 40' containers by type and weight only (the weight could be left out too). The trade is worked out from the ends (Haifa → Hamburg = export); "service": { …, "trade": "export" } would say the same. The incoterm is left out: the customer is the exporter (no party given on an export) and there is no delivery door, so it is derived as CFR (warning incoterm_derived). Container numbers, seals and the B/L numbers follow in a revision.

{
  "shipmentRef": "EXAMPLE-EXP-001",
  "service": {
    "mode": "ocean",
    "load": "FCL"
  },
  "parties": {
    "shipper": {
      "name": "Example Exports Ltd",
      "taxId": "510000128",
      "address": "5 Industrial Street",
      "city": "Haifa",
      "country": "IL"
    },
    "consignee": {
      "name": "Example Handel GmbH",
      "address": "1 Hafenstrasse",
      "city": "Hamburg",
      "country": "DE"
    },
    "customer": {
      "reference": "PO-EXAMPLE-77"
    }
  },
  "routing": {
    "pol": "ILHFA",
    "pod": "DEHAM"
  },
  "carriage": {
    "carrier": {
      "scac": "MSCU"
    },
    "etd": "2026-12-02",
    "eta": "2026-12-20",
    "booking": "EXBOOK0000001"
  },
  "cargo": {
    "containers": [
      {
        "isoType": "45G1",
        "grossKg": 12000,
        "goods": [
          {
            "description": "MACHINE PARTS"
          }
        ]
      },
      {
        "isoType": "45G1",
        "grossKg": 11500,
        "goods": [
          {
            "description": "MACHINE PARTS"
          }
        ]
      }
    ]
  }
}

4.9 FCL cross-trade, tracking off #

Neither end is in Israel, so no party has to be Israeli and there are no customs steps. tracking.active: false keeps Freightools tracking off for this shipment whatever the company default.

{
  "shipmentRef": "EXAMPLE-XT-001",
  "service": {
    "mode": "ocean",
    "load": "FCL"
  },
  "parties": {
    "shipper": {
      "name": "Example Trading Co., Ltd",
      "address": "12 Harbour Road",
      "city": "Shenzhen",
      "country": "CN"
    },
    "consignee": {
      "name": "Example Handel GmbH",
      "address": "1 Hafenstrasse",
      "city": "Hamburg",
      "country": "DE"
    },
    "customer": {
      "party": "consignee",
      "reference": "PO-EXAMPLE-88"
    }
  },
  "routing": {
    "pol": "CNSZX",
    "pod": "DEHAM"
  },
  "carriage": {
    "carrier": {
      "scac": "MSCU"
    },
    "eta": "2027-01-15"
  },
  "master": {
    "document": {
      "number": "MSCUEX0000205"
    }
  },
  "house": {
    "document": {
      "number": "EXHBL0000205",
      "type": "waybill"
    }
  },
  "commercial": {
    "incoterm": "FOB"
  },
  "cargo": {
    "containers": [
      {
        "number": "EXMU0000205",
        "isoType": "45G1",
        "seal": "SEAL000205",
        "grossKg": 9800,
        "packages": {
          "count": 40,
          "type": "CT"
        },
        "goods": [
          {
            "hs": "441011",
            "description": "PARTICLE BOARD"
          }
        ]
      }
    ]
  },
  "tracking": {
    "active": false
  }
}

5. Validation layers #

Validation runs completely before any Freightools write, stops at the first failing layer and returns every finding of that layer, so you fix one layer at a time with no partial side effects.

6. Error envelope, codes, warnings and known deviations #

6.1 Envelope #

Every non-2xx response is JSON:

{ "type": "consistency_error", "status": 422, "requestId": "req_01JC…", "shipmentRef": "EXAMPLE-FCL-001",
  "errors": [ { "path": "/cargo/containers/0/grossKg", "code": "weight_mismatch",
                "message": "Sum of goods weights (11200 kg) differs from the container gross weight (11500 kg)",
                "value": 11500, "hint": "Set grossKg to the sum of the goods lines, or correct the goods weights" } ],
  "warnings": [] }

path is a JSON Pointer into your body ('' = whole body). The same {path, code, message, value?, hint?} shape is used for errors[], warnings[] and knownDeviations[], in the API and in the portal. Quote requestId when you contact support.

Other statuses you will meet, same envelope: 401 (no/invalid token), 403 (scope or IP), 404 (unknown id, or the shipment belongs to another environment), 409 (transmission_exists, not_ready, decision_stale, illegal_transition), 412 (precondition_failed: If-Match mismatch), 413 (payload_too_large: body > 1 MiB), 429 (rate_limited, §13), 501 (preview_not_verified, not_implemented), 503 (gate_closed on the manual send/preview; tenant_not_configured when the environment has no license key).

6.2 Error codes by layer #

L0 — schema (400 validation_error)

L1 — codes and formats (400 validation_error)

The codes invalid_scac, invalid_airline_code, invalid_incoterm, invalid_flight_number, invalid_manifest_number, invalid_vin, invalid_shipment_ref and invalid_email exist in src/domain/codes.ts but nothing emits them: those shapes are enforced by the JSON schema at L0, so a bad SCAC, flight number, manifest number, VIN, shipmentRef (^[A-Za-z0-9._/-]{1,60}$) or e-mail comes back as invalid_format, and a bad incoterm as invalid_enum, each with the field's JSON Pointer.

L2 — reference resolution (422 resolution_error)

L3 — supported combination (422 unsupported)

L4 — cross-field (422 consistency_error)

L5 — tenant policy (422 policy_error)

6.3 Warnings #

Warnings never block; they tell you what was decided for you or what customs will not see.

6.4 Known deviations #

knownDeviations[] lists, per shipment, what customs does not receive today and the Freightools change request that would fix it. They are facts about Freightools' manifest generation, surfaced so nobody mistakes "stored" for "transmitted".

7. The shipment representation #

Returned by POST /v1/shipments, GET /v1/shipments/{id} and GET /v1/shipments/by-ref/{ref}. Since release 2 it also carries deliveryOrder: null, or the delivery-order details collected in the portal (details, a completeness list of checks with ok | missing | invalid | waiting | blocked and ready, updatedAt, updatedBy) — delivery orders are not transmitted to customs yet (phase 3). The portal renders exactly this object (both are built by buildShipmentView in src/domain/read-models.ts). The example below is the updated_not_retransmitted scenario that /openapi.json carries, produced by the serialiser itself (src/api/examples.ts → buildShipmentView), so it cannot drift from what the server returns.

{
  "id": "0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "shipmentRef": "EXAMPLE-FCL-001",
  "version": 7,
  "etag": "\"7\"",
  "service": {
    "mode": "ocean",
    "load": "FCL",
    "lclArrangement": null,
    "variant": "F"
  },
  "revisions": {
    "current": {
      "id": "11111111-2222-4333-8444-555555555552",
      "rev": 2,
      "kind": "data",
      "state": "applied",
      "dataHash": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6",
      "submitManifest": true,
      "receivedAt": "2026-10-25T09:00:00.000Z",
      "appliedAt": "2026-10-25T09:04:00.000Z",
      "changedPaths": [
        "/cargo/containers/0/grossKg"
      ],
      "submittedBy": {
        "type": "api_key",
        "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a"
      }
    },
    "lastApplied": {
      "id": "11111111-2222-4333-8444-555555555552",
      "rev": 2,
      "kind": "data",
      "state": "applied",
      "dataHash": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6",
      "submitManifest": true,
      "receivedAt": "2026-10-25T09:00:00.000Z",
      "appliedAt": "2026-10-25T09:04:00.000Z",
      "changedPaths": [
        "/cargo/containers/0/grossKg"
      ],
      "submittedBy": {
        "type": "api_key",
        "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a"
      }
    },
    "lastTransmitted": {
      "id": "11111111-2222-4333-8444-555555555551",
      "rev": 1,
      "kind": "data",
      "state": "applied",
      "dataHash": "3f1a0c6b9d2e8f7a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a",
      "submitManifest": true,
      "receivedAt": "2026-10-25T07:00:00.000Z",
      "appliedAt": "2026-10-25T07:04:00.000Z",
      "changedPaths": [],
      "submittedBy": {
        "type": "api_key",
        "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a"
      }
    },
    "inSync": false,
    "count": 2
  },
  "processing": {
    "state": "ready",
    "readiness": {
      "checks": [
        {
          "id": "manifest_number",
          "status": "waiting",
          "detail": "SO.ManifestNumber not filled by the Freightools customs lookup yet",
          "nextCheckAt": "2026-10-25T13:00:00.000Z"
        },
        {
          "id": "master_transaction",
          "status": "waiting",
          "detail": "SO.CarrierTransactionNumber (IL2) not filled yet"
        },
        {
          "id": "house_transaction",
          "status": "waiting",
          "detail": "CS.TransactionNumber (IL1) not filled yet"
        },
        {
          "id": "delivery_order",
          "status": "waiting",
          "detail": "SO.DeliveryOrderReceived is false (policy warn)"
        },
        {
          "id": "il1_unique_on_manifest",
          "status": "ok",
          "detail": "no live transmission uses this (manifest, IL1) pair"
        },
        {
          "id": "execution_step",
          "status": "ok",
          "detail": "execution step 800001 covers the container goods"
        },
        {
          "id": "iso_type_vs_master",
          "status": "unknown",
          "detail": "no public path to the carrier master (CR-18)"
        },
        {
          "id": "master_serials",
          "status": "unknown",
          "detail": "no public path to the carrier master (CR-18)"
        },
        {
          "id": "unloading_site_vs_master",
          "status": "unknown",
          "detail": "no public path to the carrier master (CR-18)"
        },
        {
          "id": "dg_flag_vs_master",
          "status": "unknown",
          "detail": "no public path to the carrier master (CR-18)"
        },
        {
          "id": "send_gates",
          "status": "ok",
          "detail": "customs send gates open"
        }
      ],
      "masterChecks": "not_available",
      "evaluatedAt": "2026-10-25T07:05:00.000Z"
    }
  },
  "manifest": {
    "state": "updated_not_retransmitted",
    "lastOutcome": "accepted",
    "autoSend": "disarmed",
    "submitManifest": true
  },
  "customs": {
    "manifestNumber": "123456",
    "houseTransactionNumber": "I000111A01",
    "masterTransactionNumber": "I000111A00",
    "consignmentSequence": 6501,
    "deliveryOrderReceivedAt": null
  },
  "freightools": {
    "environment": "test",
    "customerShipment": {
      "id": "400001",
      "code": "CS 030001"
    },
    "shippingOrder": {
      "id": "250001",
      "code": "SO 030001-2026 - O-I - FCL/FCL"
    },
    "manifestExecutionStepId": "800001"
  },
  "diff": [
    {
      "path": "/cargo/containers/0/grossKg",
      "from": 11500,
      "to": 11800
    }
  ],
  "actionsRequired": [
    {
      "id": "33333333-4444-4555-8666-777777777771",
      "type": "customs_decision",
      "state": "open",
      "revision": 2,
      "transmissionId": "22222222-3333-4444-8555-666666666661",
      "details": {},
      "options": [
        "keep",
        "correction",
        "cancel_and_resend",
        "cancel_only",
        "refer_to_operator"
      ],
      "createdAt": "2026-10-25T09:04:00.000Z",
      "closedAt": null
    }
  ],
  "transmissions": [
    {
      "id": "22222222-3333-4444-8555-666666666661",
      "kind": "initial",
      "state": "feedback_received",
      "revision": 1,
      "manifestNumber": "123456",
      "il1": "I000111A01",
      "consignmentSequence": 6501,
      "ftLogId": "9912001",
      "applicationId": "APP-77120",
      "sentAt": "2026-10-25T07:07:00.000Z",
      "feedbackAt": "2026-10-25T07:08:00.000Z",
      "outcome": {
        "statusCode": "1",
        "statusNameHe": "נקלט",
        "outcome": "accepted",
        "manifestState": "accepted_with_exceptions",
        "functionCode": "90",
        "manifestNumber": "123456",
        "il1": "I000111A01",
        "applicationId": "APP-77120",
        "errors": [
          {
            "code": "4852",
            "messageHe": "סוג מכולה אינו תואם למצהר הקו",
            "messageEn": "Container type differs from the carrier master",
            "severity": "warning",
            "path": "/cargo/containers/0/isoType",
            "hint": "Set isoType to the type on the carrier master (the master cannot be pre-checked, CR-18)",
            "itemSerial": "1"
          }
        ],
        "requiredDocuments": []
      },
      "confirmationId": null,
      "error": null
    }
  ],
  "decisions": [],
  "documents": {
    "count": 0,
    "items": [],
    "levelsNotice": "Uploading a document stores it here only. Customs transmission of documents is not available yet."
  },
  "knownDeviations": [
    {
      "path": "/house/document/number",
      "code": "HBL_NOT_EMITTED",
      "message": "The house B/L number is never emitted in the manifest (Freightools change request CR-1)",
      "variant": "F",
      "hint": "CR-1"
    },
    {
      "path": "/dgContact",
      "code": "DG_CONTACT_NOT_EMITTED",
      "message": "The DG contact (UNDGContact 37B, customs check 602) has no Freightools field and is not transmitted (Freightools change request CR-1b)",
      "variant": "F",
      "hint": "CR-1b"
    },
    {
      "path": "/cargo/containers/0/packages",
      "code": "TOTAL_PACKAGES_IS_CONTAINER_COUNT",
      "message": "For FCL Freightools sends the container count as total packages (146), not the package count (Freightools change request CR-2)",
      "variant": "F",
      "hint": "CR-2"
    }
  ],
  "warnings": [
    {
      "path": "/routing/pod",
      "code": "pod_defaulted_from_site",
      "message": "/routing/pod defaulted to \"ILASH\" from /master/dischargeSite",
      "value": "ILASH"
    },
    {
      "path": "/master/goodsReceiptSite",
      "code": "goods_receipt_site_defaulted",
      "message": "/master/goodsReceiptSite defaulted to \"ILAST\" from /master/dischargeSite",
      "value": "ILAST"
    }
  ],
  "timestamps": {
    "createdAt": "2026-10-25T07:00:00.000Z",
    "updatedAt": "2026-10-25T09:04:00.000Z"
  },
  "links": {
    "self": "/v1/shipments/0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
    "revisions": "/v1/shipments/0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b/revisions",
    "transmissions": "/v1/shipments/0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b/transmissions",
    "decisions": "/v1/shipments/0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b/manifest/decisions",
    "actions": "/v1/shipments/0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b/actions",
    "documents": "/v1/shipments/0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b/documents",
    "feedback": "/v1/shipments/0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b/feedback",
    "audit": "/v1/shipments/0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b/audit",
    "diff": "/v1/shipments/0f6c1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b/diff?from=transmitted&to=current"
  }
}

Freightools identifiers are strings (never do arithmetic on them). Times are ISO 8601 UTC. version is the ETag (also sent as the ETag header and echoed in etag): send it as If-Match: "7" on decisions and manual sends; a stale version is 412.

• revisions.current / lastApplied / lastTransmitted are revision summary objects (or null), not numbers; inSync is true when nothing has been transmitted yet or the current revision's dataHash equals the last transmitted one's.
• diff is the path-level diff between the last transmitted revision and the current one, as an array of {path, from, to}; it is null while nothing has been transmitted or the two are equal. For other comparisons use GET …/diff?from=&to= (transmitted | applied | <rev> → current | <rev>) or GET …/revisions/{rev} (diffFromPrevious).
• processing.readiness.checks[] entries are {id, status, detail, since?, nextCheckAt?} (§9.2); masterChecks is not_available today (CR-18).
• documents.items[] are the clean, non-deleted documents with the three fixed level texts (§12); levelsNotice is the fixed sentence.
• links are paths under /v1.

8. Other endpoints #

All under /v1, bearer-authenticated.

9. States — what each means for you #

Full vocabularies are in the OpenAPI document; the ones you must act on:

9.1 processing.state (current revision vs Freightools) #

9.2 Readiness checks (processing.readiness.checks[]) #

Each check is ok | waiting | unknown | blocked with a detail and, when waiting, nextCheckAt. Sea: manifest_number, master_transaction, house_transaction (filled by Freightools' customs lookup — the shipment waits; you are never asked for them), delivery_order (warning by default), il1_unique_on_manifest, execution_step, the four master checks (iso_type_vs_master, master_serials, unloading_site_vs_master, dg_flag_vs_master — always unknown: no public path to the carrier master), send_gates. Air: air_manifest_path (blocked until the Freightools air process steps carry a customs integration tool, CR-AIR), air_mawb_under_manifest (unknown). Imports also carry manifest_data: waiting while the shipment still lacks something the customs manifest needs — the consignee or its tax id, the shipper, an address of either (unless their Freightools partner already holds it), the customs discharge site (LCL: also the goods-receipt site), a weight, HS codes, the master or house document number; air: the airline and the flight; FCL: container numbers, seals or packages; LCL: the shared container or its number (the detail names them; send them in a revision, §3.1.1). An export or cross-trade has a single check, trade_scope (ok: no Israeli customs manifest), and is ready once applied. The watcher re-reads Freightools on a cadence from ETA−8 days to ETA+14 days; after that an operator_review action is opened. The shipment stays valid and is never asked to be resubmitted.

9.3 manifest.state and manifest.lastOutcome #

lastOutcome is the customs CargoStatus mapped to words (accepted, received_with_errors, split_merged, correction_pending_approval, cancelled, correction_approved, closed, held, rejected, correction_approved_manually, documents_required, correction_rejected, correction_withdrawn, other). Hebrew customs texts are returned verbatim beside the English mapping.

A transmission without feedback is never shown as accepted. waiting, awaiting_feedback and unknown_outcome are not success.

9.4 manifest.autoSend #

not_requested (submitManifest false) · armed (will send as soon as ready and the gates are open, and no transmission exists) · disarmed (a transmission exists; further sends need a decision).

10. Decisions — when and how #

After a transmission, any data change results in updated_not_retransmitted and an open action {type: "customs_decision", revision, transmission, options}. Nothing is retransmitted, corrected or cancelled at customs without your explicit decision, because a resend is a customs correction and a cancellation invalidates the house transaction number.

POST /v1/shipments/{id}/manifest/decisions
If-Match: "7"
{ "action": "correction", "revision": 2, "transmission": "<transmission id>", "note": "weight corrected per revised B/L" }

revision is the current revision's number or id; transmission may be omitted (the latest non-cancel transmission is assumed). The answer is 201 with the representation (decisions[] holds the row).

409 decision_stale: the revision is no longer current or the transmission is not the latest one — re-read the shipment and decide again. A new data revision while a decision executes finishes the running steps and opens a fresh decision. The portal posts to the same endpoint.

11. Reference endpoints #

Use them to populate pick-lists and to validate before you POST:

• GET /v1/reference/countries — ISO-2 codes Freightools knows (read once per environment, cached 24 h).
• GET /v1/reference/ports?q=ILASH / GET /v1/reference/airports?q=ILTLV — q must be a 5-character UN/LOCODE (free-text search is not available: Freightools resolves places by LOCODE only); zero or one record, resolved against your environment (sea ports and airports are different Freightools records even when the LOCODE is the same).
• GET /v1/reference/container-types — the curated ISO 6346 codes with the Freightools freight unit and the mixes each is allowed in.
• GET /v1/reference/package-types — UNECE Rec 21 codes with the LCL restriction flag.
• GET /v1/reference/incoterms — the codes your tenant has ids for.
• GET /v1/reference/il-sites — Israeli customs sites (sea and air) with your tenant's allow-list flag and the default commercial port each maps to.
• GET /v1/reference/document-types — the document types the upload accepts (§12).
• GET /v1/reference/states — every state vocabulary the API and the portal use (§9).

12. Documents #

Documents are uploaded separately from the shipment JSON:

POST /v1/shipments/{id}/documents     multipart/form-data: documentType, note? — then ONE file part named "file"
GET  /v1/shipments/{id}/documents

The documentType (and the optional note) fields must come before the file part: the upload is streamed and the row is reserved for that type before the first byte is stored, so a file part that arrives first is 400 ("documentType must precede the file part"). The answer is 201 with the document, or 200 with deduplicated: true when a clean document of the same type and sha256 already exists on the shipment. Too large is 413, a disallowed or mismatched content type 415.

Types: IL_287 cargo explanation letter, 707 B/L copy, 98 tally report (all VERIFIED from customs request 2570), 380 commercial invoice, 271 packing list (INFERRED), OTHER. Max 20 MiB (tenant-configurable). PDF, JPEG, PNG and XLSX are accepted; the type is sniffed from the file's bytes and must agree with the declared type and the extension, so a renamed executable is rejected. Files are virus-scanned when the deployment has a scanner (SCANNER=clamd; with SCANNER=none they are stored as clean at once); only clean files are listable or downloadable. Downloads are short-lived (5-minute) links with forced attachment disposition.

Every document has three independent levels, with fixed wording that the API and portal use verbatim:

1. Stored here — in our bucket, scanned, linked to the shipment and the revision at upload. Release 1.
2. Copied to Freightools (file) — pushed to the Freightools file store (SetFile). Not available yet: awaits Freightools documenting the mechanism (set E6).
3. Transmitted to customs — sent through AttachmentToManifest. Later phase.

Release 1 therefore states on every documents screen and in every documents response: "Uploading a document stores it here only. Customs transmission of documents is not available yet." A documents_required action (customs 2570) tells you which types customs asked for; satisfying it at customs is still a manual step in release 1.

13. Rate limits #

60 requests per minute per API key (a token bucket that refills continuously; unauthenticated callers share a bucket per IP). The service itself is paced against Freightools (one pacer per Freightools license key, about 4 calls/s), so the effective throughput of applies is bounded by Freightools, not by your POST rate. A refused request is 429 rate_limited with Retry-After (also retryAfterSeconds in the envelope); back off and retry — a retry of the same body is always safe (§2.2). Validation-only traffic (dryRun) counts against the same limit.

14. Webhooks (planned) #

Release 1 is poll-based: GET /v1/shipments?updatedSince=<ISO time> returns what changed. A POST /v1/webhooks registration (events: revision applied, readiness changed, transmission sent, feedback received, action opened) is planned and will be announced in this guide and the OpenAPI document before it is enabled. Do not depend on it yet.

15. Versioning and compatibility #

• The path prefix /v1 is the contract version. Additive changes (new optional fields, new warning or deviation codes, new states listed in the OpenAPI enums) happen inside /v1 without notice beyond the changelog; treat unknown codes as "unknown, show the message".
• Breaking changes (a field removed or re-typed, a state removed) go to /v2, with /v1 kept for at least six months.
• The OpenAPI document at /openapi.json is generated from the same schemas that validate your body, so it is always the authoritative shape.
• Freightools-dependent behaviour (marked FT-DEPENDENT above) may change when Freightools changes; such changes are documented in knownDeviations[] codes before the behaviour switches.

16. Checklist for a first integration #

1. Get an em_test_… key with shipments:read shipments:write from the portal (Settings → API keys).
2. POST /v1/shipments with example 4.1 and "options": { "dryRun": true }; read warnings[] and knownDeviations[].
3. Remove dryRun; expect 201. If your test environment's write gate is still closed the shipment is recorded and processing.state stays blocked (readiness send_gates) until your contact opens it — there is no error to handle.
4. Poll GET /v1/shipments/{id} until processing.state is waiting or ready; look at freightools.customerShipment.code in Freightools.
5. POST the same body again → 200 + Idempotent-Replayed: true. Change grossKg → 202, then look at revisions.current.changedPaths and GET …/revisions/2 (diff in the representation is only filled after a transmission).
6. Handle, in your UI, the states waiting, accepted_with_exceptions, received_with_errors, updated_not_retransmitted and the customs_decision action.