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:

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.

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

jdoc Attach extra information to the purchase document, in JSON format.

To ensure interoperability, only certain JSON properties, defined by Erply, are allowed. The contents of the field are validated using a JSON schema, and the schema is globally the same for all Erply accounts. Thus this field is best suited for standard applications that get used on many accounts.

The general pattern is that each application, integration or workflow stores its data under its own top-level object (a namespace). All custom properties added by Brazil POS are under BrazilPOS.*, for example.

API clients that modify existing documents and add data to JSON must take care to preserve the data created by other applications, too.

This is the same data that can be retrieved and saved using standalone calls in JSON API. string

*****

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

rowJDoc# Attach extra information to the purchase document row, in JSON format.

To ensure interoperability, only certain JSON properties, defined by Erply, are allowed. The contents of the field are validated using a JSON schema, and the schema is globally the same for all Erply accounts. Thus this field is best suited for standard applications that get used on many accounts.

The general pattern is that each application, integration or workflow stores its data under its own top-level object (a namespace). All custom properties added by Brazil POS are under BrazilPOS.*, for example.

API clients that modify existing documents and add data to JSON must take care to preserve the data created by other applications, too.

This is the same data that can be retrieved and saved using standalone calls in JSON API. 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 name	Type	Description
rowID	Integer	Invoice row ID. That is a transient value, it changes every time the document is re-saved.
stableRowID	Integer	Stable row ID. ID that will be persisted for the row if the row is the same between saves.
productID	Integer	Product ID.
serviceID	Integer	Service ID.
amount	Decimal	Purchased quantity.