manual consumo de apis

Manual Consumo de ApiseCommerce Prestadores

Historial de Cambios

Fecha Versión Descripción Cambio Responsable

30.03.2020 1.0 Creación documento Betsy Medina

15.10.2020 2.0 Se incluye nuevo diseño estandarizado y compatible

con las políticas de seguridad de Cruz Blanca. Se

actualiza la mayoría de los servicios.

Betsy Medina

28.10.2020 3.0 Se agrega mensaje de Validación de Fecha de Venta Betsy Medina

04.11.2020 4.0 Se actualiza documento con los últimos ajustes

realizados en el desarrollo

Betsy Medina

11.02.2021 5.0 Se actualiza tipos de métodos de los MS Anular Venta y

MS Registrar Venta

Betsy Medina

Contenido

Introducción 4

Flujos eCommerce Prestador 4

Descripción de métodos de API eCommerce 8

Seguridad 15

Glosario de código de errores transversales 23

1. Introducción

Esta guía está dirigida a desarrolladores de Prestadores autorizados, para consumirlas APIs de eCommerce de Isapre Cruz Blanca.

Los métodos de la API Ecommerce Uso Excedentes son:● Consulta Afiliado● Factibilidad● Registrar Venta● Anular Venta

2. Flujos eCommerce Prestador

El flujo de ECommerce para Prestadores permite integrarse con el Front deECommerce Cruz Blanca para poder realizar pagos de productos y servicios, haciendouso de los Excedentes del Afiliado.

Esta solución integra la Aplicación del Prestador con la API del ECommerce CruzBlanca de manera segura y protegiendo la información del Cliente/Afiliado, tanto alvalidar sus datos de afiliación, como al realizar el cargo de la compra a susExcedentes.

Además, una vez realizado el cargo, la API devuelve al prestador la informaciónnecesaria para cerrar la transacción de venta y así poder conciliar posteriormente conCruz Blanca para gestionar los pagos correspondientes.

1. El cliente ingresa a la página web del prestador para realizar sus compras.

2. Cuando el cliente finaliza la selección de sus productos, la página Web delPrestador consulta si el cliente es afiliado vigente de la Isapre Cruz Blanca,accediendo a API “Consulta Afiliado” enviando el rut del paciente (más detalle enpunto 3.1 Método "Consulta Afiliado" ). Este paso es opcional. (Paso “0” deldiagrama)

3. En el caso que el rut si pertenezca a un afiliado de la Isapre, el Prestadorconsultará la “Factibilidad”, para poder determinar si habilita el botón “Pago conExcedentes de Cruz Blanca”, accediendo a API “Factibilidad” y enviando comoparámetro de entrada, la siguiente información (más detalle en punto 3.2 Método"Factibilidad" ). Si no se ejecutó el paso 2, se debe usar esta API directamente, laque validará como primer paso si el rut es afiliado de la Isapre.(Paso “1” deldiagrama)

● código de venta (número de pedido)● fecha venta● rut prestador● rut cliente● monto compra● url redirect

Dicha API validará las condiciones para determinar si el afiliado puede comprarsus productos por medio de “Uso de Excedentes de Cruz Blanca”.Si el afiliado cumple con las condiciones para realizar la compra con “Uso deExcedentes de Cruz Blanca”, la API entregará como parámetro de salida:

● rutCliente● codVenta● idTranServ● link● appToken

4. Si el cliente cumple las condiciones necesarias, el Prestador habilitará el botón“Pago con Excedentes de Cruz Blanca”, para que el cliente pueda seleccionar ycomprar sus productos. En caso contrario no se debe mostrar el botón.

5. Si el cliente selecciona el botón “Pago con Excedentes de Cruz Blanca”, elPrestador enviará por medio de un redirect de tipo POST a la Url de Linkcorrespondiente a “Uso de Excedentes eCommerce”, enviando como parámetroun JWT generado según las indicaciones del Capítulo 4 de Seguridad.

Ejemplo URL:https://ecommerce.cruzblanca.cl/68500dc8baaedd85fee4e4c4ef0601b71d44fcf1534cc41ec587dbb019e45b5cee87fe627a23cc5c2bac599b2ad5c019

6. Se levantará pantalla de Inicio de “Uso de Excedentes Cruz Blanca”, donde elcliente ingresa sus credenciales, y solicita iniciar sesión por medio de botón“Accede a Mi Cruz Blanca”

7. Luego el cliente ingresa el monto a cancelar con excedentes y confirma el pago,por medio de botón “Pagar”

