Notificación de recetas

Cuando un médico genera una receta electrónica, esta pasa por diferentes etapas, y en cada una de ellas Osigu puede generar una notificación, estas etapas son:

Receta emitida
PDF de receta generado
PDF de receta firmada electrónicamente
Envío de receta al paciente
Receta anulada

Para esta funcionalidad, el cliente deberá proveer de un servicio web que actué como webhook y este deberá de cumplir con las siguientes características:

Ambientes

El cliente deberá proveer a Osigu de dos ambientes, un ambiente de pruebas o sandbox y un ambiente productivo. La conexión a los dos ambientes únicamente puede darse únicamente bajo el protocolo HTTPS.

Autenticación

Para consumir el servicio web debe de existir un mecanismo de autenticación a través de un header y un valor determinado por cliente. El cliente deberá proveer para la autenticación en cada uno de los ambientes lo siguiente:

Nombre del header
API token a utilizar

Request y Request Body

El verbo HTTP a utilizar es POST, y el servicio a consumir por parte de Osigu debe de tener los siguientes atributos, estos no pueden variar en ninguna forma de nombre o de tipo. Osigu enviará la información dentro del request body como JSON codificado en UTF8.

Nombre	Tipo	Descripción
event	String, requerido	Tipo de evento que se esta notificando. Los posibles eventos son: `PRESCRIPTION_CREATED`, `PDF_RENDERED`, `PDF_SIGNED`, `EMAIL_SENT`, `PRESCRIPTION_VOIDED`.
prescription_id	Long, requerido	ID de la receta electrónica asignada por Osigu.
prescription_document_id	String, requerido	Código alfanumérico del documento.
prescription_document_code	String, requerido	Código alfanumérico del documento.
type	String, requerido	Indica si el evento es sobre una receta de medicamentos, indicación de exámenes de diagnóstico o bien de procedimientos médicos. Los posibles valores son `PRESCRIPTION`, `DIAGNOSTIC_TEST_INDICATION`, `MEDICAL_PROCEDURE_INDICATION`.
doctor_id	Long, requerido	Identificador del doctor que ha generado la receta. Este es el identificador asignado por Osigu.
external_provider_id	String, opcional	Identificador externo del doctor, si el cliente no provee este dato durante el proceso de registro del médico, este valor será NULO.
created_at	String	Fecha en que ocurrió el evento, esta cadena de texto contiene la fecha en formato ISO 8601.

{
  "event": "PRESCRIPTION_CREATED",
  "prescription_id": 3902,
  "prescription_document_id": 23940,
  "prescription_document_code": "RC-234ABV3J",
  "type": "PRESCRIPTION",
  "doctor_id": 223,
  "external_provider_id": "ea6d5dca-ae1b-4ca0-a565-818d9791094a",
  "created_at": "2022-06-02T09:00:20.382Z"
}

HTTP Code y Response Body

El servicio debe de responder con los siguientes códigos HTTP y cuerpos de la respuesta.

HTTP 204

Se debe de utilizar este código cuando la notificación ha sido exitosa, este código indica que no se obtiene ningún dato adicional en el response body.

HTTP 4xx

Todos los errores a la hora de consumir el servicio que ha ocurrido por un error en la solicitud, deberán retornar cualquiera de los códigos 4xx. Por ejemplo un 400 si el JSON esta mal formado o un 401 si la autenticación fue fallida.

Cualquiera de los códigos 4xx debe de incluir el siguiente cuerpo de respuesta.

Nombre	Tipo	Descripción
code	String, requerido	Código de error del cliente. Este código de error será utilizado para casos de soporte durante la implementación o errores obtenidos ya en la puesta en producción.
message	String, requerido	Mensaje correspondiente al código de error recibido.

{
  "code": "3920-A39",
  "message": "Authentication failed"  
}

HTTP 5xx

Cualquier respuesta 5xx indicará un error no controlado por parte del cliente y las notificaciones que obtengan este tipo de error entrarán al sistema de colas para realizar hasta 10 re-intentos con diferencia de minutos en cada uno.

Al igual que los códigos 4xx, estos mensajes de error deben de contener un campo de código y uno de mensaje los cuales pueden ser útiles para temas de soporte.

Eventos

Los eventos a ser notificados son:

Evento	Descripción
PRESCRIPTION_CREATED	Este evento se emite cuando una receta ha sido recientemente creada por el médico, pero el documento PDF que se envía al paciente aún no esta listo.
PDF_RENDERED	El documento PDF de la receta ha sido generado, en este punto la receta ya puede descargarse. Los países cuya regulación requieren una receta electrónica, en este punto el documento no es válido para su dispensación.
PDF_SIGNED	El documento PDF de la receta ha sido firmado electrónicamente y esta listo para ser enviado al paciente. Este evento solo se emite para aquellos países donde la regulación requiere de una firma electrónica.
EMAIL_SENT	El correo electrónico al paciente ha sido enviado, este evento sucede posterior a la solicitud que se realiza al sistema de envíos de correo.
PRESCRIPTION_VOIDED	Este evento se emite cuando el doctor ha anulado una receta.