There is a newer version of the API available. To link to the newest API documentation, click here - Version 20110301
  1. Introduction
  2. Getting Started
  3. Failure Codes
  4. Sandbox
  5. Export Automation
  6. Limits
  7. Partner Site
  8. Creating Users through the API
  9. Managing Memberships
  10. Order Lifecycle

Introduction

Copyright Notice

© 2005-2017 DOBA, Inc. All Rights Reserved.

The information contained in this reference document is proprietary and confidential. For more information, contact:

partners@doba.com

This document and the API therein may only be used in accordance with the terms contained within a signed Doba Partnership Agreement.

Doba and the Doba logo are trademarks of DOBA, Inc. All other brands are the property of their respective owners.

Overview

The Doba API allows you to utilize the Doba supply chain platform programmatically within your own application. The API includes functions to search or browse the Doba product catalog, obtain detailed product information, lookup shipping and handling charges, submit orders, fund orders, obtain shipment information for orders when they ship. Additional functions are provided for partners who want to create subscription members or leads and manage the account through the member life-cycle.

The API includes the following systems:

 

User API

Allows for the creation and manipulation of Doba member accounts.

The User API can be used to submit leads or new users to the Doba platform. If agreed to beforehand, revenue due to upgrades and subscription payments can be shared.

 

Product API

Allows for the retrieval of on-demand and up-to-the-minute product data from the Doba platform.

 

Order API

Allows for the submittal of orders to the Doba platform as well as the retrieval of current order status and shipping/tracking data.

Orders submitted via the API can be funded through the API using several different payment methods.

Current order status can be called at any time although status updates can be provided in real-time through callback's.

 

Callbacks

Callbacks are sent to the URL on file to notify the integrators system of changes in order status, product status, etc. Callbacks are significant due to its purpose of keeping the end-user up to date with the most accurate information available to the Doba platform.

For example: When the status of a product changes from in-stock to out-of-stock, the retailer's system will be informed via callback if the product is currently being sold by that retailer. When an supplier submits shipment tracking information through the Doba platform, the retailers system will be notified via callback.

 

Certification

To ensure the highest quality customer experience, Doba must certify the API integration for those who utilize a one-to-one-to-many solution, meaning that your integration will be utilized by more than one seperate Doba member, those of which utilize their own software platform to simplify the tasks of orgonizing products and submitting orders for fulfillment.

Upon being certified, the Partner will be allowed to display the Certified Integrated Partner logo on the intergrated website.

Change Log

Release Schedule

Doba strives to provide the most robust, flexible and reliable API and as such may deem it necessary to update functionality or provide bug fixes as required. We understand that certain changes to the API could disrupt the integrations of our API clients and have set up the following schedule for releaseing any updates to the API.

  1. All updates will be available on the Sandbox server for testing and validation for one week prior to any updates being released on the production servers.
  2. Notification of all changes to the API will be provided to all API clients one week prior to the release.
  3. Updates will be sent to the email address stored on your account.
  4. Updates to the API will be released, typically, on the first Tuesday of the month at 2:00 PM MST.

 

 

 

Getting Started

API Demo Code

Demo code has been provided to make it easier for developers to quickly and easily learn to use the Doba API. The demo is not intended to be a fully functional site, but to show examples of using the Doba API to perform many of the tasks required for a Doba integration. The demo site includes code for both SOAP and XML integrations. You can download and install the code locally or find it installed here - http://www.doba.com/developer-demo/5.0/Partner

This demo code includes debug panes that show the actual API request and response for each call. To show the debug panes click on 'Show' at the top of the window.

Before running a locally installed copy of the demo code the config.inc must be updated with an API username and password, and a valid retailer id.

When running the code green text indicates tips/practices to include in each Doba integration, and red text indicates data that should be stored/updated in a local database.

Use following URL to download the PHP5 code for the demo site.

http://www.doba.com/developer-demo/5.0/Partner.zip [link]

Installation instructions are included in ReadMe.txt in the download.

 

Standards

The Doba API utilizes industry standard solutions including SOAP and XML in an effort to simplify the integration process and to ensure compatibility among software platforms.

 

SOAP

SOAP, which stands for Simple Object Access Protocol, is a protocol for exchanging XML-based messages over computer networks, normally using HTTP/HTTPS. SOAP forms the foundation layer of the Web services stack, providing a basic messaging framework upon which abstract layers can be built.

Please visit Wikipedia for a more thorough introduction to SOAP.

All API calls are sent via HTTPS requests. The XML for the SOAP request is sent as an HTTP POST request; the response is sent back as the response to the POST.

To aid in development, you may utilize toolkits specially designed to work with SOAP API's. Together with the WSDL, explained below, development time of your application with the Doba API can be shortened greatly. The toolkit will do the heavy lifting when it comes to generating the XML required to interact with the API. The WSDL provides the necessary API specifications required for each function and provides your application with the format and options available to each API function.

The toolkit you will use depends on the development environment you currently employ. Some toolkits require you to write more XML than others so research the options available to you before implementing a new solution.

 

WSDL

The Web Services Description Language (WSDL, pronounced 'wiz-dul' or spelled out, 'W-S-D-L') is an XML-based language that provides a model for describing Web services.

Please visit Wikipedia for a more thorough introduction.

The Doba API WSDL defines all of the functions available through the API along with their data types. Using the WSDL can greatly decrease the development time needed to integrate with the Doba API. The location of the Doba API WSDL's are provided below.

 

XML

Extensible Markup Language (XML) is a general-purpose markup language. It is classified as an extensible language because it allows its users to define their own tags. Its primary purpose is to facilitate the sharing of structured data across different information systems, particularly via the Internet.

Please visit Wikipedia for a more thorough introduction to XML.

 

 

XML

 

XML API URL

