Skip to main content
HomeBlogGidsenHoe u API's voor zendingtracking gebruikt om proactieve bezorgmeldingen te versturen

Hoe u API's voor zendingtracking gebruikt om proactieve bezorgmeldingen te versturen

17TRACK

Om proactieve leveringsmeldingen met een API voor zendingtracking te verzenden, koppelt u elk pakket aan de bestelling, verwerkt u trackingupdates, vertaalt u die updates naar relevante gebeurtenissen voor de klant en activeert u berichten via uw e-mail-, sms- of app-meldingsservice. Plaats een duurzame wachtrij en controles op dubbele gebeurtenissen tussen binnenkomende trackinggegevens en uitgaande berichten, zodat herhaalde of vertraagde updates geen verwarrende meldingen opleveren.

Een API voor zendingtracking gebruiken om proactieve leveringsmeldingen te verzenden

Deze handleiding is bedoeld voor ontwikkelaars en e-commerceteams die deze workflow bouwen. Het doel is niet om elke scan van de vervoerder door te sturen, maar om klanten te laten weten wanneer er iets betekenisvols verandert, wat die verandering betekent en of ze actie moeten ondernemen.

Ontwerp de meldingsworkflow voordat u de API koppelt

Een API voor zendingtracking levert trackinginformatie; uw toepassing bepaalt hoe u die gebruikt. Behandel inzicht in de zending en communicatie met klanten als afzonderlijke verantwoordelijkheden, ook als de door u gekozen service beide biedt.

Een praktische architectuur bestaat uit zes fasen:

  1. Bestellingskoppeling: koppel indien nodig een trackingnummer en vervoerders-ID aan een intern zendingsrecord.
  2. Trackingregistratie: dien de zending in of registreer deze volgens de integratievereisten van de provider.
  3. Verwerking van updates: ontvang webhook-callbacks, haal updates op via API-verzoeken of combineer beide benaderingen.
  4. Gebeurtenisverwerking: valideer, normaliseer, verwijder dubbele gebeurtenissen en beoordeel binnenkomende gebeurtenissen.
  5. Meldingsbeslissing: bepaal of u een melding verzendt, met wie u contact opneemt en welk kanaal en sjabloon u gebruikt.
  6. Berichtlevering: verzend de melding en leg de reactie van de berichtenservice vast.

Bewaar contactgegevens van klanten in uw eigen bestel- of berichtensysteem, tenzij de integratie het daadwerkelijk vereist om deze te delen. Een trackingservice heeft doorgaans niet het e-mailadres van de klant nodig alleen om uw toepassing een trackinggebeurtenis aan een bestelling te laten koppelen.

1. Bevestig het integratiecontract

Controleer voordat u de ontvanger schrijft de documentatie van de provider op het gebied van authenticatie, zendingregistratie, identificatie van vervoerders, ondersteunde updatemethoden, antwoordindelingen, aanvraaglimieten en foutafhandeling. Controleer bij webhook-integraties ook hoe callbacks worden geauthenticeerd, welk antwoord de ontvangst bevestigt en hoe mislukte leveringen worden afgehandeld.

Begin voor een 17TRACK-implementatie met de 17TRACK Tracking API-pagina en de officiële API-documentatie. Gebruik het gedocumenteerde contract voor uw integratie en behandel de illustratieve veldnamen in deze handleiding niet als 17TRACK-aanvraag- of antwoordvelden. Bevestig vóór de implementatie de callbackconfiguratie, beveiligingsvereisten en accountspecifieke limieten.

