A-Cube MCP by usefulapi

Sent and received Italian e-invoices (SDI) of the account: uuid, invoice number and date, document type (TD01...), sender and recipient, amounts, marking and notification status. Filter by date, number, document type, party name or VAT number. GET /invoices.

{
  "type": "object",
  "properties": {
    "invoice_date_from": {
      "description": "Invoice date on or after this day.",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "invoice_date_to": {
      "description": "Invoice date on or before this day.",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "created_from": {
      "description": "Created in A-Cube on or after this day.",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "created_to": {
      "description": "Created in A-Cube on or before this day.",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "invoice_number": {
      "description": "Exact invoice number.",
      "type": "string",
      "maxLength": 40
    },
    "document_type": {
      "description": "SDI document type, e.g. TD01 (invoice), TD04 (credit note), TD17-TD19 (reverse-charge self-invoices).",
      "type": "string",
      "maxLength": 10
    },
    "sender_name": {
      "description": "Sender business name (partial match).",
      "type": "string",
      "maxLength": 120
    },
    "recipient_name": {
      "description": "Recipient business name (partial match).",
      "type": "string",
      "maxLength": 120
    },
    "sender_vat_number": {
      "description": "Sender VAT number code (digits, without the country prefix).",
      "type": "string",
      "maxLength": 30
    },
    "recipient_vat_number": {
      "description": "Recipient VAT number code (digits, without the country prefix).",
      "type": "string",
      "maxLength": 30
    },
    "signed": {
      "description": "Only signed (true) or unsigned (false) invoices.",
      "type": "boolean"
    },
    "downloaded": {
      "description": "Only invoices already downloaded (true) or not yet (false).",
      "type": "boolean"
    },
    "order_by": {
      "description": "Sort field (default invoice_date).",
      "type": "string",
      "enum": [
        "invoice_date",
        "invoice_number",
        "uuid"
      ]
    },
    "order": {
      "description": "Sort direction (default desc).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "page": {
      "description": "Page number, from 1 (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "items_per_page": {
      "description": "Items per page, 1 to 30 (default 30). A full page means there may be more: ask for the next page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One invoice by uuid: metadata plus the FatturaPA JSON payload (parties, lines, VAT, payment), or the XML file sent to the SDI. GET /invoices/{uuid}.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The invoice uuid (from acube_list_invoices)."
    },
    "format": {
      "description": "json (default) or xml.",
      "type": "string",
      "enum": [
        "json",
        "xml"
      ]
    }
  },
  "required": [
    "uuid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The SDI notifications of one invoice (delivery receipt RC, rejection NS, outcome NE, failed delivery MC, deadline expiry DT...), with their type, date and status: how you tell whether an invoice was delivered or rejected. GET /invoices/{uuid}/notifications.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The invoice uuid."
    }
  },
  "required": [
    "uuid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One SDI notification by uuid, with its payload. GET /notifications/{uuid}.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The notification uuid (from acube_list_invoice_notifications)."
    }
  },
  "required": [
    "uuid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Counters of invoices and notifications for a year (annual; monthly or daily detail only if A-Cube activated it), for the whole account or one fiscal id. GET /invoices/stats/{year}.

{
  "type": "object",
  "properties": {
    "year": {
      "type": "integer",
      "minimum": 2000,
      "maximum": 2100,
      "description": "The year, e.g. 2026."
    },
    "fiscal_id": {
      "description": "Only this customer's fiscal id (a business registry configuration).",
      "type": "string",
      "maxLength": 30
    }
  },
  "required": [
    "year"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Draft invoices that were created but not yet sent to the SDI. Same filters as acube_list_invoices. GET /invoices/draft.

{
  "type": "object",
  "properties": {
    "invoice_date_from": {
      "description": "Invoice date on or after this day.",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "invoice_date_to": {
      "description": "Invoice date on or before this day.",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "invoice_number": {
      "description": "Exact invoice number.",
      "type": "string",
      "maxLength": 40
    },
    "recipient_name": {
      "description": "Recipient business name (partial match).",
      "type": "string",
      "maxLength": 120
    },
    "page": {
      "description": "Page number, from 1 (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "items_per_page": {
      "description": "Items per page, 1 to 30 (default 30). A full page means there may be more: ask for the next page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One draft invoice by uuid, with its FatturaPA JSON content. GET /invoices/draft/{uuid}.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The draft invoice uuid."
    }
  },
  "required": [
    "uuid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Checks an invoice against the FatturaPA rules without creating or sending anything; returns the validation result or A-Cube's errors. POST /invoices/validate.

{
  "type": "object",
  "properties": {
    "fattura_elettronica_header": {
      "description": "FatturaPA header as A-Cube JSON (snake_case keys): dati_trasmissione (codice_destinatario, pec_destinatario), cedente_prestatore (seller), cessionario_committente (buyer). Give the full header (seller and buyer) for a draft you intend to send: A-Cube only fills in transmission data automatically, and acube_validate_invoice shows what is missing.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "fattura_elettronica_body": {
      "minItems": 1,
      "maxItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "description": "Exactly one invoice body (an array with one object), snake_case keys: dati_generali (dati_generali_documento...), dati_beni_servizi (dettaglio_linee, dati_riepilogo), optional dati_pagamento. Field names as in the A-Cube Italy API reference."
    }
  },
  "required": [
    "fattura_elettronica_body"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: saves a new invoice as a DRAFT in A-Cube. Nothing is sent to the SDI until acube_send_draft_invoice. Not idempotent: calling it twice creates two drafts. Validate first with acube_validate_invoice. POST /invoices/draft.

{
  "type": "object",
  "properties": {
    "fattura_elettronica_header": {
      "description": "FatturaPA header as A-Cube JSON (snake_case keys): dati_trasmissione (codice_destinatario, pec_destinatario), cedente_prestatore (seller), cessionario_committente (buyer). Give the full header (seller and buyer) for a draft you intend to send: A-Cube only fills in transmission data automatically, and acube_validate_invoice shows what is missing.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "fattura_elettronica_body": {
      "minItems": 1,
      "maxItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "description": "Exactly one invoice body (an array with one object), snake_case keys: dati_generali (dati_generali_documento...), dati_beni_servizi (dettaglio_linee, dati_riepilogo), optional dati_pagamento. Field names as in the A-Cube Italy API reference."
    }
  },
  "required": [
    "fattura_elettronica_body"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: accepts a draft and transmits it to the Sistema di Interscambio. This is a legal act: a sent e-invoice cannot be recalled (only corrected with a credit note) and may be billed by A-Cube. Without confirm: true it only returns the draft for review. Show the draft to the user and get their explicit OK first. POST /invoices/draft/{uuid}/send.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The draft invoice uuid."
    },
    "confirm": {
      "description": "Must be true to actually send. Otherwise the draft is returned as a preview.",
      "type": "boolean"
    }
  },
  "required": [
    "uuid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: permanently deletes a draft invoice (a draft only: a sent invoice answers 409). Without confirm: true it only returns the draft. DELETE /invoices/draft/{uuid}.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The draft invoice uuid."
    },
    "confirm": {
      "description": "Must be true to actually delete. Otherwise the draft is returned as a preview.",
      "type": "boolean"
    }
  },
  "required": [
    "uuid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Electronic commercial receipts (scontrini) with number, date, status, type (sale, void, return) and totals. GET /receipts.

{
  "type": "object",
  "properties": {
    "fiscal_id": {
      "description": "Only this business's receipts (its fiscal id).",
      "type": "string",
      "maxLength": 30
    },
    "document_number": {
      "description": "Exact receipt document number.",
      "type": "string",
      "maxLength": 40
    },
    "status": {
      "description": "Receipt status, as shown in the list.",
      "type": "string",
      "maxLength": 30
    },
    "type": {
      "description": "Receipt type, e.g. sale, void, return.",
      "type": "string",
      "maxLength": 30
    },
    "document_date_from": {
      "description": "Receipt date on or after this day.",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "document_date_to": {
      "description": "Receipt date on or before this day.",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "page": {
      "description": "Page number, from 1 (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "items_per_page": {
      "description": "Items per page, 1 to 100 (default 30). A full page means there may be more: ask for the next page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One electronic receipt by uuid: type, status, number, date, total and links to voiding or returned receipts (no line items: use acube_get_receipt_details). GET /receipts/{uuid}.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The receipt uuid (from acube_list_receipts)."
    }
  },
  "required": [
    "uuid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The line items and VAT, discount and taxable totals of one electronic receipt. GET /receipts/{uuid}/details.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The receipt uuid (from acube_list_receipts)."
    }
  },
  "required": [
    "uuid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The businesses (fiscal ids) set up on the account, with which services are on: customer invoices, supplier invoices, receipts, signature, legal storage. GET /business-registry-configurations.

{
  "type": "object",
  "properties": {
    "fiscal_id": {
      "description": "Exact fiscal id.",
      "type": "string",
      "maxLength": 30
    },
    "name": {
      "description": "Business name (partial match).",
      "type": "string",
      "maxLength": 120
    },
    "email": {
      "description": "Contact email.",
      "type": "string",
      "maxLength": 254
    },
    "supplier_invoice_enabled": {
      "description": "Only businesses that receive supplier invoices (true) or not (false).",
      "type": "boolean"
    },
    "receipts_enabled": {
      "description": "Only businesses with electronic receipts on (true) or off (false).",
      "type": "boolean"
    },
    "page": {
      "description": "Page number, from 1 (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "items_per_page": {
      "description": "Items per page, 1 to 100 (default 30). A full page means there may be more: ask for the next page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One business by fiscal id: name, email, enabled services and its webhook configurations. GET /business-registry-configurations/{fiscalId}.

{
  "type": "object",
  "properties": {
    "fiscal_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The business's fiscal id (codice fiscale or partita IVA)."
    }
  },
  "required": [
    "fiscal_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The webhooks (events and target URLs) configured on the account. Authentication keys and tokens are never returned. GET /api-configurations.

{
  "type": "object",
  "properties": {
    "fiscal_id": {
      "description": "Only webhooks of this business (fiscal id).",
      "type": "string",
      "maxLength": 30
    },
    "page": {
      "description": "Page number, from 1 (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "items_per_page": {
      "description": "Items per page, 1 to 30 (default 30). A full page means there may be more: ask for the next page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The invoice numbering sequences (name, year, last number). GET /numbering-sequences.

{
  "type": "object",
  "properties": {
    "sequence_name": {
      "description": "Only this sequence name.",
      "type": "string",
      "maxLength": 60
    },
    "year": {
      "description": "Only this year.",
      "type": "integer",
      "minimum": 2000,
      "maximum": 2100
    },
    "page": {
      "description": "Page number, from 1 (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "items_per_page": {
      "description": "Items per page, 1 to 100 (default 30). A full page means there may be more: ask for the next page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The sequence now in use for a sequence name. Its number is the LAST number used: the next invoice gets that number plus one. GET /numbering-sequences/current/{name}.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The sequence name."
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Background jobs (invoice, report and zip downloads, F24 and daily receipt report downloads) with status ready, started, completed or error. GET /jobs.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Only jobs in this status.",
      "type": "string",
      "enum": [
        "ready",
        "started",
        "completed",
        "error"
      ]
    },
    "job_type": {
      "description": "Only this job type.",
      "type": "string",
      "enum": [
        "invoice-download",
        "invoice-report-download",
        "invoice-zip-download",
        "f24-download",
        "daily-receipt-report-download"
      ]
    },
    "fiscal_id": {
      "description": "Only this business's jobs.",
      "type": "string",
      "maxLength": 30
    },
    "page": {
      "description": "Page number, from 1 (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "items_per_page": {
      "description": "Items per page, 1 to 30 (default 30). A full page means there may be more: ask for the next page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One background job by uuid with its status and result. GET /jobs/{uuid}.

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The job uuid (from acube_list_jobs)."
    }
  },
  "required": [
    "uuid"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Checks whether a codice fiscale or partita IVA is valid. GET /verify/fiscal-id/{id}.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The fiscal id or VAT number to check, e.g. 12345678901."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Basic registry data of an Italian company by VAT number (name, address, status), optionally with the split-payment check. GET /verify/company/{id}.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The company's VAT number or fiscal id."
    },
    "check_split_payment": {
      "description": "Also tell whether the company is subject to split payment.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The account's 7-character SDI recipient code (codice destinatario), the address customers put on invoices they send to you. GET /users/me/recipient-code.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}