FAQ - accountsIQ/API-Wiki GitHub Wiki
Frequently Asked Questions
Please find below a list of frequently asked questions that we have gathered after discussions with many integrators.
Index
- Login Issues
- I have finished developing the integration link. How can I go live now?
- Can the customer/supplier codes be automatically generated by the system?
- Why is the customer I am trying to create not saved?
- Are the web services compatible with language? (Java, C#, VB, PHP, Classic ASP...)
- Do you have any examples in PHP?
- I created a new order/invoice. I then retrieved it to check it was saved and updated it again, but it failed.
- How can I get example XML requests for an operation (GetCustomer for example) on the web services?
- How do I tell the system that the order/invoice is in Currency ?
- What sort of authentication/authorisation is used on the web services?
- I have to create, populate and post several thousands of invoices and this seems to be taking longer than I would like.
- I am getting errors while creating a sales order?
- I have created customers/suppliers in the system that I would like to clear before trying again, how can I do this?
- I am getting errors while creating a sales receipt?
- I am trying to call the Login method but the server is not sending back a session token?
- On which edition is the integration via API available?
- I want to create a new customer but there are a lot of fields in the customer record which I do not know what to populate them with?
- What is that "auth" reference in every code examples and where does it come from?
- We are using classic ASP, any idea of how we could generate a proxy?
Q: I have finished developing the integration link. How can I go live now?
Send an email to [email protected] requesting a live production partner key. Then switch your web reference to the live production web service url.
Your users will then need to provide you or your software with their user integration key.
Q: Can the customer/supplier codes be automatically generated by the system?
No, the system does not generate customer codes automatically via API.
Q: Why is the customer I am trying to create not saved?
There can be multiple causes reasons for this:
The customer code must be specified
The customer code must be upper case
The BankCode must exist in the system (the BankAccountCode is the physical bank account number in the bank's branch while the BankCode is the General Ledger code representing the bank in the system)
The referral ID cannot be specified throught the API and must be left blank/null
Example:
C#
private void CreateNewCustomer()
{
Integration_1_1.Integration_1_1 ws = new Integration_1_1.Integration_1_1();
String auth = ws.Login(companyID, partnerKey, userKey);
if (auth != null)
{
Integration_1_1.Customer customer = new Integration_1_1.Customer();
customer.Name = "ABC Account 01";
customer.Address1 = "this is my address 1";
customer.Address2 = "this is my address 2";
customer.City = "this is my city";
customer.County_State = "this is my county";
customer.Country = "this is my country";
customer.PostCode = "this is my postcode";
customer.Contact = "Contact";
customer.Email = "[email protected]";
customer.Fax = "0123459";
customer.Phone = "0123457";
// This will not work because the account code was not set and the system does not generate them
// dynamically
Integration_1_1.WSResult2OfBoolean result = ws.UpdateCustomer(auth, customer, true);
Assert.IsNotNull(result);
Assert.AreEqual(true, result.Result);
}
}
Q: Are the web services compatible with language? (Java, C#, VB, PHP, Classic ASP...)
Yes, the web services are SOAP based and are language agnostic. Languages such as PHP and Classic ASP may require more work to generate a proxy to connect to the web service though.
Q: Do you have any examples in PHP?
No, we do not have any examples available at the moment. We only provide examples in C# and VB.NET.
However, if you are using PHP here are some instructions to get started. The simplest way to integrate is first to generate a set of proxy classes from our WSDL using a tool such as wsdl2php. You should then be able to generate a set of classes by pointing it to the Staging Environment.
You then have to require_once the generated include php files and follow the C# examples that we have provided in this help file.
Please send a mail to [email protected] if you require any help on this.
Q: I created a new order/invoice. I then retrieved it to check it was saved and updated it again, but it failed.
You need to send back the modified values on top of the retrieved order/invoice and not on top of the original one as the values set during saving such as RowVersionNumber would not match.
Q: How can I get example XML requests for an operation (GetCustomer for example) on the web services?
Using a browser, directly query the following url:
This will present you with an example query.
Q: How do I tell the system that the order/invoice is in Currency ?
Ordering/Invoicing is always done in the currency of the associated customer/supplier. So if the invoices have to be in Sterling, the customer/supplier has to be in Sterling.
Q: What sort of authentication/authorisation is used on the web services?
The web services require a first call to the Login method with the correct credentials to obtain a session token. This token is valid for 5 minutes. The token is to be sent along with every single method call as the first parameter.
Q: I have to create, populate and post several thousands of invoices and this seems to be taking longer than I would like.
In this case, use the bulk methods instead of the single methods for the various operations. The bulk methods are identified by their plural names, i.e.:
GetNewSalesInvoices instead of GetNewSalesInvoice
PostInvoicesGetBackTransactionIDs instead of PostInvoiceGetBackTransactionID
Similar operations exist on the purchases side. The bulk methods can support thousands of records a second.
Q: I am getting errors while creating a sales order?
There can be multiple reasons for this:
CurrencyCode is mandatory
OrderDate is mandatory
"NA", "N/A" are not recognised values. Use null (xsi:nil="true") instead.
Creation Date should be null
Status should be null
Author User ID should be null
QuoteID should be null
Do not specify a row version number
OrderID should be blank
Hold should be 0
In each line:
QuoteItemID should be null
OrderItemIDshould be 0
CreationDate should be null
Do not specify a row version number
OpeningStockGLAccountCode is mandatory and cannot be left empty
Q: I have created testing data in the system that I would like to clear before trying again, how can I do this?
Send an e-mail to [email protected] specifying what you want done on which company and it will be done for you.
Q: I am getting errors while creating a sales receipt?
There can be multiple reasons for this:
BankAccountCode is mandatory
CustomerCode is mandatory
CheckReference is mandatory
Q: I am trying to call the Login method but the server is not sending back a session token?
Confirm whether you are linking to the staging environment or the live production servers. The production servers require a different set of keys and will thus refuses your credentials. You must request a set of production keys from us directly.
If you copied your keys from a received email, make sure that you do not copy spurious line endings or blank spaces as part of the key.
Q: On which edition is the integration via API available?
On all editions without restriction.
Q: I want to create a new customer but there are a lot of fields in the customer record which I do not know what to populate them with?
Use the GetNewCustomerFromDefaults method to get the shell of a customer pre-populated with all the default values from the system. This is a useful method to use when first creating a test customer.
Q: What is that "auth" reference in every code examples and where does it come from?
This is the session token that can be retrieved by calling the Login method with the correct credentials.
Example:
C#
Integration_1_1.Integration_1_1 ws = new Integration_1_1.Integration_1_1();
String auth = ws.Login(companyID, partnerKey, userKey);
if (auth != null)
{
// ...
}
Q: We are using classic ASP, any idea of how we could generate a proxy?
The easiest way is to generate the proxy dll with the .NET tools and then reference the assembly from the classic ASP files.