Filmo Docs
Español

Invoices

Create or update the mirror of an externally issued invoice

Keeps in Filmo a read-only copy of an invoice issued by ANOTHER system (an ERP such as Business Central), so the operations team can see it.

Tool
filmo_invoices_upsert_external
Access: Write

Result

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_invoices_upsert_external",
    "arguments": {
      "originSystem": "<originSystem>",
      "originExternalId": "orig_8f2a1c",
      "invoiceNumber": "<invoiceNumber>",
      "invoiceDate": "2026-09-01",
      "lines": [
        {
          "description": "<description>",
          "quantity": "<quantity>",
          "unitPrice": "1234.50",
          "discountPercent": "<discountPercent>",
          "taxType": "1234.50",
          "taxRate": "1234.50"
        }
      ]
    }
  }
}

generated from the schema

Filmo does not issue it: it is not numbered against a Filmo series, not signed and never sent to Verifactu. It is stored validated, locked and marked as externally issued, and in Filmo it cannot be edited, voided, collected, rectified, e-invoiced or emailed: every change arrives through this same call. The key is the pair in the path: repeating it updates the same mirror, and repeating the same content changes nothing. Responds 201 when it creates the mirror and 200 when it updates it or it was already identical. The customer is resolved by contactId, then by tax ID, then by exact name (contacts are never created implicitly); one that cannot be resolved is a 400 validation_error whose errors[0].path says why: contactId (no such contact), contactTaxId (several contacts share that tax ID, or none has it and no contactName was sent) or contactName (several contacts, or none, have that name). The declared totals are checked against the lines with a tolerance of one cent per line: if they do not match it is a 400 validation_error with errors[0].path subTotal, taxTotal or total (also total when base plus taxes do not add up to it); a tax rate that cannot be recognised for a line is lines[n].taxRate. 409 if the invoice number is already used by another invoice of the account, if the key belongs to an invoice that is not a synced mirror, or if a voided mirror is sent back as issued. Returns the full invoice, the same projection as its GET.

Arguments

originSystemstringRequired

Source system identifier, a lowercase slug (e.g. booqable, rentman, business_central).

Limits: pattern ^[a-z][a-z0-9_]{1,39}$

originExternalIdstringRequired

Identifier of the document in the source system.

Limits: min length 1, max length 200

invoiceNumberstringRequired

Invoice number exactly as issued by the source system.

Limits: min length 1, max length 60

invoiceDatestring<date>Required

Issue date.

dueDatestring<date>

Due date.

currencystringdefault:"EUR"

ISO 4217 currency.

Limits: min length 3, max length 3

contactIdstring

Filmo contact identifier.

Limits: min length 1, max length 128

contactTaxIdstring

Customer tax ID, when its Filmo identifier is unknown.

Limits: min length 1, max length 40

contactNamestring

Exact customer name, as a last resort.

Limits: min length 1, max length 200

linesobject[]Required

Invoice lines.

Limits: min 1 items, max 500 items

Show child attributes
lines.descriptionstringRequired

Line description.

Limits: min length 1, max length 500

lines.quantitystringRequired

Quantity.

Limits: pattern ^-?\d{1,13}(\.\d{1,6})?$

lines.unitPricestringRequired

Unit price before taxes.

Limits: pattern ^-?\d{1,13}(\.\d{1,6})?$

lines.discountPercentstring

Line discount as a percentage (0-100).

Limits: pattern ^-?\d{1,13}(\.\d{1,6})?$

lines.taxTypestring

Filmo tax type (e.g. IVA_21). When missing it is inferred from taxRate.

lines.taxRatestring

Tax percentage of the line (e.g. "21"). Required when taxType is missing.

Limits: pattern ^-?\d{1,13}(\.\d{1,6})?$

subTotalstring

Taxable base according to the source system (checked against the lines).

Limits: pattern ^-?\d{1,13}(\.\d{1,6})?$

taxTotalstring

Tax total according to the source system.

Limits: pattern ^-?\d{1,13}(\.\d{1,6})?$

totalstring

Total according to the source system.

Limits: pattern ^-?\d{1,13}(\.\d{1,6})?$

externalStatusstringdefault:"issued"

issued, or voided in the source system.

Available options: issued, voided

voidReasonstring

Reason the source system voided it.

Limits: max length 500

paymentStatusstring

Payment status according to the source system.

Available options: unpaid, partially_paid, paid, overpaid

totalPaidstring

Amount collected according to the source system.

Limits: pattern ^-?\d{1,13}(\.\d{1,6})?$

originUrlstring<uri>

Link to the document in the source system (https).

Limits: max length 2048

originFileUrlstring<uri>

Original PDF issued by the source system (https).

Limits: max length 2048

notesstring

Internal notes.

Limits: max length 2000

idempotencyKeystring

Idempotency key chosen by the client (a UUID is recommended). Repeating the same key with the same arguments within 24 h returns the stored response without executing again; with different arguments it responds 422. It is the safe way to retry after a network failure.

Limits: min length 1, max length 255

Result

On success the result carries structuredContent with data and meta. These are the attributes of data.

Show the attributes of data
idstring

Unique invoice identifier.

