Fatture in Cloud CLI Skill

Use the fic CLI to interact with the Fatture in Cloud API - Italy's most popular e-invoicing platform.

Prerequisites

• fic must be installed: composer global require 16bitsrl/fattureincloud-cli
• Must be authenticated: run fic auth:login if not yet configured
• A default company must be set: run fic company:set if not yet configured

Check status with: fic auth:status --json

Reference docs bundled with this skill

• references/api-basics.md - filtering, sorting, pagination, and response customization
• references/faqs-and-troubleshooting.md - API limitations, classic FAQ answers, errors, and quotas
• references/xml-import.md - XML import strategy, mapping behavior, and V.2025 notes

Authentication

# Interactive login (prompts for token or OAuth)
fic auth:login

# Direct token login (non-interactive, ideal for CI/agents)
fic auth:login --token=YOUR_ACCESS_TOKEN

# OAuth2 flow with client credentials
fic auth:login --client-id=ID --client-secret=SECRET

# Check auth status
fic auth:status
fic auth:status --json

# Refresh OAuth token
fic auth:refresh

# Logout
fic auth:logout

Company context

Most API calls require a --company-id parameter. Set a default to avoid repeating it:

# Interactive selection
fic company:set

# Direct set
fic company:set 12345

# Check current
fic company:current
fic company:current --json

When company_id is set as default, you still need to pass it as --company-id to API commands, but you can read it from fic company:current --json.

Plain-text search helpers

The raw API --q parameter uses Fatture in Cloud query syntax such as name like '%acme%'. For plain-text search, prefer the helper commands:

fic clients:search Acme --company-id=COMPANY_ID
fic clients:search Acme --company-id=COMPANY_ID --json
fic suppliers:search Studio --company-id=COMPANY_ID
fic products:search consulting --company-id=COMPANY_ID

When you use raw --q, write full query syntax:

fic api:list-clients --company-id=COMPANY_ID --q="name like '%acme%'" --json
fic api:list-suppliers --company-id=COMPANY_ID --q="name like '%studio%'" --json
fic api:list-products --company-id=COMPANY_ID --q="name like '%consulting%'" --json

Output formats

All API commands support multiple output formats:

• Default (JSON): Pretty-printed JSON (best for agents)
• --yaml: YAML output
• --minify: Compact single-line JSON (best for piping)
• --headers: Include HTTP response headers
• Human-readable tables are shown for list endpoints when not using --json/--yaml

Filtering with --q (query syntax)

The --q parameter uses a SQL-like query language based on field op value triplets.

Operators

Operator	Symbol
Equal	=
Not equal	<>, !=
Greater than	>
Greater or equal	>=
Less than	<
Less or equal	<=
Like	like
Not like	not like
Contains	contains
Starts with	starts with
Ends with	ends with
Is null	is null, = null
Is not null	is not null, != null

Values

• Strings: 'value' (single-quoted)
• Numbers: 46, 12.34
• Booleans: true, false

Combining filters

Use AND / OR and parentheses:

--q="date >= '2025-01-01' AND date <= '2025-12-31'"
--q="entity.name = 'Acme' AND amount_net > 1000"
--q="city = 'Milano' OR city = 'Roma'"

Filterable fields per endpoint

Endpoint	Filterable fields
listClients	id, code, name, type, vat_number, tax_code, address_street, address_postal_code, address_city, address_province, country, email, certified_email, phone, fax, notes, e_invoice, ei_code, created_at, updated_at
listSuppliers	id, code, name, type, vat_number, tax_code, address_street, address_postal_code, address_city, address_province, country, email, certified_email, phone, fax, notes, e_invoice, ei_code, created_at, updated_at
listProducts	id, name, code, net_price, gross_price, net_cost, description, category, notes, in_stock, created_at, updated_at
listIssuedDocuments	type, entity.id, entity.name, entity.vat_number, entity.tax_code, entity.city, entity.province, entity.country, date, number, numeration, any_subject, amount_net, amount_vat, amount_gross, next_due_date, created_at, updated_at
listReceivedDocuments	id, type, category, description, entity.id, entity.name, date, next_due_date, amount_gross, amount_net, amount_vat, invoice_number, created_at, updated_at
listReceipts	date, type, description, rc_center, created_at, updated_at
listF24	due_date, status, amount, description
listArchiveDocuments	date, category, description

Common filter examples

# Invoices from 2025
fic api:list-issued-documents --company-id=COMPANY_ID --type=invoice \
  --q="date >= '2025-01-01' AND date <= '2025-12-31'" --json

# Received documents from a specific supplier
fic api:list-received-documents --company-id=COMPANY_ID \
  --q="entity.name = 'Fornitore S.r.l.'" --json

# Received documents from 2025 by a specific supplier
fic api:list-received-documents --company-id=COMPANY_ID \
  --q="entity.name = 'Fornitore S.r.l.' AND date >= '2025-01-01' AND date <= '2025-12-31'" --json

# Unpaid invoices (next_due_date in the past)
fic api:list-issued-documents --company-id=COMPANY_ID --type=invoice \
  --q="next_due_date < '2025-03-18'" --json

# Client by VAT number
fic api:list-clients --company-id=COMPANY_ID \
  --q="vat_number = '12345678901'" --json

# Products over 100 EUR
fic api:list-products --company-id=COMPANY_ID \
  --q="net_price > 100" --json

IMPORTANT: Document list endpoints (issued, received) do NOT have --date-from / --date-to options. You MUST use --q with the date field to filter by date range. Only api:list-cashbook-entries has --date-from and --date-to as dedicated parameters.

Pagination

List endpoints return paginated results.

Parameter	Description	Default	Max
--page	Page number	1	-
--per-page	Items per page	50	100

The response includes pagination metadata: current_page, last_page, total, per_page, from, to, first_page_url, last_page_url, next_page_url, prev_page_url.

# Get page 2 with 25 items per page
fic api:list-clients --company-id=COMPANY_ID --page=2 --per-page=25 --json

# Get all invoices (first check total, then paginate)
fic api:list-issued-documents --company-id=COMPANY_ID --type=invoice --per-page=100 --json

Sorting with --sort

Use --sort with comma-separated field names. Prefix with - for descending order.

# Sort invoices by date descending
fic api:list-issued-documents --company-id=COMPANY_ID --type=invoice --sort=-date --json

# Sort clients by name ascending
fic api:list-clients --company-id=COMPANY_ID --sort=name --json

# Sort received documents by date desc, then amount asc
fic api:list-received-documents --company-id=COMPANY_ID --sort=-date,amount_net --json

Sortable fields per endpoint

Endpoint	Sortable fields
listClients	code, name, type, vat_number, tax_code, address_street, address_postal_code, address_city, address_province, country, email, certified_email, phone, fax, notes, e_invoice, ei_code, created_at, updated_at
listSuppliers	code, name, type, vat_number, tax_code, address_street, address_postal_code, address_city, address_province, country, email, certified_email, phone, fax, notes, e_invoice, ei_code, created_at, updated_at
listProducts	name, code, net_price, gross_price, net_cost, description, category, notes, in_stock, created_at, updated_at
listIssuedDocuments	entity.id, entity.name, entity.vat_number, entity.tax_code, entity.city, entity.province, entity.country, date, number, numeration, amount_net, amount_vat, amount_gross, next_due_date, created_at, updated_at
listReceivedDocuments	id, category, entity.id, entity.name, date, next_due_date, amount_gross, amount_net, amount_vat, created_at, updated_at
listReceipts	date, rc_center, created_at, updated_at
listF24	due_date, status, amount, description
listArchiveDocuments	date, category, description

Errors

Code	Meaning
401	Unauthorized - token missing, invalid or expired. Re-authenticate with fic auth:login
403	Forbidden - insufficient permissions/scopes, expired license, or hourly/monthly rate limit exceeded
404	Not found - the resource does not exist
409	Conflict - cannot perform the operation
422	Unprocessable entity - invalid request body (validation errors in response)
429	Too many requests - short-term rate limit exceeded. Wait for Retry-After seconds

Rate limits

Limit type	Quota	Window
Short-term	300 requests / 5 minutes	Sliding window, per company
Hourly	1,000 requests / hour	Fixed window, per company-app
Monthly	40,000 requests / month	Fixed window, per company-app (public) or per company (private)

Rate limit headers are included in every response: RateLimit-HourlyRemaining, RateLimit-HourlyLimit, RateLimit-MonthlyRemaining, RateLimit-MonthlyLimit.

When exceeded: 403 for hourly/monthly limits, 429 for short-term limits. Both include a Retry-After header.

Agents should treat 403 plus Retry-After as quota exhaustion, not just as a scope problem.

XML e-invoice import

The official API still does not accept raw XML uploads, but the CLI can recreate XML invoices through JSON:

# Preview a single XML
fic einvoice:import /absolute/path/to/fattura.xml --company-id=COMPANY_ID --dry-run

# Preview a signed XML.p7m file
fic einvoice:import /absolute/path/to/fattura.xml.p7m --company-id=COMPANY_ID --dry-run

# Import a folder of XML files (direction is auto-detected from XML content)
fic einvoice:import /absolute/path/to/xml-dir --company-id=COMPANY_ID --yes

Important notes:

• The CLI parses FatturaPA XML and recreates the document through the API
• Direction (issued/received) is automatically inferred from the XML: if the seller matches the company it is issued, if the buyer matches the company it is received, and self-invoice types (TD16-TD23, TD28, TD29) where the buyer is the company are treated as issued
• For issued XML imports, the recreated document should be an electronic invoice by default
• For received XML imports, treat electronic XML as the default case too, but remember that received documents can also come from non-electronic sources like receipts, foreign invoices, or scanned paper documents
• A recap is shown before import, and --dry-run is available for validation
• Signed .xml.p7m files are supported and unpacked before import
• XML attachments are carried over too; if there are multiple embedded attachments, they are bundled into a zip because Fatture in Cloud exposes one structured attachment slot (attachment_token)
• The import preserves XML-specific sections in ei_raw
• Supported e-invoice fields are mapped to structured Fatture in Cloud fields first; ei_raw is the fallback for unsupported sections
• If neither CedentePrestatore nor CessionarioCommittente matches the selected company, the importer must stop instead of proceeding
• The bundled XML import reference covers current V.2025 nuances (TD29, RF20, technical specs 1.9)

Scopes

Scopes follow the resource:level pattern. Levels: :r (read-only), :a (full access).

Scope	Description
situation:r	Dashboard, summary cards, deadlines
entity.clients:r/a	Clients
entity.suppliers:r/a	Suppliers
products:r/a	Products
issued_documents.invoices:r/a	Invoices
issued_documents.credit_notes:r/a	Credit notes
issued_documents.quotes:r/a	Quotes
issued_documents.proformas:r/a	Proforma invoices
issued_documents.receipts:r/a	Receipts (ricevute)
issued_documents.delivery_notes:r/a	Delivery notes (DDT)
issued_documents.orders:r/a	Orders
received_documents:r/a	All received documents (fatture passive)
receipts:r/a	Corrispettivi
taxes:r/a	F24 taxes
cashbook:r/a	Prima nota
archive:r/a	Archive
settings:r/a	Company settings
emails:r	Emails (read-only)
calendar:r/a	Scadenziario Plus
stock:r/a	Magazzino

Quick command reference

List all available commands

fic api:list

User & Companies

fic api:get-user-info
fic api:list-user-companies
fic api:get-company-info --company-id=COMPANY_ID
fic api:get-company-plan-usage --company-id=COMPANY_ID --category=documents

Clients

# List clients
fic api:list-clients --company-id=COMPANY_ID

# Get a specific client
fic api:get-client --company-id=COMPANY_ID --client-id=CLIENT_ID

# Create a client
fic api:create-client --company-id=COMPANY_ID --input='{"data":{"name":"Acme S.r.l.","vat_number":"IT12345678901","type":"company"}}'

# Modify a client
fic api:modify-client --company-id=COMPANY_ID --client-id=CLIENT_ID --input='{"data":{"name":"New Name"}}'

# Delete a client
fic api:delete-client --company-id=COMPANY_ID --client-id=CLIENT_ID

Suppliers

fic api:list-suppliers --company-id=COMPANY_ID
fic api:get-supplier --company-id=COMPANY_ID --supplier-id=SUPPLIER_ID
fic api:create-supplier --company-id=COMPANY_ID --input='{"data":{"name":"Fornitore S.r.l.","type":"company"}}'
fic api:modify-supplier --company-id=COMPANY_ID --supplier-id=SUPPLIER_ID --input='{"data":{"name":"New Name"}}'
fic api:delete-supplier --company-id=COMPANY_ID --supplier-id=SUPPLIER_ID

Products

fic api:list-products --company-id=COMPANY_ID
fic api:get-product --company-id=COMPANY_ID --product-id=PRODUCT_ID
fic api:create-product --company-id=COMPANY_ID --input='{"data":{"name":"Widget","net_price":100,"code":"WDG001"}}'
fic api:modify-product --company-id=COMPANY_ID --product-id=PRODUCT_ID --input='{"data":{"net_price":120}}'
fic api:delete-product --company-id=COMPANY_ID --product-id=PRODUCT_ID

Issued documents (invoices, quotes, orders, credit notes, etc.)

# List invoices
fic api:list-issued-documents --company-id=COMPANY_ID --type=invoice

# List invoices from 2025
fic api:list-issued-documents --company-id=COMPANY_ID --type=invoice \
  --q="date >= '2025-01-01' AND date <= '2025-12-31'" --json

# List quotes
fic api:list-issued-documents --company-id=COMPANY_ID --type=quote

# Get a document
fic api:get-issued-document --company-id=COMPANY_ID --document-id=DOC_ID

# Create an invoice
fic api:create-issued-document --company-id=COMPANY_ID --input='{"data":{"type":"invoice","entity":{"id":CLIENT_ID},"items_list":[{"name":"Service","net_price":1000,"qty":1,"vat":{"id":VAT_ID}}]}}'

# Modify a document
fic api:modify-issued-document --company-id=COMPANY_ID --document-id=DOC_ID --input='{"data":{...}}'

# Delete a document
fic api:delete-issued-document --company-id=COMPANY_ID --document-id=DOC_ID

# Get document totals
fic api:get-existing-issued-document-totals --company-id=COMPANY_ID --document-id=DOC_ID

# Get email data for sending
fic api:get-email-data --company-id=COMPANY_ID --document-id=DOC_ID

# Schedule email
fic api:schedule-email --company-id=COMPANY_ID --document-id=DOC_ID --input='{"data":{"sender_email":"you@example.com","recipient_email":"client@example.com","subject":"Invoice","body":"Please find attached."}}'

Attachments

Attachment upload for issued documents is a 2-step flow. The upload command does not attach the file directly to the document: it only returns an attachment_token.

# 1. Upload the file and get attachment_token
fic api:upload-issued-document-attachment \
  --company-id=COMPANY_ID \
  --field=filename=document.pdf \
  --field='attachment=@/absolute/path/to/document.pdf' \
  --json

# 2a. Attach it when creating a document
fic api:create-issued-document --company-id=COMPANY_ID --input='{
  "data": {
    "type": "invoice",
    "entity": {"id": CLIENT_ID},
    "attachment_token": "abc123..."
  }
}'

# 2b. Or attach it to an existing document
fic api:modify-issued-document \
  --company-id=COMPANY_ID \
  --document-id=DOCUMENT_ID \
  --input='{
    "data": {
      "attachment_token": "abc123..."
    }
  }'

# 3. Verify the attachment was linked
fic api:get-issued-document --company-id=COMPANY_ID --document-id=DOCUMENT_ID --json

Notes:

• filename must be a plain string
• attachment must use the uploaded file with @/absolute/path/to/file.pdf
• document-id is not accepted by the upload endpoint
• After attaching, verify attachment_url on the document response

E-Invoices (fattura elettronica)

# Send e-invoice to SDI
fic api:send-e-invoice --company-id=COMPANY_ID --document-id=DOC_ID

# Verify e-invoice XML
fic api:verify-e-invoice-xml --company-id=COMPANY_ID --document-id=DOC_ID

# Get e-invoice XML
fic api:get-e-invoice-xml --company-id=COMPANY_ID --document-id=DOC_ID

# Get rejection reason
fic api:get-e-invoice-rejection-reason --company-id=COMPANY_ID --document-id=DOC_ID

Received documents (fatture passive)

fic api:list-received-documents --company-id=COMPANY_ID
fic api:get-received-document --company-id=COMPANY_ID --document-id=DOC_ID
fic api:create-received-document --company-id=COMPANY_ID --input='{"data":{...}}'
fic api:modify-received-document --company-id=COMPANY_ID --document-id=DOC_ID --input='{"data":{...}}'
fic api:delete-received-document --company-id=COMPANY_ID --document-id=DOC_ID

# Filter by date range (use --q, NOT --date-from/--date-to)
fic api:list-received-documents --company-id=COMPANY_ID \
  --q="date >= '2025-01-01' AND date <= '2025-12-31'" --json

# Filter by supplier name
fic api:list-received-documents --company-id=COMPANY_ID \
  --q="entity.name = 'Fornitore S.r.l.'" --json

Attachments

Attachment upload for received documents is a 2-step flow. The upload command does not attach the file directly to the document: it only returns an attachment_token.

# 1. Upload the file and get attachment_token
fic api:upload-received-document-attachment \
  --company-id=COMPANY_ID \
  --field=filename=invoice.pdf \
  --field='attachment=@/absolute/path/to/invoice.pdf' \
  --json

