Invoices (v1)

http://github.com/folio-org/mod-invoice-storage

Invoice CRUD API
/invoice-storage

Invoice CRUD API

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

/invoice-storage

GET /invoice-storage/invoices

Get list of invoices

GET /invoice-storage/invoices

Query Parameters

offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)
Skip over a number of elements by specifying an offset value for the query
Example:
```
0
```
limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)
Limit the number of elements returned in the response
Example:
```
10
```
query: (string)
A query expressed as a CQL string (see 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 folioInvoiceNo
Example:
```
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode

folioInvoiceNo=="123invoicenumber45"
```
lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Returns a list of invoice items

Body

Media type: application/json

Type: json

Content:

{
  "$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"
  ]
}

Example:

{
  "invoices": {
    "id": "c0d08448-347b-418a-8c2f-5fb50248d67e",
    "approvedBy": "ab18897b-0e40-4f31-896b-9c9adc979a88",
    "approvalDate": "2018-07-29T00:00:00.000+0000",
    "chkSubscriptionOverlap": false,
    "currency": "USD",
    "folioInvoiceNo": "123invoicenumber45",
    "invoiceDate": "2018-07-20T00:00:00.000+0000",
    "note": "Some note",
    "owner": "d79b0bcc-DcAD-1E4E-Abb7-DbFcaD5BB3bb",
    "paymentDue": "2018-08-29T00:00:00.000+0000",
    "paymentTerms": "Payment in Advance",
    "paymentMethod": "EFT",
    "prorata": false,
    "status": "Open",
    "source": "024b6f41-c5c6-4280-858e-33fba452a334",
    "totalAmount": 5,
    "vendorInvoiceNo": "YK75851",
    "disbursementNumber": "58",
    "voucherNumber": "478",
    "paymentId": "a5065f0d-fb88-4d23-b0c1-57e754fba40e",
    "disbursementDate": "2018-08-19T00:00:00.000+0000",
    "poNumbers": [
      "AB268758XYZ"
    ],
    "vendorId": "168f8a63-d612-406e-813f-c7527f241ac3",
    "manualPayment": true,
    "metadata": {
      "createdDate": "2018-07-19T00:00:00.000+0000",
      "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
    }
  },
  "totalRecords": 1
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list invoices -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list invoices -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /invoice-storage/invoices

Create a new invoice item.

POST /invoice-storage/invoices

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice",
      "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}$"
    },
    "approvedBy": {
      "description": "UUID of user that approved this invoice",
      "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}$"
    },
    "approvalDate": {
      "description": "Date the invoice was approved for processing",
      "type": "string",
      "format": "date-time"
    },
    "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"
    },
    "currency":{
      "description": "Ideally this is the ISO code and not something the user defines",
      "type": "string"
    },
    "folioInvoiceNo": {
      "description": "Invoice number in folio system",
      "type": "string"
    },
    "invoiceDate": {
      "description": "Invoice date",
      "type": "string",
      "format": "date-time"
    },
    "note": {
      "description": "Invoice note",
      "type": "string"
    },
    "owner": {
      "description": "The location/branch/division etc that's responsible for this invoice. This may or may not be the same as the PO. ie. North Branch",
      "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}$"
    },
    "paymentDue": {
      "description": "When this is required to be paid. Generally governed by the relationship with the Vendor",
      "type": "string",
      "format": "date-time"
    },
    "paymentTerms": {
      "description": "Invoice payment terms",
      "type": "string"
    },
    "paymentMethod": {
      "description": "Inherited from vendor record",
      "type": "string"
    },
    "prorata": {
      "description": "IF TRUE the additional charges will be applied to each line item and reflected in the total. IF FALSE each charge will be added to the invoice as it's own line item. (Default would be Yes) Ideally this can be done by price.",
      "type": "boolean",
      "default": true
    },
    "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. Manually, EDIFACT, MARC etc",
      "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}$"
    },
    "totalAmount": {
      "description": "Total amount",
      "type": "number"
    },
    "vendorInvoiceNo": {
      "description": "This is the number from the vendor's invoice this may or may not be the same as 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",
      "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}$"
    },
    "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]{5,16}$"
      }
    },
    "vendorId": {
      "description": "UUID of vendor",
      "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}$"
    },
    "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"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "currency",
    "folioInvoiceNo",
    "invoiceDate",
    "paymentMethod",
    "approvalDate",
    "status",
    "source",
    "totalAmount",
    "vendorInvoiceNo",
    "voucherNumber",
    "paymentId",
    "vendorId"
  ]
}

