Webhooky dobropisů

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

1. V administraci Retino přejděte do Nastavení > Marketplace
2. Aktivujte doplněk Webhooky dobropisů
3. Po aktivaci přejděte na detail doplňku kliknutím na tlačítko Spravovat
4. Zadejte URL adresu vašeho endpointu, kam budeme odesílat data o dobropisech
5. Klikněte na tlačítko Uložit

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:

1. Vytvořit endpoint na vašem serveru, který bude přijímat HTTP POST požadavky
2. Implementovat zpracování příchozích dat ve formátu JSON
3. Ověřit autenticitu požadavku pomocí hlavičky X-Retino-Secret (více v dokumentaci webhooků)
4. Odpovědět na požadavek se stavovým kódem 2xx v časovém limitu 10 sekund

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:

1. Nahrání souboru pomocí URL:

{
  "file_url": "https://example.com/path/to/your/file.pdf"
}

1. 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.