Riferimento per sviluppatori
Documentazione API
Crea integrazioni con la piattaforma NearbyAssist. Endpoint RESTful, risposte JSON coerenti e copertura completa per prenotazioni, messaggistica, fatturazione e altro.
URL base
https://api.nearbyassist.comAutenticazione
Token Bearer tramite l'intestazione Authorization
Limiti di richiesta
500 req/15 min (globale), 20 req/15 min (endpoint di autenticazione)
Formato
Richieste/risposte JSON. Codifica UTF-8. Date ISO 8601.
Autenticazione
Tutti gli endpoint autenticati richiedono un token Bearer nell'intestazione Authorization. Ottenere un token accedendo tramite POST /api/auth/signin. Per le integrazioni con i partner, utilizzare una chiave API con l'intestazione 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_..."
Ottieni la tua chiave API
Genera chiavi API dal dashboard Integrazioni. Le chiavi utilizzano il prefisso na_live_ e supportano permessi limitati (bookings:read, bookings:write, ecc.). La chiave completa viene mostrata solo una volta alla creazione.
Autenticazione
(3 endpoint)Utenti
(3 endpoint)Attività
(7 endpoint)Prenotazioni
(8 endpoint)Servizi
(4 endpoint)Recensioni e domande
(6 endpoint)Messaggistica
(5 endpoint)Fatturazione e pagamenti
(6 endpoint)Personale
(5 endpoint)Integrazioni
(7 endpoint)Webhook
(3 endpoint)Risposte di errore
Tutti gli errori restituiscono un corpo JSON con error e un array opzionale errors per i fallimenti di validazione.
{
"error": "Validation failed",
"errors": [
{ "field": "email", "message": "Email is required" },
{ "field": "password", "message": "Minimum 8 characters" }
]
}| Codice | Stato | Descrizione |
|---|---|---|
| 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. |
Paginazione
Gli endpoint elenco supportano la paginazione basata su cursore tramite i parametri page e limit. Il limite predefinito è 20, il massimo è 100.
GET /api/bookings/my-bookings?page=2&limit=10
{
"bookings": [...],
"total": 47,
"page": 2,
"limit": 10
}Eventi webhook
Registra endpoint webhook per ricevere notifiche in tempo reale. Tutti i payload includono un'intestazione X-NearbyAssist-Signature per la verifica tramite 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.