Přístup k souborům
K souborům (dokumentů) uloženým v CRM se můžete dostat dvěma způsoby. Prvním je přístup přes globální koncový bod /api/files, který umožňuje přistupovat k souborům nezávisle na tom, ke kterému záznamu jsou připojeny. Druhý způsob je přes endpoint pod jiným záznamem (příležitost, kontakt, apod.), což umožňuje získat soubory, které jsou připojeny (attachments) k nějakému záznamu v CRM.
Např.: /api/parties/241/files zpřístupňuje soubory připojené ke kontaktu s kódem 241. Obdobně /api/opportunities/1602/files zpřísupňuje soubory připojené k příležitosti s kódem 1602, atd. V dalším textu budeme používat URL <record_endpoint>/files pro přístup k souborům, připojeným k záznamu adresovanému koncovým bodem <record_endpoint>.
Pokud za <record_endpoint> dosadíte koncový bod /api, budete přistupovat k souborům globálně.
GET <record_endpoint>/files
Získání seznamu souborů/dokumentů, které jsou připojeny k záznamu
| Query parametr | Typ | Popis | Výchozí |
|---|---|---|---|
orderBy | string | podle jakého údaje mají být vrácené záznamy řazeny | modified |
desc | boolean | pořadí řazení je sestupné | true |
Odpověď (application/json)
200 OK
V těle odpovědi je stránka s metadaty k souborům. Záznamy nebudou obsahovat vlastnost data s tělem souboru.
GET <record_endpoint>/files/{fid}
Získání jednoho souboru, připojeného k záznamu.
| Query parametr | Typ | Popis | Výchozí |
|---|---|---|---|
data | boolean | příznak, jestli má API vrátit tělo souboru JSONu | false |
Odpověď (application/json)
200 OK
V těle odpovědi budou metadata k souborům a pokud byl použit parametr data=true, tak bude JSON obsahovat i vlastnost data, ve které bude string s Base64 kódovanými daty těla souboru. Alternativní způsob, jak získat tělo souboru je použít následující koncový bod
404 NOT FOUND
Soubor s kódem {fid} neexistuje.
403 FORBIDDEN
Autentizovaný uživatel nemá dostatek práv, aby mohl číst požadovaný soubor.
GET <record_endpoint>/files/{fid}/content
Získání obsahu souboru.
Odpověď (*/* Content-Type odpovídající danému souboru)
200 OK
V těle odpovědi bude obsah souboru.
404 NOT FOUND
Soubor s kódem {fid} neexistuje.
403 FORBIDDEN
Autentizovaný uživatel nemá dostatek práv, aby mohl číst požadovaný soubor.
POST <record_endpoint>/files
Připojení nového souboru k záznamu.
Požadavek (*/* Content-Type odpovídající danému souboru)
| Query parametr | Typ | Popis | Výchozí |
|---|---|---|---|
name | string | jméno souboru, který se má vytvořit | - viz. níže - |
folder | string | cesta k adresáři v CRM, kam se má soubor umístit | - viz. níže - |
read | string | pokud má být přístup k souboru omezen pro čtení, použijte loginname uživatele v tomto parametru | bez omezení |
write | string | pokud má být přístup k souboru omezen pro zápis, použijte loginname uživatele v tomto parametru | bez omezení |
annotation | string | textový popis k souboru (max. 255 znaků) | - |
public | boolean | příznak, jestli bude tento soubor veřejně dostupný | false |
Každý uploadovný soubor musí být pojmenován. Koncový bod určí jméno souboru tak, že nejprve zjistí přítomnost parametru name, pokud chybí, zjišťuje obsah standardní HTTP hlavičky Content-Disposition (parametr hlavičky filename). Pokud ani tam není žádný název, vygeneruje se název podle aktuálního datumu a času.
Soubory, které začínají na logo-, face- nebo avatar- mohou být v budoucnosti použity pro obrázky s logem firmy, fotkou osoby nebo avatarem osoby. Nepoužívejte je pro jiné, než tyto účely. Takový soubor musí mít Content-Type ve tvaru image/*.
Není vhodné uploadovat soubory do kořenového adresáře, a proto je k dispozici parametr folder, který může obsahovat absolutní nebo relativní cestu k adresáři v interním úložišti dokumentů v CRM. Pokud je cesta relativní, interpretuje se jako relativní vůči domovskému adresáři uživatele, který soubor uploaduje. Pokud parametr folder chybí úplně, soubor bude umístěn přímo do domovského adresáře volajícího uživatele.
Odpověď (application/json)
201 OK CREATED
Soubor byl úspěšně uploadován a byl připojen k záznamu. V těle odpovědi budou metadata nového souboru.