Service_orders
This resource allows you to interact with service orders in Octopi.

Supported Formats

json
>>>

GET /api/v1/service_orders.json
Returns all the service orders present in Octopi.

Supported Formats

json

Errors

Code Description
404 Resource Not Found
422 Validation Error
500 Internal Server Error

Examples

curl 'https://app.octopi.co/api/v1/service_orders' \
  -X 'GET' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token token=YOURTOKEN'

{
  "total_count": 28,
  "service_orders": [
    {
      "id": 41,
      "order_number": "API_TEST_002",
      "due_at": "2024-04-30T20:00:00-04:00",
      "cargo_type": "container",
      "status": "cancelled",
      "comment": "Latest Comment",
      "created_at": "2024-01-29T05:33:55-05:00",
      "ordered_by": "System",
      "service_order_items": [
        {
          "id": 74,
          "container_id": 4337700,
          "status": "cancelled",
          "cancelled_at": "2024-01-29T05:50:02-05:00",
          "cancelled_by": "System",
          "cancellation_reason": "Lorem Ipsum",
          "container_number": "0317933",
          "service_type": "custom",
          "service_id": 721,
          "service_name": "Repainting"
        },
        {
          "id": 75,
          "container_id": 4337700,
          "status": "cancelled",
          "cancelled_at": "2024-01-29T05:50:02-05:00",
          "cancelled_by": "System",
          "cancellation_reason": "Lorem Ipsum",
          "container_number": "0317933",
          "service_type": "default",
          "service_id": "cleaning",
          "service_name": "Cleaning (Default)"
        }
      ]
    },
    {
      "id": 39,
      "order_number": "API_TEST_001",
      "due_at": "2024-02-19T19:00:00-05:00",
      "cargo_type": "container",
      "status": "cancelled",
      "comment": "New SO",
      "created_at": "2024-01-25T13:44:45-05:00",
      "ordered_by": "System",
      "service_order_items": [
        {
          "id": 65,
          "container_id": 231596,
          "status": "cancelled",
          "cancelled_at": "2024-01-25T13:45:59-05:00",
          "cancelled_by": "System",
          "cancellation_reason": "Lorem Ipsum",
          "container_number": "278434",
          "service_type": "custom",
          "service_id": 723,
          "service_name": "Color Painting"
        },
        {
          "id": 66,
          "container_id": 231596,
          "status": "cancelled",
          "cancelled_at": "2024-01-25T13:45:59-05:00",
          "cancelled_by": "System",
          "cancellation_reason": "Lorem Ipsum",
          "container_number": "278434",
          "service_type": "default",
          "service_id": "reseal",
          "service_name": "Reseal (Default)"
        },
        {
          "id": 71,
          "container_id": 28776,
          "status": "pending",
          "container_number": "ABCU1236033",
          "service_type": "default",
          "service_id": "inspection",
          "service_name": "Inspection (Default)"
        },
        {
          "id": 72,
          "container_id": 4337700,
          "status": "cancelled",
          "cancelled_at": "2024-01-29T05:05:23-05:00",
          "cancelled_by": "System",
          "cancellation_reason": "Lorem Ipsum",
          "container_number": "0317933",
          "service_type": "default",
          "service_id": "inspection",
          "service_name": "Inspection (Default)"
        }
      ]
    },
    {
      "id": 37,
      "order_number": "SO123456",
      "due_at": "2024-01-19T19:00:00-05:00",
      "cargo_type": "container",
      "status": "pending",
      "comment": "New SO",
      "created_at": "2024-01-09T06:52:28-05:00",
      "ordered_by": "System",
      "service_order_items": [
        {
          "id": 61,
          "container_id": 4337700,
          "status": "pending",
          "container_number": "0317933",
          "service_type": "default",
          "service_id": "cleaning",
          "service_name": "Cleaning (Default)"
        },
        {
          "id": 62,
          "container_id": 95951,
          "status": "pending",
          "container_number": "1TRUCKMACKDR332724",
          "service_type": "default",
          "service_id": "cleaning",
          "service_name": "Cleaning (Default)"
        }
      ]
    },
    {
      "id": 35,
      "order_number": "SO120240104014",
      "due_at": "2024-01-20T01:30:00-05:00",
      "cargo_type": "container",
      "status": "pending",
      "comment": "",
      "created_at": "2024-01-04T01:30:46-05:00",
      "ordered_by": "Kamalraj Matheswaran",
      "service_order_items": [
        {
          "id": 59,
          "container_id": 2538488,
          "status": "pending",
          "container_number": "3CHASSISDR346929",
          "service_type": "default",
          "service_id": "scanning",
          "service_name": "Scanning (Default)"
        }
      ]
    },
    {
      "id": 33,
      "order_number": "SO120240104013",
      "due_at": "2024-01-18T01:30:00-05:00",
      "cargo_type": "container",
      "status": "pending",
      "comment": "",
      "created_at": "2024-01-04T01:30:12-05:00",
      "ordered_by": "Kamalraj Matheswaran",
      "service_order_items": [
        {
          "id": 58,
          "container_id": 40602,
          "status": "pending",
          "container_number": "5298338",
          "service_type": "default",
          "service_id": "cleaning",
          "service_name": "Cleaning (Default)"
        }
      ]
    },
    {
      "id": 32,
      "order_number": "SO120240104012",
      "due_at": "2024-01-13T01:29:00-05:00",
      "cargo_type": "container",
      "status": "pending",
      "comment": "",
      "created_at": "2024-01-04T01:29:58-05:00",
      "ordered_by": "Kamalraj Matheswaran",
      "service_order_items": [
        {
          "id": 56,
          "container_id": 45261,
          "status": "pending",
          "container_number": "4556104",
          "service_type": "custom",
          "service_id": 721,
          "service_name": "Repainting"
        },
        {
          "id": 57,
          "container_id": 45261,
          "status": "pending",
          "container_number": "4556104",
          "service_type": "custom",
          "service_id": 722,
          "service_name": "Test Service"
        }
      ]
    },
    {
      "id": 31,
      "order_number": "SO120240104011",
      "due_at": "2024-01-25T01:29:00-05:00",
      "cargo_type": "container",
      "status": "pending",
      "comment": "",
      "created_at": "2024-01-04T01:29:39-05:00",
      "ordered_by": "Kamalraj Matheswaran",
      "service_order_items": [
        {
          "id": 55,
          "container_id": 1098881,
          "status": "pending",
          "container_number": "4128586",
          "service_type": "custom",
          "service_id": 721,
          "service_name": "Repainting"
        }
      ]
    },
    {
      "id": 30,
      "order_number": "SO120240104010",
      "due_at": "2024-01-10T01:29:00-05:00",
      "cargo_type": "container",
      "status": "pending",
      "comment": "",
      "created_at": "2024-01-04T01:29:24-05:00",
      "ordered_by": "Kamalraj Matheswaran",
      "service_order_items": [
        {
          "id": 54,
          "container_id": 50053,
          "status": "pending",
          "container_number": "4812187",
          "service_type": "custom",
          "service_id": 722,
          "service_name": "Test Service"
        }
      ]
    },
    {
      "id": 29,
      "order_number": "SO120240104009",
      "due_at": "2024-01-19T01:29:00-05:00",
      "cargo_type": "container",
      "status": "pending",
      "comment": "",
      "created_at": "2024-01-04T01:29:10-05:00",
      "ordered_by": "Kamalraj Matheswaran",
      "service_order_items": [
        {
          "id": 53,
          "container_id": 2047032,
          "status": "pending",
          "container_number": "CAIU6889279",
          "service_type": "default",
          "service_id": "reseal",
          "service_name": "Reseal (Default)"
        }
      ]
    },
    {
      "id": 27,
      "order_number": "SO120240104007",
      "due_at": "2024-01-24T01:28:00-05:00",
      "cargo_type": "breakbulk",
      "status": "pending",
      "comment": "",
      "created_at": "2024-01-04T01:28:34-05:00",
      "ordered_by": "Kamalraj Matheswaran",
      "service_order_items": [
        {
          "id": 51,
          "container_id": 3190442,
          "status": "pending",
          "container_description": "1030134737/577498 DWV PVC",
          "service_type": "custom",
          "service_id": 722,
          "service_name": "Test Service"
        }
      ]
    }
  ]
}

