Metody - zamówienia
CancelReceipts
Anulowanie dyspozycji wydruku paragonu. Metoda stworzona z myślą o integracji z drukarką fiskalną. W panelu sklepu administrator oznacza zamówienia, dla których ma zostać wydrukowany paragon. Integrator pobiera dane tych zamówień, przekazując do metody GetOrdersSpecified parametr 'receipt' = 1. Jeśli operator drukarki rezygnuje z wydruku paragonu, integrator może wysłać do metody CancelReceipts odpowiednią informację, aby dane tego zamówienia nie były w dalszym ciągu pobierane.
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> <id>123</id> <!-- numer zamówienia w AtomStore (wymagany) --> </order> <order> <id>126</id> </order> </orders>
Przykładowe wywołanie (PHP):
$client = new SoapClient('http://demo.atomstore.pl/atom_api/wsdl/atom_api');
$authenticate = array('login' => 'admin', 'password' => 'admin');
$xml = '<orders><order><id>123</id></order></orders>';
$message = array('xml' => $xml);
$response = $client->CancelReceipts($authenticate, $message);
echo $response;
Dane zwracane:
OK
Uwagi:
- jeśli w ustawieniach sklepu zdefiniowano prefiks / sufiks do numerów zamówień, nie należy ich przekazywać w polu <order> → <id>,
- metoda pomija zamówienia, którym w międzyczasie uzupełniono numer paragonu (takie zamówienia tak czy inaczej nie będą już zwracane do drukarki),
- zmiany wykonywane przez Atom API nie aktualizują daty ostatniej modyfikacji zamówienia, dzięki czemu zewnętrzna integracja nie pobiera niepotrzebnie informacji o własnych zmianach w ramach importu zamówień nowych / zmodyfikowanych.
GetOrders
Uogólniona postać metody GetOrdersSpecified, pozwalająca na pobranie wszystkich zamówień zapisanych w sklepie. Metoda niezalecana ze względu na potencjalnie bardzo duże ilości 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' |
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->GetOrders($authenticate);
header('Content-Type: application/xml');
echo $response;
Dane zwracane, uwagi:
Patrz: GetOrdersSpecified.
GetOrdersSpecified
Pobieranie zamówień 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 |
| receipt | nie | int | 0 | parametr stworzony z myślą o integracji z drukarką fiskalną; dla wartości 1 zwrócone zostaną zamówienia oznaczone przez administratora do wydrukowania paragonu, przy czym zamówienia z przypisanym już numerem paragonu będą pominięte |
| 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 |
| userFilter | nie | string | filtrowanie wg ID klienta w AtomStore (jeśli przekazano liczbę) lub wg adresu e-mail | |
| extraFilters | nie | string |
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/atom_api/wsdl/atom_api');
$authenticate = array('login' => 'admin', 'password' => 'admin');
$response = $client->GetOrdersSpecified($authenticate, '2,4', 0, 20, 0, '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 -->
<paymentMethodAtomId>13</paymentMethodAtomId> <!-- zewnętrzne 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ę -->
<tracking_status>W drodze</tracking_status> <!-- status listu przewozowego -->
<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>1553677547</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ą -->
<receipt>0</receipt> <!-- czy zamówienie zostało oznaczone do wydruku paragonu (1 = tak, 0 = nie) -->
<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) -->
<invoiceByEmail>1</invoiceByEmail> <!-- Zgoda na par/fv przez e-mail -->
<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 -->
<registered>0</registered> <!-- czy klient jest zarejestrowany (1 = tak, 0 = nie) -->
<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, jak wlaczone odpowiednie ustawienie to zwraca takze wartosci zw i np -->
<quantity>2</quantity> <!-- zamówiona ilość produktu -->
<noReturn>0</noReturn> <!-- promocja z brakiem prawa zwrotu -->
<unit>sztuka</unit> <!-- jednostka -->
<weight>1.0000</weight> <!-- waga produktu -->
<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>
<partner> <!-- Jesli włączony moduł partnerski -->
<partnerID>4195</partnerID> <!-- id Partnera w AtomStore -->
<email>partner@partner.pl</email> <!-- email partnera -->
<company>Partner</company> <!-- Firma partnera -->
<firstname>Partner</firstname> <!-- Imie partnera -->
<lastname>Partnerski</lastname> <!-- Nazwisko partnera -->
</partner>
</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> <moduleKey>0</moduleKey> <!-- spersonalizowany klucz voucherowy (do bonu) --> <voucher>0</voucher> <!-- czy płatność bonem (id użytego bonu) --> <paymentMethodId>13</paymentMethodId> <!-- id formy płatności --> <paymentValue>100.00</paymentValue> <!-- kwota wpłaty, brutto, waluta zamówienia --> <paymentTransactionId>ieungyxwgn</paymentTransactionId> <!-- identyfikator wpłaty --> <paymentTransactionNumber>1553677547</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> <moduleKey>0</moduleKey> <voucher>0</voucher> <paymentMethodId>13</paymentMethodId> <!-- id formy płatności --> <paymentValue>59.99</paymentValue> <paymentTransactionId></paymentTransactionId> <!-- numer transakcji może być pusty --> <paymentTransactionNumber>1553677547</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:
| 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/atom_api/wsdl/atom_api');
$authenticate = array('login' => 'admin', 'password' => 'admin');
$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/atom_api/wsdl/atom_api');
$authenticate = array('login' => 'admin', 'password' => 'admin');
$response = $client->GetOrderStatus($authenticate, 7812);
echo $response;
Dane zwracane:
3
Uwagi:
- jeśli w ustawieniach sklepu zdefiniowano prefiks / sufiks do numerów zamówień, nie należy ich przekazywać w parametrze 'orderId',
- nazwę aktualnego statusu można uzyskać na podstawie jego id oraz słownika zwracanego z metody GetOrdersStatuses.
SetInvoices
Tworzenie i aktualizacja faktur VAT oraz korekt, a także zapis płatności do 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' |
| 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:
<invoices>
<invoice>
<number>F/123/05/2015</number> <!-- numer faktury (wymagany) -->
<proforma>0</proforma> <!-- faktura proforma (1 = tak, 0 = nie) -->
<advance>0</advance> <!-- faktura zaliczkowa (1 = tak, 0 = nie) -->
<ereceipt>1</ereceipt> <!-- e-paragon (1 = tak, 0 = nie) -->
<order_id>5432</order_id> <!-- numer zamówienia w AtomStore (wymagany) -->
<date_created>2015-03-22</date_created> <!-- data wystawienia faktury (wymagana) -->
<date_sale>2015-03-22</date_sale> <!-- data sprzedaży (opcjonalnie) -->
<date_payment>2015-03-28</date_payment> <!-- termin płatności (wymagany) -->
<payment_method>Przelew</payment_method> <!-- sposób płatności (opcjonalny, priorytet nad payment_method_id) -->
<payment_method_id>2</payment_method_id> <!-- sposób płatności po id (opcjonalny) -->
<value>129.84</value> <!-- wartość dokumentu brutto (wymagana) -->
<currency>PLN</currency> <!-- waluta dokumentu (opcjonalnie) -->
<pdf_base64>...</pdf_base64> <!-- pdf zakodowany w base64 (opcjonalnie) -->
<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> <!-- inne dane pozycji dokumentu, w postaci zserializowanej -->
</invoice>
<invoice>
<number>FK/123-1/05/2015</number>
<parent>F/123/05/2015</parent> <!-- wskazanie faktury nadrzędnej - dla korekt -->
<order_id>5432</order_id>
<date_created>2015-03-29</date_created>
<date_sale>2015-03-28</date_sale>
<date_payment>2015-03-30</date_payment>
<payment_method>Gotówka</payment_method>
<value>91.84</value>
<paid>0</paid> <!-- wartość opłacona (opcjonalnie) -->
<pdf_base64/>
</invoice>
<invoice>
<number>F/130/05/2015</number>
<order_id>5438</order_id>
<additional_orders>5438|5439|5440</additional_orders> <!-- możliwość powiązania faktury z większą ilością zamówień -->
<!-- (...) -->
</invoice>
</invoices>
Przykładowe wywołanie (PHP):
$client = new SoapClient('http://demo.atomstore.pl/atom_api/wsdl/atom_api');
$authenticate = array('login' => 'admin', 'password' => 'admin');
$xml = '<invoices>';
$xml .= '<invoice>';
$xml .= '<number>F/123/05/2015</number><order_id>5432</order_id>';
$xml .= '<date_created>2015-03-22</date_created><date_sale>2015-03-22</date_sale><date_payment>2015-03-28</date_payment>';
$xml .= '<payment_method>Przelew</payment_method><value>129.84</value>';
$xml .= '</invoice>';
$xml .= '</invoices>';
$message = array('xml' => $xml);
$response = $client->SetInvoices($authenticate, $message);
echo $response;
Dane zwracane:
OK
Uwagi:
- jeśli w ustawieniach sklepu zdefiniowano prefiks / sufiks do numerów zamówień, nie należy ich przekazywać w polu <order_id>,
- wpłata zgodna z wartością pola <paid> (jeśli podano) lub pola <value> jest rejestrowana zarówno dla faktury (zawsze), jak i dla zamówienia (gdy f. VAT i przy odpowiednich ustawieniach Atom API),- aby nadpisać istniejącą fakturę (i wartość wpłaty), należy podać jej numer oraz id zamówienia w AtomStore,
- dane kupującego czerpane są automatycznie z danych wskazanego zamówienia, podobnie data sprzedaży, jeśli nie została podana,
- aktualnie metoda pozwala na zapis faktur VAT oraz korekt (wymagane pole <parent>).
SetOrderExternalId
Nadanie zamówieniu zewnętrznego identyfikatora, na rzecz wyświetlania / wykorzystania go po stronie AtomStore.
Parametry wejściowe:
| nazwa | obowiązkowy | typ | domyślnie | opis |
| authenticate | tak | auth | - | struktura składająca się z pól 'login' i 'password' |
| atomId | tak | int | - | numer zamówienia w AtomStore |
| externalId | tak | string | - | zewnętrzny identyfikator zamówienia |
| externalName | nie | string | zewnętrzna nazwa zamówienia | |
| moduleKey | nie | string | klucz integracji zewnętrznej (lub modułu w AtomStore) |
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->SetOrderExternalId($authenticate, 7812, 'agsuia#123');
echo $response;
Dane zwracane:
OK
Uwagi:
- jeśli w ustawieniach sklepu zdefiniowano prefiks / sufiks do numerów zamówień, nie należy ich przekazywać w parametrze 'atomId',
- nie ma ograniczeń odnośnie formatu identyfikatora zewnętrznego ani klucza integracji, natomiast zalecane jest stosowanie tylko cyfr i liter (bez polskich znaków),
- aktualnie zewnętrzny numer zamówienia nie może służyć do identyfikacji w metodach do zapisu zamówień (np. SetOrders) - wymagany jest numer zamówienia w AtomStore,
- zmiany wykonywane przez Atom API nie aktualizują daty ostatniej modyfikacji zamówienia, dzięki czemu zewnętrzna integracja nie pobiera niepotrzebnie informacji o własnych zmianach w ramach importu zamówień nowych / zmodyfikowanych.
SetOrders
Tworzenie i aktualizacja zamówień. Nowe zamówienie może być przypisane do istniejącego kontrahenta lub utworzone wraz z dodaniem nowego klienta.
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 |
| price_list_id | nie | int | 0 |
id cennika, z którego system pobierze cenę dla nowej pozycji zamówienia, jeśli cena nie została przekazana w danych; 0 = cennik domyślny |
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) --> <shippmentDate>2021-06-17</shippmentDate> <!-- Data wysyłki (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 --> <tracking_labels> <tracking_label for="111222333"><![CDATA[ (...) ]]></tracking_label> <!-- Etykieta przewozowa w formacie BASE64 --> <tracking_label for="111222444"><![CDATA[ (...) ]]></tracking_label> <!-- Etykieta przewozowa w formacie BASE64 --> </tracking_labels> <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 --> <currencyValue>5.88840001</currencyValue> <!-- kurs waluty --> <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 --> <inventory_enabled>0</inventory_enabled> <!-- 0 = brak reakcji magazynu na zapis zamówienia --> <language>pol</language> <!-- język zamówienia --> <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) --> <username><![CDATA[ AtomStore ]]></username> <!-- nazwa użytkownika 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[ AtomStore ]]></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 --> <registration>1</registration> <!-- czy konto użytkownika ma zostać zapamiętane (1 = tak, 0 = nie) --> </client> <admin> <email>admin_sprzedaz_1</email> <!-- login opiekuna zamówienia --> </admin> <products> <code>www222_1</code> <!-- kod produktu lub wariantu --> <productName> <!-- nazwa pozycji zamówienia (opcjonalnie) --> <![CDATA[ Rower Hexagon ]]> </productName> <price>644.0569</price> <!-- cena jednostkowa netto (opcjonalnie), waluta zamówienia --> <tax>23</tax> <!-- stawka VAT (opcjonalnie) --> <quantity>1</quantity> <!-- zamówiona ilość produktu (wymagana) --> <kitID>0</kitID> <!-- id zestawu, do którego należy produkt (opcjonalnie) --> </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> <couponCode>c0up0nc0d3</couponCode> <!-- Opcjonalne --> <couponID>123</couponID> <!-- Opcjonalne --> <couponValue>10.50</couponValue> <!-- Opcjonalne --> </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> <invoice>1</invoice> <!-- czy wystawić fakturę (1/0) --> <invoiceNumber>F/06/2015/12345</invoiceNumber> <!-- numer faktury --> <invoiceByEmail>1</invoiceByEmail> <!-- Zgoda na par/fv przez e-mail --> <paymentTerm>2015-06-15</paymentTerm> <!-- termin płatności --> <allegroNumber>555555555</allegroNumber> <!-- numer aukcji Allegro --> <allegroTransactionId>0</allegroTransactionId> <!-- numer transakcji Allegro --> <tracking_status>W drodze</tracking_status> <!-- status listu przewozowego --> <tracking_number>001122334455</tracking_number> <!-- numer listu przewozowego --> <tracking_url>http://adres-do-sledzenie.pl?q=001122334455</tracking_url> <!-- adres URL do śledzenie przesyłki --> <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" email_subject="Tytul emailu"><![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> <price>644.0569</price> <tax>23</tax> <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/atom_api/wsdl/atom_api');
$authenticate = array('login' => 'admin', 'password' => 'admin');
$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:
- jeśli w ustawieniach sklepu zdefiniowano prefiks / sufiks do numerów zamówień, nie należy ich przekazywać w polu <order> → <id>, nie będą też uwzględnione w zwracanych numerach nowych zamówień,
- 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ę przypisania klienta ani na zmianę adresu e-mail, tylko na aktualizację danych adresowych w zamówieniu; pola identyfikujące klienta są uwzględniane tylko dla nowych zamówień,
- metoda nie pozwala na zmianę waluty / kursu waluty,
- 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,
- jeżeli nie podano nazwy towaru / ceny / stawki VAT, ale produkt został zidentyfikowany w AtomStore, dane te zostaną wczytane 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 Atom API,
- 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,
- jeśli przekazano znacznik <create returnNewOrdersIds="1">1..., numery poszczególnych nowych zamówień będą oddzielone przecinkami (w szczególności może to być pusty ciąg znaków, gdy żadnego zamówienia nie udało się dodać),
- zmiany wykonywane przez Atom API nie aktualizują daty ostatniej modyfikacji zamówienia, dzięki czemu zewnętrzna integracja nie pobiera niepotrzebnie informacji o własnych zmianach w ramach importu zamówień nowych / zmodyfikowanych.
SetOrderStatus
Zmiana statusu pojedynczego 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 |
| statusId | tak | int | - | identyfikator statusu zamówienia zgodny ze słownikiem zwracanym z metody GetOrdersStatuses |
| emailNotification | nie | string | auto |
wysłanie do klienta powiadomienia o zmianie statusu zamówienia: - auto - zgodnie z ustawieniami statusu, - enable - wymuszenie powiadomienia, - disable - brak powiadomienia bez względu na konfigurację statusu |
| refreshModified | nie | boolean | false |
Czy zmiana statusu zamowienia, powinna zmienic ostatnią datę modyfikacji zamowienia |
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->SetOrderStatus($authenticate, 7812, 4);
echo $response;
Dane zwracane:
OK
Uwagi:
- jeśli w ustawieniach sklepu zdefiniowano prefiks / sufiks do numerów zamówień, nie należy ich przekazywać w parametrze 'orderId',
- wysłanie obecnego statusu zamówienia nie powoduje żadnych zmian; podobnie wielokrotne wysłanie tego samego statusu,
- zmiany wykonywane przez Atom API nie aktualizują daty ostatniej modyfikacji zamówienia, dzięki czemu zewnętrzna integracja nie pobiera niepotrzebnie informacji o własnych zmianach w ramach importu zamówień nowych / zmodyfikowanych.
SetReceiptNumbers
Zapis numerów paragonów dla 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' |
| 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> <id>223</id> <!-- numer zamówienia w AtomStore (wymagany) --> <paragon>PF/28712/223</paragon> <!-- numer paragonu (wymagany) --> </order> <order> <id>226</id> <paragon>PF/28713/226</paragon> </order> </orders>
Przykładowe wywołanie (PHP):
$client = new SoapClient('http://demo.atomstore.pl/atom_api/wsdl/atom_api');
$authenticate = array('login' => 'admin', 'password' => 'admin');
$xml = '<orders><order><id>223</id><paragon>PF/28712/223</paragon></order></orders>';
$message = array('xml' => $xml);
$response = $client->SetReceiptNumbers($authenticate, $message);
echo $response;
Dane zwracane:
OK
Uwagi:
- jeśli w ustawieniach sklepu zdefiniowano prefiks / sufiks do numerów zamówień, nie należy ich przekazywać w polu <order> → <id>,
- metoda nadpisuje zarówno pusty, jak i niepusty (uzupełniony wcześniej) numer paragonu,
- zmiany wykonywane przez Atom API nie aktualizują daty ostatniej modyfikacji zamówienia, dzięki czemu zewnętrzna integracja nie pobiera niepotrzebnie informacji o własnych zmianach w ramach importu zamówień nowych / zmodyfikowanych.
GetOrderPayments
Funkcja zwraca inofrmację o opłaceniu wybranych 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' |
| message | tak | string | - | 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> <id>1</id> <!-- ID zamówienia w AtomStore --> </order> <order> <id>2</id> <!-- ID zamówienia w AtomStore --> </order> ... </orders>
Przykładowe wywołanie (PHP):
$client = new SoapClient('http://demo.atomstore.pl/atom_api/wsdl/atom_api');
$authenticate = array('login' => 'admin', 'password' => 'admin');
$xml = '<orders><order><id>1</id></order><order><id>2</id></order></orders>';
$message = array('xml' => $xml);
$response = $client->GetOrderPayments($authenticate, $message);
echo $response;
Dane zwracane:
<orders> <order> <id>1</id> <-- ID zamówienia w AtomStore --> <paid>500.00</paid> <-- opłacona kwota (w walucie zamówienia) --> <payments> <payment> <voucher>1</voucher> <-- informacje o tym czy to płatność bonem rabatowym, możliwe wartości 1 lub 0) --> <paymentValue>200.00</paymentValue> <-- wartość wpłaty --> <paymentTransactionId>KOD_ZEWN</paymentTransactionId> <-- identyfikator płatności w systemie zewnętrznym (pośrednik), np. w PayU --> <paymentTransactionNumber>31613664</paymentTransactionNumber> <-- dodatkowy identyfikator płatności --> <paymentTransactionDate>2017-10-10 09:21:30</paymentTransactionDate> <-- data zaksięgowania wpłąty --> <paymentCommission>0.00</paymentCommission> <-- wysokość zapłaconej prozwizji pośrednikowi --> <paymentMethodId>1</paymentMethodId> <-- id formy płatności --> </payment> <payment> <voucher>0</voucher> <paymentValue>300.00</paymentValue> <paymentTransactionId>012017</paymentTransactionId> <paymentTransactionNumber>31613664</paymentTransactionNumber> <paymentTransactionDate>2017-10-11 08:11:10</paymentTransactionDate> <paymentCommission>3.00</paymentCommission> </payment> </payments> </order> <order> <id>2</id> <paid>0.00</paid> <payments></payments> </order> </orders>
zobacz DEMO
