curl --request POST \
--url https://api.melso.ai/v1/companies/{company_id}/mandates \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"administration": "aeat",
"procedures": [
"tax_returns",
"notifications",
"certificates"
],
"signer": {
"name": "Lucía Martín Pérez",
"tax_id": "12345678Z",
"email": "lucia@example.com"
},
"return_url": "https://partner.example.com/melso/mandate-done"
}
'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/mandates"
payload = {
"administration": "aeat",
"procedures": ["tax_returns", "notifications", "certificates"],
"signer": {
"name": "Lucía Martín Pérez",
"tax_id": "12345678Z",
"email": "lucia@example.com"
},
"return_url": "https://partner.example.com/melso/mandate-done"
}
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({
administration: 'aeat',
procedures: ['tax_returns', 'notifications', 'certificates'],
signer: {name: 'Lucía Martín Pérez', tax_id: '12345678Z', email: 'lucia@example.com'},
return_url: 'https://partner.example.com/melso/mandate-done'
})
};
fetch('https://api.melso.ai/v1/companies/{company_id}/mandates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"administration": "aeat",
"procedures": [
"tax_returns"
],
"status": "pending_signature",
"created_at": "2023-11-07T05:31:56Z",
"signing_url": "<string>",
"rejection_reason": "<string>",
"signed_at": "2023-11-07T05:31:56Z",
"activated_at": "2023-11-07T05:31:56Z",
"revoked_at": "2023-11-07T05:31:56Z",
"evidence": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
}
}{
"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": "invoice not found",
"code": "not_found",
"request_id": "req_01JAB3K9X2"
}{
"error": "The tax return changed or is not ready for approval",
"code": "version_conflict",
"request_id": "req_01JAB3K9X2"
}Request a mandate
Asks the company to grant Melso representation before one administration for the procedures listed.
curl --request POST \
--url https://api.melso.ai/v1/companies/{company_id}/mandates \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"administration": "aeat",
"procedures": [
"tax_returns",
"notifications",
"certificates"
],
"signer": {
"name": "Lucía Martín Pérez",
"tax_id": "12345678Z",
"email": "lucia@example.com"
},
"return_url": "https://partner.example.com/melso/mandate-done"
}
'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/mandates"
payload = {
"administration": "aeat",
"procedures": ["tax_returns", "notifications", "certificates"],
"signer": {
"name": "Lucía Martín Pérez",
"tax_id": "12345678Z",
"email": "lucia@example.com"
},
"return_url": "https://partner.example.com/melso/mandate-done"
}
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({
administration: 'aeat',
procedures: ['tax_returns', 'notifications', 'certificates'],
signer: {name: 'Lucía Martín Pérez', tax_id: '12345678Z', email: 'lucia@example.com'},
return_url: 'https://partner.example.com/melso/mandate-done'
})
};
fetch('https://api.melso.ai/v1/companies/{company_id}/mandates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"administration": "aeat",
"procedures": [
"tax_returns"
],
"status": "pending_signature",
"created_at": "2023-11-07T05:31:56Z",
"signing_url": "<string>",
"rejection_reason": "<string>",
"signed_at": "2023-11-07T05:31:56Z",
"activated_at": "2023-11-07T05:31:56Z",
"revoked_at": "2023-11-07T05:31:56Z",
"evidence": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
}
}{
"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": "invoice not found",
"code": "not_found",
"request_id": "req_01JAB3K9X2"
}{
"error": "The tax return changed or is not ready for approval",
"code": "version_conflict",
"request_id": "req_01JAB3K9X2"
}signing_url
where the company’s legal representative reviews and signs the mandate.
A mandate is active once the administration has registered it; until
then Melso does not act before that administration.Authorizations
Your partner secret key, mk_live_… for real companies or mk_test_…
for test companies. Keep it on your servers. See
Authentication.
Headers
A unique key, such as a UUID, that makes a retried create safe. Reusing a key with a different body is refused.
255Path Parameters
The company's ID. Every company-scoped call works in exactly this company.
Body
aeat, tgss, sepe 1What Melso may do under the mandate. AEAT: tax_returns, notifications,
certificates, census (036 and 037). TGSS: affiliation,
contributions, notifications, certificates. SEPE: contracts
(Contrat@), company_certificates (Certific@2).
tax_returns, notifications, certificates, census, affiliation, contributions, contracts, company_certificates The company's legal representative, or the autónomo.
Show child attributes
Show child attributes
Where the hosted signing page sends the person when they finish.
Response
The mandate, waiting for signature.
aeat, tgss, sepe What Melso may do under the mandate. AEAT: tax_returns, notifications,
certificates, census (036 and 037). TGSS: affiliation,
contributions, notifications, certificates. SEPE: contracts
(Contrat@), company_certificates (Certific@2).
tax_returns, notifications, certificates, census, affiliation, contributions, contracts, company_certificates signed: the company signed; Melso is registering it with the
administration. active: registered, so Melso can act. rejected:
the administration refused the registration; rejection_reason says why.
pending_signature, signed, active, rejected, revoked, expired The hosted page where the signer signs. Present while pending_signature.
Show child attributes
Show child attributes