Item positions API

Introduction

Item positions can be used on the following resources: estimates, orders and invoices. The resource URL is built like this:

/%parent_resource%/%parent_id%/kb_position_article

If you have an invoice with ID 4 you should replace the placeholder %parent_resource% with kb_invoice and replace the placeholder %parent_id% with 4. Estimates will be used in the upcomming examples.

List item positions

GET /kb_offer/1/kb_position_article
Accept: application/json
Authorization: Bearer 677a1598d208d6c303fa5ca1c774709250e21749
Name Required Type Description
order_by optional string Sorting
limit optional integer Limit
offset optional integer Offset
callback optional string Javascript callback

The following sort parameters may be applied:

  • id

The following scopes are needed:

  • kb_invoice_edit
  • kb_offer_edit
  • kb_order_edit
  • kb_bill_edit
Status: 200 OK
X-Authenticated-User: apiextract_1
Content-Length: 611
Content-Type: application/json
[
  {
    "id": 1,
    "type": "KbPositionArticle",
    "amount": "1.0000",
    "unit_id": 1,
    "account_id": null,
    "unit_name": "h",
    "tax_id": 4,
    "tax_value": "0.00",
    "text": "Mozzarella",
    "unit_price": "4.0000",
    "discount_in_percent": null,
    "position_total": "4.0000",
    "pos": "3",
    "internal_pos": 3,
    "parent_id": null,
    "is_optional": false,
    "article_id": 1
  },
  {
    "id": 14,
    "type": "KbPositionArticle",
    "amount": "1.0000",
    "unit_id": null,
    "account_id": 79,
    "unit_name": null,
    "tax_id": 1,
    "tax_value": "8.00",
    "text": "Produkt 1",
    "unit_price": "5.4500",
    "discount_in_percent": null,
    "position_total": "5.4500",
    "pos": "6",
    "internal_pos": 8,
    "parent_id": null,
    "is_optional": false,
    "article_id": 1
  }
]

Search item positions

POST /kb_offer/1/kb_position_article/search
Accept: application/json
Authorization: Bearer 677a1598d208d6c303fa5ca1c774709250e21749
[
  {
    "field": "article_id",
    "value": 1
  }
]
Name Required Type Description
order_by optional string Sorting
limit optional integer Limit
offset optional integer Offset
callback optional string Javascript callback

The following sort parameters may be applied:

  • id
Name Required Type Description
article_id optional string
amount optional string
tax_id optional string
text optional string
discount_in_percent optional string
position_total optional string

The following scopes are needed:

  • kb_invoice_edit
  • kb_offer_edit
  • kb_order_edit
  • kb_bill_edit
Status: 200 OK
X-Authenticated-User: apiextract_1
Content-Length: 611
Content-Type: application/json
[
  {
    "id": 1,
    "type": "KbPositionArticle",
    "amount": "1.0000",
    "unit_id": 1,
    "account_id": null,
    "unit_name": "h",
    "tax_id": 4,
    "tax_value": "0.00",
    "text": "Mozzarella",
    "unit_price": "4.0000",
    "discount_in_percent": null,
    "position_total": "4.0000",
    "pos": "3",
    "internal_pos": 3,
    "parent_id": null,
    "is_optional": false,
    "article_id": 1
  },
  {
    "id": 14,
    "type": "KbPositionArticle",
    "amount": "1.0000",
    "unit_id": null,
    "account_id": 79,
    "unit_name": null,
    "tax_id": 1,
    "tax_value": "8.00",
    "text": "Produkt 1",
    "unit_price": "5.4500",
    "discount_in_percent": null,
    "position_total": "5.4500",
    "pos": "6",
    "internal_pos": 8,
    "parent_id": null,
    "is_optional": false,
    "article_id": 1
  }
]

Show item position

GET /kb_offer/1/kb_position_article/14
Accept: application/json
Authorization: Bearer 677a1598d208d6c303fa5ca1c774709250e21749
Name Required Type Description
callback optional string Javascript callback

The following scopes are needed:

  • kb_invoice_edit
  • kb_offer_edit
  • kb_order_edit
  • kb_bill_edit
Status: 200 OK
X-Authenticated-User: apiextract_1
Content-Length: 305
Content-Type: application/json
{
  "id": 14,
  "type": "KbPositionArticle",
  "amount": "1.0000",
  "unit_id": null,
  "account_id": 79,
  "unit_name": null,
  "tax_id": 1,
  "tax_value": "8.00",
  "text": "Produkt 1",
  "unit_price": "5.4500",
  "discount_in_percent": null,
  "position_total": "5.4500",
  "pos": "6",
  "internal_pos": 8,
  "parent_id": null,
  "is_optional": false,
  "article_id": 1
}

