Contracts

The cycle has two halves. First you define what the contract says — the legal articles, in a template, and the rules of the place, in a house rules set — and choose which combination each property or each booking uses. Then, once the party signs, Kinapi generates the signed contract for that booking and you can download it. All over the API.

A contract is two pieces

The document your guest signs is built from two things that change for different reasons. The legal articles (subject of the contract, liability, governing law) are much the same across your whole portfolio; the house rules change from one property to the next — the villa with a pool does not share them with the city-centre flat.

That is why they are two separate resources: templates under /contract-templates hold the articles, and sets under /house-rules hold the rules. They are combined when each contract is generated, so M templates and N rule sets give you all M × N combinations with nothing duplicated. House rules used to live inside the template: changing a single rule for one apartment meant duplicating the entire template — legal articles included — and then keeping the same legal text in several copies that drift apart on their own.

Why several templates

One account can run accommodations with different legal conditions — an apartment block and a country house do not always sign the same thing. Each template is created once and assigned by id to as many properties as use it (contractTemplateId in /properties). A property with none assigned uses the one marked isDefault for the tenant.

If the only difference between two properties is the rules, you do not need a second template: create another house rules set and assign that instead. Templates only multiply when the legal articles change.

The template object

{
  "id": "8a2e1f0c-…",
  "name": "Premium villas",
  "isDefault": true,
  "bodyMode": "clauses",
  "showOwnerInfo": true,
  "showOwnerDocument": true,
  "showPropertyInfo": true,
  "houseRules": [
    { "es": "No se permiten fiestas ni eventos.", "en": "No parties or events." }
  ],
  "legalClauses": [
    { "es": "El huésped se compromete a respetar el aforo máximo indicado.", "en": "…" }
  ],
  "createdAt": "2026-07-01T09:00:00.000Z",
  "updatedAt": "2026-07-19T10:00:00.000Z"
}

Each clause is bilingual: es is required, en optional (the generated contract always carries both languages — if en is missing, that clause appears in Spanish only).

The template’s houseRules field is the older model and is kept for compatibility: it is only printed when the booking resolves to no house rules set. On a fresh setup, leave the field alone and write the rules in their own resource.

Pasting a contract you already have

If your contract is already written, there is no need to chop it into clauses. Set bodyMode: "document" and send the whole text in body, one entry per language.

curl -X PATCH https://api.kinapi.es/api/v1/contract-templates/8a2e1f0c-…   -H "ocp-apim-subscription-key: YOUR_API_KEY"   -H "content-type: application/json"   -d '{
    "bodyMode": "document",
    "body": {
      "es": "# CONTRATO DE ARRENDAMIENTO

## Artículo 1. Objeto
Este contrato regula el **uso turístico**…",
      "nl": "# HUUROVEREENKOMST

## Artikel 1. Voorwerp
Deze overeenkomst regelt het **toeristisch gebruik**…"
    }
  }'

The accepted markup is deliberately small, because anything accepted has to be drawable in the PDF: # ## ### for chapter, article and sub-section headings; - and 1. for lists; **bold** and *italic*. There are no tables, images, links or multi-level numbering: an “Article 3.2” is written as a heading.

List numbering is recalculated at print time, so you can write every item as 1. and they will come out 1, 2, 3. Inserting an article in the middle does not force you to renumber the rest.

In document mode the text you paste usually carries its own rules inside it, so the rules of the older model — those written inside the template or inside the property — are not appended. A house rules set is printed, in its own section after the body, whenever the booking resolves to one: its own, the property’s or the tenant default. That is exactly the “articles × rules” combination the split exists to allow.

The contract is issued in the booking’s language, and that comes from a chain of three: the locale you send in POST /checkins, failing that the communicationLocale of the accommodation, and failing that Spanish. It is the same chain that decides the guest form and the emails they receive: one setting governs all three, so you can never invite someone in one language and have them sign in another.

With contractTemplateId in that same call you can pick a different template per booking, if you prefer one per language rather than a single multilingual document.

showOwnerInfo, showOwnerDocument and showPropertyInfo control which sections of the PDF appear — not which data is used (that always comes from the assigned property and owner). For instance, to avoid revealing the owner’s tax number on the contract the guest signs, leave showOwnerInfo at true but set showOwnerDocument to false.

Which template a contract uses

From most specific to most general, the first one that exists wins:

1. The booking’s template (contractTemplateId on the check-in).
2. The property’s template (contractTemplateId on the property).
3. The tenant default (isDefault).
4. Kinapi’s standard clauses, for an account that has not created any template yet.

