API Reference

Import a PDF invoice and convert it to an e-invoice

post
https://app.pennylane.com/api/external/v2/customer_invoices/e_invoices/import_and_convert

This endpoint imports a customer invoice from a PDF file and asynchronously converts it
into a Factur-X e-invoice (PDF/A-3) by embedding a structured XML into the provided PDF.
The invoice is returned immediately in the response; the conversion happens in the
background shortly after. Amounts are stored exactly as provided. Pennylane does not
recalculate or round them.

Requirements:

  • file_attachment_id must reference a PDF file.
  • The PDF must not already embed a Factur-X (or ZUGFeRD) XML. Import those files with
    /customer_invoices/e_invoices/imports instead.
  • The customer must be a company and not a public administration.
  • The three mandatory French legal notices ("Late payment penalties", "Fixed recovery
    cost for late payment", and "Early payment discount") are required. Either provide
    them in legal_notices, or configure them in the footer of the default invoice
    template of your Pennylane account. Without either, the request returns a 422 error.

Factur-X amount compliance (BR-CO-14/BR-CO-15): The Factur-X XML standard
requires the sum of line-level currency_tax values to equal the invoice-level
currency_tax exactly, and currency_amount_before_tax + currency_tax to equal
currency_amount exactly. A difference of even a few cents produces a
non-compliant XML. Ensure your amounts are fully consistent before sending.

ℹ️

This endpoint requires the following scope: customer_invoices:all

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
int64
required

ID of a previously uploaded file attachment. The attachment must already have a file.
If the file is not available yet, the API returns 409; retry after a few seconds.

date
required

Invoice date (ISO 8601)

date
required

Invoice payment deadline (ISO 8601)

int64
required

Customer identifier

enum

Type of sale printed on the invoice (Type de vente).
goods is a supply of goods, services is a supply of services,
and goods_and_services is both. null means the type has not been chosen.
This is not invoice line substance.
Omit this field to keep the invoice template default. Send null to clear it.

Type of sale printed on a customer invoice. This is not invoice line substance.

string
length ≤ 35
^[a-zA-Z0-9\-+_/]+$

Invoice number. Only alphanumeric characters and -+_/ are allowed.

string
enum
Defaults to EUR
string
required
^-?\d+(\.\d+)?$

Invoice currency amount before tax (total value before tax of the invoice in the currency of the invoice)

string
required
^-?\d+(\.\d+)?$

Invoice currency amount (total value of the invoice in the currency of the invoice)

string
^(-?\d+(\.\d+)?)?$

Invoice amount in euros (total value of the invoice in euros). If the currency is euro, currency_amount and amount are identical.

string
required
^-?\d+(\.\d+)?$

Invoice taxable amount (in invoice currency)

string
^(-?\d+(\.\d+)?)?$

Invoice taxable amount (in euros). If the currency is euro, currency_tax and tax are identical.

string | null

Custom label for the invoice used on accounting (ledger) entries. If not provided, Pennylane generates a label automatically.

transaction_reference
object

By adding this field you can automatically reconcile the newly imported invoice with a transaction. See documentation about automatic payment matching.

invoice_lines
array of objects
required
length ≥ 1
invoice_lines*
string
required
^-?\d+(\.\d+)?$

Invoice line total amount in the currency of the invoice.

string
^(-?\d+(\.\d+)?)?$

Invoice line amount in euros. If the currency is euro, currency_amount and amount are identical.

string
required
^-?\d+(\.\d+)?$

Invoice line taxable amount (in invoice currency)

string
^(-?\d+(\.\d+)?)?$

Invoice line taxable amount (in euros). If the currency is euro, currency_tax and tax are identical.

string
required
\S

Line item label

number
required

Line item quantity (number of items)

int64

The ledger account ID

string
enum

Resolves the line's ledger account to the company's goods or services account.

Unlike customer invoice create, import does not auto-fill fields from product_id, and product_id is not checked against substance.

When provided together with ledger_account_id, both must refer to the same account. If they do not match, the request returns 422.

Allowed:
string
required

The unit price excluding taxes. Can be set up to 6 decimals.

string
required

Line item unit (type of unit)

string
enum
required

Product VAT rate. A 20% VAT in France is FR_200.

string | null
deprecated

The description of the invoice line

⚠️

This attribute is deprecated and will be removed soon.

int64

The product ID

imputation_dates
object | null
performance_period
ledger_entry_line
object
discount
object

Line-level discount. All amounts must be provided after discount, no recomputation is performed. Use relative for a percentage discount and absolute for a fixed amount discount.

discount
object

Invoice-level discount. All amounts must be provided after discount, no recomputation is performed. Use relative for a percentage discount and absolute for a fixed amount discount.

legal_notices
object

The three mandatory French legal notices to embed in the e-invoice.
When provided, it takes priority over the legal notices configured in the
footer of your Pennylane account.

int64

ID of an existing customer invoice in Pennylane that this credit note credits.
The imported document must have negative amounts (a credit note).
The referenced invoice must exist in the same company, belong to the same
customer, be finalized (not a draft), not itself be a credit note, and have
enough remaining amount to absorb the credit note.

string

A unique external reference you can provide to track this customer invoice. If not provided, Pennylane will generate an identifier for you.

string | null

Buyer's purchase order reference (e-invoice field BT-13). Maximum 50 characters.

string | null

Contract reference (e-invoice field BT-12). Maximum 50 characters.

Headers
string

Numeric ID of the company to act on. Required when authenticating with a firm token. Ignored when the token is already bound to a company.

Responses

Updated about 12 hours ago

Language
Credentials
OAuth2
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 12 hours ago