# API BeMyTalent: dal contatto al preventivo

> Chiavi API, permessi, contratto OpenAPI ed esempio JavaScript testato: cerchi un contatto, crei un preventivo in bozza e verifichi il risultato in BeMyTalent.

Fonte: https://www.bemytalent.com/it/documentazione-api · aggiornato il 2026-11-07 · altre lingue: [fr](https://www.bemytalent.com/fr/documentation-api.md) · [de](https://www.bemytalent.com/de/api-dokumentation.md) · [en](https://www.bemytalent.com/en/api-documentation.md)

Per gli sviluppatori di software professionali

## API BeMyTalent: dal contatto al preventivo

Questa prima referenza copre il percorso REST contatto → preventivo. I contratti describe permettono di scoprire gli altri ambiti. Chiavi e diritti REST sono distinti da quelli del connettore MCP.

### Avvio rapido

- Nel dossier di prova, apra Impostazioni → Agenti & API e crei una chiave dedicata con i quattro diritti indicati sotto.

- Copi gli indirizzi API CRM e Contabilità mostrati nella schermata. Devono condividere la stessa base, terminante con /functions/v1.

- Conservi la chiave nell’ambiente del server. Gli esempi non richiedono mai una chiave di servizio Supabase né un token di sessione del browser.

- Verifichi esercizio e fatturazione. L’esempio usa dati fittizi e un’aliquota IVA dimostrativa pari a zero: adatti l’aliquota al caso reale.

- `crm:read`

- `crm:write`

- `invoicing:read`

- `invoicing:write`

### Accesso e perimetro

- La chiave bmt_… identifica il dossier: il percorso non invia project_id. I riferimenti devono appartenere allo stesso dossier.

- Una chiave per applicazione e ambiente facilita la revoca in Impostazioni → Agenti & API. Verifichi la scadenza e la sostituisca in tempo.

- Invii Authorization: Bearer seguito dalla chiave e Content-Type: application/json per le scritture. La chiave resta sul server, fuori da codice sorgente, URL e registri.

- I diritti di scrittura REST sono più ampi di quelli MCP. Conceda solo quelli necessari; una descrizione API non concede ulteriori accessi.

### Contratti e operazioni

I percorsi seguono /functions/v1. Tutte e quattro le descrizioni richiedono un’autenticazione valida. Le descrizioni dei mandati e della pianificazione richiedono anche, rispettivamente, mandates:read e planning:read. Il contratto OpenAPI scaricabile copre solo le cinque operazioni di questo percorso.

**CRM: risorse, filtri e riferimenti**

`GET /crm-api/describe`

**Contabilità e fatturazione: azioni**

`GET /accounting-api?action=describe`

**Mandati e tempi: azioni**

`GET /mandates-api?action=describe`

**Pianificazione: schemi e azioni**

`GET /planning-api?action=describe`

| Operazione | Metodo | Indirizzo relativo | Diritto richiesto | Risposta |
|---|---|---|---|---|
| Cercare per e-mail esatta | `GET` | `/crm-api/contacts` | `crm:read` | 200 |
| Creare il contatto | `POST` | `/crm-api/contacts` | `crm:write` | 201 |
| Rileggere il contatto | `GET` | `/crm-api/contacts/{id}` | `crm:read` | 200 |
| Preparare il preventivo in bozza | `POST` | `/accounting-api?action=create_offer` | `invoicing:write` | 200 |
| Rileggere preventivo e righe | `GET` | `/accounting-api?action=quotes&id={id}` | `invoicing:read` | 200 |

