Integrace s vaší administrací (doporučená implementace)

API slouží ke zjednodušení a automatizaci procesů po vytvoření faktury. Poskytuje veškeré operace s fakturou, které lze provést z administrace e-shopu. Jedná se o doporučený způsob implementace, který e-shopu umožní plně automatizovat všechny procesy.

Čtyři akce mění stav faktury: aktivace, zrušení, úprava a vrácení položek faktury. Dostupnost těchto akcí závisí na stavu faktury. Po aktivaci již nelze fakturu upravovat ani rušit. Místo toho lze pouze nahlásit vrácení.

Kdykoli:

získání dat
seznam faktur

Před aktivací faktury:

aktivace faktury
zrušení faktury
úprava faktury
rozdělení faktury

Po aktivaci faktury:

nahlášení vrácení faktury
zrušení nahlášeného vrácení faktury
částečné vrácení faktury
úplné vrácení faktury
snížení ceny faktury

Upozornění: Všechny chybové stavy mohou skončit chybou. Může jít o validační chybu dat, neautorizovaný stav faktury nebo interní chybu serveru. V těchto případech je stav odpovědi 400 nebo 500 a knihovna navíc vyhodí výjimku. Pokud je API navázáno na akci ve vašem e-shopu, je vhodné volat API před uložením dat do databáze a při chybě API akci zrušit a uživateli zobrazit chybovou zprávu.

Získání dat

Aktuální data faktury lze získat odesláním požadavku GET v knihovně voláním metody GET. To je možné kdykoli bez ohledu na stav faktury.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');
$invoice->get();

echo $invoice->pdf_url;
?>

Odpověď obsahuje všechny informace, které se o faktuře zobrazují v administraci e-shopu.

Poznámka: Všechny akce vracejí v odpovědi aktualizovaná data. Po úspěšné akci tedy není nutné znovu volat metodu get v knihovně.

Aktivace faktury

Aktivace faktury probíhá v okamžiku odeslání objednávky z e-shopu zákazníkovi. Aktivace automaticky nastaví datum splatnosti a vygeneruje PDF fakturu s platebními údaji pro zákazníka. Součástí odpovědi je adresa pdf_url, ze které lze stáhnout soubor PDF faktury. Fakturu lze aktivovat pouze jednou, jinak API vrátí chybu. Také nelze aktivovat zrušenou fakturu.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');
$invoice->activate();

echo $invoice->pdf_url;
?>

Zrušení faktury

Zrušit lze pouze fakturu, která není aktivovaná ani zrušená, jinak API vrátí chybu.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');
$invoice->cancel();
?>

Úprava faktury

Upravit lze pouze fakturu, která není aktivovaná ani zrušená, jinak API vrátí chybu. Povolena je jen úprava položek objednávky. Požadavek musí obsahovat všechny položky faktury v poli items. Položky se párují podle atributu product_id. Po odeslání požadavku se položky přepíšou. Položky, které byly součástí faktury, ale v požadavku chybí, budou smazány. Chcete-li přidat jen jednu položku, musíte vypsat i všechny ostatní.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');

// stačí vyplnit pole items, není nutné mít načtená všechna data faktury
$invoice->items = array(
    new Twisto\Item(
        Twisto\Item::TYPE_DEFAULT,                  // typ
        'Agatha Christie: The Secret Adversary',    // název
        942,                                        // product_id
        1,                                          // quantity
        285.31,                                     // price_vat
        15,                                         // vat
        null,                                       // ean_code
        '9781609421052'                             // isbn_code
    ),
    new Twisto\Item(
        Twisto\Item::TYPE_SHIPMENT,     // typ
        'Doprava DPD',                  // název
        'shipment',                     // product_id
        1,                              // quantity
        119,                            // price_vat
        21                              // vat
    ),
    new Twisto\Item(
        Twisto\Item::TYPE_PAYMENT,                  // typ
        'Twisto Faktura – platím až po vyzkoušení', // název
        'payment',                                  // product_id
        1,                                          // quantity
        0,                                         // price_vat
        21                                          // vat
    ),
);
$invoice->save();

// po uložení byla celková cena faktury přepočítána
echo $invoice->total_price_vat;
?>

Rozdělení faktury

Rozdělení faktur slouží pro případy, kdy se část zboží z původní objednávky expeduje dříve než zbytek a obě části by proto měly mít jiné datum splatnosti.

Rozdělení je povoleno jen zákazníkům, u kterých je tato funkce zapnutá (aktuálně je pro váš e-shop vypnutá). Kontaktujte nás pro zapnutí nebo vypnutí.

