Incoming Invoices

This section explains how to receive, validate, review, and process incoming invoices using faktoora's infrastructure. We support various input channels, automatic validations, and multi-level approval workflows.

Supported Input Channels

1. Email (IMAP or faktoora mailbox)

You can connect your own IMAP mailbox in the faktoora UI under Settings > Inbox.
Alternatively, faktoora provides a default mailbox address (you@in.faktoora.de) for immediate use.
faktoora scans all mailboxes every 5 minutes to extract attached invoices (PDF, XRechnung, ZUGFeRD).

2. API Upload

Submit invoices via POST /import/incoming with multipart/form-data, not JSON.
Form field:
- file (binary): The invoice file to upload (XRechnung XML, ZUGFeRD PDF/A-3, etc.)
Response (202 Accepted):
```
{
  "importId": "IMP456789"
}
```
- importId (string): Unique identifier for this import task

Backwards compatibility: The legacy endpoint POST /import (without the /incoming segment) also accepts invoice uploads and is still supported. New integrations should use POST /import/incoming.

3. PEPPOL Network

faktoora supports full PEPPOL connectivity.
You can receive invoices directly via your faktoora-assigned PEPPOL ID.

Import API Endpoints

All /import/incoming paths require apiKeyAuth. The legacy /import/{importId} prefix is also supported for backwards compatibility.

Endpoint	Method	Purpose
POST `/import/incoming`	POST	Upload an invoice file (`multipart/form-data`, field: `file`). Returns `{ “importId”: “...” }`.
PATCH `/import/incoming/{importId}`	PATCH	Edit invoice data after import (partial update). Returns the updated invoice record.
GET `/import/incoming`	GET	Paginated list of all incoming imported invoices (supports `page`, `perPage`, `sort`, `order`, filters).
GET `/import/incoming/{importId}/validation`	GET	JSON validation summary. Returns `{ “status”: “accepted” }` or `{ “status”: “rejected” }`.
GET `/import/incoming/{importId}/validation/pdf`	GET	PDF validation report.
GET `/import/incoming/{importId}/status`	GET	Import processing status with `validationStatus`, `visualizationStatus`, and `overallStatus`.
GET `/import/incoming/{importId}/content/summary`	GET	Key invoice attributes.
GET `/import/incoming/{importId}/content`	GET	Merged complete content (seller, buyer, line items, taxes, payment terms, payment means, delivery).
GET `/import/incoming/{importId}/content/pdf`	GET	PDF visual representation of the invoice.
GET `/import/incoming/{importId}/content/lineitems`	GET	Array of invoice line items.
GET `/import/incoming/{importId}/content/taxes`	GET	VAT breakdown by category.
GET `/import/incoming/{importId}/content/paymentterms`	GET	Payment terms (due date, Skonto conditions, etc.).
GET `/import/incoming/{importId}/content/paymentmeans`	GET	Payment methods (bank transfer, SEPA, etc.).
GET `/import/incoming/{importId}/content/seller`	GET	Seller snapshot from the invoice.
GET `/import/incoming/{importId}/content/buyer`	GET	Buyer snapshot from the invoice.
GET `/import/incoming/{importId}/content/delivery`	GET	Delivery address from the invoice.
GET `/import/incoming/{importId}/source`	GET	Original source file (XML preferred over PDF). Returns `application/xml` or `application/pdf`.
GET `/import/incoming/{importId}/attachments`	GET	Paginated list of embedded attachments extracted from the invoice.
GET `/import/incoming/{importId}/attachment/{attachmentId}`	GET	Metadata for a single attachment.
GET `/import/incoming/{importId}/attachment/{attachmentId}/file`	GET	Download the attachment file (`application/octet-stream`).

Example: Upload an invoice

curl -X POST \
     -H “X-API-KEY: your-api-token” \
     -F “file=@invoice.xml” \
     https://api.faktoora.com/api/v1/import/incoming

Response (202 Accepted)

{ “importId”: “IMP456789” }

Example: Check import status

curl -H “X-API-KEY: your-api-token” \
     https://api.faktoora.com/api/v1/import/incoming/IMP456789/status

Response (200 OK)

{
  “validationStatus”: “accepted”,
  “visualizationStatus”: “accepted”,
  “overallStatus”: “accepted”
}

overallStatus is accepted only when both validationStatus and visualizationStatus are accepted. Possible values for each: accepted, failed, pending.