invoiceNumberstring | null

Invoice number; null while it is a draft (the number is assigned on validation).

statusstring

Document lifecycle status: draft, validated (validated and numbered) or voided.

Available options: draft, validated, voided

isRectificationboolean

Whether the invoice rectifies a previous one. Invoices created in Filmo are never rectifications, and credit notes are served by /api/v1/credit-notes; but /api/v1/invoices can still return imported rectifying documents (for example from a Rentman import) with this set to true, so deduplicate them against the credit notes by number.

invoiceDatestring<date-time> | null

Issue date in ISO 8601 with offset; null while it is a draft.

dueDatestring<date-time> | null

Due date in ISO 8601 with offset; null if not set.

currencystring

Invoice currency as an ISO 4217 code (for example "EUR").

contactobject | null

Compact reference to the invoiced contact; null if none.

Show child attributes
contact.idstring

Unique contact identifier.

contact.namestring

Contact name.

orderIdstring | null

Identifier of the source order; null if the invoice does not come from an order.

orderNumberstring | null

Number of the source order; null if the invoice does not come from an order.

projectIdstring | null

Identifier of the linked project; null if not linked.

subTotalstring

Subtotal before discounts and taxes, as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

discountTotalstring

Total discounts as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

taxesPricestring

Tax total as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

netPricestring

Taxable base (net before taxes) as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

grossPricestring

Total including taxes, as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

totalPaidstring | null

Amount collected to date as a decimal string "1234.50" (ROUND_HALF_UP); null if not recorded.

Limits: pattern ^-?\d+\.\d{2}$

paymentStatusstring

Payment status: unpaid (nothing collected yet, also for invoices without a recorded collection), partially_paid, paid, overpaid (collected above the total), overdue (past due and unpaid) or voided (the document is voided, whatever was collected before). The paymentStatus filter uses the same values.

Available options: unpaid, partially_paid, paid, overpaid, overdue, voided

paymentMethodstring | null

Payment method of the invoice; null if not recorded.

tagsobject[]

Tags attached to the invoice, with their identifier and name.

Show child attributes
tags.idstring

Unique identifier of the tag.

tags.namestring

Tag name.

createdAtstring<date-time>

Creation date in ISO 8601 with offset.

updatedAtstring<date-time>

Last update date in ISO 8601 with offset.

projectNamestring | null

Name of the linked project; null if not linked.

taxBreakdownobject[] | null

Tax breakdown by type; null if not calculated.

Show child attributes
taxBreakdown.taxTypestring

Tax type key (for example "IVA_21").

taxBreakdown.labelstring

Human-readable tax label.

taxBreakdown.ratenumber

Tax rate applied, as a percentage (for example 21 for 21%).

taxBreakdown.baseAmountstring

Taxable base the tax is applied to, as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

taxBreakdown.amountstring

Tax amount as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

productDiscountTotalstring

Total discounts applied at product level, as a decimal string "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal.

Limits: pattern ^-?\d+\.\d{2}$

globalDiscountTotalstring

Global discount total of the document, as a decimal string "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal.

Limits: pattern ^-?\d+\.\d{2}$

insuranceTotalstring

Insurance total as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

depositTotalstring

Deposit total as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

exchangeRatenumber | null

Exchange rate applied when the currency differs from the base currency; null if not applicable.

billingAddressobject | null

Billing address; null if not recorded.

Show child attributes
billingAddress.labelstring | null

Descriptive label of the address; null if not recorded.

billingAddress.addressLine1string | null

First address line; null if not recorded.

billingAddress.addressLine2string | null

Second address line; null if not recorded.

billingAddress.citystring | null

City; null if not recorded.

billingAddress.provincestring | null

Province or region; null if not recorded.

billingAddress.postcodestring | null

Postal code; null if not recorded.

billingAddress.countrystring | null

Country; null if not recorded.

sourceQuoteIdsstring[] | null

Identifiers of the source quotes; null if the invoice does not come from quotes.

sourceProformaIdsstring[] | null

Identifiers of the source proformas; null if the invoice does not come from proformas.

An error is a result with isError: true and the problem in content[0].text; there is no structuredContent. See Errors.

The same operation by REST

This tool runs PUT /api/v1/invoices/external/{originSystem}/{originExternalId}.

Related pages

Link to this section: Related pages

  • Invoices

    Create or update the mirror of an externally issued invoice

    Keeps in Filmo a read-only copy of an invoice issued by ANOTHER system (an ERP such as Business Central), so the operations team can see it.

  • Guides

    Safe writes

    An assistant that can write can also write the wrong thing. Decide which tools need a person, retry without duplicating, and know what a write sets in motion.

  • Guides

    Errors

    A tool error is a result with isError: true and the problem in the first text block. Branch on its code.

Was this page helpful?

Cookies

If you accept, we use Google cookies to measure visits and show you ads. Privacy policy

More information

With your consent we use Google Ads and Google Analytics cookies to measure which campaigns bring visitors and requests, and to show you Filmo ads on other sites. Without acceptance, Google receives cookieless measurement signals, including your IP address, browser information and a cleaned page URL. Your choice is shared with the Filmo app.