PRO VÝVOJÁŘE A INTEGRÁTORY

Dokumentace API

MaltAI má veřejné API s tokeny: připomínky k modelu v otevřeném formátu BCF do něj nahrajete i z něj stáhnete. MaltAI přitom pracuje nad stejnými daty jako Autodesk Forma — a v tomhle rozcestníku najdete i cestu k jejímu API.

Začít s API tokeny Autodesk Forma (dříve ACC)

01API tokeny

Token si vytvoříte sami.

Token vytvoříte v aplikaci: Nastavení → záložka API tokeny. Zaškrtnete jen oprávnění, která integrace potřebuje — mezi nimi „Nahrávat soubory BCF do vad“ (bcf:write) a „Stahovat vady jako soubor BCF“ (bcf:read).

Token se posílá v hlavičce Authorization: Bearer <token>. Přístup token nerozšiřuje: platí stejná práva jako v aplikaci — členství v projektu a úroveň přístupu v modulu Vady.

Příklad

# stažení vad projektu jako soubor BCF
curl -H "Authorization: Bearer $MALTAI_TOKEN" \
  -o vady.bcfzip \
  "https://maltai.cz/api/projects/{id}/defects/bcf/export"

bcf:write: Nahrávat soubory BCF do vad · editor
bcf:read: Stahovat vady jako soubor BCF · čtení

02Import BCF

Připomínky z modelu rovnou do vad.

Soubor s připomínkami (.bcf nebo .bcfzip, formát BCF 2.0, 2.1 i 3.0, nejvýš 40 MiB) nahrajete na adresu projektu. Každé téma se stane vadou, komentáře se přenesou, snímky se uloží jako fotky a prvky modelu se přiřadí podle IFC GUID. Opakovaný import téhož tématu vadu aktualizuje, nezdvojí.

U projektu propojeného s Autodesk Forma (dříve ACC) se vada hned založí i jako Issue ve Formě se špendlíkem na prvku — u modelů IFC i Revit.

POSThttps://maltai.cz/api/projects/{id}/defects/bcf/import

GEThttps://maltai.cz/api/projects/{id}/defects/bcf/import/{jobId}

soubor: Pole multipart formuláře se souborem .bcf / .bcfzip (BCF 2.0, 2.1, 3.0; nejvýš 40 MiB).
rezim: Nepovinné pole formuláře. rezim=nahled = jen náhled: odpověď 200 s přehledem, co by import udělal (nová vada / aktualizace / přeskočeno), nic se nezapíše. Bez pole se import provede. Jiná hodnota je chyba 400.
Idempotency-Key: Hlavička, nepovinná.
Odpověď: 202 s { "jobId": "…" }. Průběh zjistíte dotazem GET …/defects/bcf/import/{jobId}; stavy: PRIPRAVENO, BEZI, HOTOVO, CHYBA.
Oprávnění: Token s bcf:write; úroveň v modulu Vady: editor.
Limit: 10 importů za hodinu; v projektu běží nejvýš jeden import najednou (druhý dostane 409 s jobId běžícího).

Příklad

curl -X POST "https://maltai.cz/api/projects/{id}/defects/bcf/import" \
  -H "Authorization: Bearer $MALTAI_TOKEN" \
  -F "soubor=@pripominky.bcfzip"
# → 202 {"jobId":"…"}

# jen náhled, nic se nezapíše
curl -X POST "https://maltai.cz/api/projects/{id}/defects/bcf/import" \
  -H "Authorization: Bearer $MALTAI_TOKEN" \
  -F "soubor=@pripominky.bcfzip" -F "rezim=nahled"

curl -H "Authorization: Bearer $MALTAI_TOKEN" \
  "https://maltai.cz/api/projects/{id}/defects/bcf/import/{jobId}"

03Export BCF

Vady zpět jako BCF.

Vady projektu stáhnete jako soubor BCF — přes API, nebo tlačítkem „Stáhnout jako BCF“ v seznamu vad. Export obsahuje vady z MaltAI i Issues z Autodesk Forma (dříve ACC) a stejnou věc nevypíše dvakrát.

Výchozí je BCF 2.1; volitelně 3.0. Pro import do Autodesk Forma slouží cíl forma.

GEThttps://maltai.cz/api/projects/{id}/defects/bcf/export

