About the SOAP API
Status of SOAP
The e-conomic SOAP API is our older API. SOAP has wide support for e-conomic functionality. SOAP is in 'feature-freeze'. This means that we are not actively extending functionality of the SOAP API and over time we will be deprecating it to replace it with the REST API. It also means that our development efforts are focused on REST as the API of the future.
When possible we recommend to start with our REST API and only fall back to SOAP when absolutely necessary. As both APIs use the same token authentication a hybrid solution can be built on the same tokens across APIs.
Connecting to SOAP
Different languages and frameworks will have their own functionality for connecting to a SOAP-based web service. Most of these involve automatically generating client code based on the WSDL, but it is also possible to build the XML envelopes completely by hand.
You must ensure that the ASPNet session cookie is passed along in all requests - some frameworks will do this automatically, but not all.
Connecting using .NET
There are two ways of connecting to the API through .NET:
1. Adding a service reference in Visual Studio
It is possible to add a service reference in Visual Studio directly (through the add service reference in the project menu). The main drawback with this approach is that it will generate a new proxy with every build, and thus slow down your build process.
To instantiate the client use the following line: EconomicWebServiceSoapClient client = new EconomicWebServiceSoapClient(); ((BasicHttpBinding)client.Endpoint.Binding).AllowCookies = true;
2. Creating an API Web Service Library
We've written a guide to creating a library dll that you can reference from inside your solution. The benefit here is speed while working with the solution.
Connecting using Java
To ensure the cookie is passed back to our service use the following code:
EconomicWebService service = new EconomicWebService(apiUrl); EconomicWebServiceSoap session = service.getEconomicWebServiceSoap(); ((BindingProvider)session).getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY,true);
Before even trying to implement a given functionality through the API, ensure that you know how to do it in e-conomic. Trying to map your understanding of a workflow or a terminology from another system to e-conomic is one thing, but mapping directly to the API before trying it out in e-conomic is even harder.
There are two tricks for figuring out which fields map to which API properties (and also which API objects to use):
- Change the language in your e-conomic test agreement to English (from whatever language you are running in). The API terms more or less corresponds to the GUI terms (the API is strictly English).
- Trial and error in an e-conomic test agreement. Often it is easiest to simply test the API by trying out the different methods and testing the result through e-conomic.
Most of the functionality from e-conomic is available and more or less works in the same way. The most notable exception is Inventory which to a large extent is not available through the API. The only Inventory functionality available is Orders and CurrentInvoice (it is possible to upgrade an Order to a CurrentInvoice) and CurrentSupplierInvoice.
Of special interest: Please note that varians/variance and inventory stocking and corrections is not supported in SOAP API, and that EAN or any other electronic invoicing is not available.
Furthermore any mail sending of PDFs must be handled by your own integration. The API supplies these via the _GetPdf functions.
When a customer enables an integration that requires certain e-conomic modules to be enabled, it is not possible to determine this directly in SOAP. A workaround is to either use the REST API /self endpoint to get a list of enabled modules or via SOAP to simply test using methods and if you receive an authorization error with error code E0300* it means that a required module has not been enabled.
StockAccessError = "E03000"; DimensionAccessError = "E03010"; ProjectAccessError = "E03020"; PaymentsAccessError = "E03030"; ScanningAccessError = "E03040"; SubscriptionAccessError = "E03050"; AccrualsAccessError = "E03060";
Which methods to test against depends on the modules. For the Project module, for instance, it would be feasible to just retrieve all projects.