Post invoices to your accounting system

# Export FILMO_API_KEY first: a key with the scopes listed above.
FILMO_URL="${FILMO_BASE_URL:-https://app.filmo.io}"

// filmo.mjs: a small client. Node 22 or later, no dependencies.
export const API = (process.env.FILMO_BASE_URL ?? "https://app.filmo.io") + "/api/v1";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// GET with query parameters. Waits out a 429 as Retry-After says.
export async function get(path, query = {}, headers = {}) {
  const url = new URL(API + path);
  for (const [key, value] of Object.entries(query)) url.searchParams.set(key, String(value));
  for (;;) {
    const res = await fetch(url, {
      headers: { Authorization: ["Bearer", process.env.FILMO_API_KEY].join(" "), ...headers },
    });
    if (res.status === 429) {
      await sleep(Number(res.headers.get("Retry-After") ?? 1) * 1000);
      continue;
    }
    if (res.status === 304) return { status: 304, etag: res.headers.get("ETag") };
    if (!res.ok) {
      throw Object.assign(new Error(res.status + " " + (await res.text())), { status: res.status });
    }
    return {
      ...(await res.json()),
      status: res.status,
      etag: res.headers.get("ETag"),
      serverTime: new Date(res.headers.get("Date")), // the server's clock, not yours
    };
  }
}

# filmo.py: a small client. Python 3 and requests.
import os
import time
from email.utils import parsedate_to_datetime

import requests

API = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io") + "/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['FILMO_API_KEY']}"


def get(path, headers=None, **query):
    """GET with query parameters. Waits out a 429 as Retry-After says."""
    while True:
        res = session.get(API + path, params=query, headers=headers)
        if res.status_code == 429:
            time.sleep(int(res.headers.get("Retry-After", "1")))
            continue
        if res.status_code == 304:
            return {"status": 304, "etag": res.headers.get("ETag")}
        res.raise_for_status()
        body = res.json()
        body["status"] = res.status_code
        body["etag"] = res.headers.get("ETag")
        body["serverTime"] = parsedate_to_datetime(res.headers["Date"])  # the server's clock
        return body

# Export FILMO_API_KEY first: a key with the scopes listed above.
FILMO_URL="${FILMO_BASE_URL:-https://app.filmo.io}"

curl -sS "$FILMO_URL/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY"

import { get } from "./filmo.mjs";

const { data: account } = await get("/account");
console.log(account.timezone, account.currency, account.rateLimits.global.perMinute);

from filmo import get

account = get("/account")["data"]
print(account["timezone"], account["currency"], account["rateLimits"]["global"]["perMinute"])

FILMO_URL="${FILMO_BASE_URL:-https://app.filmo.io}"

# One window [updatedFrom, updatedBefore), one page. If pagination.hasMore is true, split the window.
curl -sS -G "$FILMO_URL/api/v1/invoices" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "updatedFrom=2026-10-08T00:00:00.000Z" \
  --data-urlencode "updatedBefore=2026-10-09T00:00:00.000Z" \
  --data-urlencode "sort=updatedAt" \
  --data-urlencode "limit=500"

// window.mjs: the windowed read of the syncing guide, one page per query.
import { get } from "./filmo.mjs";

const iso = (ms) => new Date(ms).toISOString();

export const START = Date.parse("2020-01-01T00:00:00Z"); // move it to the month of your first record

// B: the server's time minus the safety margin of the guide (2 minutes and 1 second). The time is the
// Date header of a response, never your own clock.
export async function upperBound() {
  const { serverTime } = await get("/account");
  return serverTime.getTime() - (2 * 60 * 1000 + 1000);
}

// Every record whose updatedAt (or createdAt) falls in [from, to), in epoch milliseconds.
// It never follows the cursor: a window that overflows one page is split in half.
export async function windowed(path, from, to, { field = "updated", query = {} } = {}) {
  const page = await get(path, {
    ...query,
    [field + "From"]: iso(from),
    [field + "Before"]: iso(to),
    sort: field + "At",
    limit: 500,
  });
  if (!page.pagination.hasMore) return page.data;
  if (to - from <= 1) throw new Error("More than 500 records share one millisecond: see the guide");
  const mid = Math.floor((from + to) / 2);
  const merged = new Map();
  for (const half of [
    await windowed(path, from, mid, { field, query }),
    await windowed(path, mid, to, { field, query }),
  ]) {
    for (const record of half) merged.set(record.id, record); // deduplicate by id
  }
  return [...merged.values()];
}

