PHP SDK

Oficiální knihovna pro PHP. Zabalí volání API do typovaných objektů, takže neskládáte JSON ručně a chyby jsou vidět už při psaní kódu.

Instalace

composer require iucto/iucto-api-php-sdk

Vyžaduje PHP 7.2 nebo novější a Guzzle 6 či 7. Licence MIT.

Načtení dokladů

require __DIR__ . '/vendor/autoload.php';

$iUcto = IUcto\IUctoFactory::create(getenv('IUCTO_API_KEY'));

try {
    $result = $iUcto->getInvoiceIssued();

    echo 'stránek: ', $result['pageCount'], "\n";

    foreach ($result['invoice_issued'] as $invoice) {
        echo $invoice->getId(), "\n";
    }
} catch (IUcto\UnautorizedException $e) {
    // neplatný klíč (401)
} catch (IUcto\PaymentRequiredException $e) {
    // vyčerpaná kvóta nebo zdroj mimo tarif (402)
} catch (IUcto\ConnectionException $e) {
    // síť, nebo neznámý stavový kód
}

Návratová hodnota je dvouúrovňová

getInvoiceIssued() nevrací seznam dokladů, ale pole ['pageCount' => n, '<typ dokladu>' => [InvoiceIsseudOverview, …]]. Klíčem druhé úrovně je typ dokladu (invoice_issued, credit_note_issued, …), takže foreach rovnou přes návratovou hodnotu iteruje nejdřív přes int. Stejný tvar mají i ostatní get*() metody vracející seznamy.

Založení zákazníka

$customer = new \IUcto\Command\SaveCustomer();
$customer->setName('Jan Novák');
$customer->setComid('12345679');
$customer->setVatid('CZ12345679');
$customer->setVatPayer(true);
$customer->setUsualMaturity(14);
$customer->setPreferredPaymentMethod('transfer');
$customer->setInvoiceLanguage('cs');

$address = new \IUcto\Dto\Address();
$address->setCountry('CZ');
$address->setStreet('Stodolní 123');
$address->setCity('Ostrava');
$address->setPostalcode('702 00');
$customer->setAddress($address);

$iUcto->createCustomer($customer);

Verze API

SDK volá ve výchozím stavu verzi 1.2

IUctoFactory::create() má třetí parametr $version s výchozí hodnotou '1.2'. Novinky verze 1.3 — řazení parametrem sort, pole modified, zůstatky u bankovních účtů — tedy ve výchozím nastavení nedostanete.

Verzi předejte explicitně:

$iUcto = IUcto\IUctoFactory::create(getenv('IUCTO_API_KEY'),
    IUcto\IUctoFactory::DEFAULT_ENDPOINT, '1.3');

Co SDK pokrývá

Doklady vydané i přijaté, interní předpisy nákladů, adresář, platby, bankovní pohyby, číselníky a zaúčtování — tedy většinu API. Metody kopírují operace v referenci: getInvoiceIssued(), createInvoiceIssued(), accountInvoiceIssued(), getInvoiceIssuedPdf() a podobně.

Když v SDK něco nenajdete, volejte API přímo — reference popisuje všech 161 operací.

Chyby

Knihovna překládá stavové kódy na výjimky:

Výjimka	Kdy
IUcto\ValidationException	server odmítl data (400) a v těle je mapa errors — hlášky vrací getErrors()
IUcto\BadRequestException	ostatní odmítnutí s kódem 400 (například nevalidní JSON)
IUcto\UnautorizedException	neplatný nebo chybějící klíč (401) — překlep v názvu je v SDK
IUcto\PaymentRequiredException	vyčerpaná kvóta nebo zdroj mimo tarif (402)
IUcto\ForbiddenException	operaci nelze provést (403) — uzavřené období, závislosti
IUcto\NotFoundException	záznam nenalezen (404)
IUcto\ServerException	chyba na straně iÚčta (500 a výš)
IUcto\MaintenanceException	probíhá údržba (503)
IUcto\ConnectionException	síťová chyba, nečitelná odpověď, neznámý stavový kód

Co který stavový kód znamená, popisuje Chyby a jak je číst.

Zdroj

Knihovna je na Packagistu jako iucto/iucto-api-php-sdk.