tag:blogger.com,1999:blog-63339252680053894772024-03-19T14:10:50.013+03:00In For The CloudSerge Afanasyevhttp://www.blogger.com/profile/10885684401183410143noreply@blogger.comBlogger4125tag:blogger.com,1999:blog-6333925268005389477.post-83191592105105299692012-08-21T16:05:00.001+04:002012-08-21T16:05:39.425+04:00TradeShift REST API Explorer with OAuth LiteWhile I've been exploring TradeShift's API I actually fell flat when I needed to do actual getting/posting stuff with technology I am most familiar with: Microsoft .NET Framework. I am sure there are lot's of folks using this technology that would like to benefit from TadeShift doing things: be able to integrate with this awesome network.<br />
Unfortunately I couldn't find any comprehensible/maintainable approach to use OAuth authentication with .NET so I had to do one myself like it happens often enough with some new cool stuff emerging out there.
I've shared what I've done through CodePlex and you can feel free to <a href="http://oauthlite.codeplex.com/SourceControl/list/changesets">download the source code</a>.<br />
<br />
The library is extremely easy to use. It provides an OAuthClient class derived from WebClient and you can use in the same manner you use WebClient.<br />
<br />
<br />
<code>
var oauthSecret = new OAuthSecret ("ConsumerKey", "ConsumerSecret", "Token", "TokenSecret"); </code><br />
<code>var oauth = new OAuthClient(oauthSecret); </code><br />
<code>oauth.Headers["Accept"] = "text/xml";</code><br />
<code>oauth.Headers["Accept-Encoding"] = "utf-8";</code><br />
<code>oauth.Headers["Content-Type"] = "text/xml";</code><br />
<code>oauth.Headers["User-Agent"] = "DOTNET API Explorer/1.0";</code><br />
<code>oauth.Headers["X-Tradeshift-TenantId"] = "Your Tradeshift Tenant Id";</code><br />
<code><br /></code>
<code>//use this method to GET what you want from TradeShift</code><br />
<code>var data = oauth.DownloadData("https://api-sandbox.tradeshift.com/tradeshift/rest/external/network/connections");</code><br />
<code><br /></code>
<code></code><br />
<code>//use this method to upload content to TradeShift</code>
<br />
<code>var upload = new byte [0]; </code><br />
<code>data = oauth.UploadData("", "PUT", upload);</code><br />
<br />
Now you have two methods to manipulate your web resources. To GET you need to use DownloadData method and for everything else you can use UploadData.<br />
To find out what are your values for consumer key, consumer secret, token and token secret you need to install <a href="https://sandbox.tradeshift.com/apps/view/Tradeshift.APIAccessToOwnAccount">API Access to own Account</a> application.<br />
<br />
I've also developed a simple TradeShift API Explorer application which is very similar to the Java application on TradeShift site ( check Exploring the <a href="http://developer.tradeshift.com/blog/exploring-the-tradeshift-rest-api/">Tradeshift REST API</a> article). You can install .NET version of API Explorer <a href="http://oauthlite.codeplex.com/releases/view/93127">here</a>.<br />
<br />
Happy coding!<br />
<br />Serge Afanasyevhttp://www.blogger.com/profile/10885684401183410143noreply@blogger.com0tag:blogger.com,1999:blog-6333925268005389477.post-14116352317708713632012-08-21T16:00:00.000+04:002013-05-20T13:18:02.509+04:00Thank you, TradeShift<span style="font-family: Helvetica Neue, Arial, Helvetica, sans-serif;">Quite a time has passed since my last post but I am sure that the coming season will bring us more challenges and therefore more interesting topics to discuss. Anyway, I anticipate it to be a very active season.</span><br />
<div>
<span style="font-family: Helvetica Neue, Arial, Helvetica, sans-serif;">And first of all I'd like to thank TradeShift for their attention and appreciation of my efforts.</span></div>
<div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://www.facebook.com/photo.php?fbid=380641565311044&set=a.170452939663242.32676.170323493009520&type=3&theater"><img border="0" height="240" src="https://fbcdn-sphotos-b-a.akamaihd.net/hphotos-ak-prn1/558513_380641565311044_1955610675_n.jpg" width="320" /></a></div>
<br /></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div>
<span style="font-family: Helvetica Neue, Arial, Helvetica, sans-serif;"><br /></span></div>
<div>
<span style="font-family: Helvetica Neue, Arial, Helvetica, sans-serif;">Now I use it every morning and it always reminds me that there are many things TradeShift that need my attention. Thank you Troels Feodor Nielsen and TradeShift team. It was an honor.</span><br />
<div>
<br />
<div>
<br /></div>
<div>
<br /></div>
</div>
</div>
Serge Afanasyevhttp://www.blogger.com/profile/10885684401183410143noreply@blogger.com0tag:blogger.com,1999:blog-6333925268005389477.post-14949886710197533342012-04-22T20:20:00.000+04:002012-04-24T11:18:55.088+04:00Invoicing with TradeShift API, part 2<div dir="ltr" style="text-align: left;" trbidi="on">
This time I am going to cover the subject of creating invoice for a customer that's not yet in your network. But first let's review what we learned last time. For me it was very important not to let myself be overwhelmed with huge amount of details that come with UBL format:<br />
<ol style="text-align: left;">
<li>UBL is just a format, like SOAP, which envelopes your data, so there is nothing to be afraid of though some additional digging is very helpful. I suggest that <a href="http://www.schemacentral.com/sc/ubl20/e-ns19_Invoice.html"><span style="color: blue;">UBL 2.0 Invoice Schema</span></a> and <a href="http://www.peppol.eu/about_peppol/results/einvoicing/d5.3-specification-of-architecture-and-components-enabling-cross-border-einvoicing/PEPPOL%20D5_3%20-%20Attachment%20A%20Profile%204a.pdf/view"><span style="color: blue;">PEPPOL e-Invoicing profile</span></a>
<span style="font-family: 'Times New Roman', serif; line-height: 16px; text-align: -webkit-auto;">should be kept handy because</span> these are the primary sources of information.</li>
<li>Besides XML validity we have to keep in mind the compatibility of invoice vocabulary, i.e. values that can be supplied in XML entities such as standard currency codes, units of measure, taxation details. These values come from vocabulary lists supported by UBL by default and can be viewed in <a href="http://docs.oasis-open.org/ubl/cs-UBL-2.0/cl/gc/default/"><span style="color: blue;">default lists of codes.</span></a> Particular e-invoice exchange implementation such as PEPPOL on top of which TradeShift is functioning can specify it's own vocabulary preferences as stated for example in
<a href="http://www.peppol.eu/about_peppol/results/einvoicing/d5.3-specification-of-architecture-and-components-enabling-cross-border-einvoicing/PEPPOL%20D5_3%20-%20Attachment%20A%20Profile%204a.pdf/view"><span style="color: blue;">PEPPOL e-Invoicing profile</span></a> in chapter 5: Semantic Interoperability.</li>
</ol>
<div>
Now lets grab our indispensable tool <a href="http://developer.tradeshift.com/wp-content/uploads/explorer.jnlp"><span style="color: blue;">The REST API Explorer</span></a> and do some finger work. Our goal now is to create an invoice for our new customer and eventually create a new network connection. There is however a constraint: the connection we are creating in this manner obviously will not be part of TradeShift network and as a result it can't use e-invoice transportation framework enjoyed by regular TradeShift connections. You will be able to send invoices to this connection only by e-mail or snail-mail.</div>
<div>
<br />
So here is what we need to specify our new connection: company name, obviously, e-mail address and postal address. Let's consult <a href="http://www.schemacentral.com/sc/ubl20/e-ns19_Invoice.html"><span style="color: blue;">UBL 2.0 Invoice Schema</span></a> and it's not very hard to figure out that our AccountingCustomerParty will look like this:</div>
<div>
<br /></div>
<div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b><cac:Party><span class="Apple-tab-span" style="white-space: pre;"> </span></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cac:PartyName><cbc:Name>Your New Customer Name</cbc:Name></cac:PartyName></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cac:PostalAddress></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:StreetName>Your New New Customer Street</cbc:StreetName></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:BuildingNumber>
Your New New Customer Building Number</cbc:BuildingNumber></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:CityName>Customer City Name</cbc:CityName></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:PostalZone>Customer Postal Code</cbc:PostalZone></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cac:Country></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:IdentificationCode>Customer Country Code</cbc:IdentificationCode></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> </cac:Country></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> </cac:PostalAddress></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cac:Contact></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:ElectronicMail>Your Customer E-Mail</cbc:ElectronicMail></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> </cac:Contact></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b></cac:Party></b></span></div>
</div>
<div>
<br /></div>
<div>
So just grab your XML from previous article and put our customer in the proper place:</div>
<div>
<br /></div>
<div>
<b style="background-color: white; color: #38761d; font-family: 'Courier New', Courier, monospace; line-height: 18px; text-align: -webkit-auto;"><span style="vertical-align: baseline; white-space: pre-wrap;"><?xml version="1.0" encoding="utf-8"?></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"><Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:UBLVersionID>2.0</cbc:UBLVersionID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:CustomizationID>urn:tradeshift.com:ubl-2.0-customizations:2010-06</cbc:CustomizationID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:ProfileID schemeID="CWA 16073:2010" schemeAgencyID="CEN/ISSS WS/BII" schemeVersionID="1">urn:www.cenbii.eu:profile:bii04:ver1.0</cbc:ProfileID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID /></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:IssueDate>2012-04-18</cbc:IssueDate></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:DocumentCurrencyCode>USD</cbc:DocumentCurrencyCode></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:AccountingSupplierParty></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:Party></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:PartyIdentification></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="TS:ID">your tenant ID</cbc:ID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:PartyIdentification></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:Party></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:AccountingSupplierParty></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"></span><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:AccountingCustomerParty></span></b><br />
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b><cac:Party><span class="Apple-tab-span" style="white-space: pre;"> </span></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cac:PartyName><cbc:Name>Your New Customer Name</cbc:Name></cac:PartyName></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cac:PostalAddress></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:StreetName>Your New New Customer Street</cbc:StreetName></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:BuildingNumber> Your New New Customer Building Number</cbc:BuildingNumber></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:CityName>Customer City Name</cbc:CityName></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:PostalZone>Customer Postal Code</cbc:PostalZone></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cac:Country></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:IdentificationCode>Customer Country Code</cbc:IdentificationCode></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> </cac:Country></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> </cac:PostalAddress></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cac:Contact></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> <cbc:ElectronicMail>Your Customer E-Mail</cbc:ElectronicMail></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b> </cac:Contact></b></span></div>
<div>
<span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b></cac:Party></b></span></div>
<b style="background-color: white; color: #38761d; font-family: 'Courier New', Courier, monospace; line-height: 18px; text-align: -webkit-auto;"><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:AccountingCustomerParty></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"></span><span style="vertical-align: baseline; white-space: pre-wrap;"></span><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:LegalMonetaryTotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:LineExtensionAmount currencyID="RUB">0</cbc:LineExtensionAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:PayableAmount currencyID="RUB">0</cbc:PayableAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:LegalMonetaryTotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"></span><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:InvoiceLine></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID></cbc:ID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:InvoicedQuantity unitCode="HUR">3</cbc:InvoicedQuantity></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:LineExtensionAmount currencyID="RUB">75</cbc:LineExtensionAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxTotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxSubtotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxableAmount currencyID="USD">75</cbc:TaxableAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxCategory></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:Percent>0</cbc:Percent></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxScheme></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>VAT</cbc:Name></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxScheme></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxCategory></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxSubtotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxTotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:Item></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:Description>item 2</cbc:Description></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>item 2</cbc:Name></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:Item></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:Price></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:PriceAmount currencyID="USD">75</cbc:PriceAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:BaseQuantity>1</cbc:BaseQuantity></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:Price></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:InvoiceLine></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:InvoiceLine></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID></cbc:ID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:InvoicedQuantity unitCode="HUR">2</cbc:InvoicedQuantity></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:LineExtensionAmount currencyID="USD">200</cbc:LineExtensionAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxTotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxSubtotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxableAmount currencyID="USD">200</cbc:TaxableAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxCategory></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:Percent>0</cbc:Percent></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxScheme></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>VAT</cbc:Name></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxScheme></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxCategory></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxSubtotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxTotal></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:Item></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:Description>item 1</cbc:Description></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>item 1</cbc:Name></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:Item></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cac:Price></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:PriceAmount currencyID="USD">200</cbc:PriceAmount></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:BaseQuantity>1</cbc:BaseQuantity></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:Price></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"> </cac:InvoiceLine></span><br /><span style="vertical-align: baseline; white-space: pre-wrap;"></span><span style="vertical-align: baseline; white-space: pre-wrap;"></Invoice></span></b>
</div>
<div>
<br /></div>
<div>
Please note that it is always required to include taxation details (unlike stated in the previous article) in item lines because though you'll be able to create an invoice, TradeShift API will return the proper HTTP 204 response but you will not be able to access the draft without taxation details in TradeShift Documents view.</div>
<div>
<br /></div>
<div>
Another consequence of creating invoices in this manner is that a new connection will be created each time because we are not supplying distinctive customer identity, only name, e-mail and postal address. So I really doubt any practical use of creating connection within invoice not even for initial import purposes, because it's prone to errors, for example if in a bunch of invoices you might be importing to TradeShift there are invoices destined for the same customer you will have duplicate connections. It might be much better to exercise import in two stages: first import customers and note their TradeShift identities and then import invoices with corresponding TradeShift connections.<br />
<br />
Now that we have some basic understanding over what's going on and are tired (I guess) of doing lots of copy/paste gestures our next move logically would be to apply some computer technology to do this so as to give us a break.<br />
<br /></div>
<div>
<br /></div>
</div>Serge Afanasyevhttp://www.blogger.com/profile/10885684401183410143noreply@blogger.com1tag:blogger.com,1999:blog-6333925268005389477.post-8356330442396281632012-04-18T19:33:00.001+04:002012-04-22T20:06:07.754+04:00Invoicing with TradeShift API, part 1<div dir="ltr" style="text-align: left;" trbidi="on">
<div class="separator" style="clear: both; text-align: center;">
</div>
<span id="internal-source-marker_0.22966589941643178" style="text-align: -webkit-auto;"><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">I am happy to present the first part of blog post series dedicated to creation of invoices with TradeShift REST API.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">I assume that you are familiar with TradeShift REST API, Open Authentication, TradeShift API explorer and XML and the only little problem is: how the hell am I going to create an actual invoice? If you have not yet read </span><a href="http://developer.tradeshift.com/blog/exploring-the-tradeshift-rest-api/" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Exploring the Tradeshift REST API</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"> in </span><a href="http://developer.tradeshift.com/blog/" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">TradeShift Developer Blog</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"> I encourage you to take a break and read it.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">For this very first post on the matter I have chosen a very simple example: let’s assume that you already have a connection in your network for which you want to create an invoice and you are able to create it manually through web application user interface.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Please note that I will be using TradeShift sandbox environment and I encourage you to do the same until you’re confident enough of what you are doing. For this very example I recommend to add a test company to your network if you haven’t done it yet.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">When you have someone in your network you can check if you are able to create an invoice for this company. Just to remind you how to check it: go to </span><a href="https://sandbox.tradeshift.com/network/search" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">https://sandbox.tradeshift.com/network/search</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">and click Create invoice link. Invoice edit form should appear and that means that your network connection is valid and you can send invoices to this company. We will need test company id that identifies it in TradeShift network. The simplest way to obtain this id is from link to this company in your network view:</span><br /><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjIwVWuseLBGGQMA6ogKZAleIDDDD30wusDmTJu5o8jqz1S_Ik28zAGO8Tk0VHFAZNjRpIPVSsoLH01yTVrEl4wfDXwvm5JKbc-1lOi-BdMdOfU3mYu3Am2OHncprOMMs168QwPe8o1LQVZ/s1600/Network2.png" imageanchor="1" style="font-weight: bold; margin-left: 1em; margin-right: 1em;"><img border="0" height="179" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjIwVWuseLBGGQMA6ogKZAleIDDDD30wusDmTJu5o8jqz1S_Ik28zAGO8Tk0VHFAZNjRpIPVSsoLH01yTVrEl4wfDXwvm5JKbc-1lOi-BdMdOfU3mYu3Am2OHncprOMMs168QwPe8o1LQVZ/s320/Network2.png" width="320" /></a> <br /><br /><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Next thing you will need is your own company tenant id. It can be obtained by installing and running </span><a href="https://sandbox.tradeshift.com/apps/view/Tradeshift.APIAccessToOwnAccount" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">API Access to Own Account</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"> application.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">We have everything we need now, let’s start </span><a href="http://developer.tradeshift.com/wp-content/uploads/explorer.jnlp" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">The REST API Explorer</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"> and create our first invoice with TradeShift API.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">User interface is pretty straightforward and the only thing that is not quite obvious is the request content. Just to remind you though besides filling in your credentials like Company account ID,</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Consumer key, Consumer secret, Token and Token secret values (they can be obtained from </span><a href="https://sandbox.tradeshift.com/apps/view/Tradeshift.APIAccessToOwnAccount" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">API Access to Own Account</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">) you have to make sure that 3-legged option is checked, Method is set to PUT and request URL is according to </span><a href="https://api.tradeshift.com/tradeshift/rest/external/doc" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Tradeshift REST API Detail Documentation</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"> set to something like this:</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">https://api-sandbox.tradeshift.com/tradeshift/rest/external/documents/FA4FE9A7-313B-49E5-894A-5BA2F690EAA3?documentProfileId=tradeshift.invoice.1.0&draft=true</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">where complicated “[a-zA-Z0-9]” part is UUID of document manipulation request and documentProfileId=tradeshift.invoice.1.0 is the name of XML/UBL flavor which is going to be used for document validation and processing. The list of valid options can be seen in </span><a href="https://api.tradeshift.com/tradeshift/rest/external/info/documentprofiles" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">supported document profiles</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">. </span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Now on with the request. For the sake of simplicity it’s very convenient to think that XML document consists of two parts: format and data. By format part I mean all the necessary XML declarations and side steps that should be included to produce a valid XML/UBL document and by data part I understand entities we need to include to produce useful document: supplier, customer, line items etc.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Let’s start with format part:</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"><Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:UBLVersionID>2.0</cbc:UBLVersionID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:CustomizationID>urn:tradeshift.com:ubl-2.0-customizations:2010-06</cbc:CustomizationID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ProfileID schemeID="CWA 16073:2010" schemeAgencyID="CEN/ISSS WS/BII" schemeVersionID="1">urn:www.cenbii.eu:profile:bii04:ver1.0</cbc:ProfileID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"></Invoice></span></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">From application development standpoint there is nothing interesting here. Think about it as a SOAP envelope because intention is the same: to put actual data in context so that it can be processed according to some rules.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">It’s time to add some data. For our document we most likely can supply some identification and here is how: with </span><span style="color: #38761d; font-family: 'Courier New', Courier, monospace; font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"><b><cbc:ID /></b></span><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"> tag. We can leave it empty though but in fact we must include the tag.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">We must supply the date when document is created:</span></span><br />
<span style="text-align: -webkit-auto;"><span style="color: #38761d; font-family: 'Courier New', Courier, monospace; font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"><b><cbc:IssueDate>2012-04-18</cbc:IssueDate></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">We must supply invoice currency, for example US dollars:</span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace; font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"><b><cbc:DocumentCurrencyCode>USD</cbc:DocumentCurrencyCode></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Now for this document to be useful we must include supplier (that’s us) and customer (test company). Code for supplier follows:</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:AccountingSupplierParty></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Party></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:PartyIdentification></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="TS:ID">your tenant id</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:PartyIdentification></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Party></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:AccountingSupplierParty></span></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Please note, that schemeID attribute is set to “TS:ID” which means that the supplied identity is TradeShift tenant ID.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Customer reference will look like this:</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:AccountingCustomerParty></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Party></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:PartyIdentification></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="TS:ID">test company tenant id</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:PartyIdentification></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Party></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:AccountingCustomerParty></span></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">And again schemeID=“TS:ID” means that we mean a company from TradeShift network which we are connected to.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Now comes invoice total. Obviously the value is calculated from invoice lines but should be included in the document before any invoice lines:</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:LegalMonetaryTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:LineExtensionAmount currencyID="USD">0</cbc:LineExtensionAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:PayableAmount currencyID="USD">0</cbc:PayableAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"></cac:LegalMonetaryTotal></span></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Invoice line consists of the following attributes: line id which can be empty, quantity and unit, line total amount, taxation details and amount, item name, item description, item price per base quantity. </span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"><cac:InvoiceLine></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID></cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:InvoicedQuantity unitCode="HUR">3</cbc:InvoicedQuantity></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:LineExtensionAmount currencyID="USD">75</cbc:LineExtensionAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxSubtotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxableAmount currencyID="USD">75</cbc:TaxableAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxCategory></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Percent>0</cbc:Percent></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxScheme></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>VAT</cbc:Name></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxScheme></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxCategory></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxSubtotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Item></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Description>item 2</cbc:Description></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>item 2</cbc:Name></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Item></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Price></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:PriceAmount currencyID="USD">75</cbc:PriceAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:BaseQuantity>1</cbc:BaseQuantity></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Price></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:InvoiceLine></span></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"> </span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">That’s the biggest chunk of data so far wrapped in huge amount of formatting details. Let’s go over it one by one.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">We must include item line identity tag, though we can leave it empty: <cbc:ID></cbc:ID></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">To specify quantity and unit we need to include </span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace; font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"><b><cbc:InvoicedQuantity unitCode="HUR">3</cbc:InvoicedQuantity></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">where unitCode specifies unit of measure. For the list of valid codes see</span><br /><a href="http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/gc/cefact/UnitOfMeasureCode-2.0.gc" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Unit Of Measure Codes</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">To specify total line amount excluding taxes we need to include</span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace; font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"><b><cbc:LineExtensionAmount currencyID="USD">75</cbc:LineExtensionAmount></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">It’s not necessary to include taxation details but let’s do it anyway because it gives me opportunity to share some important information:</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxSubtotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxableAmount currencyID="USD">75</cbc:TaxableAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxCategory></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Percent>0</cbc:Percent></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxScheme></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>VAT</cbc:Name></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxScheme></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxCategory></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxSubtotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxTotal></span></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><b><span style="color: #cc0000;">Update: Actually it is necessary to include taxation details in item lines. Though TradeShift will return HTTP 204 response code meaning that invoice draft has been created, you will not be able to access it through TradeShift Documents view.</span></b><br /><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Probably you have already noted that identity tags often specify attributes like schemeID, schemeAgencyID, schemeVersionID. These are the attributes that specify vocabulary of invoice document. To put it simply, validation process needs to know how to validate certain values that cannot be checked with standard XML rules: well-formedness and XML schema compliance.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">For example, value for TaxCategory is Z. What can we make of it? Without reference to a vocabulary we can’t be sure what it’s all about. Why isn’t it A or B or whatever? But look in </span><a href="http://www.unece.org/trade/untdid/d07a/tred/tred5305.htm" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">5305 Duty or tax or fee category code</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"> and it’s perfectly clear that Z means “Zero rated goods”, exactly what we need since we do not wish to apply taxation to our invoice line. Just like OTH means “Other taxes” according to </span><a href="http://contrataciondelestado.es/codice/cl/2.0/TaxSchemeID.gc" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">UN/EDIFACT Data Element 5305</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">. I am sure you have got the idea.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">The obvious question though is how do we know which code list we should use? I invite you to check </span><a href="http://www.peppol.eu/about_peppol/results/einvoicing/d5.3-specification-of-architecture-and-components-enabling-cross-border-einvoicing/PEPPOL%20D5_3%20-%20Attachment%20A%20Profile%204a.pdf/view" style="font-weight: bold;"><span style="color: #1155cc; font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">PEPPOL e-Invoicing profile</span></a><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">. As a point of reference, it states “Invoice tax categories MUST be coded using UN/ECE 5305 code list” so that we know which code list to use in TaxCategory ID.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">So this is basically it. The resulting sample document will look like this:</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="color: #38761d; font-family: 'Courier New', Courier, monospace;"><b><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"><?xml version="1.0" encoding="utf-8"?></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"><Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:UBLVersionID>2.0</cbc:UBLVersionID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:CustomizationID>urn:tradeshift.com:ubl-2.0-customizations:2010-06</cbc:CustomizationID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ProfileID schemeID="CWA 16073:2010" schemeAgencyID="CEN/ISSS WS/BII" schemeVersionID="1">urn:www.cenbii.eu:profile:bii04:ver1.0</cbc:ProfileID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID /></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:IssueDate>2012-04-18</cbc:IssueDate></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:DocumentCurrencyCode>USD</cbc:DocumentCurrencyCode></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:AccountingSupplierParty></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Party></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:PartyIdentification></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="TS:ID">your tenant ID</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:PartyIdentification></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Party></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:AccountingSupplierParty></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"></span><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:AccountingCustomerParty></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Party></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:PartyIdentification></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="TS:ID">your customer tenant ID</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:PartyIdentification></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Party></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:AccountingCustomerParty></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"></span><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"></span><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:LegalMonetaryTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:LineExtensionAmount currencyID="RUB">0</cbc:LineExtensionAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:PayableAmount currencyID="RUB">0</cbc:PayableAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:LegalMonetaryTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"></span><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:InvoiceLine></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID></cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:InvoicedQuantity unitCode="HUR">3</cbc:InvoicedQuantity></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:LineExtensionAmount currencyID="RUB">75</cbc:LineExtensionAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxSubtotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxableAmount currencyID="USD">75</cbc:TaxableAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxCategory></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Percent>0</cbc:Percent></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxScheme></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>VAT</cbc:Name></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxScheme></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxCategory></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxSubtotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Item></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Description>item 2</cbc:Description></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>item 2</cbc:Name></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Item></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Price></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:PriceAmount currencyID="USD">75</cbc:PriceAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:BaseQuantity>1</cbc:BaseQuantity></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Price></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:InvoiceLine></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:InvoiceLine></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID></cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:InvoicedQuantity unitCode="HUR">2</cbc:InvoicedQuantity></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:LineExtensionAmount currencyID="USD">200</cbc:LineExtensionAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxSubtotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxableAmount currencyID="USD">200</cbc:TaxableAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxCategory></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Percent>0</cbc:Percent></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:TaxScheme></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>VAT</cbc:Name></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxScheme></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxCategory></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxSubtotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:TaxTotal></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Item></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Description>item 1</cbc:Description></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:Name>item 1</cbc:Name></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Item></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cac:Price></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:PriceAmount currencyID="USD">200</cbc:PriceAmount></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:BaseQuantity>1</cbc:BaseQuantity></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:Price></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"> </cac:InvoiceLine></span><br /><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"></span><span style="font-size: 15px; vertical-align: baseline; white-space: pre-wrap;"></Invoice></span></b></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;">Grab it and play with it using API Explorer, I am sure you’ll have lot’s of fun. Of course this topic is far from being complete, I’ve only detailed a simple case in which we are already connected to a customer in TradeShift framework. Next time I plan to go over the case of creating invoice for a new customer/connection. You are very welcome to send me your feedback along with suggestions what other API use cases you would like me to cover.</span><br /><span style="font-family: Arial; font-size: 15px; font-weight: normal; vertical-align: baseline; white-space: pre-wrap;"></span></span></div>Serge Afanasyevhttp://www.blogger.com/profile/10885684401183410143noreply@blogger.com3