sp_...) en todas las consultas, en lugar de reenviar los campos de identificación cada vez.
Los campos de identificación (name, idCountry, idType, idValue) son los mismos que usa set-consultation-context y siguen las mismas reglas de validación; consulta Documentos aceptados por país.
El acceso a los pacientes está limitado según el rol de tu API key: una clave de médico solo ve sus propios pacientes; una clave institucional ve todos los pacientes de su institución. Nunca necesitas enviar un id de cuenta o de institución: el alcance se aplica en el servidor.
Crear un paciente
POST /v1/patients requiere name, idCountry, idType e idValue. El idType debe ser válido para el idCountry dado (p. ej., CC con idCountry: BR devuelve 400).
internalCode es opcional. Es tu propio identificador para el paciente, único dentro de tu institución. Envíalo al crear el paciente y luego consulta el paciente o lista sus sesiones con ese código. Volver a enviar el mismo documento de identidad actualiza el paciente en lugar de duplicarlo. Si omites internalCode, se conserva el valor que ya estuviera guardado.
Listar pacientes
GET /v1/patients devuelve los pacientes visibles para tu API key, del más reciente al más antiguo. Pagina con page (base 1) y limit (1–50, por defecto 20).
total y totalPages solo se calculan en la primera página: son null en las páginas siguientes para evitar un recorrido completo en cada cambio de página. Usa hasMore para paginar de forma confiable; es exacto en todas las páginas.Consultar un paciente
GET /v1/patients/{patient_id} busca un único paciente. El {patient_id} puede ser el id público (sp_...) o el internalCode que definiste para tu institución. Devuelve 404 si tu API key no tiene visibilidad sobre ningún paciente con ese id.
idCountry, idType e idValue pueden ser null en pacientes creados fuera de esta API que no tienen identificación.Actualizar un paciente
PATCH /v1/patients/{patient_id} actualiza el name o el internalCode de un paciente, por su id público (sp_...) o internalCode. El documento de identidad (idCountry/idType/idValue) no se puede editar aquí. Omite un campo para dejarlo sin cambios; envía internalCode como null para borrarlo. Devuelve 404 si tu API key no tiene visibilidad sobre ningún paciente con ese id, y 409 si el internalCode ya lo usa otro paciente de tu institución.
Eliminar un paciente
DELETE /v1/patients/{patient_id} elimina un paciente por su id público (sp_...) o internalCode. Úsalo para atender solicitudes de supresión de datos (derecho al olvido). Devuelve 204 si la operación es exitosa y 404 si tu API key no tiene visibilidad sobre ningún paciente con ese id.
Una eliminación exitosa devuelve
204 con un cuerpo vacío. Un paciente eliminado deja de aparecer en los endpoints de listado y consulta.