atlas-sdk-core v4.18.0

Atlas JavaScript SDK Core

This SDK covers the functionality provided by team Atlas' (aka Distributed Commerce) APIs, namely, Checkout, Guest Checkout, and Catalog APIs.

Those APIs, and in turn this SDK, provide our partners a more streamlined access the Zalando shopping platform to enable our customers to purchase wherever they are.

The purpose of this project is to provide low-level calls to API backend and response models for Zalando Checkout, Guest Checkout, and Catalog APIs in order to allow easily integrate and run Zalando Сheckout in minutes using your own UI solution.

If you want to access the APIs directly we recommend that you take a look at their documentation.

We use Promises a lot :)

Installation

npm install --save atlas-sdk-core es6-promise

On install we're transpiling the code for your convenience. You have access to two files under a lib/ folder, one for using in node and another for browser usages.

Warning

Because we are using Promises you must bring your own ES6 Promise compatible polyfill, e.g. es6-promise.

Local Development

If you want to contribute, please, read our Contributing guidelines first.

In order to start SDK development simply run

npm run tdd

Check existing codebase tests for test examples.

Configuration and Usage

You need to configure Atlas JavaScript SDK Core first and use configured instance variable to interact with AtlasSDK.

In order to configure AtlasSDK manually provide an object with 2 mandatory parameters client_id and sales_channel:

import AtlasSDK from 'atlas-sdk-core';

AtlasSDK.configure({
  client_id: 'CLIENT_ID',
  sales_channel: 'SALES_CHANNEL',
  is_sandbox: true
}).then((sdk) => {
  // sdk instance is ready to use

  sdk.getArticle('AD112B0F6-A11').then((article) => {
    console.log(`Article name: ${article.name}`);
  });
}).catch((error) => {
  console.error(`${error}`);
});

Since we are using Promises you can benefit from await/async:

import AtlasSDK from 'atlas-sdk-core';

const sdk = await AtlasSDK.configure({
  client_id: 'CLIENT_ID',
  sales_channel: 'SALES_CHANNEL'
});
const article = await sdk.getArticle('AD112B0F6-A11');
console.log(`Article name: ${article.name}`);

API Reference

Modules

Classes

Constants

Functions

AtlasSDK

AtlasSDK is a global namespace.

Access: public

AtlasSDK.configure(options) ⇒ Promise.<AtlasSDKClient>

Configure AtlasSDK. This is the main entry point to use the AtlasSDK.

Kind: static method of AtlasSDK
Returns: Promise.<AtlasSDKClient> - a promise resolving with an AtlasSDKClient object
Access: public

Example

const sdk = await AtlasSDK.configure({
  client_id: 'CLIENT_ID',
  sales_channel: 'SALES_CHANNEL',
  is_sandBox: true
});

AtlasSDKClient

AtlasSDK instance returned from AtlasSDK configure method.

Kind: global class

• AtlasSDKClient
  • new AtlasSDKClient(config)
  • .getLocale() ⇒ String
  • .getLanguage() ⇒ String
  • .getCountryCode() ⇒ String
  • .getConfig() ⇒ Object
  • .getArticle(sku, [options]) ⇒ Article
  • .getArticles(skus, [options]) ⇒ Array.<Article>
  • .getArticleFamilies(sku, [options]) ⇒ Array.<ArticleFamily>
  • .getGuestCheckout(checkoutId, token) ⇒ GetCheckoutResponse
  • .createGuestOrder(checkoutId, token) ⇒ CreateOrderResponse
  • .getRecommendations(sku, [options]) ⇒ Array.<RecommendedArticle>
  • .createGuestCheckout(json) ⇒ CreateOrderRedirectResponse
  • .getCheckoutCustomer(token) ⇒ CheckoutCustomer
  • .getCheckoutAddresses(token) ⇒ CheckoutAddress
  • .getCheckoutCarts(token, headers) ⇒ CartsResponse
  • .createCheckoutCart(json, token, options) ⇒ CartResponse
  • .getCheckoutCart(cartId, token) ⇒ CartResponse
  • .putCheckoutcart(json, cartId, token, headers) ⇒ CartResponse

new AtlasSDKClient(config)

Creates an AtlasSDK instance from config provided by config-api

atlasSDKClient.getLocale() ⇒ String

Returns locale based on sales channel, e.g. 'de_DE'

Kind: instance method of AtlasSDKClient
Returns: String - locale

atlasSDKClient.getLanguage() ⇒ String

Returns language based on sales channel, e.g. 'de'

Kind: instance method of AtlasSDKClient
Returns: String - language

atlasSDKClient.getCountryCode() ⇒ String

