oktavilla/assently-ruby

Ruby client for communicating with the Assently API

Assently API Client

Ruby client for the Assently API v2. Check out the official API documentation here.

Supported API calls

API call	Supported
createcase	✔️
sendcase	✔️
getcase	✔️
createcasefromtemplate
updatecase
remindcase
deletecase
recallcase
findcases	✔️
createcasefromtemplate
findtemplates
getdocumentdata	✔️
createagent
createssoticket

Missing something? Contributions are very welcome! 😘

Installation

Include the gem in your Gemfile:

gem "assently"

Usage

Environment

When creating a client instance you can choose to use either Assently's production (default when not specified) or test environment. The host app.assently.com is used for production and test.assently.com is used for test when constructing the API commands. Test environment is specified like this:

Assently.client ENV["ASSENTLY_API_KEY"], ENV["ASSENTLY_API_SECRET"], :test

Creating a case

assently = Assently.client assently_api_key, assently_api_secret

case_id = SecureRandom.uuid

signature_case = Assently::Case.new "Agreement", ["electronicid"], id: case_id
signature_case.add_party Assently::Party.new_with_attributes({
  name: "First Last",
  email: "[email protected]",
  social_security_number: "1234567890"
})
signature_case.add_document Assently::Document.new "/some/path/file.pdf"

event_subscription = Assently::CaseEventSubscription.new ["finished", "expired"], "https://example.com/my-endpoint"

result = assently.create_case(signature_case, {
  # Callback for document events
  event_callback: event_subscription,
  # User ends up here after finishing the signing process
  continue: {
    url: "http://example.com/user-endpoint",
    auto: true
  },
  # User ends up here when cancelling, at the moment there is no cancel callback
  cancel_url: "http://example.com/user-canceled"
})

if result.success?
  puts "#{signature_case.id} was created."
else 
  puts "There was some issues with the case"
  result.errors.each do |error|
    puts error
  end
end

Making a case available for signing

assently = Assently.client API_KEY, API_SECRET
result = assently.get_case case_id

if result.success?
  assently.send_case case_id
  
  signing_case = assently.get_case case_id
  
  puts "Sign it here: #{signing_case.response["Parties"].first["PartyUrl"]}"
else
  puts "Could not get signature url"
  result.errors.each do |error|
    puts error
  end
end

Local development

Create a .env file in the root directory to run the integration tests against your Assently test environment.

ASSENTLY_API_KEY=your-api-key
ASSENTLY_API_KEY=your-api-secret

Contributing

Contributions is more than welcome!

Just create a fork and submit a pull request.

Please adhere to the coding standards used in the project and add tests.

assently-ruby's Issues

Remove all api v1 properties that still exists in the code base (CaseReferenceId etc)

Creating a case from a template

Support the createcasefromtemplate endpoint.

https://app.egree.com/api#Createfromtemplate

Remove Faraday dependency

We should really not need any external dependencies. If we do want some niceness around http interactions we should probably switch to the http gem.

Required functionality for an minimal mvp

• Create case
• Get case url
• Specify continue url for the end user.
• Specify callback url.

Support all v2 CaseModel properties

https://app.egree.com/api#CaseModel

Support v2 options when creating cases

All new options when creating cases (including templateId and the new EventCallback structure)

https://app.egree.com/api#Createacase

Mapper objects to unserialize api data to domain object.

Egree::Document needs to be converted to a value object. Current functionality could be moved to a CreateDocument service which takes an url/path and returns a Document instance.

Handle api v2 responses

Another thing is to decide how we want to handle responses from Egree. Since we do not get a simple url back from a specific call I think we should either just use raw hashes (as it is now with the get_case response) or support read only representations (ie. RemoteCase?) as ruby objects.

Initially I wanted to hide the internals of the egree structure as much as possible since I found it to a bit awkward (creating cases payload includes both properties on the actual case and options surrounding how the process should be handled) and I do not generally like to deal with hashes as data objects, especially when we do not control the structure of them.

Relates to #2