API Web Services para Integración - Talana · 11/05/2018 Maximiliano Opitz Actualización...

API Web Services para Integración

Talana – Documentación de Web Sevices

Control de Versiones

Fecha Autor Observaciones

20/04/2018 José Antonio Akel Versión Inicial

25/04/2018 José Antonio Akel Formatos de Serialización

4/05/2018 José Antonio Akel Actualización de ausentismos

8/05/2018 José Antonio Akel We Service Centralización Contable

11/05/2018 Maximiliano Opitz Actualización servicios de persona, personaEmpresa y ausentismos

31/08/2018 Maximiliano Opitz Se agrego es especificación del detalle de persona para la creación de persona

11/10/2018 José Antonio Akel Servicios de Marcas de asistencia

12/10/2018 Sebastián Díaz Servicio de Asignación de Items a Persona

19/10/2018 Sebastián Díaz Servicio de creación de documentos para personas

15/11/2018 José Antonio Akel Ejemplos de código

30/11/2018 Alexander Gonzalez Servicios resumidos para contratos, ausencias, vacaciones y días administrativos

17/12/2018 Sebastián Díaz Filtros para servicios de contratos

17/12/2018 José Antonio Akel “empresa” como parámetro en los servicios

18/12/2018 Sebastián Díaz Filtros empleado en vacaciones, ausentismo, días administrativos

21/12/2018 José Antonio Akel Actualización de método de contratos resumidos

26/12/2018 Maximiliano Opitz Se agrego un ejemplo de la inserción de marcas

26/12/2018 Sebastián Díaz Filtros de empleados para vacaciones, ausentismos y contratos resumidos

27/12/2018 Maximiliano Opitz Ejemplo del uso de los filtros en el servicio que devuelve las marcas

08/01/2018 Alexander Gonzalez “rolPrivado” como parámetro en servicio contratos resumido

13/05/2019 Alexander Gonzalez Servicios de firma digital y liquidaciones

Sistemas de Gestión de Recursos Humanos | www.talana.com | Página 2 de 49

http://www.talana.com/


Tabla de Contenidos

Antecedentes......................................................................................................................................5Autenticación......................................................................................................................................6Formatos de salida.............................................................................................................................7Filtros..................................................................................................................................................8EndPoints...........................................................................................................................................8

Empresas con acceso..................................................................................................................8

Persona........................................................................................................................................9

Contratos....................................................................................................................................12

Filtros.......................................................................................................................................... 17

Los siguientes parámetros pueden ser pasados por url para filtrar la lista de contratos:............17

modificado_desde (fecha formato “YYYY-MM-DD”): contratos creados o modificados superiores a la fecha....................................................................................................................................17

modificado_hasta (fecha formato “YYYY-MM-DD”): contratos creados o modificados inferiores a la fecha.......................................................................................................................................17

Ejemplo:.....................................................................................................................................17

https://talana.com/es/api/contratos/?modificado_desde=2018-10-25.........................................17

Contratos Resumido...................................................................................................................18

Vacaciones.................................................................................................................................19

Filtros.......................................................................................................................................... 19


empleado (id del empleado): solo las vacaciones del empleado especificado............................19

Ejemplo:.....................................................................................................................................19

https://talana/es/api/vacacionesSolicitud/?empleado=1..............................................................19

Vacaciones Resumido................................................................................................................20

Ausentismo.................................................................................................................................21

Filtros.......................................................................................................................................... 23


empleado (id del empleado): solo las ausencias del empleado especificado.............................23

Ejemplo:.....................................................................................................................................23

https://talana/es/api/personaAusencia/?empleado=1.................................................................23

Ausentismo Resumido................................................................................................................24




Centralización Contable..............................................................................................................25

Asignación de Items de pago......................................................................................................26

Creación de documentos par personas......................................................................................28

Días Administrativos...................................................................................................................29

Filtros.......................................................................................................................................... 29


empleado (id del empleado): solo los días administrativos del empleado especificado..............29

Ejemplo:.....................................................................................................................................29

https://talana/es/api/diaAdministrativoSolicitud/?empleado=1....................................................29

Días Administrativos Resumido..................................................................................................30

Turno.......................................................................................................................................... 31

Días de Turno Semanal..............................................................................................................32

Días de Turno Manual................................................................................................................33

Asignación de Personas a Turnos..............................................................................................34

Inyección (y visualización) de marcas........................................................................................35

Asignación de tarjetas a personas..............................................................................................36

Turnos y horarios asignados por Trabajador...............................................................................37

Otros Modelos............................................................................................................................38

Ejemplos de Código..........................................................................................................................40Python........................................................................................................................................ 40

Java............................................................................................................................................ 41

PHP............................................................................................................................................ 44




Antecedentes

Talana, dadas sus características como SaaS, no ofrece como opción la conexión directa a base de datos, que es el

mecanismo que se utilizaba con el proveedor anterior. En su lugar, se utilizan Web Services REST, con mensajes

serializados en formato Json, tanto para la lectura como para la escritura de objetos.

El objetivo de este documento es entregar los antecedentes necesarios que permitan construir interfaces de integración

entre sistemas de información de nuestros clientes y los web services de Talana.




Autenticación

Los WebServices son servicios REST con los cuales se pueden gestionar las solicitudes de días libres para los empleados, ya sea para consultar, crear, modificar o eliminar datos. Esta información necesita estar estructurada en formato JSON y los métodos que permite son:

• Listar (GET)

• Crear (POST)

• Modificar (PUT / PATCH)

• Eliminar (DELETE)

Para utilizar cualquiera de los métodos previamente listados es necesario enviar un “token” de autenticación en cada “request” que se realice hacia la plataforma. Para obtener este “token” de autenticación debemos realizar una petición como en el siguiente ejemplo:

URL: https://talana.com/es/api/api-token-auth/

MÉTODO: POST

BODY: {“username”: “[email protected]”, “password”: “demo”}

Donde:

“[email protected]” es el nombre de usuario de la persona a autenticar.

