Web services - SuperOffice

When you are calling a web service, you usually don’t have direct access to the database. The objective of the NetServer web services is to provide a simple yet powerful API to access SuperOffice CRM functionality. The web services let you work with the database without having to know the details of how data is stored inside the database. The service layer presents a high-level API where all the hard work of language decoding, security checks, database selects, and joining tables are handled for you. A single service call will represent many database queries and contain business logic, user-preference checking, and default handling. All SuperOffice CRM Online applications depend on NetServer web services for database access.

NetServer web services

NetServer has many API layers to access SuperOffice data, with web services at the top of the API stack. Each SuperOffice installation exposes web services for all clients, including SuperOffice Web, SuperOffice Mobile, and partner application clients. Each web service NetServer Architecture

Endpoints concept

A service endpoint is primarily a method exposed by the NetServer to manipulate the data or enhance the presentation of the data in the SuperOffice database. SuperOffice.Services vs. web services diagram

SuperOffice.Services vs. web services diagram

NetServer has many service endpoints to support the entire SuperOffice platform. NetServer web services endpoint listing

Supported protocols

SuperOffice NetServer supports two distinct web services protocols:

REST (reference), two distinct flavors:
- RESTful (reference)
- HTTP RPC Agents (reference)
SOAP (reference)

The SOAP APIs use Windows Communication Foundation service models for communication and are considered legacy. The RESTful APIs use Microsoft AspNet WebApi for communication, and come in two flavors:

RESTful endpoints
HTTP RPC Agent endpoints

RESTful endpoints

RESTful endpoints are entity endpoints that:

get data using an HTTP GET request
modify data using HTTP PUT or PATCH
create data using HTTP POST and
delete data using HTTP DELETE.

Example GET sale request:

GET https://{superoffice_url}/api/v1/sale/3
Authorization: {type} {credential}
Accept: application/json

HTTP RPC Agents

HTTP RPC Agent endpoints are structured identical to the SOAP endpoints and implement the Service Agent pattern. Unlike SOAP, which uses XML body content to transport messages, HTTP RPC Agents use URL query string parameters and JSON body content.

Service agents endpoints represent a specific business area, such as Appointment, Project or Sale. An agent fragment exposes a set of method endpoints, typically for inserting, retrieving, updating, and deleting data. Each method on the agent corresponds to one HTTP POST request. Example GetAppointmentEntity endpoint method:

POST https://{superoffice_url}/api/v1/Agents/Appointment/GetAppointmentEntity?appointmentEntityId=4
Authorization: {type} {credential}
Accept: application/json

All HTTP RPC Agent requests are POST requests.

Authentication and Authorization

Every request needs a form of credential to verify ones identity. Credentials are passed to service APIs using headers.

RESTful headers

You must provide one of the following types of credential.

BASIC authentication: Base64 Encode SuperOffice username:password
SOTICKET authentication. Pass the SuperOffice ticket (7T:abc123==) without any encoding.
BEARER authentication. Pass along an access token (7A:abc123==) from SuperID.
NEGOTIATE / NTLM authentication. Initiates an Active Directory user authentication.

Auth type	Example	Onsite	Online
No header		x	x
Basic	YWrtMdo=	x
SOTicket	7T:xyz123abc==	x	x
Bearer	8A:xyz123abc==	x	x
Negotiate		x

No Authorize header on a request means that you either:

have IIS configured to handle identity and uses your current Active Directory user, or
included an X-XSRF-TOKEN header to prove that you have access to a logged-in session

You must explicitly enable the authentication methods that you want to use in the web.config file.

Basic

This Authorization header is a key entry of “Basic ”, and a value equal to a base64 encoded representation of the user name, plus a colon, and password.

// conceptual:
Authorization: Basic username:password

// actual:
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Note the space following the word Basic. The username:password text must not be passed in clear text and must be base64 encoded. It is shown here as such for demonstration purposes only.

Basic is not allowed in Online, since all usernames and passwords must flow through SuperID to get a bearer access token.

Bearer

This Authorization header used in CRM Online is obtained using OAuth 2.0 or OpenID Connect.

Authorization: Bearer 8A:Cust12345.Aaq+TbrrXsV...truncated for brevity

Read more about OAuth authorization or OpenID Connect authentication in the Authentication pages. While not common, it is possible for onsite installations to use a Bearer token. This only happens when an access_token is obtained via the UserAgent.GetCurrentToken method.

SOTicket

An SOTicket Authorization header credential is used:

by onsite installation to pass current user credentials to applications hosted in a web panel (forbidden in CRM Onsite due to security reasons)
by CRM Online and onsite installations performing back-channel communications with a system user.

When a web page is running in the context of a SuperOffice web panel, and web panel is configured to pass the usec template variable, the current user’s SoCredential.Ticket credential is sent as a query string parameters to the web application. In that case, the application can use the Authentication header value “SOTicket ” plus the ticket string to request additional API data. Once again, notice the space following SOTicket.

The use of the usec template variable is forbidden in online environments. If you need to use the usec variable for debugging or other purposes, it should only be done in a secure, onsite installation where access is restricted to authorized personnel. If you have already used the usec variable in an online environment, it will only return an empty string from v11.5.

When used in online, the SOTicket header must accompany with the SO-AppToken header, and the SO-AppToken value must be the application secret (OAuth client_secret).

Authorization: SoTicket 7A:adasd098098sdfs0df8KJHSKh230...123dsa==
SO-AppToken: qw123f4c56770bc278017796cd16bd11

In this case, do not convert a Ticket to base64 because the ticket value is already base64 encoded.

X-XSRF-TOKEN

When requests are received without an Authorization header, the API will try authorize the current user’s SuperOffice session. SuperOffice pages contain a hidden INPUT field XSRF_TOKEN, which contains a random value identifying the current session. You must add an X-XSRF-TOKEN header with the random value from the input field. To avoid 3rd-party pages calling the API - piggy-backing off the current session, the API requires that a special HTTP header X-XSRF-TOKEN is added to each requests. The XSRF-TOKEN is also stored in a cookie for convenience. HTTP libraries like AXIOS will automatically pick up the XSRF-TOKEN cookie from the browser and add the X-XSRF-TOKEN header to your HTTP requests. The following snippet will return HTTP error 401 Unauthorized.

GET /api/v1/Contact/2
Accept: application/json

Whereas the following snippet will work, and use the current user’s session to read the data.

GET /api/v1/Contact/2
Accept: application/json
X-XSRF-TOKEN: abc1234

SOAP headers

Each service method the SOAP documentation contains the following two headers:

ApplicationToken
Credentials

The application token is only used in CRM Online, and is reserved for application identifiers, an OAuth client_secret value. The Credentials element must always be populated with the current users Ticket credential. This is set automatically when using the SuperOffice.NetServer.Services nuget package, but are manually set by custom proxies.

<ApplicationToken>1234567-1234-9876</ApplicationToken>
<Credentials>
  <Ticket>7T:1234abcxyzExample==</Appointment:Ticket>
</Credentials>

REST web service resources

Read more about: RESTful API
Read more about: Agent API

Here you can find OpenAPI / Swagger files for available for download for each REST flavor. They are also available for download at the bottom of each page link above, respectively.

Nuget package

There is one nuget package for .NET developers. This package exposes the same Agent API as the SOAP proxy, making it an easy transition for applications using the SOAP proxy: SuperOffice.WebApi (HTTP RPC Agent)

reference)

SOAP web service resources

WSDL files for all versioned endpoints are available for download in the reference section, or as individual files on each endpoint reference page. Download All: Download all WSDLs

Download Single: Download all WSDLs

Nuget package

There is one nuget package for .NET developers: SuperOffice.NetServer.Services (SOAP)

View API reference.

Restricted agents

Not all agents are available in SuperOffice CRM Online. Access must be requested specifically when an app is registered.

Agent Name	Availability
CRMScriptAgent	available upon request
EMailAgent	restricted
ErpSyncAgent	available with ERPSync connectors
MessagingAgent	restricted
ReplicationAgent	restricted
UserAgent	restricted
WebhookAgent	available upon request

Required web service license

Access to the web services is included in your Development Tools subscription.

​NetServer web services

​Endpoints concept

​Supported protocols

​RESTful endpoints

​HTTP RPC Agents

​Authentication and Authorization

​RESTful headers

​Basic

​Bearer

​SOTicket

​X-XSRF-TOKEN

​SOAP headers

​REST web service resources

​Nuget package

​SOAP web service resources

​Nuget package

​Restricted agents

​Required web service license

NetServer web services

Endpoints concept

Supported protocols

RESTful endpoints

HTTP RPC Agents

Authentication and Authorization

RESTful headers

Basic

Bearer

SOTicket

X-XSRF-TOKEN

SOAP headers

REST web service resources

Nuget package

SOAP web service resources

Nuget package

Restricted agents

Required web service license