Dokumentace API - Faktury

Základní informace

Základní informace k API, autentizaci, stavové kódy, HTTP metody, datové typy a další najdete na API v2 základní informace.

Některé údaje nejsou dostupné přímo ve faktuře, ale v detailu související objednávky, kde je lze získat přes API. Více zde.

Seznam faktur

• URI: /api/v2/invoices/{invoice_number}?invoice_numbers={invoice_numbers}&creation_time_from={creation_time_from}&last_update_time_from={last_update_time_from}&page={page}&paid_yn={paid_yn}&type={type}
• HTTP metoda: GET
• hlavičky:
  • Authorization: Basic dGVzdDp0ZXN0
  • Content-Type: application/json
• parametry (musí být definovám alespoň jeden parametr):
  • invoice_number (string) - číslo faktury
  • invoice_numbers (string) - čísla faktur oddělená středníkem ;
  • creation_time_from (date) - vrátí faktury vytvořené od tohoto data
  • last_update_time_from (date) - vrátí faktury změněné od tohoto data
  • page (int) - stránka, pokud není definováno, vrací vždy stranu 1
  • paid_yn (bool) - pokud je 1, vrátí zaplacené faktury
  • type (string) - typ dokladu, hodnoty jsou:
    • invoice - faktura
    • creditNote - dobropis
    • receipt - účtenka

Odpověď

Seznam faktur je dostupný po jednotlivých stranách, výstup je omezen na 100 položek na stránku.

• tělo
  • current_page (int) - aktuální strana
  • current_page_items (int) - počet položek na aktuální straně
  • number_of_pages (int) - celkový počet stran
  • number_of_items (int) - celkový počet položek
  • invoices (array) - pole objektů s fakturami
    • invoice_number (string) - číslo faktury
    • related_invoice_number (string) - číslo související faktury, pouze u dobropisu
    • type (string) - typ faktury, hodnoty:
      • invoice - faktura
      • creditNote - dobropis
      • receipt - účtenka
    • order_number (string) - číslo objednávky
    • external_order_number (string) - číslo objednávky z externího systému
    • case_number (string) - číslo obchodního případu
    • language_id (language) - jazyk faktury
    • currency_id (currency) - měna faktury
    • date_of_issuance (date) - datum vystavení
    • date_of_vat_revenue_recognition (date) - datum zdanitelného plnění
    • date_of_expiration (date) - datum splatnosti
    • creation_time (date) - datum vytvoření
    • variable_symbol (string) - variabilní symbol
    • specific_symbol (string) - specifický symbol
    • payment (string) - platba
    • paid_yn (bool) - zaplaceno
    • paid_date (date) - datum zaplacení
    • total_rest (float) - zaokrouhlení celkové částky
    • total_with_vat (float) - celková částka s DPH
    • total_without_vat (float) - celková částka bez DPH
    • note (string) - poznámka
    • invoice_pdf_url (string) - URL na PDF fakturu
    • supplier (object) - dodavatel
      • email (string) - email
      • phone (string) - telefon
      • name (string) - jméno osoby nebo název firmy
      • street (string) - ulice a číslo
      • city (string) - město
      • zip (string) - PSČ
      • country_id (country) - stát
      • company_yn (bool) - příznak jestli je firma
      • var_payer_yn (bool) - příznak jestli je plátce DPH
      • ico (string) - IČ
      • dic (string) - DIČ
      • account_number (string) - číslo účtu
      • iban (string) - IBAN
      • swift (string) - SWIFT
      • web (string) - webová stránka
    • customer (object) - zákazník
      • email (string) - email
      • phone (string) - telefon
      • name (string) - jméno osoby nebo název firmy
      • street (string) - ulice a číslo
      • city (string) - město
      • zip (string) - PSČ
      • country_id (country) - stát
      • company_yn (bool) - příznak jestli je firma
      • ico (string) - IČ
      • dic (string) - DIČ
    • items (array) - pole objektů s položkami
      • code (string) - kód, pouze pokud je položka produkt a je k u produktu zadán, jinak je hodnota null
      • name (string) - název, pouze pokud je položka produkt, jinak je hodnota null
      • description (string) - popis
      • quantity (float) - počet kusů
      • unit (string) - jednotka
      • vat (float) - procentuální sazba DPH
      • price_per_unit_with_vat (float) - cena za jednotku s DPH
      • price_per_unit_without_vat (float) - cena za jednotku bez DPH
      • price_with_vat (float) - cena za s DPH
      • price_without_vat (float) - cena za bez DPH
    • eet (object) - informace o EET (bude vyplněno pouze u faktury typu účtenka)
      • send_yn (bool) - příznak jestli se má poslat do EET, určuje systém a to na základě nastavení v eshopu
      • production_yn (bool) - pokud je hodnota 0, není v eshopu aktivován produkční režim napojení na EET a data se do EET posílají v neprodukčním testovacím režimu
      • id_provoz (string) - ID provozovny
      • id_pokl (string) - ID pokladního zažízení
      • rezim (string) - režim EET, hodnoty:
        • common - běžný
        • simplified - zjednodušený
      • bkp (string) - BKP (bezpečnostní kód poplatníka)
      • fik (string) - FIK (fiskální identifikační kód)
      • pkp (string) - PKP (podpisový kód poplatníka)
    • recapitulation_currency_id (currency) - měna rekapitulace DPH. Pokud bude faktura v jiné měně než je měna země provozovatele esohpu, jinými slovy pokud eshop prodává do zahraničí, bude zde měna provozovatele eshopu, čili měna ve které je přehled DPH. Pokud není uvedeno, je přehled DPH ve měně faktury.
    • recapitulation_currency_rate (float) - kurz měny rekapitulace DPH
    • recapitulation_vats (array) - přehled DPH, pole objektů s jednotlivými hladinami DPH, klíč pole je procentuální sazba DPH
      • base (float) - základ
      • vat (float) - výše DPH
      • total (float) - celkem s DPH
    • recapitulation_vats_total (object) - přehled DPH celkem
      • base (float) - základ
      • vat (float) - výše DPH
      • total (float) - celkem s DPH

