Batch Vouchers version v2.0
http://github.com/folio-org/mod-invoice-storage
Batch Vouchers API
API used to manage batch vouchers.
/batch-voucher/batch-vouchers
Get and Delete a specific batch voucher. Update operation is not allowed
get
Retrieve batch-voucher item with given {batch-voucherId}
get /batch-voucher/batch-vouchers/{id}
Retrieve batch-voucher item with given {batch-voucherId}
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 a batch voucher
Headers
- Accept: required(string)
either application/xml or application/json
HTTP status code 200
Returns item with a given ID
Body
Media type: application/xml
Type: any
Example:
<batchVoucher>
<id>cb7592ae-621c-4f35-bc1d-47909e55f9f5</id>
<batchGroup>Amherst College (AC)</batchGroup>
<created>2019-12-07T00:01:04Z</created>
<start>2019-12-06T00:00:00Z</start>
<end>2019-12-07T00:00:00Z</end>
<batchedVouchers>
<batchedVoucher>
<accountingCode>0206</accountingCode>
<amount>23.45</amount>
<batchedVoucherLines>
<batchedVoucherLine>
<amount>23.45</amount>
<fundCodes>
<fundCode>HIST</fundCode>
<fundCode>LATHIST</fundCode>
<fundCode>CANHIST</fundCode>
</fundCodes>
<externalAccountNumber>54321098</externalAccountNumber>
</batchedVoucherLine>
</batchedVoucherLines>
<adjustments>
<adjustment>
<description>GST</description>
<prorate>Not pro rate</prorate>
<relationToTotal>Separate from</relationToTotal>
<type>Payment</type>
<value>20.0</value>
<totalAmount>20.0</totalAmount>
</adjustment>
</adjustments>
<disbursementNumber>EFT546789</disbursementNumber>
<disbursementDate>2019-12-06T00:01:04Z</disbursementDate>
<disbursementAmount>23.45</disbursementAmount>
<enclosureNeeded>false</enclosureNeeded>
<exchangeRate>1</exchangeRate>
<folioInvoiceNo>123folionumber456</folioInvoiceNo>
<invoiceCurrency>USD</invoiceCurrency>
<invoiceDate>2019-12-05T00:00:00Z</invoiceDate>
<invoiceTerms>Payment in Advance</invoiceTerms>
<invoiceNote>Process immediately</invoiceNote>
<status>Paid</status>
<systemCurrency>USD</systemCurrency>
<type>Voucher</type>
<vendorInvoiceNo>YK75851</vendorInvoiceNo>
<vendorName>GOBI</vendorName>
<voucherDate>2019-12-06T00:00:00Z</voucherDate>
<voucherNumber>1023</voucherNumber>
<vendorAddress>
<addressLine1>10 Estes Street</addressLine1>
<city>Ipswich</city>
<stateRegion>MA</stateRegion>
<zipCode>01938</zipCode>
<country>USA</country>
</vendorAddress>
</batchedVoucher>
</batchedVouchers>
<totalRecords>1</totalRecords>
</batchVoucher>
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "top-level batch voucher, i.e. a collection of batched vouchers",
"type": "object",
"properties": {
"id": {
"description": "UUID of batch voucher",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"batchGroup": {
"description": "The human-readable name of the batch group used when generating this batch voucher",
"type": "string"
},
"batchedVouchers": {
"description": "an array of batched voucher records",
"id": "batchVouchers",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A single voucher which is part of a batch voucher",
"properties": {
"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"
},
"batchedVoucherLines": {
"description": "an array of batched voucher line records",
"id": "batchedVoucherLines",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "One line of a batched voucher",
"properties": {
"amount": {
"description": "Total amount of this voucher",
"type": "number"
},
"fundCodes": {
"description": "an array of fund codes",
"id": "fundCodes",
"type": "array",
"items": {
"type": "string"
}
},
"externalAccountNumber": {
"description": "All distributions that come from funds with the same account number are grouped by voucher line",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"amount",
"externalAccountNumber",
"fundCodes"
]
}
},
"adjustments": {
"description": "Defined in settings - the amount field will be editable and pro-rate toggle will be editable if enabled for that adjustment",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Adjustment",
"properties": {
"id": {
"description": "UUID of this adjustment",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"adjustmentId": {
"description": "UUID of the Invoice adjustment incase of prorated adjustments",
"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": "Displayed in invoice line as a name for the input",
"type": "string"
},
"exportToAccounting": {
"description": "Whether or not to show this adjustment in batchedVoucherLines",
"type": "boolean",
"default": false
},
"fundDistributions": {
"description": "Fund distribution records from which this adjustment will be paid; only valid at invoice level",
"id": "fundDistributions",
"type": "array",
"items": {
"description": "fund distribution record",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"code": {
"description": "The code of the fund associated with this fund distribution",
"type": "string"
},
"encumbrance": {
"description": "UUID of encumbrance record associated with this fund distribution",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"fundId": {
"description": "UUID of the fund associated with this fund distribution",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"invoiceLineId": {
"description": "UUID of the invoice line associated with this fund distribution",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"distributionType": {
"description": "Percentage or amount type of the value property",
"type": "string",
"enum": [
"amount",
"percentage"
],
"default": "percentage"
},
"expenseClassId": {
"description": "UUID of the expense class associated with this fund distribution",
"$schema": "http://json-schema.org/draft-04/schema#",
"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}$"
},
"value": {
"description": "The percentage of the cost to be applied to this fund",
"type": "number"
}
},
"additionalProperties": false,
"required": [
"fundId",
"distributionType",
"value"
]
}
},
"prorate": {
"description": "Displayed in invoice line per adjustment in toggled on in settings",
"type": "string",
"enum": [
"By line",
"By amount",
"By quantity",
"Not prorated"
],
"default": "Not prorated"
},
"relationToTotal": {
"description": "Relationship of this adjustment to the total;In addition to: added to subtotal;Included in: reported as subtotal portion;Separate from:calculated from subtotal",
"type": "string",
"enum": [
"In addition to",
"Included in",
"Separate from"
],
"default": "In addition to"
},
"type": {
"description": "Adjustment type",
"type": "string",
"enum": [
"Percentage",
"Amount"
]
},
"value": {
"description": "Adjustment value",
"type": "number"
},
"totalAmount": {
"description": "Total adjustment amount",
"type": "number"
}
},
"additionalProperties": false,
"required": [
"description",
"exportToAccounting",
"prorate",
"relationToTotal",
"type",
"value"
]
}
},
"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
},
"exchangeRate": {
"description": "Exchange rate used to generate transaction",
"type": "number"
},
"folioInvoiceNo": {
"description": "Represents associated invoice number",
"type": "string"
},
"invoiceCurrency": {
"description": "The currency in which invoice was originally defined",
"type": "string"
},
"invoiceDate": {
"description": "Invoice date",
"type": "string",
"format": "date-time"
},
"invoiceTerms": {
"description": "Invoice payment terms",
"type": "string"
},
"invoiceNote": {
"description": "Free-form notes from the invoice",
"type": "string"
},
"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"
]
},
"vendorInvoiceNo": {
"description": "Corresponding invoice's vendorInvoiceNo",
"type": "string"
},
"vendorName": {
"description": "The name of the vendor",
"type": "string"
},
"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]*$"
},
"vendorAddress": {
"description": "Primary address of the vendor.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"addressLine1": {
"description": "The first line of this address",
"type": "string"
},
"addressLine2": {
"description": "The second line of this address",
"type": "string"
},
"city": {
"description": "The city for this address",
"type": "string"
},
"stateRegion": {
"description": "The state or region for this address",
"type": "string"
},
"zipCode": {
"description": "The zip code for this address",
"type": "string"
},
"country": {
"description": "The country for this address",
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"accountingCode",
"amount",
"batchedVoucherLines",
"folioInvoiceNo",
"invoiceCurrency",
"status",
"systemCurrency",
"type",
"vendorInvoiceNo",
"vendorName",
"voucherDate",
"voucherNumber"
]
}
},
"created": {
"description": "When this batch voucher was created",
"type": "string",
"format": "date-time"
},
"start": {
"description": "This export is for all vouchers between start and end",
"type": "string",
"format": "date-time"
},
"end": {
"description": "This export is for all vouchers between start and end",
"type": "string",
"format": "date-time"
},
"totalRecords": {
"description": "total number of records in the array",
"type": "integer"
}
},
"required": [
"batchGroup",
"batchedVouchers",
"created",
"start",
"end",
"totalRecords"
]
}Example:
{
"id": "35657479-83b9-4760-9c39-b58dcd02ee27",
"batchGroup": "Amherst College (AC)",
"start": "2019-12-06T00:00:00.000+0000",
"end": "2019-12-07T00:00:00.000+0000",
"created": "2019-12-07T00:01:04.000+0000",
"batchedVouchers": [
{
"accountingCode": "0206",
"amount": 23.45,
"disbursementNumber": "EFT546789",
"disbursementDate": "2019-12-06T00:01:04.000+0000",
"disbursementAmount": 23.45,
"enclosureNeeded": false,
"exchangeRate": 1,
"folioInvoiceNo": "123invoicenumber45",
"invoiceCurrency": "USD",
"invoiceDate": "2019-12-05T00:00:00.000+0000",
"invoiceTerms": "Payment in Advance",
"invoiceNote": "Process immediately",
"status": "Paid",
"systemCurrency": "USD",
"type": "Voucher",
"voucherDate": "2019-12-06T00:00:00.000+0000",
"voucherNumber": "1023",
"vendorName": "GOBI",
"vendorInvoiceNo": "YK75851",
"vendorAddress": {
"addressLine1": "10 Estes Street",
"addressLine2": "",
"city": "Ipswich",
"stateRegion": "MA",
"zipCode": "01938",
"country": "USA"
},
"batchVoucherLines": [
{
"amount": 23.45,
"externalAccountNumber": "54321098",
"fundCodes": [
"HIST",
"LATHIST",
"CANHIST"
]
}
]
}
],
"totalRecords": 1
}
HTTP status code 401
Not authorized to perform requested action
Body
Media type: application/json
Type: any
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Media type: text/plain
Type: any
Example:
unable to get retrieve batch-voucher -- unauthorizedHTTP status code 404
Item with a given ID not found
Body
Media type: application/json
Type: any
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Media type: text/plain
Type: any
Example:
"batch-voucher not found"
HTTP status code 422
Validation errors
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"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"
}
]
}
]
}
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: application/json
Type: any
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Media type: text/plain
Type: any
Example:
internal server error, contact administrator