PortalData Export verstuurt verzendgegevens van nShift naar je systemen wanneer er gebeurtenissen plaatsvinden voor een zending of pakket. Je bepaalt welke gebeurtenissen worden verstuurd, wanneer ze worden verstuurd, wat het bestand bevat en waar het naartoe gaat.
Wanneer gebruik je dit?
Gebruik PortalData Export wanneer een extern systeem automatisch verzendgebeurtenissen van nShift moet ontvangen, zoals boekingen, trackingupdates van vervoerders of scans van Scan App.
Belangrijkste begrippen
-
Export setting: de configuratie die bepaalt welke gebeurtenissen worden geëxporteerd, wanneer ze worden verstuurd, wat het bestand bevat en waar het naartoe gaat.
-
Event origin: de bron van een gebeurtenis, zoals het boekingssysteem, een vervoerder of de nShift Scan App.
-
Installation: de nShift-installatie waarvan de zendingen worden geëxporteerd.
-
Out-profile: de bestemming waarnaar bestanden worden doorgestuurd, zoals een FTP-server, een HTTP-endpoint, e-mail of sms.
- Batching: gebeurtenissen verzamelen en volgens een schema gezamenlijk versturen in plaats van één bestand per gebeurtenis te versturen.
PortalData Export aanvragen
Vraag PortalData Export aan zodat nShift een exportinstelling kan aanmaken die verzendgebeurtenissen naar je systeem verstuurt.
Belangrijk:
Alleen medewerkers van nShift kunnen exportinstellingen aanmaken en bewerken. Dien een verzoek in bij de klantenservice om een exportinstelling te laten aanmaken.
Stappen
- Bepaal welke gebeurtenissen je wilt exporteren. Zie Gebeurtenisbronnen, Gebeurtenistypen en Filters.
- Bepaal wanneer bestanden worden verstuurd. Zie Verzendmomenten.
- Bepaal wat het bestand moet bevatten. Zie Bestandsopties en Aanvullende gegevens.
- Bepaal waar de bestanden naartoe worden verstuurd. Zie Bestemmingstypen en Verzendmethoden.
- Dien een verzoek in bij de klantenservice met de gegevens uit de tabel Benodigde aanvraaggegevens.
nShift maakt de exportinstelling aan en activeert deze zodra je bevestigt dat de bestemming klaar is om bestanden te ontvangen. Er wordt niets geëxporteerd totdat de instelling actief is.
Benodigde gegevens voor de configuratie
Raadpleeg Standard Portal Export configureren voor de gegevens en velden in het standaardbestandsformaat van nShift.
Gegevens die je bij je aanvraag aan de klantenservice van nShift moet verstrekken:
| Onderdeel | Wat moet je opgeven? |
|---|---|
| Gebruikersnaam | Je gebruikersnaam voor nShift Portal of de UUID van het bedrijf |
| Installaties | De ID van elke installatie waarvan gegevens moeten worden geëxporteerd |
| Gebeurtenissen | De gebeurtenisbronnen en gebeurtenistypen die een bestand activeren |
| Vervoerders en diensten | Optioneel. De vervoerders of diensten die moeten worden opgenomen of uitgesloten |
| Timing | Direct per gebeurtenis, of op vaste tijdstippen of met een vast interval, en je tijdzone |
| Bestandsformaat | Het bestandstype en een voorbeeld van de indeling of een XSLT-bestand als je dat hebt, of een verzoek om onbewerkte XML |
| Bestandsnaam | De naamgevingsconventie als de bestanden specifieke namen moeten hebben |
| Bestemming | Het bestemmingstype en de bijbehorende gegevens. Voeg voor e-mail, sms en bestandsuitvoer een voorbeeld van de sjabloon toe. Voeg voor HTTP de API-documentatie toe, een voorbeeld van een POST-verzoek met headers en payload, het endpoint en de authenticatiemethode: API-sleutel of token, OAuth met client-ID en clientgeheim of JSON Web Token, of basisverificatie |
Gebeurtenisbronnen
Gebeurtenisbronnen bepalen welk soort gebeurtenis een bestand activeert. Je kunt meerdere bronnen selecteren.
| Waarde | Betekenis |
|---|---|
| ShipmentInsert | Eén export wanneer een zending wordt aangemaakt |
| BookAndPrint | Gebeurtenissen uit het boekingssysteem, inclusief updates van zendingen na het indienen. Dit is de standaardinstelling |
| CarrierData | Trackinggebeurtenissen ontvangen van vervoerders |
| ScanApp | Scans uitgevoerd met de nShift Scan App. Vereist om te kunnen filteren op action center |
| ClientData | Gebeurtenissen die door de klant worden aangeleverd |
Belangrijk:
ShipmentInsert en BookAndPrint kunnen niet tegelijkertijd worden geselecteerd. Een ShipmentInsert-gebeurtenis bevat de boekingsgebeurtenissen al, waardoor de boeking anders twee keer zou worden geëxporteerd.
Gebeurtenistypen
Gebeurtenistypen beperken de export tot bepaalde soorten gebeurtenissen. Een gebeurtenis wordt geëxporteerd als deze overeenkomt met een van de geselecteerde typen. Als je geen typen selecteert, worden alle typen geëxporteerd.
| Waarde | Betekenis |
|---|---|
| TrackAndTrace | Trackingstatusgebeurtenissen |
| Measurement | Gebeurtenissen met gewicht of afmetingen |
| Price | Prijsgebeurtenissen |
Filters
Met filters bepaal je welke gebeurtenissen worden geëxporteerd.
| Filter | Wat wordt beperkt? |
|---|---|
| Installations | Vereist voor klantbedrijven. Alleen zendingen van de geselecteerde installaties worden geëxporteerd |
| Event max age | Gebeurtenissen die ouder zijn dan dit aantal dagen worden niet geëxporteerd. De standaardwaarde is 365 dagen. Niet van toepassing op ShipmentInsert |
| Actors | Afzenderaccounts binnen de geselecteerde installaties |
| Carriers | De vervoerders die moeten worden opgenomen of uitgesloten |
| Services | De diensten van de geselecteerde vervoerders die moeten worden opgenomen of uitgesloten. Worden in de exportinstelling weergegeven als Products |
| Action centers | Action centers van Scan App. Alleen beschikbaar met de gebeurtenisbron ScanApp |
| Orphan shipments | Scans die niet aan een zending konden worden gekoppeld |
| Normalized categories and statuses | Alleen gebeurtenissen met deze genormaliseerde waarden, bijvoorbeeld alle afgeleverde zendingen bij verschillende vervoerders. De categorieën zijn System, In transit, Delivered, Information, Carrier exception, Receiver exception en Sender exception |
| Status kind and status text | Gebeurtenissen die overeenkomen op basis van een numerieke gebeurtenistype-ID of een exacte, hoofdlettergevoelige gebeurtenisnaam, per gebeurtenisbron |
| Advanced filtering | Een aangepast JavaScript-filter voor vereisten die niet met de andere filters kunnen worden ingesteld. nShift schrijft dit filter. Wordt niet toegepast op ShipmentInsert |
Voor Actors, Carriers en Services keert de schakelaar Exclude de selectie om, zodat alles behalve de geselecteerde items wordt geëxporteerd.
Verzendmomenten
De instellingen voor verzendmomenten bepalen wanneer bestanden worden verstuurd.
| Optie | Betekenis |
|---|---|
| Immediately | Eén bestand per gebeurtenis, verstuurd zodra de gebeurtenis plaatsvindt. Dit is de standaardinstelling |
| At fixed times | Gebeurtenissen worden verzameld en gezamenlijk verstuurd op vaste tijdstippen van de dag in je tijdzone, bijvoorbeeld om 06:00 en 18:30 |
| At fixed intervals | Gebeurtenissen worden verzameld en gezamenlijk verstuurd met een vast interval van een bepaald aantal minuten |
| Grouped | Gebeurtenissen worden verzameld, gegroepeerd op basis van een sleutel zoals een klantreferentie en volgens een schema verstuurd als één bestand per groep. nShift configureert de groepering met aangepast JavaScript |
Bestemmingstypen
| Type | Opmerkingen |
|---|---|
| Alleen platte tekst | |
| SMS | Berichten van meer dan 160 tekens worden als een extra sms verstuurd |
| FTP | Zowel FTP als SFTP worden ondersteund. Bestanden kunnen in het standaardformaat, een aangepast formaat of onbewerkt worden verstuurd |
| HTTP | POST-verzoeken naar één endpoint. Authenticatie kan plaatsvinden via basisverificatie, een bearer-token of een aangepaste header met een sleutel en waarde |
Verzendmethoden
| Methode | Betekenis |
|---|---|
| Gateway | Elk bestand wordt direct naar elk geselecteerd out-profile verstuurd. Dit is de standaardinstelling |
| JobManager | Bestanden worden in een wachtrij geplaatst en per out-profile in jobs verstuurd |
Opmerking: Out-profiles voor e-mail en sms werken niet met onbewerkte XML of met JobManager.
Bestandsopties
| Optie | Betekenis |
|---|---|
| Standard format | Een CSV- of XML-bestand in de standaardindeling van nShift. Zie Standard Portal Export configureren |
| Customized format | Een bestand dat wordt gegenereerd met een XSLT-bestand waarin de indeling is gedefinieerd |
| Unprocessed XML | De export-XML van nShift wordt ongewijzigd verstuurd, zonder transformatie |
| File type | xml, json, csv, edi of lst. Moet overeenkomen met het formaat dat de transformatie genereert |
| File name | Een optionele naamgevingssjabloon die is opgebouwd uit tokens zoals de instellings-ID, de barcode van de gebeurtenis of de datum. De sjabloon moet de bestandsextensie bevatten. Als het veld leeg is, wordt een unieke naam gegenereerd |
| Compress files | Elk bestand wordt gecomprimeerd tot een ZIP-bestand. Alleen beschikbaar bij gebruik van een transformatie |
| Single export | None exporteert elke overeenkomende gebeurtenis. Shipment verstuurt alleen het eerste bestand per zending. EventLevel verstuurt alleen het eerste bestand per pakket, of per zending voor gebeurtenissen op zendingsniveau |
| Units | Lengte, volume en gewicht worden omgerekend naar de gewenste eenheden, met 0 tot 4 decimalen. Intern worden waarden opgeslagen in millimeters, grammen en kubieke millimeters |
Aanvullende gegevens
Met aanvullende gegevens wordt extra informatie toegevoegd aan de export-XML voordat deze wordt getransformeerd.
| Waarde | Wat wordt toegevoegd? |
|---|---|
| Driver | De naam, het e-mailadres en het telefoonnummer van de chauffeur bij de gebeurtenis |
| Base64Signature | De afbeelding van de handtekening, ingesloten als base64. De link is altijd aanwezig |
| Base64Image | De afbeelding van de gebeurtenis, bijvoorbeeld een foto als afleverbewijs, ingesloten als base64 |
| PriceCalculation | Het volledige document met de prijsberekening van de vervoerder |
| ShipmentDetails | Extra verzamelingen met zendingsgegevens |
| ReturnLabelUrl | Openbare URL's en documenttypen voor zendings- en pakketdocumenten, zoals retourlabels |
| Articles | Artikellijsten op zendings- en pakketniveau |
Opmerking: Base64-afbeeldingen en handtekeningen maken bestanden aanzienlijk groter. Vraag deze alleen aan wanneer het ontvangende systeem ze nodig heeft.