getPurchaseDocuments

Returns a list of purchase documents (purchase invoices or orders), according to the supplied filtering parameters.

If you have specified document ID or invoice number, or if the search criteria match a single sales document, or if you have set getRowsForAllInvoices = 1, API returns all documents together with their rows. Otherwise only document headers will be returned.

If you are looking for a way to pull all purchase data for external processing, see getPurchaseReport. getPurchaseReport can output either detailed data or aggregate it as needed: it can provide totals by products, by product groups, by dates, by locations, etc.

Input parameters

Parameter name	Description	Possible value
id	ID of a specific purchase document	integer
ids	Multiple purchase document IDs, separated by commas, such as: 1,2,3,4,5.	string
supplierID	Supplier ID.	integer
supplierIDs	Multiple supplier IDs, separated by commas, such as: 1,2,3,4,5.	string
type	PRCINVOICE, CASHPRCINVOICE, PRCORDER, PRCRETURN, PRCWAYBILL, PRCINVOICEONLY, COMMITMENT, COMMITMENT_DEDUCTION or AVAILABILITY_CHANGE. See explanation below!	string
status	Comma-separated list of statuses. The possible statuses are: PENDING, PARTIALLY_RECEIVED, RECEIVED or READY. See explanation below!	string
stateID	Purchase document status ID	integer
dateFrom	Filter by purchase document date field	Date (yyyy-mm-dd)
dateTo	Filter by purchase document date field	Date (yyyy-mm-dd)
confirmed	integer	0 or 1. integer
paid	integer	0 or 1. integer
number	Number of purchase document.	string
referenceNumber	Reference number of purchase document.	string
warehouseID	Warehouse ID.	integer
regnumber	Reg. number of purchase document.	string
employeeID	ID of the system employee, who is set as the creator of the invoice/order/etc.	integer
reasonID	Reason ID.	integer
shipDateFrom	Filter by the ship date field	Date (yyyy-mm-dd)
shipDateTo	Filter by the ship date field	Date (yyyy-mm-dd)
emailEnabled		Integer (1 or 0)
eInvoiceEnabled		Integer (1 or 0)
docuraEDIEnabled		Integer (1 or 0)
getRowsForAllInvoices	Set this field to 1 to retrieve the rows for each returned purchase document. Not that in some cases, rows are returned anyway — see the specification of the "rows" field below.	0 or 1
getCost	Set this field to 1 to retrieve the inventory cost of each purchased item. Cost is only a property of purchase invoices (not POs), and only products have a cost (services do not, since services are not taken into inventory). Cost is the sum of purchase price, plus shipping and other costs divided between invoice items. If set to 1, API will return "unitCost" and "costTotal" for each document row, and "cost" for the whole document.	0 or 1
searchAttributeName	Name of attribute to search from. Both "searchAttributeName" and "searchAttributeValue" have to be specified. Error 1030 will be returned if value is an array.	string
searchAttributeValue	Attribute value to search for. Error 1030 will be returned if value is an array.	string
orderBy	'documentID', 'dateAndNumber', 'supplierName', or 'lastChanged'. By default 'dateAndNumber'	string
orderByDir	Sort direction: 'asc' (ascending order) or 'desc' (descending order). By default, items are sorted in descending order.	string
recordsOnPage	Number of records API should return. By default 20, at most 100.	integer
pageNo	API returns at most recordsOnPage items at a time. To retrieve the next recordsOnPage items, send a new request with pageNo incremented by one. By default, API returns "page 1".	integer
changedSince	Retrieve only items that have been added or modified since the specified timestamp. Use it to keep a local database in sync with Erply.	Integer (Unix timestamp)
getAddedTimestamp	If set to 1, API will also return each document's creation timestamp (field `added`).	0 or 1

Response

Field name Type Description

id integer Purchase document ID

type

string

If your account has configuration setting use_purchase_waybills enabled, then the possible types are:

