Metody

CheckConnection

Test Atom User API w zakresie połączenia i autoryzacji.

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$response = $client->CheckConnection($authenticate);
echo $response;

Dane zwracane: 

OK 

Uwagi:
– metoda zwraca ciąg znaków „OK” lub „User API: nieudana autoryzacja” (w przypadku błędnego loginu / hasła lub niedostępności modułu w sklepie).

GetDocuments

Pobranie informacji o dokumentach handlowych (faktury, rozrachunki) stworzonych dla kontrahenta w ramach modułu B2B.

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’
modifiedniestring 0000-00-00 00:00:00zawężenie danych do dokumentów utworzonych albo zmodyfikowanych z datą równą lub późniejszą od podanej

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$response = $client->GetDocuments($authenticate);
header('Content-Type: application/xml');
echo $response;

Dane zwracane + komentarze: 

<documents>
	<document>
		<user>
			<atom_id>24</atom_id> <!-- id kontrahenta w AtomStore -->
			<external_id>ext24</external_id> <!-- zewn. identyfikator kontrahenta, obecny, jeśli został nadany -->
			<email>marcinek95@wp.pl.9999</email> <!-- adres e-mail -->
		</user>
		<type>FK</type> <!-- typ dokumentu -->
		<number><![CDATA[FK/1111/2019]]></number> <!-- numer -->
		<value>100.22</value> <!-- wartość -->
		<to_pay>0.00</to_pay> <!-- do zapłaty -->
		<products> <!-- pozycje na dokumencie -->
			<product>
				<code><![CDATA[kkkpom222]]></code> <!-- kod produktu / wariantu -->
				<quantity>2.0000</quantity> <!-- ilość -->
				<price>50.11</price> <!-- cena -->
				<tax>23</tax> <!-- stawka podatkowa -->
				<data><![CDATA[ (...) ]]></data> <!-- inne dane pozycji dokumentu, w postaci zserializowanej -->
			</product>
		</products>
		<!-- inne, dowolne dane dokumentu, w postaci zserializowanej -->
		<data><![CDATA[a:2:{s:8:"order_id";i:223344;s:8:"payments";a:2:{s:2:"p1";s:6:"123,45";s:2:"p2";s:6:"400,00";}}]]></data>
		<file>
			<url></url> <!-- URL do załącznika -->
		</file>
		<created>2019-02-19 22:10:00</created> <!-- data dodania dokumentu -->
		<modified>2019-02-20 15:15:59</modified> <!-- data ostatniej modyfikacji dokumentu -->
	</document>
</documents>

Uwagi:
– dane zwracane są w kolejności według daty ostatniej modyfikacji dokumentu, rosnąco,
– maksymalna liczba zwróconych dokumentów: 1000.

GetOrders

Pobieranie zamówień (własnych) z możliwością filtrowania i różnicowania danych.

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’
orderStatusIdniestring opcjonalne filtrowanie po statusie zamówienia wskazanym poprzez id (patrz: GetOrdersStatuses); można przekazać wiele statusów oddzielając je przecinkiem
fromOrderIdnieint0zawężenie danych do zamówień z numerem równym lub większym od podanego
limitnieint0ilość pobieranych zamówień; dla wartości 0 zakres zwracanych danych nie jest limitowany
timestampniestring0000-00-00 00:00:00zawężenie danych do zamówień utworzonych albo zmodyfikowanych z datą równą lub późniejszą od podanej
userFilterniestring filtrowanie wg ID klienta w AtomStore (jeśli przekazano liczbę) lub wg adresu e-mail
extraFiltersniestring mapa dodatkowych filtrów postaci „klucz1|wartosc1;klucz2|wartosc2” – filtrowanie po id Partnera „partnerId|123” – filtrowanie po email partnera „partnerEmail|partner@parnter.pl” – filtrowanie po id Zamówienia „id|123” – filtrowanie po id sklepu „storeId|2”

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$response = $client->GetOrders($authenticate, '2,4', 0, 20, '2015-04-30 11:59:59');
header('Content-Type: application/xml');
echo $response;

Dane zwracane + komentarze: 

