Interfaces de

integración con
Sistemas Base

Solución:
Afiliación digital CES

Versión 1.00
Vigente desde 02/11/2023

.
 Contenido
1 INTRODUCCIÓN............................................................................................... 2
2 ALCANCE........................................................................................................... 2
3 TÉRMINOS Y REFERENCIAS.............................................................................2
4 TIPO DE TECNOLOGÍA PARA IMPLEMENTAR LAS INTERFACES...................2
5 FORMATO DE NUMERACIÓN DE PRODUCTOS FINANCIEROS.......................2
6 MANEJO DE ERRORES......................................................................................2
7 SERVICIOS........................................................................................................ 3
7.1 Clases....................................................................................................................3
7.1.1 ErrorDTOIBAN..................................................................................................3
7.1.2 NaturalPerson...................................................................................................3
7.1.3 CuentaIBANDTO................................................................................................4
7.1.4 ClienteDTO.........................................................................................................4
7.1.5 ClSolicitudAfiliacionTempTipoProductoDTO..................................................5
7.1.6 InsertCustomerAddressDTO............................................................................5
7.1.7 PhoneDTO..........................................................................................................5
7.1.8 EmailDTO...........................................................................................................5
7.1.9 ClClienteDireccionesEntregaDTO.....................................................................6
7.1.10 DebitCardReqDTO...........................................................................................6
7.1.11 GetAccountInfoRequestDTO...........................................................................6
7.1.12 GetAccountInfoResponseDTO........................................................................7
7.1.13 NaturalPersonRequestDTO............................................................................7
7.1.14 NaturalPersonResponseDTO..........................................................................7
7.1.15 MajorChildrenOvelDTO..................................................................................8
7.1.16 PepOvelDTO....................................................................................................8
7.1.17 CustomerOvelDTO..........................................................................................9
7.1.18 CustomerRequestOvelDTO...........................................................................10
7.1.19 CustomerResponseOvelDTO........................................................................10
7.1.20 ClienteResponseDTO....................................................................................11
7.1.21 ClClienteAfiliarRequestDTO.........................................................................11
7.2 Métodos..............................................................................................................12
8 CODIFICACIONES........................................................................................... 13
8.1 IdType.................................................................................................................13
8.2 Gender.................................................................................................................13
PS-ODB- Interfaces con Sistemas Base
 8.3 CurrencyCode.....................................................................................................13

PS-ODB- Interfaces con Sistemas Base

 1

Historial de Versiones
Versión Descripción Fecha
1.00 Versió n inicial del documento 02-11-2023

Interfaces con Sistemas Base

 2

1 Introducción
Este documento describe las interfaces que requiere la plataforma de afiliació n digital CES, para
comunicarse con los Sistemas Internos de su Entidad Financiera.
El documento detalle el tipo de tecnología, mensajes y pará metros de entrada y salida que de las
diferentes funcionalidades presenten en las interfaces expuestas, esto con el fin de interconectar los
sistemas de la forma má s simple y transparente.

2 Alcance
Este documento describe las interfaces que requiere la plataforma de afiliació n digital CES.

3 Términos y referencias
 PCD: Proyecto de coperativa digital

4 Tipo de tecnología para implementar las interfaces

Todas las interfaces se exponen por medio de Servicios Web, de manera que, la integració n se haga de
forma má s abierta e interoperable.

5 Formato de numeración de productos financieros

Las siguientes consideraciones deben ser tomadas en cuenta al desarrollar las interfaces en este
documento de integració n.
 Cuando su Entidad Financiera sea costarricense, en todos los servicios y métodos relacionados
con cuentas y préstamos, tanto para la consulta como para efectuar pagos o cobros, el nú mero de
producto deberá indicarse utilizando el está ndar de numeració n internacional IBAN.

