Chcesz przenieść sklep na nową platformę, ale nie wiesz jak to zrobić? Wszystkiego dowiesz się z e-booka "Migracja sklepu" Pobierz teraz

Metody

CheckConnection

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

 

Parametry wejściowe:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - 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:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - struktura składająca się z pól 'login' i 'password'
modified nie string  0000-00-00 00:00:00 zawęż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:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - struktura składająca się z pól 'login' i 'password'
orderStatusId nie string   opcjonalne filtrowanie po statusie zamówienia wskazanym poprzez id (patrz: GetOrdersStatuses); można przekazać wiele statusów oddzielając je przecinkiem
fromOrderId nie int 0 zawężenie danych do zamówień z numerem równym lub większym od podanego
limit nie int 0 ilość pobieranych zamówień; dla wartości 0 zakres zwracanych danych nie jest limitowany
timestamp nie string 0000-00-00 00:00:00 zawężenie danych do zamówień 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->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 -->
		<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 -->
		<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:

 

externalId występuje, jeśli nadano zamówieniu zewnętrzny identyfikator
number występuje, jeśli w konfiguracji AtomStore (preferencje administracyjne) zdefiniowano format dla alternatywnych kodów zamówień
code pole możliwe do włączenia/wyłączenia w ustawieniach Atom API
shippingMethodOptionKey wystę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_name

znaczniki obecne przy włączonym module Multistore
allegroNumber
allegroTransactionId
allegroAccount
występują tylko dla zamówień zaimportowanych z Allegro
couponCode wystę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
payments alternatywna (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 
receiptNumber znacznik obecny, jeśli wystawiono paragon do zamówienia
invoices znacznik obecny, jeśli wystawiono fakturę (jedną lub więcej) do zamówienia
dropshipping nie występuje, jeśli moduł dropshippingu jest wyłączony
dropshippingCodValue występuje tylko dla zamówień dropshippingowych
client → subUserID znacznik obecny, jeśli zamówienie zostało złożone poprzez subkonto klienta
client → externalId występuje tylko dla klientów z nadanym identyfikatorem zewnętrznym
client → allegroUserId
client → allegroUserLogin
występują tylko dla zamówień zaimportowanych z Allegro
client → shippingEmail wystę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>
admin występuje dla zamówień, do których przypisano opiekuna
salesrep występuje tylko w zamówieniach złożonych przez handlowców
offerName nie występuje, jeśli moduł ofertowania jest wyłączony
products → positionID pole możliwe do włączenia/wyłączenia w ustawieniach Atom API
products → externalId występuje tylko dla produktów z nadanym identyfikatorem zewnętrznym
products → unit pole 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 → comments tylko gdy kupujący podał uwagi do zamawianego produktu
products → extras nie występuje automatycznie - wymaga konsultacji z BOK AtomStore
products → producer pole możliwe do włączenia/wyłączenia w ustawieniach Atom API
products → couponCode wskazanie, że kupon został wykorzystany na konkretną pozycję zamówienia - tylko przy odpowiedniej konfiguracji Atom API
otherIdentifiers wymaga odpowiedniej konfiguracji Atom API
order_fields tylko 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 -->
		<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 -->
		<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:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - 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:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - struktura składająca się z pól 'login' i 'password'
orderId tak int - 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:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - struktura składająca się z pól 'login' i 'password'
code tak string - kod szukanego produktu
only_id nie int 1

1 = 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  0

1 = 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:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - struktura składająca się z pól 'login' i 'password'
reservations nie boolean false czy zwracane stany mają być pomniejszone o ilości zarezerwowane w niezrealizowanych zamówieniach (niezalecane)
modified nie string 1970-01-01 data 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

Pobranie pełnych danych towarowych.

 

Parametry wejściowe:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - struktura składająca się z pól 'login' i 'password'
product_id nie string   id produktu w AtomStore LUB zakres id w formie 'x-y'
all_images nie int 0

0 - zwrócona zostanie informacja tylko o głównym zdjęciu produktu;
1 - zwrócone zostaną informacje o wszystkich zdjęciach przypisanych do produktu

image_size nie imagesize null

struktura 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

combinations nie int 0 0 - dane zwracane bez informacji o wariantach produktu;
1 - dane zwracane wraz z informacjami o wariantach produktu
get_attributes nie int 0 0 - dane z wyłączeniem atrybutów opisujących poszczególne towary;
1 - dane wraz z atrybutami
modified nie string 1970-01-01 data 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_products nie int 0 0 - 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'
limit nie int 0 ilość pobieranych kartotek;
0 - brak limitu
verified nie string  

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

phrase nie string  

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_keywords> <!-- słowa kluczowe strony produktu (dla SEO) -->
			<![CDATA[ test,SEO,keywords ]]>
		</seo_keywords> 
		<seo_description> <!-- opis strony produktu (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:

 

categories występuje tyle razy, w ilu kategoriach jest produkt, w szczególności 0 
attributes występuje tylko jeśli przekazano parametr 'get_attributes' o wartości innej niz 0
price_promo występuje, gdy produkt jest obecnie w promocji
only_suppliers nie występuje, jeśli moduł "Dostawcy" jest wyłączony
loyalty_points_price nie występuje, jeśli moduł "Program lojalnościowy" jest wyłączony
loyalty_points_addition j.w.
images nie występuje, jeśli produkt nie ma przypisanego żadnego zdjęcia
combinations występuje dla produktów z wariantami, jeśli przekazano parametr 'combinations' = 1
deleted występuje jedynie z wartością 1, jeśli produkt został przeniesiony do kosza
update występuje jedynie z wartością 0, jeśli przekazano parametr 'only_new_products' = 1
package_content nie występuje, jeśli moduł "Zestawy" jest wyłączony
service tylko przy włączonym module "Usługi"
services j.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:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - 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

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:

nazwa obowiązkowy typ domyślnie opis
authenticate tak auth - struktura składająca się z pól 'login' i 'password'
message tak message - 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>
		<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.


AtomStore to platforma e-commerce klasy premium. Tworzymy dedykowane sklepy internetowe oraz systemy B2B. Oferujemy kompleksowe wdrożenia od A do Z, sklepy mobilne w technologii responsive web design, integracje z programami Comarch Optima, XL, WF-Mag, Subiekt.
Wspólnie rozwiązujemy problemy polskiego e-handlu!

Znajdź nas na:

  • Blog
  • Facebook
  • Youtube
  • Linked in
  • iab