Creating Invoices via API

Owned by William Walsh
Last updated: Aug 31, 2023 by Mallory

NOTE: Invoices created via API are an option for vendors unable to supply EDI invoicing. To use API invoices, the vendor must also supply MARC records containing Embedded Order Data (EOD) to first generate orders in Alma. To request a new implementation, please use the ITS Dataloads Request Form. See Dataloads Requests: New Implementations and Profile Configuration Changes for additional details.


General

  • Script runs daily at 4:00 as part of Embedded Order Data process before any .mrc files are archived from the incoming MARC folders.
  • Configured per vendor block via the EOD dropoff and pickup files.
  • Alma vendor codes currently configured:
    • GARCIA
    • INCA
    • ITURRIAGA
    • MEXBOOKS
    • KARNO 
    • LEXICON
    • LINARDI
    • RETTA
    • WORLDWIDE

EOD import setup

  • An EOD .mrc file must have been imported to Alma for an invoice to be created.
    • This happens the previous evening. Schedule is controlled via individual import profiles in Alma.


    • Vendor must include the vendor invoice number in 980 $f with their records. This is mapped via the PO Line Information tab of the import profile.

  • Each EOD .mrc file should contain all records for an invoice; each file should contain only records for that invoice. 
  • Invoices must be limited to 100 lines. (This is due to a limitation on the API call to retrieve PO lines.) 

Invoice creation steps

See Tamar Fuches's Tech Blog post for additional background on this process.

PO line retrieval 

  • Script retrieves PO lines using the vendor invoice number from the EOD file (GET /almaws/v1/acq/po-lines?q=invoice_reference)
    • The following information is recorded:
      • POL owner
      • Vendor
      • POL number
      • Fund
      • Reporting Code
      • Price
      • Quantity
      • Currency
    • As noted above, Ex Libris has a 100 line limit for results of this query.

Invoice creation

  • Invoice is created using information collected from the POLs (POST /almaws/v1/acq/invoices)
    • Invoice number
    • Invoice owner (same as POL owner)
    • Vendor
    • Date (date file was posted). PLEASE NOTE: This date needs to be changed to the actual invoice date when paying the invoice in Alma
    • Currency
    • Total amount 

Invoice line creation

  • Invoice lines are created using the Unique Invoice Identifier of the newly created invoice, along with the information collected from the POLs (POST /almaws/v1/acq/invoices/{invoice_id}/lines)
    • POL number
    • Fund
    • Reporting code
    • Price
    • Quantity
  • Also, for each line, the Invoice Status of the corresponding POL is set to Fully Invoiced

If the script cannot create an invoice line (e.g., due to an issue with a fund), it will move on to the next line (or step) and create a ticket to log the problem.


Process invoice

  • After the lines are added, the invoice must be processed, which is equivalent to saving it. Otherwise, it will not be editable by users (POST /almaws/v1/acq/invoices/{invoice id}?op=process_invoice)

Invoices created via APIs in Alma

Invoices created via this process will have a Creation from value of From API in Alma. An invoice review rule (Configuration > Acquisitions > Invoices) places these invoices In Review until processed by staff.