BeMyTalent API: vom Kontakt zur Offerte

Schnellstart

1. Öffnen Sie im Testdossier Einstellungen → Agenten & API und erstellen Sie einen eigenen Schlüssel mit den vier unten genannten Rechten.
2. Kopieren Sie dort die API-Adressen für CRM und Buchhaltung. Beide müssen dieselbe Basis mit der Endung /functions/v1 verwenden.
3. Bewahren Sie den Schlüssel in der Serverumgebung auf. Die Beispiele benötigen weder einen Supabase-Serviceschlüssel noch ein Browser-Sitzungstoken.
4. Prüfen Sie Geschäftsjahr und Fakturierung. Das Beispiel nutzt fiktive Daten und einen MWST-Demonstrationssatz von null; passen Sie den Satz für den echten Anwendungsfall an.

• crm:read
• crm:write
• invoicing:read
• invoicing:write

Zugriff und Umfang

• Der Schlüssel bmt_… bestimmt das Dossier; der Ablauf sendet keine project_id. Referenzen müssen zum selben Dossier gehören.
• Ein Schlüssel je Anwendung und Umgebung erleichtert den Widerruf unter Einstellungen → Agenten & API. Prüfen Sie das Ablaufdatum und ersetzen Sie den Schlüssel rechtzeitig.
• Senden Sie Authorization: Bearer mit dem Schlüssel und bei Schreibzugriffen Content-Type: application/json. Der Schlüssel bleibt auf dem Server, ausserhalb von Quellcode, URLs und Protokollen.
• REST-Schreibrechte reichen weiter als MCP-Rechte. Vergeben Sie nur die nötigen Rechte; eine API-Beschreibung erteilt keine zusätzlichen Zugriffe.

Verträge und Operationen

Die Pfade folgen auf /functions/v1. Alle vier Beschreibungen erfordern eine gültige Authentifizierung. Die Beschreibungen für Mandate und Planung benötigen zusätzlich mandates:read beziehungsweise planning:read. Der herunterladbare OpenAPI-Vertrag umfasst nur die fünf Operationen dieses Ablaufs.

CRM: Ressourcen, Filter und Referenzen

GET /crm-api/describe

Buchhaltung und Fakturierung: Aktionen

GET /accounting-api?action=describe

Mandate und Zeiten: Aktionen

GET /mandates-api?action=describe

Planung: Schemata und Aktionen

GET /planning-api?action=describe

OpenAPI-Vertrag herunterladen (.json)

Kontakt → Offerte, Schritt für Schritt

1. 1. Vor dem Erstellen suchen

   Der E-Mail-Filter verlangt exakte Übereinstimmung mit Gross-/Kleinschreibung. count ist die Gesamtzahl der gefilterten CRM-Treffer. Bei limit=2 stoppt das Beispiel, sobald count grösser als eins ist. Eine Suche garantiert keine Eindeutigkeit bei gleichzeitigen Erstellungen.

2. 2. Kontakt erstellen und erneut lesen

   Ohne Treffer liefert POST /contacts HTTP 201 und data.id. Bewahren Sie die ID auf und lesen Sie den Kontakt erneut. Erstellen Sie für diesen ersten Test keine separate Firma.

3. 3. Offerte erstellen

   POST accounting-api?action=create_offer erhält contact_id und lines. Eine Position enthält description, quantity und unit_price_excl_vat. Die HTTP-200-Antwort enthält invoice_id, document_kind=quote und status=draft. Auch Offerten verwenden das Feld invoice_id.

4. 4. Dokument erneut lesen

   GET accounting-api?action=quotes&id=… liefert ein quotes-Array mit Positionen. Prüfen Sie Kontakt, Status und Beträge. Allgemeine Buchhaltungslisten sind begrenzt und als unvollständig gekennzeichnet; count ist keine globale Gesamtzahl.

5. 5. In BeMyTalent prüfen

   Öffnen Sie Fakturierung → Offerten im Testdossier. Das Beispiel stellt nichts aus und versendet nichts. Der lokale Beleg bewahrt die Test-IDs auf.

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"
}

