Ayuda en linea de SUAP

La creación de recursos es mediante el método POST. La dirección a la que hay que realizar el post es como una URI pero sin el tokenpuesto que no lo tendremos. Por ejemplo si deseamos crear una orden para autorizar, la dirección del post sería URI BASE + ordenes. En el entorno de testing nos queda:

Un request mediante POSTmas un contenido en esa dirección puede terminar en una orden autorizada. En términos generales un POSTa una dirección de recurso puede instanciar un recurso en suap. Existe la posibilidad de que no ocurra esto ya que puede haber errores o datos incompletos.

• Política de persistencia. Si la respuesta del POST contiene una sección REST con una clave token y un valor diferente de null, entonces el recurso se persistió. Su URI será exactamente la misma del POST + el token.

En términos formales el contenido del POST es un JSON con los atributos del recurso que el consumidor desea crear. Dicho JSON está estructurado en dos grandes secciones que representan dos políticas diferentes de como se referencia la información dentro de suap. Una sección es REST y la otra sección es SEARCH.

En esta sección se indican los atributos con su valor y los recursos relacionados mediante su URI. Por ejemplo, en una orden, la fecha de realización es un atributo cuyo nombre es “FechaRealizacion” que debe contener una fecha en formato: yyyy-mm-dd hh:mm:ss. Un afiliado es un recurso relacionado que debe ser especificado por su URI.

Supongamos que deseamos instanciar un recurso orden con:

• Fecha de realización 23/06/2018

• Afiliado Marta Laura Corbalán del ejemplo anterior, cuyo recurso tiene como URI
  https://ws.test.suap.com.ar/procesador/doV2/afiliados/7C9tIPdWMNTt99Zn1afALxroGVuQMt
  
  

Para pedirle al WS que cree el recurso orden con esos datos especificados en la sección REST debemos armar el siguiente JSON:

En general es poco probable que se cuente con la URI de los recursos y mas que nada al principio. Por lo que si el consumidor fuera por este camino tendría que implementar primero una serie de herramientas para poder buscar afiliados para poder incorporarlos en la sección REST, y lo mismo con los prescriptores y así con todos los recursos relacionados a una orden en este ejemplo. Recién entonces podría armar un contenido completo para realizar el POST y obtener finalmente el recurso instanciado en suap.

Si bien el WS no impide estas prácticas tampoco la alienta. Es por eso que ofrecemos la sección SEARCH que hace exactamente lo ante dicho pero en una cantidad menor de pasos.

En esta sección se le indica a suap que se van a identificar los recursos mediante busquedas por sus atributos. Es decir, por ejemplo si es el POST a una orden y no tenemos el token del afiliado que deseamos, podemos indicar que se lo busque por su nombre, DNI, o cualquier dato parcial o completo que tengamos del mismo. Suap aplicará una política simple en esta condición, si encuentra un único recurso con esos criterios de búsqueda, entonces lo utilizará, si encuentra mas de uno requerirá que sea seleccionado uno por parte del usuario mediante la sección VIEW del response.

Cabe destacar que los atributos deben seguir siendo especificados en la sección REST.

A modo de ejemplo un uso de la sección SEARCH del WS identificando al afiliado por su DNI y un conjunto de practicas identificados por sus ultimos 4 digitos del NBU.

Este ejemplo crea una orden de PAMI, simplemente creando un ejemplo con otro afiliado de otra OS debería generarse otra orden

FALTA DOCUMENTAR

El view es una lista de requerimientos y ofertas que hay que hacerle al usuario. Cada requerimiento u oferta indica exactamente donde debe ir el resultado de lo que el usuario responda.
Un requerimiento es algo que faltó o que es necesario resolver por parte del usuario. Por ejemplo un requerimiento puede ser definir un profesional ya que con la matrícula brindada hay dos o mas opciones posibles. Los requerimientos están siempre presentes como un error en la sub sección ERROR de la sección STATUS.
Una oferta es algo que le puede ser de utilidad al usuario. Por ejemplo un comprobante para imprimir es algo que el usuario puede necesitar o no para terminar un proceso externo a suap y necesario para el colegio. Pero no es algo necesario para instanciar un recurso.
Si se realiza un procesador de la sección VIEW practicamente no haría falta nada mas para instanciar recursos en suap (por ejemplo ordenes), mas allá de que sería quizás torpe y se realizarían muchisimas mas llamadas de las necesarias. Comencemos con un ejemplo considerando que operamos en la instalación de test.

