API: Sales invoices

POST /sales_api/addCreate a new sales invoice using FORM DATA.
POST /sales_api/add/finvoiceCreate a new sales invoice from Finvoice
POST /sales_api/do/upload_attachmentAdd an attachment to the sales invoice. Should be in PDF-format.
POST /sales_api/do/approveApprove an existing sales invoice in Fennoa.
POST /sales_api/do/sendSend an invoice to a customer. Only approved invoices can be sent.
POST /sales_api/add/paymentCreate a new sales invoice payment.
GET /sales_api/get/paymentsFetch a list of payments to sales invoices in Fennoa.
GET /sales_api/Get all the information about single sales invoice, including delivery and payment informations (using Fennoa invoice id).
GET /sales_api/get/invoice_noGet all the information about single sales invoice, including delivery and payment informations (using invoice number).

GET /sales_api/

Get all the information about single sales invoice (id) including delivery and payment informations or paged list of sales invoices.

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

/sales_api/<id>

Name Description Data type Req’d Example
id Unique identifier of the sales invoice int 100
?page=x List 200 invoices per page. x=page number. ?page=2

Response
Response code Description
200 Ok, fetching an invoice was successfull
400 Unable to fetch invoice
401 API key / company code is invalid or the user does not have permission to fetch ledger
404 Invoice not found
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 invoice data. Descriptions of sub-arrays below. array {”SalesInvoice”: {”id”: 100 … }}
Response data: SalesInvoice
Name Description Data type Possible values / Examples
id Unique identifier of the invoice int 100
invoice_no Invoice number int 1001
invoice_type_id 1 = Debit invoice, 2 = Credit invoice, 3=cash invoice int 1
auxiliary_name_id Auxiliary name identifier, if any int 1
customer_id Unique identifier of the customer int 50
name Name of the customer string Partner Inc
name2 Secondary name of the customer string Purchases department
address Street address of the customer string Mariankatu 2
postalcode Postal code of the customer string 00170
city City of the customer string Helsinki
shipping_name Shipping name (if any) string
shipping_name2 Secondary shipping name (if any) string
shipping_address Shipping address (if any) string
shipping_postalcode Shipping postalcode (if any) string
shipping_city Shipping city (if any)
total_net Invoice total sum (excl. VAT) number 10690.00
total_gross Invoice total sum (incl. VAT) number 13255.60
total_vat VAT sum number 2565.60
total_paid Paid sum number 0.00
total_due Due sum number 13255.60
banking_reference Banking reference string
invoice_date Invoice date string (date) 2018-11-14
due_date Due date string (date) 2018-12-29
cash_discount_date Cash discount date (if any) string (date)
cash_discount_sum Cash discount sum (if any) number
cash_discount_percent Cash discount percent (if any) number
vat_number VAT number of the customer string FI25939313
our_reference Our reference string Our salesperson
your_reference Customer’s reference string Customers contact person
penal_interest Penal interest number 7.50
complaint_days Complaint days int 8
notes_internal Internal notes (not visible in the invoice) string
notes_before Text above the invoice rows. Max. 500 characters. (Specification details in UI) string
delivery_method Delivery method string
delivery_terms Delivery terms string
shipping_date Shipping date string (date)
delivery_period_start Delivery start date string (date) 2022-03-01
delivery_period_end Delivery end date string (date) 2022-03-31
order_identifier Order Identifier string
agreement_identifier Agreement identifier string
tender_reference Tender reference string
delivery_note_identifier Delivery note identifier string
waybill_identifier Waybill idenfier string
created Timestamp when invoice was created string (datetime) 2018-11-15 05:30:33
Response data: Country
Name Description Data type Possible values / Examples
code Country code (ISO 3166-1) string FIN
Response data: ShippingCountry
Name Description Data type Possible values / Examples
code Country code (ISO 3166-1) string FIN
Response data: Currency
Name Description Data type Possible values / Examples
code Currency code (ISO 4217) string EUR
Response data: PaymentTerm
Name Description Data type Possible values / Examples
id Unique identifier of the payment terms int 10
name Name of the payment term string 14 days net
days Payment after X days after invoice date int 14
discount_1_days Cash discount if payment is not later than X days after invoice date int 3
discount_1_percent Cash discount % number 2.00
discount_2_days Cash discount if payment is made not later than X days after invoice date int 7
Response data: SalesInvoiceRow (array)
Name Description Data type Possible values / Examples
product_id Unique identifier of the product (if any) int 10
code Product code string ABC123
name Name of the product string Product ABC-123
Description Description string
price Unit price number 10690.00
price_with_vat Unit price (incl. VAT) – only given if the invoice is saved with VAT included number
include_vat 0 = Do not include VAT, 1 = Include VAT int 0
quantity Quantity number 1.00
unit Unit string pcs
vatpercent VAT-% number 24.00
discount_percent Discount-% number 0.00
total_net Invoice row total (excl. VAT) number 10690.00
total_vat Invoice row VAT total number 2565.60
total_gross Invoice row total (incl. VAT) number 13255.60
dim Row dimension: Dimension type:dimension value string DIM1:1000
Response data: SalesInvoiceDelivery (array)
Name Description Data type Possible values / Examples
address Electronic address the invoice has been sent to (or PRINT) string noreply@fennoa.com
einvoice_operator_id Unique identifier of the einvoice operator (null if not applicable) int
bic einvoice operator code string
sent Timestamp string (datetime)
Response data: SalesInvoicePayment (array)
Name Description Data type Possible values / Examples
description Description of the payment string
sum Sum of the payment number 6778.80
payment_date Date of the payment string (date) 2018-12-12
created Timestamp when the payment was created string (datetime) 2018-12-31 12:30:22

