Version 2.20
January, 2021
Table of Contents
INTRODUCTION
The Domibus Send Data System is organized around REST. Domibus SDS uses predictable, resource-oriented URLs, and uses HTTP POST requests. We support cross-origin resource sharing, allowing you to recieve data securely with our SDS from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is sent by all our requests.
This section of the documentation is geared towards developers.
REST Request - how to send a request including the domains, paths, and HTTP Method conventions we use. Also includes how to authenticate yourself.
REST Response - we have a standard response wrapped, which is detailed here. We also talk about HTTP status codes and how we return error messages.
REQUESTS
Using SSL
All requests should be called over SSL. You must use SSL when working with non-public data such as customer accounts and private information. Make sure your client/server technology supports SSL.
Data Types
Array Inputs
JSON Payloads Data is returned using JSON (Javascript Object Notation). JSON is the only format we support. It's a lightweight serialization language that is compatible with many different programming languages and technologies. JSON is syntactically correct JavaScript code, meaning you can use the Javascript eval() function to parse it.
HTTP Methods
All requests will be sent via HTTP POST, since we will be sending/creating one or more resources. However, some operation require other HTTP methods:
HTTP Method | Description |
GET | Reads resources via URL, often with query string criteria |
POST | Create a new resource. |
PATCH | Updates an existing resource. |
Authentication
Your Partner Token is provided by Domibus. Token API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.
Authentication to your API/Webhook is performed via HTTP Shared User Token.
Each POST request needs to contain information that identifies you as the client and the agent/office.
The following variables will be included in all POST calls:
- Authorization: Bearer which is the Partner Token sent in the header. (using the parameter Authorization: Bearer TOKEN)
- agent_id which is sent as a POST variable. (Given by you in order to identify the user/agent sending real estate information)
- agent_token which is sent as a POST variable. (Given by you in order to identify the user/agent sending real estate information)
POST Request parameters V.2 (coded)
Parameter | Value | Description |
agent_id | String | The identifier of the user sending data. |
agent_token | String | The token identifier of the user sending data. |
reference | Int | The reference of the property. |
prospect | Bool | Is it a prospect? |
operacion_type | Int | The type of operation being offered. Values: ('for sale'=>1,'for rent'=>2) |
price | Int | The price of the property. |
property_type | Int | The type of property being offered. Values ES: ('Loft'=>3299, 'Estudio'=>3099, 'Estudios'=>3099, 'Apartamentos'=>2799, 'Apartamento'=>2799, 'Piso'=>3399, 'Pisos'=>3399, 'Atico'=>4799, 'Aticos'=>4799, 'Bajo'=>3499, 'Buhardilla'=>4699, 'plantas bajas'=>3499, 'Planta baja'=>3499, 'Plantas bajas'=>3499, 'Vivienda'=>3399, 'Chalet'=>499,'chalet'=>499,'Chalet adosado'=>199,'Chalet pareado'=>999, 'Casa'=>399,'Casa de pueblo'=>6299,'Casa o chalet independiente'=>399,'Casa adosada'=>399,'Casa rural'=>11699,'Casa terrera'=>6599, 'Duplex'=>2999, 'Bungalow'=>299, 'Triplex'=>2999, |
country | String | The country code where the property is located. Values: ('Spain'=>'es','France'=>'fr','Italy'=>'it') |
provence | Int | The provence where the property is located. Values: localities_es.json |
locality | Int | The locality where the property is located. Values: localities_es.json |
street | String | The street where the property is located. |
street_number | String | The street number where the property is located. |
lat | Float | The lattude where the property is located. |
lng | Float | The longitude where the property is located. |
bedroom | Int | The number of rooms on the property. |
wc | Int | The number of bathrooms on the property. |
m2 | Int | The area of the property. |
m2_terrain | Int | The area of the terrain of property. |
origin | String | The origin website of the property. |
url | String | The url of the property. |
description | String | The description of the property. |
tags | String List | The list of features on the property. |
handicapped_acc | Bool | There is handicapped access. |
water | Bool | There is water. |
central_air | Bool | There is central air. |
air_conditioning | Bool | There is air conditioning. |
alarm | Bool | There is alarm. |
fire_alarm | Bool | There is fire alarm. |
theft_tlarm | Bool | There is theft tlarm. |
separate_apartment | Bool | There is separate apartment. |
trees | Bool | There is trees. |
builtin_cabinet | Bool | There is builtin cabinet. |
elevator | Bool | There is elevator. |
balcony | Bool | There is balcony. |
bar | Bool | There is bar. |
barbecue | Bool | There is barbecue. |
attic | Bool | There is attic. |
safe | Bool | There is safe. |
heating | Bool | There is heating. |
central_heating | Bool | There is central heating. |
shopping_mall | Bool | There is shopping mall. |
fireplace | Bool | There is fireplace. |
kitchen_type | Int | Kitchen type. Values: ('office'=>1,'independent'=>2) |
conservation | Int | Conservation. Values ES: ('Para reformar'=>5, 'De origen'=>10, 'Reformar Parcialmente'=>15, 'Entrar a vivir'=>20, 'Buen estado'=>30, 'Semireformado'=>40, 'Reformado'=>50, 'Seminuevo'=>60, 'Nuevo'=>70,'Obra Nueva'=>80,'En construcción'=>90, 'En proyecto'=>100) |
community_fees_incl | Bool | It is community fees included. |
water_tank | Bool | There is water tank. |
water_softener | Bool | There is water softener. |
pantry | Bool | There is pantry. |
diaphanous | Bool | Itis diaphanous. |
gallery | Bool | There is gallery. |
double_garage | Bool | There is double garage. |
city_gas | Bool | There is city gas. |
gym | Bool | There is gym. |
playroom | Bool | There is playroom. |
hydromassage | Bool | There is hydromassage. |
piped_music | Bool | There is piped music. |
jacuzzi | Bool | There is jacuzzi. |
garden | Bool | There is garden. |
orientation_key | Int | Orientation key. Value: ('None'=>0, 'North'=>1, 'South'=>2, 'East'=>3, 'West'=>4, 'Northwest'=>5, 'Southwest'=>6, 'East, West'=>7, 'Southeast'=>8, 'North, South'=>9, 'Northeast'=>10) |
laundry | Bool | There is laundry. |
telephone_l | Bool | There is telephone line. |
luminous | Bool | It is luminous. |
electricity | Bool | There is electricity. |
viewpoint | Bool | There is viewpoint. |
forklift | Bool | There is forklift. |
furniture | Bool | There is furniture. |
portholes | Bool | There is portholes. |
option_to_buy | Bool | There is option to buy. |
courtyard | Bool | There is courtyard. |
pergola | Bool | There is pergola. |
com_swimming_pool | Bool | There is community swimming pool. |
priv_swimming_pool | Bool | There is private swimming pool. |
floor | Int | Floor number. Value: ('Floor 0'=>0,'Floor 2'=>2,'Floor 3'=>3,'Floor 4'=>4,'Floor 5'=>5,...) |
garage | Bool | There is garage. |
preinst_air_conditioning | Bool | There is preinstallation for air conditioning. |
preinst_piped_music | Bool | There is preinstallation for piped music. |
beachfront | Bool | There is beachfront. |
automatic_doors | Bool | There is automatic doors. |
armored_door | Bool | There is armored door. |
automatic_irrigation | Bool | There is automatic irrigation. |
satellite | Bool | There is satellite. |
sauna | Bool | There is sauna. |
solarium | Bool | There is solarium. |
basement | Bool | There is basement. |
priv_tennis_court | Bool | There is private tennis court. |
com_tennis_court | Bool | There is community tennis court. |
terrace | Bool | There is terrace. |
glazed_terrace | Bool | There is glazed terrace. |
all_exterior | Bool | Itis all exterior. |
storage_room | Bool | There is storage room. |
three_phase | Bool | There is three phase power. |
tv | Bool | There is tv. |
fencing | Bool | There is fencing. |
changing_room | Bool | There is changing room. |
video_intercom | Bool | There is video intercom. |
sea_views | Bool | There is sea views. |
children_area | Bool | There is children area. |
status | Int | The prospect status of the property. Values: ('Pending'=>1,'Contacted'=>2,'Prospected'=>3,'Do Not Contact'=>4,'Not Available'=>5) |
first_name | String | The prospect first name of the property. |
last_name | String | The prospect last name of the property. |
phone | String | The prospect phone of the property. |
phone_alt | String | The prospect phone alternative of the property. |
String | The prospect email of the property. | |
observations | String | The prospect observations of the property. |
RESPONSE
Response Formats
All responses must be returned using JSON. JSON is a lightweight serialization language that is compatible with many different languages. JSON is syntactically correct JavaScript code, meaning you can use the Javascript eval() function to parse it.
HTTP Status Codes
Standard HTTP status codes must be used to indicate success or failure of the calls. Like with most topics, Wikipedia has good resources on HTTP Statuses, but here are the basics of what we will return:
HTTP Code | Message | Description |
200 | OK | The request was processed and returned successfully. Nothing was changed. |
201 | Created | The new resource was created successfully |
400 | Bad Request | Problem with the request, such as a missing, invalid or type mismatched parameter |
401 | Unauthorized | The request did not have valid authorization credentials |
403 | Forbidden | Private data you are not allowed to access. |
404 | Not Found | Your URL is wrong, or the requested resource doesn't exist |
429 | Too Many Requests | You've hit a rate limit. |
500 | Server Error | We call this the "crap code" error. Basically we've got a problem on our side. If this persists please contact support. We log and review all errors but your help often helps us fix it quicker. |
503 | Service Unavailable | Our API is down. Please try again. We work hard to make this rare. |
The non-20x status codes above correspond with an error of one type or another.
Errors
Errors are communicated to the client in the payload of the response.
Errors in the Response Payload
The standard response payload can contain errors. This will give more finely grained details about specific what caused the error or errors, which should allow you to respond appropriately. This might include displaying validation messages to your users, or changing the request at runtime.
Example:
{ "code": "rest_no_route", "message": "No route was found matching the URL and request method", "status": 404 }
Error Type Definition
The errors have the following data definition:
Name | Type | Description | ||
code | String | Error code. Unique string identifying the type of error. See the table below for a list of possible error codes. (Always returned) | ||
message | String | Localized user readable message describing the error. (This will be shown to the end user) | ||
status | Int | The HTTP code. |
Response Payload
Each API response is wrapped in a standard payload that contains the results of the call, plus some additional useful information and metadata.
Name | Type | Description | ||
code | String | Determines the code of the message. | ||
message | String | An explanatory description about the response. (This will be shown to the end user) | ||
status | Int | The HTTP code. |
Here's an example of a response:
{ "code": "ok", "message": "All good", "status": 200 }