# API & Integrări CRM HomePitch > Documentație tehnică HomePitch pentru integrarea oricărui CRM imobiliar: pull feed, push proprietate, mapare câmpuri, limite per plan și pași de onboarding. Source: https://homepitch.ro/api-docs API public · v1 · Mai 2026 # API & Integrări CRM HomePitch Această pagină descrie **tot ce trebuie să știe un CRM imobiliar** (RENET, REBS, ImmoFlux sau orice CRM nou) pentru a se putea integra cu HomePitch. Poți începe implementarea **înainte de a fi aprobat** de echipa noastră — aprobarea e necesară doar la momentul go-live pentru activarea limitei de plan a agenților. ## Cuprins [1. Modele de integrare](#modele) [2. Autentificare & chei API](#autentificare) [3. Pull — feed CRM → HomePitch](#pull) [4. Push — CRM → HomePitch punctual](#push) [5. Schema câmpurilor proprietate](#schema) [6. Tipuri de proprietate](#tipuri) [7. Facilități & tag-uri](#facilitati) [8. Identificarea agenților](#agenti) [9. Limite per plan](#limite) [10. Coduri de eroare](#erori) [11. Webhook-uri emise de HomePitch](#webhooks) [12. Onboarding & aprobare](#onboarding) [13. Exemple end-to-end](#exemple) [14. Suport](#suport) ## 1. Modele de integrare HomePitch suportă două modele complementare, pe care le poți implementa independent: Model Cine inițiază Când e folosit Pull HomePitch Sincronizare zilnică automată a feed-ului agentului (cron 03:30 UTC) Push CRM extern Publicare imediată la create/update în CRM sau click pe „Listează pe HomePitch” Recomandare: implementează ambele. Pull garantează consistența, push oferă experiență instant agentului. ## 2. Autentificare & chei API ### 2.1 Cheia CRM → HomePitch citește CRM-ul tău Fiecare agent (sau agenție) din CRM-ul tău trebuie să poată genera o cheie API proprie pe care o va introduce în HomePitch la `/setari-crm`. HomePitch trimite cheia în request-urile către API-ul tău în unul din formatele: ``` Authorization: # fără prefix Bearer (compatibil RENET/REBS) # sau ?api_key= # query string # sau X-Api-Key: # header custom (acceptat) ``` Suportă toate trei — HomePitch alege în funcție de configurația CRM-ului. ### 2.2 Cheia HomePitch → CRM-ul tău apelează HomePitch Pentru push, folosești endpoint-ul public HomePitch (vezi §4). Autentificarea se face cu cheia proprie a agentului din CRM-ul tău, transmisă în body ca `inline_api_key`. Nu ai nevoie de o cheie HomePitch dedicată în v1. ### 2.3 Chei de agenție (opțional, recomandat) Dacă CRM-ul tău emite o singură cheie pe agenție care poate citi feed-ul tuturor agenților acelei agenții, marchează-o în documentația ta ca „agency-wide”. HomePitch o va salva în tabelul intern `agency_keys` și o va folosi ca fallback pentru agenții care nu și-au introdus încă o cheie proprie. ## 3. Pull — HomePitch citește CRM-ul tău În fiecare noapte HomePitch apelează CRM-ul tău per-agent. Trebuie să expui: Endpoint minim Descriere GET /properties?limit=100&offset=N Listare paginată a proprietăților agentului (filtrat prin cheia API) GET /properties/{id} Detalii complete proprietate (folosit și de push) GET /agents/me (recomandat) Identificare agent — returnează cel puțin { email, first_name, last_name, phone, agency_name } ### Paginare - Suportă `limit` (max 500) și `offset`. - Returnează un obiect cu `{ count, results: [] }` sau array direct + header `X-Total-Count`. ### Filtre utile - `updated_since=ISO8601` — HomePitch trimite ultimul timestamp cunoscut pentru sincronizare incrementală. - `is_active=true` — doar proprietăți publicabile. ## 4. Push — CRM → HomePitch punctual Un singur endpoint universal: ``` POST https://bwfexvoapabfvkmmnxkg.supabase.co/functions/v1/crm-push-property Headers: apikey: // cheia publică HomePitch, ok în cod client Content-Type: application/json Body: { "provider": "renet" | "rebs" | "immoflux" | "custom", "external_id": "12345", // ID-ul proprietății în CRM-ul tău "inline_api_key": "", // cheia lui în CRM-ul tău "callback_url": "https://…" // opțional, webhook status } ``` Răspuns: - `200` — `{ success: true, property_url, already_imported? }` - `402` — `{ error: "plan_limit_reached", limit, current }` - `403` — `{ error: "agent_mismatch" }` - `404` — `{ error: "not_found" }` - `422` — `{ error: "invalid_payload", details }` ### Redirect direct din browser Poți plasa în interfața CRM-ului un buton „Listează pe HomePitch” care deschide: ``` https://homepitch.ro/crm{provider}/{external_id}?api_key= ``` Exemple concrete existente: `/crmrenet/12345`, `/crmrebs/98765`. ## 5. Schema câmpurilor proprietate Câmpuri pe care HomePitch le extrage automat. Trimite tot ce ai — restul sunt ignorate. Câmp HomePitch Tip Obligatoriu Descriere external_id string ✓ ID-ul unic din CRM title string ✓ Max 200 caractere description text ✓ Recomandăm min 300 caractere property_type enum ✓ Vezi §6 transaction_type enum ✓ vanzare | inchiriere price number ✓ În EUR (obligatoriu — HomePitch afișează doar EUR) city_name, zone_name, street string ✓ (oraș) Text liber, HomePitch normalizează lat, lng number ✓ WGS84. Obligatoriu — proprietățile fără pin nu sunt importate rooms, bedrooms, bathrooms int – surface_usable, surface_built, surface_total, surface_land number (m²) – floor, building_floors int – floor acceptă și „P”, „D”, „M” year_built int – images[] string[] – URL-uri absolute, HTTPS, max 40 img video_link, virtual_tour_link string – YouTube / Matterport / URL tags[] string[] – Slug-uri normalizate → §7 collab_commission_percent number – Comision colaborare (%) date_added, date_updated ISO8601 – Timezone recomandat: UTC agent.email string ✓ Cheia de match cu contul HomePitch ## 6. Tipuri de proprietate HomePitch folosește enum-ul intern din stânga. Dacă folosești coduri numerice (ca RENET), documentează-le clar — vom adăuga maparea în admin. HomePitch enum RENET REBS Sinonime acceptate apartament 1 apartment flat, condo casa 2 house vila, duplex birou 3 office office_space spatiu_comercial 4 commercial retail, shop teren 5 land plot spatiu_industrial 6 industrial warehouse, hala ## 7. Facilități & tag-uri Trimite `tags[]` ca **slug-uri lowercase fără diacritice**. HomePitch aplică un mapping configurabil tag → facilitate standard, editabil de admin. Exemple: `aer-conditionat`, `centrala-proprie`, `lift`, `parcare`, `balcon`, `terasa`, `gradina`, `piscina`, `boxa`, `mobilat`, `utilat`, `pet-friendly`, `prima-inchiriere`. ## 8. Identificarea agenților - Cheia de match este **email-ul agentului** — asigură-te că e unic și corect în CRM-ul tău. - Dacă agentul nu are cont HomePitch la momentul push-ului, îl creăm automat pe baza email-ului, cu parolă temporară și email de welcome. - Recomandat să trimiți și `phone`, `first_name`, `last_name`, `agency_name` pentru un profil complet. ## 9. Limite per plan HomePitch Se aplică pe **numărul de proprietăți active**, indiferent de provider CRM. Plan Proprietăți active Import zilnic Gratuit 10 3 / zi VIP 30 30 / zi Pro 100 50 / zi La depășire push returnează `402 plan_limit_reached`, pull sare peste proprietățile suplimentare și trimite agentului email de upgrade. Limitele pot fi extinse manual la cerere. ## 10. Coduri de eroare HTTP Cod Cauză Acțiune recomandată 400 bad_request JSON invalid Verifică payload-ul 401 invalid_api_key Cheia CRM nu e recunoscută Regenerează în CRM și retrimite 402 plan_limit_reached Agentul a atins limita planului Trimite user-ul la /pricing 403 agent_mismatch Proprietatea aparține altui agent Nu retrimite 404 not_found external_id nu există în feed-ul CRM Verifică ID 422 invalid_payload Lipsesc câmpuri obligatorii (ex: lat/lng) Vezi details 429 rate_limited Prea multe push-uri < 1s Backoff exponențial 5xx server_error Eroare HomePitch Retry cu backoff, apoi contact ## 11. Webhook-uri emise de HomePitch (opțional) Dacă furnizezi `callback_url` în push, HomePitch trimite POST cu: ``` { "event": "property.imported" | "property.updated" | "property.rejected", "external_id": "12345", "property_url": "https://homepitch.ro/proprietate/…", "status": "active" | "pending" | "rejected", "reason": "..." // doar la rejected } ``` Semnătura HMAC (SHA-256) în header `X-HomePitch-Signature`, folosind secretul webhook pe care ți-l furnizăm la onboarding. ## 12. Onboarding & aprobare - **Implementează** pull + push conform §3–§5 folosind orice cont de test. - **Testează** pe endpoint-ul HomePitch de staging (cere-l pe email). - Trimite pe [contact@homepitch.ro](mailto:contact@homepitch.ro): Documentația API-ului CRM-ului tău (link sau PDF). - URL-ul feed-ului și un exemplu de proprietate. - Cheie API de test pentru un agent demo. - Echipa HomePitch adaugă providerul în `Admin → CRM`, activează maparea de tag-uri, și îți dă acces pentru agenții pilot. - Go-live: extindem limitele agenților care solicită și adăugăm butonul „Setări CRM {provider}” în `/setari-crm`. Poți începe implementarea acum , fără aprobare prealabilă. Schema din §5 și endpoint-ul din §4 sunt stabile. ## 13. Exemple end-to-end ### Push punctual (curl) ``` curl -X POST https://bwfexvoapabfvkmmnxkg.supabase.co/functions/v1/crm-push-property \ -H "apikey: " \ -H "Content-Type: application/json" \ -d '{ "provider": "custom", "external_id": "AB-1234", "inline_api_key": "sk_live_xxx", "callback_url": "https://crm.exemplu.ro/hooks/homepitch" }' ``` ### RENET (deja live) ``` curl -X POST https://bwfexvoapabfvkmmnxkg.supabase.co/functions/v1/crmrenet-import-property \ -H "apikey: " \ -H "Content-Type: application/json" \ -d '{"renet_id":"12345","inline_api_key":""}' ``` ### REBS (deja live) ``` curl -X POST https://bwfexvoapabfvkmmnxkg.supabase.co/functions/v1/crmrebs-import-property \ -H "apikey: " \ -H "Content-Type: application/json" \ -d '{"rebs_id":"98765","inline_api_key":""}' ``` ### Redirect browser ``` https://homepitch.ro/crmrenet/12345?api_key= https://homepitch.ro/crmrebs/98765?api_key= ``` ## 14. Suport - Email tehnic: [contact@homepitch.ro](mailto:contact@homepitch.ro) - Specificații existente: [RENET](/api-docs/renet) · [REBS](/api-docs/rebs) - Status integrări active: [/admin/crm/conectari](https://homepitch.ro/admin/crm/conectari) (necesită cont admin) - SLA răspuns onboarding: 2 zile lucrătoare.