[Scaricare il contratto OpenAPI (.json)](https://www.bemytalent.com/.well-known/bmt-api/openapi.json)

### Contatto → preventivo, passo per passo

- 1. Cercare prima di creare Il filtro e-mail richiede un’uguaglianza esatta e distingue maiuscole e minuscole. count è il totale dei risultati CRM filtrati. Con limit=2, un totale superiore a uno ferma l’esempio; la ricerca non garantisce l’unicità in presenza di creazioni simultanee.

- 2. Creare e rileggere il contatto Se non vi sono corrispondenze, POST /contacts restituisce HTTP 201 e data.id. Conservi l’identificativo e rilegga la scheda. Per questo primo test non crei una società separata.

- 3. Creare il preventivo POST accounting-api?action=create_offer riceve contact_id e lines. Una riga contiene description, quantity e unit_price_excl_vat. La risposta HTTP 200 include invoice_id, document_kind=quote e status=draft. Anche il preventivo usa invoice_id.

- 4. Rileggere il documento GET accounting-api?action=quotes&id=… restituisce l’array quotes con le righe. Verifichi contatto, stato e importi. Gli elenchi contabili generali sono limitati e segnalati come non esaustivi; count non è un totale globale.

- 5. Verificare in BeMyTalent Apra Fatturazione → Preventivi nel dossier di prova. L’esempio non emette e non invia nulla. La ricevuta locale conserva gli identificativi del test.

```
curl --fail-with-body --get "$BMT_API_BASE/crm-api/contacts" \
  -H "Authorization: Bearer $BMT_API_KEY" \
  --data-urlencode "filter.email=integration-demo@example.invalid" \
  --data-urlencode "limit=2" --data-urlencode "offset=0"
```

```
{
  "first_name": "Alex",
  "last_name": "Integration Demo",
  "email": "integration-demo@example.invalid",
  "language": "fr"
}
```

```
{
  "subject": "INTEGRATION TEST — DO NOT SEND",
  "language": "fr",
  "qr_bill_enabled": false,
  "reminders_enabled": false,
  "lines": [
    {
      "description": "Demonstration service",
      "quantity": 2,
      "unit": "h",
      "unit_price_excl_vat": 100
    }
  ],
  "contact_id": "11111111-2222-4333-8444-555555555555"
}
```

Esempio di risposta di creazione con identificativi fittizi. Gli importi reali dipendono dalle righe e dalla configurazione del dossier.

```
{
  "ok": true,
  "invoice_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
  "document_kind": "quote",
  "status": "draft",
  "lines_count": 1
}
```

L’esempio Node.js 22+ esegue questi passi senza tentativi automatici. Fornisca le variabili tramite l’ambiente del server e sostituisca la base fittizia con quella copiata da BeMyTalent. Il download contiene lo stesso codice verificato dai test.

- Scarichi il file JavaScript in una cartella dedicata a questo test.

- Imposti BMT_API_BASE e BMT_API_KEY nell’ambiente e confermi che il dossier contiene solo dati di prova.

- Lo script riserva bmt-contact-quote-receipt.json prima di ogni chiamata e rifiuta una nuova esecuzione se il file esiste. Lo conservi per esaminare il risultato; non lo elimini per riprovare alla cieca.

[Scaricare l’esempio JavaScript (.mjs)](https://www.bemytalent.com/.well-known/bmt-api/contact-quote.mjs)

```
export BMT_API_BASE="https://your-api-host.example.invalid/functions/v1"
# BMT_API_KEY: server environment / secret manager
BMT_DEMO_CONFIRMED=yes node contact-quote.mjs
```

### Riprese e duplicati

- POST /contacts e create_offer accettano l’intestazione facoltativa Idempotency-Key (1–200 caratteri ASCII visibili, senza spazi). Lo script salva nella ricevuta una chiave distinta per ogni creazione. Dopo una risposta persa, riutilizzi tale chiave, la stessa chiave API e lo stesso corpo JSON. Senza questa intestazione, ogni chiamata resta una nuova creazione.

- Preventivo e tutte le righe sono creati in un’unica transazione: un errore annulla l’intera creazione. Una ripetizione riuscita riporta Idempotency-Replayed: true. Il contatto mantiene il suo identificativo e restituisce i campi attuali; il preventivo restituisce la ricevuta iniziale. Rilegga il documento per conoscerne lo stato attuale.

- La chiave di ripresa è limitata a dossier, chiave API e operazione. Contenuti diversi o un oggetto eliminato restituiscono 409 senza ricreazione. Le ricevute restano fino all’eliminazione del dossier. Conservi insieme riferimento professionale, chiave di ripresa e identificativi BMT; cambiare chiave API modifica anche l’ambito della protezione dai duplicati.

### Comprendere le risposte

**400**

Parametro o riferimento rifiutato. Un errore SQL annulla la creazione interessata; contatto e preventivo restano due operazioni distinte.

**401 / 403**

Verifichi validità della chiave, diritti concessi e accesso al dossier.

**402**

Le scritture richiedono un accesso attivo al dossier. Verifichi l’abbonamento o il periodo di prova.

**404**

La risorsa non è accessibile in questo dossier. Verifichi identificativo e perimetro.

**409 / 422**

Conflitto applicativo o riferimento incompatibile. Rilegga l’oggetto prima di procedere.

**429**

Rispetti retry_after_seconds nel corpo della risposta. Per una creazione, verifichi anche il risultato prima di riprovare.

**5xx / rete**

L’esito può essere incerto. L’esempio non ripete automaticamente le creazioni.

### Versioni e verifica

Versione della guida : 1.1.0

Questa versione identifica la guida e il suo contratto parziale, non tutte le API BMT. I test eseguono le richieste documentate contro gli handler REST con autenticazione e archiviazione sintetiche, inclusi rifiuti e risposte incerte. Prima della produzione resta necessario un collaudo sul Suo dossier.