Ga naar inhoud
Cargofollow

Changelog

Elke wijziging in de API staat hier, nieuwste eerst. Abonneer je op de RSS-feed als je niet wilt wachten tot iets je opvalt.

Handtekeningen, integriteit en inspectielinks1.0.0-alpha.3

Handtekeningen met rollen en trust-levels, een narekenbare hash-keten per zending, en een publieke inspectielink met QR-code.

Nieuw

  • Handtekeningen — POST /v1/shipments/{id}/signatures legt een ondertekening of zegel vast per rol (consignor, carrier, consignee), met een methode, een vertrouwensniveau en bewijsmateriaal. Zie Concepten.
  • Integriteit — GET /v1/shipments/{id}/integrity rekent de hash-keten server-side na en antwoordt met head_hash en eventuele seq_gaps. GET /v1/shipments/{id}/events geeft de schakels zelf, zodat je het zelf kunt narekenen.
  • Organisatiebrede feed — GET /v1/events geeft de laatste 90 dagen aan gebeurtenissen over alle zendingen, met filters op type, shipment_id en since.
  • Inspectielinks — een token-URL met QR-code waarmee een handhaver de vrachtbrief inziet zonder account. Bezoeken komen terug als inspection.viewed.
  • Landvereisten — GET /v1/requirements geeft per corridor terug wat er geldt, met bron en verified_at per regel.

Gewijzigd

  • POST /v1/shipments/validate geeft regelbevindingen nu gescheiden terug in errors (blokkerend) en warnings (niet blokkerend), in plaats van alles als fout.

Bekend

  • De simulatieroutes (POST /v1/test/shipments/{id}/simulate) zijn nog niet uitgerold en antwoorden met 404. Zie Sandbox.
  • ades en qes worden geaccepteerd en bewaard, maar er is nog geen koppeling met een QTSP.

Zendingen, levenscyclus en documenten1.0.0-alpha.2

Brekende wijziging

De zending als resource, uitgifte die de vrachtbriefvelden bevriest, PDF-rendering en webhooks met ondertekende leveringen.

Nieuw

  • Zendingen — POST /v1/shipments, GET /v1/shipments/{id}, GET /v1/shipments met cursor-paginering en filters, en PATCH met regels per status.
  • Levenscyclus — POST /v1/shipments/{id}/issue en POST /v1/shipments/{id}/cancel, met een state machine die verboden overgangen weigert met invalid_transition.
  • Documenten — uploaden, opslaan met een sha256 en downloaden via een kortlevende gesigneerde URL. De vrachtbrief wordt bij elke versie opnieuw als PDF gerenderd.
  • Webhooks — POST /v1/webhook-endpoints met een whsec_-secret, ondertekende leveringen, acht pogingen in 24 uur en een leveringslog. Zie Webhooks.

Brekend

  • Uitgifte bevriest velden. Partijen, adressen, goederen, kosten, transport_type en provider liggen na issue vast. Een PATCH op zo’n veld geeft nu invalid_state in plaats van stilletjes te slagen. Verplaats wijzigingen naar vóór de uitgifte, of annuleer en maak opnieuw aan.
  • document_hash hoort bij de versie, niet bij de zending. Wie de hash op zendingniveau las, moet nu de huidige versie uitlezen.

Gewijzigd

  • Foutcodes zijn stabiel geworden en staan opgesomd op Foutcodes. Programmeer op code, nooit op title.

Eerste publieke sandbox1.0.0-alpha.1

De sandbox op api.eftisandbox.app gaat open, met API-keys, idempotentie en een OpenAPI-document.

Nieuw

  • Sandbox — https://api.eftisandbox.app is bereikbaar. Keys met de prefix sk_test_; test- en live-data staan volledig los. Zie Sandbox.
  • Authenticatie — API-keys met scopes, via Authorization: Bearer. Een ontbrekende scope geeft 403 insufficient_scope.
  • Idempotentie — Idempotency-Key op elke POST, 24 uur geldig per key en organisatie. Dezelfde key met dezelfde body geeft dezelfde respons, herkenbaar aan idempotent-replayed: true.
  • OpenAPI — het document staat op /openapi.json en is de bron voor de API-reference en voor de SDK’s.

Bekend

  • Productie (https://api.cargofollow.com) is nog niet opengesteld.
  • De API is alpha: er kan nog van alles veranderen. Wat wel en niet stabiel is, staat onderaan Changelog.

Waar je op kunt vertrouwen

Section titled “Waar je op kunt vertrouwen”

Deze dingen veranderen niet zonder een nieuwe versie in het pad:

  • Paden en methodes onder /v1.
  • Foutcodes in code. De title en detail eromheen mogen wel veranderen en zijn vertaalbaar.
  • Gebeurtenisnamen (shipment.issued, shipment.delivered, …). De catalogus staat op Gebeurtenissen.
  • Id-prefixen (shp_, ver_, evt_, doc_, sig_, whe_, …).
  • De berekening van de hash-keten. Wat je vandaag zelf narekent, klopt over vijf jaar nog.

Wat kan veranderen zonder aankondiging

Section titled “Wat kan veranderen zonder aankondiging”
  • Nieuwe optionele velden in responses. Negeer velden die je niet kent.
  • Nieuwe gebeurtenistypes. Een webhook-handler moet een onbekend type overslaan, niet crashen.
  • Nieuwe waarden in open enums, zoals package_type en provider.
  • Nieuwe regels in het regelregister. Die komen terug als warnings, en een nieuwe regel kan een bestaande corridor een bevinding opleveren die er gisteren niet was.
  • Nieuwe foutcodes. Behandel een onbekende code als de HTTP-status suggereert.

Hoe je een brekende wijziging merkt

Section titled “Hoe je een brekende wijziging merkt”

Brekende wijzigingen krijgen een eigen versie in het pad (/v2), en de oude versie blijft draaien. Je hoort het bovendien vooraf per e-mail op het adres van je organisatie. De entries hierboven die als brekend gemarkeerd staan, dateren van vóór de eerste stabiele versie — tijdens alpha kan het nog.