# 2a. Attach it when creating a document
fic api:create-received-document --company-id=COMPANY_ID --input='{
  "data": {
    "type": "expense",
    "entity": {"name": "Fornitore S.r.l."},
    "attachment_token": "abc123..."
  }
}'

# 2b. Or attach it to an existing document
fic api:modify-received-document \
  --company-id=COMPANY_ID \
  --document-id=DOCUMENT_ID \
  --input='{
    "data": {
      "attachment_token": "abc123..."
    }
  }'

# 3. Verify the attachment was linked
fic api:get-received-document --company-id=COMPANY_ID --document-id=DOCUMENT_ID --json

Notes:

• filename must be a plain string
• attachment must use the uploaded file with @/absolute/path/to/file.pdf
• document-id is not accepted by the upload endpoint
• After attaching, verify attachment_url or attachment_preview_url on the document response

Receipts (corrispettivi)

fic api:list-receipts --company-id=COMPANY_ID
fic api:get-receipt --company-id=COMPANY_ID --document-id=DOC_ID
fic api:create-receipt --company-id=COMPANY_ID --input='{"data":{...}}'
fic api:get-receipts-monthly-totals --company-id=COMPANY_ID

Taxes (F24)

fic api:list-f24 --company-id=COMPANY_ID
fic api:get-f24 --company-id=COMPANY_ID --document-id=DOC_ID
fic api:create-f24 --company-id=COMPANY_ID --input='{"data":{"amount":1000,"description":"IRPEF","due_date":"2025-06-16"}}'
fic api:modify-f24 --company-id=COMPANY_ID --document-id=DOC_ID --input='{"data":{...}}'
fic api:delete-f24 --company-id=COMPANY_ID --document-id=DOC_ID

Cashbook (prima nota)

# Cashbook is the ONLY endpoint with --date-from / --date-to parameters
fic api:list-cashbook-entries --company-id=COMPANY_ID --date-from=2025-01-01 --date-to=2025-12-31
fic api:get-cashbook-entry --company-id=COMPANY_ID --document-id=DOC_ID
fic api:create-cashbook-entry --company-id=COMPANY_ID --input='{"data":{...}}'

Archive

fic api:list-archive-documents --company-id=COMPANY_ID
fic api:get-archive-document --company-id=COMPANY_ID --document-id=DOC_ID
fic api:create-archive-document --company-id=COMPANY_ID --input='{"data":{"date":"2025-01-15","description":"Contract"}}'

Settings

fic api:get-tax-profile --company-id=COMPANY_ID

# Payment accounts
fic api:list-payment-accounts --company-id=COMPANY_ID
fic api:create-payment-account --company-id=COMPANY_ID --input='{"data":{"name":"Conto corrente","type":"standard"}}'

# Payment methods
fic api:list-payment-methods --company-id=COMPANY_ID
fic api:create-payment-method --company-id=COMPANY_ID --input='{"data":{"name":"Bonifico","type":"standard"}}'

# VAT types
fic api:list-vat-types --company-id=COMPANY_ID
fic api:create-vat-type --company-id=COMPANY_ID --input='{"data":{"value":22,"description":"IVA 22%"}}'

Info (reference data)

fic api:list-cities --postal-code=20100
fic api:list-countries
fic api:list-currencies
fic api:list-languages
fic api:list-units-of-measure
fic api:list-templates
fic api:list-cost-centers --company-id=COMPANY_ID
fic api:list-revenue-centers --company-id=COMPANY_ID
fic api:list-product-categories --company-id=COMPANY_ID

Webhooks

fic api:list-webhooks-subscriptions --company-id=COMPANY_ID
fic api:create-webhooks-subscription --company-id=COMPANY_ID --input='{"data":{"sink":"https://example.com/webhook","event_types":["it.fattureincloud.webhooks.issued_documents.invoices.create"]}}'
fic api:delete-webhooks-subscription --company-id=COMPANY_ID --subscription-id=SUB_ID

Common workflows

See references/workflows.md for detailed multi-step workflows.

Important notes

• All monetary amounts are in EUR unless a currency is specified
• Document types for issued documents: invoice, quote, proforma, receipt, delivery_note, credit_note, order
• The --input flag accepts JSON strings for POST/PUT requests
• Attachment upload is token-based: upload first, then pass attachment_token to the document create/modify call
• Field filtering is available with --fields and --fieldset parameters
• When an API call fails, the error response includes details in JSON format
• --date-from / --date-to are only available on api:list-cashbook-entries. For all other list endpoints, use --q with date filters