FedEx: Combined Commercial Invoice + USMCA Certification of Origin, with optional signature image

[minchaminder]

Related to #859

We need to generate a Commercial Invoice together with a USMCA/CUSMA Certification of Origin via FedEx. FedEx supports stamping a signature image on these docs, but it should be optional. If no signature is provided, FedEx should still generate valid unsigned documents.

What we send to FedEx (high level)

• customsClearanceDetail.regulatoryControls includes USMCA.
• Each commodity has usmcaDetail.originCriterion.
• shippingDocumentSpecification.shippingDocumentTypes includes USMCA_COMMERCIAL_INVOICE_CERTIFICATION_OF_ORIGIN.
• Provide usmcaCommercialInvoiceCertificationOfOriginDetail with certifier/producer details and document format.
• ETD alignment: shipmentSpecialServices.etdDetail.requestedDocumentTypes includes USMCA_COMMERCIAL_INVOICE_CERTIFICATION_OF_ORIGIN.

Signature handling: optional

If a signature image is uploaded, reference it via customerImageUsages. If not uploaded, omit customerImageUsages entirely. FedEx will generate the docs without a signature.

1) Uploading the signature image (Document API)

This is the upload we use:

• Endpoint: POST https://documentapi.prod.fedex.com/documents/v1/lhsimages/upload

• Auth: OAuth2

• Headers:

  • x-customer-transaction-id: 12345

• Body: multipart form-data with:

  • document: JSON describing the image and where it will be referenced later
  • attachment: the actual image file

Example

POST /documents/v1/lhsimages/upload HTTP/1.1
Host: documentapi.prod.fedex.com
Authorization: Bearer <token>
x-customer-transaction-id: 12345
Content-Type: multipart/form-data; boundary=BOUNDARY

--BOUNDARY
Content-Disposition: form-data; name="document"
Content-Type: application/json

{
  "document": {
    "referenceId": "1234",
    "name": "LH2.PNG",
    "contentType": "image/png",
    "meta": {
      "imageType": "SIGNATURE",
      "imageIndex": "IMAGE_1"
    }
  },
  "rules": {
    "workflowName": "LetterheadSignature"
  }
}
--BOUNDARY
Content-Disposition: form-data; name="attachment"; filename="LH2.PNG"
Content-Type: image/png

<binary png bytes>
--BOUNDARY--

Expected success response includes:

{
  "output": {
    "meta": { "imageType": "SIGNATURE", "imageIndex": "IMAGE_1" },
    "documentReferenceId": "1234",
    "status": "SUCCESS"
  },
  "customerTransactionId": "12345"
}

Key notes:

• The image will later be referenced by its imageIndex value (e.g., IMAGE_1) in customerImageUsages.
• documentReferenceId confirms storage; we do not place it in the CI/CO request body for stamping. FedEx samples show using customerImageUsages with the id matching the imageIndex.

2) Using the signature on USMCA CO and/or CI (optional block)

Only include this if the upload has succeeded and you have the imageIndex (for example IMAGE_1). If no signature, omit this array.

With signature:

"shippingDocumentSpecification": {
  "shippingDocumentTypes": [
    "USMCA_COMMERCIAL_INVOICE_CERTIFICATION_OF_ORIGIN"
  ],
  "usmcaCommercialInvoiceCertificationOfOriginDetail": {
    "customerImageUsages": [
      {
        "id": "IMAGE_1",
        "type": "SIGNATURE",
        "providedImageType": "SIGNATURE"
      }
    ],
    "documentFormat": {
      "docType": "PDF",
      "stockType": "PAPER_LETTER",
      "dispositions": [{ "dispositionType": "RETURNED" }]
    },
    "certifierJobTitle": "Shipping Manager",
    "certifierSpecification": "EXPORTER",
    "importerSpecification": "UNKNOWN",
    "producerSpecification": "SAME_AS_EXPORTER",
    "producer": { "...": "..." }
  }
}

Without signature:

"shippingDocumentSpecification": {
  "shippingDocumentTypes": [
    "USMCA_COMMERCIAL_INVOICE_CERTIFICATION_OF_ORIGIN"
  ],
  "usmcaCommercialInvoiceCertificationOfOriginDetail": {
    "documentFormat": {
      "docType": "PDF",
      "stockType": "PAPER_LETTER",
      "dispositions": [{ "dispositionType": "RETURNED" }]
    },
    "certifierJobTitle": "Shipping Manager",
    "certifierSpecification": "EXPORTER",
    "importerSpecification": "UNKNOWN",
    "producerSpecification": "SAME_AS_EXPORTER",
    "producer": { "...": "..." }
  }
}

If we also want the signature stamped on the plain Commercial Invoice, we add the same customerImageUsages array to shippingDocumentSpecification.commercialInvoiceDetail.

Proposal for karrio

• Add a way to request combined CI + USMCA CO in the FedEx mapper:

  • Flag like include_usmca_co: true.
  • Optional signature_image_id (string, e.g., IMAGE_1). If provided, injects customerImageUsages for both the USMCA CO and CI docs. If omitted, no signature block is added.

• Validate that when include_usmca_co: true:

  • customsClearanceDetail.regulatoryControls contains USMCA.
  • Each commodity includes usmcaDetail.originCriterion.
  • ETD requestedDocumentTypes includes USMCA_COMMERCIAL_INVOICE_CERTIFICATION_OF_ORIGIN.

• Leave monetary and date fields untouched by this logic.

Questions

• Is there already an abstraction for combined CI + USMCA CO in karrio's FedEx provider?
• Preference for where to surface signature_image_id? Shipment options vs document options?
• Any objections to omitting customerImageUsages entirely when no signature is present?

Thanks!