Example:

{
  "id": "c0d08448-347b-418a-8c2f-5fb50248d67e",
  "approvedBy": "ab18897b-0e40-4f31-896b-9c9adc979a88",
  "approvalDate": "2018-07-29T00:00:00.000+0000",
  "chkSubscriptionOverlap": false,
  "currency": "USD",
  "folioInvoiceNo": "123invoicenumber45",
  "invoiceDate": "2018-07-20T00:00:00.000+0000",
  "note": "Some note",
  "owner": "d79b0bcc-DcAD-1E4E-Abb7-DbFcaD5BB3bb",
  "paymentDue": "2018-08-29T00:00:00.000+0000",
  "paymentTerms": "Payment in Advance",
  "paymentMethod": "EFT",
  "prorata": false,
  "status": "Open",
  "source": "024b6f41-c5c6-4280-858e-33fba452a334",
  "totalAmount": 5,
  "vendorInvoiceNo": "YK75851",
  "disbursementNumber": "58",
  "voucherNumber": "478",
  "paymentId": "a5065f0d-fb88-4d23-b0c1-57e754fba40e",
  "disbursementDate": "2018-08-19T00:00:00.000+0000",
  "poNumbers": [
    "AB268758XYZ"
  ],
  "vendorId": "168f8a63-d612-406e-813f-c7527f241ac3",
  "manualPayment": true,
  "metadata": {
    "createdDate": "2018-07-19T00:00:00.000+0000",
    "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
  }
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers

Location: required (string)
URI to the created invoice item

Body

Media type: application/json

Type: any

Example:

{
  "id": "c0d08448-347b-418a-8c2f-5fb50248d67e",
  "approvedBy": "ab18897b-0e40-4f31-896b-9c9adc979a88",
  "approvalDate": "2018-07-29T00:00:00.000+0000",
  "chkSubscriptionOverlap": false,
  "currency": "USD",
  "folioInvoiceNo": "123invoicenumber45",
  "invoiceDate": "2018-07-20T00:00:00.000+0000",
  "note": "Some note",
  "owner": "d79b0bcc-DcAD-1E4E-Abb7-DbFcaD5BB3bb",
  "paymentDue": "2018-08-29T00:00:00.000+0000",
  "paymentTerms": "Payment in Advance",
  "paymentMethod": "EFT",
  "prorata": false,
  "status": "Open",
  "source": "024b6f41-c5c6-4280-858e-33fba452a334",
  "totalAmount": 5,
  "vendorInvoiceNo": "YK75851",
  "disbursementNumber": "58",
  "voucherNumber": "478",
  "paymentId": "a5065f0d-fb88-4d23-b0c1-57e754fba40e",
  "disbursementDate": "2018-08-19T00:00:00.000+0000",
  "poNumbers": [
    "AB268758XYZ"
  ],
  "vendorId": "168f8a63-d612-406e-813f-c7527f241ac3",
  "manualPayment": true,
  "metadata": {
    "createdDate": "2018-07-19T00:00:00.000+0000",
    "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
  }
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add invoice -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create invoices -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

GET /invoice-storage/invoices/{id}

Retrieve invoice item with given {invoiceId}

GET /invoice-storage/invoices/{id}

URI Parameters

id: required (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}$)
The UUID of an invoice

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice",
      "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}$"
    },
    "approvedBy": {
      "description": "UUID of user that approved this invoice",
      "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}$"
    },
    "approvalDate": {
      "description": "Date the invoice was approved for processing",
      "type": "string",
      "format": "date-time"
    },
    "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"
    },
    "currency":{
      "description": "Ideally this is the ISO code and not something the user defines",
      "type": "string"
    },
    "folioInvoiceNo": {
      "description": "Invoice number in folio system",
      "type": "string"
    },
    "invoiceDate": {
      "description": "Invoice date",
      "type": "string",
      "format": "date-time"
    },
    "note": {
      "description": "Invoice note",
      "type": "string"
    },
    "owner": {
      "description": "The location/branch/division etc that's responsible for this invoice. This may or may not be the same as the PO. ie. North Branch",
      "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}$"
    },
    "paymentDue": {
      "description": "When this is required to be paid. Generally governed by the relationship with the Vendor",
      "type": "string",
      "format": "date-time"
    },
    "paymentTerms": {
      "description": "Invoice payment terms",
      "type": "string"
    },
    "paymentMethod": {
      "description": "Inherited from vendor record",
      "type": "string"
    },
    "prorata": {
      "description": "IF TRUE the additional charges will be applied to each line item and reflected in the total. IF FALSE each charge will be added to the invoice as it's own line item. (Default would be Yes) Ideally this can be done by price.",
      "type": "boolean",
      "default": true
    },
    "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. Manually, EDIFACT, MARC etc",
      "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}$"
    },
    "totalAmount": {
      "description": "Total amount",
      "type": "number"
    },
    "vendorInvoiceNo": {
      "description": "This is the number from the vendor's invoice this may or may not be the same as 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",
      "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}$"
    },
    "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]{5,16}$"
      }
    },
    "vendorId": {
      "description": "UUID of vendor",
      "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}$"
    },
    "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"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "currency",
    "folioInvoiceNo",
    "invoiceDate",
    "paymentMethod",
    "approvalDate",
    "status",
    "source",
    "totalAmount",
    "vendorInvoiceNo",
    "voucherNumber",
    "paymentId",
    "vendorId"
  ]
}

