savePurchaseDocument

Create a new purchase invoice, purchase order or purchase return, or update an existing one.

To update document row prices see API call updatePurchaseDocumentRows.

To update additional costs see API call updatePurchaseDocumentAdditionalCosts.
To make savePurchaseDocument calls idempotent, use the "temporaryUUID" field.

Input parameters

Parameter name Description Possible value Required
id ID of existing document. If this parameter is present, then an existing document is updated. integer
warehouseID ID of the warehouse
If omitted, system will associate with the warehouse with the first ID.		 integer
deliveryAddressID Delivery address ID. integer
currencyCode Currency code: EUR, USD. Currency must be present in the system. string yes
no Number to be given to the purchase document. string yes
type If your account has configuration setting use_purchase_waybills enabled, then the possible types are:
PRCORDERPurchase order
PRCINVOICEPurchase 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)
CASHPRCINVOICEPurchase receipt. Same as previous.
PRCRETURNPurchase 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.
PRCWAYBILLPurchase waybill. This document ONLY takes items into stock, and does not generate an obligation to pay.
PRCINVOICEONLYPurchase 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:
PRCORDERPurchase order
PRCINVOICEPurchase 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.)
CASHPRCINVOICEPurchase receipt. Same as previous.
PRCRETURNPurchase return. Functionally same as a purchase invoice-waybill, but it is used to return goods back to supplier.
COMMITMENTPurchase commitment.
COMMITMENT_DEDUCTIONCommitment Deduction.
AVAILABILITY_CHANGEAvailability Change.


By default: PRCINVOICE		 string
date eg. 2010-01-29
If omitted, date of request will be used Format: yyyy-mm-dd.		 string
time eg. 14:59:00
If omitted, time of submission will be used		 Time
confirmInvoice By default 1 0 or 1
supplierID integer yes
addressID integer
contactID integer
employeeID ID of the system employee, who is set as the creator of the invoice/order/etc. integer
stateID Status of the document itself. See getPurchaseDocumentStatuses. integer
currencyRate eg. 1.25543
Exchange rate of the main currency against system's default currency.
If the invoice is in system's default currency, does not have to be specified (but if specified, use 1.0)
If omitted, the current exchange rate stored in the system will be used.		 Decimal
paymentDays eg. 5
In how many days the purchase document is due.		 integer
paid 0 or 1
transactionTypeID Transaction types can be configured in Settings → Purchase transactions (Intrastat) integer
transportTypeID Transport types can be configured in Settings → Transportation types (Intrastat) integer
deliveryTermsID Delivery terms can be configured in Settings → Incoterms integer
deliveryTermsLocation string
triangularTransaction Integer (0 or 1)
projectID integer
reasonID Reason ID. See getReasonCodes. integer
referenceNumber String (50)
baseDocumentIDs Source document IDs, separated by commas, such as: 1,2,3,4,5 string
notes string
ediStatus Status (Docura integration). string
ediText Text (Docura integration). string
documentURL Document URL (Docura integration). string
shipDate ISO date (yyyy-mm-dd)
rounding Decimal, 2 places
netTotalForAccounting Decimal, 2 places
totalForAccounting Decimal, 2 places
*****

Lines (rows) of the purchase document. Send the lines as a flat list, each line defined by the following set of parameters. Replace # with set number (1, 2, 3, ...). For example: productID1, amount1, price1, vatrateID1 for the first invoice row, productID2, amount2, price2, vatrateID2 for the second one and so on.

VAT is calculated automatically, a separate VAT row is not needed. When updating an existing document and the input parameters contain no information about invoice rows, then sytem leaves the existing rows in the database as they are. However, if row definitions are present, then all rows on the document are replaced with new ones.
stableRowID# Stable ID of the invoice row. This will be persisted if the row is the same as previously. Can be used to reference a specific row if it existed previously. Fields that are copied over are limited so saves still require other fields to be present. Only use this when the row is infact the same existing row. integer
productID# ID of the product. Either productID or serviceID can be set, but not both at the same time. Both can be omitted, however - in that case a free-text invoice row is created integer
serviceID# ID of the service integer
itemName# name of the item (use only if you want to override the default product/service name) string
vatrateID# ID of VAT rate. integer yes
amount#

Purchased quantity.

On a Purchase Return, the quantity should be negative.

 number yes
price# Original net price (pre-discount) per item. number yes
discount# Decimal
packageID#

Set this field if you want to indicate that the product is purchased as packages, or that you want to order the product in packages. Use it together with "amountOfPackages#".

Packages are product-specific; a product can have zero or more defined packages. To retrieve a product's packages, call getProducts with input parameter getPackageInfo = 1 and see the block productPackages in the output.

 integer
amountOfPackages#

Amount of packages sold.

If you specify both amount# and amountOfPackages#, they must correspond to each other: amount# must be equal to amountOfPackages# multiplied by the quantity in one package.

However, it is sufficient to specify only one of the two fields; the second one will be calculated automatically.

 Decimal
deliveryDate# Supplier quoted delivery date.

To use this, you should enable the feature "Delivery date tracking on sales and purchase orders" in Erply backend: Settings » Configuration » Inventory and Purchase: Enable Extra Features.		 ISO date (yyyy-mm-dd)
supplierPriceListSupplierCode# string
supplierPriceListImportCode# string
supplierPriceListNotes# string
***** Additional attributes associated with this item.
Attributes must be supplied as a flat list, each attribute defined by the following set of three parameters. Replace # with set number (1, 2, 3, ...).

When updating an existing entry, API will only update the attributes specified in input data and leave all other existing attributes unchanged. To delete an attribute, set its value to 'null' or 'undefined'.
attributeName# Attribute name. Name can only contain the following symbols: A-Z, a-z, 0-9, dash and underscore. string
attributeType# Attribute type, possible types are 'text', 'int' and 'double'. By default 'text'. string
attributeValue# Value of the attribute. Set value to 'null' or 'undefined' to delete an attribute.
'text' attribute can be any string, maximum 255 characters.
'int' must be a signed 32-bit integer.
'double' must be a decimal number.		 string
temporaryUUID Optional id value. Used as custom identification on creating new documents. Can be used as a unique value to identify new document creation requests for duplicate requests prevention. A valid value can contain characters a-z+A-Z+0-9, symbols (. and -) and can be maximum of 128 characters long string

Response

Field name Type Description
invoiceID integer ID of the created (or updated) document
invoiceRegNo string Reg. number of the document (if it was confirmed)
invoiceNo string
invoiceLink string URL pointing to a HTML 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.
net number Net total of the document
vat number Total VAT of the document
total number Document total
rows array
Field nameTypeDescription
rowIDIntegerInvoice row ID. That is a transient value, it changes every time the document is re-saved.
stableRowIDIntegerStable row ID. ID that will be persisted for the row if the row is the same between saves.
productIDIntegerProduct ID.
serviceIDIntegerService ID.
amountDecimalPurchased quantity.