/admin/comments

Path: /admin/comments
Namespace: admin
Resource: comments

Overview

The Comment resource allows adding notes, annotations, and comments to various resources in the system. Comments support threaded discussions and can be associated with invoices, addresses, items, and other resources.

Relationships

Model Associations

Comment connects to the following resources:

User

• Type: belongs_to via user_id
• Field: user_id
• Description: User who created the comment. Comments are always attributed to a user.
• Reverse: User has many comments (user.comments)
• API Access:
  • Direct: Included in comment response as user_id
  • Filter: GET /admin/comments.json?q[user_id_eq]=1
  • Filter by email: GET /admin/comments.json?q[user_email_cont]=admin
• Related Documentation: Users
• Example: Get all comments by a specific user:

  const comments = await fetch('/admin/comments.json?q[user_id_eq]=1', {
    credentials: 'include',
    headers: { 'Accept': 'application/json' }
  }).then(r => r.json());

Domain

• Type: belongs_to via host_id
• Field: host_id
• Description: Tenant domain for multi-tenant scoping. Comments are scoped to domains.
• Reverse: Domain has many comments (domain.comments)
• API Access:
  • Direct: Included in comment response as host_id
  • Filter: GET /admin/comments.json?q[host_id_eq]=1
• Related Documentation: Domains

Commentable (Polymorphic)

• Type: belongs_to polymorphic via commentable_type and commentable_id
• Fields: commentable_type, commentable_id
• Description: The resource this comment is attached to. Comments can be associated with any commentable resource (Invoice, Address, Item, etc.).
• Reverse: Commentable resources have many comments (e.g., invoice.comments, address.comments)
• API Access:
  • Direct: comment.commentable_type, comment.commentable_id
  • Filter:
    • GET /admin/comments.json?q[commentable_type_eq]=Invoice - Comments on invoices
    • GET /admin/comments.json?q[commentable_type_eq]=Address - Comments on addresses
    • GET /admin/comments.json?q[commentable_type_eq]=Invoice&q[commentable_id_eq]=123 - Comments on specific invoice
• Supported Commentable Types: Invoice, Address, Item, Payment, User, Domain, and other resources
• Example: Get all comments on a specific invoice:

  const invoiceComments = await fetch('/admin/comments.json?q[commentable_type_eq]=Invoice&q[commentable_id_eq]=123', {
    credentials: 'include',
    headers: { 'Accept': 'application/json' }
  }).then(r => r.json());

Reverse Associations

The following resources can have comments attached (polymorphic):

Invoice[]

• Type: has_many on Invoice via polymorphic commentable association
• Description: Comments attached to invoices. Add notes, annotations, and discussions to invoices.
• API Access:
  • Filter: GET /admin/comments.json?q[commentable_type_eq]=Invoice&q[commentable_id_eq]=123
  • Direct: Included in invoice response as comments array (if present)
• Related Documentation: Invoices
• Example: Get all comments for an invoice:

  const comments = await fetch('/admin/comments.json?q[commentable_type_eq]=Invoice&q[commentable_id_eq]=123', {
    credentials: 'include',
    headers: { 'Accept': 'application/json' }
  }).then(r => r.json());

Address[]

• Type: has_many on Address via polymorphic commentable association
• Description: Comments attached to addresses. Add notes and annotations to business partners.
• API Access:
  • Filter: GET /admin/comments.json?q[commentable_type_eq]=Address&q[commentable_id_eq]=123
• Related Documentation: Addresses
• Example: Get all comments for an address:

  const comments = await fetch('/admin/comments.json?q[commentable_type_eq]=Address&q[commentable_id_eq]=123', {
    credentials: 'include',
    headers: { 'Accept': 'application/json' }
  }).then(r => r.json());

Item[]

• Type: has_many on Item via polymorphic commentable association
• Description: Comments attached to items. Add notes and annotations to products.
• API Access:
  • Filter: GET /admin/comments.json?q[commentable_type_eq]=Item&q[commentable_id_eq]=123
• Related Documentation: Items

Payment[]

• Type: has_many on Payment via polymorphic commentable association
• Description: Comments attached to payments. Add notes and annotations to payment transactions.
• API Access:
  • Filter: GET /admin/comments.json?q[commentable_type_eq]=Payment&q[commentable_id_eq]=123
• Related Documentation: Payments

Relationship Patterns

Creating Comment on Resource

• Use Case: Add a comment to any commentable resource (Invoice, Address, Item, etc.)
• Example: Create a comment on an invoice:

  const comment = await fetch('/admin/comments.json', {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({
      comment: {
        body: 'Please review this invoice before sending',
        commentable_type: 'Invoice',
        commentable_id: 123
      }
    })
  }).then(r => r.json());

Filtering Comments by Resource Type

• Use Case: Get all comments for a specific resource type
• Example: Get all comments on invoices:

  const invoiceComments = await fetch('/admin/comments.json?q[commentable_type_eq]=Invoice', {
    credentials: 'include',
    headers: { 'Accept': 'application/json' }
  }).then(r => r.json());

Filtering Comments by Specific Resource

• Use Case: Get all comments on a specific resource (e.g., invoice ID 123)
• Example: Get all comments for a specific invoice:

  const comments = await fetch('/admin/comments.json?q[commentable_type_eq]=Invoice&q[commentable_id_eq]=123', {
    credentials: 'include',
    headers: { 'Accept': 'application/json' }
  }).then(r => r.json());

Comments by User

• Use Case: Get all comments created by a specific user
• Example: Get all comments by a user:

  const userComments = await fetch('/admin/comments.json?q[user_id_eq]=1', {
    credentials: 'include',
    headers: { 'Accept': 'application/json' }
  }).then(r => r.json());

Key Features

• Threaded Discussions: Comments support replies and threaded conversations
• Resource Association: Comments can be attached to any resource via polymorphic association
• User Attribution: Comments are attributed to users
• Domain Scoping: Comments are scoped to domains

Available Operations

List Comments (GET)

Endpoint: GET /admin/comments.json

Query Parameters:

• q[field_predicate]=value - Ransack query filters for advanced filtering
• page=N - Page number for pagination
• per_page=N - Items per page (default: 25)

Request Examples:

curl -X GET "https://your-company.erpax.com/admin/comments.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

curl -X GET "https://your-company.erpax.com/admin/comments.json?q[commentable_type_eq]=Invoice&q[commentable_id_eq]=123" \
  -H "Accept: application/json"

JavaScript Example:

const response = await fetch('/admin/comments.json', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
});
const data = await response.json();

Response (200 OK):

{
  "comments": [
    {
      "id": 1,
      "body": "Please review this invoice",
      "commentable_type": "Invoice",
      "commentable_id": 123,
      "user_id": 1,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 1,
    "total_count": 5
  }
}

Show Comment (GET /:id)

Endpoint: GET /admin/comments/:id.json

Request Example:

curl -X GET "https://your-company.erpax.com/admin/comments/1.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (200 OK):

{
  "comment": {
    "id": 1,
    "body": "Please review this invoice",
    "commentable_type": "Invoice",
    "commentable_id": 123,
    "user_id": 1,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Create Comment (POST)

Endpoint: POST /admin/comments.json

Request Example:

curl -X POST "https://your-company.erpax.com/admin/comments.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "comment": {
      "body": "This invoice needs attention",
      "commentable_type": "Invoice",
      "commentable_id": 123
    }
  }'

JavaScript Example:

const response = await fetch('/admin/comments.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    comment: {
      body: 'This invoice needs attention',
      commentable_type: 'Invoice',
      commentable_id: 123
    }
  })
});
const comment = await response.json();

Response (201 Created):

{
  "comment": {
    "id": 2,
    "body": "This invoice needs attention",
    "commentable_type": "Invoice",
    "commentable_id": 123,
    "user_id": 1,
    "created_at": "2024-01-15T14:30:00Z"
  }
}

Update Comment (PATCH /:id)

Endpoint: PATCH /admin/comments/:id.json

Request Example:

curl -X PATCH "https://your-company.erpax.com/admin/comments/1.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "comment": {
      "body": "Updated comment text"
    }
  }'

Response (200 OK):

{
  "comment": {
    "id": 1,
    "body": "Updated comment text",
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Delete Comment (DELETE /:id)

Endpoint: DELETE /admin/comments/:id.json

Request Example:

curl -X DELETE "https://your-company.erpax.com/admin/comments/1.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (204 No Content):

(empty response)

Scopes

No custom scopes are configured (uses default 'all' scope).

Filters

Available filters for searching and filtering comments:

• body_cont - Text filter - Search by comment body (contains)
• commentable_type - Select filter - Filter by commentable resource type
• commentable_id - Filter by commentable resource ID
• user - Select filter - Filter by user
• created_at - Date filter - Filter by creation date
• updated_at - Date filter - Filter by update date

Business Rules

• Polymorphic Association: Comments can be associated with any resource via polymorphic association
• User Attribution: Comments are automatically attributed to the current user
• Domain Scoping: Comments are automatically scoped to the current domain

Related Resources

• Invoices - Comments can be associated with invoices
• Addresses - Comments can be associated with addresses
• Items - Comments can be associated with items