`ptkl integration`

Manage platform integrations: lifecycle (install/activate/…), typed interfaces for the first-party integrations, and a generic JSON-RPC passthrough.

Overview

Integrations are not platform primitives like component/workflow, which exist on every project by default. An integration is installed and activated per project and is subscription-gated, so it lives under one ptkl integration namespace instead of as flat top-level commands. This mirrors the SDK exactly: Integrations (@ptkl/sdk/beta) is a façade mapping an integration id to a typed client via getInterfaceOf(id), with uniform list()/isInstalled(id)/isActive(id) methods, reached through the integrations gateway (IntegrationsBaseClient, host/luma/integrations) — see Toolkit Overview → The Gateway Model.

There are three invocation layers:

Lifecycle (this page, top level) — uniform for every integration: list | install | uninstall | activate | deactivate | onboarding | marketplace | explore.
Typed interfaces — first-party integrations with an SDK client: payments, mail, dms, timber, serbia. Each subtree pre-checks that its integration is active before calling through, and fails with a friendly hint instead of a raw 403 if it isn't:

protokol-payments is not active for this project — run `ptkl integration activate protokol-payments`

Generic passthrough — ptkl integration run <id> <method>, for satellites and any provider without a typed client. Same door as ptkl satellite execute.

No ecommerce here

The protokol-ecommerce integration (storefront domains/onboarding) is intentionally not exposed under ptkl integration — automate the underlying protokol-ecommerce::* / protokol-inventory::* components via ptkl component instead.

Lifecycle subcommands

Subcommand	Description
`list`	List integrations installed on the current project
`install <id>`	Install an integration on the current project
`uninstall <id>`	Uninstall an integration from the current project
`activate <id>`	Activate an installed integration
`deactivate <id>`	Deactivate an installed integration
`onboarding <id>`	Advance/update the onboarding state of an installed integration
`marketplace`	List marketplace-available integrations (subscription/geo aware)
`explore`	List explorable integration templates (subscription/geo aware)
`run <id> <method>`	Invoke a satellite command on an integration (generic JSON-RPC passthrough)

# See what's installed, then bring payments online
ptkl integration list
ptkl integration install protokol-payments
ptkl integration activate protokol-payments

# Advance an onboarding step
ptkl integration onboarding protokol-payments --step merchant-details --data '{"merchant_id":"..."}'

# Generic passthrough (satellites, or any provider without a typed subtree)
ptkl integration run my-satellite echo --params '{"inputs":{"message":"hello"}}'

--data/--params on lifecycle commands take a JSON string.

Typed interfaces

Interface	Integration id	Wraps
`integration payments`	`protokol-payments`	SDK `Payments` — see Payments
`integration mail`	`protokol-mail`	SDK `Mail` — see Mail
`integration dms`	`protokol-dms`	SDK `DMS` — see DMS
`integration timber`	`protokol-timber`	SDK `Timber` — see Timber
`integration serbia`	`serbia-minfin` / `nbs` / `protokol-minimax`	SDK `VPFR`/`Invoicing`/`NBS`/`SerbiaMinFin`/`Minimax` — see Serbia MinFin, NBS

Every subcommand under a typed interface pre-checks isActive(<id>) before issuing a request.

`ptkl integration payments`

Payments integration: transactions, payment links, refunds/void/cancel, provider settings. --provider accepts monri | wspay | stripe | braintree. Full field reference: Payments.

Subcommand	Description
`list`	List payment transactions for a user (`-u/--user`, `-s/--status`, `--sort-by`, `--sort-direction`, `-l/--limit`, `--page`)
`get`	Get a single transaction (`-p/--provider`, `-u/--user`, `-t/--tx`)
`link`	Create a payment link (`-p/--provider`, `-u/--user`, `-d/--description`, `-a/--total-amount` or `-i/--items`, `--token`, `--is-token-request`, `--redirect-url`, `--lang`)
`token-request`	Create a token-request link to tokenize a card without charging it
`direct-pay`	Charge a previously tokenized card directly (`--token` required)
`refund`	Refund a transaction
`void`	Void a pending transaction
`cancel`	Cancel (deactivate) a payment link
`settings`	Get the merchant settings for a provider

ptkl integration payments link \
  --provider monri --user user-123 \
  --total-amount 15,00 --description "Order #456" \
  --redirect-url https://myapp.com/payment/complete

ptkl integration payments refund --provider monri --user user-123 --tx tx-id-789

--total-amount and --items are mutually exclusive (exactly one is required for link/direct-pay).

`ptkl integration mail`

Protokol Mail integration: send/list/get/resend emails, manage attachments. Full field reference: Mail.

Subcommand	Description
`send`	Send an email (`-t/--to`, `-s/--subject`, `-b/--body`, `--cc`, `--bcc`, `--reply-to`, `--sender-name`, `-a/--attachments`)
`list`	List emails, paginated (`--status`, `--page`, `--limit`)
`get <messageId>`	Get a single email
`resend <messageId>`	Resend a previously failed email
`attachments list <messageId>`	List attachment metadata for an email
`attachments download <messageId> <attachmentId>`	Download an attachment's binary content (`-o/--out` required)

ptkl integration mail send \
  --to billing@example.com --subject "Invoice #123" \
  --body "<p>Please find your invoice attached.</p>"

ptkl integration mail attachments download <messageId> <attachmentId> --out ./attachment.pdf

--to/--cc/--bcc accept comma-separated addresses.

`ptkl integration dms`

Protokol DMS integration: files/libraries/dirs, data conversion, OCR, document templates, plus three management groups — backup, policies, reminders. Full field reference: DMS (Protokol Media).

Files & libraries

Subcommand	Description
`upload`	Upload local files (`--file <paths...>`, `-d/--dir`, `--public`, `--replace`, `--expires-at`, `-m/--metadata`)
`download <key>`	Download a file's binary content (`-o/--out` required)
`libraries`	List DMS libraries for the current project
`dirs list` \| `dirs create <path>` \| `dirs delete <path>`	Manage library directories

ptkl integration dms upload --file ./invoice.pdf --dir /invoices/2024
ptkl integration dms download invoices/2024/invoice-001.pdf --out ./invoice.pdf

Data conversion

convert mirrors the JSON/CSV/Excel matrix from DMS — Data Conversion:

Subcommand	Description
`convert data`	Generic conversion via `--from`/`--to` (`json`\|`csv`\|`excel`\|`xlsx`)
`convert info` \| `convert validate`	Inspect or validate data without converting
`convert json-to-csv` \| `convert csv-to-json`	JSON ⇄ CSV
`convert json-to-excel` \| `convert csv-to-excel`	JSON/CSV → Excel (`.xlsx`, `-o/--out` required)
`convert excel-to-json` \| `convert excel-to-csv`	Excel → JSON/CSV

Each subcommand reads its input from -i/--input <path>; binary results (Excel) require -o/--out, text/JSON results print to stdout unless -o/--out is given.

OCR & documents

Subcommand	Description
`ocr`	Run OCR extraction (`-m/--model`, `-k/--image-key` or `-i/--image-file`, `-b/--boundary`)
`document create` \| `get` \| `get-raw` \| `update` \| `delete` \| `list` \| `list-deleted` \| `restore` \| `comment` \| `generate` \| `revisions` \| `revision`	Templated document CRUD, revisions, and rendering — see DMS — Document Templates

Backup — library export archives

internal/media/controllers/v3/ library exports: point-in-time snapshots of the project's library (or a directory within it) as a downloadable archive. v3 resolves the project's single library server-side from the auth context — no library uuid is passed on the command line.

Subcommand	Description
`backup create`	Create an export archive (`-p/--path` to scope to a directory, `--archive-format zip\\|tar\\|tar.gz`)
`backup list`	List export archives for the project's library
`backup get <exportUuid>`	Get a single export archive (metadata + download URL)

ptkl integration dms backup create --path /invoices --archive-format zip
ptkl integration dms backup list

Policies — quota / file-type / notification

Resolves platform-default → library → directory. Omit --dir for the library-level policy.

Subcommand	Description
`policies get [--dir <path>]`	Get the effective policy for the project's library or a directory
`policies set [--dir <path>] -p <json>`	Set/update the project's library or a directory policy

ptkl integration dms policies get
ptkl integration dms policies set --dir /uploads --payload '{"max_file_size_mb":50}'

Reminders — notification-rules engine

Drives the recurring "Media reminder: <file>" emails.

Subcommand	Description
`reminders list`	List notification rules for the project's library
`reminders create`	Create a recurring reminder (`--media-uuid` or `--file-key`, `--frequency daily\\|weekly\\|monthly\\|yearly`, `--start-at`, `--interval`, `--end-at`, `--max-occurrences`, `--recipient-email`)
`reminders delete <ruleUuid>`	Delete a notification rule

ptkl integration dms reminders create \
  --file-key contracts/lease.pdf --frequency monthly \
  --start-at 2026-08-01T09:00:00Z --recipient-email ops@example.com

`ptkl integration timber`

Typed interface for the Timber audit log — query/write/usage. Full field reference: Timber.

Subcommand	Description
`query`	Query audit-log entries (filters: `--source`, `--level`, `--from`/`--to`, `--actor-id`, `--actor-name`, `--actor-type`, `--action`, `--resource-type`, `--resource-id`, `--request-uuid`, `-s/--search`, `-l/--limit`, `-c/--cursor`)
`write`	Write a log entry (`-m/--message`, `--level`, `--service`, `--resource-type`, `--resource-id`, `--resource-name`, `-a/--attributes`, `--trace-id`, `--span-id`, `--request-id`)
`usage`	Show Timber ingestion usage for the current project

