Draft a corrective invoice

curl --request POST \
  --url https://api.melso.ai/v1/companies/{company_id}/invoices/{invoice_id}/correct \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "issue_date": "2023-12-25",
  "lines": [
    {
      "description": "<string>",
      "quantity": "<string>",
      "unit_price": "<string>"
    }
  ],
  "notes": "<string>",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "due_date": "2023-12-25"
}
'

import requests

url = "https://api.melso.ai/v1/companies/{company_id}/invoices/{invoice_id}/correct"

payload = {
    "issue_date": "2023-12-25",
    "lines": [
        {
            "description": "<string>",
            "quantity": "<string>",
            "unit_price": "<string>"
        }
    ],
    "notes": "<string>",
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "due_date": "2023-12-25"
}
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({
    issue_date: '2023-12-25',
    lines: [{description: '<string>', quantity: '<string>', unit_price: '<string>'}],
    notes: '<string>',
    customer_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    due_date: '2023-12-25'
  })
};

fetch('https://api.melso.ai/v1/companies/{company_id}/invoices/{invoice_id}/correct', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version": "<string>",
  "type": "standard",
  "status": "draft",
  "issue_date": "2023-12-25",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "lines": [
    {
      "description": "<string>",
      "quantity": "<string>",
      "unit_price": "<string>",
      "vat_rate": "<string>",
      "product_kind": "goods",
      "amount": "121.00"
    }
  ],
  "subtotal": "121.00",
  "vat_amount": "121.00",
  "irpf_amount": "121.00",
  "total": "121.00",
  "currency": "EUR",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "series": "<string>",
  "number": 123,
  "due_date": "2023-12-25",
  "customer_name": "<string>",
  "customer_tax_id": "<string>",
  "irpf_rate": "<string>",
  "tax_label": "IVA",
  "notes": "<string>",
  "fiscal_network": "verifactu",
  "verifactu_status": "pending",
  "pdf_ready": true,
  "payment_link": "<string>",
  "payment_link_status": "pending",
  "email_delivery_status": "pending",
  "email_delivery_error": "<string>",
  "sent_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "corrects_invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "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"
}

POST

companies

{company_id}

invoices

{invoice_id}

correct

Draft a corrective invoice

curl --request POST \
  --url https://api.melso.ai/v1/companies/{company_id}/invoices/{invoice_id}/correct \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "issue_date": "2023-12-25",
  "lines": [
    {
      "description": "<string>",
      "quantity": "<string>",
      "unit_price": "<string>"
    }
  ],
  "notes": "<string>",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "due_date": "2023-12-25"
}
'

import requests

url = "https://api.melso.ai/v1/companies/{company_id}/invoices/{invoice_id}/correct"

payload = {
    "issue_date": "2023-12-25",
    "lines": [
        {
            "description": "<string>",
            "quantity": "<string>",
            "unit_price": "<string>"
        }
    ],
    "notes": "<string>",
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "due_date": "2023-12-25"
}
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({
    issue_date: '2023-12-25',
    lines: [{description: '<string>', quantity: '<string>', unit_price: '<string>'}],
    notes: '<string>',
    customer_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    due_date: '2023-12-25'
  })
};

fetch('https://api.melso.ai/v1/companies/{company_id}/invoices/{invoice_id}/correct', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "version": "<string>",
  "type": "standard",
  "status": "draft",
  "issue_date": "2023-12-25",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "lines": [
    {
      "description": "<string>",
      "quantity": "<string>",
      "unit_price": "<string>",
      "vat_rate": "<string>",
      "product_kind": "goods",
      "amount": "121.00"
    }
  ],
  "subtotal": "121.00",
  "vat_amount": "121.00",
  "irpf_amount": "121.00",
  "total": "121.00",
  "currency": "EUR",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "series": "<string>",
  "number": 123,
  "due_date": "2023-12-25",
  "customer_name": "<string>",
  "customer_tax_id": "<string>",
  "irpf_rate": "<string>",
  "tax_label": "IVA",
  "notes": "<string>",
  "fiscal_network": "verifactu",
  "verifactu_status": "pending",
  "pdf_ready": true,
  "payment_link": "<string>",
  "payment_link_status": "pending",
  "email_delivery_status": "pending",
  "email_delivery_error": "<string>",
  "sent_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "corrects_invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "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"
}

