Security

Tractis use HTTPS for all its requests to the API. This guarantees all the data is encrypted and protected between client and server.

API Requirements

Format Specification

Tractis uses the same URLs for the front-end application and the API, those requests for the web interface and the XML API only differ in the format requested.

When invoking the API methods we have to specify that the requested format is XML. For doing so we have these two options:

  • Using the HTTP header Accept: Accept: application/xml
  • Appending the extension .xml to the URL: Using https://www.tractis.com/contracts.xml in stead of using https://www.tractis.com/contracts

Furthermore, when we need to use an XML document as an argumet for a method invocation we have to specify the HTPP header Content-type: Content-Type: application/xml

Authentication

  • Authentication and authorization in the API is done with basic HTTP Authentication with Tractis account and password in each request.

Character encoding

  • API invocations must use UTF-8 encoding.

Request status

  • Request status is notified using HTTP Status codes. Those codes are defined in RFC2616 "Hypertext Transfer Protocol -- HTTP/1.1"

POST /contracts

    Parameters: (bold ones are mandatory)
  • name: Name for the contract
  • template: Template ID wich will be used to create the contract
  • show_menu (true/false): Specify if Tractis menus (layout) will is used to present the contract. Default is true
  • allow_simple_accept (true/false): Specifies if the contract can be accepted ("accept" button) appart from digitally signed. When accepted tractis stores IP address from the person accepting and the date and time when it was accepted notify_when_signed_to: Email addresses list separated by commas. Those emails will be notified when someone signs or accepts a contract
  • auto_complete: Set of variables from the template and the values which will be assigned to them
    • tag_list: list of tags which will be applied to the contract sepparated by commas
  • team: Contains information about the people you want to invite to the contract
Team parameters: A team contains one or more members. We use the <member> tag to wrap member details.
    Member parameters: (bold ones are mandatory)
  • email: Email address where the invitation will be sent
  • invited (true/false): When true the person will receive a Tractis invitation and will have to sign up in Tractis. Otherwise he will just receive a random URL where he will be able to read and sign the contract without signing up in Tractis
  • sign (true/false): Specifies if the member will have sign permissions. Default is false
  • message: When invited is false, you can specify the email which will be sent to the member. Inside this <message> tag you can use: <subject> and <body>. You can specify where the URL will be placed in the email by using URL, otherwise it will be placed at the end of the email.
    Return codes:
  • 201 Created: Contract succesfully created. HTTP header Location contains the url for the contract (https://www.tractis.com/contracts/id)
  • 40X: Errors

Example XML 

  <contract> 
    <name>Renting contract</name>
    <allow_simple_accept>true</allow_simple_accept> 
    <show_menu>false</show_menu>
    <notify_when_signed_to>john@example.com, allison@example.com</notify_when_signed_to> 
    <template>123456789</template> 
    <team> 
      <member> 
        <email>client@ejemplo.com</email> 
        <invited>false</invited> 
        <sign>true</sign> 
        <message> 
          <subject>Renting contract</subject> 
          <body>Hello Paul,
            As we talked, here is the url with your contract to sign.
            ##URL##
            
            Regards
            John Doe
          </body> 
        </message> 
      </member> 
    </team> 
    <auto_complete>
      <client>
        <name>Paul Anderson</name>
      </client>
      <house>
        <address>Some street</address>
        <city>New York</city>
      </house>
      <contract_dated>
        <begin>1st May 2008</begin>
        <end>15 June 2008</end>
      </contract_dated>
    </auto_complete> 
  </contract>