Brani Balič - napojení přes API

Napojení Vašeho systému na expediční software Brani Balič se skládá ze 3 částí:

• Posílání informací o e-shopu
• Posílání objednávek
• Webhooky pro získání informací zpět

Používáte Shoptet, Upgates, Money alebo Flexi? Napojení máme hotové, ozvěte se nám na support@brani.cz.

Informace o e-shopu

Abychom mohli korektně pracovat s Brani Baličem pro Váš e-shop, potřebujeme mít některé základní údaje o Vašem e-shopu, jako jsou dopravy, platby, stavy objednávek a podobně.

Není nutné, aby tyto číselníky byly přesně totožné s Vaším e-shopem, v mnohých případech se hodí je upravit.

Volat tento endpoint stačí jen v případě, kdy se něco změnilo.

• GET endpoint na získání aktuálních dat (vrátí null, když k nám nic nepošlete)
• POST endpoint pro aktualizaci dat

Ukázka API volání

import requests
url = "https://api.brani.cz/eshop/info"
headers = {
    "Authorization": "Bearer VAS_TOKEN"
}
response = requests.get(url, headers=headers)
print(response.json())

Objednávky

Objednávky k nám posílejte ve formátu JSON. Dostupné jsou tyto endpointy:

• POST endpoint pro upsert objednávky (unikátní identifikátor objednávky je "code". Jestliže pošlete víc requestů s totožným "code", budeme danou objednávku aktualizovat)
• DEL endpoint pro mazání objednávky

Prosím, projděte si hlavní schéma (nikoliv jen sample), kde jsou uvedeny všechny dostupné atributy objednávky.

Webhooky

Abyste získali z Brani Baliče informace o tom, co se s objednávkou děje, je potřeba implementovat webhooky. Podporujeme 4 hlavní typy webhooků (balic_packed, package_number, status_change a order_history).

Není nutné implementovat všechny webhooky, pokud je nepotřebujete. Jakmile pošleme webhook, očekáváme návratový kód 200. Pokud neobdržíme kód 200, zkusíme to za chvíli znovu. Celkově děláme 3 pokusy o poslání webhooku.

Veškeré eventy je možné si i vypsat přes tento endpoint, kde si můžete vypsat například pouze nedoručené webhooky, abyste si dosynchronizovali eventy, které se Vám nepodařilo doručit.

Aplikační API

Jestliže potřebujete přesnější informace z Brani Baliče, tak je možné získat prakticky vše, co je k dispozici na balic.brani.cz. Naše aplikace používá API, které můžete také používat.

Dokumentaci najdete zde. Případně sledujte síťovou komunikaci v prohlížeči během toho, když pracujete v této aplikaci. Náš frontend s tímto API pracuje.

Autorizace

S tímto API se nepoužívá ten stejný token, jako v případě veřejného API, ale přihlašuje se přes e-mail a heslo na našem auth serveru, který Vám token vygeneruje s omezenou platností.

Ideálně si tedy přidejte nového uživatele jen pro obsluhu API. Potencionálně můžete přes toto API kompletně například balit objednávky, tento uživatel bude zapsaný v logu změn.
Zde je dokumentace k auth API.

Ukázka API volání

V tomto Python skriptu je ukázka získání tokenu přes auth a použití v endpointu na získání nastavení Brani Baliče.

import requests

# URL pro přihlášení
login_url = 'https://auth.brani.cz/api/login/'

# Data pro přihlášení
login_data = {
    'username': 'meno@mail.cz',
    'password': 'heslo'
}

# Přihlášení a získání access tokenu
response = requests.post(login_url, data=login_data)
response_data = response.json()
access_token = response_data.get('access_token')

# Pokud je access token dostupný, pokračujeme s GET požadavkem
if access_token:
    settings_url = 'https://balic.brani.cz/api/settings/?calculate_filters=true'
    headers = {
        'Authorization': f'Bearer {access_token}'
    }
    settings_response = requests.get(settings_url, headers=headers)
    settings_data = settings_response.json()
    print(settings_data)
else:
    print("Nepodařilo se získat access token.")