Use case
Sales invoices are transferred from external system to Procountor and invoices are wanted to send automatically from Procountor to customer too.
Procountor software requires that the sales invoice needs to be approved before sending. After importing the status of sales invoice is “Unfinished”. The invoice needs to be approved first and then it is ready to be sent. No changes can be made to the invoice after approval.
Endpoints to be used and other requirements
POST /invoices endpoint creates a new invoice. Status of new invoice is always “UNFINISHED”. Successfully saved invoice returns invoice data including id of the invoice. The id of the invoice is needed for approving and sending the invoice.
PUT /invoices/{id}/approve endpoint approves the invoice.
PUT /invoices/{id}/send endpoint sends the invoice.
Process of sales invoice in brief
Setting the reference number
According to the Finvoice standard, a reference number is mandatory for electronic invoices. However, to ensure proper payment allocation, all invoices, including those sent via other channels too, must include a reference number.
Via the API interface, the reference number is set as follows:
Procountor automatically generates a reference number if the value provided in the request is empty: "bankReferenceCode": ""
A reference number generated by another system can be provided in the bankReferenceCode field. The format of the reference number is validated.
If the invoice is posted without the bankReferenceCode field, it is created without a reference number.
Invoice channels
Sales Invoice Sending Channels and Related API Requirements
The available invoice channels (invoiceChannel) are:
EMAIL (email)
MAIL (mail)
ELECTRONIC_INVOICE (electronic invoice)
NO_SENDING (no sending)
More information about the different invoice channels can be found here.
When an invoice is sent by email, the recipient’s email address (counterParty.email) is mandatory.
It is possible to provide the customer’s address details (counterParty.counterPartyAddress), a billing address (billingAddress), and a delivery address (deliveryAddress) for the invoice.
If no billing address is specified, the customer’s counter party address details are used as the billing address.
If the billing address differs from the customer’s address, a separate billing address must be provided on the invoice.
Electronic invoice
The recipient’s e-invoice address is provided in the invoice’s counterParty.einvoiceAddress element:
address – recipient’s e-invoice address (mandatory). The address will be validated.
operator – operator ID of the e-invoice operator (mandatory). This page lists the e-invoice operators available for selection in Procountor.
ediId – OVT ID (optional)
Example of Finago Oy’s e-invoice address:
"einvoiceAddress": {
"operator": "003723327487",
"address": "003708369224",
"ediId": "003708369224"
}
Sending the E-invoice abroad
A foreign e-invoice address (address) can be provided with the prefix 9999 in the format 9999electronicinvoiceaddress. When using the 9999 prefix, the e-invoice operator field (operator) must be left empty.
This requires that the environment is in production and that the company has a Finago Apix e-invoice sending address in use. In the trial use, the API will return an error.
Example when the customer’s foreign e-invoice address is 123456789:
"einvoiceAddress": {
"operator": "",
"address": "9999123456789"
}This article explains in more detail what needs to be considered when sending e-invoices abroad via Procountor.
No sending
When the invoice channel is set to No sending, the invoice is not sent via Procountor. This channel can be used, for example, in situations where the invoice has already been sent from another system.