Dokumentacja API dla partnerów

Działające Partner API v1

Endpointy REST są dostępne pod adresem https://rentumi.pl/v1. Indywidualny klucz produkcyjny lub testowy przekazujemy po aktywacji partnera. Standardowa publikacja jest bezpłatna i nie ma limitu liczby ofert.

Prześlij

Wyślij ofertę przez JSON API albo paczkę XML na FTP.

Zweryfikuj

Rentumi waliduje pola, prawa do publikacji i kompletność kontaktu.

Synchronizuj

Zmiany i wycofania są nanoszone na podstawie external_id.

Zakres wersji v1

Importujemy wyłącznie ogłoszenia długoterminowego wynajmu mieszkań, domów i pokoi. Kontakt zainteresowanego trafia bezpośrednio do osoby lub firmy wskazanej w ofercie.

Tworzenie i aktualizacja ofert
Wycofanie lub czasowe ukrycie oferty
Zdjęcia przekazywane jako publiczne adresy HTTPS
Import pełny oraz przyrostowy
Raport walidacji dla każdej oferty
Izolacja danych każdego partnera

Wybierz sposób importu ofert

Nie musisz przebudowywać swojego systemu pod jeden format. Dobieramy metodę do możliwości technicznych partnera, częstotliwości zmian i liczby ofert. REST API jest najbardziej elastyczne, ale nie jest jedyną opcją.

Rekomendowane

REST API

Najlepsze do aktualizacji w czasie rzeczywistym. System partnera wysyła utworzenie, zmianę lub wycofanie konkretnej oferty.

Najprostszy start

Feed HTTPS: XML lub JSON

Rentumi cyklicznie pobiera plik z chronionego albo publicznego adresu URL. Dobre rozwiązanie, gdy CRM generuje gotowy eksport.

Import paczkowy

SFTP / FTP

Pełne lub przyrostowe paczki z ofertami i zdjęciami trafiają do osobnego katalogu partnera i są przetwarzane automatycznie.

Bez zmiany CRM

Istniejący format CRM

Możemy przygotować mapowanie obecnego eksportu, np. ASARI, Oferty.net lub uzgodnionego schematu własnego.

Możliwy jest również model hybrydowy — np. pierwszy pełny import przez plik, a późniejsze zmiany przez REST API. Konkretny wariant potwierdzamy po otrzymaniu przykładowych danych bez danych wrażliwych.

Uwierzytelnianie

Każde żądanie wymaga tokenu Bearer przypisanego do partnera i środowiska. Token należy przechowywać wyłącznie po stronie serwera. Nie wolno umieszczać go w aplikacji klienckiej, repozytorium ani przesyłać w parametrach URL.

Nagłówki żądania

Authorization: Bearer {partner_token}
Content-Type: application/json
Idempotency-Key: {unikalny_klucz_operacji}

Endpointy REST

Bazowy adres produkcyjny to https://rentumi.pl. Wszystkie odpowiedzi mają format JSON i zawierają nagłówek X-Request-Id ułatwiający obsługę techniczną. Pełny, maszynowy kontrakt jest dostępny jako OpenAPI 3.1 JSON.

GET

/v1/health

Publiczny test dostępności API. Nie wymaga tokenu.

GET

/v1/listings?limit=50&cursor=...

Zwraca stronicowaną listę ofert należących wyłącznie do uwierzytelnionego partnera.

PUT

/v1/listings/{external_id}

Tworzy albo zastępuje pełny stan oferty (upsert). Wielokrotne wysłanie tego samego rekordu nie tworzy duplikatu.

GET

/v1/listings/{external_id}

Zwraca aktualny stan publikacji, adres ogłoszenia i ewentualne ostrzeżenia.

DELETE

/v1/listings/{external_id}

Wycofuje ofertę z publikacji. Rekord jest archiwizowany, a nie fizycznie usuwany.

POST

/v1/listings/batch

Przyjmuje do 100 operacji upsert lub delete i zwraca wynik walidacji osobno dla każdej pozycji.

Klucz Idempotency-Key jest opcjonalny dla operacji PUT i DELETE oraz rekomendowany dla paczek. Wynik przechowujemy przez 24 godziny. Ponowienie identycznego żądania zwraca zapisany wynik z nagłówkiem Idempotency-Replayed: true.

Przykładowe żądanie

PUT /v1/listings/CRM-1042
Authorization: Bearer {partner_token}
Content-Type: application/json
Idempotency-Key: oferta-CRM-1042-v1

{
  "external_id": "CRM-1042",
  "transaction": "rent",
  "property_type": "apartment",
  "status": "active",
  "title": "Jasne 2 pokoje blisko centrum",
  "description": "Mieszkanie dostępne od września...",
  "rent_pln": 3200,
  "admin_fee_pln": 650,
  "deposit_pln": 4000,
  "area_m2": 48.5,
  "rooms": 2,
  "floor": 3,
  "total_floors": 6,
  "available_from": "2026-09-01",
  "address": {
    "country": "PL",
    "voivodeship": "mazowieckie",
    "city": "Warszawa",
    "district": "Wola",
    "street": "Prosta",
    "postal_code": "00-838",
    "latitude": 52.2321,
    "longitude": 20.9847
  },
  "contact": {
    "name": "Anna Kowalska",
    "email": "anna@example.pl",
    "phone": "+48 500 600 700"
  },
  "amenities": ["furnished", "balcony", "elevator"],
  "media": [
    {
      "url": "https://partner.pl/images/CRM-1042-1.jpg",
      "sort_order": 1
    }
  ]
}

Odpowiedź 201

HTTP/1.1 201 Created

{
  "id": "7bc41c61-1291-4a6b-9ac4-92fe98f2cde0",
  "external_id": "CRM-1042",
  "status": "active",
  "url": "https://rentumi.pl/wynajem/...",
  "created_at": "2026-08-18T18:42:11Z",
  "warnings": []
}

Model oferty

Pola niewymagane można pominąć albo przekazać jako null. Nie należy wysyłać pustych ciągów znaków zamiast braku wartości.

Pole	Typ	Wymagane	Opis
`external_id`	string	tak	Stały i unikalny identyfikator w systemie partnera, maksymalnie 100 znaków.
`transaction`	enum	tak	W wersji v1 jedyna wartość to `rent`.
`property_type`	enum	tak	`apartment`, `house` albo `room`.
`status`	enum	tak	`active`, `hidden`, `rented` albo `archived`.
`title`	string	tak	Tytuł oferty, od 10 do 120 znaków.
`description`	string	nie	Opis publiczny bez danych śledzących i skryptów HTML.
`rent_pln`	number	tak	Miesięczna kwota najmu w PLN.
`admin_fee_pln`	number	nie	Miesięczny czynsz administracyjny w PLN.
`deposit_pln`	number	nie	Wymagana kaucja w PLN.
`area_m2`	number	tak	Powierzchnia nieruchomości w m².
`rooms`	integer	nie	Liczba pokoi. Dla oferty pokoju można podać dane całego lokalu.
`available_from`	date	nie	Data dostępności w formacie `YYYY-MM-DD`.
`address.city`	string	tak	Miejscowość prezentowana w ofercie.
`contact.phone`	string	tak	Numer osoby uprawnionej do obsługi zapytań dotyczących oferty.
`media`	array	nie	Maksymalnie 30 publicznych adresów HTTPS do plików JPG, PNG lub WebP.

Zasady synchronizacji

Identyfikacja

Rentumi łączy identyfikator partnera z external_id. Identyczny external_id przesłany przez innego partnera jest osobnym rekordem.

Aktualizacja

PUT traktujemy jako pełny stan oferty. Pola pominięte w aktualizacji mogą zostać wyczyszczone, dlatego rekomendujemy przesyłanie kompletnego rekordu.

Wycofanie

DELETE lub status archived usuwa ofertę z publicznych wyników. Ponowne przesłanie statusu active może ją wznowić.

Zdjęcia

Rentumi może skopiować zdjęcia do własnego magazynu. Partner musi utrzymać adresy źródłowe co najmniej do zakończenia importu.

Import pełny

Po wcześniejszym uzgodnieniu brak oferty w pełnym eksporcie może oznaczać jej automatyczne wycofanie.

Ponawianie żądań

Po odpowiedzi 429 respektuj nagłówek Retry-After. Błędy 5xx można ponawiać ze stopniowo zwiększanym odstępem i tym samym Idempotency-Key.

Kody odpowiedzi i błędy

200 / 201Operacja wykonana

400Niepoprawny JSON lub parametry

401Brak lub nieważny token

404Oferta nie istnieje

409Konflikt identyfikatora lub wersji

422Błąd walidacji oferty

429Przekroczony limit żądań

500Błąd po stronie Rentumi

