Invoices

Invoices are the primary resource in Mandato. Each invoice represents a document that is validated, converted to the target country’s XML format, and submitted to the government e-invoicing system.

Invoice object

{
  "id": "inv_a1b2c3d4e5f6",
  "country": "RO",
  "supplierVat": "RO12345678",
  "customerVat": "RO87654321",
  "status": "accepted",
  "netAmount": "5200.00",
  "vatAmount": "988.00",
  "grossAmount": "6188.00",
  "currency": "RON",
  "govId": "4523789012",
  "externalId": "order-12345",
  "errorMessage": null,
  "errorTranslated": null,
  "errorFix": null,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:15.000Z"
}

Fields

Field	Type	Description
id	string	Unique invoice identifier
country	string	ISO 3166-1 alpha-2 country code (RO, IT, BE, etc.)
supplierVat	string	Supplier VAT number
customerVat	string	Customer VAT number
status	string	Current lifecycle status (see below)
netAmount	string	Net amount (decimal string)
vatAmount	string	Total VAT amount (decimal string)
grossAmount	string	Gross amount including VAT (decimal string)
currency	string	ISO 4217 currency code
govId	string|null	Government-assigned ID after submission
externalId	string|null	Your external reference ID
errorMessage	string|null	Raw error from the government system
errorTranslated	string|null	AI-translated error in plain English
errorFix	string|null	AI-suggested fix for the error
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

Invoice statuses

Status	Description
created	Invoice received and queued for processing
validated	Passed EN 16931 + country-specific validation rules
converting	Being converted to the target XML format
submitting	Being uploaded to the government system
submitted	Government acknowledged receipt, awaiting decision
accepted	Government accepted the invoice
rejected	Government rejected the invoice (see errorMessage)
error	Internal error during processing

---

Create an invoice

POST /v1/invoices

Creates a new invoice, validates it, converts it to XML, and submits it to the government system. The invoice is created immediately with a created status and processed asynchronously.

Headers

Header	Required	Description
Authorization	Yes	Bearer sk_test_... or Bearer sk_live_...
Content-Type	Yes	application/json
X-Idempotency-Key	No	Unique key to prevent duplicate submissions

Request body

Field	Type	Required	Description
country	string	Yes	Target country code (RO, IT, BE, PL, FR, DE)
invoiceType	string	No	invoice (default), credit_note, or debit_note
companyId	string	No	Specific company ID. If omitted, auto-matched by country.
externalId	string	No	Your external reference ID
supplier	object	Yes	Supplier party (see Party object below)
customer	object	Yes	Customer party (see Party object below)
lines	array	Yes	One or more line items (see Line object below)
currency	string	No	ISO 4217 code. Defaults to EUR.
issueDate	string	No	ISO 8601 date (YYYY-MM-DD). Defaults to today.
dueDate	string	No	ISO 8601 date (YYYY-MM-DD)
note	string	No	Free-text note included in the invoice
paymentMeans	object	No	Payment details (see below)
attachments	array	No	File attachments (see below)

Party object

Field	Type	Required	Description
vatNumber	string	Yes	VAT identification number (with country prefix)
name	string	Yes	Legal name
address	object	No	Address with street, city, postalCode, country, stateOrProvince
email	string	No	Contact email
phone	string	No	Contact phone
sdiCode	string	No	Italy SDI recipient code (7 characters)
peppolId	string	No	Peppol participant ID
siret	string	No	France SIRET number (14 digits)
leitwegId	string	No	Germany Leitweg-ID

Line object

Field	Type	Required	Description
description	string	Yes	Item description
quantity	number	No	Quantity (defaults to 1)
unitPrice	number	Yes	Unit price
vatRate	number	Yes	VAT rate as percentage (e.g., 19 for 19%)
unitCode	string	No	UN/ECE unit code (defaults to C62 / “unit”)
discount	number	No	Discount amount per unit
itemCode	string	No	Product/item classification code

PaymentMeans object