GET /sales_api/get/invoice_no

Get all the information about single sales invoice, including delivery and payment informations.

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

/sales_api/get/invoice_no/<invoice_no>

Name Description Data type Req’d Example
invoice_no Invoice number int YES 1234
Response

For detailed description of the response, please see /sales_api/ call.

POST /sales_api/add

Create a new sales invoice using FORM DATA.

Invoice rows are given as an array, for example row[x][quantity] is the quantity value of the row x.

Request parameters
Name Description Data type Req’d Example
customer_no Customer number string 1000
account_type Account type int 1=company (default)
2=consumer
name Name of the customer string YES Customer Inc
name2 Secondary name of the customer string Purchasing department
address Address of the customer string YES Mariankatu 2
postalcode Postalcode of the customer string YES 00170
city City of the customer string YES Helsinki
country Country code of the customer string YES FI
phone Phone number of the customer string
email Email of the customer string Just for info of the customer
sales_invoice_taxclass_id Tax classification
1= Domestic sales (S) Default
2=EU-sales services (K)
3=EU-sales goods (K)
4=Construction services (AE)
5=Scrap metal sales (AE)
6=Foreign sales, outside of EU (G)
7=Domestic sales VAT-free (Z)
8=Triangulation (K)
int 1
invoice_type_id Invoice type
1 = debit invoice
2 = credit invoice
3 = cash invoice
int 1
vat_number VAT number of the customer string 2593931-3
currency Currency code string EUR
invoice_date Invoice date (YYYY-MM-DD) string (date) YES 2018-12-12
due_date Due date (YYYY-MM-DD) string (date) YES 2018-12-26
shipping_date Shipping (entry) date (YYYY-MM-DD) string (date) 2018-11-30
cash_discount_date Cash discount date (YYYY-MM-DD) string (date)
cash_discount_percent Cash discount percent (if any) number
banking_reference Banking reference (if omitted, Fennoa will calculate automatically) string
locale Language of the invoice string fi, sv, en
our_reference Our reference string
your_reference Your reference string
contact_person Contact person string
penal_interest Penal interest number 7.0
notes_before Notes visible in the invoice form above invoice rows. Max. 500 characters.
string
delivery_method Delivery method of the invoice string postal, manual, *email, *finvoice, *consumerfinvoice, *consumerdirect
*needs also address in einvoice_address.
If sending to Peppol Network, use finvoice
einvoice_address Customer e-invoice address or email address for invoicing string
einvoice_operator einvoice operator, if sending email, leave empty string If sending to Peppol Network, use Peppol
shipping_name Shipping name (if any) string
shipping_name2 Secodary shipping name (if any) string
shipping_address Shipping address (if any) string
shipping_postalcode Shipping postalcode (if any) string
shipping_city Shipping city (if any) string
shipping_country Shipping country (code, if any) string FI
delivery_period_start Start of the delivery period string (date) 2018-11-01
delivery_period_end End of the delivery period string (date) 2018-11-30
credited_invoice_no If this is a credit invoice, enter the credited (debit) invoice number here int
proposed_invoice_number Invoice number in the source system. Fennoa will use this as the final invoice number once the invoice has been approved. int Minimum value is 100
notes_internal Internal notes (not visible in the invoice) string
sales_factoring_partner_id Is factoring invoice? int 0 = No, 1 = Yes
order_identifier Order identifier string
agreement_identifier Agreement identifier string
waybill_identifier Waybill identifier string
delivery_note_identifier Delivery note idenfifier string
delivery_terms Delivery terms string
delivery_method_text Delivery method of the goods (free text field printed on the invoice) string
include_vat Use ”price_with_vat” fields as primary and calculate the net sums from gross sums int 0 = No, 1 = Yes
sales_invoice_series_id Sales invoice series ID int 1
auxiliary_name_id Auxiliary name identifier, if any int 1
order_identifier Order identifier string
row[1][product_no] Product number for the first invoice row string
row[1][name] Product name for the first invoice row string
row[1][description] Description for the first invoice row string
row[1][price] Price for the first invoice row number 56.66
row[1][quantity] Quantity for the first invoice row number 12.50
row[1][unit] Unit for the first invoice row string pcs
row[1][vatpercent] VAT-% for the first invoice row int 0, 10, 14, 24
row[1][account_code] Accounting account code string 3001
Works only rows with product_no
row[1][discount_percent] Discount-% for the first row number 10.0
row[1][dim][dim(dim_type)] eg. row[1][dim][dim1]
Dimension () of the first invoice row
string 1000
row[2][product_no] Product number for the second invoice row

