Registration of sending parcels from your sender's address

The Courier pickup feature allows sending parcels directly from an address. Through the API, clients can create requests for courier pickup, manage visit time intervals, cancel, and edit requests.

This article outlines the key aspects of working with courier pickup through the API.

Courier pickup methods in API

Courier pickup API workflow

1. 1
   Creating a courier pickup request
   
   The client uses the POST /pickups method to create a new courier call request. At this stage, the request is assigned the status Draft. While in this status, the client can:

   • 1.1
     Add or remove parcels.
   • 1.2
     Modify the address or time intervals.
2. 2
   Adding parcels to a courier pickup request
   
   Parcels are added using the POST /pickups/{id}/shipments method. The client provides an array of shipment IDs to be added.
   
   Limitations:

   • 2.1
     Parcels must have the status ReadyToShip.
   • 2.2
     Parcels with a different sender's address cannot be added.
3. 3
   Specifying the Date/Time of courier arrival
   
   After adding parcels, the client must specify the date and time for the courier's visit:
   

   1. 3.1
      Use POST /time-intervals/find to retrieve available time intervals and select a convenient one.
   2. 3.2
      The selected interval is passed as parameters pickedTimeFrom and pickedTimeTo.
4. 4
   Changing the Request Status
   
   Once all parcels are added, the client updates the request status to Created using PUT /pickups/{id}/status. In this status, the request awaits processing by the courier.
   
   Limitations:

   • 4.1
     Shipments must have the status Paid or ContractAfterPayment.
   • 4.2
     Paid or ContractAfterPayment. The request can no longer be modified, except for updating the time interval.

1. 5
   Viewing requests
   
   The client can retrieve a list of their requests using the GET /pickups method. The response includes the current status of each request.
   
   Request statuses:

   • 5.1
     Draft: Initial status of the request. In this status, the client can add or remove parcels.
   • 5.2
     Created: The request is ready for processing by the courier.
   • 5.3
     AppointedCourier: A courier has been assigned to the request.
   • 5.4
     InProgress: The courier is en route to the sender's address.
   • 5.5
     ReceivedByCourier: The courier has collected the parcels from the sender and is delivering them to the branch.
   • 5.6
     Done: The courier has completed the request, and the parcels have been delivered to the branch.
   • 5.7
     ClientCanceled: The request was canceled by the client.
   • 5.8
     NotCompleted: The courier canceled the request due to the inability to collect the parcels (e.g., parcels were not ready).
   • 5.9
     Deleted: The request has been removed from the system.

Each parcel in a courier call request has an individual status, reflecting its current state during the pickup process (pickup_shipments[...]).

Parcel statuses:

• 1
  Added: The parcel has been added to the request. Available only when the request status is Draft. This is the initial status for each parcel added to the request. 
• 2
  Accepted: The parcel has been successfully accepted by the courier. Applicable only to requests with the status AppointedCourier or InProgress.
• 3
  NotReady: The parcel was removed from the request because it was not ready for dispatch. This status can only be set by the courier and is available for requests with the status AppointedCourier or InProgress.
• 4
  NotPacked: The parcel was not properly packed for handover to the courier. This status can only be set by the courier and is available in requests with the status AppointedCourier or InProgress.
• 5
  ClientCanceled: The parcel was removed from the request at the client's initiative. Available for requests with any status except Draft and Deleted.
• 6
  Deleted: The parcel has been removed from the courier call request. Available only in requests with the status Draft. Deleted parcels can be restored to the Added status. 

1. 6
   Cancellation and Deletion

   • 6.1
     To cancel a request in the Created status, the client changes its status to ClientCanceled using the PUT /pickups/{id}/status.
   • 6.2
     To delete a request in the Draft status, the DEL /pickups/{id} method is used.

Limitations and Key Points

• 1
  Adding and removing parcels is only possible for requests in the Draft status.
• 2
  Requests in the Created status or higher cannot be modified, only canceled, except for updating the time interval.
• 3
  The sender's address for all parcels in a courier call request must be identical, except for the Note field.
• 4
  Time intervals must be selected using the available slots. Same-day time intervals (PickupDayToDay) are not available for all cities. New cities are added progressively.
• 5
  When making changes to a courier call request, the lockVersion field value must be incremented by one.

Detailed API method documentation can be found in the Nova Post API documentation.