---
title: "BizCollect: costruire uno strumento di dati business API-First"
description: "BizCollect raccoglie e struttura dati business prima tramite una API pulita, l'UI viene dopo. Perche l'API-First ha cambiato il mio modo di costruire prodotti."
type: "build"
locale: "it"
category: "saas"
canonical: "https://agenticschool.dev/it/progetti/bizcollect"
dateModified: "2026-06-12"
---

# BizCollect: costruire uno strumento di dati business API-First

- Category: saas
- Status: internal
- Stack: TypeScript, Node.js, REST API, OpenAPI, Convex, Claude Code
- Updated: 2026-06-12
- Keywords: API-first, business data, OpenAPI, agent-first, data collection
- Canonical URL: https://agenticschool.dev/it/progetti/bizcollect
- Locale: it

> Il progetto che mi ha insegnato che l'IA deve amare la tua API, non la tua UI.

BizCollect raccoglie e struttura dati business prima tramite una API pulita, l'UI viene dopo. Perche l'API-First ha cambiato il mio modo di costruire prodotti.

## Il problema che volevo risolvere

Avevo bisogno di un modo affidabile di raccogliere, pulire e strutturare dati business provenienti da molte fonti caotiche, poi di trasmetterli ad altri strumenti in una forma prevedibile. Il mio primo riflesso, come la maggior parte delle persone, e stato costruire un bel dashboard. Ho cominciato dagli schermi. E l'errore che mi ha insegnato di piu.

## Perche sono passato all'API-First

Lungo la strada, ho realizzato che ogni consumatore di questi dati era un programma, non un umano che clicca su pulsanti: un'automazione, uno scraper, un altro agente, un futuro io che scrive uno script a mezzanotte. L'UI era un sottile aggiunta a posteriori. Ho quindi ricostruito tutto attorno a una API documentata, con il dashboard come semplice client di questa API piuttosto che come il prodotto stesso.

- Ogni capacita e un endpoint con un contratto stabile, non un pulsante sepolto in uno schermo.
- L'API viene fornita con uno spec OpenAPI, perche un agente possa scoprirla e usarla senza che io spieghi qualsiasi cosa.
- Le risposte sono JSON prevedibile, sempre della stessa forma, perche i consumatori non debbano mai indovinare.

## Cosa e cambiato quando l'API e passata prima

Dall'istante in cui l'API e diventata il prodotto, tutto cio che seguiva e diventato piu semplice. Le automazioni si collegavano senza scrapare schermi. I test sono diventati banali, perche testavo endpoint, non percorsi di click. E quando ho lanciato un agente IA sullo spec OpenAPI, ha saputo usare BizCollect correttamente al primo colpo, perche il contratto gli diceva esattamente cosa inviare e cosa ricevere. E stato il clic: uno strumento che un'IA puo capire e pilotare senza che gli si tenga la mano vale molto di piu nel 2026 di uno strumento in cui solo un umano puo navigare.

## Cosa farei diversamente

Scriverei lo spec OpenAPI prima di scrivere il minimo endpoint, e lo tratterei come un documento di progettazione. Versionerei anche l'API dal primo giorno, invece di aggiungere il versionamento piu tardi. Il dashboard, lo si puo sempre rigenerare; un contratto di API rotto rompe tutti quelli che dipendono da te, inclusi agenti che non hai mai incontrato.

## Lessons learned

- Progetta l'API prima dell'UI. L'API e il prodotto; l'UI e solo uno dei suoi client.
- Pubblica un contratto leggibile dalla macchina (OpenAPI), perche gli agenti usino il tuo strumento senza che un umano traduca la doc.
- Risposte prevedibili e identiche battono le risposte astute. I consumatori non dovrebbero mai dover gestire sorprese.
- In un mondo Agent-First, "l'IA puo pilotarlo senza sorveglianza" e una vera feature, non un bonus.