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

# HR and payroll platforms

> Your platform calculates payslips. Melso files what follows: Social Security affiliation and settlements, Contrat@, Certific@2, modelos 111 and 190.

<Info>
  The payroll and Social Security modules are in preview: we are building them
  with design partners. The employee roster and the tax returns they feed are
  live capabilities today. See [Availability](/api/availability).
</Info>

An HR platform already knows when someone is hired, what they earn, what was
withheld and when they leave. What it rarely wants to own is the last mile:
the Sistema RED, Contrat@, Certific\@2 and the AEAT, their deadlines, their
error codes and their mailboxes. That last mile is what the Melso API does.

**Your platform calculates. Melso communicates, settles, declares and answers.**

## The employee lifecycle

| Event in your product | Call | What Melso does | Legal deadline |
| - | - | - | - |
| Hire | [Add an employee](/api/reference/employees/create-employee), then [request the alta](/api/reference/social-security/create-affiliation) | Registers the employee with the TGSS through the Sistema RED and keeps the resolution | Before the first day of work |
| Contract signed | [Notify a contract](/api/reference/employment-notifications/notify-contract) | Communicates the contract to the SEPE through Contrat@ | 10 working days from signature |
| Change of hours, group or contract | [Request a variación](/api/reference/social-security/create-affiliation) | Communicates the new data to the TGSS | 3 calendar days |
| Monthly payroll | [Submit a payroll run](/api/reference/payroll-runs/create-payroll-run) | Settles contributions and feeds the 111 and 190 | See below |
| Leaving | [Request the baja](/api/reference/social-security/create-affiliation), then [send the company certificate](/api/reference/employment-notifications/send-company-certificate) | Deregisters with the TGSS and sends the certificado de empresa through Certific\@2 | 3 calendar days; 10 days |
| January | Nothing new | Files the 190 and builds each [withholding certificate](/api/reference/employees/get-withholding-certificate) | 31 January |

## The monthly cycle

<Steps>
  <Step title="You send the payroll run">
    One [payroll run](/api/reference/payroll-runs/create-payroll-run) per
    month with each payslip's days contributed, gross pay, IRPF base, rate and
    amount withheld, contribution bases and the employee's share. Melso does not
    recalculate the payslips: it validates them against each employee's
    affiliation and the year's minimum and maximum bases, and reports `issues`.
  </Step>

  <Step title="Melso settles Social Security">
    Under the liquidación directa system, Melso requests the TGSS's calculation for
    the company's CCC, compares it with your run employee by employee, and sends
    the CRA data for the concepts paid. A difference becomes
    `contribution_settlement.discrepancy` with the field and both values; a match
    is confirmed and paid by direct debit by the last day of the next month. The
    RNT and the RLC are attached to the
    [settlement](/api/reference/social-security/get-contribution-settlement).
  </Step>

  <Step title="Melso declares the withholdings">
    The run's IRPF fills the work-income boxes of the modelo 111 (perceptors,
    amounts paid and withheld, cash and in kind) for the quarter, or the month for
    a large company. The 111 is approved by the company's owner like any return
    and filed by Melso's professionals. In January, the year's runs become the
    key A records of the modelo 190.
  </Step>
</Steps>

## What the 111 looks like today

The modelo 111 is a live capability: Melso calculates it today from the
withholdings on professionals' invoices (boxes 07 to 09) and produces its AEAT
import file. Payroll runs add the work-income boxes (01 to 06), so one 111
covers both.

## Why not just export files

| Owning the last mile yourself | With the Melso API |
| - | - |
| A RED authorization, certificates and SILTRA operators | One mandate per company, signed in a hosted flow |
| Error codes from each administration to interpret | `issues` and `rejection_reason` in plain language, and webhooks |
| Deadlines tracked by people | The tax calendar and `tax_obligation.due_soon` |
| A mailbox per company to watch | [Administration notifications](/api/reference/administration-notifications/list-administration-notifications), summarized and turned into cases |
| Liability for filings | Melso's professionals file under the company's mandate, with the receipt as proof |

## Get started

Write to [hello@melso.ai](mailto:hello@melso.ai). Design partners choose the
order in which we ship the preview modules, starting with affiliation and the
monthly settlement.


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