PRCORDER	Purchase order
PRCINVOICE	Purchase invoice-waybill. Takes items into stock and affects your Accounts Payable. A Purchase Invoice-Waybill is equivalent to making a Purchase Waybill (PRCWAYBILL), followed by a Purchase Invoice (PRCINVOICEONLY)
CASHPRCINVOICE	Purchase receipt. Same as previous.
PRCRETURN	Purchase return. Functionally same as a purchase invoice-waybill, but it is used to return goods back to supplier. On a purchase return, amounts are negative.
PRCWAYBILL	Purchase waybill. This document ONLY takes items into stock, and does not generate an obligation to pay.
PRCINVOICEONLY	Purchase invoice. This is usually a follow-up for the items that have arrived earlier with an invoice-waybill. For example, the supplier may send shipments continuously throughout the month, and bill the customer once a month, for all the shipments sent. The invoice does not affect stock, but it affects your Accounts Payable.

If the setting is not enabled, possible types are:

PRCORDER	Purchase order
PRCINVOICE	Purchase invoice-waybill. Takes items into stock and affects your Accounts Payable. (Here, we can also call it a "purchase invoice" for short, since there are no other similar document types.)
CASHPRCINVOICE	Purchase receipt. Same as previous.
PRCRETURN	Purchase return. Functionally same as a purchase invoice-waybill, but it is used to return goods back to supplier.
COMMITMENT	Purchase commitment.
COMMITMENT_DEDUCTION	Commitment Deduction.
AVAILABILITY_CHANGE	Availability Change.

status

string

The possible statuses are:

PENDING	Document not confirmed.
PARTIALLY_RECEIVED	Purchase order (PRCORDER) only. Document has been confirmed and its status is "partially received". This status can be set manually, but typically this means that the PO has been associated with a purchase invoice, or purchase invoices, but not all ordered items have been received yet.
RECEIVED	Purchase order (PRCORDER) only. Document is confirmed and its status is "received".
READY	Any other confirmed purchase document (for example a purchase invoice or a purchase return) — or a confirmed purchase order that has not been fulfilled yet.

currencyCode string Currency code: EUR, USD.

currencyRate number eg. 1.25543
Exchange rate of the purchase document currency against system's default currency.

warehouseID integer ID of the warehouse

warehouseName string Name of the warehouse

number string Number of purchase document

regnumber string Reg. number of purchase document

date string Format: yyyy-mm-dd. eg. 2010-01-29

inventoryTransactionDate string Format: yyyy-mm-dd. Inventory transaction date.
This is the date on which the document was confirmed and when the items on this document were added into inventory, or removed from inventory. While "document date" can be edited by users at any time, "inventory transaction date" is always set by Erply and cannot be changed.
Inventory Reports and COGS reports are based on the inventory transaction date.

time Time eg. 14:59:00

supplierID integer

supplierName string

supplierGroupID integer ID of supplier's group (see getSupplierGroups).

addressID integer

address string

contactID integer

contactName string

employeeID integer ID of the system employee, who is set as the creator of the invoice/order/etc.

employeeName string

supplierID2 integer

supplierName2 string

stateID integer

paymentDays integer In how many days the purchase document is due.

paid integer 0 or 1

transactionTypeID integer

transportTypeID integer

deliveryTermsID integer

deliveryTermsLocation string

deliveryAddressID integer Address ID that has been selected for deliveries.

triangularTransaction integer 0 or 1

projectID integer

reasonID integer Reason ID. See getReasonCodes.

confirmed integer 0 or 1

referenceNumber string

notes string

ediStatus string Status (Docura integration).

ediText string Text (Docura integration).

documentURL string Document URL (Docura integration).

rounding Decimal, 2 places

netTotal Decimal

vatTotal Decimal

total number =netTotal+vatTotal+rounding

netTotalsByTaxRate

array

List of VAT (tax) rates and purchase document net totals for each rate. Each list element contains the following fields:

Field name	Type	Description
vatrateID	Integer	Tax rate ID, see getVatRates
total	Decimal	Net total

