API

Pro jednoduché integrace doporučujeme používat integraci pomocí make.com, kterou pravidelně udržujeme.

Pokud chcete naprogramovat vlastní integraci, zde naleznete základní potřebné informace.

Základní informace

Costlocker obsahuje aktuálně 2 API - Rest a GraphQL.

REST API

Původní API Costlockeru, jejíž provoz bude ukončen k 31. Březnu 2025.

Původní dokumentaci naleznete na Apiary 🔗.

Pokud potřebujete pomoci s migrací na novou API, prosím kontakujte náš support.

GraphQL

Nově Costlocker používá GraphQL API, která pohání náš Frontend - můžete tedy pomocí ní dělat cokoliv, co je dostupné v uživatelském rozhraní.

GraphQL dokumentace je dostupná přímo na endpointu samotné API - https://api.costlocker.com/graphql 🔗

Autorizace

GraphQL API využívá dvě možnosti autorizace

API Token

Základní forma, která využívá pro autorizaci Osobní API Token. Pro autorizaci je nutné použít následující hlavičku:

Authorization: Static ${PERSONAL_API_TOKEN}

JWT Token

Druhá varianta využívá JWT Token, generovaný backendem po přihlášení (mutace Login). Ta využívá set dvou hlaviček

Authorization: JWT ${JWT_TOKEN}
Person-Id: ${personId}

U JWT Tokenu se využívá v hlavičce dále Person-Id, jelikož Costlocker je multi-tenant platforma, můžete mít tedy dostupných více účtů pod jedním přihlášením. Person ID je ID z modulu Lidé (viditelné v URL parametru).

Deprecation a warning handling

U GraphQL API se nevyužívá verzování, ale označování jednotlivých query / mutací nebo atributů jako deprecated a následně jejich odebrání.

Pro sledování těchto změn doporučujeme implementaci logování warningů do logovacího nástroje, např. Sentry 🔗.

Veškeré odpovědi z Costlocker API mohou obsahovat Extensions 🔗 s atributem warnings.

Warnings pak obsahuje informaci o ukončení podpory vámi využívaných Queries / Mutací nebo jejich atributů:

{
    "data": ...,
    "error": ...,
    "extras": null | {
        "warnings": null | string
    }
}

Deprecation informace jsou pak ve formátu

DEPRECATED: Field ${FIELD_NAME} is deprecated: ${DEPRECATION_DETAILS}

Např.

DEPRECATED: Field revenue_loss is deprecated: Use field metrics.revenue_loss instead. Will be removed on 03/31/2025.

Migrace na GraphQL ještě není dokončena - pokud nenaleznete potřebný endpoint, který by byl ekvivalentem pro původní Rest API, prosím kontaktujte nás.