Manual

Consumo de Apis
eCommerce 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 Betsy Medina

con las políticas de seguridad de Cruz Blanca. Se
actualiza la mayoría de los servicios.

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 Betsy Medina
realizados en el desarrollo

11.02.2021 5.0 Se actualiza tipos de métodos de los MS Anular Venta y Betsy Medina
MS Registrar Venta
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 consumir
las 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 de
ECommerce Cruz Blanca para poder realizar pagos de productos y servicios, haciendo
uso de los Excedentes del Afiliado.
Esta solución integra la Aplicación del Prestador con la API del ECommerce Cruz
Blanca de manera segura y protegiendo la información del Cliente/Afiliado, tanto al
validar sus datos de afiliación, como al realizar el cargo de la compra a sus
Excedentes.
Además, una vez realizado el cargo, la API devuelve al prestador la información
necesaria para cerrar la transacción de venta y así poder conciliar posteriormente con
Cruz 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 del

Prestador 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 en
punto 3.1 Método "Consulta Afiliado" ). Este paso es opcional. (Paso “0” del
diagrama)
3. En el caso que el rut si pertenezca a un afiliado de la Isapre, el Prestador
consultará la “Factibilidad”, para poder determinar si habilita el botón “Pago con
Excedentes de Cruz Blanca”, accediendo a API “Factibilidad” y enviando como
pará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, la
que validará como primer paso si el rut es afiliado de la Isapre.(Paso “1” del
diagrama)
● 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 comprar
sus productos por medio de “Uso de Excedentes de Cruz Blanca”.
Si el afiliado cumple con las condiciones para realizar la compra con “Uso de
Excedentes 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 y
comprar 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”, el

Prestador enviará por medio de un redirect de tipo POST a la Url de Link
correspondiente a “Uso de Excedentes eCommerce”, enviando como parámetro
un JWT generado según las indicaciones del Capítulo 4 de Seguridad.

Ejemplo URL:
https://ecommerce.cruzblanca.cl/68500dc8baaedd85fee4e4c4ef0601b71d44fcf1534cc4
1ec587dbb019e45b5cee87fe627a23cc5c2bac599b2ad5c019

6. Se levantará pantalla de Inicio de “Uso de Excedentes Cruz Blanca”, donde el

cliente 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ón
en formato JSON:
 Parámetro Descripción Tipo Largo Valor

codRespuesta Código de respuesta string 6 2000

“Cargo venta
menRespuesta Mensaje Respuesta string 250
confirmado””
ID de transacción de
IdTransaccionServ numérico 256
Servicio
codVenta número de pedido numérico 9
codCierre código de cierre string 50
monto pagado con
montoPagado numérico 9
excedentes
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

“Cliente desiste
mensajeRespuesta Mensaje Respuesta string 250
compra”
ID de transacción de
idTransaccionServ numérico 256
Servicio
montoPagado monto del pago numérico 9 valor cero

