Skip to content

Invoices

Endpoints for listing and creating sales invoice documents.

GET /invoices

List invoices with optional filtering, searching, and pagination.

Request

GET /api/{account}/v4.0.0/invoices
Authorization: Bearer <xa-token>

Parameters

Name In Type Required Description
nonce query integer (int64) No Client-generated unique sequential number
filterDate query string No Filter by date or interval. Format: YYYY-MM-DD or YYYY-MM-DD:YYYY-MM-DD
searchString query string No Search by document number. Example: searchString=123456
searchColumn query string No Column to search instead of document number. Example: searchColumn=document_set&searchString=ORD
searchOperator query string No Comparison operator: lt (<), lte (<=), gt (>), gte (>=), ne (<>)
skip query integer No Number of records to skip (pagination)
limit query integer No Max records to return. Max: 1000, default: 50

Responses

200 — Success

Returns an array of customerDocument objects (empty array if none found).

[
  {
    "id": 1001,
    "document_set": "FT",
    "seq_number": "FT2024/1001",
    "date": "2024-11-01",
    "currency": "EUR",
    "total_amount": 1230.00,
    "customer": { "name": "Acme Corp", "vat_id": "PT123456789" },
    "items": [ ... ]
  }
]

400 — Invalid input parameters

POST /invoices

Create a new invoice document.

Request

POST /api/{account}/v4.0.0/invoices?nonce={nonce}
Authorization: Bearer <xa-token>
Content-Type: application/json

Parameters

Name In Type Required Description
nonce query integer (int64) Yes Client-generated unique sequential number
print query integer No Pass 1 to receive the created document as a PDF. Default: 0

Request Body

A customerDocument object. Required fields: document_set, seq_number, date, currency, total_amount.

{
  "document_set": "FT",
  "seq_number": "FT2024/1002",
  "date": "2024-11-15",
  "currency": "EUR",
  "total_amount": 500.00,
  "customer": {
    "name": "Acme Corp",
    "vat_id": "PT123456789"
  },
  "items": [
    {
      "description": "Consulting Services",
      "qty": 2,
      "unit_price": 250.00,
      "vat": 23.0
    }
  ]
}

Responses

201 — Document created

Returns a documentCreated object by default, or a PDF binary when print=1.

{
  "id": 1002,
  "documentSeries": "FT",
  "documentNumber": "FT2024/1002",
  "url": "https://gestix.pt/.../FT2024-1002.pdf"
}

400 — Invalid input

Returns an apiError.

409 — Duplicate entry

Returned when a document with the same identifier already exists. Returns an apiError.

See Also