<orders>
	<order>
		<id>531</id> <!-- numer zamówienia w AtomStore -->
		<externalId>ZK/246/2015</externalId> <!-- zewnętrzny identyfikator zamówienia, np. w ERP (jeśli został nadany) -->
		<number>uw28fh8a/2015</number> <!-- alternatywny kod zamówienia -->
		<code>de5b5a12b8687d8326a6e8956522cdd4dff20f54</code> <!-- kod autoryzacyjny (generowanie odnośnika do zamówienia) -->
		<statusID>2</statusID> <!-- aktualny status zamówienia wyrażony poprzez id -->
		<confirmed>1</confirmed> <!-- czy zamówienie jest potwierdzone przez klienta (1 = tak, 0 = nie) -->
		<paymentMethodId>13</paymentMethodId> <!-- id formy płatności -->
		<paymentMethod>PayU</paymentMethod> <!-- nazwa formy płatności -->
		<paymentPrice>0.0000</paymentPrice> <!-- koszt z tytułu formy płatności, wartość brutto, waluta zamówienia -->
		<paymentTaxValue>23</paymentTaxValue> <!-- stawka VAT dla kosztu z tytułu formy płatności -->
		<paymentCOD>0</paymentCOD> <!-- płatność przy odbiorze (1 = tak, 0 = nie) -->
		<shippingMethodId>8</shippingMethodId> <!-- id formy dostawy -->
		<shippingMethodOptionKey>P12345</shippingMethodOptionKey> <!-- kod opcji dostawy (np. wybranego punktu odbioru) -->
		<shippingMethod>Paczkomaty</shippingMethod> <!-- nazwa formy dostawy -->
		<shippingPrice>11.5000</shippingPrice> <!-- koszt dostawy, wartość brutto, waluta zamówienia -->
		<shippingTaxValue>23</shippingTaxValue> <!-- stawka VAT dla formy dostawy -->
		<shippingComments><![CDATA[ Prosze dzwonic domofonem. ]]></shippingComments> <!-- Komentarz do wysylki -->
		<shippingQuantity>1</shippingQuantity> <!-- ilość paczek, na które podzielono przesyłkę -->
		<trackingNumber></trackingNumber> <!-- numer listu przewozowego -->
		<created>2015-04-30 12:18:54</created> <!-- data utworzenia zamówienia -->
		<modified>2015-04-30 12:20:11</modified> <!-- data ostatniej modyfikacji zamówienia -->
		<comments><![CDATA[ Proszę o szybką wysyłkę. ]]></comments> <!-- uwagi klienta do zamówienia -->
		<source>ALLEGRO</source> <!-- źródło sprzedaży -->
		<store_id>1</store_id> <!-- id sklepu (Multistore) -->
		<store_name><![CDATA[Sklep AtomStore]]></store_name> <!-- nazwa sklepu (Multistore) -->
		<allegroNumber>555555555</allegroNumber> <!-- numer aukcji, dla zamówień zaimportowanych z Allegro -->
		<allegroTransactionId>5999999999</allegroTransactionId> <!-- numer transakcji, dla zamówień Allegro -->
		<allegroAccount>xxxyyyzzz</allegroAccount> <!-- konto Allegro, z którego aukcja została wystawiona -->
		<currency>PLN</currency> <!-- waluta, w której złożono zamówienie -->
		<currencyValue>1.00000000</currencyValue> <!-- kurs waluty w chwili zapisu zamówienia -->
		<couponValue>0.00</couponValue> <!-- wartość wykorzystanego kuponu rabatowego, brutto, waluta zamówienia -->
		<couponName></couponName> <!--nazwa wykorzystanego kuponu rabatowego -->
		<paid>952.18</paid> <!-- kwota opłacona, odczytana z chwilą generowania danych; wartość brutto, waluta zamówienia -->
		<order_sum>952.18</order_sum> <!-- wartość zamówienia, brutto, waluta zamówienia -->
		<paymentTransactionId>9384579283578</paymentTransactionId> <!-- identyfikator płatności internetowej -->
		<paymentTransactionNumber>472477477</paymentTransactionNumber> <!-- dodatkowy identyfikator płatności internetowej -->
		<paymentTransactionDate>2015-04-30 12:20:11</paymentTransactionDate> <!-- data płatności internetowej -->
		<paymentCommission>2.86</paymentCommission> <!-- prowizja pobrana przez podmiot obsługujący płatność internetową -->
		<receiptNumber>PF/477/2015</receiptNumber> <!-- numer wystawionego paragonu -->
		<invoice>1</invoice> <!-- czy do zamówienia ma zostać wystawiona faktura (1 = tak, 0 = nie) -->
		<invoices>FV/297/2015;FKOR/12/2015</invoices> <!-- numery wystawionych faktur (oddzielone średnikiem) -->
		<dropshipping>0</dropshipping> <!-- czy zamówienie jest zamówieniem dropshippingowym -->
		<dateShipment>2015-05-04</dateShipment> <!-- automatycznie obliczona data wysyłki -->
		<dateDelivery>2015-05-05</dateDelivery> <!-- planowana data dostarczenia -->
		<language>pol</language> <!-- język zamówienia -->
        <remoteIP>46.248.190.177</remoteIP> <!-- adres IP kupującego -->
		<client>
			<userID>4195</userID> <!-- id klienta w AtomStore -->
			<externalId>u_1238902</externalId> <!-- zewnętrzny identyfikator klienta, o ile został nadany -->
			<allegroUserId>101010</allegroUserId> <!-- id kupującego w Allegro -->
			<allegroUserLogin>mojNick123</allegroUserLogin> <!-- login kupującego w Allegro -->
			<userMail>maciej.kowalski@atomstore.pl</userMail> <!-- aktualny adres e-mail klienta -->
			<username><![CDATA[ Maciej Kowalski ]]></username> <!-- nazwa klienta -->
			<email>maciej.kowalski@atomstore.pl</email> <!-- adres e-mail klienta zapisany w zamówieniu -->
			<newsletter>0</newsletter> <!-- czy klient jest zapisany do newslettera (1 = tak, 0 = nie) -->
			<language>pol</language> <!-- język klienta -->
			<shippingAddressId><![CDATA[ 32312 ]]></shippingAddressId> <!-- id adresu dostawy -->
			<shippingFirstName><![CDATA[ Maciej ]]></shippingFirstName> <!-- adres dostawy: imię -->
			<shippingLastName><![CDATA[ Kowalski ]]></shippingLastName> <!-- adres dostawy: nazwisko -->
			<shippingCompany><![CDATA[ ]]></shippingCompany> <!-- adres dostawy: nazwa firmy -->
			<shippingStreet><![CDATA[ Partyzantów ]]></shippingStreet> <!-- adres dostawy: ulica -->
			<shippingStreetNumber1><![CDATA[ 5 ]]></shippingStreetNumber1> <!-- adres dostawy: numer domu -->
			<shippingStreetNumber2><![CDATA[ ]]></shippingStreetNumber2> <!-- adres dostawy: numer lokalu  -->
			<shippingPostCode><![CDATA[ 31-435 ]]></shippingPostCode> <!-- adres dostawy: kod pocztowy -->
			<shippingCity><![CDATA[ Kraków ]]></shippingCity> <!-- adres dostawy: miejscowość -->
			<shippingStateCode><![CDATA[ 12 ]]></shippingStateCode> <!-- adres dostawy: kod województwa -->  
			<shippingState><![CDATA[ małopolskie ]]></shippingState> <!-- adres dostawy: województwo -->
			<shippingCountryCode>pl</shippingCountryCode> <!-- adres dostawy: kod kraju -->
			<shippingCountry><![CDATA[ Polska ]]></shippingCountry> <!-- adres dostawy: nazwa kraju -->
			<shippingPhone><![CDATA[ 543215432 ]]></shippingPhone> <!-- adres dostawy: telefon kontaktowy -->
			<paymentUser>0</paymentUser> <!-- czy płatnikiem do zamówienia jest inny klient -->
			<paymentAddressId><![CDATA[ 32311 ]]></paymentAddressId> <!-- id adresu klienta -->
			<paymentFirstName><![CDATA[ Maciej ]]></paymentFirstName> <!-- dane klienta: imię -->
			<paymentLastName><![CDATA[ Kowalski ]]></paymentLastName> <!-- dane klienta: nazwisko -->
			<paymentCompany><![CDATA[ NetArch ]]></paymentCompany> <!-- dane klienta: nazwa firmy -->
			<paymentNIP><![CDATA[ 945-208-91-38 ]]></paymentNIP> <!-- dane klienta: NIP -->
			<paymentStreet><![CDATA[ Turystyczna ]]></paymentStreet> <!-- dane klienta: ulica -->
			<paymentStreetNumber1><![CDATA[ 777 ]]></paymentStreetNumber1> <!-- dane klienta: numer domu -->
			<paymentStreetNumber2><![CDATA[ 2 ]]></paymentStreetNumber2> <!-- dane klienta: numer lokalu -->
			<paymentPostCode><![CDATA[ 31-213 ]]></paymentPostCode> <!-- dane klienta: kod pocztowy -->
			<paymentCity><![CDATA[ Kraków ]]></paymentCity> <!-- dane klienta: miejscowość -->
			<paymentStateCode><![CDATA[ 12 ]]></paymentStateCode> <!-- dane klienta: kod województwa --> 
			<paymentState><![CDATA[ małopolskie ]]></paymentState> <!-- dane klienta: województwo -->
			<paymentCountryCode>pl</paymentCountryCode> <!-- dane klienta: kod kraju -->
			<paymentCountry><![CDATA[ Polska ]]></paymentCountry> <!-- dane klienta: nazwa kraju -->
			<paymentPhone><![CDATA[ 543215432 ]]></paymentPhone> <!-- dane klienta: telefon kontaktowy -->
			<paymentTerm><![CDATA[ 2015-05-10 ]]></paymentTerm> <!-- termin płatności do zamówienia -->
		</client>
		<admin>
			<email>admin_sprzedaz_1</email> <!-- login opiekuna zamówienia -->
		</admin>
		<products>
			<positionID>88777</positionID> <!-- id pozycji zamówienia w bazie zamówień AtomStore -->
			<code>kkk111</code> <!-- kod produktu lub wariantu -->
			<productID>5505</productID> <!-- id produktu w AtomStore -->
			<productName> <!-- nazwa pozycji zamówienia -->
				<![CDATA[ Pompka do roweru ]]>
			</productName>
			<price>12.1951</price> <!-- cena jednostkowa netto, waluta zamówienia -->
			<priceBrutto>15.00</priceBrutto> <!-- cena jednostkowa brutto, waluta zamówienia -->
			<defaultPrice>12.1951</defaultPrice> <!-- cena podstawowa netto, waluta zamówienia -->
			<tax>23</tax> <!-- stawka VAT -->
			<quantity>2</quantity> <!-- zamówiona ilość produktu -->
			<noReturn>0</noReturn> <!-- promocja z brakiem prawa zwrotu -->
			<unit>sztuka</unit> <!-- jednostka -->
			<combinationID>0</combinationID>
			<combinationName>
				<![CDATA[ ]]>
			</combinationName>
			<comments> <!-- uwagi kupującego do zamawianego towaru -->
				<![CDATA[ Nie potrzebuję mocowania. ]]>
			</comments>
			<serial></serial>
			<producer>
				<![CDATA[ Unibike ]]> <!-- nazwa producenta -->
			</producer>
			<kitID>0</kitID> <!-- id zestawu, jeśli produkt został zakupiony w zestawie -->
			<gratis>0</gratis> <!-- czy jest to produkt gratisowy (1 = tak, 0 = nie) -->
			<availabilityStatusId>1</availabilityStatusId> <!-- id statusu dostępności w chwili zakupu -->
		</products>
		<products>
			<positionID>88778</positionID>
			<code>www222_1</code> <!-- priorytet kodu wariantu, o ile jest niepusty -->
			<productID>5403</productID>
			<productName>
				<![CDATA[ Rower Hexagon ]]>
			</productName>
			<price>644.0569</price>
			<priceBrutto>792.19</priceBrutto> 
			<defaultPrice>700.0000</defaultPrice>
			<tax>23</tax>
			<quantity>1</quantity>
			<noReturn>0</noReturn>
			<unit>sztuka</unit>
			<combinationID>22230</combinationID> <!-- id wybranego przez klienta wariantu -->
			<combinationName> <!-- nazwa wariantu (atrybuty opisujące wariant) -->
				<![CDATA[ rozmiar ramy: 28 ]]>
			</combinationName>
			<serial></serial>
			<producer>
				<![CDATA[ Kross ]]>
			</producer>
			<kitID>0</kitID>
			<gratis>0</gratis>
			<availabilityStatusId>1</availabilityStatusId>
		</products>
		<products>
			<positionID>88779</positionID>
			<code></code>
			<productID>5403</productID>
			<externalId>eee_333</externalId> <!-- zewnętrzny identyfikator produktu, o ile został nadany -->
			<productName>
				<![CDATA[ Pakiet w serwisie w Krakowie ]]>
			</productName>
			<price>81.2927</price>
			<priceBrutto>99.99</priceBrutto>
			<defaultPrice>81.2927</defaultPrice>
			<tax>23</tax> 
			<quantity>1</quantity>
			<noReturn>0</noReturn>
			<unit>sztuka</unit>
			<combinationID>33331</combinationID> 
			<combinationName>
				<![CDATA[ zakres: tylko naprawa ]]>
			</combinationName>
			<serial>111-222-333-444</serial> <!-- numer seryjny wprowadzony przez klienta np. na rzecz przedłużenia licencji -->
			<extras> <!-- dodatkowe dane wprowadzone przez klienta wraz z numerem seryjnym -->
				<extra label="Imię i nazwisko"><![CDATA[ Karolina Kowalska ]]></extra>
				<extra label="Telefon kontaktowy"><![CDATA[ 771231232 ]]></extra>
			</extras>
			<producer>
				<![CDATA[ ]]>
			</producer>
			<kitID>0</kitID>
			<gratis>0</gratis>
			<availabilityStatusId>2</availabilityStatusId>
		</products>
		<otherIdentifiers> <!-- inne identyfikatory zamówienia -->
			<otherIdentifier>
				<module>MODULE_ALLEGRO</module> <!-- klucz modułu / integracji -->
				<identifier>xxx-yyy-zzz</identifier> <!-- identyfikator -->
				<name></name> <!-- nazwa pomocnicza -->
			</otherIdentifier>
		</otherIdentifiers>
		<order_fields> <!-- dodatkowe pola opisujące zamówienie -->
			<order_field>
				<id>7</id> <!-- id pola -->
				<key>b2b_own_number</key> <!-- klucz pola -->
				<name><![CDATA[Numer własny]]></name> <!-- nazwa pola -->
				<value><![CDATA[RO713]]></value> <!-- wartość dla zamówienia -->
			</order_field>
		</order_fields>
	</order>
	<order> <!-- zamówienie dropshippingowe -->
		<id>532</id>
		<!-- (...) -->
		<dropshipping>1</dropshipping> 
		<dropshippingCodValue>999.99</dropshippingCodValue> <!-- wartość pobrania przy zamówieniu dropshippingowym -->
		<!-- (...) -->
		<client>
			<userID>4195</userID> 
			<subUserID>5206</subUserID> <!-- id subkonta klienta -->
			<!-- (...) -->
			<shippingPhone><![CDATA[ 500111222 ]]></shippingPhone>
			<shippingEmail><![CDATA[ nowak@gmail.com ]]></shippingEmail> <!-- adres e-mail adresata przesyłki -->
			<!-- (...) -->
		</client>
		<!-- (...) -->
	</order>
	<order> <!-- zamówienie złożone przez handlowca na rzecz wybranego klienta i/lub realizacja oferty -->
		<id>533</id>
		<!-- (...) -->
		<client>
			<!-- (...) -->
		</client>
		<salesrep>
			<email>adres_handlowca@domena.pl</email> <!-- adres e-mail handlowca -->
			<code>PH_X</code> <!-- akronim handlowca -->
			<firstname>Przykładowy</firstname> <!-- imię handlowca -->
			<lastname>handlowiec</lastname> <!-- nazwisko handlowca -->
		</salesrep>
		<offerName><![CDATA[ testowa ]]></offerName> <!-- nazwa realizowanej oferty -->
		<!-- (...) -->
	</order>
	<order> <!-- zamówienie z kuponem rabatowym -->
		<id>534</id>
		<!-- (...) -->
		<couponValue>10.00</couponValue> <!-- wartość kuponu, brutto, waluta zamówienia -->
		<couponName>nagroda za recenzję produktu</couponName> <!-- nazwa kuponu -->
		<couponCode>ABCDEF999</couponCode> <!-- kod kuponu rabatowego -->
		<!-- (...) -->
	</order>
