Class: Assinafy::Resources::TagResource

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

Overview

Workspace-scoped tag management.

Tags are labels that can be attached to documents and templates for filtering and organization.

See https://api.assinafy.com.br/v1/docs#tag for the full documentation of these 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, account_id_override = nil) ⇒ Hash

Create a tag in the workspace.

Returns 409 Conflict if a tag with the same name (case-insensitive) already exists.

Examples:

Create a tag

# Request: POST /accounts/{account_id}/tags
# Body: { "name": "Contracts", "color": "ff8800" }
client.tags.create(name: 'Contracts', color: 'ff8800')

# Response (unwrapped data payload):
{
  'resource' => 'tag',
  'id' => '1032009e69e366ca5adc879ef26c',
  'name' => 'Contracts',
  'color' => 'ff8800',
  'created_at' => '2026-06-05T21:21:19Z',
  'updated_at' => '2026-06-05T21:21:19Z'
}

Parameters:

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

Options Hash (payload):

  • :name (String) —

    required tag display name

  • :color (String, nil) —

    optional 6-character hex color

Returns:

  • (Hash) —

    the created tag object

Raises:

See Also:

  • /accounts/{account_id}/tags


71
72
73
74
75
76
77
78
 
# File 'lib/assinafy/resources/tag_resource.rb', line 71

def create(payload,  = nil)
  acc_id = ()
  body   = tag_payload(payload, require_name: true)

  call('Failed to create tag') do
    http_post("accounts/#{acc_id}/tags", body)
  end
end

#delete(tag_id, account_id_override = nil, force: false) ⇒ Hash

Delete a tag. By default, deletion fails with 409 Conflict if the tag is attached to any document or template. Pass force: true to detach it from everything and delete it; the documents and templates themselves are not deleted.

Examples:

Delete a tag, detaching it from documents and templates first

# Request: DELETE /accounts/{account_id}/tags/{tag_id}?force=true
client.tags.delete('1032009e69e366ca5adc879ef26c', force: true)

# Response (unwrapped data payload):
{ 'deleted' => true }

Parameters:

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

Returns:

  • (Hash) —

    { 'deleted' => true }

See Also:

  • /accounts/{account_id}/tags/{tag_id}


142
143
144
145
146
147
148
149
150
151
 
# File 'lib/assinafy/resources/tag_resource.rb', line 142

def delete(tag_id,  = nil, force: false)
  acc_id = ()
  tid    = require_id(tag_id, 'Tag ID')
  force  = require_boolean(force, 'force')
  params = force ? { force: true } : {}

  call('Failed to delete tag') do
    http_delete("accounts/#{acc_id}/tags/#{tid}", params)
  end
end

#list(params = {}, account_id_override = nil) ⇒ Hash{Symbol=>Array,Hash}

List tags in the workspace, ordered alphabetically by name.

Examples:

List tags matching a search term

# Request: GET /accounts/{account_id}/tags?search=doc
client.tags.list(search: 'doc')

# Response (unwrapped data payload):
{
  data: [
    {
      'id' => '1031f6544019bafc410c6c5317f4',
      'name' => 'customer-agreement',
      'color' => nil,
      'created_at' => '2026-06-05T16:33:35Z',
      'updated_at' => '2026-06-05T16:33:35Z'
    }
    # ... (each entry also carries 'resource' => 'tag')
  ],
  meta: { current_page: 1, per_page: 3, total: 13, last_page: 5 }
}

Parameters:

  • params (Hash) (defaults to: {}) —

    documented search query; additional deployment-specific keys are forwarded

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

Returns:

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

    { data: [...], meta: { ... } }

See Also:

  • /accounts/{account_id}/tags


37
38
39
40
41
42
43
 
# File 'lib/assinafy/resources/tag_resource.rb', line 37

def list(params = {},  = nil)
  acc_id = ()

  call_list('Failed to list tags') do
    http_get("accounts/#{acc_id}/tags", params)
  end
end

#update(tag_id, payload, account_id_override = nil) ⇒ Hash

Update a tag's name and/or color. Documents and templates already attached to the tag keep their relationship; only the tag's own attributes change. Returns 409 Conflict if another tag already uses the new name (case-insensitive).

At least one of :name or :color must be supplied: an empty payload raises, and a blank :name raises.

Examples:

Rename a tag and recolor it

# Request: PUT /accounts/{account_id}/tags/{tag_id}
# Body: { "name": "Sales Contracts", "color": "112233" }
client.tags.update('1032009e69e366ca5adc879ef26c',
                   name: 'Sales Contracts', color: '112233')

# Response (unwrapped data payload):
{
  'resource' => 'tag',
  'id' => '1032009e69e366ca5adc879ef26c',
  'name' => 'Sales Contracts',
  'color' => '112233',
  'created_at' => '2026-06-05T21:21:19Z',
  'updated_at' => '2026-06-05T22:00:00Z'
}

Clear a tag's color (pass nil explicitly)

# Request: PUT /accounts/{account_id}/tags/{tag_id}
# Body: { "color": null }
client.tags.update('1032009e69e366ca5adc879ef26c', color: nil)
#=> { 'resource' => 'tag', 'id' => '1032009e69e366ca5adc879ef26c', 'color' => nil, ... }

Parameters:

  • tag_id (String)
  • payload (Hash)
  • account_id_override (String, nil) (defaults to: nil)

Options Hash (payload):

  • :name (String) —

    optional new name

  • :color (String, nil) —

    optional new color; nil clears it

Returns:

  • (Hash) —

    the updated tag object

Raises:

See Also:

  • /accounts/{account_id}/tags/{tag_id}


116
117
118
119
120
121
122
123
124
 
# File 'lib/assinafy/resources/tag_resource.rb', line 116

def update(tag_id, payload,  = nil)
  acc_id = ()
  tid    = require_id(tag_id, 'Tag ID')
  body   = tag_payload(payload, require_name: false)

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