Example:

{
  "id": "c0d08448-347b-418a-8c2f-5fb50248d67e",
  "approvedBy": "ab18897b-0e40-4f31-896b-9c9adc979a88",
  "approvalDate": "2018-07-29T00:00:00.000+0000",
  "chkSubscriptionOverlap": false,
  "currency": "USD",
  "folioInvoiceNo": "123invoicenumber45",
  "invoiceDate": "2018-07-20T00:00:00.000+0000",
  "note": "Some note",
  "owner": "d79b0bcc-DcAD-1E4E-Abb7-DbFcaD5BB3bb",
  "paymentDue": "2018-08-29T00:00:00.000+0000",
  "paymentTerms": "Payment in Advance",
  "paymentMethod": "EFT",
  "prorata": false,
  "status": "Open",
  "source": "024b6f41-c5c6-4280-858e-33fba452a334",
  "totalAmount": 5,
  "vendorInvoiceNo": "YK75851",
  "disbursementNumber": "58",
  "voucherNumber": "478",
  "paymentId": "a5065f0d-fb88-4d23-b0c1-57e754fba40e",
  "disbursementDate": "2018-08-19T00:00:00.000+0000",
  "poNumbers": [
    "AB268758XYZ"
  ],
  "vendorId": "168f8a63-d612-406e-813f-c7527f241ac3",
  "manualPayment": true,
  "metadata": {
    "createdDate": "2018-07-19T00:00:00.000+0000",
    "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
  }
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"invoice not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /invoice-storage/invoices/{id}

Delete invoice item with given {invoiceId}

DELETE /invoice-storage/invoices/{id}

URI Parameters

id: required (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}$)
The UUID of an invoice

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete invoice -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"invoice not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /invoice-storage/invoices/{id}

Update invoice item with given {invoiceId}

PUT /invoice-storage/invoices/{id}

URI Parameters

id: required (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}$)
The UUID of an invoice

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice",
      "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}$"
    },
    "approvedBy": {
      "description": "UUID of user that approved this invoice",
      "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}$"
    },
    "approvalDate": {
      "description": "Date the invoice was approved for processing",
      "type": "string",
      "format": "date-time"
    },
    "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"
    },
    "currency":{
      "description": "Ideally this is the ISO code and not something the user defines",
      "type": "string"
    },
    "folioInvoiceNo": {
      "description": "Invoice number in folio system",
      "type": "string"
    },
    "invoiceDate": {
      "description": "Invoice date",
      "type": "string",
      "format": "date-time"
    },
    "note": {
      "description": "Invoice note",
      "type": "string"
    },
    "owner": {
      "description": "The location/branch/division etc that's responsible for this invoice. This may or may not be the same as the PO. ie. North Branch",
      "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}$"
    },
    "paymentDue": {
      "description": "When this is required to be paid. Generally governed by the relationship with the Vendor",
      "type": "string",
      "format": "date-time"
    },
    "paymentTerms": {
      "description": "Invoice payment terms",
      "type": "string"
    },
    "paymentMethod": {
      "description": "Inherited from vendor record",
      "type": "string"
    },
    "prorata": {
      "description": "IF TRUE the additional charges will be applied to each line item and reflected in the total. IF FALSE each charge will be added to the invoice as it's own line item. (Default would be Yes) Ideally this can be done by price.",
      "type": "boolean",
      "default": true
    },
    "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. Manually, EDIFACT, MARC etc",
      "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}$"
    },
    "totalAmount": {
      "description": "Total amount",
      "type": "number"
    },
    "vendorInvoiceNo": {
      "description": "This is the number from the vendor's invoice this may or may not be the same as 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",
      "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}$"
    },
    "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]{5,16}$"
      }
    },
    "vendorId": {
      "description": "UUID of vendor",
      "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}$"
    },
    "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"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "currency",
    "folioInvoiceNo",
    "invoiceDate",
    "paymentMethod",
    "approvalDate",
    "status",
    "source",
    "totalAmount",
    "vendorInvoiceNo",
    "voucherNumber",
    "paymentId",
    "vendorId"
  ]
}

