Partner API
Partner API is part of ERPLY Books API that makes it possible to integrate ERPLY Books by using Books API in a way that you store your own ID values in ERPLY Books. Then you don’t have to store Books ID values and can basically let ERPLY Books take care of updating values when you send your own ID.
For example you have invoice with id 82738732. You send it to Books by stating partnerDocumentId = 82738732. You just have to read if Books gives you error or not. If not then invoice is created in Books. Then let’s say it is updated tomorrow – without any check you again just send it to Books by stating partnerDocumentId = 82738732. As you use Partner API then Books knows that this invoice exists and updates it and does not create new one.
Partner API has following options:
- PartnerCustomerId
- PartnerSupplierId
- PartnerDocumentId
- PartnerArticleId
- PartnerAccountId
- PartnerTaxRateId
By sending information via Partner API you are treated with partner type PARTNER_API. If anyone else starts sending information via API then they must use the same id values as you are or connect with ERPLY Books ID values – because for example when you have X for receivables account and another party that wants to use API has Y for receivables account then as both of you are treated as PARTNER_API then X is not equal to Y and it cannot find unique key for the account. For shorter explanation if you have more than one source where invoices come from then you must be sure that all those sources use the same partner id’s.
Partner API rules:
- GLOBAL_API_USE_PARTNER_API
- You must enable this to use partner API features
- GLOBAL_API_AGGREGATE_DOCUMENTS
- If enabled ERPLY Books aggregates document rows – by grouping articles and projects
- GLOBAL_API_UPDATE_SUPPLIERS
- When sending customer object with invoice then it automatically updates customer information (applies also to payer – if payer object is available)
- GLOBAL_API_UPDATE_CUSTOMERS
- When sending customer object with invoice then it automatically updates customer information (applies also to payer – if payer object is available)
- GLOBAL_API_DO_NOT_UPDATE_SUPPLIERS
- GLOBAL_API_DO_NOT_UPDATE_CUSTOMERS
- GLOBAL_API_DO_NOT_UPDATE_PAYMENTS
- GLOBAL_API_ROUND_INVOICE_TOTALS
- With this you can send also invoice totals (sumWithVat, sumNoVat) and Books calculates if there is any difference with calculated sums from invoice rows and actual totals and creates rounding automatically.
Difference between ordinary “Invoice”
API documentation for Partner API is the same as with ordinary invoices. Only difference is that the url is “invoices/partner” not “invoices”. Also remember to add partnerDocumentId element. But with Partner API you have following attributes:
- Invoice.partnerDocumentId (String)
- Invoice.projectNames (String array) – if present then tries to find projects with the same name. If cannot find then adds new project automatically
- [“Project1”, “Project2”]
- Projects – if present then no other project fields are used
- [23982, 439832]
- Invoice.connectedDocuments – with this you can connect various documents with each other. For example connecting sales order with its invoice. Field:
- id (Long) – leave empty
- parentDocumentId (Long) – leave empty
- baseDocumentId (Long) – leave empty
- partnerParentDocumentId (String) – fill with your id
- partnerBaseDocumentId (String) – fill with your id
- Invoice.rows.partnerTaxRateId (String)
- Invoice.rows.partnerTaxRateName (String)
- Invoice.rows.partnerArticleId (String)
- Invoice.payer (CustomerInfo) – with this you can add payer. The same data structure as with customer
Invoice.attributes: List of APIAttributeInfoV2
| PARAMETER NAME | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| id | long | ||
| transactionEntryId | long | ||
| value | String | ||
| name | String |  | |
| dateFrom | Date | ||
| dateTo | Date | ||
| decimalValue | BigDecimal | ||
| projectId | long | ||
| alternativeValue | String | ||
| alternativeValue2 | String | ||
| alternativeValue3 | String | ||
| alternativeValue4 | String | ||
| alternativeValue5 | String | ||
| alternativeValue6 | String | ||
| alternativeValue7 | String | ||
| alternativeValue8 | String | ||
| alternativeValue9 | String |
How to make sure system runs automatically without problems?
How to update API token (default token lifetime is 1 year)
NB: this must be approved by ERPLY Books support. Send request to support@erplybooks.com.
Call POST /settings/update_token
It will return new token.
Securing API with your IP address
Under API settings you can set IP addresses for managing API calls.
Sending error messages via API
Global name = GLOBAL_API_SEND_ERROR_MESSAGE
Value = email title
altValue = who gets the error message