Outgoing Invoices

This section explains how to create, send, retrieve, and manage outgoing invoices via faktoora's e-Invoicing API. Invoices are created asynchronously, with webhook notifications or polling available to track status and fetch the resulting documents.

---

Creation Modes

When creating invoices via POST /invoices, you can choose one of three modes in the request payload:

• Draft (draftOnly=true):
  The invoice is created in draft status and requires manual confirmation in the UI before sending.
• Review (reviewMode=true):
  The invoice enters review status; a user must approve in the UI before sending.
• Direct (no draft or review flags):
  The invoice is created and sent automatically upon generation.

---

Outgoing Invoice API Endpoints

All invoice endpoints require apiKeyAuth.

Endpoint	Method	Description
POST /invoices	POST	Create one or more invoices (202 Accepted). Returns faktooraId and detailsPage.
GET /invoices	GET	List invoices with pagination and filtering (keyword, invoiceNumber, date ranges, sort).
GET /invoices?invoiceNumber=	GET	Download a single invoice by invoiceNumber (PDF or XML). Set Accept header accordingly.
GET /invoices/{faktooraId}	GET	Download an invoice by faktooraId (PDF or XML). Set Accept header accordingly.
GET /invoices/{faktooraId}/status	GET	Poll invoice processing status (authority registration, delivery, validation). Use after POST 202.
GET /invoices/{faktooraId}/validation-report	GET	Download the PDF validation report for the most recent validation. Returns 404 if none exists.
DELETE /invoices/{faktooraId}	DELETE	Delete an invoice. Requires invoiceDeleteMode to be enabled on the account.

Example: Create invoice

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "invoices": [
      {
        "buyer": { /* ... EN16931 fields ... */ },
        "seller": { /* ... */ },
        "invoiceNumber": "INV-1001",
        "issueDate": "20250630",
        "delivery": { /* optional send config */ },
        "draftOnly": true
      }
    ]
  }' \
  https://api.faktoora.com/api/v1/invoices

Response (202 Accepted)

[
  {
    "faktooraId": "INV123456",
    "detailsPage": "https://app.faktoora.com/invoice/details/..."
  }
]

Example: Poll invoice status

curl -H "X-API-KEY: your-api-token" \
     https://api.faktoora.com/api/v2/invoices/INV123456/status

Response (200 OK)

{
  "invoiceStatus": "created",
  "jobStatus": null,
  "authority": [],
  "delivery": [
    {
      "type": "email",
      "recipient": "buyer@example.com",
      "carbonCopy": null,
      "blindCarbonCopy": null
    }
  ],
  "validation": {
    "status": "success",
    "validity": true,
    "createdAt": "2026-03-26T12:34:56Z"
  }
}

invoiceStatus progresses through: draft → review → created → sent. Poll until invoiceStatus is "created" (or "sent" if delivery is configured) before downloading the invoice.

The validation field is present only if validation was triggered (via validate: true on creation or manually in the UI). See Invoice Validation for details.

Example: Retrieve created invoice

# Download by faktooraId as PDF
curl -H "X-API-KEY: your-api-token" \
     -H "Accept: application/pdf" \
     https://api.faktoora.com/api/v1/invoices/INV123456

# Download by invoiceNumber as XML
curl -G -H "X-API-KEY: your-api-token" \
     -H "Accept: application/xml" \
     --data-urlencode "invoiceNumber=INV-1001" \
     https://api.faktoora.com/api/v1/invoices

Example: List invoices with filtering

curl -G -H "X-API-KEY: your-api-token" \
     --data-urlencode "keyword=Acme" \
     --data-urlencode "page=1" \
     --data-urlencode "perPage=20" \
     --data-urlencode "sort=issueDate" \
     --data-urlencode "order=desc" \
     https://api.faktoora.com/api/v1/invoices

Response (200 OK) — array of invoice items with pagination metadata.

Example: Delete an invoice

curl -X DELETE \
     -H "X-API-KEY: your-api-token" \
     https://api.faktoora.com/api/v1/invoices/INV123456

Deletion requires the invoiceDeleteMode feature to be enabled for your account. Returns 204 No Content on success.

---

Invoice Validation

You can automatically validate generated invoices against XRechnung/ZUGFeRD standards by setting validate: true in your POST /invoices request. Validation runs asynchronously after invoice file generation and produces a downloadable PDF report.

Requires the invoiceValidation feature to be enabled on your account. If the feature is not enabled, the validate parameter is silently ignored.

Triggering Validation