6 Manejo de errores
La plataforma PCD tiene la capacidad de presentar los mensajes de errores que generen sus Sistemas
Internos en mú ltiples idiomas. Si desea aprovechar esta funcionalidad, deberá entregar una lista con
todos los có digos y mensajes de errores que estaría devolviendo en las interfaces que desarrollará .
Con esta lista, PCD se encargará de configurar los mensajes en los diferentes idiomas (su Entidad
deberá aportar las traducciones), de manera que, en funció n del lenguaje que el usuario seleccione en
la plataforma así se mostrará la descripció n del error.
Si no desea aprovechar esta capacidad, entonces en todas las clases de respuesta (terminadas con
RESPONSE) cuando suceda un error y desee notificarlo a nuestra plataforma PCD, deberá indicar
SIEMPRE un -1 en el có digo del error e indicar el mensaje respectivo (de lo que sucedió o validó ) en el
idioma que desee que se le presente al usuario.

Interfaces con Sistemas Base

 3

7 Servicios

7.1 Clases
En todas las clases REQUEST, deben indicarle el valor para todos los atributos indicados, a menos que,
explícitamente se indique que es opcional

7.1.1 ErrorDTOIBAN
Clase para transporte el detalle de un error.

Atributo Descripción Tipo Long. Max

Code Có digo del error del sistema interno Int
de la entidad.
La entidad deberá pasar el catá logo
completo de posibles có digos de
error si quiere que PCD retorne los
mensajes a los canales.
Type Tipo de error segú n catá logo. int
Message Mensaje de error donde la entidad String 250
indicará a detalle el error
presentado.

7.1.2 NaturalPerson

Atributo Descripción Tipo Long. Max

Id Nú mero de identificació n de la String 20
persona consultada
Name Nombre de la persona String 50
FatherLastName Primer apellido String 50
MotherLastName Segundo apellido String 50
Photo Fotografía de la persona base 64 Char[] 2500
SignatureImg Firma de la persona base 64 Char[] 2500
RightHandFingerIdentifier Nú mero de dedo de la mano Int
derecha utilizado para
identificarse
LeftHandFingerIdentifier Nú mero de dedo de la mano Int
izquierda utilizado para
identificarse
Death Indicador de si está fallecido. True Boolean
indica fallecido.
IdCardDueData Fecha de vencimiento de la Date
identificació n
ProvinceCode Có digo de provincia donde nació Int

Interfaces con Sistemas Base

 4

la persona
CantonCode Có digo de canton donde nació la Int
persona
DistrictCode Có digo de distrito donde nació la Int
persona
Division1Name ? String
Division2Name ? String
Division3Name ? String
ElectoralDistrict Distrito electoral String 5
ElectoralDistrictName Nombre del distrito electoral String 250
BirthDate Fecha de nacimiento Date
Gender Indicador de sexo. Segú n catá logo Int
KnownAs Nombre de la persona có mo String 250
también es conocido

7.1.3 CuentaIBANDTO
Clase que devuelve los datos al consultar una cuenta IBAN
Propiedad Descripción Tipo Long. Max

AccountNumber Cuenta IBAN del producto consultado String 35

HolderId Identificació n del dueñ o de la cuenta String 20
HolderIdType Tipo de identificació n segú n catá logo Int
Holder Nombre del dueñ o de la cuenta String 250
CurrencyCode Có digo de moneda segú n catá logo String 4
CountryCode Có digo de país segú n catá logo String 4
CountryName Nombre del país String 250
EntityCode Có digo de entidad dueñ a de la cuenta IBAN. Segú n String 4
está ndar de BCCR
EntityName Nombre de la entidad dueñ a de la cuenta IBAN. String 250
ProductName Descripció n del producto consultado String 250
State Estado de la cuenta. Segú n catá logo String 3

7.1.4 ClienteDTO
Clase de respuesta a una solicitud de afiliació n

Propiedad Descripción Tipo Long.

Max
Code Có digo del cliente Int

DeductionAgreement Indica si tiene deducció n de planilla Boolean

Interfaces con Sistemas Base

 5

Id Nú mero de identificació n del cliente String 20