// Walks [start, end) in 30-day windows. Returns a Map of id to record.
export async function readRange(path, start, end, options) {
  const step = 30 * 24 * 3600 * 1000;
  const records = new Map();
  for (let from = start; from < end; from += step) {
    for (const record of await windowed(path, from, Math.min(from + step, end), options)) {
      records.set(record.id, record);
    }
  }
  return records;
}

# window.py: the windowed read of the syncing guide, one page per query.
from datetime import datetime, timezone

from filmo import get


START = int(datetime(2020, 1, 1, tzinfo=timezone.utc).timestamp() * 1000)  # move it to the month of your first record


def upper_bound():
    """B: the server's time minus the safety margin of the guide (2 minutes and 1 second).
    The time is the Date header of a response, never your own clock."""
    return int(get("/account")["serverTime"].timestamp() * 1000) - (2 * 60 * 1000 + 1000)


def iso(ms):
    stamp = datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
    return stamp.isoformat(timespec="milliseconds").replace("+00:00", "Z")


def windowed(path, start, end, field="updated", **query):
    """Every record whose updatedAt (or createdAt) falls in [start, end), in epoch ms.
    It never follows the cursor: a window that overflows one page is split in half."""
    page = get(
        path,
        **query,
        **{field + "From": iso(start), field + "Before": iso(end), "sort": field + "At", "limit": 500},
    )
    if not page["pagination"]["hasMore"]:
        return page["data"]
    if end - start <= 1:
        raise RuntimeError("More than 500 records share one millisecond: see the guide")
    mid = (start + end) // 2
    merged = {r["id"]: r for r in windowed(path, start, mid, field, **query)}
    merged.update({r["id"]: r for r in windowed(path, mid, end, field, **query)})
    return list(merged.values())


def read_range(path, start, end, field="updated", **query):
    """Walks [start, end) in 30-day windows. Returns a dict of id to record."""
    step = 30 * 24 * 3600 * 1000
    records = {}
    for begin in range(start, end, step):
        for record in windowed(path, begin, min(begin + step, end), field, **query):
            records[record["id"]] = record
    return records

FILMO_URL="${FILMO_BASE_URL:-https://app.filmo.io}"

# One window [updatedFrom, updatedBefore), one page. If pagination.hasMore is true, split the window.
curl -sS -G "$FILMO_URL/api/v1/invoices" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "updatedFrom=2026-10-08T00:00:00.000Z" \
  --data-urlencode "updatedBefore=2026-10-09T00:00:00.000Z" \
  --data-urlencode "sort=updatedAt" \
  --data-urlencode "limit=500"

import { readRange, upperBound } from "./window.mjs";

const B = await upperBound();
const A = Date.parse("2025-01-01T00:00:00Z"); // first load: before your first invoice; later: the watermark

const all = await readRange("/invoices", A, B);

// The list has no status filter: split by status here. A credit note is read from /credit-notes;
// a row with isRectification set is kept: match it against the credit notes by number.
const rows = [...all.values()];
const validated = rows.filter((i) => i.status === "validated");
const voided = rows.filter((i) => i.status === "voided");
console.log(validated.length + " validated, " + voided.length + " voided; drafts are ignored");

from datetime import datetime, timezone

from window import read_range, upper_bound

B = upper_bound()
A = int(datetime(2025, 1, 1, tzinfo=timezone.utc).timestamp() * 1000)  # first load; later: the watermark

all_rows = read_range("/invoices", A, B)

# The list has no status filter: split by status here. A credit note is read from /credit-notes;
# a row with isRectification set is kept: match it against the credit notes by number.
rows = list(all_rows.values())
validated = [i for i in rows if i["status"] == "validated"]
voided = [i for i in rows if i["status"] == "voided"]
print(len(validated), "validated,", len(voided), "voided; drafts are ignored")

# The detail is the only place with the tax breakdown.
curl -sS "$FILMO_URL/api/v1/invoices/$INVOICE_ID" \
  -H "Authorization: Bearer $FILMO_API_KEY"

import { get } from "./filmo.mjs";

const cents = (amount) => Number(amount.replace(".", "")); // "1234.50" -> 123450

export async function readTaxes(invoiceId) {
  const { data: invoice, etag } = await get("/invoices/" + invoiceId);
  const breakdown = invoice.taxBreakdown; // null if Filmo has not calculated it
  if (!breakdown) return { invoice, etag, breakdown: null, matches: false };

  // The breakdown is the detail of the totals; check it before you post it.
  const tax = breakdown.reduce((sum, row) => sum + cents(row.amount), 0);
  const base = breakdown.reduce((sum, row) => sum + cents(row.baseAmount), 0);
  const matches = tax === cents(invoice.taxesPrice) && base === cents(invoice.netPrice);
  return { invoice, etag, breakdown, matches };
}

