Fișiere media

Acest capitol explică fluxul pentru imagini și resurse media: verificarea existenței fișierelor, încărcarea prin addFile, formatul conținutului media și sincronizarea listei de fișiere.

Flux recomandat

1. Publică sau actualizează oferta prin saveProperty.
2. Verifică dacă fișierul există deja prin existsFile.
3. Încarcă fișierul lipsă prin addFile.
4. Sincronizează lista finală prin syncFiles, dacă vrei ca oferta să păstreze doar fișierele transmise în FILE_IDS.

Nu apela addFile sau syncFiles pentru o ofertă care nu a fost creată cu succes prin saveProperty. Dacă oferta lipsește, operațiile media pot răspunde cu erori de tip Property not found sau cu warnings despre FILE_IDS invalide.

existsFile verifică starea fișierului, nu existența ofertei. Pentru o ofertă inexistentă poate răspunde cu _isValid = true, photo = false și _data.exists = false.

Câmpuri pentru addFile

Pentru addFile, câmpurile fișierului se transmit direct în options, fără structură imbricată:

• AGENTIA - ID-ul agenției autorizate pentru publicare.
• ID_LOCAL - identificatorul numeric al ofertei la care se atașează fișierul.
• FILE_ID - identificatorul unic al fișierului.
• FILE_TITLE - titlul sau descrierea fișierului.
• FILE_BODY - conținutul imaginii în Base64 brut, generat din conținutul binar.
• FILE_URL - URL HTTP/HTTPS al sursei imaginii; poate fi folosit în loc de FILE_BODY pentru imagini, sau împreună cu FILE_TYPE = "youtube" pentru video YouTube.
• FILE_TYPE - opțional; folosește image/images pentru imagini sau youtube pentru linkuri YouTube.
• ORDER - poziția fișierului în lista media a ofertei.

Pentru imagini trebuie să trimiți cel puțin una dintre valorile FILE_BODY sau FILE_URL. FILE_BODY nu acceptă prefixe Data URI precum data:image/jpeg;base64,.

FILE nu este câmp pentru addFile; structura FILE.ID se folosește la deleteFile.

Formatul identificatorilor de fișier

FILE_ID și valoarea corespunzătoare FILE.ID trebuie să fie identificatori ASCII stabili, de maximum 100 de caractere. Folosește un identificator alfanumeric sau un UUID; forma recomandată acceptă numai litere ASCII, cifre și cratimă: ^[A-Za-z0-9-]+$.

Nu folosi text liber, spații, diacritice, bare / sau \, caractere de control ori caractere specifice URL-urilor și interogărilor, precum ?, &, # și =. Păstrează exact aceeași valoare pentru același fișier în addFile, existsFile, deleteFile și syncFiles.

Câmpuri pentru deleteFile

Pentru ștergerea unei imagini atașate, folosește deleteFile cu:

• AGENTIA - ID-ul agenției.
• ID_LOCAL - identificatorul ofertei.
• FILE.ID - identificatorul fișierului de șters. În fluxul obișnuit acesta este FILE_ID trimis la addFile, respectiv valoarea photo_id returnată de răspunsul addFile.

După ștergere, poți confirma rezultatul prin existsFile; pentru fișierul șters răspunsul trebuie să indice exists = false.

Câmpuri pentru existsFile

Folosește existsFile înainte de addFile ca să eviți reîncărcarea aceleiași imagini:

• AGENTIA - ID-ul agenției.
• ID_LOCAL - identificatorul ofertei.
• FILE_ID - identificatorul stabil al fișierului în sistemul sursă.

Câmpuri pentru syncFiles

După încărcarea imaginilor, trimite lista finală prin syncFiles:

• AGENTIA - ID-ul agenției.
• ID_LOCAL - identificatorul ofertei.
• FILE_IDS - lista fișierelor care trebuie să rămână în galeria ofertei, transmisă ca string.

syncFiles este o operație de reconciliere: fișierele care nu apar în FILE_IDS pot fi eliminate din galeria ofertei.

Serverul acceptă mai multe formate pentru FILE_IDS: array PHP serializat, JSON array, obiect JSON de forma {"ids":[...]} sau listă text separată prin virgulă, punct și virgulă, bară verticală ori spații. Pentru compatibilitate cu integrarea existentă, formatul folosit frecvent este array PHP serializat.

Trimite în FILE_IDS doar identificatori de fișiere care au fost acceptați anterior pentru aceeași ofertă. Dacă lista conține fișiere care nu există pe ofertă, răspunsul poate include warnings de tip No valid FILE_IDs found in input.

Un warning la syncFiles nu înseamnă întotdeauna eșec SOAP. Verifică explicit _warnings chiar dacă _isValid este true, mai ales când reconcilierea nu găsește niciun FILE_ID valid.

Răspunsul poate include trebuie_trimise în _success.0.result. Lista conține identificatori de fișiere care trebuie retrimiși prin addFile, de obicei pentru imagini care lipsesc sau nu au fost reconciliate corect după apelul syncFiles.

Exemplu de structură relevantă în răspuns:

{
  "_success": [
    {
      "result": {
        "trebuie_trimise": [101, 102]
      }
    }
  ]
}

Pentru lista operațiilor SOAP asociate, vezi Operații API. Pentru fluxul complet de publicare și sincronizare, vezi Sincronizare.