foliolib.folio.api.invoice.Invoice

class foliolib.folio.api.invoice.Invoice(tenant: str, okapi: Optional[foliolib.okapi.okapiClient.OkapiClient] = None)

Bases: foliolib.folio.FolioApi

Invoice API

This documents the API calls that can be made to manage invoices

Parameters

  • tenant (str) – Tenant id

  • okapi (OkapiClient, optional) – Instance of OkapiClient. Defaults to None.

Methods

delete_document(invoicesId, documentId)

Delete document item with given {documentId}

delete_invoice(invoicesId)

Delete an invoice with given {id}

delete_invoiceLine(invoiceLinesId)

Delete an invoice line with given {id}

get_document(invoicesId, documentId)

Retrieve document item with given {documentId}

get_documents(invoicesId, **kwargs)

Get list of documents

get_fiscalYears(invoicesId, **kwargs)

Get a list of fiscal years to approve or pay the invoice

get_invoice(invoicesId)

Return an invoice with given {id}

get_invoiceLine(invoiceLinesId)

Return an invoice line with given {id}

get_invoiceLines(**kwargs)

Retrieve a list of invoiceLine items.

get_invoiceNumbers()

Get system generated Invoice Number

get_invoices(**kwargs)

Retrieve a list of invoice items.

modify_invoice(invoicesId, invoice)

Update invoice.

modify_invoiceLine(invoiceLinesId, invoiceLine)

Update an invoice line with given {id}

modify_validate(validate)

Validate is total amount equals to sum of all fund distributions

set_document(invoicesId)

POST /invoice/invoices/{invoicesId}/documents

set_fiscalYear(invoicesId)

POST /invoice/invoices/{invoicesId}/fiscal-years

set_invoice(invoice)

Post invoice.

set_invoiceLine(invoiceLine)

Post an invoice lines to corresponding invoice

set_invoiceNumber()

POST /invoice/invoice-number
delete_document(invoicesId: str, documentId: str)

Delete document item with given {documentId}

DELETE /invoice/invoices/{invoicesId}/documents/{documentId}

Parameters

  • invoicesId (str) –

  • documentId (str) –

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestNotFound – Not Found

  • OkapiFatalError – Server Error

delete_invoice(invoicesId: str)

Delete an invoice with given {id}

DELETE /invoice/invoices/{invoicesId}

Parameters

invoicesId (str) –

Raises

  • OkapiRequestNotFound – Not Found

  • OkapiRequestError – Bad Request

  • OkapiFatalError – Server Error

delete_invoiceLine(invoiceLinesId: str)

Delete an invoice line with given {id}

DELETE /invoice/invoice-lines/{invoiceLinesId}

Parameters

invoiceLinesId (str) –

Raises

  • OkapiRequestNotFound – Not Found

  • OkapiRequestError – Bad Request

  • OkapiFatalError – Server Error

get_document(invoicesId: str, documentId: str)

Retrieve document item with given {documentId}

GET /invoice/invoices/{invoicesId}/documents/{documentId}

Parameters

  • invoicesId (str) –

  • documentId (str) –

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestNotFound – Not Found

  • OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Document attached/associated with an invoice either via a hyperlink to the document or by direct upload and storage within FOLIO",
  "type": "object",
  "properties": {
    "documentMetadata": {
      "description": "Document metadata",
      "type": "object",
      "$ref": "document_metadata.json"
    },
    "contents": {
      "description": "Base64 encoded file data",
      "type": "object",
      "$ref": "document_data.json"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "documentMetadata"
  ]
}
get_documents(invoicesId: str, **kwargs)

Get list of documents

GET /invoice/invoices/{invoicesId}/documents

Parameters

  • invoicesId (str) –

  • **kwargs (properties) – Keyword Arguments

Keyword Arguments

  • totalRecords (str) –

    (default=auto) How to calculate the totalRecords property. “exact” for the correct number, “estimated” for an estimation, “auto” to automatically select “exact” or “estimated”, “none” for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords

    Example

    • none

  • offset (int) –

    (default=0) Skip over a number of elements by specifying an offset value for the query

    Example

    • 0

  • limit (int) –

    (default=10) Limit the number of elements returned in the response

    Example

    • 10

  • query (str) –

    A query expressed as a CQL string (see [dev.folio.org/reference/glossary#cql](https://dev.folio.org/reference/glossary#cql)) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    with valid searchable fields: for example metadata.createdDate

    Example

    • (username==”ab*” or personal.firstName==”ab*” or personal.lastName==”ab*”) and active==”true” sortby personal.lastName personal.firstName barcode

    • metadata.createdDate > ‘2018-07-19T00:00:00.000+0000’

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Collection of documents",
  "type": "object",
  "properties": {
    "documents": {
      "description": "an array of document records",
      "id": "documents",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "document_metadata.json"
      }
    },
    "totalRecords": {
      "description": "total number of records in the array",
      "type": "integer"
    }
  },
  "required": [
    "documents",
    "totalRecords"
  ]
}
get_fiscalYears(invoicesId: str, **kwargs)

Get a list of fiscal years to approve or pay the invoice

GET /invoice/invoices/{invoicesId}/fiscal-years

Parameters

  • invoicesId (str) –

  • **kwargs (properties) – Keyword Arguments

