Sincronizar contactos desde tu CRM

// filmo-client.mjs: one place for the base URL, the key and the 429 backoff.
const BASE = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";

export async function filmo(method, path, { query, body, idempotencyKey, ifMatch, retries = 5 } = {}) {
  const url = new URL(path, BASE);
  for (const [name, value] of Object.entries(query ?? {})) {
    if (value != null) url.searchParams.set(name, String(value));
  }
  const headers = { Authorization: `Bearer ${process.env.FILMO_API_KEY}` };
  if (body) headers["Content-Type"] = "application/json";
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
  if (ifMatch) headers["If-Match"] = ifMatch;

  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, { method, headers, body: body ? JSON.stringify(body) : undefined });
    if (res.status === 429 && attempt < retries) {
      // Wait what the server says, plus a little jitter, then repeat the same request.
      const seconds = Number(res.headers.get("Retry-After") ?? 1);
      await new Promise((resolve) => setTimeout(resolve, (seconds + Math.random()) * 1000));
      continue;
    }
    const isJson = (res.headers.get("Content-Type") ?? "").includes("json");
    return { status: res.status, ok: res.ok, headers: res.headers, body: isJson ? await res.json() : null };
  }
}

# filmo_client.py: one place for the base URL, the key and the 429 backoff.
import os
import random
import time

import requests

BASE = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")


def filmo(method, path, params=None, body=None, idempotency_key=None, if_match=None, retries=5):
    headers = {"Authorization": f"Bearer {os.environ['FILMO_API_KEY']}"}
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    if if_match:
        headers["If-Match"] = if_match
    for attempt in range(retries + 1):
        res = requests.request(
            method, BASE + path, params=params, json=body, headers=headers, timeout=30
        )
        if res.status_code == 429 and attempt < retries:
            # Wait what the server says, plus a little jitter, then repeat the same request.
            time.sleep(float(res.headers.get("Retry-After", 1)) + random.random())
            continue
        break
    is_json = "json" in res.headers.get("Content-Type", "")
    return res.status_code, (res.json() if is_json else None), res.headers

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS "$BASE/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY"

import { filmo } from "./filmo-client.mjs";

const res = await filmo("GET", "/api/v1/account");
if (!res.ok) throw new Error("getAccount " + res.status + " " + res.body?.code);

const { timezone, currency, addons, trial, apiKey } = res.body.data;
console.log({ timezone, currency, addons, trial: trial.active, scopes: apiKey.scopes });

from filmo_client import filmo

status, body, _ = filmo("GET", "/api/v1/account")
if status != 200:
    raise RuntimeError(f"getAccount {status} {(body or {}).get('code')}")

account = body["data"]
print(account["timezone"], account["currency"], account["addons"],
      account["trial"]["active"], account["apiKey"]["scopes"])

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS -G "$BASE/api/v1/contacts" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "email=ana@example.com" \
  --data-urlencode "limit=500"

import { filmo } from "./filmo-client.mjs";

const sameEmail = (contact, email) =>
  contact.emails.some((e) => e.email.toLowerCase() === email.toLowerCase());

// The filter's matching rules are not specified, so compare the addresses yourself.
export async function findByEmail(email) {
  const res = await filmo("GET", "/api/v1/contacts", { query: { email, limit: 500 } });
  if (!res.ok) throw new Error("listContacts " + res.status + " " + res.body?.requestId);
  return res.body.data.filter((contact) => sameEmail(contact, email));
}

from filmo_client import filmo


def same_email(contact, email):
    return any(e["email"].lower() == email.lower() for e in contact["emails"])


# The filter's matching rules are not specified, so compare the addresses yourself.
def find_by_email(email):
    status, body, _ = filmo("GET", "/api/v1/contacts", params={"email": email, "limit": 500})
    if status != 200:
        raise RuntimeError(f"listContacts {status} {(body or {}).get('requestId')}")
    return [c for c in body["data"] if same_email(c, email)]

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS -X POST "$BASE/api/v1/contacts/lookup" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "references": ["crm-c-1042", "crm-c-1043", "crm-c-1044"]
}
JSON

import { filmo } from "./filmo-client.mjs";

