Classify and Connect Bank Transactions to Invoices and Receipts

const organizationId = "your_org_id";
const token = "YOUR_TOKEN_HERE";

fetch(
  `https://api.enlivy.com/organizations/${organizationId}/bank-transaction-cost-types?page=1&limit=50`,
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json"
    }
  }
);

const organizationId = "your_org_id";
const token = "YOUR_TOKEN_HERE";

fetch(`https://api.enlivy.com/organizations/${organizationId}/bank-transaction-cost-types`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    title_lang_map: { en: "Client Payment", ro: "Încasare client" }, // per-locale map

    // does a transaction of this type have to be linked to a business entity?
    connection_required: true,

    // which entity types it may be connected to (required when connection_required = true)
    // options: invoice | receipt | payslip | bank_transaction | user
    connection_types: ["invoice", "receipt"],

    // optional: parent cost type for a nested / hierarchical category
    organization_bank_transaction_cost_type_id: null
  })
});

const organizationId = "your_org_id";
const token = "YOUR_TOKEN_HERE";

fetch(
  `https://api.enlivy.com/organizations/${organizationId}/bank-transactions?page=1&limit=20` +
    // state: backlog | classified | connected | connected_partially | danger | trashed
    `&state=backlog&direction=inbound` +
    // find transactions connected to a specific entity, send BOTH params together:
    // `&connection_entity_type=invoice&connection_entity_id=invoice_id` +
    // free-text search with q=... (min 3 chars) instead of ids
    `&include=cost_type,connection_entities,bank_account`,
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json"
    }
  }
);

const organizationId = "your_org_id";
const transactionId = "your_transaction_id";
const token = "YOUR_TOKEN_HERE";

fetch(
  `https://api.enlivy.com/organizations/${organizationId}/bank-transactions/${transactionId}` +
    // includes: organization, bank_account, cost_type, connection_entities, deleted_by_user, tag_ids
    `?include=cost_type,connection_entities,bank_account`,
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json"
    }
  }
);

const organizationId = "your_org_id";
const token = "YOUR_TOKEN_HERE";

fetch(`https://api.enlivy.com/organizations/${organizationId}/bank-transactions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    hash: "unique-dedupe-key",       // required; unique within a bank account (import de-dup key)
    title: "Incoming transfer from Acme Studio",
    amount: 1200.00,                 // money: signed decimal in MAJOR units (not cents)
                                     // direction is DERIVED from the sign (positive = inbound, negative = outbound)
    currency: "EUR",
    organization_bank_account_id: "bank_account_id",
    sender_label: "ACME STUDIO SRL", // free-text counterpart name from the bank feed
    note: "Invoice #2026-0142 settlement"

    // state is managed by classification (defaults to "backlog"), no need to set it.
    // optionally classify inline with organization_bank_transaction_cost_type_id + connection_entities (see below).
  })
});

const organizationId = "your_org_id";
const transactionId = "your_transaction_id";
const token = "YOUR_TOKEN_HERE";

fetch(`https://api.enlivy.com/organizations/${organizationId}/bank-transactions/${transactionId}`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    // 1. Classify, assign a cost type. Moves state: backlog -> classified.
    organization_bank_transaction_cost_type_id: "cost_type_id",

    // 2. Reconcile, link the transaction to what it pays for.
    //    connection_entity_type must be one of the cost type's allowed connection_types.
    //    The array is an UPSERT:
    //        { connection_entity_type, connection_entity_id, amount }  -> create a link
    //        { id }                                                    -> keep an existing link
    //        { id, _deleted: true }                                    -> remove a link
    //    (omitting an existing link does NOT delete it)
    //    Amounts covering the full transaction -> "connected"; partial -> "connected_partially".
    connection_entities: [
      { connection_entity_type: "invoice", connection_entity_id: "invoice_id", amount: 1000.00 },
      { connection_entity_type: "receipt", connection_entity_id: "receipt_id", amount: 200.00 }
    ]
  })
});

const organizationId = "your_org_id";
const token = "YOUR_TOKEN_HERE";

fetch(
  `https://api.enlivy.com/organizations/${organizationId}/bank-transactions/analytics/summary` +
    // analyticsType: summary | history_monthly
    `?start_date=2026-01-01&end_date=2026-12-31` +
    `&direction=outbound&entity_state=connected&convert_to_currency=EUR`,
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json"
    }
  }
);

const organizationId = "your_org_id";
const transactionId = "your_transaction_id";
const token = "YOUR_TOKEN_HERE";

// soft delete, restore via POST /bank-transactions/restore/{transactionId}
fetch(`https://api.enlivy.com/organizations/${organizationId}/bank-transactions/${transactionId}`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  }
});