Rozdělit lze jen faktury, které ještě nejsou aktivované a mají více než jeden kus (quantity) zboží. Rozdělit lze pouze zboží. Pokud chcete k nově vytvořené faktuře doplnit poplatek za dopravu, použijte úpravu faktury. Maximální počet rozdělení faktury není omezen. Faktury vytvořené rozdělením však již dále rozdělit nelze.

<?php
$invoice = new Twisto\Invoice($twisto, '123');

// definice položek, které se mají přenést na samostatnou fakturu
// přenos 4 kusů s product_id 123 a jednoho kusu s product_id 432 na novou fakturu
$items = array(
    new Twisto\ItemSplit("123", 4)
    new Twisto\ItemSplit("432", 1)
);

// objekt `$split_invoice` bude obsahovat novou fakturu
$split_invoice = $invoice->splitItems($items);
?>

Nahlášení vrácení faktury

Nahlásí příchozí vrácení faktury. Prodlouží datum splatnosti faktury. Tato funkce není ve výchozím stavu povolena.

<?php
$invoice = new Twisto\Invoice($twisto, '123');
$invoice->reportReturn();
?>

Zrušení nahlášeného vrácení faktury

Pokud bylo vrácení faktury nahlášeno a ještě neproběhlo, lze nahlášené vrácení zrušit, pokud na to faktura splňuje podmínky.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');
$invoice->cancelReportReturn();
?>

Částečné vrácení faktury

Vrácení položek je dostupné jen pro aktivované faktury. Vrátit lze jen položky zboží, slev a dopravy (TYPE_DEFAULT, TYPE_DISCOUNT a TYPE_SHIPMENT). Při vrácení všech položek se automaticky označí jako vrácené i položky dopravy a platby. U položek typu sleva (TYPE_DISCOUNT) lze měnit cenu jen pokud je počet kusů (quantity) roven 1. Má-li sleva více než 1 kus, cenu nelze měnit.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');

$invoice->returnItems(
    // vrácení 1 kusu s product_id 942
    array(new Twisto\ItemReturn(942, 1)),

    // změna ceny slevové položky na -42 Kč s product_id 852
    array(new Twisto\ItemDiscountReturn(852, -42))
);

// po vrácení byla celková cena faktury přepočítána
echo $invoice->total_price_vat;
?>

Úplné vrácení faktury

Vrátit lze jen aktivovanou fakturu.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');

$invoice->returnAll();
?>

Snížení ceny faktury

Snížení ceny je možné jen u aktivovaných faktur. Metoda slouží k vrácení části nebo celé faktury v případech, kdy nelze použít ID položek.

Snížení ceny faktury je povoleno jen zákazníkům, u kterých je tato funkce zapnutá (u vašeho e-shopu je zapnutá). Kontaktujte nás pro zapnutí nebo vypnutí.

Cenu faktury lze snížit pouze o kladnou částku, která je menší nebo rovna celkové ceně faktury.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');

$invoice->refund(
    // Snížení ceny faktury o 12,34 Kč
    12.34
);
?>

Seznam faktur

Výpis a vyhledávání ve všech fakturách. Maximálně 100 položek na stránku, next obsahuje odkaz na další stránku a previous na předchozí.

Parametry dotazu pro vyhledávání

Název	Maximální délka	Hodnota
date_from	ISO 8601	Faktury s datem větším nebo rovným tomuto
date_to	ISO 8601	Faktury s datem menším nebo rovným tomuto
invoice_id	10	ID faktury Twisto
eshop_invoice_id	10	ID faktury e-shopu. Pokud je vyplněno, použije se jako variabilní symbol platby na účet e-shopu. Povoleny jsou pouze číslice.
external_id	50	ID objednávky / faktury e-shopu. Pokud je vyplněno, vrátí se v odpovědích API a zobrazí v přehledu XLSX.
customer_email	254	E-mail zákazníka
provider_id	254	ID objednávky platebního poskytovatele. Je vyžadován formát EYDDDNNNNNNNN.

{
  "next": "http://api.twisto.cz/v2/invoice/list/?cursor=cD00NjQ%3D",
  "previous": null,
  "results": [
    {
      "invoice_id": "19383193",
      "eshop_invoice_id": "",
      "customer_email": "gigatest9@twisto.cz",
      "date_created": "2018-02-05T00:00:00Z",
      "date_returned": "2018-02-28T11:14:00Z",
      "date_cancelled": null,
      "date_activated": "2018-02-05T00:00:00Z",
      "date_paid": null,
      "date_due": "2018-03-01",
      "initial_date_due": "2018-03-01",
      "total_price_vat": "0.00",
      "pdf_url": "http://api.twisto.cz/invoice/pdtk31vk3lt0uocq1ws679n4cbb5ecxoo8yafncifs7qmip40l/19383193.pdf"
    }
  ]
}

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: your-public-key,your-security-key" \
'https://api.twisto.cz/v2/invoice/list/'