The signed contract arrives by email

When the party finishes signing, the PDF goes out by email to every one of the people who signed it, attached and carrying the accommodation's branding. There is nothing to switch on or ask for: it happens whenever the signer left an email address. The download link keeps working exactly as before — this is an addition, it replaces nothing.

It goes out as one email per person, not one with everybody in the To field. The guests on a booking are separate people, and putting them together in the header hands each one's address to all the others, which none of them agreed to.

List templates

curl https://api.kinapi.es/api/v1/contract-templates \
  -H "ocp-apim-subscription-key: YOUR_API_KEY"

Create a template

curl -X POST https://api.kinapi.es/api/v1/contract-templates \
  -H "ocp-apim-subscription-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "name": "Premium villas", "isDefault": true }'

Read a template

Update a template

Partial update: only the fields you send change. To edit clauses, send the whole houseRules or legalClauses list — it replaces the previous one, it does not merge clause by clause.

curl -X PATCH https://api.kinapi.es/api/v1/contract-templates/8a2e1f0c-… \
  -H "ocp-apim-subscription-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "houseRules": [{ "es": "No se admiten mascotas.", "en": "No pets." }] }'

Delete a template

Properties and bookings that had it assigned fall back to the tenant default (or to Kinapi’s standard clauses if there is no default either). The orphaned contractTemplateId stays stored — nobody cleans the reference up — but when the contract is generated no other assigned template is looked for: it goes straight to the default, even for a booking on a property that has one of its own.

Preview a template

Returns a sample PDF built with this template — clauses or document, depending on its bodyMode — over fictional data. It lets you check how the contract turns out while you are assembling it over the API, without creating a real check-in or waiting for anyone to sign.

It accepts ?locale= so you can see it in a given booking’s language. It applies exactly the same rules as the real contract: what you see here is what your guests will sign.

It shows the template on its own: its articles and, in clauses mode, the rules written inside it. Assigned house rules sets are not combined here, because that combination depends on the property and the booking, and a preview has neither.

curl -OJ -X POST "https://api.kinapi.es/api/v1/contract-templates/8a2e1f0c-…/preview?locale=nl" \
  -H "ocp-apim-subscription-key: YOUR_API_KEY"

House rules

A house rules set is a document of its own, a sibling of the contract template rather than a section inside it. You create and edit sets in the House rules area of the dashboard or over the API at /house-rules, and they are combined with the legal articles when each contract is generated.

A set is written in one of two ways, the same two the contract body offers: clauses (a bilingual list, rule by rule) or document (the text already written out, one per language, with the same markup as a pasted contract). The clauses are kept when you switch to document mode: going back never costs you work already done.

The house rules object

{
  "id": "c41b90a7-…",
  "name": "Villas with a pool",
  "isDefault": false,
  "bodyMode": "clauses",
  "clauses": [
    { "es": "La piscina cierra a las 22:00.", "en": "The pool closes at 22:00." },
    { "es": "No se admiten mascotas.", "en": "No pets allowed." }
  ],
  "hasText": true,
  "createdAt": "2026-08-01T09:00:00.000Z",
  "updatedAt": "2026-08-12T10:00:00.000Z"
}

In document mode the object also carries body, one entry per language, and clauses stays there as a backup. hasText is a computed field: it tells you whether the set has actual text in the mode it is written in.

Which rules a contract prints

From most specific to most general, the first one with actual text wins:

1. The booking’s set (houseRulesId on the check-in).
2. The property’s set (assigned from the dashboard, on the property itself).
3. The tenant default set (isDefault).
4. The rules of the older model: those written inside the property if it has any, and otherwise those inside the contract template.
5. Kinapi’s standard house rules, for an account that has not created any template yet.

An id that no longer exists does not break the chain: if you delete a set an old booking still referenced, that contract moves down one step instead of ending up with no rules. The same goes for a set that exists but is empty. And a template whose rules list you emptied on purpose prints no rules section at all: emptying it is an instruction, not a gap.

The rules are printed in their own section, NORMAS DE LA CASA / HOUSE RULES, right before the legal conditions. In clauses mode they come out numbered and bilingual; in document mode, in the booking’s language with Spanish underneath, just like the contract body.

With the template in document mode the last two steps never get printed: the text you pasted already carries its own rules, so only the first three add a section — a set from the booking, from the property, or the tenant default.

Assigning a set to a booking

With houseRulesId in POST /checkins you choose, in the same call that creates the booking, which articles and which rules make up the contract about to be signed — without needing a template for every crossing of the two axes.