from filmo import get


def cents(amount):
    return int(amount.replace(".", ""))  # "1234.50" -> 123450


def read_taxes(invoice_id):
    body = get("/invoices/" + invoice_id)
    invoice, etag = body["data"], body["etag"]
    breakdown = invoice["taxBreakdown"]  # None if Filmo has not calculated it
    if not breakdown:
        return invoice, etag, None, False

    # The breakdown is the detail of the totals; check it before you post it.
    tax = sum(cents(row["amount"]) for row in breakdown)
    base = sum(cents(row["baseAmount"]) for row in breakdown)
    matches = tax == cents(invoice["taxesPrice"]) and base == cents(invoice["netPrice"])
    return invoice, etag, breakdown, matches

# What was invoiced, line by line, with the names frozen when the invoice was issued.
curl -sS -G "$FILMO_URL/api/v1/invoices/$INVOICE_ID/lines" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "limit=500"

import { get } from "./filmo.mjs";

export async function readInvoiceLines(invoiceId) {
  const lines = [];
  let cursor;
  do {
    const page = await get("/invoices/" + invoiceId + "/lines", { limit: 500, ...(cursor && { cursor }) });
    lines.push(...page.data);
    cursor = page.pagination.hasMore ? page.pagination.nextCursor : undefined;
  } while (cursor);
  return lines; // document order; a validated invoice does not change, so read it once
}

from filmo import get


def read_invoice_lines(invoice_id):
    lines, cursor = [], None
    while True:
        query = {"limit": 500}
        if cursor:
            query["cursor"] = cursor
        page = get("/invoices/" + invoice_id + "/lines", **query)
        lines += page["data"]
        if not page["pagination"]["hasMore"]:
            return lines  # document order; a validated invoice does not change, so read it once
        cursor = page["pagination"]["nextCursor"]

# Newest change first. Stop reading when updatedAt is older than what you already hold.
curl -sS -G "$FILMO_URL/api/v1/invoices/$INVOICE_ID/payments" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "sort=-updatedAt" \
  --data-urlencode "limit=500"

# Once a day: the invoices that can still receive a payment.
curl -sS -G "$FILMO_URL/api/v1/invoices" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "paymentStatuses=unpaid,partially_paid,overdue" \
  --data-urlencode "limit=500"

import { get } from "./filmo.mjs";

// The payments of one invoice changed since "since" (epoch ms), newest first, with an early stop.
export async function paymentsSince(invoiceId, since) {
  const found = new Map(); // deduplicate by id
  let cursor;
  for (;;) {
    const page = await get("/invoices/" + invoiceId + "/payments", {
      sort: "-updatedAt",
      limit: 500,
      ...(cursor && { cursor }),
    });
    for (const payment of page.data) {
      if (Date.parse(payment.updatedAt) < since) return found; // everything after is older
      found.set(payment.id, payment);
    }
    if (!page.pagination.hasMore) return found;
    cursor = page.pagination.nextCursor;
  }
}

// Which invoices to check: compare totalPaid and paymentStatus with what you stored.
// "since" is your last check of that invoice minus the safety margin; use 0 to read all of them.
export function needsPayments(invoice, stored) {
  return invoice.totalPaid !== stored?.totalPaid || invoice.paymentStatus !== stored?.paymentStatus;
}

from datetime import datetime

from filmo import get


def payments_since(invoice_id, since_ms):
    """The payments of one invoice changed since since_ms, newest first, with an early stop."""
    found, cursor = {}, None  # deduplicate by id
    while True:
        query = {"sort": "-updatedAt", "limit": 500}
        if cursor:
            query["cursor"] = cursor
        page = get("/invoices/" + invoice_id + "/payments", **query)
        for payment in page["data"]:
            changed = datetime.fromisoformat(payment["updatedAt"].replace("Z", "+00:00")).timestamp() * 1000
            if changed < since_ms:
                return found  # everything after is older
            found[payment["id"]] = payment
        if not page["pagination"]["hasMore"]:
            return found
        cursor = page["pagination"]["nextCursor"]


def needs_payments(invoice, stored):
    """Compare totalPaid and paymentStatus with what you stored; read the payments if they differ."""
    stored = stored or {}
    return invoice["totalPaid"] != stored.get("totalPaid") or invoice["paymentStatus"] != stored.get("paymentStatus")

