# UPS Shipping

### UPS Shipping

For accessing the UPS-Shipping Gebra Suite interface, the UPS services need the following setup values (configuration -> settings).

* **UPSBillingAccountNumber** billing account number for your UPS profile
* **UPSAppClientID** client id for your OAuth2 app
* **UPSAppClientSecret** client secret for your OAuth2 app

### CreateShipment

Creates a UPS shipping label

### Incoming Information

To create labels four groups of information are available:

* **1. Settings** with the following fields (If the group/field is not present default values will be assumed)
  * **ServiceCode:** default value "11" UPS Standard. Valid values according to UPS service codes.
  * **MetricMeasurements:** "1" sets to true. This is the default. Measurements will be metric (e.g. kg, cm or nonmetric for lbs, inch)
  * **Language:** Language code according to UPS. e.g. **deu**, **eng**, **spa**. This field will be set to user language by default. If the user language is not available for UPS, **eng** will be used.
* **2. Shipper:**
  * Name
  * Street
  * HouseNo
  * ZipCode
  * City
  * CountryCode
  * StateProvinceCode
  * AttentionName
  * Phone
  * EMail
  * FaxNumber
  * TaxIdentificationNumber
* **3. ShipAddress:**
  * Name
  * Street
  * HouseNo
  * ZipCode
  * City
  * CountryCode
  * StateProvinceCode
  * AttentionName
  * Phone
  * EMail
  * FaxNumber
  * TaxIdentificationNumber
* **4. ParcelData:**
  * Description
  * **PackageType:** Package type according to UPS. If no value is given, the default will be set to: "02" _Customer Supplied Package_
  * Weight
  * Height
  * Length
  * Width

### Returning Information

* In case of **success (status 200)**, the following fields are returned
  * **ShipmentIdentificationNumber:** The UPS generated ID. This will be used for further references to this shipment.
  * **TrackingNumber:** The UPS generated ID, usually same as **ShipmentIdentificationNumber**, but may differ. This will be used for further references to this shipment.
  * **LabelData:** this is a blob response. It contains the actual label in PDF format and can be directly used for further processing. E.g. `app.printBlob(LabelData)`
* In case of **error (status 400)**, the following fields are returned:
  * **error:** a text showing the error. E.g. `console.log(result.error)`

### Example Usage

```javascript
var result = await app.businessFunction({
  functionName: "UPSShipping",
  methodName: "CreateShipment",
  Settings: {
    Language: "deu",
    MetricMeasurements: 1,
    ServiceCode: "11",
  },
  Shipper: {
    Name: "GEBRA-IT GmbH",
    Street: "Im Erdbeerfeld",
    HouseNo: "20",
    ZipCode: "52078",
    City: "Aachen",
    CountryCode: "DE",
  },
  ShipFromAddress: {
    Name: "GEBRA-IT GmbH",
    Street: "Im Erdbeerfeld",
    HouseNo: "20",
    ZipCode: "52078",
    City: "Aachen",
    CountryCode: "DE",
    Phone: "+49 1234 5678-9",
    EMail: "m.mustermann@mustermann.com"
  },
  ShipAddress: {
    Name: "GEBRA-IT GmbH",
    Street: "Im Erdbeerfeld",
    HouseNo: "20",
    ZipCode: "52078",
    City: "Aachen",
    CountryCode: "DE",
    Phone: "+49 1234 5678-9",
    EMail: "m.mustermann@mustermann.com",
  },
  ParcelData: {
    Description: "Product name",
    Height: 10,
    Length: 20,
    Width: 15,
    Weight: "4.5",
  },
});

console.log("Tracking Number: " + result.TrackingNumber);
app.printBlob(result.LabelData);
```

### CancelShipment

To cancel an existing shipment, **ShipmentIdentificationNumber** and **TrackingNumber** are needed.

```javascript
var result = await app.businessFunction({
  functionName: "UPSShipping",
  methodName: "CancelShipment",
  ShipmentIdentificationNumber: app.getFieldValue("ExistingShipmentIdentificationNumber"),
  TrackingNumber: app.getFieldValue("ExistingTrackingNumber"),
});
```

### GetLabel

In case the label is needed again, it can be retrieved with an existing **TrackingNumber**. The result will contain LabelData.

```javascript
var result = await app.businessFunction({
  functionName: "UPSShipping",
  methodName: "GetLabel",
  TrackingNumber: app.getFieldValue("ExistingTrackingNumber"),
});
```