“demo” es la clave de la persona a autenticar.

El formato del contenido del BODY, es JSON.

La respuesta de la anterior consulta es un “String” en formato JSON que contiene el “token”:

{“token”: “ehe657583hgyydt565729g0ddjdg65585hgyyd65”}

Finalmente para su uso, es necesario agregar el “token” en el encabezado de cada consulta:

Authorization: Token ehe657583hgyydt565729g0ddjdg65585hgyyd65



mailto:[email protected]

mailto:[email protected]

https://talana.com/es/api/api-token-auth/


Formatos de salida

La librería utilizada para la construcción de los servicios permite generar datos en múltiples formatos. El serializador se

selecciona por defecto en base al content-type de la solicitud. De esta forma, si se visitan mediante un navegador web, los

servicios entregar HTML. Pero si se consumen con un cliente de WS como Postman, que solicita datos en text/json, escoge

el serializador de manera acorde.

Es posible también “forzar” el formato de salida, enviando como parámetro en la URL el formato.

Por ejemplo, para descargar el listado de bancos desde Talana en formato XML, se puede consumir la siguiente URL:

https://talana.com/es/api/banco/?format=xml

Los formatos soportados en estos momentos son:

• json

• jsonp

• xml

• api



https://talana.com/es/api/banco/?format=xml


Filtros

Algunos de los servicios aceptan filtros como parámetros GET.

Los servicios que entrega colecciones de objetos asociados a una empresa en específica (como los de “contratos” y

“personas”, en contraposición con el de “bancos”, que es común a todas las empresas) aceptan como parámetro el ID de la

empresa de la cual se requieren datos. El servicio devolverá los datos de esa empresa, siempre y cuando el usuario cuente

con los permisos para acceder a esa empresa.

Ejemplo:

https://talana.com/es/api/persona/?empresa=1

y

ht tps://talana.com/es/api/persona/ ? empresa=5

entregarán las personas de las empresas con ID 1 y 5 respectivamente

EndPoints

Si bien Talana expone muchísimos servicios, para efectos de las integraciones típicas basta con considerar los que se

exponen a continuación:

Empresas con acceso

https://talana.com/es/api/empresas-que-puedo-administrar

Entrega el listado de las empresas a las cuales el usuario actual tiene acceso

Métodos aceptados: GET

Devuelve un listado de empresas y sus razones sociales de acuerdo a la siguiente estructura:

Propiedad Tipo Get Descripción

id integer ID único

nombre string Nombre de la empresa

vigente boolean Si la empresa está o no vigente

url string URL de la empresa








logo string URL del logo de la empresa, para utilizar en los

documentos

firma string URL de la firma del representante legal de la

empresa, para utilizar en los documentos

razones_sociales list[razonSocial] Listado de objetos [razonSocial]

Persona

https://talana.com/es/api/persona/{id}

El maestro de personas. Cada persona puede tener uno o más contratos a lo largo de la relación laboral con una empresa, pero sólo tendrá una ficha.

Métodos aceptados: GET, POST, PUT

Para los métodos PUT y POST, la información a enviar deber estar en el “body” del “request” en formato JSON.

Los objetos de persona tienen las siguientes propiedades:

Propiedad Tipo Get Tipo POST,

PUT

Uso Opcional Descripción


fechaCreacion datetime GET Si Fecha y hora de creación

rut string string GET, POST,

PUT

No Rut, sin puntos, con guión y DV

nombre string string GET, POST,

PUT

No Nombre

apellidoPaterno string string GET, POST,

PUT

No Apellido Paterno

apellidoMaterno string string GET, POST,

PUT

No Apellido Materno

sexo char(1) char(1) GET, POST,

PUT

Si M / F

fechaNacimiento date date GET, POST, Si Fecha de Nacimiento




PUT

nacionalidad string string GET, POST,

PUT

Si País, como código ISO

username string string Nombre de usuario

permisos list[permisos] GET Si Lista de permisos adicionales

email string string GET, POST,

PUT

Si Email principal

detalles list[detalles] GET, POST Si Detalles personales

externalReference list[externalRef

erence]

GET Si Lista de Identificadores

Objeto "Detalle" que se usara en la creación de personas

Propiedad Tipo POST Uso Opcional Descripción

id ID único

fechaCreacion date GET, POST Si Fecha y hora de creación

validoDesde date GET, POST No Fecha desde la cual es valido el

detalle

email string GET, POST No Email principal del detalle

telefono string GET, POST No El teléfono del detalle de la

persona

celular string GET, POST,

PUT

No Celular del detalle de la persona

direccionCalle string GET, POST Si Calle del domicilio

direccionNumero String GET, POST No Numero del domicilio

direccionDepartamento String GET, POST No Numero del departamento

estadoCivil String GET, POST No Estado civil de la persona

nivelEducacional String GET, POST No Nivel educacional de la persona




colegio String GET, POST No Colegio de la persona

InstitucionEstudiosSuperiores

String GET, POST No Institución superior de la

persona

profesion String GET, POST No Profesión de la persona

observaciones String GET, POST No Agregar cualquier observación

sobre la persona

contratosDeEmergencia String GET, POST No Agregar cualquier contrato de

emergencia de la persona




Contratos

https://talana.com/es/api/contrato/{id}

El o los contratos de los trabajadores, y sus condiciones contractuales. Muestra los contratos y condiciones activas al día de hoy.

Métodos aceptados: GET, POST, PUT.


Los objetos de tipo contrato tienen las siguientes propiedades:

Propiedad Tipo GET POST, PUT Uso Opcional Descripción

id integer GET No Id único

empleado integer integer GET, POST,

PUT

No Puntero a objeto [persona]

codigo string string GET, POST,

PUT

Si Código del contrato

fechaCreacion datetime GET Si Fecha de Creación original de estas

condiciones contractuales

tipoContrato integer integer GET, POST,

PUT

Si Puntero a objeto [tipoContrato]. Se

especifican detalles en tipoContratoDetails