// crmIds: 1 to 200 ids of your CRM. The contact number we write is "crm-" + id.
export async function lookup(crmIds) {
  const references = crmIds.map((id) => "crm-" + id);
  const res = await filmo("POST", "/api/v1/contacts/lookup", { body: { references } });
  if (!res.ok) throw new Error("lookupContacts " + res.status + " " + res.body?.requestId);

  const { contacts, notFound } = res.body.data;
  // The answer does not pair references with contacts: pair them by contactNumber yourself.
  // A contact number is not unique, so several contacts can come back for one reference.
  return references.map((reference) => {
    const matches = contacts.filter((c) => c.contactNumber === reference);
    return {
      reference,
      filmoId: matches.length === 1 ? matches[0].id : null,
      conflict: matches.length > 1 ? matches.map((c) => c.id) : null, // for a human to resolve
      noMatch: notFound.includes(reference),
    };
  });
}

from filmo_client import filmo


# crm_ids: 1 to 200 ids of your CRM. The contact number we write is "crm-" + id.
def lookup(crm_ids):
    references = ["crm-" + i for i in crm_ids]
    status, body, _ = filmo("POST", "/api/v1/contacts/lookup", body={"references": references})
    if status != 200:
        raise RuntimeError(f"lookupContacts {status} {(body or {}).get('requestId')}")

    data = body["data"]
    # The answer does not pair references with contacts: pair them by contactNumber yourself.
    # A contact number is not unique, so several contacts can come back for one reference.
    results = []
    for ref in references:
        matches = [c["id"] for c in data["contacts"] if c["contactNumber"] == ref]
        results.append({
            "reference": ref,
            "filmo_id": matches[0] if len(matches) == 1 else None,
            "conflict": matches if len(matches) > 1 else None,  # for a human to resolve
            "no_match": ref in data["notFound"],
        })
    return results

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS -X POST "$BASE/api/v1/contacts" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-contact-create-c-1042" \
  --data @- <<'JSON'
{
  "name": "Ana Example",
  "contactType": "person",
  "role": "client",
  "email": "ana@example.com",
  "phone": "+34 600 000 000",
  "contactNumber": "crm-c-1042"
}
JSON

import { createHash } from "node:crypto";
import { filmo } from "./filmo-client.mjs";

// A stand-in for your database: CRM id -> { filmoId, hash, updatedAt }.
export const links = new Map();

const primary = (list, key) => (list.find((x) => x.isPrimary) ?? list[0])?.[key] ?? "";

// The fingerprint of a Filmo contact, from what the API returned (never from what you sent).
export const hashOf = (dto) =>
  createHash("sha256")
    .update(JSON.stringify([
      dto.name,
      dto.contactType,
      primary(dto.emails, "email").toLowerCase(),
      primary(dto.phoneNumbers, "number"),
      dto.contactNumber ?? "",
    ]))
    .digest("hex");

export const link = (crmId, dto) =>
  links.set(crmId, { filmoId: dto.id, hash: hashOf(dto), updatedAt: dto.updatedAt });

export async function createInFilmo(person) {
  const res = await filmo("POST", "/api/v1/contacts", {
    idempotencyKey: "crm-contact-create-" + person.id,
    body: {
      name: person.name,
      contactType: person.type, // "person" or "company"
      role: "client",
      email: person.email,
      phone: person.phone,
      contactNumber: "crm-" + person.id,
    },
  });
  if (res.ok) link(person.id, res.body.data);
  return res; // 400 and 422 are for the caller to route, see "Handle errors"
}

import hashlib
import json

from filmo_client import filmo

# A stand-in for your database: CRM id -> {"filmo_id", "hash", "updated_at"}.
links = {}


def primary(items, key):
    chosen = next((x for x in items if x["isPrimary"]), items[0] if items else None)
    return chosen[key] if chosen else ""


# The fingerprint of a Filmo contact, from what the API returned (never from what you sent).
def hash_of(dto):
    fields = [
        dto["name"],
        dto["contactType"],
        primary(dto["emails"], "email").lower(),
        primary(dto["phoneNumbers"], "number"),
        dto["contactNumber"] or "",
    ]
    return hashlib.sha256(json.dumps(fields).encode()).hexdigest()


def link(crm_id, dto):
    links[crm_id] = {"filmo_id": dto["id"], "hash": hash_of(dto), "updated_at": dto["updatedAt"]}


def create_in_filmo(person):
    body = {
        "name": person["name"],
        "contactType": person["type"],  # "person" or "company"
        "role": "client",
        "email": person["email"],
        "phone": person.get("phone"),
        "contactNumber": "crm-" + person["id"],
    }
    body = {k: v for k, v in body.items() if v is not None}
    status, payload, _ = filmo(
        "POST", "/api/v1/contacts", body=body,
        idempotency_key="crm-contact-create-" + person["id"],
    )
    if status == 201:
        link(person["id"], payload["data"])
    return status, payload  # 400 and 422 are for the caller to route, see "Handle errors"

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
# 1. Read the contact: the response carries its ETag header and the current lists.
curl -sS -i "$BASE/api/v1/contacts/$CONTACT_ID" \
  -H "Authorization: Bearer $FILMO_API_KEY"

