> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# invoices

> Input, output and examples for the invoices MCP tool.

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](/mcp/permissions).

## Input

### Autónomo / Company schema

```json theme={null}
{
  "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.

<AccordionGroup>
  <Accordion title="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.

    ```json theme={null}
    {
      "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"
    }
    ```
  </Accordion>

  <Accordion title="get">
    Read one workspace invoice including its current reviewed-content version and totals.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Workspace-scoped invoice UUID.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list">
    List this workspace's local invoice copies, totals and provider statuses. The invoice record holds the legal registration and PDF.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {},
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    {
      "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"
    }
    ```
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Workspace-scoped invoice UUID.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## 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](/mcp/results).

## 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.

```bash theme={null}
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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.