empleadorRazonSoc

ial

integer integer GET, POST,

PUT

No Puntero a objeto [razonSocial]

cargo string string GET, POST,

PUT

Si

fechaContratacion date date GET, POST,

PUT

Si Fecha de contratación original del trabajador

desde date date GET, POST,

PUT

No Desde cuándo rigen estas condiciones

contractuales

hasta date date GET, POST,

PUT

Si Hasta cuándo rigen estas condiciones.

Puede estar vacío

unidadOrganizacion

al

integer POST, PUT Si Puntero a objeto [unidadOrganizacional]

sucursal [sucursal] integer GET, POST, Si Objeto sucursal




PUT

grupos list[grupo] list[integer] GET, POST,

PUT

Si Lista de los grupos al cual pertenece la

persona

anexo string string GET, POST,

PUT

Si

centroCosto [centroCosto

]

integer GET, POST,

PUT

Si Objeto centroCosto

jornada integer integer GET, POST,

PUT

Si Puntero a objeto [jornada]

horasDeLaJornada integer integer GET, POST,

PUT

Si Cantidad de horas semanales de trabajo

codigoFranquiciaSe

nce


PUT

Si

nivelSence string string GET, POST,

PUT

Si

sindicato integer integer GET, POST,

PUT

Si Puntero a objeto [sindicato]

jefe integer integer GET, POST,

PUT

Si Puntero a objeto [persona]

esPensionado char(1) char(1) GET, POST,

PUT

Si N=No | S=Si | C=Si, pero cotiza | A = Activo >

65 años | X = Expatriado

tramoAsignacionPre

visional


PUT

Si Puntero a objeto [tramoAsignacionFamiliar]

zonaAsignacionPrevi

sional


PUT

Si Puntero a objeto [ubicacionGeografica]

correspondeAsignaci

onMaternal

boolean boolean GET, POST,

PUT

Si Si es que tiene asignación maternal

isapre integer integer GET, POST,

PUT

Si Puntero a objeto [prevision]




montoPactadoIsapre float float GET, POST,

PUT

Si Monto Pactado con Isapre. Si está vacío, se

asume 7%

montoPactadoIsapre

Moneda

string string GET, POST,

PUT

Si Moneda monto pactado. UF=UF | $=Pesos |

7+GES=7%+Ges en UF | 7+GES$=7% +

GES en pesos

afp integer integer GET, POST,

PUT

Si Puntero a objeto [afp]

adscribeASeguroCe

santiaParaContratos

PreviosA2002

boolean GET No Si el trabajador está contratado con fecha

anterior al 2002, si adscribe o no al seguro

de cesantía

apvMonto float GET Si Monto primer APV

apvMoneda string GET Si Moneda APV: UF | $

apvInstitucion integer GET Si Puntero a [institucionAPV]

apvTipo char(1) GET Si Tipo de APV: “A” | “B”

apvCuentaDos float GET Si Monto cuenta dos

apvCuentaDosMone

da

string GET Si Moneda cuenta dos

depositoConvenido

Monto

float GET Si Monto Depósito Convenido

depositoConvenido

Moneda

string GET Si Moneda Depósito Convenido: UF | $

retencionJuducialDe

stinatario

string GET Si Nombre de persona destinatario de retención

judicial

sueldoPatronal boolean GET Si ¿Es sueldo patronal? Sólo para socios de la

empresa

sueldoBase integer integer GET, POST,

PUT

Si Sueldo Base mensual en $

sueldoFormaPago string string GET, POST,

PUT

Si Forma de pago de sueldo.

sueldoBanco id id GET, POST,

PUT

Si Puntero a [banco]




sueldoCuentaCorrie

nte


PUT,

Si Número de cuenta corriente para depósito

sueldoCuentaCorrie

nteTipo


PUT

Si Tipo de cuenta corriente: Cuenta Vista |

Cuenta de Ahorro | Cuenta Corriente

sueldoTipoPago string string GET, POST,

PUT

Si Forma de cálculo sueldo: mensual | diario |

hora

valorHoraExtraPacta

da

float float GET, POST,

PUT

Si

mesesImponiblesrec

onocidos


PUT

Si "Meses que se reconocen como trabajados

de antes de contratar a la persona. Se usan

para los días progresivos

mesesImponiblesRe

conocidosDesde

date date GET, POST,

PUT

Si

vacacionesReconoci

doDesde


PUT

Si Beneficio. Fecha de contratación utilizada

para cálculo de vacaciones progresivas

asignacionMovilizaci

on


PUT

Si Movilización mensual en $

asignacionColacion integer integer GET, POST,

PUT

Si Colación mensual en $

anticipoPactado integer integer GET, POST,

PUT

Si

fechaDeContratacio

nReconocidaParaAn

osDeServicio


PUT

Si Beneficio. Fecha de Contratación a utilizar

para cálculo de años de servicio

pagaTresPrimerosDi

asLicencia


PUT

Si Beneficio. ¿Se subsidian los 3 primeros días

de licencia?

mantieneRentaLiqui

daLicencia


PUT

Si Beneficio. ¿Mantiene la renta líquida durante

las licencias?

diasAdministrativos integer integer GET, POST,

PUT

Si Beneficio. Días administrativos por trabajador

durante el periodo




beneficiosInfoAdicio

nal

string string GET Si String con beneficios adicionales

indemnizacionSinTo

peAnos


PUT

Si Beneficio. Al calcular la indemnización por

años de servicio al finiquitar, ¿se quita el

tope de años?

indemnizacionSinTo

peRenta


PUT

Si Beneficio. Al calcular la indemnización por

años de servicio al finiquitar, ¿se quita el

tope de renta?

diasAdicionalesVaca

ciones


PUT

Si Beneficio. Días adicionales de vacaciones

por año.

creadoPor integer GET Si Creador del contrato. Puntero a [persona]

descripcionDelCargo string string GET, POST,

PUT

Si Descripción en texto del cargo

clausulasAdicionales string string GET, POST,

PUT

Si

detalleAnexoContrat

o


PUT

Si

documentoEsContra

toOAnexo


PUT

No

claseSalarial [claseSalaria

l]

integer GET, POST,

PUT

Si

rolPrivado boolean boolean GET, POST,

PUT, PATCH

Si

asignacionZonaExtr

ema

float GET Si Factor de asignación adicional por zona

extrema

unidadOrganizacion

alDetails

[unidadOrga

nizacional]

GET Si Objeto detallado [unidadOrganizacional]

tipoContratoDetails [tipoContrato

]

GET Si Objeto detallado [tipoContrato]

externalReference list[externalR

eference]

GET Si Objeto detallado con los Ids de este contrato

en otros sistemas




finiquitado boolean boolean GET, POST,

PUT, PATCH

Si ¿Fue finiquitado?

motivoEgreso [motivoEgres

o]

integer GET Si Motivo de término de contrato (si fue

finiquitado)

INE [codigoIne] integer GET, POST,

PUT, PATCH

Si Objeto detallado con el código INE del

trabajador

userDefinedFields list[userDefin

edField]

GET, POST,

PUT, PATCH

Si Listado con campos personalizados

Filtros

Los siguientes parámetros pueden ser pasados por url para filtrar la lista de contratos:

modificado_desde (fecha formato “YYYY-MM-DD”): contratos creados o modificados superiores a la fecha

modificado_hasta (fecha formato “YYYY-MM-DD”): contratos creados o modificados inferiores a la fecha

Ejemplo:

https://talana.com/es/api/contratos/?modificado_desde=2018-10-25




Contratos Resumido

https://talana.com/es/api/contracts-resumed/

Los contratos de los trabajadores y sus condiciones contractuales. Muestra los contratos y condiciones activas al día de hoy.



Propiedad Tipo GET Uso Opcional Descripción

id integer GET No Id único

empleado integer GET No Puntero a objeto [persona]

codigo string GET Si Código del contrato

fechaCreacion datetime GET Si Fecha de Creación original de estas

condiciones contractuales

tipoContrato integer GET Si Puntero a objeto [tipoContrato]. Se

especifican detalles en tipoContratoDetails

empleadorRazonSocial integer GET No Puntero a objeto [razonSocial]

cargo string GET Si

fechaContratacion date GET Si Fecha de contratación original del trabajador

hasta date GET Si Hasta cuándo rigen estas condiciones.

Puede estar vacío

finiquitado boolean GET Si ¿Fue finiquitado?

rolPrivado boolean GET Si ¿Manejar como Rol Privado?

unidadOrganizacional GET Si Puntero a objeto [unidadOrganizacional]

sucursal [sucursal] GET Si Objeto sucursal

jornada integer GET Si Puntero a objeto [jornada]

horasDeLaJornada integer GET Si Cantidad de horas semanales de trabajo

centroCosto [centroCosto] GET Si Objeto centroCosto

personaDetails list[detalles] GET Si Detalles personales

userDefinedFields list[userDefinedField] GET Si Listado con campos personalizados

activo boolean GET (calculado) Si el contrato está activo al




momento de consumir el servicio

Filtros aceptados:

Solo-activos=1 : sólo devuelve los contratos activos al día de hoy

since=<fecha>: devuelve los contratos existentes desde la fecha indicada en adelante, donde <fecha> se especifica en el

formato "%Y%m%d%H%M%S"; por ejemplo “20181224000001”

empleado (id del empleado): solo los contratos del empleado especificado

Vacaciones

https://talana/es/api/ vacacionesSolicitud /

Las solicitudes de vacaciones de los trabajadores, aprobadas o pendientes de aprobación.

Propiedad Tipo Descripción


empleado integer Puntero a [persona]

vacacionesDesde date Fecha inicio de vacaciones

numeroDias float Cantidad de días solicitados

jornada char(1) M=Mañana | T=Tarde (para medios días)

mediosDias boolean ¿Sólo medio día?

vacacionesHasta date Último día de vacaciones solicitado

vacacionesRetorno date Fecha de reincorporación

aprobada char(1) ¿Aprobada?: A=Aprobada | P=Pendiente | R=Rechazada

aprobadaPor integer Puntero a [persona]

creadaPor integer Puntero a [persona]

fechaAprobacion datetime Fecha de Aprobación

detallesTrabajador [persona] Datos detallados del trabajador

externalReference list[externalReference] Objeto detallado con los Ids de este contrato en otros sistemas

fechaCreacion datetime Fecha de Creación

Filtros




https://talana/es/api/validateMark/




empleado (id del empleado): solo las vacaciones del empleado especificado

Ejemplo:

https://talana/es/api/ vacacionesSolicitud /?empleado=1






Vacaciones Resumido

https://talana/es/api/ vacations -resumed/

Las solicitudes de vacaciones de los trabajadores, aprobadas o pendientes de aprobación.




vacacionesDesde date Fecha inicio de vacaciones



vacacionesHasta date Último día de vacaciones solicitado

vacacionesRetorno date Fecha de reincorporación



Filtros


empleado (id del empleado): solo las vacaciones del empleado especificado

Ejemplo:

https://talana/es/api/ vacations - resumed /?empleado=1






Ausentismo

https://talana/es/api/ p ersonaAusencia/{id}

Ausencias por licencias médicas, permisos con o sin goce, etc.

Este endpoint es de Lectura y Escritura.

Métodos aceptados: GET, POST, PUT


Propiedad Tipo GET Tipo POST,

PUT

Uso Opcional Descripción

id integer GET Si ID único

empleado integer integer GET, POST,

PUT

No Puntero a [persona]

fechaDesde date date GET, POST,

PUT

No Fecha inicio de ausencia

numeroDias float float GET, POST,

PUT

No Cantidad de días solicitados

jornada char(1) GET Si M=Mañana | T=Tarde (para medios días)

mediosDias boolean boolean GET, POST,

PUT

Si ¿Sólo medio día?

fechaHasta date GET Si Último día de ausencia