IdType Tipo de identificació n segú n catá logo String 20
Name Nombre del cliente String 250
PrincipalEmail Correo principal del cliente String 250
PrincipalPhone Nú mero de teléfono principal del cliente String 50
Status Có digo de estado del cliente. Segú n catá logo Int
Type Tipo de cliente. Segú n catá logo String 10

7.1.5 ClSolicitudAfiliacionTempTipoProductoDTO
Clase de respuesta a una solicitud de afiliació n

Propiedad Descripción Tipo Long.

Max
CodCompania Có digo de compañ ia String 8
NumSolicitud Nú mero de solicitud Long 22
CodTipoProducto Có digo de producto segú n catá logo Long 22
AceptaTerminosCondiciones Indicador si aceptó los términos y String 1
condiciones. “S” Sí o “N” No
FecCreacion Fecha de creació n de la solicitud Date
UsuCreacion Usuario que registró la solicitud String 30

7.1.6 InsertCustomerAddressDTO
Clase que contiene las direcciones de un cliente

Propiedad Descripción Tipo Long.

Max
Tipo Tipo de direcció n. Segú n Catá logo String 3
Principal Indica si es la direcció n principal Boolean
CodigoPais Có digo del país de la direcció n. Segú n String 3
catá logo
CodigoDivision1 Có digo de provincia String 3
CodigoDivision2 Có digo de cantó n String 3
CodigoDivision3 Có digo de distrito String 3
CallesAvenidas Detalle de la calle y avenida donde se String 50
encuentra la direcció n
Detalles Detalles de la direcció n del cliente. Có mo String 250
señ as.

7.1.7 PhoneDTO
Clase que contiene los teléfonos de un cliente

Interfaces con Sistemas Base

 6

Propiedad Descripción Tipo Long.

Max
Tipo Tipo de teléfono segú n catá logo. String
Principal Indica si es el teléfono es el principal Boolean
Numero Nú mero de teléfono del cliente. String 50

7.1.8 EmailDTO
Clase que contiene los correos de un cliente

Propiedad Descripción Tipo Long.

Max
Tipo Tipo de correo segú n catá logo. String 3
Principal Indica si es el teléfono es el principal Boolean
Correo Direcció n de correo de un cliente String 150

7.1.9 ClClienteDireccionesEntregaDTO
Clase que contiene el detalle de la entrega de una tarjeta

Propiedad Descripción Tipo Long.

Max
CountryCode Có digo del país de la direcció n. Segú n String 3
catá logo
Division1Code Có digo de provincia. String 3
Division2Code Có digo de cantó n. String 3
Division3Code Có digo de distrito. String 3
StreetAddress Nú mero de calle y avenida String 50
Details Detalles de la direcció n String 250
Phone Nú mero de teléfono a contactar String 10

7.1.10 DebitCardReqDTO
Clase que contiene los datos necesarios para realizar una solicitud de tarjeta de débito

Propiedad Descripción Tipo Long.

Max
NameToEmboss Nombre a embozar String 80
DebitCardBrand Marca de la tarjeta. Segú n catá logo String
DebitarCardType Tipo de tarjeta. Segú n catá logo String
DebitCardDesign Diseñ o de la tarjeta. Segú n catá logo String
DeliveryAddress Direcció n donde debe entregarse la tarjeta CLClienteDirec
cionesEntrega
DTO
DeliveryBranch Sucursal de entrega String 50

Interfaces con Sistemas Base

 7

Remarks Observaciones String 250

7.1.11 GetAccountInfoRequestDTO
Clase que permite consultar datos de una cuenta IBAN
Propiedad Descripción Tipo Long. Max

CompanyCode Có digo de la compañ ía a donde se debe ir a validar la String 20

cuenta IBAN
HostId Identificador del canal que está realizando la consulta String 50
OperationId Identificador del llamado, debe ser ú nico y será el valor String 50
que se debe utilizar para validar contra PCD si hubo algú n
error durante la ejecució n de la solicitud
ClientIpPAddress Direcció n IP que identifica desde donde se realiza el String 20
llamado
CultureCode Cultura utilizada para formatos. Ej: “ES-CR” String 8
AccountNumber ? String 35
IbanAccount Cuenta IBAN a consultar String 35
RequestNumber Nú mero que identifica la solicitud realizada Long
AccessToken Có digo de acceso que permite realizar la consulta en la String 20
entidad destino

7.1.12 GetAccountInfoResponseDTO
Clase que devuelve los datos al consultar una cuenta IBAN
Propiedad Descripción Tipo Long. Max

Account Clase que contiene los datos de la cuenta consutada CuentaIBA

NDTO
IsSuccessful Identificador del canal que está realizando la consulta. Boolean 50
True es exitoso y False con Error
OperationId Identificador del llamado, debe ser ú nico y será el valor String 50
que se debe utilizar para validar contra PCD si hubo algú n
error durante la ejecució n de la solicitud
Errors Lista de errores generados por el sistema de la entidad. Se ErrorDTOI
debe enviar por parte de la entidad la lista de errores para BAN[]
configurarlos en PCD

7.1.13 NaturalPersonRequestDTO
Clase que permite consultar datos personales de un cliente aunque no esté asociado a la entidad
Propiedad Descripción Tipo Long. Max

IdType Tipo de identificació n de la persona para el que se Int

Interfaces con Sistemas Base

 8

solicitan los datos. Segú n cá talogo

CustomerId Nú mero de identificació n del cliente para el que se String 20
solicitan los datos

7.1.14 NaturalPersonResponseDTO
Clase de respuesta de la solicitud de informació n de una persona

Propiedad Descripción Tipo Long.

Max
Success Indica si la solicitud se procesó (true) o si falló (False) Boolean
ErrorCode Có digo de error devuelto por el sistema interno. La entidad Int
deberá enviar el listado de motivos de error vá lidos para ser
devueltos.
NaturalPersonDT Clase con los datos del cliente, si la consulta fue exitosa. NaturalPerson
O

7.1.15 MajorChildrenOvelDTO
Clase de respuesta que contiene la informació n de un hijo mayor de edad.

Propiedad Descripción Tipo Long.

Max
Cedula Nú mero de identificació n del hijo String 20
Edad Edad del hijo String
Bachillerato Indica si tiene bachillerato String

Profesion Indica la profesió n del hijo String

Matrimonios Indica si ha estado casado String
Hijos Indica si tiene hijos String
EconomicoActivo Indica si tiene trabajo actualmente String

7.1.16 PepOvelDTO
Clase de respuesta que contiene la informació n si una persona es PEP (Persona expuesta pó litica o
pú blicamente).

Propiedad Descripción Tipo Long.

Max
Descripcion Lista de descripciones del puesto String[]
InicioPeriodo Indica cuando inicio el puesto político String
FinPeriodo Indica la finalizació n del puesto String
Puesto Detalle del puesto que ocupo String
Institucion Nombre de la institució n donde ocupo el String
cargo

Interfaces con Sistemas Base

 9

PartidoPolitico Descripció n del partido político String

Categoria ? String
Directo ? String

Identificacion Identificació n de la persona cuando String

ocupo el cargo
Nombre Nombre de la persona cuando ocupo el String
cargo
Provincia ? String

Canton ? String
Distrito ? String
TipoFuente ? String
DescripcionRelacion ? String
Pep
CodigoRelacionPep ? String

7.1.17 CustomerOvelDTO
Clase de respuesta de la solicitud de informació n de una persona.

Propiedad Descripción Tipo Long.

Max
ErrorFatal Indica si hubo un error en la consulta (true) Boolean
o no (false)
MensajeErrorFatal Descripció n detallada del problema String 1000
presentado
HijosMayores Lista que contiene el detalle de los hijos MajorChildrenOvelDTO[]
mayores
ListasInternacional No se utiliza actualmente devolver la lista InternationalListOvelDTO[]
es vacía
Tipo ? String 255
Vehiculos Lista que contiene el detalle de los VehicleOvelDTO
vehículos que tiene la persona
Consentimiento ? String 255
UltimaConsulta ? String 255
FiliacionFisica No se utiliza actualmente devolver la lista PhisicalFiliationOvelDTO
vacía
FiliacionJuridica No se utiliza actualmente devolver la lista BusinessAffiliationOvelDTO
vacía
CCSS No se utiliza actualmente devolver la lista CcssOvelDTO
vacía
Contribuyente No se utiliza actualmente devolver la lista ContributorOvelDTO
vacía

