OpenAPI Specification
openapi: 3.0.3
info:
version: '1.0'
title: Company authorization items API
description: The Bokio Company API containing all resources for company tenant.
termsOfService: https://docs.bokio.se/page/terms/
contact:
name: Bokio
url: https://docs.bokio.se
email: support@bokio.se
servers:
- url: https://api.bokio.se/v1
description: Bokio API
x-bokio-api: true
security:
- tokenAuth: []
tags:
- name: items
description: Operations for managing inventory items
paths:
/companies/{companyId}/items:
parameters:
- name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
format: uuid
example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
post:
tags:
- items
summary: Create an item
description: 'Creates a new item for the company.
**Scope:** `items:write`
'
operationId: post-item
requestBody:
description: Post the necessary fields for the API to create a new item.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/item'
examples:
New item:
value:
description: Description of product 1
itemType: salesItem
productType: goods
unitType: piece
unitPrice: 100
taxRate: 25
bookkeepingAccountNumber: 3920
responses:
'200':
description: Item created
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/item'
examples:
Item created:
value:
id: 835ba700-b306-4bd9-8447-59207b6b0002
description: Description of product 1
itemType: salesItem
productType: goods
unitType: piece
unitPrice: 100
taxRate: 25
bookkeepingAccountNumber: 3920
'400':
description: Missing Required Information
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: validation-error
message: Validation failed with 3 errors
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
errors:
- field: '#/description'
message: The description field is required
- field: '#/itemType'
message: The item type field is required
- field: '#/unitPrice'
message: The unit price field is required
security:
- tokenAuth: []
get:
tags:
- items
summary: Get items
description: 'Get all items for the company. Use the query parameters to filter and navigate through the results.
**Scope:** `items:read`
'
operationId: get-items
parameters:
- name: page
in: query
required: false
description: Page number
schema:
type: integer
format: int32
default: 1
- name: pageSize
in: query
required: false
description: Number of items per page
schema:
type: integer
format: int32
default: 25
maximum: 100
- name: query
in: query
required: false
description: 'Optional query to filter the data set with supported fields listed below and [available operations](filtering).
| Field | Type |
| -------------------- | ----------- |
| description | string |
| itemType | string |
| productType | string |
| unitType | string |
| unitPrice | number |
| taxRate | number |
'
schema:
type: string
example: description~Product 1
responses:
'200':
description: Items found
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/pagedResponse'
- type: object
properties:
items:
type: array
items:
oneOf:
- $ref: '#/components/schemas/item'
security:
- tokenAuth: []
/companies/{companyId}/items/{itemId}:
parameters:
- name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
format: uuid
example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
- name: itemId
in: path
required: true
description: Unique identifier of the item
schema:
type: string
format: uuid
example: 83e3d68a-cfbc-46e4-9fe6-f0fc6d739672
get:
tags:
- items
summary: Get an item
description: 'Retrieve the information of the item with the matching itemId.
**Scope:** `items:read`
'
operationId: get-items-itemId
responses:
'200':
description: Item found
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/item'
examples:
Item found:
value:
id: 835ba700-b306-4bd9-8447-59207b6b0002
description: Description of product 1
itemType: salesItem
productType: goods
unitType: piece
unitPrice: 100
taxRate: 25
bookkeepingAccountNumber: 3920
'404':
description: Item Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: not-found
message: Item not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
put:
tags:
- items
summary: Update an item
description: 'Update an existing item for the company.
**Scope:** `items:write`
'
operationId: put-item
requestBody:
description: Post the necessary fields for the API to update an Item.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/item'
examples:
Update item:
value:
id: 835ba700-b306-4bd9-8447-59207b6b0002
description: Description of product 1
itemType: salesItem
productType: goods
unitType: piece
unitPrice: 100
taxRate: 25
bookkeepingAccountNumber: 3920
responses:
'200':
description: Item updated
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/item'
examples:
Update item:
value:
id: 835ba700-b306-4bd9-8447-59207b6b0002
description: Description of product 1
itemType: salesItem
productType: goods
unitType: piece
unitPrice: 100
taxRate: 25
bookkeepingAccountNumber: 3920
'400':
description: Missing required information
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: validation-error
message: Validation failed with 3 errors
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
errors:
- field: '#/description'
message: The description field is required
- field: '#/unitPrice'
message: The unit price field is required
- field: '#/taxRate'
message: 'Invalid tax rate. The tax rate must be one of the following values: 0%, 6%, 12%, or 25%'
security:
- tokenAuth: []
delete:
tags:
- items
summary: Delete an item
description: 'Delete an existing item for the company.
**Scope:** `items:write`
'
operationId: delete-item
responses:
'204':
description: Item deleted
security:
- tokenAuth: []
components:
schemas:
apiError:
type: object
title: apiError
properties:
code:
type: string
message:
type: string
bokioErrorId:
type: string
format: uuid
errors:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
pagedResponse:
type: object
title: pagedResponse
properties:
totalItems:
type: integer
format: int32
example: 1
totalPages:
type: integer
format: int32
example: 1
currentPage:
type: integer
format: int32
example: 1
item:
type: object
title: item
oneOf:
- $ref: '#/components/schemas/salesItem'
- $ref: '#/components/schemas/descriptionOnlyItem'
salesItem:
type: object
title: salesItem
required:
- description
- itemType
- productType
- unitType
- unitPrice
- taxRate
properties:
id:
type: string
format: uuid
nullable: true
description: Should not be set for new items
description:
type: string
minLength: 1
maxLength: 500
itemType:
type: string
enum:
- salesItem
productType:
type: string
enum:
- goods
- services
unitType:
type: string
enum:
- unspecified
- piece
- hour
- day
- month
- kilogram
- gram
- liter
- meter
- centimeter
- millimeter
- meterSquared
- meterCubic
- mile
- kilometer
- gigabyte
- hectar
- words
- year
- week
- minute
- megabyte
- ton
unitPrice:
type: number
format: double
taxRate:
type: number
format: double
bookkeepingAccountNumber:
type: integer
format: int32
nullable: true
description: The bookkeeping account number for this item. If not set, the account will be automatically selected based on the item productType, taxRate, customer and company settings.
example:
id: fc967153-1f8a-48d0-b773-fe3e61978263
description: Product 1
itemType: salesItem
productType: goods
unitType: piece
unitPrice: 100
taxRate: 25
bookkeepingAccountNumber: 3920
descriptionOnlyItem:
type: object
title: descriptionOnlyItem
required:
- description
- itemType
properties:
id:
type: string
format: uuid
nullable: true
description: Should not be set for new items
description:
type: string
itemType:
type: string
enum:
- descriptionOnlyItem
example:
id: bd34bd41-d13b-434d-858e-092231d6228a
description: Custom description line
itemType: descriptionOnlyItem
securitySchemes:
tokenAuth:
type: http
scheme: bearer
access_token:
type: oauth2
flows:
clientCredentials:
tokenUrl: /token
scopes: {}
authorizationCode:
authorizationUrl: /authorize
tokenUrl: /token
scopes:
bank-payments:read-limited: Read access to bank payments created by the integration
bank-payments:write: Write access to bank payments
chart-of-accounts:read: Read access to chart of accounts
company-information:read: Read access to company information
credit-notes:read: Read access to credit notes
credit-notes:write: Write access to credit notes
customers:read: Read access to customers
customers:write: Write access to customers
fiscal-years:read: Read access to fiscal years
invoices:read: Read access to invoices
invoices:write: Write access to invoices
items:read: Read access to items
items:write: Write access to items
journal-entries:read: Read access to journal entries
journal-entries:write: Write access to journal entries
sie:read: Read access to SIE files
supplier-invoices:read: Read access to supplier invoices
supplier-invoices:write: Write access to supplier invoices
suppliers:read: Read access to suppliers
suppliers:write: Write access to suppliers
tags:read: Read access to tag groups and tags
tags:write: Write access to tag groups and tags
uploads:read: Read access to uploads
uploads:write: Write access to uploads
client_auth:
type: http
scheme: basic
externalDocs:
url: https://docs.bokio.se
description: Read the API Documentation
x-readme:
explorer-enabled: true
proxy-enabled: false
samples-languages:
- shell
- http
- node
- csharp
- java