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

# Conventions

> Errors, money and dates, versions and concurrency, pagination, idempotency and rate limits across the Melso API.

## Errors

Every error is JSON with a message for a person and, where you can act on it,
a stable `code` to branch on:

```json theme={null}
{
  "error": "The tax return changed or is not ready for approval",
  "code": "version_conflict",
  "request_id": "req_01JAB3K9X2"
}
```

| Status | Meaning |
| - | - |
| `400` | Malformed request or invalid field. Unknown fields are refused, so a typo fails loudly. |
| `401` | Missing or invalid key. |
| `402` | The company's plan does not include the service, or its allowance is used up. |
| `403` | The key cannot do this, or the step needs a person. |
| `404` | Not found in this company. |
| `409` | The object changed or its state does not allow this. Read it again. |
| `422` | A file or a document cannot be read or used as is. `code` says why. |
| `429` | Too many requests. Wait for `Retry-After` seconds. |
| `502` | The tax authority's network has not answered yet. Retry the same request. |
| `503` | Melso is briefly unavailable. Retry with backoff. |

Codes you will meet often:

| Code | What to do |
| - | - |
| `invoicing_not_ready` | The company cannot invoice yet: finish its fiscal profile or its invoicing authorization. |
| `invalid_invoice` | Fix the field named in `error`. |
| `invoicing_provider_pending` | Retry the same issue call. Never draft a replacement invoice. |
| `tax_service_required` | The company's plan does not include the tax service. |
| `version_conflict` | Read the object and show the person the current version. |
| `person_required` | Send the person the approval link instead. |

## Money

Amounts are strings in euros with two decimals, such as `"1210.00"`, never
floating-point numbers. Rates are strings too, such as `"21"` or `"15"`. A
negative amount on a return means a result to offset or refund.

## Dates and periods

Dates are `YYYY-MM-DD`; timestamps are RFC 3339. A tax period is one of:

| Period | Example |
| - | - |
| Year | `2026` |
| Quarter | `2026-Q3` |
| Month | `2026-09` |
| Instalment | `2026-1P` |

Deadlines already move for national and regional public holidays.

## Versions

Anything a person approves carries a `version`, and approving it needs that
exact `expected_version`. Records you edit (expenses, income, corporate tax
inputs) use the same check: send the `version` you read as `expected_version`,
and a `409` tells you someone changed it first.

This is how the API keeps the rule that a person approves exactly what they
saw. A draft that changed after the person read it cannot be approved by
mistake.

## Pagination

Lists return a page and a cursor:

```json theme={null}
{
  "data": [],
  "next_cursor": "c2VjcmV0LWN1cnNvcg"
}
```

Pass `next_cursor` as `cursor` for the next page. `next_cursor` is `null` on
the last page. `limit` sets the page size, 50 by default and 200 at most.

## Idempotency

Send an `Idempotency-Key` header, such as a UUID, on every `POST` that creates
something. Retrying with the same key returns the first result instead of
creating a second object; reusing a key with a different body is refused.

Some operations are idempotent by nature and say so: issuing an invoice again
with the same `expected_version` reuses its number, and marking an invoice paid
twice keeps the first `paid_at`.

## Rate limits

A key may make 600 requests a minute. Over the limit, the API answers `429`
with `Retry-After`. Push bank movements and payslips in batches rather than one
call each.

## Versioning

The version is in the path, `/v1`. Within `v1`, Melso adds fields, operations,
event types and enum values without notice, so ignore what you do not know.
Anything that would break a client comes as a new version, and every partner
hears about it before it ships.


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