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>