Wednesday, April 18, 2012

Invoicing with TradeShift API, part 1

I am happy to present the first part of blog post series  dedicated to creation of invoices with TradeShift REST API.

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 Exploring the Tradeshift REST API in TradeShift Developer Blog I encourage you to take a break and read it.

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.

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.

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 https://sandbox.tradeshift.com/network/search
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:




Next thing you will need is your own company tenant id. It can be obtained by installing and running  API Access to Own Account  application.

We have everything we need now, let’s start The REST API Explorer and create our first invoice with TradeShift API.

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,
Consumer key, Consumer secret, Token and Token secret values (they can be obtained from API Access to Own Account) you have to make sure that 3-legged option is checked, Method is set to PUT and request URL is according to Tradeshift REST API Detail Documentation set to something like this:

https://api-sandbox.tradeshift.com/tradeshift/rest/external/documents/FA4FE9A7-313B-49E5-894A-5BA2F690EAA3?documentProfileId=tradeshift.invoice.1.0&draft=true

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 supported document profiles.

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.

Let’s start with format part:

<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">
 <cbc:UBLVersionID>2.0</cbc:UBLVersionID>
 <cbc:CustomizationID>urn:tradeshift.com:ubl-2.0-customizations:2010-06</cbc:CustomizationID>
 <cbc:ProfileID schemeID="CWA 16073:2010" schemeAgencyID="CEN/ISSS WS/BII" schemeVersionID="1">urn:www.cenbii.eu:profile:bii04:ver1.0</cbc:ProfileID>
</Invoice>


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.

It’s time to add some data. For our document we most likely can supply some identification and here is how: with  <cbc:ID /> tag. We can leave it empty though but in fact we must include the tag.

We must supply the date when document is created:

<cbc:IssueDate>2012-04-18</cbc:IssueDate>

We must supply invoice currency, for example US dollars:
<cbc:DocumentCurrencyCode>USD</cbc:DocumentCurrencyCode>

Now for this document to be useful we must include supplier (that’s us) and customer (test company). Code for supplier follows:

 <cac:AccountingSupplierParty>
   <cac:Party>
     <cac:PartyIdentification>
       <cbc:ID schemeID="TS:ID">your tenant id</cbc:ID>
     </cac:PartyIdentification>
   </cac:Party>
 </cac:AccountingSupplierParty>


Please note, that schemeID attribute is set to “TS:ID” which means that the supplied identity is TradeShift tenant ID.


Customer reference will look like this:

 <cac:AccountingCustomerParty>
   <cac:Party>
     <cac:PartyIdentification>
       <cbc:ID schemeID="TS:ID">test company tenant id</cbc:ID>
     </cac:PartyIdentification>
   </cac:Party>
 </cac:AccountingCustomerParty>


And again schemeID=“TS:ID” means that we mean a company from TradeShift network which we are connected to.

Now comes invoice total. Obviously the value is calculated from invoice lines but should be included in the document before any invoice lines:

<cac:LegalMonetaryTotal>
   <cbc:LineExtensionAmount currencyID="USD">0</cbc:LineExtensionAmount>
   <cbc:PayableAmount currencyID="USD">0</cbc:PayableAmount>
</cac:LegalMonetaryTotal>


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.

<cac:InvoiceLine>
   <cbc:ID></cbc:ID>
   <cbc:InvoicedQuantity unitCode="HUR">3</cbc:InvoicedQuantity>
   <cbc:LineExtensionAmount currencyID="USD">75</cbc:LineExtensionAmount>
   <cac:TaxTotal>
     <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount>
     <cac:TaxSubtotal>
       <cbc:TaxableAmount currencyID="USD">75</cbc:TaxableAmount>
       <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount>
       <cac:TaxCategory>
         <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID>
         <cbc:Percent>0</cbc:Percent>
         <cac:TaxScheme>
           <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID>
           <cbc:Name>VAT</cbc:Name>
         </cac:TaxScheme>
       </cac:TaxCategory>
     </cac:TaxSubtotal>
   </cac:TaxTotal>
   <cac:Item>
     <cbc:Description>item 2</cbc:Description>
     <cbc:Name>item 2</cbc:Name>
   </cac:Item>
   <cac:Price>
     <cbc:PriceAmount currencyID="USD">75</cbc:PriceAmount>
     <cbc:BaseQuantity>1</cbc:BaseQuantity>
     <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate>
   </cac:Price>
 </cac:InvoiceLine>

 
That’s the biggest chunk of data so far wrapped in huge amount of formatting details. Let’s go over it one by one.

We must include item line identity tag, though we can leave it empty: <cbc:ID></cbc:ID>

To specify quantity and unit we need to include
<cbc:InvoicedQuantity unitCode="HUR">3</cbc:InvoicedQuantity>
where unitCode specifies unit of measure. For the list of valid codes see
Unit Of Measure Codes.

To specify total line amount excluding taxes we need to include
<cbc:LineExtensionAmount currencyID="USD">75</cbc:LineExtensionAmount>

It’s not necessary to include taxation details but let’s do it anyway because it gives me opportunity to share some important information:

