API
Version 67, last updated by barium at 2018-10-10
*Updated the the URL to development server with HTTPS://
API-DOCUMENTATION
CONNECTION INFORMATION FOR DEVELOPMENT SERVER
SERVER URL: https://fsab.bariumlive.com/
SERVER API: https://fsab.bariumlive.com/API/v1.0/
CONNECTION INFORMATION FOR PRODUCTION ENVIRONMENT
SERVER URL: https://www.fastighetsagarnadokument.se
SERVER API: https://www.fastighetsagarnadokument.se/API/v1.0/
IMPORTANT: Note that production environment user accounts are registered by each customer separately at https://www.fastighetsagarnadokument.se.
The API key that we issue to system vendors shall normally be used by all customers of the system vendor and specified in a configuration file or the like.
Keep in mind that the production environment uses HTTPS (SSL). Ensure that the server URL can be entered and changed in your application in a simple way. Different customers may have different server addresses, depending on whether they use the central form service or a local form server.
VERSION
1.0 - Current API version (not modified during the development project)
SYNTAX
<<SERVER URL>>/API/v1.0/<<Resource>>/<<Id>>/<<Selector>>
| Resource | Resource type that you want to reach, for example, form the subject, form or file. |
| Id | (Optional) The system-generated ID or registered identifier for the resource. |
| Selector | (Optional) Selects a specific set of data or underlying resource from the indicated resource. |
| SelectorId | (Optional) Select an item from the specific set of data or the resource identified with the Selector. |
| SubSelector | (Optional) Selects a specific set of data or underlying resource from the SelectorId designated resource. |
DATA FORMAT
All data except binary data is returned in JSON format (http://en.wikipedia.com/wiki/JSON) or XML (output is controlled using parameter format = json or format = xml).
All date fields are returned in format ISO 8601 (http://en.wikipedia.com/wiki/ISO_8601) in coordinated universal time (UTC).
All HTTP POST requests except for file uploads must include the HTTP header "Content-Type" with the value "application/x-www-form-urlencoded".
All HTTP POST parameters except for file uploads must be URL-encoded according to x-www-form-urlencoded (http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1) where non -ASCII characters must be encoded in UTF-8. More information is available on http://en.wikipedia.org/wiki/Percent-encoding
HTTP POST file upload must comply with RFC 1867 (http://www.faqs.org/rfcs/rfc1867.html)
NOTE: You can also post JSON data by setting the Content-Type to "application/json". Note that the character coding then must be in UTF-8 format.
ERROR MESSAGES
Error messages are returned as standard HTTP error messages with an HTTP status code and a response to JSON format:
{Success: false, errorCode: ERROR_CODE, error message: "Error message", errorLogId: "ERROR_LOG_ID" errorData: ERROR_DATA}
ERROR_CODE is standard HTTP status codes (such as 400=Bad request, 404=Not found, 500=Internal server error). ERROR_LOG_ID refers to a logged error message that may contain more information about the error (contact Barium for access to these). The format of ERROR_DATA varies and depends on the error.
GLOSSARY
| Instance | Form case |
| App | Application (The form service is built up of process applications that are used to start, manage, control and store form files) |
| Object | Objects stored in the system, eg completed forms, uploaded files and folders |
DOCUMENTATION SECTION
- API for User Information
- API for Authentication
- API for Form Cases
- API for Form Templates
- API for Company Information
- API for Information Model
- API for Objects in Form Cases
- API for Status and Balance Payment
FORMS AND INFORMATION MODEL FOR PROPERTY INFORMATION
| Form | Reference ID | Type namespace | Description |
| 12B.2 | 12b.2 | 12B2HyreskontraktForLokal | Tenancy agreement |
| 6F | 6f | 6FIndexklausulForLokal | Index clause |
| 7B | 7b | 7BFastighetsskatteklausul | Property tax clause |
Description of data types
| Datatype | Description |
| System.String | String/text based values |
| System.Number | Integer & Float |
| System.Date.Time | Date and time on ISO-8601 in UTC |
| System.Bool | Boolean data (primarily used for checkbox fields). The system accepts the following values as input for True: ["on", "true", true, "1"] The system accepts the following values as input for False: [ "off", "false" false, "0"] NOTE! The system currently stores all Boolean data with the format "on" or "off" internally, which means that boolean values are always returned in this format regardless of how they were received when the object was created / updated. |
| System.Binary | Binary data |
EXAMPLE
The following examples are designed to illustrate how a number of common API calls might look like. All calls except the first requires that you use the HTTP header "Ticket" or send to "Ticket" as query string. Ticket is obtained by the first call to POST /API/v1.0/Authenticate. Please study the documentation section to get a complete description of each API method. Note that the examples below refer to fictitious ID values.
Do not forget to set the HTTP header "Content-Type" to "application / x-www-form-urlencoded" in all HTTP POST requests except for file uploads.
| POST /API/v1.0/Authenticate | Authenticates against the form service by sending a HTTP POST with parameters: APIKey=<<API_KEY>>&Username=<<USER_NAME>>&Password=<<PASSWORD>> | |
| POST /API/v1.0/Apps/Form | Starts a new form case by sending an HTTP POST to the application "Form" according to: POST /API/v1.0/apps/form Check out the DATA FORMAT section which regulates how the HTTP POST calls must be encoded. Populate the form case with data and forms by placing so-called object entries in the Request Body according to the example shown below (for more information on this, see the API for Objects in Form Cases) In the object entry below four objects are created in the form case: Three pure data objects that carry data and one data object that is also linked to the form 7B. Only data objects with the property templateid are shown in the user interface, the others are used only to store data. In this case form 7B, which has fields from all data objects, automatically uses all data from all data objects. This allows one to pre-populate a form case with information on the Customer, Landlord, Property, etc. and allow this information to be shared by all forms in the form case.
| |
| GET /API/v1.0/Instances | Retrieves a list of all started / completed form cases | |
| GET /API/v1.0/Instances/cabda881-8412- 47a8-b48d-158b4de54304 | Retrieves information about form case with Id = cabda881-8412-47a8-b48d-158b4de54304 | |
| GET /API/v1.0/Instances/cabda881-8412-47a8-b48d-158b4de54304/Objects | Retrieves a list of items that are stored in form case with Id = cabda881-8412-47a8-b48d-158b4de54304, such as forms, files, folders | |
| GET /API/v1.0/Objects/4d82ad9b-60db-403c-94eb-b98a15990f1f | Retrieves information about the object (such as form) with ID = 4d82ad9b-60dB-403c-94eb-b98a15990f1f | |
| GET /API/v1.0/Objects/4d82ad9b-60db-403c-94eb-b98a15990f1f/Properties | Retrieves all the properties (such as field values) of the object (form) with ID = 4d82ad9b-60dB-403c-94eb-b98a15990f1f | |
| GET /API/v1.0/Instances/cabda881-8412-47a8-b48d-158b4de54304/PDF | Retrieves (generates) a PDF as a binary stream for form case with Id = 4d82ad9b-60dB-403c-94eb-b98a15990f1f | |
| GET /API/v1.0/Templates | Lists the available forms in the form library including information about each forms category and price. Use /API/v1.0/Types/BlankettKategori/TypeInstances to get a list of all form categories and their structure. | |
| GET /API/v1.0/Types | Lists all the concepts from the form service information model, such as "Customer" and "Rent" |
START/OPEN A FORM CASE FOR EDITING IN WEB BROWSER
1. Authenticate against form service with POST /API/v1.0/Authenticate?webTicket=true to get a webTicket which can then be used when opening the form service in a browser window.
2. Start a form case with POST /API/v1.0/apps/form and obtain a form case ID in the response from the POST call (The property Id).
3. Retrieve ongoing tasks for form case with GET /API/v1.0/Instances/{InstanceId}/Tasks
4. The list in the step (3) will in this case contain the first task. Download this work task ID and use that TaskId in step (5).
5. Start a browser on the user's computer with the following URL (without the API path) to open the case in normal viewing mode with automatic logon: http://{SERVERURL}/tasks/task /{TaskId}?webticket={webTicket}
NOTE! If a display mode suitable for integration in an external application is desired (where certain navigation and buttons to copy, delete and status change issues are hidden), the querystring-parameter navigationmode=external can be added to the URL in step 5 of the format: http://{SERVERURL}/tasks/task/{TaskId}?webticket={webTicket}&navigationmode=external. Note that in this case, end users can not themselves change the status of a case from draft to sharp. Instead, this functionality must be offered by the users system via API call.