Live capability. Melso runs this in production today. Partner keys reach it once your partner account is enabled. See Availability.

notes must give the reason for the correction, and lines may carry negative prices. The original stays as issued; the corrective is issued like any draft, in the R- series.

Authorizations

Authorization

string

header

required

Your partner secret key, mk_live_… for real companies or mk_test_… for test companies. Keep it on your servers. See Authentication.

Headers

Idempotency-Key

string

A unique key, such as a UUID, that makes a retried create safe. Reusing a key with a different body is refused.

Maximum string length: 255

Path Parameters

company_id

string<uuid>

required

The company's ID. Every company-scoped call works in exactly this company.

invoice_id

string<uuid>

required

Body

application/json

issue_date

string<date>

required

lines

object[]

required

Required array length: 1 - 200 elements

Show child attributes

notes

string

required

The reason for the correction.

Maximum string length: 4000

customer_id

string<uuid>

Must be the original invoice's customer. Defaults to it.

due_date

string<date>

irpf_rate

enum<string>

Available options:

0,

7,

15

Response

The corrective draft, with type corrective and corrects_invoice_id.

string<uuid>

required

version

string

required

A fingerprint of the invoice's fiscal content. Issuing requires the exact version the person reviewed.

type

enum<string>

required

Available options:

standard,

proforma,

corrective

status

enum<string>

required

draft until a person issues it. issued once numbered; sent once emailed; paid once marked paid.

Available options:

draft,

issued,

sent,

paid

issue_date

string<date>

required

customer_id

string<uuid>

required

lines

object[]

required

Show child attributes

subtotal

string

required

An amount in euros as a decimal string with two decimals, such as "121.00".

Pattern: ^-?[0-9]+\.[0-9]{2}$

Example:

"121.00"

vat_amount

string

required

An amount in euros as a decimal string with two decimals, such as "121.00".

Pattern: ^-?[0-9]+\.[0-9]{2}$

Example:

"121.00"

irpf_amount

string

required

An amount in euros as a decimal string with two decimals, such as "121.00".

Pattern: ^-?[0-9]+\.[0-9]{2}$

Example:

"121.00"

total

string

required

An amount in euros as a decimal string with two decimals, such as "121.00".

Pattern: ^-?[0-9]+\.[0-9]{2}$

Example:

"121.00"

currency

string

required

Allowed value: "EUR"

created_at

string<date-time>

required

updated_at

string<date-time>

required

series

string | null

Set at issue. The issue year, such as 2026; R-2026 for a corrective.

number

integer | null

Set at issue, the next in the series.

due_date

string<date> | null

customer_name

string

The customer's name when the invoice was drafted.

customer_tax_id

string

irpf_rate

string

A decimal number as a string, such as "21" or "0.5".

Pattern: ^-?[0-9]{1,10}(\.[0-9]{1,6})?$

tax_label

enum<string>

Available options:

IVA,

IGIC

notes

string

fiscal_network

enum<string>

Where the invoice is registered, from the company's tax territory.

Available options:

verifactu,

ticketbai

verifactu_status

enum<string>

The registration state with VERI*FACTU or TicketBAI.

Available options:

pending,

registered,

error

pdf_ready

boolean

payment_link

string<uri> | null

payment_link_status

enum<string>

Available options:

pending,

creating,

active,

inactive,

error,

unknown

email_delivery_status

enum<string>

Available options:

pending,

sending,

sent,

error,

unknown

email_delivery_error

string | null

sent_at

string<date-time> | null

paid_at

string<date-time> | null

corrects_invoice_id

string<uuid> | null

Get started

Solutions

Companies and access

Invoicing

Bookkeeping

Taxes

Payroll and Social Security

Draft a corrective invoice

Authorizations

Headers

Path Parameters

Body

Response