Dodanie zamówienia z własnego sklepu lub marketplace

Do czego służy ta instrukcja

Ten artykuł pokazuje, jak dodać do xSale zamówienie pochodzące z własnego sklepu lub marketplace, dla którego nie masz gotowej integracji w katalogu xSale. Krok po kroku uzupełniasz dane zamówienia, płatności, dostawy/przesyłki oraz kontrahenta, aby w xSale powstał kompletny rekord do dalszej obsługi.

Na początku znajdziesz skrótowy opis procesu i wymagania, a dalej część techniczną z endpointami i przykładami (pozostawioną bez zmian).

W tym artykule znajdziesz

• kiedy warto dodawać zamówienia do xSale przez API
• wymagania i dane wejściowe
• szybki przepis krok po kroku (co w jakiej kolejności wywołać)
• typowe problemy i sposób weryfikacji

Kiedy stosować

To rozwiązanie stosuje się, gdy zamówienia powstają w systemie zewnętrznym (np. autorski sklep lub niestandardowy marketplace), a chcesz obsługiwać je w xSale — np. uruchamiać automatyzacje, przekazywać do ERP lub tworzyć wysyłki. W praktyce API pozwala odtworzyć strukturę zamówienia tak, jakby została pobrana przez standardową integrację.

Wymagania

• dostęp do REST API xSale (autoryzacja) dla właściwej organizacji
• wartość organizationName
• dane zamówienia z systemu źródłowego (pozycje, kwoty, waluta, statusy)
• dane płatności (jeśli występują) oraz dane dostawy/przesyłki
• dane kontrahenta (klienta) powiązane z zamówieniem

Szybki przepis (krok po kroku)

1. Dodaj zamówienie do xSale (utworzenie rekordu zamówienia).
2. Dodaj płatność i powiąż ją z zamówieniem (jeśli dotyczy).
3. Uzupełnij dane dostawy i przesyłki (metoda, adres, parametry).
4. Utwórz lub powiąż kontrahenta (klienta) oraz przypisz go do zamówienia.
5. Zweryfikuj w xSale, czy zamówienie ma komplet danych i jest gotowe do dalszej obsługi.

Typowe problemy i jak je sprawdzić

• Brak części danych na zamówieniu — upewnij się, że wykonałeś wszystkie kroki (zamówienie → płatność → dostawa/przesyłka → kontrahent).
• Duplikaty zamówień — w systemie źródłowym trzymaj jednoznaczne identyfikatory i zapisuj powiązania po stronie integracji.
• Błąd autoryzacji — sprawdź dane logowania/token oraz uprawnienia do REST API.
• Niezgodny format danych — porównaj body zapytań z przykładami w części technicznej (nazwy pól i typy).

Szczegóły techniczne

Dzięki zasobom REST API możesz wprowadzać do xSale zamówienia z dedykowanych platform e-commerce oraz marketplace, niedostępnych w katalogu integracji xSale. Zakres danych w  zamówieniu wprowadzanym z własnego systemu sprzedażowego obejmuje kilka obszarów. Ten poradnik opisuje dodawanie do xSale zamówień i płatności. Omawia także zasoby, których należy użyć, aby uzupełnić szczegółowe informacje o dostawie i przesyłce oraz dane kontrahenta powiązanego z zamówieniem. Zdecyduj, jakie dane chcesz importować do xSale i skorzystaj z poniższych instrukcji, aby przesłać zamówienie.

1. Wprowadzenie zamówienia do xSale

Aby dodać zamówienie do xSale, użyj zasobu:

POST /{organizationName}/orders

Wymagane pola

Poniższa lista prezentuje pola wymagane do utworzenia zamówienia. Jest to minimalny zakres danych, niezbędny do przesłania w zapytaniu, aby xSale mógł utworzyć zamówienie.

Dane o integracji i płatności:

• ID integracji – IntegrationId – wskazuje źródło, z którego  pochodzi zamówienie. Sprawdź tutaj, jak dodać integrację REST API.
• ID formy płatności – PaymentFormId
• data zamówienia – PurchaseDate  – np. 2024-10-25

Dane kontrahenta:

• ID nabywcy – BuyerId
• ID odbiorcy – RecipientId
• ID płatnika – PayerId

Dodając zamówienie możesz wyszukać wśród kontrahentów istniejących w bazie xSale twojej firmy (np. po adresie e-mail lub numerze NIP) i użyć ID odnalezionego kontrahenta lub stworzyć nowego kontrahenta. Więcej informacji o danych kontrahenta znajdziesz w dalszej części wpisu.

Zamówione produkty:

• ID oferty – OfferId
• ID wariantu – VariantId
• ilość – Quantity
• cena netto – PriceNet – cena netto za jednostkę towaru
• cena brutto – PriceGross – cena brutto za jednostkę towaru

