The API returns standardized responses depending on the requested route.

Responses

The following response status is used for all the API communication.

200: successful

The request was successful.

{
  // a resource or array of resources depending on the endpoint...
}

201: created

A new resource is created.

{
  // a resource depending on the endpoint...
}

401: unauthenticated

The request was not completed due to invalid credentials.

{
  "message": "Unauthenticated."
}

403: forbidden

The (authenticated) request was not valid for the given endpoint.

{
  "reason": "General error.",
  "messages": [
    "Forbidden."
  ]
}

404: not found

The requested endpoint/resource was not found.

{
  "reason": "General error.",
  "messages": [
    "Record not found."
  ]
}

405: method not allowed

The method used is not valid for the request.

{
  "reason": "General error.",
  "messages": [
    "Method not allowed."
  ]
}

410: gone

The signed URL expired for the request.

{
  "reason": "General error.",
  "messages": [
    "Signature invalid or expired."
  ]
}

422: unprocessable entity

The given data is invalid due to validation errors.

{
  "reason": "Validation errors.",
  "messages": [
    "The selected consignments.0.associationType is invalid."
  ]
}

429: too many requests

Too many requests are sent.

{
  "reason": "General error.",
  "messages": [
    "Too many attempts."
  ]
}

Learn more about the rate limits on the viaTYGO API endpoints.

500: internal server error

There was an internal server error while processing the request.

When a list of objects is returned, for example, a list of TransportOrders for a company, it will be paginated. Because there is nothing standardized, we use the default Laravel pagination response.

Example paginated response:

{
  data: [
    {
      // transport order resources #1...
    },
    {
      // transport order resources #2...
    }
  ],
  "links": {
    "first": "https://otm.viatygo.com/v5/transportOrders?page=1",
    "last": "https://otm.viatygo.com/v5/transportOrders?page=5",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://otm.viatygo.com/v5/transportOrders?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://otm.viatygo.com/v5/transportOrders",
    "per_page": 10,
    "to": 10,
    "total": 49
  }
}

The differences compared to the other API endpoints:

all data is wrapped inside a data-key
there are links linking to the next page(s)
meta-information about the pagination is given inside the meta-key
all paginated responses have 10-objects per page

Debugging

When you want to request support on the API requests, please provide the given Request-Id from the response you got from the endpoints. This is a unique ID to identify & debug the specific API request.