<cac:TaxTotal>
     <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount>
     <cac:TaxSubtotal>
       <cbc:TaxableAmount currencyID="USD">75</cbc:TaxableAmount>
       <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount>
       <cac:TaxCategory>
         <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID>
         <cbc:Percent>0</cbc:Percent>
         <cac:TaxScheme>
           <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID>
           <cbc:Name>VAT</cbc:Name>
         </cac:TaxScheme>
       </cac:TaxCategory>
     </cac:TaxSubtotal>
   </cac:TaxTotal>


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.

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.
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 5305  Duty or tax or fee category code 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 UN/EDIFACT Data Element 5305. I am sure you have got the idea.
The obvious question though is how do we know which code list we should use? I invite you to check PEPPOL e-Invoicing profile. 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.

So this is basically it. The resulting sample document will look like this:

<?xml version="1.0" encoding="utf-8"?>
<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">
 <cbc:UBLVersionID>2.0</cbc:UBLVersionID>
 <cbc:CustomizationID>urn:tradeshift.com:ubl-2.0-customizations:2010-06</cbc:CustomizationID>
 <cbc:ProfileID schemeID="CWA 16073:2010" schemeAgencyID="CEN/ISSS WS/BII" schemeVersionID="1">urn:www.cenbii.eu:profile:bii04:ver1.0</cbc:ProfileID>
 <cbc:ID />
 <cbc:IssueDate>2012-04-18</cbc:IssueDate>
 <cbc:DocumentCurrencyCode>USD</cbc:DocumentCurrencyCode>
 <cac:AccountingSupplierParty>
   <cac:Party>
     <cac:PartyIdentification>
       <cbc:ID schemeID="TS:ID">your tenant ID</cbc:ID>
     </cac:PartyIdentification>
   </cac:Party>
 </cac:AccountingSupplierParty>
 <cac:AccountingCustomerParty>
   <cac:Party>
     <cac:PartyIdentification>
       <cbc:ID schemeID="TS:ID">your customer tenant ID</cbc:ID>
     </cac:PartyIdentification>
   </cac:Party>
 </cac:AccountingCustomerParty>
 <cac:LegalMonetaryTotal>
   <cbc:LineExtensionAmount currencyID="RUB">0</cbc:LineExtensionAmount>
   <cbc:PayableAmount currencyID="RUB">0</cbc:PayableAmount>
 </cac:LegalMonetaryTotal>
 <cac:InvoiceLine>
    <cbc:ID></cbc:ID>
   <cbc:InvoicedQuantity unitCode="HUR">3</cbc:InvoicedQuantity>
   <cbc:LineExtensionAmount currencyID="RUB">75</cbc:LineExtensionAmount>
   <cac:TaxTotal>
     <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount>
     <cac:TaxSubtotal>
       <cbc:TaxableAmount currencyID="USD">75</cbc:TaxableAmount>
       <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount>
       <cac:TaxCategory>
         <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID>
         <cbc:Percent>0</cbc:Percent>
         <cac:TaxScheme>
           <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID>
           <cbc:Name>VAT</cbc:Name>
         </cac:TaxScheme>
       </cac:TaxCategory>
     </cac:TaxSubtotal>
   </cac:TaxTotal>
   <cac:Item>
     <cbc:Description>item 2</cbc:Description>
     <cbc:Name>item 2</cbc:Name>
   </cac:Item>
   <cac:Price>
     <cbc:PriceAmount currencyID="USD">75</cbc:PriceAmount>
     <cbc:BaseQuantity>1</cbc:BaseQuantity>
     <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate>
   </cac:Price>
 </cac:InvoiceLine>
 <cac:InvoiceLine>
   <cbc:ID></cbc:ID>
   <cbc:InvoicedQuantity unitCode="HUR">2</cbc:InvoicedQuantity>
   <cbc:LineExtensionAmount currencyID="USD">200</cbc:LineExtensionAmount>
   <cac:TaxTotal>
     <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount>
     <cac:TaxSubtotal>
       <cbc:TaxableAmount currencyID="USD">200</cbc:TaxableAmount>
       <cbc:TaxAmount currencyID="USD">0</cbc:TaxAmount>
       <cac:TaxCategory>
         <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6" schemeVersionID="D08B">Z</cbc:ID>
         <cbc:Percent>0</cbc:Percent>
         <cac:TaxScheme>
           <cbc:ID schemeID="UN/ECE 5153 Subset" schemeAgencyID="6" schemeVersionID="D08B">OTH</cbc:ID>
           <cbc:Name>VAT</cbc:Name>
         </cac:TaxScheme>
       </cac:TaxCategory>
     </cac:TaxSubtotal>
   </cac:TaxTotal>
   <cac:Item>
     <cbc:Description>item 1</cbc:Description>
     <cbc:Name>item 1</cbc:Name>
   </cac:Item>
   <cac:Price>
     <cbc:PriceAmount currencyID="USD">200</cbc:PriceAmount>
     <cbc:BaseQuantity>1</cbc:BaseQuantity>
     <cbc:OrderableUnitFactorRate>1</cbc:OrderableUnitFactorRate>
   </cac:Price>
 </cac:InvoiceLine>
</Invoice>


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.

3 comments:

  1. If you are looking for an online invoicing software with beautiful invoice templates, you should give Clouodbooks a shot. Once you set it up, it'll automatically send the payment reminders and recurring invoices. You can send personalized notifications to your customers and even receive online payments. Sign up for free and check out if it fits your needs - https://www.clouodbooksapp.com Plans starts from $2 per month. Give it a Try!

    ReplyDelete
  2. Thank you again for all the knowledge you distribute,Good post. I was very interested in the article, it's quite inspiring I should admit. expense management software

    ReplyDelete
  3. Thank you for this explanation. Very helpful to me.

    ReplyDelete