feat: support requestid for idempotent write ops

src/DataService/DataService.php

@@ -150,6 +150,12 @@ class DataService
      */
     private $clientName = CoreConstants::CLIENT_CURL;
 
+    /**
+     * Optional Request Id to be sent as query parameter on write operations
+     * @var string|null
+     */
+    private $requestId;
+
 
     /**
      * Initializes a new instance of the DataService class. The old way to construct the dataService. Used by PHP SDK < 3.0.0
@@ -371,6 +377,19 @@ public function setClientName($clientName){
        return $this;
     }
 
+    /**
+     * Set the request id which will be appended as query parameter to supported operations
+     * (Add, Update, Void, SendEmail) for idempotency.
+     *
+     * @param string $requestId
+     * @return $this
+     */
+    public function setRequestId($requestId)
+    {
+        $this->requestId = $requestId;
+        return $this;
+    }
+
     /**
      * New Static function for static Reading from Config or Passing Array
      * The config needs to include
@@ -643,6 +662,7 @@ private function sendRequestParseResponseBodyAndHandleHttpError($entity, $uri, $
             case DataService::ADD:
             case DataService::VOID:
             case DataService::UPDATE:
+                $uri = $this->appendRequestIdToUri($uri);
                 $requestParameters = $this->initPostRequest($entity, $uri);
                 break;
             case DataService::FINDBYID:
@@ -1979,4 +1999,19 @@ private function getIDString($id){
             return (String)$id;
         }
     }
+
+    /**
+     * Appends request id to uri if it is set
+     * @param string $uri
+     * @return string
+     */
+    private function appendRequestIdToUri($uri)
+    {
+        if (isset($this->requestId) && $this->requestId !== '') {
+            $delimiter = (strpos($uri, '?') === false) ? '?' : '&';
+            return $uri . $delimiter . 'requestid=' . urlencode($this->requestId);
+        }
+        $this->requestId = null;
+        return $uri;
+    }
 }