Referencia para desarrolladores
Documentación API
Crea integraciones con la plataforma NearbyAssist. Endpoints RESTful, respuestas JSON consistentes y cobertura completa para reservas, mensajería, facturación y más.
URL base
https://api.nearbyassist.comAutenticación
Token Bearer a través del encabezado Authorization
Límites de solicitudes
500 req/15 min (global), 20 req/15 min (endpoints de autenticación)
Formato
Solicitudes/respuestas JSON. Codificación UTF-8. Fechas ISO 8601.
Autenticación
Todos los endpoints autenticados requieren un token Bearer en el encabezado Authorization. Obtén un token iniciando sesión a través de POST /api/auth/signin. Para integraciones de socios, usa una clave API con el encabezado 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_..."
Obtén tu clave API
Genera claves API desde el panel de Integraciones. Las claves usan el prefijo na_live_ y soportan permisos con alcance limitado (bookings:read, bookings:write, etc.). La clave completa solo se muestra una vez en la creación.
Autenticación
(3 endpoints)Usuarios
(3 endpoints)Negocios
(7 endpoints)Reservas
(8 endpoints)Servicios
(4 endpoints)Reseñas y preguntas
(6 endpoints)Mensajería
(5 endpoints)Facturación y pagos
(6 endpoints)Personal
(5 endpoints)Integraciones
(7 endpoints)Webhooks
(3 endpoints)Respuestas de error
Todos los errores devuelven un cuerpo JSON con error y un array opcional errors para fallos de validación.
{
"error": "Validation failed",
"errors": [
{ "field": "email", "message": "Email is required" },
{ "field": "password", "message": "Minimum 8 characters" }
]
}| Código | Estado | Descripción |
|---|---|---|
| 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. |
Paginación
Los endpoints de lista soportan paginación basada en cursor usando los parámetros page y limit. El límite por defecto es 20, el máximo es 100.
GET /api/bookings/my-bookings?page=2&limit=10
{
"bookings": [...],
"total": 47,
"page": 2,
"limit": 10
}Eventos de webhook
Registra endpoints webhook para recibir notificaciones en tiempo real. Todos los payloads incluyen un encabezado X-NearbyAssist-Signature para verificación usando 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.