Przykład błędu walidacji

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "validation_error",
    "message": "Oferta nie spełnia wymagań publikacji.",
    "fields": {
      "contact.phone": "Wymagany poprawny numer telefonu.",
      "rent_pln": "Wartość musi być większa lub równa 0."
    }
  },
  "request_id": "req_01J5ZQW9N7AB2K2F9R"
}

Feed XML/JSON oraz SFTP/FTP

Partnerzy korzystający z systemów CRM mogą wystawić cyklicznie pobierany feed HTTPS albo przesyłać pełne i przyrostowe paczki. Obsługę XML, JSON i istniejącego formatu — np. Oferty.net, ASARI albo własnego schematu partnera — potwierdzamy po otrzymaniu przykładowego pliku bez danych wrażliwych.

Minimalny przykład XML

<?xml version="1.0" encoding="UTF-8"?>
<rentumi version="1.0" export="incremental">
  <listing action="upsert">
    <external_id>CRM-1042</external_id>
    <transaction>rent</transaction>
    <property_type>apartment</property_type>
    <status>active</status>
    <title>Jasne 2 pokoje blisko centrum</title>
    <rent_pln>3200</rent_pln>
    <area_m2>48.5</area_m2>
    <city>Warszawa</city>
    <contact_phone>+48 500 600 700</contact_phone>
    <images>
      <image order="1">CRM-1042-1.jpg</image>
    </images>
  </listing>
</rentumi>

Parametry feedu i SFTP/FTP

• feed HTTPS może być zabezpieczony indywidualnymi danymi dostępowymi,
• osobne konto i katalog dla każdego partnera,
• kodowanie UTF-8, plik XML lub JSON opcjonalnie spakowany jako ZIP,
• zdjęcia jako pliki w paczce albo publiczne adresy HTTPS,
• raport przetwarzania wysyłany po zakończeniu importu.

Podaj e-mail — prześlemy dane do API

Wyślemy informacje o środowisku testowym, identyfikatorze partnera i uruchomieniu integracji. W odpowiedzi możemy też dobrać prostszy sposób importu do Twojego systemu.

Zakres wersji v1

Importujemy wyłącznie ogłoszenia długoterminowego wynajmu mieszkań, domów i pokoi. Kontakt zainteresowanego trafia bezpośrednio do osoby lub firmy wskazanej w ofercie.

Tworzenie i aktualizacja ofert

Wycofanie lub czasowe ukrycie oferty

Zdjęcia przekazywane jako publiczne adresy HTTPS

Import pełny oraz przyrostowy

Raport walidacji dla każdej oferty

Izolacja danych każdego partnera

Wybierz sposób importu ofert

Rekomendowane

REST API

Najlepsze do aktualizacji w czasie rzeczywistym. System partnera wysyła utworzenie, zmianę lub wycofanie konkretnej oferty.

Najprostszy start

Feed HTTPS: XML lub JSON

Rentumi cyklicznie pobiera plik z chronionego albo publicznego adresu URL. Dobre rozwiązanie, gdy CRM generuje gotowy eksport.

Import paczkowy

SFTP / FTP

Pełne lub przyrostowe paczki z ofertami i zdjęciami trafiają do osobnego katalogu partnera i są przetwarzane automatycznie.

Bez zmiany CRM

Istniejący format CRM

Możemy przygotować mapowanie obecnego eksportu, np. ASARI, Oferty.net lub uzgodnionego schematu własnego.

PUT /v1/listings/CRM-1042 Authorization: Bearer {partner_token} Content-Type: application/json Idempotency-Key: oferta-CRM-1042-v1 { "external_id": "CRM-1042", "transaction": "rent", "property_type": "apartment", "status": "active", "title": "Jasne 2 pokoje blisko centrum", "description": "Mieszkanie dostępne od września...", "rent_pln": 3200, "admin_fee_pln": 650, "deposit_pln": 4000, "area_m2": 48.5, "rooms": 2, "floor": 3, "total_floors": 6, "available_from": "2026-09-01", "address": { "country": "PL", "voivodeship": "mazowieckie", "city": "Warszawa", "district": "Wola", "street": "Prosta", "postal_code": "00-838", "latitude": 52.2321, "longitude": 20.9847 }, "contact": { "name": "Anna Kowalska", "email": "anna@example.pl", "phone": "+48 500 600 700" }, "amenities": ["furnished", "balcony", "elevator"], "media": [ { "url": "https://partner.pl/images/CRM-1042-1.jpg", "sort_order": 1 } ] }

