API REST para aseguradoras de decesos

Integra la gestión del legado digital post-mortem en tus sistemas: abre casos automáticamente desde tus pólizas, consulta el estado de las cuentas digitales del fallecido, recibe notificaciones en tiempo real vía webhooks y obtén métricas de siniestralidad. Toda la API trabaja sobre https://{tenant}.defuncia.com/api/v1 y devuelve JSON.

1. Autenticación

Las aseguradoras autentican con API Key en la cabecera X-API-Key. Operadores y admins usan JWT Bearer tras POST /auth/login.

2. Obtención de la API Key

Genera tu key desde el backoffice (Configuración). Tiene formato dfk_... y solo se muestra una vez; guárdala de forma segura.

3. Formato de respuesta

Siempre un envoltorio uniforme: {"success":true,"data":...} o {"success":false,"error":"..."}.

4. Rate limiting

1000 peticiones/hora por API Key. Cabeceras X-RateLimit-* en cada respuesta; 429 al exceder con Retry-After.

Ejemplos rápidos (cURL)

# POST /api/v1/casos — crear un caso de gestión post-mortem
curl -X POST https://demo.defuncia.com/api/v1/casos \
  -H "X-API-Key: dfk_tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "fallecido": {
      "nombre": "Manuel",
      "apellidos": "Rodríguez Sáez",
      "dni": "12345678Z",
      "fecha_fallecimiento": "2026-05-30"
    },
    "heredero": {
      "nombre": "Lucía",
      "apellidos": "Rodríguez Pons",
      "email": "lucia.rodriguez@example.com",
      "telefono": "+34600112233",
      "parentesco": "hija"
    },
    "poliza_numero": "DEC-2025-558721",
    "modulos_contratados": ["borrado", "suscripciones"]
  }'

# Respuesta 201:
# {"success":true,"data":{"caso_id":"CAS-2026-00042","estado":"abierto",
#   "portal_url":"https://demo.defuncia.com/portal/?token=...","token_heredero":"..."}}

# POST /api/v1/siniestro — apertura automática desde póliza de decesos
curl -X POST https://demo.defuncia.com/api/v1/siniestro \
  -H "X-API-Key: dfk_tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "poliza_numero": "DEC-2025-558721",
    "fallecido": {
      "nombre": "Manuel",
      "apellidos": "Rodríguez Sáez",
      "dni": "12345678Z",
      "fecha_fallecimiento": "2026-06-01"
    },
    "heredero": {
      "nombre": "Lucía",
      "apellidos": "Rodríguez Pons",
      "email": "lucia.rodriguez@example.com",
      "telefono": "+34600112233",
      "parentesco": "hija"
    },
    "modulos": ["borrado", "suscripciones", "certificados"],
    "prioridad": "urgente",
    "notas_aseguradora": "Cliente premium. Tramitar con prioridad."
  }'

# Respuesta 201: incluye caso_id, portal_url, token_heredero y dispara
# el webhook "siniestro_abierto" + email de bienvenida al heredero.

# GET /api/v1/casos/{id} — detalle del caso (cuentas + documentos)
curl https://demo.defuncia.com/api/v1/casos/CAS-2026-00042 \
  -H "X-API-Key: dfk_tu_api_key_aqui"

# GET /api/v1/casos/{id}/cuentas — estado de cada cuenta digital
curl https://demo.defuncia.com/api/v1/casos/CAS-2026-00042/cuentas \
  -H "X-API-Key: dfk_tu_api_key_aqui"

# GET /api/v1/reporting — métricas de siniestralidad del periodo
curl "https://demo.defuncia.com/api/v1/reporting?desde=2026-01-01&hasta=2026-06-30" \
  -H "X-API-Key: dfk_tu_api_key_aqui"

# Al registrar un webhook recibes un "secret" (solo una vez).
# Cada entrega llega como POST con las cabeceras:
#   X-Webhook-Signature: sha256={hmac}
#   X-Webhook-Event: {evento}
# La firma = HMAC-SHA256(cuerpo_json_crudo, secret).

# --- Verificación en PHP (en tu endpoint receptor) ---
$cuerpo   = file_get_contents('php://input');
$firma    = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$esperada = 'sha256=' . hash_hmac('sha256', $cuerpo, $TU_SECRET);

if (!hash_equals($esperada, $firma)) {
    http_response_code(401);
    exit('Firma inválida');
}
// Firma válida: procesar el evento
$evento = json_decode($cuerpo, true);
// $evento['evento'], $evento['data'], $evento['timestamp']

Eventos de webhook disponibles: caso_abierto, caso_cerrado, documentacion_completa, cuenta_resuelta, siniestro_abierto, modulo_completado y documentacion_recibida. Reintentos: 3 con backoff exponencial; se considera entregado ante cualquier respuesta 2xx.