invoices

Read invoices and prepare unnumbered drafts or corrections. request_approval returns the saved preview and a web approval link; only the person can approve issuance there. No action issues or sends an invoice. Each action accepts only its own fields (* required): get(id*); prepare(customer_id*, issue_date*, lines*, due_date, id, irpf_rate, notes, type); request_approval(id*); correct(invoice_id*, customer_id*, issue_date*, lines*, due_date, irpf_rate, notes); list. Availability: Autónomo / Empresa. Catalog: Core (tools/list). The live catalog is authoritative: company type, membership, plan, connected apps and execution context can narrow this contract. Understand access.

Input

Autónomo / Company schema

{
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": [
        "get",
        "prepare",
        "request_approval",
        "correct",
        "list"
      ],
      "type": "string"
    },
    "customer_id": {
      "description": "Customer UUID from customers action upsert.",
      "type": "string"
    },
    "due_date": {
      "description": "Optional calendar due date YYYY-MM-DD.",
      "type": "string"
    },
    "id": {
      "description": "Workspace-scoped invoice UUID.",
      "type": "string"
    },
    "invoice_id": {
      "description": "Issued original invoice UUID; correction remains a draft pending human approval.",
      "type": "string"
    },
    "irpf_rate": {
      "description": "Optional IRPF percentage for autonomous professionals, 0, 7 or 15. Company invoices omit it or use 0.",
      "type": "string"
    },
    "issue_date": {
      "description": "Calendar date YYYY-MM-DD.",
      "type": "string"
    },
    "lines": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "description": {
            "description": "Service or product description.",
            "type": "string"
          },
          "product_kind": {
            "description": "Optional fiscal classification for TicketBAI; omitted new lines use services.",
            "enum": [
              "goods",
              "services"
            ],
            "type": "string"
          },
          "quantity": {
            "description": "Decimal quantity.",
            "type": "string"
          },
          "unit_price": {
            "description": "Unit price in EUR as a decimal string.",
            "type": "string"
          },
          "vat_rate": {
            "description": "IVA percentage 0/4/10/21, or IGIC 7 for the supported Canary Islands regime.",
            "type": "string"
          }
        },
        "required": [
          "description",
          "quantity",
          "unit_price",
          "vat_rate"
        ],
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    },
    "notes": {
      "description": "Invoice notes.",
      "type": "string"
    },
    "type": {
      "enum": [
        "standard",
        "proforma",
        "corrective"
      ],
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "type": "object"
}

Actions

The family schema combines fields for discovery. Each action accepts only its own fields below; add action when calling the family.

correct

Prepare a corrective draft with signed financial differences referencing an issued original. Negative unit prices credit or cancel the original; positive prices increase the amount. For a full credit of 1200 EUR, use unit_price=-1200 with positive quantity. The original stays immutable. Request human approval again.

{
  "additionalProperties": false,
  "properties": {
    "customer_id": {
      "description": "Customer UUID from customers action upsert.",
      "type": "string"
    },
    "due_date": {
      "description": "Optional calendar due date YYYY-MM-DD.",
      "type": "string"
    },
    "invoice_id": {
      "description": "Issued original invoice UUID; correction remains a draft pending human approval.",
      "type": "string"
    },
    "irpf_rate": {
      "description": "Optional IRPF percentage for autonomous professionals, 0, 7 or 15. Company invoices omit it or use 0.",
      "type": "string"
    },
    "issue_date": {
      "description": "Calendar date YYYY-MM-DD.",
      "type": "string"
    },
    "lines": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "description": {
            "description": "Service or product description.",
            "type": "string"
          },
          "product_kind": {
            "description": "Optional fiscal classification for TicketBAI; omitted new lines use services.",
            "enum": [
              "goods",
              "services"
            ],
            "type": "string"
          },
          "quantity": {
            "description": "Decimal quantity.",
            "type": "string"
          },
          "unit_price": {
            "description": "Unit price in EUR as a decimal string.",
            "type": "string"
          },
          "vat_rate": {
            "description": "IVA percentage 0/4/10/21, or IGIC 7 for the supported Canary Islands regime.",
            "type": "string"
          }
        },
        "required": [
          "description",
          "quantity",
          "unit_price",
          "vat_rate"
        ],
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    },
    "notes": {
      "description": "Invoice notes.",
      "type": "string"
    }
  },
  "required": [
    "invoice_id",
    "customer_id",
    "issue_date",
    "lines"
  ],
  "type": "object"
}

