ConSol REST API

Version 1.12 Status: draft

 

Scope

This REST API is intended as a generically applicable collection of web services. Intended clients include:

  • ConSol Mobile applications (iOS and Android)
  • ConSol browser-based client (future AngularJS/ajax enhancements)
  • search service (a.k.a. operations dashboard)
  • customer system integrations
  • datamart extract/synchronisation service(s)

 

Events

Order, attachment and variation entity-related events are sent using the representation defined in the (W3C event source standard)[http://www.w3.org/TR/eventsource/]. Events are sent from the time the connection is made unless Last-Event-ID is specified.

Request:

GET /events?events=<entityName or eventName>[,<entityName or eventName>,...]
Last-Event-ID: <x>    // optionally used to restart an event stream from a known point

Response:

HTTP/1.1 200 OK
Content-Type: text/event-stream

id: 1
event: order/new
data: /orders/12345

id: 2
event: order/change
data: /orders/12345

...

Event name

Data

Description

attachment/new

attachment URI, parent URI

A new attachment has been created.

attachment/change

attachment URI, parent URI

An attachment attribute has changed (e.g. content has been uploaded).

order/new

order URI

An order is newly visible to the user.

order/change

order URI

An order attribute has changed.

order/remove

order URI

An order attribute has been removed.

order-items/change

order items URI

The order's items have changed.

order-notes/change

order notes URI

The order's notes have changed (i.e. there's a new note).

variation/new

variation URI

A new variation has been created.

variation/change

variation URI

A variation attribute has changed.

variation/remove

variation URI

A variation attribute has been remove.

Notes:

  • Suggested iOS client library: https://github.com/neilco/EventSource

 

 

Retrieve orders list

Request:

GET /orders[?includeCollections=(attachments,items,notes,scheduleItems,variations)+]
Accept: application/json

Parameter

Description

Default

includeCollections

Controls the inclusion of potentially large collections. One or more of these collection names may be included in a comma-separated list.

none

includeCollections value

Response will include...

attachments

An object listing all attachments included in the order.

items

An object listing all items included in the order.

notes

A notes object listing the order's notes.

scheduleItems

A scheduleItems object listing all schedule items associated with the order.

variations

An object listing the order's variation history.

Response (/orders):

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

[
  {
    uri:  "/orders/12345[?includeCollections=(attachments,items,notes,scheduleItems,variations)+]",
    etag: "\"fjfJdaxz12D\""
  },
  ...
]

Notes:

  • The overall (HTTP header) ETag changes whenever the orders list changes, as expected from ETags.
  • The individual order ETags are identical to the ETag header that would be obtained from the respective order URI.
  • HTTP status code 304 will be returned if the ETag in the request matches the one from server.

 

Retrieve order

Request:

GET /orders/:id[?includeCollections=(attachments,items,notes,scheduleItems)+]
Accept: application/json

Parameter

Description

Default

includeCollections

Controls the inclusion of potentially large collections. One or more of these collection names may be included in a comma-separated list.

none

includeCollections value

Response will include...

attachments

An attachments object listing the order's attachments.

items

An items object listing all items included in the order.

notes

A notes object listing the order's notes.

scheduleItems

A scheduleItems object listing all schedule items associated with the order.

variations

An object listing the order's variation history.

Response (/orders/:id):

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

