Invico pro vývojáře

Faktury, kontakty, náklady a sklady přes jednoduché REST API. Podepsané webhooks pro události, MCP server pro AI agenty. Klíč vytvoříte v Nastavení → Integrace.

Rychlý start

curl https://app.invico.org/v1/documents?limit=5 \
  -H "Authorization: Bearer invk_…"

Čtecí klíč smí jen GET; zapisovací i POST/PUT/DELETE. Vše je vždy vázané na firmu klíče — žádný tenant parametr. Odpovědi chyb: {"error":"code"} — 401 špatný klíč, 403 scope/plán, 429 rate/kvóta, 409 kolize čísla dokladu.

Endpointy

Metoda + cesta	Popis
GET /v1/ping	kontrola klíče → {ok, company}
GET /v1/documents	seznam dokladů — ?status=, ?kind=, ?contactId=, ?limit=, ?offset=
POST /v1/documents	vytvoření/upsert (s id = update); položky v items[]
GET /v1/documents/:id	doklad + položky + platby + události
PUT /v1/documents/:id	úprava dokladu
POST /v1/documents/:id/status	{status:"issued"|"paid"|"sent"|"cancelled"}
POST /v1/documents/:id/finalize	koncept → vystaveno (+ odeslání)
POST /v1/documents/:id/send	e-mail s PDF a veřejným odkazem
POST /v1/documents/:id/payments	{amount, currency, paidAt, method, note}
GET|POST /v1/contacts	kontakty — upsert {name, ico, dic, address, email, kind}
GET|POST /v1/expenses	náklady — včetně recurEvery pro opakované
GET /v1/collections/:kind	ceník, kategorie, projekty…
GET /v1/ares?ico=	dotaz do ARES (český registr)
POST /v1/mcp	JSON-RPC rozhraní pro agenty (stejné nástroje jako stdio MCP)

OpenAPI spec: /openapi.yaml. Limpa pro LLM: /llms.txt.

Webhooks

Odběry nastavíte v aplikaci (Nastavení → Integrace → Webhooky). Každá doručovka je POST JSON s hlavičkami X-Invico-Event, X-Invico-Delivery a podpisem X-Invico-Signature: sha256=<hmac-sha256 body> podle endpoint secretu. Filtr událostí: *, document.*, nebo přesný název (payment.matched, quote.negotiation…). Na plánu Max lze navíc vlastní JSON šablonou přemapovat payload — předlohy pro Slack/Discord/Teams jsou připravené v UI.

POST https://vas-server.cz/hook
X-Invico-Event: payment.matched
X-Invico-Signature: sha256=…

{"id":"…","event":"payment.matched","companyIco":"25549260",
 "createdAt":"2026-10-19T10:00:00Z","data":{"documentId":"…","amount":12100}}

MCP server

apps/mcp v repozitáři je stdio MCP server vystavující invico_* nástroje — vystavení faktury, čtení dokladů, kontakty, přehledy. Stejná rozhraní jede i přes POST /v1/mcp (JSON-RPC). Připojení v klientovi:

{ "mcpServers": { "invico": {
    "command": "invico-mcp",
    "env": { "INVICO_API_KEY": "invk_…", "INVICO_API_BASE": "https://app.invico.org" }
} } }