Keyword Arguments

  • totalRecords (str) –

    (default=auto) How to calculate the totalRecords property. “exact” for the correct number, “estimated” for an estimation, “auto” to automatically select “exact” or “estimated”, “none” for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords

    Example

    • none

  • offset (int) –

    (default=0) Skip over a number of elements by specifying an offset value for the query

    Example

    • 0

  • limit (int) –

    (default=10) Limit the number of elements returned in the response

    Example

    • 10

  • query (str) –

    A query expressed as a CQL string (see [dev.folio.org/reference/glossary#cql](https://dev.folio.org/reference/glossary#cql)) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    with valid searchable fields: for example metadata.createdDate

    Example

    • (username==”ab*” or personal.firstName==”ab*” or personal.lastName==”ab*”) and active==”true” sortby personal.lastName personal.firstName barcode

    • metadata.createdDate > ‘2018-07-19T00:00:00.000+0000’

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A collection of fiscal years",
  "type": "object",
  "properties": {
    "fiscalYears": {
      "description": "The list of fiscal year objects in this collection",
      "type": "array",
      "id": "fiscal_years",
      "items": {
        "type": "object",
        "$ref": "fiscal_year.json"
      }
    },
    "totalRecords": {
      "description": "The number of objects in this collection",
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "fiscalYears",
    "totalRecords"
  ]
}
get_invoice(invoicesId: str)

Return an invoice with given {id}

GET /invoice/invoices/{invoicesId}

Parameters

invoicesId (str) –

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestNotFound – Not Found

  • OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice",
      "$ref": "../../common/schemas/uuid.json"
    },
    "accountingCode": {
      "description": "Number that represents the vendor is an external accounting system which may include details like \"Address code\" in it. This is the number as stated on the invoice",
      "type": "string"
    },
    "adjustments": {
      "description": "List of invoice level adjustments. The adjustments can be pro-rated which are defined at the invoice level, but are applied to the invoice lines. A generic example is a shipping fee which should be spread out across all of the invoice lines so that all funds involved pay some portion of the fee.",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "adjustment.json"
      }
    },
    "adjustmentsTotal": {
      "description": "Total amount which is sum of all invoice line adjustments and all non-prorated invoice level adjustments. This amount is always calculated by system.",
      "type": "number"
    },
    "approvedBy": {
      "description": "UUID of user that approved this invoice",
      "$ref": "../../common/schemas/uuid.json"
    },
    "approvalDate": {
      "description": "Date the invoice was approved for processing",
      "type": "string",
      "format": "date-time"
    },
    "batchGroupId": {
      "description": "UUID of the batch group to use when generating batch vouchers",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "default": "2a2cb998-1437-41d1-88ad-01930aaeadd5"
    },
    "billTo": {
      "description": "UUID of the billing address",
      "$ref": "../../common/schemas/uuid.json"
    },
    "chkSubscriptionOverlap": {
      "description": "IF TRUE the system will check if there is another invoice for this subscription and whether the dates overlap. IF the dates overlap, the system should issue an alert.",
      "type": "boolean"
    },
    "cancellationNote": {
      "description": "The reason of the invoice cancellation.",
      "type": "string"
    },
    "currency": {
      "description": "Ideally this is the ISO code and not something the user defines",
      "type": "string"
    },
    "enclosureNeeded": {
      "description": "Indicates that an enclosure is needed",
      "type": "boolean",
      "default": false
    },
    "exchangeRate": {
      "description": "Exchange rate",
      "type": "number"
    },
    "exportToAccounting": {
      "description": "This would keep the invoice from being feed into the batch process (i.e. not generate an external voucher/payment) but would still move values in the system. This might be defined by the vendor relationship and exposed for override on the invoice.",
      "type": "boolean",
      "default": false
    },
    "folioInvoiceNo": {
      "description": "Invoice number in folio system",
      "type": "string"
    },
    "invoiceDate": {
      "description": "Invoice date",
      "type": "string",
      "format": "date-time"
    },
    "lockTotal": {
      "description": "Total amount which manually set by user. The calculated total must match this before the invoice can be approved",
      "type": "number"
    },
    "note": {
      "description": "Invoice note",
      "type": "string"
    },
    "paymentDue": {
      "description": "When this is required to be paid. Generally governed by the relationship with the Vendor",
      "type": "string",
      "format": "date-time"
    },
    "paymentDate": {
      "description": "When the invoice was actually paid",
      "type": "string",
      "format": "date-time"
    },
    "paymentTerms": {
      "description": "Invoice payment terms",
      "type": "string"
    },
    "paymentMethod": {
      "description": "Inherited from vendor record",
      "type": "string"
    },
    "status": {
      "description": "Open: Record has been created, Reviewed: details have been verified, Approved: Funds are release, Paid: confirmation that funds have been exchanged and check number has been returned amounts are frozen, cancelled.\nNote: invoices are never partially paid.",
      "type": "string",
      "enum": [
        "Open",
        "Reviewed",
        "Approved",
        "Paid",
        "Cancelled"
      ]
    },
    "source": {
      "description": "This does not denote a user ID but describes how the record was created. Eg. User, API, EDI",
      "type": "string",
      "enum": [
        "User",
        "API",
        "EDI"
      ]
    },
    "subTotal": {
      "description": "Invoice amount before adjustments are applied. This is sum of all subTotal amounts of the corresponding invoice lines. This amount is always calculated by system.",
      "type": "number",
      "readonly": true
    },
    "total": {
      "description": "The total amount is calculated \"on the fly\" of this invoice which is sum of subTotal and adjustmentsTotal. Must be the same with existed \"lockTotal\", when approve invoice.",
      "type": "number",
      "readonly": true
    },
    "vendorInvoiceNo": {
      "description": "This is the number from the vendor's invoice, which is different from the folioInvoiceNo",
      "type": "string"
    },
    "disbursementNumber": {
      "description": "The identifier for the physical transaction corresponding to a payment (Eg. Check #, EFT # etc.) Brought in from external source",
      "type": "string"
    },
    "voucherNumber": {
      "description": "Number generated by folio that will eventually identify the payment request sent out to external financial system.",
      "type": "string"
    },
    "paymentId": {
      "description": "Id of payment",
      "$ref": "../../common/schemas/uuid.json"
    },
    "disbursementDate": {
      "description": "Date payment was made from financial system (eg. corresponding check date)",
      "type": "string",
      "format": "date-time"
    },
    "poNumbers": {
      "description": "May or may not be provided; references the PO associated to the invoice",
      "id": "poNumbers",
      "type": "array",
      "items": {
        "description": "A human readable ID assigned to this purchase order",
        "type": "string",
        "pattern": "^[a-zA-Z0-9]{1,22}$"
      }
    },
    "vendorId": {
      "description": "UUID of vendor",
      "$ref": "../../common/schemas/uuid.json"
    },
    "fiscalYearId": {
      "description": "UUID of fiscal year",
      "$ref": "../../common/schemas/uuid.json"
    },
    "accountNo": {
      "description": "The unique number of the organization account",
      "type": "string"
    },
    "manualPayment": {
      "description": "This would keep the invoice from being feed into the batch process (Not generate a external voucher/payment) but would still move values in the system. Note: this is ideally defined by the vendor relationship and exposed for override on the invoice.",
      "type": "boolean"
    },
    "acqUnitIds": {
      "description": "acquisition unit ids associated with this invoice",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "nextInvoiceLineNumber": {
      "description": "Number that will be used next time an invoice line is created",
      "type": "integer",
      "readonly": true
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "tags": {
      "type": "object",
      "description": "arbitrary tags associated with this invoice",
      "$ref": "../../../raml-util/schemas/tags.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "batchGroupId",
    "currency",
    "invoiceDate",
    "paymentMethod",
    "status",
    "source",
    "vendorInvoiceNo",
    "vendorId"
  ]
}
get_invoiceLine(invoiceLinesId: str)

Return an invoice line with given {id}

GET /invoice/invoice-lines/{invoiceLinesId}

Parameters

invoiceLinesId (str) –

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestNotFound – Not Found

  • OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice line",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice line",
      "$ref": "../../common/schemas/uuid.json"
    },
    "accountingCode": {
      "description": "Pulled based on account number.",
      "type": "string"
    },
    "accountNumber": {
      "description": "Account number that the vendor assigned",
      "type": "string"
    },
    "adjustments": {
      "description": "Defined in settings - the amount field will be editable and pro-rate toggle will be editable if enabled for that adjustment",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "adjustment.json"
      }
    },
    "adjustmentsTotal": {
      "description": "Sum of all invoice line adjustments. This amount is always calculated by system.",
      "type": "number"
    },
    "comment": {
      "description": "Free form commentary",
      "type": "string"
    },
    "description": {
      "description": "Title as captured in the Purchase Order Line. In the absence of a POL link this could be used to describe the POL",
      "type": "string"
    },
    "fundDistributions": {
      "description": "List of fund distributions",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "fund_distribution.json"
      }
    },
    "invoiceId": {
      "description": "UUID of this parent invoice",
      "$ref": "../../common/schemas/uuid.json"
    },
    "invoiceLineNumber": {
      "description": "Sequentially generated and not editable by the user.",
      "type": "string"
    },
    "invoiceLineStatus": {
      "description": "Invoice line status",
      "type": "string",
      "enum": [
        "Open",
        "Reviewed",
        "Approved",
        "Paid",
        "Cancelled",
        "Error"
      ]
    },
    "poLineId": {
      "description": "UUID of the corresponding purchase order line this invoice line is based on",
      "$ref": "../../common/schemas/uuid.json"
    },
    "productId": {
      "description": "product identifier",
      "type": "string"
    },
    "productIdType": {
      "description": "the type of product id",
      "type": "string",
      "$ref": "../../common/schemas/product_id_type.json"
    },
    "quantity": {
      "description": "quantity",
      "type": "integer"
    },
    "releaseEncumbrance": {
      "description": "This is intended to not only release encumbrances but to indicate that this is the final invoice line for corresponding order line. This should take into account the fiscal year. We may release encumbrance for this FY but for on-going orders expect to encumber again next year.",
      "type": "boolean",
      "default": true
    },
    "subscriptionInfo": {
      "description": "The user should use this field to provide info on the subscription (eg. which volumes are being invoiced). It is MANDATORY if the chk_subscription_overlap is FALSE AND there is no start date provided",
      "type": "string"
    },
    "subscriptionStart": {
      "description": "Subscription start date",
      "type": "string",
      "format": "date-time"
    },
    "subscriptionEnd": {
      "description": "Subscription end date",
      "type": "string",
      "format": "date-time"
    },
    "subTotal": {
      "description": "Invoice line amount before adjustments are applied",
      "type": "number"
    },
    "total": {
      "description": "Invoice line total amount which is sum of subTotal and adjustmentsTotal. This amount is always calculated by system.",
      "type": "number"
    },
    "referenceNumbers": {
      "description": "Reference number items array",
      "$ref": "../../common/schemas/reference_numbers.json"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "tags": {
      "type": "object",
      "description": "arbitrary tags associated with this invoice line",
      "$ref": "../../../raml-util/schemas/tags.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "description",
    "invoiceId",
    "invoiceLineStatus",
    "subTotal",
    "quantity",
    "releaseEncumbrance"
  ]
}
get_invoiceLines(**kwargs)