Beispiel einer Erstellungsantwort mit fiktiven IDs. Die tatsächlichen Beträge hängen von Positionen und Dossiereinstellungen ab.

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

Das Beispiel für Node.js 22+ führt diese Schritte ohne automatische Wiederholung aus. Geben Sie die Variablen über Ihre Serverumgebung vor und ersetzen Sie die fiktive Basis durch die aus BeMyTalent kopierte Adresse. Der Download enthält denselben Code wie die Tests.

1. Laden Sie die JavaScript-Datei in ein Verzeichnis für diesen Test herunter.
2. Setzen Sie BMT_API_BASE und BMT_API_KEY in Ihrer Umgebung und bestätigen Sie, dass das Dossier nur Testdaten enthält.
3. Das Skript reserviert vor dem ersten Aufruf bmt-contact-quote-receipt.json. Existiert die Datei, verweigert es einen neuen Lauf. Bewahren Sie sie zur Prüfung auf; löschen Sie sie nicht für eine blinde Wiederholung.

JavaScript-Beispiel herunterladen (.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

Wiederaufnahme und Duplikate

• POST /contacts und create_offer akzeptieren den optionalen Header Idempotency-Key (1–200 sichtbare ASCII-Zeichen, ohne Leerzeichen). Das Skript speichert für jede Erstellung einen eigenen Schlüssel im Beleg. Verwenden Sie nach einer verlorenen Antwort denselben Schlüssel, denselben API-Schlüssel und denselben JSON-Inhalt. Ohne diesen Header erstellt jeder Aufruf ein neues Objekt.
• Offerte und alle Positionen entstehen in einer Transaktion: Ein Fehler nimmt die gesamte Erstellung zurück. Eine erfolgreiche Wiederholung trägt Idempotency-Replayed: true. Ein Kontakt behält seine ID und liefert aktuelle Felder; eine Offerte liefert den ursprünglichen Erstellungsbeleg. Lesen Sie das Dokument erneut für den aktuellen Stand.
• Der Wiederholungsschlüssel gilt pro Dossier, API-Schlüssel und Vorgang. Anderer Inhalt oder ein gelöschtes Objekt führt zu 409 ohne Neuerstellung. Belege bleiben bis zur Löschung des Dossiers erhalten. Speichern Sie Fachreferenz, Wiederholungsschlüssel und BMT-IDs zusammen; ein anderer API-Schlüssel ändert auch den Geltungsbereich des Duplikatschutzes.

Antworten verstehen

400

Parameter oder Referenz abgelehnt. Ein SQL-Fehler nimmt diese Erstellung zurück; Kontakt und Offerte bleiben zwei getrennte Vorgänge.

401 / 403

Gültigkeit des Schlüssels, erteilte Rechte und Dossierzugriff prüfen.

402

Schreibzugriffe erfordern einen aktiven Zugang zum Dossier. Prüfen Sie Abonnement oder Testzeitraum.

404

Die Ressource ist in diesem Dossier nicht zugänglich. ID und Umfang prüfen.

409 / 422

Fachlicher Konflikt oder unpassende Referenz. Objekt vor dem nächsten Schritt erneut lesen.

429

retry_after_seconds im Antwortkörper beachten. Bei Erstellungen auch das Ergebnis vor einer Wiederholung prüfen.

5xx / Netzwerk

Das Ergebnis kann ungewiss sein. Das Beispiel wiederholt Erstellungen nie automatisch.

Versionen und Prüfung

Version der Anleitung : 1.1.0

Diese Version bezeichnet die Anleitung und ihren Teilvertrag, nicht sämtliche BMT-APIs. Tests führen die dokumentierten Anfragen gegen REST-Handler mit synthetischer Authentifizierung und Speicherung aus, einschliesslich Ablehnungen und ungewisser Antworten. Vor der Produktion bleibt ein Abnahmetest auf Ihrem Dossier nötig.