fechaRetorno date GET Si Fecha de reincorporación

aprobada char(1) GET Si ¿Aprobada?: A=Aprobada | P=Pendiente |

R=Rechazada

aprobadaPor integer integer GET Si Puntero a [persona]

creadoPor integer GET Si Puntero a [persona]

fechaAprobaci

on

datetime GET Si Fecha de Aprobación

detallesTrabaja

dor

[persona] GET Si Datos detallados del trabajador

externalRefere

nce

list[externalR

eference]

GET Si Objeto detallado con los Ids de este contrato en

otros sistemas






fechaCreacion datetime GET Si Fecha de Creación

numeroLicenci

a


PUT

Si Número de Licencia médica (opcional)

medicoLicencia string string GET, POST,

PUT

Si Nombre del médico que emitió la licencia

(opcional)

tipoAusencia string string GET, POST,

PUT

No Tipo de ausencia. Puntero a [tipoAusencia]

documentacion string string GET Si Documentación adicional presentada por el

trabajador (opcional)

esContinuacion boolean boolean GET, POST,

PUT

Si ¿es continuación de una licencia anterior?

Este método permite la creación de ausencias, al consumirlo con los métodos POST o PUT con un payload con una estructura como la siguiente:

{

"mediosDias": true,

"tipoAusencia": "string",

"empleado": "string",

"numeroLicencia": "string",

"fechaDesde": "string",

"medicoLicencia": "string",

"motivo": "string",

"numeroDias": 0,

"esContinuacion": true

}

Bajo este esquema, sólo se acepta el siguiente subset de propiedades:



fechaDesde date Fecha inicio de ausencia






numeroLicencia string Número de Licencia médica (opcional)

medicoLicencia string Nombre del médico que emitió la licencia (opcional)

tipoAusencia string Tipo de ausencia. Puntero a [tipoAusencia]

esContinuacion boolean ¿es continuación de una licencia anterior?

Filtros


empleado (id del empleado): solo las ausencias del empleado especificado

Ejemplo:

https://talana/es/api/ p ersonaAusencia/?empleado=1






Ausentismo Resumido

https://talana/es/api/ absentism-resumed

Ausencias por licencias médicas, permisos con o sin goce, etc.

Este endpoint es de Lectura.


Propiedad Tipo GET Uso Opcional Descripción

id integer GET Si ID único

empleado integer GET No Puntero a [persona]

fechaDesde date GET No Fecha inicio de ausencia

numeroDias float GET No Cantidad de días solicitados

fechaHasta date GET Si Último día de ausencia

fechaRetorno date GET Si Fecha de reincorporación

fechaAprobacion datetime GET Si Fecha de Aprobación

fechaHoraAprobacion datetime GET Si Fecha y hora de Aprobación

fechaCreacion datetime GET Si Fecha de Creación

tipoAusencia string GET No Tipo de ausencia. Puntero a [tipoAusencia]

Filtros


empleado (id del empleado): solo las ausencias del empleado especificado

Ejemplo:

https://talana/es/api/ absentism-resumed/?empleado=1






Centralización Contable

https://talana.com/es/api/centralizacion-contable-generica?ano=<ano>&mes=<mes>&empresa=<id_empresa>

Este servicio permite descargar la centralización contable, pero desagregado a nivel de datos.

Recibe los siguientes parámetros como argumentos GET:

• ano: El número del año a centralizar (obligatorio)

• mes: El número del mes a centralizar (obligatorio)

• format: El formato de salida (json , xml) (opcional; default json)

• empresa: El ID de la empresa (opcional) (sólo si la cuenta de acceso es multiempresa)

Este endpoint se basa en los mismos módulos de centralización contable que generan los archivos en formato csv o excel, por lo que son susceptibles de ser parametrizados hasta cierto punto. Es posible, por ejemplo, parametrizar las columnas y criterios que se usan para consolidar (“aggregation”) las filas.


razonSocial__nombre String Razón social del empleador

razonSocial String Rut de la razón social del empleador

nombreTrabajador String Nombre del Trabajador (para ítems desglosados por trabajador)

rutTrabajador String Rut del Trabajador (para ítems desglosados por trabajador)

sucursal__codigo String Sucursal asignada al trabajador (código)

sucursal__nombre String Sucursal asignada al trabajador (nombre)

item String El nómbre del ítem (ej: sueldo base)

item__codigo String Código asignado al ítem

item__nombreParametro String Cödigo de ítem asignado por Talana

year Integer Año del periodo centralizado

month Integer Mes del periodo centralizado

centroCosto__nombre String Nombre del centro de costo asignado a esa línea

centroCosto__codigo String Código del centro de costo asignado a esa línea

debe Integer Valor del “debe”

haber Integer Valor del “haber”

cuentaContable__codigo String Código cuenta Contable asignada

cuentaContable__nombre String Nombre cuenta Contable asignada




Asignación de Items de pago

https://talana.com/es/api/remuneraciones/item-pago/asignacion/

Servicio para agregar o actualizar el valor de un ítem de pago para un contrato en el periodo actual, basándose en el rut del empleado o el id del contrato.

Métodos aceptados: POST

Propiedad POST Uso Opcional Descripción

tipo_item string POST No Nombre del item de pago

valorFijo float POST No Valor a insertar o actualizar

id_contrato integer POST Si Id del contrato

rut_empleado string POST Si Rut del empleado

Ejemplo de request

{

"tipo_item": “bonoDeProduccion”,

"valorFijo": 123456,

“id_contrato”: 367

}

ó

{

"tipo_item": “bonoDeProduccion”,

"valorFijo": 123456,

“rut_empleado”: “10253930-3”

}

https://talana.com/es/api/remuneraciones/item-pago/asignacion/<id_persona>/<tipo_item>/

Servicio para leer el valor de una asignación de un item de pago.


Propiedad GET Uso Opcional Descripción

valorFijo float GET No Valor del item de pago




Creación de documentos par personas

https://talana.com/es/api/remuneraciones/documentos/

