v1

latestOpenAPI 3.1.02026-08-0658107212.4 KB

Invoices

Create Invoice

Creates a new invoice, simplified_invoice, invoice_receipt, credit_note or debit_note.

Creating new clients or items along with the documents

This method also allows to create a new client and/or new items in the same request with the following behavior:

If the client name does not exist, a new one is created.
If items do not exist with the given names, new ones will be created.
If item name already exists, the item is updated with the new values.

Taxes

Regarding item taxes, if the tax name is not found, the default tax is applyed to that item. Portuguese accounts should also send the IVA exemption reason if the invoice contains exempt items (IVA 0%).

Note: Simplified Invoices are only available in Portugal.

post/{invoices-type}.json

Path parameters

invoices-type'invoices' | 'invoice_receipts' | 'simplified_invoices' | 'credit_notes' | 'debit_notes' required

The type of the invoice document.

Query parameters

api_keystring required

Example:YOUR_API_KEY

Your API Key.

Request body

proprietary_uidstring

Example request

{
  "invoice": {
    "date": "22/11/2025",
    "due_date": "22/12/2025",
    "reference": "PO-999",
    "observations": "Services rendered",
    "retention": "0",
    "tax_exemption": "M00",
    "sequence_id": "123456",
    "client": {
      "name": "Client A",
      "code": "CLI-001",
      "email": "client@mail.com",
      "address": "Street A",
      "city": "Lisbon",
      "postal_code": "1000-100",
      "fiscal_id": "500999888",
      "country": "Portugal",
      "website": "www.client-a.com",
      "phone": "912345678",
      "fax": "212345678",
      "observations": "VIP Client"
    },
    "items": [
      {
        "name": "Consulting",
        "description": "IT Services",
        "unit_price": 50,
        "quantity": 2,
        "unit": "hour",
        "tax": {
          "name": "IVA23"
        }
      }
    ],
    "mb_reference": "1",
    "owner_invoice_id": 1049,
    "tax_exemption_reason": "M00",
    "currency_code": "USD",
    "rate": "1.10",
    "plugin_id": "plugin_123",
    "global_discount": {
      "value_type": "percentage",
      "value": 10
    }
  },
  "proprietary_uid": "uuid-123"
}

Response

SUCCESS

Creates a new quote, proforma or fees_note.

Possible values for field atcud:

ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.
N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.
N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.

Example response

{
  "invoice": {
    "id": 2137287,
    "status": "final",
    "type": "Invoice",
    "sequence_number": "6/G",
    "inverted_sequence_number": "G/6",
    "atcud": "ABCD1234-6",
    "sequence_id": "12345",
    "tax_exemption": "M01",
    "date": "04/08/2016",
    "due_date": "19/08/2016",
    "reference": "ref123",
    "observations": "Observations",
    "retention": "0",
    "permalink": "https://www.app.invoicexpress.com/documents/...",
    "saft_hash": "J4ay",
    "sum": 24.39,
    "before_taxes": 24.39,
    "taxes": 5.61,
    "total": 30,
    "currency": "Euro",
    "client": {
      "id": 628535,
      "name": "John Doe",
      "code": "C1",
      "country": "Portugal",
      "email": "john@example.com"
    },
    "items": [
      {
        "name": "Product A",
        "description": "Big Product",
        "unit_price": 100,
        "quantity": 1,
        "unit": "un",
        "tax": {
          "name": "IVA23",
          "value": 23
        },
        "total": 123
      }
    ],
    "mb_reference": {
      "entity": "10611",
      "reference": "123 456 789",
      "value": 123.45
    }
  }
}