Send a CBDS Manifest File via SFTP¶

Overview¶

If you cannot use the Create Shipment API to provide parcel data to Pitney Bowes, then you must send a manifest file via SFTP. This option is not available for all CBDS shipments.

Send a Manifest File to Pitney Bowes¶

Create a JSON manifest file that contains all the parcels shipped to the CBDS Hub. Follow the File-Based Integration Specification, downloadable here. Name the file according to the Naming Convention described below on this page.
Upload the manifest file to the SFTP server.

After the file is uploaded, Pitney Bowes processes the records line-by-line and returns one of the following:
- If the file is processed successfully, Pitney Bowes returns a file with the same name but with the .ok extension. The OK file contains the following information:
  - Date-Time Stamp: The date and time in UTC/GMT that the file was processed.
  - Number of Records: The total number of records successfully processed.
- If the file contains errors, Pitney Bowes returns a file with the same name but with .err extension. The error file contains the following pieces of information:
  - Date-Time Stamp: The date and time in UTC/GMT that the data record was processed.
  - Record Number: The line number in the file for the record in error.
  - Error Code: A predefined code (e.g. INVALID_FILE_FORMAT) that identifies an error. An UNKNOWN or NULL value may be specified if the error is not known, or if the error is undefined.
  - Details: An optional field carrying additional information about the error. This field may carry a brief error description (especially when the error code is unavailable) or the original input record as a reference.
  - Context_Field_Name: An optional field containing a field name in error.
  - Context_Field_Value: An optional field containing the value of a field name in error.
- If the file format is wrong or does not conform to the naming convention, or if the file does not parse, Pitney Bowes rejects the file.
If you receive an .err file, submit a replacement file for the shipment notification. In this replacement file, submit only the fixed records; that is, records that were in error in the original file. Do not submit partial updates for these error records.
If you receive an .ok file, there are no errors in your file, and your shipment notifications have been fully received. To avoid clutter in your inbound folder, mark all .ok files as “processed” and move the files to an archive folder.

Manifest File Exchange Process¶

The following diagram depicts an overview of the manifest file exchange process, highlighting the touch points between you and Pitney Bowes.

Naming Convention for the CBDS Manifest File¶

Data, message, and log files transferred between you and Pitney Bowes use the following file-naming convention:

<sender_id>_<data_feed_name>_<operation>_<recipient_id>_<utc_date_time>_<random_6_digits>.<file_extension>

Where:

<sender_id>	A pre-authorized business ID that identifies your business.
<data_feed_name>	Name of the data feed. Possible values are: `shipment-details`: Shipment manifest file generated by you. `transaction-details`: Transaction details feed generated by Pitney Bowes. `shipment-response`: Shipment response feed for successfully processed records in the manifest file. `tracking-update`: Tracking file feed generated by Pitney Bowes.
<operation>	The operation to perform. Possible values are: `update` – Records will be updated if exist by the given primary key, otherwise inserted. `delete` – Records exist by the given primary key will be removed, otherwise ignored.
<recipient_id>	A pre-authorized business ID that identifies Borderfree. For example, `16061`.
<utc_date_time>	The date and time in UTC/GMT that the data file was published, defined in the following format: `YYYYMMDD`
<random_6_digits>	A 6-digit random number that ensures that the file name is unique.
<file_extension>	File extension that identifies the file type/format. This must be `zip`, `csv`, or `json`.

Example File Names¶

The following table provides example file names. In the examples, the <sender_id> is GS00001:

From / To	Data Feed Name	Example File Name
From you to Pitney Bowes	`shipment-details`	GS00001_shipment-details_update_16061_20210427_131530_123456.json
From you to Pitney Bowes	`category-tree`	GS00001_category-tree_update_16061_20210427_131530_123456.json
From Pitney Bowes to you	`tracking-update`	16061_tracking-update_update_GS00001_20210427_140346_966998.csv
From Pitney Bowes to you	`tx-details`	16061_tx-details_update_GS00001_20210427_140346_966998.csv