Errors
Every error is JSON with a message for a person and, where you can act on it, a stablecode to branch on:
Codes you will meet often:
Money
Amounts are strings in euros with two decimals, such as"1210.00", never
floating-point numbers. Rates are strings too, such as "21" or "15". A
negative amount on a return means a result to offset or refund.
Dates and periods
Dates areYYYY-MM-DD; timestamps are RFC 3339. A tax period is one of:
Deadlines already move for national and regional public holidays.
Versions
Anything a person approves carries aversion, and approving it needs that
exact expected_version. Records you edit (expenses, income, corporate tax
inputs) use the same check: send the version you read as expected_version,
and a 409 tells you someone changed it first.
This is how the API keeps the rule that a person approves exactly what they
saw. A draft that changed after the person read it cannot be approved by
mistake.
Pagination
Lists return a page and a cursor:next_cursor as cursor for the next page. next_cursor is null on
the last page. limit sets the page size, 50 by default and 200 at most.
Idempotency
Send anIdempotency-Key header, such as a UUID, on every POST that creates
something. Retrying with the same key returns the first result instead of
creating a second object; reusing a key with a different body is refused.
Some operations are idempotent by nature and say so: issuing an invoice again
with the same expected_version reuses its number, and marking an invoice paid
twice keeps the first paid_at.
Rate limits
A key may make 600 requests a minute. Over the limit, the API answers429
with Retry-After. Push bank movements and payslips in batches rather than one
call each.
Versioning
The version is in the path,/v1. Within v1, Melso adds fields, operations,
event types and enum values without notice, so ignore what you do not know.
Anything that would break a client comes as a new version, and every partner
hears about it before it ships.