📥 Import ofert przez FTP - dokumentacja
Wgrywaj paczki .zip przez FTP - system automatycznie dodaje, aktualizuje i usuwa oferty. Obsługujemy 4 formaty XML: nasz natywny zaadresowani.pl oraz trzy popularne standardy polskie (oferty.net, Gratka, Otodom). Format wybierasz w Panelu konta → Import FTP.
O imporcie FTP
Import pozwala synchronizować Twoją bazę ofert z portalem bez ręcznego dodawania - wystarczy że Twój system CRM eksportuje paczki ZIP w jednym z obsługiwanych formatów, a my zajmiemy się resztą. Co kilka minut nasz cron skanuje katalog FTP i automatycznie przetwarza nowe paczki.
Kompatybilne CRM-y
Poniżej lista systemów CRM które obsługują integrację z zaadresowani.pl. Jeśli używasz jednego z nich - wystarczy że włączysz eksport w odpowiednim formacie, a paczki będą trafiać prosto do nas.
Domuly to nowoczesny, chmurowy system CRM stworzony specjalnie dla branży nieruchomości (deweloperów i biur nieruchomości), który integruje zarządzanie ofertami, klientami oraz procesem sprzedaży w jednym miejscu. Pozwala automatyzować pracę, obsługiwać rezerwacje i eksportować oferty na portale ogłoszeniowe.
Strona producenta →
EstiCRM to chmurowy system CRM dla branży nieruchomości, który integruje zarządzanie ofertami, klientami i sprzedażą. Pozwala automatyzować procesy, eksportować oferty na portale ogłoszeniowe, zarządzać dokumentami oraz skuteczniej obsługiwać klientów na każdym etapie transakcji.
Strona producenta →
Grupa Morizon-Gratka dostarcza rozwiązania dla branży nieruchomości, obejmujące portale ogłoszeniowe oraz narzędzia wspierające pracę biur nieruchomości i deweloperów. W ramach ekosystemu oferuje m.in. system CRM Agencja5000, integracje z portalami nieruchomości oraz rozwiązania umożliwiające promocję ofert i skuteczne dotarcie do potencjalnych klientów.
Strona producenta →Twój CRM nie jest na liście, ale eksportuje w jednym z obsługiwanych formatów (zaadresowani.pl, oferty.net, Gratka, Otodom)? Też się sprawdzi - wybierz odpowiedni format w ustawieniach konta i zacznij importować. Jeśli chcesz żeby Twój CRM trafił do tej listy, napisz na biuro@zaadresowani.pl.
Jak uzyskać dostęp
- Zaloguj się na konto biura lub dewelopera w portalu zaadresowani.pl.
- Wejdź w Panel konta → Import FTP i kliknij Wyślij zgłoszenie.
- Administrator portalu utworzy dla Ciebie indywidualne konto FTP i prześle dane logowania mailem.
- W panelu konta wybierz format danych (domyślnie zaadresowani.pl) i zacznij wgrywać paczki.
Jak działa import
- Detekcja - co kilka minut cron skanuje katalogi klientów. Paczka jest pomijana, jeśli była zmodyfikowana w ostatnich 30 sekundach.
- Idempotencja - system liczy SHA-256 paczki. Ten sam plik nie jest importowany dwukrotnie.
- Walidacja - sprawdzenie poprawności XML i obecności wymaganych pól (zależnie od formatu).
- Parsowanie - każda oferta przetwarzana po kolei, z podziałem na: dodaj / aktualizuj / usuń / dezaktywuj.
- Zdjęcia - z dwóch trybów: snapshot (pełna lista per oferta) lub incremental (operacje per zdjęcie). Diff po SHA-256 - kopiujemy tylko nowe pliki.
- Tryb
calosc- po imporcie wygaszamy oferty których nie było w paczce (statusinactive, odwracalne). - Archiwizacja - paczki przeniesione do
processed/lubfailed/po stronie serwera. - Powiadomienie - e-mail z podsumowaniem (dodane / zaktualizowane / usunięte / pominięte ze względu na limit / błędy).
Struktura paczki ZIP
- Jeden plik
.xmlw paczce - zawiera wszystkie oferty. - Zdjęcia luzem (bez podkatalogów).
- Nazwy plików zdjęć - bez polskich znaków diakrytycznych, unikalne w obrębie paczki.
| Cecha | Wartość |
|---|---|
| Kodowanie XML | UTF-8 (lub ISO-8859-2 dla formatu Gratka) |
| Maks. liczba plików w ZIP | 50 000 |
| Maks. rozmiar pojedynczego pliku | 200 MB |
| Dozwolone rozszerzenia | xml, jpg, jpeg, png, webp, gif |
| Limit zdjęć per oferta | z pakietu klienta - patrz Limity |
Format 1: zaadresowani.pl (natywny, zalecany) ⭐
Nasz format zaprojektowany pod kątem maksymalnej czytelności. Wszystkie tagi po polsku w lowercase, wartości słownikowe jako jasne stringi (cegla, blok, do_zamieszkania) - bez liczbowych ID-ków ze słowników. Najprostszy do napisania w Twoim CRM.
Korzeń pliku
Inwestycje deweloperskie (opcjonalne) 🏗️
Jeśli sprzedajesz mieszkania w ramach inwestycji (osiedle, budynek wielomieszkaniowy), możesz dodać blok <inwestycje> z definicją inwestycji, a w każdej ofercie referencję <inwestycja_ref>. Dzięki temu portal pokaże mieszkania zgrupowane pod nazwą inwestycji, z mapą terenu, logiem i wspólnymi danymi.
Klucz id jest Twoim identyfikatorem - przy kolejnym imporcie ten sam id = aktualizacja istniejącej inwestycji (po parze konto + id). Może być dowolny string, np. OS-1, UUID, czy slug.
W ofercie linkujemy do inwestycji przez <inwestycja_ref>:
- Inwestycję wystarczy zdefiniować raz (przy pierwszym imporcie), kolejne paczki mogą zawierać tylko zmiany ofert + ten sam
<inwestycja_ref>. - Jeśli zmienisz dane inwestycji (np. przesunie się
data_oddania) i wyślesz blok<inwestycje>z tym samymid, zostanie zaktualizowana. - Logo wystarczy raz w paczce ZIP - przy kolejnych importach pomijasz, system zachowuje wcześniejsze.
- Status
etap:planowany | w_realizacji | gotowy | sprzedany. - Inwestycje pokazują się w /inwestycje i na profilu dewelopera, oferty na /oferty z linkiem do "macierzystej" inwestycji.
Pełny przykład oferty
Wartości słownikowe
Format używa tych samych kluczy co nasza baza - co widzisz w XML, to widzisz w panelu konta. Brak ID-ków, brak konwersji.
Dostępność pól per typ nieruchomości
Nie wszystkie pola mają sens dla każdego typu - np. ogrzewanie dla mieszkania ale nie dla działki. Tabela pokazuje co warto wypełnić:
| Pole | mieszkanie | dom | lokal/biuro/hala/magazyn | działka | pokój | garaż |
|---|---|---|---|---|---|---|
rynek | ✓ | ✓ | - | - | - | - |
budynek/typ | ✓ | ✓ | ✓ | - | - | ✓ |
budynek/material | ✓ | ✓ | - | - | - | - |
budynek/stan_wykonczenia | ✓ | ✓ | - | - | - | - |
parametry/pokoje | ✓ | ✓ | ✓ (liczba pomieszczeń) | - | ✓ | - |
parametry/forma_wlasnosci | ✓ | ✓ | - | - | - | - |
udogodnienia | ✓ | ✓ | - | - | - | - |
media | ✓ | ✓ | ✓ | - | - | - |
ogrzewanie | ✓ | ✓ | - | - | - | - |
wyposazenie | ✓ | ✓ | ✓ (kategoria Ogólne) | - | ✓ (Kuchnia/Łazienka/Ogólne) | - |
Pola pominięte dla danego typu są ignorowane przy imporcie - nie powodują błędu.
typ - typ nieruchomości
| Klucz w XML | Etykieta |
|---|---|
mieszkanie | Mieszkanie |
dom | Dom |
dzialka | Działka |
lokal | Lokal użytkowy |
pokoj | Pokój (tylko wynajem) |
garaz | Garaż |
Dla biura, hali i magazynu używaj <typ>lokal</typ> + <budynek><typ>biurowiec</typ></budynek> (lub hala / magazyn).
transakcja
| Klucz | Etykieta |
|---|---|
sprzedaz | Sprzedaż |
wynajem | Wynajem |
rynek (tylko mieszkanie i dom)
| Klucz | Etykieta |
|---|---|
pierwotny | Pierwotny |
wtorny | Wtórny |
budynek/typ (rodzaj budynku) - różne wartości per typ nieruchomości
Lista zależy od typu nieruchomości - np. dla mieszkania nie ma sensu "siedlisko", a dla domu "loft".
| Klucz | Etykieta | mieszkanie | dom | lokal/biuro | hala/magazyn |
|---|---|---|---|---|---|
apartamentowiec | Apartamentowiec | ✓ | - | ✓ | - |
blizniak | Bliźniak | - | ✓ | - | - |
blok | Blok mieszkalny | ✓ | - | ✓ | - |
dom_wolnostojacy | Dom wolnostojący | ✓ | ✓ | - | - |
dom_wielorodzinny | Dom wielorodzinny | ✓ | - | - | - |
dworek_palac | Dworek / pałac | - | ✓ | ✓ | - |
kamienica | Kamienica | ✓ | ✓ | ✓ | - |
dom_letniskowy | Dom letniskowy | - | ✓ | - | - |
rezydencja | Rezydencja | ✓ | ✓ | ✓ | - |
dom_szeregowy | Dom szeregowy | - | ✓ | - | - |
budynek_wolnostojacy | Budynek wolnostojący | - | - | ✓ | ✓ |
kompleks_budynkow | Kompleks budynków | - | - | ✓ | ✓ |
hala | Hala | - | - | ✓ | ✓ |
garaz | Garaż | - | - | ✓ | - |
biurowiec | Biurowiec | - | - | ✓ | - |
magazyn | Magazyn | - | - | ✓ | ✓ |
gospodarstwo_rolne | Gospodarstwo rolne | - | ✓ | - | - |
dom_z_funkcja_uslugowa | Dom z funkcją usługową | - | ✓ | ✓ | ✓ |
siedlisko | Siedlisko | - | ✓ | - | - |
obiekt_handlowo_uslugowy | Obiekt handlowo-usługowy | - | - | ✓ | ✓ |
loft | Loft | ✓ | - | ✓ | - |
obiekt_biurowo_handlowo_uslugowy | Obiekt biurowo-handlowo-usługowy | - | - | ✓ | ✓ |
centrum_handlowe | Centrum handlowe | - | - | ✓ | ✓ |
pietro_domu | Piętro domu | - | ✓ | - | - |
czesc_domu | Część domu | - | ✓ | - | - |
oficyna | Oficyna | ✓ | - | ✓ | - |
budynek/material - materiał budowy (mieszkanie, dom)
| Klucz | Etykieta |
|---|---|
cegla | Cegła |
wielka_plyta | Wielka płyta |
pustak | Pustak |
pustak_ceramiczny | Pustak ceramiczny |
drewno | Drewno |
keramzyt | Keramzyt |
beton | Beton |
silikat | Silikat |
beton_komorkowy | Beton komórkowy |
inne | Inne |
budynek/stan_wykonczenia (mieszkanie, dom)
| Klucz | Etykieta |
|---|---|
do_wykonczenia | Do wykończenia |
do_zamieszkania | Do zamieszkania |
wysoki_standard | Wysoki standard |
deweloperski | Stan deweloperski |
po_remoncie | Po remoncie |
parametry/forma_wlasnosci (mieszkanie, dom)
| Klucz | Etykieta |
|---|---|
pelna_wlasnosc | Pełna własność |
spoldzielcze_wl | Spółdzielcze własnościowe |
spoldzielcze_lok | Spółdzielcze lokatorskie |
uzytkowanie_wieczyste | Użytkowanie wieczyste |
udzial | Udział |
udogodnienia/udogodnienie - różne wartości per typ
| Klucz | Etykieta | mieszkanie | dom |
|---|---|---|---|
balkon | Balkon | ✓ | ✓ |
ogrodek | Ogródek | ✓ | ✓ |
piwnica | Piwnica | ✓ | ✓ |
ogrodzenie | Ogrodzenie | - | ✓ |
garaz | Garaż | - | ✓ |
media/element - różne wartości per typ
| Klucz | Etykieta | mieszkanie | dom | lokal | biuro | hala | magazyn |
|---|---|---|---|---|---|---|---|
prad | Prąd | - | ✓ | ✓ | ✓ | ✓ | ✓ |
woda | Woda | - | ✓ | ✓ | ✓ | ✓ | ✓ |
gaz | Gaz | - | ✓ | ✓ | - | ✓ | - |
internet | Internet | ✓ | - | ✓ | ✓ | - | - |
telewizja | Telewizja | ✓ | - | ✓ | - | - | - |
telefon | Telefon | ✓ | ✓ | ✓ | ✓ | - | - |
kanalizacja | Kanalizacja | - | ✓ | ✓ | ✓ | ✓ | ✓ |
szambo | Szambo | - | ✓ | ✓ | - | - | - |
oczyszczalnia | Oczyszczalnia | - | ✓ | ✓ | - | - | - |
ogrzewanie/typ (mieszkanie, dom)
| Klucz | Etykieta |
|---|---|
elektryczne | Elektryczne |
gazowe | Gazowe |
miejskie | Miejskie / sieciowe |
pompa_ciepla | Pompa ciepła |
olejowe | Olejowe |
weglowe | Węglowe |
kominek | Kominek |
podlogowe | Podłogowe |
kolektory | Kolektory słoneczne |
biomasa | Biomasa |
pellety | Pellety |
brak | Brak ogrzewania |
wyposazenie/element - pełna lista per kategoria
Wyposażenie podzielone jest na kategorie. Dla mieszkania i domu dostępne są wszystkie. Dla pokoju - Kuchnia/Łazienka/Ogólne. Dla lokalu/biura - tylko Ogólne.
🍳 Kuchnia - mieszkanie, dom, pokój
| Klucz | Etykieta |
|---|---|
lodowka | Lodówka |
zamrazarka | Zamrażarka |
kuchenka | Kuchenka |
kuchenka_indukcyjna | Kuchenka indukcyjna |
zmywarka | Zmywarka |
mikrofalowka | Mikrofalówka |
okap | Okap |
ekspres | Ekspres do kawy |
toster | Toster |
czajnik | Czajnik elektryczny |
🛋️ Salon - mieszkanie, dom
| Klucz | Etykieta |
|---|---|
telewizor | Telewizor |
telewizor_smart | Smart TV |
kanapa | Kanapa |
fotel | Fotel |
stol_jadalny | Stół jadalny |
biurko_salon | Biurko |
klimatyzacja | Klimatyzacja |
internet_salon | Wi-Fi |
rolety | Rolety / żaluzje |
netflix | Netflix / streaming |
🛏️ Sypialnia - mieszkanie, dom
| Klucz | Etykieta |
|---|---|
lozko | Łóżko |
lozko_dwuosobowe | Łóżko 2-osobowe |
szafa | Szafa |
szafa_wnekowa | Szafa wnękowa |
biurko | Biurko |
lustro | Lustro |
komoda | Komoda |
zasony | Zasłony |
klimatyzacja_sypialnia | Klimatyzacja |
rolety_sypialnia | Rolety zaciemniające |
🛁 Łazienka - mieszkanie, dom, pokój
| Klucz | Etykieta |
|---|---|
pralka | Pralka |
suszarka | Suszarka ubrań |
pralko_suszarka | Pralko-suszarka |
wanna | Wanna |
prysznic | Prysznic |
kabina_prysznicowa | Kabina prysznicowa |
suszarka_do_wlosow | Suszarka do włosów |
szafka_lazienka | Szafka łazienkowa |
lustro_lazienka | Lustro z oświetleniem |
bidet | Bidet |
🏢 Ogólne - mieszkanie, dom, lokal, biuro, pokój
| Klucz | Etykieta |
|---|---|
winda | Winda |
garaz_miejsce | Garaż / parking |
rower_stojak | Stojak na rowery |
domofon | Domofon |
wideodomofon | Wideodomofon |
monitoring | Monitoring |
alarm | Alarm |
rolety_zewn | Rolety zewnętrzne |
balkon_taras | Balkon / taras |
ogrodek | Ogródek |
piwnica | Piwnica / komórka |
suszarnia | Suszarnia |
Wymagane pola
<symbol>- unikalny identyfikator z Twojego CRM<lokalizacja><miasto><cena><powierzchnia>
Pozostałe pola są opcjonalne. Dla operacji usun i dezaktywuj wystarczy podać <symbol>.
Format 2: oferty.net (domy.pl)
Standard domy.pl/eksport (wersja 0.4.x). Korzeń <plik> z meta-headerem, listą działów per typ × transakcja, polami jako <param nazwa="…" typ="…">.
Szkielet XML
Pełna specyfikacja: https://domy.pl/eksport. Wszystkie pola jako <param nazwa="…"> wewnątrz <oferta>. Tryb calosc/roznica w headerze. Działy: mieszkania, domy, dzialki, lokale, pokoje.
Zdjęcia w trzech wariantach (parser autodetektuje):
- A -
<param nazwa="zdjecie1..15">wewnątrz<oferta>(oficjalna spec, max 15) - B - globalny blok
<zdjecia>jako siostra<lista_ofert>z atrybutem<akcja>d|u</akcja>(Domuly, bez limitu) - C -
<zdjecia><zdjecie nazwa="…"/>wewnątrz<oferta>(intuicyjny, bez limitu)
Format 3: Gratka
Format eksportu na Gratka.pl. Korzeń <dane>, każda oferta jako <record> z polami w postaci bezpośrednich tagów. Pola słownikowe (np. id_material, id_stan_mieszkania_nowy) jako liczbowe ID - bez znajomości słowników Gratki nie wszystkie zostaną zmapowane na nasze klucze (klient może uzupełnić ręcznie po imporcie).
Szkielet XML
Cechy charakterystyczne:
- Encoding często
ISO-8859-2(Latin-2) - parser automatycznie konwertuje do UTF-8 - Limit zdjęć 12 per oferta (
<z1>…<z12>jako flagitrue/false) - Pliki zdjęć w paczce nazwane
{numer_oferty}_{N}.jpg(z fallbackiem na{id_inspert}_{N}.jpg) - Tryb
full= snapshot,inc= incremental
Format 4: Otodom
Format eksportu na Otodom.pl (wersja 170130). Korzeń <otoDom>, oferty jako <Insertion> w bloku <Insertions>. Bardzo silnie typowane słownikami liczbowymi (BuildingType, BuildingMaterial, ConstructionStatus itp.).
Szkielet XML
Cechy charakterystyczne:
- Akcje jako liczby:
Action= 0 (insert/update), 1 (dezaktywuj), 2 (usuń) - Limit zdjęć 20 per oferta
- Aktualne słowniki: https://www.otodom.pl/api/lite/dictionaries
- Pełna spec: dokumentacja "Otodom Import" wersja 170130
Tryby: całość vs różnica
Każdy z formatów rozróżnia dwa tryby paczki (różne nazwy, ta sama logika):
| Format | Snapshot | Incremental |
|---|---|---|
| zaadresowani.pl | <tryb>calosc</tryb> | <tryb>roznica</tryb> |
| oferty.net | <zawartosc_pliku>calosc</zawartosc_pliku> | <zawartosc_pliku>roznica</zawartosc_pliku> |
| Gratka | <export>full</export> | <export>inc</export> |
| Otodom | <ImportType>full</ImportType> | <ImportType>incremental</ImportType> |
Snapshot (calosc / full)
Paczka zawiera wszystkie aktualne oferty. Po imporcie oferty na portalu, których nie ma w paczce, są wygaszane (status inactive - odwracalne). To bezpieczna semantyka - kolejna paczka snapshot przywróci zaginione oferty.
Incremental (roznica / inc)
Paczka zawiera tylko zmiany względem ostatniego eksportu. Operacje są jawne - dodaj/aktualizuj/usuń/dezaktywuj. Oferty niewymienione w paczce pozostają bez zmian. Najbezpieczniejszy tryb dla codziennego eksportu.
Akcje na ofertach
| Akcja | zaadresowani.pl | oferty.net | Gratka | Otodom |
|---|---|---|---|---|
| Dodaj / aktualizuj | akcja="dodaj" | <oferta> | <action>insert</action> | <Action>0</Action> |
| Hard delete | akcja="usun" | <oferta_usun> | <action>delete</action> | <Action>2</Action> |
| Soft delete (dezaktywacja) | akcja="dezaktywuj" | tryb calosc (auto) | - | <Action>1</Action> |
System rozróżnia: hard delete = trwałe usunięcie (rekord + zdjęcia), soft delete = wygaszenie (status inactive, klient może wznowić).
Zdjęcia
Pliki zdjęć w paczce ZIP - luzem w głównym katalogu. Każdy format ma własny sposób referowania nazw plików.
| Format | Schemat zapisu w XML | Maks. w XML |
|---|---|---|
| zaadresowani.pl | <zdjecia><zdjecie kolejnosc="N">plik.jpg</zdjecie> | bez limitu |
| oferty.net (A) | <param nazwa="zdjecieN">plik.jpg</param> | 15 (twarda spec) |
| oferty.net (B) | globalny <zdjecia> z <akcja>d|u</akcja> | bez limitu |
| oferty.net (C) | <zdjecia><zdjecie nazwa="…"/> | bez limitu |
| Gratka | <zdjecia><z1>true</z1>…</zdjecia> + pliki {numer_oferty}_{N}.jpg | 12 (twarda spec) |
| Otodom | <Photos><Photo><File>…</File></Photo></Photos> | 20 (twarda spec) |
Kolumna "Maks. w XML" to ile zdjęć da się fizycznie zadeklarować w pliku danego formatu - wynika z jego specyfikacji. Np. oferty.net Wariant A definiuje tagi zdjecie1…zdjecie15 i nic więcej.
System najpierw sprawdza ile zdjęć dostajesz w swoim pakiecie (np. 10 bezpłatnych + 10 po dokupie = max 20). Jeśli paczka zawiera więcej zdjęć dla oferty niż przewiduje pakiet - nadwyżka zostaje pominięta, a Ty otrzymasz mail: "Pominięto X zdjęć - wykup dodatkowe w panelu konta i wgraj paczkę ponownie".
Przykład: klient z pakietem Starter (10 zdjęć) wgrywa paczkę Otodom z 20 zdjęciami → system zaimportuje pierwsze 10, pozostałe 10 pominie. Limit 20 z Otodom to tylko ograniczenie samego XML.
Aktualny limit zdjęć dla Twojego konta zobaczysz w Panelu konta → Mój pakiet w sekcji "Zdjęcia / oferta".
Diff po SHA-256 - zdjęcia o niezmienionej zawartości nie są kopiowane ponownie przy kolejnych importach. Oszczędza dysk i transfer.
Limity i pakiety
Liczba aktywnych ofert i zdjęć per oferta jest ograniczona przez pakiet:
- Limit ofert - np. starter agency = 5, pro = 30, premium = ∞. Po wyczerpaniu nowe oferty z paczki są pomijane (skipped_by_limit).
- Limit zdjęć / oferta - z pakietu lub fallback z roli (agency = 10 + 10 po dokupie). Nadwyżka pomijana.
- Aktualizacje (już istniejących) i usunięcia nie wliczają się do limitu.
- Wygaszone oferty (status
inactive) zwalniają slot pakietu - można dodać kolejną.
Walidacja i typowe błędy
Statystyki w mailu z podsumowaniem importu:
| Statystyka | Znaczenie |
|---|---|
| Dodane | Liczba nowych ofert utworzonych w bazie. |
| Zaktualizowane | Liczba istniejących ofert których pola zmieniono. |
| Usunięte | Suma: hard delete + wygaszone (soft delete). |
| Pominięte (limit) | Nowe oferty, które nie zmieściły się w limicie pakietu. |
| Błędy | Oferty których nie udało się zaimportować - szczegóły w logu i historii runu. |
Każdy run ma stronę szczegółów z listą ofert i ich operacji - w panelu klienta i admina.
Upload manualny (alternatywa dla FTP)
Jeśli nie chcesz konfigurować klienta FTP - np. do testowego importu pojedynczej paczki - wgraj plik bezpośrednio z przeglądarki w Panelu konta → Import FTP:
- Maksymalny rozmiar: 500 MB.
- Paczka trafia do tej samej kolejki - wynik w historii w ciągu kilku minut.
- Wymaga aktywnego konta FTP.