Catálogo de servicios

Para qué sirve

El catálogo responde a la pregunta «¿qué puedo pedir?» para tu contrato. Antes de crear avisos, tu integración debe leerlo para saber:

• qué tipos de servicio tienes disponibles (consulta general, urgencias, pediatría, enfermería…) y qué profesional requiere cada uno;
• si tu contrato exige nº de expediente en cada aviso;
• si eres intermediario, para qué aseguradoras finales puedes enviar avisos.

curl "$SERAD_API_URL/catalog" \
  -H "X-Api-Key: $SERAD_API_KEY"

Requiere el ámbito visits:write (es lo que necesita quien crea avisos).

La respuesta

{
  "status": 200,
  "data": {
    "providerType": "INTERMEDIARY",
    "requiresExternalRef": true,
    "serviceTypes": [
      { "id": "57605fe9-bade-4040-b403-5eeb58e57c9e", "code": "GENERAL_CONSULTATION", "name": "Consulta general", "requiredProfessional": "DOCTOR" },
      { "id": "9a1e4c3b-7d2f-4b6a-8e5c-3f2d1c0b9a87", "code": "PEDIATRICS", "name": "Pediatría", "requiredProfessional": "DOCTOR" },
      { "id": "0c7f3a52-3f1d-4b8e-9d6a-2f4b5c6d7e8f", "code": "NURSING_CARE", "name": "Curas de enfermería", "requiredProfessional": "NURSE" }
    ],
    "insurers": [
      { "id": "fe8faeb8-0051-40d5-b0c1-dce10d5f5ba1", "name": "Aseguradora Ejemplo" },
      { "id": "2b7c9d1e-4f3a-4c8b-a6d5-e9f8c7b6a5d4", "name": "Mutua Ejemplo" }
    ]
  },
  "message": "Operación realizada correctamente"
}

Tipos de servicio y profesional requerido

Los tipos de servicio que ves son los que tienen precio en tu tarifa vigente. Si pides uno que no está en tu catálogo, el alta responde 400 con el tipo /errors/provider/service-type-not-allowed. Si necesitas un servicio que no aparece, habla con nosotros: es un cambio de contrato, no de integración.

requiredProfessional te dice qué tipo de unidad irá al domicilio:

• DOCTOR: unidad médica (médico y conductor). Consulta, urgencias no vitales, pediatría…
• NURSE: unidad de enfermería. Curas, inyectables, controles, retirada de puntos o sondas…

Úsalo para guiar a quien da de alta el aviso en tu sistema (por ejemplo, para no ofrecer «curas» cuando el motivo es «fiebre alta»). Cuando el aviso se asigna, el webhook y la consulta del aviso indican el tipo de unidad (unitType / unit.type: MEDICAL o NURSING).

Aseguradoras finales (intermediarios)

Si eres un intermediario (providerType: "INTERMEDIARY"), trabajas para varias aseguradoras y cada aviso es de un asegurado de una de ellas. Indícala en el alta con insurerId, tomado de insurers[]:

{
  "insurerId": "fe8faeb8-0051-40d5-b0c1-dce10d5f5ba1",
  "serviceTypeCode": "GENERAL_CONSULTATION",
  "…": "…"
}

• El insurerId tiene que ser una de tus aseguradoras; si no, 400 con el tipo /errors/provider/insurer-not-managed.
• Si no eres intermediario, no envíes insurerId: responde el mismo 400.
• Los id de las aseguradoras cambian entre entornos. Léelos del catálogo de cada entorno (por nombre) en vez de copiarlos.

Nº de expediente obligatorio

Si requiresExternalRef es true, tu contrato exige que cada aviso lleve tu nº de expediente (externalRef, hasta 100 caracteres). Sin él, el alta responde 400 con el tipo /errors/visits/external-ref-required.

Aunque no sea obligatorio, te recomendamos enviarlo siempre: es lo que relaciona el aviso con tu sistema, aparece en tus facturas, en los webhooks y en el portal, y permite buscar el aviso con GET /visits?externalRef=… sin guardar nuestro id.

Cada cuánto leerlo

El catálogo cambia poco (cuando cambia tu tarifa o tus aseguradoras). Lo razonable es:

• leerlo al arrancar tu integración y guardarlo en caché;
• refrescarlo una vez al día;
• y volver a leerlo si un alta responde service-type-not-allowed o insurer-not-managed, por si ha cambiado.

No hace falta leerlo antes de cada alta.