jaz-api

Documentation

# jaz-api — Claude Code Plugin

[![Version](https://img.shields.io/badge/version-1.8.0-blue)](https://github.com/teamtinvio/claude-plugins)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/teamtinvio/claude-plugins/blob/main/LICENSE)
[![Plugin](https://img.shields.io/badge/claude--code-plugin-purple)](https://github.com/teamtinvio/claude-plugins)

Teaches any AI agent the correct field names, payload shapes, auth patterns, and dependency ordering for the [Jaz](https://app.jaz.ai)/[Juan](https://app.juan.ac) REST API. **45 rules · 40+ endpoints · full error catalog · 5 reference files.**

## Installation

### Claude Code

```bash
/plugin install teamtinvio/claude-plugins
```

### Claude.ai

1. Download the `skills/jaz-api/` folder
2. **Settings > Capabilities > Skills > Upload skill**
3. Toggle on

Works with any agent that reads markdown skills.

## What the Skill Teaches

**Without the skill** — agents guess standard REST conventions and fail:
```
Authorization: Bearer <key>
POST /invoices       { issueDate, currencyCode: "USD", lineItems: [{ debit: 500 }] }
POST /payments       { amount: 100 }
PUT /chart-of-accounts  { chartOfAccounts: [...] }
```

**With the skill** — agents use the actual API contract:
```
x-jk-api-key: <key>
POST /api/v1/invoices             { valueDate, currency: { sourceCurrency: "USD" }, lineItems: [{ amount: 500, name: "..." }] }
POST /api/v1/invoice-payments     { payments: [{ paymentAmount: 100 }] }
POST /api/v1/chart-of-accounts    { accounts: [...] }
```

Covers invoices, bills, journals, credit notes, payments, bank records, FX, CoA, contacts, items, tax profiles, reports, and schedulers.

## What's Inside

```
skills/jaz-api/
├── SKILL.md                        # 45 rules, auth, patterns
└── references/
    ├── endpoints.md                # Request/response examples for every endpoint
    ├── errors.md                   # Every error encountered + root cause + fix
    ├── field-map.md                # Intuitive → actual field name mappings
    ├── dependencies.md             # Resource creation order (CoA → contacts → items → transactions → payments)
    └── full-api-surface.md         # Complete endpoint catalog, enums, search filters, limits
```

## Use Cases

- **Stripe → Jaz sync** — Map charges to invoices, create contacts on the fly, post payments on settlement
- **Monthly close** — Pull trial balance, flag imbalances, post adjusting journals, generate P&L and balance sheet
- **Legacy migration** — Create CoA, contacts, items, invoices, payments in dependency order across years of data
- **Multi-entity reporting** — Query SG and PH orgs, handle FX conversion, produce consolidated financials
- **Bank reconciliation** — Upload CSV statements, match transactions to open invoices/bills, post reconciling entries
- **O2C / P2P orchestration** — Full cycle: draft → approve → finalize → collect/pay → apply credits → reconcile

## Build on Jaz: Ledger, Software, Agents

Jaz is a programmable accounting platform engineered for the agentic era — every operation is an API call.

| Layer | What It Does |
|-------|-------------|
| **REST API** | 40+ endpoints: ledger, AR/AP, banking, reporting, FX |
| **This plugin** | 45 rules + field mappings + error catalog + dependency ordering, packaged as a portable skill |
| **Your agent** | Installs the skill, calls the API, runs multi-step accounting workflows autonomously |

No SDK. No integration layer. Install the skill, point at the API, build.

## Gotchas

Common failures agents hit. Full catalog in `references/errors.md`.

| Symptom | Fix |
|---------|-----|
| 401 on every request | Auth is `x-jk-api-key` header, not `Authorization: Bearer` |
| Invoice created in base currency despite passing `currencyCode: "USD"` | `currencyCode` string is silently ignored — use `currency: { sourceCurrency: "USD" }` |
| `lineItems[0].name is required` | Always include `name` on line items (unless `itemResourceId` is set) |
| `journalEntries is a required field` | Cash receipts/payments use `journalEntries`, not `lineItems` |
| Invoice finalized when you wanted draft | `saveAsDraft: false` is the default — and requires `accountResourceId` on every line item |
| Payment returns 200 but nothing happens | Field is `paymentAmount`, not `amount` |
| Phone number rejected | Must be E.164: `+65XXXXXXXX` (SG), `+63XXXXXXXXXX` (PH), no spaces |

## Known Limitations

| Endpoint | Status |
|----------|--------|
| Currency exchange rates | No rate-setting API. Enable currencies via API; rates set in UI (ECB auto-fetch as fallback). |
| `POST /api/v1/fixed-assets` | Returns 500 (known server bug). Create via UI. |
| `POST /api/v1/capsules` | Returns 500 (known server bug). |
| Tax profiles | Read-only. Pre-provisioned per org. Discover via `GET /api/v1/tax-profiles`. |

## License

MIT. Jaz is a portfolio product of Tinvio. All rights reserved.

> This is a read-only mirror. Pull requests will be auto-closed. For bugs or suggestions, email [[email protected]](mailto:[email protected]).
Keywords

Documentation