Kies uw updatemethode volgens het integratiecontract:

  • Webhooks: gebruik callbacks wanneer deze worden ondersteund en geschikt zijn voor uw infrastructuur. Hiermee kan uw toepassing updates verwerken wanneer de provider ze verzendt, zonder dezelfde zending steeds opnieuw op te vragen.
  • Polling: haal trackinginformatie volgens een schema op wanneer callbacks niet beschikbaar of niet geschikt zijn. Houd het schema binnen de gedocumenteerde aanvraaglimieten.
  • Gecombineerde aanpak: gebruik callbacks voor normale verwerking en selectief ophalen via de API om zendingen te verifiëren waarvan de updates verouderd lijken, als de provider deze workflow ondersteunt.

Beloof klanten geen onmiddellijke meldingen alleen omdat u webhooks gebruikt. Uw toepassing kan een gebeurtenis van de vervoerder niet melden voordat de onderliggende trackinggegevens beschikbaar zijn.

2. Bouw een zendingsrecord dat echte bestellingen aankan

Gebruik een interne zendings-ID als primaire referentie, niet alleen het trackingnummer. Een bestelling kan meerdere pakketten bevatten en trackingnummers mogen niet voor altijd als wereldwijd uniek worden beschouwd.

Een nuttig intern record bevat:

  • Interne bestel-ID en zendings-ID.
  • Trackingnummer en vervoerders-ID, indien bekend.
  • De zendingsreferentie van de provider, indien verstrekt.
  • De huidige genormaliseerde status en de meest recente betekenisvolle gebeurtenis.
  • Het tijdstip van de gebeurtenis bij de vervoerder, inclusief tijdzone of offset indien beschikbaar.
  • Het tijdstip waarop uw systeem de update heeft ontvangen.
  • Een verwijzing naar de communicatievoorkeuren van de klant.
  • Meldingsgeschiedenis en eventuele actieve workflow voor uitzonderingen.

Bewaar het tijdstip van de gebeurtenis afzonderlijk van het ontvangsttijdstip. Een eerdere scan kan na een recentere scan binnenkomen. Als uw toepassing alleen op volgorde van binnenkomst sorteert, kan deze een geleverde zending ten onrechte weer op onderweg zetten.

Koppel meldingen bij gesplitste bestellingen aan het betreffende pakket. “Eén pakket van uw bestelling is aangekomen” is nauwkeuriger dan “Uw bestelling is aangekomen” wanneer een ander pakket nog onderweg is.

3. Koppel trackinggebeurtenissen aan klantbeslissingen

Beschrijving van vervoerders zijn operationele gegevens, geen kant-en-klare klantberichten. Bouw een normalisatielaag die de oorspronkelijke gebeurtenis bewaart en tegelijkertijd een interne categorie toewijst die uw meldingsregels kunnen begrijpen.

De volgende categorieën zijn voorgestelde toepassingsconcepten, geen universele API-statuswoordenschat:

Interne categorieMeldingsbeslissingGrenzen voor berichtgeving
Zendingsinformatie ontvangenVerzend alleen een voorbereidingsupdate als dat nuttig is.Wek niet de indruk dat de vervoerder het pakket fysiek in bezit heeft op basis van alleen het aanmaken van een label.
OnderwegOverweeg een melding bij de eerste betekenisvolle verplaatsing.Onderdruk routinematige scans bij faciliteiten tenzij deze de volgende stap van de klant veranderen.
Bezorging onderwegMeld dit wanneer een ondersteunde gebeurtenis deze status aangeeft.Zet de status niet om in een gegarandeerd bezorgtijdstip.
Bezorgpoging of ophalen vereistVerzend een melding waarop actie kan worden ondernomen.Neem deadlines of ophaalinstructies alleen op wanneer deze zijn geverifieerd.
Uitzondering bij bezorgingBeoordeel de oorzaak en of de klant actie moet ondernemen.Beschrijf niet elke uitzondering als een verloren pakket.
BezorgdVerzend een bevestiging op pakketniveau.Verzin geen ontvanger, bezorglocatie of bewijs van bezorging.