Wymagane jest przesłanie wartości przynajmniej w jednym z pól – PriceNet lub PriceGross. Natomiast domyślne mechanizmy w xSale działają w oparciu o cenę brutto, dlatego rekomendujemy wprowadzanie ceny brutto.

Dodatkowe informacje

Opcjonalnie możesz przesłać dodatkowe dane, które ułatwią obsługę zamówienia w xSale i/lub umożliwią prawidłowe działanie dalszych akcji i procesów. Wśród tych akcji znajduje się szereg automatyzacji związanych m. in. z przekazywaniem zamówienia do systemu ERP, tworzeniem przesyłki i drukowaniem listu przewozowego, wystawianiem faktur oraz wysyłaniem do klienta maili z aktualizacjami statusu realizacji zamówienia.

Status i identyfikacja zamówienia

• numer obcy – ForeignId – np. ID zamówienia ze sklepu lub marketplace
• ID statusu – StatusId – dla nowych zamówień rekomendujemy użycie statusu Nowe (ID: 3), który domyślnie wyzwala automatyzacje działające np. w integracjach z systemami ERP

Informacje o dostawie i przesyłce

• ID sposobu dostawy – DeliveryMethodId
• liczba paczek – NumberOfPackages
• punkt dostawy – PointOfDelivery – np. numer Paczkomatu InPost – (KRA197M)

Zarządzanie sposobami dostawy odbywa się z wykorzystaniem zasobu DeliveryMethod. Aby pobrać listę dostępnych sposobów dostawy odpytaj endpoint:

GET /{organizationName}/delivery-method

Adres odbiorcy, nabywcy i płatnika

Powiązanie kontrahenta z zamówieniem odbywa się poprzez ID odbiorcy, nabywcy i płatnika. Jeśli jednak nie zamierzasz wyszukiwać kontrahenta w bazie xSale, prześlij w danych zamówienia dane adresowe, uzupełniając odpowiednie sekcje:

• adres kupującego – BuyerAddress
• adres odbiorcy – RecipientAddress – dane do wysyłki
• adres płatnika – PayerAddress

Zestaw pól, które możesz uzupełnić, wygląda następująco:

• nazwa – Name, np. imię lub nazwa firmy
• nazwa 2 – Name2, np. nazwisko
• nazwa 3 – Name3
• NIP – TaxNumber
• numer telefonu – Phone – użyj tego pola, aby podać numer do przekazania kurierowi
• numer telefonu komórkowego – MobilePhone
• e-mail – Email
• miasto – City
• ulica – Street
• numer budynku / lokalu – StreetNumber
• kod pocztowy – ZipCode
• kraj – Country
• notatki – Notes

Kraj klienta i kody ISO

Przy przekazywaniu danych klienta podaj prawidłowy kod kraju ISO alfa-2, na przykład DE dla Niemiec, FR dla Francji lub PL dla Polski. Sama nazwa kraju, na przykład Germany, nie zastępuje kodu DE.

Kod kraju jest wykorzystywany przez xSale podczas dalszego przetwarzania zamówienia, między innymi do rozpoznania sprzedaży zagranicznej i zastosowania odpowiedniej stawki VAT. Nieprawidłowy lub brakujący kod może spowodować błędne rozpoznanie kraju klienta.

Poniższa tabela zawiera kraje obsługiwane przez xSale. Kod alfa-2 to podstawowy, dwuliterowy kod ISO. Kod alfa-3 podajemy pomocniczo.

