API: Purchases

GET /purchases_api/<id>Get all the information about single purchase invoice.
GET /purchases_api/get/approval_queueGet the list of purchase invoices waiting for (API user’s) approval.
GET-/purchases_api/get/finvoiceFetch the original Finvoice data (if available).
GET-/purchases_api/get/attachmentFetch an attachment of the purchase invoice.
POST /purchases_api/do/approveApprove a purchase invoice approval.
POST /purchases_api/do/rejectReject a purchase invoice approval.
POST /purchases_api/do/set_tagsSet tags for a purchase invoice.
GET /purchases_api/get/tagsGet purchace invoice tags.
GET /purchases_api/get/unbookedGet unbooked or prebooked purchace invoices.
POST /purchases_api/addPost purchase invoices.
POST /purchases_api/do/upload_attachmentPost attachment to purchase invoice.
GET /purchaces_api/get/suppliersGet suppliers
POST /purchases_api/do/add_paymentPost 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) 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
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
finvoice_available 1 = Finvoice is available for downloading (see below) int 1
created Creation date (in Fennoa) of invoice date 2018-12-19 09:12:27
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
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-dd Show only purchase invoices/approvals modified after given date date NO 2023-01-01
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
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
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>]

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 /account_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

[

{

”percent”:50.00,

”account_code”: 4000,

”description”: ”50% to account 4000 (purchases)”

},

{

”sum”: 40.99,

”dim_1”: 100,

”dim_2”: 200,

”description”: ”Bought something for 40.99 euros that belongs to two dimensions”

},

]

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 Data type Req’d Example
showPreBooked=1 Shows prebooked purchase invoices
isApproved= 1 Shows level 1 approved purchase invoices
isApproved=0 Shows level 1 purchase invoices waiting approve

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
created Created string (date)

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 Req’d 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