Behoud onzekerheid. Een niet-herkende gebeurtenis moet naar een beoordelings- of terugvalpad gaan in plaats van geforceerd te worden in de dichtstbijzijnde bekende categorie. Houd de onbewerkte beschrijving beschikbaar voor ondersteuningsmedewerkers bij het oplossen van problemen.

4. Ontvang updates zonder werk te verliezen of te dupliceren

Uw webhook-eindpunt moet het verzoek valideren, de geaccepteerde update duurzaam opslaan en de door de provider vereiste bevestiging retourneren. Genereer berichten asynchroon in plaats van tijdens het callbackverzoek te wachten op een e-mail- of sms-service.

Implementeer de gedocumenteerde callbackverificatiemethode van de provider. Verzin geen handtekeningheader en ga er niet van uit dat elke provider hetzelfde authenticatieschema gebruikt. Dwing ook HTTPS, limieten voor de aanvraaggrootte, payloadvalidatie en passende toegangscontroles af.

Een vereenvoudigde verwerkingsstroom ziet er als volgt uit. Dit zijn bewerkingen op toepassingsniveau, geen werkend SDK-voorbeeld:

callback ontvangen
  verzoek verifiëren met het gedocumenteerde mechanisme van de provider
  payload valideren
  geaccepteerde payload opslaan en verwerking atomair in de wachtrij plaatsen
  gedocumenteerde bevestiging retourneren

update uit de wachtrij verwerken
  interne zending zoeken
  relevante gebeurtenissen normaliseren
  reeds verwerkte gebeurtenissen negeren
  chronologie en statusovergang beoordelen
  meldingsopdracht aanmaken als het beleid dit toestaat
  status en opdracht samen vastleggen

meldingsopdracht verzenden
  voorkeuren van ontvanger en onderdrukkingsregels controleren
  bericht indienen bij de berichtenservice
  resultaat vastleggen en alleen indien gepast opnieuw proberen

De atomaire stappen zijn belangrijk. Als uw toepassing een statuswijziging opslaat maar crasht voordat de meldingsopdracht is aangemaakt, ontvangt de klant de melding mogelijk nooit. Een transactionele outbox is één ontwerpoptie: sla de statuswijziging en de openstaande opdracht op in dezelfde databasetransactie en laat vervolgens een worker de opdracht verzenden.

Behandel onbekende zendingsreferenties expliciet. Plaats ze in quarantaine voor onderzoek of reconciliatie in plaats van te raden welke klant een melding moet ontvangen.

5. Voeg bescherming tegen dubbele gebeurtenissen en chronologische controles toe

Ontwerp de ontvanger zo dat deze herhaalde callbacks en nieuwe pogingen van workers aankan. Gebruik bij voorkeur een stabiele gebeurtenis-ID van de provider wanneer deze is gedocumenteerd. Maak anders een deterministische vingerafdruk van geschikte velden, zoals de interne zendings-ID, gebeurteniscode, tijdstip van de gebeurtenis en locatie. Test die vingerafdruk met echte payloads voordat u erop vertrouwt.

Deduplicatie van gebeurtenissen en onderdrukking van meldingen lossen verschillende problemen op. Deduplicatie voorkomt dat dezelfde gebeurtenis tweemaal wordt verwerkt. Onderdrukking voorkomt dat meerdere afzonderlijke scans in wezen hetzelfde klantbericht genereren.

Definieer een meldingsidentiteit rond de bedrijfsmatige gebeurtenis. Een bezorgbevestiging kan de zendings-ID en de mijlpaal ‘bezorgd’ gebruiken. Voor een bezorgpoging is mogelijk een pogingsspecifieke identiteit nodig, omdat een latere poging een werkelijk nieuwe gebeurtenis kan zijn.

Vergelijk bij updates die niet in de juiste volgorde binnenkomen de tijdstempels van gebeurtenissen en beoordeel toegestane statusovergangen. Ga er niet van uit dat een callback alleen een nieuwe scan bevat; controleer of de gedocumenteerde structuur een afzonderlijke gebeurtenis, een momentopname of een geschiedenis weergeeft. Stuur tegenstrijdige updates naar reconciliatie in plaats van alle correcties stilzwijgend te verwijderen.