Params

Param name Description
order_number
optional

The unique service order number given while creating one. You can do partial string search as well.

Validations:

  • Must be a String
due_at
optional

The date and time before which you want to fulfil the order, in ISO 8601 format (Eg. 2023-08-18T14:00:00Z) in UTC.

Validations:

  • Must be a String
status
optional

The current status of the service order.

Validations:

  • Must be one of: pending, completed, cancelled, in_progress, partially_completed.
cargo_type
optional

container or breakbulk

Validations:

  • Must be one of: container, vehicle, breakbulk.
container_id
optional

Octopi ID of any container.

Validations:

  • Must be a Integer
page
optional

Specify which page of results to fetch. This value defaults to 1.

Validations:

  • Must be a Integer
per
optional

The number of service orders to be displayed. This value defaults to 10 and accepts a maximum of 100.

Validations:

  • Must be a Integer
>>>

GET /api/v1/service_orders/:order_number.json
Returns information about the service order.

Supported Formats

json

Errors

Code Description
404 Resource Not Found
422 Validation Error
500 Internal Server Error

Examples

curl 'https://app.octopi.co/api/v1/service_orders/ORDER_NUMBER.json' \
  -X 'GET' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token token=YOURTOKEN'

{
  "id": 6,
  "order_number": "SO120230928001",
  "due_at": "2023-09-29T05:32:00-04:00",
  "cargo_type": "breakbulk",
  "status": "partially_completed",
  "comment": "",
  "created_at": "2023-09-28T05:32:05-04:00",
  "ordered_by": "Kamalraj Matheswaran",
  "service_order_items": [
    {
      "id": 1,
      "container_id": 2388117,
      "status": "cancelled",
      "cancelled_at": "2023-10-25T03:23:15-04:00",
      "cancelled_by": "Kamalraj Matheswaran",
      "cancellation_reason": "This page is a service order document for Caribbean Port Services (CPS) with the ID SO120230928001. It provides details of the order including:\r\n\r\nThe key details are the service order ID, required date, and status. It also lists 3 order items and their service statuses.",
      "container_description": "2014 SUBARU FORESTER VIN# JF2SJAGC1EH400056",
      "service_type": "custom",
      "service_id": 723,
      "service_name": "Color Painting"
    },
    {
      "id": 2,
      "container_id": 2388117,
      "status": "completed",
      "completed_at": null,
      "completed_by": "Kamalraj Matheswaran",
      "container_description": "2014 SUBARU FORESTER VIN# JF2SJAGC1EH400056",
      "service_type": "custom",
      "service_id": 722,
      "service_name": "Test Service"
    },
    {
      "id": 32,
      "container_id": 2333777,
      "status": "completed",
      "completed_at": null,
      "completed_by": null,
      "container_description": "SLAC PERSONAL EFFECTCARGO MOVING INBOND UNDER T&E# 679876665POR: NDR#3DTHC COLLECT",
      "service_type": "custom",
      "service_id": 722,
      "service_name": "Test Service"
    }
  ]
}