When implimenting the API using XML, you will POST your calls to the URL intended for the environment you are currently working in.

The following URL is to be used for development and testing:

https://sandbox.doba.com/api/5.0/xml_partner_api.php [link]

The following URL is to be used in production after testing on the sandbox server has been validated:

https://www.doba.com/api/5.0/xml_partner_api.php [link]

 

 

XML Structure

Certain required elements are required of every API call regardless of the functions used.

The <dce> tag must enclose everything else, meaning that it should open at the beginning of the call and should close as the end of the call.

The <authentication> tag must follow the opening <dce> tag. The <partner> tag will be used when the API is utilized on behalf of a retailer. The API account's username and password will be included to verify access rights to the API.

The <request> tag will encapsulate the actions request, the core of each API call.

 

 

XML Request Outline

<dce>	
    <request>
	
        <authentication>
            <username><!-- partner username --></username>
            <password><!-- partner password --></password>
        </authentication>

  <action><!-- request specific action --></action>
  
  <!-- action specific xml request data -->

    </request>
</dce>

 

 

XML Response Outline

Each API request will return a response inside the <response> tag. The <action> tag will repeat the action requested.

The <outcome> tag will indicate whether the call succeeded or failed. If the call failed, it will provide additional information that will indicate the level of failure that has occurred.

The ENTITY information is provided to ensure that no special characters will cause problems while parsing the data. Your XML parsing system should use the ENTITY information to replace special characters throughout the response automatically.

