Siteshop Integration Cloud – JSON Web Services V3

Data can be sent to Integration Cloud using our JSON Web Service API.
Below you will find the description on how that API works.

Import

The Import endpoint is an API endpoint, used for inserting and updating data into SuperOffice. The endpoint works as a “upsert”, where the API user does not need to consider if the object already exists, as long as the keys are controlled, this is automatically handled.

Request

The request is a POST call, that carries a payload and the necessary headers for the web service to understand the call.

Endpoint

https://ws.siteshop.eu/SicImportREST/sicapi/v3/Import

Headers

Datatype	Select one from a the list below
IntegrationId	Unique id for the customer’s specific integration

Authorization

The service uses a Bearer Token with JWT method. Use Postmand or your favorite variant to test the auth, most of tools like this have a UI option for configuring Bearer Token auth.
To generate the JWT, refer to the document sent separately “Sic_Import_REST_Authenticator_V3.docx”.

Body

The body should be a JSON formatted request, containing one or more of the same type datatype (Compan/Person/etc.)

Example for sending a single Company, with a few extra fields:

{
  "Company":[
    {
      "IntegrationId": "17PS01010001",
      "CompUserKey01": "Key123",
      "Name": "Siteshop ApS",
      "CVR": "21252832",
      "CompUserCheck01": true,
      "CompUserNum01": 42,
      "CompUserDec01": 150.49,
      "IntegrationIdCheck": "17PS01010001"
    }
  ]
}

Example for sending multiple Companies:

{
  "Company":[
    {
      "IntegrationId": "17PS01010001",
      "Name": "Siteshop ApS",
      "CompUserKey01": "Key123",
      "IntegrationIdCheck": "17PS01010001"
    },
    {
      "IntegrationId": "17PS01010001",
      "Name": "Lego ApS",
      "CompUserKey01": "4280",
      "IntegrationIdCheck": "17PS01010001"
    }
  ]
}

Sending Documents

It’s possible to include documents, such as .pdf, .xlsx, .txt, and much more.
This is done by setting the Datatype header and JSON object name to “Document”. For this two special fields, “File” and “Name” are required.

Name: Is the name the document will have once it is in CRM, usually the original filename recommended.
File: Is the filecontent encoded as Base64.

It is possible to update a Document object, without including the file, for example when updating a description of the object.
However, if Name exists, File must as well, and vice versa.

Multiple files in the same call is supported, however, the Name must be unique across every object. If two Documents should have the same Name in CRM, they must be sent in separate calls. This is to ensure that a Document File and Document Object is never mixed up.

Example for sending a single Document request:

{
  "Document":[
    {
      "IntegrationId": "17PS01010001",
      "DocuUserKey01": "Docu_01",
      "Name": "Dummy.txt",
      "File": "VGhpcyBpcyBhIGR1bW15IHRleHQgZmlsZQ0KDQpXaXRoIG5ldyBsaW5lcw0K",
      "IntegrationIdCheck": "17PS01010001"
    }
  ]
}

Additional information

It’s not possible to send mulitple different datatype elements in the same call
Full list of supported fields can be found here. Fields marked as mandatory must be included in the JSON payload

Response

The response will consist of an HTTP Status Code and a response content. The content will carry additional information, either for error reporting or other details.
Responses might look like this:

Only properties that have data, are ever show. So in the first screenshot, “details” is hidden, as no relevant information is there. Here are the names of all potential properties currently supported:

message
details
errorCode

There are several options for how the service might respond, depending on the particular error. It is generally recommended to examine the response content, to get more details, particularly in an error response. A few common response status codes include:

HTTP Status	Cause
200 Ok	The request was handled normally
400 Bad Request	The request was not valid, perhaps a header is missing or payload data is malformed
401 Unauthorized	The request was not authorized
404 Not Found	The IntegrationId might be incorrect

Datatypes

Appointment
Company
CompanyInterest
Document
Person
PersonInterest
PriceList
ProjectMember
Product
Project
Relation
Sale
NormalTable01
RelationTable01
NormalTable02
RelationTable02
NormalTable03
RelationTable03
NormalTable04
RelationTable04
NormalTable05
RelationTable05

Search

The Search endpoint is an API endpoint, for exporting data out of SuperOffice for use in arbitrary other system. Ranging from ERP, custom applications, Power BI analysis, this endpoint is used for a wide variety of tasks.

Request

The request is a POST call, requiring headers.

Endpoint

https://ws.siteshop.eu/SicImportREST/sicapi/v3/Search

Headers

Datatype	Select one from a the list below
IntegrationId	Unique id for the customer’s specific integration
SearchName	Name of the Search, these can be customized to retrieve data based on the specific needs. Eg. Companies, Persons, CompanyInterests, … The SearchNames are provided by Siteshop
SearchParameter	The parameter the Search should use to restrict which objects to return

SearchParameter

The SearchParameter is formated as a series of brackets, amount depending on what operator is used. A SearchParameter looks as follows:

[FieldName][Operator][Value]

FieldName: Name of the field to be queried
- Examples: personId, UpdatedDate, ShouldExport, and so on.
- The FieldName is case sensitive.
- If the FieldName is not recognized, the SearchParameter will be ignored.
- Any field in the response, is able to be queried, however mind that querying some fields may produce full table scans, consult with Siteshop before making changes.
Operator: What sort of operation should be done on the field. If the Operator is not recognized, the SearchParameter will be ignored. The following Operators are valid, however be mindful of types:
- =
- <>
- >
- <
- >=
- <=
- In – Value for this Operator is a comma separated list, like 1,2,3
- Inside – Value for this Operator has an extra [] at the end, so for example
  [SaleDate][Inside][2024-01-01][2024-12-31]
- Like – Value for this Operator is much like SQL Like, for example Site%, %ApS, %Invoice%
Value: Which value should be considered
- Examples: 5, Siteshop, 2025-01-01, and so on.
- Value should never exceed 500 characters

Several separators are supported, using the pipe ( | ) symbol, for example
[LastUpdated][>][2025-01-01]|[AssociateName][=][ph]
This would give a list of all companies (assuming it is a Company Search) updated after 2025-01-01 and the Associate is ph.

Since pipe is a separator, and not an explicit and/or we have also built support for an explicit or keyword, since separator usually works like and. Example of or in use looks like:

[RevenueLastYear][>][100]OR[RevenueThisYes][>][100]

This would produce a list of all companies that follow either one of the SearchParameters.

Important: The OR keyword internally performs a separate Search for each OR separation, making this an expensive query, use mindfully.
The results of all the Searches are merged, with duplicate results being ignored, for example when a company fulfills both SearchParameters. Ignoring duplicate results can be turned of by Siteshop, should that be necessary

{
  "Company-ExternalCall": [
    {
    "ContactId": 2,
    "Name": "Siteshop ApS",
    "CreatedDate": "2012-04-27T14:01:21",
    "CreatedByName": "",
    "UpdatedDate": "2023-08-29T12:53:49",
    "UpdatedByName": "APP",
    "CompUserKey01": "Key123"
    }
  ]
}

Additional info

Usual Datatypes

Since Search is very free form, many datatype are in theory possible, but here are the more popular ones used. This is mostly used for logging and debugging purposes.

Appointment
Company
CompanyInterest
Document
Person
PersonInterest
PriceList
ProjectMember
Product
Project
Relation
Sale

Postet i Uncategorized

Siteshop

Certifiseret