SWHelp:StampWants API Send

From StampWantsWiki

The StampWants API allows you to send information to StampWants.com to either create new listings, or take actions on existing listings and sales.

Contents 1 Creating a Post 1.1 The File Command URL 1.2 Passing a Comma Separate Value (csv) File 2 Receiving a Response 3 File Command CSV File Format 4 File Command Commands and Required Fields 4.1 LIST 4.2 LISTIFNOT 4.3 EDIT 4.4 END 4.5 UPDATE 5 File Command Results CSV File Format

Creating a Post

To request action be taken on StampWants.com, through the StampWants API you must make an HTTP or HTTPS post the the File Command URL, and you must post a Comma Separated Value (csv) file in the File Command format.

The File Command URL

Using the basic File Command URL format, set your username and password as usual, and set the type variable to 'upload':

http://www.stampwants.com/filecommand.php?username=myUserName&password=myPassWord&type=upload

Passing a Comma Separate Value (csv) File

You must pass a File Command csv file as a POST variable to the File Command URL. The POST variable containing the File Command file must be named:

auctionfile

(the above variable name is case sensitive)

Depending on the programming language you are using, the exact specification how to post a file to a URL will differ. However, here is an example of a PHP (with cUrl enabled) function which will post a File Command csv file to the File Command URL:

 function stampwantsFileCommand($username,$password,$commandfilename){
	$FileCommandURL = "http://www.stampwants.com/filecommand.php?username=".$username."&password=".$password."&type=upload";

	$postdata['auctionfile'] = "@".$commandfilename; //The @ in front makes CURL load the file content, not just use the literal string
	
	$ch = curl_init(); 

	curl_setopt($ch, CURLOPT_URL, $FileCommandURL );
	curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 
	curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);

	$result = curl_exec($ch);

	curl_close ($ch);
	
	//Should be a File Command Results CSV file (as a string)
	return $result;
 }
 

The above function could be used to send a File Command CSV file to the File Command URL by calling:

stampwantsFileCommand("myUserName","myPassWord","/home/usr/temp/fileCommand.csv")

Where "myUserName" is your StampWants username, "myPassWord" is your StampWants password and "/home/usr/temp/fileCommand.csv" is a File Command CSV file your program or application has created.

Receiving a Response

When posting a File Command CSV file to the StampWants API, you will receive a response back in the form of a File Command Results CSV file. The File Command Results CSV file will be echoed as the response to your HTTP post. You should save the response you receive as a string in your program or application, and then parse that string as a csv file. The File Command Results CSV file will contain information on each of the commands sent in your File Command CSV file, as well as the success of each command.

File Command CSV File Format

When sending a File Command CSV File to the StampWants API it must be in the File Command CSV File Format. The first row of your file must contain the headers for the columns in your file. The columns which are available are as follows:

Field Name	Allowed Values	Description
Command	LIST, LISTIFNOT, EDIT, END, or UPDATE	The command you are requesting for this row. Please see the File Command Commands section below.
StampWants ID	Integer (StampWants ID)	The StampWants ID of the listing or transaction that you want to take action on. Note: This does not apply to 'LIST' and 'LISTIFNOT', since no StampWants ID exists yet for items you have not yet listed.
Private ID	Text	The Private ID of the listing that you want to take action on. Note: This does not apply to 'LIST' and 'LISTIFNOT'. Note: You cannot UPDATE a transaction (an item you have sold or won) using the Private ID field. You must use either the StampWants ID or the Transaction ID.
Transaction ID	Integer	The Transaction ID of the transaction that you want to take action on. Note: This only applies to 'UPDATE'.
Update Paid	Unpaid, Paid, Paid with PayPal, Paid by Check, Paid by Money Order, Paid by Credit Card, Paid with Google, Waiting...*, Check Clearing...*, Canceled or Refunded	The value you want to change the Paid Status to. Note: This only applies to 'UPDATE'. Additionally 'Waiting...' is only available if you are the buyer of the item indicated, and 'Check Clearing...' is only available if you are the seller of the item indicated.
Update Shipped	Not Shipped, Shipped, Processing, Canceled, Returned	The value you want to change the Shipped Status to. Note: This only applies to 'UPDATE'. (and if you are the seller of the item indicated)
Update Received	Not Received, Received, Canceled or Returned	The value you want to change the Received Status to. Note: This only applies to 'UPDATE'. (and if you are the buyer of the item indicated)
Update Feedback	1,3,5	The rating you wish to leave for feedback for the indicated transaction. 1=Negative, 3=Neutral, 5=Positive. Note: This only applies to 'UPDATE'.
Update Feedback Comment	Text (255 Characters)	The comment you wish to leave for feedback for the indicated transaction. Note: This only applies to 'UPDATE'.

Additionally, your file must contain additional fields if you are using the 'LIST', 'LISTIFNOT' or 'EDIT' command. These fields are listed on the Bulk Uploader Fields List page.

