Skip to main content

Overview

The purpose of the Lightyear Integration API is to allow 3rd party systems to export documents from Lightyear.

The API includes operations for:

  • for getting a list of documents in a state where they can be exported
  • getting the invoice detail including line items for a specific invoice
  • getting any soft-copy version of the invoice (PDF, JPEG, PNG, TIFF)
  • marking documents as being successfully exported
  • uploading external data such as supplier cards

Architecture Overview​

The API described in this document will be hosted in AWS API Gateway. API Gateway will be responsible for handling authorization and routing the request to be serviced by the internal Lightyear applications.

Files associated with the invoices will be accessed directly from S3 by external applications via pre-signed time limited URLs retrieved from the API.

Authorisation and Authentication​

note

TBC but the intention will be to leverage API Gateway and Cognito to implement a machine-to-machine flow.

Exporting Invoices from Lightyear​

The following sequence diagram shows a possible use of the API for polling and retrieving invoices ready for export.

Request a list of invoices available for export from Lightyear. For each invoice in the list either complete or reject using the corresponding API call.

info

Because the list API is paged it maybe necessary to make multiple calls using the returned continuation key to retrieve all the invoices available for export. See the documentation for more details on using the continuation key.

info

Each Lightyear company is assumed have its own scheduled poll. A request to Get Exportable Invoice IDs will only return invoice IDs for the company specified in the Lightyear-Company-ID HTTP header.

Downloading Documents from Lightyear​

Request a download URL for the invoice using the invoice id. Use the returned url to download the file direct from the S3 document store.

Importing data into Lightyear​

Start an import job and keep the returned job ID. At this point the import job will be in-progress. Next, get the import job details and check the status field of the returned object. If the import job status is IN_PROGRESS re-request the import job details at repeated intervals until the status is either FINISHED or FAILED.