API BeMyTalent: dal contatto al preventivo

Avvio rapido

1. Nel dossier di prova, apra Impostazioni → Agenti & API e crei una chiave dedicata con i quattro diritti indicati sotto.
2. Copi gli indirizzi API CRM e Contabilità mostrati nella schermata. Devono condividere la stessa base, terminante con /functions/v1.
3. Conservi la chiave nell’ambiente del server. Gli esempi non richiedono mai una chiave di servizio Supabase né un token di sessione del browser.
4. 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

Scaricare il contratto OpenAPI (.json)

Contatto → preventivo, passo per passo

1. 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. 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. 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. 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. 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.

1. Scarichi il file JavaScript in una cartella dedicata a questo test.
2. Imposti BMT_API_BASE e BMT_API_KEY nell’ambiente e confermi che il dossier contiene solo dati di prova.
3. 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)

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.