Virtual Fax API User Guide

Transcription

1 Virtual Fax API User Guide

2 Introduction 2 Single Fax Job Submission (XML) 2 Protus XML Submission Services 2 Input: Job Request 2 Output: Status Response 2 Single Fax Job Submission XML Element Hierarchy 3 Single Fax Job Submission XML Element Descriptions 3 Example Single Fax Request 7 Protus Single Fax Job Submission (SMTP) 8 Protus SMTP Submission Services 8 Content 8 Required Parameters 8 Optional Parameters 9 Example 12 Sample Fax Cover Page 13 Single Fax Confirmation Messages 14 Confirmation Destination and Parsing 14 Other Fax Result Reporting Options 14 Deactivating Confirmations 14 Successful Fax Delivery Confirmation 15 Default Confirmation Style 15 Alternate Machine Friendly Confirmation Style 16 Failed Fax Delivery Confirmation 17 Default Confirmation Style 17 Alternate Machine Friendly Confirmation Style 18 PIPSUGVFAPI Protus IP Solutions

3 Introduction Protus offers a set of Application Programmer Interfaces (APIs) as part of its Job Submission capabilities. Customers can use either SMTP, or XML over HTTPS to submit jobs easily and securely, receiving immediate confirmation that Protus has received the job. Under the Virtual Fax product line, Protus has two APIs which may be used to submit single destination faxes: Single Fax Job Submission (SMTP) Single Fax Job Submission (XML) Under the Messaging Services product line, Protus has a number of APIs available to send multiple destination fax or voice broadcasts: Fax Broadcast Job Submission (SMTP) Fax Broadcast Job Submission (XML) Voice Broadcast Job Submission (XML) The following sections describe each of the Virtual Fax APIs. The Messaging Service APIs may be found in the user guide: Messaging Service APIs. Single Fax Job Submission (XML) Protus XML Submission Services The Protus system requires an XML document as the Job Submission input and provides a Request Status XML document as the result. Input: Job Request To submit a job request to Protus, post a SOAP encapsulated XML document called a Job Request, to the Protus XML Submission Web Services: The XML document must contain all of the account and document information needed to create a Protus Job Request, as described below. Output: Status Response The Protus server responds to a Broadcast Request with SOAP encapsulated response, which provides a status code indicating the success or failure of the Broadcast Request. PIPSUGVFAPI Protus IP Solutions

4 Single Fax Job Submission XML Element Hierarchy single_fax_info o login_key user_id user_ user_password o single_fax_options billing_code from_name start_hour end_hour legal_size_flag tiff_image_flag resolution cover_page cover_page_name cover_page_tags cover_page_subject o fax_recipient fax_recipient_number fax_recipient_name o document_list document Single Fax Job Submission XML Element Descriptions single_fax_info is the root element of the Single Fax Request XML document. Its only attributes are used to define the namespace and the location of the schema. It contains the four main functional elements for the broadcast: login_key, single_fax_options, fax_recipient, and document_list. login_key required contains elements pertaining to account identification and authentication user_id only one of either user_id or user_ is required contains the account user id number, which is an integer from 1 to user_ only one of either user_id or user_ is required contains the address assigned to an account user, which is a string of up to 60 characters. PIPSUGVFAPI Protus IP Solutions

5 user_password required contains the password associated with the account user, which is a string of up to 20 characters. single_fax_options required contains elements pertaining to any special options to be applied to the fax send billing_code will appear on the broadcast report, but not on the faxed document value: string of up to 128 characters default: depends upon the account settings from_name will appear as the from text on the fax banner line value: string of up to 50 characters default: account from name default setting start_hour specifies the beginning hour of the allowed range of delivery hours value: integer 0-23 default: 0 end_hour specifies the end hour of the allowed range of delivery hours value: integer 0-23 default: 23 legal_size_flag specifies that document should be converted as legal size paper value: true false default: false PIPSUGVFAPI Protus IP Solutions

6 tiff_image_flag specifies that document provided is a tiff image requiring no further image conversion value: true false default: false resolution specifies whether the document should be converted to a high (fine) resolution or low (draft) resolution tiff image value: low high default: low cover_page identifies whether or not a cover page should be inserted at the beginning of the fax transmission. Cover pages provide Fax Number, To, From, Page Count, Date Time, Subject, Cover Page Flags and Comments as merged fields inside the first page of the fax transmission contains elements pertaining to the creation of the cover page cover_page_name can be used by clients who have Custom Cover Page templates on file with the Protus System. Client s requiring custom cover pages (i.e. movement of cover page merge points to alternate locations) must contact their sales representative and provide samples of desired cover page layouts. Once complete, custom cover page templates are assigned a unique code that must be identified here. value: string (15) default: none cover_page_tags sets the use of the Cover Page Flags. The flags are: U-Urgent, R-Reply, I- Information, C-Please Comment, A-Reply ASAP. value: string (5) default: none cover_page_subject PIPSUGVFAPI Protus IP Solutions

