Skip to content
Cargofollow

Changelog

Every change to the API is here, newest first. Subscribe to the RSS feed if you would rather not wait until something catches your eye.

Signatures, integrity and inspection links1.0.0-alpha.3

Signatures with roles and trust levels, a recomputable hash chain per shipment, and a public inspection link with a QR code.

Added

  • Signatures — POST /v1/shipments/{id}/signatures records a signature or seal per role (consignor, carrier, consignee), with a method, a trust level and evidence. See Concepts.
  • Integrity — GET /v1/shipments/{id}/integrity recomputes the hash chain server-side and answers with head_hash and any seq_gaps. GET /v1/shipments/{id}/events returns the links themselves, so you can recompute it yourself.
  • Organisation-wide feed — GET /v1/events returns the last 90 days of events across all shipments, with filters on type, shipment_id and since.
  • Inspection links — a token URL with a QR code that lets an enforcement officer see the consignment note without an account. Visits come back as inspection.viewed.
  • Country requirements — GET /v1/requirements returns what applies to a lane, with a source and a verified_at per rule.

Changed

  • POST /v1/shipments/validate now separates rule findings into errors (blocking) and warnings (non-blocking) instead of reporting everything as an error.

Known limitations

  • The simulation routes (POST /v1/test/shipments/{id}/simulate) are not rolled out yet and answer with 404. See Sandbox.
  • ades and qes are accepted and stored, but there is no QTSP integration yet.

Shipments, lifecycle and documents1.0.0-alpha.2

Breaking change

The shipment as a resource, issuing that freezes the consignment note fields, PDF rendering, and webhooks with signed deliveries.

Added

  • Shipments — POST /v1/shipments, GET /v1/shipments/{id}, GET /v1/shipments with cursor pagination and filters, and PATCH with rules per status.
  • Lifecycle — POST /v1/shipments/{id}/issue and POST /v1/shipments/{id}/cancel, with a state machine that refuses forbidden transitions with invalid_transition.
  • Documents — upload, storage with a sha256, and download through a short-lived signed URL. The consignment note is re-rendered as a PDF for every version.
  • Webhooks — POST /v1/webhook-endpoints with a whsec_ secret, signed deliveries, eight attempts over 24 hours and a delivery log. See Webhooks.

Breaking

  • Issuing freezes fields. Parties, addresses, goods, charges, transport_type and provider are fixed after issue. A PATCH on such a field now returns invalid_state instead of quietly succeeding. Move changes to before issuing, or cancel and create again.
  • document_hash belongs to the version, not to the shipment. Anyone reading the hash at shipment level has to read the current version instead.

Changed

  • Error codes are stable now and are listed on Error codes. Program against code, never against title.

First public sandbox1.0.0-alpha.1

The sandbox on api.eftisandbox.app opens, with API keys, idempotency and an OpenAPI document.

Added

  • Sandbox — https://api.eftisandbox.app is reachable. Keys carry the sk_test_ prefix; test and live data are fully separate. See Sandbox.
  • Authentication — API keys with scopes, through Authorization: Bearer. A missing scope returns 403 insufficient_scope.
  • Idempotency — Idempotency-Key on every POST, valid for 24 hours per key and organisation. The same key with the same body returns the same response, recognisable by idempotent-replayed: true.
  • OpenAPI — the document is served on /openapi.json and is the source for the API reference and for the SDKs.

Known limitations

  • Production (https://api.cargofollow.com) is not open yet.
  • The API is alpha: things can still change. What is and is not stable is listed at the bottom of Changelog.

What you can rely on

Section titled “What you can rely on”

These do not change without a new version in the path:

  • Paths and methods under /v1.
  • Error codes in code. The title and detail around them may change and are translatable.
  • Event names (shipment.issued, shipment.delivered, …). The catalogue is on Events.
  • Id prefixes (shp_, ver_, evt_, doc_, sig_, whe_, …).
  • The hash chain computation. What you recompute today still adds up in five years.

What may change without notice

Section titled “What may change without notice”
  • New optional fields in responses. Ignore fields you do not know.
  • New event types. A webhook handler must skip an unknown type, not crash.
  • New values in open enums, such as package_type and provider.
  • New rules in the rule register. They come back as warnings, and a new rule can give an existing lane a finding it did not have yesterday.
  • New error codes. Treat an unknown code the way its HTTP status suggests.

How you notice a breaking change

Section titled “How you notice a breaking change”

Breaking changes get their own version in the path (/v2), and the old version keeps running. You also hear about it beforehand by email at your organisation’s address. The entries above marked as breaking predate the first stable version — during alpha it is still allowed.