Import method for new purchase orders from dealers.
Input is a multidimensional array (struct) of tns:orders, which is a complex structure best described in WSDL. There are some optional field in this structure, so read the WSDL comments carefully.
Output is an (in)complete 2D array of tns:ordersShort, which contains distributor's order number(s) with dealers' own number submitted on input. Optionally a pairing status code(s) may be included in response, but should be ignored by the client.
Method processes all orders one by one, but stops processing on any error. Each head and row is checked first and each order is saved in an isolated transaction (which assures that every already processed order is saved), but there may occur any application or database error, while checking or saving each currently processed order.
If any check fails, processing is stopped, fault is returned and no more orders are saved (no new database transaction is started). Already processed orders are left saved, so client must ask for their numbers (which are not returned with fault) using getOrdersList method in addition to reporting the error to user.
If error occurs on database level, processing is stopped, fault is returned and no more orders are saved (database transaction saving currently processed order is rolled back).
If error occurs on application level (for example unhandled exception), processing is stopped, fault is returned and no more orders are saved (database transaction saving currently processed order is not executed).
When fault is returned, client is responsible for at least notifying the user that the SOAP transaction failed and must be re-processed. In addidition to this, client should ask server for numbers of already saved orders (using number_ext for pairing) and do not re-submit such orders again.
If address code is present and matched, address parts are dropped.
If person code is present and matched, firstname and lastname are dropped.
Delivery method code is optional, if not present default is used (if any). If additionally no default is found, server returns exception (see below).
Payment method code is optional, if not present default is used (if any). If additionally no default is found, server returns exception (see below).
Currency code is optional, if not present default is used. If additionally no default is present, CZK is used.
If currency, delivery method or payment method code is omitted, server will use defaults.
If no person code is present, server will use default person code related to client. No automatic person (contact) creation is done and will not be added.
If no address is present, server will use default address code related to client. No automatic address creation is done, but will be possibly added later.
If no default is present, server returns exception when handling delivery method or payment method, so if you need to use this service, please make a call to your primary contact.
All string matching/pairing is done by comparing two strings converted to ASCII 7-bit and it is case insensitive. When multiple results found, server takes first one and does not continue to exact match.
If person code is present and not matched, server returns fault.
If person code is not present, both firstname and lastname are present and matched, server will use person code related to first matched firstname and lastname pair.
If address code is present and not matched and address parts are omitted, server returns fault.
If address code is present and not matched and address parts are present and not matched, server will create new end user address and will use it for the order. Address name is optional, but if client supplies address code (xsd:normalizedString [15]) of new address , street (xsd:normalizedString [30]), city (xsd:normalizedString [30]) and zip (xsd:normalizedString [10]) are mandatory. Element content longer than maximum specified length is truncated. that Region for new address is set to Czech Republic, but it may change in future releases.
If address code is not present, and all address parts are present and not matched, server will use address code related to first matched address parts.
Some delivery options are available only in Prague, so they are not valid in other locations. Matching is done on address zip code.
Even if order is accidentally re-submitted by the client, server returns fault because it does not accept duplicate orders (matching is done using number_ext and existing external numbers).
| Letters | Code | Status |
|---|---|---|
| AR | 1 | Address matched code to code. |
| AR | 2 | Address not matched code to code, set to default address. |
| AR | 3 | Address matched each part to each part. |
| AR | 4 | Address not supplied, set to default address. |
| AR | 5 | No recipient supplied, set to default address. |
| AR | 6 | Address code not matched, address parts not matched and new address successfully created. |
| CT | 1 | Contact person matched code to code. |
| CT | 2 | Contact firstname and lastname supplied, but not matched, set to default. |
| CT | 3 | Contact person matched name to name. |
| CT | 4 | Neither code nor firstname and lastname supplied, set to default. |
| CT | 5 | No person supplied, set to default contact. |
| CD | 1 | Delivery method code valid. |
| CD | 2 | Delivery method code invalid, using default. |
| CP | 1 | Payment method code valid. |
| CP | 2 | Payment method code invalid, using default. |
| CC | 1 | Currency code valid. |
| CC | 2 | Currency code present, but invalid, using default. |
| CC | 3 | Currency code present, but invalid, using CZK (no default found). |
| CC | 4 | Currency code not present, using default. |
| CC | 5 | Currency code not present, using CZK (no default found). |
| OD | 0 | Order will be shipped in parts (divide flag set to true). |
| OD | 1 | Order may be optionally shipped only if all products are on stock (divide flag set to false). |
| PC | row number | Number of order row where the customer price is lower than our price. |
Client should do all necessary checks before submitting each order or set of orders. Weak clients should submit each order as the only input, whereas strong clients should use full capabilities of the method.
Client may immediately re-submit orders, which was not processed due to a failure of any of previous transaction, but only those, which followed the faulty order.
Method returns SOAP fault (according to SOAP Version 1.2, section 2.3 Fault Scenarios) on failure or when no data found for client request. Database error may be returned with specific error prefix, when database is not ready or something unwanted happens.
| Code | Actor | String | Detail |
|---|---|---|---|
| any negative | SERVER | Unhandled exception. | possibly anything |
| 1 | CLIENT | Malformed request. | client input |
| 2 | CLIENT | Empty request. | client input |
| 101 | CLIENT | Malformed request, head not present. | order position |
| 102 | CLIENT | Malformed request, number_ext not present. | order position |
| 103 | CLIENT | Duplicate order, already saved. | order position |
| 104 | CLIENT | Malformed request, recipient code invalid. | order position |
| 105 | CLIENT | Malformed request, person code not found. | order position |
| 106 | CLIENT | Malformed request, failed to create new end user address. | order position |
| 201 | CLIENT | Malformed request, no row(s) present. | order position |
| 202 | CLIENT | Malformed request, product code not found. | order position followed by a semicolon and invalid part number |
| 203 | CLIENT | Invalid delivery option selected for address. | order position |
| 204 | CLIENT | Malformed request, zero price detected. | order position followed by a semicolon and invalid part number |
| 205 | CLIENT | Invalid payment method. | order position |
| 206 | CLIENT | Invalid currency. | order position followed by semicolon and invalid code |
| 207 | CLIENT | KURYR delivery option is available only from Monday to Friday at 05:00 - 12:55. | order position |
| 208 | CLIENT | Invalid payment method for selected address. | order position |
| 209 | CLIENT | Invalid currency for selected payment method. | order position |
| 210 | CLIENT | Order contains electronic license or service and code payment is 30 (cash on delivery). | order position |
| 211 | CLIENT | Order rows contains prices but customers prices are not enabled. | order position |
| 212 | CLIENT | Customer price is negative or zero. | order position followed by semicolon and row number |
| 300 | SERVER | Exception occured, transaction rolled back. | order position |
| ORA-[0-9]{1-5} | DATABASE | Database subsystem error. | database error message |
If order position is returned, it starts with 0 (zero) for first order in request array. Optionally it may be followed by a semicolon delimited sequence of another numbers or tokens, so client must be able to divide the string before semicolon to get the invalid order number. For example 3;RAH-66 with error 202, means that in order 4 somebody wants Commanche helicopter and we do not have them currently in our ERP (probably because we do not have a contract with Boeing-Sikorsky).
SOAP client must be capable of basic HTTP authentication to use this method.
| code_deliver parameter | Description |
|---|---|
| TOP | standard transportation TOPTRANS |
| KURYR | transportation in 4 hours - region Prague only |
| TOPTIME | transportation TOPTRANS in the forenoon |
| TOPPRIVAT | evening transportation TOPTRANS |
| code_payment parameter | Description |
|---|---|
| 30 | cash on delivery |
| 33 | prepayment (pro forma invoice) |
| 34 | invoice with due date |
| Type | Description |
|---|---|
| 0 | none (in case of proforma payment method (33) reservation type 1 will be applied) |
| 1 | binding reservation |
| 2 | not binding reservation |
If customer sends proforma payment method (33), type 1 reservation will be used. In that case, the goods will be reserved for 7 days, whether it's on stock or not.
If customer sends type 1 reservation and other payment method than proforma (33), goods will be reserved for 7 days, depending on every part of order being on stock. In other case, goods will be reserved for 1 day (until the workday ends, or until the next workday ends, in case of orders saved after 4:00 P.M.)
If customer sends type 2 reservation, order will be blocked for 7 days (however, we will NOT reserve the goods).
If customer doesn't send any reservation type, type 0 will be used as default, including proforma payment method (33) process logic.
| POST /index.php HTTP/1.0 | |
|---|---|
| User-Agent: | ClTest/1.0.0 (0.99) |
| Host: | dev.techdata.cz |
| Content-Type: | text/xml; charset=UTF-8 |
| SOAPAction: | "http://xchgdemo.techdata.cz/index.php/putOrders" |
| Content-Length: | 2700 |
| HTTP/1.1 200 OK | |
|---|---|
| Date: | Thu, 12 Aug 2004 09:36:05 GMT |
| Server: | Apache |
| X-SOAP-Server: | NuSOAP/0.6.8 (1.76) |
| Content-Length: | 847 |
| Connection: | close |
| Content-Type: | text/xml; charset=UTF-8 |
SOAP fault is returned in ISO-8859-1 encoding, except of server header UTF-8 charset declaration.