In Octopi, the following three types of invoices can be created: * A pro-forma invoice for a Bill of Lading. These invoices is generally for consignees (importers or exporters). It shows how much they need to pay to retrieve a container from the terminal. * An invoice for a container movement. Any container movement in Octopi can generate an invoice if there is a tariff tied to this event type. For example, a tariff can be created for all ‘Gate Out Full’ so that every time a container gates out full out of the terminal, an invoice is created for the consignee to which this container is being delivered to. * An invoice for a voyage. An invoice can be generated to charge the shipping lines for the vessel operations and/or container storage following a voyage.
This API endpoint allows you to access these invoices. To fetch invoices, it is mandatory to pass in two query parameters: * a customer_type which can be either Consignee, ShippingLine or Agent * a customer_general_ledger_id which is a String and represents the General Ledger ID stored in Octopi (and the accounting system) for that Shipping Line or Consignee.
In addition, you can also pass in a parameter called ‘created_during’ to filter and only have access to specific invoices for that customer.
In Octopi, some invoices are generated automatically by the software (triggered by an event such as a gate out for example) or generated manually by a user (by clicking on a button to generate the invoice). When created automatically, the creation_method returned by this API will be AUTO. For invoices generated manually by a user, creation_method is set to MANUAL.
For Bill of Lading pro-formas, it is possible for a pro-forma to be created for all the containers in the Bill Of Lading or for only some of the containers in the Bill Of Lading. To find out which containers were billed for in that pro-forma, there are two arrays called bl_container_ids and bl_container_numbers that return respectively an array of IDs and an array of container numbers for the containers that were billed in this pro-forma.
| Code | Description |
|---|---|
| 404 | Not found. |
| 400 | Invalid request. |
| 500 | Server crashed. |
curl "https://app.octopi.co/api/v1/invoices.json" -X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=ADD TOKEN HERE" -d '{"customer_type":"ShippingLine", "customer_general_ledger_id":"ADD SHIPPING LINE ID HERE"}'
"actions" : {
"last" : {
"url" : "https://app.octopi.co/api/v1/invoices.json?page=18",
"method" : "GET"
},
"next" : {
"url" : "https://app.octopi.co/api/v1/invoices.json?page=2",
"method" : "GET"
},
"previous" : {
"url" : "https://app.octopi.co/api/v1/invoices.json",
"method" : "GET"
},
"index" : {
"method" : "GET",
"url" : "https://app.octopi.co/api/v1/invoices.json"
}
}
"invoices" : [
{
"general_ledger_id" : null,
"taxes_and_fees" : "0.0",
"id" : 12008,
"is_proforma": true,
"paid": false,
"approved": true,
"approved_by": "John Doe",
"created_during": "voyage",
"movement_id": 123456,
"creation_method": "manual",
"line_items" : [
{
"quantity" : 1,
"currency" : "USD",
"total" : "100.0",
"description" : "Crane Fee",
"billed_by" : "unit",
"billed_per" : "move",
"amount" : 100.0,
"item" : "REFN1231",
"tariff_general_ledger_id" : "REFN1231",
"tariff_name": "Crane Lift Tariff"
"container": "MAEU1312311"
},
{
"description" : "Stevedoring Fee",
"billed_by" : "unit",
"total" : "50.0",
"quantity" : 1,
"currency" : "USD",
"item" : "REFN1232",
"tariff_general_ledger_id" : "REFN1232",
"billed_per" : "move",
"amount" : "50.0",
"tariff_name": "Stevedoring Tariff"
"container": "MAEU1312311"
},
,
{
"description" : "Extra Fee",
"billed_by" : "unit",
"total" : "50.0",
"quantity" : 1,
"currency" : "USD",
"item" : "REFN1230",
"billed_per" : "move",
"amount" : "30.0",
"tariff_general_leger_id" : "REFN1230",
"tariff_name": "Extra fee tariff"
"container": "MAEU1010101"
}
],
"totals_by_container": {
"MAEU1312311": 150.0,
"MAEU1010101": 30.0
},
"subtotal" : "49240.0",
"customer" : {
"id" : 49,
"address" : "",
"general_ledger_id" : "123",
"email" : "",
"name" : "DEMO LINE",
"contact_person" : "",
"phone" : ""
},
"voyage" : {
"id" : 1033,
"vessel" : {
"imo_number" : "9252876",
"name" : "NADJA",
"vessel_type" : "container_ship"
},
"number" : "115"
},
"truck_visit": {
"id": 520155,
"truck": {
"id": 2826,
"license_plate": "CESF51",
"trucking_company_id": 118,
"active": true,
"allowed_until": null
},
"truck_driver": {
"id": 23897,
"number": null,
"license_number": "N/A",
"firstname": "Anier",
"lastname": "Venega",
"twic": null,
"active": true
},
"gated_in_at": "2019-05-10T23:47:25Z",
"gated_out_at": "2019-05-11T00:00:58Z"
},
"total" : "49240.0",
"created_at" : "2016-11-28T19:01:41.936-05:00",
"invoiced_at" : "2016-11-28T19:01:41.936-05:00",
"approved_at" : "2016-11-28T19:02:41.936-05:00"
},
{
"general_ledger_id" : null,
"taxes_and_fees" : "0.0",
"id" : 12008,
"is_proforma": true,
"paid": false,
"approved": false,
"approved_by": null,
"created_during" : "payment",
"movement_id": null,
"creation_method": "auto",
"line_items" : [
{
"quantity" : 1,
"currency" : "USD",
"total" : "100.0",
"description" : "Crane Fee",
"billed_by" : "unit",
"billed_per" : "move",
"amount" : 100.0,
"item" : "REFN1231",
"tariff_general_ledger_id" : "REFN1231",
"tariff_name": "Crane Lift Tariff"
"container": "MAEU1312311"
}
],
"subtotal" : "49240.0",
"customer" : {
"id" : 49,
"address" : "",
"general_ledger_id" : "123",
"email" : "",
"name" : "IMPORTER ONE",
"contact_person" : "",
"phone" : ""
},
"bol_segment" : {
"id": 1034,
"bl_number" : "1033",
"containers": ["BSIU9028942", "AMLU5506569"]
},
"bill_of_lading" : {
"id": 1034,
"bl_number" : "1033",
"containers": ["BSIU9028942", "AMLU5506569"]
},
"bl_container_ids": [2131, 1231],
"bl_container_numbers": ["BSIU9028942", "AMLU5506569"],
"total" : "500.0",
"created_at" : "2016-11-28T19:01:41.936-05:00",
"invoiced_at" : "2016-11-28T19:01:41.936-05:00",
"approved_at" : "2016-11-28T19:02:41.936-05:00"
}
]
}
| Param name | Description |
|---|---|
|
q optional |
q stands for query. It allows you to search by invoice general ledger ID or total. Validations:
|
|
line_items_q optional |
line_items_q stands for line item query. It allows you to search invoices by line items description. Validations:
|
|
customer_type optional |
The type of customer. Validations:
|
|
customer_general_ledger_id optional |
The General Ledger ID for the customer. You must include a customer_type if you include a customer_general_ledger_id. Validations:
|
|
created_during optional |
Filter invoices based on when they were created. Can be one of ‘payment’, ‘gate_out’, ‘gate_in’, ‘tally’, etc… Validations:
|
|
movement_id optional |
Filter invoices by movement id. Validations:
|
|
creation_method optional |
Filter invoices by creation method. One of auto or manual. Validations:
|
|
missing_general_ledger_id optional |
Set to true to return all invoices that do not have a general ledger ID Validations:
|
|
currency optional |
Filter invoices by currency Validations:
|
|
bill_of_lading_number optional |
Filter invoices by Bill of Lading Number Validations:
|
|
bill_of_lading_id optional |
Filter invoices by Bill of Lading ID Validations:
|
|
tariff_id optional |
Filter invoices by tariff Validations:
|
|
container_id optional |
Filter invoices by container/cargo ID Validations:
|
|
container_number optional |
Filter invoices by container number Validations:
|
|
voyage_id optional |
Filter invoices by voyage ID Validations:
|
|
voyage_number optional |
Filter invoices by voyage number Validations:
|
|
truck_visit_id optional |
Filter invoices by truck visit ID Validations:
|
|
paid optional |
Filter for paid invoices by setting to true. Or set to false to get all unpaid invoices. If absent, Octopi will return both paid and unpaid invoices. Validations:
|
|
is_proforma optional |
Filter for proforma invoices by setting to true. Or set to false to return all invoices that are not proformas. If absent, Octopi will return all invoices: proforma or not. Validations:
|
|
approved optional |
Filter for approved invoices by setting to true. Or set to false to get all not approved invoices. If absent, Octopi will return both approved and not approved invoices. Validations:
|
|
page optional |
Specify which page of results to fetch. This value defaults to 1. Validations:
|
|
per optional |
The number of items to be displayed. This value defaults to 10 and accepts a maximum of 100. Validations:
|
This API endpoint allows you to update a invoice.
| Code | Description |
|---|---|
| 404 | Not found. |
| 400 | Invalid request. |
| 500 | Server crashed. |
curl "https://app.octopi.co/api/v1/invoices/353388.json" -X PUT -d '{ "general_ledger_id" : "C8191" }' -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=YOUR TOKEN HERE"
{
"invoice" : {
"id" : "222",
"number": "5",
"general_ledger_id"; "1231",
"created_at": "2016-11-28T19:01:41.936-05:00",
"invoiced_at": "2016-11-28T19:01:41.936-05:00",
"paid": false,
"total": 1231.00
}
}
| Param name | Description |
|---|---|
|
id required |
Validations:
|