Tech Blog

Creating an invoice using APIs

The purpose of this blog is to describe in details the required steps for creating a new invoice in Alma using APIs.

In general, creating an invoice using APIs is parallel to creating an invoice manually in the Alma UI. The following steps are required:

  • Create an invoice
  • Add invoice lines
  • Process the invoice (in Alma UI this is the “Save and continue” action, for moving the invoice forward in the workflow)

Note that invoice must be processed (Step 3) in order to be editable in the Alma User Interface.

Following is a detailed description of each step:

1. Create an invoice:

POST /almaws/v1/acq/invoices

An invoice body payload is required. For example:

<invoice>
  <number>A-127</number>
  <invoice_date>2018-08-06Z</invoice_date>
  <total_amount>120</total_amount>
  <currency>USD</currency>
  <vendor>ACM</vendor>
  <payment_method>ACCOUNTINGDEPARTMENT</payment_method>
  <owner>MY_LIB</owner>
  <invoice_vat>
    <vat_per_invoice_line>false</vat_per_invoice_line>
    <percentage>10.00</percentage>
    <type>INCLUSIVE</type>
    <expended_from_fund>true</expended_from_fund>
  </invoice_vat>
</invoice>

The response will include the invoice id (in “id” field). This id should be used in subsequent queries regarding the invoice. Note that “created from” is set to “API”.

2. Add invoice lines:

The following API adds a single invoice line. This means that you should submit it multiple times – according to the number of invoice lines.

POST /almaws/v1/acq/invoices/{invoice id}/lines

Payload of the invoice line body is required. For example:

<invoice_line>
  <type>REGULAR</type>
  <price>60</price>
  <quantity>1</quantity>
  <reporting_code>7020</reporting_code>
</invoice_line>

3. Process invoice:

You should submit this API after creating the invoice and its lines. This API is parallel to the “Save and continue” action in the Alma UI, and will process the invoice: The invoice will move forward in the workflow, or, if there are issues – will be sent to “review” with the relevant alerts.

Note that this step is mandatory.

POST /almaws/v1/acq/invoices/{invoice id}?op=process_invoice

An empty invoice object should be sent as a payload: The response will include the invoice with an updated status, and alerts (if exist).

Leave a Reply