Web services
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
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.
NetServer has many service endpoints to support the entire SuperOffice platform.
Supported protocols
SuperOffice NetServer supports two distinct web services protocols:
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
Note
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
Note
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.
Note
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.
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
Note
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)
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 Single:
Read more about: SOAP Services.
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.