Visma.Api (Visma v0.1.0)

Visma API Elixir implementation. This module offers a way to play with visma API. It has been tested on the demo API, and should work as well on the main one. This is a low level interface, you should probably use other module to directly craft the correct request.

Link to this section Summary

Types

add_user_to_group_arguments()

campaign_name()

cancel_signing_arguments()

cancel_transaction_arguments()

create_group_arguments()

create_user_arguments()

document()

documents()

email()

get_campaigns_arguments()

get_rejection_comment_arguments()

get_signing_arguments()

get_signing_status_arguments()

get_template_messages_arguments()

group_id()

group_name()

initiate_campaign_arguments()

initiate_signing_arguments()

login_arguments()

name()

options()

password()

recipient()

recipients()

sender()

signing_token()

template_id()

token()

transaction_token()

user_name()

Functions

add_user_to_group(api, args)

TODO: not tested yet.

cancel_signing(api, args)

TODO: not tested yet.

cancel_transaction(api, args)

Cancel a transaction. The transaction id can be found with get_signing_status/2 function.

create_group(api, args)

TODO: not tested yet.

create_user(api, args)

TODO: not tested yet.

get_campaigns(api, args)

Get all running campaigns.

get_groups(api)

TODO: not tested yet.

get_rejection_comment(api, args)

TODO: not tested yet.

get_signing(api, args)

Get signing state of a specific signature.

get_signing_status(api, args)

Get the signing status of each documents. A transaction id is associated with each of them, and can be cancelled with cancel_transaction/2 function.

get_signing_templates(api)

Returns a signing template available. A signing template is needed when using initiate_signing/2 function. Choose one method, and extract its id.

get_template_messages(api, args)

TODO: not tested yet.

initiate_campaign(api, args)

Initiate a new campaign.

initiate_signing(api, args)

This function initiate a signing procedure by sending information about a sender, a list of recipients and a list of document.

login2(api, args)

Similar than login/2 except it requires a token to be set.

Log to Visma API using email and password as credentials. A valid connection returns a token. Be careful, the token has a limited lifetime, if you are reusing it, you should ensure it is still valid.

new()

Initialize a new Visma.Api data-structure used to generate request. By default, the base_url key is initialized using environment but it can be bypassed by using new/1 function.

new(opts)

prepare(api)

Prepare a request by adding a token or any mandatory elements.

prepare(api, args)

send(api)

Send a request and wait for its response. It automatically uses prepare/1 function to prepare the request. Reponse is parsed using parse_response/1 internal function.

Link to this section Types

add_user_to_group_arguments()

@type add_user_to_group_arguments() :: [email: email(), group_id: integer()]

campaign_name()

@type campaign_name() :: String.t()

cancel_signing_arguments()

@type cancel_signing_arguments() :: [{:signing_token, signing_token()}]

cancel_transaction_arguments()

@type cancel_transaction_arguments() :: [{:transaction_token, token()}]

create_group_arguments()

@type create_group_arguments() :: [name: String.t(), description: String.t()]

create_user_arguments()

@type create_user_arguments() :: [
  email: email(),
  language_id: integer(),
  phone: String.t(),
  role_id: integer(),
  send_welcome_email: boolean()
]

document()

@type document() :: map()

documents()

@type documents() :: [document(), ...]

email()

@type email() :: String.t()

get_campaigns_arguments()

@type get_campaigns_arguments() :: [{:reference, token()}]

get_rejection_comment_arguments()

@type get_rejection_comment_arguments() :: [{:signing_token, signing_token()}]

get_signing_arguments()

@type get_signing_arguments() :: [{:signing_token, signing_token()}]

get_signing_status_arguments()

@type get_signing_status_arguments() :: [{:signing_token, signing_token()}]

get_template_messages_arguments()

@type get_template_messages_arguments() :: [{:template_id, Ecto.UUID.t()}]

group_id()

@type group_id() :: Ecto.UUID.t()

group_name()

@type group_name() :: String.t()

initiate_campaign_arguments()

@type initiate_campaign_arguments() :: [
  signing_template_id: Ecto.UUID.t(),
  recipients: [],
  site: String.t(),
  transaction_state_change_url: String.t(),
  last_reminder: integer(),
  signing_method: integer()
]

initiate_signing_arguments()

@type initiate_signing_arguments() :: [{:signing_request, map()}]

login_arguments()

@type login_arguments() :: [email: email(), password: password()] | Keyword.t()

name()

@type name() :: String.t()

options()

@type options() :: Keyword.t()

password()

@type password() :: String.t()

recipient()

@type recipient() :: map()

recipients()