# 2. Write only what changed, conditional on the ETag header you just read (set ETAG to its value).
curl -sS -X PATCH "$BASE/api/v1/contacts/$CONTACT_ID" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" \
  -H "Idempotency-Key: crm-contact-update-c-1042-v7" \
  --data @- <<'JSON'
{
  "name": "Ana Example Rentals"
}
JSON
# Add "contactNumber": "crm-c-1042" only when the contact has none yet (see the text).

import { createHash } from "node:crypto";
import { filmo } from "./filmo-client.mjs";
import { link } from "./create.mjs";

// person.version: the version or updated-at of the CRM record. The key also carries a hash of
// the body: a retry after a timeout whose body changed in the meantime gets a new key, and the same key with another body is a 422.
export async function updateInFilmo(person, filmoId) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const current = await filmo("GET", "/api/v1/contacts/" + filmoId);
    if (current.status === 404) return current; // deleted or outside your tenancy (an archived contact answers 200)
    const dto = current.body.data;

    const patch = { name: person.name };
    // Never overwrite a contact number: the team may have set its own. Write ours only when empty.
    if (!dto.contactNumber) patch.contactNumber = "crm-" + person.id;
    if (!dto.emails.some((e) => e.email.toLowerCase() === person.email.toLowerCase())) {
      // emails REPLACES the whole list: keep the addresses people added in Filmo.
      patch.emails = [
        { email: person.email, isPrimary: true },
        ...dto.emails.map((e) => ({ email: e.email, label: e.label ?? undefined, isPrimary: false })),
      ];
    }

    const res = await filmo("PATCH", "/api/v1/contacts/" + filmoId, {
      body: patch,
      ifMatch: current.headers.get("ETag"),
      idempotencyKey:
        "crm-contact-update-" + person.id + "-v" + person.version + "-" +
        createHash("sha256").update(JSON.stringify(patch)).digest("hex").slice(0, 12),
    });
    if (res.status === 412) continue; // it changed after you read it: read again
    if (res.ok) link(person.id, res.body.data);
    return res;
  }
  throw new Error("contact " + filmoId + " keeps changing; try again on the next pass");
}

import hashlib
import json

from create import link
from filmo_client import filmo


# person["version"]: the version or updated-at of the CRM record. The key also carries a hash of
# the body: a retry after a timeout whose body changed in the meantime gets a new key, and the same key with another body is a 422.
def update_in_filmo(person, filmo_id):
    for _ in range(3):
        status, payload, headers = filmo("GET", "/api/v1/contacts/" + filmo_id)
        if status == 404:
            return status, payload  # deleted or outside your tenancy (an archived contact answers 200)
        dto = payload["data"]

        patch = {"name": person["name"]}
        # Never overwrite a contact number: the team may have set its own. Write ours only when empty.
        if not dto["contactNumber"]:
            patch["contactNumber"] = "crm-" + person["id"]
        if not any(e["email"].lower() == person["email"].lower() for e in dto["emails"]):
            # emails REPLACES the whole list: keep the addresses people added in Filmo.
            patch["emails"] = [{"email": person["email"], "isPrimary": True}] + [
                {k: v for k, v in
                 {"email": e["email"], "label": e["label"], "isPrimary": False}.items()
                 if v is not None}
                for e in dto["emails"]
            ]

        status, payload, _ = filmo(
            "PATCH", "/api/v1/contacts/" + filmo_id, body=patch,
            if_match=headers["ETag"],
            idempotency_key="crm-contact-update-" + person["id"] + "-v" + str(person["version"]) + "-"
            + hashlib.sha256(json.dumps(patch, sort_keys=True).encode()).hexdigest()[:12],
        )
        if status == 412:
            continue  # it changed after you read it: read again
        if status == 200:
            link(person["id"], payload["data"])
        return status, payload
    raise RuntimeError(f"contact {filmo_id} keeps changing; try again on the next pass")

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
# One window, one page: [A, B) with A and B as UTC instants.
curl -sS -G "$BASE/api/v1/contacts" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "updatedFrom=2026-10-09T08:00:00Z" \
  --data-urlencode "updatedBefore=2026-10-09T08:15:00Z" \
  --data-urlencode "sort=updatedAt" \
  --data-urlencode "limit=500"

import { filmo } from "./filmo-client.mjs";
import { hashOf, links } from "./create.mjs";

// Contacts changed in Filmo inside [from, before), minus the echoes of your own writes.
export async function changedContacts(from, before) {
  const res = await filmo("GET", "/api/v1/contacts", {
    query: { updatedFrom: from, updatedBefore: before, sort: "updatedAt", limit: 500 },
  });
  if (!res.ok) throw new Error("listContacts " + res.status + " " + res.body?.requestId);
  if (res.body.pagination.hasMore) throw new Error("window too large: split it, do not follow the cursor");

  const crmIdOf = new Map([...links].map(([crmId, l]) => [l.filmoId, crmId]));
  const changes = [];
  for (const dto of res.body.data) {
    const crmId = crmIdOf.get(dto.id) ?? null;
    if (crmId && hashOf(dto) === links.get(crmId).hash) continue; // your own write coming back
    changes.push({ crmId, dto });
    // After you apply a change to the CRM, store its fingerprint so the CRM does not send it back:
    // links.get(crmId).hash = hashOf(dto);
  }
  return changes;
}

from create import hash_of, links
from filmo_client import filmo


# Contacts changed in Filmo inside [from, before), minus the echoes of your own writes.
def changed_contacts(start, before):
    status, body, _ = filmo("GET", "/api/v1/contacts", params={
        "updatedFrom": start, "updatedBefore": before, "sort": "updatedAt", "limit": 500,
    })
    if status != 200:
        raise RuntimeError(f"listContacts {status} {(body or {}).get('requestId')}")
    if body["pagination"]["hasMore"]:
        raise RuntimeError("window too large: split it, do not follow the cursor")

    crm_id_of = {link["filmo_id"]: crm_id for crm_id, link in links.items()}
    changes = []
    for dto in body["data"]:
        crm_id = crm_id_of.get(dto["id"])
        if crm_id and hash_of(dto) == links[crm_id]["hash"]:
            continue  # your own write coming back
        changes.append({"crm_id": crm_id, "dto": dto})
        # After you apply a change to the CRM, store its fingerprint so the CRM does not send it back:
        # links[crm_id]["hash"] = hash_of(dto)
    return changes

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"
curl -sS -G "$BASE/api/v1/crm/opportunities" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "status=all" \
  --data-urlencode "sort=-updatedAt" \
  --data-urlencode "limit=500"

# The opportunities of one mapped contact:
curl -sS -G "$BASE/api/v1/crm/opportunities" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "status=all" \
  --data-urlencode "contactId=$CONTACT_ID"

import { filmo } from "./filmo-client.mjs";

// Opportunities updated since a watermark: newest first, stop when you pass it, dedupe by id.
export async function changedOpportunities(since) {
  const found = new Map();
  let cursor;
  for (;;) {
    const res = await filmo("GET", "/api/v1/crm/opportunities", {
      query: { status: "all", sort: "-updatedAt", limit: 500, cursor },
    });
    if (res.status === 402) return []; // no CRM add-on on this account
    if (!res.ok) throw new Error("listOpportunities " + res.status + " " + res.body?.requestId);

    const page = res.body.data;
    for (const o of page) {
      if (Date.parse(o.updatedAt) >= Date.parse(since)) found.set(o.opportunityId, o);
    }
    const last = page.at(-1);
    if (!res.body.pagination.hasMore || !last || Date.parse(last.updatedAt) < Date.parse(since)) {
      return [...found.values()];
    }
    cursor = res.body.pagination.nextCursor;
  }
}

from datetime import datetime

from filmo_client import filmo


def parse(instant):
    return datetime.fromisoformat(instant.replace("Z", "+00:00"))


# Opportunities updated since a watermark: newest first, stop when you pass it, dedupe by id.
def changed_opportunities(since):
    found, cursor = {}, None
    while True:
        status, body, _ = filmo("GET", "/api/v1/crm/opportunities", params={
            "status": "all", "sort": "-updatedAt", "limit": 500, "cursor": cursor,
        })
        if status == 402:
            return []  # no CRM add-on on this account
        if status != 200:
            raise RuntimeError(f"listOpportunities {status} {(body or {}).get('requestId')}")

        page = body["data"]
        for o in page:
            if parse(o["updatedAt"]) >= parse(since):
                found[o["opportunityId"]] = o
        if not body["pagination"]["hasMore"] or not page or parse(page[-1]["updatedAt"]) < parse(since):
            return list(found.values())
        cursor = body["pagination"]["nextCursor"]