Url to navigate to a contact

[Stuart Eastland]

We push sales invoices from our in-house system into sage using the API, a process that also creates customers and suppliers in Sage if required.

When I create a Contact (customer or vendor) using the API I get a 32 character "id" and the $path shows as /contacts/abcde where abcde is the 32 character id.  When I use Sage online and search for a contact the resulting url looks like /contacts/customers/12345678 where 12345678 is an 8 digit numeric id which I cannot find in the data returned from Sage when I do a Contact GET.  I note that the API uses the 32 character id when creating sales invoices, so this is what I am persisting against customers in our in-house system..

So my question is, how can I construct a url to a contact using the 32 character id? 

If this is not possible, how can I obtain the numeric id that Sage uses in the page url for contacts?

 

As a wider question, why does Sage use so many different identifiers?

It is even worse in a sales invoice which has the 32 character id, a SI-nnnnn transaction id and another sequential sales invoice id in the reference field.  the SI-nnnnn seems unnecessary.  We have just migrated from sage50 where we used to use the reference column to hold a unique identifier to the corresponding despatch data in our own system, but there is no suitable place for this now.

 

 

[Reginald Jackson]

Hi,

I'm just exploring this API and I agree. In Sage 50c every table had a unique id that could be used, customer code, sales invoice number etc, so it is confusing why they've gone down this path, particularly in requiring yo uto somehow know this new id field in order to do a search... 

[Ben Smith]

Hi both,

I can fully appreciate the issue with different ids being used in different places. I cannot give you an explanation on the why, but can see what I can do to help give you options for working around this.

In terms of the contacts endpoint and the reference/id used in the url - it is different to whats used in the API, but its obtainable with a second request. As you are persisting the contact_id against the customers in your system, you would need to make a GET request to /contacts{id} and nested within the links array of the response you will see the `href` property. That gives the link as shown in the URL bar of the contact within the Accounting web UI. 

I fully appreciate this is not ideal,  and will feed this back - we need to have consistency in the way this sort of thing is handled.

In respect of the sales invoice reference you want to use, you do still have the property of reference that is independent of the invoice_number field which you should be able to continue to use like you did with Sage 50cloud Accounts, as its just a string that takes up to 25 characters.

 

Ben

[Stuart Eastland]

Thanks.  That is perfect.  I thought that I had looked through the returned json but maybe missed this.

 

I think the issue with the reference number is that the migration populated the reference number with the original invoice number and the invoice number with a transaction number that previously had not been visible to end users.  This means that all our sales invoices now have different numbers to those sent to our customers.  I anticipate some frustration when we start getting queries on these!

I have not been very impressed by the migration.  I don't see why the data above has been transposed as it is clear that I can create new invoices the way I want to, and use the reference number for our internal despatch number and continue to use the previous invoice number sequence in invoice number.

Also the migrated data is read only.  What happens if we need to change a journal code or reprint a sales order (print is disabled too).

[Stuart Eastland]

Hi Ben, I wonder if you can help me again?  Your suggestion to use the links/href  in the contact json resolved my requirements for contacts, however the products uses the same dual unique key scenario where the API requires the 32 character key and the pages require a numeric id which I cannot find anywhere in the json returned or a product.  This does not have a links section.

 

So, how do I find this numeric id for a product so I can construct a link from our internal website?

[Ben Smith]

Morning Stuart,

So as you've no doubt noticed the links array isn't exposed on the products endpoints, and so you cannot obtain the id you are looking for through that method.

However, after doing some digging and discussing this with our API dev team, I've found out that we have a query param that you can use anywhere you see that id used in the URL of show_legacy_id=true. This adds the attribute legacy_id to the response body either when used on a GET to all /products?show_legacy_id=true (the id is displayed for each product/service etc) or when you do a GET on products/{id}?show_legacy_id=true.

{
    "$total": 4,
    "$page": 1,
    "$next": null,
    "$back": null,
    "$itemsPerPage": 20,
    "$items": [
        {
            "legacy_id": 3605378,
            "id": "92b7697e4a9211e796210a57719b2edb",
            "displayed_as": "Product used for test purposes",
            "$path": "/products/92b7697e4a9211e796210a57719b2edb"
        },
        {
            "legacy_id": 5107040,
            "id": "8c9ecb543d6111e8b45c048132dab352",
            "displayed_as": "Stock test",
            "$path": "/products/8c9ecb543d6111e8b45c048132dab352"
        },

This works on the /contacts endpoint as well just so you know. It will be far simpler to get the id you want using this method, rather than the href 

I would also add that as these ids were used in earlier versions of the API and so I cannot guarantee it will always work this way, but we will document any changes if or when they were to happen.

 

Ben

[Stuart Eastland]

Thanks Ben,  that works perfectly although it does mean a second request when creating new products/contacts.

Also your pointers to the "key concepts" in your help pages should reduce the number of further questions from me 😁

My project to allow our in-house system to push products, contacts and sales invoices directly into Sage went live this week following our migration from sage50 and should result in significant time (and error) savings.

However, the json in your previous answer makes me question the best way for me to deal with paginated queries.  I understand the principle behind the $total, $page, $items elements, however I have not found an efficient way to de-serialize the "$" prefixed data.  I appreciate that this is more of a basic coding question rather than Sage specific, but I wondered if you can give me some hints for use with C#.

[Ben Smith]

Hi Stuart,

Glad thats helping! 

I'd initially recommend having a look at our Sample app for C#.NET Core and another provided by Ledgerscope, both of which you can download here: https://developer.sage.com/accounting/guides/getting-started/sample_apps/

The Ledgerscope app retrieves all of the response attributes using properties and handles them in an PagingHandler class - definitely worth a look. 

 

Ben