feat: Add ability to manage Purchase Orders using external id

CHANGELOG.md

@@ -23,6 +23,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   id or external id if `useSystem=external` is passed.
 - Add support for `useSystem=external` for `updatePaymentTerm` and
   `deletePaymentTerm`.
+- Add support for `useSystem=external` for `getPurchaseOrder`,
+  `updatePurchaseOrder`, `deletePurchaseOrder`, `getPurchaseOrderItem`, and
+  `deletePurchaseOrderItem`
 
 ## v0.21.0
 

vic.api.v0.yaml

@@ -1439,9 +1439,12 @@ paths:
         - name: purchaseOrderId
           in: path
           required: true
-          description: The internal id of the purchase order.
+          description: |
+            The internal or external of the purchase order. If using the
+            external id, you **must** pass `useSystem=external`.
           schema:
             type: string
+        - $ref: '#/components/parameters/UseSystem'
       responses:
         '200':
           $ref: '#/components/responses/PurchaseOrderResponse'
@@ -1461,9 +1464,12 @@ paths:
         - name: purchaseOrderId
           in: path
           required: true
-          description: The id of the purchase order.
+          description: |
+            The internal or external of the purchase order. If using the
+            external id, you **must** pass `useSystem=external`.
           schema:
             type: string
+        - $ref: '#/components/parameters/UseSystem'
       requestBody:
         $ref: '#/components/requestBodies/UpdatePurchaseOrderRequest'
       responses:
@@ -1487,9 +1493,12 @@ paths:
         - name: purchaseOrderId
           in: path
           required: true
-          description: The internal id of the purchase order.
+          description: |
+            The internal or external of the purchase order. If using the
+            external id, you **must** pass `useSystem=external`.
           schema:
             type: string
+        - $ref: '#/components/parameters/UseSystem'
       responses:
         '204':
           $ref: '#/components/responses/PurchaseOrderDeletedResponse'
@@ -1511,9 +1520,12 @@ paths:
         - name: purchaseOrderId
           in: path
           required: true
-          description: The internal id of the purchase order.
+          description: |
+            The internal or external of the purchase order. If using the
+            external id, you **must** pass `useSystem=external`.
           schema:
             type: string
+        - $ref: '#/components/parameters/UseSystem'
       responses:
         '200':
           $ref: '#/components/responses/PurchaseOrderResponse'
@@ -1533,9 +1545,12 @@ paths:
         - name: purchaseOrderId
           in: path
           required: true
-          description: The internal id of the purchase order.
+          description: |
+            The internal or external of the purchase order. If using the
+            external id, you **must** pass `useSystem=external`.
           schema:
             type: string
+        - $ref: '#/components/parameters/UseSystem'
       responses:
         '200':
           $ref: '#/components/responses/PurchaseOrderResponse'
@@ -1555,9 +1570,12 @@ paths:
         - name: purchaseOrderId
           in: path
           required: true
-          description: The internal id of the purchase order.
+          description: |
+            The internal or external of the purchase order. If using the
+            external id, you **must** pass `useSystem=external`.
           schema:
             type: string
+        - $ref: '#/components/parameters/UseSystem'
       responses:
         '200':
           $ref: '#/components/responses/PurchaseOrderResponse'
@@ -1596,9 +1614,12 @@ paths:
         - name: purchaseOrderLineItemId
           in: path
           required: true
-          description: The id of the purchase order line item.
+          description: |
+            The internal or external of the purchase order line item. If using
+            the external id, you **must** pass `useSystem=external`.
           schema:
             type: string
+        - $ref: '#/components/parameters/UseSystem'
       requestBody:
         $ref: '#/components/requestBodies/UpdatePurchaseOrderLineItemRequest'
       responses:
@@ -1620,9 +1641,12 @@ paths:
         - name: purchaseOrderLineItemId
           in: path
           required: true
-          description: The id of the purchase order line item.
+          description: |
+            The internal or external of the purchase order line item. If using
+            the external id, you **must** pass `useSystem=external`.
           schema:
             type: string
+        - $ref: '#/components/parameters/UseSystem'
       responses:
         '204':
           $ref: '#/components/responses/PurchaseOrderLineItemDeletedResponse'
@@ -3341,6 +3365,11 @@ components:
         lineNumber:
           type: integer
           minimum: 1
+        externalId:
+          oneOf:
+            - type: string
+              maxLength: 255
+            - type: 'null'
         dimensions:
           type: array
           items:
@@ -3405,6 +3434,11 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/DimensionRef'
+        externalId:
+          oneOf:
+            - type: string
+              maxLength: 255
+            - type: 'null'
     UpdatePurchaseOrderLineItem:
       type: object
       required:
@@ -3452,6 +3486,11 @@ components:
         lineNumber:
           type: integer
           minimum: 1
+        externalId:
+          oneOf:
+            - type: string
+              maxLength: 255
+            - type: 'null'
         dimensions:
           type: array
           items: