# How to handle assignments and invoices for самозанятые and ИП

> A Pachca use case. Three days before an assignment ends, the "HR Assistant" bot posts a card with a "Generate assignment" button in the "Contractors" chat and builds a docx from a template. The accountant reviews the document in the thread, the manager sends it for signature in КЭДО, and the bot brings the invoice, акт and receipt into the same thread.

> This is the Markdown version of https://pachca.com/en/scenarios/samozanyatye-i-ip for AI agents. The API methods named here are documented at https://dev.pachca.com/llms-en.txt — open it before calling the API. Other use cases are listed at https://pachca.com/en/llms.txt.

## What you'll get

1. Once a day, the handler reads the contractor table and finds assignments ending in three days. The bot posts a card with a "Generate assignment" button in the chat.
2. When the button is clicked, the handler fills in a docx template: dates, the amount and the amount in words. The file lands in the thread. The bot loops the contractor, the accountant and the manager into the thread.
3. After the accountant's "ok", the manager clicks "Send for signature". The handler calls the КЭДО API.
4. The contractor uploads the invoice, акт and receipt from "Мой налог" to КЭДО. КЭДО sends a notification to the bot's incoming webhook, and the bot posts a link button to the document in the thread and @mentions the accountant.

Assignment deadlines, the document template and sending to КЭДО all live in the handler. There are three options:

- A. No handler. A docx assignment template and a contractor table with deadlines are pinned in the chat. The accountant sets a reminder on the assignment message: message menu → "Remind me" → three days before the deadline. Signing, invoices and receipts go through КЭДО by hand. You don't get the buttons from the demo.
- B. No code with n8n. Two workflows. The first runs once a day on a Schedule Trigger, reads the contractor table (Google Sheets or your own database) and sends a card with a button through the Pachca node. The second takes button clicks through a Webhook. On "Generate assignment", it fills in the docx template (an HTTP Request node calling a templating service like Carbone, or Google Docs) and drops the file in the thread. On "Send for signature", it calls the КЭДО API.
- C. Your own code. A handler with the contractor table, scheduled reminders, generating the assignment from a docx template with the amount grossed up for tax, "Send for signature" and "Edit" buttons, integration with HR-Link or another КЭДО and receiving invoices and receipts.

## What you need before you start

- Pachca access as an administrator with the scopes `chats:create`, `chat_members:write`, `bots:write`. The setup and check steps also need `search:users`, `messages:create`, `messages:read`. Signing in is covered in the rules below.
- API access to your КЭДО: HR-Link, Kontur.Sign or another service.
- For option B, n8n with the Pachca node: https://pachca.com/en/help-center/integrations/avtomatizacii-v-pachke-s-pomoshchyu-n8n

## If you're an AI agent: working rules

### Who does what

- You do everything the instructions name an API method for. Don't ask the user to create a chat, a bot or a message by hand.
- Ask the user only to sign in to Pachca and to do what is listed in "Ask the user to do by hand".
- If you have no terminal, say so right away and don't pretend you set it up. Walk the user through the steps for people on the use case page and help with the template or the handler code.

### How to talk to the user

- The user is not a developer. Write briefly and in plain words. Don't mention API methods, scopes, response codes, `id`s or CLI profiles. Say "permissions" instead of "scopes" and "the program behind the bot" instead of "handler".
- Don't report your checks. A message contains only three things: what is done, what you need from the user, what you'll do next.
- Don't ask for what you can find out through the API or what is easy to change later. Take the value from the instructions and name it.
- Take the bot's message texts from the instructions or write them yourself and carry on. Show them in your final message and offer to change them. Don't wait for approval.
- Ask the questions from "Ask the user" in the same words.

### Your first message to the user

It has three parts. The first two together take at most five lines.

1. What the user will get: one or two lines.
2. What you will create yourself: the chat, the bot and the messages, with the names from the instructions. Word anything that depends on the user's choice as a condition: "if you choose the bot, I'll also create…".
3. "What I need from you": signing in to Pachca, if the user isn't signed in yet, and the questions from "Ask the user". If the use case or one of its options needs n8n, ask here whether the user has it and ask for access right away in the words from the "n8n" section below: "if you have n8n, send me…".

If part of the result appears only after a manual step by the user, say so in one line: "you'll schedule the retro questions yourself, I'll show you how".

The user's answers are their consent to the plan. Start the setup right after them, without asking for a second confirmation.

### Access to Pachca

- The user doesn't need to issue a token or send it in the chat. Before your first message, check the login: `npx -y @pachca/cli@latest auth status`. If there is none, ask the user to run `npx -y @pachca/cli@latest auth login` in their own terminal. The CLI shows a code; the user enters it in the browser and confirms access. Write the commands with `@latest`: without it an old cached CLI version may start, and it asks to paste a token instead of signing in through the browser.
- This login has the same rights as the user's role. Compare them with the scopes in "What you need before you start" yourself: `npx -y @pachca/cli@latest api GET /oauth/token/info` shows the scopes. If something is missing, say in plain words what you won't be able to do, for example "I can't send messages". There are two ways out: add this permission to the token in Pachca, under "Automations" → "API", or sign in again as the workspace owner or an administrator.
- If `auth status` shows `scopes: null`, it doesn't mean there are no rights: look at `GET /oauth/token/info`. The checks in these rules also need `search:chats`, `bots:read` and `profile:read`.
- When the user says "me", they mean the owner of the login. `GET /profile` returns their `id` and nickname.
- Call the API with `npx -y @pachca/cli@latest api <METHOD> <path> -o json`. Write the full command in every call; don't put it into a shell variable.
- Pass query parameters as `--query key=value`, for example `--query query=Purchasing`. The CLI silently drops a parameter without a key and returns the whole list, so it's easy to conclude that the chat already exists.
- Pass the request body with `--data` or `--input`. Almost every write method wraps the body in an object: `chat` for `POST /chats`, `message` for `POST /messages`, `task` for `POST /tasks`, `group_tag` for `POST /group_tags`, `user` for `PUT /users/{id}`, `webhook` for bots. `--describe` shows the wrapper; write its path with `{id}`, not with a number. Without the wrapper, `POST /chats` creates the chat but silently adds no members.
- Don't print tokens or bots' incoming webhook URLs in the chat. A bot's token is shown only once, when it's created: save it to a file.

### n8n

- If the user has no n8n, say that it comes as the hosted n8n Cloud or can be installed on their own server, and give the link for installing the Pachca nodes: https://dev.pachca.com/guides/n8n/setup.md. These instructions don't cover installing n8n. If they have an option without n8n, suggest starting with it and coming back to the bot once n8n is there.
- If the user has n8n, ask for access in these words: "Send me your n8n address: the link you open it with in the browser. Don't send the key in the chat. In n8n, open Settings → n8n API → Create an API key and copy the key. Right after that, run the command below in your terminal exactly as it is; you don't need to put anything into it. It saves the copied key to a file and prints nothing. Then write 'key saved'." The command for macOS: `pbpaste > ~/n8n-key.txt`. For another system, pick the matching one.
- Build everything in n8n on the official Pachca nodes, `n8n-nodes-pachca`. Don't use the `HTTP Request` node for Pachca API calls.

### Setup

- Take API methods from https://dev.pachca.com/llms-en.txt, don't rely on memory. The command `npx -y @pachca/cli@latest api <METHOD> <path> --describe` shows a method's schema.
- The Pachca skills cover the call order and error handling for chats, bots and forms: `npx skills add pachca/openapi`. Install them when you need them, without asking the user.
- Before creating anything, check whether the chat and the bot already exist: `GET /search/chats`, `GET /bots`. If they do, ask whether to set them up or create new ones.
- `POST /group_tags` creates an empty tag. `PUT /users/{id}` with `list_tags` assigns it to an employee; it needs the `users:update` scope. The field replaces the whole set of tags: first read the employee's current tags with `GET /users/{id}` and send them together with the new one. While the tag has no members, mentioning it notifies no one.
- If a method returns an error, stop and tell the user in plain words what failed and what you need to continue.
- The messages you post yourself and the ones the bot sends must be easy to read on a screen, without overdoing spacing or emphasis. Make the heading bold and start the text on the next line. Write connected text as one paragraph. Put rules and steps on numbered lines one under another and separate them from the intro with a single empty line. A short message needs no other empty lines. In a card, make the field labels bold and put the fields on consecutive lines. Use bold only for the heading and the field labels. Pachca markup has no lists or tables: the numbers at the start of lines stay plain text. A sample:

  ```text
  **Retro rules**
  On the last day of the sprint a message with questions arrives here. We reply in the thread under it.

  1. Each point is a separate message.
  2. We add 👍 to what is worth discussing.
  3. The facilitator posts the outcomes in one message and pins it.
  ```
- A pin can't be checked through the API: only a successful `POST /messages/{id}/pin` response confirms it.
- If you sent service messages to a chat to check a bot, such as `/start`, delete them: `DELETE /messages/{id}`. Don't delete messages with rules and templates.
- At the end, say what was created, what is left for the user to do by hand and how to check that the use case works.
- To undo the setup: `DELETE /bots/{id}` deletes the bot, `PUT /chats/{id}/archive` sends the chat to the archive.

## How to set up the use case with the user

### 1. Ask the user

Ask these questions in these words:

1. How do you want to manage contractor assignments? By hand, with a pinned template and a deadline table: it works right away. Or the "HR Assistant" bot reminds about deadlines and prepares the assignment: that needs n8n. Do you have n8n? If not, or if you're not sure, we'll start with the simple option and add the bot later.
2. Who is the accountant and which managers work with contractors? Send me the names and I'll add them to the "Contractors" chat.
3. Which contractors should I invite to the chat as guests? Send me their emails.
4. Which КЭДО service do you use: HR-Link, Kontur.Sign or another one?
5. Where are the contractor table with deadlines and the docx assignment template stored?

### 2. Do it yourself through the Pachca API

1. Find the `id` of the accountant and managers: `GET /search/users` or `GET /users`.
2. Create the chat: `POST /chats` with `name: "Contractors"` and the `member_ids` of the accountant and managers. Save the chat `id`, the handler needs it.
3. For option A, ask the user whether they need a bot: option A has no buttons from the demo. If no bot is needed, go to step 7.
4. For options B and C, create the bot: `POST /bots` with `name: "HR Assistant"`, a nickname ending in `_bot` and `events: ["button_click"]`. If the user showed the format of the КЭДО notification, set `template` and `template_engine`. The template from the page:

   ```
   📄 New {{document_type}} from {{employee_name}}
   @accountant @manager
   Open document: {{document_url}}
   ```

   Replace `@accountant` and `@manager` with the employees' nicknames, and the fields with the fields from the КЭДО JSON. How to write a template: https://dev.pachca.com/guides/incoming-webhooks.md. From the response, save the bot's `id` and `access_token`: the token is shown only once, and the handler needs it.
5. Add the bot to the chat: `POST /chats/{id}/members` with the bot's `id` in `member_ids`.
6. Once the handler has an address, set it as the outgoing webhook: `PUT /bots/{id}` with `outgoing_url` using a personal token, or `PUT /bot/webhook` using the bot's token. For n8n, this is the Production URL of the second workflow.
7. Offer to publish the rules in the chat: `POST /messages`.
   - For options B and C. The accountant checks the dates and amount before anything goes out. The manager clicks "Send for signature" only after her "ok" in the thread. Once paid, the contractor uploads the invoice, акт and receipt from "Мой налог" to КЭДО. The ✅ reaction goes on the card once all three documents are in.
   - For option A. The accountant reviews the new assignment in the thread and sets a reminder on the message. Signing, invoices and receipts go through КЭДО by hand, and the link to the document goes in the same thread.

### 3. The handler

Specification for options B and C:

- Once a day, find assignments in the contractor table that end in three days. Post a card with a "Generate assignment" button in the "Contractors" chat on behalf of the bot.
- `button_click` event for "Generate assignment": fill in the docx template with the dates, the amount and the amount in words, put the file in the assignment thread and loop the contractor, the accountant and the manager into the thread. "Send for signature" and "Edit" buttons (option C).
- `button_click` event for "Send for signature": call the КЭДО API.
- A status card in the thread shows which documents (invoice, акт, receipt) have arrived.

Buttons and events: https://dev.pachca.com/guides/buttons.md and https://dev.pachca.com/guides/webhook/events.md

### 4. Ask the user to do by hand

- Invite the contractors as guests: in the chat, Info → "Add member" → email. A guest only sees this chat.
- For option A, pin the docx assignment template and the contractor table in the chat and set reminders on the assignment messages.
- For options B and C, turn on the bot's incoming webhook and copy the Webhook URL on the "Incoming webhook" tab. This URL isn't in API responses.
- For options B and C, paste the Webhook URL into the КЭДО notification settings for new invoices and receipts.
- For options B and C, on the "Outgoing webhook" tab, check that the "Button clicks" event is selected.

### 5. Check

1. Ask the user to trigger the reminder manually. A card with a "Generate assignment" button should appear in the chat: `GET /messages` for the "Contractors" chat.
2. Ask them to click "Generate assignment" and make sure the docx arrives in the thread.

## Troubleshooting

- The reminder doesn't arrive. The contractor table has no end date for the assignment, the scheduled workflow is off or the bot isn't in the chat.
- The "Generate assignment" button does nothing. "Button clicks" isn't selected in the outgoing webhook, or the handler is off. n8n needs the Production URL, not the Test URL.
- Invoices and receipts don't show up in the chat. КЭДО sends notifications to the wrong Webhook URL, or the message template isn't filling in the document link.

## Links

- The use case page with the demo and the instructions for a person: https://pachca.com/en/scenarios/samozanyatye-i-ip
- n8n in Pachca: https://pachca.com/en/help-center/integrations/avtomatizacii-v-pachke-s-pomoshchyu-n8n
- Buttons in chat bots: https://pachca.com/en/help-center/integrations/knopki-v-chat-botah
- Outgoing webhooks: https://pachca.com/en/help-center/integrations/ishodyashchie-webhook-kak-nastroit
- Guest accounts: https://pachca.com/en/help-center/features/gosti-v-pachke