Servicio para agregar documentos a la carpeta de una persona.

Métodos aceptados: POST

Propiedad POST Uso Opcional Descripción

empleado integer POST Si (si

existe rut)

Id persona

rut string POST Si (si

existe

empleado)

Rut de la persona

adjunto multipart POST No El documento

nombre string POST No Id del contrato

categoria string POST Si Nombre de la categoría

puedeVerloElTrabajador boolean POST Si Visibilidad del documento para el

dueño de éste




Días Administrativos

https://talana/es/api/ diaAdministrativo Solicitud /

Días administrativos solicitados por el trabajador




desde date Fecha inicio de solicitud


jornada char(1) M=Mañana | T=Tarde (para medios días)


hasta date Último día solicitado

retorno date Fecha de reincorporación

aprobada char(1) ¿Aprobada?: A=Aprobada | P=Pendiente | R=Rechazada

aprobadaPor integer Puntero a [persona]

creadaPor integer Puntero a [persona]

detallesTrabajador [persona] Datos detallados del trabajador


Filtros


empleado (id del empleado): solo los días administrativos del empleado especificado

Ejemplo:

https://talana/es/api/ diaAdministrativo Solicitud / ?empleado=1












Días Administrativos Resumido

https://talana/es/api/administrative-leaves-resumed/

Días administrativos solicitados por el trabajador




desde date Fecha inicio de solicitud



hasta date Último día solicitado

retorno date Fecha de reincorporación







Enrrolamiento de firma digital

https://talana.com/es/api/enrolments/

Lista de enrolamientos de la empresa




rut String Rut del Trabajador

vigente Boolean Flag que muestra si el enrolamiento esta vigente

tipo String Tipo de enrolamiento

fechaCreacion Date Fecha de creación del enrolamiento

mobileNumber String Numero de teléfono del enrolamiento

creadoPor Integer Puntero a [persona]





Solicitudes de firma digital

https://talana.com/es/api/signature-requests/

Lista de solicitudes de firma de la empresa




documentUrl String URL de verificación del documento

documentType String Tipo de documento

documentReference integer ID único del documento

signed boolean Flag que muestra si el documento esta firmado

requestTS datetime Fecha de creación de la solicitud

uuid String Código único de la solicitud

Atributos del registro de detalles asociado a la solicitud de firma (una por cada empleado que firma)



requestedUser integer Puntero a [persona]

signed boolean Flag que muestra si esta solicitud de firma por empleado fue firmada

status String Estado de la solicitud de firma

token String ID único del documento

signatureTS datetime Timestamp de la firma

TSASignature datetime Timestamp de la TAS de la firma

ip String IP desde donde se firmo

userAgent String Agente desde el cual se firmo

passVerification String Hash de verificación de la firma

huella String Información de la huella





Turno

https://talana.com/es/api/workShift/

La definición de los turnos.



name string Nombre asignado

holidaysConsider boolean ¿Considera trabajar los días festivos?

tolerance float Tolerancia en minutos respecto a atrasos y adelantos

workShiftType char(1) Tipo de rotación: W=Semanal | M=Manual

schedule string Resumen de horarios considerados (ej: “09:00 : 19:00”)

publicId integer ID correlativo sólo para la empresa




Días de Turno Semanal

https://talana.com/es/api/rotativeDay/

El detalle de los días asociados a un turno con rotación semanal



name string Nombre del día

numberSnackMinutes integer Duración de la colación, en minutos

startWorkingHours string Hora de inicio, en formato “HH:MM:SS”

numberWorkingMinutes integer Duración en minutos

workingDay boolean Ese día de la semana ¿se trabaja en este turno?

numberWorkingDay integer Día de la semana (en base 0)

workShift integer Puntero a [workShift]




Días de Turno Manual

https://talana.com/es/api/specificDay/

El detalle de los días asociados a un turno de construcción “manual”



date string Fecha del día, en formato “YYYY-mm-dd”

startWorkingHours string Hora de inicio, en formato “HH:MM:SS”

numberWorkingMinutes integer Duración en minutos

workingDay boolean Ese día ¿se trabaja en este turno?

workShift integer Puntero a [workShift]




Asignación de Personas a Turnos

https://talana.com/es/api/workShiftPersonRange/

Asignación de personas a turnos por rango de fechas. Una persona puede tener más de un turno asignado el mismo día.



fromDate string Fecha de inicio de asignación, en formato “YYYY-mm-dd”

toDate string Fecha de fin de asignación, en formato “YYYY-mm-dd”

person integer Persona asignada. Puntero a [persona]

workShift integer El turno asignado. Puntero a [workShift]




Inyección (y visualización) de marcas

http://talana.com/es/api/mark/

Métodos aceptados: GET, POST,

Para el método POST, la información a enviar deber estar en el “body” del “request” en formato JSON.

Para la cración de marcas, se debe recibir rut o card_id

Los objetos de persona tienen las siguientes propiedades:

Propiedad Tipo GET Tipo POST Uso Opcional Descripción


person [persona] - GET - Detalles de la persona que marcó

rut - string POST Si Rut, sin puntos, con guión y DV

card_id - string POST Si El código de tarjeta asignado

office integer integer GET, POST Si ID en Talana de la sucursal

direction char(1) char(1) GET, POST Si Dirección de la marca. (Tipo

Marca)

“E” = Enter

“X” = Exit

TS timestamp timestamp GET, POST No Fceha y Hora real de marca.

Formato "2018-07-13T17:22:21"

sourceMark string string GET, POST Si Fuente de la marca (usar como

Tipo de Actualización de Registro)

received_datetime timestamp timestamp GET, POST No Fecha y hora de recepción de

marca

Formato "2018-07-13T17:22:21"




Ejemplo:

Este JSON debe ir en el cuerpo del request. Es importante destacar que ante cualquier error, el servicio entregara el detalle

de este.