10. El Prestador una vez terminada su venta debe enviar la información de respaldo
de la compra realizada accediendo a la API “Registra Venta” enviando como
pará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 “Anula
Venta” enviando como parámetro de entrada, la siguiente información (más
detalle 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
valores posibles:
estado Estado de Resultado string ● ‘OK’
● ‘ERROR’
codigoRespuesta Código Respuesta string 6
respuesta
mensajeRespuesta Mensaje Respuesta string 250
codigo Código del error string
errores (arreglo)
descripcion Descripción del error string

Códigos de Respuesta
Código
Status Code Estado Mensaje Retorno
Respuesta
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"
},
{
"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

Parámetro Descripción Tipo Largo Formato Obligatorio

codVenta N° de Pedido numérico 9 S
Fecha y hora de venta
aaaa-mm-dd
fechaHoraVenta (La fecha-hora no puede string 19 S
hh:mm:ss
ser futura)
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
Parámetro Sub Parámetro Descripción Tipo Largo Valor
 valores posibles:
estado Estado de Resultado string ● ‘OK’
● ‘ERROR’
codigoRespuesta Código Respuesta string 6
mensajeRespuesta Mensaje Respuesta string 250
rutCliente Rut Cliente numerico 9
codVenta N° de Pedido numerico 9
respuesta
Id de transacción de
idTranServ string 256
Servicio
link aplicación
link string
eCommerce
appToken Token app string
codigo Código del error string
errores (arreglo)
descripcion Descripción del error string

Códigos de Respuesta
Código
Status Code Estado Mensaje Retorno
Respuesta
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.

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

{
"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
 }

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

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

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

Parámetro Descripción Tipo Largo Formato Obligatorio

codVenta Número de pedido numérico 9 S
rutPrestador Rut del prestador numérico 9 sin dígito verificador S

Salida
Parámetro Sub Parámetro Descripción Tipo Largo Valor
valores posibles:
estado Estado de Resultado string ● ‘OK’
● ‘ERROR’
codigoRespuesta Código Respuesta string 6
mensajeRespuesta Mensaje Respuesta string 250
idVenta número de pedido numerico 9
respuesta fecha y hora de la anulación
fechaHoraAnulacion (formato aaaa-mm-dd string 10
hh:mm:ss)
rutPrestador Rut del Prestador numerico 9
rutTitular Rut del Titular numerico 9
errores codigo Código del error string
(arreglo) descripcion Descripción del error string

Códigos de Respuesta
Status Código
Code Estado Respuesta Mensaje Retorno
200 OK 3000 Cargo venta anulado
200 ERROR 6002 Transacción se encuentra en estado <descripción del estado>
Venta se encuentra en estado <descripción del estado de la
200 ERROR 5024
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

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

{
"estado": "OK",
"respuesta": {
"codigoRespuesta": "3000",
"mensajeRespuesta": "Cargo venta anulado",
"idVenta": 133,
"fechaHoraAnulacion": "2020/03/02 15:55:03",
"rutTitular": 12345678,
"rutPrestador": 12345678
},
"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"
},
{
"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
Parámetro Descripción Tipo Largo Formato Obligatorio
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
aaaa/mm/dd
fechaBoleta Fecha de la Boleta String 19 S
hh:mm:ss
codAutorizacion código de autorización string 50 S

Salida
Parámetro Sub Parámetro Descripción Tipo Largo Valor
valores posibles:
estado Estado de Resultado string ● ‘OK’
● ‘ERROR’
codigoRespuesta Código Respuesta string 6
mensajeRespuesta Mensaje Respuesta string 250
idVenta id de la venta numerico 9
fecha de la venta
fecVenta (formato aaaa-mm-dd string 19
respuesta hh:mm:ss)
folBoleta folio boleta numerico 12
rutTitular rut titular numerico 9
rutPrestador rut prestador numerico 9
codCierre código de cierre string 50
codigo Código del error string
errores (arreglo)
descripcion Descripción del error string

Códigos de Respuesta
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>
Transacción se encuentra en estado <descripción del
200 ERROR 6002 estado>
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

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

{
"estado": "OK",
"respuesta": {
"codigoRespuesta": "5017",
"mensajeRespuesta": "Venta Registrada",
"idVenta": 824,
"fecVenta": "2020-03-02 15:55:03",
"folBoleta": 6424,
"rutTitular": 17463549,
"rutPrestador": 13887331,
"codCierre": "5f87023oi5d830263f60001"
},
"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"
},
{
"codigo": "string",
"descripcion": "string"
}
4. Seguridad
ECommerce como mecanismo de seguridad utiliza JSon Web Token (JWT). Este es un
método abierto, estándar de la industria RFC 7519 para representar solicitudes de forma
segura 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
Paso 3

Importante: las imágenes y datos que se entregan en el manual son de referencia, los
datos reales se entregan de acuerdo a los flujos mostrados en los diagramas del punto
4, 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, los
datos reales se entregan de acuerdo a los flujos mostrados en los diagramas del punto
4, 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+jZ
jFllsvl+imbugtF3EbLRI3cL0S5o+wLsMh968vDquWt8Mz8oEYRg089VnwoOlpKU
wYPZAjo7lK/8HYSWIq2Srd6pdqi+p0m6FpjRmBxa9Ch7VOSyQlmevEfK9qT7xVXO
ANmD1UnHV75XSIvYNiKyA9+StrFeE3f8aa2v6LYmTcSY0pgUHdLMifsqajHMYJsg
pKI2ivMoUXWQ/UAZ85nO5Kt762LYM6WkqnAvLEo900urlRkpSlnnt6Bx+KPSQ2AJ
sr3i8PFWTu/JF65uLi5s3D20WiUoC1+tAW4MjQIDAQABAoIBAQCkdf8MnniIY13O
zLJRZP7+V4weyHghOLzVvMOXIJ+7gDX1txd8KTHzxdWtKheIQrxvtEKzkV6XIzTn
W09fhq/a5C/gYzL/lIG1jy13yEHMEmRgl8OZyEZcas0qCZ6CVx9/i+N4lt3GOEDm
RrUm8ofWOP63OCniusZVrC33YkWQn1tHORL4iRg2ZZyaN3A9yIWr7R08OxkA+qM2
zHvsSoRWVQD5fBGh/3JDxvELdMvveuFsIvjGSgfFaOLfpzi4fTMeXLkuKlX2wLdh
l74SyqQuwmL6dbeIoBV/JOe5bmrhUmUIRA01bZbTR2wBuS+KnjpcXFgs1nXcA4BO
jviachm5AoGBAPNGHIKbOeA3G7c0LisqC0/j8XbwWlOui5rA5eSd/38TRKfB+yRB
r09c7A6k67Es+L9bJxb9VkSvuyDZjxVgo9Akwkdn0btCzdr8zqstscD5lsCOjlQG
NZT7MRAHsr6Gmr8/RSjqX4NRpdJx1k4ZAGJswcpWwXI1uddLM4B+j8nfAoGBAO21
1Hf+1bTlmpDHP2ERcFfLfKDkSFfqajkjCSUmrHA0QzILgfkI9Rt7gANnzY8K0RwB
qcsLXa6fEf+W1g1jeHCBP/DCyNcnnjH8VJl6Sx/5pLm1nzBmfYUY7MdXu6Fa5LeT
 t7KqVFQMzKlnZl6BkrA4aYfkeCJSz5+WjWtJ0g8TAoGAcTC1ATvyQNXDSom31ZOZ
cdGQPxP0Iy16fUW1cZrmDx1K+3cxQBxj0lxc5S9tDqHrFzX1SSgUpJ7TRaSUg5DU
h3si/hBbMHMTzwmDq3f2VeCLeQqbRJMjCS+bE2dRjn6Yr9Vje3cZe8NYkUMwQGQ3
npQV0uxs05QV5Qtzahz5ECcCgYAC8ueA2ZNzHAoP07jwjlPTcv3HzS0skgbhUJLz
eAhZl/xhaY0iNr87qQuMf0QoixzO+SJPF4QA/44smoVrQxmiY6gUZ4YwTRiETDoM
cVzvN5yYhS1FX3AdL5L4Yhk8xjDiKh30RHKpXENJsrOtZnQYZYrBmc73tglHVInK
k+7cKwKBgQDWy4x1hAPMuVygosNnNV0bnLQlsFKPHXm1f6PMC8FqupthnHL0GvUF
uXiM9blDlxItda83hD9TdaZ42KknuXTPvL+235fDU0yKTFuYAlrsabTKEaeJF+Uk
7scp5+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"
5. Glosario de código de errores transversales
Códigos de Respuesta

Status Code Código Mensaje Retorno

Respuesta
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.