API for integratorsv1

GoToCheck handles guest registration with the authorities and the guest-facing online check-in. A PMS or booking engine selling in Spain needs both, and normally does not build them: it is years of work per country, and administrations change their interfaces without notice.

What GoToCheck is not: a PMS. We do not handle rates, availability or payments. If you already have that, we sit beside it.

Everything marked Live has been tested against production. Everything marked Proposed is specified but not built, and its shape may still change. Tell us what you need and we will shape it around your integration — that is easier now than later.

One key per integrator. Long, stable, and revocable at any time.

GET /api/v1/propiedades HTTP/1.1
Host: app.gotocheck.pro
Authorization: Bearer gtc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

No JWT and no expiry: there is no person behind the key signing in, there is a server calling every few minutes with no screen to re-enter a password on. Same approach Channex takes with user-api-key.

A key is bound to one host account and sees only that account's data. Missing header, or a revoked key: 401.

Rate limits

60 calls per minute and 600 per hour, per key. Over that, 429 with a Retry-After header in seconds — and it tells you when a slot actually frees up, not a round number:

{ "error": "Has llegado al límite de 60 llamadas por minuto.
            Vuelve a intentarlo en 34 segundos." }

The limit is per key: one integrator going over does not take service away from another. If your integration needs more, say so and we raise it — it is a number, not a technical ceiling.

Every id takes the form cm-123 or sin-123, and is used verbatim in the URL:

GET /api/v1/reservas/sin-946612
GET /api/v1/reservas/cm-4471/registro
GET /api/v1/reservas?propiedad_id=sin-156

The prefix is not decoration. Hosts with a channel manager and hosts without one are stored in two separate data models, each numbering independently, so reservation 1 exists in both at once. An id without a prefix is rejected with 400 rather than returning the neighbouring reservation.

The tipo field (cm / sin_cm) remains in every response. The prefix does not replace it, it just makes it usable in a URL.

Or use your own reference

Anywhere a reservation id is accepted, ext- plus your own external_id works too — on reads as well as writes:

GET    /api/v1/reservas/ext-MY-REF-001
GET    /api/v1/reservas/ext-MY-REF-001/registro
PATCH  /api/v1/reservas/ext-MY-REF-001
DELETE /api/v1/reservas/ext-MY-REF-001

That means you never have to store our identifiers at all: create a reservation with your reference and keep using it.

Creating, updating and cancelling reservations is available. Your key needs write access enabled — a key handed over for reading does not start creating reservations just because the method exists.

{ "external_id": "MY-REF-001",
  "propiedad_id": "sin-156",
  "fecha_entrada": "2026-10-01",
  "fecha_salida": "2026-10-05",
  "numero_huespedes": 2,
  "huesped": { "nombre": "Jane Doe", "email": "jane@…",
               "telefono": "+34600111222", "idioma": "en" } }

PATCH /api/v1/reservas/sin-946612
PATCH /api/v1/reservas/ext-MY-REF-001

{ "cancelada": "cm-1042",
  "parte": { "estado": "anulado",
             "motivo": "Cancelled before arrival (03/10/2026): the stay did not take place.",
             "lotes": ["0a1b2c3d-…"] } }

So you don't have to ask every few minutes whether the guest has checked in. We tell you when it happens.

checkin.completado · parte.enviado · parte.confirmado · parte.error · parte.anulado

parte.confirmado arrives when SES validates the submission, carrying the communication code (see section 5). parte.enviado arrives first, when the file goes out: it does not mean SES has accepted it.

How it arrives

POST https://your-system.example.com/gotocheck
Content-Type: application/json
X-GoToCheck-Evento: parte.enviado
X-GoToCheck-Evento-Id: 3f2b8c1e-6a4d-4e0b-9c7a-1d5e8f0a2b3c
X-GoToCheck-Firma: 9f8a7c…

{ "evento_id": "3f2b8c1e-6a4d-4e0b-9c7a-1d5e8f0a2b3c",
  "evento": "parte.enviado",
  "ocurrido_en": "2026-09-24T21:00:13+02:00",
  "reserva": "sin-946612",
  "registro": { "checkin": { … }, "parte_autoridades": { … } } }

registro is exactly what GET /reservas/{id}/registro returns. On purpose: if the API said one thing and the notification another, neither would be any use settling a dispute.

Event ID and duplicates

Every notification carries an evento_id, in the body and in the X-GoToCheck-Evento-Id header. It is unique and stays the same across retries: store it and discard anything you have already processed. A retry is the same request byte for byte — same body, same timestamp, same signature.

Each event is sent once per submission. A submission that is rejected, corrected and sent again is a new one: you will receive parte.error for the first and a fresh parte.enviado (and later parte.confirmado) for the second, each with its own evento_id. The same error repeated does not notify twice.

The signature

X-GoToCheck-Firma is an HMAC-SHA256 of the whole body, using the secret handed to you along with the URL. Verify it before acting on a notification: guessing your URL is then not enough to forge one.

Retries

If your server does not answer with a 2xx, we retry six times with growing gaps: 1 minute, 5, 15, 1 hour, 6 hours, 1 day. After that we stop trying — but we keep the record of what was attempted and what your server answered.

The one that matters is parte.error: if an administration rejects a submission and nobody hears about it, the host pays the fine. That is why this is a queue and not a direct call — your server may well be down at the exact moment a submission goes out.

You do not need this API to start. GoToCheck can read reservations straight from the host's own channel manager account, read-only. Today: Channex, Lodgify, Smoobu, Guesty, Hostaway, Hospitable, Cloudbeds, MangoBeds, Little Hotelier and others.

Channex, in detail

Using the host's key, we make three calls, all reads:

GET /api/v1/properties     validate the credential, list properties
GET /api/v1/bookings       filter[arrival_date][gte], filter[property_id]

No POST, no PUT, no DELETE.

Channex does not offer read-only keys — a key carries the same powers as the user who creates it. What you can do is create a separate key limited to the properties you choose (untick "Access to all properties") and revoke it at any time with "Withdraw". That is what we recommend: you never share the credential your own system uses, and we only ever read with it.

Latency today

2 minUpper bound, polling interval

Covers

New · Modified · CancelledNot new bookings only

Cancellations detected by

cancelled, canceled, declined, expired, failed

Getting to seconds Live

You register a webhook in your own Channex account pointing at an endpoint of ours, and reservations arrive in seconds instead of up to two minutes. Ask us for your URL — it carries a token tied to your account.

Three things worth knowing about it:

• You register it, not us. Creating a webhook is a write (POST /webhooks), and if we did it with your key it would stop being true that we only read. So the URL is yours to paste into your Channex panel.
• It does not disturb your own integration. Channex webhooks are broadcast, unlike the feed, which is consumed — your PMS keeps receiving its own events exactly as before. We have this running in our own account, where our webhook coexists with eleven belonging to a revenue management tool.
• It is an accelerator, not a dependency. We never send an ack, and if the endpoint is down nothing is lost: the two-minute poll picks it up anyway.

A property can be configured with its authority system set to test. The full cycle works — check-in, form, submission generation, status — and nothing leaves for the real administration.

channel manager  →  GoToCheck  →  online check-in  →  submission in test mode

Not small print. It is the first thing to be clear about.

The system itself confirms this: the authority credentials belong to the host, per property. Submissions go out signed with theirs, never with the integrator's. Technically the integrator is never the declaring party, and that is a line worth not crossing.

Listed on purpose, so nothing comes as a surprise.

1. A submission is voided as a whole batch. SES has no way to remove one guest from a filed submission: it is voided and sent again corrected.
2. Test mode is a simulation, not an SES sandbox. See section 9: it validates the path end to end, but SES itself does not check your files. Their pre-production environment can be enabled instead if that is what you need.

What used to be on this list and no longer is: the SES communication code was not stored, so /registro could say a submission went out but not hand you the receipt — it does now, with a confirmado state and its own webhook. Cancelling did not void a filed submission — it does now, before arrival or on the arrival day, and there is an endpoint to void one yourself. GET /reservas capped at 200 rows with no way past it — it paginates by cursor now. There was no rate limiting — there is, per key, with the numbers in section 3. And writing reservations and outbound webhooks were both only specified — both are built.