Field	Type	Required	Description
bankAccount	string	No	IBAN bank account number
bic	string	No	BIC/SWIFT code
paymentTerms	string	No	Free-text payment terms description
dueDate	string	No	ISO 8601 payment due date

Attachment object

Field	Type	Required	Description
filename	string	Yes	File name with extension
content	string	Yes	Base64-encoded file content
mimeType	string	Yes	MIME type (e.g., application/pdf)

Example request

curl -X POST https://api.getmandato.dev/v1/invoices \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-12345-inv-001" \
  -d '{
    "country": "RO",
    "externalId": "order-12345",
    "supplier": {
      "vatNumber": "RO12345678",
      "name": "TechVision SRL",
      "address": {
        "street": "Strada Exemplu 42",
        "city": "Bucharest",
        "postalCode": "010101",
        "country": "RO"
      }
    },
    "customer": {
      "vatNumber": "RO87654321",
      "name": "Client Corp SRL",
      "address": {
        "street": "Bulevardul Unirii 10",
        "city": "Cluj-Napoca",
        "postalCode": "400001",
        "country": "RO"
      }
    },
    "lines": [
      {
        "description": "Software development services",
        "quantity": 1,
        "unitPrice": 5000,
        "vatRate": 19
      },
      {
        "description": "Cloud hosting",
        "quantity": 1,
        "unitPrice": 200,
        "vatRate": 19
      }
    ],
    "currency": "RON",
    "issueDate": "2025-01-15",
    "dueDate": "2025-02-15",
    "paymentMeans": {
      "bankAccount": "RO49AAAA1B31007593840000",
      "bic": "AAABROBU",
      "paymentTerms": "Net 30"
    },
    "note": "Thank you for your business."
  }'

Example response (201 Created)

{
  "data": {
    "id": "inv_a1b2c3d4e5f6",
    "country": "RO",
    "supplierVat": "RO12345678",
    "customerVat": "RO87654321",
    "status": "created",
    "netAmount": "5200.00",
    "vatAmount": "988.00",
    "grossAmount": "6188.00",
    "currency": "RON",
    "govId": null,
    "externalId": "order-12345",
    "errorMessage": null,
    "errorTranslated": null,
    "errorFix": null,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
}

Error responses

Status	Type	Description
400	validation_error	Invalid request body or missing required fields
401	authentication_error	Invalid or missing API key
403	usage_limit_exceeded	Monthly invoice limit reached
409	conflict_error	Idempotency key conflict (different body for same key)
429	rate_limit_error	Too many requests

---

List invoices

GET /v1/invoices

Returns a paginated list of invoices for your account. Results are ordered by creation date (newest first).

Query parameters

Parameter	Type	Description
country	string	Filter by country code (e.g., RO)
status	string	Filter by status (e.g., accepted, rejected)
companyId	string	Filter by company ID
search	string	Search in VAT numbers, external ID
dateFrom	string	Filter invoices created after this date (ISO 8601)
dateTo	string	Filter invoices created before this date (ISO 8601)
cursor	string	Cursor for pagination (from nextCursor in previous response)
limit	number	Number of results per page (default 20, max 100)

Example request

curl "https://api.getmandato.dev/v1/invoices?country=RO&status=accepted&limit=10" \
  -H "Authorization: Bearer sk_test_your_key"

Example response

{
  "data": [
    {
      "id": "inv_a1b2c3d4e5f6",
      "country": "RO",
      "supplierVat": "RO12345678",
      "customerVat": "RO87654321",
      "status": "accepted",
      "netAmount": "5200.00",
      "vatAmount": "988.00",
      "grossAmount": "6188.00",
      "currency": "RON",
      "govId": "4523789012",
      "externalId": "order-12345",
      "errorMessage": null,
      "errorTranslated": null,
      "errorFix": null,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:15.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6Imludl9hMWIyYzNkNGU1ZjYifQ"
}

Pagination

Mandato uses cursor-based pagination. To get the next page, pass the nextCursor value as the cursor parameter:

curl "https://api.getmandato.dev/v1/invoices?cursor=eyJpZCI6Imludl9hMWIyYzNkNGU1ZjYifQ&limit=10" \
  -H "Authorization: Bearer sk_test_your_key"

When hasMore is false, there are no more results.

---

Get an invoice

GET /v1/invoices/:id

Retrieves a single invoice by ID.

Path parameters

Parameter	Type	Description
id	string	Invoice ID (e.g., inv_a1b2c3d4e5f6)

Example request

curl https://api.getmandato.dev/v1/invoices/inv_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_test_your_key"

Example response

{
  "data": {
    "id": "inv_a1b2c3d4e5f6",
    "country": "RO",
    "supplierVat": "RO12345678",
    "customerVat": "RO87654321",
    "status": "accepted",
    "netAmount": "5200.00",
    "vatAmount": "988.00",
    "grossAmount": "6188.00",
    "currency": "RON",
    "govId": "4523789012",
    "externalId": "order-12345",
    "errorMessage": null,
    "errorTranslated": null,
    "errorFix": null,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:15.000Z"
  }
}

Error responses

Status	Type	Description
404	not_found	Invoice not found or belongs to a different account

---

Validate an invoice (dry-run)

POST /v1/invoices/validate

Runs the full validation pipeline on an invoice without creating or submitting it. Use this for pre-submission checks and form validation.

The request body is identical to POST /v1/invoices.

Example request

curl -X POST https://api.getmandato.dev/v1/invoices/validate \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "RO",
    "supplier": {
      "vatNumber": "RO12345678",
      "name": "TechVision SRL"
    },
    "customer": {
      "vatNumber": "RO87654321",
      "name": "Client Corp SRL"
    },
    "lines": [
      {
        "description": "Consulting",
        "unitPrice": 1000,
        "vatRate": 19
      }
    ]
  }'

Example response (valid)

{
  "valid": true,
  "errors": []
}

Example response (invalid)

{
  "valid": false,
  "errors": [
    "BR-RO-010: Supplier address is required for Romanian invoices",
    "BR-16: Invoice must have at least one line with a positive amount"
  ]
}

Tip

Use the validate endpoint in your UI to show real-time validation feedback as users fill in invoice forms. It runs the same rules as the create endpoint but does not persist anything.

---

Get invoice events

GET /v1/invoices/:id/events

Returns the full event timeline for an invoice, showing every status transition with timestamps and metadata.

Path parameters

Parameter	Type	Description
id	string	Invoice ID

Example request

curl https://api.getmandato.dev/v1/invoices/inv_a1b2c3d4e5f6/events \
  -H "Authorization: Bearer sk_test_your_key"

Example response

{
  "data": [
    {
      "id": "evt_001",
      "event": "invoice.created",
      "status": "created",
      "metadata": null,
      "createdAt": "2025-01-15T10:00:00.000Z"
    },
    {
      "id": "evt_002",
      "event": "invoice.validated",
      "status": "validated",
      "metadata": {
        "rulesChecked": 42,
        "format": "UBL-CIUS-RO"
      },
      "createdAt": "2025-01-15T10:00:01.000Z"
    },
    {
      "id": "evt_003",
      "event": "invoice.submitted",
      "status": "submitted",
      "metadata": {
        "govEndpoint": "ANAF e-Factura",
        "uploadId": "8734291"
      },
      "createdAt": "2025-01-15T10:00:05.000Z"
    },
    {
      "id": "evt_004",
      "event": "invoice.accepted",
      "status": "accepted",
      "metadata": {
        "govId": "4523789012",
        "govMessage": "Factura a fost acceptata"
      },
      "createdAt": "2025-01-15T10:00:15.000Z"
    }
  ]
}

Event types

Event	Description
invoice.created	Invoice received and queued
invoice.validated	Passed all validation rules
invoice.submitted	Uploaded to the government system
invoice.accepted	Government accepted the invoice
invoice.rejected	Government rejected the invoice
invoice.error	Internal processing error