Dokumentacja dla programistów
Dokumentacja API
Twórz integracje z platformą NearbyAssist. Endpointy RESTful, spójne odpowiedzi JSON i pełne pokrycie dla rezerwacji, wiadomości, rozliczeń i nie tylko.
Bazowy URL
https://api.nearbyassist.comUwierzytelnianie
Token Bearer przez nagłówek Authorization
Limity żądań
500 req/15 min (globalnie), 20 req/15 min (endpointy auth)
Format
Żądania/odpowiedzi JSON. Kodowanie UTF-8. Daty ISO 8601.
Uwierzytelnianie
Wszystkie uwierzytelnione endpointy wymagają tokenu Bearer w nagłówku Authorization. Token uzyskasz logując się przez POST /api/auth/signin. W przypadku integracji partnerskich użyj klucza API z nagłówkiem X-API-Key.
# Session token (user authentication)
curl https://api.nearbyassist.com/api/users/profile \
-H "Authorization: Bearer <access_token>"
# API key (partner integration)
curl https://api.nearbyassist.com/api/integrations/partner/bookings \
-H "X-API-Key: na_live_..."
Uzyskaj swój klucz API
Generuj klucze API z panelu Integracje. Klucze używają prefiksu na_live_ i obsługują ograniczone uprawnienia (bookings:read, bookings:write itp.). Pełny klucz jest wyświetlany tylko raz podczas tworzenia.
Uwierzytelnianie
(3 endpointów)Użytkownicy
(3 endpointów)Firmy
(7 endpointów)Rezerwacje
(8 endpointów)Usługi
(4 endpointów)Recenzje i pytania
(6 endpointów)Wiadomości
(5 endpointów)Rozliczenia i płatności
(6 endpointów)Personel
(5 endpointów)Integracje
(7 endpointów)Webhooks
(3 endpointów)Odpowiedzi błędów
Wszystkie błędy zwracają ciało JSON z error i opcjonalną tablicą errors dla błędów walidacji.
{
"error": "Validation failed",
"errors": [
{ "field": "email", "message": "Email is required" },
{ "field": "password", "message": "Minimum 8 characters" }
]
}| Kod | Status | Opis |
|---|---|---|
| 200 | OK | Request succeeded. |
| 201 | Created | Resource created successfully. |
| 400 | Bad Request | Invalid request body or query parameters. |
| 401 | Unauthorized | Missing or invalid authentication token. |
| 403 | Forbidden | Authenticated but lacking permission for this resource. |
| 404 | Not Found | Resource does not exist. |
| 409 | Conflict | Resource conflict (e.g. duplicate booking slot). |
| 422 | Unprocessable Entity | Validation failed. Check the errors array in the response. |
| 429 | Too Many Requests | Rate limit exceeded. Retry after the Retry-After header value. |
| 500 | Internal Server Error | Unexpected error. Contact support if persistent. |
Paginacja
Endpointy list obsługują paginację opartą na kursorze z parametrami page i limit. Domyślny limit to 20, maksimum to 100.
GET /api/bookings/my-bookings?page=2&limit=10
{
"bookings": [...],
"total": 47,
"page": 2,
"limit": 10
}Zdarzenia webhook
Rejestruj endpointy webhook, aby otrzymywać powiadomienia w czasie rzeczywistym. Wszystkie payloady zawierają nagłówek X-NearbyAssist-Signature do weryfikacji za pomocą HMAC-SHA256.
booking.createdA new booking is confirmed.booking.updatedBooking status or time changed.booking.cancelledA booking was cancelled.lead.receivedNew lead available for your business.lead.acceptedA lead was accepted and charged.review.createdNew review posted for your business.message.receivedInbound message from any channel.payment.completedA payment was processed successfully.// Verify webhook signature
const crypto = require('crypto');
const signature = req.headers['x-nearbyassist-signature'];
const expected = crypto
.createHmac('sha256', webhookSecret)
.update(JSON.stringify(req.body))
.digest('hex');
if (signature !== expected) {
return res.status(401).json({ error: 'Invalid signature' });
}Integration Guide
Step-by-step walkthrough for OAuth, API keys, and common integration scenarios.
OpenAPI Spec
Download the OpenAPI 3.0 YAML spec. Import into Swagger UI or code generators.
Postman Collection
Pre-configured Postman collection with all endpoints ready to test.
Need help integrating?
Our developer support team is available to help with integration questions, debugging, and best practices.