Retrieve a list of invoiceLine items.

GET /invoice/invoice-lines

Parameters

**kwargs (properties) – Keyword Arguments

Keyword Arguments

  • totalRecords (str) –

    (default=auto) How to calculate the totalRecords property. “exact” for the correct number, “estimated” for an estimation, “auto” to automatically select “exact” or “estimated”, “none” for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords

    Example

    • none

  • offset (int) –

    (default=0) Skip over a number of elements by specifying an offset value for the query

    Example

    • 0

  • limit (int) –

    (default=10) Limit the number of elements returned in the response

    Example

    • 10

  • query (str) –

    A query expressed as a CQL string (see [dev.folio.org/reference/glossary#cql](https://dev.folio.org/reference/glossary#cql)) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    using CQL (indexes for invoice lines)

    Example

    • (username==”ab*” or personal.firstName==”ab*” or personal.lastName==”ab*”) and active==”true” sortby personal.lastName personal.firstName barcode

    • status==”Open”

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestUnauthorized – Authentication is required

  • OkapiFatalError – Server Error

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "collection of invoice lines",
  "type": "object",
  "properties": {
    "invoiceLines": {
      "description": "an array of invoice line records",
      "id": "invoiceLines",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "invoice_line.json"
      }
    },
    "totalRecords": {
      "description": "total number of records in the array",
      "type": "integer"
    }
  },
  "required": [
    "invoiceLines",
    "totalRecords"
  ]
}
get_invoiceNumbers()

