> ## 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.
# Save the corporate tax inputs
> Saves what the year's corporate tax needs beyond the books, at exactly expected_version, and returns the recalculated tax.
**Live capability.** Melso runs this in production today. Partner keys reach it once your partner account is enabled. See [Availability](/api/availability).
**A person decides.** The company's owner makes this call, signed in to Melso. Partner keys cannot make it: send the person the approval link instead. See [Approvals and filing](/api/approvals).
Only the fields
you send change; an empty amount takes the value from the books. It does
not approve or file the 200.
## OpenAPI
````yaml api/openapi.yaml PUT /companies/{company_id}/corporate-tax/{year}
openapi: 3.1.0
info:
title: Melso API
version: 1.0.0-preview
summary: Spanish tax and labour compliance for the companies on your platform.
description: |
The Melso API lets an HR, payroll, banking or ERP platform run the
Spanish tax and labour obligations of the companies it serves: invoices,
books, tax returns, Social Security and employment notifications.
Melso calculates and prepares. A person at the company approves the exact
version. Melso's professionals file under the company's representation, and
the filing is proven only by the administration's reference and receipt.
Every operation states its availability in `x-melso-status`:
- `live`: Melso runs this capability in production today. Partner keys
reach it once a partner account is enabled.
- `preview`: a contract proposed to design partners. Not callable yet.
`x-melso-actor: person` marks a decision a signed-in person makes in
Melso; a partner sends them the approval link instead.
contact:
name: Melso partnerships
email: hello@melso.ai
url: https://docs.melso.ai/api/overview
servers:
- url: https://api.melso.ai/v1
description: API. Keys and access are issued per partner.
security:
- partnerKey: []
tags:
- name: Companies
description: The companies you operate for, their fiscal profile and hosted onboarding.
- name: Mandates
description: >-
The company's representation of Melso before the AEAT, the TGSS and the
SEPE.
- name: Webhook endpoints
description: Where Melso sends signed events about your companies.
- name: Invoicing setup
description: Registration of the company as a VERI*FACTU or TicketBAI invoice issuer.
- name: Customers
description: The company's invoice customers.
- name: Invoices
description: >-
Drafts, approval, legal registration, delivery and payment of the
company's invoices.
- name: Expenses
description: >-
Purchase invoices and receipts, with their AEAT category and
deductibility.
- name: Income
description: Income invoiced outside Melso.
- name: Documents
description: >-
Files the company gives Melso, and Melso's structured reading of an
invoice or receipt.
- name: Banking
description: >-
Bank accounts, movements, statements and reconciliation with invoices and
expenses.
- name: Accounting
description: Journal, imported books and the company's financial statements.
- name: Tax calendar
description: The forms the company must file, with their periods and deadlines.
- name: Tax returns
description: The returns Melso calculates, their approval and their filing.
- name: Corporate tax
description: The year's corporate tax (modelo 200) and its instalments (modelo 202).
- name: Tax estimates
description: What the company should set aside for taxes, as of today.
- name: Cases
description: Gestiones, the procedures Melso's professionals carry out for the company.
- name: Administration notifications
description: Electronic notifications from the administration to the company.
- name: Certificates
description: >-
Official certificates such as being up to date with the AEAT or the Social
Security.
- name: Employees
description: The people the company employs.
- name: Payroll runs
description: >-
The payroll results your platform calculated, for Melso to settle and
declare.
- name: Social Security
description: >-
Affiliation (altas, bajas and variaciones) and monthly contribution
settlements.
- name: Employment notifications
description: >-
Contrat@ contract notifications and Certific@2 company certificates to the
SEPE.
paths:
/companies/{company_id}/corporate-tax/{year}:
parameters:
- $ref: '#/components/parameters/CompanyId'
- name: year
in: path
required: true
description: The fiscal year, such as `2025`.
schema:
type: integer
minimum: 2000
maximum: 2100
put:
tags:
- Corporate tax
summary: Save the corporate tax inputs
description: |
Saves what the year's corporate tax needs beyond the books, at exactly
`expected_version`, and returns the recalculated tax. Only the fields
you send change; an empty amount takes the value from the books. It does
not approve or file the 200.
operationId: saveCorporateTaxInputs
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CorporateTaxInput'
example:
expected_version: 2
adjustments:
- concept: Multa de tráfico (art. 15.c LIS)
amount: '300.00'
temporary: false
capitalization_reserve: true
losses_offset: '4500.00'
responses:
'200':
description: The recalculated tax.
content:
application/json:
schema:
$ref: '#/components/schemas/CorporateTax'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
$ref: '#/components/responses/Conflict'
components:
parameters:
CompanyId:
name: company_id
in: path
required: true
description: >-
The company's ID. Every company-scoped call works in exactly this
company.
schema:
type: string
format: uuid
schemas:
CorporateTaxInput:
type: object
required:
- expected_version
additionalProperties: false
properties:
expected_version:
type: integer
minimum: 0
description: The `version` you read; `0` when nothing was saved yet.
adjustments:
type: array
maxItems: 50
description: >-
Every adjustment to the accounting result (ajustes extracontables).
Replaces the saved list.
items:
type: object
required:
- concept
- amount
properties:
concept:
type: string
description: >-
What it is and the article it rests on, such as "Multa (art.
15.c LIS)".
amount:
$ref: '#/components/schemas/Amount'
description: Positive raises the taxable base, negative lowers it.
temporary:
type: boolean
description: It reverses in later years
with a deferred tax.: null
capitalization_reserve:
type: boolean
description: Apply the capitalization reserve (art. 25 LIS).
deductions:
$ref: '#/components/schemas/Amount'
instalments:
type: string
description: The year's 202 instalments paid. Empty to take them from the books.
losses_offset:
type: string
description: Negative bases of earlier years offset.
new_entity:
type: boolean
description: A company in its first or second year with a positive base
at 15 %.: null
period_base:
type: boolean
description: >-
The company opted for the 202 on the year's result so far (art. 40.3
LIS).
prior_turnover:
type: string
description: >-
The year before's turnover, which sets the rate. Empty to take it
from the books.
withholdings:
type: string
description: Withholdings suffered. Empty to take them from the books.
workforce_growth:
type: integer
description: Growth of the average workforce over the year before
in percent.: null
CorporateTax:
type: object
properties:
year:
type: integer
version:
type: integer
result_before_tax:
$ref: '#/components/schemas/Amount'
adjustments_total:
$ref: '#/components/schemas/Amount'
capitalization_reserve:
$ref: '#/components/schemas/Amount'
losses_offset:
$ref: '#/components/schemas/Amount'
taxable_base:
$ref: '#/components/schemas/Amount'
rate:
$ref: '#/components/schemas/Decimal'
gross_tax:
$ref: '#/components/schemas/Amount'
net_tax:
$ref: '#/components/schemas/Amount'
withholdings:
$ref: '#/components/schemas/Amount'
instalments_paid:
$ref: '#/components/schemas/Amount'
to_pay:
$ref: '#/components/schemas/Amount'
instalments:
type: array
description: >-
The modelo 202 instalments of the next year that build on this
result.
items:
type: object
properties:
period:
$ref: '#/components/schemas/Period'
amount:
$ref: '#/components/schemas/Amount'
deadline:
type: string
format: date
review:
type: array
items:
type: string
additionalProperties: true
Amount:
type: string
pattern: ^-?[0-9]+\.[0-9]{2}$
description: >-
An amount in euros as a decimal string with two decimals, such as
`"121.00"`.
examples:
- '121.00'
Decimal:
type: string
pattern: ^-?[0-9]{1,10}(\.[0-9]{1,6})?$
description: A decimal number as a string, such as `"21"` or `"0.5"`.
Period:
type: string
pattern: ^[0-9]{4}(-Q[1-4]|-(0[1-9]|1[0-2])|-[1-3]P)?$
description: >-
A year (`2026`), a quarter (`2026-Q3`), a month (`2026-09`) or an
instalment (`2026-1P`).
examples:
- 2026-Q3
Error:
type: object
required:
- error
properties:
error:
type: string
description: What went wrong, for a person to read.
code:
type: string
description: >-
A stable code to branch on, such as `invoicing_not_ready` or
`version_conflict`.
request_id:
type: string
description: Quote it when you contact Melso.
responses:
BadRequest:
description: >-
The request is malformed or a field is invalid. Unknown fields are
refused.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: lines[0].vat_rate must be 21, 10, 4 or 0
code: invalid_invoice
request_id: req_01JAB3K9X2
Unauthorized:
description: The key is missing, revoked or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: invalid token
code: unauthorized
request_id: req_01JAB3K9X2
Conflict:
description: >-
The object changed or is not in a state that allows this. Read it again
and decide.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: The tax return changed or is not ready for approval
code: version_conflict
request_id: req_01JAB3K9X2
securitySchemes:
partnerKey:
type: http
scheme: bearer
description: |
Your partner secret key, `mk_live_…` for real companies or `mk_test_…`
for test companies. Keep it on your servers. See
[Authentication](/api/authentication).
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.