API & Integrări CRM HomePitch

Cuprins

1. Modele de integrare

HomePitch suportă două modele complementare, pe care le poți implementa independent:

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: <API_KEY>         # fără prefix Bearer (compatibil RENET/REBS)
# sau
?api_key=<API_KEY>              # query string
# sau
X-Api-Key: <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:

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: <SUPABASE_ANON_KEY_PUBLIC>   // 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 agentului>",   // 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=<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.

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.

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.

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

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

1. Implementează pull + push conform §3–§5 folosind orice cont de test.
2. Testează pe endpoint-ul HomePitch de staging (cere-l pe email).
3. Trimite pe [email protected]:
   • 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.
4. Echipa HomePitch adaugă providerul în Admin → CRM, activează maparea de tag-uri, și îți dă acces pentru agenții pilot.
5. Go-live: extindem limitele agenților care solicită și adăugăm butonul „Setări CRM {provider}” în /setari-crm.

13. Exemple end-to-end

Push punctual (curl)

curl -X POST https://bwfexvoapabfvkmmnxkg.supabase.co/functions/v1/crm-push-property \
  -H "apikey: <SUPABASE_ANON_KEY_PUBLIC>" \
  -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: <SUPABASE_ANON_KEY_PUBLIC>" \
  -H "Content-Type: application/json" \
  -d '{"renet_id":"12345","inline_api_key":"<RENET_API_KEY>"}'

REBS (deja live)

curl -X POST https://bwfexvoapabfvkmmnxkg.supabase.co/functions/v1/crmrebs-import-property \
  -H "apikey: <SUPABASE_ANON_KEY_PUBLIC>" \
  -H "Content-Type: application/json" \
  -d '{"rebs_id":"98765","inline_api_key":"<REBS_API_KEY>"}'

Redirect browser

https://homepitch.ro/crmrenet/12345?api_key=<RENET_API_KEY>
https://homepitch.ro/crmrebs/98765?api_key=<REBS_API_KEY>

14. Suport

• Email tehnic: [email protected]
• Specificații existente: RENET · REBS
• Status integrări active: /admin/crm/conectari (necesită cont admin)
• SLA răspuns onboarding: 2 zile lucrătoare.