API REST para aseguradoras de decesos

Integre la gestión del legado digital post-mortem en sus sistemas: abra casos automáticamente desde sus pólizas, consulte el estado de las cuentas digitales del fallecido, reciba avisos en tiempo real por webhooks y obtenga métricas de siniestralidad. Toda la API trabaja sobre https://defuncia.com/api/v1 (la API Key determina la aseguradora, sin subdominios) y devuelve JSON.

1. Autenticación

Las aseguradoras autentican con API Key en la cabecera X-API-Key. Es el único mecanismo: no hay login con usuario y contraseña ni Bearer/JWT.

2. Obtención de la API Key

Genere su clave desde el backoffice (Configuración). Tiene formato dfk_... y solo se muestra una vez: guárdela en un lugar seguro.

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://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 (el enlace del portal le llega a la familia por email;
# la aseguradora NO recibe el token):
# {"success":true,"data":{"caso_id":"CAS-2026-00042","estado":"abierto",
#   "modulos_contratados":["borrado","suscripciones"],"pack":"personalizado",
#   "acceso_heredero":{"canal":"email","notificado":true,"caduca":"2027-03-30T..."}}}

# POST /api/v1/siniestro — apertura automática desde póliza de decesos
curl -X POST https://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"
    },
    "pack": "basico",
    "prioridad": "urgente",
    "notas_aseguradora": "Cliente premium. Tramitar con prioridad."
  }'

# Respuesta 201: caso_id, módulos del pack y acceso_heredero (sin token).
# Dispara el webhook "siniestro_abierto" y envía a la familia UN email con
# su enlace personal al portal. El siniestro queda en el registro del canal.

# GET /api/v1/casos/{id} — detalle del caso (cuentas + documentos)
curl https://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://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://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 que se envían hoy: caso_abierto, caso_cerrado y siniestro_abierto (solo metadatos, nunca contenidos). Se pueden registrar también documentacion_completa, cuenta_resuelta, modulo_completado y documentacion_recibida, que se enviarán cuando estén disponibles. Reintentos: uno inmediato y cinco más desde la cola (a los 1, 4, 16, 64 y 256 minutos); cuenta como entregado cualquier respuesta 2xx.