</orders>

Uwagi:
– filtrowanie wg parametru 'orderStatusId’ nie wymaga, aby podany status był dla danego zamówienia statusem bieżącym, tylko tego, żeby był on obecny w historii tego zamówienia; dzięki temu można dokonywać kolejnych zmian po stronie sklepu bez ryzyka, że zewnętrzna integracja nie zdążyła jeszcze pobrać pasujących danych (np. integracja pobiera zamówienia ze statusem 'Opłacone’, a administrator zmienia status na 'Przekazane do magazynu’ – mimo to, dane będą zwrócone z Atom API, ponieważ status 'Opłacone’ jest zachowany w historii zamówienia),
– jeśli w ustawieniach sklepu zdefiniowano prefiks / sufiks do numerów zamówień, nie należy ich przekazywać w parametrze 'fromOrderId’,
– znaczniki występujące w danych warunkowo:

externalIdwystępuje, jeśli nadano zamówieniu zewnętrzny identyfikator
numberwystępuje, jeśli w konfiguracji AtomStore (preferencje administracyjne) zdefiniowano format dla alternatywnych kodów zamówień
codepole możliwe do włączenia/wyłączenia w ustawieniach Atom API
shippingMethodOptionKeywystępuje tylko dla form dostawy, dla których zdefiniowano opcje i tylko wtedy, gdy wybrana opcja ma przypisany niepusty kod 
shippingBills
paymentBills		koszty dostawy/płatności rozbite proporcjonalnie wg różnych stawek VAT występujących w zamówieniu (struktura wraz z opisem poniżej); pole możliwe do włączenia/wyłączenia w ustawieniach modułu „Fakturowanie” w panelu AtomStore
store_id store_nameznaczniki obecne przy włączonym module Multistore
allegroNumber
allegroTransactionId
allegroAccount		występują tylko dla zamówień zaimportowanych z Allegro
couponCodewystępuje tylko dla zamówień, w których wykorzystany został kupon rabatowy i tylko przy odpowiednim ustawieniu Atom API (alternatywnie kod kuponu może być wskazany przy konkretnych pozycjach zamówienia)
paymentTransactionId
paymentTransactionDate
paymentCommission		występują tylko wtedy, gdy zamówienie zostało opłacone za pośrednictwem płatności interentowych
paymentsalternatywna (względem powyższej), bardziej szczegółowa notacja wpłat do zamówienia (struktura wraz z opisem poniżej), zwracana tylko przy odpowiedniej konfiguracji Atom API 
receiptNumberznacznik obecny, jeśli wystawiono paragon do zamówienia
invoicesznacznik obecny, jeśli wystawiono fakturę (jedną lub więcej) do zamówienia
dropshippingnie występuje, jeśli moduł dropshippingu jest wyłączony
dropshippingCodValuewystępuje tylko dla zamówień dropshippingowych
client → subUserIDznacznik obecny, jeśli zamówienie zostało złożone poprzez subkonto klienta
client → externalIdwystępuje tylko dla klientów z nadanym identyfikatorem zewnętrznym
client → allegroUserId
client → allegroUserLogin		występują tylko dla zamówień zaimportowanych z Allegro
client → shippingEmailwystępuje tylko dla zamówień dropshippingowych
client → paymentStateCode
client → shippingStateCode		występuje tylko gdy określono kod województwa
client → shippingField…
client → paymentField…		dodatkowe pola adresowe zdefiniowane na życzenie sprzedawcy w kontakcie z BOK AtomStore;
nazwa znacznika to 'shippingField’ / 'paymentField’ połączone z kluczem pola, np. <paymentFieldRegon>
adminwystępuje dla zamówień, do których przypisano opiekuna
salesrepwystępuje tylko w zamówieniach złożonych przez handlowców
offerNamenie występuje, jeśli moduł ofertowania jest wyłączony
products → positionIDpole możliwe do włączenia/wyłączenia w ustawieniach Atom API
products → externalIdwystępuje tylko dla produktów z nadanym identyfikatorem zewnętrznym
products → unitpole możliwe do włączenia/wyłączenia w ustawieniach Atom API;
możliwe wartości: sztuka / komplet / para / opakowanie / kilogram / litr / metr / metr kwadratowy / metr sześcienny / gram
products → commentstylko gdy kupujący podał uwagi do zamawianego produktu
products → extrasnie występuje automatycznie – wymaga konsultacji z BOK AtomStore
products → producerpole możliwe do włączenia/wyłączenia w ustawieniach Atom API
products → couponCodewskazanie, że kupon został wykorzystany na konkretną pozycję zamówienia – tylko przy odpowiedniej konfiguracji Atom API
otherIdentifierswymaga odpowiedniej konfiguracji Atom API
order_fieldstylko gdy uzupełniono dodatkowe pola do zamówienia

 – w polach <statusID>, <paymentMethodId> oraz <shippingMethodId> mogą być zwracane zewnętrzne identyfikatory statusów / form płatności / form dostawy, o ile tylko zostały zdefiniowane,