Returns country code based on sales channel, e.g. 'DE'

Kind: instance method of AtlasSDKClient
Returns: String - country code

atlasSDKClient.getConfig() ⇒ Object

Returns configuration from config-api

Kind: instance method of AtlasSDKClient
Returns: Object - config

atlasSDKClient.getArticle(sku, options) ⇒ Article

Fetches an article based on a SKU.

Kind: instance method of AtlasSDKClient
Returns: Article - return Article object
Access: public

Example

const sdk = await AtlasSDK.configure({
  client_id: 'CLIENT_ID',
  sales_channel: 'SALES_CHANNEL',
  is_sandBox: true,
  lang: 'en'
});
const article = await sdk.getArticle('AD112B0F6-A11', {
   media: {
     image_resolutions: ['thumbnail', 'medium']
   }
});

atlasSDKClient.getArticles(skus, options) ⇒ Array.<Article>

Fetches multiple articles based on SKUs.

Kind: instance method of AtlasSDKClient
Returns: Array.<Article> - return Article[] object
Access: public

Example

const sdk = await AtlasSDK.configure({
  client_id: 'CLIENT_ID',
  sales_channel: 'SALES_CHANNEL',
  is_sandBox: true,
  lang: 'en'
});
const articles = await sdk.getArticles('AD112B0F6-A11,SO254C009-K12', {
   media: {
     image_resolutions: ['thumbnail', 'medium']
   }
});

atlasSDKClient.getArticleFamilies(sku, options) ⇒ Array.<ArticleFamily>

Fetches article families based on SKU.

Kind: instance method of AtlasSDKClient
Returns: Array.<ArticleFamily> - return ArticleFamily[] object
Access: public

Example

const sdk = await AtlasSDK.configure({
  client_id: 'CLIENT_ID',
  sales_channel: 'SALES_CHANNEL',
  is_sandBox: true,
  lang: 'en'
});
const article = await sdk.getArticleFamilies('AD112B0F6-A11');

atlasSDKClient.getGuestCheckout(checkoutId, token) ⇒ GetCheckoutResponse

Returns the complete details of the checkout: guest checkout object GetCheckoutResponse created using createGuestCheckout. Parameters checkoutId, token should be fetched from redirect URL after payment.

Kind: instance method of AtlasSDKClient
Returns: GetCheckoutResponse - guest checkout object
Access: public

atlasSDKClient.createGuestOrder(checkoutId, token) ⇒ CreateOrderResponse

Creates an order for the guest chekout object based on checkoutId, token.

Kind: instance method of AtlasSDKClient
Returns: CreateOrderResponse - object with order information
Access: public

atlasSDKClient.getRecommendations(sku, options) ⇒ Array.<RecommendedArticle>

Fetches recommendations for an article based on a SKU.

Kind: instance method of AtlasSDKClient
Returns: Array.<RecommendedArticle> - return array of RecommendedArticle[] objects
Access: public

Example

const sdk = await AtlasSDK.configure({
  client_id: 'CLIENT_ID',
  sales_channel: 'SALES_CHANNEL',
  is_sandBox: true
});
const recos = await sdk.getRecommendations('AD112B0F6-A11', {
   reco_id: 'UUID',
   tracking_string: 'TRACK',
   media: {
     cdn: 'mosaic02',
     image_resolutions: ['thumbnail', 'medium']
   },
   filters: {
     '-filter_gender': 'FEMALE'
     'brand_code': ['AN1', 'N12', 'PU1'],
   }
});

atlasSDKClient.createGuestCheckout(json) ⇒ CreateOrderRedirectResponse

Creates guest checkout object with payload.

Kind: instance method of AtlasSDKClient
Returns: CreateOrderRedirectResponse - response containing redirectURL that should be used to go to the payment.
Access: public

atlasSDKClient.getCheckoutCustomer(token) ⇒ CheckoutCustomer

Returns customer object CheckoutCustomer. Parameters customer token needed to fetch customer object.

Kind: instance method of AtlasSDKClient
Returns: CheckoutCustomer - customer object
Access: public

atlasSDKClient.getCheckoutAddresses(token) ⇒ CheckoutAddress

Returns customer addresses CheckoutAddress. Parameters customer token needed to fetch customer object.

Kind: instance method of AtlasSDKClient
Returns: CheckoutAddress - CheckoutAddress array
Access: public

atlasSDKClient.getCheckoutCarts(token, headers) ⇒ CartsResponse

Returns a customer's cart(s)

Kind: instance method of AtlasSDKClient
Returns: CartsResponse - - carts

atlasSDKClient.createCheckoutCart(json, token, options) ⇒ CartResponse