6. Schrijf berichten die uitleggen wat er daarna gebeurt

Elke melding moet het relevante pakket, de bevestigde wijziging en de volgende stap voor de klant vermelden. Voeg een beveiligde trackinglink en een herkenbare bestelreferentie toe. Vermijd het tonen van volledige adressen of onnodige persoonsgegevens in sms-berichten en meldingen op vergrendelschermen.

Bijvoorbeeld:

  • Bezorging onderweg: “Uw pakket voor bestelling {order_reference} is onderweg voor bezorging. Volg de voortgang hier: {tracking_link}.”
  • Bezorging geprobeerd: “De vervoerder heeft een bezorgpoging voor uw pakket gemeld. Bekijk de trackingpagina voor beschikbare vervolgstappen: {tracking_link}.”
  • Bezorgd: “De vervoerder heeft uw pakket voor bestelling {order_reference} als bezorgd gemarkeerd. Bekijk de beschikbare bezorggegevens: {tracking_link}.”

Vul placeholders alleen met gevalideerde gegevens. Als er een geschatte bezorgtijd beschikbaar en geschikt voor weergave is, label deze dan als schatting. Ontbreekt deze, laat haar dan weg in plaats van een datum te verzinnen.

Maak bij uitzonderingen onderscheid tussen een probleem met de zending en een taak voor de klant. Voor een verstoring kan alleen uitleg nodig zijn; een geverifieerd adresprobleem kan actie vereisen. Stuur klanten niet naar een betalings- of documentuploadpagina op basis van uitsluitend onbetrouwbare vrije tekst uit trackinginhoud.

Kies kanalen op basis van klantvoorkeuren, kanaalrechten, urgentie en toepasselijke regels. Controleer vereisten voor toestemming, afmelden en stille uren voor de rechtsgebieden en berichtkanalen die u gebruikt. Houd meldingen over de bezorgservice gescheiden van promotiecampagnes en ga er niet van uit dat voor beide dezelfde toestemmingen gelden.

7. Bepaal wat er gebeurt wanneer tracking stilvalt

Proactieve communicatie moet zowel ontbrekende voortgang als nieuwe gebeurtenissen omvatten, maar stilte alleen bewijst niet dat een zending vertraagd of verloren is.

Maak een regel voor verouderde tracking op basis van het serviceniveau, de route, de laatste betekenisvolle gebeurtenis en een eventuele ondersteunde bezorgschatting. Stel drempels vast op basis van uw operationele gegevens en ondersteuningsproces in plaats van één universele wachttijd op elke zending toe te passen.

Controleer wanneer die regel wordt geactiveerd op gemiste verwerking, stem waar mogelijk af met de trackingbron en bepaal of u een interne supporttaak moet openen. Als u de klant informeert, gebruik dan bewoordingen die weergeven wat u weet: “We hebben geen nieuwe trackingupdate ontvangen” verschilt van “Uw pakket is verloren.”

Wijs een verantwoordelijke toe aan onopgeloste uitzonderingen. Een meldingssysteem dat herhaaldelijk een probleem aankondigt zonder een route naar oplossing te creëren, kan de frustratie van klanten vergroten.

8. Test het volledige traject voordat u automatisch verzenden inschakelt

