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.

PUT
/api/v1/invoices/external/{originSystem}/{originExternalId}

Request examples

curl https://app.filmo.io/api/v1/invoices/external/orig_8f2a1c/orig_8f2a1c \
  --request PUT \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
  --header 'Content-Type: application/json' \
  --data '{
  "invoiceNumber": "FV26-001042",
  "invoiceDate": "2026-09-15",
  "dueDate": "2026-10-15",
  "currency": "EUR",
  "contactTaxId": "B00000000",
  "lines": [
    {
      "description": "Alquiler de equipo de cámara (3 jornadas)",
      "quantity": "3",
      "unitPrice": "450.00",
      "taxRate": "21"
    },
    {
      "description": "Transporte ida y vuelta",
      "quantity": "1",
      "unitPrice": "120.00",
      "taxType": "IVA_21"
    }
  ],
  "total": "1778.70",
  "externalStatus": "issued",
  "paymentStatus": "unpaid",
  "originUrl": "https://businesscentral.dynamics.com/?company=Filmo&page=132&filter=FV26-001042"
}'
{
  "data": {
    "id": "invoice_9f3a2b",
    "invoiceNumber": "2026-0001",
    "status": "draft",
    "isRectification": true,
    "invoiceDate": "2026-09-01T08:00:00.000Z",
    "dueDate": "2026-09-01T08:00:00.000Z",
    "currency": "EUR",
    "contact": {
      "id": "contact_9f3a2b",
      "name": "Example contact"
    },
    "orderId": "order_9f3a2b",
    "orderNumber": "2026-0001",
    "projectId": "project_9f3a2b",
    "subTotal": "120.00",
    "discountTotal": "120.00",
    "taxesPrice": "120.00",
    "netPrice": "120.00",
    "grossPrice": "120.00",
    "totalPaid": "120.00",
    "paymentStatus": "unpaid",
    "paymentMethod": "Example payment method",
    "tags": [
      {
        "id": "tag_9f3a2b",
        "name": "Example tag"
      }
    ],
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z",
    "projectName": "Example project name",
    "taxBreakdown": [
      {
        "taxType": "120.00",
        "label": "Main",
        "rate": 1,
        "baseAmount": "120.00",
        "amount": "120.00"
      }
    ],
    "productDiscountTotal": "120.00",
    "globalDiscountTotal": "120.00",
    "insuranceTotal": "120.00",
    "depositTotal": "120.00",
    "exchangeRate": 1,
    "billingAddress": {
      "label": "Main",
      "addressLine1": "Calle de Ejemplo 12",
      "addressLine2": "Calle de Ejemplo 12",
      "city": "Madrid",
      "province": "Madrid",
      "postcode": "28001",
      "country": "ES"
    },
    "sourceQuoteIds": [
      "source_quote_9f3a2b"
    ],
    "sourceProformaIds": [
      "source_proforma_9f3a2b"
    ]
  }
}

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.

Authorizations

Bearer API key with the scope below. invoices:write

Headers

Idempotency-Keystring

Unique identifier of the request, chosen by the client (a UUID works). Between 1 and 255 characters: an empty header is rejected with 400 validation_error, because the client would believe itself protected. Repeating the same key with the SAME body within 24 h returns the stored response without executing again, with the Idempotent-Replay: true header. With a DIFFERENT body it returns 422. It is the safe way to retry after a network timeout.

Limits: min length 1, max length 255

Example:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

Path parameters

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

Body

application/json

Body schema: InvoiceExternalUpsertBody

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

Response

application/json

Successful response.

Response schema: InvoiceDetailDto

Envelope: InvoiceDetailResponse. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay

dataobject

The invoice in full, as returned by the API.

Show child attributes
data.idstring

Unique invoice identifier.

data.invoiceNumberstring | null

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

data.statusstring

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

Available options: draft, validated, voided

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

data.invoiceDatestring<date-time> | null

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

data.dueDatestring<date-time> | null

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

data.currencystring

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

data.contactobject | null

Compact reference to the invoiced contact; null if none.

Show child attributes
data.contact.idstring

Unique contact identifier.

data.contact.namestring

Contact name.

data.orderIdstring | null

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

data.orderNumberstring | null

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

data.projectIdstring | null

Identifier of the linked project; null if not linked.

data.subTotalstring

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

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

data.discountTotalstring

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

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

data.taxesPricestring

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

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

data.netPricestring

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

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

data.grossPricestring

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

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

data.totalPaidstring | null

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

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

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

data.paymentMethodstring | null

Payment method of the invoice; null if not recorded.

data.tagsobject[]

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

Show child attributes
data.tags.idstring

Unique identifier of the tag.

data.tags.namestring

Tag name.

data.createdAtstring<date-time>

Creation date in ISO 8601 with offset.

data.updatedAtstring<date-time>

Last update date in ISO 8601 with offset.

data.projectNamestring | null

Name of the linked project; null if not linked.

data.taxBreakdownobject[] | null

Tax breakdown by type; null if not calculated.

Show child attributes
data.taxBreakdown.taxTypestring

Tax type key (for example "IVA_21").

data.taxBreakdown.labelstring

Human-readable tax label.

data.taxBreakdown.ratenumber

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

data.taxBreakdown.baseAmountstring

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

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

data.taxBreakdown.amountstring

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

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

data.productDiscountTotalstring

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

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

data.globalDiscountTotalstring

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

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

data.insuranceTotalstring

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

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

data.depositTotalstring

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

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

data.exchangeRatenumber | null

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

data.billingAddressobject | null

Billing address; null if not recorded.

Show child attributes
data.billingAddress.labelstring | null

Descriptive label of the address; null if not recorded.

data.billingAddress.addressLine1string | null

First address line; null if not recorded.

data.billingAddress.addressLine2string | null

Second address line; null if not recorded.

data.billingAddress.citystring | null

City; null if not recorded.

data.billingAddress.provincestring | null

Province or region; null if not recorded.

data.billingAddress.postcodestring | null

Postal code; null if not recorded.

data.billingAddress.countrystring | null

Country; null if not recorded.

data.sourceQuoteIdsstring[] | null

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

data.sourceProformaIdsstring[] | null

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

metaobject

Additional information about the response.

Show child attributes
meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes
meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

StatusCodesMeaning
400validation_errorMalformed query or body. errors[] lists every offending field with its stable code.
402addon_requiredThe account plan does not include the add-on this operation needs; requiredAddon names it.
404not_foundIt does not exist or is outside the scope of the API key.
409conflictThe current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (If-Match) held the resource for more than five seconds. errors[0].code says which: in_progress and lock_timeout are solved by retrying; invalid_state is not, because the state of the resource forbids the operation.
422idempotency_key_reusedThe same key was used before with a different body. Change the key.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy

Related

Related pages

Link to this section: Related pages

  • Finance

    Invoice

    The invoice, as returned by the API.

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.