vatTotalsByTaxRate

array

List of VAT (tax) rates and total VAT (tax) amounts for each rate. Each list element contains the following fields:

Field name	Type	Description
vatrateID	Integer	Tax rate ID, see getVatRates
total	Decimal	Total VAT / tax

invoiceLink string URL pointing to a HTML printout version of the document.

This URL is valid only for 24 hours; if you want to send the purchase invoice / PO by e-mail, you must retrieve the contents of this URL and enclose it as an attachment, instead of sending the URL itself.

shipDate string Format: yyyy-mm-dd. eg. 2010-01-29

cost number Total inventory cost of the purchased products. Cost equals invoice net total, less services and non-stock products (since services are not taken into inventory, they can never have cost) + shipping and handling costs.

Cost is always in account's default currency. This field is returned only if you set getCost = 1.

netTotalForAccounting Decimal, 2 places

totalForAccounting Decimal, 2 places

additionalCosts Decimal

additionalCostsCurrencyId integer

additionalCostsCurrencyRate Decimal

additionalCostsDividedBy string Possible values:
AMOUNT - additional costs divided between products by amounts.
PRICE - additional costs divided between products by wholesale price.

baseToDocuments

array

Array of purchase documents that have been made from this document. This element is always present but may be empty if there are no documents.

Array elements have the following attributes:

id - Integer - Purchase Document ID
number - String - Number of purchase document
regnumber - String - Reg. number of purchase document
type - String - Type of purchase document
date - Date (yyyy-mm-dd) - Date of purchase document

baseDocuments

array

Array of source documents. This element is always present but may be empty if there are no source documents.

Array elements have the following attributes:

id - Integer - Purchase Document ID
number - String - Number of purchase document
regnumber - String - Reg. number of purchase document
type - String - Type of purchase document
date - Date (yyyy-mm-dd) - Date of purchase document

jdoc Object Contains data that is saved using the JSON Api. Contents of this field change depending on what is saved into the json field. Output is always given as valid json or null when the field is not set.
Example: {"myValue":"123"}

added integer Unix timestamp. Document creation time. To retrieve this field, please pass input parameter getAddedTimestamp=1.

lastModified Unix timestamp

rows

array

Purchase document rows. Rows are returned only in specific cases (if you searched purchase document by ID or number, or if result set contained just one document, or if you specified getRowsForAllInvoices = 1. Each row (ie. each array element) has the following fields:

Field name	Type	Description
stableRowID	Integer	Stable row ID. ID that will be persisted for the row if the row is the same between saves.
productID	Integer
serviceID	Integer
itemName	String
code	String
code2	String
vatrateID	Integer	ID of VAT rate.
amount	Decimal
price	Decimal	Net price per item
discount	Decimal
deliveryDate	Date	Supplier quoted delivery date. Available only if the feature "Delivery date tracking on sales and purchase orders" is enabled on your account.
unitCost	Decimal	Inventory cost for 1 unit. Cost is always in account's default currency. Returned only if you set `getCost = 1`.
costTotal	Decimal	unitCost multiplied by amount. Returned only if you set `getCost = 1`.
packageID	Integer	Package ID, if the item has been purchased in packages. To retrieve the packages of a particular product, see getProducts, block `"productPackages"`.
amountOfPackages	Decimal	Amount of packages
amountInPackage	Decimal	Amount of products contained in one package
packageType	String	Readable package type name
packageTypeID	Integer	Type ID of the package.
jdoc	Object	Contains data that is saved using the JSON Api. Contents of this field change depending on what is saved into the json field. Output is always given as valid json or null when the field is not set. Example: {"myValue":"123"}
supplierPriceListSupplierCode	String/NULL
supplierPriceListImportCode	String/NULL
supplierPriceListNotes	String/NULL

attributes

array

Additional attributes for the document. Each array element has the following fields:

Field name	Type	Description
attributeName	String	Attribute name
attributeType	String	Attribute type
attributeValue	String	Value of the attribute