Home Integration guide Invoice sending

Invoice sending via API

How to send an invoice

To send the invoice, use API method:

The method creates a new invoice from an existing XML invoice or a ZIP file with invoice XML file and attachments.

After creation the invoice is automatically sent to Maventa that does the the necessary conversions and validations before sending the invoice forward.

The sending methods can be used to give extra information related to sending. You can give a specific electronic address where to send the invoice or choose which routes you want or don’t want to use to send the invoice. Also it is possible to specify invoice UUID yourself. E.g. for case of timeouts, you can retry with same UUID and if it already exists you know the invoice got created already.

NOTE! Sending or receiving of invoices is not allowed if company_state is unverified (-1) and API will return error message “Unauthorized”. Invoices can be sent after the authorization is done.

Invoice statuses

SOAP API

The following states can be returned as invoice state values.

State code Reason Description
0 PENDING Awaiting delivery (scheduled transmission)
1 SENT Invoice sent
2 DECLINED Rejected/declined by the recipient (Only e-mail and internal Maventa)*
3 ACCEPTED Accepted/approved by the recipient (Only e-mail and internal Maventa)*
6 PAID Invoice marked as paid (Internal Maventa only)*
7 VIEWED Invoice link opened by the recipient (Only e-mail and internal Maventa)*
92 DISPUTED Disputed by the recipient (Only internal Maventa)*
99 ERROR Send error occurred

* = Internal and should be used for information only.

The main invoice states used are 0=PENDING, 1=SENT and 99=ERROR. Additionally invoice can get other states if it is sent from Maventa user to another. Note that these states are informational only! For example state “DISPUTED” does not mean legal disputing of invoice.

Invoice state flow

When invoice is sent it first gets the value “PENDING”, after that the invoice will go to either state “SENT” or state “ERROR”.

Invoice sending states

For internal recipients (recipients also using Maventa service) invoice can after sent state get further status based on the actions made on the invoice (“DECLINED”, “ACCEPTED”, “VIEWED” “PAID”, “DISPUTED”). If the invoice is sent to external operator or network it is possible that the state of the sent invoice changes to “ERROR” if operator or network returns an error of not being able to deliver the invoice.

REST API

Invoice state functionality is similar to SOAP API, but with REST only three different states are returned:

  • PROCESSING (matches to PENDING in SOAP API)
  • FAILED (matches to ERROR in SOAP API)
  • DELIVERED (matches to all other SOAP API states)

Webhooks & polling

For monitoring sent invoices we recommend to register webhooks. This way the sender can get the status changes of invoices immediately and take further actions if needed.

We also enable polling for the invoice status using the API methods:

  • SOAP: sent_invoices_status This is recommeneded to be done as a backup routine e.g. once a day for sent invoices in pending state to ensure that states get updated and all invoices fetched even if something unexpected would happen during the handling of the received message.
  • REST: GET /v1/invoices with param direction=SENT or GET /v1/invoices/{id}

Error handling

More information of invoices in error state can be seen by using API method:

Depending on the cause of the error invoices can be rerouted or a new invoice needs to be sent.