Class: Assinafy::Resources::AccountResource

Inherits:
BaseResource show all
Defined in:
lib/assinafy/resources/account_resource.rb,
sig/assinafy.rbs

Overview

Accounts (workspaces): CRUD plus the per-account theme, KPI stats, and brand logo (upload/download/delete).

See https://api.assinafy.com.br/v1/docs for the Account Object and its related endpoints.

Constant Summary

Constants inherited from BaseResource

BaseResource::AUTH_HEADERS, BaseResource::PAGINATION_HEADERS, BaseResource::PATH_SEGMENT

Instance Method Summary collapse

Methods inherited from BaseResource

#initialize

Constructor Details

This class inherits a constructor from Assinafy::Resources::BaseResource

Instance Method Details

#create(payload) ⇒ Hash

Create a new account (workspace).

Examples:

Create an account

# Request: POST /accounts
# Body: { "name": "Acme Inc." }
client.accounts.create(name: 'Acme Inc.')

# Response (unwrapped data payload):
{
  'id' => 'account-id',
  'name' => 'Acme Inc.',
  'primary_color' => nil,
  'secondary_color' => nil,
  'created_at' => '2026-07-20T15:53:33Z'
}

Parameters:

  • payload (Hash)

Options Hash (payload):

  • :name (String) —

    required display name

  • :notification_sender_type (String) —

    "User" or "Account"

Returns:

  • (Hash) —

    the created account (envelope data unwrapped)

See Also:

  • /accounts


60
61
62
63
64
65
66
67
 
# File 'lib/assinafy/resources/account_resource.rb', line 60

def create(payload)
  body = body_params(require_payload(payload, 'Account payload'))
  require_present(body['name'], 'name')

  call('Failed to create account') do
    http_post('accounts', body)
  end
end

#delete(force: false, account_id_override: nil) ⇒ nil

Delete an account. Deletion is blocked while documents are pending. For an active paid subscription, pass force: true to cancel the subscription as part of deletion.

Examples:

Force-delete a throwaway account

# Request: DELETE /accounts/{account_id}
# Body: { "force": true }
client.accounts.delete(force: true, account_id_override: 'account-id')
# => nil

Parameters:

  • force (Boolean) (defaults to: false) —

    cancel an active paid subscription and continue deletion (default false); it does not bypass pending-document checks

  • account_id_override (String, nil) (defaults to: nil)
  • force: (Boolean) (defaults to: false)
  • account_id_override: (String, nil) (defaults to: nil)

Returns:

  • (nil) —

    the API returns data: []; the SDK normalizes this to nil

See Also:

  • /accounts/{account_id}


136
137
138
139
140
141
142
143
 
# File 'lib/assinafy/resources/account_resource.rb', line 136

def delete(force: false, account_id_override: nil)
  acc_id = ()
  force  = require_boolean(force, 'force')

  call_void('Failed to delete account') do
    http_delete("accounts/#{acc_id}", body: body_params(force: force))
  end
end

#delete_logo(account_id_override = nil) ⇒ nil

Delete the account brand logo.

Examples:

Delete the logo

# Request: DELETE /accounts/{account_id}/logo
client.accounts.
# => nil

Parameters:

  • account_id_override (String, nil) (defaults to: nil)

Returns:

  • (nil) —

    the documented success envelope has no data payload

See Also:

  • /accounts/{account_id}/logo


265
266
267
268
269
270
271
 
# File 'lib/assinafy/resources/account_resource.rb', line 265

def ( = nil)
  acc_id = ()

  call_void('Failed to delete account logo') do
    http_delete("accounts/#{acc_id}/logo")
  end
end

#download_logo(account_id_override = nil) ⇒ String

Download the account brand logo as raw image bytes.

Examples:

Download the logo and save it

# Request: GET /accounts/{account_id}/logo
bytes = client.accounts.
File.binwrite('logo.png', bytes)

Parameters:

  • account_id_override (String, nil) (defaults to: nil)

Returns:

  • (String) —

    binary image body

Raises:

See Also:

  • /accounts/{account_id}/logo


219
220
221
222
223
224
225
 
# File 'lib/assinafy/resources/account_resource.rb', line 219

def ( = nil)
  acc_id = ()

  call_binary('Failed to download account logo') do
    http_get("accounts/#{acc_id}/logo")
  end
end

#get(account_id_override = nil) ⇒ Hash

Fetch an account by ID (defaults to the client's account).

Examples:

Fetch the current account

# Request: GET /accounts/{account_id}
client.accounts.get

# Response (unwrapped data payload):
{
  'id' => 'account-id',
  'name' => 'MT',
  'primary_color' => nil,
  'secondary_color' => nil,
  'created_at' => '2026-05-12T18:05:11Z'
}

Parameters:

  • account_id_override (String, nil) (defaults to: nil)

Returns:

  • (Hash) —

    the account (envelope data unwrapped)

See Also:

  • /accounts/{account_id}


86
87
88
89
90
91
92
 
# File 'lib/assinafy/resources/account_resource.rb', line 86

def get( = nil)
  acc_id = ()

  call('Failed to fetch account') do
    http_get("accounts/#{acc_id}")
  end
end

#list ⇒ Hash{Symbol=>Array,nil}

List the accounts (workspaces) the authenticated user can access.

Examples:

List my accounts

# Request: GET /accounts
client.accounts.list

# Response (unwrapped data payload):
{
  data: [
    {
      'id' => 'account-id',
      'name' => 'MT',
      'roles' => ['owner'],
      'is_delete_allowed' => true,
      'created_at' => '2026-05-12T18:05:11Z'
    }
    # ... (one Hash per accessible account)
  ],
  meta: nil
}

Returns:

  • (Hash{Symbol=>Array,nil}) —

    { data: [Account, ...], meta: nil } (this endpoint sends no pagination headers)

See Also:

  • /accounts


34
35
36
37
38
 
# File 'lib/assinafy/resources/account_resource.rb', line 34

def list
  call_list('Failed to list accounts') do
    http_get('accounts')
  end
end

#stats(granularity: nil, month: nil, account_id_override: nil) ⇒ Array<Hash>

Note:

Documented in the API reference but not enabled on every environment — the sandbox currently returns 404 for this route.

Fetch per-account document KPIs.

Examples:

Fetch monthly KPIs

# Request: GET /accounts/{account_id}/stats?granularity=monthly&month=2026-06
client.accounts.stats(granularity: 'monthly', month: '2026-06')

# Response (unwrapped data payload):
[
  {
    'period' => '2026-06',
    'documents_uploaded' => 42,
    'documents_sent' => 37,
    'signature_requests' => 61,
    'signature_requests_notification_email' => 55,
    'signature_requests_notification_whatsapp' => 18,
    'signature_requests_notification_bypass' => 3,
    'signature_requests_verification_email' => 48,
    'signature_requests_verification_whatsapp' => 6,
    'signature_requests_verification_bypass' => 3,
    'signature_requests_verification_digital_certificate' => 4,
    'signature_requests_viewed' => 44,
    'signature_requests_completed' => 52,
    'documents_certified' => 30
  }
]

Parameters:

  • granularity (String, nil) (defaults to: nil) —

    "monthly" or "daily"

  • month (String, nil) (defaults to: nil) —

    e.g. "2026-06"

  • account_id_override (String, nil) (defaults to: nil)
  • granularity: (String, nil) (defaults to: nil)
  • month: (String, nil) (defaults to: nil)
  • account_id_override: (String, nil) (defaults to: nil)

Returns:

  • (Array<Hash>) —

    one KPI entry per period

See Also:

  • /accounts/{account_id}/stats


201
202
203
204
205
206
207
 
# File 'lib/assinafy/resources/account_resource.rb', line 201

def stats(granularity: nil, month: nil, account_id_override: nil)
  acc_id = ()

  call_array('Failed to fetch account stats') do
    http_get("accounts/#{acc_id}/stats", query_params(granularity: granularity, month: month))
  end
end

#theme(account_id_override = nil) ⇒ Hash

Fetch the account's public theme (name, brand colors, logo URL).

Examples:

Fetch the account theme

# Request: GET /accounts/{account_id}/theme
client.accounts.theme

# Response (unwrapped data payload):
{
  'account_name' => 'MT',
  'primary_color' => '2072b9',
  'secondary_color' => 'ffffff',
  'logo' => nil
}

Parameters:

  • account_id_override (String, nil) (defaults to: nil)

Returns:

  • (Hash) —

    { 'account_name' =>, 'primary_color' =>, 'secondary_color' =>, 'logo' => }

See Also:

  • /accounts/{account_id}/theme


161
162
163
164
165
166
167
 
# File 'lib/assinafy/resources/account_resource.rb', line 161

def theme( = nil)
  acc_id = ()

  call('Failed to fetch account theme') do
    http_get("accounts/#{acc_id}/theme")
  end
end

#update(payload, account_id_override = nil) ⇒ Hash

Update an account.

Examples:

Rename the current account

# Request: PUT /accounts/{account_id}
# Body: { "name": "Acme Renamed" }
client.accounts.update(name: 'Acme Renamed')

# Response (unwrapped data payload):
{
  'id' => 'account-id',
  'name' => 'Acme Renamed',
  'primary_color' => nil,
  'secondary_color' => nil,
  'created_at' => '2026-07-20T15:53:33Z'
}

Parameters:

  • payload (Hash) —

    name and/or notification_sender_type

  • account_id_override (String, nil) (defaults to: nil)

Returns:

  • (Hash) —

    the updated account (envelope data unwrapped)

See Also:

  • /accounts/{account_id}


113
114
115
116
117
118
119
120
 
# File 'lib/assinafy/resources/account_resource.rb', line 113

def update(payload,  = nil)
  acc_id = ()
  body   = body_params(require_payload(payload, 'Account payload'))

  call('Failed to update account') do
    http_put("accounts/#{acc_id}", body)
  end
end

#upload_logo(source, account_id_override = nil) ⇒ nil, Hash

Upload (replace) the account brand logo.

Examples:

Upload a PNG logo

# Request: POST /accounts/{account_id}/logo (multipart/form-data)
# Body: file=<binary image/png>
client.accounts.('/path/to/logo.png')

# Current sandbox response (unwrapped data payload):
{
  'mime_type' => 'image/png',
  'version' => 1784562814,
  'updated_at' => '2026-07-20T15:53:35Z'
}
# => nil when the API returns the documented no-data envelope

Parameters:

  • source (String, Hash) —

    a path to an image, or a Hash with :file_path (path) or :buffer + :file_name (raw bytes).

  • account_id_override (String, nil) (defaults to: nil)

Returns:

  • (nil, Hash) —

    nil for the OpenAPI's no-data envelope; the current sandbox returns { 'mime_type' =>, 'version' =>, 'updated_at' => }

See Also:

  • /accounts/{account_id}/logo


247
248
249
250
251
252
253
254
 
# File 'lib/assinafy/resources/account_resource.rb', line 247

def (source,  = nil)
  acc_id = ()
  buffer, file_name = read_source(source)

  call('Failed to upload account logo') do
    http_post("accounts/#{acc_id}/logo", { file: file_part(buffer, file_name) })
  end
end