# ferreteros.app — developers

> Intelligence for inventory and buying in independent hardware stores in Latin America.
> We are not an ERP. The POS remains the system of record.

Page: https://web.ferreteros.app/developers
How data is sent: https://web.ferreteros.app/developers#spec
Talk to us: https://web.ferreteros.app/developers#partner

## Role

The POS (or an agent) sends stock and sales.
ferreteros.app answers what is stuck, what to order, and where capital sits.

## What you can ask (contract v0)

- Enviar existencias (`send_inventory`): Una foto del stock: código, cantidad, costo, precio y fecha.
- Enviar ventas (`send_sales`): Lo que se vendió, por producto y por día (o el movimiento suelto).
- Salud del inventario (`stock_health`): Qué está sano, qué apura y qué lleva demasiado tiempo en el estante.
- Stock que no se mueve (`ghost_stock`): Piezas que el sistema dice que hay, pero no rotan.
- Días de cobertura (`days_of_cover`): Cuántos días te dura cada producto o categoría al ritmo actual.
- Capital por categoría (`capital_by_category`): Dónde está el dinero parado, agrupado como lo ve el negocio.
- Borrador de pedido (`purchase_draft`): Una lista sugerida de compra, a partir de la demanda y del stock real.

These already run on Excel/CSV and on the Ferrisur POS connection (in beta).
Outside keys are by invitation. There is no public store to buy queries.

## How data is identified

workspace + upload_id + as_of.
Planned auth: one API key per workspace.

Example payload (replace YYYY-MM-DD with the visit date):
{
  "workspace_id": "ws_demo",
  "upload_id": "YYYY-MM-DD_sync_01",
  "as_of": "YYYY-MM-DD",
  "source": "pos",
  "items": [
    {
      "sku": "TOR-001",
      "name": "Tornillo hex 1/4",
      "qty": 120,
      "cost": 0.12,
      "price": 0.25,
      "category": "Fijación"
    }
  ]
}

Example reply fragment:
{
  "upload_id": "YYYY-MM-DD_sync_01",
  "flags": [{ "sku": "TOR-001", "ghost_stock_candidate": false }],
  "coverage_days": 18,
  "capital_tied": 14.4
}

## Today

- Ferrisur POS — in beta; sends sales and stock.
- Excel / CSV — in production for any POS that can export.
- Other POS talks are open; we do not name brands until a connection exists or the partner says so.
- Files from SICAR, Siigo or Tango are an export format, not a native API.

## Not yet

One API per ERP brand, writing stock back into the POS (except an explicit count/audit), a public test environment, or selling query packs.

## Contact

Use the form on https://web.ferreteros.app/developers#partner — not the store-owner waitlist.