ptkl integration timber query --level error --search "payment failed" --limit 50
ptkl integration timber write --message "Order confirmation sent" --level info --service checkout

ptkl logs back-compat alias

The pre-existing top-level ptkl logs command is now a thin alias of integration timber query — same underlying call, but ptkl logs keeps its original flag set (--source, --level, --action, --resource-type, -s/--search, -l/--limit, -t/--tail, --interval, --json) and does not gain timber query's extended filters (--from/--to, --actor-id/--actor-name/--actor-type, --resource-id, --request-uuid, -c/--cursor). Kept for backward compatibility; new scripts should prefer ptkl integration timber query.

`ptkl integration serbia`

Serbia-market integrations: VPFR fiscalization, SEF/eOtpremnica e-invoicing, VAT recording, NBS/ IPS-QR, MinFin receipt extraction, Minimax accounting. Seven subgroups, each pre-checking the relevant integration id (serbia-minfin for vpfr/sef/eotpremnica/vat/minfin, nbs for nbs, protokol-minimax for minimax). See also Serbia MinFin and NBS.

`vpfr` — fiscalization (cash registers, receipts, reports)

Subcommand	Description
`vpfr registers list` \| `add`	Cash register (ESIR) list/add (`add` uploads an optional `--crt`/`--key` certificate pair)
`vpfr fiscal-invoice create` \| `get <requestId>`	Create/poll a fiscal receipt
`vpfr receipt create`	Alias of `fiscal-invoice create`
`vpfr report`	Presek stanja (Z-report) for a date range (`--from`, `--to`)
`vpfr tax-rates`	List fiscal tax rates/labels
`vpfr status`	VPFR connectivity status
`vpfr sync-offline`	Manually trigger a sync of offline-queued fiscal receipts

ptkl integration serbia vpfr fiscal-invoice create --data '{"register_id":"...","items":[...]}'
ptkl integration serbia vpfr report --from 2026-07-01 --to 2026-07-31

`sef` — Sistem Elektronskih Faktura (e-invoices)

Subcommand	Description
`sef sales list` \| `get` \| `create` \| `storno`	Sales (outbound) e-invoices
`sef purchase list` \| `get` \| `accept` \| `reject`	Purchase (inbound) e-invoices
`sef request <method> <endpoint>`	Generic passthrough for routes without a dedicated subcommand

ptkl integration serbia sef sales create --user user-123 --data '{"buyer":{...},"items":[...]}'
ptkl integration serbia sef purchase accept --provider sef --user user-123 --id inv-789

`nbs` — National Bank of Serbia

Subcommand	Description
`nbs search --vat-number <vat>`	Search NBS company records by VAT number
`nbs ips-qr generate`	Generate an IPS QR payment code (`-c/--code`, `-s/--size`, `-l/--lang`)
`nbs ips-qr validate`	Validate an IPS QR code string (`-q/--qr`, `-l/--lang`)

ptkl integration serbia nbs ips-qr generate --code '{"TransactionType":"PR", ...}' --size 300

`minfin` — receipt extraction & conto

Subcommand	Description
`minfin receipt from-url`	Extract a receipt from a fiscal QR code URL (`-u/--url`, `-s/--source`)
`minfin receipt from-qr`	Extract a receipt from a base64 QR code image
`minfin conto`	List conto (chart of accounts) entries

`minimax` — accounting (representative surface + generic passthrough)

Minimax exposes roughly 80 REST methods. ptkl integration serbia minimax wraps a representative subset (accounts, customers, documents, issued-invoices, journals — each with list/ get) plus settings, and a generic request <method> <endpoint> passthrough for everything else, relative to .../api/orgs/{org}/.

ptkl integration serbia minimax accounts list --user user-123 --org 42
ptkl integration serbia minimax request GET accounts/42 --user user-123 --org 42

Gated subtrees — no reachable backend yet

eotpremnica, vat, and minimax are fully built (route shapes match the real karadjordje API), but integrations-api does not yet proxy these routes to a backend, so invoking any command under them fails fast with a [unavailable] notice instead of a confusing 404/502. vpfr registers update/delete are gated for the same reason — the vpfr gateway proxy only forwards POST/GET. Run --help on the affected commands to see the [unavailable] marker.

ptkl integration

Overview

Lifecycle subcommands

Typed interfaces

ptkl integration payments

ptkl integration mail

ptkl integration dms

Files & libraries

Data conversion

OCR & documents

Backup — library export archives

Policies — quota / file-type / notification

Reminders — notification-rules engine

ptkl integration timber

ptkl integration serbia

vpfr — fiscalization (cash registers, receipts, reports)

sef — Sistem Elektronskih Faktura (e-invoices)

nbs — National Bank of Serbia

minfin — receipt extraction & conto

minimax — accounting (representative surface + generic passthrough)

See Also