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”: “...” }.
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

---

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:

1. Review the imported invoice details.
2. Manually reject with a reason (triggers a rejection email).
3. Confirm to begin an approval workflow.
4. Trigger payment (if a bank account is connected).
5. 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.