get

Read one workspace invoice including its current reviewed-content version and totals.

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Workspace-scoped invoice UUID.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

list

List this workspace’s local invoice copies, totals and provider statuses. The invoice record holds the legal registration and PDF.

{
  "additionalProperties": false,
  "properties": {},
  "type": "object"
}

prepare

Validate an invoice with GOBL and save an unnumbered draft (or replace an unapproved draft via id). Never issues, sends or records VeriFactu. Use invoices action request_approval afterwards.

{
  "additionalProperties": false,
  "properties": {
    "customer_id": {
      "description": "Customer UUID from customers action upsert.",
      "type": "string"
    },
    "due_date": {
      "description": "Optional calendar due date YYYY-MM-DD.",
      "type": "string"
    },
    "id": {
      "description": "Existing unapproved draft UUID to replace; omit to create a new draft.",
      "type": "string"
    },
    "irpf_rate": {
      "description": "Optional IRPF percentage for autonomous professionals, 0, 7 or 15. Company invoices omit it or use 0.",
      "type": "string"
    },
    "issue_date": {
      "description": "Calendar date YYYY-MM-DD.",
      "type": "string"
    },
    "lines": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "description": {
            "description": "Service or product description.",
            "type": "string"
          },
          "product_kind": {
            "description": "Optional fiscal classification for TicketBAI; omitted new lines use services.",
            "enum": [
              "goods",
              "services"
            ],
            "type": "string"
          },
          "quantity": {
            "description": "Decimal quantity.",
            "type": "string"
          },
          "unit_price": {
            "description": "Unit price in EUR as a decimal string.",
            "type": "string"
          },
          "vat_rate": {
            "description": "IVA percentage 0/4/10/21, or IGIC 7 for the supported Canary Islands regime.",
            "type": "string"
          }
        },
        "required": [
          "description",
          "quantity",
          "unit_price",
          "vat_rate"
        ],
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    },
    "notes": {
      "description": "Invoice notes.",
      "type": "string"
    },
    "type": {
      "enum": [
        "standard",
        "proforma",
        "corrective"
      ],
      "type": "string"
    }
  },
  "required": [
    "customer_id",
    "issue_date",
    "lines"
  ],
  "type": "object"
}

request_approval

Read the draft preview and return Emitir/Cambiar actions for the authenticated user’s web page. Present the preview and approval URL. The user must approve there; chat text and agent tools cannot issue an invoice.

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Workspace-scoped invoice UUID.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

Output

The selected invoice records or saved draft preview. request_approval returns an approval link for the person. These actions do not issue or send an invoice. The result uses MCP content blocks; JSON payloads are encoded in text and may also appear in structuredContent. Check isError before reading a success payload. The server does not currently declare an outputSchema, so treat additional fields as extensible. Result handling.

Example

Use an OAuth access token issued for this MCP resource (a Run token for Run-only tools). Replace example identifiers with values from your own account. Write actions change data.

curl --fail-with-body https://melso.ai/api/mcp \
  -H "Authorization: Bearer $MELSO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data-binary @- <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "invoices",
    "arguments": {
      "action": "list"
    }
  }
}
JSON

Connect

Contracts and access

Core tools

Agents and managed-Run tools

Advanced tools

Input

Autónomo / Company schema

Actions

Output

Example

​Input

​Autónomo / Company schema

​Actions

​Output

​Example

Input

Autónomo / Company schema

Actions

Output

Example