Kraj	Kod ISO alfa-2	Kod ISO alfa-3
Afganistan	AF	AFG
Albania	AL	ALB
Algieria	DZ	DZA
Andora	AD	AND
Angola	AO	AGO
Anguilla	AI	AIA
Antarktyka	AQ	ATA
Antigua i Barbuda	AG	ATG
Arabia Saudyjska	SA	SAU
Argentyna	AR	ARG
Armenia	AM	ARM
Aruba	AW	ABW
Australia	AU	AUS
Austria	AT	AUT
Azerbejdżan	AZ	AZE
Bahamy	BS	BHS
Bahrajn	BH	BHR
Bangladesz	BD	BGD
Barbados	BB	BRB
Belgia	BE	BEL
Belize	BZ	BLZ
Benin	BJ	BEN
Bermudy	BM	BMU
Bhutan	BT	BTN
Białoruś	BY	BLR
Boliwia	BO	BOL
Bonaire, Sint Eustatius i Saba	BQ	BES
Bośnia i Hercegowina	BA	BIH
Botswana	BW	BWA
Brazylia	BR	BRA
Brunei	BN	BRN
Brytyjskie Terytorium Oceanu Indyjskiego	IO	IOT
Brytyjskie Wyspy Dziewicze	VG	VGB
Bułgaria	BG	BGR
Burkina Faso	BF	BFA
Burundi	BI	BDI
Chile	CL	CHL
Chiny	CN	CHN
Chorwacja	HR	HRV
Curaçao	CW	CUW
Cypr	CY	CYP
Czad	TD	TCD
Czarnogóra	ME	MNE
Czechy	CZ	CZE
Dalekie Wyspy Mniejsze Stanów Zjednoczonych	UM	UMI
Dania	DK	DNK
Demokratyczna Republika Konga	CD	COD
Dominika	DM	DMA
Dominikana	DO	DOM
Dżibuti	DJ	DJI
Egipt	EG	EGY
Ekwador	EC	ECU
Erytrea	ER	ERI
Estonia	EE	EST
Eswatini	SZ	SWZ
Etiopia	ET	ETH
Falklandy	FK	FLK
Fidżi	FJ	FJI
Filipiny	PH	PHL
Finlandia	FI	FIN
Francja	FR	FRA
Francuskie Terytoria Południowe i Antarktyczne	TF	ATF
Gabon	GA	GAB
Gambia	GM	GMB
Georgia Południowa i Sandwich Południowy	GS	SGS
Ghana	GH	GHA
Gibraltar	GI	GIB
Grecja	GR	GRC
Grenada	GD	GRD
Grenlandia	GL	GRL
Gruzja	GE	GEO
Guam	GU	GUM
Guernsey	GG	GGY
Gujana Francuska	GF	GUF
Gujana	GY	GUY
Gwadelupa	GP	GLP
Gwatemala	GT	GTM
Gwinea Bissau	GW	GNB
Gwinea Równikowa	GQ	GNQ
Gwinea	GN	GIN
Haiti	HT	HTI
Hiszpania	ES	ESP
Holandia	NL	NLD
Honduras	HN	HND
Hongkong	HK	HKG
Indie	IN	IND
Indonezja	ID	IDN
Irak	IQ	IRQ
Iran	IR	IRN
Irlandia	IE	IRL
Irlandia Północna	NB	NBB
Islandia	IS	ISL
Izrael	IL	ISR
Jamajka	JM	JAM
Japonia	JP	JPN
Jemen	YE	YEM
Jersey	JE	JEY
Jordania	JO	JOR
Kajmany	KY	CYM
Kambodża	KH	KHM
Kamerun	CM	CMR
Kanada	CA	CAN
Katar	QA	QAT
Kazachstan	KZ	KAZ
Kenia	KE	KEN
Kirgistan	KG	KGZ
Kiribati	KI	KIR
Kolumbia	CO	COL
Komory	KM	COM
Kongo	CG	COG
Korea Południowa	KR	KOR
Korea Północna	KP	PRK
Kostaryka	CR	CRI
Kuba	CU	CUB
Kuwejt	KW	KWT
Laos	LA	LAO
Lesotho	LS	LSO
Liban	LB	LBN
Liberia	LR	LBR
Libia	LY	LBY
Liechtenstein	LI	LIE
Litwa	LT	LTU
Luksemburg	LU	LUX
Łotwa	LV	LVA
Macedonia Północna	MK	MKD
Madagaskar	MG	MDG
Majotta	YT	MYT
Makau	MO	MAC
Malawi	MW	MWI
Malediwy	MV	MDV
Malezja	MY	MYS
Mali	ML	MLI
Malta	MT	MLT
Mariany Północne	MP	MNP
Maroko	MA	MAR
Martynika	MQ	MTQ
Mauretania	MR	MRT
Mauritius	MU	MUS
Meksyk	MX	MEX
Mikronezja	FM	FSM
Mjanma	MM	MMR
Mołdawia	MD	MDA
Monako	MC	MCO
Mongolia	MN	MNG
Montserrat	MS	MSR
Mozambik	MZ	MOZ
Namibia	NA	NAM
Nauru	NR	NRU
Nepal	NP	NPL
Niemcy	DE	DEU
Niger	NE	NER
Nigeria	NG	NGA
Nikaragua	NI	NIC
Niue	NU	NIU
Norfolk	NF	NFK
Norwegia	NO	NOR
Nowa Kaledonia	NC	NCL
Nowa Zelandia	NZ	NZL
Oman	OM	OMN
Pakistan	PK	PAK
Palau	PW	PLW
Palestyna	PS	PSE
Panama	PA	PAN
Papua-Nowa Gwinea	PG	PNG
Paragwaj	PY	PRY
Peru	PE	PER
Pitcairn	PN	PCN
Polinezja Francuska	PF	PYF
Polska	PL	POL
Portoryko	PR	PRI
Portugalia	PT	PRT
Południowa Afryka	ZA	ZAF
Republika Środkowoafrykańska	CF	CAF
Republika Zielonego Przylądka	CV	CPV
Reunion	RE	REU
Rosja	RU	RUS
Rumunia	RO	ROU
Rwanda	RW	RWA
Sahara Zachodnia	EH	ESH
Saint Kitts i Nevis	KN	KNA
Saint Lucia	LC	LCA
Saint Vincent i Grenadyny	VC	VCT
Saint-Barthélemy	BL	BLM
Saint-Martin	MF	MAF
Saint-Pierre i Miquelon	PM	SPM
Salwador	SV	SLV
Samoa Amerykańskie	AS	ASM
Samoa	WS	WSM
San Marino	SM	SMR
Senegal	SN	SEN
Serbia	RS	SRB
Seszele	SC	SYC
Sierra Leone	SL	SLE
Singapur	SG	SGP
Sint Maarten	SX	SXM
Słowacja	SK	SVK
Słowenia	SI	SVN
Somalia	SO	SOM
Sri Lanka	LK	LKA
Stany Zjednoczone	US	USA
Sudan	SD	SDN
Sudan Południowy	SS	SSD
Surinam	SR	SUR
Svalbard i Jan Mayen	SJ	SJM
Syria	SY	SYR
Szwajcaria	CH	CHE
Szwecja	SE	SWE
Tadżykistan	TJ	TJK
Tajlandia	TH	THA
Tajwan	TW	TWN
Tanzania	TZ	TZA
Timor Wschodni	TL	TLS
Togo	TG	TGO
Tokelau	TK	TKL
Tonga	TO	TON
Trynidad i Tobago	TT	TTO
Tunezja	TN	TUN
Turcja	TR	TUR
Turkmenistan	TM	TKM
Turks i Caicos	TC	TCA
Tuvalu	TV	TUV
Uganda	UG	UGA
Ukraina	UA	UKR
Urugwaj	UY	URY
Uzbekistan	UZ	UZB
Vanuatu	VU	VUT
Wallis i Futuna	WF	WLF
Watykan	VA	VAT
Wenezuela	VE	VEN
Węgry	HU	HUN
Wielka Brytania	GB	GBR
Wietnam	VN	VNM
Włochy	IT	ITA
Wybrzeże Kości Słoniowej	CI	CIV
Wyspa Bouveta	BV	BVT
Wyspa Bożego Narodzenia	CX	CXR
Wyspa Man	IM	IMN
Wyspa Świętej Heleny, Wyspa Wniebowstąpienia i Tristan da Cunha	SH	SHN
Wyspy Alandzkie	AX	ALA
Wyspy Cooka	CK	COK
Wyspy Dziewicze Stanów Zjednoczonych	VI	VIR
Wyspy Heard i McDonalda	HM	HMD
Wyspy Kokosowe	CC	CCK
Wyspy Marshalla	MH	MHL
Wyspy Owcze	FO	FRO
Wyspy Salomona	SB	SLB
Wyspy Świętego Tomasza i Książęca	ST	STP
Zambia	ZM	ZMB
Zimbabwe	ZW	ZWE
Zjednoczone Emiraty Arabskie	AE	ARE