Add validate: true to any invoice in the creation payload:

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "invoices": [
      {
        "buyer": { /* ... */ },
        "invoiceNumber": "INV-1001",
        "issueDate": "20260330",
        "currency": "EUR",
        "format": "xrechnung",
        "validate": true
      }
    ]
  }' \
  https://api.faktoora.com/api/v1/invoices

Checking Validation Status

Poll GET /invoices/{faktooraId}/status — when validation has been triggered, the response includes a validation object:

{
  "invoiceStatus": "created",
  "jobStatus": null,
  "authority": [],
  "delivery": [],
  "validation": {
    "status": "success",
    "validity": true,
    "createdAt": "2026-03-26T12:34:56Z"
  }
}

Field	Type	Description
status	string	processing, success, or error
validity	boolean | null	Whether the invoice passed validation. null while processing.
createdAt	string	ISO 8601 timestamp of when validation was triggered.

The validation field is only present if a validation job exists for the invoice. If validate was not set or the feature is not enabled, this field is omitted.

Downloading the Validation Report

Once validation.status is success or error, download the report PDF:

curl -H "X-API-KEY: your-api-token" \
     -o validation-report.pdf \
     https://api.faktoora.com/api/v1/invoices/INV123456/validation-report

Returns application/pdf. Returns 404 if no validation has been performed or the report is not yet available.

---

Outgoing Invoice Content Endpoints (/import/outgoing)

Once an outgoing invoice has been created via POST /invoices, you can retrieve its structured content via the /import/outgoing/{faktooraId} track. These endpoints provide machine-readable access to the invoice's parsed data.

All /import/outgoing endpoints require apiKeyAuth.

Endpoint	Method	Description
GET /import/outgoing	GET	Paginated list of all outgoing imported invoices.
POST /import/outgoing	POST	Import an existing XRechnung or ZUGFeRD file (multipart/form-data, field: file). Returns { faktooraId }.
GET /import/outgoing/{faktooraId}/content/summary	GET	Key invoice attributes summary.
GET /import/outgoing/{faktooraId}/content	GET	Merged complete content (seller, buyer, line items, taxes, payment terms, payment means).
GET /import/outgoing/{faktooraId}/content/lineitems	GET	Array of invoice line items.
GET /import/outgoing/{faktooraId}/content/taxes	GET	VAT breakdown by category.
GET /import/outgoing/{faktooraId}/content/paymentterms	GET	Payment terms (e.g., due date, Skonto conditions).
GET /import/outgoing/{faktooraId}/content/paymentmeans	GET	Payment methods (bank transfer, SEPA, etc.).
GET /import/outgoing/{faktooraId}/content/seller	GET	Seller snapshot from the invoice.
GET /import/outgoing/{faktooraId}/content/buyer	GET	Buyer snapshot from the invoice.
GET /import/outgoing/{faktooraId}/content/delivery	GET	Delivery address from the invoice.
GET /import/outgoing/{faktooraId}/content/pdf	GET	PDF visual representation of the invoice.
GET /import/outgoing/{faktooraId}/source	GET	Original source file (XML preferred over PDF). Returns application/xml or application/pdf.
GET /import/outgoing/{faktooraId}/validation	GET	JSON validation summary. Returns { "status": "accepted" } or { "status": "rejected" }.
GET /import/outgoing/{faktooraId}/validation/pdf	GET	PDF validation report.
GET /import/outgoing/{faktooraId}/status	GET	Import processing status with validationStatus, visualizationStatus, and overallStatus (accepted, failed, or pending).
GET /import/outgoing/{faktooraId}/attachments	GET	Paginated list of embedded attachments extracted from the invoice.
GET /import/outgoing/{faktooraId}/attachment/{attachmentId}	GET	Metadata for a single attachment.
GET /import/outgoing/{faktooraId}/attachment/{attachmentId}/file	GET	Download the attachment file (application/octet-stream).

Example: Fetch invoice content summary

curl -H "X-API-KEY: your-api-token" \
     https://api.faktoora.com/api/v1/import/outgoing/INV123456/content/summary

Example: Check import status

curl -H "X-API-KEY: your-api-token" \
     https://api.faktoora.com/api/v1/import/outgoing/INV123456/status

Response (200 OK)

{
  "validationStatus": "accepted",
  "visualizationStatus": "accepted",
  "overallStatus": "accepted"
}

---

Webhook Notifications

Upon invoice creation or status changes, faktoora sends a webhook to your configured endpoint:

• status=draft, status=review, or status=created
• Payload includes faktooraId, status, timestamp, and invoice metadata.

---

Process Diagrams

Sequence Diagram

Illustrates the full lifecycle from client submission through sending and retrieval.

Flowchart

Shows conditional flows for creation modes, webhooks, and retrieval.