Voer de workflow eerst in schaduwmodus uit: verwerk echte of goedgekeurde testgebeurtenissen, genereer voorgestelde meldingen en controleer de resultaten zonder contact op te nemen met klanten.

  • Speel een identieke callback opnieuw af en bevestig dat deze geen nieuw bericht aanmaakt.
  • Verwerk een oudere gebeurtenis tijdens transport na een gebeurtenis ‘bezorgd’ en controleer de resulterende status.
  • Test ontbrekende tijdstempels, onbekende statussen en onjuist gevormde payloads.
  • Simuleer een databasefout vóór de bevestiging en een workerfout na persistentie.
  • Test time-outs bij berichten, inclusief een onzekere reactie waarbij de service het bericht mogelijk al heeft geaccepteerd.
  • Bevestig dat gesplitste zendingen pakket-specifieke formuleringen opleveren.
  • Controleer uitgeschreven ontvangers, ongeldige contactgegevens en de afhandeling van stille uren.
  • Controleer of trackinglinks geen bestelgegevens van een andere klant blootleggen.

Monitor geaccepteerde callbacks, verwerkingsfouten, wachtrijleeftijd, meldingsopdrachten, onderdrukking van dubbele meldingen en resultaten van berichten. Meet de verwerkingslatentie vanaf het ontvangsttijdstip van uw systeem afzonderlijk van de leeftijd van de gebeurtenis van de vervoerder. Dit onderscheid helpt bepalen of een trage melding werd veroorzaakt door de beschikbaarheid van upstreamgegevens of door uw eigen pijplijn.

Begin met een kleine reeks goed begrepen mijlpalen. Breid de regels pas uit nadat support- en operationele teams het erover eens zijn dat de berichten nauwkeurig, bruikbaar en de moeite van het ontvangen waard zijn.

Veelgestelde vragen

Verzendt een API voor zendingtracking automatisch e-mails of sms-berichten?

Niet noodzakelijk. Toegang tot trackinggegevens en klantberichten zijn afzonderlijke mogelijkheden. Controleer de gedocumenteerde reikwijdte van de service. In een aangepaste integratie kan uw toepassing trackingupdates verwerken en meldingen verzenden via een afzonderlijke berichtenservice.

Moet ik klanten informeren over elke tracking scan?

Meestal niet. Geef prioriteit aan betekenisvolle mijlpalen en gebeurtenissen die actie vereisen. Meerdere scans bij faciliteiten kunnen normaal transport vertegenwoordigen zonder te veranderen wat de klant moet weten. Bewaar de gedetailleerde geschiedenis op de trackingpagina.

Kan ik realtime leveringsmeldingen garanderen?

U kunt een verwerkingsdoel instellen en monitoren nadat uw systeem een update heeft ontvangen. U kunt niet garanderen wanneer een vervoerder een scan registreert of publiceert. Beschrijf de service in bewoordingen die deze afhankelijkheid weerspiegelen.

Hoe kan ik dubbele leveringsberichten voorkomen?

Gebruik permanente deduplicatie van gebeurtenissen, een afzonderlijke meldingsidentiteit voor elke bedrijfsmatige mijlpaal en transactionele aanmaak van opdrachten. Gebruik idempotentie als extra beveiliging wanneer uw berichtenservice dit ondersteunt. Alleen een controle op dubbele gebeurtenissen in het geheugen overleeft geen herstarts of meerdere workers.

Wat moet er gebeuren als de vervoerder een status ‘bezorgd’ corrigeert?

Bewaar beide gebeurtenissen en stem de status van de zending opnieuw af. Als de correctie grote gevolgen heeft voor de klant, stuur dan een duidelijke correctie of stuur de zaak volgens uw beleid naar support. Maak de status ‘bezorgd’ niet permanent onomkeerbaar alleen om de code eenvoudiger te maken.

Bronnen

De volgende officiële bronnen zijn de implementatiereferenties voor de hierboven besproken 17TRACK-integratie. Het interne schema, de meldingsregels en de verwerkingsstroom in deze handleiding zijn architectuuraanbevelingen en geen geciteerde API-contracten.

  • 17TRACK Tracking API — officieel startpunt voor het beoordelen van de API-integratie.
  • 17TRACK API-documentatie — referentie voor providerspecifieke aanvraagindelingen, authenticatie, trackingbewerkingen en integratievereisten.