No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
src
tests
.gitattributes
.gitignore
.travis.yml
Readme.md
composer.json
phpunit.xml

Readme.md

Build Status Latest Stable Version

Klient pro jednoduché napojení na produktové feedy dodavatelů v ShopAPI.cz.

Podrobná dokumentace API v docs/api.md.

Přednosti ShopAPI/Client

Nenáročnost na server a vysoký výkon

  • stahování feedů používá kompresi, takže je rychlé a nezatěžuje případný datový limit.
  • zpracování probíhá streamovaně, takže i 5GB feed si vystačí s pár MB paměti (@todo benchmark)

Jednodušší napojení

Při použití klienta jste úplně odstíněni od XML a pracujete přímo s jednoduchými objekty. Není proto problém později přejít z XML feedu na REST API (filtry atd.), aniž by bylo nutné měnit zásadně kód napojení.

Instalace

composer require shopapicz/client
composer require composer/ca-bundle       # nepovinné, doporučené

Doporučujeme nainstalovat i composer/ca-bundle kvůli certifikátům, pokud váš server nemá aktuální.

Použití

<?php
use ShopAPI\Client\XmlReader;

$reader = new XmlReader();
/*
 * URL XML feedu je https://shopapi.cz/feed/dddd8888eeee
 */
foreach ($reader->readFromUrl('dddd8888eeee') as $product) {
    echo $product->getName();
}

Kódy

Identifikátor UID je unikátní a je dostupný vždy. Je přidělován v ShopAPI a doporučujeme ho použít pro párování. Je ale nevhodný pro komunikaci s dodavatelem, protože ten má zboží vedené pod vlastními kódy. Doporučujeme proto ukládat i code a EAN, pokud jsou dostupné.

UID doporučujeme používat pouze interně v aplikaci a zákazníkům/uživatelům ho vůbec nezobrazovat.

Obrázky

Obrázky jsou nabízeny v maximálním možném rozlišení bez další komprese, tak jak byly získány od dodavatele. Jsou proto zcela nevhodné pro přímé použití v eshopu a je potřeba je dále zpracovat.

Obrázky jsou uložené v CDN a je možné bez obtíží stahovat je rychle paralelně. URL obrázku se ale může později změnit, takže nedoporučujeme se na ni dlouhodobě spoléhat.

Dostupnost položky

Dostupnost položky je uváděna několika způsoby. U různých položek mohou být v různých kombinacích

  • code - kód dostupnosti (in_stock, out_of_stock, unknown, pre_order, unavailable)
  • hours - počet hodin (168 = týden)
  • quantity - počet kusů na skladě
  • text - slovní popis (skladem, poslední kusy, není a nebude, ...)

Při napojování doporučujeme používat code - je dostupný vždy a má jasně daný formát. Naopak na text se nedá nijak spolehnout a je vhodný pouze pro informativní zobrazení.

<?php
use \ShopAPI\Client\Entity\Availability;

if($product->getAvailability()->getCode() === Availability::IN_STOCK){
    echo 'skladem!';
}
// nebo zkráceně:
if($product->getAvailability()->isInStock()){
    echo 'skladem!';
}

Na co si dát pozor

Každý dodavatel nabízí data v jiném rozsahu a rozsah dat se může později měnit. Například dodavatel, který uváděl u všech produktů značku může později zařadit produkty, které značku uvedenou nemají. Při napojování je nutné s takovou situací počítat.

<?php
// ŠPATNĚ
echo $product->getBrand()->getName(); 

// SPRÁVNĚ
if($product->getBrand()) {
    echo $product->getBrand()->getName(); 
}

Příklady

<?php
use ShopAPI\Client\XmlReader;

$reader = new XmlReader();
/*
 * URL XML feedu je https://shopapi.cz/feed/dddd8888eeee
 */
foreach ($reader->readFromUrl('dddd8888eeee') as $product) {
    echo '<h1>' . $product->getName() . '</h1>';
    
    foreach($product->getImages() as $image) {
        echo '<img src="' . $image->getUrl() . '">';
    }
    
    if(count($product->getVariants())) {
        echo '<h2>Dostupné varianty:</h2>';
        echo '<ul>';
        foreach($product->getVariants() as $variant) {
            if($variant->getAvailability()->isInStock()) {
                echo '<li style="color:green">';
            } else {
                echo '<li style="color:red">';
            }
            echo $variant->getName();
            echo ' - ';
            echo $variant->getAvailability()->getText();
            echo  '</li>';
        }
        echo '</ul>';
    }
}

API

Kromě XML je možné používat také REST API. Údaje pro API jsou generovány v ShopAPI.cz pro každý export zvlášť.

<?php
use ShopAPI\Client\Api\ApiClient;
use ShopAPI\Client\Api\ApiConfig;

$client = new ApiClient(new ApiConfig('username', 'password'));

Seznam způsobů dodání

<?php
use ShopAPI\Client\Api\ApiClient;
use ShopAPI\Client\Api\ApiConfig;
use ShopAPI\Client\FieldList\DeliveryFields;

$client = new ApiClient(new ApiConfig('username', 'password'));
$returnFields = (new DeliveryFields())->addName();
foreach($client->getDeliveries($returnFields) as $delivery) {
    echo $delivery->getName() . "\n";
}

Odeslání nové objednávky

<?php
use ShopAPI\Client\Api\ApiClient;
use ShopAPI\Client\Api\ApiConfig;
use ShopAPI\Client\Api\OrderRequest\OrderRequest;
use ShopAPI\Client\Entity\Address;

$orderRequest = new OrderRequest();
$orderRequest
    ->setNote('Please hurry!')
    ->setDeliveryByUid('ogd9d5d44h')
    ->addItemByUid('w5d5v5vd5f', 2)
    ->setDeliveryAddress((new Address())
        ->setFirstName('John')
        ->setLastName('Smith')
        ->setStreet('Main Street')
        ->setHouseNumber('10a')
        ->setCity('Prague')
        ->setCountry('CZ')
    );

$client = new ApiClient(new ApiConfig('username', 'password'));
$orderResponse = $client->createOrder($orderRequest);

echo $orderResponse->getCode(); // order code
echo $orderResponse->getMessage();