OpenAPI Specification
openapi: 3.0.3
info:
version: '1.0'
title: Company authorization invoices 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: invoices
description: Operations for managing invoices
paths:
/companies/{companyId}/invoices:
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:
- invoices
summary: Create an invoice
description: 'Creates a new draft invoice for the company.
**Scope:** `invoices:write`
'
operationId: post-invoice
requestBody:
description: Post the necessary fields for the API to create a new invoice.
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
examples:
New invoice:
value:
type: invoice
customerRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
contactDetailRef:
id: d3b07384-d9a0-4c9b-8b3a-6e1f2a5c8d4e
invoiceNumber: '1234'
orderNumberReference: ORD-5678
projectReference: PROJ-001
buyerReference: BUYER-123
contractReference: CONTRACT-456
currency: SEK
currencyRate: 1
totalAmount: 10000
totalTax: 2500
paidAmount: 0
invoiceDate: 2024-10-10
dueDate: 2024-10-10
lineItems:
- description: Product 1
itemRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
itemType: salesItem
productType: goods
unitType: piece
quantity: 1
unitPrice: 5000
taxRate: 25
- description: Installation work
itemType: salesItem
productType: services
unitType: hour
quantity: 10
unitPrice: 500
taxRate: 25
taxReduction:
taxReductionType: rot
jobType: rotConstruction
- description: A description line
itemType: descriptionOnlyItem
deliveryAddress:
line1: Delivery Street 15
line2: Floor 2
city: Stockholm
postalCode: 111 11
country: SE
taxReduction:
type: rot
description: Bathroom renovation
propertyType: realEstate
realEstateNumber: STOCKHOLM SÖDER 1:2
deductionPeople:
- personalNumber: 19850101-1234
deductionAmount: 1500
metadata:
project: Website Redesign
department: IT
externalId: EXT-INV-2024-001
responses:
'200':
description: Invoice created
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
examples:
invoice created:
value:
id: a419cf69-db6f-4de9-992c-b1a60942a443
type: invoice
customerRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
contactDetailRef:
id: d3b07384-d9a0-4c9b-8b3a-6e1f2a5c8d4e
email: contact@customer1.com
phone: '+46701234567'
invoiceNumber: '1234'
paymentReference: null
orderNumberReference: ORD-5678
projectReference: PROJ-001
buyerReference: BUYER-123
contractReference: CONTRACT-456
currency: SEK
currencyRate: 1
totalAmount: 10000
totalTax: 2500
paidAmount: 0
status: draft
invoiceDate: 2024-10-10
dueDate: 2024-10-10
lineItems:
- id: 1
itemRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
description: Product 1
description: Product 1
itemType: salesItem
productType: goods
unitType: piece
quantity: 1
unitPrice: 5000
taxRate: 25
- id: 2
description: Installation work
itemType: salesItem
productType: services
unitType: hour
quantity: 10
unitPrice: 500
taxRate: 25
taxReduction:
taxReductionType: rot
jobType: rotConstruction
- id: 3
description: A description line
itemType: descriptionOnlyItem
billingAddress:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
deliveryAddress:
line1: Delivery Street 15
line2: Floor 2
city: Stockholm
postalCode: 111 11
country: SE
taxReduction:
type: rot
description: Bathroom renovation
propertyType: realEstate
realEstateNumber: STOCKHOLM SÖDER 1:2
deductionAmount: 1500
status: draft
deductionPeople:
- personalNumber: 19850101-1234
deductionAmount: 1500
attachmentRefs:
- id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
fileName: myfile.pdf
- id: 94a8f806-8493-40f6-9d5b-0495c84f8ab9
fileName: myfile2.pdf
metadata:
project: Website Redesign
department: IT
externalId: EXT-INV-2024-001
'400':
description: Missing required information
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: validation-error
message: Validation failed with 2 errors
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
errors:
- field: '#/invoiceDate'
message: The invoice date field is required
- field: '#/lineItems/0/taxRate'
message: The tax rate field is required
security:
- tokenAuth: []
- access_token:
- invoices:write
get:
tags:
- invoices
summary: Get invoices
description: 'Get all invoices for the company. Use the query parameters to filter and navigate through the results.
**Tax reduction:** Personal numbers in `taxReduction.deductionPeople` have the last 4 digits masked when the invoice was created by a different integration. Masked values are returned as `YYYYMMDD-XXXX`.
**Scope:** `invoices:read`
'
operationId: get-invoice
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).
View documentation for filtering on metadata [here](metadata).
| Field | Type |
| -------------------- | ----------- |
| type | string |
| customerRef | string |
| orderNumberReference | string |
| projectReference | string |
| buyerReference | string |
| contractReference | string |
| currency | string |
| totalAmount | number |
| status | string |
| invoiceDate | date |
| dueDate | date |
| metadata | string |
'
schema:
type: string
example: dueDate==2024-10-10&¤cy==SEK
responses:
'200':
description: Invoices found
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/pagedResponse'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/invoice'
security:
- tokenAuth: []
- access_token:
- invoices:read
/companies/{companyId}/invoices/{invoiceId}:
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: invoiceId
in: path
required: true
description: Unique identifier of the invoice
schema:
type: string
format: uuid
example: a419cf69-db6f-4de9-992c-b1a60942a443
get:
tags:
- invoices
summary: Get an invoice
description: 'Retrieve the information of the invoice with the matching invoiceId.
**Tax reduction:** Personal numbers in `taxReduction.deductionPeople` have the last 4 digits masked when the invoice was created by a different integration. Masked values are returned as `YYYYMMDD-XXXX`.
**Scope:** `invoices:read`
'
operationId: get-invoices-invoiceId
responses:
'200':
description: Invoice found
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
examples:
Update invoice:
value:
id: a419cf69-db6f-4de9-992c-b1a60942a443
type: invoice
customerRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
contactDetailRef:
id: d3b07384-d9a0-4c9b-8b3a-6e1f2a5c8d4e
email: contact@customer1.com
phone: '+46701234567'
invoiceNumber: '1234'
paymentReference: null
orderNumberReference: ORD-5678
projectReference: PROJ-001
buyerReference: BUYER-123
contractReference: CONTRACT-456
currency: SEK
currencyRate: 1
totalAmount: 10000
totalTax: 2500
paidAmount: 0
status: draft
invoiceDate: 2024-10-10
dueDate: 2024-10-10
lineItems:
- id: 1
itemRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
description: Product 1
itemType: salesItem
productType: goods
unitType: piece
quantity: 1
unitPrice: 5000
taxRate: 25
- id: 2
description: Installation work
itemType: salesItem
productType: services
unitType: hour
quantity: 10
unitPrice: 500
taxRate: 25
taxReduction:
taxReductionType: rot
jobType: rotConstruction
- id: 3
description: A description line
itemType: descriptionOnlyItem
billingAddress:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
deliveryAddress:
line1: Delivery Street 15
line2: Floor 2
city: Stockholm
postalCode: 111 11
country: SE
taxReduction:
type: rot
description: Bathroom renovation
propertyType: realEstate
realEstateNumber: STOCKHOLM SÖDER 1:2
deductionAmount: 1500
status: draft
deductionPeople:
- personalNumber: 19850101-1234
deductionAmount: 1500
attachmentRefs:
- id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
fileName: myfile.pdf
- id: 94a8f806-8493-40f6-9d5b-0495c84f8ab9
fileName: myfile2.pdf
journalEntryRef:
id: e7f8a972-5a21-411b-aed2-f224d1b6fd68
metadata:
project: Website Redesign
department: IT
externalId: EXT-INV-2024-001
'404':
description: Invoice not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: not-found
message: invoice not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
- access_token:
- invoices:read
put:
tags:
- invoices
summary: Update an invoice
description: 'Update an existing invoice draft for the company.
This operation will update all fields of the invoice. It''s recommended that you perform a GET request
to the invoice first to get the current state of the invoice and then update the fields you want to change.
**NOTE:** It''s only possible to update invoices that are in draft status.
**Tax reduction:** Only the integration that created the invoice can modify tax reduction data. If a different integration includes `taxReduction` changes in the request, the changes will be silently ignored and the existing tax reduction data will be preserved.
**Scope:** `invoices:write`
'
operationId: put-invoice
requestBody:
description: Post the necessary fields for the API to update an invoice.
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
examples:
Update invoice:
value:
id: a419cf69-db6f-4de9-992c-b1a60942a443
type: invoice
customerRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
contactDetailRef:
id: d3b07384-d9a0-4c9b-8b3a-6e1f2a5c8d4e
invoiceNumber: '1234'
orderNumberReference: ORD-5678
projectReference: PROJ-001
buyerReference: BUYER-123
contractReference: CONTRACT-456
currency: SEK
currencyRate: 1
totalAmount: 10000
totalTax: 2500
paidAmount: 0
invoiceDate: 2024-10-10
dueDate: 2024-10-10
lineItems:
- id: 1
description: Product 1
itemType: salesItem
productType: goods
unitType: piece
quantity: 1
unitPrice: 5000
taxRate: 25
- id: 2
description: Installation work
itemType: salesItem
productType: services
unitType: hour
quantity: 10
unitPrice: 500
taxRate: 25
taxReduction:
taxReductionType: rot
jobType: rotConstruction
- id: 3
itemRef:
id: e964435e-50ef-4524-a439-05ff87794952
description: A description line
itemType: descriptionOnlyItem
deliveryAddress:
line1: Delivery Street 15
line2: Floor 2
city: Stockholm
postalCode: 111 11
country: SE
taxReduction:
type: rot
description: Bathroom renovation
propertyType: realEstate
realEstateNumber: STOCKHOLM SÖDER 1:2
deductionPeople:
- personalNumber: 19850101-1234
deductionAmount: 1500
metadata:
project: Website Redesign
department: IT
externalId: EXT-INV-2024-001
responses:
'200':
description: Invoice updated
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
examples:
Update invoice:
value:
id: a419cf69-db6f-4de9-992c-b1a60942a443
type: invoice
customerRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
contactDetailRef:
id: d3b07384-d9a0-4c9b-8b3a-6e1f2a5c8d4e
email: contact@customer1.com
phone: '+46701234567'
status: draft
invoiceNumber: '1234'
paymentReference: null
orderNumberReference: ORD-5678
projectReference: PROJ-001
buyerReference: BUYER-123
contractReference: CONTRACT-456
currency: SEK
currencyRate: 1
totalAmount: 10000
totalTax: 2500
paidAmount: 0
invoiceDate: 2024-10-10
dueDate: 2024-10-10
lineItems:
- id: 1
description: Product 1
itemType: salesItem
productType: goods
unitType: piece
quantity: 1
unitPrice: 5000
taxRate: 25
- id: 2
description: Installation work
itemType: salesItem
productType: services
unitType: hour
quantity: 10
unitPrice: 500
taxRate: 25
taxReduction:
taxReductionType: rot
jobType: rotConstruction
- id: 3
itemRef:
id: e964435e-50ef-4524-a439-05ff87794952
description: A description line
description: A description line
itemType: descriptionOnlyItem
billingAddress:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
deliveryAddress:
line1: Delivery Street 15
line2: Floor 2
city: Stockholm
postalCode: 111 11
country: SE
taxReduction:
type: rot
description: Bathroom renovation
propertyType: realEstate
realEstateNumber: STOCKHOLM SÖDER 1:2
deductionAmount: 1500
status: draft
deductionPeople:
- personalNumber: 19850101-1234
deductionAmount: 1500
attachmentRefs:
- id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
fileName: myfile.pdf
- id: 94a8f806-8493-40f6-9d5b-0495c84f8ab9
fileName: myfile2.pdf
metadata:
project: Website Redesign
department: IT
externalId: EXT-INV-2024-001
'400':
description: Missing required information
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: validation-error
message: Validation failed with 2 errors
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
errors:
- field: '#/invoiceDate'
message: The invoice date field is required
- field: '#/lineItems/0/taxRate'
message: The tax rate field is required
security:
- tokenAuth: []
- access_token:
- invoices:write
delete:
tags:
- invoices
summary: Delete an invoice
description: 'Deletes the specified invoice. Only invoices in draft status can be deleted.
**Scope:** `invoices:write`
'
operationId: delete-invoice-with-id
security:
- tokenAuth: []
- access_token:
- invoices:write
responses:
'204':
description: Invoice deleted successfully
'400':
description: Invalid request or invoice cannot be deleted
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
InvalidRequest:
value:
code: operation-not-allowed
message: Invoice with value a419cf69-db6f-4de9-992c-b1a60942a443 cannot be deleted as it is not in draft status
bokioErrorId: 4d408943-7a1e-47ac-85a7-ac52b2c210d3
/companies/{companyId}/invoices/{invoiceId}/attachments:
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: invoiceId
in: path
required: true
description: Unique identifier of the invoice
schema:
type: string
format: uuid
example: a419cf69-db6f-4de9-992c-b1a60942a443
post:
tags:
- invoices
summary: Add an attachment to an invoice
description: 'Adds an attachment to an existing draft invoice. The attachment will be added last in the list of attachments on the invoice.
Attached files will appear as additional pages in the final invoice
Supported file types: jpeg, png and pdf
Show example of multipart MIME as we do for uploads
**NOTE:** The invoice must be in draft status.
Maximum file size is 4 MB and all files can''t exceed 10 MB.
Dimensions must be less than height of 7016 and width of 4960 in pixels
**Scope:** `invoices:write`
'
operationId: post-invoice-attachment
parameters:
- name: Content-Type
in: header
required: true
description: Content type of the request
schema:
type: string
example: multipart/form-data;boundary=JLQPFBPUP0
requestBody:
description: Post the necessary fields for the API to add an attachment to an invoice.
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: The file to attach to invoice
required:
- file
responses:
'200':
description: Attachment added to invoice
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/invoiceAttachment'
examples:
Attachment:
value:
id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
invoiceId: a419cf69-db6f-4de9-992c-b1a60942a443
fileName: myfile.pdf
'400':
description: Missing required information
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: validation-error
message: Missing required information
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
'404':
description: The requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
InvoiceNotFound:
value:
code: not-found
message: The requested resource invoice with value a419cf69-db6f-4de9-992c-b1a60942a443 was not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
AttachmentNotFound:
value:
code: not-found
message: The requested resource attachment with value 240a4af0-edfd-47b1-b4ab-f30450eaac19 was not found
bokioErrorId: 8d408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
- access_token:
- invoices:read
get:
tags:
- invoices
summary: Get attachments
description: 'Retrieve the information of the attachments for the invoice. Use the query parameters to filter and navigate through the results.
**Scope:** `invoices:read`
'
operationId: get-invoice-attachments
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 |
| ------------------------- | ----------- |
| fileName | string |
'
schema:
type: string
example: fileName~faktura
responses:
'200':
description: Attachments found
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/pagedResponse'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/invoiceAttachment'
examples:
Attachments:
value:
totalItems: 2
totalPages: 1
currentPage: 1
items:
- id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
invoiceId: a419cf69-db6f-4de9-992c-b1a60942a443
fileName: myfile.pdf
- id: 390a4af0-edfd-47b1-b4ab-f30450eaac19
invoiceId: a419cf69-db6f-4de9-992c-b1a60942a443
fileName: myfile2.pdf
'404':
description: The requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
InvoiceNotFound:
value:
code: not-found
message: The requested resource invoice with value a419cf69-db6f-4de9-992c-b1a60942a443 was not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
- access_token:
- invoices:read
/companies/{companyId}/invoices/{invoiceId}/attachments/{attachmentId}:
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: invoiceId
in: path
required: true
description: Unique identifier of the invoice
schema:
type: string
format: uuid
example: a419cf69-db6f-4de9-992c-b1a60942a443
- name: attachmentId
in: path
required: true
description: Unique identifier of the attachment
schema:
type: string
format: uuid
example: 240a4af0-edfd-47b1-b4ab-f30450eaac19
get:
tags:
- invoices
summary: Get an attachment
description: 'Retrieve the information of the attachment with the matching attachmentId.
**Scope:** `invoices:read`
'
operationId: get-invoice-attachment
responses:
'200':
description: Attachment found
content:
application/json:
schema:
$ref: '#/components/schemas/invoiceAttachment'
examples:
Attachment:
value:
id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
invoiceId: a419cf69-db6f-4de9-992c-b1a60942a443
fileName: myfile.pdf
'404':
description: Attachment not found
content:
application/json:
schema
# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bokio/refs/heads/main/openapi/bokio-invoices-api-openapi.yml