{
  orderId:    <string>,
  orderRefId: <string>,
  customer: {
    companyName: <string>
  },
  description:  <string>,
  specialInstructions: <string>,
  slaStatus:    <string>,
  address: {
    concatenatedAddress: <string>,
    suburb:              <string>,
    state:               <string>,
    postcode:            <string>
  },
  requestedByUser: {
    givenNames: <string>,
    surname:    <string>,
    phone:      <string>,
    email:      <string>
  },
  metadata: {
    <KEYNAME1>: <VALUE1>,
    ...
  },
  start:       <ISO 8601 date/time>,
  end:         <ISO 8601 date/time>,
  actionBy:    <ISO 8601 date/time>,
  workType:    <string>,
  updateDate:  <ISO 8601 date/time>,
  orderStatus: <string>,
  acquiredBy:  <string - user id>,
  geo:         { latitude: <number>, longitude: <number> }
  // attachments is only included for includeCollections=attachments
  attachments: {
    etag:             <string>,
    uri:              <string>,
    collection: [
      {
        uri:            <attachment uri>,
        etag:           <attachment etag>,
        parentUri:      <owning resource's URI>,
        contentUri:     <content URI>,
        contentEtag:    <ETag string as would be returned for contentUri>,
        thumbnailUri:   <thumbnail image URI>,                              // only when a thumbnail is present
        thumbnailEtag:  <ETag string as would be returned for contentUri>,  // only when a thumbnail is present
        createdDate:    <ISO 8601 date/time>,
        type:           "<document type>",
        // optional attributes below
        tags:           [ <string>, <string>, ... ],
        geo:            { latitude: <number>, longitude: <number> }
      },
      ...
    ]
  },
  attributes: {
    <ATTRNAME1>: { type: <string|number|date|enum>, value: <ATTRVALUE1>, editable: <boolean> },
    ...
  },
  complianceItems: [
    {
      uri: "/rest/orders/B123/complianceItems/LAC",
      code: "LAC",
      name:           <string>,                 // e.g. "LAC"
      description:    <string>,
      expiryDate:     <ISO 8601 date/time>,
      commencementDate: <ISO 8601 date/time>
    },
    ...
  ],
  // items is only included for includeCollections=items
  items: {
    etag:             <string>,
    uri:              <string>,
    collection: [
      {
        uri:            <individual item uri>,
        code:           <string>,
        description:    <string>,
        // item detail is the custom comments field on order item
        itemDetail:     <string>,
        orderedQty:     <number>,
        claimedQty:     <number>,
        deliveredQty:   <number>,
        usedQty:        <number>,
        unitOfMeasure:  <string>
        attributes: {
          <name>:       <string or number>,
          ...
        }
      },
      ...
    ]
  },
  // notes is only included for includeCollections=notes
  notes: {
    etag:               <string>,
    uri:                <string>,
    collection: [
      {
        uri:            <individual note uri>,
        created:        <ISO 8601 date/time>,
        creator:        <ConSol userid string>,
        creatorName:    <firstname surname string>,
        creatorCompany: <company name string>,
        type:           <misc|mobile>,
        body:           <string>,
        // optional attributes below
        subtype:        <string>,
        geo:            { latitude: <number>, longitude: <number> }
      },
      ...
    ]
  },
  // scheduleItems is only included for includeCollections=scheduleItems
  scheduleItems: {
    etag:               <string>,
    uri:                <string>,
    collection: [
      {
        code:           <string>,
        description:    <string>,
        unitOfMeasure:  <string>
      },
      ...
    ]
  },
  variations: {
    etag:               <string>,
    uri:                <string>,
    collection: [
      {
        uri:              <string>,
        etag:             <string>
      },
      ...
    ]
  }
}

Notes:

  • HTTP status code 304 will be returned if the ETag in the request matches the one from server.

 

Retrieve surveys list

Request:

GET /orders/:id/surveys
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

[
  {
    id:      <string>,
    created: <ISO 8601 date/time>,
    response: {
      <KEYNAME>: <VALUE>,
      ...
    }
  },
  ...
]

 

Update surveys

Request:

POST /orders/:id/surveys
Content-Type: application/json

{
  id:          <string>,
  created:     <ISO 8601 date/time>
  response: {
    <KEYNAME>: <VALUE>,
    ...
  },
  actions: {
    <KEYNAME(SOR Item ID)>: <VALUE(Quantity)>,
    ...
  }
},

 

Retrieve items

Request:

GET /orders/:id/items
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

[ {
    itemId:        <number>,
    // indicates the unique item sequence position, in this case, sequence no is the ConSol order item primary key.
    itemSeqNo:     <number>,
    description:   <string>,
    // item detail is the custom comments field on order item
    itemDetail:    <string>,
    orderedQty:    <number>,
    claimedQty:    <number>,
    deliveredQty:  <number>,
    usedQty:       <number>,
    unitOfMeasure: <string>,
    attributes: {
      <name>:      <string or number>,
      ...
    }
  },
  ...
]

Notes:

  • HTTP status code 304 will be returned if the ETag in the request matches the one from server.

 

Update items

Notes:

  • description, itemDetail, orderedQty, claimedQty and deliveredQty fields must be silently ignored by ConSol if received in the update items request.
  • HTTP status code 412 will be returned if the ETag in the request does not match the one from server.

Request:

PUT /orders/:id/items
Content-Type: application/json

[ {
    itemId:      <number>,
    // indicates the unique item sequence position, in this case, sequence no is the ConSol order item primary key.
    itemSeqNo:   <number>,
    usedQty:     <number>,
    attributes: {
      <name>:    <string or number>,
      ...
    }
  },
  ...
]

Response:

The full, updated items list is returned in response.

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

[ {
    itemId:      <number>,
    // indicates the unique item sequence position, in this case, sequence no is the ConSol order item primary key.
    itemSeqNo:   <number>,
    usedQty:     <number>,
    attributes: {
      <name>:    <string or number>,
      ...
    }
  },
  ...
]

 

Retrieve order schedule items

Request:

GET /orders/:id/scheduleItems
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

[
  {
    code:           <string>,
    itemType:       <string>,
    description:    <string>,
    unitOfMeasure:  <string>
  },
  ...
]

 

Update order

Request:

PUT /orders/:id
Content-Type: application/json

{
  // destination status, valid values are:
  // REFUS" when order is refused by supplier
  // ACVAR" when order is refused with variations agreed by supplier
  // NAC" when order is un-accepted by supplier
  // ALLOC" when order is accepted by user
  // DONE" when job is completed.
  orderStatus: <"REFUS"|"ACVAR"|"NAC"|"ALLOC"|"DONE">,
  acquiredBy:      <string>,
  // acceptanceGeo only applies when order is set to "ALLOC"
  acceptanceGeo:    { latitude: <number>, longitude: <number> },
  // rejectionReason/Geo only apply when order is set to "REFUS" or "ACVAR"
  rejectionReason:  <string>,
  rejectionGeo:     { latitude: <number>, longitude: <number> },
  // completionGeo only applies when order is set to "DONE"
  completionGeo:    { latitude: <number>, longitude: <number> },
  // uncompletionGeo only applies when order is set to "ALLOC"
  uncompletionGeo:    { latitude: <number>, longitude: <number> },
}

Response:

The full, updated order is returned in response.

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

{
  orderId:    <string>,
  orderRefId: <string>,
  customer: {
    companyName: <string>
  },
  description: <string>,
  specialInstructions: <string>,
  slaStatus: <string>,
  address: {
    concatenatedAddress: <string>,
    suburb:              <string>,
    state:               <string>,
    postcode:            <string>
  },
  requestedByUser: {
    givenNames: <string>,
    surname:    <string>,
    phone:      <string>,
    email:      <string>
  },
  metadata: {
    <KEYNAME1>: <VALUE1>,
    ...
  },
  start:       <ISO 8601 date/time>,
  end:         <ISO 8601 date/time>,
  workType:    <string>,
  updateDate:  <ISO 8601 date/time>,
  orderStatus: <string>,
  acquiredBy:  <string - user id>,
  geo:         { latitude: <number>, longitude: <number> }
  attributes: {
    <ATTRNAME1>: <ATTRVALUE1>,
    ...
  }
}

Notes:

  • HTTP status code 412 will be returned if the ETag in the request does not match the one from server.

 

Retrieve notes

Request:

GET /orders/:id/notes
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

[
  {
    uri:            <individual note uri>,
    created:        <ISO 8601 date/time>,
    creator:        <ConSol userid string>,
    creatorName:    <firstname surname string>,
    creatorCompany: <company name string>,
    type:           <misc|mobile>,
    body:           <string>,
    // optional attributes below
    subtype:        <string>,
    geo:            { latitude: <number>, longitude: <number> }
  },
  ...
]

