This resource allows clients to view, create and delete pre-advices in Octopi

Supported Formats

json

GET /api/v1/pre_advices/:advice_number

Returns information about a specific pre-advice.

Supported Formats

json

Errors

Code Description
404 Not found.
422 Unprocessable Entity.
500 Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/pre_advices/OCTO231234.json" -X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=ADD TOKEN HERE"'
{
  "advice_number": "OCTO231234",
  "truck": "TRA123",
  "truck_driver": {
    "id": 1234,
    "fullname": "John Doe",
    "license_number": "JNA321",
    "twic": "",
    "number": "633353",
    "active": true,
    "date_of_birth": null,
    "telephone_number": null,
    "email": null,
    "remarks": null,
    "trucking_company": "FAST TRUCKS, INC.",
    "allowed_until": null,
    "created_at": "2017-09-15T15:47:12Z",
    "updated_at": "2023-09-15T15:47:12Z"
  },
  "purposes": [
    {
      "purpose_type": "drop_off",
      "cargo": "NYKU438609",
      "booking": "BOOK123",
      "bill_of_lading": "BOL123"
    },
    {
      "purpose_type": "pick_up",
      "cargo": "TEMU714171",
      "booking": "BOOK321",
      "bill_of_lading": "BOL321"
    }
  ]
}

Params

Param name Description
advice_number
required

The pre-advice’s number.

Validations:

  • Must be a String


POST /api/v1/pre_advices.json

Creates a pre-advice

Supported Formats

json

Errors

Code Description
404 Not found.
422 Unprocessable Entity.
500 Internal Server Error.

Examples

curl --location --request POST 'https://app.octopi.co/api/v1/pre_advices.json'     --header 'Authorization: Bearer token_value'     --header 'Content-Type: application/json'     --data-raw '{
  "advice_number": "ADVICE1234",
  "truck": "TRA123",
  "truck_driver": "JD231",
  "trucking_company": "Blue Trucks",
  "comments": "On time",
  "expected_at": "2023-04-13T14:30:00Z",
  "purposes": [
    {
      "purpose_type": "drop_off",
      "cargo": {
        "cargo_type": "container",
        "container_number": "NYKU438409",
        "container_type": "20DV",
        "container_status": "full",
        "weight": 12000,
        "container_usage": "export",
        "goods": "play stations",
        "shipping_line": "MAERSK"
      },
      "booking": "BOOK1234",
      "bill_of_lading": "BOL1234",
      "delivery_order": "DO1234",
      "interchange":{
        "seals": "SEAL1,SEAL2,SEAL3",
        "weight": 12000
      }
    }
  ]
}'
{
  "advice_number": "ADVICE1234",
  "truck": "TRA123",
  "truck_driver": {
    "id": 1234,
    "fullname": "John Doe",
    "license_number": "JD231",
    "twic": "",
    "number": "JD231",
    "active": true,
    "date_of_birth": null,
    "telephone_number": null,
    "email": null,
    "remarks": null,
    "trucking_company": "Blue Trucks",
    "allowed_until": null,
    "created_at": "2023-09-15T15:47:12Z",
    "updated_at": "2023-09-15T15:47:12Z"
  },
  "comments": "On time",
  "expected_at": "2023-04-13T14:30:00Z",
  "purposes": [
    {
      "purpose_type": "drop_off",
      "cargo": "NYKU438409",
      "booking": "BOOK1234",
      "bill_of_lading": "BOL1234",
      "delivery_order": "DO1234",
      "interchange":{
        "seals": "SEAL1,SEAL2,SEAL3",
        "weight": 12000
      }
    }
  ]
}

Params

Param name Description
advice_number
optional

Unique advice number. Should be at least 4 characters. Octopi will auto-generate one if not provided.

Validations:

  • Must be a String

truck
required

Truck’s license plate number. Required only if your organization requires it.

Validations:

  • Must be a String

truck_driver_id
optional

