# Správca nájmov API

> Signed server-to-server API for partner integrations: sign-up invitations with prefilled onboarding.

The complete contract — schemas, examples, error codes and the request-signing guide with a worked example and code in Node.js, Python, PHP and shell — is the OpenAPI document. Read it before calling the API.

- [OpenAPI 3.1 document](https://api.spravcanajmov.sk/openapi.json): authoritative and machine-readable; the signing guide is in `info.description`
- [Human-readable reference](https://api.spravcanajmov.sk/docs)

## Essentials

- Server-to-server only. The key id (`snk_…`) and secret (`snsk_…`) are issued by the operator; the secret never goes to a browser, an app or a log.
- Every `/v1` request is signed: RFC 9421 HTTP Message Signatures with `alg="hmac-sha256"`, covering `"@method" "@target-uri" "content-digest"` with `created`, `keyid` and a fresh `nonce`, plus an RFC 9530 `Content-Digest: sha-256=:…:` header (also for an empty body). `created` must be within 300 seconds of the server clock; a nonce is accepted once.
- `POST /v1/invitations` requires an `Idempotency-Key` header; retry with the same key (and a new signature) after timeouts or 5xx.
- Errors are `application/problem+json` with a stable `code`; rate-limited responses carry `Retry-After`.
- There are no webhooks. Read an invitation on demand; do not poll on a timer.
- Prefill accepts only the documented fields (profile name, workspace, first property's address and unit). Rent, tenants and listing data are refused.

## Operations

- `GET /v1/ping` — Test the connection: Verifies your signature and key and returns your client. Creates nothing and sends nothing; it counts towards the rate limit.
- `POST /v1/invitations` — Create an invitation: Creates a single-use sign-up link for one e-mail address, with optional prefill. No account is created and no e-mail is sent: deliver `signupUrl` yourself. Requires `Idempotency-Key`; see Idempotency.
- `GET /v1/invitations/{invitationId}` — Read an invitation: Returns one of your invitations with its current status. Read it on demand, when you need to show progress; there is no need to poll.