Get system generated Invoice Number

GET /invoice/invoice-number

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiFatalError – Server Error

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "collection of invoices",
  "type": "object",
  "properties": {
    "invoices": {
      "description": "an array of invoice records",
      "id": "invoices",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "invoice.json"
      }
    },
    "totalRecords": {
      "description": "total number of records in the array",
      "type": "integer"
    }
  },
  "required": [
    "invoices",
    "totalRecords"
  ]
}
get_invoices(**kwargs)

Retrieve a list of invoice items.

GET /invoice/invoices

Parameters

**kwargs (properties) – Keyword Arguments

Keyword Arguments

  • totalRecords (str) –

    (default=auto) How to calculate the totalRecords property. “exact” for the correct number, “estimated” for an estimation, “auto” to automatically select “exact” or “estimated”, “none” for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords

    Example

    • none

  • offset (int) –

    (default=0) Skip over a number of elements by specifying an offset value for the query

    Example

    • 0

  • limit (int) –

    (default=10) Limit the number of elements returned in the response

    Example

    • 10

  • query (str) –

    A query expressed as a CQL string (see [dev.folio.org/reference/glossary#cql](https://dev.folio.org/reference/glossary#cql)) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    using CQL (indexes for invoice)

    Example

    • (username==”ab*” or personal.firstName==”ab*” or personal.lastName==”ab*”) and active==”true” sortby personal.lastName personal.firstName barcode

    • invoiceLineStatus==”Open”

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestUnauthorized – Authentication is required

  • OkapiFatalError – Server Error

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "collection of invoices",
  "type": "object",
  "properties": {
    "invoices": {
      "description": "an array of invoice records",
      "id": "invoices",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "invoice.json"
      }
    },
    "totalRecords": {
      "description": "total number of records in the array",
      "type": "integer"
    }
  },
  "required": [
    "invoices",
    "totalRecords"
  ]
}
modify_invoice(invoicesId: str, invoice: dict)

Update invoice. Only in case an acquisition units list has to be changed, it is required that user should have extra permission invoices.acquisitions-units-assignments.manage to update an Invoice.

PUT /invoice/invoices/{invoicesId}

Parameters

  • invoicesId (str) –

  • invoice (dict) – See Schema below

Raises

  • OkapiRequestNotFound – Not Found

  • OkapiRequestError – Bad Request

  • OkapiRequestConflict – Conflict

  • OkapiFatalError – Server Error

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice",
      "$ref": "../../common/schemas/uuid.json"
    },
    "accountingCode": {
      "description": "Number that represents the vendor is an external accounting system which may include details like \"Address code\" in it. This is the number as stated on the invoice",
      "type": "string"
    },
    "adjustments": {
      "description": "List of invoice level adjustments. The adjustments can be pro-rated which are defined at the invoice level, but are applied to the invoice lines. A generic example is a shipping fee which should be spread out across all of the invoice lines so that all funds involved pay some portion of the fee.",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "adjustment.json"
      }
    },
    "adjustmentsTotal": {
      "description": "Total amount which is sum of all invoice line adjustments and all non-prorated invoice level adjustments. This amount is always calculated by system.",
      "type": "number"
    },
    "approvedBy": {
      "description": "UUID of user that approved this invoice",
      "$ref": "../../common/schemas/uuid.json"
    },
    "approvalDate": {
      "description": "Date the invoice was approved for processing",
      "type": "string",
      "format": "date-time"
    },
    "batchGroupId": {
      "description": "UUID of the batch group to use when generating batch vouchers",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "default": "2a2cb998-1437-41d1-88ad-01930aaeadd5"
    },
    "billTo": {
      "description": "UUID of the billing address",
      "$ref": "../../common/schemas/uuid.json"
    },
    "chkSubscriptionOverlap": {
      "description": "IF TRUE the system will check if there is another invoice for this subscription and whether the dates overlap. IF the dates overlap, the system should issue an alert.",
      "type": "boolean"
    },
    "cancellationNote": {
      "description": "The reason of the invoice cancellation.",
      "type": "string"
    },
    "currency": {
      "description": "Ideally this is the ISO code and not something the user defines",
      "type": "string"
    },
    "enclosureNeeded": {
      "description": "Indicates that an enclosure is needed",
      "type": "boolean",
      "default": false
    },
    "exchangeRate": {
      "description": "Exchange rate",
      "type": "number"
    },
    "exportToAccounting": {
      "description": "This would keep the invoice from being feed into the batch process (i.e. not generate an external voucher/payment) but would still move values in the system. This might be defined by the vendor relationship and exposed for override on the invoice.",
      "type": "boolean",
      "default": false
    },
    "folioInvoiceNo": {
      "description": "Invoice number in folio system",
      "type": "string"
    },
    "invoiceDate": {
      "description": "Invoice date",
      "type": "string",
      "format": "date-time"
    },
    "lockTotal": {
      "description": "Total amount which manually set by user. The calculated total must match this before the invoice can be approved",
      "type": "number"
    },
    "note": {
      "description": "Invoice note",
      "type": "string"
    },
    "paymentDue": {
      "description": "When this is required to be paid. Generally governed by the relationship with the Vendor",
      "type": "string",
      "format": "date-time"
    },
    "paymentDate": {
      "description": "When the invoice was actually paid",
      "type": "string",
      "format": "date-time"
    },
    "paymentTerms": {
      "description": "Invoice payment terms",
      "type": "string"
    },
    "paymentMethod": {
      "description": "Inherited from vendor record",
      "type": "string"
    },
    "status": {
      "description": "Open: Record has been created, Reviewed: details have been verified, Approved: Funds are release, Paid: confirmation that funds have been exchanged and check number has been returned amounts are frozen, cancelled.\nNote: invoices are never partially paid.",
      "type": "string",
      "enum": [
        "Open",
        "Reviewed",
        "Approved",
        "Paid",
        "Cancelled"
      ]
    },
    "source": {
      "description": "This does not denote a user ID but describes how the record was created. Eg. User, API, EDI",
      "type": "string",
      "enum": [
        "User",
        "API",
        "EDI"
      ]
    },
    "subTotal": {
      "description": "Invoice amount before adjustments are applied. This is sum of all subTotal amounts of the corresponding invoice lines. This amount is always calculated by system.",
      "type": "number",
      "readonly": true
    },
    "total": {
      "description": "The total amount is calculated \"on the fly\" of this invoice which is sum of subTotal and adjustmentsTotal. Must be the same with existed \"lockTotal\", when approve invoice.",
      "type": "number",
      "readonly": true
    },
    "vendorInvoiceNo": {
      "description": "This is the number from the vendor's invoice, which is different from the folioInvoiceNo",
      "type": "string"
    },
    "disbursementNumber": {
      "description": "The identifier for the physical transaction corresponding to a payment (Eg. Check #, EFT # etc.) Brought in from external source",
      "type": "string"
    },
    "voucherNumber": {
      "description": "Number generated by folio that will eventually identify the payment request sent out to external financial system.",
      "type": "string"
    },
    "paymentId": {
      "description": "Id of payment",
      "$ref": "../../common/schemas/uuid.json"
    },
    "disbursementDate": {
      "description": "Date payment was made from financial system (eg. corresponding check date)",
      "type": "string",
      "format": "date-time"
    },
    "poNumbers": {
      "description": "May or may not be provided; references the PO associated to the invoice",
      "id": "poNumbers",
      "type": "array",
      "items": {
        "description": "A human readable ID assigned to this purchase order",
        "type": "string",
        "pattern": "^[a-zA-Z0-9]{1,22}$"
      }
    },
    "vendorId": {
      "description": "UUID of vendor",
      "$ref": "../../common/schemas/uuid.json"
    },
    "fiscalYearId": {
      "description": "UUID of fiscal year",
      "$ref": "../../common/schemas/uuid.json"
    },
    "accountNo": {
      "description": "The unique number of the organization account",
      "type": "string"
    },
    "manualPayment": {
      "description": "This would keep the invoice from being feed into the batch process (Not generate a external voucher/payment) but would still move values in the system. Note: this is ideally defined by the vendor relationship and exposed for override on the invoice.",
      "type": "boolean"
    },
    "acqUnitIds": {
      "description": "acquisition unit ids associated with this invoice",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "nextInvoiceLineNumber": {
      "description": "Number that will be used next time an invoice line is created",
      "type": "integer",
      "readonly": true
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "tags": {
      "type": "object",
      "description": "arbitrary tags associated with this invoice",
      "$ref": "../../../raml-util/schemas/tags.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "batchGroupId",
    "currency",
    "invoiceDate",
    "paymentMethod",
    "status",
    "source",
    "vendorInvoiceNo",
    "vendorId"
  ]
}
modify_invoiceLine(invoiceLinesId: str, invoiceLine: dict)

Update an invoice line with given {id}

PUT /invoice/invoice-lines/{invoiceLinesId}

Parameters

  • invoiceLinesId (str) –

  • invoiceLine (dict) – See Schema below

Raises

  • OkapiRequestNotFound – Not Found

  • OkapiRequestError – Bad Request

  • OkapiRequestConflict – Conflict

  • OkapiFatalError – Server Error

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice line",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice line",
      "$ref": "../../common/schemas/uuid.json"
    },
    "accountingCode": {
      "description": "Pulled based on account number.",
      "type": "string"
    },
    "accountNumber": {
      "description": "Account number that the vendor assigned",
      "type": "string"
    },
    "adjustments": {
      "description": "Defined in settings - the amount field will be editable and pro-rate toggle will be editable if enabled for that adjustment",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "adjustment.json"
      }
    },
    "adjustmentsTotal": {
      "description": "Sum of all invoice line adjustments. This amount is always calculated by system.",
      "type": "number"
    },
    "comment": {
      "description": "Free form commentary",
      "type": "string"
    },
    "description": {
      "description": "Title as captured in the Purchase Order Line. In the absence of a POL link this could be used to describe the POL",
      "type": "string"
    },
    "fundDistributions": {
      "description": "List of fund distributions",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "fund_distribution.json"
      }
    },
    "invoiceId": {
      "description": "UUID of this parent invoice",
      "$ref": "../../common/schemas/uuid.json"
    },
    "invoiceLineNumber": {
      "description": "Sequentially generated and not editable by the user.",
      "type": "string"
    },
    "invoiceLineStatus": {
      "description": "Invoice line status",
      "type": "string",
      "enum": [
        "Open",
        "Reviewed",
        "Approved",
        "Paid",
        "Cancelled",
        "Error"
      ]
    },
    "poLineId": {
      "description": "UUID of the corresponding purchase order line this invoice line is based on",
      "$ref": "../../common/schemas/uuid.json"
    },
    "productId": {
      "description": "product identifier",
      "type": "string"
    },
    "productIdType": {
      "description": "the type of product id",
      "type": "string",
      "$ref": "../../common/schemas/product_id_type.json"
    },
    "quantity": {
      "description": "quantity",
      "type": "integer"
    },
    "releaseEncumbrance": {
      "description": "This is intended to not only release encumbrances but to indicate that this is the final invoice line for corresponding order line. This should take into account the fiscal year. We may release encumbrance for this FY but for on-going orders expect to encumber again next year.",
      "type": "boolean",
      "default": true
    },
    "subscriptionInfo": {
      "description": "The user should use this field to provide info on the subscription (eg. which volumes are being invoiced). It is MANDATORY if the chk_subscription_overlap is FALSE AND there is no start date provided",
      "type": "string"
    },
    "subscriptionStart": {
      "description": "Subscription start date",
      "type": "string",
      "format": "date-time"
    },
    "subscriptionEnd": {
      "description": "Subscription end date",
      "type": "string",
      "format": "date-time"
    },
    "subTotal": {
      "description": "Invoice line amount before adjustments are applied",
      "type": "number"
    },
    "total": {
      "description": "Invoice line total amount which is sum of subTotal and adjustmentsTotal. This amount is always calculated by system.",
      "type": "number"
    },
    "referenceNumbers": {
      "description": "Reference number items array",
      "$ref": "../../common/schemas/reference_numbers.json"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "tags": {
      "type": "object",
      "description": "arbitrary tags associated with this invoice line",
      "$ref": "../../../raml-util/schemas/tags.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "description",
    "invoiceId",
    "invoiceLineStatus",
    "subTotal",
    "quantity",
    "releaseEncumbrance"
  ]
}
modify_validate(validate: dict)

Validate is total amount equals to sum of all fund distributions

PUT /invoice/invoice-lines/fund-distributions/validate

Parameters

validate (dict) – See Schema below

Raises

OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Fund distribution amount validation",
  "type": "object",
  "properties": {
    "subTotal": {
      "description": "Invoice line amount before adjustments are applied",
      "type": "number"
    },
    "currency": {
      "description": "An ISO currency code",
      "type": "string"
    },
    "fundDistribution": {
      "description": "fund distribution records for this purchase order line",
      "id": "fundDistribution",
      "type": "array",
      "items": {
        "description": "a fund distribution record",
        "type": "object",
        "$ref": "../../mod-invoice-storage/schemas/fund_distribution.json"
      }
    },
    "adjustments": {
      "description": "Defined in settings - the amount field will be editable and pro-rate toggle will be editable if enabled for that adjustment",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "../../mod-invoice-storage/schemas/adjustment.json"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "subTotal",
    "currency",
    "fundDistribution"
  ]
}
set_document(invoicesId: str)

POST /invoice/invoices/{invoicesId}/documents

Parameters

invoicesId (str) –

set_fiscalYear(invoicesId: str)

POST /invoice/invoices/{invoicesId}/fiscal-years

Parameters

invoicesId (str) –

set_invoice(invoice: dict)

