UPS-API/api-documentation

Rates: Incompatible types returned on response props

Opened this issue · 0 comments

In the rate response (RATEResponseWrapper) there are two nested props that have types that are not properly documented when compared with what the server is providing.

TransactionReference Property

First is the RATEResponseWrapper.RateResponse.Response.TransactionReference prop.
The docs (yaml OAPI spec) of Apr 2024 says it is the following:

TransactionReference: "$ref": "#/components/schemas/Request_TransactionReference"
...
Request_TransactionReference:
  type: object
  maximum: 1
  properties:
    CustomerContext:
      description: May be used to synchronize request/response pairs. Information in the request element is echoed back in the response.
      type: string
      minLength: 1
      maxLength: 512
      maximum: 1
  xml:
    name: TransactionReference
  description: TransactionReference identifies transactions between client and server.
...

However when I make a basic rate request from Postman I get back:

{
  "RateResponse": {
      "Response": {
          ...
          "TransactionReference": {
              "TransactionIdentifier": "XXXXXXXXXXXXXXXXXXXXXX"
          }
      },
...

As you can see when comparing the docs to the actual server response, the TransactionReference contains a different property inside.

Rated Shipment

Next is the RATEResponseWrapper.RateResponse.RatedShipment property. The same YAML spec (mentioned above) says that in v2403 this is always an array but I still receive it as an object:

Docs

RateResponse:
      ...
            **NOTE:** For versions >= v2403, this element will always be returned as an array. For requests using versions < v2403, this element will be returned as an array if there is more than one object and a single object if there is only 1.
          type: array
          items:
            "$ref": "#/components/schemas/RateResponse_RatedShipment"
      xml:
        name: RateResponse
      description: Rate Response Container.
      maximum: 1

# further down
RateResponse_RatedShipment:
  type: object
  properties:
    Disclaimer:
      description: |
        Disclaimer is used to provide more information to the shipper regarding the processed shipment. It is used to notify the shipper about possible taxes and duties that might have been added or might apply to the shipment. Refer to the Appendix for various disclaimers. This field may be returned only if TaxInformationIndicator is present in the request.
  
        **NOTE:** For versions >= v2403, this element will always be returned as an array. For requests using versions < v2403, this element will be returned as an array if there is more than one object and a single object if there is only 1.
      type: array
...

Response

{
    "RateResponse": {
         ...
         "RatedShipment": {
            "Service": {
         ...

RatedShipment in the response is an object not an array. (I am using v2403)

I'm really trying to get my previous implementation moved over before the deadline so fast action on this is very much appreciated.