Flow API

Base: https://flow.eel.software/api/public/v1

The finance and operations app. Every POST that creates or records something requires an Idempotency-Key header, with one exception: the two webhook management routes at the bottom of this page. See the shared rules for pagination, errors and pace, once for all four apps.

Catalog and stock

GET /products is cursor-paginated and filters with q (name or SKU), active, or updated_since (ISO date). Each row carries its UPID, the id every other product route takes: sku, name, active, list_price, currency, tax and uom.

PATCH /products/{upid} edits name, list_price (decimal string, null clears it), tax_code (null clears it) or active. sku and uom are deliberately immutable through the API.

GET /products/{upid}/stock returns per-warehouse on_hand and available-to-sell (available = on_hand minus active reservations), optionally filtered to one warehouse. It is eventually consistent with checkout.

GET /warehouses lists all active warehouses (CENTRAL and STORE) with the warehouse_id that sales and stock reads take; STORE rows also carry the partner_id of the partner that represents that store.

GET /financial-accounts lists active CASH / BANK / PROCESSOR accounts with their currency, identity only, no balances. It is the source of the financial_account_id that a sale or a payment takes.

Partners

There is no dedicated read scope for partners: reading and searching both ride flow:partners:write, the same asymmetry the scopes catalogue notes for Wrap's notes and follow-ups.

GET /partners?q= searches by name (contains) or tax id prefix. POST /partners upserts a partner (customer/supplier) by tax id (tax_id_type + tax_id_number) or email: it returns the existing record when one matches, so it also doubles as a lookup by NIT. NIT verification digits are validated, or computed when omitted.

Sales

POST /sales is the one-call sale: it draws stock from a warehouse, invoices the customer, and optionally records the payment.

GET /sales/{id} returns the invoice number and status, the outbound reference, and dian_status (the status of DIAN e-invoicing).

Invoices and bills

GET /invoices browses AR documents (customer invoices) newest-issued first, cursor-paginated: the "revenue this month" view. GET /bills/list is the same shape for AP documents (supplier bills), plus supplier_number and PENDING_APPROVAL as an extra status. flow_list_open_items (below) only shows the unpaid subset of either.

Both filter by status, partner_id, or an issued_from/issued_to window (ISO dates), and both return the formatted number (null while DRAFT), partner_id/name, string money and the retention-aware remaining.

POST /bills creates a DRAFT purchase bill; a human posts it inside Flow. Reference the supplier by partner_id or pass an inline partner object (upserted by tax id or email). A duplicate (partner, supplier_number) pair is rejected with conflict and the existing bill_id in the error details.

Payments

Both record a payment (a receipt against an invoice, or a disbursement against a bill), with the same rules: amount is a decimal string in the document's own currency, and the financial_account_id must match that currency. Rejected when the document is DRAFT/VOID/already PAID, the amount exceeds what remains, or the fiscal month is closed.

A payment against a bill at or above the workspace's approval threshold goes through only when the caller is a workspace administrator. Both routes return the payment plus the document's post-payment remaining and status.

Open items

Open (unpaid) documents with their remaining balance: side=AP for supplier bills owed, side=AR for customer invoices owed to us. Filter by partner_nit or an as_of date. This is the route behind "what do we owe X", "who owes us", and cartera questions generally.

Webhooks

These two POST routes are the exception to the idempotency rule above: POST /webhooks and POST /webhook-deliveries/{id}/redeliver neither require nor look at Idempotency-Key.

POST /webhooks takes url (up to 2000 chars) and events (at least one of invoice.posted, invoice.paid, bill.posted, payment.created, stock.changed). The response includes the signing secret once, at create, never again. GET /webhook-deliveries?webhook= lists recent deliveries, optionally filtered to one webhook; POST /webhook-deliveries/{id}/redeliver re-queues one for the next drain.

Delivery is at-least-once: a webhook consumer must be idempotent on its own side, keying off the event body, not off delivery count.