Example:

{
  "id": "c0d08448-347b-418a-8c2f-5fb50248d67e",
  "approvedBy": "ab18897b-0e40-4f31-896b-9c9adc979a88",
  "approvalDate": "2018-07-29T00:00:00.000+0000",
  "chkSubscriptionOverlap": false,
  "currency": "USD",
  "folioInvoiceNo": "123invoicenumber45",
  "invoiceDate": "2018-07-20T00:00:00.000+0000",
  "note": "Some note",
  "owner": "d79b0bcc-DcAD-1E4E-Abb7-DbFcaD5BB3bb",
  "paymentDue": "2018-08-29T00:00:00.000+0000",
  "paymentTerms": "Payment in Advance",
  "paymentMethod": "EFT",
  "prorata": false,
  "status": "Open",
  "source": "024b6f41-c5c6-4280-858e-33fba452a334",
  "totalAmount": 5,
  "vendorInvoiceNo": "YK75851",
  "disbursementNumber": "58",
  "voucherNumber": "478",
  "paymentId": "a5065f0d-fb88-4d23-b0c1-57e754fba40e",
  "disbursementDate": "2018-08-19T00:00:00.000+0000",
  "poNumbers": [
    "AB268758XYZ"
  ],
  "vendorId": "168f8a63-d612-406e-813f-c7527f241ac3",
  "manualPayment": true,
  "metadata": {
    "createdDate": "2018-07-19T00:00:00.000+0000",
    "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
  }
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update invoice -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"invoice not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /invoice-storage/invoice-lines

Get list of invoice lines

GET /invoice-storage/invoice-lines

Query Parameters

offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)
Skip over a number of elements by specifying an offset value for the query
Example:
```
0
```
limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)
Limit the number of elements returned in the response
Example:
```
10
```
query: (string)
A query expressed as a CQL string (see 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 poLineId
Example:
```
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode

poLineId=="c0d08448-347b-418a-8c2f-5fb50248d67e"
```
lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Returns a list of invoice-line items

Body

Media type: application/json

Type: json

Content:

{
  "$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"
  ]
}

Example:

{
  "invoiceLines": {
    "id": "e0d08448-343b-118a-8c2f-4fb50248d672",
    "description": "Some description",
    "poLineIds": [
      "c0d08448-347b-418a-8c2f-5fb50248d67e"
    ],
    "invoiceLineNumber": "123invoicenumber45-1",
    "invoiceLineStatus": "Open",
    "vendorRefNo": "1",
    "productId": "9780764354113",
    "productIdType": "ISBN",
    "invoiceLineTax": 11.2,
    "comment": "Sample invoice line",
    "price": 2.2,
    "quantity": 3.0,
    "doNotReleaseEncumbrance": true,
    "reportTax": 3.5,
    "subscriptionInfo": "Subscription information",
    "subscriptionStart": "2018-08-01T00:00:00.000+0000",
    "subscriptionEnd": "2019-01-01T00:00:00.000+0000",
    "pieceIds": [
      "5e317dc2-deeb-4429-b2a1-91e5cd0fd5f7"
    ],
    "invoiceId": "c0d08448-347b-418a-8c2f-5fb50248d67e",
    "fundDistributions": [
      "HIST"
    ],
    "adjustmentsFieldSet": [
      {
        "adjustmentLabel": "Adjustment label",
        "adjustmentType": "Percentage",
        "adjustmentValue": 10.1,
        "proRateAdjustment": true
      }
    ],
    "metadata": {
      "createdDate": "2018-07-19T00:00:00.000+0000",
      "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
    }
  },
  "totalRecords": 1
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list invoice-lines -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list invoice-lines -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /invoice-storage/invoice-lines

Create a new invoice-line item.

POST /invoice-storage/invoice-lines

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice line",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice line",
      "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}$"
    },
    "description": {
      "description": "Title as capured in the Purchase Order Line. In the absence of a POL link this could be used to describe the POL",
      "type": "string"
    },
    "poLineIds": {
      "description": "List of UUID`s of the POL",
      "id": "poLineIds",
      "type": "array",
      "items": {
        "description": "UUID of the purchase order line associated with invoice",
        "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}$"
      }
    },
    "invoiceLineNumber": {
      "description": "Sequentially generated and not editable by the user.",
      "type": "string",
      "readonly": true
    },
    "invoiceLineStatus": {
      "description": "Invoice line status",
      "type": "string",
      "enum": [
        "Open",
        "Reviewed",
        "Approved",
        "Paid",
        "Cancelled",
        "Error"
      ]
    },
    "vendorRefNo": {
      "description": "This is the number used to match POLs created by import to invoices created by import",
      "type": "string"
    },
    "productId": {
      "description": "product identifier",
      "type": "string"
    },
    "productIdType": {
      "description": "the type of product id",
      "type": "object",
      "$ref": "../../common/schemas/product_id_type.json"
    },
    "invoiceLineTax": {
      "description": "Invoice line tax",
      "type": "number"
    },
    "comment": {
      "description": "Free form commentary",
      "type": "string"
    },
    "price": {
      "description": "Invoice line price",
      "type": "number"
    },
    "quantity": {
      "description": "quantity",
      "type": "integer"
    },
    "doNotReleaseEncumbrance": {
      "description": "If this is intended to not only release encumbrances but to indicate that this is the final invoice. Should the label be changed? 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"
    },
    "reportTax": {
      "description": "Report tax",
      "type": "number"
    },
    "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"
    },
    "pieceIds": {
      "description": "Uuids for associated pieces as link through the POL",
      "id": "pieceIds",
      "type": "array",
      "items": {
        "description": "UUID of the piece",
        "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}$"
      }
    },
    "invoiceId": {
      "description": "UUID of this parent invoice",
      "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}$"
    },
    "fundDistributions": {
      "description": "List of fund distributions",
      "id": "fundDistributions",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "adjustmentsFieldSet": {
      "description": "Defined in settings - the amount field will be editable and pro-rate toggle will be editable if enabled for that adjustment",
      "id": "adjustmentsFieldSet",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "adjustment.json"
      }
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "description",
    "invoiceLineNumber",
    "invoiceLineStatus",
    "price",
    "quantity",
    "doNotReleaseEncumbrance",
    "pieceIds",
    "invoiceId",
    "fundDistributions"
  ]
}

Example:

