PEpennylane
Supplier Invoices

Import a supplier invoice with a file attached

Changed on

This endpoint allows you to import a supplier invoice with a file attached.

ℹ️ This endpoint requires the following scope: supplier_invoices:all

post/api/external/v2/supplier_invoices/import

Request

  • Base URL
    https://app.pennylane.com
  • URL
    https://app.pennylane.com/api/external/v2/supplier_invoices/import
  • Auth
    OAuth 2
    Authorization code: https://app.pennylane.com/oauth/authorize
    Token URL: https://app.pennylane.com/oauth/oauth/token scopes: supplier_invoices:all

Headers

X-Company-Idstring
Example:12345

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.

Request body

file_attachment_idinteger 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.

import_as_incompleteboolean

This will mark the invoice as incomplete.

supplier_idinteger required

The ID of the supplier to import the invoice for

datestring date required

The date of the invoice (ISO 8601)

deadlinestring date required

Invoice payment deadline (ISO 8601)

invoice_numberstring

The invoice number

currency'EUR' | 'USD' | 'GBP' | 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'FJD' | 'FKP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SLE' | 'SOS' | 'SRD' | 'STD' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'UYU' | 'UZS' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XDR' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMK' | 'ZMW' | 'ZWL'
currency_amount_before_taxstring required

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

currency_amountstring required

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

amountstring

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

currency_taxstring required

Invoice taxable amount (in invoice currency)

taxstring

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

labelstring nullable

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

external_referencestring

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

Example request

{
  "file_attachment_id": 123,
  "supplier_id": 456,
  "date": "2021-01-30",
  "deadline": "2021-01-30",
  "invoice_number": "F20230001",
  "currency_amount_before_tax": "100.00",
  "currency_amount": "120.00",
  "amount": "120.00",
  "currency_tax": "20.00",
  "tax": "20.00",
  "label": "Custom accounting label",
  "transaction_reference": {
    "banking_provider": "bank",
    "provider_field_name": "label",
    "provider_field_value": "invoice_number"
  },
  "invoice_lines": [
    {
      "label": "Demo label",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor",
      "currency_amount": "120.00",
      "amount": "120.00",
      "currency_tax": "20.00",
      "tax": "20.00",
      "ledger_account_id": 1255,
      "vat_rate": "FR_200",
      "imputation_dates": {
        "start_date": "2020-06-30",
        "end_date": "2021-06-30"
      },
      "performance_period": {
        "start_date": "2023-07-01",
        "end_date": "2023-07-31"
      },
      "ledger_entry_line": {
        "label": "Demo label"
      }
    }
  ],
  "external_reference": "FR123"
}

Response

The imported supplier invoice

idinteger required

The ID of the supplier invoice

labelstring nullable required
invoice_numberstring required
currency'EUR' | 'USD' | 'GBP' | 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'FJD' | 'FKP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SLE' | 'SOS' | 'SRD' | 'STD' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'UYU' | 'UZS' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XDR' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMK' | 'ZMW' | 'ZWL' required
amountstring required

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

currency_amountstring required

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

currency_amount_before_taxstring required

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

exchange_ratestring required

Invoice exchange rate (used to convert the invoice to euros. If the invoice currency is euro it will be 1.0)

datestring date nullable required

Invoice issue date (ISO 8601)

deadlinestring date nullable required

Invoice payment deadline (ISO 8601)

performance_datestring date nullable required

End date of the performance period of the first invoice line that has one (ISO 8601). Used for German VAT accounting (Leistungsdatum). Null if the company does not use German accounting, or if no invoice line has a performance period.

currency_taxstring required

Invoice taxable amount (in invoice currency)

taxstring required

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

reconciledboolean required

Whether the invoice has been reconciled or not

accounting_status'draft' | 'archived' | 'entry' | 'validation_needed' | 'complete' required

The accounting state of the invoice.

  • draft: The invoice is not yet sent to the accountant.
  • archived: The invoice has been archived.
  • entry: The invoice is incomplete. Some information is missing on the invoice and needs to be completed by SME.
  • validation_needed: The invoice is sent to the accountant and needs validation.
  • complete: The invoice has been validated by the accountant.
filenamestring nullable required

Name of the file attached to the invoice

public_file_urlstring nullable required

Public URL of the invoice file. The URL will expire after 30 minutes.

remaining_amount_with_taxstring nullable required

The remaining amount with VAT to pay for the invoice to be considered paid

remaining_amount_without_taxstring nullable required

The remaining amount without VAT to pay for the invoice to be considered paid

payment_status'to_be_processed' | 'to_be_paid' | 'partially_paid' | 'payment_error' | 'payment_scheduled' | 'payment_in_progress' | 'payment_emitted' | 'payment_found' | 'paid_offline' | 'fully_paid' required
paidboolean required

Invoice paid status (set to true if the invoice is paid)

external_referencestring required

The unique external reference that was assigned during creation either by you or Pennylane

archived_atstring date-time nullable required

The time the invoice has been archived

created_atstring date-time required

The time the invoice has been created

updated_atstring date-time required

The last time the invoice has been updated

Example response

{
  "id": 123,
  "label": "Demo label",
  "invoice_number": "F20230001",
  "amount": "230.32",
  "currency_amount": "230.32",
  "currency_amount_before_tax": "196.32",
  "exchange_rate": "1.0",
  "date": "2023-08-30",
  "deadline": "2023-09-30",
  "performance_date": "2023-07-31",
  "currency_tax": "34.0",
  "tax": "34.0",
  "filename": "my_file.pdf",
  "public_file_url": "https://app.pennylane.com/public/invoice/pdf?encrypted_id=bzjoVJe...3D%3D",
  "remaining_amount_with_tax": "20.0",
  "remaining_amount_without_tax": "16.0",
  "ledger_entry": {
    "id": 42003
  },
  "supplier": {
    "id": 456,
    "url": "https://app.pennylane.com/api/external/v2/suppliers/42"
  },
  "payment_method_ledger_account": {
    "id": 1255,
    "url": "https://app.pennylane.com/api/external/v2/ledger_accounts/1255"
  },
  "invoice_lines": {
    "url": "https://app.pennylane.com/api/external/v2/supplier_invoices/42/invoice_lines"
  },
  "categories": {
    "url": "https://app.pennylane.com/api/external/v2/supplier_invoices/42/categories"
  },
  "transaction_reference": {
    "banking_provider": "bank",
    "provider_field_name": "label",
    "provider_field_value": "invoice_number"
  },
  "payments": {
    "url": "https://app.pennylane.com/api/external/v2/supplier_invoices/42/payments"
  },
  "matched_transactions": {
    "url": "https://app.pennylane.com/api/external/v2/supplier_invoices/42/matched_transactions"
  },
  "external_reference": "FR123",
  "import_source": {
    "source": "dropbox",
    "path": "/ACCOUNTING INVOICES/2024/invoice.pdf"
  },
  "e_invoicing": {
    "source_file_url": "https://app.pennylane.com/rails/active_storage/blobs/redirect/abc123/invoice.xml",
    "electronic_billing_address": "0009:123456789"
  },
  "archived_at": "2023-08-30T10:08:08.146343Z",
  "created_at": "2023-08-30T10:08:08.146343Z",
  "updated_at": "2023-08-30T10:08:08.146343Z"
}

Changes

  • 871f863307e5Revision changes
    • breaking

      the // request property type changed from no type to string

    • warning

      added the new VES enum value to the response property for the response status

    • info

      added the new optional header request parameter X-Company-Id

    • info

      added the new optional request property //

    • info

      added the new DE_intracom_exempt_BU0233 enum value to the request property //

    • info

      added the new ES_intracom_sales_goods enum value to the request property //

    • info

      added the new ES_intracom_sales_services enum value to the request property //

    • info

      added the new ES_isp_purchases_100 enum value to the request property //

    • info

      added the new ES_isp_purchases_210 enum value to the request property //

    • info

      added the new ES_isp_sales enum value to the request property //

    • info

      added the new ES_suplido enum value to the request property //

    • info

      added the new VES enum value to the request property

    • info

      added the new helloasso enum value to the request property /

    • info

      added the new order_id enum value to the request property /

    • info

      added the required property / to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status