Fetch purchase invoices approval queue, approve or reject invoices, fetch Finvoice data or set accounting propositions and dimensions
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
- 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 | |
| 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) | 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 | 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 | |||
| 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 | |
| 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 |