SOAP Client Compatibility Guide
This guide applies to any client consuming our SOAP services, regardless of programming language or framework.
Our Guarantee
We will only ever make two types of changes to the WSDL:
- Add new optional fields to an existing request or response
- Add new endpoints
We will never rename, retype, or remove an existing field, endpoint, namespace, or operation.
Rules to Follow
1. Accept unknown XML elements in responses
Configure your XML/SOAP deserializer to silently ignore fields it does not recognise. Most frameworks do this by default — do not override it with strict schema validation.
Strict schema validation will cause your client to throw an error the moment the server adds a new field, even if you never read that field.
Why disable it: Our compatibility guarantee only promises new fields are additive and optional — it does not promise your locally cached copy of the WSDL/schema will match the server byte-for-byte forever. Strict schema validation checks the response against that fixed local copy, so it fails closed on any unrecognised element, even one that is harmless and irrelevant to your integration. This turns a non-breaking server change into a breaking client error purely because of how the client chooses to validate, not because of anything incompatible in the response itself. Disabling strict validation (or configuring your deserializer to ignore unknown elements) lets your client honor the "old proxy keeps working against a newer service" guarantee described below.
2. Do not count or enumerate response fields
Only read the fields your code actually uses. Never write logic that validates the total number of fields returned or iterates over all fields in a response.
3. Handle unknown enum and status code values
If we add a new value to an existing status code or enum field, a parser configured to reject unrecognised values will crash. Always parse enum-like fields with a fallback:
- Map recognised values to your local constants
- Fall back to a generic
UnknownorUnhandledcase for anything else - Never hard-fail on an unrecognised value
4. Handle SOAP Faults explicitly
Errors from the service are returned as SOAP Faults, not HTTP error codes. Ensure your client explicitly catches and handles SOAP Faults — do not rely solely on HTTP status handling. Unhandled faults will surface as unexpected exceptions in your application.
5. Null-check all response fields
New optional fields will arrive as null or empty. Do not assume a field will always be populated just because it has been populated historically. Apply null/empty checks to every field you read.
6. Send requests without new fields — it is always safe
When we add a new field to a request, we treat it as optional with a safe server-side default. You are never required to populate a field you do not know about. Your existing requests will continue to work without any change.
Do You Need to Regenerate Your Proxy / Client?
| Scenario | Regenerate? |
|---|---|
| Server added new response fields you don't need | No |
| Server added new response fields you want to use | Yes |
| Server added a new endpoint you don't need | No |
| Server added a new endpoint you want to call | Yes |
Your existing proxy works against an updated service indefinitely for all existing endpoints.
Important: If you regenerate your proxy against a newer WSDL, do not deploy it against an older version of the service. Always align the proxy version with the deployed service version.
Accessing the WSDL
WSDLs are versioned and available at:
https://cdn.parpos.com/WSDL/{version}/{ServiceName}.xml
Example:
https://cdn.parpos.com/WSDL/0.2.145/Settings2.xml
Use the WSDL URL matching the version of the service you are integrating against. You do not need to update your proxy when the version changes unless you want to use new fields or endpoints.
Troubleshooting
If your integration breaks after a service update, check these first:
| Symptom | Likely cause |
|---|---|
| Deserialization error on a new field | Strict schema validation is enabled — disable it |
| Validation logic breaks after an update | Code is counting or enumerating response fields — read only what you use |
| Crash on an unrecognised status/enum value | Enum parsing is not using a fallback — add one |
| SOAP Fault causes an unhandled exception | Fault handling is not implemented — catch SOAP Faults explicitly |
| Null reference error after an update | A new field is arriving as null — add a null check |
| Proxy works locally but fails in production | Proxy was regenerated against a newer WSDL than the deployed service |