{ “rut": "17798529-5", "direction": "E", "TS": "2019-01-01T00:00:00"}

También es posible aplicar filtros a la llamada de las marcas que son realizadas con el método GET:

• desde(YYYY-MM-DD): Fecha desde la cual se obtendrán las marcas hacia adelante.

• hasta(YYYY-MM-DD): Fecha hasta la cual se obtendrán las marcas hacia atrás.

• person(Numero): Id de a persona a obtener sus macas

Ejemplo de URL:

https://dev.talana.com/es/api/mark/?desde=2018-11-01&hasta=2018-11-01

** Importante: para la realización de la consulta debe estar el Token ingresado en los headers. Dependiendo de los

permisos del usuario, también entregara solo las marcas que tiene permitido ver.

Asignación de tarjetas a personas.

https://talana.com/es/api/zkcard/

Se entiende que se asigna la tarjeta con el código indicado de ahora en adelante.

Si es que la tarjeta ya está asignada a otra persona, el sistema no lo permite y arroja un error.

Para desasignar una tarjeta a una persona se le debe asignar el número null,”” o no enviando el valor de “card_id”

Métodos aceptados: GET, POST

Para el método POST, la información a enviar deber estar en el “body” del “request” en formato JSON.


Propiedad Tipo GET POST Uso Opcional Descripción

rut string string GET, POST No Rut, sin puntos, con guión y DV

card_id string string GET, POST Si Código de la tarjeta, o null para

desasignar



https://dev.talana.com/es/api/mark/?desde=2018-11-01&hasta=2018-11-01


Turnos y horarios asignados por Trabajador

https://talana.com/es/api/workShiftPersonRange/getAssignationsDays/

Este servicio entrega la obligación de marcar y los horarios asociados a cada trabajador en el rango de fecha indicados.

Recibe como parámetros la fecha de inicio y de fin del periodo a revisar, en las variables:

fromDate: fecha de inicio del periodo a revisar

toDate: fecha de fin del periodo a revisar

Ejemplo:

https://talana.com/es/api/workShiftPersonRange/getAssignationsDays/?fromDate=2018-04-01&toDate=2018-04-09




person integer Id de persona

personName string Nombre y apellidos de la persona

rut string Rut de la persona

days [ asignacion ] Lista de objetos de tipo “asignacion”

Cada objeto de tipo “asignación” tiene las siguientes propiedades:


workshift string Nombre del turno asignado

card string Código de la tarjeta asignado para ese día

entranceTime timestamp Fecha y hora de entrada del trabajador

exitTime timestamp Fecha y hora de salida del trabajador

hasToMark boolean ¿debe marcar ese día?

reason string La razón por la cual no debe marcar ese día




Otros Modelos

A continuación enumeramos varios servicios que exponen otros modelos que pueden ser relevantes:

Paises / Nacionalidades:

https://talana.com/es/api/pais/

Bancos:

https://talana.com/es/api/banco/

Formas de Pago:

https://talana.com/es/api/formas-de-pago/

Tipos de Jornada Laboral:

https://talana.com/es/api/jornadaLaboral/

Tipos de Contrato:

https://talana.com/es/api/tipoContrato/

Árbol de Ubicaciones geográficas:

https://talana.com/es/api/ubicacionGeografica/

Instituciones Previsionales (Isapres / Fonasa):

https://talana.com/es/api/prevision/

AFPs:

https://talana.com/es/api/afp/

Instituciones de APV:

https://talana.com/es/api/institucionAPV/

Cajas de Compensación:

https://talana.com/es/api/cajaCompensacion/

Mutuales de Seguridad:

https://talana.com/es/api/mutualSeguridad/

Razones Sociales de la empresa:

https://talana.com/es/api/razonSocial/

Tipos de Ausencia

https://talana.com/es/api/tipoAusencia/

Fecha del servidor:

https://talana.com/es/api/fechaserver/

Hora del Servidor:






https://talana.com/es/api/tipoAusencia/

https://talana.com/es/api/razonSocial/

https://talana.com/es/api/mutualSeguridad/

https://talana.com/es/api/cajaCompensacion/

https://talana.com/es/api/institucionAPV/

https://talana.com/es/api/afp/

https://talana.com/es/api/prevision/

https://talana.com/es/api/ubicacionGeografica/

https://talana.com/es/api/tipoContrato/

https://talana.com/es/api/jornadaLaboral/

https://talana.com/es/api/formas-de-pago/

https://talana.com/es/api/banco/


Unidades Organizacionales de la empresa:

https://talana.com/es/api/unidadOrganizacional/

Sindicatos de la empresa:

https://talana.com/es/api/sindicatoEmpresa/

Sucursales de la empresa:

https://talana.com/es/api/sucursal/

Centros de costo de la empresa:

https://talana.com/es/api/centroCosto/

Cuentas contables de la empresa:

https://talana.com/es/api/cuentaContable/



https://talana.com/es/api/cuentaContable/

https://talana.com/es/api/centroCosto/

https://talana.com/es/api/sucursal/

https://talana.com/es/api/sindicatoEmpresa/

https://talana.com/es/api/unidadOrganizacional/


Ejemplos de Código

Python

#!/usr/bin/python

import requests

# 1 - Obtenemos el token

url = "https://dev.talana.com/es/api/api-token-auth/"

user = "[email protected]"

password = "PasswordDePrueba"

response = requests.post(url, json={"username" : user, "password": password})

token = response.json()["token"]

# 2 - con ese token, consumimos el servicio de personas

url_personas = "https://dev.talana.com/es/api/persona"

response = requests.get(url_personas, headers={"Authorization": "Token {}".format(token)})

for p in response.json():

print "Persona:", p

# 3 - Inyectar una marca de asistencia para la 1a persona

from datetime import datetime as dt

url_marcas = "http://dev.talana.com/es/api/mark/"

persona = response.json()[0]

persona_id = persona["id"]

persona_rut = persona["rut"]

response = requests.post( url_marcas,

json={

"rut" : persona_rut,

"direction" : "E",

"TS" : dt.now().strftime("%Y-%m-%dT%H:%M:%S"),

"sourceMark": "Ej. Script de Integracion"},

headers={"Authorization": "Token {}".format(token)}

)

print response




Java

Puede descargar una copia completa de este mini-proyecto aquí:

https://git.linq.cl/kziete/ejemplo-consumo-api/

ApiClient.java:

package com.talana;

import java.io.BufferedReader;import java.io.IOException;import java.io.InputStreamReader;import java.net.HttpURLConnection;import java.net.MalformedURLException;import java.net.URL;

public class APIClient { private static final String API_URL = "https://talana.com/es/api/"; private static final String TOKEN = "INSERTAR_AUTH_TOKEN_AQUI";

public String get(String path){ URL url = null; try { url = new URL(API_URL + path); HttpURLConnection conn = (HttpURLConnection)url.openConnection(); setHeaders(conn);

conn.setRequestMethod("GET"); conn.setUseCaches(false); conn.setDoInput(true);

return responseToString(conn);

} catch (MalformedURLException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } return null; }

private String responseToString(HttpURLConnection conn) throws IOException { BufferedReader br = null; try { br = new BufferedReader(new InputStreamReader((conn.getInputStream()))); } catch (IOException e) { e.printStackTrace(); } StringBuilder sb = new StringBuilder(); String output; while ((output = br.readLine()) != null) { sb.append(output); } return sb.toString(); }

private void setHeaders(HttpURLConnection conn) { conn.setRequestProperty("Authorization", "Token " + TOKEN); conn.setRequestProperty("Accept", "application/json"); conn.setRequestProperty("Content-Type", "application/json;charset=utf-8"); }}



https://git.linq.cl/kziete/ejemplo-consumo-api/


parser.java:

package com.talana;

import com.talana.models.Person;import org.json.simple.JSONArray;import org.json.simple.JSONObject;import org.json.simple.parser.JSONParser;import org.json.simple.parser.ParseException;

import java.util.ArrayList;import java.util.List;

public class Parser { public static List<Person> getPersonList(String json) { List<Person> persons = new ArrayList<>();

JSONParser parser = new JSONParser(); Object obj = null; try { obj = parser.parse(json); } catch (ParseException e) { e.printStackTrace(); } JSONArray array = (JSONArray)obj;

for(Object per: array){ JSONObject object = (JSONObject)per; persons.add(getPerson(object)); }

return persons; }

public static Person getPerson(JSONObject object){ Person person = new Person(); person.rut = (String)object.get("rut"); person.apellidoPaterno = (String)object.get("apellidoPaterno"); person.apellidoMaterno = (String)object.get("apellidoMaterno"); person.nombre = (String)object.get("nombre");

person.detalles = new ArrayList<>(); JSONArray details = (JSONArray)object.get("detalles");

for(Object det: details){ JSONObject obj = (JSONObject)det;

Person.PersonDetail detail = new Person.PersonDetail(); detail.foto = (String)obj.get("foto");

person.detalles.add(detail); }

return person; }}




main.java:

package com.talana;

import com.talana.models.Person;

import java.util.List;

public class Main {

public static void main(String[] args) { APIClient client = new APIClient();

String jsonResponse = client.get("persona/");

List<Person> persons = Parser.getPersonList(jsonResponse);

for(Person per:persons){ System.out.println(per.toString()); } }}

models/person.java:

package com.talana.models;

import java.util.List;

public class Person { public String rut; public String apellidoPaterno; public String apellidoMaterno; public String nombre; public List<PersonDetail> detalles;

public static class PersonDetail{ public String foto;

@Override public String toString() { return "PersonDetail{" + "foto='" + foto + '\'' + '}'; } }

@Override public String toString() { return "Person{" + "rut='" + rut + '\'' + ", apellidoPaterno='" + apellidoPaterno + '\'' + ", apellidoMaterno='" + apellidoMaterno + '\'' + ", nombre='" + nombre + '\'' + ", detalles=" + detalles + '}'; }}




PHP

<?php

# 1.- Obtencion del Token

# Username$username = "[email protected]";# Contraseña$password = "PasswordDeIntegracion";

#URL para obtener el Token$url_solicitud_token = 'https://talana.com/es/api/api-token-auth/';

# Creamos un "stream context" que contiene la peticion y los encabezados$solicitud_token = json_encode(

array("username" => $username, "password" => $password));