• příklad odpovědi (HTTP 200 OK)

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "current_page": "",
      "current_page_items": "",
      "number_of_pages": "",
      "number_of_items": "",
      "invoices": [
          {
              "invoice_number": "",
              "related_invoice_number": "",
              "type": "",
              "order_number": "",
              "external_order_number": "",
              "case_number": "",
              "language_id": "",
              "currency_id": "",
              "date_of_issuance": "",
              "date_of_vat_revenue_recognition": "",
              "date_of_expiration": "",
              "creation_time": "",
              "variable_symbol": "",
              "specific_symbol": "",
              "payment": "",
              "paid_yn": "",
              "paid_date": "",
              "total_with_vat": "",
              "total_without_vat": "",
              "note": "",
              "invoice_pdf_url": "",
              "supplier": {
                  "email": "",
                  "phone": "",
                  "name": "",
                  "street": "",
                  "city": "",
                  "zip": "",
                  "country_id": "",
                  "company_yn": "",
                  "var_payer_yn": "",
                  "ico": "",
                  "dic": "",
                  "account_number": "",
                  "iban": "",
                  "swift": "",
                  "web": ""
              },
              "customer": {
                  "email": "",
                  "phone": "",
                  "name": "",
                  "street": "",
                  "city": "",
                  "zip": "",
                  "country_id": "",
                  "company_yn": "",
                  "ico": "",
                  "dic": ""
              },
              "items": [
                  {
                      "description": "",
                      "info": "",
                      "unit": "",
                      "quantity": "",
                      "price_per_unit_with_vat": "",
                      "price_per_unit_without_vat": "",
                      "price_with_vat": "",
                      "price_without_vat": "",
                      "vat": ""
                  }
              ],
              "eet": {
                  "send_yn": "",
                  "production_yn": "",
                  "id_provoz": "",
                  "id_pokl": "",
                  "rezim": "",
                  "bkp": "",
                  "fik": "",
                  "pkp": ""
              },
              "vats": [
                  {
                      "base": "",
                      "vat": "",
                      "total": "",
                      "vat_value": ""
                  }
              ],
              "vat_totals": {
                  "base": "",
                  "vat": "",
                  "total": ""
              }
          }
      ]
  }

PDF faktura

Vrací fakturu ve formátu PDF.

• URI: /api/v2/invoices/{invoice_number}/pdf

• HTTP metoda: GET

• hlavičky:

  • Authorization: Basic dGVzdDp0ZXN0
  • Content-Type: application/json

• parametry:

  • invoice_number (string) - číslo faktury

• hlavičky odpovědi (HTTP 200 OK)

  HTTP/1.1 200 OK
  Content-Type: application/pdf