{
  "id": "e0d08448-343b-118a-8c2f-4fb50248d672",
  "description": "Some description",
  "poLineIds": [
    "c0d08448-347b-418a-8c2f-5fb50248d67e"
  ],
  "invoiceLineNumber": "123invoicenumber45-1",
  "invoiceLineStatus": "Open",
  "vendorRefNo": "1",
  "productId": "9780764354113",
  "productIdType": "ISBN",
  "invoiceLineTax": 11.2,
  "comment": "Sample invoice line",
  "price": 2.2,
  "quantity": 3.0,
  "doNotReleaseEncumbrance": true,
  "reportTax": 3.5,
  "subscriptionInfo": "Subscription information",
  "subscriptionStart": "2018-08-01T00:00:00.000+0000",
  "subscriptionEnd": "2019-01-01T00:00:00.000+0000",
  "pieceIds": [
    "5e317dc2-deeb-4429-b2a1-91e5cd0fd5f7"
  ],
  "invoiceId": "c0d08448-347b-418a-8c2f-5fb50248d67e",
  "fundDistributions": [
    "HIST"
  ],
  "adjustmentsFieldSet": [
    {
      "adjustmentLabel": "Adjustment label",
      "adjustmentType": "Percentage",
      "adjustmentValue": 10.1,
      "proRateAdjustment": true
    }
  ],
  "metadata": {
    "createdDate": "2018-07-19T00:00:00.000+0000",
    "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
  }
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers

Location: required (string)
URI to the created invoice-line item

Body

Media type: application/json

Type: any

Example:

{
  "id": "e0d08448-343b-118a-8c2f-4fb50248d672",
  "description": "Some description",
  "poLineIds": [
    "c0d08448-347b-418a-8c2f-5fb50248d67e"
  ],
  "invoiceLineNumber": "123invoicenumber45-1",
  "invoiceLineStatus": "Open",
  "vendorRefNo": "1",
  "productId": "9780764354113",
  "productIdType": "ISBN",
  "invoiceLineTax": 11.2,
  "comment": "Sample invoice line",
  "price": 2.2,
  "quantity": 3.0,
  "doNotReleaseEncumbrance": true,
  "reportTax": 3.5,
  "subscriptionInfo": "Subscription information",
  "subscriptionStart": "2018-08-01T00:00:00.000+0000",
  "subscriptionEnd": "2019-01-01T00:00:00.000+0000",
  "pieceIds": [
    "5e317dc2-deeb-4429-b2a1-91e5cd0fd5f7"
  ],
  "invoiceId": "c0d08448-347b-418a-8c2f-5fb50248d67e",
  "fundDistributions": [
    "HIST"
  ],
  "adjustmentsFieldSet": [
    {
      "adjustmentLabel": "Adjustment label",
      "adjustmentType": "Percentage",
      "adjustmentValue": 10.1,
      "proRateAdjustment": true
    }
  ],
  "metadata": {
    "createdDate": "2018-07-19T00:00:00.000+0000",
    "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
  }
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add invoice-line -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create invoice-lines -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /invoice-storage/invoice-lines/{id}

Update invoice-line item with given {invoice-lineId}

PUT /invoice-storage/invoice-lines/{id}

URI Parameters

id: required (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}$)
The UUID of an invoice line

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice line",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice line",
      "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}$"
    },
    "description": {
      "description": "Title as capured in the Purchase Order Line. In the absence of a POL link this could be used to describe the POL",
      "type": "string"
    },
    "poLineIds": {
      "description": "List of UUID`s of the POL",
      "id": "poLineIds",
      "type": "array",
      "items": {
        "description": "UUID of the purchase order line associated with invoice",
        "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}$"
      }
    },
    "invoiceLineNumber": {
      "description": "Sequentially generated and not editable by the user.",
      "type": "string",
      "readonly": true
    },
    "invoiceLineStatus": {
      "description": "Invoice line status",
      "type": "string",
      "enum": [
        "Open",
        "Reviewed",
        "Approved",
        "Paid",
        "Cancelled",
        "Error"
      ]
    },
    "vendorRefNo": {
      "description": "This is the number used to match POLs created by import to invoices created by import",
      "type": "string"
    },
    "productId": {
      "description": "product identifier",
      "type": "string"
    },
    "productIdType": {
      "description": "the type of product id",
      "type": "object",
      "$ref": "../../common/schemas/product_id_type.json"
    },
    "invoiceLineTax": {
      "description": "Invoice line tax",
      "type": "number"
    },
    "comment": {
      "description": "Free form commentary",
      "type": "string"
    },
    "price": {
      "description": "Invoice line price",
      "type": "number"
    },
    "quantity": {
      "description": "quantity",
      "type": "integer"
    },
    "doNotReleaseEncumbrance": {
      "description": "If this is intended to not only release encumbrances but to indicate that this is the final invoice. Should the label be changed? 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"
    },
    "reportTax": {
      "description": "Report tax",
      "type": "number"
    },
    "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"
    },
    "pieceIds": {
      "description": "Uuids for associated pieces as link through the POL",
      "id": "pieceIds",
      "type": "array",
      "items": {
        "description": "UUID of the piece",
        "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}$"
      }
    },
    "invoiceId": {
      "description": "UUID of this parent invoice",
      "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}$"
    },
    "fundDistributions": {
      "description": "List of fund distributions",
      "id": "fundDistributions",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "adjustmentsFieldSet": {
      "description": "Defined in settings - the amount field will be editable and pro-rate toggle will be editable if enabled for that adjustment",
      "id": "adjustmentsFieldSet",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "adjustment.json"
      }
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "description",
    "invoiceLineNumber",
    "invoiceLineStatus",
    "price",
    "quantity",
    "doNotReleaseEncumbrance",
    "pieceIds",
    "invoiceId",
    "fundDistributions"
  ]
}

