К основному содержанию
скилл CX Codex

connector-quickbooks — скилл QuickBooks Online для Claude Code

Скилл connector-quickbooks для Claude Code и других агентов: работает со счетами, клиентами, платежами и товарами в QuickBooks Online через пакет quickbooks-client. Выставляет и отправляет счета прямо из проекта.

Apache-2.0 10 200 установок ★ 2 обновлён 2026-11-02

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add caffeinelabs/skills --skill connector-quickbooks -a claude-code
Открыть на GitHub

Что делает connector-quickbooks

Скилл подключает пакет quickbooks-client к запросам агента. Он умеет создавать, читать и обновлять счета, клиентов, платежи, товары и счета учёта в QuickBooks Online, отправлять счета по почте и выполнять запросы query_ по данным QBO.

Внутри — Motoko-биндинги для пяти сущностей: Customer, Invoice, Payment, Item, Account. Все 12 операций живут в Apis/DefaultApi.mo: пары save*/get* для каждой сущности плюс sendInvoice и query_. Схемы переписаны из официального XSD Intuit.

Аутентификация — OAuth 2.0 Authorization Code, статического API-ключа нет. Пользователь подключает свою компанию QuickBooks, приложение получает короткоживущий Bearer-токен примерно на час. При 401 нужно заново провести авторизацию. Для исходящих вызовов обязателен is_replicated = ?false: ответ QBO недетерминирован, реплицированный вызов продублируется на ~13 репликах и не пройдёт консенсус. Создание и обновление используют одну операцию save<Entity>: без Id и SyncToken это создание, с ними — обновление. Транзакции (Invoice, Payment) удаляются через operation = ?#delete; клиентов, товары и счета учёта удалить нельзя — только деактивировать через Active = ?false. Оценки, счета поставщиков и остальные сущности QBO в этот срез не входят.

Какие задачи решает

  • создать счёт с несколькими строками и отправить его клиенту
  • получить данные клиента или товара по Id
  • провести частичное обновление счёта через sparse-режим
  • выполнить произвольный запрос к QBO через query_
  • удалить счёт или платёж с правильным SyncToken

Примеры запросов агенту

  • Создай счёт на $100 за консультацию для клиента 58, товар 1, и отправь его на почту
  • Найди клиента по Id и покажи его текущие данные
  • Удали счёт 12345, предварительно получив его SyncToken через getInvoice

Как установить connector-quickbooks

1Через Skills CLI (Vercel)

npx skills add caffeinelabs/skills --skill connector-quickbooks -a claude-code

2Вручную: положить файлы

~/.claude/skills/connector-quickbooks/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/connector-quickbooks/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о connector-quickbooks

Как установить connector-quickbooks в Claude Code?

Выполни npx skills add caffeinelabs/skills --skill connector-quickbooks -a claude-code. Скилл появится в ~/.claude/skills/connector-quickbooks/SKILL.md.

Что делает connector-quickbooks?

Даёт агенту доступ к QuickBooks Online через пакет quickbooks-client: счета, клиенты, платежи, товары и счета учёта. Поддерживает создание, чтение, обновление, удаление транзакций и отправку счетов.

Чем создание отличается от обновления в этом скилле?

Обе операции идут через save<Entity>. Если в теле есть Id и текущий SyncToken — это обновление, если их нет — создание. Для частичного обновления ставь sparse = ?true.

Исходный текст

SKILL.md · Apache-2.0
---
name: connector-quickbooks
description: >-
  Use the `quickbooks-client` mops package whenever the user asks the canister
  to create/read/update invoices, customers, payments, items, or chart-of-account
  entries in QuickBooks Online (QBO), email an invoice, or run a QuickBooks query.
  The package wraps the QuickBooks Online Accounting API v3 at
  `https://quickbooks.api.intuit.com` via outbound HTTPS calls.
version: 0.3.0
caffeineai-subscription: [none]
compatibility:
  mops:
    quickbooks-client: "~0.4.0"
---

# quickbooks-client

Motoko bindings for a curated slice of the [QuickBooks Online Accounting API
v3](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account):
**Customer, Invoice, Payment, Item, Account**. Schemas were transcribed from
Intuit's official XSD. All 12 operations live in `Apis/DefaultApi.mo`:
`saveCustomer`/`getCustomer`, `saveItem`/`getItem`, `saveAccount`/`getAccount`,
`saveInvoice`/`getInvoice`/`sendInvoice`, `savePayment`/`getPayment`, and `query_`
(trailing underscore — `query` is a reserved word in Motoko).

## Trigger phrases

Reach for this skill on any request mentioning: QuickBooks, QBO, invoice,
"bill a customer", "send an invoice", record/receive a payment, customer,
accounting, bookkeeping, chart of accounts, item/product/service,
"sync to QuickBooks".

**Not in this slice:** Estimate, Bill, Vendor, PurchaseOrder, CreditMemo and the
rest of the QBO entity set — the spec is hand-curated to Customer, Invoice,
Payment, Item and Account. If a request needs one of the others, say so rather
than mapping it onto Invoice; the spec has to be re-spun from Intuit's XSD
first.

## How QuickBooks authentication works (read before wiring)

QBO uses **OAuth 2.0 Authorization Code** — there is no static API key. Each
end-user authorises their QuickBooks company; the app exchanges the authorization
code for a short-lived **Bearer access token** (~1 hour) and passes it to the
client at call time. On expiry the API returns HTTP 401 — surface a
`#Err("auth_expired")` result and re-authenticate off-chain.

Two identifiers travel with every call:
- **`realmId`** — the QuickBooks *company id*, obtained during the OAuth handshake.
  It is the first argument to every operation.
- **`minorversion`** — the API minor version (default `"75"`); pass `""` to omit
  and use the account default.

**The token exchange is itself an on-chain outcall** to Intuit's token endpoint
and needs the app's **Client Secret**. Two hazards (identical to the googlemail
connector):
- **`is_replicated = ?false` on the exchange too** — the token response is
  non-deterministic, so a replicated exchange duplicates across ~13 replicas and
  fails IC consensus.
- **The Client Secret leaks with exported source** — Caffeine can export the app
  to a `.zip` or public GitHub repo, carrying the secret along. Scope it minimally
  and rotate if the source is shared.

Persist the per-user refresh/session token across upgrades (stable memory) so a
redeploy doesn't force re-authentication. OAuth scope: `com.intuit.quickbooks.accounting`.

## Create vs. update vs. delete (important QBO semantics)

- **Create and update BOTH use the `save<Entity>` (POST) operation.** It's an
  *update* when the body carries the entity's `Id` **and** current `SyncToken`
  (fetch them first via `get<Entity>`); set `sparse = ?true` for a partial update.
  Without `Id`/`SyncToken` it's a create.
- **Delete** (transactions only — `Invoice`, `Payment`): call `saveInvoice` /
  `savePayment` with `operation = ?#delete` and a body carrying `Id` + `SyncToken`.
  The `operation` argument is **optional** (`?SaveInvoiceOperationParameter`),
  not a bare variant. Pass **`null` for a normal create or update** — the client
  then omits the query parameter entirely, which is what QBO wants; the spec
  says "Omit for create/update; 'delete' removes the invoice". Only `?#delete`
  is routinely needed. Name-list entities
  (`Customer`, `Item`, `Account`) are **not deletable** — set `Active = ?false`
  to deactivate instead (their `save*` ops take no `operation` argument).
- **Responses are wrapped**: `getCustomer` returns `CustomerResponse` with a
  `Customer` field (and a `time`); same shape per entity. `query_` returns a
  `QueryResponse` whose `QueryResponse` field holds arrays per entity type.
  The operation is `query_`, not `query`.
- **Invoice lines and Payment lines are different types.** `Invoice.Line` is
  `[Line]`, where `DetailType` is **required**. `Payment.Line` is
  `[PaymentLine]` — `{Amount, LinkedTxn, …}` with **no** `DetailType`, which is
  what Intuit actually sends when a payment is applied to invoices. They were
  one shared type until 0.2.0, and that made every payment response fail to
  decode.

## Frontend surfaces (two pages)

Like any per-user OAuth connector, an app needs **two** surfaces:
- An **admin-gated Intuit app configuration page** — the **Client ID** and
  **Client Secret** are canister-wide, set once by an admin; never expose the
  Client Secret to ordinary users.
- A **per-user OAuth 2.0 handshake page** — each user connects their own
  QuickBooks company (yielding their `realmId` + token); re-prompt on HTTP 401.

## Usage

```mo:quickbooks-client
import { saveInvoice; getInvoice; sendInvoice; saveCustomer }
  "mo:quickbooks-client/Apis/DefaultApi";
import Invoice "mo:quickbooks-client/Models/Invoice";
import { defaultConfig } "mo:quickbooks-client/Config";

let cfg = {
  defaultConfig with
    auth          = ?#bearer "<off-chain OAuth2 access token>";
    is_replicated = ?false;  // non-replicated: required for writes; reads too
};
let realmId = "<company id from OAuth handshake>";

// Build an invoice: one sales line, $100, item "1", billed to customer "58".
// Invoice has no required fields → init {} then record-update the optionals.
// NOTE: DetailType is REQUIRED on a Line, and its variants are lowercase.
let inv = {
  Invoice.init {} with
    CustomerRef = ?{ value = "58"; name = null };
    Line = ?[ {
      DetailType          = #salesitemlinedetail;   // required; lowercase variant
      Amount              = ?100.0;
      Description         = ?"Consulting";
      SalesItemLineDetail = ?{ ItemRef = ?{ value = "1"; name = null };
                               Qty = ?1.0; UnitPrice = ?100.0; TaxCodeRef = null; ServiceDate = null };
      Id = null; LineNum = null; LinkedTxn = null;
    } ];
};
// saveInvoice(config, realmId, invoice, minorversion, operation)
// `operation` is optional: null omits it — the create/update path.
let created = await* saveInvoice(cfg, realmId, inv, "75", null);
// Email it to the customer (config, realmId, invoiceId, sendTo, minorversion):
// ignore await* sendInvoice(cfg, realmId, "<invoiceId>", "[email protected]", "75");
```