Notes:

  • HTTP status code 304 will be returned if the ETag in the request matches the one from server.

 

Retrieve note

Request:

GET /orders/:id/notes/:noteid
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

{
  created:        <ISO 8601 date/time>,
  creator:        <ConSol userid string>,
  creatorName:    <firstname surname string>,
  creatorCompany: <company name string>,
  type:           <misc|mobile>,
  body:           <string>,
  // optional attributes below
  subtype:        <string>,
  geo:            { latitude: <number>, longitude: <number> }
}

Notes:

  • HTTP status code 304 will be returned if the ETag in the request matches the one from server.

 

Add a note

Request:

POST /orders/:id/notes
Content-Type: application/json

{
  created:        <ISO 8601 date/time>,
  type:           <misc|mobile>,
  body:           <string>,
  // optional attributes below
  subtype:        <string>,
  geo:            { latitude: <number>, longitude: <number> }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /orders/12345/notes/39
ETag: <ETag>

{
  created:        <ISO 8601 date/time>,
  creator:        <ConSol userid string>,
  creatorName:    <firstname surname string>,
  creatorCompany: <company name string>,
  type:           <misc|mobile>,
  body:           <string>,
  // optional attributes below
  subtype:        <string>,
  geo:            { latitude: <number>, longitude: <number> }
}

Note:

The creator is inferred from the API authentication credentials if not present and must match the authentication credentials (or effective-user if explicitly provided). Any supplied creatorName and creatorCompany fields must be ignored.

 

Retrieve attachments

Request:

GET /orders/:id/attachments?fields=<fieldName>[,<fieldName>,...]
Accept: application/json

Parameter

Description

fields

An optional comma-delimited list of attachment attribute names to include in the response. Defaults to all fields.

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

[
  {
    uri:            "<attachment uri>",
    etag:           "<attachment etag>",
    parentUri:      "<owning resource's URI>",
    contentUri:     "<content URI>",
    contentEtag:    "<ETag string as would be returned for contentUri>",
    thumbnailUri:   "<thumbnail image URI>",                              // only when a thumbnail is present
    thumbnailEtag:  "<ETag string as would be returned for contentUri>",  // only when a thumbnail is present
    createdDate:    "<ISO 8601 date/time>",
    type:           "<document type>",
    // optional attributes below
    tags:           [ "<string>", "<string>", ... ],
    geo:            { latitude: <number>, longitude: <number> }
  },
  ...
]

Notes:

  1. The ETag must change if the contentEtag attribute, or any other attribute in the response, has changed.
  2. A request that doesn't include the parentUris parameter should return all attachments accessible to the authenticated user.
  3. HTTP status code 304 will be returned if the ETag in the request matches the one from server.

 

Retrieve attachment

Request:

GET /orders/:id/attachments/:id (OR /orders/:orderId/variations/:variationId/attachments/:id)
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

{
  parentUri:                "<owning resource's URI>",  // e.g. "/orders/1234"
  contentUri:               "<content URI>",
  contentEtag:              "<ETag string as would be returned for contentUri>",
  thumbnailUri:             "<thumbnail image URI>",                              // only when a thumbnail is present
  thumbnailEtag:            "<ETag string as would be returned for contentUri>",  // only when a thumbnail is present
  name:                     "<image or document name>",
  createdDate:              "<ISO 8601 date/time>",
  type:                     "<document type>",
  // optional attributes below
  tags:                     [ "tag 1", "tag 2", ... ],
  geo:                      { latitude: <number>, longitude: <number> }
}

Note:

The ETag must change if the contentEtag attribute, or any other attribute in the response, has changed. HTTP status code 304 will be returned if the ETag in the request matches the one from server.

 

Create attachment on an order

Request:

POST /orders/:id/attachments
Content-Type: multipart/form-data; boundary=--xxxx

--xxxx
Content-Disposition: form-data; name="createdDate"
Content-Type: text/plain

<ISO 8601 date/time>
--xxxx
Content-Disposition: form-data; name="tags"
Content-Type: text/plain

<tag>,<tag>,<tag>
--xxxx
Content-Disposition: form-data; name="geo"
Content-Type: text/plain

<lat>,<lon>
--xxxx
Content-Disposition: form-data; name="thumbnail"; filename="<filename>.jpg"
Content-Type: image/jpeg

<binary image data>
--xxxx
Content-Disposition: form-data; name="content"; filename="<filename>.jpg"
Content-Type: <content media type>

<binary content data>
--xxxx--

Response:

HTTP/1.1 201 Created
Location: /orders/<orderId>/attachments/<id>
Content-Type: application/json
ETag: <ETag>

{
  parentUri:                "<owning resource's URI>",
  contentUri:               "<content URI>",
  contentEtag:              "<ETag string as would be returned for contentUri>",
  thumbnailUri:             "<thumbnail image URI>",                              // only when a thumbnail is present
  thumbnailEtag:            "<ETag string as would be returned for contentUri>",  // only when a thumbnail is present
  name:                     "<image or document name>",
  createdDate:              "<ISO 8601 date/time>",
  type:                     "<document type>",
  // optional attributes below
  tags:                     [ "<tag>", "<tag>", ... ],
  geo:                      { latitude: <number>, longitude: <number> }
}

 

Get attachment content

Request:

GET /orders/:orderId/attachments/:id/content OR
GET /orders/:orderId/variations/:variationId/attachments/:id/content

N.B. Do not rely on the above URI. Always obtain the content URI from the corresponding attachment metadata resource.

Response:

Content-Type: <depends on document>
ETag: <ETag>

<Text or binary body as per Content-Type.>

 

Retrieve variation

Request:

GET /orders/:orderId/variations/:variationId[?includeCollections=attachments]
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

{
  acknowledgedDate:          "2014-02-20T14:43:22Z",      // acknowledged date of variation on server side
  createdDate:               "2014-02-20T14:43:22Z",      // create date of variation on server side
  itemChanges: [
    {
      itemId:               <string>,                     // item id from schedule of rates (i.e. scheduleItems resource)
      itemSeqNo:            <number>,                     // only present for modified items; null for new items (orderItemNo)
      requestedQty:         <number>,                     // the new quantity being requested
      respondedQty:         <number>,                     // the new quantity being responded
      requestedPrice:       <number>,                     // the new price being requested (for variable price items)
      respondedPrice:       <number>,                     // the new price being responded (for variable price items)
      status:               "agreed" | "partial" | "new" | "rejected" // Order Item variation status
    },
      ...
  ],
  requestedDate:            "2014-02-20T14:43:22Z",       // requested date of variation on server side
  requestedReason:          <string>,                     // (optional, only available for current variation)
  requestor: {                                            // (optional, only available for current variation)
    name:                   <string>,
    phone:                  <string>
  },
  respondedDate:            "2014-02-20T14:43:22Z",       // responded date of variation on server side
  respondedReason:          <string>,                     // (optional, only available for current variation)
  status:                   "new" | "open" | "resolved" | "closed",
  // attachments is only included for includeCollections=attachments
  attachments: {
    etag:             <string>,
    uri:              <string>,
    collection: [
      {
        uri:            <attachment uri>,
        etag:           <attachment etag>,
        parentUri:      <owning resource's URI>,
        contentUri:     <content URI>,
        contentEtag:    <ETag string as would be returned for contentUri>,
        thumbnailUri:   <thumbnail image URI>,                              // only when a thumbnail is present
        thumbnailEtag:  <ETag string as would be returned for contentUri>,  // only when a thumbnail is present
        createdDate:    <ISO 8601 date/time>,
        // optional attributes below
        tags:           [ <string>, <string>, ... ],
        geo:            { latitude: <number>, longitude: <number> }
      },
      ...
    ]
  },
}

Notes:

  • HTTP status code 304 will be returned if the ETag in the request matches the one from server.
  • A variation request can be responded to by the supplier's customer with a partial approval whereby either the requested quantity OR the requested price is agreed but not both.

 

Retrieve variation attachments

Request:

GET /orders/:orderId/variations/:variationId/attachments?fields=<fieldName>[,<fieldName>,...]

Request parameters and response as per retrieve order attachments.

 

Create attachment on a variation

Request:

POST /orders/:orderId/variations/:variationId/attachments
Content-Type: multipart/form-data; boundary=--xxxx

<Same multipart data as per order attachments above>

Response:

HTTP/1.1 201 Created
Location: /orders/<orderId>/variations/<variationId>/attachments/<id>
Content-Type: application/json
ETag: <ETag>

<Same response data as per order attachments above>

 

Create variation

Request:

POST /orders/:orderId/variations
Content-Type: application/json

{
  actioned: {
    date: "2014-02-20T14:43:22Z",
    geo:  { latitude: <number>, longitude: <number> }
  },
  itemChanges: [                                        // only valid for type="labourAndMaterial" (VAR)
    {
      itemId:                 <string>,                 // item code from schedule of rates (i.e. scheduleItems resource)
      itemSeqNo:              <number>,                 // only present for modified items (orderItemNo); null for new items
      requestedQty:           <number>,                 // the new quantity being requested
      requestedPrice:         <number>                  // the new price being requested (optional), only for variable priced items.
    },
     ...
  ],
  requestedReason:            <string>,
  status:                     "new" | "open",           // optional, default value is new
}

Response:

HTTP/1.1 201 CREATED
Content-Type: application/json
ETag: <ETag>

{
  actioned: {
    date: "2014-02-20T14:43:22Z", //date of action recorded on mobile device
    geo:  { latitude: <number>, longitude: <number> }
  },
  itemChanges: [
    {
      itemId:               <string>,                   // item code from schedule of rates (i.e. scheduleItems resource)
      itemSeqNo:            <number>,                   // orderItemNo
      requestedQty:         <number>,                   // the new quantity being requested
      requestedPrice:       <number>                    // the new price being requested (optional), only for variable priced items.
      status:               "agreed" | "partial" | "new" | "rejected"                    // status of item variation
    },
    ...
  ],
  requestedReason:          "Weather conditions",
  requestor: {
    name:                   <string>,
    phone:                  <string>
  },
  status:                   "new" | "open",
  updatedDate:              "2014-02-20T14:43:22Z"      //update date of variation on server side
}

Note:

  • The requestor is inferred from the authenticated user accessing the REST API.

If another variation (EOT or VAR) is already in progress in ConSol, the creation request should fail.

Failure response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  reason:                   "active-variation",     // means "the order already has an existing, open or resolved variation"
  activeVariation:          "<uri>"
}

 

