PHPackages                             mervit/idoklad-v3 - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. mervit/idoklad-v3

ActiveLibrary[API Development](/categories/api)

mervit/idoklad-v3
=================

PHP třída pro ulehčení požadavků na iDoklad api v3.

v1.1.0(1y ago)213.7k↓11.8%1MITPHPPHP >=7.1.0

Since Mar 3Pushed 1y agoCompare

[ Source](https://github.com/mervit/iDoklad-v3)[ Packagist](https://packagist.org/packages/mervit/idoklad-v3)[ Docs](https://github.com/mervit/iDoklad-v3)[ RSS](/packages/mervit-idoklad-v3/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)DependenciesVersions (3)Used By (0)

[![Open Source Love](https://camo.githubusercontent.com/2d4eac62d5f5830a5309100b88e0ecccb171aee1fbcd794149f4a580b0010c56/68747470733a2f2f6261646765732e66726170736f66742e636f6d2f6f732f6d69742f6d69742e7376673f763d313032)](https://github.com/ellerbrock/open-source-badge/)

iDoklad v3
==========

[](#idoklad-v3)

PHP třída pro zasílání požadavků na iDoklad api v3.

[Dokumentace iDoklad api v2](https://api.idoklad.cz/Help/v2)

[Dokumentace iDoklad api v3](https://api.idoklad.cz/Help/v3/cs/)

Děkuji @malcanek za vytvoření v2, knihovnu jsem upgradoval na verzi 3 a dávám jí tímto k dispozici ostatním zájemcům

Změny v kodu proti verzi v2 od /iDoklad-v2
------------------------------------------

[](#změny-v-kodu-proti-verzi-v2-od-idoklad-v2)

- Podstattná změna je v odpovědích, kdy bylo u listů TotalItems a TotalPages přesunuto pod parametr data. Položky listů tedy již nelze načíst metodou getData ale nově vzniklou metodou getItems. U existujících aplikací je tedy nutné při přechodu z verze 2 na verzi 3 zasáhnout do všech callu které vrací list výsledků.
- Přepracované jsou filtry, které nyní umožňují seskupování a zanořování podmínek a kombinací logických operátorů `or` a `and`
- Requesty GET nově podporují parametr select pro omezení dat ve výsledcích
- Requesty GET nově podporují také parametr include který umožňuje zahrnout do odpovědi i data z připojených entit

Vložení knihovny do projektu
----------------------------

[](#vložení-knihovny-do-projektu)

Knihovnu vložíme do projektu naincludováním souboru src/iDoklad.php, nebo si knihovnu přidáme pomocí composeru. Následně se na knihovnu odkážeme pomocí use.

```
composer require mervit/idoklad-v3
```

Zadáme naše client ID, client secret a v případě, že chceme použít OAuth2 autentifikaci i redirect URI. Nakonec si zavoláme objekt iDokladu, který zajišťuje veškerou komunikaci.

```
include_once 'src/iDoklad.php';

use mervit\iDoklad\iDoklad;
use mervit\iDoklad\auth\iDokladCredentials;
use mervit\iDoklad\iDokladException;

$clientId = 'Your client ID';
$clientSecret = 'Your client secret';
$redirectUri = 'Your redirect URI for OAuth2';

$iDoklad = new iDoklad($clientId, $clientSecret, $redirectUri);
```

Autorizace pomocí OAuth2 - Authorization code flow
--------------------------------------------------

[](#autorizace-pomocí-oauth2---authorization-code-flow)

Autorizace pomocí OAuth probíhá v několika krocích. Jako client ID a client secret používáme údaje získané z developer portálu.

Nejdříve nabídneme uživateli URL adresu, kde zadá své přihlašovací údaje. Tu získáme pomocí nasledující metody:

```
echo 'Odkaz';
```

Po zadání přihlašovacích údajů je uživatel přesměrován na zadanou redirect URI i s kódem, pomocí kterého získáme jeho credentials údaje. Kód zpracujeme následujícím způsobem:

```
$iDoklad->requestCredentials($_GET['code']);
```

Nyní jsou v instanci objektu založeny credentials a můžeme odesílat dotazy na iDoklad api. Credentials můžeme získat 2 způsoby. Získání credentials přímo z objektu:

```
$credentials = $iDoklad->getCredentials();
echo $credentials->toJson();
```

### Zpracování credentials pomocí credentials callbacku:

[](#zpracování-credentials-pomocí-credentials-callbacku)

Callback funguje tak, že knihovna zavolá callback funkci vždy, když jsou změněny credentials. To se hodí, jelikož automaticky probíhá refresh tokenu po jeho vypršení.

```
$iDoklad->setCredentialsCallback(function($credentials){
    file_put_contents('credentials.json', $credentials->toJson());
});
```

### Nahrání credentials do iDoklad objektu

[](#nahrání-credentials-do-idoklad-objektu)

Založení objektu s již existujícími credentials

```
$iDoklad = new iDoklad($clientId, $clientSecret, $redirectUri, $credentials);
```

Vložení credentials do již existujícího objektu

```
$iDoklad->setCredentials($credentials);
```

Poté co objekt obsahuje credentials, lze provádět dotazy do iDoklad api.

Autorizace pomocí OAuth2 - Client credentials flow
--------------------------------------------------

[](#autorizace-pomocí-oauth2---client-credentials-flow)

Tato metoda je jednodušší. Credentials získáme na základě client id a client secret, které získáme z nastavení účtu uživatele. Po založení objektu pouze zavoláme:

```
$iDoklad->authCCF();
```

Jako u OAuth2 - Authorization code flow i zde funguje credentials callback.

Odesílání požadavků na iDoklad api
----------------------------------

[](#odesílání-požadavků-na-idoklad-api)

Pro odeslání požadavku na api slouží iDokladRequest objekt. Ten lze v nejjednodušší podobě založit pouze s jedním parametrem, který určuje akci dle dokumentace, a poté rovnou odeslat na api.

```
$request = new iDokladRequest('IssuedInvoices');
$response = $iDoklad->sendRequest($request);
```

Získání dat z api
-----------------

[](#získání-dat-z-api)

Pokud požadavek proběhne úspěšně, jsou zpět vrácena data v podobě iDokladResponse objektu. Nejdříve zkontrolujeme, zda požadavek proběhl v pořádku (návratová hodnota by měla být 200):

```
$response->getCode();
```

Poté můžeme získat samotná data v poli:

```
$response->getData();
```

Odchytávání chyb
----------------

[](#odchytávání-chyb)

Třída vyhazuje vyjímky typu iDokladException.

Vytvoření nové faktury
----------------------

[](#vytvoření-nové-faktury)

```
$request->addMethodType('POST');
$data = array(
    'PurchaserId' => 3739927,
    'IssuedInvoiceItems' => [array(
        'Name' => 'Testovaci polozka',
        'UnitPrice' => 100,
        'Amount' => 1
    )]
);
$request->addPostParameters($data);
```

Případně můžeme nově zadat method type pomocí fce, což by nyní vypadalo následovně:

```
$data = array(
    'PurchaserId' => 3739927,
    'IssuedInvoiceItems' => [array(
        'Name' => 'Testovaci polozka',
        'UnitPrice' => 100,
        'Amount' => 1
    )]
);
$request->post()->addPostParameters($data);
```

Použití filtru a třídění
------------------------

[](#použití-filtru-a-třídění)

Pro použití filtru použijeme třídu iDokladFilter. Parametry můžeme zadat hned při založení třídy, první parametr je jméno pole, které chceme filtrovat, druhý parametr je operátor, poslední parametr je hodnota.

```
$filter = new iDokladFilter('DocumentNumber', '==', '20170013');
$request->addFilter($filter);
```

Vztahy mezi jednotlivými filtry můžeme definovat pomocí metody setFilterType.

```
$request->setFilterType('and');
```

Filtrů můžeme přidat několik a pomocí filterGroup třídy je můžeme seskupit.

```
$filterGroup = new \mervit\iDoklad\request\iDokladFilterGroup('or');
$filter2 = new \mervit\iDoklad\request\iDokladFilter('Id', '!eq', '123');
$filterGroup->addFilter($filter2);
$filter3 = new \mervit\iDoklad\request\iDokladFilter('Id', 'eq', '456');
$filterGroup->addFilter($filter3);
$request->addFilter($filterGroup);
```

Pro použití třídění použijeme třídu iDokladSort. Opět můžeme hned přidávat parametry, kdy první parametr je jméno pole a druhý parametr je dobrovolný a lze zadat, zda řadit vzestupně (asc) či sestupně (desc).

```
$sort = new iDokladSort('DocumentNumber', 'desc');
$request->addSort($sort);
```

Stránkování a počet vrácených položek
-------------------------------------

[](#stránkování-a-počet-vrácených-položek)

```
$request->setPage(2);
$request->setPageSize(5);
```

Omezení výsledku
----------------

[](#omezení-výsledku)

Pomocí metody addSelect můžeme omezit data, které API vrací a výrazně tím dobu zpracování požadavku

```
$request->addSelect('Id');
$request->addSelect('CurrencyId');
```

Zanořená data odělujeme tečkou

```
$request->addSelect('DeliveryAddress.Name');
```

Můžeme přidat i více proměných odělené čárkou

```
$request->addSelect('Items.Id,Items.Name');
```

Načtení připojených entit
-------------------------

[](#načtení-připojených-entit)

Pomocí metody addInclude můžeme naopak rozšířit vrácené data o detaily připojených entit. Díky této funkci již nemusíme načítat detail připojené entity samostatným callem.

```
$request->addInclude('Currency');
```

Zanořená data odělujeme tečkou

```
$request->addInclude('Items.PriceListItem.Currency');
```

Můžeme přidat i více proměných odělené čárkou

```
$request->addInclude('Currency,Items.PriceListItem.Currency');
```

Vyhazování exception při návratových kódech vyšších nebo rovno 400
------------------------------------------------------------------

[](#vyhazování-exception-při-návratových-kódech-vyšších-nebo-rovno-400)

Pokud chceme zapnout vyhazování exception při http návratových kódech vyšších rovno 400, stačí nám zavolat fci

```
$iDoklad->httpExceptionsOn()
```

Upload přílohy
--------------

[](#upload-přílohy)

Pokud chceme uploadovat přílohu, stačí nám použít metodu addFile nad request objektem.

```
$request = new \mervit\iDoklad\request\iDokladRequest('Attachments/{documentId}/{documentType}');
$request->addFile(new CURLFile(path_to_your_file));
$response = $iDoklad->sendRequest($request);
```

Jiné úpravy
-----------

[](#jiné-úpravy)

Pokud potřebujeme použít metody POST, PUT, PATCH, DELETE, použijeme k tomu metodu addMethodType nad objektem iDokladRequest.

Příklady
--------

[](#příklady)

Příklady použití lze vidět v souborech acf.php a ccf.php. acf.php obsahuje příklad použití authorization code flow, ccf obsahuje příklad na client credentials flow, stačí doplnit vlastní client ID, client secret a redirect URI.

### Příklad vytvoření faktury

[](#příklad-vytvoření-faktury)

```
// Generate company name
        $companyName = $order->getFirstname() . ' ' . $order->getLastname();
        if($order->getCompanyName()){
            $companyName = $order->getCompanyName();
        }

        // Try to find existing company in address book
        $filter = new iDokladFilter('CompanyName', '==', $companyName);
        $contactRequest = new iDokladRequest('Contacts');
        $contactRequest->addFilter($filter);
        $contactResponse = $this->sendRequest($contactRequest);
        if($contactResponse->getTotalItems() > 0){
            $contactId = $contactResponse->getItems()[0]["Id"];
        }

        // Create or update company in address book
        $contactRequest = new iDokladRequest('Contacts');
        $contactRequestPostParameters = [];
        $contactRequestPostParameters['CountryId'] = 1;
        $contactRequestPostParameters['Email'] = $order->getEmail();
        $contactRequestPostParameters['Mobile'] = $order->getPhone();
        $contactRequestPostParameters['Firstname'] = $order->getFirstname();
        $contactRequestPostParameters['Surname'] = $order->getLastname();
        $contactRequestPostParameters['CompanyName'] = $companyName;
        if($order->getCin()) {
            $contactRequestPostParameters['IdentificationNumber'] = $order->getCin();
        }
        if($order->getVat()){
            $contactRequestPostParameters['VatIdentificationNumber'] = $order->getVat();
        }
        if($order->getAddress()){
            $contactRequestPostParameters['Street'] = $order->getAddress();
        }
        if(isset($contactId)){
            $contactRequestPostParameters['Id'] = $contactId;
            $contactRequest->addMethodType('PATCH');
        } else {
            $contactRequest->addMethodType('POST');
        }
        $contactRequest->addPostParameters($contactRequestPostParameters);

        $contactResponse = $this->sendRequest($contactRequest);
        $contact = $contactResponse->getData();

        // Get default numeric sequence
        $numericSequenceRequest = new iDokladRequest('NumericSequences');
        $numericSequenceRequest->addFilter(new iDokladFilter('IsDefault', '==', 'true'));
        $numericSequenceRequest->addFilter(new iDokladFilter('DocumentType', '==', '0')); // 0 = IssuedInvoices
        $numericSequenceResponse = $this->sendRequest($numericSequenceRequest);
        $numericSequences = $numericSequenceResponse->getItems();
        $defaultNumericSequenceId = $numericSequences[0]['Id'];
        $lastDocumentSerialNumber = $numericSequences[0]['LastNumber'];

        // Get default payment option
        $paymentOptionRequest = new iDokladRequest('PaymentOptions');
        $paymentOptionResponse = $this->sendRequest($paymentOptionRequest);
        $paymentOptions = $paymentOptionResponse->getItems();
        $paymentOptionId = null;
        foreach($paymentOptions as $po){
            if($po['IsDefault'] == 'true'){
                $paymentOptionId = $po['Id'];
                break;
            }
        }

        // Create Issued Invoice
        $dateOfIssue = new \DateTime();
        $dateOfMaturity = clone $dateOfIssue;
        $dateOfMaturity->modify('+14 days');
        $invoicePostParameters = [];
        $invoicePostParameters['PartnerId'] = $contact['Id'];
        $invoicePostParameters['CurrencyId'] = 1;
        $invoicePostParameters['Description'] = 'Nákup v eshopu';
        $invoicePostParameters['DateOfIssue'] = $dateOfIssue->format('Y-m-d');
        $invoicePostParameters['DateOfMaturity'] = $dateOfMaturity->format('Y-m-d');
        $invoicePostParameters['DateOfTaxing'] = $dateOfIssue->format('Y-m-d');
        $invoicePostParameters['DocumentSerialNumber'] = (string)((int) $lastDocumentSerialNumber + 1);
        $invoicePostParameters['IsEet'] = false;
        $invoicePostParameters['IsIncomeTax'] = true;
        $invoicePostParameters['NumericSequenceId'] = $defaultNumericSequenceId;
        $invoicePostParameters['PaymentOptionId'] = $paymentOptionId;
        $invoicePostParameters['Items'] = [];

        foreach ($order->getItems() as $item) {
            $invoiceItem = [];
            $invoiceItem['Amount'] = $item->getQuantity();
            $invoiceItem['PriceType'] = 0; // Cena s daní
            $invoiceItem['VatRateType'] = 1; // Základní sazba DPH
            $invoiceItem['UnitPrice'] = $item->getPrice();
            $invoiceItem['Name'] = $item->getName();
            $invoiceItem['DiscountPercentage'] = 0;
            $invoiceItem['IsTaxMovement'] = false;
            $invoicePostParameters['Items'][] = $invoiceItem;
        }

        $invoiceRequest = new iDokladRequest('IssuedInvoices');
        $invoiceRequest->addMethodType('POST');
        $invoiceRequest->addPostParameters($invoicePostParameters);
        return $this->sendRequest($invoiceRequest);
```

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance31

Infrequent updates — may be unmaintained

Popularity31

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~77 days

Total

2

Last Release

729d ago

PHP version history (2 changes)v1.0.0PHP >=5.5.0

v1.1.0PHP >=7.1.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/cdc564151e455bd979864697938aada9f819585cec05ed249c56f3ed907de7a6?d=identicon)[mervit](/maintainers/mervit)

---

Top Contributors

[![mervit](https://avatars.githubusercontent.com/u/6680486?v=4)](https://github.com/mervit "mervit (14 commits)")[![malcanek](https://avatars.githubusercontent.com/u/21026285?v=4)](https://github.com/malcanek "malcanek (12 commits)")[![martinveverka](https://avatars.githubusercontent.com/u/2683415?v=4)](https://github.com/martinveverka "martinveverka (2 commits)")[![mskocik](https://avatars.githubusercontent.com/u/25513620?v=4)](https://github.com/mskocik "mskocik (1 commits)")[![petrvacha](https://avatars.githubusercontent.com/u/659610?v=4)](https://github.com/petrvacha "petrvacha (1 commits)")[![xpalko](https://avatars.githubusercontent.com/u/8526481?v=4)](https://github.com/xpalko "xpalko (1 commits)")[![martinille](https://avatars.githubusercontent.com/u/2567894?v=4)](https://github.com/martinille "martinille (1 commits)")[![mlazovla](https://avatars.githubusercontent.com/u/2652944?v=4)](https://github.com/mlazovla "mlazovla (1 commits)")

---

Tags

idokladfakturace

### Embed Badge

![Health badge](/badges/mervit-idoklad-v3/health.svg)

```
[![Health](https://phpackages.com/badges/mervit-idoklad-v3/health.svg)](https://phpackages.com/packages/mervit-idoklad-v3)
```

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[facebook/php-business-sdk

PHP SDK for Facebook Business

90821.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

74513.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

265103.1M454](/packages/google-gax)[google/common-protos

Google API Common Protos for PHP

173103.7M50](/packages/google-common-protos)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)