Using eformsign API¶
The API provided by eformsign allows customers to call and use eformsign features in their system/service.
Getting started¶
You need the following information to use eformsign API.
Company ID and Document ID
API Key and Private Key
Generating a signature
Caution
There is a 30 second time limit for generating a signature. You must create a signature and get token issued within 30 seconds.
Where to find Company ID and Document ID¶
To use eformsign API, you need to know the company ID and the document ID that you want to lookup.
Log in to eformsign service and find the company ID and the document ID.
Getting an API key and private key¶
Log in to eformsign as the company administrator and then go to [Integration] > [API / Webhook] in the sidebar menu.
Select the [Manage API key] tab and then click the Create an API key button.
Enter the alias and application name in the Create an API key pop-up and then click the Save button.
Click the View key in the list to view the API key and Private key.
Note
Editing an API key
You can change the alias and application name by clicking the Edit button in the API key list. You can also disable/enable the key by clicking the Status toggle button.
Note
Deleting an API key
You can delete an API key by clicking the Delete button in the API key list.
Generating a signature¶
eformsign_signature uses asymmetric key cryptography and elliptic curve cryptography.
Tip
Elliptic curve cryptography is a public key encryption method and is currently the most popular method used in data encryption, digital authentication, etc.
The following describes how to generate a signature for each language: Java, Python, and PHP.
Java¶
Convert the current time of the server to String (UTF-8) and sign using the private key issued to you in Getting an API Key. Then, convert the signed data into hex string.
Note
The signature algorithm used is SHA256withECDSA.
Javascript(Node.JS)¶
Ensure that Jsrsasign(https://kjur.github.io/jsrsasign/) npm is installed.
npm install jsrsasign
Python¶
Use the library for key generation in the link below. Install the library using the following command.
pip install https://github.com/warner/python-ecdsa/archive/master.zip
PHP¶
Ensure that PHP OpenSSL library is installed and the keycheck.inc.php and test.php files in the following examples are located in the same path before proceeding.
Examples¶
The following shows the examples for each language.
Note
For execution_time, long type is used. Therefore, when entering the execution_time, add ‘L’ at the end of the excution time which were given with the issuance of the Access Token.
import java.security.KeyFactory;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.PrivateKey;
import java.security.Signature;
//private key
String privateKeyHexStr = "the private key(String) issued to you";
KeyFactory keyFact = KeyFactory.getInstance("EC");
PKCS8EncodedKeySpec psks8KeySpec = new PKCS8EncodedKeySpec(new BigInteger(privateKeyHexStr,16).toByteArray());
PrivateKey privateKey = keyFact.generatePrivate(psks8KeySpec);
//execution_time - the current server time
long execution_time = new Date().getTime();
String execution_time_str = String.valueOf(execution_time);
//the generated eformsign_signature
Signature ecdsa = Signature.getInstance("SHA256withECDSA");
ecdsa.initSign(privateKey);
ecdsa.update(execution_time_str.getBytes("UTF-8"));
String eformsign_signature = new BigInteger(ecdsa.sign()).toString(16);
//the current time and the signature value at the current time
System.out.print("execution_time : "+execution_time);
System.out.print("eformsign_signature : "+eformsign_signature);
const rs = require('jsrsasign');
// User-Data-Here
const execution_time = Date.now()+"";
const privateKeyHex = "the private key(String) issued to you";
// User-Data-Here
var privateKey = rs.KEYUTIL.getKeyFromPlainPrivatePKCS8Hex(privateKeyHex);
// Sign
var s_sig = new rs.Signature({alg: 'SHA256withECDSA'});
s_sig.init(privateKey);
s_sig.updateString(execution_time);
var signature = s_sig.sign();
console.log('data:', execution_time);
console.log('eformsign_signature:', signature);
import hashlib
import binascii
from time import time
from ecdsa import SigningKey, VerifyingKey, BadSignatureError
from ecdsa.util import sigencode_der, sigdecode_der
# private key
privateKeyHex = "the private key(String) issued to you"
privateKey = SigningKey.from_der(binascii.unhexlify(privateKeyHex))
# execution_time - current server time
execution_time_int = int(time() * 1000)
execution_time = str(execution_time_int)
# the generated eformsign_signature
eformsign_signature = privateKey.sign(execution_time.encode('utf-8'), hashfunc=hashlib.sha256, sigencode=sigencode_der)
# the current time and the signature value at the current time
print("execution_time : " + execution_time)
print("eformsign_signature : " + binascii.hexlify(signature).decode('utf-8'))
<?php
namespace eformsignECDSA;
class PublicKey
{
function __construct($str)
{
$pem_data = base64_encode(hex2bin($str));
$offset = 0;
$pem = "-----BEGIN PUBLIC KEY-----\n";
while ($offset < strlen($pem_data)) {
$pem = $pem . substr($pem_data, $offset, 64) . "\n";
$offset = $offset + 64;
}
$pem = $pem . "-----END PUBLIC KEY-----\n";
$this->openSslPublicKey = openssl_get_publickey($pem);
}
}
class PrivateKey
{
function __construct($str)
{
$pem_data = base64_encode(hex2bin($str));
$offset = 0;
$pem = "-----BEGIN EC PRIVATE KEY-----\n";
while ($offset < strlen($pem_data)) {
$pem = $pem . substr($pem_data, $offset, 64) . "\n";
$offset = $offset + 64;
}
$pem = $pem . "-----END EC PRIVATE KEY-----\n";
$this->openSslPrivateKey = openssl_get_privatekey($pem);
}
}
function getNowMillisecond()
{
list($microtime,$timestamp) = explode(' ',microtime());
$time = $timestamp.substr($microtime, 2, 3);
return $time;
}
function Sign($message, $privateKey)
{
openssl_sign($message, $signature, $privateKey->openSslPrivateKey, OPENSSL_ALGO_SHA256);
return $signature;
}
?>
<?php
require_once __DIR__ . '/keycheck.inc.php';
use eformsignECDSA\PrivateKey;
define('PRIVATE_KEY', 'the private key(String)' issued to you);
//setting a private key
$privateKey = new PrivateKey(PRIVATE_KEY);
//execution_time - current server time
$execution_time = eformsignECDSA\getNowMillisecond();
//the generated eformsign_signature
$signature = eformsignECDSA\Sign(execution_time, $privateKey);
//the current time and the signature value at the current time
print 'execution_time : ' . execution_time . PHP_EOL;
print 'eformsign_signature : ' . bin2hex($signature) . PHP_EOL;
?>
Open API list¶
eformsign provides API for generating a signature and API for document creation and process.
API for generating a signature¶
To generate a signature, use Access Token API.
POST
: Issue Access Token
Click here for more information about Access Token API.
Caution
There is a time limit of 30 seconds when generating a signature. A signature must be generated and a token must be issued within 30 seconds. Also, the server time and the current time may not match. Check the ‘execution_time’ of response message received after calling Access Token API.
{ "code": "4000002", "ErrorMessage": "The validation time has expired.", "execution_time": 1611538409405 }
Enter ‘execution_time’ in the following Example.
Access Token can be issued for member. To get an Access Token for a member, enter ‘member_id’ together with the ‘execution_time’.
When the API is executed, Access Token will be issued and you will receive the following response.
{ "api_key": { "name": "Application_", "alias": "test", "company": { "company_id": "dec5418e58694d90a65d6c38e3d226db", "name": "Sample demo", "api_url": "https://kr-api.eformsign.com" } }, "oauth_token": { "expires_in": 3600, "token_type": "JWT", "refresh_token": "8fd0a3c1-44dc-4a03-96ad-01fa34cd159c", "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJlZm9ybXNpZ24uaWFtIiwiY29udGV4dCI6eyJjbGllbnRJZCI6IjY4MDk0ZWVhMjVhZjRhNjI5ZTI4ZGU5Y2ZlYzRlYmZjIiwiY2xpZW50S2V5IjoiZTNiM2IzZTUtMGEzMS00NTE1LWE5NzEtN2M4Y2FlNDI4NzZmIiwibWFuYWdlbWVudElkIjoiMzRhYWI4MDBjMmEwNDQwNThmZDRlZjc5OGFlY2RlY2EiLCJzY29wZXMiOiJzbWFydF9lZm9ybV9zY29wZSIsInR5cGUiOiJ1c2VyIiwidXNlck5hbWUiOiIzMmIzZDRmOC00MjdkLTRjZjQtOTZiYS1mYzAxNjIxNWRkNDciLCJ1c2VySWQiOiJhNTEyNGVkNmU2M2Y0OTMzOGJlOTA0MjVhNjFkYjlmNSIsInJlZnJlc2hUb2tlbiI6IjhmZDBhM2MxLTQ0ZGMtNGEwMy05NmFkLTAxZmEzNGNkMTU5YyJ9LCJjbGFpbSI6eyJjb21wYW55X2lkIjoiZGVjNTQxOGU1ODY5NGQ5MGE2NWQ2YzM4ZTNkMjI2ZGIiLCJhY2Nlc3Nfa2V5IjoiMzJiM2Q0ZjgtNDI3ZC00Y2Y0LTk2YmEtZmMwMTYyMTVkZDQ3In0sImV4cCI6MTYxMTU0MjIzNiwiaWF0IjoxNjExNTM4NjM2fQ.BltoXXBSabjXfpyLsZik9OZTE5XtLqe9lguMmJ_qfwZN1NyoVoxDqA5y1-_TLis7FvvNjfI1eegOroCZDZPFyXRaBxAj0CW8TijVjbhliJBuccHFyKXaJxmo_GMmTHYtxNNB1SUgLeFIrYROnpQndU8J7ZkfPDgYGwh1YSx-5s4" } }
Caution
Register the issued API key by clicking the Authorize button() in here. Note that you must enter Base64-encoded strings in the API key value. Go to https://www.base64encode.org/ and enter the issued API key to encode it.
Note
Make sure to enter API key value by clicking the Authorize button of Access Token API.
API for document creation and process¶
After generating a signature, you can use the following document API to create new documents, to inquiry document information, or to download completed document files(PDF and audit trail certificate), or attached files.
Caution
To use the document API, you need to get Access Token first. Enter the Access Token issued from Access Token API by clicking the Authorize button() in here.
Note
Make sure to enter Access Token value by clicking the Authorize button.
The followings are Document API provided in eformsign.
POST
: Create a new document_member
POST
: Create a new document_external recipients
GET
: Inquiry document information
GET
: Download document files_PDF and Audit trail certificate
DELETE
: Delete document
POST
: Resend a document_external recipients
GET
: Inquiry available template lists
POST
: Send in bulk
API for managing members and groups¶
You can use the following API to manage members and groups.
Caution
To use the document API, you need to get Access Token first. Enter the Access Token issued from Access Token API by clicking the Authorize button() in here.
Note
Make sure to enter Access Token value by clicking the Authorize button.
The followings are Member and group management API provided in eformsign.
API for managing groups¶
GET
: Inquiry group list
POST
: Add group
PATCH
: Edit group
DELETE
: Delete group
Note
Click here for more information about each eformsign document API.
API code¶
API status code¶
The API status code are as follows.
200¶
Code |
Description |
Remark |
---|---|---|
200 |
Success |
Success |
202¶
Code |
Description |
Remark |
---|---|---|
2020001 |
Generating a PDF |
-Downloadable when rerequesting within seconds to minutes. |
400¶
Code |
Description |
Remark |
---|---|---|
4000001 |
When omitting a required input value |
When the API’s required input value (header or parameter value) is omitted |
4000002 |
Authentication timeout |
When the API authentication request time has expired |
4000003 |
No API key |
When the API key is deleted or incorrectly entered |
4000004 |
No document |
When the document ID is incorrectly entered |
4000005 |
No company |
When the company is deleted |
403¶
Code |
Description |
Remark |
---|---|---|
4030001 |
No permission to access |
When the API is disabled |
4030002 |
Access token authentication error |
When the access token is incorrect |
4030003 |
Refresh token authentication error |
When the refresh token is incorrect |
4030004 |
Signature value authentication failure |
When the signature value is incorrect |
4030005 |
Unsupported API |
When calling an unsupported API |
405¶
Code |
Description |
Remark |
---|---|---|
4050001 |
Unsupported method |
When calling an unsupported method |
500¶
Code |
Description |
Remark |
---|---|---|
5000001~5000003 |
Server error |
When a server error occurs |
Step types¶
Type |
Code |
Description |
---|---|---|
Start |
00 |
Start step |
Complete |
01 |
Complete step |
Approval |
02 |
Approval step |
External |
03 |
External recipient step |
Accept |
04 |
Internal recipient step |
Participant |
05 |
Participant |
Reviewer |
06 |
Reviewer |
User types¶
Type |
Code |
Description |
---|---|---|
Internal member |
01 |
Whether the user is an internal member or not |
External recipient |
02 |
Whether the user is an external user or not |
Status types¶
Type |
Code |
Description |
---|---|---|
Draft |
00 |
Document saved as draft at start step |
In pregress |
01 |
Document requested for approval, requested to member or external recipient |
Correcting |
02 |
Document being corrected (member, document creator) |
Completed |
03 |
Document completed |
Rejected |
04 |
Document rejected by approver, member, or external recipient |
Voided |
05 |
Document voided |
Void requested |
06 |
Document requested to void to member |
Action types¶
Type |
Code |
Description |
---|---|---|
doc_tempsave |
001 |
Saving a document as a draft |
doc_create |
002 |
Creating a document |
doc_complete |
003 |
Completing a document |
doc_request_approval |
010 |
Requesting a document for approval |
doc_reject_approval |
011 |
Declining a document approval request |
doc_accept_approval |
012 |
Approving a document approval request |
doc_cancel |
013 |
Cancelling a document approval |
doc_request_reception |
020 |
Requesting a document to be approved by an internal recipient |
doc_reject_reception |
021 |
Requesting a document to be declined by an internal recipient |
doc_accept_reception |
022 |
An internal recipient approving a document approval request |
doc_accept_tempsave |
023 |
An internal recipient saving a document as a draft |
doc_request_outsider |
030 |
Requesting a document approval to an internal recipient |
doc_reject_outsider |
031 |
An external recipient declining a document |
doc_accept_outsider |
032 |
An external recipient approving a document |
doc_rerequest_outsider |
033 |
Rerequesting a document approval to an external recipient |
doc_open_outsider |
034 |
An external recipient opening a document |
doc_outsider_tempsave |
035 |
An external recipient saving a document as a draft |
doc_request_revoke |
040 |
Requesting a document to be voided |
doc_refuse_revoke |
041 |
Declining a document void request |
doc_revoke |
042 |
Voiding a document |
doc_update |
043 |
Correcting a document |
doc_cancel_update |
044 |
Cancelling a document correction |
doc_request_reject |
045 |
Requesting a document to be declined |
doc_refuse_reject |
046 |
Rejecting a document decline request |
doc_request_delete |
047 |
Requesting a document to be deleted |
doc_refuse_delete |
048 |
Rejecting a document deletion request |
doc_delete |
049 |
Deleting a document |
doc_complete_send_pdf |
050 |
Sending a PDF file of a completed document |
doc_transfer |
051 |
Transferring a document |
doc_request_participant |
060 |
Requesting a document to participant |
doc_reject_participant |
061 |
Rejecting a document by participant |
doc_accept_participant |
062 |
A participant approving a document |
doc_rerequest_participant |
063 |
A participant(external recipient) rerequesting a document |
doc_open_participant |
064 |
A participant(external recipient) opening a document |
doc_request_reviewer |
070 |
A reviewer requesting a document |
doc_reject_reviewer |
071 |
A reviewer rejecting a document |
doc_request_reviewer |
072 |
A reviewer approving a document |
doc_rerequest_reviewer |
073 |
A reviewer(external recipient) rerequesting a document |
doc_open_review |
074 |
A reviewer(external recipient) opening a document |
Detailed status type¶
Type |
Code |
Description |
---|---|---|
doc_tempsave |
001 |
Draft (when a document is saved as a draft by the initial creator) |
doc_create |
002 |
Document created |
doc_complete |
003 |
Document completed |
doc_update |
043 |
Document modified |
doc_request_delete |
047 |
Document deletion requested |
doc_delete |
049 |
Document deleted |
doc_request_revoke |
040 |
Document void requested |
doc_revoke |
042 |
Document voided |
doc_request_reject |
045 |
Document decline requested |
doc_request_approval |
010 |
Document approval requested |
doc_accept_approval |
012 |
Document approval request approved |
doc_reject_approval |
011 |
Document approval request declined |
doc_cancel |
013 |
Document approval request canceled |
doc_request_reception |
020 |
Document approval requested to internal recipient |
doc_accept_reception |
022 |
Document approval request approved by internal recipient |
doc_reject_reception |
021 |
Document approval request declined by internal recipient |
doc_request_outsider |
030 |
Document approval requested to external recipient |
doc_accept_outsider |
032 |
Document approved request approved by external recipient |
doc_reject_outsider |
031 |
Document approval request declined by external recipient |
doc_request_participant |
060 |
Document requested to participant |
doc_accept_participant |
062 |
Document accepted by participant |
doc_reject_participant |
061 |
Document rejected by participant |
doc_request_reviewer |
070 |
Document requested to reviewer |
doc_accept_reviewer |
072 |
Document accepted by reviewer |
doc_reject_reviewer |
071 |
Document rejected by reviewer |