# Credit notes have their own endpoints. The same windowed read, on updatedAt.
curl -sS -G "$FILMO_URL/api/v1/credit-notes" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "updatedFrom=2026-10-08T00:00:00.000Z" \
  --data-urlencode "updatedBefore=2026-10-09T00:00:00.000Z" \
  --data-urlencode "sort=updatedAt" \
  --data-urlencode "limit=500"

import { readRange, upperBound } from "./window.mjs";

const B = await upperBound();
const A = Date.parse("2025-01-01T00:00:00Z"); // first load; later: the watermark
const notes = await readRange("/credit-notes", A, B);
for (const note of notes.values()) {
  if (note.status !== "validated") continue; // draft: wait; voided: cancelled in Filmo, so reflect that in your books
  // invoiceId is the invoice it rectifies, or null.
  console.log(note.creditNoteNumber, note.issueDate, note.invoiceId, note.netPrice, note.taxesPrice, note.grossPrice);
}

from datetime import datetime, timezone

from window import read_range, upper_bound

B = upper_bound()
A = int(datetime(2025, 1, 1, tzinfo=timezone.utc).timestamp() * 1000)  # first load; later: the watermark
notes = read_range("/credit-notes", A, B)
for note in notes.values():
    if note["status"] != "validated":
        continue  # draft: wait; voided: cancelled in Filmo, so reflect that in your books
    # invoiceId is the invoice it rectifies, or None.
    print(note["creditNoteNumber"], note["issueDate"], note["invoiceId"], note["netPrice"], note["taxesPrice"], note["grossPrice"])

# originSystem is a lowercase slug you choose; originExternalId is the document id in your ERP.
curl -sS -X PUT "$FILMO_URL/api/v1/invoices/external/acme_erp/INV-2026-0001" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "invoiceNumber": "INV-2026-0001",
    "invoiceDate": "2026-10-08",
    "dueDate": "2026-11-07",
    "currency": "EUR",
    "contactTaxId": "B00000000",
    "lines": [
      { "description": "Camera package, 2 days", "quantity": "2", "unitPrice": "150.00", "taxRate": "21" },
      { "description": "Delivery", "quantity": "1", "unitPrice": "80.00", "taxRate": "21" }
    ],
    "subTotal": "380.00",
    "taxTotal": "79.80",
    "total": "459.80",
    "externalStatus": "issued"
  }'

import { randomUUID } from "node:crypto";
import { API } from "./filmo.mjs";

const originSystem = "acme_erp";
const originExternalId = "INV-2026-0001";

const res = await fetch(API + "/invoices/external/" + originSystem + "/" + encodeURIComponent(originExternalId), {
  method: "PUT",
  headers: {
    Authorization: ["Bearer", process.env.FILMO_API_KEY].join(" "),
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(), // reuse the same value if you retry this exact call
  },
  body: JSON.stringify({
    invoiceNumber: "INV-2026-0001",
    invoiceDate: "2026-10-08",
    dueDate: "2026-11-07",
    currency: "EUR",
    contactTaxId: "B00000000",
    lines: [
      { description: "Camera package, 2 days", quantity: "2", unitPrice: "150.00", taxRate: "21" },
      { description: "Delivery", quantity: "1", unitPrice: "80.00", taxRate: "21" },
    ],
    subTotal: "380.00",
    taxTotal: "79.80",
    total: "459.80",
    externalStatus: "issued",
  }),
});
const { data } = await res.json();
// 201 created the mirror, 200 updated it or found it identical. Keep data.id: it is the Filmo id.
console.log(res.status, data.id, data.status);

import uuid
from urllib.parse import quote

from filmo import API, session

origin_system = "acme_erp"
origin_external_id = "INV-2026-0001"

res = session.put(
    API + "/invoices/external/" + origin_system + "/" + quote(origin_external_id, safe=""),
    headers={"Idempotency-Key": str(uuid.uuid4())},  # reuse the same value if you retry this exact call
    json={
        "invoiceNumber": "INV-2026-0001",
        "invoiceDate": "2026-10-08",
        "dueDate": "2026-11-07",
        "currency": "EUR",
        "contactTaxId": "B00000000",
        "lines": [
            {"description": "Camera package, 2 days", "quantity": "2", "unitPrice": "150.00", "taxRate": "21"},
            {"description": "Delivery", "quantity": "1", "unitPrice": "80.00", "taxRate": "21"},
        ],
        "subTotal": "380.00",
        "taxTotal": "79.80",
        "total": "459.80",
        "externalStatus": "issued",
    },
)
res.raise_for_status()
data = res.json()["data"]
# 201 created the mirror, 200 updated it or found it identical. Keep data["id"]: it is the Filmo id.
print(res.status_code, data["id"], data["status"])