From 04caf20655990ec4ccccb23a3d5f927e1ff227ff Mon Sep 17 00:00:00 2001
From: Skylar Ittner <skylar@netsyms.com>
Date: Sun, 26 Nov 2023 00:17:34 -0700
Subject: [PATCH] Update 'Specification'

---
 Specification.md | 76 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 64 insertions(+), 12 deletions(-)

diff --git a/Specification.md b/Specification.md
index 1173d51..c610735 100644
--- a/Specification.md
+++ b/Specification.md
@@ -3,7 +3,7 @@
 * The barcode shall be in QR Code, DataMatrix, or PDF417 format.
 * Data fields shall be delineated with a pipe character (`|`).
 * Data shall be encoded as ASCII or UTF-8. If the chosen barcode format has a different default/preferred encoding, that encoding may be used instead.
-* Data fields shall not include a pipe character or newline.
+* Data fields shall not include a newline, or a `|`, `=`, or `+` character.
 * The data must not start or end with a pipe character.
 * Most fields are not strictly required and may be left empty when not needed. Implementations may reject a code with insufficient data.
 
@@ -11,19 +11,16 @@
 
 All barcodes shall start with `QSv1` as the first field. The second field shall specify the subtype of the barcode.
 
-### Subtypes
-
-* `tofrom`: Destination and return addresses only.
-* `full`: Same as `tofrom` but with additional fields for the package's characteristics and requested extra services.
-
 ## Data Fields
 
-### `tofrom`
+### Subtype `a`
+
+Basic to/from address data only.
 
 Position | Meaning
 ---------|--------
 0 | Format header (`QSv1`)
-1 | Type header (`tofrom`)
+1 | Subtype header (`a`)
 2 | Sender/payer account number (vendor/implementation specific)
 3 | To name
 4 | To company/firm/business
@@ -47,11 +44,13 @@ Position | Meaning
 22 | From email
 
 
-### `full`
+### Subtype `p`
+
+Contains address data, plus parcel information and options.
 
 Position | Meaning
 ---------|--------
-0 - 22 | See `tofrom`
+0 - 22 | See `a`
 23 | Weight (U.S. ounces)
 24 | Item type (see appendix)
 25 | Length (inches)
@@ -66,11 +65,45 @@ Position | Meaning
 34 | Insurance amount, USD
 35 | Signature services. 1: Signature required, 2: Adult signature required, 3: Restricted delivery signature, 4: Adult restricted signature, 5: Indirect signature.
 
+### Subtype `ac`
+
+Address data plus customs form.
+
+Position | Meaning
+---------|--------
+0 - 22 | See `tofrom`
+23 | Customs contents type: "documents", "gift", "merchandise", "returned_goods", "sample", "dangerous_goods", "humanitarian_donation", or "other" (this field always required)
+24 | Customs form signer name (electronically sign the form)
+25 | Non-delivery option: `r` or `a` for return or abandon, respectively. Default if empty is `r`.
+26 | Explanation of contents (required if field 23 is "other")
+27 | Restriction type (empty, "other", "quarantine", or "sanitary_phytosanitary_inspection")
+28 | Restriction comments (required if field 27 is not empty)
+29 | EEL/PFC: Use "NOEEI 30.37(a)" for most shipments under $2,500. Otherwise, use the shipment's Automated Export System (AES) Internal Transaction Number (ITN).
+30 | Customs items. See appendix for format.
+
+
+### Subtype `pc`
+
+Address data, parcel information, and customs form.
+
+Position | Meaning
+---------|--------
+0 - 22 | See `a`
+23-35 | See `p`
+36 | Customs contents type: "documents", "gift", "merchandise", "returned_goods", "sample", "dangerous_goods", "humanitarian_donation", or "other" (this field always required)
+37 | Customs form signer name (electronically sign the form)
+38 | Non-delivery option: `r` or `a` for return or abandon, respectively. Default if empty is `r`.
+39 | Explanation of contents (required if field 36 is "other")
+40 | Restriction type (empty, "other", "quarantine", or "sanitary_phytosanitary_inspection")
+41 | Restriction comments (required if field 40 is not empty)
+42 | EEL/PFC: Use "NOEEI 30.37(a)" for most shipments under $2,500. Otherwise, use the shipment's Automated Export System (AES) Internal Transaction Number (ITN).
+43 | Customs items. See appendix for format.
+
 ## Appendix
 
 ### Item Types
 
-The following values are allowed for field 24 in a `full` type code:
+The following values are allowed for field 24 in a `parcel` type code:
 
 * (empty) when a custom size and weight item is being shipped
 * Card
@@ -102,4 +135,23 @@ The following values are allowed for field 24 in a `full` type code:
 * FedExSmallBox
 * FedExMediumBox
 * FedExLargeBox
-* FedExExtraLargeBox
\ No newline at end of file
+* FedExExtraLargeBox
+
+### Customs Items
+
+The customs items field contains multiple rows of data, with several fields per row.
+
+Rows are delineated with `=`. Fields inside a row are delineated with `+`.
+
+Following is a chart of the field positions within a customs item row.
+
+All fields are required.
+
+Position | Meaning
+---------|--------
+0 | Human readable item description
+1 | Quantity of item
+2 | Value of item in USD (quantity * value of a single item)
+3 | Weight of the item in ounces (quantity * weight of single item)
+4 | Harmonized Tariff Schedule number
+5 | Country of origin as two-character ISO country code
\ No newline at end of file