Pierwsze kroki
Od klucza API do pierwszego żądania i pierwszego webhooka — w pięć minut.
Jeden klucz API otwiera trzy powierzchnie: REST API, serwer MCP i webhooki. Poniżej przechodzisz przez wszystkie trzy.
Bazowy adres to zawsze:
https://app.mediflo.ai/api/external/v1Wygeneruj klucz API
W Portalu wejdź w Ustawienia → Integracje → Klucze API i kliknij Wygeneruj nowy klucz API. Nadaj mu nazwę i zaznacz zakresy.
Klucz zobaczysz tylko raz
Pełny klucz jest pokazywany jednorazowo, zaraz po utworzeniu. Skopiuj go od razu do menedżera sekretów albo do zmiennej środowiskowej. Później nie da się go odczytać — można go tylko zrotować.
Zaznacz minimalny zestaw zakresów, jakiego potrzebuje Twoja integracja. Dla tego przewodnika wystarczą dwa:
| Zakres | Po co |
|---|---|
bots.read | Odczyt botów głosowych, ich konfiguracji, przepływów i gotowości |
webhooks.manage | Zarządzanie punktami końcowymi webhooków i podgląd dostarczeń |
Więcej o zakresach i o tym, dlaczego bot-calls.write i webhook-payloads.read trzeba nazwać wprost: Zakresy.
Wykonaj pierwsze żądanie
Klucz wędruje w nagłówku Authorization ze schematem Bearer:
curl -s https://app.mediflo.ai/api/external/v1/bots \
-H "Authorization: Bearer mflo_live_..." \
-H "Content-Type: application/json"Odpowiedź to lista w standardowej kopercie { data, pagination }:
{
"data": [
{
"id": "a1b2c3d4-1111-2222-3333-444455556666",
"name": "Potwierdzanie wizyt",
"description": null,
"isActive": true,
"priority": 0,
"maxConcurrentCalls": 5,
"country": "PL",
"locationId": "0d1e2f30-1111-2222-3333-444455556666",
"location": { "id": "0d1e2f30-1111-2222-3333-444455556666", "name": "Przychodnia Centrum" },
"phoneNumberId": null,
"phoneNumber": null,
"currentConfigSnapshotId": "9a8b7c6d-1111-2222-3333-444455556666",
"operatingHours": [],
"createdAt": "2026-08-20T09:00:00.000Z",
"updatedAt": "2026-09-01T11:42:00.000Z"
}
],
"pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}Dostałeś 401? Klucz jest nieznany, wygasł albo został unieważniony. 403 z kodem API_KEY_INSUFFICIENT_SCOPE znaczy, że klucz jest dobry, ale brakuje mu zakresu — details mówi którego. Pełna lista: Błędy.
Zarejestruj webhook i wyślij zdarzenie testowe
Zamiast odpytywać API w pętli, zarejestruj endpoint HTTPS, na który wypchniemy zdarzenia:
curl -s -X POST https://app.mediflo.ai/api/external/v1/webhook-endpoints \
-H "Authorization: Bearer mflo_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://twoj-system.example.com/mediflo",
"description": "Integracja produkcyjna",
"subscribedEvents": ["bot_call.completed"]
}'201 zwraca endpoint razem z sekretem podpisującym:
{
"data": {
"id": "7c9e6679-1111-2222-3333-444455556666",
"url": "https://twoj-system.example.com/mediflo",
"description": "Integracja produkcyjna",
"subscribedEvents": ["bot_call.completed"],
"payloadConfig": null,
"status": "ENABLED",
"consecutiveFailures": 0,
"lastSuccessAt": null,
"lastFailureAt": null,
"autoDisabledAt": null,
"previousSecretExpiresAt": null,
"secret": "whsec_...",
"createdAt": "2026-09-07T08:00:00.000Z",
"updatedAt": "2026-09-07T08:00:00.000Z"
}
}Sekret też pokazujemy raz
secret jest w odpowiedzi jeden jedyny raz. Zapisz go, zanim zamkniesz połączenie — służy do weryfikacji podpisu Mediflo-Signature i nie da się go odczytać ponownie.
Teraz wyślij zdarzenie testowe przez tę samą, prawdziwą ścieżkę dostarczania:
curl -s -X POST \
https://app.mediflo.ai/api/external/v1/webhook-endpoints/7c9e6679-1111-2222-3333-444455556666/test \
-H "Authorization: Bearer mflo_live_..." \
-H "Content-Type: application/json" \
-d '{ "eventType": "bot_call.completed" }'Odpowiedź 202 — dostarczenie trafiło do kolejki:
{ "data": { "deliveryId": "3f2e1d0c-1111-2222-3333-444455556666", "eventType": "bot_call.completed" } }Dostarczenie testowe niesie nagłówek Mediflo-Event-Test: true — prawdziwe zdarzenia go nie mają. Szczegóły i sposób odfiltrowania ruchu testowego: Testowanie webhooków.