8. Al terminar el proceso de pago, la aplicación “Uso de Excedentes Cruz Blanca”devuelve por medio de Redirect a la página del Prestador la siguiente informaciónen formato JSON:

Parámetro Descripción Tipo Largo Valor

codRespuesta Código de respuesta string 6 2000

menRespuesta Mensaje Respuesta string 250“Cargo venta

confirmado””

IdTransaccionServID de transacción de

Servicionumérico 256

codVenta número de pedido numérico 9

codCierre código de cierre string 50

montoPagadomonto pagado con

excedentesnumérico 9

idVenta id de la venta generada numérico 9

codAutorizacion código de autorización string 50

Ejemplo JSON de salida con codRespuesta = 2000

{"codRespuesta": "2000","menRespuesta": "Cargo venta confirmado ","idTransaccionServ": 12345678,"codVenta": 555555,"codCierre": "string","montoPagado": 10000,"idVenta": 251,"codAutorizacion": kjhd87AS098Dnx098AS09SD}

9. En el caso de que el cliente desista el pago con “Uso de Excedentes Cruz Blanca”,se hará el Redirect con:

Parámetro Descripción Tipo Largo Valor

codRespuesta Código de respuesta string 6 2030

mensajeRespuesta Mensaje Respuesta string 250“Cliente desiste

compra”

idTransaccionServID de transacción de

Servicionumérico 256

montoPagado monto del pago numérico 9 valor cero

10. El Prestador una vez terminada su venta debe enviar la información de respaldode la compra realizada accediendo a la API “Registra Venta” enviando comoparámetro de entrada, la siguiente información (más detalle en punto 3.4 Método"Registra Venta" ) (Paso 5 del diagrama)

● idVenta● codCierre● folioBoleta

● xmlBoleta● fechaBoleta● codAutorizacion

11. En el caso que la venta fue anulada, el Prestador debe acceder a API “AnulaVenta” enviando como parámetro de entrada, la siguiente información (másdetalle en punto 3.3 Método "Anula Venta" ) (Paso 7 del diagrama)

● codVenta● rutPrestador

3. Descripción de métodos de API eCommerce

3.1 Método “Consulta Afiliado”Método “Consulta Afiliado” permite consultar si rut pertenece a afiliado de Isapre Cruz Blanca

URI: GET - {{host}}/afiliados/{rut}

Entrada

Parámetro Descripción Tipo Largo Formato Obligatorio

rut (path) Rut del afiliado numérico 9 sin dígito verificador S

Salida

Parámetro Sub Parámetro Descripción Tipo Largo Valor

estado Estado de Resultado string

valores posibles:

● ‘OK’

● ‘ERROR’

respuestacodigoRespuesta Código Respuesta string 6

mensajeRespuesta Mensaje Respuesta string 250

errores (arreglo)codigo Código del error string

descripcion Descripción del error string

Códigos de Respuesta

Status Code EstadoCódigo

RespuestaMensaje Retorno

200 “ERROR” 4000 No es Afiliado

200 “OK” 4001 Afiliado autorizado

200 “ERROR” 4003 Afiliado no autorizado

Ejemplo Json de salida con parámetro de salida “estado”= “OK”

{"estado": "OK","respuesta": {"codigoRespuesta": "4001","mensajeRespuesta": "Afiliado Autorizado"

},"errores": null

}

Ejemplo Json de salida con parámetro de salida “estado”= “ERROR”

"estado": "ERROR","respuesta": null,"errores": [{"codigo": "string","descripcion": "string"

},{

"codigo": "string","descripcion": "string"

},{


}

3.2 Método “Factibilidad”Para poder habilitar el botón de pago con excedentes de Cruz Blanca,a un afiliado de Isapre CruzBlanca, es

necesario consumir el API “MS Factibilidad”, de acuerdo a lo siguiente

URI: POST- {{host}}/factibilidad

Entrada


codVenta N° de Pedido numérico 9 S

fechaHoraVenta

Fecha y hora de venta

(La fecha-hora no puede

ser futura)

string 19aaaa-mm-dd

hh:mm:ssS

rutCliente Rut del cliente numerico 9 S

rutPrestador Rut del Prestador numerico 9 sin dígito verificador S

montoServicio monto total de la compra numerico 9 sin dígito verificador S

urlRedirect url Redirect string 256 S

Salida



valores posibles:

● ‘OK’

● ‘ERROR’

respuesta

codigoRespuesta Código Respuesta string 6


rutCliente Rut Cliente numerico 9

codVenta N° de Pedido numerico 9

idTranServId de transacción de

Serviciostring 256

linklink aplicación

eCommercestring

appToken Token app string




Status Code EstadoCódigo

RespuestaMensaje Retorno

200 ERROR 4000 No es Afiliado

200 ERROR 4003 Afiliado no autorizado

200 ERROR 5012 Registro ya existe - <codVenta>

200 OK 4017 Afiliado Con Saldo de Excedentes

200 ERROR 4018 Afiliado Sin Saldo de Excedentes

200 ERROR 4019 Fecha inválida. La fecha-hora no puede ser futura.


{

"estado": "OK",

"respuesta": {

"codigoRespuesta": "4017",

"mensajeRespuesta": "Afiliado Con Saldo de Excedentes",

"rutCliente": 37621443,

"codVenta": "8234",

"idTranServ":

"0067980bcc691249171234bb0e4f272cb9baddf877216869a17bf8cdde67aa14b16ee

da42abc4576ba206e6be35bbe41",

"link": "https://ecommerce.cruzblanca.cl/ejemplo",

"appToken":

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFt

ZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36

POk6yJV_adQssw5c"

},

"errores": null

https://ecommerce.cruzblanca.cl/ejemplo

}



},{


},{


}

