Upload Documents

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

In order to upload the documents to eBay we will have to use the Media API and store each document id in Hemi which we will use in the other product calls. We want to make the process as seamless as possible so we want to introduce the same logic like we have for eBay videos. We want to get all unique eBay documents urls from Account Marketplace eBay > Document OR Product Account eBay > Document and store them in a separate table called eBay Documents where we want to have the Document URL, Document Type, Document Id and Document Status after we upload it to eBay.

eBay Documents

So the whole flow will look like we will have all the document urls added in the Account and Product Account eBay and we want to get all unique urls and store them in eBay Documents without the ids. Once we have the unique document URLs in the eBay Documents we can start uploading them. The flow consists of two steps Create Document and Upload Document which it is up to the dev team if we shall add into a single flow or have two separate flows. There is not actual response reader but we can check the document status using the Get Document call which we will use to track the status and store and errors.

The first step is to obtain the document id with the CreateDocument call.

Create Document

The trigger will be Listing > List Update The Whole Item = Pending which will check if we have URLs for that product and will start uploading them. Once the everything is uploaded we will push the update to eBay. If we receive an error during the document upload we will set error status on the listing.

For each unique url we want to generate a documentId which will allow us to upload the document afterwards. So we have to pick each separate document individually and generate the documentId.

API Call: POST [https://api.ebay.com/commerce/media/v1_beta/document](https://api.ebay.com/commerce/media/v1_beta/document) API Docs: https://developer.ebay.com/api-docs/commerce/media/resources/document/methods/createDocument

Sample Request: **POST [https://api.ebay.com/commerce/media/v1_beta/document](https://api.ebay.com/commerce/media/v1_beta/document)

Sample Body:

{
  "documentType": "DocumentTypeEnum : [CERTIFICATE_OF_ANALYSIS,CERTIFICATE_OF_CONFORMITY,DECLARATION_OF_CONFORMITY,INSTRUCTIONS_FOR_USE,OTHER_SAFETY_DOCUMENTS,SAFETY_DATA_SHEET,TROUBLE_SHOOTING_GUIDE,USER_GUIDE_OR_MANUAL,INSTALLATION_INSTRUCTIONS]",
  "languages": [
    "LanguageEnum"
  ]
}

Mapping:

This is a document provided by the manufacturer or a qualified third-party laboratory that confirms the product has been tested and meets the specified criteria. CERTIFICATE_OF_CONFORMITY This certificate is issued by a manufacturer or a certification body to declare that a product meets all the required safety and regulatory standards. DECLARATION_OF_CONFORMITY This is a document self-issued by a manufacturer declaring that their product complies with all the relevant requirements of the GPSR and other applicable regulations and standards. INSTRUCTIONS_FOR_USE These are detailed directions provided by the manufacturer that inform the consumer on how to use the product correctly and safely. OTHER_SAFETY_DOCUMENTS This could refer to any additional safety-related documentation that accompanies a product. This may include safety warnings, emergency procedures, information on safe storage and handling, or any other relevant safety information that doesn't fall into the other specified categories. SAFETY_DATA_SHEET This is a detailed document that provides information on the properties of a chemical product. It includes information on the potential hazards (health, fire, reactivity, and environmental), safe handling practices, and emergency control measures (for example, fire-fighting). TROUBLE_SHOOTING_GUIDE This guide helps users diagnose and resolve problems that they may encounter with a product. USER_GUIDE_OR_MANUAL A user guide or manual is a comprehensive resource that includes all the necessary information for consumers to understand and operate the product. INSTALLATION_INSTRUCTIONS These are step-by-step instructions provided by the manufacturer that detail how to properly install a product. | | languages | Account > Ebay Marketplace | Yes | We want to provide a mapping based on the country as follows: eBay Australia - ENGLISH eBay France - FRENCH eBay Germany - GERMAN eBay Ireland - ENGLISH eBay Italy - ITALIAN eBay Motors - OTHER eBay Netherlands - DUTCH eBay Spain - SPANISH eBay UK - ENGLISH eBay United States - ENGLISH We want to push the value based on the mapping. |

Sample Request:

{
    "languages": [
        "ENGLISH"
    ],
    "documentType": "USER_GUIDE_OR_MANUAL"
}

Sample Response:

{
"documentId": "33d7965e-eb8c-4115-8158-e64985ba044f",
"languages":[
"ENGLISH"
],
"documentStatus": "PENDING_UPLOAD",
"documentType": "USER_GUIDE_OR_MANUAL"
}

Response Mapping:

If we have "documentStatus": = "PENDING_UPLOAD" and eBay Documents > eBay Id this means we are ready to upload the document using Upload Document call.

Upload Document

All Documents with "documentStatus": = "PENDING_UPLOAD" and populated eBay Documents > eBay Id are ready for upload and we want this to be the trigger for upload documents.

API Call: POST https://api.ebay.com/commerce/media/v1_beta/document/[documentId]/upload API Docs:https://developer.ebay.com/api-docs/commerce/media/types/api:DocumentTypeEnum

Sample Request: POST [https://api.ebay.com/commerce/media/v1_beta/document/dbfdb630-9621-447d-8562-4040f0686463/upload](https://api.ebay.com/commerce/media/v1_beta/document/dbfdb630-9621-447d-8562-4040f0686463/upload)

Sample Body:

Note:You must use a Content-Type header with its value set to multipart/form-data

This call does not have a JSON Request payload but uploads the file as form-data. For example:

file: @"/C:/Users/.../drone_user_warranty.pdf"

File should be picked from the eBay Douments > URL

Sample Response:

{
    "documentId": "dbfdb630-9621-447d-8562-4040f0686463",
    "languages": [
        "ENGLISH"
    ],
    "documentStatus": "SUBMITTED",
    "documentType": "USER_GUIDE_OR_MANUAL",
    "documentMetadata": {
        "fileName": "test.pdf",
        "fileType": "application/pdf",
        "fileSize": "71222"
    }
}

Response Mapping:

If we have "documentStatus":= "SUBMITTED" this means we have uploaded the document successfully and this is our final status. However we can receive different statuses which we should be aware and know how to treat thus we need to use the Get Documents call to get the correct document status.

Get Document

All Documents with "documentStatus" different from "SUBMITTED" should be obtained and checked.

API Call: GET [https://api.ebay.com/commerce/media/v1_beta/document/{document_id}](https://api.ebay.com/commerce/media/v1_beta/document/%7Bdocument_id%7D) API Docs: https://developer.ebay.com/api-docs/commerce/media/resources/document/methods/getDocument

Sample Request: GET https://api.ebay.com/commerce/media/v1_beta/document/dbfdb630-9621-447d-8562-4040f0686463

Sample Body:N/A

Sample Response:

{
    "documentId": "dbfdb630-9621-447d-8562-4040f0686463",
    "languages": [
        "ENGLISH"
    ],
    "documentStatus": "ACCEPTED",
    "documentType": "USER_GUIDE_OR_MANUAL",
    "documentMetadata": {
        "fileName": "test.pdf",
        "fileType": "application/pdf",
        "fileSize": "71222"
    }
}

Response Mapping:

Please note if we have the same status we want to ignore it and do not update it.