Params

Param name Description
order_number
required

Octopi ID or the unique service order number given while creating one.

Validations:

  • Must be a String
>>>

POST /api/v1/service_orders.json
Creates a new service order.

Supported Formats

json

Errors

Code Description
404 Resource Not Found
422 Validation Error
500 Internal Server Error

Examples

curl 'https://app.octopi.co/api/v1/service_orders' \
  -X 'POST' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token token=YOURTOKEN' \
  -d '{
    "service_order": {
      "order_number": "API_TEST_002",
      "cargo_type": "container",
      "due_at": "2024-05-20T00:00:00Z",
      "comment": "New SO",
      "container_ids": [
        4337700
      ],
      "service_ids": [
        "cleaning",
        721
      ]
    }
  }'

{
  "id": 41,
  "order_number": "API_TEST_002",
  "due_at": "2024-05-19T20:00:00-04:00",
  "cargo_type": "container",
  "status": "pending",
  "comment": "New SO",
  "created_at": "2024-01-29T05:33:55-05:00",
  "ordered_by": "System",
  "service_order_items": [
    {
      "id": 74,
      "container_id": 4337700,
      "status": "pending",
      "container_number": "0317933",
      "service_type": "custom",
      "service_id": 721,
      "service_name": "Repainting"
    },
    {
      "id": 75,
      "container_id": 4337700,
      "status": "pending",
      "container_number": "0317933",
      "service_type": "default",
      "service_id": "cleaning",
      "service_name": "Cleaning (Default)"
    }
  ]
}

Params

Param name Description
service_order
optional

Validations:

  • Must be a Hash
service_order[order_number]
required

The unique service order number given while creating one.

Validations:

  • Must be a String
service_order[cargo_type]
required

container or breakbulk

Validations:

  • Must be one of: container, vehicle, breakbulk.
service_order[container_ids]
required

Octopi IDs of containers.

Validations:

  • Must be an array of Integer
service_order[service_ids]
required

Array of default & custom service type IDs provided by Octopi.

Validations:

  • Must be an array of any type
>>>

PUT /api/v1/service_orders/:order_number.json
Updates an existing service order.

Supported Formats

json

Errors

