API: Purchases

Content:

GET /purchases_api/<id>: Get all the information about single purchase invoice
GET /purchases_api/get/approval_queue: Get the list of purchase invoices waiting for (API user’s) approval
GET-/purchases_api/get/finvoice: Fetch the original Finvoice data (if available)
GET-/purchases_api/get/attachment: Fetch an attachment of the purchase invoice
POST /purchases_api/do/approve: Approve a purchase invoice approval
POST /purchases_api/do/reject: Reject a purchase invoice approval
POST /purchases_api/do/set_tags: Set tags for a purchase invoice
GET /purchases_api/get/tags: Get purchace invoice tags
GET /purchases_api/get/unbooked: Get unbooked or prebooked purchace invoices
GET/purchases_api/get/list: Get list of purchase invoices
POST /purchases_api/add: Post purchase invoices
POST /purchases_api/do/upload_attachment: Post attachment to purchase invoice
GET /purchaces_api/get/suppliers: Get suppliers
POST /purchases_api/do/add_payment: Post manual payment to purchace invoice

GET /purchases_api/<id>

Get all the information about single purchase invoice.

Request parameters are given as part of the URL as follows:

/purchases_api/<id>

Name	Description	Data type	Req’d	Example
id	Unique identifier of the purchase invoice	int	YES	100

Response

Response data: PurchaseInvoice

Name	Description	Data type	Possible values / Examples
id	Unique identifier of the invoice	int	100
supplier_name	Supplier name	string
supplier_business_id	Supplier business id (y-tunnus)	string	2593931-3
supplier_vat_number	Supplier VAT number	string	FI25939313
invoice_date	Invoice date	string (date)	2023-09-01
due_date	Due date	string (date)	2023-09-15
entry_date	Entry date	string (date)
total_gross	Invoice total sum (incl. VAT)	number
total_due	Due sum	number
total_gross_hc	Invoice total sum in EUR (incl. VAT)	number
total_net
total_net_hc
currency_rate	Currency conversion rate used	number
our_reference	Selle’rs reference	string
your_reference	Buyer’s reference	string
invoice_number	Invoice number	string
order_number	Order number	string
purchase_order_id	Purchase order identifier	int
bank_account	Bank account	string
bank_bic	Bank BIC/SWIFT code	string	NDEAFIHH
bank_message	Bank message	String
bank_reference	Banking reference	string
terms_of_payment	Terms of payment	string
is_receipt	0 = Purchase invoice, 1 = Purchase receipt	int	0
is_first_invoice	Is this the first invoice from this supplier, 0 = No, 1 = Yes	int
on_hold	1=Yes, 0=No
finvoice_available	1 = Finvoice is available for downloading (see below)	int	1
created	Creation date (in Fennoa) of invoice	date	2023-12-19 09:12:27
ApprovalStatus	”status_id”:10,”status”:”Approved”
	”status_id”:0,”status”:”Waiting for approval”
	”status_id”:30, ”status”:”Rejected”
Approvers	”user_id”
	”approval_level”
	”approval_level id”
	”status_id”
	”status”

Responce data: Currency

Name	Description	Data type	Possible values / Examples
code	Currency code (ISO 4217)	string	EUR
name	Name of currency	string	Euro

Response data: PurchaceInvoiceType

Name	Description	Data type	Possible values / Examples
name	Purchase invoice type name	string	Debit invoice / Credit invoice

Response data: PurchaseInvoiceRow

