# Úvod k Chameleoon API integrácii pre expedičné systémy
Táto dokumentácia popisuje integráciu <a href="https://www.chameleoon.sk" target="_blank" >expedičného systému Chameleoon</a>  cez API. Umožňuje vám automaticky vytvárať zásielky, <a href="https://www.chameleoon.sk/hromadna-expedicia/" target="_blank" >tlačiť prepravné štítky</a> a <a href="https://www.chameleoon.sk/sledovanie-zasielok/" target="_blank" >sledovať stav doručenia</a> priamo z vášho e-shopu — bez nutnosti manuálneho prepisovania údajov. API integrácia je vhodná pre vývojárov, ktorí chcú napojiť e-shop (<a href="https://www.chameleoon.sk/podporovane-zdroje/shoptet/" target="_blank" >Shoptet</a>, <a href="https://www.chameleoon.sk/podporovane-zdroje/woocommerce/" target="_blank" >WooCommerce</a>, <a href="https://www.chameleoon.sk/podporovane-zdroje/upgates/" target="_blank" >Upgates</a> a ďalšie) na kuriérov <a href="https://www.chameleoon.sk/podporovani-dopravcovia/gls/" target="_blank" >GLS</a>, <a href="https://www.chameleoon.sk/podporovani-dopravcovia/dpd/" target="_blank" >DPD</a>, <a href="https://www.chameleoon.sk/podporovani-dopravcovia/packeta/" target="_blank" >Packeta</a> a iných podporovaných prepravcov.

## Autentifikácia

Chameleoon API používa dva rôzne spôsoby autentifikácie v závislosti od typu API.

### Verejné API (Public API)

Verejné API endpointy používajú hlavičku `X-Chameleoon-ApiKey` pre autentifikáciu na úrovni partnera/účtu.

```
X-Chameleoon-ApiKey: <váš-api-kľúč>
```

API kľúče môžete spravovať v aplikácii Chameleoon na stránke nastavení API. Tu môžete:
- Zobraziť existujúce API kľúče
- Vytvoriť nové API kľúče
- Deaktivovať alebo odstrániť existujúce kľúče

### Privátne API (Private API)

Privátne API endpointy vyžadujú **Bearer token** v hlavičke `Authorization`. Tieto endpointy sa používajú pre správu účtov, fakturáciu a spracovanie platieb.

Pre získanie tokenu:
1. Kontaktujte podporu Chameleoon pre získanie M2M prihlasovacích údajov (`clientId` a `clientSecret`)
2. Zavolajte `POST https://apis.chameleoon.sk/api/auth/m2m` s vašimi údajmi
3. Použite vrátený `accessToken` v hlavičke `Authorization: Bearer <token>`

```
Authorization: Bearer <váš-access-token>
```

Tokeny majú obmedzenú platnosť indikovanú hodnotou `expiresIn` (v sekundách). Pred vypršaním platnosti si vyžiadajte nový token.

## Request ID

Každá odpoveď z Chameleoon API obsahuje hlavičku `Request-Id` s jedinečným identifikátorom požiadavky.

### Použitie pri komunikácii s podporou

V prípade problémov alebo otázok týkajúcich sa konkrétnej požiadavky uveďte Request ID pri kontaktovaní našej podpory. Tento identifikátor nám umožní:
- Rýchlo nájsť konkrétnu požiadavku v systéme
- Analyzovať detaily spracovania požiadavky
- Diagnostikovať príčinu problému
- Poskytnúť vám čo najrýchlejšie riešenie

Request ID nájdete v response headers každej API odpovede.

## Všeobecné funkcie API

### Stránkovanie (Pagination)

API podporuje stránkovanie výsledkov pomocou query parametrov:
- `page` - číslo stránky (predvolené: 1, minimum: 1)
- `pageSize` - počet položiek na stránku (predvolené: 50, maximum: 50)

Odpoveď obsahuje informácie o stránkovaní:
- `page` - aktuálne číslo stránky
- `pageSize` - počet položiek na stránke
- `totalPages` - celkový počet stránok
- `nextPage` - či existuje ďalšia stránka
- `previousPage` - či existuje predchádzajúca stránka
- `itemsCount` - celkový počet položiek
- `result` - pole výsledkov

### Lokalizácia

API podporuje lokalizáciu pomocou hlavičky `Accept-Language`:
- **Podporované jazyky:** sk, cz, en
- **Predvolený jazyk:** sk

Hlavička ovplyvňuje jazyk chybových hlášení a validačných správ vrátených API.

## Zoznam podporovaných prepravcov

Chameleoon API podporuje nasledujúcich prepravcov:

| ID | Názov |
|----|-------|
| cargus | Cargus |
| cp | Česká pošta |
| depo | Depo |
| dhl | DHL Express |
| dpd | DPD |
| dpdat | DPD AT |
| dpdcz | DPD CZ |
| dpdpl | DPD PL |
| geis | Geis |
| gls | GLS |
| neoship | Neoship |
| own-transport | Vlastná doprava |
| packeta | Packeta |
| pbh | Pošta bez hraníc |
| ppl | PPL |
| sds | SDS |
| sp | Slovenská pošta |
| sps | SPS |
| toptrans | Toptrans |
| wedo | WEDO |
| fan | FAN |
| inpost | InPost |
| qdl | QDL |
| expressone | Express One |
| mp | Magyar Posta |
| futar | Futár |
| foxpost | FoxPost |
| eushipments | EU Shipments |
| brt | BRT |
| dp | DHL DE |
| ups | UPS |
| boxpi | Boxpi |
| postasi | Slovinská pošta |
| easyship | DPD HR - SI |
| dpdhu | DPD HU |
| glspl | GLS PL |
| vhl | VHL |
| deliveo | Deliveo |
| pttexpress | PTT Express |
| raben | Raben |

Detailné informácie o funkciách jednotlivých prepravcov nájdete v dokumentácii API.

## Základný pracovný postup s API

Typický pracovný postup s Chameleoon API pozostáva z troch krokov:

### 1. Získanie zoznamu konfigurácií prepravcov

Prvým krokom je získať zoznam dostupných konfigurácií prepravcov pre váš účet. Každý prepravca môže mať viacero profilov (konfigurácií) nastavených v aplikácii Chameleoon.

Odpoveď obsahuje ID prepravcu (`courierId`) a zoznam profilov s ich identifikátormi (`profileId`). Tieto dve hodnoty budete potrebovať pri vytváraní zásielok.

### 2. Vytvorenie zásielky

S použitím ID prepravcu (`courierId`) a ID profilu (`profileId`) vytvoríte zásielku odoslaním údajov o príjemcovi, balíku a ďalších potrebných informácií.

Po úspešnom vytvorení zásielky dostanete späť prepravné číslo (`shippingNumber`), ktoré identifikuje zásielku v systéme prepravcu a slúži na sledovanie stavu doručenia.

### 3. Tlač štítkov

Po úspešnom vytvorení zásielky môžete vytlačiť prepravné štítky. API vráti PDF súbor so štítkami, ktoré nalepíte na balíky.

Pri tlači môžete špecifikovať formát štítkov (A4, A6) a pozíciu prvého štítku na stránke.

---

Podrobné informácie o jednotlivých endpointoch, parametroch a formátoch požiadaviek nájdete v dokumentácii API v2 alebo API v1.