ERPax

Appearance

/admin/sales_agreements ​

Path: /admin/sales_agreements
Namespace: admin
Resource: sales_agreements

Overview ​

The SalesAgreement resource represents sales contracts, pricing agreements, and terms between parties. Sales agreements define pricing, terms, and conditions for business relationships.

Relationships ​

Model Associations ​

SalesAgreement connects to the following resources:

Address (Seller) ​
  • Type: belongs_to via seller_id
  • Field: seller_id
  • Description: Seller address in the sales agreement. The party selling goods/services under this agreement.
  • Reverse: Address has many sales agreements as seller (address.sales_agreements_as_seller)
  • API Access:
    • Direct: Included in sales agreement response as seller_id
    • Filter: GET /admin/sales_agreements.json?q[seller_id_eq]=1
  • Related Documentation: Addresses
  • Example: Get all sales agreements where an address is seller:
    javascript
    const agreements = await fetch('/admin/sales_agreements.json?q[seller_id_eq]=123', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
}).then(r => r.json());
Address (Buyer) ​
  • Type: belongs_to via buyer_id
  • Field: buyer_id
  • Description: Buyer address in the sales agreement. The party purchasing goods/services under this agreement.
  • Reverse: Address has many sales agreements as buyer (address.sales_agreements_as_buyer)
  • API Access:
    • Direct: Included in sales agreement response as buyer_id
    • Filter: GET /admin/sales_agreements.json?q[buyer_id_eq]=2
  • Related Documentation: Addresses
  • Example: Get all sales agreements where an address is buyer:
    javascript
    const agreements = await fetch('/admin/sales_agreements.json?q[buyer_id_eq]=123', {
  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. All sales agreements belong to a domain.
  • Reverse: Domain has many sales agreements (domain.sales_agreements)
  • API Access:
    • Direct: Included in sales agreement response as host_id
    • Filter: GET /admin/sales_agreements.json?q[host_id_eq]=1
  • Related Documentation: Domains

Reverse Associations ​

The following resources connect to SalesAgreement:

Invoice[] ​
  • Type: has_many on Invoice via sales_agreement_id (if applicable)
  • Description: Invoices that reference this sales agreement. Invoices can be created under sales agreements to apply pricing terms.
  • API Access:
    • Filter: GET /admin/invoices.json?q[sales_agreement_id_eq]=123
  • Related Documentation: Invoices
  • Example: Get all invoices under a sales agreement:
    javascript
    const invoices = await fetch('/admin/invoices.json?q[sales_agreement_id_eq]=123', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
}).then(r => r.json());

Relationship Patterns ​

Creating Sales Agreement Between Parties ​
  • Use Case: Establish a sales agreement between seller and buyer with pricing terms
  • Example:
    javascript
    const agreement = await fetch('/admin/sales_agreements.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    sales_agreement: {
      agreement_number: 'SA-2024-001',
      seller_id: 1,
      buyer_id: 2,
      start_date: '2024-01-01',
      end_date: '2024-12-31',
      status: 'active',
      pricing_terms: 'Volume Discount',
      agreement_terms: 'Special pricing for bulk orders'
    }
  })
}).then(r => r.json());
Filtering Sales Agreements by Parties ​
  • Use Case: Find all active sales agreements between specific seller and buyer
  • Example:
    javascript
    const agreements = await fetch('/admin/sales_agreements.json?q[seller_id_eq]=1&q[buyer_id_eq]=2&q[status_eq]=active', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
}).then(r => r.json());
Using Sales Agreement in Invoice ​
  • Use Case: Create invoice under a sales agreement to apply pricing terms
  • Example:
    javascript
    const invoice = await fetch('/admin/invoices.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    invoice: {
      invoice_type: 'invoice',
      seller_id: 1,
      buyer_id: 2,
      sales_agreement_id: 123, // Apply sales agreement terms
      date: '2024-01-15'
    }
  })
}).then(r => r.json());

Key Features ​

  • Contract Management: Manage sales contracts and agreements
  • Pricing Terms: Define pricing structures and terms
  • Party Association: Agreements are associated with addresses (seller/buyer)
  • Term Management: Track agreement start/end dates and terms
  • Status Tracking: Track agreement status (active, expired, pending)

Available Operations ​

List Sales Agreements (GET) ​

Endpoint: GET /admin/sales_agreements.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:

bash
curl -X GET "https://your-company.erpax.com/admin/sales_agreements.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"
bash
curl -X GET "https://your-company.erpax.com/admin/sales_agreements.json?q[seller_id_eq]=1&q[status_eq]=active" \
  -H "Accept: application/json"

JavaScript Example:

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

Response (200 OK):

json
{
  "sales_agreements": [
    {
      "id": 1,
      "agreement_number": "SA-2024-001",
      "seller_id": 1,
      "buyer_id": 2,
      "start_date": "2024-01-01",
      "end_date": "2024-12-31",
      "status": "active",
      "created_at": "2024-01-01T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 1,
    "total_count": 3
  }
}

Show Sales Agreement (GET /:id) ​

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

Request Example:

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

Response (200 OK):

json
{
  "sales_agreement": {
    "id": 1,
    "agreement_number": "SA-2024-001",
    "seller_id": 1,
    "buyer_id": 2,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "status": "active",
    "pricing_terms": "Volume discounts apply",
    "agreement_terms": "Standard terms and conditions",
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}

Create Sales Agreement (POST) ​

Endpoint: POST /admin/sales_agreements.json

Request Example:

bash
curl -X POST "https://your-company.erpax.com/admin/sales_agreements.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "sales_agreement": {
      "agreement_number": "SA-2024-002",
      "seller_id": 1,
      "buyer_id": 3,
      "start_date": "2024-02-01",
      "end_date": "2024-12-31",
      "status": "active",
      "pricing_terms": "Special pricing for bulk orders"
    }
  }'

JavaScript Example:

javascript
const response = await fetch('/admin/sales_agreements.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    sales_agreement: {
      agreement_number: 'SA-2024-002',
      seller_id: 1,
      buyer_id: 3,
      start_date: '2024-02-01',
      end_date: '2024-12-31',
      status: 'active',
      pricing_terms: 'Special pricing for bulk orders'
    }
  })
});
const agreement = await response.json();

Response (201 Created):

json
{
  "sales_agreement": {
    "id": 2,
    "agreement_number": "SA-2024-002",
    "seller_id": 1,
    "buyer_id": 3,
    "start_date": "2024-02-01",
    "end_date": "2024-12-31",
    "status": "active",
    "created_at": "2024-01-15T14:30:00Z"
  }
}

Update Sales Agreement (PATCH /:id) ​

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

Request Example:

bash
curl -X PATCH "https://your-company.erpax.com/admin/sales_agreements/1.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "sales_agreement": {
      "status": "expired"
    }
  }'

Response (200 OK):

json
{
  "sales_agreement": {
    "id": 1,
    "status": "expired",
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Delete Sales Agreement (DELETE /:id) ​

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

Request Example:

bash
curl -X DELETE "https://your-company.erpax.com/admin/sales_agreements/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 sales agreements:

  • seller - Select filter - Filter by seller address
  • buyer - Select filter - Filter by buyer address
  • status - Select filter - Filter by status
  • start_date - Date filter - Filter by start date
  • end_date - Date filter - Filter by end date
  • created_at - Date filter - Filter by creation date
  • updated_at - Date filter - Filter by update date

Filtering Examples:

bash
# Filter by seller and status
GET /admin/sales_agreements.json?q[seller_id_eq]=1&q[status_eq]=active

# Filter by date range
GET /admin/sales_agreements.json?q[start_date_gteq]=2024-01-01&q[end_date_lteq]=2024-12-31

Business Rules ​

  • Agreement Number Uniqueness: Agreement numbers should be unique within a domain
  • Date Validation: End date must be after start date
  • Status Management: Agreements can have statuses like active, expired, pending
  • Domain Scoping: Agreements are automatically scoped to the current domain
  • Addresses - Seller and buyer addresses
  • Invoices - Invoices may reference sales agreements

Released under an open source license.

Copyright © ERPax.com