Introducing the .NET wrapper for the Sage One Accounting API

A while back my accountant convinced me to move our accounting package to Sage One Online. Not only am I very happy with the change, I’m also intrigued with their API, which enables developers to integrate with Sage One and perform a wide range of tasks . As a result I’ve created an open source project with the aim to create a fully fledged .Net wrapper library for the Sage One Accounting API. The code is available on GitHub, so please feel free to grab your fork and start contributing! The project is still under active development and I’m adding features as I need them. As of writing, the library supports the following operation s:

  • Account
    • Get All
    • Get
    • Save (Create and Update)
    • Delete
    • Get with System Accounts
    • Get by Category
  • Customer
    • Get All
    • Get
    • Save (Create and Update)
    • Delete
  • Company
    • Get Current
  • Item
    • Get All
    • Get
    • Save (Create and Update)
    • Delete
  • Categories (Account, Asset, Bank Account, Customer, Item, Supplier)
    • Get All
    • Get
    • Save (Create and Update) excl. Account Categories
    • Delete
  • Sales Representative
    • Get All
    • Get
    • Save (Create and Update)
    • Delete
    • HasActivity
  • Supplier
    • Get All
    • Get
    • Save (Create and Update)
    • Delete
  • Tax Invoice
    • Get All
    • Get
    • Save (Create and Update)
    • Calculate

For example to get a list of customers on Sage One you’ll use the following C# code:

The Sage One API is pretty neat in the fact that it support OData queries out of the box. For example to find a customer with an e-mail address, you can simply pass in a filter parameter to the Get method:

In case you’re wondering how OData queries work, take a look at the following example. The load a customer by ID, you’ll use the following:

In order to create a new Sage One Customer, you’ll need to create a new instance of the Customer class, as illustrated below:

To delete a Sage One Customer, simply call the Delete method:

To create a Tax Invoice:

Lots more to come. Keep watching this space!

14 Comments

  • Wow thanks for this. Been struggling to integrate my jobcard project with this api. Do you perhaps have any docs on usage and installation? Is there a vb.net version? Awesome work!

  • Hi Werner,

    Glad you could use it!

    To install, simply download the library from GitHub, you can then build and reference the .dll or you can include the source project inside your Visual Studio solution and reference it from there. There is no documentation, refer to the Sage One API docs (https://accounting.sageone.co.za/api/1.1.1/Help)
    The C# code is a direct implementation of some(Not all) of the API methods.

    No VB.Net version unfortunately, however, you will still be able to reference the project from a VB.net project.

    Any questions, feel free to ask.

    • Hi Pieter

      So I got the got it up and running, but if possible, could you help with code for retrieving the current company. Also, when supplying the API key, do I include the {}?

      Thanks

  • Hi Werner,

    Have a look at CompanyTests.cs in the Tests project. In order to retrieve the current company you’ll use:

    var api = new ApiRequest(“Username”, “Password”, “Apikey”, 0);
    var currentCompany = api.CompanyRequest.Current();

    In VB:

    Dim api = New ApiRequest(“Username”, “Password”, “Apikey”, 0)
    Dim currentCompany = api.CompanyRequest.Current()

    Note, the ApiRequest constructor expects a companyId, in this instance its Ok to pass in a 0.

    Yes, you need to include the {} for the API Key.

  • Hi Pieter

    Thanks. I think I am getting the hang of it. Got the saving etc working. Just one thing I am struggling with, how to I get the JSON array that is returned when getting a list of customers into a listbox? When I bind the listbox’ datasource to the CustomerRequest I get the correct amount of records but the text shown is SageOneApi.Customers.Get

  • All Get Operations returns a PagingResponse object – which is essentially a .Net wrapper around the PagingResponse returned from the Sage API.

    In the customer case you’ll see the result returned from the following:

    var customers = api.CustomerRequest.Get();

    will return a PagingResponse<Customer>. Inside this object you’ll find a property called Results. This is a collection of the returned objects, which in this case is Customer.

    You’ll need to bind to the Results collection, not the PagingResponse.

    Hope this helps!

  • Hi Pieter

    Thanks got it all working. I had forgotten to make use of the Displaymember property for the listbox. Eish.

    Thanks for the help. Your wrapper is working a treat!

  • I definitely will. I’ll go over the code this weekend to wrap my brain around it, then try and add features where I can.

  • Hi Pieter

    So i’ve been using your warpper quite a bit and trying to add a couple of functions to the wrapper. But the one thing I cannot seem to get working is the Saving of a new invoice. Would it be possible for you to give me an example of inserting a new invoice.

    When inserting a test invoice the code runs through successfully, but the invoice is never inserted into sage. I’m sure i’m missing something small somewhere.

    Below is some messy code im using to try and get it working.

    Dim Username, Password, ApiKey As String
    Dim ComapnyId As Integer

    Username = “*************”
    Password = “*************”
    ApiKey = “{**************}”
    ComapnyId = *****

    Dim api As New ApiRequest(Username, Password, ApiKey, ComapnyId)
    Dim api2 As New ApiRequest(Username, Password, ApiKey, ComapnyId)
    Dim api3 As New ApiRequest(Username, Password, ApiKey, ComapnyId)
    Dim invoice As New TaxInvoice
    Dim customer = api2.CustomerRequest.Get(4162528)
    Dim salesrep = api3.SalesRepresentativeRequest.Get(42866)

    invoice.AllowOnlinePayment = True
    invoice.AmountDue = 0
    invoice.Customer = customer
    invoice.CustomerId = 4162528
    invoice.CustomerName = “Test co”
    invoice.Date = “2015-10-31T00:00:00Z”
    invoice.DeliveryAddress01 = “D1”
    invoice.DeliveryAddress02 = “D2”
    invoice.DeliveryAddress03 = “D3”
    invoice.DeliveryAddress04 = “D4”
    invoice.DeliveryAddress05 = “D5”
    invoice.Discount = 0
    invoice.DiscountPercentage = 0
    invoice.DocumentNumber = “INV00000003”
    invoice.DueDate = “2015-11-31T00:00:00Z”
    invoice.Exclusive = 0
    invoice.Inclusive = False
    invoice.Lines = Nothing
    invoice.PostalAddress01 = “P1”
    invoice.PostalAddress02 = “P2”
    invoice.PostalAddress03 = “P3”
    invoice.PostalAddress04 = “P4”
    invoice.PostalAddress05 = “P5”
    invoice.Reference = “Reference”
    invoice.SalesRepresentativeId = 42866
    invoice.SalesRepresentative = salesrep
    invoice.Tax = 0
    invoice.TaxReference = “4060242825”
    invoice.Total = 0
    invoice.StatusId = 0
    invoice.Printed = False
    invoice.Rounding = 0

    Try
    api.TaxInvoiceRequest.Save(invoice)
    MessageBox.Show(“Success”)
    Catch ex As Exception
    MessageBox.Show(ex.Message)
    End Try

  • Hi Werner,

    Make sure you include at least one line item when creating the Tax Invoice. I’ve updated the api library to allow you to retrieve Tax Types – this is needed to create an invoice item. The Invoice dates has also been changed from string to DateTime.

    The blog post has been updated with an example on how to create an invoice in c#.

    This is the minimum code(VB.Net) required to create an invoice (I’ve used a code converter, so might not be 100%):

    Public Sub Create()
    Dim api = New ApiRequest(Username, Password, Apikey, CompanyId)
    Dim customerId = 0
    Dim salesRepId = 0

    Dim itemId = 0
    Dim taxTypeId = 0

    Dim invoice As New TaxInvoice()
    Dim customer = api.CustomerRequest.[Get](customerId)
    Dim salesRep = api.SalesRepresentativeRequest.[Get](salesRepId)

    ‘ Must set both CustomerId and Customer in order to work
    invoice.CustomerId = customerId
    invoice.Customer = customer

    ‘ Must set both SalesRepresentativeId and SalesRepresentative in order to work
    invoice.SalesRepresentativeId = salesRepId
    invoice.SalesRepresentative = salesRep

    invoice.[Date] = DateTime.Now
    invoice.DueDate = New DateTime(2015, 12, 12)

    invoice.Lines = New List(Of CommercialDocumentLine)()

    ‘ This must be an item or account id
    ‘ Use TaxTypeRequest to get list of Tax Types
    ‘ 0=Item/1=Account
    Dim line1 = New CommercialDocumentLine() With {
    Key.SelectionId = itemId,
    Key.TaxTypeId = taxTypeId,
    Key.LineType = 0,
    Key.Quantity = 1,
    Key.UnitPriceExclusive = 390,
    Key.UnitPriceInclusive = 390,
    Key.DiscountPercentage = 0
    }

    invoice.Lines.Add(line1)

    Dim newTaxInvoice = api.TaxInvoiceRequest.Save(invoice)
    End Sub

    Hope this helps!

  • eish, thanx a bunch. Seems I screwed up with the lines.

    FYI: If anyone needs to get the doc number or any detail from an invoice they have just saved you can reference the newTaxInvoice variable after directly after saving eg.

    Dim newTaxInvoice = api.TaxInvoiceRequest.Save(invoice)

    ‘ Get the saved invoice’ doc number
    dim saveToMyField = newTaxInvoice.DocumentNumber

    Again thank you for your help. I have started delving into your code. Hopefully I can contribute in some way.

    PS: I see you have commented out the emailTaxInvoice sub. Me thinks I’m gonna start there.

  • You’re right, Werner. Every Save method returns the newly created/updated object.

    Great! Looking forward to your contributions!

  • Hi Pieter,
    Your Sage One API Wrapper was the only one I could find in .NET
    My problem is that your wrapper uses basic auth and Sage One API v2 now uses OAuth 2.0
    It is possible to update the auth to OAuth 2.0 and use your wrapper ?

    Thanks in advance!


Leave a Reply

Your email address will not be published. Required fields are marked *