@type recipients() :: [recipient(), ...]

sender()

@type sender() :: Visma.Api.Types.Sender.sender()

signing_token()

@type signing_token() :: Ecto.UUID.t()

template_id()

@type template_id() :: Ecto.UUID.t()

token()

@type token() :: Ecto.UUID.t()

transaction_token()

@type transaction_token() :: Ecto.UUID.t()

user_name()

@type user_name() :: String.t()

Link to this section Functions

add_user_to_group(api, args)

@spec add_user_to_group(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  add_user_to_group_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

TODO: not tested yet.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#069afa57-89d7-4738-921b-d369570bd2e0

examples
Examples

cancel_signing(api, args)

@spec cancel_signing(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  cancel_signing_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

TODO: not tested yet.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#a878b950-fe29-4610-b68f-94fcf3e530c9

examples
Examples

cancel_transaction(api, args)

@spec cancel_transaction(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  cancel_transaction_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

Cancel a transaction. The transaction id can be found with get_signing_status/2 function.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#97f933ae-2da5-44cf-98e2-612fa95bf0ae

examples
Examples

create_group(api, args)

@spec create_group(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  create_group_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

TODO: not tested yet.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#a8f2fa53-7d8f-4e5b-97b9-34bb1c232dd6

examples
Examples

create_user(api, args)

@spec create_user(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  create_user_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

TODO: not tested yet.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#ab6343f6-c77b-4b38-a0f8-5d04014bfb08

examples
Examples

get_campaigns(api, args)

@spec get_campaigns(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  get_campaigns_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

Get all running campaigns.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#d8dd97cf-dd49-4737-957d-442718a99b05

examples
Examples

get_groups(api)

@spec get_groups(%Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

TODO: not tested yet.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#7720dbe8-cd53-4d6a-9bc2-ce43aab28b82

examples
Examples

get_rejection_comment(api, args)

@spec get_rejection_comment(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  get_rejection_comment_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

TODO: not tested yet.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#57a67bc6-3680-41e7-ba3b-01044b8482db

examples
Examples

get_signing(api, args)

@spec get_signing(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  get_signing_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

Get signing state of a specific signature.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#7893bed4-4e05-4cdb-902c-661c2440ed8e

examples
Examples

iex> api = Visma.Api.new()
iex> request = Visma.Api.get_signing_arguments(token: "my-token", signing_token: "my-signing-token")
iex> Visma.Api.send(request)

get_signing_status(api, args)

@spec get_signing_status(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  get_signing_status_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

Get the signing status of each documents. A transaction id is associated with each of them, and can be cancelled with cancel_transaction/2 function.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#f4e61e46-c91a-4470-8ada-fbb21085db45

examples
Examples

get_signing_templates(api)

@spec get_signing_templates(%Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

Returns a signing template available. A signing template is needed when using initiate_signing/2 function. Choose one method, and extract its id.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#383ab277-6264-4847-9e6f-32b41670733d

example
example

iex> api = Visma.Api.new()
iex> request = Visma.Api.get_signing_templates(api, token: "my_token")
iex> Visma.Api.send(request)
{:ok, %{ "SigningTemplateItems" => templates }}

get_template_messages(api, args)

@spec get_template_messages(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  Keyword.t()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

TODO: not tested yet.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#e32a8a09-902c-4b43-bb99-c784fe010299

examples
Examples

initiate_campaign(api, args)

@spec initiate_campaign(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  initiate_campaign_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

Initiate a new campaign.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#233559d9-1668-4c10-8c6b-cbb87276b58f

examples
Examples

initiate_signing(api, args)

@spec initiate_signing(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  initiate_signing_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

This function initiate a signing procedure by sending information about a sender, a list of recipients and a list of document.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#71c7e5fd-0239-4bf8-ab5a-93f38a12aa4c

example
example

iex> signing = Visma.Signing.new()
iex> signing = Visma.Signing.request(signing,
  signing_template_id: "template_id"
)
iex> signing = Visma.Signing.sender(signing, ...)
iex> signing = Visma.Signing.document(signing, ...)
iex> signing = Visma.Signing.recipient(signing, ...)
iex> signing_map = Visma.Signing.to_map(signing)
iex> api = Visma.Api.new()
iex> request = Visma.Api.initiate_signing(api,
  token: "my-token",
  signing_request: signing_map
)
iex> Visma.Api.send(request)

login2(api, args)

@spec login2(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  login_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

Similar than login/2 except it requires a token to be set.

examples
Examples

iex> api = Visma.Api.new()
iex> request = Visma.Api.login(api,
  email: "foo@bar.com",
  password: "my_password"
)
iex> prepared_request = Visma.Api.prepare(request, token: token)
iex> Visma.Api.send(prepared_request)
{:ok, "00000000-0000-0000-0000-000000000000"}

login(api, args)

@spec login(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  login_arguments()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

Log to Visma API using email and password as credentials. A valid connection returns a token. Be careful, the token has a limited lifetime, if you are reusing it, you should ensure it is still valid.

see: https://documenter.getpostman.com/view/4950720/RWMLJkeo#563cb993-f2f6-4ca2-b8e7-7d61c240e714

Simple example, change with the correctly values.

iex> api = Visma.Api.new()
iex> request = Visma.Api.login(api,
  email: "foo@bar.com",
  password: "my_password"
)
iex> prepared_request = Visma.Api.prepare(request)
iex> Visma.Api.send(prepared_request)
{:ok, "00000000-0000-0000-0000-000000000000"}

A Working example with demo credentials from official. It will return a valid token.

iex> api = Visma.Api.new(base_url: "https://demo.vismaaddo.net/WebService/v2.0/restsigningservice.svc")
iex> request = Visma.Api.login(api,
  email: "fake.email.for.api.test@visma.com",
  password: Base.decode64!("c/SjPSMTRcZW1yzcvs6qdUOrnx4GyHoH0fyD0h9XnAAYP7PP/sNgTjKDMSUGlZAXB+ZFmm20JWK6hrsgJHsGYw=="),
  password_is_base64: true)
)
iex> Visma.Api.send(request)
{:ok, "00000000-0000-0000-0000-000000000000"}

Using an invalid email

iex> api = Visma.Api.new()
iex> request = Visma.Api.login(api,
  email: "invalid@email.com",
  password: "test"
)
iex> Visma.Api.send(request)
{:error, [%{"FaultCode" => 900, "Reason" => "Invalid email"}]}

new()

@spec new() :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

Initialize a new Visma.Api data-structure used to generate request. By default, the base_url key is initialized using environment but it can be bypassed by using new/1 function.

TODO: sanitize base_url field

examples
Examples

iex> Visma.Api.new()

iex> Visma.Api.new(base_url: "http://my-url.com/api")

new(opts)

@spec new(Keyword.t()) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

prepare(api)

Prepare a request by adding a token or any mandatory elements.

prepare(api, args)

@spec prepare(
  %Visma.Api{
    api_path: term(),
    base_url: term(),
    body: term(),
    full_url: term(),
    headers: term(),
    method: term(),
    query: term(),
    token: term(),
    token_in_body: term(),
    token_required: term()
  },
  Keyword.t()
) :: %Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}

send(api)

@spec send(%Visma.Api{
  api_path: term(),
  base_url: term(),
  body: term(),
  full_url: term(),
  headers: term(),
  method: term(),
  query: term(),
  token: term(),
  token_in_body: term(),
  token_required: term()
}) :: {:ok, any()} | {:error, any()}

Send a request and wait for its response. It automatically uses prepare/1 function to prepare the request. Reponse is parsed using parse_response/1 internal function.

Settings Visma.Api (Visma v0.1.0)

Link to this section Summary

Types

Functions

Link to this section Types

add_user_to_group_arguments()

campaign_name()

cancel_signing_arguments()

cancel_transaction_arguments()

create_group_arguments()

create_user_arguments()

document()

documents()

email()

get_campaigns_arguments()

get_rejection_comment_arguments()

get_signing_arguments()

get_signing_status_arguments()

get_template_messages_arguments()

group_id()

group_name()

initiate_campaign_arguments()

initiate_signing_arguments()

login_arguments()

name()

options()

password()

recipient()

recipients()

sender()

signing_token()

template_id()

token()

transaction_token()

user_name()

Link to this section Functions

add_user_to_group(api, args)

examples Examples

cancel_signing(api, args)

examples Examples

cancel_transaction(api, args)

examples Examples

create_group(api, args)

examples Examples

create_user(api, args)

examples Examples

get_campaigns(api, args)

examples Examples

get_groups(api)

examples Examples

get_rejection_comment(api, args)

examples Examples

get_signing(api, args)

examples Examples

get_signing_status(api, args)

examples Examples

get_signing_templates(api)

example example

get_template_messages(api, args)

examples Examples

initiate_campaign(api, args)

examples Examples

initiate_signing(api, args)

example example

login2(api, args)

examples Examples

login(api, args)

example example

new()

examples Examples

new(opts)

prepare(api)

prepare(api, args)

send(api)

Visma.Api (Visma v0.1.0)

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

example
example

examples
Examples

examples
Examples

example
example

examples
Examples

example
example

examples
Examples