3.3 Flujo “Anular Venta”Para anular una venta, es necesario consumir el API “Anular Venta”, de acuerdo a lo siguiente:

URI: DELETE- {{host}}/ventas

Entrada


codVenta Número de pedido numérico 9 S

rutPrestador Rut del prestador numérico 9 sin dígito verificador S

Salida



valores posibles:

● ‘OK’

● ‘ERROR’

respuesta



idVenta número de pedido numerico 9

fechaHoraAnulacion

fecha y hora de la anulación

(formato aaaa-mm-dd

hh:mm:ss)

string 10

rutPrestador Rut del Prestador numerico 9

rutTitular Rut del Titular numerico 9

errores

(arreglo)

codigo Código del error string



Status

Code Estado

Código

Respuesta Mensaje Retorno

200 OK 3000 Cargo venta anulado

200 ERROR 6002 Transacción se encuentra en estado <descripción del estado>

200 ERROR 5024Venta se encuentra en estado <descripción del estado de la

Venta>

200 ERROR 3030 Error sistema ws anulación | datos de autenticacion inválidos

200 ERROR 3031 No anulada|no existe transaccion asociada

200 ERROR 3032 No anulada|ya existe una anulacion asociada

200 ERROR 3039 Error sistema|dac anulacion

200 ERROR 3039 Error sistema bc anulacion | " + mensaje sistema

200 ERROR 3039 Error sistema ws confirmacion | " + mensaje sistema


{

"estado": "OK",

"respuesta": {


"mensajeRespuesta": "Cargo venta anulado",

"idVenta": 133,

"fechaHoraAnulacion": "2020/03/02 15:55:03",

"rutTitular": 12345678,

"rutPrestador": 12345678

},

"errores": null

}



},{

"codigo": "string",

"descripcion": "string"},

{"codigo": "string","descripcion": "string"

}

3.4 Flujo “Registra Venta”Para Registrar una venta, es necesario consumir el API “Registrar Venta”, de acuerdo a lo siguiente:

URI: PATCH- {{host}}/ventas

Entrada


idventa Id de la Venta numérico 9 S

codCierre código de cierre de la venta string 50 S

folioBoleta Folio de la Boleta numérico 12 S

xmlBoleta Xml de Boleta texto S

fechaBoleta Fecha de la Boleta String 19aaaa/mm/dd

hh:mm:ssS

codAutorizacion código de autorización string 50 S

Salida



valores posibles:

● ‘OK’

● ‘ERROR’

respuesta



idVenta id de la venta numerico 9

fecVenta

fecha de la venta

(formato aaaa-mm-dd

hh:mm:ss)

string 19

folBoleta folio boleta numerico 12

rutTitular rut titular numerico 9

rutPrestador rut prestador numerico 9

codCierre código de cierre string 50




Status Code Estado Código Respuesta Mensaje Retorno

200 OK 5017 Venta Registrada

200 ERROR 5024 Venta se encuentra en estado <descripción del estado>

200 ERROR 6002Transacción se encuentra en estado <descripción delestado>

200 ERROR 5031 Prestador no posee Modalidad 130 o 131

200 ERROR 5026 Debe enviar XML boleta

200 ERROR 5023 Código de Cierre no corresponde para transacción

200 ERROR 5022 Codigo de Autorizacion inválido