Create item position

POST /kb_offer/1/kb_position_article
Accept: application/json
Authorization: Bearer 677a1598d208d6c303fa5ca1c774709250e21749
{
  "amount": 1,
  "tax_id": 1,
  "article_id": 1,
  "unit_price": 5.45,
  "text": "Produkt 1"
}
Name Required Type Description
callback optional string Javascript callback
Name Required Type Description
account_id required Resource account
amount required decimal
article_id required Resource article
tax_id required Resource tax
unit_price required decimal
discount_in_percent optional decimal
text optional string (4000)
unit_id optional Resource unit

The following scopes are needed:

  • kb_invoice_edit
  • kb_offer_edit
  • kb_order_edit
  • kb_bill_edit
Status: 201 Created
X-Authenticated-User: apiextract_1
Content-Length: 296
Content-Type: application/json
{
  "id": 14,
  "type": "KbPositionArticle",
  "amount": "1",
  "unit_id": null,
  "account_id": 79,
  "unit_name": null,
  "tax_id": 1,
  "tax_value": "8.00",
  "text": "Produkt 1",
  "unit_price": "5.45",
  "discount_in_percent": null,
  "position_total": "5.45",
  "pos": "6",
  "internal_pos": 8,
  "parent_id": null,
  "is_optional": false,
  "article_id": 1
}

Overwrite item position

PUT /kb_offer/1/kb_position_article/14
Accept: application/json
Authorization: Bearer 677a1598d208d6c303fa5ca1c774709250e21749
{
  "amount": 1,
  "tax_id": 1,
  "unit_price": 5.45,
  "text": "Produkt 1"
}
Name Required Type Description
callback optional string
Name Required Type Description
account_id required Resource account
amount required decimal
tax_id required Resource tax
unit_price required decimal
discount_in_percent optional decimal
is_optional optional boolean
text optional string (4000)
unit_id optional Resource unit

The following scopes are needed:

  • kb_invoice_edit
  • kb_offer_edit
  • kb_order_edit
  • kb_bill_edit
Status: 200 OK
X-Authenticated-User: apiextract_1
Content-Length: 296
Content-Type: application/json
{
  "id": 14,
  "type": "KbPositionArticle",
  "amount": "1",
  "unit_id": null,
  "account_id": 79,
  "unit_name": null,
  "tax_id": 1,
  "tax_value": "8.00",
  "text": "Produkt 1",
  "unit_price": "5.45",
  "discount_in_percent": null,
  "position_total": "5.45",
  "pos": "6",
  "internal_pos": 8,
  "parent_id": null,
  "is_optional": false,
  "article_id": 1
}

Edit item position

POST /kb_offer/1/kb_position_article/14
Accept: application/json
Authorization: Bearer 677a1598d208d6c303fa5ca1c774709250e21749
{
  "unit_price": 6
}
Name Required Type Description
callback optional string Javascript callback
Name Required Type Description
account_id optional Resource account
amount optional decimal
discount_in_percent optional decimal
is_optional optional boolean
tax_id optional Resource tax
text optional string (4000)
unit_id optional Resource unit
unit_price optional decimal

The following scopes are needed:

  • kb_invoice_edit
  • kb_offer_edit
  • kb_order_edit
  • kb_bill_edit
Status: 200 OK
X-Authenticated-User: apiextract_1
Content-Length: 295
Content-Type: application/json
{
  "id": 14,
  "type": "KbPositionArticle",
  "amount": "1.0000",
  "unit_id": null,
  "account_id": 79,
  "unit_name": null,
  "tax_id": 1,
  "tax_value": "8.00",
  "text": "Produkt 1",
  "unit_price": "6",
  "discount_in_percent": null,
  "position_total": "6",
  "pos": "6",
  "internal_pos": 8,
  "parent_id": null,
  "is_optional": false,
  "article_id": 1
}

Delete item position

DELETE /kb_offer/1/kb_position_article/14
Accept: application/json
Authorization: Bearer 677a1598d208d6c303fa5ca1c774709250e21749
Name Required Type Description
callback optional string Javascript callback

The following scopes are needed:

  • kb_invoice_edit
  • kb_offer_edit
  • kb_order_edit
  • kb_bill_edit
Status: 200 OK
X-Authenticated-User: apiextract_1
Content-Length: 16
Content-Type: application/json
{
  "success": true
}