## Notes

- **Use `is_replicated = ?false` for writes** (`save*`, `sendInvoice`, delete via
  `operation = ?#delete`). These outcalls are non-idempotent and QBO's response is
  non-deterministic; in replicated mode every replica issues the request — creating
  duplicate invoices/payments and failing IC consensus. Reads (`get*`, `query_`)
  also use `?false` (one node, ~13× cheaper).
- **Update needs a fresh `SyncToken`** — always `get<Entity>` first, copy its
  `SyncToken` into the body, then `save<Entity>`. A stale token → HTTP 400
  ("stale object").
- `minorversion` defaults to `"75"`; pass `""` to omit.
- QBO returns errors as an `ErrorResponse` whose list field is `Fault.Error_` —
  note the trailing underscore, `Error` being reserved — so surface
  `Fault.Error_[0].Message` to the caller; never blind-retry a write.
- Sandbox vs production: point the client host at
  `sandbox-quickbooks.api.intuit.com` for the Intuit sandbox company during
  development (edit the server in `Config`), and `quickbooks.api.intuit.com` for
  production.

© caffeinelabs · Apache-2.0 · caffeinelabs/skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
quickbooks-online-mcp-server reason-machines Подключает ассистента к серверу QuickBooks Online для управления счетами, контрагентами и финансовыми отчётами через протокол MCP. CX Codex +1 166установок quickbooks membrane Подключает QuickBooks через Membrane: читает и создаёт счета, клиентов, платежи прямо из чата. CX Codex +1 338установок QuickBooks Automation Claude Office Skills Скилл QuickBooks Automation для Claude Code автоматизирует работу с QuickBooks — от счетов и расходов до сверки банковских выписок и финансовых отчётов. Ведёт бухгалтерию из интерфейса агента. CX Codex +1 4 900установок QuickBooks Online mindstone MCP-сервер связывает ИИ-агента с QuickBooks Online: он работает со счетами, клиентами, поставщиками и финансовыми отчётами. CX Codex +1 ★ 14звёзд репо quickbooks-mcp laf-rge MCP-сервер связывает чат с QuickBooks Online для работы с бухгалтерией на понятном языке. Он строит финансовые отчёты и находит контрагентов по именам, а не по внутренним ID. CX Codex +1 ★ 13звёзд репо LedgerCrossing for QuickBooks Desktop LedgerCrossing MCP-сервер LedgerCrossing for QuickBooks Desktop для Claude Code подключает ИИ-агента к QuickBooks Desktop через LedgerCrossing. Агент может искать операции, читать данные и менять записи компании. CX Codex +1

Из того же набора33

Весь набор →
connector-x Скилл connector-x для Claude Code, Codex, Cursor и других платформ. Задаёт правила интеграции канистр на Motoko с X API v2 через пакет x-client и пользовательский OAuth 2.0 PKCE. CX Codex +1 11 600установок connector-weatherapi Скилл connector-weatherapi задаёт правильный способ читать погоду в Caffeine-сборках: через mops-пакет weatherapi-client, а не самодельные вызовы ic.http_request. CX Codex +1 11 400установок connector-spotify Скилл connector-spotify для Caffeine-сборок на Motoko: подключает Spotify Web API через пакет spotify-client и запрещает самодельные HTTP-вызовы. CX Codex +1 10 700установок connector-tmdb Скилл connector-tmdb для работы с данными фильмов, сериалов и актёров через The Movie Database API в Motoko-проектах на Internet Computer. CX Codex +1 10 300установок migrating-motoko-actors Скилл migrating-motoko-actors помогает переносить состояние актора Motoko между апгрейдами канистры и менять схему stable-полей через цепочку миграций в migrations/. CX Codex +1 8 600установок troubleshooting-motoko-migrations Скилл troubleshooting-motoko-migrations для Claude Code разбирает ошибки цепочки Motoko, когда диагностика не совпадает с main.mo или правка миграции не срабатывает. CX Codex +1 8 600установок writing-motoko Скилл writing-motoko для Claude Code задаёт актуальные правила Motoko, архитектуры и mops для разработки бэкенда на Internet Computer. CX Codex +1 8 600установок extension-http-endpoints Скилл extension-http-endpoints настраивает приём входящих HTTPS-запросов в бэкенд-канистрах Motoko. Позволяет обрабатывать вебхуки Stripe, колбэки Telegram и запросы проверки доступности. CX Codex +1 7 200установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой