Overslaan naar inhoud
  • Er zijn geen suggesties want het zoekveld is leeg.

Webhook

Statusberichten en PDF-documenten vanuit Stratech Shipment

  1. inleiding:

    Stratech Shipment kan na het versturen van een douaneaangifte automatisch statusinformatie terugsturen naar jouw ERP-systeem.   
    Dit gebeurt via zogeheten statusberichten.
    Het eerste statusbericht wordt verstuurd zodra de aangifte naar de Douane is verzonden. 
    Daarna worden extra statusberichten verstuurd zodra de status van de aangifte wijzigt.



    Voorbeeldflow van een DMS Uitvoeraangifte:

    - Een dataset wordt vanuit een bronsysteem, naar Shipment verzonden.
    - Wanneer deze vervolgens de aangifte naar de Douane verzonden wordt, zal Shipment op basis van wat de Douane afgeeft aan statusupdates, deze ook weer terug-communiceren naar het bronsysteem.
    - Wanneer de Douane een statusupdate heeft afgegeven, waarbij een documentafgifte hoort, kan hierna middels GET opdracht, op basis van een DocumentId, de PDF opgehaald worden wanneer gewenst.

    Voorbeeld van de statusberichten bij een DMS Uitvoeraangifte:


    Deze functionaliteit is beschikbaar in Shipment Enterprise en Shipment Business. 




























     

  2. Status callback URL configureren  
    Om statusberichten te ontvangen, moet jouw ERP een endpoint beschikbaar stellen waar Stratech de berichten naartoe kan sturen.  

    Je richt dit in via de Shipment omgeving.

    Volg hiervoor de onderstaande stappen: 
    1.   Log in op de Shipment omgeving.   
    2.   Ga naar Instellingen, ERP Koppeling.   
    3.   Vul bij Status callback URL de URL van jouw ERP-endpoint in.   
    4.   Klik op Toepassen.

    Vanaf dat moment stuurt Shipment statusupdates automatisch naar de opgegeven URL.

  3. Beveiliging  

    Voor het beveiligen van deze verbinding ondersteunt Stratech Shipment twee instellingen

    1. Basic authentication met een gebruikersnaam en wachtwoord die Stratech gebruikt om verbinding te maken met jouw endpoint. 
    2.  Certificaatvalidatie.
      -  Wanneer certificaatvalidatie op Ja staat, controleert Stratech of op het endpoint een vertrouwd SSL-certificaat aanwezig is.   
      -  Als certificaatvalidatie op Nee staat, kan Stratech ook verbinding maken met een self-signed certificaat.






  4. Berichtmethode  

    Statusberichten vanuit Stratech Shipment worden altijd verzonden met de POST-methode.   
    Andere methoden worden niet ondersteund.

    1. Veldspecificaties  
      De specificaties van de velden in statusberichten zijn te bekijken op de Swagger-pagina van jouw Shipment omgeving.   

      De URL van deze Swagger-pagina is af te leiden uit het hoofdstuk URL set-up van de douane API.   
      Binnen Swagger kun je via Importdossier en vervolgens het tabblad Callbacks het volledige schema van de statusberichten bekijken. 






    2. Voorbeeldbericht en functionele toelichting:

      Een DMS uitvoeraangifte welke een Status 3 heeft gekregen.

      {
        "ApplicationReferenceId": "Test_EOG (18)_1782127036",
        "DossierNumber": "Test_EOG (18)_1782127036",
        "Status": 3,
        "SubmissionType": 8,
        "DeclarationType": 2,
        "Frn": "260622-1104264",
        "Mrn": "26NL062211172098E8",
        "Arc": null,
        "ConsignmentId": null,
        "StatusChangeTime": "2026-06-22T11:17:25+00:00"
      }

      ApplicationReferenceId = API ID
      DossierNumber = Dossiernaam in Shipment
      Status = 3 = Cleared
      SubmissionType = 8 = IE515 - The export declaration
      DeclarationType = 2 = DmsExport 
      Frn = Aangiftenummer
      Mrn = Mrn afgegeven door de Douane
      Arc = Arc nummer in geval van EMCS
      ConsignmentId = ID Deelzending
      StatusChangeTime" = Datumtijd van update

       

    3. Best practices voor statusberichten  

      Bij het implementeren van statusberichten kun je ervoor kiezen om alle berichten in jouw ERP te verwerken, maar je kunt ook alleen de statussen opnemen die voor jouw organisatie relevant zijn.

      De meest voorkomende toepassing is het automatisch verwerken van MRN-informatie in het ERP.   
      Voor een MRN-upload volstaat het meestal om de onderstaande statussen te verwerken.
       -   DMS 4.0 statuscode 3 voor definitieve vrijgave.   
       -   DMS 4.0 statuscode 4 voor voorlopige vrijgave.   
       -   DMS 4.1 statuscode 5 voor vrijgave voor IIAA. 

      In deze berichten staan de douanegoedkeuringen en het door de Douane toegekende MRN.   
      Dit MRN kan worden gebruikt in de douaneadministratie van het ERP.   
      Voor exportaangiften kan aanvullend worden overwogen om ook status 28 te verwerken.   
      Status 28 staat voor exit of goods of confirmation of exit.   

      Voor DMS 4.1 declaranten geldt dat de MRN-administratie compleet aanwezig moet zijn in het ERP voor de verplichte audit file
      Je kunt ook waarschuwingen of signalen laten aanmaken in het ERP wanneer er een procesblokkerend douanebericht binnenkomt.   
      Daarvoor kun je overwegen om extra statussen te verwerken.
      -   Status 23 voor foutmeldingen op aangiften.   
       -  Status 24 en 25 voor bescheidcontrole en fysieke controles. 

      Met deze berichten kun je medewerkers binnen jouw organisatie ook buiten Stratech Shipment om attenderen op een benodigde actie.   

      Deze berichten zijn optioneel, omdat ze ook zichtbaar zijn in Shipment zelf.

  5. Documentberichten en PDF ophalen

    De API biedt de mogelijkheid om documenten uit Shipment als PDF-bestand op te halen middels een zogenaamde Document Status callback.   
    Hiermee kun je documenten uit Shipment automatisch opslaan in jouw eigen netwerk of systeem.   
    Het gaat hierbij om documenten die door Shipment worden gegenereerd na goedkeuring van de Douane. 

    Voorbeelden hiervan zijn:  
    -   Wegvoering- of uitvoerdocumenten.  
    -   Uitnodiging tot Betaling documenten.

    1. Endpoint inrichten  
      Voor documentberichten richt je in Shipment een aparte Document Callback URL in.   
      Dit doe je in het scherm Instellingen, Import, ERP Koppeling.   
      De werking van deze velden is hetzelfde als bij de statusafhandeling uit hoofdstuk 1 van dit artikel.










    2. Voorbeeld van een documentbericht:

      Als na het verwerken van een douanebericht een document wordt aangemaakt in Shipment, dan verstuurt Shipment een event naar de ingestelde callback URL.   
      Dat bericht bevat meerdere velden waarmee jouw systeem het document kan identificeren en ophalen:

      {
        "DocumentId": "5456fee3-b7fa-4adf-9938-9137c474b61b",
        "ApiReference": "240510-0702523",
        "tenantId": "https://JansenLogistiekBV.shipment-stratech.nl",
        "requisiteDocumentId": 0,
        "documentSource": "Dms",
        "documentContentType": "Original",
        "occurredOn": "2024-05-10T07:11:40.6522127+00:00"
      }


      DocumentId.  = ID van het document om de PDF op te halen.   
      ApiReference. Dit is het  local reference number/LRN van de aangifte.  
      TenantId. Dit is de URL van jouw Shipment omgeving.   
      documentSource. Dit geeft aan om welk soort aangifte het gaat, bijvoorbeeld DMS.   
      documentContentType. Dit geeft het type document aan.   
      occurredOn. Dit is het tijdstip waarop het event is verstuurd.

      Het element DocumentId is het belangrijkste veld in dit bericht, zonder dit ID kun je de PDF niet ophalen.
      De waarde van ApiReference komt overeen met het Frn-element uit de statusberichten.   
      Deze waarde wordt door Stratech gegenereerd zodra een aangifte wordt verzonden.

      Voor documentContentType worden in het document voorbeelden genoemd zoals: 

      -   Original voor een wegvoeringdocument bij import of een uitvoerdocument bij export.   
      -   PaymentRequestFinal voor een definitieve UTB.

    3. PDF ophalen via GET 

      Nadat jouw systeem een documentbericht heeft ontvangen, moet nog een extra API-aanroep worden gedaan om het document daadwerkelijk op te halen.   

      Dit gebeurt via een GET-aanroep naar de Shipment omgeving.   
      In deze aanroep gebruik je het DocumentId uit het documentbericht.

      De URL-opbouw is als volgt:  
      /erpservices/Documents?id={DocumentId}

      Een voorbeeld van een volledige URL is:  
      https://JansenLogistiekBV.shipment-stratech.nl/erpservices/Documents?id=5456fee3-b7fa-4adf-9938-9137c474b61b

      Deze GET-aanroep moet voorzien zijn van een Bearer token.   
      De authenticatie werkt hetzelfde als bij de POST-aanroepen van aangiftedata in de douane API.

      • Voorbeeld respons  

        De respons van deze GET-aanroep levert het document als PDF op.   
        Deze PDF kan daarna automatisch worden opgeslagen of verwerkt in jouw eigen systeem.

      • Bestandsnamen van PDF-documenten  

        • Bij gebruik van Document GET hebben de PDF-bestanden een vast bestandsnaamformaat.   
          Deze bestandsnamen zijn niet aanpasbaar.   

          Wanneer beschikbaar bevatten deze bestandsnamen altijd informatie zoals het soort document, het MRN-nummer, het aangiftenummer of FRN-nummer en het ARC-nummer. 

          Voorbeelden die in de documentatie worden genoemd zijn:  

          -   DMS 429-CLE 25NL3VBAZBZOD2DDR2 240408-1009319.pdf. Dit is een voorbeeld van een definitieve vrijgave voor DMS-uitvoer met MRN-nummer en FRN-nummer.   
          -   DMS TAX-FINAL 25NL5NLTJSXXWUVDR5 250523-1020090.pdf. Dit is een voorbeeld van een DMS UTB met MRN-nummer en FRN-nummer.  
          -   DVA GOODS RELEASE NOTIFICATION 25NL000590KKZEATJ0.pdf. Dit is een voorbeeld van een DVA-document met MRN-nummer.  
          -   EMCS DEPARTURE-ACCEPTED 25NL132517592391582S2 252215-138800050.pdf. Dit is een voorbeeld van een EMCS-document met ARC-nummer en FRN-nummer.