"PurchaseInvoiceRow": [
{
"article_identifier": "10",
"article_name": "Rullahiiri",
"freetext": "",
"price": "49.00000000",
"unit": "EA",
"quantity": "7.00000000",
"sum_net": "343.00000000",
"sum_gross": "430.47000000",
"vatpercent": "25.50",
"discount_value": null,
"discount_percent": "0.00"
}

Response data: Attachments

Name	Description	Data type	Possible values / Examples
id	Unique identifier of the attachment	int	123
file	Filename of the attachment	string	file.pdf
mimetype	MIME type of the attachment	string	application/pdf
filesize	Size of file	string	3224105

GET /purchases_api/get/approval_queue

Get the list of purchase invoices waiting for (API user’s) approval.

Maximum number of purchase invoices is 20. To fetch further invoices, page number must be given:

/purchases_api/get/approval_queue/<page>

Request parameters

Name	Description	Data type	Req’d	Example
page	Page number (default is 1)	int	NO	2
modifiedAfter= yyyy-mm-ddThh:mm:ss	Show only purchase invoices/approvals modified after given date and time. Can be used with or without timestamp. Timestamp can be used without seconds. hh:mm	date time	NO	2024-10-01T T14:21:22

Name

Description

Data type

Req’d

Example

page

Page number (default is 1)

int

modifiedAfter=

yyyy-mm-ddThh:mm:ss

Show only purchase invoices/approvals modified after given date and time.
Can be used with or without timestamp. Timestamp can be used without seconds. hh:mm

date time

2024-10-01T
T14:21:22

Response

Response code	Description
200	Ok, fetching a list was successfull
400	Unable to fetch list
401	API key / company code is invalid or the user does not have permission to fetch list
405	Invalid method, double check you are sending ”GET” and not ”POST” etc
500	Server was unable to process the request due to a technical failure
503	Service Unavailable

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
data	Array containing approval queue.	array
data.count	Total number of purchase invoices in approval queue	int
data.page	Fetched page number	int

Response data: PurchaseInvoice

Name	Description	Data type	Possible values / Examples
id	Unique identifier of the invoice	int	100
supplier_name	Supplier name	string
supplier_business_id	Supplier business id (y-tunnus)	string	2593931-3
supplier_vat_number	Supplier VAT number	string	FI25939313
invoice_date	Invoice date	string (date)	2023-09-01
due_date	Due date	string (date)	2023-09-15
entry_date	Entry date	string (date)
total_gross	Invoice total sum (incl. VAT)	number
total_due	Due sum	number
total_gross_hc	Invoice total sum in EUR (incl. VAT)	number
currency_rate	Currency conversion rate used	number
our_reference	Selle’rs reference	string
your_reference	Buyer’s reference	string
invoice_number	Invoice number	string
order_number	Order number	string
purchase_order_id	Purchase order identifier	int
bank_account	Bank account	string
bank_bic	Bank BIC/SWIFT code	string	NDEAFIHH
bank_reference	Banking reference	string
is_receipt	0 = Purchase invoice, 1 = Purchase receipt	int	0
is_first_invoice	Is this the first invoice from this supplier, 0 = No, 1 = Yes	int
on_hold	1=Yes, 0=No
finvoice_available	1 = Finvoice is available for downloading (see below)	int	1
created	Timestamp of purchase invoice creation	string (datetime)	2023-01-01 12:00:00
modified	Timestamp of purchase invoice’s last modification	string (datetime)

Response data: Currency

Name	Description	Data type	Possible values / Examples
code	Currency code (ISO 4217)	string	EUR

Response data: PurchaseInvoiceType

Name	Description	Data type	Possible values / Examples
name	Purchase invoice type name	string	Debit invoice / Credit invoice

Response data: PurchaseInvoiceRow is null

Use GET /purchases_api/<id> or GET /purchases_api/get/finvoice (if available) to fetch rows

  "PurchaseInvoiceRow": {
                        "article_identifier": null,
                        "article_name": null,
                        "freetext": null,
                        "price": null,
                        "unit": null,
                        "quantity": null,
                        "sum_net": null,
                        "sum_gross": null,
                        "vatpercent": null,
                        "discount_value": null,
                        "discount_percent": null
                    }

Response data: PurchaseInvoiceApproval

Name	Description	Data type	Possible values / Examples
id	Unique identifier of the approval (used in approving/rejecting)	int	1000
approval_level	Level of approval, 1 = Approval (most important), 2 = Verification, 3 = Pre-verification	int	1
status	Status of approval, 0 = Not approved	int	0

Response data: Attachments

Name	Description	Data type	Possible values / Examples
id	Unique identifier of the attachment	int	123
file	Filename of the attachment	string	file.pdf
mimetype	MIME type of the attachment	string	application/pdf

GET /purchases_api/get/finvoice

Fetch the original Finvoice data (if available). Finvoices are available 12 month from inbound date.

/purchases_api/get/finvoice/<id>

Request parameters

Name	Description	Data type	Req’d	Example
id	Purchase invoice id	int	YES	1000

Response

Response code	Description
200	Ok, fetching a finvoice was successfull
400	Unable to fetch finvoice
401	API key / company code is invalid or the user does not have permission to fetch finvoice
404	Purchase invoice not found or finvoice data is not available
405	Invalid method, double check you are sending ”GET” and not ”POST” etc
503	Service Unavailable

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
data	Array containing approval queue.	array
data.encoding	Encoding used (always base64)	string	base64

GET /purchases_api/get/attachment

Fetch an attachment of the purchase invoice.

/purchases_api/get/attachment/<purchase_invoice_id>/<attachment_id>

Request parameters

Name	Description	Data type	Req’d	Example
purchase_invoice_id	Purchase invoice identifier	int	YES	1000

Response

Response code	Description
200	Ok, fetching an attachment was successfull
400	Unable to fetch attachment
401	API key / company code is invalid or the user does not have permission to fetch attachment
404	Purchase invoice not found, attachment not found, or given attachment_id does not belong to the given purchase_invoice_id
405	Invalid method, double check you are sending ”GET” and not ”POST” etc
503	Service Unavailable

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
data	Array containing the data requested	array
data.encoding	Encoding used (always base64)	string	base64
data.mimetype	MIME type of the attachment	string	application/pdf

POST /purchases_api/do/approve

Approve a purchase invoice approval.

/purchases_api/do/approve/<approval-id>

An approval comment is optional:

/purchases_api/do/approve/<approval-id>/[<comment>]

comment max 200 characters

Request parameters

Name	Description	Data type	Req’d	Example
approval-id	Purchase invoice APPROVAL id	int	YES	1000

Response

Response code	Description
200	Ok, purchase invoice was approved successfully
400	Error approving invoice
401	API key / company code is invalid or the user does not have permission
405	Invalid method, double check you are sending ”POST” and not ”GET” etc
503	Service Unavailable

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
errors	Array of errors (only if status = ERROR)	array

POST /purchases_api/do/reject

Reject a purchase invoice approval. Comment/reason is mandatory.

/purchases_api/do/approve/<approval-id>/<comment>

Request parameters

Name	Description	Data type	Req’d	Example
approval-id	Purchase invoice APPROVAL id	int	YES	1000

Response

Response code	Description
200	Ok, purchase invoice was rejected successfully
400	Error rejecting invoice
401	API key / company code is invalid or the user does not have permission
405	Invalid method, double check you are sending ”POST” and not ”GET” etc
503	Service Unavailable

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
errors	Array of errors (only if status = ERROR)	array

POST /purchases_api/do/set_tags

Set tags for a purchase invoice. Tags are used to prebook a purchase invoice and to guide the bookkeeper how it should be booked. If the purchase invoice is already booked, tags have no effect.

/purchases_api/do/set_tags/<purchase_invoice_id>

Request data

Tags are given in JSON array format using single field, ”json”.

Name	Description	Data type	Req’d	Example
json	Tags data in JSON format (see JSON data fields below) in array	string	YES	[{”percent”:100,”account_code”:4000}]

JSON data

The table below explains all of the possible fields for a single row.

Name	Description	Data type	Req’d	Example
percent	Percentage of the purchase invoice (gross) sum being tagged	number	YES*	100.00
sum	Sum being tagged	number	YES*	59.99
account_code	Account code	int	NO	4000
vatcode_id	VAT handling (identifier) for the row. Use GET /accounting_api/get/vatcodes for full list of VAT handling identifiers and their functions. NOTE! Use only vatcodes with type ”purchases”.	int	NO	1
dim_X	Dimension ID, where ”X” is the id of the dimension TYPE and value is id of dimension. For example dim_1: 100	int	NO	100
description	Description	string	NO	Description text

* = Either percent OR sum is required. If both are given, sum is dominate.

Example JSON data

”json”: ”[{\”percent\”:100,\”account_code\”:4020,\”vatcode_id\”:1,\”dim_1\”:100, \”description\”:\”selite\” }]”

Response

Response code	Description
200	Ok, purchase invoice tags was set succesfully
400	Error setting tags
401	API key / company code is invalid or the user does not have permission
405	Invalid method, double check you are sending ”POST” and not ”GET” etc
503	Service Unavailable

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
errors	Array of errors (only if status = ERROR)	array

GET /purchases_api/get/tags

Get purchace invoice tags.

/purchases_api/get/tags/<invoiceId>

Request parameters

Name	Description	Data type	Req’d	Example
invoice_id	Purchase invoice identifier	int	YES	1000

Response data

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
errors	Array of errors (only if status = ERROR)	array

Response data: PuchaseInvoiceTag

Name	Description	Data type	Possible values / Examples
id	Unique identifier of the invoice	int	92
purchase_invoice_id	Purchase invoice id	string	291
description	Description	string	Selite
account_code	Account code	string	4011
sum	Sum	string (date)	2.00000000
percent	Percent	string (date)	40.0000
created	Creation date	string (date)	2022-03-19

GET /purchases_api/get/unbooked

Get unbooked or prebooked purchace invoices.

/purchases_api/get/unbooked

Request parameters

Name	Description	Req’d
showPreBooked=1	Shows prebooked purchase invoices
isApproved= 1	Shows level 1 approved purchase invoices
isApproved=0	Shows level 1 purchase invoices waiting approve
modifiedAfter=2024-04-25 12:48:00	Shows purchase invoices modified after given date	date and time
modifiedBefore=2024-04-25 12:48:00	Shows puchase invoices modified before given date	date and time
modifiedBefore=2024-04-24 12:45:00&modifiedAfter=2024-04-20 12:45:00	Shows puchase invoices modified within daterange	date and time

Only one isApproved parameter at time is allowed.

Response data

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
errors	Array of errors (only if status = ERROR)	array

Response data: PuchaseInvoice

Name	Description	Data type	Possible values / Examples
id	Unique identifier of the invoice	int	100
supplier_name	Supplier name	string
supplier_business_id	Supplier business id (y-tunnus)		2593931-3
invoice_date	Invoice date	string (date)	2019-09-01
due_date	Due date	string (date)	2019-09-15
entry_date	Entry date	string (date)
total_gross	Invoice total sum (incl. VAT)	number
total_due	Due sum	number
total_gross_hc	Invoice total sum in EUR (incl. VAT)	number
total_net		number
total_net_hc		number
currency_rate	Currency conversion rate used	number
our_reference	Seller’s reference	string
your_reference	Buyer’s reference	string
invoice_number	Invoice number	string
order_number	Order number	string
purchase_order_id	Purchase order identifier	string
bank_account	Bank account	string
bank_bic	Bank BIC/SWIFT code	string	NDEAFIHH
bank_message		string
bank_reference	Banking reference	string
terms_of_payment	Terms of payment	string
is_receipt	0 = Purchase invoice, 1 = Purchase receipt	int	0
is_first_invoice	Is this the first invoice from this supplier, 0 = No, 1 = Yes	int
on_hold	1=Yes, 0=No
created	Created	string (date)

GET/purchases_api/get/list

Example:

api/purchases_api/get/list?isApproved=1&includeReceipts=1&excludeIds=20,21

Request parameters

Name	Description
isApproved	1=Yes
includeReceipts	1=Yes
excludeInvoices	1=Yes
excludeIds	20,21
createdAfter	2025-01-01
createdBefore	2025-05-01

Response:

{
"status": "ok",
"data": [
{
"PurchaseInvoice": {
"id": "45",
"is_receipt": "0",
"created": "2025-01-07 06:32:23",
"finvoice_available": 1
}
},
{
"PurchaseInvoice": {
"id": "63",
"is_receipt": "0",
"created": "2025-02-12 11:13:07",
"finvoice_available": 1
}
},
{
"PurchaseInvoice": {
"id": "75",
"is_receipt": "1",
"created": "2025-03-27 11:46:47",
"finvoice_available": 0
}
}
]
}

POST /purchases_api/add

Create a new purchace invoice using FORM DATA, remember also to post the PDF-image for each invoice using POST /api/purchases_api/do/upload_attachment.

/purchases_api/add

Parameters

Name	Description	Data type	Req’d	Example
purchase_invoice_type_id	(default)Invoice type 1= invoice, 2=credit invoice		Yes
purchase_supplier_id	Supplier id. If empty creates new supplier. Non-Eu suppiers can not be created. Create in Fennoa before POST.	string	Yes/No
supplier_name	Supplier name	string	Yes
supplier_vat_number	Supplier VAT number	string
supplier_business_id	Supplier business id (y-tunnus)	string
supplier_country	Supplier country code, ISO 3166 alpha-2. Default (empty)= FI	string		FI
invoice_number	Invoice number	string
credited_invoice_no	Credited invoice number, if credit invoice	string
invoice_date	Invoice date (YYYY-MM-DD)	string(date)	Yes
due_date	Due date (YYYY-MM-DD)	string(date)	Yes
discount_date1	Discount date (YYYY-MM-DD)	string(date)
discount_percent1	Discount percent	number
discount_sum1	Sum of discount	number
entry_date	Entry date (YYYY-MM-DD)	string(date)
bank_account	Bank account	string	Yes
bank_bic	Bank BIC/SWIFT code	string	Yes
bank_reference	Banking reference	string	*Yes/No
bank_message	Banking message	string	*Yes/No
total_net	Total net, 2 decimals max	number		100.00
total_gross	Total gross, 2 decimals max	number	Yes	124.00
currency	Currency, ISO 4217, Default (empty) =EUR	string		EUR
order_number	Order number	string
your_reference	Your reference (customer´s)	string
our_reference	Our reference (supplier´s)	string
terms_of_payment	Terms of payment	string
payable_account_code	Payable account code	number		2780

*Bank reference OR bank message is req´d.

Response

Response code	Description
200	Ok, purchase invoice created succesfully
400	Error
401	API key / company code is invalid or the user does not have permission
405	Invalid method, double check you are sending ”POST” and not ”GET” etc
503	Service Unavailable

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
errors	Array of errors (only if status = ERROR)	array

Response data: PuchaseInvoice

Name	Description	Data type	Possible values / Examples
id	Unique identifier of the invoice id	int
purchase_supplier_id	If POST have no purchase_supplier_id, new suplier created and id in response.	int

POST /purchases_api/do/upload_attachment

Post PDF-attachment to purchase invoice.

/purchases_api/do/upload_attachment/<invoice id>

Parameters

Name	Description	Data type	Req’d	Example
id	Unique identifier of the invoice id	int	Yes

Form data

Content type must be multipart/form-data which is used to send binary data to the server. Form-data contains one field ”file” that is the actual file upload.

Name	Description	Data type	Req’d	Example
file	File do upload	file	Yes

Response

Response code	Description
200	Ok, File stored.
400	Error
401	API key / company code is invalid or the user does not have permission
405	Invalid method, double check you are sending ”POST” and not ”GET” etc
503	Service Unavailable

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
errors	Array of errors (only if status = ERROR)	array

GET /purchases_api/get/suppliers

Get suppliers.

/purchases_api/get/suppliers

Parameters

Name	Description	Data type	Example
page	Page number (default is 1)	int
createdAfter	Created after	date	2019-06-31
createdBefore	Created before	date	2019-06-31
modifiedAfter	Modified before	date	2019-06-31
modifiedBefore	Modified after	date	2019-06-31

Response data

Name	Description	Data type	Possible values / Examples
status	Status of the operation	string	OK / ERROR
errors	Array of errors (only if status = ERROR)	array

Response data: PuchaseSupplier

Name	Description	Data type	Possible values / Examples
id	Unique identifier of the supplier	int	100
name	Name	string
name2	Name 2	string
address	Street address	string
postalcode	Postal code	string
city	City	string
country_id	Fennoa country id	int
business_id	Business id	string
vat_number	VAT-number	string
bank_account	IBAN	string
bank_bic	BIC	string
bank_account_2	IBAN	string
bank_bic_2	BIC	string
bank_account_3	IBAN	string
bank_bic_3	BIC	string
bank_account_4	IBAN	string
bank_bic_4	BIC	string
bank_clearing_code	Clearing code	string
bank_name	Bank´s name	string
bank_name2	Name 2	string
bank_address	Address	string
bank_postalcode	Postal code	string
bank_city	City	string
bank_country_id	Fennoa country id	int
default_account_code	Default account code	string
default_currency_id	Default Fennoa currency id	int
default_payment_terms_id	Default Fennoa payment terms id	int
created	Created date	string (date)	2019-12-30
modified	Modified date	string (date)	2019-12-31

POST /purchases_api/do/add_payment

Create a payment to purchace invoice using JSON. Needs accountant rights.

Name	Description	Req’d	Example
purchase_invoice_id	Purchace invoice id	YES	123
sum	Sum of payment	YES	100.00
payment_date	Payment date (YYYY-MM-DD)	YES	2023-04-26
description	Description		Cash payment
account_code	Account code (if no account code, default 199999)		1234

API: Purchases

Fetch purchase invoices approval queue, approve or reject invoices, fetch Finvoice data or set accounting propositions and dimensions

GET /purchases_api/<id>

Response

Response data: PurchaseInvoice

Responce data: Currency

Response data: PurchaceInvoiceType

Response data: PurchaseInvoiceRow

Response data: Attachments

GET /purchases_api/get/approval_queue

Request parameters

Response

Response data: PurchaseInvoice

Response data: Currency

Response data: PurchaseInvoiceType

Response data: PurchaseInvoiceRow is null

Response data: PurchaseInvoiceApproval

Response data: Attachments

GET /purchases_api/get/finvoice

Request parameters

Response

GET /purchases_api/get/attachment

Request parameters

Response

POST /purchases_api/do/approve

Request parameters

Response

POST /purchases_api/do/reject

Request parameters

Response

POST /purchases_api/do/set_tags

Request data

JSON data

Example JSON data

Response

GET /purchases_api/get/tags

Request parameters

Response data: PuchaseInvoiceTag

GET /purchases_api/get/unbooked

Request parameters

Response data: PuchaseInvoice

GET/purchases_api/get/list

Request parameters

POST /purchases_api/add

Parameters

Response

Response data: PuchaseInvoice

POST /purchases_api/do/upload_attachment

Parameters

Response

GET /purchases_api/get/suppliers

Parameters

Response data: PuchaseSupplier

POST /purchases_api/do/add_payment