<?xml version="1.0"?>
<!DOCTYPE dce [
<!ENTITY apos "&#39;">
<!ENTITY minus "&#45;">
<!ENTITY circ "&#94;">
<!ENTITY tilde "&#126;">
<!ENTITY Scaron "&#138;">
<!ENTITY lsaquo "&#139;">
<!ENTITY OElig "&#140;">
<!ENTITY lsquo "&#145;">
<!ENTITY rsquo "&#146;">
<!ENTITY ldquo "&#147;">
<!ENTITY rdquo "&#148;">
<!ENTITY bull "&#149;">
<!ENTITY ndash "&#150;">
<!ENTITY mdash "&#151;">
<!ENTITY trade "&#153;">
<!ENTITY scaron "&#154;">
<!ENTITY rsaquo "&#155;">
<!ENTITY oelig "&#156;">
<!ENTITY Yuml "&#159;">
<!ENTITY yuml "&#255;">
<!ENTITY fnof "&#402;">
<!ENTITY Alpha "&#913;">
<!ENTITY Beta "&#914;">
<!ENTITY Gamma "&#915;">
<!ENTITY Delta "&#916;">
<!ENTITY Epsilon "&#917;">
<!ENTITY Zeta "&#918;">
<!ENTITY Eta "&#919;">
<!ENTITY Theta "&#920;">
<!ENTITY Iota "&#921;">
<!ENTITY Kappa "&#922;">
<!ENTITY Lambda "&#923;">
<!ENTITY Mu "&#924;">
<!ENTITY Nu "&#925;">
<!ENTITY Xi "&#926;">
<!ENTITY Omicron "&#927;">
<!ENTITY Pi "&#928;">
<!ENTITY Rho "&#929;">
<!ENTITY Sigma "&#931;">
<!ENTITY Tau "&#932;">
<!ENTITY Upsilon "&#933;">
<!ENTITY Phi "&#934;">
<!ENTITY Chi "&#935;">
<!ENTITY Psi "&#936;">
<!ENTITY Omega "&#937;">
<!ENTITY alpha "&#945;">
<!ENTITY beta "&#946;">
<!ENTITY gamma "&#947;">
<!ENTITY delta "&#948;">
<!ENTITY epsilon "&#949;">
<!ENTITY zeta "&#950;">
<!ENTITY eta "&#951;">
<!ENTITY theta "&#952;">
<!ENTITY iota "&#953;">
<!ENTITY kappa "&#954;">
<!ENTITY lambda "&#955;">
<!ENTITY mu "&#956;">
<!ENTITY nu "&#957;">
<!ENTITY xi "&#958;">
<!ENTITY omicron "&#959;">
<!ENTITY pi "&#960;">
<!ENTITY rho "&#961;">
<!ENTITY sigmaf "&#962;">
<!ENTITY sigma "&#963;">
<!ENTITY tau "&#964;">
<!ENTITY upsilon "&#965;">
<!ENTITY phi "&#966;">
<!ENTITY chi "&#967;">
<!ENTITY psi "&#968;">
<!ENTITY omega "&#969;">
<!ENTITY thetasym "&#977;">
<!ENTITY upsih "&#978;">
<!ENTITY piv "&#982;">
<!ENTITY ensp "&#8194;">
<!ENTITY emsp "&#8195;">
<!ENTITY thinsp "&#8201;">
<!ENTITY zwnj "&#8204;">
<!ENTITY zwj "&#8205;">
<!ENTITY lrm "&#8206;">
<!ENTITY rlm "&#8207;">
<!ENTITY sbquo "&#8218;">
<!ENTITY bdquo "&#8222;">
<!ENTITY dagger "&#8224;">
<!ENTITY Dagger "&#8225;">
<!ENTITY hellip "&#8230;">
<!ENTITY permil "&#8240;">
<!ENTITY prime "&#8242;">
<!ENTITY Prime "&#8243;">
<!ENTITY oline "&#8254;">
<!ENTITY frasl "&#8260;">
<!ENTITY euro "&#8364;">
<!ENTITY image "&#8465;">
<!ENTITY weierp "&#8472;">
<!ENTITY real "&#8476;">
<!ENTITY alefsym "&#8501;">
<!ENTITY larr "&#8592;">
<!ENTITY uarr "&#8593;">
<!ENTITY rarr "&#8594;">
<!ENTITY darr "&#8595;">
<!ENTITY harr "&#8596;">
<!ENTITY crarr "&#8629;">
<!ENTITY lArr "&#8656;">
<!ENTITY uArr "&#8657;">
<!ENTITY rArr "&#8658;">
<!ENTITY dArr "&#8659;">
<!ENTITY hArr "&#8660;">
<!ENTITY forall "&#8704;">
<!ENTITY part "&#8706;">
<!ENTITY exist "&#8707;">
<!ENTITY empty "&#8709;">
<!ENTITY nabla "&#8711;">
<!ENTITY isin "&#8712;">
<!ENTITY notin "&#8713;">
<!ENTITY ni "&#8715;">
<!ENTITY prod "&#8719;">
<!ENTITY sum "&#8721;">
<!ENTITY lowast "&#8727;">
<!ENTITY radic "&#8730;">
<!ENTITY prop "&#8733;">
<!ENTITY infin "&#8734;">
<!ENTITY ang "&#8736;">
<!ENTITY and "&#8743;">
<!ENTITY or "&#8744;">
<!ENTITY cap "&#8745;">
<!ENTITY cup "&#8746;">
<!ENTITY int "&#8747;">
<!ENTITY there4 "&#8756;">
<!ENTITY sim "&#8764;">
<!ENTITY cong "&#8773;">
<!ENTITY asymp "&#8776;">
<!ENTITY ne "&#8800;">
<!ENTITY equiv "&#8801;">
<!ENTITY le "&#8804;">
<!ENTITY ge "&#8805;">
<!ENTITY sub "&#8834;">
<!ENTITY sup "&#8835;">
<!ENTITY nsub "&#8836;">
<!ENTITY sube "&#8838;">
<!ENTITY supe "&#8839;">
<!ENTITY oplus "&#8853;">
<!ENTITY otimes "&#8855;">
<!ENTITY perp "&#8869;">
<!ENTITY sdot "&#8901;">
<!ENTITY lceil "&#8968;">
<!ENTITY rceil "&#8969;">
<!ENTITY lfloor "&#8970;">
<!ENTITY rfloor "&#8971;">
<!ENTITY lang "&#9001;">
<!ENTITY rang "&#9002;">
<!ENTITY loz "&#9674;">
<!ENTITY spades "&#9824;">
<!ENTITY clubs "&#9827;">
<!ENTITY hearts "&#9829;">
<!ENTITY diams "&#9830;">
<!ENTITY nbsp "&#160;">
<!ENTITY iexcl "&#161;">
<!ENTITY cent "&#162;">
<!ENTITY pound "&#163;">
<!ENTITY curren "&#164;">
<!ENTITY yen "&#165;">
<!ENTITY brvbar "&#166;">
<!ENTITY sect "&#167;">
<!ENTITY uml "&#168;">
<!ENTITY copy "&#169;">
<!ENTITY ordf "&#170;">
<!ENTITY laquo "&#171;">
<!ENTITY not "&#172;">
<!ENTITY shy "&#173;">
<!ENTITY reg "&#174;">
<!ENTITY macr "&#175;">
<!ENTITY deg "&#176;">
<!ENTITY plusmn "&#177;">
<!ENTITY sup2 "&#178;">
<!ENTITY sup3 "&#179;">
<!ENTITY acute "&#180;">
<!ENTITY micro "&#181;">
<!ENTITY para "&#182;">
<!ENTITY middot "&#183;">
<!ENTITY cedil "&#184;">
<!ENTITY sup1 "&#185;">
<!ENTITY ordm "&#186;">
<!ENTITY raquo "&#187;">
<!ENTITY frac14 "&#188;">
<!ENTITY frac12 "&#189;">
<!ENTITY frac34 "&#190;">
<!ENTITY iquest "&#191;">
<!ENTITY Agrave "&#192;">
<!ENTITY Aacute "&#193;">
<!ENTITY Acirc "&#194;">
<!ENTITY Atilde "&#195;">
<!ENTITY Auml "&#196;">
<!ENTITY Aring "&#197;">
<!ENTITY AElig "&#198;">
<!ENTITY Ccedil "&#199;">
<!ENTITY Egrave "&#200;">
<!ENTITY Eacute "&#201;">
<!ENTITY Ecirc "&#202;">
<!ENTITY Euml "&#203;">
<!ENTITY Igrave "&#204;">
<!ENTITY Iacute "&#205;">
<!ENTITY Icirc "&#206;">
<!ENTITY Iuml "&#207;">
<!ENTITY ETH "&#208;">
<!ENTITY Ntilde "&#209;">
<!ENTITY Ograve "&#210;">
<!ENTITY Oacute "&#211;">
<!ENTITY Ocirc "&#212;">
<!ENTITY Otilde "&#213;">
<!ENTITY Ouml "&#214;">
<!ENTITY times "&#215;">
<!ENTITY Oslash "&#216;">
<!ENTITY Ugrave "&#217;">
<!ENTITY Uacute "&#218;">
<!ENTITY Ucirc "&#219;">
<!ENTITY Uuml "&#220;">
<!ENTITY Yacute "&#221;">
<!ENTITY THORN "&#222;">
<!ENTITY szlig "&#223;">
<!ENTITY agrave "&#224;">
<!ENTITY aacute "&#225;">
<!ENTITY acirc "&#226;">
<!ENTITY atilde "&#227;">
<!ENTITY auml "&#228;">
<!ENTITY aring "&#229;">
<!ENTITY aelig "&#230;">
<!ENTITY ccedil "&#231;">
<!ENTITY egrave "&#232;">
<!ENTITY eacute "&#233;">
<!ENTITY ecirc "&#234;">
<!ENTITY euml "&#235;">
<!ENTITY igrave "&#236;">
<!ENTITY iacute "&#237;">
<!ENTITY icirc "&#238;">
<!ENTITY iuml "&#239;">
<!ENTITY eth "&#240;">
<!ENTITY ntilde "&#241;">
<!ENTITY ograve "&#242;">
<!ENTITY oacute "&#243;">
<!ENTITY ocirc "&#244;">
<!ENTITY otilde "&#245;">
<!ENTITY ouml "&#246;">
<!ENTITY divide "&#247;">
<!ENTITY oslash "&#248;">
<!ENTITY ugrave "&#249;">
<!ENTITY uacute "&#250;">
<!ENTITY ucirc "&#251;">
<!ENTITY uuml "&#252;">
<!ENTITY yacute "&#253;">
<!ENTITY thorn "&#254;">
<!ENTITY lt "&lt;">
<!ENTITY gt "&gt;">
<!ENTITY amp "&amp;">
]>
<dce>

 <response>
  <outcome><!-- 'success', 'failure' : level 3, 'api_error' : level 2, 'system_error' : level 1 --></outcome>
		
  <!-- if the outcome is not 'success' then the section below will contain error information -->
  <errors>
   <error>
    </code>
    </description>
   </error>
  </errors>
  
  <!-- response data specific to the request made -->

 </response>
 