{

"estado": "OK",

"respuesta": {


"mensajeRespuesta": "Venta Registrada",

"idVenta": 824,

"fecVenta": "2020-03-02 15:55:03",

"folBoleta": 6424,

"rutTitular": 17463549,

"rutPrestador": 13887331,

"codCierre": "5f87023oi5d830263f60001"

},

"errores": null

}



},{


},{


}

4. Seguridad

ECommerce como mecanismo de seguridad utiliza JSon Web Token (JWT). Este es unmétodo abierto, estándar de la industria RFC 7519 para representar solicitudes de formasegura entre dos partes. Para más detalles, se puede consultar el sitio web https://jwt.io/.

Estos son los pasos para la interacción entre nuestro servicio y el prestador:

Paso 1

Paso 2

https://jwt.io/

Paso 3

Importante: las imágenes y datos que se entregan en el manual son de referencia, losdatos reales se entregan de acuerdo a los flujos mostrados en los diagramas del punto4, pasos 1, 2 y 3.

4.1 ¿Cuál es la estructura JSON Web Token?

En su forma compacta, JSON Web Tokens consta de tres partes separadas por puntos (.),

que son:

● Header

● Payload

● Signature

Por lo tanto, un JWT generalmente se parece a lo siguiente.

● xxxxx.yyyyy.zzzzz

4.2 Tipo de JWT Utilizado (RS256)

RS256 (RSA Signature con SHA-256 ) es un algoritmo asimétrico, y usa un par de claves

pública/privada: el proveedor de identidad tiene una clave privada (secreta) utilizada para

generar la firma, y El consumidor del JWT obtiene una clave pública para validar la firma.

Dado que la clave pública, a diferencia de la clave privada, no necesita mantenerse segura,

la mayoría de los proveedores de identidad hacen que esté fácilmente disponible para que

los consumidores la obtengan y usen (generalmente a través de una URL de metadatos).

Importante: las imágenes y datos que se entregan en el manual son de referencia, losdatos reales se entregan de acuerdo a los flujos mostrados en los diagramas del punto4, pasos 1, 2 y 3.

Crear Llaves Para el consumo de APIs

4.2.1 Crear Certificados RSA

$> openssl genrsa -out server.key 2048

$> openssl rsa -in server.key -pubout -out public.pem