All File Command CSV Files must contain the 'Command' column, and this column cannot be blank for any rows within your file. Depending on which command you are requesting certain other fields are required from the list above. It is possible to mix commands in a single File Command CSV File. To do so simply leave any unneeded columns blank in any particular row.

File Command Commands and Required Fields

LIST

This indicates that you want to list the item in this row of your File Command CSV File.

In addition to Command, the Title, (Starting Bid or Buy It Now Price [or Spot Gold Price and Percent for Coins Only]) and Category are required. However, we recommend that you set as many of the fields found on the Bulk Uploader Fields List page as possible, to ensure that your listing is both accurate and complete. This includes but is not limited to payment, shipping and image information. Also, please note that if you do not set any values for shipping costs, your shipping will be indicated as free, unless you are using table rate shipping.

LISTIFNOT

This indicates that you want to list the item in this row of your File Command CSV File, if and only if there is not item currently listed with the private id indicated in this row.

In addition to Command, the Title, (Starting Bid or Buy It Now Price [or Spot Gold Price and Percent for Coins Only]) and Category are required. However, we recommend that you set as many of the fields found on the Bulk Uploader Fields List page as possible, to ensure that your listing is both accurate and complete. This includes but is not limited to payment, shipping and image information. Also, please note that if you do not set any values for shipping costs, your shipping will be indicated as free, unless you are using table rate shipping.

EDIT

This indicates that you want to edit the item indicated by the StampWants ID or Private ID in this row, and update the information of that listing with the information indicated in this row.

In addition to Command, the StampWants ID or Private ID is required. Any other fields filled in will result in your listing being updated with such information. For example, filling in the Title field will replace the title of the indicated listing with the new title you have provided. Note: You can not change the duration of your existing listings. You also cannot edit an auction with active bids.

END

This indicates that you want to end the item indicated by the StampWants ID or Private ID in this row.

In addition to Command, the StampWants ID or Private ID is required. Note: You can not end an auction or fixed price listing which has less than 1 hour left, or any active bids and less than 12 hours left.

UPDATE

This indicates that you want to update the sales transaction associated with either the StampWants ID or Transaction ID in this row, for items which have sold or you have won.

In addition to Command, the StampWants ID or Transaction ID is required. The additional fields available for this command are Update Paid, Update Shipped, Update Received, Update Feedback and Update Feedback Comment. Note: Once Feedback has been left for an item it cannot be changed or updated. Additionally, if you are setting the Update Feedback please also set the Update Feedback Comment.

File Command Results CSV File Format

After you post your File Command CSV file to the StampWants API, we will post a File Command Results CSV file back to you in response. Depending on the amount of commands you send, this may take a while to complete. Please make sure that if sending a large file, you program or application does not timeout too soon.

The first line of the csv file will contain the names of each column - the column headings. Please note that if no data is returned you should still receive the column headings back. If you do not receive a csv file with at least 1 row consisting of the column headings your File Command URL may be set incorrectly. Please first check for any issues in your program or application and the File Command URL you are sending. If you cannot correct the issue, please contact us for assistance.

Here is the format of the File Command Results CSV file returned to you:

Field Name	Value Type	Description
Row	Integer	The Row number in the original File Command CSV File you sent which this response corresponds to. Note: Starting with Row 1, and not including the column headers row.
Command	LIST, LISTIFNOT, EDIT, END, or UPDATE	The Command your File Command CSV File requested for this row.
Success	SUCCESS, WARNING, FAILURE	The Success of the command. SUCCESS=The command was executed sussesfully with no issues. WARNING=The command was executed, but their may have been one or more problems with your command, which may or may not result in the exact result you intended. For clarification, see the Message field.
Message	Text	If the success was either a WARNING or FAILURE, the message will contain additional information as to any problems with the command requested.
StampWants ID	Integer (StampWants ID)	The StampWants ID of either the listing affected by the command, or the new StampWants ID in the result of a 'LIST' or 'LISTIFNOT' command.
PrivateID	Text	The Private ID of either the listing affected by the command, or the Private ID of the newly created listing in the result of a 'LIST' or 'LISTIFNOT' command. Note: This only applies if you have a Private ID set for this listing.
Category	Integer Number (a valid Category Code, as found on the Category Code page).	The main category of the listing. Note: This only applies to the 'LIST' or 'LISTIFNOT' command. The reason this information is given is in case you set the category to a Magic Category when creating the listing, this will show you the result of which category your item was placed into.
Additional Category	Integer Number (a valid Category Code, as found on the Category Code page).	The additional category of the listing. Note: This only applies to the 'LIST' or 'LISTIFNOT' command. The reason this information is given is in case you set the additional category to a Magic Category when creating the listing, this will show you the result of which additional category your item was placed into.
Title	Text	The Title of either the listing affected by the command, or the new listing in the result of a 'LIST' or 'LISTIFNOT' command.