Référence développeur
Documentation API
Créez des intégrations avec la plateforme NearbyAssist. Endpoints RESTful, réponses JSON cohérentes et couverture complète pour les réservations, la messagerie, la facturation et plus encore.
URL de base
https://api.nearbyassist.comAuthentification
Token Bearer via l'en-tête Authorization
Limites de requêtes
500 req/15 min (global), 20 req/15 min (endpoints d'authentification)
Format
Requêtes/réponses JSON. Encodage UTF-8. Dates ISO 8601.
Authentification
Tous les endpoints authentifiés nécessitent un token Bearer dans l'en-tête Authorization. Obtenez un token en vous connectant via POST /api/auth/signin. Pour les intégrations partenaires, utilisez une clé API avec l'en-tête 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_..."
Obtenir votre clé API
Générez des clés API depuis le tableau de bord Intégrations. Les clés utilisent le préfixe na_live_ et supportent les permissions limitées (bookings:read, bookings:write, etc.). La clé complète n'est affichée qu'une seule fois à la création.
Authentification
(3 endpoints)Utilisateurs
(3 endpoints)Entreprises
(7 endpoints)Réservations
(8 endpoints)Services
(4 endpoints)Avis et questions
(6 endpoints)Messagerie
(5 endpoints)Facturation et paiements
(6 endpoints)Personnel
(5 endpoints)Intégrations
(7 endpoints)Webhooks
(3 endpoints)Réponses d'erreur
Toutes les erreurs renvoient un corps JSON avec error et un tableau optionnel errors pour les échecs de validation.
{
"error": "Validation failed",
"errors": [
{ "field": "email", "message": "Email is required" },
{ "field": "password", "message": "Minimum 8 characters" }
]
}| Code | Statut | Description |
|---|---|---|
| 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. |
Pagination
Les endpoints de liste supportent la pagination basée sur le curseur avec les paramètres page et limit. La limite par défaut est 20, le maximum est 100.
GET /api/bookings/my-bookings?page=2&limit=10
{
"bookings": [...],
"total": 47,
"page": 2,
"limit": 10
}Événements webhook
Enregistrez des endpoints webhook pour recevoir des notifications en temps réel. Tous les payloads incluent un en-tête X-NearbyAssist-Signature pour la vérification via 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.