Collega Tiny Ant ai tuoi strumenti
API REST, server MCP e webhook
Usa l'API REST per lavorare con trattative, contatti, compiti, proposte e dati sui visitatori del sito. Il server MCP mette a disposizione un insieme di queste azioni agli assistenti compatibili. Una chiave API può sia leggere sia modificare i dati dello spazio di lavoro, quindi collega solo strumenti di cui ti fidi.
Autenticazione
Ogni richiesta include una chiave API dello spazio di lavoro nell'header Authorization:
Authorization: Bearer ta_live_...Gli amministratori dello spazio di lavoro creano le chiavi nella pagina Impostazioni dell'app (sezione API e MCP). Una chiave viene mostrata una sola volta al momento della creazione e può essere revocata in qualsiasi momento. Se chi l'ha creata passa al ruolo di membro, le sue chiavi vengono revocate in modo permanente; se viene rimosso, le sue chiavi vengono invalidate. Promuoverlo di nuovo ad amministratore non ripristina le vecchie chiavi. Le chiavi non possono essere usate mentre lo spazio di lavoro è sospeso. La chiave agisce a nome dell'amministratore che l'ha creata: note, compiti ed eventi sono attribuiti a quella persona e tutto ciò che la chiave crea è visibile all'intero spazio di lavoro. L'API e il server MCP sono inclusi nei piani Pro e Team. Crea e gestisci le chiavi in Impostazioni → API e MCP.
Le richieste senza una chiave valida ricevono 401. Uno spazio di lavoro con il piano Free riceve 403.
URL di base
https://app.tinyant.io/api/v1La maggior parte dei corpi delle richieste e delle risposte usa il formato JSON (UTF-8). Il caricamento delle proposte usa dati multipart form, come indicato di seguito. Gli ID hanno il formato de_, co_, pe_, ta_ e no_ seguiti da 12 caratteri; gli ID delle proposte sono composti da 12 caratteri senza prefisso. I timestamp sono espressi in millisecondi Unix. Gli endpoint riportati qui sotto descrivono l'interfaccia di integrazione pubblicata. Usa le richieste di rete dell'app come esempi laddove il payload completo non sia documentato in questa pagina.
Endpoint
| Metodo | Percorso | Cosa fa |
|---|---|---|
| GET POST PUT DELETE | /automations, /automations/:id | CRM Advanced: regole di amministrazione e ultime 100 esecuzioni accessibili. POST/PUT richiede name, definition, confirmation ottenuta dall'anteprima, revision (0 per le nuove regole) e mode off|simulate|live. Si parte con simulate; la modalità live richiede una simulazione riuscita della versione invariata. Le regole create via API restano vincolate all'amministratore e alla chiave originali. Le azioni sulla titolarità sono disponibili solo nell'app. DELETE archivia la regola e annulla le esecuzioni in sospeso. |
| POST | /automations/preview | Convalida {definition}: version:1; trigger deal_created|stage_changed|stalled|proposal_opened; pipeline_id, stage_id e owner_id facoltativi; stalled con after_days 1..90. Una sola azione: create_task {title,delay_days:0..90,assignee_id}, set_field {field:expected_close,value:YYYY-MM-DD} oppure notify {assignee_id}. L'assegnatario è l'ID di un membro attuale o deal_owner. Restituisce confirmation e al massimo 20 esempi corrispondenti, senza applicare modifiche. |
| POST | /automations/:id/simulate, /automations/:id/stop, /automations/:id/cancel | Mette in coda una simulazione {deal_id}, ferma una regola {} o annulla un'esecuzione in sospeso {run_id}. L'esecuzione in background ricontrolla le autorizzazioni attuali. Modifiche e ricevute vengono salvate insieme; i nuovi tentativi non ripetono mai un'azione già confermata. Non viene inviata alcuna email all'esterno. |
| GET | /automation-notifications | Posta in arrivo interna dell'utente attuale, filtrata in base all'accesso attuale alle trattative. Non invia email né notifiche push del browser. |
| GET PUT | /dashboard | Dashboard personale: GET restituisce il catalogo dei riquadri, la configurazione salvata e le metriche in tempo reale filtrate in base agli accessi; PUT {revision,config} salva solo il layout e i filtri dell'utente attuale. Configurazione versione 1: days 7/30/90, owner all/mine/unassigned, pipeline_id e currency annullabili, e riquadri univoci {id,size} dal catalogo con larghezze 4/6/8/12. Previsioni ed esiti richiedono l'accesso da amministratore Advanced; Visitors richiede un piano a pagamento. I dati non vengono mai salvati insieme ai layout. Le chiavi API mantengono il proprio ambito di accesso ai record. |
| GET | /bulk | Membri attuali, impostazioni delle attività e i tuoi 20 lotti di operazioni in blocco più recenti. L'anteprima e l'avanzamento delle operazioni in blocco sono riservati a chi li ha creati e alla stessa chiave API. |
| POST | /bulk/preview | Genera un'anteprima per un numero da 1 a 100 di aziende, persone o trattative specificate usando entity, ids e action: activity, più i campi dell'attività come nella creazione di un compito. Restituisce i nomi selezionati, la convalida per ciascun record e confirmation. La creazione delle attività usa gli attuali diritti di modifica e gli stessi controlli di pianificazione, tipo Advanced e capacità previsti per le singole attività. I cambi di responsabile sono disponibili solo nell'app dello spazio di lavoro e riservati agli amministratori, in linea con la gestione degli accessi ai record. |
| GET POST | /bulk/:id | Legge un'anteprima o i risultati oppure invia tramite POST la relativa confirmation per applicare fino a cinque righe in modo atomico per chiamata. Ripeti con lo stesso ID/hash fino al completamento; le righe completate non vengono mai rielaborate. Gli esiti sono applied, skipped, failed o pending. Eventuali modifiche al CRM o agli accessi invalidano il lavoro in sospeso: verifica i risultati e genera una nuova anteprima solo per i record rimanenti. Vengono conservati fino a 100 lotti per spazio di lavoro, accessibili per sette giorni e poi rimossi dalla pulizia pianificata o dalla successiva anteprima in blocco. Anche l'eliminazione del creatore o dello spazio di lavoro rimuove anteprime e ricevute. Non vengono inviate email né inviti. |
| GET | /imports/catalog | Catalogo dei campi e delle pipeline per la mappatura delle importazioni. Tutti i membri del CRM possono generare anteprime e importare; la configurazione di campi personalizzati e pipeline aggiuntive richiede comunque CRM Advanced. |
| POST | /imports/preview | Genera un'anteprima da 1 a 100 righe (fino a 500 KB) con kind e duplicates: fill o skip. Supporta custom_fields tramite ID stabile, ID o nomi univoci di pipeline e fasi, e ID espliciti dei record. L'opzione fill compila solo i campi vuoti; importo, stato e fase delle trattative esistenti restano invariati. I record ripetuti vengono ignorati. Nessun record del CRM viene modificato durante l'anteprima. Restituisce azioni ed errori per riga, ID del lotto e hash di conferma. I piani di anteprima e le ricevute di ripetizione scadono dopo sette giorni e vengono rimossi dalla pulizia pianificata o dalla successiva importazione nello spazio di lavoro. |
| GET POST | /imports/:id | Solo il creatore del lotto può leggerlo o riprenderlo. Inviando tramite POST la confirmation dell'anteprima verificata vengono applicate fino a dieci righe alla volta, ciascuna in modo atomico insieme a contatti correlati, campi, note e cronologia. Ripeti con lo stesso ID/hash fino al completamento; le righe completate non vengono mai rielaborate. Modifiche concorrenti al CRM rifiutano le anteprime non più aggiornate: leggi next_row e genera l'anteprima solo per le righe rimanenti. Vengono conservati fino a 100 lotti per spazio di lavoro. |
| POST | /import | Importazione immediata legacy senza ripetizione sicura; è preferibile usare /imports/preview. Importa fino a 500 aziende, persone o trattative; restituisce il conteggio dei record creati, aggiornati, ignorati o troncati e gli errori numerati per riga. I contatti esistenti possono essere completati anche a capacità raggiunta. |
| PUT | /deals/:id | Usa before_id (una trattativa nella fase di destinazione, oppure null per metterla in coda), stage_id e revision per riordinare. L'ordine delle schede non modifica la durata di permanenza nella fase. |
| POST | /deals/move | Genera l'anteprima o applica lo spostamento di fino a 100 trattative aperte: deal_ids, pipeline_id, stage_id, preview. Applica le modifiche con il preview_hash restituito. Le anteprime scadute vengono rifiutate; i risultati sono restituiti per singola trattativa. |
| GET POST | /views/:entity | Viste salvate per trattative, persone o aziende. GET restituisce le viste leggibili, il catalogo di campi e operatori e i valori predefiniti. Gli utenti Advanced possono creare viste private; gli amministratori possono creare viste condivise nello spazio di lavoro. POST richiede name, sharing (private/workspace), revision:0 e definition {version:1, columns, sort, filter}. La condivisione nello spazio di lavoro non amplia mai i permessi di accesso ai dati. |
| PUT | /views/:entity/:id | Aggiorna una vista con la revision attesa. L'impostazione sharing non è modificabile; salva una copia per cambiarla. Solo il proprietario può aggiornare una vista privata; solo gli amministratori possono aggiornare le viste condivise. archived:true nasconde la vista. Massimo 100 viste attive per spazio di lavoro. |
| POST | /query/:entity | Un'unica query convalidata per elenchi ed esportazioni CSV paginate. Invia definition o view_id, offset (0..100000), limit (1..100) e format (json/csv). Definition: version:1, columns (1..20 ID), sort (fino a 3 voci {field,direction}), filter {op:and/or,rules:[gruppi o {field,op,value}]}. Massimo 20 nodi e profondità 3. I valori sono parametri associati, mai SQL diretto. owner_id eq me viene risolto sull'utente attuale; value_cents è espresso in centesimi. has_task include i compiti aperti senza data; next_task è il primo compito aperto con data di scadenza. La risposta include total, next_offset e le righe in JSON o CSV protetto dalle formule. Nel CSV le etichette sostituiscono gli ID delle opzioni. I confronti sui campi vuoti usano empty/not_empty; gli altri confronti escludono i valori mancanti. Le viste e l'esportazione restano leggibili anche quando termina l'accesso a CRM Advanced. La paginazione è ordinata con spareggio per ID, ma non costituisce uno snapshot invariabile tra richieste diverse. |
| GET PUT | /layouts/:entity | Layout condiviso delle schede per aziende, persone o trattative. GET restituisce layout, valori predefiniti, revision, schema_revision e fields. Gli amministratori Advanced possono inviare con PUT il layout {main, side, details}, entrambe le revisioni e tutti i campi come oggetti ordinati {id, group_name}, inclusi i campi archiviati. Ogni sezione e chiave di dettaglio deve comparire esattamente una volta; non sono ammessi HTML né sezioni nascoste. I membri e gli spazi di lavoro senza CRM Advanced mantengono l'accesso in lettura. |
| GET POST | /fields/:entity | Elenca o crea campi personalizzati per aziende, persone o trattative. La creazione richiede un amministratore Advanced. Tipi: text, long_text, number, date, boolean, select, multi_select. group_name e position sono facoltativi. |
| PUT | /fields/deals/:id/rules | Amministratore Advanced: genera un'anteprima e sostituisce gli ambiti visible_in/required_in (pipeline_id, stage_id facoltativo). Richiede la revision del campo, prima con preview:true e poi con preview:false insieme al preview_hash restituito. Un visible_in vuoto significa visibile ovunque; i campi obbligatori restano sempre visibili. L'anteprima segnala le trattative aperte esistenti a cui mancano i valori richiesti. |
| PUT | /fields/:entity/:id | Aggiorna name, group_name, position, archived e options con la revision attesa. Il tipo di un campo esistente non può essere modificato. La creazione di una trattativa accetta custom_fields indicizzati per ID del campo; se mancano valori obbligatori per la fase, viene restituito 422 alla creazione, al cambio di fase e alla riapertura, anche tramite importazione e MCP. Le opzioni mantengono il proprio ID; le scelte precedenti omesse vengono archiviate. |
| GET PUT | /:entity/:id/fields | Legge o aggiorna i valori tipizzati per ID del campo. PUT richiede values, revision e schema_revision ottenuti da GET; null cancella il valore. I campi a scelta usano gli ID delle opzioni. I campi archiviati restano leggibili. Questi endpoint non supportano ancora i campi obbligatori o specifici per fase. |
| GET POST | /pipelines | Elenca le pipeline (incluse quelle archiviate) o ne crea una (name; richiede amministratore Advanced) |
| PUT | /pipelines/:id | Aggiorna name, position, make_default o archived con la revision attesa. Sposta o chiudi le trattative aperte prima di archiviare una pipeline; /deals/move offre un'anteprima e i risultati per singola trattativa. |
| GET | /reports | Tipi di report, note di calcolo, filtri e report personali salvati (amministratore Advanced) |
| POST | /reports/run | Esegue definition o view_id con le autorizzazioni attuali sui record. Parametri facoltativi: group dalla risposta, offset e limit fino a 100. Gli importi in centesimi restano separati per valuta. |
| POST PUT | /reports/views, /reports/views/:id | Salva un report personale: name, definition, revision (0 per i nuovi report); archived:true nasconde un report esistente |
| GET | /capabilities | Abilitazioni attuali delle funzioni CRM e azioni consentite; ciò non implica che ogni funzione sia già implementata |
| GET | /me | Spazio di lavoro, piano e utente a nome del quale agisce la chiave |
| GET | /deals?status=open|won|lost&q=&pipeline_id= | Elenca le trattative con fase, valore, azienda, contatto e stato di lettura della proposta |
| POST | /deals | Crea una trattativa (name, company_id o company_name, person_id, value, currency, pipeline_id, stage_id, expected_close) |
| GET PUT DELETE | /deals/:id | Singola trattativa con cronologia; aggiorna campi, fase o stato; close_details Advanced facoltativi, oppure next_activity alla riapertura, con revision; elimina |
| POST | /deals/:id/proposals | Collega una proposta alla trattativa ({proposal_id}) |
| DELETE | /deals/:id/proposals/:pid | Scollega una proposta |
| GET POST | /companies | Elenca o crea aziende |
| GET PUT DELETE | /companies/:id | Singola azienda con persone, trattative e cronologia |
| GET POST | /people | Elenca o crea persone (contatti) |
| GET PUT DELETE | /people/:id | Singola persona con trattative e cronologia |
| GET PUT | /activity-settings | Legge o imposta il tuo fuso orario IANA; gli amministratori possono impostare anche workspace_timezone. Il valore null usa l'impostazione predefinita. |
| GET POST | /tasks | Elenca o crea attività. Parametri: scope=mine|all|unassigned, status=open|done|cancelled|all (legacy done=0|1|all), ID dei record, offset e limit (massimo 500). Segui next_offset quando has_more è true. |
| GET PUT DELETE | /tasks/:id | Legge, modifica, completa, annulla o elimina un'attività. Sono supportati notes, completed_date, call_result e next_activity atomica. Invia revision nelle modifiche e ?revision= nelle eliminazioni; le scritture non aggiornate restituiscono 409. |
| POST | /notes | Aggiunge una nota a una trattativa, persona o azienda |
| PUT DELETE | /notes/:id | Modifica o elimina una nota |
| GET | /stages?pipeline_id= | Fasi della pipeline, membri e valuta (pipeline predefinita se omessa) |
| PUT | /stages | Salva le fasi con pipeline_id e revision. Dalle fasi in uso è necessario prima spostare o chiudere le trattative aperte. Le fasi omesse vengono archiviate. |
| GET | /activity?since=&limit=&deal_id=&person_id=&company_id= | Registro strutturato degli eventi, dal più recente. since è un timestamp Unix in millisecondi |
| GET | /search?q= | Aziende, persone e trattative in un'unica ricerca |
| GET | /visitors?days=7|30|90 | Tiny Ant Visitors: aziende che hanno visitato il tuo sito, pagine viste, ultima visita, collegamento al CRM e quota di visite da connessioni domestiche, mobili e data center |
| GET POST | /visitors/settings | Stato e snippet di Visitors; attiva o disattiva ({enabled}), collega o rimuovi ipapi.is ({ipapi_key}) |
| POST | /visitors/companies/:id/add | Aggiunge un'azienda visitatrice al CRM |
| GET | /proposals?status=active|won|closed|archived | Proposte con visite, tempo di lettura e trattativa collegata |
| GET | /proposals/:id | Singola proposta con tempo di lettura per pagina, destinatari, attività e versioni |
| POST | /proposals | Carica una proposta (stesso corpo usato dall'app: multipart con file PDF, nome e pagine) |
| POST | /proposals/:id/status | Imposta lo stato ({status: active|closed|won}) |
Attività
Gli endpoint dei compiti salvano anche chiamate, riunioni e follow-up per gli spazi di lavoro con CRM Advanced nei piani Team, Enterprise o in un progetto pilota attivo. Invia activity_type (task, call, meeting o follow_up), due_date (YYYY-MM-DD), due_time facoltativo (HH:mm), timezone (nome IANA), duration_minutes (da 1 a 1440), assignee_id e, facoltativamente, deal_id, person_id o company_id. I compiti giornalieri senza orario mantengono la data di calendario. Se manca il fuso orario, viene usato per impostazione predefinita quello dell'utente, poi quello dello spazio di lavoro e infine UTC. Un orario locale inesistente viene rifiutato; un orario ripetuto richiede occurrence: earlier o later. Leggi un'attività prima di modificarla e invia la relativa revision; le modifiche non aggiornate restituiscono 409. I client legacy possono omettere revision. Il valore null cancella i campi facoltativi. Elenca le attività con scope=mine, all o unassigned, done=0, 1 o all, ID dei record facoltativi, limit fino a 500 e offset; segui next_offset quando has_more è true. Quando termina l'accesso a CRM Advanced, le attività tipizzate esistenti restano modificabili e completabili, mentre rimane possibile creare nuovi compiti di base. Le attività non effettuano chiamate, non inviano messaggi e non spediscono inviti alle riunioni. Completarne una non contrassegna una trattativa o una proposta come vinta.
Registra i contatti via email, SMS, LinkedIn o altri canali come activity_type: follow_up con contact_channel: email, sms, linkedin o other (Advanced). Le note sulle attività accettano fino a 10.000 caratteri. done: true registra il completamento; completed_date è in formato YYYY-MM-DD, non successivo a oggi. Per completare una chiamata è richiesto call_result: answered, no_answer o busy. cancelled: true annulla l'attività senza eliminarla; done e cancelled non possono essere entrambi true. Elenca usando status: open, done, cancelled o all; i record annullati sono esclusi dagli elenchi di lavoro aperti e dai report sulle attività.
Una scrittura di attività può includere next_activity: {title, due_date, activity_type, contact_channel, notes, assignee_id}; il nuovo record eredita la trattativa e la sua data deve essere oggi o successiva. Le scritture combinate su record esistenti richiedono revision. Entrambe le modifiche vengono salvate in modo atomico. Un amministratore Advanced può attivare require_next_activity su una pipeline. Una trattativa aperta deve quindi mantenere un'attività aperta quando l'ultima attività viene completata, annullata, rimossa o scollegata, e quando la trattativa viene riaperta. Creare o spostare una trattativa senza un'attività resta comunque consentito. Il requisito cessa di applicarsi quando termina l'accesso a CRM Advanced.
Gli aggiornamenti avanzati delle trattative possono includere close_details con status won o lost e revision: close_date (non successiva a oggi), open_activities (keep o cancel), notes facoltative e won_reason per le trattative vinte, oppure loss_category per quelle perse. Le categorie di perdita sono price, timing, no_need, competitor, no_response, no_authority_or_budget, in_house, poor_fit e other. Il campo facoltativo competitor si applica alla categoria competitor; revisit_date deve essere una data futura e non crea un promemoria. Lo stato won richiede un valore positivo della trattativa. La chiusura e l'eventuale annullamento delle attività vengono salvati insieme secondo le autorizzazioni attuali sui record. Per riaprire una trattativa, invia status: open e, se necessario, next_activity. La riapertura cancella i dettagli di chiusura ma non ripristina le attività annullate. Gli aggiornamenti legacy del solo stato restano supportati.
Esempi
Elenca le trattative aperte:
curl https://app.tinyant.io/api/v1/deals?status=open \
-H "Authorization: Bearer ta_live_..."Crea una trattativa e lascia che Tiny Ant crei o associ l'azienda per nome:
curl -X POST https://app.tinyant.io/api/v1/deals \
-H "Authorization: Bearer ta_live_..." \
-H "Content-Type: application/json" \
-d '{"name": "Website redesign", "company_name": "Acme Ltd", "value": 12500}'Tutto ciò che è successo a partire da un timestamp, ad esempio per sincronizzare il tuo sistema:
curl "https://app.tinyant.io/api/v1/activity?since=1760000000000&limit=100" \
-H "Authorization: Bearer ta_live_..."Server MCP
Il server MCP (Model Context Protocol) si trova all'indirizzo:
https://app.tinyant.io/mcpIl trasporto usa Streamable HTTP, stateless, con JSON-RPC su POST. L'autenticazione avviene con la stessa chiave Bearer. Non ci sono flussi avviati dal server, quindi basta un normale client HTTP.
Claude Code. Una riga nel terminale, poi chiedi a Claude informazioni sulle tue trattative:
claude mcp add --transport http tiny-ant https://app.tinyant.io/mcp --header "Authorization: Bearer ta_live_..."Altri client MCP. Usa un client che supporti Streamable HTTP e un header Authorization personalizzato. Imposta l'URL del server sull'indirizzo indicato sopra e il valore dell'header su Bearer seguito dalla tua chiave API. Verifica le opzioni di connessione supportate dal client. Se il supporto MCP diretto non è disponibile, un'integrazione personalizzata può chiamare l'API REST. Tiny Ant non fornisce un'integrazione pronta all'uso per ogni client.
OAuth. La connessione MCP pubblicata di Tiny Ant usa attualmente una chiave Bearer statica. Un client che richiede OAuth non può utilizzare direttamente questa connessione. Verifica la compatibilità prima di scegliere un client.
Strumenti MCP
Ogni strumento chiama la stessa API descritta sopra e restituisce la risposta JSON come testo.
| Strumento | Descrizione |
|---|---|
search | Cerca aziende, persone e trattative nel CRM per nome, email o dominio. |
list_deals | Elenca le trattative. |
get_deal | Vista completa di una trattativa: dettagli, azienda, contatto, proposte con dati di lettura, compiti e cronologia di note ed eventi. |
create_deal | Crea una trattativa. |
update_deal | Aggiorna una trattativa: rinomina, modifica il valore, sposta di fase, contrassegna come vinta o persa, collega un'azienda o un contatto. |
list_companies | Elenca le aziende con numero di persone, trattative aperte e valore aperto. |
get_company | Singola azienda con persone, trattative e cronologia. |
create_company | Crea un'azienda. |
list_people | Elenca le persone (contatti), facoltativamente per una singola azienda. |
get_person | Singola persona con trattative e cronologia. |
create_person | Crea un contatto. |
add_note | Aggiunge una nota a una trattativa, persona o azienda. |
list_tasks | Elenca i compiti aperti per il titolare della chiave (mine) o per tutti. |
create_task | Crea un compito, facoltativamente collegato a una trattativa, persona o azienda. |
get_task | Legge un'attività inclusa la relativa revision. |
update_task | Modifica un'attività. |
get_activity_settings | Legge il fuso orario effettivo delle attività e i tipi disponibili. |
complete_task | Contrassegna un compito come completato (o lo riapre con done=false). |
get_crm_capabilities | Abilitazioni attuali delle funzioni CRM e azioni consentite per questo utente. |
list_stages | Fasi di una pipeline (quella predefinita se omessa), membri dello spazio di lavoro e valuta. |
move_deals | Genera l'anteprima o applica lo spostamento di fino a 100 trattative aperte. |
get_dashboard | Legge la tua dashboard personale con metriche in tempo reale filtrate in base agli accessi. |
save_dashboard | Salva il layout e i filtri della tua dashboard con la revision ottenuta da get_dashboard. |
list_automations | Legge le regole di automazione associate alla chiave API e gli ultimi risultati di esecuzione accessibili. |
preview_automation | Convalida una regola e mostra in anteprima le trattative aperte corrispondenti senza applicare modifiche. |
save_automation | Crea o modifica una regola usando la conferma ottenuta dall'anteprima. |
simulate_automation | Mette in coda una simulazione per una trattativa attuale corrispondente. |
stop_automation | Disattiva una regola e annulla le relative esecuzioni in sospeso. |
archive_automation | Archivia una regola e annulla le relative esecuzioni in sospeso. |
cancel_automation_run | Annulla un'esecuzione in sospeso. |
list_automation_notifications | Legge le notifiche interne delle automazioni in base all'accesso attuale alle trattative. |
list_reports | Legge tipi di report, note di calcolo, filtri e report personali salvati (amministratore Advanced). |
run_report | Esegue un report con le autorizzazioni attuali di accesso ai record. |
save_report | Salva la definizione di un report personale. |
list_views | Elenca le viste salvate leggibili, il catalogo di campi e operatori e i valori predefiniti. |
query_records | Sfoglia per pagina una vista CRM convalidata. |
preview_bulk_change | Genera l'anteprima per un numero da 1 a 100 di record CRM selezionati. |
get_bulk_change | Legge l'anteprima in blocco e i risultati persistenti per riga per sette giorni, usando la stessa chiave API. |
apply_bulk_change | Applica fino a cinque righe dell'anteprima in modo atomico per riga. |
preview_import | Genera l'anteprima di fino a 100 righe del CRM senza modificare i record. |
get_import | Legge l'anteprima di importazione e l'avanzamento salvato; i lotti scadono dopo sette giorni. |
apply_import | Applica fino a dieci righe dell'anteprima in modo atomico per riga. |
save_view | Crea o aggiorna una vista personale, oppure una vista dello spazio di lavoro come amministratore (Advanced). |
get_card_layout | Legge le sezioni condivise delle schede, l'ordine dei dettagli e i gruppi di campi personalizzati. |
set_card_layout | Sostituisce il layout condiviso delle schede e i gruppi di campi personalizzati (amministratore Advanced). |
list_fields | Elenca le definizioni dei campi personalizzati, inclusi i campi archiviati e le opzioni con ID stabile. |
create_field | Crea un campo personalizzato (amministratore Advanced). |
update_field | Rinomina, riordina, raggruppa o archivia un campo (amministratore Advanced). |
set_field_rules | Genera l'anteprima o salva la visibilità e l'obbligatorietà dei campi delle trattative (amministratore Advanced). |
get_record_fields | Legge i campi personalizzati, i valori e la revision di un record. |
set_record_fields | Aggiorna i valori dei campi personalizzati per ID del campo. |
list_pipelines | Elenca le pipeline dello spazio di lavoro, incluse quelle archiviate, e la pipeline predefinita. |
create_pipeline | Crea una pipeline con quattro fasi iniziali. |
update_pipeline | Rinomina, riordina, archivia o imposta una pipeline come predefinita. |
set_stages | Sostituisce le fasi attive di una pipeline. |
activity | Registro strutturato degli eventi dello spazio di lavoro, dal più recente: trattative create e spostate, vinte e perse, note, compiti, proposte collegate e lette. |
list_proposals | Proposte con stato di lettura: visite, tempo di lettura totale, lettura in corso e trattativa collegata. |
get_proposal | Singola proposta: tempo di lettura per pagina, destinatari, attività, versioni e trattativa collegata. |
list_visitors | Aziende che hanno visitato il tuo sito web (Tiny Ant Visitors): reti aziendali identificate con pagine viste, ultima visita e azienda collegata nel CRM, più il numero di visite provenienti da connessioni domestiche, mobili o data center. |
link_proposal | Collega una proposta esistente a una trattativa affinché le letture compaiano nella cronologia della trattativa. |
Limiti di frequenza e uso corretto
MCP accetta un messaggio JSON-RPC per ogni richiesta POST, fino a 512 KiB. Gli array JSON vengono rifiutati senza eseguire alcuno strumento. Invia richieste separate. Le richieste CRM diverse da GET, incluse importazioni, operazioni in blocco e anteprime di query, condividono un limite aggiuntivo di 120 richieste al minuto per spazio di lavoro tra app, API REST e MCP; in caso di superamento vengono restituiti 429 e l'header Retry-After. Questi limiti edge sono calcolati localmente per ciascuna sede Cloudflare.
I limiti di archiviazione per uso corretto del CRM si applicano per tabella (trattative, compiti e note): 500 con Free, 20.000 con Pro, 50.000 con Team ed Enterprise. Free prevede inoltre un limite separato di 10 trattative aperte. I compiti completati e le trattative chiuse concorrono comunque ai limiti di archiviazione; i record esistenti vengono conservati in caso di passaggio a un piano inferiore.
L'acquisizione di Visitors è limitata per spazio di lavoro e giorno UTC: 5.000 visualizzazioni di pagina con Pro, 20.000 con Team e 50.000 con Enterprise. Il traffico in eccesso viene scartato e la raccolta riprende il giorno successivo. Il tetto giornaliero usa un contatore condiviso nel database; la protezione edge limita inoltre un indirizzo di origine a 60 beacon al minuto e una chiave pubblica di Visitors a 600 beacon al minuto per sede Cloudflare. Una ricerca o una scrittura non riuscita dopo la prenotazione può comunque consumare uno slot giornaliero. La quota ipapi.is del cliente è separata.
Ogni chiave può effettuare fino a 120 richieste al minuto complessivamente tra API REST e server MCP, e ogni indirizzo fino a 300 al minuto. Le richieste senza una chiave valida sono limitate a 30 al minuto per indirizzo. Oltre il limite ricevi 429 con un header Retry-After: attendi e riprova. Interroga /activity con il parametro since invece di rileggere interi elenchi, usa una chiave distinta per ogni integrazione così da poterla revocare singolarmente e non condividere le chiavi con persone esterne al tuo spazio di lavoro. Uno spazio di lavoro può avere fino a 10 chiavi attive.
Le regole di automazione di CRM Advanced partono in modalità di simulazione. I limiti sono 50 regole attive e 1.000 esecuzioni ogni 24 ore (finestra mobile) per spazio di lavoro. La creazione di trattative e i cambi di fase vengono accodati in modo atomico. Le aperture esterne confermate delle proposte sono limitate a una per proposta per giorno UTC. Le scadenze delle trattative ferme hanno una finestra di recupero di sette giorni. Le esecuzioni e le notifiche interne vengono conservate per 90 giorni. Nessun dato dei clienti viene inviato a modelli di AI o a servizi di messaggistica esterni.
Gli amministratori Advanced possono eseguire report su pipeline aperta, trattative vinte o perse e tasso di successo, storico delle fasi, attività e previsioni ponderate. Le date sono espresse in giorni UTC inclusi (fino a 366); le attività pianificate usano la propria data di scadenza. Le previsioni usano le trattative aperte attuali e le probabilità delle fasi, mantenendo separate le trattative senza data e le diverse valute. Le osservazioni di base non rappresentano ingressi storici nelle fasi né durate note. I report personali salvati memorizzano i criteri scelti, non istantanee dei risultati. Ogni esecuzione e approfondimento applica le autorizzazioni attuali di accesso ai record.
Con CRM Advanced, l'accesso ai record viene applicato nell'app, nell'API REST, in MCP e nelle esportazioni. Le chiavi API e i webhook accedono per impostazione predefinita ai soli record condivisi nello spazio di lavoro, inclusi i record principali condivisi. Un amministratore può creare esplicitamente un'integrazione estesa a tutti i record dello spazio di lavoro, inclusi quelli privati. L'ambito di accesso è indicato nelle Impostazioni. Le restrizioni esistenti restano in vigore anche quando termina l'accesso a CRM Advanced. I link pubblici delle proposte per i destinatari restano un canale di condivisione separato.
Webhook
Se preferisci che sia Tiny Ant a inviare notifiche al tuo sistema, nella stessa pagina Impostazioni puoi configurare i webhook in uscita. Inviano una richiesta POST JSON firmata quando una proposta viene aperta, quando termina una sessione di lettura, quando cambia uno stato e quando una trattativa viene creata o passa da una fase all'altra.
Domande
Scrivi a hello@tinyant.io. Le modifiche all'API vengono annunciate in questa pagina.