Truck driver ID. If this parameter is present, the truck_driver parameter will be ignored.

Validations:

  • Must be a String

truck_driver
optional

Truck driver’s license number. If the truck_driver_id parameter is present, this will be ignored.

Validations:

  • Must be a String

trucking_company
optional

The trucking company for this pre-advice. If a truck is present, then the trucking company in this parameter must match it. Similarly, if a truck driver is present, the driver’s company must match this trucking company.

Validations:

  • Must be a String

comments
optional

Comments for this pre-advice.

Validations:

  • Must be a String

purposes
optional

Truck visit’s purposes (multiple purposes allowed).

Validations:

  • Must be an Array of nested elements

purposes[purpose_type]
required

Purpose type. Must be one of ‘drop off’, ‘drop_off’, ‘pick up’ or ‘pick_up’.

Validations:

  • Must be a String

purposes[cargo]
optional

Cargo details

Validations:

  • Must be a Hash

purposes[cargo][cargo_type]
required

Type of Cargo. Must be one of ‘container’, ‘chassis’, ‘general cargo’ or ‘general_cargo’.

Validations:

  • Must be a String

purposes[cargo][container_number]
optional

Container number. Required if cargo_type is ‘container’ and if the purpose is not for pick-up empty.

Validations:

  • Must be a String

purposes[cargo][container_type]
optional

Type of Container (eg 20DV). Required when creating a new container.

Validations:

  • Must be a String

purposes[cargo][container_status]
optional

Status of container (full/empty). Required if cargo_type is ‘container’

Validations:

  • Must be a String

purposes[cargo][chassis_number]
optional

Active Chassis number. Required if cargo_type is ‘chassis’.

Validations:

  • Must be a String

purposes[cargo][shipping_line]
optional

Shipping line code. Required when creating a new container if the purpose is not for pick-up empty.

Validations:

  • Must be a String

purposes[cargo][goods]
optional

Goods description.

Validations:

  • Must be a String

purposes[cargo][container_usage]
optional

The container’s usage.

Validations:

  • Must be one of: export, import, unknown.

purposes[cargo][weight]
optional

Total weight of the container in KGs.

Validations:

  • Must be a Float

purposes[booking]
optional

A valid booking number to drop off a full container or pick up an empty.

Validations:

  • Must be a String

purposes[bill_of_lading]
optional

A valid Bill of Lading number to pick up a full container if your organization validates BOLs.

Validations:

  • Must be a String

purposes[delivery_order]
optional

A valid delivery order number to pick up general cargo

Validations:

  • Must be a String

purposes[interchange]
optional

Interchange details

Validations:

  • Must be a Hash

purposes[interchange][seals]
optional

Comma separated values of seals on the container

Validations:

  • Must be a String

purposes[interchange][weight]
optional

Total weight of the container in KGs.

Validations:

  • Must be a Float

expected_at
optional

The date and time at which you expect a truck visit to use this pre advice, in ISO 8601 format (Eg 2023-04-13T14:30:00Z)

Validations:

  • Must be a String


DELETE /api/v1/pre_advices/:advice_number

This API endpoint allows you to delete a pre-advice.

Supported Formats

json

Errors

Code Description
404 Not found.
422 Unprocessable Entity.
500 Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/pre_advices/OCT1234.json" -X DELETE -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=YOUR TOKEN HERE"
{
  "advice_number": "OCT1234",
  "truck": "TRA123",
  "truck_driver": {
    "id": 1234,
    "fullname": "John Doe",
    "license_number": "JD231",
    "twic": "",
    "number": "JD231",
    "active": true,
    "date_of_birth": null,
    "telephone_number": null,
    "email": null,
    "remarks": null,
    "trucking_company": "Blue Trucks",
    "allowed_until": null,
    "created_at": "2023-09-15T15:47:12Z",
    "updated_at": "2023-09-15T15:47:12Z"
  },
  "purposes": []
}

Params

Param name Description
advice_number
required

Validations:

  • Must be a String