Arranca la API
Inicia el servicio y confirma su disponibilidad con el endpoint de salud.
01 · PRIMEROS PASOS
Empieza con una petición
La API responde JSON y usa la URL base del entorno actual. Elige el tipo de acceso correcto antes de integrar recursos protegidos.
Obtén credenciales
Usa X-API-Key para integraciones o inicia sesión en el Portal para recibir un JWT.
Haz la primera petición
Prueba una ruta pública y continúa con los recursos que necesitas.
# Comprueba que el servicio está disponible curl -sS "/api/health" # Consulta un recurso con una API Key curl -sS "/api/affiliates?page=1" \ -H "X-API-Key: TU_API_KEY"
02 · SEGURIDAD
Autenticación
Cada endpoint declara el acceso que necesita. Nunca expongas claves o tokens en código cliente público.
| Tipo | Cuándo usarlo | Header exacto | Ejemplo |
|---|---|---|---|
| Público | Salud, documentación y acceso inicial. | — | GET /api/health |
| API Key | Integraciones de servidor y recursos administrativos. | X-API-Key: TU_API_KEY | curl -H "X-API-Key: …" |
| JWT | Sesiones de pacientes autenticados. | Authorization: Bearer TU_JWT | curl -H "Authorization: Bearer …" |
03 · CONTRATO DE RESPUESTA
Convenciones
Respuestas
Éxito: { success: true, data }. Error: { success: false, error, reason?, requestId? }.
Paginación
Los recursos paginados aceptan ?page=1. El límite es fijo: 10 registros por página.
Edad y fechas
Cuando se indique age, se calcula desde el campo de fecha documentado; conserva el formato de fecha esperado por el recurso.
Rate limits y trazabilidad. Respeta los límites devueltos por el servicio. Ante un error, incluye el
requestId al solicitar soporte para facilitar el seguimiento.04 · RESPUESTAS HTTP
Códigos de error
| Código | Cuándo ocurre |
|---|---|
| 400 | Parámetros, cuerpo o formato de datos inválidos. |
| 401 | Falta una credencial válida o el token expiró. |
| 403 | La credencial es válida, pero no tiene permiso para la operación. |
| 404 | La ruta o el recurso solicitado no existe. |
| 409 | La operación entra en conflicto con el estado actual del recurso. |
| 429 | Se excedió el límite de solicitudes; espera antes de reintentar. |
| 500 | Error interno no previsto. |
| 501 | La operación aún no está implementada en el servidor. |
| 502 | Falló un proveedor o servicio aguas arriba, como SMTP. |
| 503 | Servicio temporalmente no disponible o en mantenimiento. |
05 · CATÁLOGO VIVO
Explorador de endpoints
Filtra el catálogo, genera comandos cURL y prueba rutas directamente desde esta página. La API Key se guarda solo durante esta sesión del navegador.
Cargando catálogo…
06 · CASOS DE USO
Guías detalladas
Correos bulk
Envía multipart/form-data a POST /api/emails/bulk. Incluye recipients y al menos copy o image; subject es opcional. Usa dry_run=true para validar sin entregar correos.
curl -X POST "/api/emails/bulk" \ -H "X-API-Key: TU_API_KEY" \ -F 'recipients=["cliente@ejemplo.com"]' \ -F 'subject=Información Integracorp' \ -F 'copy=Mensaje de prueba' \ -F 'dry_run=true'
Respuestas: 200 envío/procesamiento exitoso, 400 destinatarios o campos inválidos, 502 fallo del proveedor SMTP.
Consulta la disponibilidad con GET /api/notifications/whatsapp/status. Para lotes, POST /api/notifications/mass/send-batch recibe hasta 50 destinatarios y responde 202 Accepted cuando el lote queda en cola.
{
"channel": "whatsapp",
"recipients": ["584120000000", "584140000000"],
"title": "Información",
"copy": "Mensaje de campaña",
"delay_ms": 2500
}Configura una pausa prudente entre mensajes; el retraso progresivo ayuda a evitar bloqueos por comportamiento automatizado.
Recursos paginados
Solicita ?page=1; cada página contiene hasta 10 registros. Usa los valores de pagination para navegar sin suponer cuántas páginas existen.
{
"success": true,
"data": [{ "id": 1, "name": "…" }],
"pagination": {
"page": 1, "limit": 10,
"total": 42, "totalPages": 5
}
}Portal paciente
El flujo es: iniciar sesión (cédula + clave) → recibir JWT → enviar el Bearer → consultar perfil o registrar historia. El portal maneja este intercambio de forma interactiva.
POST /api/auth/login
{ "nro_identificacion": "V-12345678", "password": "clave-del-portal" }
Authorization: Bearer <token>
GET /api/me/profile
GET /api/clinical-history
POST /api/clinical-history # onboarding; 409 si ya existe