# Upload Electronic Trade Document

Electronic Trade Documents Upload API is an international shipping document upload solution that simplifies global shipping needs and allows you to electronically upload customs documentation required for international shipments.
You can submit most of your trade documents electronically relieving yourself from printing or attaching trade documents with the shipment. <br/>
This API simplifies and accelerates customs clearance by replacing physical paperwork with electronic documentation.<br/>
The customs and other agencies receive electronically sent documents faster than paper copies attached with your shipment. The customs clearance process is also optimized as capturing and sharing of critical trade information is done at earlier stages of shipping.
> Note:

- FedEx supports ETD with the special service `ELECTRONIC_TRADE_DOCUMENTS`.
- DHL Express supports ETD with the special service `PAPERLESS`.
- In certain scenarios, the originals of specific international documents still need to be attached to the package.
- For smooth customs clearance and to avoid delays, ensure that the documents are visually clear and not distorted in any way.

**How the Workflow Operates**<br/>
**Step 1: Submit Electronic Trade Document Metadata**<br/>
Initiate the process by making a POST request to the ETD Upload API with the document metadata (e.g., file name, document type, and content type).<br/>
In response, the system returns:<br/>
- A pre-signed S3 upload URL (url)<br/>
- A fileName<br/>
- A relative `s3FileId` used to reference the uploaded document later<br/>

**Step 2: Upload the Document File**<br/>
After receiving the response, you must perform a separate HTTP PUT request to the provided [url](https://docs.shipping360.pitneybowes.com/openapi/shipping/operation/uploadETD/#!c=200&path=url&t=response).<br/>
- This request must upload the binary content of the file (e.g., PDF or image)<br/>
- Upload the same file whose metadata was submitted in step-1 <br/>

**Step 3: Reference the Document in Shipment Creation**<br/>
Once the ETD uploaded successfully, the document is stored in the S3 bucket.<br/>
- Once uploaded, the document is stored in the S3 bucket and can later be referenced via the `s3FileId` in [Create International Shipment API](https://docs.shipping360.pitneybowes.com/openapi/shipping/operation/createShipment/#!path=1/customs/customsDocuments&t=request)  under `customsDocuments` object.

Endpoint: POST /api/v1/importUrl
Version: 1.0.0
Security: bearerAuth

## Request fields (application/json):

  - `carrierAccountId` (string, required)
    A unique identifier for the carrier account to which the document will be uploaded.
    Example: vO396rorMdxZ8k1

  - `shipmentDocuments` (array, required)
    List of electronic trade documents to be uploaded for the shipment.

  - `shipmentDocuments.fileName` (string, required)
    The name of the file to be uploaded.

  - `shipmentDocuments.format` (string, required)
    The format of the file to be uploaded.
    Enum: "PDF"

  - `shipmentDocuments.documentType` (string, required)
    Type of the electronic trade document to be uploaded .
    Enum: "INVOICE", "COMMERCIAL_INVOICE", "PROFORMA_INVOICE", "CERTIFICATE_OF_ORIGIN", "NAFTA_CERTIFICATE_OF_ORIGIN", "CUSTOMS_DECLARATION_FORM", "AIR_WAYBILL_AND_WAYBILL"

  - `shipmentDocuments.contentType` (string, required)
    Content type of the file to be uploaded.
    Example: DOCUMENT_REFERENCE

## Response 200 fields (application/json):

  - `fileName` (string)
    The original name of the electronic document to be uploaded.
    Example: invoice.pdf

  - `s3FileId` (string)
    The internal relative file path in the S3 bucket. This ID is used when referencing the document in the `customsDocuments` object during [shipment creation](/openapi/shipping/shipment/createshipmentv2).
    Example: uploads/shipping/intl_docs/.../invoice.pdf

  - `url` (string)
    A pre-signed Amazon S3 URL used to upload the actual binary file via an HTTP PUT request.
This URL is securely generated by the server. It allows direct upload to the S3 bucket **without requiring AWS credentials or additional authentication**. 
To complete the document upload process:
- Copy the URL and create a new request to this URL.
- Perform an HTTP PUT request to this URL.
- Set the request body to the binary content and select the same file whose  metadata was previously submitted.
Once the upload is complete, the document is stored in the specified S3 location and can be referenced later using the `s3FileId`.
    Example: https://s3-url-with-signature

## Response 400 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due to HTTP  400- Invalid or Bad Request, e.g., validation-error.
    Example: validation_error

  - `errorDescription` (string)
    The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
    Example: string

  - `additionalCode` (string)
    A unique identifier for the error, for example 1101055, 0100008, or 1021126.

  - `additionalInfo` (string)
    This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceID, or if the information is missing.

  - `additionalParameters` (array)

## Response 401 fields (application/json):

  - `message` (string, required)
    This is HTTP 401 Unauthorized response status code, which indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.

## Response 404 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due HTTP 404 Page or File not found.
    Example: not_found

  - `errorDescription` (string)
    The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource.
    Example: resource not found

  - `additionalCode` (string)
    A unique identifier for the error, for example 0100025, 1110017, or 1090001.

  - `additionalInfo` (string)
    Additional information about the error. This error 'Not Found' might appear due to `Shipment Not Found`, `No Shipments to close`, or `Original Transaction not found`.

  - `additionalParameters` (array)

## Response 500 fields (application/json):

  - `message` (string, required)
    This is HTTP 500 Internal Server Error response status code, which indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.