Como es esperable es imposible obtener un recurso ordenes con ese content. Por lo que el response del WS contendrá un VIEW requiriendo todo lo que haga falta indicado en ERROR de STATUS cada atributo y recurso faltante. Si no está en {“STATUS”:{“ERROR”:{..}}} entonces no es algo necesario es una simple oferta.

Del response tomamos 3 fragmentos mínimos a modo de ejemplo y vemos que:

1. {“REST”:[]…} Es una lista vacía por lo que token no está definido. Condición de persistencia no se cumple, ya es condición suficiente para procesar el VIEW.
2. En {“STATUS”:{“ERROR”:{..}}} se nos indica que FechaRealización es un atributo requerido mediante un código para que tome decisiones el consumidor y un mensaje para que tome decisiones el usuario en caso de ser necesario. Por eso es una buena práctica mostrar ese texto.
3. Por otra parte el {“VIEW”:{“FechaRealizacion”:{..}}} le indica al consumidor como procesar este atributo o recurso. En este caso se indica que:
   
   1. El tipo es fecha, por lo que el consumidor puede ofrecerle un formato apropiado o incluso un widget de calendario. El resultado debe ser si o si en el formato especificado por el WS
   2. El resultado de lo que el usuario ingrese debe ser colocado en el JSON de request nuevo en la posición que se indica. Las “/” separan claves. Es decir, en el ejemplo al “REST” debe agregarse una clave “FechaRealizacion” que contiene una clave “value”que vale la fecha que ingrese el usuario.
   3. Información de asistencia al usuario como el label del campo para ingresar la fecha. El error que ocacionó que el WS requiera este dato, etc.

Una propuesta para presentarle al usuario bien podría ser:

En lineas generales este criterio sirve para los tipos texto y fecha. Otro ejemplo interesante es el tipo lista. Siguiendo con el ejemplo podemos ver que hay un atributo contexto en el response de un post vacío a ordenes:

Los criterios a aplicar sobre el atributo afiliado son similares a los de FechaRealizacion vistos en el ejemplo anterior, aquí la diferencia es que el input o el entry que se le provee al afiliado es sobre una lista de opciones en las que se detalla en la sección “opciones” que mostrarle al afiliado para que elija y que devolver en la ruta especificada. Siempre se devuelve la clave y se muestra el valor

Al igual que en el caso de FechaRealizacion quedará en la ruta especificada el valor que seleccione el usuario en este caso. Ya podemos apreciar que es el usuario quien mediante estos mecanismos simples puede ir construyendo el próximo request ya que se van completando las secciones del mismo.

Otro caso interesante para ver con ejemplos es el del tipo recurso. Veamos un ejemplo mas para poder formalizar una política.

El tipo recurso es ni mas ni menos que una serie de atributos que definen un recurso cuando es imposible ofrecerlo en una lista. Por ejemplo, supongamos el ejemplo concreto del response que estamos analizando. El afiliado bien podría ser elegido de una lista, pero sería una lista con miles de opciones. Por lo que al no haber dato alguno y ser un dato necesario para instanciar la orden entonces se ofrece completar datos que buscarán un recurso afiliado adecuado. Si miramos la porción del response de afiliados dentro de VIEW veremos que está como siempre la clave “tipo” y una clave “resource” que a simple vista parece como una sección VIEW mas pequeña!. La realidad es que no parece, es. VIEW es una estructura recursiva.
La primer entidad de VIEW está implícita y es de tipo recurso.

A diferencia de los atributos anteriores (FechaRealizacion y Contexto) acá podemos observar que el destino es dentro de la clave “SEARCH”:{..} en vez de “REST”:{..}. El WS está ofreciendo herramientas de búsqueda. Repasemos como iría quedando conformado el nuevo request que pudimos armar en función de un response al realizar un request vacío.

Podemos ir observando que el WS nos indicó:

• Qué falta.
• Cómo requerirlo al usuario.
• Cómo enviarlo al WS nuevamente.

Es decir, mediante una política sencilla, nos está ayudando a requerirle al usuario la información y a construir el request para enviar nuevamente el POST.

Este tipo de widget representa relaciones entre recursos como el título lo indica. Mucho a muchos. Pensemos un poco como sería la incorporación de un conjunto de practicas a una orden en una especificación RESTfull. Por un lado para poder vincular una orden con un conjunto de items practica tendríamos que crear

• El recurso orden
• los recursos item
• vincular los recurso items con el recurso orden.

Esto sería asi porque para poder vincular el recurso orden con los items necesito los tokens. Es un problema de orden de creación. El WS no permite crear items de forma aislada.

FALTA DOCUMENTAR