Creates Zalando customer cart

Kind: instance method of AtlasSDKClient
Returns: CartResponse - - customer cart

atlasSDKClient.getCheckoutCart(cartId, token) ⇒ CartResponse

Returns a cart by id

Kind: instance method of AtlasSDKClient
Returns: CartResponse - - cart

atlasSDKClient.putCheckoutcart(json, cartId, token, headers) ⇒ CartResponse

Updates existing cart by id

Kind: instance method of AtlasSDKClient
Returns: CartResponse - - updated cart

PickupPoint

Kind: global class

new PickupPoint(name, id, memberId)

AddressSchema

Baseclass for Address model

Kind: global class

new AddressSchema(email, gender, firstName, lastName, street, zip, city, countryCode, pickupPoint)

CheckoutAddressSchema

Baseclass for CheckoutAddress model

Kind: global class

new CheckoutAddressSchema(customerNumber, email, gender, firstName, lastName, street, zip, city, countryCode, pickupPoint, defaultBilling, defaultShipping)

NormalizedAddress

Baseclass for NormalizedAddress model

Kind: global class

new NormalizedAddress(street, zip, city, countryCode)

CheckedAddress

Baseclass for CheckedAddress model

Kind: global class

new CheckedAddress(status, normalizedAddress)

Brand

Class for Brand model.

Kind: global class

new Brand(name)

Partner

Class for Partner model.

Kind: global class

new Partner(id, name, detailURL)

PriceSchema

Class for Article Unit Price model.

Kind: global class

new PriceSchema(amount, currency)

Unit

Class for Article Unit model.

Kind: global class

new Unit(id, size, price, originalPrice, available, stock, partner, media)

Attribute

Class for Article Unit Attribute model.

Kind: global class

new Attribute(name, category, subCategory, values)

EnrichmentAttribute

Class for Article Unit EnrichmentAttribute model.

Kind: global class

new EnrichmentAttribute(key, value)

TargetGroups

Class for TargetGroups model.

Kind: global class

new TargetGroups(gender, age, domain, ageRange)

ArticleImage

Class for ArticleImage model.

Kind: global class

new ArticleImage(order, catalog, catalogHD, detail, detailHD, large, largeHD)

Media

Class for Media model.

Kind: global class

new Media(images)

Item

Class for CartItem model

Kind: global class

new Item(sku, quantity)

ItemWithPrice

Class for CartItem model

Kind: global class

new ItemWithPrice(sku, configSku, quantity, price)

Payment

Class for Payment model

Kind: global class

• Payment
  • new Payment(method, selectionPageUrl, metadata)
  • new Payment(selected, selectionPageUrl)

new Payment(method, selectionPageUrl, metadata)

new Payment(selected, selectionPageUrl)

Delivery

Class for Delivery model'

Kind: global class

new Delivery(service, cost, earliest, latest, options)

ReviewRatingDistribution

Class for ReviewRatingDistribution.

Kind: global class

new ReviewRatingDistribution(count)

ReviewRating

Class for ReviewRating.

Kind: global class

new ReviewRating(average, distribution)

ReviewRecommendations

Class for ReviewRecommendations.

Kind: global class

new ReviewRecommendations(total, positive)

ReviewSummary

Class for ReviewSummary.

Kind: global class

new ReviewSummary(total, rating, recommendations)

ReviewEntry

Class for ReviewEntry.

Kind: global class

new ReviewEntry(name, title, description, rating, recommends, created)

Reviews

Class for Article Reviews.

Kind: global class

new Reviews(summary, entries)

Image

Class for Image model.

Kind: global class

new Image(type, mediaCharacter, resolutions)

Video

Class for Video model.

Kind: global class

new Video(type, mediaCharacter, url)

Article

Class for Article model

Kind: global class

new Article(id, name, color, silhouetteCode, supplierColor, productGroup, detailUrl, brand, units, images, videos, attributes, enrichmentAttributes, targetGroups, infos, review)

ArticleFamily

Class for ArticleFamily model

Kind: global class

new ArticleFamily(id, color, supplierColor, lowestPrice, images)

DiscountSchema

Class for Discount model

Kind: global class

new DiscountSchema(grossTotal, taxTotal)

CheckoutCouponDiscount

Class for Checkout Discount model

Kind: global class

new CheckoutCouponDiscount(remaining, gross, tax)

DeliveryRequest

Class for Delivery Request model

Kind: global class

new DeliveryRequest(service)

CreateCartRequest

Class for Cart Request model

Kind: global class

new CreateCartRequest(items)

SelectedPayment

Class for Selected Payment model

