API: Purchases

GET /purchases_api/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 /api/purchases_api/get/unbookedGet unbooked or prebooked purchace invoices.
POST /api/purchases_api/addPost purchase invoices.
POST /api/purchases_api/do/upload_attachmentPost attachment to purchase invoice.

GET /purchases_api/

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

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
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) 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
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
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).

/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) 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
dim_X Dimension ID, where ”X” is the id of the dimension TYPE. For example dim_1: 100 int NO 100

* = 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.

/api/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 /api/purchases_api/get/unbooked

Get unbooked or prebooked purchace invoices.

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

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 /api/purchases_api/add

Post purchase invoices to Fennoa.

/api/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
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 number
total_gross Total gross number Yes
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

*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

POST /api/purchases_api/do/upload_attachment

Post PDF-attachment to purchase invoice.

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