Webhooky dobropisů umožňují automatické odesílání informací o vytvořených dobropisech do vašeho systému. Díky této funkcionalitě můžete snadno zpracovávat a evidovat dobropisy vytvořené v Retinu přímo ve vašem vlastním systému.
Aktivace funkcionality
V administraci Retino přejděte do Nastavení > Marketplace
Aktivujte doplněk Webhooky dobropisů
Po aktivaci přejděte na detail doplňku kliknutím na tlačítko Spravovat
Zadejte URL adresu vašeho endpointu, kam budeme odesílat data o dobropisech
Klikněte na tlačítko Uložit
Důležité: Pro správné fungování webhooků je nutné na vaší straně implementovat příjem dat ve formátu popsaném níže.
Formát dat webhooků
Webhooky dobropisů využívají standardní systém webhooků v Retinu s event_type retino_credit_note.created . Příklad struktury dat:
{
"created_at": "2023-04-04T09:00:19.249525+00:00",
"event_type": "retino_credit_note.created",
"credit_note": {
"id": "5cae6caf-c1cb-49ed-96bd-2d2837765ffc",
"ticket_id": "5cae6caf-c1cb-49ed-96bd-2d2837765ffc",
"stock": true,
"currency": "CZK",
"language": "cs",
"order_id": "2022000001",
"variable_symbol": "2022000001",
"bank_account": {
"type": "CZECH_BANK_ACCOUNT",
"czech_bank_account": "123456789/0100"
},
"customer": {
"city": "Praha",
"name": "Jakub Novák",
"street": "Hradní",
"country": "CZ",
"postal_code": "11000",
"house_number": "1",
"company_id": "(ičo společnosti, může být prázdné)",
"company_vat_number": "(dič společnosti, může být prázdné)"
},
"lines": [
{
"id": "9ff867e8-7f90-4c54-9d65-9212ceceae76",
"name": "Macbook PRO",
"price": 39900,
"vat_rate": 0.21,
"amount": 1,
"variant": "Space black",
"product_id": "MAC_PRO_2023"
}
]
}
}Popis datové struktury
Webhook obsahuje následující hlavní části:
created_at - datum a čas vytvoření události
event_type - typ události (vždy "retino_credit_note.created")
credit_note - objekt obsahující data o dobropisu
Struktura objektu credit_note:
id - unikátní identifikátor dobropisu
ticket_id - ID případu v Retinu, ke kterému se dobropis vztahuje
stock - boolean hodnota určující, zda dobropis ovlivňuje skladové zásoby
currency - měna dobropisu (ISO kód, např. "CZK", "EUR")
language - jazyk dobropisu (ISO kód, např. "cs", "en")
order_id - ID objednávky, ke které se dobropis vztahuje
variable_symbol - variabilní symbol pro identifikaci platby
bank_account - objekt s informacemi o bankovním účtu
customer - objekt s informacemi o zákazníkovi
lines - pole objektů s položkami dobropisu
Implementace na vaší straně
Pro úspěšnou implementaci webhooků dobropisů je potřeba:
Vytvořit endpoint na vašem serveru, který bude přijímat HTTP POST požadavky
Implementovat zpracování příchozích dat ve formátu JSON
Ověřit autenticitu požadavku pomocí hlavičky X-Retino-Secret (více v dokumentaci webhooků)
Odpovědět na požadavek se stavovým kódem 2xx v časovém limitu 10 sekund
Tip: Pro testování příjmu webhooků můžete použít služby jako webhook.site nebo RequestBin.
Nahrání PDF souboru dobropisu (volitelné)
Po zpracování webhooků můžete volitelně nahrát vlastní PDF doklad dobropisu zpět do Retina pomocí našeho veřejného API.
Použijte endpoint:
PATCH https://app.retino.com/api/v2/retino-credit-notes/{credit_note_id}/
S jedním z následujících těl požadavku:
Nahrání souboru pomocí URL:
{
"file_url": "https://example.com/path/to/your/file.pdf"
}Nahrání souboru pomocí Base64:
{
"file_base64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoK..."
}
Monitorování a řešení problémů
Všechny odeslané webhooky a jejich stav můžete sledovat v:
Nastavení > Webhooky - v detailu konkrétního webhooky
Časté problémy:
Endpoint není dostupný nebo neodpovídá do 10 sekund
Endpoint nevrací stavový kód 2xx
Nevalidní formát URL adresy v nastavení
V případě opakovaných neúspěšných odeslání webhooků vás budeme informovat emailem.