@shipengine/connect-carrier-api 4.25.0 → 4.26.1

package/spec.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Shipping API",
     "description": "This API specification describes the canonical ShipEngine Shipping API connector module.",
-    "version": "1.39.0"
+    "version": "1.39.1"
   },
   "paths": {
     "/Register": {
@@ -39,6 +39,37 @@
         }
       }
     },
+    "/UploadDocument": {
+      "post": {
+        "tags": [
+          "Documents"
+        ],
+        "description": "This method uploads a document to the carrier.",
+        "operationId": "Upload Document",
+        "requestBody": {
+          "description": "An object information about the document to upload.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UploadDocumentRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "This object model represents the response from a successful upload document response.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UploadDocumentResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/CreateLabel": {
       "post": {
         "tags": [
@@ -957,7 +988,7 @@
           },
           "service_configuration_id": {
             "type": "string",
-            "description": "A unique ID representing a specific carrier service-level or automation rule within the carrier's or aggregator's system.",
+            "description": "A unique ID representing a specific carrier service-level or automation rule within the carrier's/aggregator's system.\r\nRequired for configuration-based service selection (e.g., Logistics Aggregators) and custom service-levels (e.g., Royal Mail)\r\nto leverage negotiated rates and service levels.",
             "nullable": true
           },
           "delivery_as_addressed": {
@@ -2340,8 +2371,7 @@
       "DisplayScheme": {
         "enum": [
           "label",
-          "paperless_label",
-          "no_box_no_label"
+          "paperless_label"
         ],
         "type": "string"
       },
@@ -2391,6 +2421,34 @@
         ],
         "type": "string"
       },
+      "DocumentUploadFormat": {
+        "enum": [
+          "PDF",
+          "PNG"
+        ],
+        "type": "string"
+      },
+      "DocumentUploadType": {
+        "enum": [
+          "commercial_invoice",
+          "certificate_of_origin",
+          "usmca_commercial_invoice_certification_of_origin",
+          "usmca_certification_of_origin",
+          "pro_forma_invoice",
+          "other",
+          "authorization_form",
+          "export_accompanying_document",
+          "export_license",
+          "import_permit",
+          "one_time_nafta",
+          "power_of_attorney",
+          "packing_list",
+          "sed_document",
+          "shippers_letter_of_instruction",
+          "declaration"
+        ],
+        "type": "string"
+      },
       "EstimatedImportCharges": {
         "type": "object",
         "properties": {
@@ -3863,16 +3921,25 @@
         "description": "Base class for all subscription channel protocols"
       },
       "PudoLocation": {
-        "required": [
-          "postal_code",
-          "country_code"
-        ],
         "type": "object",
         "allOf": [
           {
             "$ref": "#/components/schemas/AddressWithContact"
           }
         ],
+        "anyOf": [
+          {
+            "required": [
+              "location_id"
+            ]
+          },
+          {
+            "required": [
+              "postal_code",
+              "country_code"
+            ]
+          }
+        ],
         "properties": {
           "carrier_code": {
             "type": "string",
@@ -4316,62 +4383,6 @@
         ],
         "type": "string"
       },
-      "SellerDocument": {
-        "type": "object",
-        "properties": {
-          "document_upload_id": {
-            "type": "string",
-            "nullable": true
-          },
-          "type": {
-            "type": "string",
-            "description": "Standardized document format.",
-            "nullable": true
-          },
-          "name": {
-            "type": "string",
-            "description": "The document name.",
-            "nullable": true
-          },
-          "content": {
-            "type": "string",
-            "description": "Document content in base64 format.",
-            "nullable": true
-          }
-        },
-        "additionalProperties": false,
-        "description": "Represents a document in the upload request."
-      },
-      "SellerDocumentResult": {
-        "type": "object",
-        "properties": {
-          "document_upload_id": {
-            "type": "string",
-            "nullable": true
-          },
-          "carrier_document_id": {
-            "type": "string",
-            "description": "The document ID in the carrier's system.",
-            "nullable": true
-          },
-          "uploaded_to_carrier_at": {
-            "type": "string",
-            "description": "The UTC timestamp of when the document was successfully uploaded to the carrier.",
-            "format": "date-time",
-            "nullable": true
-          },
-          "errors": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "The errors that occurred while uploading a document.",
-            "nullable": true
-          }
-        },
-        "additionalProperties": false,
-        "description": "Represents the result of uploading a document to the carrier."
-      },
       "Service": {
         "type": "object",
         "properties": {
@@ -5547,10 +5558,8 @@
         "additionalProperties": false,
         "description": "This model represents the successful response for updating carrier settings request."
       },
-      "UploadDocumentsRequest": {
+      "UploadDocumentRequest": {
         "required": [
-          "documents",
-          "ship_from",
           "transaction_id"
         ],
         "type": "object",
@@ -5560,65 +5569,45 @@
           }
         ],
         "properties": {
-          "documents": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/SellerDocument"
-            },
-            "description": "An array of objects, one for each successfully processed document.",
+          "document_id": {
+            "type": "string",
+            "description": "The document id",
             "nullable": true
           },
-          "ship_from": {
-            "$ref": "#/components/schemas/ShipFrom"
+          "document_type": {
+            "$ref": "#/components/schemas/DocumentUploadType"
           },
-          "tracking_number": {
+          "document_format": {
+            "$ref": "#/components/schemas/DocumentUploadFormat"
+          },
+          "file_name": {
             "type": "string",
-            "description": "The carrier tracking number for this shipment",
+            "description": "The file name",
             "nullable": true
           },
-          "ship_to": {
-            "$ref": "#/components/schemas/ShipTo"
-          },
-          "alternative_identifiers": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/Identifier"
-            },
-            "description": "Alternative identifiers associated with this package",
+          "file_url": {
+            "type": "string",
+            "description": "The file URL",
             "nullable": true
           },
-          "service_code": {
+          "tracking_number": {
             "type": "string",
-            "description": "The service code used for this shipment",
+            "description": "The carrier tracking number for this shipment",
             "nullable": true
           },
-          "packages": {
+          "alternative_identifiers": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/ShippedPackage"
+              "$ref": "#/components/schemas/Identifier"
             },
-            "description": "The list of packages associated with this shipment",
-            "nullable": true
-          },
-          "advanced_options": {
-            "$ref": "#/components/schemas/AdvancedOptions"
-          },
-          "pickup_location": {
-            "$ref": "#/components/schemas/PudoLocation"
-          },
-          "dropoff_location": {
-            "$ref": "#/components/schemas/PudoLocation"
-          },
-          "reference": {
-            "type": "string",
-            "description": "User specified free form string to identify shipment in their own system",
+            "description": "Alternative identifiers associated with this package",
             "nullable": true
           }
         },
         "additionalProperties": false,
-        "description": "A request to upload documents for a shipment."
+        "description": "A request to upload a document for a shipment."
       },
-      "UploadDocumentsResponse": {
+      "UploadDocumentResponse": {
         "type": "object",
         "allOf": [
           {
@@ -5626,17 +5615,14 @@
           }
         ],
         "properties": {
-          "documents": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/SellerDocumentResult"
-            },
-            "description": "An array of objects, one for each successfully processed document.",
+          "carrier_document_id": {
+            "type": "string",
+            "description": "The carrier document ID.",
             "nullable": true
           }
         },
         "additionalProperties": false,
-        "description": "Response for uploading documents to a carrier."
+        "description": "Response for uploading a document to a carrier."
       },
       "ValidateInboundDataRequest": {
         "required": [
@@ -6082,6 +6068,10 @@
     {
       "name": "Normalize Inbound Data",
       "description": "Given inbound data, such as a webhook with tracking updates, return normalized information."
+    },
+    {
+      "name": "Documents",
+      "description": ""
     }
   ]
-}
+}

package/src/app/carrier-app-definition.ts

@@ -21,6 +21,7 @@ import {
   UpdateSettingsRequest,
   ListPickupsRequest,
   StartTrackingRequest,
+  UploadDocumentRequest,
 } from '../requests';
 
 import {
@@ -42,26 +43,18 @@ import {
   UpdateSettingsResponse,
   ListPickupsResponse,
   StartTrackingResponse,
+  UploadDocumentResponse,
 } from '../responses';
 
 import { CarrierAppMetadata } from './metadata/carrier-app-metadata';
 
 import { RequestResponseInfo, Handler } from '@shipengine/connect-runtime';
-import { UploadDocumentsRequest } from '../requests/upload-documents-request';
-import { UploadDocumentsResponse } from '../responses/upload-documents-response';
 
 /**
  * @description This defines a connect carrier app
  */
 export interface CarrierAppDefinition {
   Metadata: CarrierAppMetadata;
-  /**
-   * @description This method is used to upload documents to carrier
-   * @param request Data needed by the provider to upload documents
-   */
-  UploadDocuments?: (
-    request: UploadDocumentsRequest,
-  ) => UploadDocumentsResponse | Promise<UploadDocumentsResponse>;
   /**
    * @description This method is used to register an account
    * @param request The information needed to register or initialize a connection with the shipping provider
@@ -201,6 +194,13 @@ export interface CarrierAppDefinition {
   StartTracking?: (
     request: StartTrackingRequest,
   ) => StartTrackingResponse | Promise<StartTrackingResponse>;
+  /**
+   * @description This method is used to upload a document to carrier
+   * @param request Data needed by the provider to upload a document
+   */
+  UploadDocument?: (
+    request: UploadDocumentRequest,
+  ) => UploadDocumentResponse | Promise<UploadDocumentResponse>;
   /**
    * @description A collection of additional routes that can be used to extend the functionality of the app.
    * Extension methods are not automatically called by the ShipEngine platform, and require working with Auctane developers to implement.

package/src/app/constants.ts

@@ -19,5 +19,5 @@ export enum ApiEndpoints {
   UpdateSettings = '/UpdateSettings',
   ListPickups = '/ListPickups',
   StartTracking = '/StartTracking',
-  UploadDocuments = '/UploadDocuments',
+  UploadDocument = '/UploadDocument',
 }

package/src/app/create-endpoint-mapping.ts

@@ -10,7 +10,6 @@ export const createEndpointMapping = (
   [Method.POST, ApiEndpoints.CancelNotification, definition.CancelNotification],
   [Method.POST, ApiEndpoints.CancelPickup, definition.CancelPickup],
   [Method.POST, ApiEndpoints.CreateLabel, definition.CreateLabel],
-  [Method.POST, ApiEndpoints.UploadDocuments, definition.UploadDocuments],
   [Method.POST, ApiEndpoints.CreateManifest, definition.CreateManifest],
   [Method.POST, ApiEndpoints.GetManifest, definition.GetManifest],
   [Method.POST, ApiEndpoints.CreateNotification, definition.CreateNotification],
@@ -28,5 +27,6 @@ export const createEndpointMapping = (
   [Method.POST, ApiEndpoints.UpdateSettings, definition.UpdateSettings],
   [Method.POST, ApiEndpoints.ListPickups, definition.ListPickups],
   [Method.POST, ApiEndpoints.StartTracking, definition.StartTracking],
+  [Method.POST, ApiEndpoints.UploadDocument, definition.UploadDocument],
   ...mapExtensions(definition.Extensions),
 ];

package/src/models/addresses/pudo-location-schema.ts

@@ -4,4 +4,14 @@ import { AddressBaseSchema } from './address-base-schema';
 export const PudoLocationSchema = AddressBaseSchema.keys({
   carrier_code: Joi.string().optional(),
   location_id: Joi.string().optional(),
+  postal_code: Joi.string().when('location_id', {
+    is: Joi.exist(),
+    then: Joi.optional().allow(''),
+    otherwise: Joi.required(),
+  }),
+  country_code: Joi.string().when('location_id', {
+    is: Joi.exist(),
+    then: Joi.optional().allow(''),
+    otherwise: Joi.required(),
+  }),
 });

package/src/models/documents/index.ts

@@ -1,3 +1,4 @@
 export * from './document';
 export * from './document-type';
 export * from './document-type-schema';
+export * from './uploads';

package/src/models/documents/uploads/document-upload-format-schema.ts

@@ -0,0 +1,6 @@
+import Joi from 'joi';
+import { DocumentUploadFormat } from './document-upload-format';
+
+export const DocumentUploadFormatSchema = Joi.string().valid(
+  ...Object.values(DocumentUploadFormat),
+);

package/src/models/documents/uploads/document-upload-format.ts

@@ -0,0 +1,5 @@
+/** @description Accepted document upload formats */
+export enum DocumentUploadFormat {
+  Pdf = 'PDF',
+  Png = 'PNG',
+}

package/src/models/documents/uploads/document-upload-type-schema.ts

@@ -0,0 +1,4 @@
+import Joi from 'joi';
+import { DocumentUploadType } from './document-upload-type';
+
+export const DocumentUploadTypeSchema = Joi.string().valid(...Object.values(DocumentUploadType));

package/src/models/documents/uploads/document-upload-type.ts

@@ -0,0 +1,35 @@
+/** @description Types of uploaded documents */
+export enum DocumentUploadType {
+  /** @description A legal document issued by the seller (exporter) to the buyer (importer) in an international transaction and serves as a contract and a proof of sale between the buyer and seller */
+  CommercialInvoice = 'commercial_invoice',
+  /** @description A certificate of origin */
+  CertificateOfOrigin = 'certificate_of_origin',
+  /** @description A USMCA commercial invoice certification of origin */
+  UsmcaCommercialInvoiceCertificationOfOrigin = 'usmca_commercial_invoice_certification_of_origin',
+  /** @description A USMCA Certification of origin */
+  UsmcaCertificationOfOrigin = 'usmca_certification_of_origin',
+  /** @description A pro forma invoice */
+  ProFormaInvoice = 'pro_forma_invoice',
+  /** @description Other document type */
+  Other = 'other',
+  /** @description An authorization form */
+  AuthorizationForm = 'authorization_form',
+  /** @description An export accompanying document */
+  ExportAccompanyingDocument = 'export_accompanying_document',
+  /** @description An export license */
+  ExportLicense = 'export_license',
+  /** @description An import permit */
+  ImportPermit = 'import_permit',
+  /** @description A one-time NAFTA certificate */
+  OneTimeNafta = 'one_time_nafta',
+  /** @description A power of attorney document */
+  PowerOfAttorney = 'power_of_attorney',
+  /** @description A packing list */
+  PackingList = 'packing_list',
+  /** @description A SED (Shipper's Export Declaration) document */
+  SedDocument = 'sed_document',
+  /** @description A shipper's letter of instruction */
+  ShippersLetterOfInstruction = 'shippers_letter_of_instruction',
+  /** @description A declaration document */
+  Declaration = 'declaration',
+}

package/src/models/documents/uploads/index.ts

@@ -0,0 +1,4 @@
+export * from './document-upload-format';
+export * from './document-upload-format-schema';
+export * from './document-upload-type';
+export * from './document-upload-type-schema';

package/src/models/index.ts

@@ -33,7 +33,6 @@ export * from './time-window-schema';
 export * from './time-window';
 export * from './tracking';
 export * from './units';
-export * from './seller-documents';
 export * from './bill-to';
 export * from './labels/paperless-details';
 export * from './native-rating-details';

package/src/requests/index.ts

@@ -19,4 +19,4 @@ export * from './void-labels-request';
 export * from './update-settings-request';
 export * from './start-tracking-request';
 export * from './start-tracking-request-schema';
-export * from './upload-documents-request';
+export * from './upload-document-request';

package/src/requests/upload-document-request.ts

@@ -0,0 +1,22 @@
+import { BaseRequest } from './base-request';
+import { Identifier, DocumentUploadFormat, DocumentUploadType } from '../models';
+
+/**
+ * A request to upload a document for a shipment.
+ */
+export class UploadDocumentRequest extends BaseRequest {
+  /** @description The document id */
+  document_id!: string;
+  /** @description The document upload type */
+  document_type!: DocumentUploadType;
+  /** @description The document upload format */
+  document_format!: DocumentUploadFormat;
+  /** @description The file name */
+  file_name!: string;
+  /** @description The file URL */
+  file_url!: string;
+  /** @description The carrier tracking number for this shipment */
+  tracking_number!: string;
+  /** @description Non-tracking alternative ids associated with this shipment */
+  alternative_identifiers?: Identifier[];
+}

package/src/responses/index.ts

@@ -35,7 +35,5 @@ export * from './update-settings-response-schema';
 export * from './update-settings-response';
 export * from './start-tracking-response';
 export * from './start-tracking-response-schema';
-export * from './seller-document-result';
-export * from './upload-document-result-schema';
-export * from './upload-documents-response-schema';
-export * from './upload-documents-response';
+export * from './upload-document-response';
+export * from './upload-document-response-schema';

package/src/responses/upload-document-response-schema.ts

@@ -0,0 +1,6 @@
+import Joi from 'joi';
+import { BaseResponseSchema } from './base-response-schema';
+
+export const UploadDocumentResponseSchema = BaseResponseSchema.keys({
+  carrier_document_id: Joi.string().optional().empty(''),
+});

package/src/responses/upload-document-response.ts

@@ -0,0 +1,9 @@
+import { BaseResponse } from './base-response';
+
+/**
+ * Response for uploading a document to a carrier.
+ */
+export class UploadDocumentResponse extends BaseResponse {
+  /** @description The carrier document ID */
+  carrier_document_id?: string;
+}