verze: 2.1 (výchozí) nebo 3.0.
cil: obecny, nebo forma — soubor pro import v Autodesk Forma: vždy BCF 2.1; vynechá vady, které už mají Issue ve Formě; nejvýš 100 témat (jinak chyba 422); stav jen Open / Closed; u tématu nejvýš jeden prvek; snímek nejvýš 1 500 px.
forma: ano / ne — přidat Issues z Autodesk Forma, které nejsou propojené s vadou.
status severity category q: Filtry stejné jako v seznamu vad. Stav: OPEN, IN_PROGRESS, RESOLVED, CLOSED.
rezim=nahled: Místo souboru vrátí JSON přehled toho, co by export obsahoval (počet témat, co se vynechalo a proč, varování).
Oprávnění: Token s bcf:read; úroveň v modulu Vady: čtení.

Příklad

# soubor BCF 3.0 s otevřenými vadami
curl -H "Authorization: Bearer $MALTAI_TOKEN" \
  -o vady.bcfzip \
  "https://maltai.cz/api/projects/{id}/defects/bcf/export?verze=3.0&status=OPEN"

04Online BCF-API

Připravujeme

Online BCF-API

Další způsob výměny připomínek — přímo online, bez předávání souborů — připravujeme. Zatím použijte import a export souborů BCF popsané výše.

05Autodesk Forma (dříve ACC)

API Autodesk Forma — rozcestník.

MaltAI pracuje nad stejnými daty jako Autodesk Forma (dříve ACC). Pokud potřebujete s těmi daty pracovat přímo, tady je k jednotlivým oblastem jedna věta a odkazy na oficiální dokumentaci Autodesku. Platí pro ni podmínky a verze, které Autodesk sám zveřejňuje.

Přístup k API

MaltAI pracuje nad stejnými daty přes totéž API Autodesku, které je k dispozici i vám — stačí čtyři kroky.

01Zaregistrujte aplikaci u Autodesku (Autodesk Platform Services) — získáte Client ID a Client Secret.
02Povolte ji ve správě Autodesk Forma — správce účtu ji přidá jako vlastní integraci (Custom Integrations) podle Client ID.
03Získejte token OAuth 2.0 — dvounohý (aplikace sama) nebo třínohý (jménem uživatele).
04Volejte API s tokenem v hlavičce Authorization: Bearer.

Přehled Forma APIs Registrace aplikace (Create an App)Povolení aplikace ve správě účtu (Custom Integrations)Token OAuth 2.0 (třínohý)Základy API a druhy tokenů

Přístup ke všem projektům

Seznam projektů účtu vrací Hub Admin API (správci účtu všechny projekty) a Data Management API (projekty, kam má uživatel přístup).

Hub Admin — GET accounts/:account_id/projects Hub Admin API — průvodce Data Management — GET hubs/:hub_id/projects

Přístup ke všem složkám a dokumentům

Strom složek procházíte od horních složek přes obsah složek a verze položek až ke stažení souboru.

GET …/topFolders GET …/folders/:folder_id/contents GET …/items/:item_id/versions Stažení souboru (Files)

Čtení a zápis metadat dokumentů

Vlastní atributy dokumentů se čtou a zapisují přes rozhraní Files — Custom Attributes, které Autodesk zatím vede jako beta.

POST custom-attributes:batch-update (zápis hodnot, beta)POST versions:batch-get (čtení hodnot)Definice atributů na úrovni projektu (blog Autodesku)

Workflow dokumentů

Schvalovací workflow (Reviews) lze vytvářet, spouštět jako revize, sledovat jejich průběh a číst schvalovací stavy souborů.

POST workflows POST reviews Průběh revize (progress) a approval-statuses GET reviews

Export dokumentů v původní struktuře složek

Strom projdete od horních složek do hloubky a každý soubor uložíte do stejné cesty u sebe — tři kroky:

01Načtěte horní složky projektu (topFolders).
02Rekurzivně načtěte obsah složek (contents) a zapamatujte si cesty.
03U každého souboru stáhněte aktuální verzi a uložte ji do odpovídající složky.

GET …/folders/:folder_id/contents Stažení souboru (Data Management)

Správa oprávnění podle skupin

Oprávnění ke složkám nastavíte hromadně (batch-create / update / delete) pro uživatele, firmy i role (subjectType USER, COMPANY, ROLE); členy projektu spravuje Hub Admin.

Folder Permission API — oznámení a popis POST …/permissions:batch-create POST …/permissions:batch-update Hub Admin — GET projects/:projectId/users

06Kontakt

Něco v dokumentaci chybí?

Napište nám, s čím potřebujete pomoci — k API MaltAI i k napojení na Autodesk Forma.

Kontakt najdete v patičce Všechny produkty

MaltAI

PRO VÝVOJÁŘE A INTEGRÁTORY