Kind: global class

new SelectedPayment(method, metadata, externalPayment)

Payment

Class for Payment model

Kind: global class

• Payment
  • new Payment(method, selectionPageUrl, metadata)
  • new Payment(selected, selectionPageUrl)

new Payment(method, selectionPageUrl, metadata)

new Payment(selected, selectionPageUrl)

CheckoutCouponDetails

Class for Checkout Coupon Details model

Kind: global class

new CheckoutCouponDetails(coupon, warning, error, discount)

CartResponse

Class for Cart Response model

Kind: global class

new CartResponse(id, items, itemsOutOfStock, delivery, grossTotal, taxTotal, totalDiscount)

CartsResponse

Class for Carts Response model

Kind: global class

new CartsResponse(id, carts)

CreateCheckoutRequest

Class for Checkout Request model

Kind: global class

new CreateCheckoutRequest(id, billingAddressId, billingAddress, shippingAddressId, shippingAddress, delivery, coupons)

CheckoutResponse

Class for Checkout Response model

Kind: global class

new CheckoutResponse(id, customerNumber, cartId, billingAddress, shippingAddress, delivery, couponDetails, payment)

PutCheckoutRequest

Class for Put Checkout Request model

Kind: global class

new PutCheckoutRequest(billingAddressId, billingAddress, shippingAddressId, shippingAddress, delivery, coupons)

CheckoutOrderRequest

Class for Checkout Order Request model

Kind: global class

new CheckoutOrderRequest(checkoutId)

SalesChannel

SalesChannel class struct

Kind: global class

new SalesChannel(source)

Recommendations

Recommendations class struct

Kind: global class

new Recommendations(source)

Config

Config class struct

Kind: global class

new Config(source)

Example

const source = {
  catalog_api_url: 'https://catalog_api.com/api',
  checkout_api_url: 'https://checkout_api.com/api',
  oauth2_provider_url: 'https://oauth2_provider.com/api',
  sales_channel: {
    locale: 'de_DE',
    channel: '11111111-1111-1111-1111-111111111111',
    toc_url: 'https://m.zalando.de/agb/'
  },
  recommendations: {
    location: 'my_app_pdp',
    type: 'similar',
    channel: 'myapp'
  }
};

const config = new Config(source);

GuestCustomer

Class for Guest Customer model

Kind: global class

new GuestCustomer(email, subscribeNewsletter)

CheckoutCustomer

Class for Guest Customer model

Kind: global class

new CheckoutCustomer(customerNumber, customerHash, gender, firstName, lastName, email)

Cart

Cart

Kind: global class

new Cart(items, itemsOutOfStock, grossTotal, taxTotal)

Class for Cart model

CreateOrderRequest

Class for CreateOrderRequest model

Kind: global class

new CreateOrderRequest(customer, billingAddress, shippingAddress, cart, payment)

CreateOrderResponse

Class for CreateOrderResponse model

Kind: global class

new CreateOrderResponse(orderNumber, customerNumber, billingAddress, shippingAddress, grossTotal, taxTotal, created, externalPaymentURL)

CreateOrderRedirectResponse

Class for CreateOrderRedirectResponse model

Kind: global class

new CreateOrderRedirectResponse(url)

GetCheckoutResponse

Class for GetCheckoutResponse model

Kind: global class

new GetCheckoutResponse(cart, billingAddress, shippingAddress, payment, delivery)

OrderResponse

Class for Order Response model

Kind: global class

new OrderResponse(orderNumber, billingAddress, shippingAddress, grossTotal, taxTotal, created, externalPaymentURL)

CheckoutApiOrderResponseSchema

Class for Checkout Order Response model

Kind: global class

new CheckoutApiOrderResponseSchema(customerNumber, orderNumber, billingAddress, shippingAddress, grossTotal, taxTotal, created, externalPaymentURL)

CheckoutOrder

Class for Guest Customer model

Kind: global class

new CheckoutOrder(orderNumber, customerNumber, grossTotal, created, detailUrl)

RecommendedArticle

Class for Recommended Article model

Kind: global class

new RecommendedArticle(id, tracking_string, name, lowestPrice, brand, images, videos, units)

configCache

A temporary fix to handle the current high load capacity

Kind: global constant

fetchEndpoint(endpoint) ⇒ Promise

Calls the given endpoint using fetch and intercepts the response via various operations

Kind: global function
Returns: Promise - Promise after resolving or rejecting the request.

Contact

For any inquiry, please contact Team Atlas via team-atlas@zalando.de

LICENSE

The MIT License (MIT) Copyright © 2016 Zalando SE, https://tech.zalando.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.