Record a return filed elsewhere
curl --request POST \
--url https://api.melso.ai/v1/companies/{company_id}/tax-returns/imports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"request_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
"model": "303",
"period": "2026-Q2",
"tax_id": "12345678Z",
"filed_at": "2026-07-18T10:00:00Z",
"external_reference": "3030123456789",
"receipt_file_id": "6f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f",
"expected_version": 0,
"boxes": {
"27": "1840.00",
"45": "612.30",
"71": "1227.70"
}
}
'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/tax-returns/imports"
payload = {
"request_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
"model": "303",
"period": "2026-Q2",
"tax_id": "12345678Z",
"filed_at": "2026-07-18T10:00:00Z",
"external_reference": "3030123456789",
"receipt_file_id": "6f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f",
"expected_version": 0,
"boxes": {
"27": "1840.00",
"45": "612.30",
"71": "1227.70"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
request_id: '0f1e2d3c-4b5a-4968-8776-655443322110',
model: '303',
period: '2026-Q2',
tax_id: '12345678Z',
filed_at: '2026-07-18T10:00:00Z',
external_reference: '3030123456789',
receipt_file_id: '6f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f',
expected_version: 0,
boxes: {'27': '1840.00', '45': '612.30', '71': '1227.70'}
})
};
fetch('https://api.melso.ai/v1/companies/{company_id}/tax-returns/imports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"model": "<string>",
"period": "2026-Q3",
"status": "draft",
"is_estimate": true,
"amount": "121.00",
"version": 123,
"approved_version": 123,
"approved_at": "2023-11-07T05:31:56Z",
"deadline": "2023-12-25",
"direct_debit_deadline": "2023-12-25",
"boxes": [
{
"box": "<string>",
"key": "<string>",
"amount": "121.00"
}
],
"records": [
{
"tax_id": "<string>",
"name": "<string>",
"country": "<string>",
"key": "<string>",
"amount": "121.00",
"withheld": "121.00",
"quarters": [
"121.00"
],
"missing": [
"tax_id"
]
}
],
"review": [
"missing_tax_id"
],
"unconfirmed_expenses": 123,
"filed_at": "2023-11-07T05:31:56Z",
"filing": {
"filed_at": "2023-11-07T05:31:56Z",
"reference": "<string>",
"csv": "<string>",
"receipt": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
},
"filed_by": "melso"
},
"recalculated": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"id": "<string>",
"model": "<string>",
"period": "2026-Q3",
"status": "draft",
"is_estimate": true,
"amount": "121.00",
"version": 123,
"approved_version": 123,
"approved_at": "2023-11-07T05:31:56Z",
"deadline": "2023-12-25",
"direct_debit_deadline": "2023-12-25",
"boxes": [
{
"box": "<string>",
"key": "<string>",
"amount": "121.00"
}
],
"records": [
{
"tax_id": "<string>",
"name": "<string>",
"country": "<string>",
"key": "<string>",
"amount": "121.00",
"withheld": "121.00",
"quarters": [
"121.00"
],
"missing": [
"tax_id"
]
}
],
"review": [
"missing_tax_id"
],
"unconfirmed_expenses": 123,
"filed_at": "2023-11-07T05:31:56Z",
"filing": {
"filed_at": "2023-11-07T05:31:56Z",
"reference": "<string>",
"csv": "<string>",
"receipt": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
},
"filed_by": "melso"
},
"recalculated": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"error": "lines[0].vat_rate must be 21, 10, 4 or 0",
"code": "invalid_invoice",
"request_id": "req_01JAB3K9X2"
}{
"error": "invalid token",
"code": "unauthorized",
"request_id": "req_01JAB3K9X2"
}{
"error": "Review and approve in the authenticated web application",
"code": "person_required",
"request_id": "req_01JAB3K9X2"
}{
"error": "The tax return changed or is not ready for approval",
"code": "version_conflict",
"request_id": "req_01JAB3K9X2"
}Tax returns
Record a return filed elsewhere
Records a quarterly 303 or 130 that was already filed outside Melso, for example by the company’s previous gestoría, with the AEAT’s reference, its boxes and the receipt PDF.
POST
/
companies
/
{company_id}
/
tax-returns
/
imports
Record a return filed elsewhere
curl --request POST \
--url https://api.melso.ai/v1/companies/{company_id}/tax-returns/imports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"request_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
"model": "303",
"period": "2026-Q2",
"tax_id": "12345678Z",
"filed_at": "2026-07-18T10:00:00Z",
"external_reference": "3030123456789",
"receipt_file_id": "6f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f",
"expected_version": 0,
"boxes": {
"27": "1840.00",
"45": "612.30",
"71": "1227.70"
}
}
'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/tax-returns/imports"
payload = {
"request_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
"model": "303",
"period": "2026-Q2",
"tax_id": "12345678Z",
"filed_at": "2026-07-18T10:00:00Z",
"external_reference": "3030123456789",
"receipt_file_id": "6f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f",
"expected_version": 0,
"boxes": {
"27": "1840.00",
"45": "612.30",
"71": "1227.70"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
request_id: '0f1e2d3c-4b5a-4968-8776-655443322110',
model: '303',
period: '2026-Q2',
tax_id: '12345678Z',
filed_at: '2026-07-18T10:00:00Z',
external_reference: '3030123456789',
receipt_file_id: '6f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f',
expected_version: 0,
boxes: {'27': '1840.00', '45': '612.30', '71': '1227.70'}
})
};
fetch('https://api.melso.ai/v1/companies/{company_id}/tax-returns/imports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"model": "<string>",
"period": "2026-Q3",
"status": "draft",
"is_estimate": true,
"amount": "121.00",
"version": 123,
"approved_version": 123,
"approved_at": "2023-11-07T05:31:56Z",
"deadline": "2023-12-25",
"direct_debit_deadline": "2023-12-25",
"boxes": [
{
"box": "<string>",
"key": "<string>",
"amount": "121.00"
}
],
"records": [
{
"tax_id": "<string>",
"name": "<string>",
"country": "<string>",
"key": "<string>",
"amount": "121.00",
"withheld": "121.00",
"quarters": [
"121.00"
],
"missing": [
"tax_id"
]
}
],
"review": [
"missing_tax_id"
],
"unconfirmed_expenses": 123,
"filed_at": "2023-11-07T05:31:56Z",
"filing": {
"filed_at": "2023-11-07T05:31:56Z",
"reference": "<string>",
"csv": "<string>",
"receipt": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
},
"filed_by": "melso"
},
"recalculated": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"id": "<string>",
"model": "<string>",
"period": "2026-Q3",
"status": "draft",
"is_estimate": true,
"amount": "121.00",
"version": 123,
"approved_version": 123,
"approved_at": "2023-11-07T05:31:56Z",
"deadline": "2023-12-25",
"direct_debit_deadline": "2023-12-25",
"boxes": [
{
"box": "<string>",
"key": "<string>",
"amount": "121.00"
}
],
"records": [
{
"tax_id": "<string>",
"name": "<string>",
"country": "<string>",
"key": "<string>",
"amount": "121.00",
"withheld": "121.00",
"quarters": [
"121.00"
],
"missing": [
"tax_id"
]
}
],
"review": [
"missing_tax_id"
],
"unconfirmed_expenses": 123,
"filed_at": "2023-11-07T05:31:56Z",
"filing": {
"filed_at": "2023-11-07T05:31:56Z",
"reference": "<string>",
"csv": "<string>",
"receipt": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
},
"filed_by": "melso"
},
"recalculated": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"error": "lines[0].vat_rate must be 21, 10, 4 or 0",
"code": "invalid_invoice",
"request_id": "req_01JAB3K9X2"
}{
"error": "invalid token",
"code": "unauthorized",
"request_id": "req_01JAB3K9X2"
}{
"error": "Review and approve in the authenticated web application",
"code": "person_required",
"request_id": "req_01JAB3K9X2"
}{
"error": "The tax return changed or is not ready for approval",
"code": "version_conflict",
"request_id": "req_01JAB3K9X2"
}Live capability. Melso runs this in production today. Partner keys reach it once your partner account is enabled. See 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.
expected_version 0 for a period Melso has no return for, or
the current draft’s version to replace it. A return under review,
approved or filed by Melso cannot be replaced.Authorizations
Your partner secret key, mk_live_… for real companies or mk_test_…
for test companies. Keep it on your servers. See
Authentication.
Path Parameters
The company's ID. Every company-scoped call works in exactly this company.
Body
application/json
Your key for this import. Reusing it with different details is refused.
Available options:
303, 130 Pattern:
^[0-9]{4}-Q[1-4]$The tax ID on the receipt. Must be the company's.
After the quarter ended and no later than today.
The AEAT's submission reference on the receipt.
Maximum string length:
200The receipt, a PDF already in the company's Documents.
Required range:
x >= 0The declared boxes, by AEAT box number, as amounts with two decimals.
Show child attributes
Show child attributes
Response
The same import was already recorded with this request_id.
The return's UUID, or estimate:<model>:<period> for an estimate.
The form. Melso calculates 303, 130, 111, 115, 190, 180, 347, 349 and 390 today; a reminder form marked filed has its own model.
A year (2026), a quarter (2026-Q3), a month (2026-09) or an instalment (2026-1P).
Pattern:
^[0-9]{4}(-Q[1-4]|-(0[1-9]|1[0-2])|-[1-3]P)?$Example:
"2026-Q3"
draft: calculated, still recalculated from the records. approved: the owner authorized this exact version. filed: filed, with the administration's reference and receipt when Melso filed it.
Available options:
draft, approved, filed An estimate has an amount only. It has no boxes, no version and no approval.
The result. Negative to offset or refund (303); 0.00 for an informative return.
Pattern:
^-?[0-9]+\.[0-9]{2}$Example:
"121.00"
Raised on every recalculation that changes the draft. Approval needs the exact version.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
What to check before approving.
Available options:
missing_tax_id, cadastral_reference, eu_key_assumed, rates_assumed, volume_split Expenses in the return that are not yet confirmed as deductible.
Preview. The administration's evidence, when Melso filed the return.
Show child attributes
Show child attributes
For a filed return whose records changed afterwards, what it would be today. A difference may need a complementary or corrective return.