Concepte
External ID
Folosește ID-urile din CRM în loc de ID-urile interne Rentix
External ID este abordarea recomandată pentru integrare. Nu trebuie să stochezi ID-urile Rentix în baza ta de date. Folosește ID-urile obiectelor din CRM-ul tău — API-ul va găsi singur înregistrările corespunzătoare.
Problema fără External ID
O integrare tipică fără external ID necesită un tabel de mapare:
CRM-ul tău Tabel mapare Rentix
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
│ ID: APT-001 │ ──────────► │ APT-001 → 42 │ ────► │ ID: 42 │
│ ID: APT-002 │ │ APT-002 → 43 │ │ ID: 43 │
└─────────────┘ └──────────────────┘ └─────────────┘
La fiecare actualizare trebuie să:
- Găsești maparea în baza ta de date
- Obții ID-ul Rentix
- Trimiți cererea cu acel ID
Soluția cu External ID
Cu external ID nu ai nevoie de mapare — API-ul o face singur:
CRM-ul tău Rentix
┌─────────────┐ ┌─────────────────────┐
│ ID: APT-001 │ ───── externalId: "APT-001" ─────────► │ ID: 42 │
│ ID: APT-002 │ │ externalId: APT-001 │
└─────────────┘ └─────────────────────┘
La actualizare:
- Trimite cererea cu
externalId: "APT-001" - API-ul găsește singur anunțul #42
Cum să folosești
La creare
Transmite externalId — ID-ul tău din CRM:
{
"externalId": "APT-001",
"announcementType": "rent",
"propertyType": "residential",
"propertySecondaryType": "apartment",
"announcementValue": 500
}
La actualizare
Același externalId — API-ul găsește anunțul existent:
{
"externalId": "APT-001",
"announcementValue": 600
}
La obținere
Folosește endpoint-ul cu /external/:
// După external ID
const response = await fetch(
'https://crm.rentix.md/api/v1/listings/external/APT-001',
{ headers: { 'Authorization': 'ApiKey YOUR_API_KEY' } }
);
const listing = await response.json();
console.log(listing.id); // 42 (ID intern)
console.log(listing.externalId); // "APT-001" (ID-ul tău)
curl https://crm.rentix.md/api/v1/listings/external/APT-001 \
-H "Authorization: ApiKey YOUR_API_KEY"
$ch = curl_init('https://crm.rentix.md/api/v1/listings/external/APT-001');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: ApiKey YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$listing = json_decode($response, true);
Reguli de utilizare
| Regulă | Descriere |
|---|---|
| Lungime maximă | 255 caractere |
| Caractere permise | Litere, cifre, cratime, underscore |
| Unicitate | În cadrul agenției și tipului de resursă |
Un
externalId poate fi al unui anunț, altul identic — al unui fișier media. Nu va fi conflict, deoarece sunt tipuri diferite de resurse.Resurse suportate
External ID funcționează pentru toate resursele principale:
| Resursă | Exemplu endpoint |
|---|---|
| Anunțuri | GET /listings/external/{externalId} |
| Utilizatori | GET /users/external/{externalId} |
| Fișiere media | GET /media/external/{externalId} |
Legare la obiecte existente
Dacă obiectul a fost deja creat fără externalId, îl poți lega ulterior:
// Leagă external ID la anunțul #42
await fetch('https://crm.rentix.md/api/v1/listings/42/link', {
method: 'POST',
headers: {
'Authorization': 'ApiKey YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ externalId: 'APT-001' })
});
curl -X POST https://crm.rentix.md/api/v1/listings/42/link \
-H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "externalId": "APT-001" }'
$ch = curl_init('https://crm.rentix.md/api/v1/listings/42/link');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['externalId' => 'APT-001']));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ApiKey YOUR_API_KEY',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);
Dezleagă external ID:
curl -X DELETE https://crm.rentix.md/api/v1/listings/42/link \
-H "Authorization: ApiKey YOUR_API_KEY"
Erori frecvente
| Eroare | Cauză | Soluție |
|---|---|---|
External ID already linked | ID-ul este deja folosit de alt obiect | Folosește un ID unic |
Cannot provide both id and externalId | Ai transmis ambii parametri | Folosește doar unul |