HTTP/1.1 201 Created { "id": "7bc41c61-1291-4a6b-9ac4-92fe98f2cde0", "external_id": "CRM-1042", "status": "active", "url": "https://rentumi.pl/wynajem/...", "created_at": "2026-08-18T18:42:11Z", "warnings": [] }

Pole

Typ

Wymagane

Opis

external_id

string

tak

Stały i unikalny identyfikator w systemie partnera, maksymalnie 100 znaków.

transaction

enum

tak

W wersji v1 jedyna wartość to rent.

property_type

enum

tak

apartment, house albo room.

status

enum

tak

active, hidden, rented albo archived.

title

string

tak

Tytuł oferty, od 10 do 120 znaków.

description

string

nie

Opis publiczny bez danych śledzących i skryptów HTML.

rent_pln

number

tak

Miesięczna kwota najmu w PLN.

admin_fee_pln

number

nie

Miesięczny czynsz administracyjny w PLN.

deposit_pln

number

nie

Wymagana kaucja w PLN.

area_m2

number

tak

Powierzchnia nieruchomości w m².

rooms

integer

nie

Liczba pokoi. Dla oferty pokoju można podać dane całego lokalu.

available_from

date

nie

Data dostępności w formacie YYYY-MM-DD.

address.city

string

tak

Miejscowość prezentowana w ofercie.

contact.phone

string

tak

Numer osoby uprawnionej do obsługi zapytań dotyczących oferty.

media

array

nie

Maksymalnie 30 publicznych adresów HTTPS do plików JPG, PNG lub WebP.

Kody odpowiedzi i błędy

200 / 201Operacja wykonana

400Niepoprawny JSON lub parametry

401Brak lub nieważny token

404Oferta nie istnieje

409Konflikt identyfikatora lub wersji

422Błąd walidacji oferty

429Przekroczony limit żądań

500Błąd po stronie Rentumi

Przykład błędu walidacji

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "validation_error",
    "message": "Oferta nie spełnia wymagań publikacji.",
    "fields": {
      "contact.phone": "Wymagany poprawny numer telefonu.",
      "rent_pln": "Wartość musi być większa lub równa 0."
    }
  },
  "request_id": "req_01J5ZQW9N7AB2K2F9R"
}

<?xml version="1.0" encoding="UTF-8"?> <rentumi version="1.0" export="incremental"> <listing action="upsert"> <external_id>CRM-1042</external_id> <transaction>rent</transaction> <property_type>apartment</property_type> <status>active</status> <title>Jasne 2 pokoje blisko centrum</title> <rent_pln>3200</rent_pln> <area_m2>48.5</area_m2> <city>Warszawa</city> <contact_phone>+48 500 600 700</contact_phone> <images> <image order="1">CRM-1042-1.jpg</image> </images> </listing> </rentumi>

Podaj e-mail — prześlemy dane do API

Wyślemy informacje o środowisku testowym, identyfikatorze partnera i uruchomieniu integracji. W odpowiedzi możemy też dobrać prostszy sposób importu do Twojego systemu.

Integracja ofert najmu z Rentumi

Działające Partner API v1

Prześlij

Zweryfikuj

Synchronizuj

Zakres wersji v1

Wybierz sposób importu ofert

REST API

Feed HTTPS: XML lub JSON

SFTP / FTP

Istniejący format CRM

Uwierzytelnianie

Endpointy REST

Model oferty

Zasady synchronizacji

Identyfikacja

Aktualizacja

Wycofanie

Zdjęcia

Import pełny

Ponawianie żądań

Kody odpowiedzi i błędy

Feed XML/JSON oraz SFTP/FTP

Parametry feedu i SFTP/FTP

Podaj e-mail — prześlemy dane do API

Integracja ofert najmu z Rentumi

Działające Partner API v1

Prześlij

Zweryfikuj

Synchronizuj

Zakres wersji v1

Wybierz sposób importu ofert

REST API

Feed HTTPS: XML lub JSON

SFTP / FTP

Istniejący format CRM

Uwierzytelnianie

Endpointy REST

Model oferty

Zasady synchronizacji

Identyfikacja

Aktualizacja

Wycofanie

Zdjęcia

Import pełny

Ponawianie żądań

Kody odpowiedzi i błędy

Feed XML/JSON oraz SFTP/FTP

Parametry feedu i SFTP/FTP

Podaj e-mail — prześlemy dane do API