Fișiere media
Prezentare fișiere media
Încărcarea fotografiilor și videoclipurilor pentru anunțuri prin API
Fișierele media sunt o parte obligatorie a anunțurilor. Pentru publicare ai nevoie de minim 3 fotografii. API-ul suportă două modalități de încărcare și optimizează automat toate fișierele.
Nu trebuie să optimizezi fotografiile înainte de încărcare — încarcă originalele.
Modalități de încărcare
| Modalitate | Când să folosești | Descriere |
|---|---|---|
| URL în anunț | Întotdeauna când e posibil | Cel mai simplu — transmite URL-ul direct la crearea anunțului |
| Import după URL | Încărcare în avans | Încarcă fotografiile separat, apoi leagă-le la anunț |
| Signed URL | Încărcare de pe disc local | Pentru fișiere fără URL public |
Recomandare: Transmite URL-urile fotografiilor direct la crearea anunțului — sistemul le va încărca automat. Aceasta este metoda cea mai simplă.
Formate suportate
Imagini
JPEG, PNG, WebP, HEIC și alte formate populare.
Video
MP4, AVI, MOV — până la 3 minute.
Limitări
| Parametru | Valoare |
|---|---|
| Minim fotografii pentru publicare | 3 |
| Maxim fotografii per anunț | 20 |
| Fișiere într-o singură cerere | până la 100 |
| Valabilitate signed URL | 30 minute |
Scenariu tipic
Abordare recomandată — într-o singură cerere:
PUT /listings
→ transmiți files: [{ url: "https://..." }] și announcementStatus: "active"
→ sistemul încarcă și optimizează automat fotografiile
Abordare alternativă — încărcare separată:
1. Încarcă fotografiile → POST /media/bulk
→ cu operația upload-from-url
2. Leagă la anunț → PUT /listings
→ transmiți files: [{ id: 123 }] sau [{ externalFileId: "..." }]
Structura fișierului media
După încărcare și optimizare, fișierul conține:
{
"id": 123,
"externalId": "photo-001",
"size": 245000,
"contentType": "image/jpeg",
"optimization": "success",
"blurhash": "L7HuX^zY1z-6ADx?0z2@1Io#{yV_",
"originalUrl": "https://storage.../original.jpg",
"variants": [
{ "url": "https://storage.../128.webp", "variantSize": "128", "size": 4074 },
{ "url": "https://storage.../512.webp", "variantSize": "512", "size": 32850 },
{ "url": "https://storage.../1024.webp", "variantSize": "1024", "size": 98500 }
]
}
| Câmp | Descriere |
|---|---|
id | ID-ul intern al fișierului |
externalId | ID-ul tău din CRM |
optimization | Statusul optimizării |
blurhash | String pentru generarea placeholder-ului |
originalUrl | Link către original |
variants | Versiuni optimizate de diferite dimensiuni |
Endpoint-uri API
| Metodă | Cale | Descriere |
|---|---|---|
POST | /media/upload-from-url | Import după URL |
POST | /media/bulk | Operații bulk (upload-from-url, confirm-upload, etc.) |
POST | /media/request-upload-url | Signed URL |
GET | /media/:id | Obține fișier |
GET | /media/external/:externalId | Obține după external ID |
DELETE | /media/:id | Șterge fișier |
DELETE | /media/external/:externalId | Șterge după external ID |
POST | /media/:id/link | Leagă external ID |
DELETE | /media/:id/link | Dezleagă external ID |
Pașii următori
- Încarcă fotografii — instrucțiuni pas cu pas
- Gestionare fișiere — obținere, ștergere, linking