Code Description
404 Resource Not Found
422 Validation Error
500 Internal Server Error

Examples

curl 'https://app.octopi.co/api/v1/service_orders/ORDER_NUMBER.json' \
  -X 'PUT' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token token=YOURTOKEN' \
  -d '{ \
    "service_order": {
      "order_number": "API_TEST_002_UPDATED",
      "due_at": "2024-04-31T00:00:00Z",
      "comment": "Updating order number and due at"
    }
  }'

{
  "id": 41,
  "order_number": "API_TEST_002_UPDATED",
  "due_at": "2024-04-30T20:00:00-04:00",
  "cargo_type": "container",
  "status": "pending",
  "comment": "Updating order number and due at",
  "created_at": "2024-01-29T05:33:55-05:00",
  "ordered_by": "System",
  "service_order_items": [
    {
      "id": 74,
      "container_id": 4337700,
      "status": "pending",
      "container_number": "0317933",
      "service_type": "custom",
      "service_id": 721,
      "service_name": "Repainting"
    },
    {
      "id": 75,
      "container_id": 4337700,
      "status": "pending",
      "container_number": "0317933",
      "service_type": "default",
      "service_id": "cleaning",
      "service_name": "Cleaning (Default)"
    }
  ]
}

Params

Param name Description
order_number
required

Octopi ID or the unique service order number given while creating one.

Validations:

  • Must be a String
service_order
optional

Validations:

  • Must be a Hash
service_order[order_number]
required

The unique service order number given while creating one.

Validations:

  • Must be a String
service_order[due_at]
optional

The date and time before which you want to fulfil the order, in ISO 8601 format (Eg. 2023-08-18T14:00:00Z) in UTC.

Validations:

  • Must be a String
service_order[comment]
optional

Comments for this order.

Validations:

  • Must be a String
>>>

DELETE /api/v1/service_orders/:order_number.json
Deletes an existing service order.

Supported Formats

json

Errors

Code Description
404 Resource Not Found
422 Validation Error
500 Internal Server Error

Examples

curl 'https://app.octopi.co/api/v1/service_orders/ORDER_NUMBER.json' \
  -X 'DELETE' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token token=YOURTOKEN'

{
  "id": 28,
  "order_number": "SO120240104008",
  "due_at": "2024-02-03T01:28:00-05:00",
  "cargo_type": "breakbulk",
  "status": "pending",
  "comment": "",
  "created_at": "2024-01-04T01:28:56-05:00",
  "ordered_by": "Kamalraj Matheswaran",
  "service_order_items": []
}

Params

Param name Description
order_number
required

Octopi ID or the unique service order number given while creating one.

Validations:

  • Must be a String
>>>

PUT /api/v1/service_orders/:order_number/cancel.json
Cancels all the incompleted order items under the given service order.

Supported Formats

json

Errors

Code Description
404 Resource Not Found
422 Validation Error
500 Internal Server Error

Examples

curl 'https://app.octopi.co/api/v1/service_orders/ORDER_NUMBER/cancel.json' \
  -X 'PUT' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token token=YOURTOKEN' \
  -d '{ \
    "service_order": {
      "cancellation_reason": "Lorem Ipsum"
    }
  }'

{
  "id": 41,
  "order_number": "API_TEST_002",
  "due_at": "2024-04-30T20:00:00-04:00",
  "cargo_type": "container",
  "status": "cancelled",
  "comment": "Latest Comment",
  "created_at": "2024-01-29T05:33:55-05:00",
  "ordered_by": "System",
  "service_order_items": [
    {
      "id": 74,
      "container_id": 4337700,
      "status": "cancelled",
      "cancelled_at": "2024-01-29T05:50:02-05:00",
      "cancelled_by": "System",
      "cancellation_reason": "Lorem Ipsum",
      "container_number": "0317933",
      "service_type": "custom",
      "service_id": 721,
      "service_name": "Repainting"
    },
    {
      "id": 75,
      "container_id": 4337700,
      "status": "cancelled",
      "cancelled_at": "2024-01-29T05:50:02-05:00",
      "cancelled_by": "System",
      "cancellation_reason": "Lorem Ipsum",
      "container_number": "0317933",
      "service_type": "default",
      "service_id": "cleaning",
      "service_name": "Cleaning (Default)"
    }
  ]
}

Params

Param name Description
order_number
required

Octopi ID or the unique service order number given while creating one.

Validations:

  • Must be a String
service_order
optional

Validations:

  • Must be a Hash
service_order[cancellation_reason]
required

The reason for cancelling the service order.

Validations:

  • Must be a String