How to: API for XML feeds

Dear business partners,

this is a collection of very important information from emails (and calls) of customers who have started upload feeds from new CERVA B2B system.

 

First of all the most important information for API communication:  PartnerID, this is a six-digit number, you can find it on your invoice or by asking the customer service. 

Feeds transferred  from the old B2B and feeds in new B2B:

  • Feeds  “DISPO”, “EAN”, “CATALOG”  are very similar to the old versions.
  • Feeds “HEUREKA”, “PRICES” were created in our new B2B system. All the feeds are structured XML text files.

CATALOG

„KATALOG“ feed – je zastaralý a plně nahrazen naším novým feedem „HEUREKA“. Feed „KATALOG“ by měl partner používat pouze v případě, že společnost již pracuje se zdroji ze starého systému CERVA B2B. Zdroj obsahuje obecné artikly s kódy velikostních variant a barevných variant a několik atributů materiálu.

EAN

“EAN” – should be adopted if the  customer can use our EAN codes -  list of the article  measurement units with recalculation ratio to basic measurement unit(MU) and EAN to MU. Details-attributes are sorted by  generic article-variant of article-measurement unit:

<product code="01010004" title="JAY gloves combined"> #generic article

<variant code="0101000499090" title="JAY gloves combined yellow/blue -9"> #variant of the generic article

<unit baseUnit="PR" code="PR" denominator="1" eanCode="8591806196964" numerator="1"/>  #base measurement unit

<unit baseUnit="PR" code="DZ" denominator="1" eanCode="8591806066137" numerator="12"/> #alternative measurement unit

<unit baseUnit="PR" code="CTN" denominator="1" eanCode="8591806688162" numerator="120"/> #alternative measurement unit

</variant>

<variant code="0101000499100" title="JAY gloves combined yellow white 10"> #variant of the generic article

<unit baseUnit="PR" code="PR" denominator="1" eanCode="8591806162280" numerator="1"/>

<unit baseUnit="PR" code="DZ" denominator="1" eanCode="8591806649033" numerator="12"/>

<unit baseUnit="PR" code="CTN" denominator="1" eanCode="8591806649057" numerator="120"/>

</variant>

 

Question: Which of the MU is the sales unit?

Answer:  Sales unit you can find in feed Heureka in parameter name MOQ – minimum order quantity:

     <PARAM>

         <PARAM_NAME>MOQ</PARAM_NAME>

         <VAL>1 BOX</VAL>

     </PARAM>

 

Question: Where we can get Cerva order quantity?

Answer: Minimum order quantity you can find in feed Heureka in parameter name MOQ – within the element you can find minimal order  value  and the sales unit :

      <PARAM>

         <PARAM_NAME>MOQ</PARAM_NAME>

         <VAL>1 BOX</VAL>

      </PARAM>

 

Question: Why is missing EAN code on individual piece of the article?

Answer: In the most cases is CERVA using EAN code only on the packaging  like  KA1 - carton, BOX - box, PAK – package,  that we handle in our warehouse.  Mostly we do not mark the ones taken out of the carton.

DISPO

“DISPO” -  should be adopted when customer can check the  stock quantity  at CERVA. The availability is structured by the variant of the article.  Element “product” contains sub elements “code” – code of the article variant (color +size), “generic” – generic article code (base for the variants), “title” – article description, “totalDispo”  - available quantity on local stock to the moment of calculation, “unit” – measurement unit of the quantity.  Sub element “detail” contains more details about the stock e.g. availability in central warehouse and  again in local warehouse with the description. Sub element “date” – approximate date of next available delivery of the goods,  “dispo” – available quantity, “site” – description of the warehouse.  

 

Question: How frequently is the stock value calculated?

Answer:  The stock quantity is calculated once a day and it is ready to download  around 5:00 a.m.

 

Question: Could CERVA we get some on-line stock quantity check? Receive the stock once a day is not enough.  

Answer: Unfortunately on-line check is not possible due to the technical reasons. The quantity is changing  in  the system  from second to second.  Our plan is to start the second availability calculation in the afternoon.  

 

Question: Could Cerva propose date of deliver if the goods is not on stock?

Answer: DISPO feed contains  in element “detail ” sub element  “date” that represents approximate date of the next delivery to the central warehouse in Czechia.  Important -  if the sub element “dispo” contains value  0 (zero), there is nothing physically on stock and the goods is still  in delivery. See the code bellow:

      <product code="0101001399100" generic="01010013" title="TERN gloves combined - 10" totalDispo="53647" unit="PR">

         <detail dispo="0" site="regular warehouse"/>

         <detail date="2023-02-22" dispo="53647" site="customs warehouse"/>

      </product>

 

Question: Is there some possibility to check when we receive purchased goods that is not on stock.

