Skip to content

haviduck/signature-client-php

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
src
src
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
composer.json
composer.json
 
 

Repository files navigation

Getting started

Introduction

Last update

Last build date for this API: 27.10.2017

Getting started

Get an account

To use the API, you need an API account at Idfy You can get a free test account by going to our onboarding site and filling out the form there: https://onboard.signere.no

Support

We’re here to help. Get in touch and we’ll get back to you as soon as we can. Contact us.

Statuspage

If you want to know the status of our services or subscribe to notifications go to our Statuspage: http://signere.statuspage.io/

API Authentication

This API uses OAuth2 for authentication the requests. OAuth2 - an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications. Be sure to use client_credentials as grant type when connecting to this API.

Simple step by step guide to receive required access token

  1. Get access token

    http POST to https://oauth2test.signere.com/connect/token for test or https://oauth.signere.no/connect/token for prod

    • Request Headers:
      Content-Type: application/x-www-form-urlencoded
      Authorization: Basic auth with ClientId as username, and ClientSecret as password
      Pseudo code: Authorization: "[ClientId]:[Secret]".ToBase64String() (utf-8)

• Request Body:
  grant_type: client_credentials
  scope: [insert scope(s) here] (Contact us if you dont have access to this scope)

2) Use access token to access our API

In the response you will receive an item containing the id token you should use to connect to our API's named access_token.
• This token can then be added to the header in the requests to this API:
   Authorization: Bearer [access_token]

