> ## 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 MCP: https://mcp.melso.ai/mcp (OAuth; one company per connection). Documentation-search MCP: https://docs.melso.ai/mcp; it does not act on customer accounts.
>
> Use the live tool list and respect company membership. Ask the person to approve the exact invoice or tax return version in the signed-in app. Melso's professionals prepare and file included returns after approval; an AI assistant does not file. A prepared file or an approval is not evidence of filing: only the AEAT's reference and receipt are. Keep credentials out of chat and logs.

# Approvals and filing

> Who decides what, how a person approves an exact version from your product, and what proves that Melso filed a return.

The API separates three steps and never lets one stand in for another.

| Step | Who | What it proves |
| - | - | - |
| Preparation | Melso, from the data you send | A draft is ready to read. |
| Approval | A person at the company: the owner or the legal representative | That person accepted one exact version. |
| Filing | Melso's professionals, under the company's mandate | The administration's reference, CSV and receipt. |

## What needs a person

| Object | Decision |
| - | - |
| Invoice | Issuing it: numbering and registration with VERI\*FACTU or TicketBAI |
| Tax return | Authorizing a calculated version for Melso to file |
| Case | Approving a professional's draft, when the case kind asks for it |
| Mandate | Signing the representation |

Everything else (recording expenses and income, reading documents, reconciling
proposals, payroll runs, affiliation requests) your platform does with its key.

## Approval through Melso

<Steps>
  <Step title="Ask for the link">
    Call the object's approval-link operation, such as
    [Create a tax return approval link](/api/reference/tax-returns/create-tax-return-approval-link).
    The response carries `approval_url` and the `version` it shows.
  </Step>

  <Step title="Send it to the person">
    Show it in your product, or send it by email or notification. The person
    signs in to Melso and sees the exact version: every box of the return, every
    line of the invoice.
  </Step>

  <Step title="Hear the result">
    You receive `tax_return.approved` or `invoice.issued`. If the draft changed
    before the person decided, the page shows the new version and the earlier link
    no longer approves anything.
  </Step>
</Steps>

This flow is a **live capability**: it is how Melso's app and its MCP server
get approvals today.

## Approval inside your product

<Info>
  Preview. Requires a partner agreement.
</Info>

A platform that already shows the company's finances can show the return
itself and collect the approval there, with
[Attest an approval from your interface](/api/reference/tax-returns/attest-tax-return-approval).
You send the exact `expected_version`, who approved it and the evidence: when,
from where, and the fingerprint of the document you showed. Melso records the
attestation as that person's approval and keeps the evidence with the filing.

The partner agreement says who at the company may approve, how you
authenticate them, and how long you both keep the evidence. A return whose
version changed is refused, the same as on Melso's page.

## Filing

After approval, Melso's professionals review the return and file it with the
administration under the company's mandate. They contact the company through
a [case](/api/reference/cases/list-cases) if something is missing.

Today the evidence lives on the return's case: a case reaches `done` only with
the administration's `external_reference`, and the receipt is among its
documents. The Melso API also copies it onto the return (preview), so a
return is filed when its `status` is `filed` and `filing` holds the evidence:

```json theme={null}
{
  "status": "filed",
  "filing": {
    "filed_at": "2026-10-19T10:42:11Z",
    "reference": "3030000000001",
    "csv": "ABCD1234EFGH5678",
    "filed_by": "melso",
    "receipt": {
      "id": "6f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f",
      "filename": "303_2026_3T_justificante.pdf",
      "content_type": "application/pdf"
    }
  }
}
```

<Warning>
  `approved` is not filed, and an AEAT import file is not a filing. Show the
  company a return as filed only when `filing.reference` is present. A return
  the company filed by itself shows `filed_by` `company`.
</Warning>

## Filing is not paying

Filing and paying follow different deadlines. A return paid by direct debit
(domiciliación) must be filed by `direct_debit_deadline`, a few days before the
filing deadline. Melso does not move the company's money: the administration
charges the account on file.


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