External IDs in the Bimp API: mapping objects to your system

What an external ID is

An external ID is a link between a Bimp object and its identifier in your system, stored as a source + externalId pair. Because of it, the integration does not have to store Bimp UUIDs: it looks up the Bimp object by its own identifier and creates the link after the first import. Typical examples are a product ID on a website, a user ID in a store, or a marketplace order number.

Link fields:

Field	What it means
source	Identifier of the external system (prom, rozetka, shopify). Case-insensitive: the value is trimmed and converted to lower case
externalId	Identifier of the object in the external system (string)
UUID of the Bimp object	Named in the request according to the resource (see the table below)

For one Bimp object you can store a separate externalId for each source.

Which resources support external IDs

Four resources support external IDs; all paths start with /org2/, and the methods are POST.

Resource	Path	Object UUID parameter	Reference
Products	/org2/nomenclature/api-…ExternalId	nomenclatureUuid	nomenclature
Counterparties	/org2/counterparty/api-…ExternalId	counterpartyUuid	counterparty
Customer orders	/org2/invoiceForCustomerPayment/api-…ExternalId	orderUuid	invoice-for-customer-payment
Sales	/org2/salesInvoice/api-…ExternalId	salesInvoiceUuid	sales-invoice

The full set of paths for each resource is api-saveExternalId, api-readExternalId, api-readByExternalId, api-readExternalIdsList, api-readWithoutExternalId, api-deleteExternalId.

Which methods are available

All six methods work the same way for every resource. Below, <uuidField> is the parameter from the table above.

Method	What it does	Request body	data in the response
api-saveExternalId	Creates or updates a link	<uuidField>, source, externalId (all required)	{"success": true}
api-readExternalId	Returns the object’s external ID for source	<uuidField>, source (required)	{"externalId": "..."} or null
api-readByExternalId	Finds a Bimp object by external ID	source, externalId (required)	Bimp object (see below) or null if there is no link
api-readExternalIdsList	List of links with filters	pagination (required), source, <uuidField>	array of links
api-readWithoutExternalId	Objects without a link for source	pagination, source (required)	array of Bimp objects
api-deleteExternalId	Deletes a link	<uuidField> (required), source	true

pagination looks like {"offset": 0, "count": 100} (maximum count is 100), see Limits, pagination and errors.

What the read methods return, by resource:

Resource	readByExternalId and readExternalIdsList	readWithoutExternalId
Products	readByExternalId: nomenclatureUuid, name; list: nomenclatureUuid, name, source, externalId	nomenclatureUuid, name
Counterparty	readByExternalId: counterpartyUuid, name; list: counterpartyUuid, name, source, externalId	counterpartyUuid, name
Customer order	orderUuid, date, number, source, externalId	orderUuid, number, date, amount, comment, counterpartyName, counterpartyUuid, currency, statusName
Sales	salesInvoiceUuid, date, number, source, externalId	salesInvoiceUuid, number, date, amount, comment, counterpartyName, counterpartyUuid, currency (the list may be fuller)

How to map an order to your system

The typical flow for customer orders looks like this, and for products and counterparties it is identical.

1. For a new order from the store, check whether it already exists in Bimp. Call api-readByExternalId:

   curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readByExternalId \
     -H "access-token: <COMPANY_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"source": "myshop", "externalId": "ORD-10452"}'

   The response {"success": true, "data": null} means the order has not been imported yet.

2. Create the order with the /org2/invoiceForCustomerPayment/api-create method, see the reference.

3. Save the link:

   curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-saveExternalId \
     -H "access-token: <COMPANY_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"orderUuid": "<ORDER_UUID>", "source": "myshop", "externalId": "ORD-10452"}'

   { "success": true, "data": { "success": true } }

4. To find orders not yet mapped to your system, call api-readWithoutExternalId:

   curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readWithoutExternalId \
     -H "access-token: <COMPANY_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"pagination": {"offset": 0, "count": 100}, "source": "myshop"}'

Full scenarios are in Syncing orders with an online store and Syncing the product catalog.

How to delete a link

The api-deleteExternalId method deletes the link for the given source. If source is not passed, all external links of this object are deleted. The method returns true both when the link was deleted and when there was none.

curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-deleteExternalId \
  -H "access-token: <COMPANY_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"nomenclatureUuid": "<NOMENCLATURE_UUID>", "source": "prom"}'