Pozostałe informacje

• ID waluty – CurrencyId
• dokument liczony od brutto – IsVatTypeGross – domyślna i rekomendowana wartość to false
• rodzaj dokumentu – InvoiceTypeId – 1 – faktura, 2 – paragon
• uwagi klienta – Comments

Po poprawnym utworzeniu zamówienia aplikacja zwróci jego dane - ID i FGUID oraz status 201.

2. Dodawanie płatności za zamówienie

Ze względu na szerokie funkcjonalności w obszarze eksportu danych o płatnościach do zintegrowanych z xSale systemów ERP, płatności stanowią odrębny zasób. Dodając płatność możesz powiązać ją z zamówieniem, dlatego jest to operacja, którą należy wykonać chronologicznie później – wymagane jest podanie ID zamówienia. Prześlij zapytanie na endpoint:

POST /{organizationName}/payment

Wprowadź wymagane dane:

• ID kontrahenta – CustomerId
• wartość – Amount
• ID waluty – CurrencyId
• ID integracji – IntegrationId
• rodzaj płatności – TypeId – 5 – wpłata, 6 – wypłata
• data – Date – np. 2024-10-25
• ID statusu płatności – StatusId

Dodatkowo endpoint przyjmuje poniższe dane:

• ID zamówienia – OrderId
• rejestr – Register – np. Allegro
• operacja – Operation – np. KP
• uwagi – Comments
• data importu pliku zamówień – ImportKPFileDate – np. 2024-08-29T07:56:55.356Z

Zmianę statusu płatności i aktualizację jej wartości wykonasz komunikując się z API przez endpoint:

PUT /{organizationName}/payment{id}