# FIZ Public API

> REST API for certified invoicing in Portugal: issue invoices reported to the tax authority (AT), manage customers, items, series, recurring invoices, pro formas and transport documents. Base URL `https://api.fiz.co`. OpenAPI 3 document at https://api.fiz.co/-json.

## Choose your path

- **Invoice for your own company** → API key in the `x-api-key` header, created at https://app.fiz.co/settings/integrations. Follow the [quickstart](https://api.fiz.co/docs/quickstart.md) (key → company check → customer and item → draft → PDF → issue), then the [API overview](https://api.fiz.co/docs/api.md) and the OpenAPI document.
- **Build a product that invoices for its customers** → OAuth partner app. Read [Build an app with FIZ](https://api.fiz.co/docs/apps.md): registration, PKCE, signup, scopes, token lifecycle, retries.
- **Connect an AI assistant** (Claude, ChatGPT, Claude Code) → MCP server at `https://api.fiz.co/mcp`. Read the [MCP connector page](https://api.fiz.co/docs/mcp.md).

## Before you write anything

- Creating a draft (`POST /invoices`) stores real customer, item and invoice data in the connected company. It reports nothing to AT and can be deleted. Drafts are the test surface.
- `POST /invoices/{id}/issue`, `/pay`, `/cancel`, `POST /invoices/credit-notes` and `POST /transport-documents/{id}/issue` are fiscal acts: reported to AT, irreversible. Check `GET /company` for readiness first and send the draft's `updatedAt` as `expectedUpdatedAt` when issuing.
- Creating or resuming a recurring schedule (`/invoices/scheduled`) makes FIZ issue and report documents automatically.
- Development partner apps run against production FIZ. There is no fiscal sandbox.
- Every write accepts an `Idempotency-Key` header. Send one per logical write and reuse it on retry; a replay returns the original response.
- Validation is strict: unknown fields are rejected with 400. Send only documented fields.

## Docs

- [Quickstart](https://api.fiz.co/docs/quickstart.md): the API-key path in five runnable requests, and how to hand the work to a coding agent. Portuguese: https://api.fiz.co/docs/quickstart.md?lang=pt
- [API overview](https://api.fiz.co/docs/api.md): authentication, issuing flow, series and templates, recurring invoices, idempotency, MCP.
- [Partner app guide](https://api.fiz.co/docs/apps.md): OAuth for registered apps. Portuguese: https://api.fiz.co/docs/apps.md?lang=pt
- [MCP connector](https://api.fiz.co/docs/mcp.md): tools, permissions, connecting Claude and ChatGPT. Portuguese: https://api.fiz.co/docs/mcp.md?lang=pt
- [OpenAPI JSON](https://api.fiz.co/-json): the complete endpoint contract, about 140 KB. Fetch it and read the paths you need rather than loading it whole. YAML: https://api.fiz.co/-yaml
- [Swagger UI](https://api.fiz.co/): for humans; renders client-side.

## Tools for coding agents

- [fiz-invoicing skill](https://github.com/FIZ-co/fiz-invoicing-skill): Claude Code / Codex skill with Portuguese VAT rules, field reference and a curl wrapper.
- [Partner app example](https://github.com/FIZ-co/partner-app-demo): working OAuth partner app in Node.js.

## Optional

- [Portuguese OpenAPI](https://api.fiz.co/-json-pt): same contract, Portuguese descriptions.
- [Help centre](https://help.fiz.co), [plans](https://fiz.co/planos), support@fiz.co