# perfex_crm

Adopt this skill: https://proskills.md/skills/other/digidestination-perfex-openclaw-skill-skills-perfex-crm

Page: https://proskills.md/skills/other/digidestination-perfex-openclaw-skill-skills-perfex-crm
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/perfex_crm/SKILL.md
size: 2390
upstream: https://github.com/digidestination/perfex-openclaw-skill/blob/main/skills/perfex_crm/SKILL.md

```text
---
name: perfex_crm
description: Use Perfex CRM safely through the Themesic REST API module to manage customers, contacts, invoices, projects, tasks, leads, proposals, payments, and OpenClaw agent identities.
metadata:
  openclaw:
    requires:
      config:
        - plugins.entries.perfex-rest-api.enabled
---

# Perfex CRM Skill

Use the `perfex_*` tools for CRM operations.

## When to use this skill

Use this skill when the user needs to:

- manage CRM customers or contacts
- create or inspect invoices
- search or update projects and tasks
- track leads, proposals, or payments
- provision a CRM identity for an OpenClaw agent

## Authentication expectations

- The plugin should already be configured with a Perfex base URL and API token.
- Never ask the user to paste the token into chat.
- Prefer Bearer authentication when supported.

## Core rules

- Search before create whenever duplicates are possible.
- Treat `{status:false}` as an error even if the HTTP status is 200.
- Do not automatically retry create operations.
- Use pagination for large result sets.
- Confirm destructive operations before executing them in human-facing workflows.

## Agent identity rule

When the user asks to create a user for an OpenClaw agent:

1. Search for an existing customer using the agent external key or agent name.
2. If missing, create a customer record for the agent.
3. Search for the agent contact under that customer.
4. If missing, create the contact.
5. Return both identifiers and a short summary.

Use `perfex_ensure_agent_identity` for this workflow.

## Practical workflow examples

### Create a new client and primary contact

1. `perfex_customers_search`
2. `perfex_customers_create`
3. `perfex_contacts_create`
4. `perfex_contacts_list_by_customer`

### Find an invoice and its customer

1. `perfex_invoices_search`
2. `perfex_invoices_get`
3. if needed, `perfex_customers_get`

### Search active work

1. `perfex_projects_search`
2. `perfex_tasks_search`

### Provision an agent

1. `perfex_ensure_agent_identity`
2. optionally attach metadata through `perfex_request` if your deployment supports custom fields or notes via REST

## Safety guidance

- Do not guess undocumented fields.
- If a typed tool fails due to field mismatch in a specific module build, use `perfex_request` and explain the exact mismatch.
- Prefer explicit user intent before delete actions.
```

## File: README.md
upstream: https://github.com/digidestination/perfex-openclaw-skill/blob/main/README.md

````text
# Perfex CRM for OpenClaw

A GitHub-ready OpenClaw plugin + Skill bundle for integrating OpenClaw with Perfex CRM through the Themesic REST API module.

This package is designed to be practical, secure, and easy to extend. It gives OpenClaw typed tools for common Perfex workflows and a bundled skill that teaches the agent when and how to use them.

## What this package includes

- Native OpenClaw plugin scaffold
- Bundled `perfex_crm` skill
- Typed tools for common Perfex resources
- Secure config schema for base URL and API token
- Error normalization and retry helpers
- Pagination support
- Example workflows and operations manual
- GitHub-ready repository structure

## Supported resources

This implementation includes first-class tools for:

- Customers / clients
- Contacts
- Invoices
- Projects
- Tasks
- Leads
- Proposals
- Payments

It also includes a generic request tool for endpoints that are available in your Perfex module build but not yet wrapped by a typed helper.

## Important note about agent users

This package includes an `ensure_agent_identity` tool that creates or updates a dedicated Perfex identity record for each OpenClaw agent using customer + contact records.

Why this design:

- The public sources reviewed clearly expose customer/contact CRUD and search endpoints.
- Publicly accessible documentation reviewed during research did not conclusively confirm a supported REST endpoint for creating internal Perfex staff/admin users.
- Because of that, this package implements agent provisioning in a safe, documented way using confirmed CRM entities instead of guessing undocumented staff-creation behavior.

If your installation exposes a supported staff-user endpoint, extend the generic request tool or add a dedicated `staff` wrapper.

## Compatibility target

Designed for:

- Latest public Perfex CRM core release context observed during research
- Themesic REST API module for Perfex CRM
- OpenClaw native plugin + bundled skills architecture

## Quick start

1. Copy this folder into your OpenClaw plugins directory or your own repo.
2. Install dependencies.
3. Build the project.
4. Configure the plugin in OpenClaw with your Perfex base URL and API token.
5. Start a new OpenClaw session so the skill snapshot refreshes.

See:

- `MANUAL.md`
- `docs/INSTALL.md`
- `skills/perfex_crm/SKILL.md`

## Repository layout

```text
perfex-openclaw-skill/
  docs/
    INSTALL.md
    API-MAPPING.md
    SECURITY.md
  skills/
    perfex_crm/
      SKILL.md
  src/
    index.ts
    perfex-client.ts
    tool-defs.ts
  .env.example
  .gitignore
  MANUAL.md
  openclaw.plugin.json
  package.json
  tsconfig.json
  README.md
```
````
