foliolib.folio.api.invoiceStorage.Voucher

class foliolib.folio.api.invoiceStorage.Voucher(tenant: str, okapi: Optional[foliolib.okapi.okapiClient.OkapiClient] = None)

Bases: foliolib.folio.FolioApi

Vouchers CRUD API

This documents the API calls that can be made to manage vouchers;This API is intended for internal use only

Parameters

tenant (str) – Tenant id
okapi (OkapiClient, optional) – Instance of OkapiClient. Defaults to None.

Methods

`delete_voucher`(vouchersId)	Delete voucher item with given {voucherId}
`delete_voucherLine`(voucherLinesId)	Delete voucherLine item with given {voucherLineId}
`get_voucher`(vouchersId)	Retrieve voucher item with given {voucherId}
`get_voucherLine`(voucherLinesId)	Retrieve voucherLine item with given {voucherLineId}
`get_voucherLines`(**kwargs)	Get list of voucher lines
`get_vouchers`(**kwargs)	Get list of vouchers
`modify_voucher`(vouchersId, voucher)	Update voucher item with given {voucherId}
`modify_voucherLine`(voucherLinesId, voucherLine)	Update voucherLine item with given {voucherLineId}
`set_voucher`(voucher)	Create a new voucher item.
`set_voucherLine`(voucherLine)	Create a new voucherLine item.

delete_voucher(vouchersId: str)

Delete voucher item with given {voucherId}

DELETE /voucher-storage/vouchers/{vouchersId}

Parameters

vouchersId (str) –

Raises

OkapiRequestNotFound – Not Found
OkapiRequestError – Bad Request
OkapiFatalError – Server Error

delete_voucherLine(voucherLinesId: str)

Delete voucherLine item with given {voucherLineId}

DELETE /voucher-storage/voucher-lines/{voucherLinesId}

Parameters

voucherLinesId (str) –

Raises

OkapiRequestNotFound – Not Found
OkapiRequestError – Bad Request
OkapiFatalError – Server Error

get_voucher(vouchersId: str)

Retrieve voucher item with given {voucherId}

GET /voucher-storage/vouchers/{vouchersId}

Parameters

vouchersId (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": "voucher",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this voucher",
      "$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"
    },
    "accountNo": {
      "description": "The unique number of the organization account",
      "type": "string"
    },
    "amount": {
      "description": "The amount that is actually paid",
      "type": "number"
    },
    "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"
    },
    "disbursementNumber": {
      "description": "The identifier for the physical transaction corresponding to a payment;Brought in from external source",
      "type": "string"
    },
    "disbursementDate": {
      "description": "Date payment was made from financial system",
      "type": "string",
      "format": "date-time"
    },
    "disbursementAmount": {
      "description": "The amount of the payment made outside of FOLIO",
      "type": "number"
    },
    "enclosureNeeded": {
      "description": "Indicates that an enclosure is needed",
      "type": "boolean",
      "default": false
    },
    "invoiceCurrency": {
      "description": "The currency in which invoice was originally defined",
      "type": "string"
    },
    "invoiceId": {
      "description": "Corresponding invoice Id",
      "$ref": "../../common/schemas/uuid.json"
    },
    "exchangeRate": {
      "description": "Exchange rate used to generate transaction",
      "type": "number"
    },
    "exportToAccounting": {
      "description": "Export this payment record to a financial system",
      "type": "boolean"
    },
    "status": {
      "description": "Status of the voucher",
      "type": "string",
      "enum": [
        "Awaiting payment",
        "Paid",
        "Cancelled"
      ]
    },
    "systemCurrency": {
      "description": "The currency in which the voucher was paid",
      "type": "string"
    },
    "type": {
      "description": "Indicates type of payment to account",
      "type": "string",
      "enum": [
        "Payment",
        "Pre-payment",
        "Credit",
        "Voucher"
      ]
    },
    "voucherDate": {
      "description": "The date the invoice status changes to approved",
      "type": "string",
      "format": "date-time"
    },
    "voucherNumber": {
      "description": "Number generated by folio that will eventually identify the payment request sent out to external financial system.",
      "type": "string",
      "pattern": "^[a-zA-Z0-9]*$"
    },
    "vendorId": {
      "description": "UUID of vendor related to the voucher",
      "$ref": "../../common/schemas/uuid.json"
    },
    "vendorAddress": {
      "description": "Primary address of the vendor.",
      "type": "object",
      "$ref": "batch_voucher_vendor_address.json",
      "readonly": true
    },
    "acqUnitIds": {
      "description": "acquisition unit ids associated with this voucher",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "amount",
    "batchGroupId",
    "exportToAccounting",
    "invoiceCurrency",
    "invoiceId",
    "type",
    "status",
    "systemCurrency",
    "voucherNumber"
  ]
}

get_voucherLine(voucherLinesId: str)

Retrieve voucherLine item with given {voucherLineId}

GET /voucher-storage/voucher-lines/{voucherLinesId}

Parameters

