Entornos de producción y pruebas

Dos entornos separados

La API existe en dos entornos completamente independientes: dos despliegues distintos de la misma API, cada uno con su propia base de datos. Lo que haces en uno no aparece nunca en el otro.

Las rutas, los campos, los errores y los webhooks son exactamente iguales en los dos entornos: el código que funciona contra el sandbox funciona contra producción cambiando solo la URL base, la clave y el secreto del webhook.

La clave decide el entorno

Cada clave pertenece a un entorno. Si usas una clave contra el entorno equivocado, la API responde 401 con el tipo /errors/provider-api/wrong-environment y un mensaje que lo dice claramente («Estás usando una clave de pruebas contra producción»), para que no lo confundas con una clave mal copiada:

{
  "type": "/errors/provider-api/wrong-environment",
  "title": "Clave de otro entorno",
  "status": 401,
  "detail": "Estás usando una clave de pruebas contra producción",
  "instance": "/api/integrations/v1/visits",
  "timestamp": "2026-10-01T09:10:00.000Z"
}

La cabecera X-Serad-Environment

Todas las respuestas de la API, también las de error, llevan la cabecera X-Serad-Environment con el valor production o sandbox. Úsala para:

• Registrar en tus logs contra qué entorno se hizo cada llamada.
• Proteger tus pruebas automáticas: si un test de integración recibe production, que falle inmediatamente.
• Mostrarlo en tus pantallas internas («Conectado a: pruebas») para que nadie dé de alta avisos reales creyendo que son de prueba, ni al revés.

curl -sI "https://sandbox-api.saludenruta.es/api/integrations/v1/catalog" -H "X-Api-Key: $SERAD_API_KEY" | grep -i x-serad-environment
# X-Serad-Environment: sandbox

Los identificadores cambian entre entornos

Los id de los avisos, de los tipos de servicio y de las aseguradoras no coinciden entre producción y sandbox: son bases de datos distintas, y cada una genera los suyos. Un serviceTypeId copiado del sandbox no existe en producción.

Por eso:

• Usa siempre códigos, no ids, para los datos de catálogo. Al crear un aviso, envía serviceTypeCode (por ejemplo, GENERAL_CONSULTATION) en vez de serviceTypeId. Los códigos son los mismos en los dos entornos.
• Lee el catálogo de cada entorno al arrancar tu integración (o una vez al día) y guárdalo en caché, en lugar de escribir ids en tu código o en tu configuración.
• Guarda los id de los avisos junto al entorno en tu base de datos, o en tablas separadas. Un aviso del sandbox no se puede consultar en producción.
• Relaciona los avisos con tu sistema por tu nº de expediente (externalRef), que es tuyo y no depende del entorno.

Lista de comprobación para pasar a producción

Antes de pedir tu clave de producción, comprueba en el sandbox que tu integración cumple todo esto. Lo repasaremos contigo en la validación.

Configuración

• La URL base, la clave y el secreto del webhook se leen de la configuración del entorno (variables de entorno o gestor de secretos), no están en el código.
• Tus pruebas automáticas comprueban que X-Serad-Environment es sandbox.
• El tipo de servicio se envía con serviceTypeCode, y el catálogo se lee de la API.
• La clave solo se usa desde tu servidor (nunca en un navegador ni en una app).

Avisos

• Envías una Idempotency-Key única por cada alta y la reutilizas en los reintentos (idempotencia).
• Envías el nº de expediente (externalRef) si tu catálogo dice requiresExternalRef: true.
• Distingues los avisos urgentes, normales y con cita, y las citas usan scheduledFrom y estimatedMinutes (avisos).
• Sabes cancelar un aviso y gestionas el 409 cuando ya no se puede (cancelar).

Webhooks

• Verificas la firma de cada entrega con el cuerpo crudo y rechazas las que no cuadran o tienen más de 300 s (firma).
• Respondes 2xx en menos de 10 s y procesas después, en segundo plano.
• Descartas los eventos repetidos por su id (no por X-Serad-Delivery, que cambia en un reenvío manual) (idempotencia del receptor).
• Tu receptor aguanta que los eventos lleguen fuera de orden (usa los milestones, no el orden de llegada).

Errores y límites

• Tratas los errores por su status y su type (errores), y registras el detail y el instance.
• Ante un 429 esperas lo que dice Retry-After, y ante un 5xx reintentas con espera exponencial (límites de uso).
• Un fallo de la API no bloquea tu operativa: si no puedes enviar un aviso urgente, tu equipo sabe que puede llamar a la centralita (+34 611 673 280).

Cuando todo esté en verde, escríbenos para la validación.