Lead Generator

Technical Information

NIWS_PARTNER is an asynchronous web service which exposes multiple methods. The method BatchFileUpload allows an external system to submit a batch file of leads to the Netcash system

Once you have built the file, call:

• Format: Tab Delimited Text
• Web service: https://ws.netcash.co.za/NIWS/niws_partner.svc ^*
• Method: BatchFileUpload
• Service key: Lead Generator Service Key

NOTE: A unique Lead Generator Service Key is required to use this service.

^{* niws_partner service uses SOAP 1.2. with WS-* addressing. See example}

Input

Requests to the web service are sent as strings

Example

public string BatchFileUpload(string ServiceKey, string File) {
  // initialise client
  NIWS_Partner.NIWS_PartnerClient client =
      new NIWS_Partner.NIWS_PartnerClient();

  // call the BatchFileUpload method equal to a string variable
  // lead generator service key requested by channel manager
  string Request = client.BatchFileUpload(ServiceKey, File);

  // close client after response is received
  client.Close();

  // check response
  switch (Request) {
    case "100":  // Authentication failure
      break;
    case "200":  // General code exception.
      break;
    default:  // successfull
      return Request;
  }

  // use response to call RequestFileUploadReport method
  return Request;
}

Output

Successful request

If the method call was successful and the file is being processed, the web service will return a file token which is used to retrieve the load report

Example:  1507296452.20131202

Unsuccessful request

If the method call fails, the web service will return an error code:

Input File Structure

The file is a tab delimited text file and has the following mandatory records:

H – Header record identifies the upload and passes instructions to the Netcash server to determine the purpose of the file.
K – Key record must follow the header record. The key record describes the transaction records which follow. The format defined in the key record is used to validate the record structure and content.
T – Transaction records follow the key record. The fields in the transaction records must conform to the layout defined in the key.
F – Footer record must be the last record in the file and confirms that the file is complete.

Header record (H)

Every file must contain a header record as the first record in the file.

Field explanations

Example

H C74EF975-5429-4663-85FB-2A64CA0FB9EF 1 Registration My Test Batch 20100331 0

Key Record (K)

• The key record is mandatory and must appear in the file between the header record and the transaction records.
• The key defines the content, order and length of the transactions records in the file. It can be likened to the column headings in a spreadsheet.
• The key lists all the possible fields contained in the subsequent transaction records, even if not every transaction record contains data in all the fields.
• While the file is customizable, it is recommended that keys are listed in ascending numerical order for ease of debugging and support.

Example

K 101 113 114 121 201 441 524 525 528

Transaction Record (T)

• There must be at least one transaction record in the file.
• The transaction records must conform to the order of the fields as described in the key record. (In the example above, the account reference (field id 101) is defined as the first field in the record therefore every transaction record MUST have the account reference as the first field or it will fail validation)
• Every transaction record must have the same number of fields as defined in the key record (K).
• Empty fields should be replaced by a blank tab or a default value, where one has been defined.
• Where no default is defined, empty fields are indicated by two consecutive tabs
  (IE: the field delimiters preceding and following the empty field)
• Where fields are left empty, the Netcash system will assume spaces or zeroes for fields defined in the key record.

Mandatory fields

The more information correctly supplied in the request, the less the client will have to capture on the Netcash account activation web site. This will expedite the process from request to opening the account.

The following fields are mandatory. If these fields are not present and valid, the file will be rejected.

Validation of optional fields

• Any additional data supplied will be validated according to the table in Appendix 1.
• Only valid data will be inserted into the database.
• Any fields which fail content validation will not be inserted.
• Any fields which do not meet the specified minimum length will fail validation.
• Any fields which exceed the specified maximum length will be truncated.
• Non-mandatory fields which fail validation will not cause the file to be rejected.

Footer record (F)

The footer record indicates that the complete file has been received. It must be the last record in the file. If the record is not present, the system will fail the file without processing any transaction records.

Structure

Field explanations

Example

F 2 0 9999

Example of input file

H 5881ed99-XXX1-XXXX-XXXX-a103255d145a 1 Registration TestFile 20131202 0
K 101 113 114 121 201 441 301 302 303 524 525
T Test100 Soap Joe Test Co test@test.net 27821234567 Sage OpCo Name 123456789 0000001 1
T Test101 Bloggs Jane Janes Hardware jane@jane.com 27113044000 Extra1 Extra2 Extra3 1
F 2 0 9999

Retrieving the Load Report

Postback option

If you have activated the postback option in your Sage partner profile, the load report is automatically posted back to the URL you supplied.

Polling option

If you have not activated the postback option, you will need to request the load report using the file token received from the BatchFileUpload method call.

Using the file token, call:

• Web service: https://ws.netcash.co.za/NIWS/niws_partner.svc *
• Method: RequestFileUploadReport
• Service key: Lead Generator Key

Requests to the web service are sent as strings.

Example

public string RequestFileUploadReport(string ServiceKey, string FileToken) {
  // initialise client
  NIWS_Partner.NIWS_PartnerClient client =
      new NIWS_Partner.NIWS_PartnerClient();

  // call the RequestFileUploadReport method equal to a string variable
  // the same service key used in the batch upload
  string Request = client.RequestFileUploadReport(ServiceKey, FileToken);

  // close client after response is received
  client.Close();

  // check request
  switch (Request) {
    case "100":  // Authentication failure
      break;
    case "200":  // General code exception
      break;
    case "FILE NOT READY":  // The requested statement has not yet been created.
                            // Retry later
      break;
    case "NO CHANGE":  // No new transactions are available for download
      break;
    default:  // Successful, will contain the Netcash account number registered
              // with us
      break;
  }

  // use response to output to UI
  // service will respond with the result of the file upload
  return Request;
}

Output file

File content

For each successful lead in the file, the load report will contain the Netcash account number for the lead. Where errors were detected, the load report will stipulate the line number and the error message

Load report structure:

Load report header (occurs once at the start of each load report)

Load report message (occurs multiple times – once per T record in the input file)

Load report trailer (occurs once – the last line in the report)

Errors

The following is a list of the errors which could be returned:

Examples:

###BEGIN key record UNSUCCESSFUL 16:03
###ERROR A system error occurred. Please contact Netcash.
###END 16:03

###BEGIN UNSUCCESSFUL 16:02
Acc Ref :NA Line :2 Required key 101 was not provided
###END 16:02

###BEGIN My test batch SUCCESSFUL 15:45
Acc Ref : 001 Line :3 51002977916
###END 15:45

###BEGIN My test batch SUCCESSFUL WITH ERRORS 11:45
Acc Ref : 001 Line :3 51002977916
Acc Ref : 002 Line :4 INVALID EMAIL ADDRESS
###END 11:45

Appendix 1 Transaction fields

Account reference

Company contact details

Company details

Company physical address

Company postal address

Account user details

Bank account details

Software vendor information

Read the Lead Status Update File Specification here.

Testing

See the Testing section for more details. If you require any integration assistance contact our technical support team