Notes:

  • For description rows (without prices etc) send only row[x][description] for the row x.
  • Row net sum always equals price * quantity * (1 – discount_percent / 100)
  • Row gross sum always equals netsum * (1 + vat_percent / 100)
  • Fennoa always calculates invoice sums automatically
  • Credit invoices must be negative. It is advised to use negative quantities and positive prices for credit invoices.
Response
Response code Description
200 Ok, invoice created successfully
400 Error creating invoice
401 API key / company code is invalid or the user does not have permission to fetch account balance
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

POST /sales_api/add/payment

Create a new sales invoice payment.

Name Description Data type Req’d Example
invoice_no Invoice number string YES 00123
payment_date Payment date string (date) YES 2021-06-06
sum Sum of payment float YES 15.25
payment_type Payment type int YES 2
is_factoring Has invoice been sent to factoring int YES 0 = no
1 = yes

POST /sales_api/add/finvoice

Create a new sales invoice from Finvoice using FORM DATA..

Request parameters
Name Description Data type Req’d
finvoice Finvoice XML YES

Finvoice file must be UTF-8 encoded. Invoice number must be only numbers and bigger than 100. If invoice number includes anything else than numbers it will be skipped.

Response
Response code Description
200 Ok, invoice created successfully
400 Error creating invoice
401 API key / company code is invalid or the user does not have permission to fetch account balance
405 Invalid method, double check you are sending ”POST” and not ”GET” etc
503 Service Unavailable
Description Data type Possible values / Examples
status Status of the operation string OK / ERROR

GET /sales_api/get/payments

Fetch a list of payments to sales invoices.

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

/sales_api/get/payments/<from_date>/<to_date>

Request parameters
from_date Fetch payments with payment date starting from string (date) YES 2018-12-01
to_date Fetch payments with payment date ending to string (date) YES 2018-12-31
Example queries:
  • Fetch all payments from November 2018:
    • /sales_api/get/payments/2018-11-01/2018-11-30
  • Fetch all payments from year 2018 that are created afterwards:
    • /sales_api/get/payments/2018-01-01/2018-12-31/created_after:2019-01-01
Response
Response code Description
200 Ok, fetching payments was successfull
400 Unable to fetch payments
401 API key / company code is invalid or the user does not have permission to fetch accounts
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
Response: SalesInvoicePayment
Name Description Data type Possible values / Examples
id Unique identifier of the payment int 50
date Date of the payment string (date) 2018-01-01
description Description of the payment string Viitesuoritus, Customer name
sum Amount of payment number 12883.60
Response: SalesInvoice
Name Description Data type Possible values / Examples
id Unique identifier of the sales invoice the payment is linked to int 100
name Customer name from the invoice string Customer Inc
invoice_no Invoice number int 1001

POST /sales_api/do/approve

Approve an existing sales invoice in Fennoa. Approving an invoice reserves an invoice number and creates accounting statements. It also allows sending it to the customer. Before approving the invoice is considered as a ”draft”.

Request parameters

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

/sales_api/do/approve/<id>

Name Description Data type Req’d Example
id Unique identifier of an invoice int YES 1
Response
Response code Description
200 Ok, invoice 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

POST /sales_api/do/send

Send an invoice to a customer. Only approved invoices can be sent. Invoice will be sent using the delivery method and address specified in the invoice data.

Request parameters

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

/sales_api/do/send/<id>

Name Description Data type Req’d Example
id Unique identifier of an invoice int YES 1
Response
Response code Description
200 Ok, invoice sent successfully
400 Error sending 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

POST /sales_api/do/upload_attachment

Add an attachment to the sales invoice. Should be in PDF-format.

Request parameters

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

/sales_api/do/upload_attachment/<id>

Name Description Data type Req’d Example
id Unique identifier of an invoice int YES 1
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 uploaded successfully and attached to the invoice
400 Error receiving the file
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
data Description of the status (if stataus = OK) string File stored.