b24_bizproc_list

Instructions

Implementation Reference

• src/tools/feed-notifications.js:103-110 (handler)

  The handler function for b24_bizproc_list tool. It creates a Bitrix24Client, builds params with optional ENTITY and DOCUMENT_ID filters, calls 'bizproc.workflow.instances', and returns the list of workflows.

  export async function bizprocList({ entity, entity_id, webhook_url }) {
    const client = new Bitrix24Client(resolveWebhook(webhook_url));
    const params = {};
    if (entity) params.ENTITY = entity;
    if (entity_id) params.DOCUMENT_ID = entity_id;
    const res = await client.call('bizproc.workflow.instances', params);
    return { portal: client.portal, workflows: res.result ?? [] };
  }

• src/tools/feed-notifications.js:97-101 (schema)

  Zod schema defining the input parameters for b24_bizproc_list: entity (optional string, e.g. CRM_DEAL), entity_id (optional string/number), and webhook_url (optional URL).

  export const bizprocListSchema = z.object({
    entity: z.string().optional().describe('Entidad CRM: CRM_DEAL, CRM_CONTACT, CRM_COMPANY, CRM_LEAD'),
    entity_id: z.union([z.string(), z.number()]).optional().describe('ID del registro CRM'),
    webhook_url: z.string().url().optional(),
  });

• index.js:249-251 (registration)

  Registration of the 'b24_bizproc_list' tool on the MCP server with its description, schema, and wrapped handler.

  server.tool('b24_bizproc_list',
    'Lista instancias de procesos de negocio activas, filtradas por entidad o registro.',
    bizprocListSchema.shape, wrap(bizprocList));

• src/bitrix24/client.js:6-50 (helper)

  The Bitrix24Client class used by the handler to make API calls. The 'call' method (line 21) handles posting to the webhook URL with retries and rate limiting.

  export class Bitrix24Client {
    constructor(webhookUrl) {
      this.webhookUrl = webhookUrl.endsWith('/') ? webhookUrl : webhookUrl + '/';
      this.limiter = new RateLimiter(500);
      this.portal = this._extractPortal(webhookUrl);
    }
  
    _extractPortal(url) {
      try {
        return new URL(url).hostname;
      } catch {
        return 'unknown';
      }
    }
  
    async call(method, params = {}, retries = 0) {
      return this.limiter.schedule(async () => {
        try {
          const url = `${this.webhookUrl}${method}.json`;
          const response = await axios.post(url, params, { timeout: 30000 });
          if (response.data.error) {
            throw new Error(`Bitrix24 error [${response.data.error}]: ${response.data.error_description}`);
          }
          return response.data;
        } catch (err) {
          if (err.response?.status === 429 && retries < MAX_RETRIES) {
            const retryAfter = parseInt(err.response.headers['retry-after'] || '2', 10);
            await new Promise(r => setTimeout(r, retryAfter * 1000));
            return this.call(method, params, retries + 1);
          }
          if (err.code === 'ECONNABORTED' && retries < MAX_RETRIES) {
            const backoff = Math.pow(2, retries) * 1000;
            await new Promise(r => setTimeout(r, backoff));
            return this.call(method, params, retries + 1);
          }
          throw err;
        }
      });
    }
  }

• src/utils/resolve-webhook.js:1-10 (helper)

  Utility function resolveWebhook used by the handler to determine the webhook URL from the parameter or environment variable.

  export function resolveWebhook(webhookParam) {
    const url = webhookParam || process.env.B24_DEFAULT_WEBHOOK;
    if (!url) {
      throw new Error(
        'No se especificó webhook_url y no hay B24_DEFAULT_WEBHOOK configurado. ' +
        'Indicá el webhook en el parámetro webhook_url o configuralo en el servidor MCP.'
      );
    }
    return url;
  }