voucherLinesId (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": "voucher line",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this voucher line",
      "$ref": "../../common/schemas/uuid.json"
    },
    "amount": {
      "description": "Total amount of this voucher",
      "type": "number"
    },
    "externalAccountNumber": {
      "description": "All distributions that come from funds with the same account number are grouped by voucher line",
      "type": "string"
    },
    "fundDistributions": {
      "description": "List of fund distributions",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "fund_distribution.json"
      },
      "minItems": 1
    },
    "sourceIds": {
      "description": "UUID of invoice lines. There could be many invoice lines against a single voucher line. These are group on a voucher line based on External account number",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "subTransactionId": {
      "description": "UUID of sub transactions",
      "$ref": "../../common/schemas/uuid.json"
    },
    "voucherId": {
      "description": "UUID of the voucher this line belongs to",
      "$ref": "../../common/schemas/uuid.json"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "amount",
    "externalAccountNumber",
    "fundDistributions",
    "sourceIds",
    "voucherId"
  ]
}

get_voucherLines(**kwargs)

Get list of voucher lines

GET /voucher-storage/voucher-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.

with valid searchable fields: for example externalAccountNumber

Example
- (username==”ab*” or personal.firstName==”ab*” or personal.lastName==”ab*”) and active==”true” sortby personal.lastName personal.firstName barcode
- externalAccountNumber==”567891045”

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestUnauthorized – Authentication is required
OkapiFatalError – Server Error

Schema

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

get_vouchers(**kwargs)

Get list of vouchers

GET /voucher-storage/vouchers

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.

with valid searchable fields: for example voucherStatus

Example
- (username==”ab*” or personal.firstName==”ab*” or personal.lastName==”ab*”) and active==”true” sortby personal.lastName personal.firstName barcode
- voucherStatus==”Paid”

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestUnauthorized – Authentication is required
OkapiFatalError – Server Error

Schema

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

modify_voucher(vouchersId: str, voucher: dict)

Update voucher item with given {voucherId}

PUT /voucher-storage/vouchers/{vouchersId}

Parameters

vouchersId (str) –
voucher (dict) – See Schema below

Raises

OkapiRequestNotFound – Not Found
OkapiRequestError – Bad Request
OkapiRequestConflict – Conflict
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "voucher",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this voucher",
      "$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"
    },
    "accountNo": {
      "description": "The unique number of the organization account",
      "type": "string"
    },
    "amount": {
      "description": "The amount that is actually paid",
      "type": "number"
    },
    "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"
    },
    "disbursementNumber": {
      "description": "The identifier for the physical transaction corresponding to a payment;Brought in from external source",
      "type": "string"
    },
    "disbursementDate": {
      "description": "Date payment was made from financial system",
      "type": "string",
      "format": "date-time"
    },
    "disbursementAmount": {
      "description": "The amount of the payment made outside of FOLIO",
      "type": "number"
    },
    "enclosureNeeded": {
      "description": "Indicates that an enclosure is needed",
      "type": "boolean",
      "default": false
    },
    "invoiceCurrency": {
      "description": "The currency in which invoice was originally defined",
      "type": "string"
    },
    "invoiceId": {
      "description": "Corresponding invoice Id",
      "$ref": "../../common/schemas/uuid.json"
    },
    "exchangeRate": {
      "description": "Exchange rate used to generate transaction",
      "type": "number"
    },
    "exportToAccounting": {
      "description": "Export this payment record to a financial system",
      "type": "boolean"
    },
    "status": {
      "description": "Status of the voucher",
      "type": "string",
      "enum": [
        "Awaiting payment",
        "Paid",
        "Cancelled"
      ]
    },
    "systemCurrency": {
      "description": "The currency in which the voucher was paid",
      "type": "string"
    },
    "type": {
      "description": "Indicates type of payment to account",
      "type": "string",
      "enum": [
        "Payment",
        "Pre-payment",
        "Credit",
        "Voucher"
      ]
    },
    "voucherDate": {
      "description": "The date the invoice status changes to approved",
      "type": "string",
      "format": "date-time"
    },
    "voucherNumber": {
      "description": "Number generated by folio that will eventually identify the payment request sent out to external financial system.",
      "type": "string",
      "pattern": "^[a-zA-Z0-9]*$"
    },
    "vendorId": {
      "description": "UUID of vendor related to the voucher",
      "$ref": "../../common/schemas/uuid.json"
    },
    "vendorAddress": {
      "description": "Primary address of the vendor.",
      "type": "object",
      "$ref": "batch_voucher_vendor_address.json",
      "readonly": true
    },
    "acqUnitIds": {
      "description": "acquisition unit ids associated with this voucher",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "amount",
    "batchGroupId",
    "exportToAccounting",
    "invoiceCurrency",
    "invoiceId",
    "type",
    "status",
    "systemCurrency",
    "voucherNumber"
  ]
}

modify_voucherLine(voucherLinesId: str, voucherLine: dict)

Update voucherLine item with given {voucherLineId}

PUT /voucher-storage/voucher-lines/{voucherLinesId}

Parameters

