royal mail tracking

Suivi Royal Mail pour PHP

Veuillez soulever un problème dans le référentiel GitHub si vous le pouvez, sinon n'hésitez pas à me contacter.

Les demandes de tirage pour des corrections de bugs ou des modifications potentielles sont les bienvenues !

Au bas de ce fichier Lisez-moi se trouve une liste de certains codes d'événement et leur définition approximative.

Usage

PHP 8.1 ou supérieur est requis.

Pour installer le package via Composer :

composer require elliotjreed/royal-mail-tracking

Trois moyens de récupérer les données de suivi sont disponibles :

• Events : pour des informations détaillées et l'historique complet d'un numéro de suivi unique ;
• Signature : les données de signature (y compris les données d'image - soit un PNG encodé en base64, soit un SVG) ;
• Summary : pour l'événement le plus récent pour plusieurs numéros de suivi.

Les détails de chacun sont décrits ci-dessous, avec des exemples inclus.

Les informations sur la gestion des erreurs sont fournies sous les informations Events , Signature et Summary (et valent la peine d'être lues car les erreurs Summary sont traitées différemment des Events et des erreurs Summary ).

Instanciation / Configuration

 $ tracking = ( new  ElliotJReed  RoyalMail  Tracking  Events (
    new  GuzzleHttp  Client (),
    ' aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ' ,
    ' 12345678901234567890123456789012345678901234567890 ' ,
    true , // Optional, when true (default: true) exceptions will be thrown for tracking errors
    true , // Optional, when true (default: true) exceptions will be thrown for technical (eg. 500 HTTP response) errors
    ' https://api.royalmail.net/mailpieces/v2 ' // Optional , when set the default API endpoint can be overridden (default: ' https://api.royalmail.net/mailpieces/v2 ' )
));

 $ signature = ( new  ElliotJReed  RoyalMail  Tracking  Signature (
    new  GuzzleHttp  Client (),
    ' aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ' ,
    ' 12345678901234567890123456789012345678901234567890 ' ,
    true , // Optional, when true (default: true) exceptions will be thrown for tracking errors
    true , // Optional, when true (default: true) exceptions will be thrown for technical (eg. 500 HTTP response) errors
    ' https://api.royalmail.net/mailpieces/v2 ' // Optional , when set the default API endpoint can be overridden (default: ' https://api.royalmail.net/mailpieces/v2 ' )
));

 $ summary = ( new  ElliotJReed  RoyalMail  Tracking  Summary (
    new  GuzzleHttp  Client (),
    ' aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ' ,
    ' 12345678901234567890123456789012345678901234567890 ' ,
    true , // Optional, when true (default: true) exceptions will be thrown for tracking errors
    true , // Optional, when true (default: true) exceptions will be thrown for technical (eg. 500 HTTP response) errors
    ' https://api.royalmail.net/mailpieces/v2 ' // Optional , when set the default API endpoint can be overridden (default: ' https://api.royalmail.net/mailpieces/v2 ' )
));

Événements

Le comportement de l’opération d’événements est de fournir un historique des traces pour un seul élément de courrier.

Renvoie le résumé, les métadonnées de signature, la fenêtre de livraison estimée et les événements pour un numéro de suivi fourni.

 $ tracking = ( new  ElliotJReed  RoyalMail  Tracking  Events (
    new  GuzzleHttp  Client (),
    ' aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ' ,
    ' 12345678901234567890123456789012345678901234567890 '
));

$ mailPieces = $ tracking -> setTrackingNumber ( ' AB1234567890GB ' )-> getResponse ()-> getMailPieces ();

$ mailPieces -> getMailPieceId (); // 090367574000000FE1E1B
$ mailPieces -> getCarrierShortName (); // RM
$ mailPieces -> getCarrierFullName (); // Royal Mail Group Ltd

$ summary = $ mailPieces -> getSummary ();
$ summary -> getUniqueItemId (); // 090367574000000FE1E1B
$ summary -> getOneDBarcode (); // FQ087430672GB
$ summary -> getProductId (); // SD2
$ summary -> getProductName (); // Special Delivery Guaranteed
$ summary -> getProductDescription (); // Our guaranteed next day service with tracking and a signature on delivery
$ summary -> getProductCategory (); // NON-INTERNATIONAL
$ summary -> getDestinationCountryCode (); // GBR
$ summary -> getDestinationCountryName (); // United Kingdom of Great Britain and Northern Ireland
$ summary -> getOriginCountryCode (); // GBR
$ summary -> getOriginCountryName (); // United Kingdom of Great Britain and Northern Ireland
$ summary -> getLastEventCode (); // EVNMI
$ summary -> getLastEventName (); // Forwarded - Mis-sort
$ summary -> getLastEventDateTime (); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$ summary -> getLastEventLocationName (); // Stafford DO
$ summary -> getStatusDescription (); // It is being redirected
$ summary -> getStatusCategory (); // IN TRANSIT
$ summary -> getStatusHelpText (); // The item is in transit
$ summary -> getSummaryLine (); // Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20.

$ internationalPostalProvider = $ summary -> getInternationalPostalProvider ();
$ internationalPostalProvider -> getUrl (); // https://www.royalmail.com/track-your-item
$ internationalPostalProvider -> getTitle (); // Royal Mail Group Ltd
$ internationalPostalProvider -> getDescription (); // Royal Mail Group Ltd

$ signature = $ mailPieces -> getSignature ();
$ signature -> getRecipientName (); // Elliot
$ signature -> getSignatureDateTime (); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$ signature -> getImageId (); // 001234

$ estimatedDelivery = $ mailPieces -> getEstimatedDelivery ();
$ estimatedDelivery -> getDate (); // new DateTimeImmutable('2017-02-20T00:00:00+00:00')
$ estimatedDelivery -> getStartOfEstimatedWindow (); // new DateTimeImmutable('2017-02-20T08:00:00+01:00')
$ estimatedDelivery -> getEndOfEstimatedWindow (); // new DateTimeImmutable('2017-02-20T11:00:00+01:00')

$ events = $ mailPieces -> getEvents ();
$ event = $ events [ 0 ];
$ event -> getEventCode (); // EVNMI
$ event -> getEventName (); // Forwarded - Mis-sort
$ event -> getEventDateTime (); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$ event -> getLocationName (); // Stafford DO

$ linkSummary = $ mailPieces -> getLinks ()-> getSummary ();
$ linkSummary -> getHref (); // /mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B
$ linkSummary -> getTitle (); // Summary
$ linkSummary -> getDescription (); // Get summary

$ linkSignature = $ mailPieces -> getLinks ()-> getSignature ();
$ linkSignature -> getHref (); // /mailpieces/v2/090367574000000FE1E1B/signature
$ linkSignature -> getTitle (); // Signature
$ linkSignature -> getDescription (); // Get signature

$ linkRedelivery = $ mailPieces -> getLinks ()-> getRedelivery ();
$ linkRedelivery -> getHref (); // /personal/receiving-mail/redelivery
$ linkRedelivery -> getTitle (); // Redelivery
$ linkRedelivery -> getDescription (); // Book a redelivery 

Sortie JSON

 $ tracking = ( new  ElliotJReed  RoyalMail  Tracking  Events (
    new  GuzzleHttp  Client (),
    ' aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ' ,
    ' 12345678901234567890123456789012345678901234567890 '
));

echo $ tracking -> setTrackingNumber ( ' AB1234567890GB ' )-> asJson ();

Afficherait la réponse de Royal Mail au format JSON :

{
    "errors" : [],
    "httpCode" : null ,
    "httpMessage" : null ,
    "mailPieces" : {
        "carrierFullName" : " Royal Mail Group Ltd " ,
        "carrierShortName" : " RM " ,
        "estimatedDelivery" : {
            "date" : " 2017-02-20T00:00:00+00:00 " ,
            "endOfEstimatedWindow" : " 2017-02-20T11:00:00+01:00 " ,
            "startOfEstimatedWindow" : " 2017-02-20T08:00:00+01:00 "
        },
        "events" : [
            {
                "eventCode" : " EVNMI " ,
                "eventDateTime" : " 2016-10-20T10:04:00+01:00 " ,
                "eventName" : " Forwarded - Mis-sort " ,
                "locationName" : " Stafford DO "
            }
        ],
        "links" : {
            "redelivery" : {
                "description" : " Book a redelivery " ,
                "href" : " /personal/receiving-mail/redelivery " ,
                "title" : " Redelivery "
            },
            "signature" : {
                "description" : " Get signature " ,
                "href" : " /mailpieces/v2/090367574000000FE1E1B/signature " ,
                "title" : " Signature "
            },
            "summary" : {
                "description" : " Get summary " ,
                "href" : " /mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B " ,
                "title" : " Summary "
            }
        },
        "mailPieceId" : " 090367574000000FE1E1B " ,
        "signature" : {
            "imageId" : " 001234 " ,
            "recipientName" : " Elliot " ,
            "signatureDateTime" : " 2016-10-20T10:04:00+01:00 "
        },
        "summary" : {
            "destinationCountryCode" : " GBR " ,
            "destinationCountryName" : " United Kingdom of Great Britain and Northern Ireland " ,
            "internationalPostalProvider" : {
                "description" : " Royal Mail Group Ltd " ,
                "title" : " Royal Mail Group Ltd " ,
                "url" : " https://www.royalmail.com/track-your-item "
            },
            "lastEventCode" : " EVNMI " ,
            "lastEventDateTime" : " 2016-10-20T10:04:00+01:00 " ,
            "lastEventLocationName" : " Stafford DO " ,
            "lastEventName" : " Forwarded - Mis-sort " ,
            "oneDBarcode" : " FQ087430672GB " ,
            "originCountryCode" : " GBR " ,
            "originCountryName" : " United Kingdom of Great Britain and Northern Ireland " ,
            "productCategory" : " NON-INTERNATIONAL " ,
            "productDescription" : " Our guaranteed next day service with tracking and a signature on delivery " ,
            "productId" : " SD2 " ,
            "productName" : " Special Delivery Guaranteed " ,
            "statusCategory" : " IN TRANSIT " ,
            "statusDescription" : " It is being redirected " ,
            "statusHelpText" : " The item is in transit " ,
            "summaryLine" : " Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20. " ,
            "uniqueItemId" : " 090367574000000FE1E1B "
        }
    },
    "moreInformation" : null
}

Signature

 $ tracking = ( new  ElliotJReed  RoyalMail  Tracking  Signature (
    new  GuzzleHttp  Client (),
    ' aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ' ,
    ' 12345678901234567890123456789012345678901234567890 '
));

$ mailPieces = $ tracking -> setTrackingNumber ( ' AB1234567890GB ' )-> getResponse ()-> getMailPieces ();

$ mailPieces -> getMailPieceId (); // 090367574000000FE1E1B
$ mailPieces -> getCarrierShortName (); // RM
$ mailPieces -> getCarrierFullName (); // Royal Mail Group Ltd

$ signature = $ mailPieces -> getSignature ();
$ signature -> getRecipientName (); // Elliot
$ signature -> getSignatureDateTime (); // new DateTimeImmutable('2017-03-30T16:15:00+01:00')
$ signature -> getImageId (); // 001234
$ signature -> getOneDBarcode (); // FQ087430672GB
$ signature -> getHeight (); // 530
$ signature -> getWidth (); // 660
$ signature -> getUniqueItemId (); // 090367574000000FE1E1B
$ signature -> getImageFormat (); // image/svg+xml
$ signature -> getImage (); // <svg></svg>

$ events = $ mailPieces -> getLinks ()-> getEvents ();
$ events -> getHref (); // /mailpieces/v2/FQ087430672GB/events
$ events -> getTitle (); // Events
$ events -> getDescription (); // Get events

$ linkSummary = $ mailPieces -> getLinks ()-> getSummary ();
$ linkSummary -> getHref (); // /mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B
$ linkSummary -> getTitle (); // Summary
$ linkSummary -> getDescription (); // Get summary 

Sortie JSON

 $ tracking = ( new  ElliotJReed  RoyalMail  Tracking  Signature (
    new  GuzzleHttp  Client (),
    ' aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ' ,
    ' 12345678901234567890123456789012345678901234567890 '
));

echo $ tracking -> setTrackingNumber ( ' AB1234567890GB ' )-> asJson ();

Afficherait la réponse de suivi de Royal Mail au format JSON :

{
    "errors" : [],
    "httpCode" : null ,
    "httpMessage" : null ,
    "mailPieces" : {
        "carrierFullName" : " Royal Mail Group Ltd " ,
        "carrierShortName" : " RM " ,
        "links" : {
            "events" : {
                "description" : " Get events " ,
                "href" : " /mailpieces/v2/FQ087430672GB/events " ,
                "title" : " Events "
            },
            "summary" : {
                "description" : " Get summary " ,
                "href" : " /mailpieces/v2/summary?mailPieceId=090367574000000FE1E1B " ,
                "title" : " Summary "
            }
        },
        "mailPieceId" : " 090367574000000FE1E1B " ,
        "signature" : {
            "height" : 530 ,
            "image" : " <svg></svg> " ,
            "imageFormat" : " image/svg+xml " ,
            "imageId" : " 001234 " ,
            "oneDBarcode" : " FQ087430672GB " ,
            "recipientName" : " Elliot " ,
            "signatureDateTime" : " 2017-03-30T16:15:00+01:00 " ,
            "uniqueItemId" : " 090367574000000FE1E1B " ,
            "width" : 660
        }
    },
    "moreInformation" : null
}

Résumé

Le comportement de l'opération récapitulative est de permettre aux clients d'obtenir les dernières données de suivi d'un envoi postal.

Cette opération renvoie le récapitulatif d'un ou plusieurs numéros de suivi fournis dans la requête.

Cette opération permet uniquement de fournir un maximum de 30 numéros de suivi dans la méthode ->setTrackingNumbers() (par exemple ->setTrackingNumbers(['AB0123456789GB', 'CD0123456789GB']) ).

 $ summary = ( new  ElliotJReed  RoyalMail  Tracking  Summary (
    new  GuzzleHttp  Client (),
    ' aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ' ,
    ' 12345678901234567890123456789012345678901234567890 '
));

$ mailPieces = $ summary -> setTrackingNumbers ( ' AB1234567890GB ' , ' CD1234567890GB ' )-> getResponse ()-> getMailPieces ();

$ firstMailPieces = $ mailPieces [ 0 ];

$ firstMailPieces -> getMailPieceId (); // 090367574000000FE1E1B
$ firstMailPieces -> getCarrierShortName (); // RM
$ firstMailPieces -> getCarrierFullName (); // Royal Mail Group Ltd

$ summary = $ firstMailPieces -> getSummary ();
$ summary -> getUniqueItemId (); // 090367574000000FE1E1B
$ summary -> getOneDBarcode (); // FQ087430672GB
$ summary -> getProductId (); // SD2
$ summary -> getProductName (); // Special Delivery Guaranteed
$ summary -> getProductDescription (); // Our guaranteed next day service with tracking and a signature on delivery
$ summary -> getProductCategory (); // NON-INTERNATIONAL
$ summary -> getDestinationCountryCode (); // GBR
$ summary -> getDestinationCountryName (); // United Kingdom of Great Britain and Northern Ireland
$ summary -> getOriginCountryCode (); // GBR
$ summary -> getOriginCountryName (); // United Kingdom of Great Britain and Northern Ireland
$ summary -> getLastEventCode (); // EVNMI
$ summary -> getLastEventName (); // Forwarded - Mis-sort
$ summary -> getLastEventDateTime (); // new DateTimeImmutable('2016-10-20T10:04:00+01:00')
$ summary -> getLastEventLocationName (); // Stafford DO
$ summary -> getStatusDescription (); // It is being redirected
$ summary -> getStatusCategory (); // IN TRANSIT
$ summary -> getStatusHelpText (); // The item is in transit
$ summary -> getSummaryLine (); // Item FQ087430672GB was forwarded to the Delivery Office on 2016-10-20.

$ internationalPostalProvider = $ summary -> getInternationalPostalProvider ();
$ internationalPostalProvider -> getUrl (); // https://www.royalmail.com/track-your-item
$ internationalPostalProvider -> getTitle (); // Royal Mail Group Ltd
$ internationalPostalProvider -> getDescription (); // Royal Mail Group Ltd

$ events = $ firstMailPieces -> getLinks ()-> getEvents ();
$ events -> getHref (); // /mailpieces/v2/FQ087430672GB/events
$ events -> getTitle (); // Events
$ events -> getDescription (); // Get events

$ error = $ firstMailPieces -> getError ();
$ error -> getErrorCode (); // E1142
$ error -> getErrorDescription (); // Barcode reference $mailPieceId isn't recognised
$ error -> getErrorCause (); // A mail item with that barcode cannot be located
$ error -> getErrorResolution (); // Check barcode and resubmit 

Sortie JSON

 $ summary = ( new  ElliotJReed  RoyalMail  Tracking  Summary (
    new  GuzzleHttp  Client (),
    ' aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee ' ,
    ' 12345678901234567890123456789012345678901234567890 '
));

echo $ summary -> asJson ();

Afficherait la réponse de Royal Mail au format JSON :

{
    "errors" : [],
    "httpCode" : null ,
    "httpMessage" : null ,
    "mailPieces" : [
        {
            "carrierFullName" : " Royal Mail Group Ltd " ,
            "carrierShortName" : " RM " ,
            "error" : {
                "errorCause" : " A mail item with that barcode cannot be located " ,
                "errorCode" : " E1142 " ,
                "errorDescription" : " Barcode reference mailPieceId is not recognised " ,
                "errorResolution" : " Check barcode and resubmit "
            },
            "links" : {
                "events" : {
                    "description" : " Get events " ,
                    "href" : " /mailpieces/v2/FQ087430672GB/events " ,
                    "title" : " Events "
                }
            },
            "mailPieceId" : " 090367574000000FE1E1B " ,
            "summary" : {
                "destinationCountryCode" : " GBR " ,
                "destinationCountryName" : " United Kingdom of Great Britain and Northern Ireland " ,
                "internationalPostalProvider" : {
                    "description" : " Royal Mail Group Ltd " ,
                    "title" :