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

# Quickstart

> From a new company to its first calculated VAT return and the page where its owner approves it, with a test key.

<Info>
  This walk-through uses a test key, issued when your partner account is
  enabled. Test companies behave like real ones, but nothing reaches an
  administration. See [Availability](/api/availability).
</Info>

```bash theme={null}
export MELSO_PARTNER_KEY="mk_test_your_key"
export MELSO_API="https://api.melso.ai/v1"
```

<Steps>
  <Step title="Create the company">
    ```bash theme={null}
    curl --fail-with-body "$MELSO_API/companies" \
      -H "Authorization: Bearer $MELSO_PARTNER_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: 5b0f1c62-3d7e-4a8f-9b1c-2d3e4f5a6b7c" \
      --data-binary @- <<'JSON'
    {
      "kind": "freelancer",
      "name": "Lucía Martín",
      "external_id": "cus_48213",
      "owner": {"name": "Lucía Martín Pérez", "email": "lucia@example.com", "locale": "es"},
      "fiscal_profile": {
        "tax_id": "12345678Z",
        "legal_name": "Lucía Martín Pérez",
        "address": "Calle Mayor 1",
        "postal_code": "50001",
        "activity_type": "profesional",
        "registration_status": "alta",
        "registered_on": "2024-03",
        "irpf_method": "directa_simplificada",
        "vat_regime": "general",
        "client_types": ["es_business"]
      }
    }
    JSON
    ```

    Keep the `id` it returns as `COMPANY_ID`. An empty `missing` means the profile
    is complete.
  </Step>

  <Step title="Send the company's records">
    Record a sales invoice the company issued in your product, and a purchase:

    ```bash theme={null}
    curl --fail-with-body "$MELSO_API/companies/$COMPANY_ID/income" \
      -H "Authorization: Bearer $MELSO_PARTNER_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @- <<'JSON'
    {
      "customer_name": "Talleres Ebro S.L.",
      "customer_tax_id": "B12345674",
      "document_number": "A-2026-0187",
      "issue_date": "2026-08-05",
      "vat_lines": [{"rate": "21", "base": "800.00", "vat": "168.00"}],
      "irpf_rate": "15",
      "irpf_amount": "120.00"
    }
    JSON
    ```

    ```bash theme={null}
    curl --fail-with-body "$MELSO_API/companies/$COMPANY_ID/documents/extract" \
      -H "Authorization: Bearer $MELSO_PARTNER_KEY" \
      -F "file=@factura-coworking.pdf" \
      -F "direction=expense"
    ```

    The second call reads the invoice and records it as an expense, with its AEAT
    category and `review` codes to check.
  </Step>

  <Step title="Read the tax calendar">
    ```bash theme={null}
    curl --fail-with-body "$MELSO_API/companies/$COMPANY_ID/tax-calendar" \
      -H "Authorization: Bearer $MELSO_PARTNER_KEY"
    ```

    Each entry has its `deadline`, its `direct_debit_deadline`, and `melso`
    `calculates` when Melso calculates it. Once the quarter ends, `filing_id`
    points to the calculated return.
  </Step>

  <Step title="Read the return">
    ```bash theme={null}
    curl --fail-with-body "$MELSO_API/companies/$COMPANY_ID/tax-returns?model=303" \
      -H "Authorization: Bearer $MELSO_PARTNER_KEY"
    ```

    A `draft` 303 lists its boxes, its `amount` and what to `review`. Its `version`
    rises whenever new records change it. You also receive `tax_return.calculated`.
  </Step>

  <Step title="Get the owner's approval">
    ```bash theme={null}
    curl --fail-with-body -X POST "$MELSO_API/companies/$COMPANY_ID/tax-returns/$TAX_RETURN_ID/approval-link" \
      -H "Authorization: Bearer $MELSO_PARTNER_KEY"
    ```

    Send `approval_url` to the owner. When they authorize the exact version, you
    receive `tax_return.approved`; when Melso's professionals file it, you receive
    `tax_return.filed` with the AEAT's reference and receipt.
  </Step>
</Steps>

## Next

<CardGroup cols={2}>
  <Card title="Approvals and filing" icon="signature" href="/api/approvals">Collect approvals in your own product.</Card>
  <Card title="Webhooks" icon="bell" href="/api/webhooks">React to every state change.</Card>
</CardGroup>


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