DocuSign.Connection (DocuSign v2.2.1)

View Source

The module is intended to be used to establish a connection with DocuSign eSignature API and then perform requests to it.

JWT Impersonation Example

iex> user_id = "74830914-547328-5432-5432543"
iex> account_id = "61ac4bd1-c83c-4aa6-8654-ddf3tg5"
iex> {:ok, conn} = DocuSign.Connection.get(user_id)
iex> {:ok, users} = DocuSign.Api.Users.users_get_users(conn, account_id)
{:ok, %DocuSign.Model.UserInformationList{...}}

OAuth2 Authorization Code Flow Example

# Using the OAuth2 Authorization Code Strategy
iex> oauth_client = DocuSign.OAuth.AuthorizationCodeStrategy.client(
...>   redirect_uri: "https://yourapp.com/auth/callback"
...> )
...> |> DocuSign.OAuth.AuthorizationCodeStrategy.get_token!(code: "auth_code")
iex> user_info = DocuSign.OAuth.AuthorizationCodeStrategy.get_user_info!(oauth_client)
iex> account = Enum.find(user_info["accounts"], &(&1["is_default"] == "true"))
iex> {:ok, conn} = DocuSign.Connection.from_oauth_client(
...>   oauth_client,
...>   account_id: account["account_id"],
...>   base_uri: account["base_uri"] <> "/restapi"
...> )
iex> {:ok, users} = DocuSign.Api.Users.users_get_users(conn, account["account_id"])
{:ok, %DocuSign.Model.UserInformationList{...}}

Summary

Functions

Detects the environment type based on the API base URI.

Automatically determines the appropriate OAuth hostname based on a base URI.

Downloads a file from the DocuSign API.

Create new connection from OAuth2 client with tokens.

Creates a connection with automatic environment detection from OAuth client.

Create new connection for provided user ID using JWT impersonation.

Makes a request.

Types

oauth_error()

@type oauth_error() :: OAuth2.Response.t() | OAuth2.Error.t()

t()

@type t() :: %DocuSign.Connection{
  app_account: map() | nil,
  client: OAuth2.Client.t() | nil
}

Functions

detect_environment(base_uri)

@spec detect_environment(String.t()) :: :sandbox | :production

Detects the environment type based on the API base URI.

Parameters

  • base_uri - The DocuSign API base URI

Returns

  • :sandbox for sandbox/demo environments
  • :production for production environments

Examples

iex> DocuSign.Connection.detect_environment("https://demo.docusign.net")
:sandbox

iex> DocuSign.Connection.detect_environment("https://na3.docusign.net")
:production

determine_hostname(base_uri)

@spec determine_hostname(String.t()) :: String.t()

Automatically determines the appropriate OAuth hostname based on a base URI.

This function provides a convenient way to automatically configure the correct OAuth hostname by analyzing the provided base URI for sandbox/demo patterns. This is useful when creating connections with different environments.

Parameters

Returns

  • "account-d.docusign.com" for sandbox/demo environments
  • "account.docusign.com" for production environments

Examples

# Automatically detect sandbox environment
iex> DocuSign.Connection.determine_hostname("https://demo.docusign.net/restapi")
"account-d.docusign.com"

# Automatically detect production environment
iex> DocuSign.Connection.determine_hostname("https://na3.docusign.net/restapi")
"account.docusign.com"

Usage with OAuth2 Configuration

# Use automatic detection for OAuth2 setup
base_uri = "https://demo.docusign.net/restapi"
hostname = DocuSign.Connection.determine_hostname(base_uri)

Application.put_env(:docusign, :hostname, hostname)

download_file(conn, url, opts \\ [])

Downloads a file from the DocuSign API.

This is a convenience function that wraps DocuSign.FileDownloader.download/3. It provides an easy way to download documents, attachments, and other files from DocuSign APIs with automatic filename extraction and flexible storage options.

Options

See DocuSign.FileDownloader.download/3 for all available options.

Examples

# Download envelope document to temporary file
{:ok, temp_path} = DocuSign.Connection.download_file(conn, 
  "/v2.1/accounts/123/envelopes/456/documents/1")

# Download to memory
{:ok, {content, filename, content_type}} = DocuSign.Connection.download_file(conn, url,
  strategy: :memory)

# Download with custom temp options
{:ok, path} = DocuSign.Connection.download_file(conn, url,
  temp_options: [prefix: "contract", suffix: ".pdf"])

from_oauth_client(oauth_client, opts \\ [])

@spec from_oauth_client(
  OAuth2.Client.t(),
  keyword()
) :: {:ok, t()} | {:error, atom()}

Create new connection from OAuth2 client with tokens.

This function creates a connection using an OAuth2.Client obtained through the authorization code flow with DocuSign.OAuth.AuthorizationCodeStrategy.

Parameters

  • oauth_client - OAuth2.Client with valid access token
  • opts - Keyword list of options:
    • :account_id - DocuSign account ID (required)
    • :base_uri - API base URI (required)

Examples

# Using OAuth2 Authorization Code Strategy
oauth_client = DocuSign.OAuth.AuthorizationCodeStrategy.client(
  redirect_uri: "https://yourapp.com/callback"
)
|> DocuSign.OAuth.AuthorizationCodeStrategy.get_token!(code: auth_code)

# Get user info to find account details
user_info = DocuSign.OAuth.AuthorizationCodeStrategy.get_user_info!(oauth_client)
account = Enum.find(user_info["accounts"], &(&1["is_default"] == "true"))

# Create connection
{:ok, conn} = from_oauth_client(
  oauth_client,
  account_id: account["account_id"],
  base_uri: account["base_uri"] <> "/restapi"
)

Returns

  • {:ok, connection} - Success with connection struct
  • {:error, reason} - Failure with error reason

Notes

  • The base_uri should be the full API endpoint (e.g., "https://demo.docusign.net/restapi")
  • Use the account information from the user info endpoint to get correct base_uri
  • The connection can be used immediately with DocuSign API functions

from_oauth_client_with_detection(oauth_client, opts \\ [])

@spec from_oauth_client_with_detection(
  OAuth2.Client.t(),
  keyword()
) :: {:ok, t()} | {:error, atom()}

Creates a connection with automatic environment detection from OAuth client.

This is an enhanced version of from_oauth_client/2 that can automatically determine the OAuth hostname from the base_uri if not already configured.

Parameters

  • oauth_client - The OAuth2.Client with valid tokens
  • opts - Options including:
    • :account_id (required) - The DocuSign account ID
    • :base_uri (required) - The API base URI
    • :auto_detect_hostname (optional) - Whether to automatically set hostname config

Options

  • :auto_detect_hostname - If true, automatically configures the application hostname based on the base_uri environment detection. Default: false

Examples

# Create connection with automatic hostname detection
{:ok, conn} = DocuSign.Connection.from_oauth_client_with_detection(
  oauth_client,
  account_id: "12345",
  base_uri: "https://demo.docusign.net/restapi",
  auto_detect_hostname: true
)

get(user_id)

@spec get(String.t()) :: {:ok, t()} | {:error, oauth_error()}

Create new connection for provided user ID using JWT impersonation.

request(conn, opts \\ [])

@spec request(t(), Keyword.t()) :: {:ok, Tesla.Env.t()} | {:error, any()}

Makes a request.

Options

  • :ssl_options - Override SSL options for this specific request
  • All other options are passed through to Tesla

Examples

# Use custom CA certificate for this request
DocuSign.Connection.request(conn,
  method: :get,
  url: "/accounts",
  ssl_options: [cacertfile: "/custom/ca.pem"]
)