Synchronise the companies from the ERP

Prerequisites

• An access token for the HIPE instance

Synchronization Options

1. Recommended: API Synchronization - Real-time updates with validation
2. CSV Import - For bulk initial loads or legacy systems

API

If you want to synchronise your companies from the ERP with your HIPE instance, you will be able to do it by following this process.

1. We search if the company already exists in HIPE, if not we create it.
2. We update the company if it exists based on the retrieved information.

Search the company

To search if the company already exists in HIPE, you will need to make a GET request to the /api/companies?s={"name":{"$contL":"{ EXTERNAL ID }"}}&limit=5 endpoint with URL-encoded.

curl --location 'https://{ YOUR INSTANCE }-hipe.packitoo.com/api/companies?s={"name":{"$contL":"{ EXTERNAL ID }"}}&limit=5'
--header 'X-ACCESS-TOKEN: { YOUR ACCESS TOKEN }'

# Search by name (fallback)
curl --location 'https://{ YOUR INSTANCE }-hipe.packitoo.com/api/companies?s={"name":{"$contL":"Acme"}}&limit=5' \
--header 'X-ACCESS-TOKEN: { YOUR ACCESS TOKEN }'

The response should be a 200 with zero or one company with the same external-id. If you don’t find any company, you can create it.

Create the company

To create a company, you will need to make a POST request to the /api/companies endpoint.

Body parameters:

• name: The name of the company required
• externalId: The id from your ERP
• parentId: The id of the parent company if needed
• customFields: The custom fields to set, see Custom fields

You can found the other parameters in the API reference.

curl --location 'https://{ YOUR INSTANCE }-hipe.packitoo.com/api/companies' \
--header 'Content-Type: application/json' \
--header 'X-ACCESS-TOKEN: { YOUR ACCESS TOKEN }' \
--data '{
    "externalId": "ERP-64000",
    "parentId": "{ PARENT COMPANY ID }",
    "name": "My amazing jam company"
}'

You should get a 201 code with the created company in the response. You can use the id of the company to update it now.

Update the company information

To update the company information, you will need to make a PATCH request to the /api/companies/{ companyId } endpoint. You can refer to the API reference for the parameters.

curl  --request PATCH --location "https://{ YOUR INSTANCE }-hipe.packitoo.com/api/companies/{ COMPANY ID }" \
--header 'X-ACCESS-TOKEN: { YOUR ACCESS TOKEN }' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Updated company name",
    "parentId": "{ PARENT COMPANY ID }",
    "customFields":{
      "myCustomFieldBool":false,
      "myCustomFieldString":"myCustomValue", -- This one is based on the field value for the select
      "myCustomFieldMultiSelect":["myCustomValue","myCustomValue2"],
      "myCustomFieldNumber":10
    }
}'

Archive the company

To archive the company (equivalent to delete but softly), you will need to make a DELETE request to the /api/companies/{ companyId }/archived endpoint API reference.

curl  --request DELETE --location "https://{ YOUR INSTANCE }-hipe.packitoo.com/api/companies/{ COMPANY ID }/archived" \
--header 'X-ACCESS-TOKEN: { YOUR ACCESS TOKEN }' \
--header 'Content-Type: application/json'

This should return a 200 code with the archived company in the response.

CSV Import

If you want to import a CSV file containing the companies based on the external-id, you will need to make a POST request to the /api/imports endpoint.

The parameters are the following:

• type: The type of the import in your case “16” if based on external-id. You can retrieve the other available types here.
• delimiter: The delimiter used in the CSV file. You can retrieve the available delimiters here.
• csv: The CSV file containing the companies.

curl --location 'https://{ YOUR INSTANCE }-hipe.packitoo.com/api/imports' \
--header 'X-ACCESS-TOKEN: { YOUR ACCESS TOKEN }' \
--form 'type="{ TYPE }"' \
--form 'delimiter="{ DELIMITER }"' \
--form 'csv=@"/path/to/file"'

The response should be a 201 with in the body:

{
  "type": "0",
  "status": StatusCode,
  "delimiter": ",",
  "createdById": uuid,
  "fileId": uuid,
  "id": uuid,
  "code": int,
  "dryRun": bool,
  "allowDelete": bool,
  "stats": {},
  "fileArchived": bool,
  "createdAt": datetime,
  "updatedAt": datetime
}

Follow the import progress

You can follow the import progress by making a GET request to the /api/imports/{importId} endpoint.

curl --location 'https://{ YOUR INSTANCE }-hipe.packitoo.com/api/imports/{importId}' \
--header 'X-ACCESS-TOKEN: { YOUR ACCESS TOKEN }'

The response should be a 200 with the following structure:

{
  "type": "0",
  "status": StatusCode,
  "delimiter": ",",
  "createdById": uuid,
  "fileId": uuid,
  "id": uuid,
  "code": int,
  "dryRun": bool,
  "allowDelete": bool,
  "stats": {},
  "fileArchived": bool,
  "createdAt": datetime,
  "updatedAt": datetime
}

The useful status codes are:

Value	Status	Description
1	REQUESTED	The import has been requested but not started.
2	IN_PROGRESS	The import is currently being processed.
3	ABORTED	The import has been cancelled or aborted.
4	SENT	The import result has been notified by email.
7	CRASH	The import has crashed or failed.

You can also go directly on your instance and review the import progress http://{ YOUR INSTANCE}-hipe.packitoo.com/back-office/settings/imports