– pole <trackingNumber> może wystąpić więcej niż 1 raz dla 1 zamówienia (dla zamówień wysłanych w wielu paczkach),
– struktura dla kosztów dostawy/płatności rozbitych wg stawek VAT występujących w zamówieniu:

<shippingBills> <!-- przykład rozbicia kosztu dostawy w wysokości 13,00zł -->
	<shippingBill>
		<price>8.66</price> <!-- cząstkowy koszt dostawy, wartość brutto, waluta zamówienia -->
		<taxValue>23</taxValue> <!-- stawka VAT -->
	</shippingBill>
	<shippingBill>
		<price>4.34</price>
		<taxValue>5</taxValue>
	</shippingBill>
</shippingBills>
<paymentBills> <!-- przykład rozbicia kosztu płatności (np. pobrania) w wysokości 3,00zł -->
	<paymentBill>
		<price>2.00</price> <!--  -->
		<taxValue>23</taxValue> <!--  -->
	</paymentBill>
	<paymentBill>
		<price>1.00</price>
		<taxValue>5</taxValue>
	</paymentBill>
</paymentBills>

– szczegółowe dane wpłat do zamówienia wymagają uruchomienia w ustawieniach Atom API; pozwalają m.in. na rozróżnienie wpłat cząstkowych; zwracana struktura:

<payments>
	<payment>
		<voucher>0</voucher> <!-- czy płatność bonem (id użytego bonu) -->
		<paymentValue>100.00</paymentValue> <!-- kwota wpłaty, brutto, waluta zamówienia -->
		<paymentTransactionId>ieungyxwgn</paymentTransactionId> <!-- identyfikator wpłaty -->
		<paymentTransactionNumber>472477477</paymentTransactionNumber> <!-- dodatkowy identyfikator wpłaty -->
		<paymentTransactionDate>2016-04-21 13:20:11</paymentTransactionDate> <!-- data wpłaty -->
		<paymentCommission>2.90</paymentCommission> <!-- prowizja dla operatora płatności -->
	</payment>
	<payment>
		<voucher>0</voucher>
		<paymentValue>59.99</paymentValue>
		<paymentTransactionId></paymentTransactionId> <!-- numer transakcji może być pusty -->
		<paymentTransactionNumber>472477477</paymentTransactionNumber> 
		<paymentTransactionDate>2016-04-23 18:00:11</paymentTransactionDate>
		<paymentCommission></paymentCommission> <!-- prowizja może być nieokreślona -->
	</payment>
</payments>

