API: Sales invoices
| POST /sales_api/add | Create a new sales invoice using FORM DATA. |
| POST /sales_api/add/finvoice | Create a new sales invoice from Finvoice |
| POST /sales_api/do/upload_attachment | Add an attachment to the sales invoice. Should be in PDF-format. |
| POST /sales_api/do/approve | Approve an existing sales invoice in Fennoa. |
| POST /sales_api/do/send | Send an invoice to a customer. Only approved invoices can be sent. |
| POST /sales_api/add/payment | Create a new sales invoice payment. |
| GET /sales_api/get/payments | Fetch 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_no | Get all the information about single sales invoice, including delivery and payment informations (using invoice number). |
| GET/sales_api/get/delivery_errors | Get delivery errors in invoices. |
| GET/sales_api/get/pdf/<id> | Get sales invoice image. |
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) | decimal | 10690.00 |
| total_gross | Invoice total sum (incl. VAT) | decimal | 13255.60 |
| total_vat | VAT sum | decimal | 2565.60 |
| total_paid | Paid sum | decimal | 0.00 |
| total_due | Due sum | decimal | 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) | decimal | |
| cash_discount_percent | Cash discount percent (if any) | decimal | |
| 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 | decimal | 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 % | decimal | 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 | decimal | 10690.00 |
| price_with_vat | Unit price (incl. VAT) – only given if the invoice is saved with VAT included | decimal | |
| include_vat | 0 = Do not include VAT, 1 = Include VAT | int | 0 |
| quantity | Quantity | decimal | 1.00 |
| unit | Unit | string | pcs |
| vatpercent | VAT-% | decimal | 24.00 |
| discount_percent | Discount-% | decimal | 0.00 |
| total_net | Invoice row total (excl. VAT) | decimal | 10690.00 |
| total_vat | Invoice row VAT total | decimal | 2565.60 |
| total_gross | Invoice row total (incl. VAT) | decimal | 13255.60 |
| dim | Row dimension: Dimension type:dimension value | string | DIM1:1000 |
| ProductGroups | id and name | string | ”id”: ”1”, ”name”: ”Myytävät” |
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 | decimal | 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.
GET/sales_api/get/delivery_errors
Returns delivery error messages for sales invoices, resend with corrected information by calling /sales_api/do/send/<id>.
Response
”SalesInvoiceDelivery”:
”sales_invoice_id”: ”1081”,
”invoice_no”: ”10677”,
”queued”: ”2024-08-07 13:45:00”,
”sent_message”: ”Receiver not found”
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 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) 9=Domestic sales, VAT-free, No VAT-liability (O) |
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 | 2024-10-12 |
| due_date | Due date (YYYY-MM-DD) | string (date) | YES | 2024-10-26 |
| shipping_date | Shipping (entry) date (YYYY-MM-DD) | string (date) | 2024-10-30 | |
| cash_discount_date | Cash discount date (YYYY-MM-DD) | string (date) | ||
| cash_discount_percent | Cash discount percent (if any) | decimal | ||
| 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 | decimal | 7.0 | |
| notes_before |
Notes visible in the invoice form above invoice rows. Max. 500 characters. |
string | ||
| delivery_method | Delivery method of the invoice, default postal | 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 | Required if any shipping_* details are filled | |
| 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) | string | ||
| shipping_country | Shipping country (code, if any) | string | use ISO 3166-1, must not be empty. If not given default code FI | |
| delivery_period_start | Start of the delivery period | string (date) | 2024-11-01 | |
| delivery_period_end | End of the delivery period | string (date) | 2024-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 | ||
| notes_fixed_width | Specification details | string |
Allow notes_fixed_width field as a array notes_fixed_with[0},…[1].. etc or as a single field. The limit is 8000 characters. |
|
| include_vat | Use ”price_with_vat” fields as primary and calculate the net sums from gross sums | int | ||
| 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 | ||
| sales_pricelist_id | Pricelist | int | 1 | |
| 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 | decimal | 56.66 | |
| row[1][quantity] | Quantity for the first invoice row | decimal | 12.50 | |
| row[1][unit] | Unit for the first invoice row | string | pcs | |
| row[1][vatpercent] | VAT-% for the first invoice row | decimal | 0, 10, 14, 24, 25.5 (Q3/2024) | |
| row[1][account_code] | Accounting account code | string |
3001 Works only rows with product_no |
|
| row[1][discount_percent] | Discount-% for the first row | 10.0 | ||
| row[1][dim][dim(dim_type)] |
eg. row[1][dim][dim1] Dimension ( |
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.
- sales_pricelist_id is the id of the customer-specific price list, you can first GET/customer_api and there sales_pricelist_id
- Get dimension type id’s with GET/dimension_api
- A period is used as decimal separator
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 | 2024-06-06 |
| sum | Sum of payment max 2 decimal | decimal | YES | 15.25 |
| payment_type | Payment type | int | YES |
Default payment type ID´s 2=Cash payment 3=Clearing account 4=Bank card receivables 5=Credit card receivables 6=Prepayment |
| is_factoring | Has invoice been sent to factoring | int | YES |
0 = no 1 = yes |
| Response code | Description |
|---|---|
| 200 | OK, payment created |
| 400 | Invoice payment is too large. |
| 401 | API key / company code is invalid or the user does not have permission to add payment |
| 405 | Invalid method, double check you are sending ”POST” and not ”GET” etc |
| 503 | Service Unavailable |
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 | decimal | 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 |
Optional parameters
Send the invoice with different address information / delivery method than given in invoice data, using FORM DATA or JSON. New information is updated on the invoice.
NOTE!
- If ”delivery_method” information is not provided, no other information will be used/updated.
- If any of the information is missing, the values set on the invoice will be used when sending the invoice.
- If additional information is provided, such as ”country” information in the ”email” delivery method, that information will be ignored without updating it in the customer or invoice information.
| Name | Description | Data type | Req’d | Example |
| id | Invoice ID | int | Yes | |
| delivery_method | finvoice, email, postal, consumerfinvoice, consumerdirect, manual (invoice is not sent but possible delivery error message is cleared) | string | ||
| address | Used only in the ”Postal” method | string | ||
| postalcode | Used only in the ”Postal” method | int | ||
| city | Used only in the ”Postal” method | string | ||
| country | Used only in the ”Postal” method | string | ||
| einvoice_address | E-mail address in ”email” method, e-invoice address in ”Finvoice” method | string | 00371234567 | |
| einvoice_operator_address | Operator , only for ”Finvoice” and ”ConsumerFinvoice” delivery methods | string | OKOYFIHH |
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. |
GET/sales_api/get/pdf/<id>
Returns the invoice, or a draft of the invoice depending it’s status, in application/pdf format. The body of the response contains the binary data of the file, delivered as a downloadable attachment.
The response includes a filename parameter within the Content-Disposition header, suggesting a default name for the downloaded file (e.g., invoice_{id}.pdf).
| Response code | Description |
| 200 | Ok |
| 500 | Failed to generate PDF from invoice or invoice was not found |