Example:

{
  "id": "e0d08448-343b-118a-8c2f-4fb50248d672",
  "description": "Some description",
  "poLineIds": [
    "c0d08448-347b-418a-8c2f-5fb50248d67e"
  ],
  "invoiceLineNumber": "123invoicenumber45-1",
  "invoiceLineStatus": "Open",
  "vendorRefNo": "1",
  "productId": "9780764354113",
  "productIdType": "ISBN",
  "invoiceLineTax": 11.2,
  "comment": "Sample invoice line",
  "price": 2.2,
  "quantity": 3.0,
  "doNotReleaseEncumbrance": true,
  "reportTax": 3.5,
  "subscriptionInfo": "Subscription information",
  "subscriptionStart": "2018-08-01T00:00:00.000+0000",
  "subscriptionEnd": "2019-01-01T00:00:00.000+0000",
  "pieceIds": [
    "5e317dc2-deeb-4429-b2a1-91e5cd0fd5f7"
  ],
  "invoiceId": "c0d08448-347b-418a-8c2f-5fb50248d67e",
  "fundDistributions": [
    "HIST"
  ],
  "adjustmentsFieldSet": [
    {
      "adjustmentLabel": "Adjustment label",
      "adjustmentType": "Percentage",
      "adjustmentValue": 10.1,
      "proRateAdjustment": true
    }
  ],
  "metadata": {
    "createdDate": "2018-07-19T00:00:00.000+0000",
    "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
  }
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update invoice-line -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"invoice-line not found"

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /invoice-storage/invoice-lines/{id}

Retrieve invoice-line item with given {invoice-lineId}

GET /invoice-storage/invoice-lines/{id}

URI Parameters

id: required (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}$)
The UUID of an invoice line

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "invoice line",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this invoice line",
      "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}$"
    },
    "description": {
      "description": "Title as capured in the Purchase Order Line. In the absence of a POL link this could be used to describe the POL",
      "type": "string"
    },
    "poLineIds": {
      "description": "List of UUID`s of the POL",
      "id": "poLineIds",
      "type": "array",
      "items": {
        "description": "UUID of the purchase order line associated with invoice",
        "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}$"
      }
    },
    "invoiceLineNumber": {
      "description": "Sequentially generated and not editable by the user.",
      "type": "string",
      "readonly": true
    },
    "invoiceLineStatus": {
      "description": "Invoice line status",
      "type": "string",
      "enum": [
        "Open",
        "Reviewed",
        "Approved",
        "Paid",
        "Cancelled",
        "Error"
      ]
    },
    "vendorRefNo": {
      "description": "This is the number used to match POLs created by import to invoices created by import",
      "type": "string"
    },
    "productId": {
      "description": "product identifier",
      "type": "string"
    },
    "productIdType": {
      "description": "the type of product id",
      "type": "object",
      "$ref": "../../common/schemas/product_id_type.json"
    },
    "invoiceLineTax": {
      "description": "Invoice line tax",
      "type": "number"
    },
    "comment": {
      "description": "Free form commentary",
      "type": "string"
    },
    "price": {
      "description": "Invoice line price",
      "type": "number"
    },
    "quantity": {
      "description": "quantity",
      "type": "integer"
    },
    "doNotReleaseEncumbrance": {
      "description": "If this is intended to not only release encumbrances but to indicate that this is the final invoice. Should the label be changed? 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"
    },
    "reportTax": {
      "description": "Report tax",
      "type": "number"
    },
    "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"
    },
    "pieceIds": {
      "description": "Uuids for associated pieces as link through the POL",
      "id": "pieceIds",
      "type": "array",
      "items": {
        "description": "UUID of the piece",
        "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}$"
      }
    },
    "invoiceId": {
      "description": "UUID of this parent invoice",
      "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}$"
    },
    "fundDistributions": {
      "description": "List of fund distributions",
      "id": "fundDistributions",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "adjustmentsFieldSet": {
      "description": "Defined in settings - the amount field will be editable and pro-rate toggle will be editable if enabled for that adjustment",
      "id": "adjustmentsFieldSet",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "adjustment.json"
      }
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "description",
    "invoiceLineNumber",
    "invoiceLineStatus",
    "price",
    "quantity",
    "doNotReleaseEncumbrance",
    "pieceIds",
    "invoiceId",
    "fundDistributions"
  ]
}