7 the subject line which will appear on the cover page value: string (50) default: none fax_recipient required contains elements pertaining to an individual fax broadcast destination fax_recipient_number required contains the destination fax number beginning with the country code value: numeric string of up to 20 digits fax_recipient_name contains the destination name for the to field on the fax banner line value: string of up to 50 characters default: none document_list required contains at least one document element for each document to be faxed document minimum 1 document element required has attributes defining document characteristics contains document to be faxed as encoded text, as defined by the document attributes document_content_type attribute required defines MIME content type of original document: text, html, etc. document_encoding_type attribute required defines MIME encoding type used to encode document values base64 uuencode quoted-printable none bin-hex document_extension attribute required provides file extension of original document value: string PIPSUGVFAPI Protus IP Solutions

8 Example Single Fax Request <?xml version="1.0" encoding="utf-8"?> <single_fax_info xmlns=" xmlns:xsi=" xsi:schemalocation=" sfax_schema.xsd"> <login_key> <user_id>14975</user_id> <user_password>xxxxxx</user_password> </login_key> <single_fax_options> <billing_code>single - May </billing_code> <from_name>single - Randy Morrow</from_name> <start_hour>0</start_hour> <end_hour>23</end_hour> <release_date> t10:00:00</release_date> <legal_size_flag>false</legal_size_flag> <tiff_image_flag>false</tiff_image_flag> <resolution>low</resolution> <cover_page> <cover_page_tags>u</cover_page_tags> <cover_page_subject>this is the subject</cover_page_subject> </cover_page> </single_fax_options> <fax_recipient> <fax_recipient_number> </fax_recipient_number> <fax_recipient_name>singletest - Randy</fax_recipient_name> </fax_recipient> <document_list> <document document_content_type="text/plain" document_encoding_type="7bit" document_extension="txt">this is the content!</document> <document document_content_type="application/msword" document_encoding_type="base64" document_extension="doc">0m8r4kgxgueaaaaaaaaaaaaaaaaaaaaapgadap7/cqagaaaaaaaaaaaaaaab AAAAJgAAAAAA AAAAEAAAKQAAAAEAAAD+////AAAAACcAAAD///////////////////////////////////// //////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////... (lines omitted)... AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</document> </document_list> </single_fax_info> PIPSUGVFAPI Protus IP Solutions

