# Úvod k API Returns

API systému Zaslat Returns slouží k automatizaci správy servisních zakázek — vytváření a úpravě
zakázek, objednávání dopravy k nim a čtení jejich stavu — bez nutnosti používat správní rozhraní.

:::info

Kompletní referenci endpointů, parametrů a datových schémat najdete v [API Referenci](/returns-api).
Tato stránka doplňuje kontext, který se do referenční dokumentace nehodí — prostředí, přístup a
byznysová pravidla.

:::

## Přístup k webovému prostředí (správa zakázek)

### Testovací prostředí

Pro přihlášení k webovému rozhraní použijte přístupové údaje uvedené níže v sekci
[Autentizace](#autentizace) a přihlaste se na adrese [returns-demo.zaslat.cz/admin](https://returns-demo.zaslat.cz/admin).

### Ostré prostředí

Pro přístup k ostrému prostředí použijte URL vaší společnosti a přístupové údaje servisního
střediska nebo správce (např. `nokia.zaslat.cz/admin`). API klíč pro ostré prostředí najdete ve
správním rozhraní podle informací níže.

## Přístup k API rozhraní

**Produkční** API je dostupné na URL:

```
https://<název společnosti>.zaslat.cz/api/v1/<resource>
```

**Testovací** API je dostupné na URL:

```
https://returns-demo.zaslat.cz/api/v1/<resource>
```

:::warning

Veškeré změny provedené v testovacím prostředí se každou noc mažou a prostředí je znovu vytvořeno.

:::

## Autentizace

Všechny požadavky na API je nutné posílat s autentizačním HTTP headerem `x-apikey`.

Váš API klíč pro **produkční** prostředí najdete ve správě svého účtu v sekci **API**.

Pro přístup k **testovacímu** API použijte testovací účet s následujícími přístupovými údaji:

```
E-mail: apitest@apitest.cz
Heslo: apitest
API klíč: 72xfT62wIlttqh06imGrjTrxn69kk1DAz9o5ITso
```

## Typický postup integrace

1. Zákazník/servis vytvoří zakázku (`POST /commissions/create`) — u záruční zakázky nejdřív
   nahrajte doklad o nákupu (`POST /commissions/upload-file`) a jeho `token` vložte do
   `invoice_file_token`.
2. Pokud zakázka obsahuje dopravu od zákazníka (`shipment_from_customer: true`), po doručení
   zásilky do servisu se zakázka automaticky přepne do stavu `processing`.
3. Servisní středisko doplňuje průběh přes aktivity (`POST /activity/create`) — veřejné zprávy
   pro zákazníka i interní poznámky.
4. Po dokončení servisu se objedná odchozí zásilka úpravou zakázky
   (`POST /commissions/edit` s `shipment_to_customer: true` a stavem `outgoing`).
5. Stav a historii zakázky lze kdykoli ověřit přes `GET /commissions/{id}` nebo vylistovat přes
   `GET /commissions`.

Modely a kategorie výrobků potřebné při vytváření zakázky získáte přes `GET /product-model` a
`GET /product-type`.

:::note

Zakázku lze vytvořit i bez dopravy od zákazníka (`shipment_from_customer: false`) — jde o
**jednosměrnou** zakázku, typicky když zákazník výrobek přinesl osobně a stačí mu jej jen zaslat
zpět po opravě. **Obousměrná** zakázka obsahuje dopravu v obou směrech.

:::