Вашите обяви. Свързани.

# ImotPortal API v1

Base: `https://YOUR-PORTAL/api/v1`. All dates are Unix timestamps in seconds; prices are integer EUR cents; areas are integer m². UTF-8 JSON. This is a server-to-server API, not browser CORS. OpenAPI: `/api/v1/openapi.json`.

## Keys

Sign in → My profile → API → create a key. Scopes: `read` for your listings, `write` for create/update/archive/images, `export` for your outgoing published feed. Keys are shown only once, stored hashed, expire after one year and can be revoked immediately. Each key belongs to ONE advertiser; access to another advertiser's records is forbidden. Send `Authorization: Bearer ip_YOUR_KEY`. Never put keys in URLs, frontend JavaScript or public repositories. The limit is 120 authenticated/unauthenticated API operations per IP per minute. A profile may hold at most 10 active keys and 100 property records in this release.

## Agency → portal

`POST /listings` creates or updates by your stable `external_id`. Repeating the same external ID updates the same property, rather than making duplicates. Updates are serialized transactionally. Keep external IDs stable across your CRM synchronizations.

```json
{
  "external_id": "crm-4582",
  "title": "Двустаен апартамент с тераса",
  "deal": "sale",
  "type": "apartment",
  "city": "София",
  "district": "Лозенец",
  "price_cents": 17500000,
  "area_m2": 82,
  "rooms": 2,
  "floor": 3,
  "description": "Просторен апартамент с отделна кухня, тераса и южно изложение.",
  "phone": "+359888000000"
}
```

Deal: `sale|rent`. Type: `apartment|house|land|office|shop|garage`. New/updated content is always pending moderation unless you explicitly pause/archive it. Clients cannot set `published`, `vip_until`, owner IDs or advertisement prices.

`GET /listings?external_id=crm-4582` looks up your record. `GET /listings?page=1&limit=50` lists your records (all statuses). `GET /listings/ID` reads one. `PATCH /listings/ID` updates the supplied fields and preserves the others. A published record returns to `pending` when its content or photos change. `DELETE /listings/ID` archives the record; IDs are never recycled. `PATCH` with `status: paused` pauses it. To resubmit, send `status: pending`.

Photos: `POST /listings/ID/images` as multipart form data with field `photo` (one JPEG/PNG/WebP, up to 4 MB, up to 10 photos per property). Images are decoded, metadata stripped and saved as JPEG. Remote photo URLs are deliberately not fetched. A receiving integration uploads files itself. Unapproved images are not publicly accessible.

```sh
curl https://YOUR-PORTAL/api/v1/listings \
  -H "Authorization: Bearer $IMOT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @property.json
curl https://YOUR-PORTAL/api/v1/listings/123/images \
  -H "Authorization: Bearer $IMOT_API_KEY" -F [email protected]
```

## Portal → other sites

`GET /feed?limit=50&page=1` returns YOUR published properties, descriptions, public contact details and image URLs. Another site can periodically pull this feed using an export-only key. No portal-wide data extraction is allowed by ordinary advertiser keys.

Incremental synchronization: `GET /feed?since=UNIX_TIMESTAMP&changes=1`. In this mode non-public records are returned as tombstones with `removed_from_public_feed: true` and a status. The destination must remove/hide these records. Without `changes=1`, only published properties are returned. Responses include total, page, next_page and server_time. Read all pages, upsert by `id`/`external_id`, apply tombstones, then keep the first response's server_time as the next watermark. Use an overlap of at least 60 seconds and deduplicate on the destination, because content may change while pages are being read. Periodic full resynchronization is recommended.

## Errors and moderation

401 missing/invalid/expired/revoked key; 403 missing scope; 404 absent or other owner's record; 422 field validation or moderation bypass; 429 rate limit. Successful create: 201; update/read/archive: 200. API does not publish directly to imot.bg or any third-party portal without their separate integration/access. API supplies the data and integration contract; the destination site must implement an importer or consume this documented feed. No email or external webhook push is performed automatically.


LOCATION CODES (1.1.0)
GET /api/v1/locations returns all 28 regions. Use ?region_code=SOF for settlements, or ?settlement_code=68134 for Sofia neighbourhoods. This lookup is public; listing imports still require a scoped API key.
POST/PATCH listings accepts region_code, settlement_code (five-digit EKATTE, keep leading zeros), neighborhood_code. Parent/child mismatches return 422. With settlement_code the city name is resolved server-side; city can be omitted. Neighborhood codes must come from this portal's lookup. Manual district names remain supported where no mapped neighbourhood exists.
Exports include all three codes as well as the readable city/district. Existing clients using city/district continue to work; explicit EKATTE codes distinguish villages with identical names. On PATCH changing a city/settlement clears stale child codes unless explicitly supplied.

## ImotPortal.bg launch
All companies share the same six-month free launch period. The current end date is displayed on the portal. API publication still follows the documented moderation rules. No automatic billing is enabled.