9 Protus Single Fax Job Submission (SMTP) Protus SMTP Submission Services For customers who wish to send machine generated to fax transmissions Protus offers a configurable addressing method that allows the passing of fax parameters within the User Name section of the To: line. Customers are asked to create a plain text MIME with desired fax parameters included on the To: line. The method supports a number of fax parameters. All tags are optional and position independent, so only the tags you need to activate must be included to control the features you want. All of the Boolean flags default to false if they are not included. Content The Protus system requires a plain-text MIME , with the body as 7-bit plain-text and the attachments Base64 encoded, as the Fax Job Submission input. The structure is as follows: To:Fax=faxnumber/fr=fromname/to=toname/bc=billingcode/lg=logoname /st=starthour/en=endhour/cp=coverpageboolean/cf=covertags/cn=covername /le=legalboolean/rf=fineresboolean/ls=landscapeboolean@virtualfax.com From: protusaccount @customerisp.com Subject: Cover Page Subject if required Body: Password Line 1 Comment section of cover page or Fax Content Line 2 Line 3 Etc Attachments: Up to 9 attachments of supported file types Required Parameters Fax Number: Code: Fax= Type: String (11 digit number for North American destinations) Default: None The destination fax number for the transmission is inserted immediately following the string Fax=. North American destinations must begin with the number 1. International destinations must begin with the country code (example: 44 for UK destinations) Avoid use of brackets (, dashes -, and spaces. PIPSUGVFAPI Protus IP Solutions

10 Optional Parameters From Text Over Ride: Code: /fr Type: String (50 character maximum) Default: User Account From Name This is an alphanumeric string that will be used to populate the From text on the Fax banner line. If this tag is not included, then the From text will be taken from the default associated with the User Account. Space Character is not supported. Fax Recipient Name: Code: /to Type: String (50 character maximum) Default: None This is an alphanumeric string that will be used to populate the To text on the Fax banner line. If the tag is not included, then no recipient name will appear on the fax banner or within an attached cover page. Space character is not supported. Billing Code: Code: /bc Type: String (128 character maximum) Default: User Account Billing Code This parameter assigns the customer s customized billing code to the fax transmission. If not included, the billing code will be assigned from the customer s account default setting alphanumeric. Billing Codes represent the senders reference ID for an individual transmission. They appear on fax confirmations, on-line reports and invoices. Logo Name: Code: /lg Type: String (15 character maximum) Default: Default Logo for Account Note: Fee may apply, Contact your Sales Associate This is a special parameter for clients with multiple Logo s on file. The parameter allows a sender to request which specific logo should be inserted onto the fax transmission. Clients can have either a default logo or multiple logo s set up for their account by contacting their sales associate and providing them with a Black and White BMP of JPG image. Large images, requiring resizing, may loose resolution. Note that logo insertion is not a compulsory feature for using Automated Single Fax. Start Hour: Code: /st Type: Integer (0-23) Default: 0 Sets the earliest hour before which no faxing may occur. The default of 0 means that faxing may commence at midnight. PIPSUGVFAPI Protus IP Solutions

11 End Hour: Code: /en Type: Integer (0-23) Default: 23 Sets the latest hour after which no faxing may occur. The default of 23 actually refers to the end of the 23 rd hour, ie. 23:59 (11:59 PM), and means effectively that faxing is allowed until 1 minute before midnight. Cover Page: Code: /cp Type: Boolean (true/false) Default: false This tag identifies whether or not a cover page should be inserted at the beginning of the fax transmission. Cover pages provide Fax Number, To, From, Page Count, Date Time, Subject, Cover Page Flags and Comments as merged fields inside the first page of the fax transmission. This tag is required to activate the /cn and /cf parameters. Cover Page Flags: Code: /cf Type: String (URICA) Default: None This parameter sets the use of the Cover Page Flags. The flags are:u Urgent, R- Reply, I Information, C Please Comment, A Reply ASAP. Note that this tag can only be used if the Cover Page tag is set to true. Cover Page Name: Code: /cn Type: String (15 characters) Default: Default Cover Template Note: Fee may apply, Contact your sales associate. This tag can be used by clients who have Custom Cover Page templates on file with the Protus System. Client s requiring custom cover pages (i.e. movement of cover page merge points to alternate locations) must contact their sales representative and provide samples of desired cover page layouts. Once complete, custom cover page templates are assigned a unique code that must be identified via the /cn tag. Legal Conversion: Code: /le Type: Boolean (true/false) Default: False This tag is used to request a legal format Tif conversion for attached documents. Note that receiving fax machine must be configured to accept Legal size Tif images in order to receive converted image on a single page. PIPSUGVFAPI Protus IP Solutions

12 Fine Resolution: Code: /rf Type: Boolean (true/false) Default: false This tag is used to request a Fine Resolution for converted TIF images. In general, Fine resolution can improve the quality of fax images containing detailed graphics and writing below 8 point font. Landscape Orientation: Code: /ls Type: Boolean (true/false) Default: false This tag is used to request a Landscape orientation for the conversion of the plain text body. Note that Plain text s cannot be formatted in the same way as attached document files. The default font used to convert plain text bodies is Lucida Console 12 point font. See account parameters (Section 5) to change the default Font used for your account if required. Cover Page Subject: Code: no code. Uses subject line Type: String (Maximum 42 characters) Default: None The subject for the cover page can be passed on the subject line of the message. Cover Page Comment: Code: no code. Uses body Type: String ( Body following Password) Default: None The Cover page comment section is populated with the content of the Plain Text body following the Password parameter on the first line. Line length is set 72 characters. Number of lines available (using default Font size of 12) is 25 lines on 1 st page and 49 lines on subsequent pages. Password: Code: no code. Uses first line of plain text body Type: String (maximum 8 characters) Default: None The password parameter must appear as the first line in the plain text section of the body. Passwords are case sensitive and can be any combination of alpha numeric characters up to 8 characters long. Contact us to have your password changed or password validation deactivated. PIPSUGVFAPI Protus IP Solutions

13 Example In this example, the single fax automated is coming from the customer s password is mypass, and the customer wishes to send a fax to for a recipient named Bob_Smith. The From Name to appear on the fax banner line is Jane_Doe, and the faxes will be sent using fine resolution. The customer is assigning a billing code of abc1234 which will appear on all associated reports. The client is requesting a standard Cover Page with a check mark in the Urgent cover page flag and the subject BIG SALE!!!. The cover page will include a short comment and the fax content will be composed of a 1 page Microsoft Word Document called Flyer.doc. PIPSUGVFAPI Protus IP Solutions

14 Sample Fax Cover Page Virtual Fax API User Guide PIPSUGVFAPI Protus IP Solutions

15 Single Fax Confirmation Messages Confirmation Messages are sent following either fax delivery or fax failure. Fax confirmation messages are available in 2 different styles; a default style containing friendly verbiage suitable for manual interpretation of fax results and an alternate machine friendly confirmation style suitable for automated parsing. Confirmation Destination and Parsing Confirmations are sent to the Confirmation Address specified in a clients account profile. The address can be different than the originating address used for account validation. In general all confirmation s contain basic fax information in the subject line. It is therefore possible to automate confirmation parsing using only the headers. Special information like Duration and Error Reason Codes must be obtained by parsing the plain text body. Other Fax Result Reporting Options In addition to individual confirmation messages, reports of fax activity and fax results are available for download through our Client web Interface. In addition, a complete transaction breakdown is sent with all monthly Invoices. Deactivating Confirmations If desired accounts can be set to not send confirmations for Successful or Failed fax attempts. This is an account parameter that must be set manually. Contact your Sales associate or our support department to de-activate confirmation sending for your account. PIPSUGVFAPI Protus IP Solutions

16 Successful Fax Delivery Confirmation Default Confirmation Style Header Destination Confirmation Address from Account Profile Subject: Contains fax result, number, Protus Transaction ID, Account Number and Billing Code Body Body 1 st Line: Fax result string SUCCESSFUL FAX Customer No.: Account Number used to process fax transmission Reference No.: Transaction ID number generated by Protus Fax System Billing Code: Client Reference number passed via /bc tag Sent At: Delivery time stamp in EST (GMT factor included) Pages: Number of pages in transmitted TIF file Duration: Value in seconds to transmit TIF image Your Fax To: Destination Fax number To: Recipient name passed via /to tag Cost: Cost of individual fax transmission down to 4 decimal places Taxes: If appropriate Report Version: Identifier of confirmation version PIPSUGVFAPI Protus IP Solutions

17 Alternate Machine Friendly Confirmation Style Header Destination Confirmation Address from Account Profile Subject: Contains fax result, number Header Protocol: Internal Use (Always = MF) Version: Identifier of Confirmation Version Key: Billing code passed via /bc tag Status: String success for successful faxes Status_info: Error code equal to 0 for successful faxes Delivery_time: Delivery date time in GMT Page_count: number of pages in delivered TIF file Billing_Rate: Rate per page delivered Phone_Number: This is the Destination Fax Number Transmit_time: Duration of fax transmission Reference_number: Transaction ID number generated by Protus Fax System PIPSUGVFAPI Protus IP Solutions

18 Failed Fax Delivery Confirmation Default Confirmation Style Header Destination Confirmation Address from Account Profile Subject: Contains fax result, number, Protus Transaction ID, Account Number and Billing Code Body Body 1 st Line: Fax result string FAX FAILED Customer No.: Account Number used to process fax transmission Reference No.: Transaction ID number generated by Protus Fax System Billing Code: Client Reference number passed via /bc tag Your Fax To: Destination Fax number To: Recipient name passed via /to tag Sent At: Delivery time stamp in EST (GMT factor included) Has Failed Because: Short Description verbiage of fax error reason (see Appendix C) Report Version: Identifier of confirmation version PIPSUGVFAPI Protus IP Solutions

19 Alternate Machine Friendly Confirmation Style Header Destination Confirmation Address from Account Profile Subject: Contains fax result and destination fax number Body Protocol: Internal Use (Always = MF) Version: Identifier of Confirmation version Key: Billing Code passed via /bc tag Status: Short Description verbiage of fax error reason (see Appendix D) Status_info: Hardware Result Code from Brooktrout Faxout Board Delivery_Time: Last attempted date time in GMT Page Count: Number of pages delivered Billing Rate: Rate per page (if applicable) Phone_number: Destination fax number attempted Transmit_Time: Duration of fax transmission Reference_Number: Transaction ID number generated by Protus Fax System PIPSUGVFAPI Protus IP Solutions

20 PIPSUGVFAPI.05.04