Quickstart

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.

export MELSO_PARTNER_KEY="mk_test_your_key"
export MELSO_API="https://api.melso.ai/v1"

Create the company

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.

Send the company's records

Record a sales invoice the company issued in your product, and a purchase:

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

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.

Read the tax calendar

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.

Read the return

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.

Get the owner's approval

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.

Approvals and filing

Collect approvals in your own product.

Webhooks

React to every state change.

Get started

Solutions

Companies and access

Invoicing

Bookkeeping

Taxes

Payroll and Social Security

Next

Approvals and filing

Webhooks

​Next

Approvals and filing

Webhooks

Next