foliolib.folio.api.invoice.Voucher

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

Bases: foliolib.folio.FolioApi

Voucher API

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

Parameters

• tenant (str) – Tenant id

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

Methods

get_starts()	Get the current start value of the voucher number sequence
get_voucher(vouchersId)	Return a voucher with given {id}
get_voucherLine(voucherLinesId, **kwargs)	Return an voucher line with given {id}
get_voucherLines()	Retrieve a list of voucher lines.
get_vouchers(**kwargs)	Retrieve a list of voucher items.
modify_voucher(vouchersId)	PUT /voucher/vouchers/{vouchersId}
modify_voucherLine(voucherLinesId)	PUT /voucher/voucher-lines/{voucherLinesId}
set_start(value)	(Re)set the start value of the voucher number sequence

get_starts()

Get the current start value of the voucher number sequence

GET /voucher/voucher-number/start

Returns

See Schema below

Return type

dict

Raises

OkapiFatalError – Server Error

Schema

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

get_voucher(vouchersId: str)

Return a voucher with given {id}

GET /voucher/vouchers/{vouchersId}

Parameters

vouchersId (str) –

Returns

See Schema below

Return type

dict

Raises

• OkapiRequestUnauthorized – Authentication is required

• 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, **kwargs)

Return an voucher line with given {id}

GET /voucher/voucher-lines/{voucherLinesId}

Parameters

• voucherLinesId (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.

  using CQL (indexes for voucher)

  Example

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

  • voucherNumber==”1000”

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": "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()

Retrieve a list of voucher lines.

GET /voucher/voucher-lines

Returns

See Schema below

Return type

dict

Raises

• OkapiRequestError – Bad Request

• OkapiRequestUnauthorized – Authentication is required

• OkapiRequestNotFound – Not Found

• 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)

Retrieve a list of voucher items.

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

  using CQL (indexes for voucher)

  Example

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

  • voucherNumber==”1000”

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 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)

PUT /voucher/vouchers/{vouchersId}

Parameters

vouchersId (str) –

modify_voucherLine(voucherLinesId: str)

PUT /voucher/voucher-lines/{voucherLinesId}

Parameters

voucherLinesId (str) –

set_start(value: str)

(Re)set the start value of the voucher number sequence

POST /voucher/voucher-number/start/{value}

Parameters

value (str) –

Raises

• OkapiRequestError – Bad Request

• OkapiFatalError – Server Error