Submit/Recall/Acknowledge variation request response

Submit a variation/recall a variation request or acknowledge the supplier has read the customer's response to the variation request.

Request:

PUT /orders/:orderId/variations/:id
Content-Type: application/json

{
  actioned: {
    date: "<ISO 8601 date/time>",
    geo:  { latitude: <number>, longitude: <number> }
  },
  action: "close" | "open" | "recall" | "save"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

{
  actioned: {
    date: "2014-02-20T14:43:22Z",
    geo:  { latitude: <number>, longitude: <number> }
  },
  itemChanges: [                                      // only valid for type="labourAndMaterial" (VAR)
    {
      itemId:               <string>,                 // item code from schedule of rates (i.e. scheduleItems resource)
      itemSeqNo:            <number>,                 // orderItemNo
      requestedQty:         <number>,                 // the new quantity being requested
      requestedPrice:       <number>                  // the new price being requested (optional), only for variable priced items.
      status:               "agreed" | "partial" | "new" | "rejected"                    // status of item variation
    },
    ...
  ],
  requestedReason:          "Weather conditions",
  requestor: {
    name:                   <string>,
    phone:                  <string>
  },
  respondedReason:          <string>,                 // (optional, only available for current variation)
  status:                   "new" | "open" | "closed",
  updatedDate:              "<ISO 8601 date/time>"         // update date of variation on server side
}

Notes:

  • HTTP status code 412 will be returned if the ETag in the request does not match the one from server.

 

Save not submitted variation request

Update and save not yet submitted new variation.

Request:

PUT /orders/:orderId/variations/:id
Content-Type: application/json

{
  actioned: {
    date: "<ISO 8601 date/time>",
    geo:  { latitude: <number>, longitude: <number> }
  },
  action: "save",
  itemChanges: [                                      // only valid for type="labourAndMaterial" (VAR)
    {
      itemId:                 <string>,                 // item code from schedule of rates (i.e. scheduleItems resource)
      itemSeqNo:              <number>,                 // only present for modified items (orderItemNo); null for new items
      requestedQty:           <number>,                 // the new quantity being requested
      requestedPrice:         <number>                  // the new price being requested (optional), only for variable priced items.
    },
     ...
  ],
  requestedReason:            <string>,
}

Note:

  • if updated item changes not containing any item from previous item changes, the server action will be a deletion for item changes.

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

{
  actioned: {
    date: "<ISO 8601 date/time>",
    geo:  { latitude: <number>, longitude: <number> }
  },
  itemChanges: [                                      // only valid for type="labourAndMaterial" (VAR)
    {
      itemId:               <string>,                 // item code from schedule of rates (i.e. scheduleItems resource)
      itemSeqNo:            <number>,                 // orderItemNo
      requestedQty:         <number>,                 // the new quantity being requested
      requestedPrice:       <number>                  // the new price being requested (optional), only for variable priced items.
      status:               "agreed" | "partial" | "new" | "rejected"                    // status of item variation
    },
    ...
  ],
  requestedReason:          "Weather conditions",
  requestor: {
    name:                   <string>,
    phone:                  <string>
  },
  respondedReason:          <string>,                 // (optional, only available for current variation)
  status:                   "new" | "open" | "closed",
  updatedDate:              "<ISO 8601 date/time>"         // update date of variation on server side
}

Notes:

  • HTTP status code 412 will be returned if the ETag in the request does not match the one from server.

 

Cancel variation request

Cancel a variation request that is not submitted.

Request:

DELETE /orders/:orderId/variations/:id
Content-Type: application/json

{
  actioned: {
    date: "<ISO 8601 date/time>",
    geo:  { latitude: <number>, longitude: <number> }
  },
  action: "cancel"
}

Response:

HTTP/1.1 204 No Content

 

Retrieve extension of time (EOT)

Request:

GET /orders/:orderId/extensionOfTime
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: <ETag>

{
  actioned: {
    date: "<ISO 8601 date/time>",
    geo:  { latitude: <number>, longitude: <number> }
  },
  // in case of open: date_created of latest work_item 'REXV' (optional, only available for current EOT)
  // in case of status="resolved", date_created of work_item 'REEOT' (optional, only available for current EOT)
  // in case of status="closed", date_completed of work_item 'REEOT' (optional, only available for current EOT)
  requestedCompletionDate:  "<ISO 8601 date/time>",
  requestedReason:          <string>,                     // (optional, only available for current EOT)
  requestor: {                                            // (optional, only available for current EOT)
    name:                   <string>,
    phone:                  <string>
  },
  respondedReason:          <string>,                     // (optional, only available for current EOT)
  //status of EOT is determined by active work item status,
  // open -- REXV
  // resolved -- REEOT
  // closed -- all other cases
  status:                   "open" | "resolved" | "closed",
  updatedDate:              "<ISO 8601 date/time>"             // update date of variation on server side
}

 

Create extension of time (EOT)

Request:

POST /orders/:orderId/extensionOfTime
Content-Type: application/json

{
  actioned: {
    date: "<ISO 8601 date/time>",
    geo:  { latitude: <number>, longitude: <number> }
  },
 
  requestedCompletionDate:  "<ISO 8601 date/time>",
  requestedReason:          "<string>"
}

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.