Answer: Yes all the information regarding the back orders can be checked in CERVA B2B on specific screen, also the approximated dates of item delivery.

 

Question: When we can receive the goods if the goods is not available in the local warehouse, but still available in the central warehouse?

Answer: This cannot be answered in general. It really depends on local warehouse.  Even if the goods is not available at the moment, it can be purchased by the customer as a backorder.   

 

Question: We purchased 3 PCE of the article from the stock, but the order was rounded to 12 PCE, where we can find the reason why it has happened?  Answer: The  available stock quantity is information about the quantity that was calculated during the creation of the feed.  Some articles are sold in rounded quantity based on CERVA internal rules.  Minimum order quantity (rounding factor) can be found in feed Heureka, element MOQ and sales  measurement unit.  

HEUREKA

New feed “HEUREKA” – preferred feed, the main value is the variant of the generic article.  The feed  contains a lot of the  article variant attributes.  Basis for the XML structure and elements description is format Relax NG. The structure of HEUREKA feed is more simple than  Relax NG format.  All the data from the Heureka feed elements could be visible on B2B article screens.  In case of questions  regarding the “HEUREKA” feed structure and content, please contact xmlfeeds@cerva.com (communication only in English)

 

Question: How we can get pictures of the CERVA articles?

Answer: Within the Heureka feed you can find picture-related  elements  <IMGURL> and  <IMGURL_ALTERNATIVE>. The elements contain a link to the CERVA media server from where the system retrieves image data. 

PRICES

New feed “PRICES” –  feed contains code of article  variant in the element <variant… sub element “code”,   recommended final selling price in  sub element “price” and “currency” together with  price “unit”.      

   <product code="01010004" title="JAY gloves combined">

      <variant code="0101000499090" tiitle="JAY gloves combined yellow/blue - 9" price="1.567" currency="EUR" unit="PR"/>

      <variant code="0101000499100" tiitle="JAY gloves combined yellow white 10" price="1.548" currency="EUR" unit="PR"/>

      <variant code="0101000499110" tiitle="JAY gloves combined yellow red -11" price="1.649" currency="EUR" unit="PR"/>

   </product>

 

Question: How we can get our purchasing-distributor price?

Answer: Currently  we can propose only recommended final selling price.  If it is possible, apply  your distributor discount during the feed data processing within your system. Other possibility is to apply  into your system CERVA XLS pricelist, but it can be more complex task.  

How to connect FEEDS

How to connect the feeds to each other? -  The main feed is feed  “HEUREKA” ( article basic data and attributes )  leading and unique value is element   <Item_ID> with CERVA article variant code.  The same code  is   as a unique value in element <product…>  sub element  code = … within feed “DISPO”.  Both of them are identical with value of  element <variant..> sub element code = …  within the feed “EAN” and “PRICES”. Using the code  of article variant can be the data  connected together.      

 

Question: Can we use feed catalog as a main source  for the article data? 

 Answer: We do not recommend use obsolete feed “CATALOG” in the future as it is replaced by new feed “HEUREKA” which contains more information and could be enhanced with a new attributes in the future.

 

Question:  For us is important only “DISPO” feed, is it necessary to process the other feeds?

Answer: If  your system is filled with article data another way  (e.g. manually) there is not necessary to adopt other feeds than “DISPO”. 

API

Prerequisites -  the CERVA B2B  onboarding process  have  to be completed. At least one user (e-mail address) is assigned to a CERVA B2B user. For communication purposes it is recommended create a specific CERVA B2B user with limited authorization (w/o possibility create the orders).

API description – all details about connecting to the CERVA B2B  API are described in the attached file CERVA_XML_API.pdf .    Replace   “PartnerID”  with  the  CERVA customer  SAP  ID ( it can be found on the customer invoice under the customer address data nearby the text “Customer:” ). Please follow the steps described in the API document. The most important is to get authorization token. The token will be applied in all the request for the feeds.    

 

Question: We are not able to get the token, we receive an error “Error: Invalid character in header content ["pm-o0"]” or another error “Cloud Agent Error: Unable to reach the Cloud Agent. Try later or select a different agent.”.

Answer: This is  known behavior.  Please call the request repeatedly, if the system is busy, we need approximately 3 calls to get the token.

 

Question: Why is procedure to get the data so complex? In the old B2B system there was  one link to each file and very simple authorization. 

Answer: In the new CERVA B2B system are data customer specific and also the data authorization is more sophisticated. To assign  the correct list of the  articles  we need to recognize the  customer/user who is requesting the data.

 

Question: The feed files are huge, can we get only new articles or changes?  

Answer: In this time we can offer only full sets of data.

 

Question: When the feeds are created? Can we get the fresh data during the day?  

Answer:  Data are created only once a day. The data files are ready for loading  around 05:00  a.m. . It does not  make sense load the data more times during the day.

Niets om te vergelijken