Tags

Tags are flexible metadata elements that can be associated with voucher statements, allowing for additional categorization and filtering of financial data.

Endpoints

List Tags

GET /api/v2/tags

Retrieves a paginated list of tags.

Query Parameters

Response

{
  "data": [
    {
      "id": 123,
      "name": "Travel Expenses",
      "client_account_id": 456,
      "sequence_number": 1,
      "created_at": "2024-04-15T10:00:00Z",
      "updated_at": "2024-04-15T10:00:00Z",
      "created_by_id": 789,
      "updated_by_id": 789
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 50,
    "records": 1
  }
}

Get Tag

GET /api/v2/tags/{id}

Retrieves a specific tag by ID.

Response

{
  "id": 123,
  "name": "Travel Expenses",
  "client_account_id": 456,
  "sequence_number": 1,
  "created_at": "2024-04-15T10:00:00Z",
  "updated_at": "2024-04-15T10:00:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Create Tag

POST /api/v2/tags

Creates a new tag.

Request Body

Example Request

{
  "name": "Travel Expenses",
  "client_account_id": 456
}

Response

{
  "id": 123,
  "name": "Travel Expenses",
  "client_account_id": 456,
  "sequence_number": 1,
  "created_at": "2024-04-15T10:00:00Z",
  "updated_at": "2024-04-15T10:00:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Update Tag

PUT /api/v2/tags/{id}

Updates an existing tag.

Request Body

Example Request

{
  "name": "International Travel"
}

Response

{
  "id": 123,
  "name": "International Travel",
  "client_account_id": 456,
  "sequence_number": 1,
  "created_at": "2024-04-15T10:00:00Z",
  "updated_at": "2024-04-15T15:30:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Deactivate Tag

DELETE /api/v2/tags/{id}

Deactivates a tag by setting its is_active status to false. The tag record is preserved for historical purposes.

Response

{
  "id": 123,
  "name": "Travel Expenses",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": false,
  "created_at": "2024-04-15T10:00:00Z",
  "updated_at": "2024-04-15T16:00:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Deactivation Validation

When attempting to deactivate a tag, the system performs validation to ensure data integrity:

• Balance Checking: The system checks if any accounting accounts with mandatory tag dimensions have non-zero balances for this specific tag.
• Validation Failure: If any accounts have non-zero balances, the deactivation is denied with a 400 Bad Request error.
• Error Details: The error message includes specific account codes and their balances to help identify which transactions need to be resolved.

Example Error Response

{
    "error": "Cannot deactivate tag: account 6000: 3200.00, account 6100: -800.00",
    "status": 400
}

This validation ensures that tags cannot be deactivated while they still have outstanding balances, maintaining the integrity of your accounting records.

Voucher Statement Integration

Tags can be associated with voucher statements, allowing for multiple tags per voucher.

Example Voucher Statement with Tags

{
  "id": 456,
  "voucher_id": 789,
  "client_account_id": 456,
  "tags": [
    {
      "id": 123,
      "name": "Travel Expenses",
      "sequence_number": 1,
      "client_account_id": 456
    },
    {
      "id": 124,
      "name": "Marketing",
      "sequence_number": 2,
      "client_account_id": 456
    }
  ],
  "purpose": "Business trip to client meeting",
  "additional_information": "Annual strategic planning session"
}

Error Responses

Business Rules

1. Tags are associated with a specific client account
2. Users must have access to the client account to manage its tags
3. The client_account_id cannot be changed after tag creation
4. Each tag is automatically assigned a unique sequence number within its client account
5. Tags can be associated with multiple voucher statements (many-to-many relationship)
6. Tag names must be unique within a client account
7. Creation and update timestamps and user IDs are automatically tracked

Common Use Cases

1. Categorizing expenses by purpose or project
2. Adding supplementary search criteria to vouchers
3. Grouping related vouchers for reporting
4. Creating custom dimensions for financial analysis

Best Practices

1. Use concise, descriptive tag names
2. Maintain consistent naming conventions
3. Avoid creating too many similar tags
4. Use tags as an additional dimension rather than replacing existing categorization systems
5. Consider creating a tagging strategy for consistency across the organization