voucherLinesId (str) –
voucherLine (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": "voucher line",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this voucher line",
      "$ref": "../../common/schemas/uuid.json"
    },
    "amount": {
      "description": "Total amount of this voucher",
      "type": "number"
    },
    "externalAccountNumber": {
      "description": "All distributions that come from funds with the same account number are grouped by voucher line",
      "type": "string"
    },
    "fundDistributions": {
      "description": "List of fund distributions",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "fund_distribution.json"
      },
      "minItems": 1
    },
    "sourceIds": {
      "description": "UUID of invoice lines. There could be many invoice lines against a single voucher line. These are group on a voucher line based on External account number",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "subTransactionId": {
      "description": "UUID of sub transactions",
      "$ref": "../../common/schemas/uuid.json"
    },
    "voucherId": {
      "description": "UUID of the voucher this line belongs to",
      "$ref": "../../common/schemas/uuid.json"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "amount",
    "externalAccountNumber",
    "fundDistributions",
    "sourceIds",
    "voucherId"
  ]
}

set_voucher(voucher: dict)

Create a new voucher item.

POST /voucher-storage/vouchers

Parameters

voucher (dict) – See Schema below

Raises

OkapiRequestError – Bad Request
OkapiRequestUnauthorized – Authentication is required
OkapiFatalError – Server Error

Headers

Location - URI to the created voucher item

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "voucher",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this voucher",
      "$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"
    },
    "accountNo": {
      "description": "The unique number of the organization account",
      "type": "string"
    },
    "amount": {
      "description": "The amount that is actually paid",
      "type": "number"
    },
    "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"
    },
    "disbursementNumber": {
      "description": "The identifier for the physical transaction corresponding to a payment;Brought in from external source",
      "type": "string"
    },
    "disbursementDate": {
      "description": "Date payment was made from financial system",
      "type": "string",
      "format": "date-time"
    },
    "disbursementAmount": {
      "description": "The amount of the payment made outside of FOLIO",
      "type": "number"
    },
    "enclosureNeeded": {
      "description": "Indicates that an enclosure is needed",
      "type": "boolean",
      "default": false
    },
    "invoiceCurrency": {
      "description": "The currency in which invoice was originally defined",
      "type": "string"
    },
    "invoiceId": {
      "description": "Corresponding invoice Id",
      "$ref": "../../common/schemas/uuid.json"
    },
    "exchangeRate": {
      "description": "Exchange rate used to generate transaction",
      "type": "number"
    },
    "exportToAccounting": {
      "description": "Export this payment record to a financial system",
      "type": "boolean"
    },
    "status": {
      "description": "Status of the voucher",
      "type": "string",
      "enum": [
        "Awaiting payment",
        "Paid",
        "Cancelled"
      ]
    },
    "systemCurrency": {
      "description": "The currency in which the voucher was paid",
      "type": "string"
    },
    "type": {
      "description": "Indicates type of payment to account",
      "type": "string",
      "enum": [
        "Payment",
        "Pre-payment",
        "Credit",
        "Voucher"
      ]
    },
    "voucherDate": {
      "description": "The date the invoice status changes to approved",
      "type": "string",
      "format": "date-time"
    },
    "voucherNumber": {
      "description": "Number generated by folio that will eventually identify the payment request sent out to external financial system.",
      "type": "string",
      "pattern": "^[a-zA-Z0-9]*$"
    },
    "vendorId": {
      "description": "UUID of vendor related to the voucher",
      "$ref": "../../common/schemas/uuid.json"
    },
    "vendorAddress": {
      "description": "Primary address of the vendor.",
      "type": "object",
      "$ref": "batch_voucher_vendor_address.json",
      "readonly": true
    },
    "acqUnitIds": {
      "description": "acquisition unit ids associated with this voucher",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "amount",
    "batchGroupId",
    "exportToAccounting",
    "invoiceCurrency",
    "invoiceId",
    "type",
    "status",
    "systemCurrency",
    "voucherNumber"
  ]
}

set_voucherLine(voucherLine: dict)

Create a new voucherLine item.

POST /voucher-storage/voucher-lines

Parameters

voucherLine (dict) – See Schema below

Raises

OkapiRequestError – Bad Request
OkapiRequestUnauthorized – Authentication is required
OkapiFatalError – Server Error

Headers

Location - URI to the created voucherLine item

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "voucher line",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this voucher line",
      "$ref": "../../common/schemas/uuid.json"
    },
    "amount": {
      "description": "Total amount of this voucher",
      "type": "number"
    },
    "externalAccountNumber": {
      "description": "All distributions that come from funds with the same account number are grouped by voucher line",
      "type": "string"
    },
    "fundDistributions": {
      "description": "List of fund distributions",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "fund_distribution.json"
      },
      "minItems": 1
    },
    "sourceIds": {
      "description": "UUID of invoice lines. There could be many invoice lines against a single voucher line. These are group on a voucher line based on External account number",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "subTransactionId": {
      "description": "UUID of sub transactions",
      "$ref": "../../common/schemas/uuid.json"
    },
    "voucherId": {
      "description": "UUID of the voucher this line belongs to",
      "$ref": "../../common/schemas/uuid.json"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "amount",
    "externalAccountNumber",
    "fundDistributions",
    "sourceIds",
    "voucherId"
  ]
}