Interfaces con Sistemas Base

 10

ActividadEconomic No se utiliza actualmente devolver la lista EconomicActivityOvelDTO

a vacía
PEP Lista de puestos políticos que ha ocupado la PepOvelDTO[]
persona
APNFD Lista de ApnfdOvelDTO[]
Matrimonios Historial de matrimonios MarriageOvelDTO[]
Representaciones No se utiliza actualmente devolver la lista RepresentativeOvelDTO[]
vacía
HijosMenores Lista de hijos menores de edad que tiene la MinorChildrenOvelDTO[]
persona
Parientes Lista de familiares FamilyOvelDTO[]
Localizacion No se utiliza actualmente devolver la lista LocationOvelDTO[]
vacía
Propiedades No se utiliza actualmente devolver la lista PropertyOvelDTO[]
vacía
Fodesaf No se utiliza actualmente devolver la lista FodesafOvelDTO[]
vacía
Juicios No se utiliza actualmente devolver la lista JudmentOvelDTO[]
vacía
Result Indica si la solicitud se procesó (true) o si Boolean
falló (False)
ErrorList Lista de errores del sistema interno ErrorDTOIban[]

7.1.18 CustomerRequestOvelDTO
Clase de solicitud de informació n de una persona

Propiedad Descripción Tipo Long.

Max
ActualizaPeps Boolean
ActualizaArt15 Boolean
ActualizaListasEspeciales Boolean
ActualizaClientesFallecidos Boolean
ActualizaBeneficiariosFallecidos Boolean
ActualizaCodeudoresFallecidos Boolean
ActualizaFiadoresFallecidos Boolean
ActualizaProfesionesNoDesigna Boolean
das
Cedula Nú mero de identificació n de la persona a String 20
consultar
TipoOperacion String 255
AccessToken String 255

Interfaces con Sistemas Base

 11

7.1.19 CustomerResponseOvelDTO
Clase de respuesta de la solicitud de informació n de una persona

Propiedad Descripción Tipo Long.

Max
NumSolicitud Long
P_Actualiza_Art15 Boolean
P_Actualiza_Beneficiarios_Fallecidos Boolean
P_Actualiza_Clientes_Fallecidos Boolean
P_Actualiza_Codeudores_Fallecidos Boolean
P_Actualiza_Fiadores_Fallecidos Boolean
P_Actualiza_Listas_Especiales Boolean
P_Actualiza_Peps Boolean
P_Actualiza_Profesiones_No_Designadas Boolean 20
P_Peps_Actualizados String 255
P_Art15_Actualizados String 255
P_Listas_Especiales_Actualizadas String 255
P_Clientes_Fallecidos_Actualizados String 255
P_Beneficiarios_Fallecidos_Actualizados String 255
P_Codeudores_Fallecidos_Actualizados String 255
P_Fiadores_Fallecidos_Actualizados String 255
P_Profesiones_No_Designadas_Actualiza String 255
das
Ovel CustomerOvelDTO
Result Indica si la solicitud se procesó Boolean
(true) o si falló (False)
ErrorList Lista de errores del sistema ErrorDTOIban[]
interno

7.1.20 ClienteResponseDTO
Clase de respuesta a una solicitud de afiliació n

Propiedad Descripción Tipo Long.

Max
Customer Clase que contiene los datos de un cliente ClienteDTO

7.1.21 ClClienteAfiliarRequestDTO
Clase de solicitud de afiliació n de un cliente

Propiedad Descripción Tipo Long.

Max

Interfaces con Sistemas Base

 12

