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.