curl -X POST https://api.kinapi.es/api/v1/checkins \
  -H "ocp-apim-subscription-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "reservationId": "R-2026-0412",
    "listingId": "ALJ-3F9K2P",
    "confirmationCode": "HMXK4L",
    "checkInDate": "2026-09-01",
    "checkOutDate": "2026-09-08",
    "numGuests": 4,
    "contractTemplateId": "8a2e1f0c-…",
    "houseRulesId": "c41b90a7-…"
  }'

You can also change it later with PATCH /checkins/{reservationId}. An empty string unassigns the booking’s set and hands control back to the property. A contract that is already signed is never regenerated — it keeps the rules it was signed with, its timestamp and its immutable copy — so the change only affects what gets signed from then on.

Each property’s set is assigned from the dashboard, on the property itself: that is configuration you set once and leave alone, whereas the booking is what your PMS decides call by call.

List house rules sets

Returns { "results": [...] } with every set in the tenant, ordered by name.

curl https://api.kinapi.es/api/v1/house-rules \
  -H "ocp-apim-subscription-key: YOUR_API_KEY"

Create a house rules set

curl -X POST https://api.kinapi.es/api/v1/house-rules \
  -H "ocp-apim-subscription-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Villas with a pool",
    "clauses": [
      { "es": "La piscina cierra a las 22:00.", "en": "The pool closes at 22:00." }
    ]
  }'

It answers 201 with the new set, or 200 if you sent an id and it was therefore an update. Keep the id: it is what you send later as houseRulesId.

Read a house rules set

Returns the whole set, clauses included even in document mode. 404 if the id does not belong to this tenant.

Update a house rules set

Partial update: only the fields you send change. The clauses list is sent whole and replaces the previous one; body is merged per language, so sending only Dutch does not wipe the Spanish already written — and an empty string deletes that language, which is how you remove a translation.

curl -X PATCH https://api.kinapi.es/api/v1/house-rules/c41b90a7-… \
  -H "ocp-apim-subscription-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "isDefault": true, "clauses": [{ "es": "No se admiten mascotas.", "en": "No pets allowed." }] }'

Delete a house rules set

It can be deleted even while properties or bookings reference it: those ids are left orphaned and, when the contract is generated, resolution moves to the next step of the precedence. No old booking ends up without rules, and no PDF fails to generate.

Download the signed contract

Returns the final PDF of a booking’s contract: two columns — the booking’s language and Spanish — with each guest’s signature embedded and a closing evidence record page (date and time of each signature, IP, device and the SHA-256 hash of each signature image).

curl -OJ https://api.kinapi.es/api/v1/checkins/R-2026-0412/contract \
  -H "ocp-apim-subscription-key: YOUR_API_KEY"

It answers 404 until the party has completed the signing (check contract.signed on the check-in to know when it is available).

What the evidence guarantees

Every completed contract automatically produces a three-layer trail:

• Immutable copy (WORM): the exact PDF and its timestamp are archived in storage with a 3-year retention policy: they cannot be overwritten or deleted before it expires.
• RFC 3161 timestamp: the PDF’s SHA-256 hash is timestamped by an external timestamping authority. When the token arrives we check that it stamps that hash and answers our nonce; only then does it count. Any third party can verify it with openssl ts (below).
• Append-only log: document hash, timestamp token and, per signer, IP + device + time + the hash of their signature.

Reading and verifying the evidence

The evidence record of every signed contract — document hash, timestamp and signers — is available over the API, and the timestamp downloads exactly as the authority issued it: an RFC 3161 TimeStampResp in DER (extension .tsr).

Returns the timestamp as binary (application/timestamp-reply). 404 with no_timestamp if the record has no timestamp yet.

curl -OJ https://api.kinapi.es/api/v1/checkins/R-2026-0412/evidence/EVIDENCE_ID/token \
  -H "ocp-apim-subscription-key: YOUR_API_KEY"

# What it stamps, and when
openssl ts -reply -in token.tsr -text

# That it stamps THIS PDF and the authority's signature is valid
openssl ts -verify -digest $(shasum -a 256 contract.pdf | cut -d' ' -f1) \
  -in token.tsr -CAfile /etc/ssl/cert.pem

Traveller report (the document you must keep)

Not to be confused with the contract: the traveller entry report is the document RD 933/2021 requires you to keep and produce on request. With no parameters it returns a ZIP with each guest’s report; with ?guestId=, that person’s PDF.

curl -OJ "https://api.kinapi.es/api/v1/checkins/R-2026-0412/parte" \
  -H "ocp-apim-subscription-key: YOUR_API_KEY"