We have created a guide to create Oauth2 tokens for different languages here: [https://sdk.signere.com/oauthtoken.html](https://sdk.signere.com/oauthtoken.html)

Hint: The access token has a limited lifetime, check how long it will live in the response. Then you can save it to cache and reuse it (our .NET nuget client does this for you)

Read more aboute OAuth2 here: [https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2)

How to Build

The generated code has dependencies over external libraries like UniRest. These dependencies are defined in the composer.json file that comes with the SDK. To resolve these dependencies, we use the Composer package manager which requires PHP greater than 5.3.2 installed in your system. Visit https://getcomposer.org/download/ to download the installer file for Composer and run it in your system. Open command prompt and type composer --version. This should display the current version of the Composer installed if the installation was successful.

  • Using command line, navigate to the directory containing the generated files (including composer.json) for the SDK.
  • Run the command composer install. This should install all the required dependencies and create the vendor directory in your project directory.

Building SDK - Step 1

[For Windows Users Only] Configuring CURL Certificate Path in php.ini

CURL used to include a list of accepted CAs, but no longer bundles ANY CA certs. So by default it will reject all SSL certificates as unverifiable. You will have to get your CA's cert and point curl at it. The steps are as follows:

  1. Download the certificate bundle (.pem file) from https://curl.haxx.se/docs/caextract.html on to your system.
  2. Add curl.cainfo = "PATH_TO/cacert.pem" to your php.ini file located in your php installation. “PATH_TO” must be an absolute path containing the .pem file.
[curl]
; A default value for the CURLOPT_CAINFO option. This is required to be an
; absolute path.
;curl.cainfo =

How to Use

The following section explains how to use the IdfySignature library in a new project.

1. Open Project in an IDE

Open an IDE for PHP like PhpStorm. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.

Open project in PHPStorm - Step 1

Click on Open in PhpStorm to browse to your generated SDK directory and then click OK.

Open project in PHPStorm - Step 2

2. Add a new Test Project

Create a new directory by right clicking on the solution name as shown below:

Add a new project in PHPStorm - Step 1

Name the directory as "test"

Add a new project in PHPStorm - Step 2

Add a PHP file to this project

Add a new project in PHPStorm - Step 3

Name it "testSDK"

Add a new project in PHPStorm - Step 4

Depending on your project setup, you might need to include composer's autoloader in your PHP code to enable auto loading of classes.

require_once "../vendor/autoload.php";

It is important that the path inside require_once correctly points to the file autoload.php inside the vendor directory created during dependency installations.

Add a new project in PHPStorm - Step 4

After this you can add code to initialize the client library and acquire the instance of a Controller class. Sample code to initialize the client library and using controller methods is given in the subsequent sections.

3. Run the Test Project

To run your project you must set the Interpreter for your project. Interpreter is the PHP engine installed on your computer.

Open Settings from File menu.

Run Test Project - Step 1

Select PHP from within Languages & Frameworks

Run Test Project - Step 2

Browse for Interpreters near the Interpreter option and choose your interpreter.

Run Test Project - Step 3

Once the interpreter is selected, click OK

Run Test Project - Step 4

To run your project, right click on your PHP file inside your Test project and click on Run

Run Test Project - Step 5

How to Test

Unit tests in this SDK can be run using PHPUnit.

  1. First install the dependencies using composer including the require-dev dependencies.
  2. Run vendor\bin\phpunit --verbose from commandline to execute tests. If you have installed PHPUnit globally, run tests using phpunit --verbose instead.

You can change the PHPUnit test configuration in the phpunit.xml file.

Initialization

Authentication

In order to setup authentication and initialization of the API client, you need the following information.

Parameter Description
oAuthClientId OAuth 2 Client ID
oAuthClientSecret OAuth 2 Client Secret

API client can be initialized as following.

$oAuthClientId = 'oAuthClientId'; // OAuth 2 Client ID
$oAuthClientSecret = 'oAuthClientSecret'; // OAuth 2 Client Secret

$client = new IdfySignatureLib\IdfySignatureClient($oAuthClientId, $oAuthClientSecret);

You must authorize now authorize the client.

Authorizing your client

This SDK uses OAuth 2.0 authorization to authorize the client.

The authorize() method will exchange the OAuth client credentials for an access token. The access token is an object containing information for authorizing client requests.

You must pass the scopes for which you need permission to access.

try {
    $client->auth()->authorize([OAuthScope::SIGNATURE, OAuthScope::ROOT]);
} catch (IdfySignatureLib\Exceptions\OAuthProviderException $ex) {
    // handle exception
}

The client can now make authorized endpoint calls.

Scopes

Scopes enable your application to only request access to the resources it needs while enabling users to control the amount of access they grant to your application. Available scopes are defined in the IdfySignatureLib\Models\OAuthScope enumeration.

Scope Name Description
SIGNATURE
ROOT

Storing an access token for reuse

It is recommended that you store the access token for reuse.

You can store the access token in the $_SESSION global:

// store token
$_SESSION['access_token'] = IdfySignatureLib\Configuration::$oAuthToken;

Creating a client from a stored token

To authorize a client from a stored access token, just set the access token in Configuration along with the other configuration parameters before creating the client:

// load token later...
IdfySignatureLib\Configuration::$oAuthToken = $_SESSION['access_token'];

// Set other configuration, then instantiate client
$client = new IdfySignatureLib\IdfySignatureClient();

Complete example

<?php
require_once __DIR__.'/vendor/autoload.php';

use IdfySignatureLib\Models\OAuthScope;

session_start();

// Client configuration
$oAuthClientId = 'oAuthClientId';
$oAuthClientSecret = 'oAuthClientSecret';

$client = new IdfySignatureLib\IdfySignatureClient($oAuthClientId, $oAuthClientSecret);

// try to restore access token from session
if (isset($_SESSION['access_token']) && $_SESSION['access_token']) {
    IdfySignatureLib\Configuration::$oAuthToken = $_SESSION['access_token'];
} else {
    try {
        // obtain a new access token
        $token = $client->auth()->authorize([OAuthScope::SIGNATURE, OAuthScope::ROOT]);
        $_SESSION['access_token'] = $token;
    } catch (IdfySignatureLib\Exceptions\OAuthProviderException $ex) {
        // handle exception
        die();
    }
}

// the client is now authorized; you can use $client to make endpoint calls

Class Reference

List of Controllers

Class: Attachments

Get singleton instance

The singleton instance of the Attachments class can be accessed from the API Client.

$attachments = $client->getAttachments();

Method: attachmentsCreate

Create an attachment

function attachmentsCreate(
        $accountId,
        $request)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
request Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$request = new AttachmentRequest();

$result = $attachments->attachmentsCreate($accountId, $request);

Method: attachmentsGet

Retrieve an attachment

function attachmentsGet(
        $accountId,
        $documentId,
        $attachmentId)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description
attachmentId Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();
$attachmentId = uniqid();

$result = $attachments->attachmentsGet($accountId, $documentId, $attachmentId);

Back to List of Controllers

Class: Documents

Get singleton instance

The singleton instance of the Documents class can be accessed from the API Client.

$documents = $client->getDocuments();

Method: documentsCreate

Create a document

function documentsCreate(
        $accountId,
        $request)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
request Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$request = new CreateDocumentRequest();

$result = $documents->documentsCreate($accountId, $request);

Method: documentsGet

Retrieve a document

function documentsGet(
        $accountId,
        $documentId)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();

$result = $documents->documentsGet($accountId, $documentId);

Method: documentsUpdate

Update a document

function documentsUpdate(
        $accountId,
        $documentId,
        $request)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description
request Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();
$request = new UpdateDocumentRequest();

$result = $documents->documentsUpdate($accountId, $documentId, $request);

Method: documentsCancel

Cancel a document

function documentsCancel(
        $accountId,
        $documentId)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();

$result = $documents->documentsCancel($accountId, $documentId);

Method: documentsStatus

Retrieve document status

function documentsStatus(
        $accountId,
        $documentId)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();

$result = $documents->documentsStatus($accountId, $documentId);

Method: documentsGetSummary

Retrieve document summary

function documentsGetSummary(
        $accountId,
        $documentId)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();

$result = $documents->documentsGetSummary($accountId, $documentId);

Method: documentsGetCollection

List document summaries

function documentsGetCollection(
        $accountId,
        $externalId = null,
        $signerId = null,
        $externalSignerId = null,
        $fromDate = null,
        $toDate = null,
        $lastUpdated = null,
        $signedDate = null,
        $nameOfSigner = null,
        $status = null,
        $tags = null)

Parameters

Parameter Tags Description
accountId Required Your idfy account Id
externalId Optional Documents external id
signerId Optional Signer Id
externalSignerId Optional External signer Id
fromDate Optional Documents created from date (ticks)
toDate Optional Documents created to date (ticks)
lastUpdated Optional Documents updated after this date (ticks)
signedDate Optional Documents signed after this date (ticks)
nameOfSigner Optional Name of signer
status Optional Document status
tags Optional Document tags

Example Usage

$accountId = uniqid();
$externalId = 'externalId';
$signerId = uniqid();
$externalSignerId = 'externalSignerId';
$fromDate = 5;
$toDate = 5;
$lastUpdated = 5;
$signedDate = 5;
$nameOfSigner = 'nameOfSigner';
$status = string::ENUM_UNSIGNED;
$tags = 'tags';

$result = $documents->documentsGetCollection($accountId, $externalId, $signerId, $externalSignerId, $fromDate, $toDate, $lastUpdated, $signedDate, $nameOfSigner, $status, $tags);

Back to List of Controllers

Class: Files

Get singleton instance

The singleton instance of the Files class can be accessed from the API Client.

$files = $client->getFiles();

Method: filesGet

Retrieve a file

function filesGet(
        $accountId,
        $documentId,
        $fileFormat)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description
fileFormat Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();
$fileFormat = string::ENUM_UNSIGNED;

$result = $files->filesGet($accountId, $documentId, $fileFormat);

Method: filesGet1

Retrieve file for a signer

function filesGet1(
        $accountId,
        $documentId,
        $signerId,
        $fileFormat)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description
signerId Required The signers Id
fileFormat Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();
$signerId = uniqid();
$fileFormat = string::ENUM_NATIVE;

$result = $files->filesGet1($accountId, $documentId, $signerId, $fileFormat);

Back to List of Controllers

Class: Jwt

Get singleton instance

The singleton instance of the Jwt class can be accessed from the API Client.

$jwt = $client->getJwt();

Method: jwtValidate

Validate JWT

function jwtValidate(
        $accountId,
        $request)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
request Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$request = new JwtValidationRequest();

$result = $jwt->jwtValidate($accountId, $request);

Back to List of Controllers

Class: Signers

Get singleton instance

The singleton instance of the Signers class can be accessed from the API Client.

$signers = $client->getSigners();

Method: signersGet

Retrieve a signer

function signersGet(
        $accountId,
        $documentId,
        $signerId)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description
signerId Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();
$signerId = uniqid();

$result = $signers->signersGet($accountId, $documentId, $signerId);

Method: signersDelete

Delete a signer

function signersDelete(
        $accountId,
        $documentId,
        $signerId)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description
signerId Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();
$signerId = uniqid();

$result = $signers->signersDelete($accountId, $documentId, $signerId);

Method: signersUpdate

Update a signer

function signersUpdate(
        $accountId,
        $documentId,
        $signerId,
        $request)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description
signerId Required TODO: Add a parameter description
request Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();
$signerId = uniqid();
$request = new UpdateSignerRequest();

$result = $signers->signersUpdate($accountId, $documentId, $signerId, $request);

Method: signersList

List signers of a document

function signersList(
        $accountId,
        $documentId)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();

$result = $signers->signersList($accountId, $documentId);

Method: signersAdd

Add a signer to a document

function signersAdd(
        $accountId,
        $documentId,
        $signer)

Parameters

Parameter Tags Description
accountId Required TODO: Add a parameter description
documentId Required TODO: Add a parameter description
signer Required TODO: Add a parameter description

Example Usage

$accountId = uniqid();
$documentId = uniqid();
$signer = new Signer();

$result = $signers->signersAdd($accountId, $documentId, $signer);

Back to List of Controllers

About

No description, website, or topics provided.

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages