commands.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Commands - Circuit Auction API</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
  <link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css" rel="stylesheet" />
  <style>
      body { padding-top: 70px; background-color: #f8f9fa; }
      .navbar-brand { font-weight: bold; }
      .main-content { padding: 2rem; }
      pre { background: #f4f4f4; padding: 1rem; border-radius: 0.375rem; position: relative; }
      .copy-btn { position: absolute; top: 0.5rem; right: 0.5rem; font-size: 0.8rem; }
      .endpoint { font-family: 'Courier New', monospace; background: #e9ecef; padding: 0.2rem 0.4rem; border-radius: 0.25rem; }
      .badge-method { font-size: 0.7em; padding: 0.3em 0.6em; }
      .param-table th { background-color: #f8f9fa; }
  </style>
</head>
<body>
<nav class="navbar navbar-expand-lg navbar-dark bg-primary fixed-top">
  <div class="container-fluid">
    <a class="navbar-brand" href="index.html">Circuit Auction API v1.0</a>
  </div>
</nav>
<div class="container main-content">
  <nav aria-label="breadcrumb">
    <ol class="breadcrumb">
      <li class="breadcrumb-item"><a href="index.html">API</a></li>
      <li class="breadcrumb-item active">Commands</li>
    </ol>
  </nav>

  <h1>Commands</h1>
  <p class="lead">Action-oriented endpoints for invoking server functions, bulk operations, and print/export utilities.</p>

  <div class="alert alert-warning">
    These endpoints trigger server-side operations. Most are not discoverable via the API index. All require authentication unless noted.
  </div>

  <!-- Invoke Function -->
  <div class="card mb-4">
    <div class="card-header">
      <span class="badge bg-primary badge-method">POST</span>
      <code class="endpoint">/api/v1.0/invoke-function</code>
    </div>
    <div class="card-body">
      <p>Invokes a named server-side function. The available functions depend on server configuration. The response format is a raw passthrough of the function's return value and will vary by function.</p>
      <h5>Request Body</h5>
      <table class="table table-sm param-table">
        <thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
        <tbody>
          <tr><td><code>function</code></td><td>string (required)</td><td>Machine name of the function to invoke</td></tr>
          <tr><td><code>args</code></td><td>object (optional)</td><td>Key-value arguments passed to the function</td></tr>
        </tbody>
      </table>
      <h5 class="mt-3">Example Request</h5>
      <pre><code class="language-bash">POST /api/v1.0/invoke-function</code></pre>
      <pre><code class="language-json">{
  "function": "recalculate_sale_totals",
  "args": {
    "sale_id": "45"
  }
}</code></pre>
      <h5 class="mt-3">Response</h5>
      <pre><code class="language-json">{
  "data": {
    "status": "ok",
    "message": "Sale totals recalculated for sale 45."
  }
}</code></pre>
    </div>
  </div>

  <!-- Invoke Function Public -->
  <div class="card mb-4">
    <div class="card-header">
      <span class="badge bg-primary badge-method">POST</span>
      <code class="endpoint">/api/v1.0/invoke-function-public</code>
    </div>
    <div class="card-body">
      <p>Same as <code>invoke-function</code> but accessible without a Bearer token. Permission checks are performed inside the function itself — the function is responsible for validating whether the caller is authorized to execute it.</p>
      <h5>Request Body</h5>
      <table class="table table-sm param-table">
        <thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
        <tbody>
          <tr><td><code>function</code></td><td>string (required)</td><td>Machine name of the function to invoke</td></tr>
          <tr><td><code>args</code></td><td>object (optional)</td><td>Key-value arguments passed to the function</td></tr>
        </tbody>
      </table>
      <h5 class="mt-3">Example Request</h5>
      <pre><code class="language-bash">POST /api/v1.0/invoke-function-public</code></pre>
      <pre><code class="language-json">{
  "function": "get_public_sale_summary",
  "args": {
    "sale_id": "12"
  }
}</code></pre>
      <h5 class="mt-3">Response</h5>
      <pre><code class="language-json">{
  "data": {
    "sale_id": "12",
    "total_lots": 385,
    "status": "upcoming"
  }
}</code></pre>
    </div>
  </div>

  <!-- Bulk Dispatcher -->
  <div class="card mb-4">
    <div class="card-header">
      <span class="badge bg-primary badge-method">POST</span>
      <code class="endpoint">/api/v1.0/bulk-dispatcher</code>
    </div>
    <div class="card-body">
      <p>Generic endpoint for dispatching bulk operations across multiple entities. See the dedicated <a href="bulk/dispatcher.html">Bulk Dispatcher</a> page for a full list of supported operations and their parameters.</p>
      <h5>Request Body</h5>
      <table class="table table-sm param-table">
        <thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
        <tbody>
          <tr><td><code>operation</code></td><td>string (required)</td><td>Machine name of the bulk operation to run</td></tr>
          <tr><td><code>ids</code></td><td>array (required)</td><td>Array of entity node IDs to operate on</td></tr>
          <tr><td><code>params</code></td><td>object (optional)</td><td>Additional operation-specific parameters</td></tr>
        </tbody>
      </table>
      <h5 class="mt-3">Example Request</h5>
      <pre><code class="language-bash">POST /api/v1.0/bulk-dispatcher</code></pre>
      <pre><code class="language-json">{
  "operation": "mark_items_sold",
  "ids": ["100", "101", "102"],
  "params": {
    "sale_id": "45"
  }
}</code></pre>
      <h5 class="mt-3">Response</h5>
      <pre><code class="language-json">{
  "data": {
    "processed": 3,
    "errors": []
  }
}</code></pre>
    </div>
  </div>

  <!-- Generate Cheque -->
  <div class="card mb-4">
    <div class="card-header">
      <span class="badge bg-primary badge-method">POST</span>
      <code class="endpoint">/api/v1.0/generate-cheque</code>
    </div>
    <div class="card-body">
      <p>Generates a cheque document for a given transaction. Returns a URL to the generated PDF.</p>
      <h5>Request Body</h5>
      <table class="table table-sm param-table">
        <thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
        <tbody>
          <tr><td><code>transaction_id</code></td><td>string (required)</td><td>Node ID of the transaction for which to generate the cheque</td></tr>
        </tbody>
      </table>
      <h5 class="mt-3">Example Request</h5>
      <pre><code class="language-bash">POST /api/v1.0/generate-cheque</code></pre>
      <pre><code class="language-json">{
  "transaction_id": "456"
}</code></pre>
      <h5 class="mt-3">Response</h5>
      <pre><code class="language-json">{
  "data": {
    "cheque_url": "/files/cheque_456.pdf"
  }
}</code></pre>
    </div>
  </div>

  <!-- Reset Statement Charges -->
  <div class="card mb-4">
    <div class="card-header">
      <span class="badge bg-warning text-dark badge-method">PATCH</span>
      <code class="endpoint">/api/v1.0/reset-statement-charges/{id}</code>
    </div>
    <div class="card-body">
      <p>Removes all current charges from the specified consignment statement and re-assigns all unassigned charges to it. The <code>id</code> path parameter is the numeric consignment statement node ID.</p>
      <h5>Parameters</h5>
      <table class="table table-sm param-table">
        <thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
        <tbody>
          <tr><td><code>id</code></td><td>integer (path)</td><td>Consignment statement node ID</td></tr>
        </tbody>
      </table>
      <h5 class="mt-3">Example Request</h5>
      <pre><code class="language-bash">PATCH /api/v1.0/reset-statement-charges/789</code></pre>
      <h5 class="mt-3">Response</h5>
      <pre><code class="language-json">{
  "data": {
    "id": "789",
    "status": "charges_reset"
  }
}</code></pre>
    </div>
  </div>

</div>
<script src="assets/js/sidebar.js"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-core.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/autoloader/prism-autoloader.min.js"></script>
<script>
  document.querySelectorAll('pre code').forEach(block => {
    const button = document.createElement('button');
    button.className = 'btn btn-sm btn-outline-secondary copy-btn';
    button.textContent = 'Copy';
    button.onclick = () => {
      navigator.clipboard.writeText(block.textContent);
      button.textContent = 'Copied!';
      setTimeout(() => button.textContent = 'Copy', 2000);
    };
    block.parentElement.appendChild(button);
  });
</script>
</body>
</html>