</dce>

 

 

XML Code Example - PHP5

<?php
$api_url = "https://sandbox.doba.com/api/5.0/xml_partner_api.php";
$api_username = "username";
$api_password = "password";
$api_retailer_id = "123456";

$strRequest = "
<dce>
    <request>
        <authentication>
            <username>". $api_username ."</username>
            <password>". $api_password ."</password>
        </authentication>		
        <retailer_id>". $api_retailer_id ."</retailer_id>
        <action>getSuppliers</action>
    </request>
</dce>
";
	
//initialize a CURL session
$connection = curl_init();
//set the server we are using (could be Sandbox or Production server)
curl_setopt($connection, CURLOPT_URL, $api_url );
//stop CURL from verifying the peer's certificate
curl_setopt($connection, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($connection, CURLOPT_SSL_VERIFYHOST, 0);
//set method as POST
curl_setopt($connection, CURLOPT_POST, 1);
//set the XML body of the request
curl_setopt($connection, CURLOPT_POSTFIELDS, $strRequest);
//set it to return the transfer as a string from curl_exec
curl_setopt($connection, CURLOPT_RETURNTRANSFER, 1);
//increase time-out as some calls can take a long time to respond with data
set_time_limit(108000);
//Send the Request
$strResponse = curl_exec($connection);
if(curl_errno($connection)) {
    print 'Curl error: ' . curl_error($connection);
} 
//close the connection
curl_close($connection);

print_r($strResponse);
?>

 

 

SOAP

 

SOAP API URL

The following URL is to be used for development and testing:

Product Methods:

https://sandbox.doba.com/soap/5.0/wsdl/ApiPartnerSearch.wsdl link

Order Methods:

https://sandbox.doba.com/soap/5.0/wsdl/ApiPartnerOrder.wsdl link

Retailer Methods:

https://sandbox.doba.com/soap/5.0/wsdl/ApiPartnerRetailer.wsdl link

The following URL's are to be used in production after testing on the sandbox server has been validated:

Product Methods:

https://www.doba.com/soap/5.0/wsdl/ApiPartnerSearch.wsdl link

Order Methods:

https://www.doba.com/soap/5.0/wsdl/ApiPartnerOrder.wsdl link

Retailer Methods:

https://www.doba.com/soap/5.0/wsdl/ApiPartnerRetailer.wsdl link

 

SOAP Code Example - PHP5

The PHP5 example code below shows how to set up a SOAP client to call the API. There are three variables (username, password and retailer_id) within the code that you will need to replace with your own.

This code requires PHP5 with SOAP configured properly. Other development environments may use similar structure, although the functions will need to be customized accordingly.

<?php
$client = new   SoapClient("https://sandbox.doba.com/soap/5.0/wsdl/ApiPartnerSearch.wsdl", array('trace' => 1));
$objAuth = new stdClass();
$objAuth->username = '%username%'; 
$objAuth->password = '%password%';
$objRequest = new stdClass();   
$objRequest->authentication = $objAuth; 
$objRequest->retailer_id = '%retailer_id%';
$objRequest->products = array(147129); 
$objRequest->items = array(); 
$objRequest->watchlists = array(); 
$response = $client->getProductDetail($objRequest); 
if(false == is_soap_fault($response)){   
 foreach($response as $product) {   
  foreach ($product->items as $item) { 
   print   "price: "  . $item->price . "\n\n"; 
  }   
 }
	print_r($response);
}else{   
 echo   "error code: " . $response->faultstring . "<br>"; 
 echo   "error message: " . $response->detail . "<br>"; 
}   
?> 

 

SOAP Code Example - .NET

The .NET example code below shows how to set up a SOAP client to call the API. There are three variables (username, password and retailer_id) within the code that you will need to replace with your own.

This code requires that you initially build a DLL with the WSDL file. Once that is accomplished, the code below can be utilized to submit and accept the content of the request..

<%@ Page Language="C#" %>
<%@ import Namespace="System.Data" %>
<%@ import Namespace="System.IO" %>
<%@ import Namespace="System.Text" %>
<% 
  ApiRetailerAuthenticationInfo _auth = new ApiRetailerAuthenticationInfo();
  ApiRetailerSearch _ret = new ApiRetailerSearch();
  ApiRetailerBrandRequest _brand = new ApiRetailerBrandRequest();
  ApiBrandResponse[] _brandResponse;
  
  _auth.username = "username";
  _auth.password = "password";
  _brand.authentication = _auth;
  _brand.retailer_id = "retailer_id";
  _brandResponse = _ret.getBrands(_brand);
  
  for (int x = 0; x < _brandResponse.Length; x++) 
 {
 Response.Write(_brandResponse[x].name + "<BR>");
 }
%>

 

Failure Codes

Provides specific information regarding the failure of any given API call.

Because there are several layers at which an API call can fail, the API breaks the failures into varying code levels which are explained below.

Level 1 = Fatal System Error, contact Doba

There was a system error and the request was unable to be processed. The call format and/or authentication may be OK, but the system was not able to process the request properly or there was a server or communication error. Typically, these calls should be resubmitted after the cause of the error has been resolved.

It is inevitable that this error level will be provided at some point in your integrations life-time. Although Doba strives for 100% uptime, it is not always possible. Doba monitors the systems responsible for keeping the API available at all times and will be notified of any problems. If you feel that Doba is taking an unreasonable amount of time to resolve the errors, please contact us.

Level 2 = Syntax Error

There was a problem with request format.

The system is attempting to process your request, but there is a problem with the API call's XML format or the syntax of the action you are attempting to submit. Please review this documentation thoroughly to ensure that your calls are properly formatted. Please review your code and the syntax of the action you are attempting to ensure that all required sections of the call are accounted for. If this error persists, please contact Doba where your call can be reviewed and possible solution(s) can be provided.

Level 3 = Data Error

There was a problem with the authentication.

Either your username or password is incorrect or your account is not currently active or it does not have the appropriate permissions assigned. If you are unable to resolve this error on your own, please contact Doba to find out if your account has been configured properly.

 

Failure Code List

Error Explanation
200 Invalid action
201 Permission denied
2011 Permission denied no resource access
2012 Permission denied neither partner nor retailer
2013 Permission denied invalid retailer action
2014 Permission denied invalid action
2015 Permission denied insufficient permissions
2016 Permission denied invalid credentials
2017 Permission denied missing credentials
202 Missing syntax
203 Invalid xml
204 Call requires https
300 Non existent retailer
3001 Retailer not expired
301 Missing email
3010 Email or phone required
302 Missing firstname
303 Missing lastname
304 Missing phone
305 Missing billing street
306 Missing billing city
307 Missing billing state
308 Missing billing postal
309 Missing billing country
310 Missing creditcard number
311 Missing creditcard expiration
312 Missing username
313 Missing api code
314 Missing frequency
315 Missing billing responsibility
316 Missing trial
317 Missing subscription action
318 Missing retailer id
319 Missing item id
320 Missing quantity
321 Missing shipping state
322 Missing shipping postal
3220 Invalid shipping postal
3221 Shipping postal not allowed
3222 Invalid billing postal
323 Missing shipping country
324 Missing order items
325 Missing shipping city
326 Missing shipping street
327 Missing shipping firstname
328 Missing shipping lastname
329 Missing order id
330 Missing fund method
331 Missing payment account id
332 Missing billing name
333 Missing cvv2
334 Missing orderlist item info
335 Missing order status
336 Missing orderlist items
337 Missing billing lastname
338 Missing billing firstname
339 Missing creditcard expiration year
340 Missing creditcard expiration month
341 Missing watchlist id
342 Watchlist user mismatch
343 Watchlist invalid
3430 Folder invalid
344 Could not save watchlist
3440 Max watchlists reached
3441 Duplicate watchlist name
345 Could not delete watchlist
3450 Could not add items
34501 Items not available
346 Missing saved search id
347 Saved search user mismatch
348 Saved search invalid
349 Could not save search
3490 Max saved searches reached
3491 Duplicate saved search name
350 Could not delete saved search
3501 Old saved search
3502 Duplicate customization profile name
3503 Could not load customization profile
3504 Customization profile not allowed
3505 Could not delete customization profile
3506 Could not rename customization profile
3507 Empty customization profile name
3508 Could not remove customization data from item
3509 Missing customization profile id
351 Order not specified
352 Missing ip address
353 Order not available to user
354 Shipping address missing
355 No items in cart
356 Cannot cancel supplier order
357 Missing cancellation reason
358 No decisions submitted
359 No decisions exist
360 Invalid email
361 Invalid phone
362 Invalid creditcard number
363 Invalid subscription action
364 Invalid shipping state
365 Invalid shipping country
366 No action taken
367 Invalid ip address
368 Invalid username
369 Username already exists
370 Supplier order unavailable
371 Missing rma reason
372 Missing rma type
373 Missing rma items
374 Missing rma id
3740 Missing shipment date
3741 Invalid shipment date
3742 Missing carrier
3743 missing tracking
3744 Invalid parcel count
3745 Could not save tracking
375 Missing warehouse folder path
3750001 Failed to copy folder
376 Failed to save path
377 Failed to delete folder
378 Missing warehouse folder id
3780 Push request id
379 Failed to retrieve folders
380 Permission to retailer denied
381 Missing items
382 Missing folder name
383 Failed to add items to folder
3830 Failed to add items to push request
3831 Folder item limit reached
3830001 Failed to copy items to folder
384 Failed to delete items from foler
385 Failed to rename folder
3850 Folder name already exists
386 Invalid retailer id
387 Invalid billing country
390 Call limit reached
400 Unavailable order item
4001 Invalid order item
4002 Duplicate order item
401 Inaccessible order item
402 Unavailable order
403 Invalid order
404 Invalid payment account
405 Invalid subscription
406 Invalid frequency
407 Invalid billing responsibility
408 Invalid order id
4080 Invalid order group id
409 Invalid order status
410 Invalid order po number
411 Cannot mix directrelation orders
4110 Cannot group specified orders
4111 Cannot ungroup specified orders
412 Invalid export
413 Missing export
416 Missing export name
417 Missing transform commands
418 Invalid transform commands
419 Missing records
420 Missing url tag
421 Invalid url tag
422 Duplicate url tag
423 Missing folder id
4230 Missing search id
4231 Missing source type
4232 INvalid search id
424 Invalid folder id
425 Invalid changes since time
426 Invalis changes since secs
427 Missing transform
428 Missing transform id
429 Invalid transform id
430 Missing transform name
431 Missing transform format
432 Invalid transform format
433 Missing transform format parameters
434 Invalid transform format parameters
435 Invalid transform criteria
436 Invalid transform scope
437 Transform edit permission
438 Could not load export
439 Failed to run export
440 Could not run export transform
441 Failed to add export transform
442 Failed to edit export transform
443 Failed to delete export transform
444 Failed to create product export
445 Failed to edit product export
446 Failed to delete product export
447 Unavailable export
448 Unavailable transform
500 Failed to save order
501 Failed to fund order
502 Payment failed
503 Failed to save payment
510 Product not found
520 Product id required
521 Invalid status trigger
522 Item id required
523 Profile id required
530 Trigger required
531 Invalid status trigger
532 Frequency required
534 Frequency time required
535 Invalid frequency time
536 Unable to set folder preferences
537 Unable to remove folder preferences

 

 

Sandbox

A sandbox is a testing (or virtual) environment that isolates untested code changes and outright experimentation from the production environment. Sandbox environments protect production servers and their data from changes that could be damaging (regardless of the intent of the author of those changes) to a mission-critical system or which could simply be difficult to revert. Sandboxes replicate the functionality needed to test accurately the programs or other code under development. See Wikipedia for further clarification.

Notice: Although we strive to keep the sandbox server available at all times, there may be times when it will not be accessible. If this is the case, please contact Doba.

Sandbox URL

The sandbox API URL information is found in the following locations...

XML

SOAP

Sandbox Web Site

Additionally, a sandbox web site, mimicking the Doba web site, is available at the URL below.

https://sandbox.doba.com/  [link]

The sandbox web site can be used to perform several tasks that would normally be done by suppliers. For orders, you can log in as a retailer so that you can view orders and change status' and/or send callbacks upon status changes.

To change the status of an order, log in as the retailer your using in your API calls and select "orders". Select an order from the list by clicking the number in the "order" column or by searching for the order number at the top. In the supplier order section of the order detail, select the yellow button labeled "Change Order Status". Select and save the new status and a callback will be issued to the location saved in your sandbox URL settings.

To change the callback URL used in your sandbox environment, log into your partner account and select "My Account" where you can update your callback URL. Also, ensure that the callback version is set to "5.0" as callbacks will not be generated otherwise.

 

 

 

Export Automation

SMB Retailers who have access to the Warehouse Folders feature are also able to automate the download of export files set up in the Export tab.

Go to the Export tab and modify the Persistent URL to look like the following:

https://username:password@www.doba.com/retailer-export/get/type/product/tag/export_name

Replace the 'username' and 'password' parameters with your own username and password and make sure to use HTTPS as its insecure to pass sensitive information such as your username and password over URL's with HTTP.

Using this URL you can now download the export file automatically without having to log into the site and request the export file manually.

 

 

 

Limits

API version 4.0 introduced the limiting of product data that can be obtained by retailers and partners.

Doba limits the number of product API calls per minute for each retailer account. For any given minute, only 100 API calls will be allowed. If there are more than 100, those from 101 and on will wait for the next minute and then they will be returned, meaning that if you plan on making a lot of API calls per minute, it would be best to extend your time-out settings so your scripts will run longer without failing. In most cases, the limits will never be hit unless your script is set up to obtain product detail for one item at a time. As long as multiple items are requested per call, the limit should never be hit.

There are no limits on Order or Retailer API calls.

The getRetailerAccessInfo API call returns information regarding the limits and current usage for the specified retailer. The limits depend on the subscription package sold to the retailer.

The product_detail_total parameter refers to the limit on the number of products the retailer can receive detailed information for, obtained by using the getProductDetail API command.The product_detail_count parameter refers to to the current progress approaching the limit. As soon as this number matches the limit total the retailer will receive errors upon subsequent product detail calls.

The product_inventory_total parameter refers to the limit on the number of products the retailer can receive inventory information for, obtained by using the getProductInventory API command and also through triggered callbacks for which you have elected to receive inventory updates for (see the watch-list at http://www.doba.com). The product_inventory_count parameter refers to to the current progress approaching the limit. As soon as this number matches the limit total the retailer will receive errors upon subsequent product inventory calls.

 

 

 

Partner Site

Logging In

To access the Doba Partner Support site on the live website, visit the URL below and use your partner account credentials to login.

http://www.doba.com/partner/

To access the Doba Partner Support site on the sandbox website, visit the URL below and use your partner account credentials to login.

http://sandbox.doba.com/partner/

Account Setup

Your account representative will initially configure your account. However you may want to alter some of the settings on your account. To do so, visit the Account Setup section of the site.

API Errors

During the course of integrating with Doba and testing the API, the API Error log will be an invaluable tool for debugging your application. API Calls to your account which result in an error response will be shown in the API Errors section of the site.

In fact, if you followed the instructions in the Executing your First API Call section above, you should be able to see your first two calls that resulted in error code 2 in the API Error Log.

Users

To expedite the integration process you may begin referring users without implementing the API or using the direct campaigns described in the Doba Revenue Share Partner Program Guide by going to Users -> Add User.

You can also browse your referred users in the Users section of the site.

 

 

 

Creating Users through the API

 

Service Selection

Before you begin to create accounts through the API, you should first determine how you plan to promote access to Doba services to your users.

 

Promote Trial Services

One option is to bundle Doba trial accounts with your service offering. When someone signs up for your service you can give them an option to receive a free 14-day trial to Doba's Product Sourcing Services as a check box during sign up or on your confirmation page. If someone chooses to receive the 14-day trial, you would simply submit an API call to Doba to create that user. Another way to refer customers to Doba's 14-day trial that doesn't require API programming is to simply refer existing customers, past customers, and new customers to a cobranded landing page like www.doba.com/partners/ebay. Your cobranded landing page will provide your members with a free 14-day trial to Doba's product sourcing services, which is twice as long as the trial period available at Doba.com. In both cases, Doba will bill your customer for our services and pay you revenue share each month for the life of the customer. You can see the success of your marketing efforts by logging in to the Partner Support Site with your API username/password at www.doba.com/partner.

 

Reselling Doba Services

You may want to act as a reseller for Doba services and pay for your customers' access to Doba. Doba's VARs are able to purchase Doba's services at a minimum of a 50% discounted buy rate. You can purchase access for your customers on a monthly or annual basis. Each month you will receive an invoice from Doba for the active customers you have created in our system. When users are created via the API and the VAR is the billing responsible party, you are also responsible for canceling the user over an API call. Reselling the service is ideal for tightly integrated services where you are selling a new tier to your services that includes product sourcing. Receiving one bill for a bundled solution has also proven to increase overall retention.

 

Representing Doba Services

When creating an account on behalf of clients, partners are required to adhere to the following requirements.

 

Service Identification and Branding

Partners must use the integrated partner logo (right) or other alternate Doba-approved creative to identify that the service is being provided by Doba. The sales page or registration process must clearly explain which Doba services are being offered and whether they are done so on a trial basis (where the user must pay for continued access) or if the partner is provisioning the account at no cost to the client.

If the offer for Doba services is to be made verbally by a sales representative, the script must be approved by Doba to ensure the services are accurately represented and the clients understand their rights and responsibilities.

 

Terms and Conditions

At the time of sale the clients must accept the terms and conditions for the services offered. The following URL is maintained by Doba as a permanent location for the T&C content. This URL returns an HTML page that can be opened in a new window from a" Terms" link or pulled into an iframe.

http://www.doba.com/site/terms.html  [link]

 

Privacy Policy

At the time of sale partners must link to the appropriate privacy policy so clients can be made aware of how we may use their personal information. This URL returns a web page intended to be opened in a new window at the time of registration.

http://www.doba.com/site/privacy.html [link]

 

Supplier Policy

Product and Return policies are unique to each supplier, therefore requiring each supplier to maintain their own policy. This URL returns a web page intended to be opened in a new window if required. Replace [supplier_id] with the supplier's ID.

http://www.doba.com/partner/integrate/supplier/[supplier_id]/policy.html [link]

 

Supplier Description

This URL returns a web page with information regarding the supplier's product offering, shipping costs, drop-ship costs and additional information intended to be opened in a new window if required. Replace [supplier_id] with the supplier's ID.

http://www.doba.com/partner/integrate/supplier/[supplier_id]/description.html [link]

 

Help and Support

To ensure that clients have the information and assistance they require to make the most of their Doba services, partner integrations must include prominent links for service support. The link should appear, for example, wherever Doba products or orders are displayed. The link should point to:

http://www.doba.com/support [link]

 

Creating the User

Startup and Advanced Memberships

Beginning in Febuary 2008, Doba memberships are broken into packages. A Doba membership always includes drop-ship services, Premium Education and the Elite Sellers Report. Other packages may include Custom Export, Order Upload and the Push to Marketplace Tool. Additionaly, members who provide Doba with verification of tax status for their company will be given access to additional suppliers who require tax identification.

Please speak with Doba's Director of Business Development to discuss which packages would be best to promote to your customer base. You will be provided with a list of api_code’s associated with the packages you have chosen to represent.

When creating a new user, your call should include the api_code of the package you wish to sell to the user in the addRetailer API command.

 

Creating a Startup User

Suppose you wanted to create a member who had a 30 day trial, billed monthly and charged to the retailer; you would send the following to the addRetailer API command:

<dce>	
    <request>
	
        <authentication>
            <username><!-- partner username --></username>
            <password><!-- partner password --></password>
        </authentication>

  <action>AddRetailer</action>
  
  <email>foo@doba.com</email>
  <firstname>foo_first</firstname>
  <lastname>foo_last</lastname>
  <phone>435-123-4567</phone>
  <billing_street>123 Billing Street</billing_street>
  <billing_city>Fake City</billing_city>
  <billing_state>CA</billing_state>
  <billing_postal>90210</billing_postal>
  <billing_country>US</billing_country>
  <credit_card_number>4111111111111111</credit_card_number>
  <credit_card_exp_month>12</credit_card_exp_month>
  <credit_card_exp_year>2011</credit_card_exp_year>
  <accept_terms>1</accept_terms>
  <ip_address>176.145.23.47</ip_address>
  
  <subscriptions>
   <subscription>
    <api_code>SP250</api_code>
    <frequency>M</frequency>
    <billing_responsibility>R</billing_responsibility>
    <trial>30</trial>    
   </subscription>
  </subscriptions>


    </request>
</dce>

 

To create a member who has a 7 day trial, billed yearly with the partner paying for the account; you would send the following to the addRetailer API command:

<dce>	
    <request>
	
        <authentication>
            <username><!-- partner username --></username>
            <password><!-- partner password --></password>
        </authentication>

  <action>AddRetailer</action>
  
  <email>foo@doba.com</email>
  <firstname>foo_first</firstname>
  <lastname>foo_last</lastname>
  <phone>435-123-4567</phone>
  <billing_street>123 Billing Street</billing_street>
  <billing_city>Fake City</billing_city>
  <billing_state>CA</billing_state>
  <billing_postal>90210</billing_postal>
  <billing_country>US</billing_country>
  <credit_card_number>4111111111111111</credit_card_number>
  <credit_card_exp_month>12</credit_card_exp_month>
  <credit_card_exp_year>2011</credit_card_exp_year>
  <accept_terms>1</accept_terms>
  <ip_address>176.145.23.47</ip_address>
  
  <subscriptions>
   <subscription>
    <api_code>SP250</api_code>
    <frequency>Y</frequency>
    <billing_responsibility>P</billing_responsibility>    
   </subscription>
  </subscriptions>


    </request>
</dce>

 

 

 

Managing Memberships

Ending Financial Responsibility

Your financial responsibility can be ended by using the cancelRetailer API call. This will require that the retailer be responsible for their subscription. The retailer will then be billed on the expiration date currently set on their account.

 

Billing Invoices

Real time charges to your partner account can be reviewed at the Partner Support Site by going to Financial -> Billing Charges.

Invoices will be created the first of each month and will include the previous month's billing charges.

 

 

 

Order Lifecycle

A Doba order will normally progress through the following four primary stages. These four stages are also the core statuses for the Doba order life cycle.

  1. Payment Pending
  2. Funded
  3. Processing
  4. Shipped

Understanding the order life cycle is important when building an application which includes Doba order integration.

You will notice that the "Awaiting Review" status is encountered during the course of some orders. This is a fraud prevention related step where the Doba order management team reviews orders and payments which exceed a risk threshold. No action is required by integration partners to progress orders through this step. A Doba support representative may contact the client in the process of reviewing orders.

At any point in the order process an order may be placed in a "hold" or "cancelled" status. The "hold" status is used when manual intervention is required during order processing. Examples of scenarios for held orders include shipping address correction. Both the "shipped" and "cancelled" status are considered terminal statuses.

 

Order Status'

It's important to understand the structure of an order to understand the different status' that may be encountered through the order lifecycle.

A Doba order is broken into three levels. The highest level encompases the entire order, including the totals for all items, shipping, drop-ship fees, etc.

The second level contains all of the individual supplier orders, or orders broken into groups of items that come from the same supplier. Each supplier order will have its own status.

Because there can be multiple supplier orders in one order, the top-level order status will sometimes be "Various". This will happen if the suppler order status' differ from each another. If all supplier order status' are the same, the order status will be identical to the supplier order status'.

The scenerios below will help explain how different status' are represented:

Order 1
Order Status = Completed
Supplier Order Status = Completed

Order 2
Order Status = Completed
Supplier Order 1 Status = Completed
Supplier Order 2 Status = Completed
Supplier Order 3 Status = Completed

Order 3
Order Status = Various
Supplier Order 1 Status = Completed
Supplier Order 2 Status = Shipment Pending
Supplier Order 3 Status = Completed

Order 4
Order Status = Cancelled
Supplier Order 1 Status = Cancelled
Supplier Order 2 Status = Cancelled
Supplier Order 3 Status = Cancelled

Order 5
Order Status = Cancelled
Supplier Order Status = Cancelled

The last level is item status which has its own set of status'.

 

Supplier Order Status'

The full range of order lifecycle status' are explained in the following table.

Status Description
Error - Contact Support The order is in an erroneous state and is being investigated by a Doba fulfillment specialist.
Awaiting Payment Customer must submit payment for the order to continue; initiated PayPal payment may be outstanding.
Funded The order has been funded. It is being processed by the Doba platform and will be deleivered to the supplier for fulfillment if no problems are found.
Shipped Shipment information has been received from the supplier and the order is en-route or received.
Payment Declined Authorized payment failed to settle.
Processing The Doba order engine is processing the order. This status is fleeting and will normally not be encountered by integrated systems.
Hold - Input Needed Retailer input is needed for the order to be processed; customer is notified by e-mail and can provide input by logging into the site.
Shipment Pending The order has been sent to the supplier and is being fulfilled; Doba is waiting for supplier response and a shipment notice is expected.
Awaiting Payment Confirmation This normally only occurs during an eCheck transaction through PayPal, where Doba is notified of the payment but it has not yet cleared.
Awaiting Supplier Cancel The customer has requested cancellation and Doba is initiating the cancellation process with the supplier.
Cancelled The order is cancelled and will not be fulfilled.
Fraudulent Order The order was aborted and deemed to be fraudulent.
Returned The product(s) have been returned to the supplier and return receipt verified.
Completed The order completed normally.
Awaiting Supplier Acceptance Some suppliers use an asynchronous acknowledgement. In this state the order has been submitted but not acknowledged.

 

Line Item Status'

In addition to better overall order tracking and statuses the API also exposes line item statuses for each item in an order.

Status Description
Pending The item is waiting to be sent to the supplier.
Processing The DOBA order engine is processing the order. This status is fleeting and will normally not be encountered by integrated systems.
Scheduled The item has not yet been accepted by the supplier as part of an order, but the order is on back order with Doba. i.e. Doba is waiting for new inventory to re-send the item to the supplier.
Shipment Pending The item has been sent to the supplier.
Shipped The item is on route to the end consumer.
Partial Some of the quantity have shipped, others are pending shipment or possible cancellation
Cancelled The item has been cancelled and removed from the order.
Returned The item has been returned to the supplier.
Discontinued The item has been discontinued and removed from the order.
Waiting The item is waiting for the supplier to update its status.

 

Order Lifecycle Integration Work-Flow

Typically, when integrating the Order API into your application, you will want to follow the outline below as a basic work-flow.

  1. Gather all item_id's and call the orderLookup function making sure to deal with any out-of-stock items or items that may not be currently available.
  2. Display the totals found in the orderLookup function and wait for the end-user to submit the final order.
  3. Create the order using the createOrder API call. You may wish to fund the order using this call or fund the order at a separate time.
  4. Wait until order updates are delivered using the call-back functions.