Invoice sending via API

How to send an invoice

To send the invoice, use API method:

• SOAP: invoice_put_invoice_with_metadata
• REST: POST /v1/invoices

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.

* = 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”.

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:

• SOAP: invoice_show
• REST: GET /v1/invoices/{id}/actions

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

• Validation errors Invoice data is structurally not correct or invoice content is not valid, for example due date for the invoice is in the past. To fix the issue create and send a new invoice with necessary corrections.

• Routing errors The recipient is not found or the route is not in use. To fix the issue reroute the invoice to another route, or activate needed service and resend.

  • SOAP: invoice reroute
  • REST:
    • PUT/v1​/invoices​/{id}​/reroute​/einvoice to route the invoice to an electronic address
    • PUT/v1​/invoices​/{id}​/reroute​/email to route the invoice to an email address
    • PUT/v1​/invoices​/{id}​/reroute​/print to route the invoice via print