Import API: Use for position synchronization

Value and Control services of Tangl platform have Import API for synchronization of catalogs and their positions from an external source.

Import API allows you to import or update positions to an existing catalog, as well as delete positions from the catalog.

Authorization

Like other points, the synchronization point is secured and requires an access token.

How to set up authorization and get an access token see in the article Organizing Access to the Tangl API.

Sending data

To send the data, the following query must be performed and the required data must be transmitted to be written to or deleted from the catalog:

POST https://value.tangl.cloud/api/import/catalog/json/external

• Transmission format: json
• The following header is passed for authorization:

Authorization: Bearer <BEARER_ACCESS_TOKEN>

The query contains a block to list new or changing positions and a block to delete existing positions.

• Example of a request body:

{
    //Import settings
	"Settings":{
		"CatalogName":"Test"
	},
    //Positions for writing or updating
	"Data":[
      //Properties of the catalog position
	  {
		"Guid":"6e861656-a520-401b-9244-2c5d57fd8724",
		"Code":"1",
		"Name":"Reinforced concrete works",
		"Price":2000,
		"Unit":"100 м3",
        "CurrencyCharCode": "RUB",
	  },
      {
		"Guid":"d733ecd7-d135-4d39-a9f4-eacefd06d820",
		"Code":"1.1",
		"Name":"Wall construction",
		"Price":11000.45,
		"Unit":"100 м3",
        "CurrencyCharCode": "RUB",
	  },
      {
         //Another position in the catalog
      }
	],
    //Positions for removal
    "DeletedData":[
       {
    	"Guid":"d733ecd7-d135-4d39-a9f4-eacefd06d821",
		"Code":"1.2",
		"Name":"Flooring"	  
       }  
    ]
}

• Example of a successful response:

{
 "jobId" : "65577ff4b52b6ee0c326e2ec"
}

The response contains the identifier of the job that is importing the items. This identifier allows you to track the progress and status of the job, as well as request the execution log.

Rules for organizing the list of positions

Since synchronized or new positions are a list and the final view of the directory is a tree, the Tangl platform uses a mechanism to automatically recognize parent and child positions and build them into a tree.

This mechanism is described in the article Rules for organizing the list of catalog positions during synchronization.

ATTENTION!!! At the moment, data is written to a catalog only by its name, but there may be situations when a user is a member of several companies that have catalogs with the same name. In the future, the field of the company identifier, which is present in the access token, will be added to the settings

Import status request

After sending positions and receiving a job ID, you can receive the import status with a point:

GET https://value.tangl.cloud/api/import/catalog/json/external/statusbyjobid/{jobId}

• Request Data:
  • jobId - unique identifier of the import task, is the response of the import point of the catalog from the external system.
• Example of a successful response:

{
    "id": "3e142841-c730-5a29-6536-3a0eeff8b31b",
    "jobId": "65577ff4b52b6ee0c326e2be",
    "rootName": "Catalog",
    "rootId": "ebf6939c-bfa1-4e50-860b-3b3992ac213b",
    "status": "ReportCreated",
    "date": "2023-11-17T15:00:06.544Z",
    "progress": 100,
    "error": null
}

Request import status by rootName

GET https://value.tangl.cloud/api/import/catalog/json/external/statusbyroot/{rootName}

• Request Data:
  • rootName - the name of the catalog created in your company.
• Example of a successful response:

{
    "id": "3e142841-c730-5a29-6536-3a0eeff8b31b",
    "jobId": "65577ff4b52b6ee0c326e2be",
    "rootName": "Catalog",
    "rootId": "ebf6939c-bfa1-4e50-860b-3b3992ac213b",
    "status": "ReportCreated",
    "date": "2023-11-17T15:00:06.544Z",
    "progress": 100,
    "error": null
}

When the export is successfully completed in the response, the Progress field will have a value of 100 and the Error field will be null:

{
    ...
    "progress": 100,
    "error": null
}

Import log request

Once the import is complete, you can request a detailed log of which positions were added successfully, which were updated, which were deleted, and which were ignored.

GET https://value.tangl.cloud/api/import/catalog/json/external/logbyjobid/{jobId}

• Request Data:
  • jobId - unique identifier of the import task, is the response of the import point of the catalog from the external system.
• Example of a successful response:

{
    "InsertedTwigs": [
        {
            "TanglId": "0601fad5-d4d4-4de9-ad68-5803eca1fd64",
            "ExternalId": "df13161e-31ad-4ff1-bfb5-58de56da3074",
            "Code": "2.2.5",
            "Name": "New nested 5",
            "Price": 5.0,
            "CurrencyCharCode": "RUB",
            "Unit": ""
        }
    ],
    "UpdatedTwigs": [
        {
            "TanglId": "cb55283f-9bc9-46ad-bcdf-cd56d2906658",
            "SourceCode": "2.1",
            "UpdatedCode": "2.2",
            "SourceName": "Nested 3",
            "UpdatedName": "Modified 6",
            "SourcePrice": 5.0,
            "UpdatedPrice": 10.0,
            "SourceCurrencyCharCode": "RUB",
            "UpdatedCurrencyCharCode": "USD",
            "SourceUnit": "шт",
            "UpdatedUnit": "м3"
        }
    ],
    "DeletedTwigs": [
        {
            "TanglId": "a7bc15e5-4660-41f1-8e35-0412f597a41c",
            "ExternalId": "f91d8c35-53fe-4a53-c45c-3a060f3e5c30",
            "Code": "1.1",
            "Name": "Nested 1"
        }
    ],
    "IgnoredTwigs": [
        {
            "TanglId": "678f3089-9cf8-4c2c-a0f8-66bf28a8dab3",
            "ExternalId": "2dd103b3-039e-11ee-a27f-00155d6d7629",
            "Code": "2.3",
            "Name": "New nested 5",
            "Price": 5.0,
            "CurrencyCharCode": "RUB",
            "Unit": ""
        }
    ]
}