Vai al contenuto principale
L’endpoint Crea Cliente ti consente di aggiungere clienti direttamente al tuo workspace AgencyHandy da un sistema esterno. A differenza dei lead, i clienti sono contatti completamente integrati che possono essere assegnati a ordini, fatture e progetti. Usa questo endpoint per sincronizzare nuovi clienti da un CRM, da un modulo di onboarding o da qualsiasi altra fonte di dati.
Prima di utilizzare questo endpoint, completa la guida Getting Started per ottenere la tua chiave API e l’ID Azienda. A differenza dell’endpoint Crea Lead, la creazione di un cliente non richiede un passaggio separato di recupero dell’ID Ruolo.

​
Prerequisiti

  • ✅ Chiave API generata da Configurazione Workspace → Chiave API
  • ✅ ID Azienda recuperato da GET {{URL}}/accounts/companies

​
Endpoint

POST {{URL}}/members/bulk-client
HeaderValore
x-api-keyLa tua chiave API
companyIdIl tuo ID Azienda
Content-Typeapplication/json

​
Corpo della richiesta

Il corpo della richiesta è un array JSON. Puoi creare uno o più clienti in una singola richiesta.
​
firstName
string
obbligatorio
Il nome del cliente.
​
lastName
string
obbligatorio
Il cognome del cliente.
​
email
string
obbligatorio
L’indirizzo email del cliente. Deve essere univoco all’interno del tuo workspace.
​
isConvertedClient
boolean
obbligatorio
Impostato su false per un cliente completamente nuovo. Impostato su true quando si converte un lead esistente in cliente.
​
status
string
Lo stato del cliente. Valori comuni: New, Active. Predefinito a New se omesso.
​
contactNo
string
Il numero di telefono del cliente.
​
source
string
Come hai acquisito questo cliente. Valori di esempio: website, referral, social.
​
positionInBoard
number
La posizione del cliente all’interno della colonna della board. Predefinito a 1.

​
Richiesta di esempio

cURL
curl --request POST "https://api.agencyhandy.com/members/bulk-client" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyId: <YOUR_COMPANY_ID>" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'

​
Risposta di successo

{
  "message": "Client created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Stringa di conferma in caso di successo.
​
createdMembers
array
Array degli oggetti cliente creati.
​
createdMembers[].\_id
string
ID univoco del cliente appena creato. Usa questo ID quando assegni il cliente a ordini o fatture tramite l’API.
​
createdMembers[].name
string
Il nome completo del cliente (nome + cognome).
​
createdMembers[].status
string
Lo stato del cliente come memorizzato.
​
createdMembers[].role
string
Il ruolo assegnato al membro — sarà "client".
L’header companyId per questo endpoint usa la I maiuscola in Id — companyId — a differenza di alcuni altri endpoint che usano companyid (tutto minuscolo). Usa esattamente la formattazione mostrata sopra per evitare errori di autenticazione.
Passa più oggetti cliente nell’array per creare clienti in blocco in una singola chiamata API. Ogni oggetto deve avere un indirizzo email univoco. Le email duplicate causeranno un errore di validazione per quella voce.