Example:

{
  "id": "e0d08448-343b-118a-8c2f-4fb50248d672",
  "description": "Some description",
  "poLineIds": [
    "c0d08448-347b-418a-8c2f-5fb50248d67e"
  ],
  "invoiceLineNumber": "123invoicenumber45-1",
  "invoiceLineStatus": "Open",
  "vendorRefNo": "1",
  "productId": "9780764354113",
  "productIdType": "ISBN",
  "invoiceLineTax": 11.2,
  "comment": "Sample invoice line",
  "price": 2.2,
  "quantity": 3.0,
  "doNotReleaseEncumbrance": true,
  "reportTax": 3.5,
  "subscriptionInfo": "Subscription information",
  "subscriptionStart": "2018-08-01T00:00:00.000+0000",
  "subscriptionEnd": "2019-01-01T00:00:00.000+0000",
  "pieceIds": [
    "5e317dc2-deeb-4429-b2a1-91e5cd0fd5f7"
  ],
  "invoiceId": "c0d08448-347b-418a-8c2f-5fb50248d67e",
  "fundDistributions": [
    "HIST"
  ],
  "adjustmentsFieldSet": [
    {
      "adjustmentLabel": "Adjustment label",
      "adjustmentType": "Percentage",
      "adjustmentValue": 10.1,
      "proRateAdjustment": true
    }
  ],
  "metadata": {
    "createdDate": "2018-07-19T00:00:00.000+0000",
    "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
  }
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"invoice-line not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /invoice-storage/invoice-lines/{id}

Delete invoice-line item with given {invoice-lineId}

DELETE /invoice-storage/invoice-lines/{id}

URI Parameters

id: required (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}$)
The UUID of an invoice line

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete invoice-line -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"invoice-line not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

GET /invoice-storage/invoice-number

Get generated invoice number

GET /invoice-storage/invoice-number

Query Parameters

lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Sequence number object",
  "type": "object",
  "properties": {
    "sequenceNumber": {
      "description": "Sequence number",
      "type": "string"
    }
  },
  "required": [
    "sequenceNumber"
  ],
  "additionalProperties": false
}

Response 400

Bad request, e.g. malformed request body or query parameter

Body

Media type: text/plain

Type: any

Example:

Unable to generate invoice number

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /invoice-storage/invoice-line-number

Get invoice line number

GET /invoice-storage/invoice-line-number

Query Parameters

invoiceId: required (string)
invoice Id
Example:
```
8ad4b87b-9b47-4199-b0c3-5480745c6b41
```
lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Sequence number object",
  "type": "object",
  "properties": {
    "sequenceNumber": {
      "description": "Sequence number",
      "type": "string"
    }
  },
  "required": [
    "sequenceNumber"
  ],
  "additionalProperties": false
}

Response 400

Bad request, e.g. malformed request body or query parameter

Body

Media type: text/plain

Type: any

Example:

Unable to generate invoice line number

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact Administrator

Invoices (v1)

Table of contents

Invoice CRUD API

/invoice-storage

GET /invoice-storage/invoices

Query Parameters

Response 200

Response 400

Response 401

Response 500

POST /invoice-storage/invoices

Query Parameters

Response 201

Headers

Response 400

Response 401

Response 500

GET /invoice-storage/invoices/{id}

URI Parameters

Query Parameters

Response 200

Response 404

Response 500

DELETE /invoice-storage/invoices/{id}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

PUT /invoice-storage/invoices/{id}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

GET /invoice-storage/invoice-lines

Query Parameters

Response 200

Response 400

Response 401

Response 500

POST /invoice-storage/invoice-lines

Query Parameters

Response 201

Headers

Response 400

Response 401

Response 500

PUT /invoice-storage/invoice-lines/{id}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 422

Response 500

GET /invoice-storage/invoice-lines/{id}

URI Parameters

Query Parameters

Response 200

Response 404

Response 500

DELETE /invoice-storage/invoice-lines/{id}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

GET /invoice-storage/invoice-number

Query Parameters

Response 200

Response 400

Response 500

GET /invoice-storage/invoice-line-number

Query Parameters

Response 200

Response 400