– zwracane zamówienia porządkowane są kolejno wg <id> lub – jeśli przekazano parametry 'limit’ i 'timestamp’ – wg daty ostatniej modyfikacji (przy czym parametr 'receipt’ = 1 wymusza sortowanie po id),
– różnicowanie danych: zalecane jest korzystanie z parametrów 'limit’ i 'timestamp’; po stronie klienta SOAP należy wyodrębnić z pierwszego pakietu maksymalną wartość pola <modified>, a następnie przekazać tę datę do kolejnego wywołania GetOrdersSpecified, itd.; alternatywnie, jeśli pobierane mają być tylko nowe zamówienia, skorzystać można z parametru 'fromOrderId’ i w kolejnych zapytaniach przestawiać nie datę, tylko ów numer, od którego mają być uwzględniane zamówienia,
– jedno zamówienie może być zwracane wielokrotnie – po stronie klienta SOAP powinien być rejestrowany zestaw przetworzonych numerów zamówień z AtomStore, po to, żeby to samo zamówienie nie tworzyło w systemie zewnętrznym kolejnych instancji – duplikatów.

GetOrdersStatuses

Pobranie zdefiniowanego w panelu sklepu słownika statusów zamówień.

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$response = $client->GetOrdersStatuses($authenticate);
header('Content-Type: application/xml');
echo $response;

Dane zwracane + komentarze: 

<orderStatuses>
	<orderStatus>
		<id>2</id> <!-- identyfikator statusu zamówienia -->
		<name>Nowe</name> <!-- nazwa statusu zamówienia -->
	</orderStatus>
	<orderStatus>
		<id>3</id>
		<name>W trakcie realizacji</name>
	</orderStatus>
</orderStatuses>

GetOrderStatus

Pobranie identyfikatora bieżącego statusu wskazanego zamówienia.

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’
orderIdtakint–numer zamówienia w AtomStore

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$response = $client->GetOrderStatus($authenticate, 7812);
echo $response;

Dane zwracane: 

3

Uwagi:
– nazwę aktualnego statusu można uzyskać na podstawie jego id oraz słownika zwracanego z metody GetOrdersStatuses,
– kontrahent może sprawdzać status jedynie własnych zamówień, w przeciwnym wypadku zwrócony zostanie błąd „User API: brak dostępu do zamówienia”.

GetProductByCode

Pobranie identyfikatora lub pełnych danych produktu o zadanym kodzie.

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’
codetakstring–kod szukanego produktu
only_idnieint11 = zwrócony zostanie jedynie identyfikator towaru w AtomStore; 0 = zwrócone zostaną pełne dane produktu w formacie XML zgodnym z metodą GetProducts
check_combinations nie int 01 = dodatkowa próba odnalezienia produktu po kodzie konkretnego wariantu (np. rozmiaru); 0 = produkt odszukiwany tylko i wyłącznie wg kodu produktu

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$response = $client->GetProductByCode($authenticate, 'kkk111');
echo $response;

Dane zwracane: 

12001

Uwagi:
– w przypadku braku towaru o zadanym kodzie zwrócony zostanie komunikat NOT_FOUND,
– pełne dane produktu zwracane są analogicznie do wywołania metody GetProducts z parametrami all_images=1 (komplet zdjęć), combinations=1 (dane wariantów), get_attributes=1 (wszystkie atrybuty).

GetProductQuantities

Pobranie stanów w magazynie własnym i u dostawców, a także informacji o bieżącym statusie dostępności produktów.

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’
reservationsniebooleanfalseczy zwracane stany mają być pomniejszone o ilości zarezerwowane w niezrealizowanych zamówieniach (niezalecane)
modifiedniestring1970-01-01data ostatniej zmiany – parametr pozwalający na różnicowe pobieranie danych;
zwracane są tylko stany produktów zmodyfikowanych z tą datą lub później;
możliwe przekazanie daty i godziny, np. 2015-05-20 20:47:59

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$response = $client->GetProductQuantities($authenticate, false, '2015-05-20 20:47:59');
header('Content-Type: application/xml');
echo $response;

Dane zwracane + komentarze: 

<products>
	<product>
		<code>M51616151-BK</code> <!-- kod produktu -->
		<own>1</own> <!-- oznaczenie magazynu własnego -->
		<quantity>0</quantity> <!-- stan magazynowy -->
		<purchase_price>19.50</purchase_price> <!-- cena zakupu netto -->
		<auto_status>1</auto_status> <!-- wskazanie, iż produkt ma automatyczny status dostępności -->
	</product>
	<product>
		<code>M51616151-BK</code>
		<inventory_supplier>Dostawca X</inventory_supplier> <!-- nazwa dostawcy-->
		<quantity>432</quantity> <!-- stan u dostawcy -->
		<purchase_price>19.50</purchase_price> <!-- cena zakupu netto -->
	</product>
	<product>
		<code>M51616151-TAN</code>
		<own>1</own>
		<quantity>22</quantity>
		<purchase_price>19.50</purchase_price> <!-- cena zakupu netto -->
		<status_name>
			<![CDATA[ Dostępny wkrótce ]]>
		</status_name> <!-- nazwa ręcznego statusu dostępności, jeśli został przypisany do produktu -->
	</product>
</products>

Uwagi:
– warianty produktów stanowią osobne pozycje <product> w XML, z własnym kodem i własnym stanem magazynowym,
– nie są zwracane produkty będące zestawami, a także produkty i warianty z pustym kodem,
– kolejność zwracanych danych jest nieustalona.

GetProducts

Parametry wejściowe:

Pobranie pełnych danych towarowych.

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’
product_idniestring id produktu w AtomStore LUB zakres id w formie 'x-y’
all_imagesnieint00 – zwrócona zostanie informacja tylko o głównym zdjęciu produktu;
1 – zwrócone zostaną informacje o wszystkich zdjęciach przypisanych do produktu
image_sizenieimagesizenullstruktura składająca się z pól 'width’ i 'height’, pozwala narzucić maksymalne rozmiary dla zwracanych zdjęć produktu – pobierane dane będą zawierać odnośniki do gotowych miniatur w zadanym rozmiarze
combinationsnieint00 – dane zwracane bez informacji o wariantach produktu;
1 – dane zwracane wraz z informacjami o wariantach produktu
get_attributesnieint00 – dane z wyłączeniem atrybutów opisujących poszczególne towary;
1 – dane wraz z atrybutami
modifiedniestring1970-01-01data ostatniej zmiany – parametr pozwalający na różnicowe pobieranie danych;
zwracane są tylko produkty zmodyfikowane z tą datą lub później;
możliwe przekazanie daty i godziny, np. 2015-05-20 20:47:59
only_new_productsnieint00 – zwrócone zostaną produkty dodane lub zmodyfikowane z datą z parametru 'modified’ lub później;
1 – zwrócone zostaną tylko produkty nowe względem daty z parametru 'modified’
limitnieint0ilość pobieranych kartotek;
0 – brak limitu
verifiedniestring 0 – tylko kartoteki niezweryfikowane (oznaczenie administracyjne, bez wpływu na dostępność i wyświetlanie towarów); 1 – tylko kartoteki zweryfikowane; ” – brak filtrowania po fladze weryfikacji
phraseniestring fraza, po której zostaną wyszukane produkty

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$imagesize = array('width' => 250, 'height' => 150);
$response = $client->GetProducts($authenticate, 15249, 1, $imagesize, 1, 1);
header('Content-Type: application/xml');
echo $response;

Dane zwracane + komentarze: 

<products>
	<product>
		<id>15249</id> <!-- id produktu w AtomStore -->
		<created>2015-05-20 21:59:33</created> <!-- data dodania -->
		<modified>2015-05-20 22:10:02</modified> <!-- data ostatniej modyfikacji -->
		<code>kod-zestawu-X</code> <!-- kod produktu -->
		<product_name> <!-- nazwa -->
			<![CDATA[[Zestaw] Kulki Guarder + Lufa precyzyjna o długości 510 mm]]>
		</product_name> 
		<product_description> <!-- opis, może zawierać znaczniki HTML -->
			<![CDATA[Kulki 0,30-1000 [Guarder]<br /><br />Firma GUARDER wyszła na przeciw oczekiwaniom graczy...]]>
		</product_description>
		<producer_name> <!-- nazwa producenta -->
			<![CDATA[ Guarder ]]>
		</producer_name>
		<category aid="33"> <!-- kategoria jako ścieżka, poziomy oddzielone ukośnikiem; aid = identyfikator kategorii w sklepie -->
			<![CDATA[ WYPOSAŻENIE TAKTYCZNE/AKCESORIA ]]>
		</category>
		<category aid="22"> <!-- dodatkowa kategoria (może być ich wiele) -->
			<![CDATA[ MAGAZYNKI ]]>
		</category>
		<attributes> <!-- atrybuty - ich nazwy i wartości -->
			<attribute>
				<name><![CDATA[ Rodzaj_akumulatora ]]></name>
				<value><![CDATA[ litowo-jonowy ]]></value>
			</attribute>
			<attribute>
				<name><![CDATA[ Okres_gwarancji ]]></name>
				<value><![CDATA[ 24 m-ce ]]></value>
			</attribute>
			<attribute>
				<name><![CDATA[ Materiał ]]></name>
				<value><![CDATA[ żelazo ]]></value>
			</attribute>
			<attribute>
				<name><![CDATA[ Kolor ]]></name>
				<value><![CDATA[ czarny ]]></value>
			</attribute>
		</attributes>
		<price_netto>52.1138</price_netto> <!-- cena netto (zgodna z cennikiem kontrahenta) -->
		<price_promo>32.0000</price_promo> <!-- cena promocyjna netto; znacznik obecny, jeśli promocja jest zdefiniowana -->
		<vat_rate>23</vat_rate> <!-- stawka podatkowa -->
		<new>1</new> <!-- czy produkt jest oznaczony jako nowość (1 = tak, 0 = nie) -->
		<recommended>0</recommended> <!-- czy produkt jest oznaczony jako wyróżniony -->
		<bestseller>0</bestseller> <!-- czy produkt jest na liście bestsellerów -->
		<weight>0.6000</weight> <!-- waga (ciężar) produktu w kg -->
		<views>0</views> <!-- ilość odsłon karty produktu -->
		<purchases>0.0000</purchases> <!-- ilość zakupiona, w dowolnym okresie -->
		<active>1</active> <!-- czy produkt jest aktywny -->
		<only_gratis>0</only_gratis> <!-- czy produkt jest dostępny tylko jako gratis -->
		<only_suppliers>0</only_suppliers> <!-- czy dostępność u dostawców jest priorytetowa względem magazynu własnego  -->
		<login_request>0</login_request> <!-- czy produkt jest dostępny tylko dla zalogowanych -->
		<suggested_price>0.0000</suggested_price> <!-- cena katalogowa (rynkowa) netto -->
		<loyalty_points_price>15000</loyalty_points_price> <!-- cena punktowa; pole obecne przy włączonym p. lojalnościowym -->
		<loyalty_points_addition>30</loyalty_points_addition> <!-- ilość punktów za zakup; pole obecne przy wł. p. lojalnościowym -->
		<unit>sztuka</unit> <!-- jednostka -->
		<item_unit>sztuka</item_unit> <!-- podjednostka -->
		<items_per_package>5</items_per_package> <!-- ilość sztuk w opakowaniu -->
		<min_order>1.0000</min_order> <!-- minimum logistyczne -->
		<images> <!-- zdjęcia -->
			<image>
				<name> <!-- nazwa pliku -->
					<![CDATA[ 2_5392_0_3183.jpg ]]>
				</name>
				<title> <!-- tytuł zdjęcia (dla SEO) -->
					<![CDATA[[Zestaw] Kulki + Lufa]]>
				</title>
				<description> <!-- opis zdjęcia (dla SEO) -->
					<![CDATA[[Zestaw] Kulki + Lufa]]>
				</description>
				<url>http://demo.atomstore.pl/img/imagecache/150x100_product_media_2_5392_0_3183.jpg</url> <!-- URL zdjęcia -->
				<stores_excluded>2,4</stores_excluded> <!-- id wykluczonych sklepów (multistore) -->
			</image>
			<image>
				<name>
					<![CDATA[ 300x240_product_media_SRB_229_1.jpg ]]>
				</name>
				<title>
					<![CDATA[[Zestaw] Kulki + Lufa]]>
				</title>
				<description>
					<![CDATA[[Zestaw] Kulki + Lufa]]>
				</description>
				<url>http://demo.atomstore.pl/img/imagecache/150x120_product_media_SRB_229_1.jpg</url>
				<stores_excluded></stores_excluded>
			</image>
		</images>
		<tags> <!-- tagi oddzielone przecinkami -->
			<![CDATA[ tag1,tag2,test ]]>
		</tags> 
		<seo_alias>zestaw-kulki-guarder-lufa-precyzyjna-o-dlugosci-510-mm</seo_alias> <!-- alias na rzecz przyjaznego linku -->
		<seo_title> <!-- title strony produktu (metatag dla SEO) -->
			<![CDATA[ test SEO title ]]>
		</seo_title> 
                <seo_title lang="eng"> <!-- title strony produktu w innym jezyku niż domyślny (metatag dla SEO) -->
                       <![CDATA[ test SEO title ]]>
                </seo_title> 
                <seo_title lang="rus"> <!-- title strony produktu w innym jezyku niż domyślny (metatag dla SEO) -->
                       <![CDATA[ test SEO title ]]>
                </seo_title> 
		<seo_keywords> <!-- słowa kluczowe strony produktu (dla SEO) -->
			<![CDATA[ test,SEO,keywords ]]>
		</seo_keywords> 
                <seo_keywords lang="eng"> <!-- słowa kluczowe strony produktu w innym jezyku niż domyślny (dla SEO) -->
                        <![CDATA[ test,SEO,keywords ]]>
                </seo_keywords> 
                <seo_keywords lang="rus"> <!-- słowa kluczowe strony produktu w innym jezyku niż domyślny (dla SEO) -->
                        <![CDATA[ test,SEO,keywords ]]>
                </seo_keywords> 
		<seo_description> <!-- opis strony produktu (metatag dla SEO) -->
			<![CDATA[ test SEO description ]]>
		</seo_description> 
                <seo_description lang="eng"> <!-- opis strony produktu w innym jezyku niż domyślny (metatag dla SEO) -->
                	<![CDATA[ test SEO description ]]>
                </seo_description> 
                <seo_description lang="rus"> <!-- opis strony produktu w innym jezyku niż domyślny (metatag dla SEO) -->
			<![CDATA[ test SEO description ]]>
                </seo_description> 
		<update>0</update> <!-- znacznik obecny gdy przekazano parametr only_new_products = 1 -->
		<url>http://demo.atomstore.pl/zestaw-kulki-guarder-lufa-precyzyjna-o-dlugosci-510-mm</url> <!-- adres strony produktu -->
		<package_content> <!-- znacznik obecny przy włączonym module zestawów, niepusty jeśli produkt jest zestawem -->
			<code quantity="1">BB-30(1000)</code> <!-- ilość i kod produktu składowego -->
			<code quantity="1">RAG-WE--017(L)</code> <!-- UWAGA: podprodukty bez kodu nie są zwracane -->
		</package_content>
		<related_products> <!-- produkty powiązane -->
			<related_product>pr-20180802-1056</related_product> <!-- kod produktu powiązanego -->
			<related_product>pr-20180802-1057</related_product>
		</related_products>
	</product>
	<product>
		<code>pr-20180802-1052</code>
		<!-- (...) -->
		<service code="dodatkowa gwarancja">1</service> <!-- czy produkt jest usługą + opcjonalnie kod grupy usług -->
		<services></services>
	</product>
	<product>
		<code>pr-20180802-1107</code>
		<!-- (...) -->
		<service>0</service>
		<services> <!-- lista usług przypisanych do produktu -->
			<code><![CDATA[pr-20180802-1111]]></code> <!-- kod produktu będącego usługą -->
			<code><![CDATA[pr-20180802-1112]]></code>
		</services>
	</product>
</products>

Uwagi:
– dla produktów przeniesionych do kosza w danych znajdzie się dodatkowo znacznik <deleted>1</deleted>; towary normalnie usunięte nie figurują w bazie danych AtomStore, więc nie zostaną zwrócone z GetProducts,
– strukutura danych (wewnątrz <product>) dla produktów z wariantami, gdy przekazano parametr 'combinations’ = 1: 

<combinations>
	<combination>
		<id>123</id> <!-- id wariantu w AtomStore -->
		<code>kod_wariantu_X</code> <!-- kod wariantu -->
		<price_modifier>+</price_modifier> <!-- modyfikator ceny (+, -, =, %) -->
		<price_value>0.00</price_value> <!-- wartość modyfikacji ceny (netto) -->
		<attributes> <!-- atrybuty do wyboru -->
			<attribute>
				<name><![CDATA[Rozmiar]]></name>
				<value><![CDATA[L]]></value>
			</attribute>
			<attribute>
				<name><![CDATA[Kolor]]></name>
				<value><![CDATA[zielony]]></value>
			</attribute>
		</attributes>
		<params> <!-- dodatkowe atrybuty opisujące wariant -->
			<param>
				<name><![CDATA[EAN]]></name>
				<value><![CDATA[2201808021706]]></value>
			</param>
		</params>
	</combination>
	<combination>
		<id>124</id>
		<code>kod_wariantu_Y</code>
		<price_modifier>=</price_modifier>
		<price_value>159.99</price_value>
		<attributes>
			<attribute>
				<name><![CDATA[Rozmiar]]></name>
				<value><![CDATA[XXL]]></value>
			</attribute>
		</attributes>
	</combination>
</combinations>

– znaczniki występujące w danych warunkowo:

categorieswystępuje tyle razy, w ilu kategoriach jest produkt, w szczególności 0 
attributeswystępuje tylko jeśli przekazano parametr 'get_attributes’ o wartości innej niz 0
price_promowystępuje, gdy produkt jest obecnie w promocji
only_suppliersnie występuje, jeśli moduł „Dostawcy” jest wyłączony
loyalty_points_pricenie występuje, jeśli moduł „Program lojalnościowy” jest wyłączony
loyalty_points_additionj.w.
imagesnie występuje, jeśli produkt nie ma przypisanego żadnego zdjęcia
combinationswystępuje dla produktów z wariantami, jeśli przekazano parametr 'combinations’ = 1
deletedwystępuje jedynie z wartością 1, jeśli produkt został przeniesiony do kosza
updatewystępuje jedynie z wartością 0, jeśli przekazano parametr 'only_new_products’ = 1
package_contentnie występuje, jeśli moduł „Zestawy” jest wyłączony
servicetylko przy włączonym module „Usługi”
servicesj.w.

– zwracane dane są sortowane w ustalony sposób tylko jeśli przekazano parametr 'limit’ > 0, wówczas produkty są uporządkowane wg daty ostatniej modyfikacji lub wg daty dodania (jeśli przekazano parametr 'only_new_products’ = 1), rosnąco,
– różnicowanie danych: pobieranie wszystkich produktów w 1 zapytaniu jest niewskazane; preferowaną metodą podziału jest wykorzystanie parametru 'modified’ i 'limit’; po stronie klienta SOAP należy wyodrębnić z pierwszego pakietu maksymalną wartość pola <modified> (lub <created>, jeśli przekazano parametr 'only_new_products’ = 1), a następnie przekazać tę datę do kolejnego wywołania GetProducts, itd.; alternatywnie skorzystać można z metody GetProductsIdsRange i parametru 'product_id’, bez użycia parametru 'limit’ (pakiety wydzielone w ten sposób mogą zawierać różną ilość towarów, jeśli w podawanych zakresach id niektóre towary były usuwane).

GetProductsIdsRange

Pobranie zakresu id produktów w bazie AtomStore. Zwrócony zakres można dowolnie podzielić, a następnie przekazywać kolejne fragmenty w parametrze 'product_id’ do metody GetProducts celem zmniejszenia ilości danych pobieranych w jednym zapytaniu. Jest to jeden z 2 sposobów porcjowania danych z metody GetProducts, obydwa zostały objaśnione w opisie metody GetProducts.

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$response = $client->GetProductsIdsRange($authenticate);
echo $response;

Dane zwracane: 

8496-15247

GetShipmentLabels

Zwraca etykiete przysyłki

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’
order_idniestring ID zamówienia w AtomStore
tracking_numberniestring Numer paczki

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/atom_api/wsdl/atom_api');
$authenticate = array('login' => 'admin', 'password' => 'admin');
$response = $client->GetShipmentLabels($authenticate);
header('Content-Type: application/xml');
echo $response;

Dane zwracane + komentarze: 

<shipments>
    <shipment>
        <order_id>100150</order_id> <!-- ID zamówienia w AtomStore -->
        <labels>
            <label>
                <tracking_number>0000000640576Q</tracking_number> <!-- Numer paczki -->
                <url><!-- Link do pobrania etykiety paczki --></url>
            </label>
        </labels>
        <tracking_numbers>
            <tracking_number>0000000640576Q</tracking_number> <!-- Numer paczki -->
        </tracking_numbers>
    </shipment>
    <shipmentsCount>1</shipmentsCount>
</shipments>

SetOrders

Tworzenie i aktualizacja zamówień. Ograniczenia Atom User API:

– klient nie może zapisywać zamówień od innych kontrahentów, jedynie na własne konto,
– klient może aktualizować jedynie własne zamówienia,
– w jednym wywołaniu metody można stworzyć tylko jedno nowe zamówienie,
– ceny i stawki VAT produktów będą wczytane z bazy danych sklepu, nie ma możliwości ich ustalenia.

Parametry wejściowe:

nazwaobowiązkowytypdomyślnieopis
authenticatetakauth–struktura składająca się z pól 'login’ i 'password’
messagetakmessage–struktura zawierająca pole 'xml’, które powinno zawierać ciąg znaków w formacie XML; opis formatu poniżej

Format XML + komentarze:

<orders>
	<order>
		<create returnNewOrdersIds="1">1</create>
		<!-- pole create z wartością = 1 jest wymagane do utworzenia nowego zamówienia -->
		<!-- returnNewOrdersIds = 1 (dla dowolnego zamówienia) wymusza zwrócenie z metody numerów UTWORZONYCH zamówień, -->
		<!-- a jeśli nadano im identyfikatory zewnętrzne, zostaną one przyporządkowane po dwukropku -->
		<created>2017-02-14 23:40:40</created> <!-- data złożenia zamówienia (opcjonalnie; domyślnie przyjęta zostanie data zapisu) -->
		<number>05/02/2017</number> <!-- przypisania kodu zamówienia (opcjonalnie) -->
		<statusID>1</statusID> <!-- zewnętrzny lub wewnętrzny identyfikator statusu zamówienia -->
		<shippingPrice>11.00</shippingPrice> <!-- koszt dostawy, wartość brutto, waluta zamówienia -->
		<shippingTaxValue>23</shippingTaxValue> <!-- stawka VAT dla formy dostawy -->
		<shippingMethodId>fd_1</shippingMethodId> <!-- identyfikator formy dostawy -->
		<shippingMethod>Kurier</shippingMethod> <!-- nazwa formy dostawy -->
		<shippingMethodOptionKey></shippingMethodOptionKey> <!-- kod opcji dostawy (np. wybranego punktu odbioru) -->
		<shippingComments><![CDATA[ Prosze dzwonic domofonem. ]]></shippingComments> <!-- Komentarz do wysylki -->
		<shippingQuantity>1</shippingQuantity> <!-- ilość paczek (opcjonalnie) -->
		<paymentPrice>0.00</paymentPrice> <!-- koszt z tytułu formy płatności, wartość brutto, waluta zamówienia -->
		<paymentTaxValue>0</paymentTaxValue> <!-- stawka VAT dla kosztu z tytułu formy płatności -->
		<paymentMethodId>19</paymentMethodId> <!-- identyfikator formy płatności -->
		<paymentMethod>Przelew</paymentMethod> <!-- nazwa formy płatności -->
		<paymentMethodOptionKey></paymentMethodOptionKey> <!-- kod opcji płatności (np. wybranego banku dla płatności online) -->
		<salesrep> <!-- wskazanie handlowca pośredniczącego w złożeniu zamówienia (opcjonalnie) -->
			<email>adres_handlowca@domena.pl</email> <!-- adres e-mail handlowca -->
		</salesrep>
		<source>przedstawiciele</source> <!-- źródło sprzedaży - klucz (patrz: panel → USTAWIENIA → ŹRÓDŁA SPRZEDAŻY) -->
		<store_id>2</store_id> <!-- id sklepu (multistore), do którego ma zostać przypisane zamówienie -->
		<currency>GBP</currency> <!-- waluta zamówienia -->
		<comments><![CDATA[ Proszę o szybką wysyłkę. ]]></comments> <!-- uwagi do zamówienia -->
		<send_email>1</send_email> <!-- 1 = wysłanie na adres e-mail klienta powiadomienia o nowym zamówieniu -->
		<client>
			<email>maciej.kowalski@atomstore.pl</email> <!-- adres e-mail istniejącego lub nowego klienta -->
			<orderEmail>maciej.kowalski@atomstore.pl</orderEmail> <!-- adres e-mail do zapisania w zamówieniu (opcjonalnie) -->
			<shippingFirstName><![CDATA[ Maciej ]]></shippingFirstName> <!-- adres dostawy: imię -->
			<shippingLastName><![CDATA[ Kowalski ]]></shippingLastName> <!-- adres dostawy: nazwisko -->
			<shippingCompany><![CDATA[ ]]></shippingCompany> <!-- adres dostawy: nazwa firmy -->
			<shippingStreet><![CDATA[ Partyzantów ]]></shippingStreet> <!-- adres dostawy: ulica -->
			<shippingStreetNumber1><![CDATA[ 5 ]]></shippingStreetNumber1> <!-- adres dostawy: numer domu -->
			<shippingStreetNumber2><![CDATA[ ]]></shippingStreetNumber2> <!-- adres dostawy: numer lokalu  -->
			<shippingPostCode><![CDATA[ 31-435 ]]></shippingPostCode> <!-- adres dostawy: kod pocztowy -->
			<shippingCity><![CDATA[ Kraków ]]></shippingCity> <!-- adres dostawy: miejscowość -->
			<shippingCountry><![CDATA[ Polska ]]></shippingCountry> <!-- adres dostawy: nazwa kraju -->
			<shippingPhone><![CDATA[ 543215432 ]]></shippingPhone> <!-- adres dostawy: telefon kontaktowy -->
			<paymentFirstName><![CDATA[ Maciej ]]></paymentFirstName> <!-- dane klienta: imię -->
			<paymentLastName><![CDATA[ Kowalski ]]></paymentLastName> <!-- dane klienta: nazwisko -->
			<paymentCompany><![CDATA[ NetArch ]]></paymentCompany> <!-- dane klienta: nazwa firmy -->
			<paymentNIP><![CDATA[ 945-208-91-38 ]]></paymentNIP> <!-- dane klienta: NIP -->
			<paymentStreet><![CDATA[ Turystyczna ]]></paymentStreet> <!-- dane klienta: ulica -->
			<paymentStreetNumber1><![CDATA[ 777 ]]></paymentStreetNumber1> <!-- dane klienta: numer domu -->
			<paymentStreetNumber2><![CDATA[ 2 ]]></paymentStreetNumber2> <!-- dane klienta: numer lokalu -->
			<paymentPostCode><![CDATA[ 31-213 ]]></paymentPostCode> <!-- dane klienta: kod pocztowy -->
			<paymentCity><![CDATA[ Kraków ]]></paymentCity> <!-- dane klienta: miejscowość -->
			<paymentCountry><![CDATA[ Polska ]]></paymentCountry> <!-- dane klienta: nazwa kraju -->
			<paymentPhone><![CDATA[ 543215432 ]]></paymentPhone> <!-- dane klienta: telefon kontaktowy -->
		</client>
		<products>
			<code>www222_1</code> <!-- kod produktu lub wariantu -->
			<productName> <!-- nazwa pozycji zamówienia (opcjonalnie) -->
				<![CDATA[ Rower Hexagon ]]>
			</productName>
			<quantity>1</quantity> <!-- zamówiona ilość produktu (wymagana) -->
		</products>
		<products>
			<externalId>eee_333</externalId> <!-- identyfikator zewnętrzny - alternatywna identyfikacja towaru -->
			<quantity>2</quantity>
		</products>
		<products>
			<productID>5505</productID> <!-- wskazanie produktu poprzez jego identyfikator w AtomStore -->
			<quantity>1</quantity>
		</products>
		<products>
			<productID>3598</productID>
			<combinationID>47</combinationID> <!-- wskazanie wariantu poprzez jego identyfikator w AtomStore -->
			<quantity>1</quantity>
		</products>
		<products>
			<!-- pozycja bez żadnego identyfikatora - zostanie dodana, jeśli tylko podano jej nazwę i ilość -->
			<!-- niezalecane w przypadku aktualizacji zamówień - pozycja NIE będzie identyfikowana po nazwie -->
			<productName>
				<![CDATA[ Rower Hexagon ]]>
			</productName>
			<quantity>1</quantity>
		</products>
	</order>
	<order>
		<create>1</create>
		<!-- (...) -->
		<client>
			<atom_id>4195</atom_id> <!-- możliwość wskazania klienta poprzez jego id w bazie AtomStore -->
			<!-- (...) -->
		</client>
		<!-- (...) -->
	</order>
	<order>
		<create>1</create>
		<externalId>ZK714</externalId> <!-- możliwość nadania nowemu zamówieniu zewnętrznego identyfikatora -->
		<!-- (...) -->
		<client>
			<externalId>u_1238902</externalId> <!-- możliwość wskazania klienta poprzez jego zewnętrzny identyfikator -->
			<!-- (...) -->
		</client>
		<!-- (...) -->
	</order>
	<order> <!-- zamówienie dropshippingowe -->
		<create>1</create>
		<!-- (...) -->
		<dropshipping>1</dropshipping> 
		<dropshippingCodValue>999.99</dropshippingCodValue> <!-- wartość pobrania od adresata przesyłki -->
		<shippingEmail><![CDATA[ nowak@gmail.com ]]></shippingEmail> <!-- adres e-mail adresata przesyłki -->
		<client>
			<!-- (...) -->
		</client>
		<!-- (...) -->
	</order>
	<order>
		<id>521</id> <!-- numer zamówienia, które ma zostać zaktualizowane -->
		<externalId>ZK714</externalId> <!-- możliwość nadania istniejącemu zamówieniu zewnętrznego identyfikatora -->
		<statusID>5</statusID>
		<shippingPrice>11.00</shippingPrice>
		<shippingTaxValue>23</shippingTaxValue>
		<shippingMethodId>fd_1</shippingMethodId>
		<shippingMethod>Kurier</shippingMethod>
		<paymentPrice>0.00</paymentPrice>
		<paymentTaxValue>0</paymentTaxValue>
		<paymentMethodId>19</paymentMethodId>
		<paymentMethod>Przelew</paymentMethod>
		<invoiceNumber>F/06/2015/12345</invoiceNumber> <!-- numer faktury -->
		<paymentTerm>2015-06-15</paymentTerm> <!-- termin płatności -->
		<allegroNumber>555555555</allegroNumber> <!-- numer aukcji Allegro -->
		<allegroTransactionId>0</allegroTransactionId> <!-- numer transakcji Allegro -->
		<tracking_number>001122334455</tracking_number> <!-- numer listu przewozowego -->
		<unlock_quantities>1</unlock_quantities> <!-- 1 = dyspozycja zdjęcia rezerwacji stanów magazynowych -->
		<payments> <!-- płatności do zamówienia -->
			<payment>
				<paymentValue>229,41</paymentValue> <!-- wartość wpłaty, brutto, waluta zamówienia -->
				<paymentTransactionId>p_ZK714_3v3fseg2</paymentTransactionId> <!-- identyfikator transakcji (obowiązkowy) -->
			</payment>
			<payment>
				<paymentValue>0</paymentValue> <!-- możliwość przekazania zera (np. w celu skasowania wpłaty) -->
				<paymentTransactionId>p_ZK714_v38v38nv</paymentTransactionId>
			</payment>
		</payments>
		<comments send_email="1"><![CDATA[ Opóźnienie. ]]></comments> <!-- komentarz + powiadomienie (send_email = 1) -->
		<client>
			<shippingFirstName><![CDATA[ Maciej ]]></shippingFirstName>
			<shippingLastName><![CDATA[ Kowalski ]]></shippingLastName>
			<shippingCompany><![CDATA[ ]]></shippingCompany>
			<shippingStreet><![CDATA[ Partyzantów ]]></shippingStreet>
			<shippingStreetNumber1><![CDATA[ 5 ]]></shippingStreetNumber1>
			<shippingStreetNumber2><![CDATA[ ]]></shippingStreetNumber2>
			<shippingPostCode><![CDATA[ 31-435 ]]></shippingPostCode>
			<shippingCity><![CDATA[ Kraków ]]></shippingCity>
			<shippingCountryCode>pl</shippingCountryCode> <!-- możliwość wskazania kraju poprzez kod ISO 3166-1 alfa-2 -->
			<shippingPhone><![CDATA[ 543215432 ]]></shippingPhone>
			<paymentFirstName><![CDATA[ Maciej ]]></paymentFirstName>
			<paymentLastName><![CDATA[ Kowalski ]]></paymentLastName>
			<paymentCompany><![CDATA[ NetArch ]]></paymentCompany>
			<paymentNIP><![CDATA[ 945-208-91-38 ]]></paymentNIP>
			<paymentStreet><![CDATA[ Turystyczna ]]></paymentStreet>
			<paymentStreetNumber1><![CDATA[ 777 ]]></paymentStreetNumber1>
			<paymentStreetNumber2><![CDATA[ 2 ]]></paymentStreetNumber2>
			<paymentPostCode><![CDATA[ 31-213 ]]></paymentPostCode>
			<paymentCity><![CDATA[ Kraków ]]></paymentCity>
			<paymentCountryCode>pl</paymentCountryCode> <!-- możliwość wskazania kraju poprzez kod ISO 3166-1 alfa-2 -->
			<paymentPhone><![CDATA[ 543215432 ]]></paymentPhone>
			<allegroLogin>emkowal123</allegroLogin> <!-- login użytkownika Allegro -->
		</client>
		<products> <!-- aktualizacja lub dodanie produktów do zamówienia (niepodane pozycje NIE zostaną usunięte) -->
			<code>kkk111</code>
			<productName>
				<![CDATA[ Rower Hexagon ]]>
			</productName>
			<quantity>1</quantity>
		</products>
		<tracking_labels>
			<tracking_label for="111222333"><![CDATA[ (...) ]]></tracking_label> <!-- Etykieta przewozowa w formacie BASE64 -->
		</tracking_labels>
		<products forceNewEntry="1"> <!-- wymuszenie nowej pozycji zamówienia -->
			<!-- (...) -->
		</products>
	</order>
	<order>
		<externalId>ZK710</externalId> <!-- wskazanie istniejącego zamówienia poprzez identyfikator zewnętrzny -->
		<statusID>6</statusID>
	</order>
</orders>

Przykładowe wywołanie (PHP): 

$client = new SoapClient('http://demo.atomstore.pl/user_api/wsdl/user_api');
$authenticate = array('login' => 'jan@kowalski.pl', 'password' => 'kowalski123');
$xml = '<orders><order><id>521</id><tracking_number>001122334455</tracking_number></order></orders>';
$message = array('xml' => $xml);
$response = $client->SetOrders($authenticate, $message);
echo $response;

Dane zwracane: 

OK 

Uwagi:

– w polach paymentMethodId oraz shippingMethodId mogą być podane zewnętrzne identyfikatory form płatności / form dostawy, o ile tylko zostały zdefiniowane,
– formy dostawy / płatności nie muszą być rozpoznane w bazie sklepu dla poprawnego zapisu zamówień – ich nazwy i ceny są zapisywane niezależnie,
– jeśli w znaczniku <salesrep> → <email> został podany adres nieodnaleziony w bazie handlowców, pole zostanie zignorowane,
– metoda nie pozwala na zmianę waluty zamówienia,
– jeśli wskazano produkt posiadający warianty, a nie wskazano wariantu – dane zostaną zignorowane,
– nowe zamówienie, dla którego nie określono prawidłowo żadnego produktu, nie zostanie utworzone,
– niepodana nazwa towaru zostanie wczytana z bazy sklepu,
– podczas aktualizacji zamówień wymagany jest jedynie identyfikator + dowolne dane, które mają zostać nadpisane,
– pozycje aktualizowanego zamówienia, które nie zostały wskazane, nie zostaną usunięte, można to jednak przekonfigurować w ustawieniach sklepu,
– podczas tworzenia nowych zamówień wymagany jest status zamówienia, pełne dane klienta (z adresem e-mail) i minimum 1 produkt,
– w polu <statusID> można wskazać zewn. identyfikator statusu zamówienia (o ile zdefiniowano odpowiednie mapowanie) lub id statusu po stronie AtomStore (patrz: GetOrdersStatuses),
– pole <tracking_number> można przekazać więcej niż 1 raz dla 1 zamówienia, aby nadać wiele numerów paczek.

Twój e‑commerce jest gotowy na więcej?

Platforma SaaS dla marek, które myślą o wzroście. Z pełnym wsparciem: od strategii po wdrożenie i utrzymanie.