How to integrate SES Hospedajes with your PMS: the web service from the inside

“SES Hospedajes has an API” is a half-truth. It has a SOAP web service designed so management systems can file the traveller report without going into the portal. It works, it is documented and it can be automated end to end. But it looks nothing like a modern REST API, and the decisions you make while integrating it determine whether it holds up in production or gives you grief every night.

This is what we learned building that integration: what you need before writing code, what the service looks like underneath, and the four design decisions that matter.

What you need before writing code

None of this is solved by programming, so it is worth having it sorted first:

What the service looks like underneath

Three traits shape the integration:

1. SOAP, and the XML travels compressed

You do not send JSON: you build an XML with the structure of the report and send it inside a SOAP envelope, compressed. If you come from integrating REST APIs, the first day goes on assembling the envelope and on discovering that an “invalid XML” error can come from one character too many.

2. Each traveller is an independent communication

A report is not a monolithic block: inside the batch there is one comunicacion block per person. This is the service’s best feature and the one most often ignored, because it has two very useful consequences:

• One traveller’s wrong document does not block the registration of the others.
• You can send a partial report with whoever has registered and file the stragglers later, without duplicating the ones already sent.

3. Confirmation is asynchronous

The submission returns a batch number, not a confirmation. The real outcome — a communication code per traveller, or the errors — arrives when you query the batch afterwards. An integration that does not go back and ask does not know whether it is complying.

The four decisions that matter

When to send

The deadline is 24 hours from the start of the stay. Sending as soon as the first traveller registers is tempting but generates a great many partial communications; waiting for the whole party eats the deadline when somebody does not fill the form in.

What works for us is a nightly sweep on the arrival day, with whoever has registered by then, and an hourly run for whatever comes in later: if the missing ones waited for the next night, a 15:00 check-in would be more than 30 hours late. And a “send now” button for the odd case.

What to do with rejections

A rejection is not a bug in your system: it is bad data that has to be corrected and retried. You need to store the error per traveller and have the retry go out on its own once it is corrected, with no manual step. If the operator has to remember to resend, they will forget.

Where to validate

Every validation you can do in the guest’s form saves you a round trip to the Ministry and a manual correction afterwards. DNI check letter, support number, second surname, INE municipality code, a postcode that really exists, relationship for minors. We go through it in the article on SES errors.

Idempotency

Reprocessing happens: a timeout, a deploy at midnight, a manual retry. If your submission identifier is not deterministic, you will end up with duplicate reports or travellers counted twice. The identifier should come from the data (booking + traveller), not from a counter.

The test environment

SES has a test environment, and it is worth setting up before touching production: the Ministry’s errors are cryptic and you learn them by trial. Just two cautions:

1. Make the environment explicit in the code, not a comment. A test submission that ends up in production is a real report filed with the police using fake data.
2. Make sure what you send in testing does not count towards your metrics or towards what you bill a customer.

A warning: this does not apply to all of Spain

Catalonia and the Basque Country have their own system and do not use SES Hospedajes. If your accommodations are there, the integration is a different one — and in Catalonia’s case, there is no automated way to connect. Every other region, Galicia, Madrid, Andalusia, the Balearics and the Canaries included, goes through SES.

The shortcut, if you would rather not build it

Everything above is real work: SOAP, certificates, validations, retries, deltas and a test environment. It makes sense to take it on if traveller registration is your product. If it is not, there is the option of calling a REST API and letting someone else absorb that complexity.

curl -X POST https://api.kinapi.es/v1/checkins \
  -H "ocp-apim-subscription-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "reservationId": "R-2026-0412",
    "listingId": "APT-01",
    "checkInDate": "2026-08-14",
    "checkOutDate": "2026-08-18",
    "numGuests": 2
  }'

From there the guest fills in their already-validated details, signs the contract, and the report goes out to SES on its own. The quickstart covers it in five minutes.