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