NumSolicitud Nú mero de solicitud de la afiliació n Long

CodCompania Có digo de compañ ia String
CodigoOperador Có digo del operador Int
CodigoPais Có digo de país String
CodigoCanal Có digo del canal String

ReferenciaCanal ? String

TipoCliente Tipo de cliente segú n catá logo String

CuentaIBAN Cuenta IBAN donde se rebajará el capital String
social
NumeroIdentificacion Nú mero de identificació n de la persona String
TipoIdentificacion Tipo de identificació n segú n catá logo String
Nombre Nombre de la persona String
PrimerApellido Primer apellido de la persona String
SegundoApellido Segundo apellido de la persona String
ConocidoComo Detalle de có mo también es conocida la String
persona
EstadoCivil Estado civil de la persona segú n catá logo String
Nacionalidad Nacionalidad de la persona String
LugarNacimiento Detalle del lugar de nacimiento de la String
persona
FechaNacimiento Fecha de nacimiento de la persona String

Genero Indica el género de la persona segú n Int

catá logo
FechaVencimientoId Fecha de vencimiento de la cédula String

Direcciones Lista de direcciones del cliente InsertCustome

rAddressDTO[]
Telefonos Lista de teléfonos de un cliente PhoneDTO[]
Correos Lista de correos de un cliente EmailDTO[]
TarjetaDebito Solicitud de tarjeta de débito DebitCardReq
DTO[]
AccessToken Có digo de acceso String
TipoProductoSolicitado Lista de productos solicitados durante la CLSolicitudAfil
afiliació n iacionTempTip
oProductoDTO
[]

7.2 Métodos
Método

Interfaces con Sistemas Base

 13

ObtenerInfoCiudadana(request:NaturalPersonRequestDTO): NaturalPersonResponseDTO
Permite obtener los datos completa de una persona aunque no esté asociado a la entidad para validar la carga
de la cédula

GetCustomerOvel (request:CustomerRequestOvelDTO): CustomerResponseOvelDTO

Permite obtener los datos completa de una persona aunque no esté asociado a la entidad

JSONCreateCustomer (request:ClClienteAfiliarRequestDTO): ClienteResponseDTO

Realiza la afiliación de un cliente en el sistema interno.

ValidateAccount (request:GetAccountInfoRequestDTO, string Token, string Calltype):

GetAccountInfoResponseDTO
Permite obtener los datos completa de una cuenta IBAN y validada en la entidad en caso de ser una cuenta
interna o contra SINPE si es externa.

8 Codificaciones

8.1 IdType
Código Descripción
1 Persona física nacional
2 Persona jurídica nacional
3 Extranjero residente
5 Persona extranjera con pasaporte

8.2 Gender
Código Descripción
0 Masculino
1 Femenino

8.3 CurrencyCode
Código Descripción
1 Colones
2 Dó lares

Interfaces con Sistemas Base

 Código Descripción
ES ESPAÑ A
MX MEXICO
14
SV EL SALVADOR
HN HONDURAS
AR ARGENTINA
BO BOLIVIA
CO COLOMBIA
8.4 Countries
CA CANADA
PE PERU
EC ECUADOR
BR BRASIL
TT TRINIDAD Y TOBAGO
IT ITALIA
CR COSTA RICA
PA PANAMA
CU CUBA
NI NICARAGUA
GT GUATEMALA
DE ALEMANIA
US ESTADOS UNIDOS
RU RUSIA
UY URUGUAY
FR FRANCIA
IR IRAN
DK DINAMARCA
JP JAPON
CN CHINA
KZ KAZAJISTAN
AN ANTILLAS
HT HAITI
VE VENEZUELA
CL CHILE
HK HONG KONG
DO REPUBLICA DOMINICANA
HU HUNGRIA
UA UCRANIA
GB REINO UNIDO
NP NEPAL
IL ISRAEL
GR GRECIA
BG BULGARIA
BZ BELICE
RO RUMANIA
Interfaces con Sistemas Base
BE BELGICA
DZ ARGELIA