Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

Alma - ERP invoices integration using APIs

Tamar Fuches on November 19th, 2018

The Alma acquisitions process includes ordering and receiving materials from vendors, which involves the handling of both orders and invoices by vendors.
Invoices are handled outside of the library's scope, usually by the institution's Enterprise Resource Planning (ERP) system. Invoices must therefore be exported from Alma to the institution's financial system.
Institutions that want to receive confirmation about the invoice status in the Enterprise Resource Planning (ERP) system, can import the invoices from the ERP back into Alma.
Traditionally, the export and import of invoices was done using FTP servers. See Alma - Finance integration.
The December 2018 Alma release includes several new APIs for utilizing invoices integration using APIs.

The purpose of this blog is to describe in details the required steps for implementing end-to-end invoices integration with finance system using APIs.

1. Retrieve invoices for ERP handling - status code is "waiting to be sent":
GET /almaws/v1/acq/invoices?invoice_workflow_status=Waiting to be Sent&view=brief

The response will include a list of invoices that should be handled by the ERP.

2. ERP starts working on the invoice, so marks it as in ERP:
POST /almaws/v1/acq/invoices/<invoice id>?op=mark_in_erp

payload should be an empty invoice object:

<invoice>
</invoice>

Note that the status of the invoice is updated according to the institution's workflow (handle_invoice_payment parameter): If a confirmation should be returned from ERP, the status will be updated to "Waiting for Payment". Else, the invoice will be closed. This logic is the same as in the "Invoice export" job.

3. For institutions that work with confirmation from ERP, ERP should update the invoice as "paid" or as "rejected":
POST /almaws/v1/acq/invoices/{invoice id}?op=paid/rejected
If the invoice is rejected, a note must be specified in the payload including the reject reason:
<invoice>
   <notes>
     <note>
         <content>Rejected becuase no confirmation from manager</content>
     </note>
   </notes>
</invoice>

 

If the invoice is paid, payment information can be specified in the payload, as well as explicit ratio if it was used by the ERP:

<invoice>
 <payment>
   <voucher_date>2018-12-11Z</voucher_date>
   <voucher_amount>100</voucher_amount>
   <voucher_currency desc="US Dollar">USD</voucher_currency>
   <voucher_number>Release review</voucher_number>
 </payment>
</invoice>