.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::eBay 3"
.TH Net::eBay 3 2023-01-20 "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Net::eBay \- Perl Interface to XML based eBay API.
.SH VERSION
.IX Header "VERSION"
Version 0.62
.SH SYNOPSIS
.IX Header "SYNOPSIS"
This module helps user to easily execute queries against eBay's XML API.
Copyright Igor Chudov, ichudov@algebra.com.
Released under GNU Public License v. 2
.PP
.Vb 5
\&    ##################################################
\&    # For support, docs, info, email to author go to #
\&    #                                                #
\&    #             http://www.net\-ebay.org/           #
\&    ##################################################
.Ve
.PP
Also check out Object::eBay perl module for higher level abstraction
built on top of Net::eBay. Object::eBay is a work of another
individual, not Igor Chudov.
.PP
Also check out several ebay\-*.pl scripts that ship with this
distribution, they should be installed in your scripts directory.
.SS "Getting Official Time"
.IX Subsection "Getting Official Time"
.Vb 4
\& use Net::eBay;
\& my $eBay   = new Net::eBay; # look up ebay.ini in $ENV{EBAY_INI_FILE}, "./ebay.ini", "~/.ebay.ini"
\& my $result = $eBay\->submitRequest( "GeteBayOfficialTime", {} );
\& print "eBay Official Time = $result\->{EBayTime}.\en";
.Ve
.SS "Automated bidding"
.IX Subsection "Automated bidding"
eBay does not allow bidding via eBay API.
.SS "Listing Item for sale"
.IX Subsection "Listing Item for sale"
.Vb 2
\& use Net::eBay;
\& use Data::Dumper;
\&
\& # another way of creating Net::eBay object.
\& my $ebay = new Net::eBay( {
\&                              SiteLevel => \*(Aqprod\*(Aq,
\&                              DeveloperKey => \*(Aq...\*(Aq,
\&                              ApplicationKey => \*(Aq...\*(Aq,
\&                              CertificateKey => \*(Aq...\*(Aq,
\&                              Token => \*(Aq...\*(Aq,
\&                             } );
\&
\& my $result = $ebay\->submitRequest( "AddItem",
\&                      {
\&                       DetailLevel => "0",
\&                       ErrorLevel => "1",
\&                       SiteId = > "0",
\&                       Verb => "  AddItem",
\&                       Category => "14111",
\&                       CheckoutDetailsSpecified => "0",
\&                       Country => "us",
\&                       Currency => "1",
\&                       Description => "For sale is like new <A HREF=http://www.example.com/jhds/>thingamabob</A>.Shipping is responsibility of the buyer.",
\&                       Duration => "7",
\&                       Location => "Anytown, USA, 43215",
\&                       Gallery => 1,
\&                       GalleryURL => \*(Aqhttp://igor.chudov.com/images/mark_mattson.jpg\*(Aq,
\&                       MinimumBid => "0.99",
\&                       BuyItNowPrice => 19.99,
\&                       PayPalAccepted => "1",
\&                       PayPalEmailAddress => "ichudov\e@example.com",
\&                       Quantity => "1",
\&                       Region => "60",
\&                       Title => "Igor\*(Aqs Item with Gallery xaxa",
\&                      }
\&                    );
\&
\&  print "Result: " . Dumper( $result ) . "\en";
.Ve
.PP
Result of submitRequest is a perl hash obtained from the response XML using XML::Simple, something like this:
.PP
.Vb 10
\& Result: $VAR1 = {
\&          \*(AqItem\*(Aq => {
\&                    \*(AqId\*(Aq => \*(Aq4503546598\*(Aq,
\&                    \*(AqFees\*(Aq => {
\&                              \*(AqFeaturedGalleryFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqInternationalInsertionFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqCurrencyId\*(Aq => \*(Aq1\*(Aq,
\&                              \*(AqGalleryFee\*(Aq => \*(Aq0.25\*(Aq,
\&                              \*(AqAuctionLengthFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqProPackBundleFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqBorderFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqFeaturedFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqSchedulingFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqHighLightFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqFixedPriceDurationFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqPhotoDisplayFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqListingFee\*(Aq => \*(Aq0.55\*(Aq,
\&                              \*(AqBuyItNowFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqPhotoFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqGiftIconFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqSubtitleFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqInsertionFee\*(Aq => \*(Aq0.30\*(Aq,
\&                              \*(AqListingDesignerFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqBoldFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqReserveFee\*(Aq => \*(Aq0.00\*(Aq,
\&                              \*(AqCategoryFeaturedFee\*(Aq => \*(Aq0.00\*(Aq
\&                            },
\&                    \*(AqStartTime\*(Aq => \*(Aq2005\-08\-30 04:50:47\*(Aq,
\&                    \*(AqEndTime\*(Aq => \*(Aq2005\-09\-06 04:50:47\*(Aq
\&                  },
\&          \*(AqEBayTime\*(Aq => \*(Aq2005\-08\-30 04:50:47\*(Aq
\&        };
.Ve
.PP
See an alternative example of submitting an item using New Schema, in script
ebay\-add\-item.pl.
.PP
If an error in parsing XML occurs, result will be simply the string
that is the text representation of the answer.
.SH EXPORT
.IX Header "EXPORT"
new \-\- creates eBay API. Requires supplying of credentials:
DeveloperKey, ApplicationKey, CertificateKey, Token. Net::eBay will
not be created until these keys and the token are supplied.
.PP
Get them by registering at http://developer.ebay.com and self
certifying. Celf certifying is a trivial process of solemnly swearing
that you are ready to use their API.
.PP
The SiteLevel parameter is also mandatory and can be either 'prod' or
\&'dev'. prod means to use their production site (being charged real
money for listings, etc), and dev means to use eBay sandbox
http://sandbox.ebay.com/.
.PP
Parameters can be supplied in two ways:
.PP
1) As a hash table
.PP
2) As a filename (only argument). If filename and hash are missing, Net::eBay
makes an effort to fine a ebay.ini file by looking for: \f(CW$ENV\fR{EBAY_INI_FILE}, ./ebay.ini,
~/.ebay.ini . That's the default constructor.
.PP
See SAMPLE.ebay.ini in this distribution.
.SH "Defaults and XML API Versions"
.IX Header "Defaults and XML API Versions"
This module, by default, is using the "Legacy XML API" that is set to
expire in the summer of 2006. That default will change as the legacy
API actually expires.
.PP
XML API Schema is set by calling setDefaults( { ... } )
.PP
See its documentation below.
.SH "ebay.ini FILE"
.IX Header "ebay.ini FILE"
ebay.ini is a file that lists ebay access keys and whether this is for
accessing eBay production site or its developers' sandbox. Example of
the file (see SAMPLE.ebay.ini):
.PP
.Vb 2
\& # dev or prod
\& SiteLevel=prod
\&
\& # your developer key
\& DeveloperKey=KLJHAKLJHLKJHLKJH
\&
\& # your application key
\& ApplicationKey=LJKGHKLJGKJHG
\&
\& # your certificate key
\& CertificateKey=SUYTYWTKWTYIUYTWIUTY
\&
\& # your token (a very BIG string)
\& Token=JKHGHJGJHGKJHGKJHGkluhsdihdsriuhfwe87yr8wehIEWH9O78YWERF90HF9UHJESIPHJFV94Y4089734Y
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS new
.IX Subsection "new"
.SS setDefaults
.IX Subsection "setDefaults"
Sets application defaults, most importantly the XML API version to be used.
.PP
Takes a hash argument.
.PP
The following defaults can be set:
.PP
* API \-\- sets eBay API version. Only two values are supported: '1' means
Legacy API set to expire in the summer of 2006, '2' means the API that
supersedes it. All other values are illegal.
.PP
* debug \-\- if debug is set to true, prints a lot of debugging information, XML sent and received etc.
.PP
* siteid \-\- sets site id
.PP
* compatibility \-\- "compatibility level" with eBay. Set to a sensible default.
.PP
* timeout \-\- sets default query timeout, default is 50 seconds
.PP
* retries \-\- sets the number of times a failed request should be retried.  Defaults to 2 according to <http://xrl.us/bk7vb>  This only retries requests where eBay is to blame for the failure.  Faulty API requests are not retried.
.PP
Example:
.PP
.Vb 2
\&  $eBay\->setDefaults( { API => 2 } ); # use new eBay API
\&  $eBay\->setDefaults( { API => 2, debug => 1 } ); # use new eBay API and also debug all calls
.Ve
.SS submitRequest
.IX Subsection "submitRequest"
Sends a request to eBay. Takes a name of the API call and a hash of arguments.
The arguments can be hashes of hashes and are properly translated into nested
XML structures.
.PP
Example:
.PP
.Vb 5
\&  TopLevel => {
\&                Item1 => \*(Aqhello\*(Aq,
\&                Item2 => \*(Aqworld\*(Aq
\&                Item3 => [\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq]
\&              }
.Ve
.PP
it would be translated to
.PP
.Vb 6
\&  <TopLevel>
\&    <Item1>hello</Item1>
\&    <Item2>world</Item2>
\&    <Item3>foo</Item3>
\&    <Item3>bar</Item3>
\&  </TopLevel>
.Ve
.PP
If an argument has XML attributes and should be formatted like this:
.PP
.Vb 1
\& <TestAttribute currencyID="USD" >abcd</TestAttribute>
.Ve
.PP
(note "currencyID")
.PP
your argument should be
.PP
.Vb 1
\& TestAttribute => { _attributes => { currencyID => \*(AqUSD\*(Aq }, _value => \*(Aqabcd\*(Aq ),
.Ve
.PP
Depending on the default API set by setDefaults (see above), XML
produced will be compatible with the eBay API version selected by the
user.
.SS officialTime
.IX Subsection "officialTime"
Returns eBay official time
.SS "UTF8 Internal ONLY function"
.IX Subsection "UTF8 Internal ONLY function"
.SS "hash2xml Internal ONLY function"
.IX Subsection "hash2xml Internal ONLY function"
.SS "submitRequestGetText Internal ONLY function"
.IX Subsection "submitRequestGetText Internal ONLY function"
.SS "verifyAndPrint Internal ONLY function"
.IX Subsection "verifyAndPrint Internal ONLY function"
.SH AUTHOR
.IX Header "AUTHOR"
Igor Chudov, \f(CW\*(C`<ichudov@algebra.com>\*(C'\fR
.SH BUGS
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-net\-ebay@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net\-eBay>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2005 Igor Chudov, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.