$context = stream_context_create(array("http" => array(

"method" => "POST","content" => $solicitud_token,'header'=> "Content-type: application/json"

)));

# Realizamos la llamada$response = file_get_contents('https://talana.com/es/api/api-token-auth/', FALSE, $context);# Y obtenemos el token$token = json_decode($response)->token;

print "Token obtenido:" . $token . "\n";

# 2.- Consumo de servicio

# La URL del servicio para obtener los paises$url_paises = "https://talana.com/es/api/pais/";

#Creamos un stream context, que incluye los encabezados con el Token$context = stream_context_create(array( "http" => array( "method" => "GET", 'header'=> "Content-type: application/json\nAuthorization: Token $token")));

#Hacemos la llamada$response = file_get_contents($url_paises , FALSE, $context);

# Interpretamos el Json para obtener los datos como un arreglo$paises = json_decode($response);

print_r($paises);

# 3.- Inyección de items de pago

$url_inyeccion_items_pago = "https://talana.com/es/api/remuneraciones/item-pago/asignacion/";

$datos = array( "tipo_item" => "BonoporServicio", "rut_empleado" => "9538055-5", "valorFijo" => "101");$payload = json_encode($datos);

$context = stream_context_create(array( "http" => array(

"method" => "POST","content" => $payload,'header'=> "Content-type: application/json\nAuthorization: Token $token")));

$response = file_get_contents($url_inyeccion_items_pago, FALSE, $context );

print_r($response);



API Web Services para Integración - Talana · 11/05/2018 Maximiliano Opitz Actualización...

Documents

Transcript of API Web Services para Integración - Talana · 11/05/2018 Maximiliano Opitz Actualización...