Post invoice. Only in case an acquisition unit has to be assigned to the invoice, it is required that user should have extra permission invoices.acquisitions-units-assignments.assign to create an Invoice.

POST /invoice/invoices

Parameters

invoice (dict) – See Schema below

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestUnauthorized – Authentication is required

  • OkapiFatalError – Server Error

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

Headers

  • Location - URI to the created invoice item

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice",
      "$ref": "../../common/schemas/uuid.json"
    },
    "accountingCode": {
      "description": "Number that represents the vendor is an external accounting system which may include details like \"Address code\" in it. This is the number as stated on the invoice",
      "type": "string"
    },
    "adjustments": {
      "description": "List of invoice level adjustments. The adjustments can be pro-rated which are defined at the invoice level, but are applied to the invoice lines. A generic example is a shipping fee which should be spread out across all of the invoice lines so that all funds involved pay some portion of the fee.",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "adjustment.json"
      }
    },
    "adjustmentsTotal": {
      "description": "Total amount which is sum of all invoice line adjustments and all non-prorated invoice level adjustments. This amount is always calculated by system.",
      "type": "number"
    },
    "approvedBy": {
      "description": "UUID of user that approved this invoice",
      "$ref": "../../common/schemas/uuid.json"
    },
    "approvalDate": {
      "description": "Date the invoice was approved for processing",
      "type": "string",
      "format": "date-time"
    },
    "batchGroupId": {
      "description": "UUID of the batch group to use when generating batch vouchers",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "default": "2a2cb998-1437-41d1-88ad-01930aaeadd5"
    },
    "billTo": {
      "description": "UUID of the billing address",
      "$ref": "../../common/schemas/uuid.json"
    },
    "chkSubscriptionOverlap": {
      "description": "IF TRUE the system will check if there is another invoice for this subscription and whether the dates overlap. IF the dates overlap, the system should issue an alert.",
      "type": "boolean"
    },
    "cancellationNote": {
      "description": "The reason of the invoice cancellation.",
      "type": "string"
    },
    "currency": {
      "description": "Ideally this is the ISO code and not something the user defines",
      "type": "string"
    },
    "enclosureNeeded": {
      "description": "Indicates that an enclosure is needed",
      "type": "boolean",
      "default": false
    },
    "exchangeRate": {
      "description": "Exchange rate",
      "type": "number"
    },
    "exportToAccounting": {
      "description": "This would keep the invoice from being feed into the batch process (i.e. not generate an external voucher/payment) but would still move values in the system. This might be defined by the vendor relationship and exposed for override on the invoice.",
      "type": "boolean",
      "default": false
    },
    "folioInvoiceNo": {
      "description": "Invoice number in folio system",
      "type": "string"
    },
    "invoiceDate": {
      "description": "Invoice date",
      "type": "string",
      "format": "date-time"
    },
    "lockTotal": {
      "description": "Total amount which manually set by user. The calculated total must match this before the invoice can be approved",
      "type": "number"
    },
    "note": {
      "description": "Invoice note",
      "type": "string"
    },
    "paymentDue": {
      "description": "When this is required to be paid. Generally governed by the relationship with the Vendor",
      "type": "string",
      "format": "date-time"
    },
    "paymentDate": {
      "description": "When the invoice was actually paid",
      "type": "string",
      "format": "date-time"
    },
    "paymentTerms": {
      "description": "Invoice payment terms",
      "type": "string"
    },
    "paymentMethod": {
      "description": "Inherited from vendor record",
      "type": "string"
    },
    "status": {
      "description": "Open: Record has been created, Reviewed: details have been verified, Approved: Funds are release, Paid: confirmation that funds have been exchanged and check number has been returned amounts are frozen, cancelled.\nNote: invoices are never partially paid.",
      "type": "string",
      "enum": [
        "Open",
        "Reviewed",
        "Approved",
        "Paid",
        "Cancelled"
      ]
    },
    "source": {
      "description": "This does not denote a user ID but describes how the record was created. Eg. User, API, EDI",
      "type": "string",
      "enum": [
        "User",
        "API",
        "EDI"
      ]
    },
    "subTotal": {
      "description": "Invoice amount before adjustments are applied. This is sum of all subTotal amounts of the corresponding invoice lines. This amount is always calculated by system.",
      "type": "number",
      "readonly": true
    },
    "total": {
      "description": "The total amount is calculated \"on the fly\" of this invoice which is sum of subTotal and adjustmentsTotal. Must be the same with existed \"lockTotal\", when approve invoice.",
      "type": "number",
      "readonly": true
    },
    "vendorInvoiceNo": {
      "description": "This is the number from the vendor's invoice, which is different from the folioInvoiceNo",
      "type": "string"
    },
    "disbursementNumber": {
      "description": "The identifier for the physical transaction corresponding to a payment (Eg. Check #, EFT # etc.) Brought in from external source",
      "type": "string"
    },
    "voucherNumber": {
      "description": "Number generated by folio that will eventually identify the payment request sent out to external financial system.",
      "type": "string"
    },
    "paymentId": {
      "description": "Id of payment",
      "$ref": "../../common/schemas/uuid.json"
    },
    "disbursementDate": {
      "description": "Date payment was made from financial system (eg. corresponding check date)",
      "type": "string",
      "format": "date-time"
    },
    "poNumbers": {
      "description": "May or may not be provided; references the PO associated to the invoice",
      "id": "poNumbers",
      "type": "array",
      "items": {
        "description": "A human readable ID assigned to this purchase order",
        "type": "string",
        "pattern": "^[a-zA-Z0-9]{1,22}$"
      }
    },
    "vendorId": {
      "description": "UUID of vendor",
      "$ref": "../../common/schemas/uuid.json"
    },
    "fiscalYearId": {
      "description": "UUID of fiscal year",
      "$ref": "../../common/schemas/uuid.json"
    },
    "accountNo": {
      "description": "The unique number of the organization account",
      "type": "string"
    },
    "manualPayment": {
      "description": "This would keep the invoice from being feed into the batch process (Not generate a external voucher/payment) but would still move values in the system. Note: this is ideally defined by the vendor relationship and exposed for override on the invoice.",
      "type": "boolean"
    },
    "acqUnitIds": {
      "description": "acquisition unit ids associated with this invoice",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "nextInvoiceLineNumber": {
      "description": "Number that will be used next time an invoice line is created",
      "type": "integer",
      "readonly": true
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "tags": {
      "type": "object",
      "description": "arbitrary tags associated with this invoice",
      "$ref": "../../../raml-util/schemas/tags.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "batchGroupId",
    "currency",
    "invoiceDate",
    "paymentMethod",
    "status",
    "source",
    "vendorInvoiceNo",
    "vendorId"
  ]
}
set_invoiceLine(invoiceLine: dict)

Post an invoice lines to corresponding invoice

POST /invoice/invoice-lines

Parameters

invoiceLine (dict) – See Schema below

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestUnauthorized – Authentication is required

  • OkapiFatalError – Server Error

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

Headers

  • Location - URI to the created invoiceLine item

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice line",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice line",
      "$ref": "../../common/schemas/uuid.json"
    },
    "accountingCode": {
      "description": "Pulled based on account number.",
      "type": "string"
    },
    "accountNumber": {
      "description": "Account number that the vendor assigned",
      "type": "string"
    },
    "adjustments": {
      "description": "Defined in settings - the amount field will be editable and pro-rate toggle will be editable if enabled for that adjustment",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "adjustment.json"
      }
    },
    "adjustmentsTotal": {
      "description": "Sum of all invoice line adjustments. This amount is always calculated by system.",
      "type": "number"
    },
    "comment": {
      "description": "Free form commentary",
      "type": "string"
    },
    "description": {
      "description": "Title as captured in the Purchase Order Line. In the absence of a POL link this could be used to describe the POL",
      "type": "string"
    },
    "fundDistributions": {
      "description": "List of fund distributions",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "fund_distribution.json"
      }
    },
    "invoiceId": {
      "description": "UUID of this parent invoice",
      "$ref": "../../common/schemas/uuid.json"
    },
    "invoiceLineNumber": {
      "description": "Sequentially generated and not editable by the user.",
      "type": "string"
    },
    "invoiceLineStatus": {
      "description": "Invoice line status",
      "type": "string",
      "enum": [
        "Open",
        "Reviewed",
        "Approved",
        "Paid",
        "Cancelled",
        "Error"
      ]
    },
    "poLineId": {
      "description": "UUID of the corresponding purchase order line this invoice line is based on",
      "$ref": "../../common/schemas/uuid.json"
    },
    "productId": {
      "description": "product identifier",
      "type": "string"
    },
    "productIdType": {
      "description": "the type of product id",
      "type": "string",
      "$ref": "../../common/schemas/product_id_type.json"
    },
    "quantity": {
      "description": "quantity",
      "type": "integer"
    },
    "releaseEncumbrance": {
      "description": "This is intended to not only release encumbrances but to indicate that this is the final invoice line for corresponding order line. This should take into account the fiscal year. We may release encumbrance for this FY but for on-going orders expect to encumber again next year.",
      "type": "boolean",
      "default": true
    },
    "subscriptionInfo": {
      "description": "The user should use this field to provide info on the subscription (eg. which volumes are being invoiced). It is MANDATORY if the chk_subscription_overlap is FALSE AND there is no start date provided",
      "type": "string"
    },
    "subscriptionStart": {
      "description": "Subscription start date",
      "type": "string",
      "format": "date-time"
    },
    "subscriptionEnd": {
      "description": "Subscription end date",
      "type": "string",
      "format": "date-time"
    },
    "subTotal": {
      "description": "Invoice line amount before adjustments are applied",
      "type": "number"
    },
    "total": {
      "description": "Invoice line total amount which is sum of subTotal and adjustmentsTotal. This amount is always calculated by system.",
      "type": "number"
    },
    "referenceNumbers": {
      "description": "Reference number items array",
      "$ref": "../../common/schemas/reference_numbers.json"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "tags": {
      "type": "object",
      "description": "arbitrary tags associated with this invoice line",
      "$ref": "../../../raml-util/schemas/tags.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "description",
    "invoiceId",
    "invoiceLineStatus",
    "subTotal",
    "quantity",
    "releaseEncumbrance"
  ]
}
set_invoiceNumber()

POST /invoice/invoice-number