4.2.2 Crear Token (https://jwt.io/)

✔ Private Key (ejemplo “server.key”)

-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEA4eSy3ylqY0dsh7vuWUDj2Z6ZzbK2XWzffSNdTVCtYsDhM+jZjFllsvl+imbugtF3EbLRI3cL0S5o+wLsMh968vDquWt8Mz8oEYRg089VnwoOlpKU

wYPZAjo7lK/8HYSWIq2Srd6pdqi+p0m6FpjRmBxa9Ch7VOSyQlmevEfK9qT7xVXOANmD1UnHV75XSIvYNiKyA9+StrFeE3f8aa2v6LYmTcSY0pgUHdLMifsqajHMYJsgpKI2ivMoUXWQ/UAZ85nO5Kt762LYM6WkqnAvLEo900urlRkpSlnnt6Bx+KPSQ2AJsr3i8PFWTu/JF65uLi5s3D20WiUoC1+tAW4MjQIDAQABAoIBAQCkdf8MnniIY13OzLJRZP7+V4weyHghOLzVvMOXIJ+7gDX1txd8KTHzxdWtKheIQrxvtEKzkV6XIzTnW09fhq/a5C/gYzL/lIG1jy13yEHMEmRgl8OZyEZcas0qCZ6CVx9/i+N4lt3GOEDmRrUm8ofWOP63OCniusZVrC33YkWQn1tHORL4iRg2ZZyaN3A9yIWr7R08OxkA+qM2zHvsSoRWVQD5fBGh/3JDxvELdMvveuFsIvjGSgfFaOLfpzi4fTMeXLkuKlX2wLdhl74SyqQuwmL6dbeIoBV/JOe5bmrhUmUIRA01bZbTR2wBuS+KnjpcXFgs1nXcA4BOjviachm5AoGBAPNGHIKbOeA3G7c0LisqC0/j8XbwWlOui5rA5eSd/38TRKfB+yRBr09c7A6k67Es+L9bJxb9VkSvuyDZjxVgo9Akwkdn0btCzdr8zqstscD5lsCOjlQGNZT7MRAHsr6Gmr8/RSjqX4NRpdJx1k4ZAGJswcpWwXI1uddLM4B+j8nfAoGBAO211Hf+1bTlmpDHP2ERcFfLfKDkSFfqajkjCSUmrHA0QzILgfkI9Rt7gANnzY8K0RwBqcsLXa6fEf+W1g1jeHCBP/DCyNcnnjH8VJl6Sx/5pLm1nzBmfYUY7MdXu6Fa5LeT

https://en.wikipedia.org/wiki/SHA-256

https://en.wikipedia.org/wiki/Public-key_cryptography

https://jwt.io/

t7KqVFQMzKlnZl6BkrA4aYfkeCJSz5+WjWtJ0g8TAoGAcTC1ATvyQNXDSom31ZOZcdGQPxP0Iy16fUW1cZrmDx1K+3cxQBxj0lxc5S9tDqHrFzX1SSgUpJ7TRaSUg5DUh3si/hBbMHMTzwmDq3f2VeCLeQqbRJMjCS+bE2dRjn6Yr9Vje3cZe8NYkUMwQGQ3npQV0uxs05QV5Qtzahz5ECcCgYAC8ueA2ZNzHAoP07jwjlPTcv3HzS0skgbhUJLzeAhZl/xhaY0iNr87qQuMf0QoixzO+SJPF4QA/44smoVrQxmiY6gUZ4YwTRiETDoMcVzvN5yYhS1FX3AdL5L4Yhk8xjDiKh30RHKpXENJsrOtZnQYZYrBmc73tglHVInKk+7cKwKBgQDWy4x1hAPMuVygosNnNV0bnLQlsFKPHXm1f6PMC8FqupthnHL0GvUFuXiM9blDlxItda83hD9TdaZ42KknuXTPvL+235fDU0yKTFuYAlrsabTKEaeJF+Uk7scp5+TjjYAV4jZ/0Yr8RLewfC8UUUWkXqA2QEt+nlh6U5ycfo5f4A==-----END RSA PRIVATE KEY-----

✔ Estructura JWT

▪ Se deben agregar los siguientes parámetros a la estructura (los datos

mostrados son de ejemplo, los reales son enviados por Cruz Blanca de

acuerdo al flujo mostrado en el Diagrama anterior - Paso 1:

o HEADER

▪ "kid": "mbA9sC+y4cbzqAgfQG2Lw6PuNdfaNcflYEhqnsW1Fpo="

o BODY

▪ "sub": "[email protected]"

▪ Ejemplo:

✔ Token Generado

4.3 Validar Token

4.3.1 Public Key (ejemplo “public.pem”)

-----BEGIN PUBLIC KEY-----

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eSy3ylqY0dsh7vuWUDj

2Z6ZzbK2XWzffSNdTVCtYsDhM+jZjFllsvl+imbugtF3EbLRI3cL0S5o+wLsMh96

8vDquWt8Mz8oEYRg089VnwoOlpKUwYPZAjo7lK/8HYSWIq2Srd6pdqi+p0m6FpjR

mBxa9Ch7VOSyQlmevEfK9qT7xVXOANmD1UnHV75XSIvYNiKyA9+StrFeE3f8aa2v

6LYmTcSY0pgUHdLMifsqajHMYJsgpKI2ivMoUXWQ/UAZ85nO5Kt762LYM6WkqnAv

LEo900urlRkpSlnnt6Bx+KPSQ2AJsr3i8PFWTu/JF65uLi5s3D20WiUoC1+tAW4M

jQIDAQAB

-----END PUBLIC KEY-----

4.3.2 Token a validar.

4.3.3 Para validar agregue el certificado público.

4.3.4 Token verificado.

Nota: Es importante destacar que el prestador debe generar sus propios tokens, el

mencionado en el documento es solo de prueba. Para lo cual cada Prestador debe enviar

su llave pública y CB enviará:

HEADER

"kid": "yyyyyyyyyyyyyyyyyyyyy"

BODY

"sub": "xxxxxxxxx"

mailto:[email protected]

5. Glosario de código de errores transversales


Status Code CódigoRespuesta

Mensaje Retorno

200 5000 Datos de entrada vacío

200 5001 Datos de entrada con formato incorrecto

200 5002 Parametro de entrada con formato incorrecto

200 5003 Dato de entrada supera el largo máximo

200 5004 Dato de entrada inferior al largo minimo

200 5005 Fecha inválida

200 5006 Rango inválido

200 5007 No se encontró información

200 5008 Debe ingresar al menos un dato

200 5009 Datos de entrada con valor permitido incorrecto

200 5010 Fecha es mayor que la fecha actual

200 5011 Relación no encontrada

200 5012 Registro ya existe

500 5013 Problemas en conexion a la base de datos

200 5019 Header vacio

200 5020 header largo maximo

500 5021 Error interno

500 5030 Error conectividad con WebService.

manual consumo de apis

Documents