Example: Retrieve structured content

# Full merged content
curl -H “X-API-KEY: your-api-token” \
     https://api.faktoora.com/api/v1/import/incoming/IMP456789/content

# Just line items
curl -H “X-API-KEY: your-api-token” \
     https://api.faktoora.com/api/v1/import/incoming/IMP456789/content/lineitems

# Original XML source file
curl -H “X-API-KEY: your-api-token” \
     https://api.faktoora.com/api/v1/import/incoming/IMP456789/source

Editing an Imported Invoice

Use PATCH /import/incoming/{importId} to correct or enrich invoice data after import — for example, to fix a typo in the invoice number, update amounts, link the invoice to a customer, or replace line items.

Only the fields you include in the request body are updated; all other fields remain unchanged.

Restrictions

Terminal statuses: invoices with status PAID, CANCELLED, or ARCHIVED cannot be edited. The API returns 400.
Status changes: the status field is not accepted on this endpoint. Use the dedicated status-transition endpoints instead.
File references (invoiceIncomingFileId, xmlInvoiceFileId, etc.) are silently ignored if included.
Ownership: the importId must belong to the authenticated API key. Returns 404 otherwise.
customerId / projectId: validated to belong to the authenticated user. Returns 404 if not found.

Editable fields

Field	Type	Notes
`invoiceNumber`	string	Correct the invoice number
`invoiceTypeCode`	number	`380`, `381`, or `384`
`issueDate`	date-time	Invoice date
`lastPaymentDate`	date-time	Due date
`amount`	number	Total amount (max `99999999.99`)
`outstandingBalance`	number	Remaining balance (max `99999999.99`)
`buyerReference`	string	Reference/routing field
`invoiceCurrencyCode`	string	ISO 4217 currency code
`customerId`	uuid	Link to a customer record
`projectId`	uuid	Link to a project
`sellerName`	string	Seller display name
`sellerSnapshot`	object	Full seller address/contact data
`buyerSnapshot`	object	Full buyer address/contact data
`invoiceIncomingPositions`	array	Line items — full replace (existing items are deleted)
`vatBreakdown`	array	Tax breakdown — triggers automatic `taxAmount` recalculation
`paymentMeans`	array	Payment methods — full replace
`paymentterm`	string	Free-text payment terms
`specifiedTradePaymentTerms`	array	Structured Skonto terms

Example: Correct an invoice number and link to a customer

curl -X PATCH \
     -H "X-API-KEY: your-api-token" \
     -H "Content-Type: application/json" \
     -d '{
       "invoiceNumber": "RE-2024-0042",
       "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
     }' \
     https://api.faktoora.com/api/v1/import/incoming/IMP456789

Response (200 OK) — returns the full updated invoice record.

Example: Update VAT breakdown (triggers taxAmount recalculation)

curl -X PATCH \
     -H "X-API-KEY: your-api-token" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": 1190.00,
       "vatBreakdown": [
         { "category": "S", "rate": 19, "taxable": 1000.00, "amount": 190.00 }
       ]
     }' \
     https://api.faktoora.com/api/v1/import/incoming/IMP456789

taxAmount on the invoice is recalculated automatically from the provided vatBreakdown.

Validation & Reporting

Automatic EN16931 validation runs upon upload.
If rejected:
1. A PDF validation report is generated.
2. A webhook with status=rejected fires.
If accepted:
- Invoice moves into your UI for review and approval.
- You may retrieve a human-readable report via the HTML or PDF endpoints above.

Invoice Visibility & Workflow in the UI

Once an invoice import is accepted, it appears in the faktoora UI under Incoming Invoices. From there, users can:

Review the imported invoice details.
Manually reject with a reason (triggers a rejection email).
Confirm to begin an approval workflow.
Trigger payment (if a bank account is connected).
Archive after payment completion.

Process Diagrams

Sequence Diagram

This diagram shows the end-to-end flow from sender to payment.

Flowchart

This flowchart outlines the automatic and manual steps from receipt to archiving.

Supported Input Channels​

1. Email (IMAP or faktoora mailbox)​

2. API Upload​

3. PEPPOL Network​

Import API Endpoints​

Editing an Imported Invoice​

Restrictions​

Editable fields​

Validation & Reporting​

Invoice Visibility & Workflow in the UI​

Process Diagrams​

Sequence Diagram​

Flowchart​