Domibus Send Data (DSD) ES v2

Version 2.20
January, 2021

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,
'Caserón'=>6099, 'Caseron'=>6099, 'Cortijo'=>599, 'Masia'=>599, 'Masias'=>599, 'Masía'=>599, 'Masías'=>599, 'Finca rustica'=>3699,
'Castillo'=>5699, 'Castillos'=>5699, 'Torre'=>1099, 'Torres'=>1099,'Mansion / palacio'=>5699, 'Palacio'=>5699, 'Palacios'=>5699, 'Pueblo'=>4999, 'Pueblos'=>4999, 'Villa'=>4999, 'Villas'=>4999,

'Duplex'=>2999, 'Bungalow'=>299, 'Triplex'=>2999,
'Oficina'=>1399,
'Local'=>1299, 'Local o nave'=>1299,
'Almacén'=>1599, 'Nave'=>2099, 'Nave industrial'=>2099,
'Garaje'=>2399,
'Trastero'=>2699,
'Terreno'=>4099,
'Edificio'=>1699)

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.
email 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
}