Sunday, April 22, 2012

Invoicing with TradeShift API, part 2

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:
  1. 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 UBL 2.0 Invoice Schema and PEPPOL e-Invoicing profile  should be kept handy because these are the primary sources of information.
  2. 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 default lists of codes.  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  PEPPOL e-Invoicing profile in chapter 5: Semantic Interoperability.
Now lets grab our indispensable tool The REST API Explorer 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.

So here is what we need to specify our new connection: company name, obviously, e-mail address and postal address. Let's consult UBL 2.0 Invoice Schema and it's not very hard to figure out that our AccountingCustomerParty will look like this:

<cac:Party>
      <cac:PartyName><cbc:Name>Your New Customer Name</cbc:Name></cac:PartyName>
      <cac:PostalAddress>
        <cbc:StreetName>Your New New Customer Street</cbc:StreetName>
        <cbc:BuildingNumber> Your New New Customer Building Number</cbc:BuildingNumber>
        <cbc:CityName>Customer City Name</cbc:CityName>
        <cbc:PostalZone>Customer Postal Code</cbc:PostalZone>
        <cac:Country>
          <cbc:IdentificationCode>Customer Country Code</cbc:IdentificationCode>
        </cac:Country>
      </cac:PostalAddress>
       <cac:Contact>
        <cbc:ElectronicMail>Your Customer E-Mail</cbc:ElectronicMail>
      </cac:Contact>
</cac:Party>

So just grab your XML from previous article and put our customer in the proper place:

<?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:PartyName><cbc:Name>Your New Customer Name</cbc:Name></cac:PartyName>
      <cac:PostalAddress>
        <cbc:StreetName>Your New New Customer Street</cbc:StreetName>
        <cbc:BuildingNumber> Your New New Customer Building Number</cbc:BuildingNumber>
        <cbc:CityName>Customer City Name</cbc:CityName>
        <cbc:PostalZone>Customer Postal Code</cbc:PostalZone>
        <cac:Country>
          <cbc:IdentificationCode>Customer Country Code</cbc:IdentificationCode>
        </cac:Country>
      </cac:PostalAddress>
       <cac:Contact>
        <cbc:ElectronicMail>Your Customer E-Mail</cbc:ElectronicMail>
      </cac:Contact>
</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>

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.

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.

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.


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.