Histórico da Página

...

Totvs custom tabs box

tabs	Filiais,Controle do Ponto ERP,Integração Clock In, E-mail
ids	filiais,ponto,clockin,email

Totvs custom tabs box items

default	yes
referencia	filiais

Filiais - api/rh/v1/DbHrBranches

API responsável por trazer todas as filiais para serem utilizadas no filtro do Dashboard RH. Assim será possível ter uma visão macro da empresa ou apenas de uma filial em específico.

Ativação/Desativação da API

Por padrão esta API estará no sistema, porém será necessário realizar a devida configuração do serviço REST.

Configuração de Webservice Rest no Protheus no formato apresentado na seguinte documentação (Exemplo de Configuração de Webservice REST)

Controle de Ambiente

Exige que os seguintes pontos sejam revisados:

Protheus com sua arquitetura devidamente estruturada.

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância da linha Protheus.

Suporte

O suporte aos recursos da API será de responsabilidade da linha Protheus onde será analisada pela equipe de suporte da Totvs.

Fluxo das Informações

Esta API traz a funcionalidade exclusivamente para consultar todas as filiais cadastradas para serem utilizadas no filtro do Dashboard RH.

Cadastro

Esta API contempla apenas a consulta das filiais cadastradas.

Processos

O Dashboard RH realizará o consumo da API para buscar todas as filiais.

Como realizar a chamada da API REST

Preenchimento do EndPoint da API PONAPIDSB;
Utilizar a chamada do método Get e do Serviço api/rh/v1/DbHrBranches;

Internamente o Protheus identifica automaticamente o endereço do servidor REST, porém para que isso aconteça será necessário habilitar a porta multiprotocolo do Appserver. Para mais informações sobre a porta multiprotocolo acesse o link abaixo:
https://tdn.totvs.com/x/jIUoI

Formatos de Data

Por ser uma API que retorna todas as filiais, não existe qualquer parâmetro que precisa ser enviado.

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta Postman e após a configuração do server protheus a API Rest, a requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}:{porta}/{endereço Rest}/api/rh/v1/DbHrBranches

Response da API:

Application/json
{
"branches": [
"D MG 01 ",
"D MG 02 ",
"D RJ 01 ",
"D RJ 02 ",
"M PR 01 ",
"M PR 02 ",
"M SP 01 ",
"M SP 02 ",
"M SP 03 "
]
}

Totvs custom tabs box items

default	no
referencia	ponto

Ponto Completo e Incompleto - api/rh/v1/DbHrAttendanceControl

API responsável por retornar o total de funcionários, funcionários com o ponto completo, incompleto e sem marcações, que não foram demitidos antes do período selecionado ou os funcionários demitidos dentro do período selecionado. Basicamente esta API irá verificar a quantidade de marcações realizadas no período pelo funcionário e irá validar com a quantidade em que o funcionário deveria realizar de acordo com o seu turno. Por exemplo um funcionário precisa realizar a marcação do ponto 4 vezes ao dia (entrada jornada, saída para o almoço, volta do almoço e saída da jornada). Na semana o funcionário trabalha de segunda à sexta, então teremos 5 dias trabalhados, onde cada dia o funcionário precisa bater o ponto 4 vezes, totalizando 20 marcações na semana. Se o funcionário possuir 20 ou mais marcações o sistema irá contabilizar como ponto completo, caso o funcionário tenha menos de 20 marcações na semana, será considerado como ponto incompleto.

Observação: O dia da demissão do funcionário contará como dia trabalhado, caso o funcionário seja demitido no dia 19/08/2022 e o filtro do período é de 01/08/2022 à 19/08/2022, a quantidade de marcações do dia 19/08/2022 será contabilizado normalmente.

Ativação/Desativação da API

Por padrão esta API estará no sistema, porém será necessário realizar a devida configuração do serviço REST.

Configuração de Webservice Rest no Protheus no formato apresentado na seguinte documentação (Exemplo de Configuração de Webservice REST)

Controle de Ambiente

Exige que os seguintes pontos sejam revisados:

Protheus com sua arquitetura devidamente estruturada.

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância da linha Protheus.

Suporte

O suporte aos recursos da API será de responsabilidade da linha Protheus onde será analisada pela equipe de suporte da Totvs.

Fluxo das Informações

Esta API traz a funcionalidade exclusivamente para trazer o total de funcionários, funcionários que estão com o ponto completo, incompleto e sem marcações

Cadastro

Esta API contempla as consultas do cadastro de funcionários, turnos, tabela de horário padrão e marcações realizadas pelo funcionários.

Processos

O Dashboard RH realizará o consumo da API para buscar e exibir a quantidade total de funcionários, funcionários que estão com o ponto completo, incompleto e sem marcações

Como realizar a chamada da API REST

Preenchimento do EndPoint da API PONAPIDSB;
Utilizar a chamada do método Post e do Serviço api/rh/v1/DbHrAttendanceControl;
Preenchimento dos parâmetros obrigatórios da API;

Internamente o Protheus identifica automaticamente o endereço do servidor REST, porém para que isso aconteça será necessário habilitar a porta multiprotocolo do Appserver. Para mais informações sobre a porta multiprotocolo acesse o link abaixo:
https://tdn.totvs.com/x/jIUoI

Formatos de Data

As Entradas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DD

Parâmetros de Entrada:

Parâmetro	Valor de Exemplo	Obrigatório	Tipo	Parâmetro	Descrição
startDate	2022-11-01	Sim	Date	Body	Data inicial do período.
endDate	2022-11-11	Sim	Date	Body	Data final do período.
branches	["D MG 01"] ["D MG 01","M SP 01"] ["todas"]	Sim	Array	Body	Filtro da filial.
accept	application/json	Sim	String	Header
content-type	application/json	Sim	String	Header

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta Postman e após a configuração do server protheus a API Rest, a requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}:{porta}/{endereço Rest}/api/rh/v1/DbHrAttendanceControl

Response da API:

Application/json

Bloco de código

title	Resposta API

{
    "1": {
        "branch": "Todas as Filiais",
        "totalEmployees": 6,
        "totalDetails": [
            {
                "branch": "D MG 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT COMPLETO",
                "department": "DEPARTAMENTO 1 RH"
            },
            {
                "branch": "D MG 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "DEPARTAMENTO 1 RH"
            },
            {
                "branch": "D MG 01 ",
                "registration": "003923",
                "name": "DRHJORNPRT-3921 SEM MARCACOES",
                "department": "DEPARTAMENTO 1 RH"
            },
            {
                "branch": "M SP 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "GPE001- OPERACIONAL - SP"
            },
            {
                "branch": "M SP 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 SEM MARCACOES",
                "department": "GPE001- OPERACIONAL - SP"
            },
            {
                "branch": "M SP 01 ",
                "registration": "003923",
                "name": "DRHJORNPRT-3921 PT COMPLETO",
                "department": "GPE001- OPERACIONAL - SP"
            }
        ],
        "clockMarkingsComplete": 2,
        "completeDetails": [
            {
                "branch": "D MG 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT COMPLETO",
                "department": "DEPARTAMENTO 1 RH"
            },
            {
                "branch": "M SP 01 ",
                "registration": "003923",
                "name": "DRHJORNPRT-3921 PT COMPLETO",
                "department": "GPE001- OPERACIONAL - SP"
            }
        ],
        "clockMarkingsIncomplete": 2,
        "incompleteDetails": [
            {
                "branch": "D MG 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "DEPARTAMENTO 1 RH",
                "dateTime": "01/03/2023",
                "reason": "2 Marcaões faltantes",
                "estimated": "09:00 - 12:00 - 13:00 - 18:00",
                "performed": "09:00 - 12:00"
            },
            {
                "branch": "D MG 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "DEPARTAMENTO 1 RH",
                "dateTime": "02/03/2023",
                "reason": "Dia sem marcação",
                "estimated": "09:00 - 12:00 - 13:00 - 18:00",
                "performed": ""
            },
            {
                "branch": "M SP 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "GPE001- OPERACIONAL - SP",
                "dateTime": "01/03/2023",
                "reason": "Dia sem marcação",
                "estimated": "09:00 - 12:00 - 13:00 - 18:00",
                "performed": ""
            },
            {
                "branch": "M SP 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "GPE001- OPERACIONAL - SP",
                "dateTime": "02/03/2023",
                "reason": "1 Marcação faltante",
                "estimated": "09:00 - 12:00 - 13:00 - 18:00",
                "performed": "12:00 - 13:00 - 18:00"
            }
        ],
        "withoutClockMarkings": 2,
        "withoutDetails": [
            {
                "branch": "D MG 01 ",
                "registration": "003923",
                "name": "DRHJORNPRT-3921 SEM MARCACOES",
                "department": "DEPARTAMENTO 1 RH"
            },
            {
                "branch": "M SP 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 SEM MARCACOES",
                "department": "GPE001- OPERACIONAL - SP"
            }
        ]
    },
    "2": {
        "branch": "D MG 01",
        "totalEmployees": 3,
        "totalDetails": [
            {
                "branch": "D MG 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT COMPLETO",
                "department": "DEPARTAMENTO 1 RH"
            },
            {
                "branch": "D MG 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "DEPARTAMENTO 1 RH"
            },
            {
                "branch": "D MG 01 ",
                "registration": "003923",
                "name": "DRHJORNPRT-3921 SEM MARCACOES",
                "department": "DEPARTAMENTO 1 RH"
            }
        ],
        "clockMarkingsComplete": 1,
        "completeDetails": [
            {
                "branch": "D MG 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT COMPLETO",
                "department": "DEPARTAMENTO 1 RH"
            }
        ],
        "clockMarkingsIncomplete": 1,
        "incompleteDetails": [
            {
                "branch": "D MG 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "DEPARTAMENTO 1 RH",
                "dateTime": "01/03/2023",
                "reason": "2 Marcaões faltantes",
                "estimated": "09:00 - 12:00 - 13:00 - 18:00",
                "performed": "09:00 - 12:00"
            },
            {
                "branch": "D MG 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "DEPARTAMENTO 1 RH",
                "dateTime": "02/03/2023",
                "reason": "Dia sem marcação",
                "estimated": "09:00 - 12:00 - 13:00 - 18:00",
                "performed": ""
            }
        ],
        "withoutClockMarkings": 1,
        "withoutDetails": [
            {
                "branch": "D MG 01 ",
                "registration": "003923",
                "name": "DRHJORNPRT-3921 SEM MARCACOES",
                "department": "DEPARTAMENTO 1 RH"
            }
        ]
    },
    "3": {
        "branch": "M SP 01",
        "totalEmployees": 3,
        "totalDetails": [
            {
                "branch": "M SP 01 ",
                "registration": "003923",
                "name": "DRHJORNPRT-3921 PT COMPLETO",
                "department": "GPE001- OPERACIONAL - SP"
            },
            {
                "branch": "M SP 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "GPE001- OPERACIONAL - SP"
            },
            {
                "branch": "M SP 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 SEM MARCACOES",
                "department": "GPE001- OPERACIONAL - SP"
            }
        ],
        "clockMarkingsComplete": 1,
        "completeDetails": [
            {
                "branch": "M SP 01 ",
                "registration": "003923",
                "name": "DRHJORNPRT-3921 PT COMPLETO",
                "department": "GPE001- OPERACIONAL - SP"
            }
        ],
        "clockMarkingsIncomplete": 1,
        "incompleteDetails": [
            {
                "branch": "M SP 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO ",
                "department": "GPE001- OPERACIONAL - SP",
                "dateTime": "01/03/2023",
                "reason": "Dia sem marcação",
                "estimated": "09:00 - 12:00 - 13:00 - 18:00",
                "performed": ""
            },
            {
                "branch": "M SP 01 ",
                "registration": "003921",
                "name": "DRHJORNPRT-3921 PT INCOMPLETO",
                "department": "GPE001- OPERACIONAL - SP",
                "dateTime": "02/03/2023",
                "reason": "1 Marcação faltante",
                "estimated": "09:00 - 12:00 - 13:00 - 18:00",
                "performed": "12:00 - 13:00 - 18:00"
            }
        ],
        "withoutClockMarkings": 1,
        "withoutDetails": [
            {
                "branch": "M SP 01 ",
                "registration": "003922",
                "name": "DRHJORNPRT-3921 SEM MARCACOES",
                "department": "GPE001- OPERACIONAL - SP"
            }
        ]
    }
}

Observação

Caso os indicadores não possuam dados a serem exibido, será necessário enviar no retorno da API as propriedades da resposta com 0 e o detalhamento com um array vazio. Exemplo:

Bloco de código

{
    "1": {
        "branch": "Todas as Filiais",
        "totalEmployees": 0,
        "totalDetails": [],
        "clockMarkingsComplete": 0,
        "completeDetails": [],
        "clockMarkingsIncomplete": 0,
        "incompleteDetails": [],
        "withoutClockMarkings": 0,
        "withoutDetails": []
    },
    "2": {
        "branch": "Filial A",
        "totalEmployees": 0,
        "totalDetails": [],
        "clockMarkingsComplete": 0,
        "completeDetails": [],
        "clockMarkingsIncomplete": 0,
        "incompleteDetails": [],
        "withoutClockMarkings": 0,
        "withoutDetails": []
    },
    "3": {
        "branch": "Filial B",
        "totalEmployees": 0,
        "totalDetails": [],
        "clockMarkingsComplete": 0,
        "completeDetails": [],
        "clockMarkingsIncomplete": 0,
        "incompleteDetails": [],
        "withoutClockMarkings": 0,
        "withoutDetails": []
    }
}

Observação

Caso seja selecionada 2 ou mais filiais, a primeira posição da resposta obrigatoriamente será o totalizador, para a demais posições serão as filiais e suas informações.
Se for selecionado apenas 1 filial no filtro só haverá 1 posição na resposta da API.

Chamada API:

Possíveis situações no envio dos filtros

Bloco de código

title	Todas as filiais

{
    "startDate":"2023-03-01",
    "endDate":"2023-03-31",
    "branches":[
        "todas"
    ]
}

Bloco de código

title	Apenas 1 filial

{
    "startDate":"2023-03-01",
    "endDate":"2023-03-31",
    "branches":[
        "D MG 01"
    ]
}

Bloco de código

title	Duas ou mais filiais

{
    "startDate":"2023-03-01",
    "endDate":"2023-03-31",
    "branches":[
        "D MG 01",
        "M SP 01"
    ]
}

Situações de Erros Tratados

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

Mensagens de Pré-Validação

Código	Erro	Detalhe
400	"Parâmetros inválidos: Verifique se os parâmetros startDate, endDate e filial foram enviados."

Totvs custom tabs box items

default	no
referencia	clockin

Integrações Clock In - api/rh/v1/DbHrClockin

API responsável por retornar o total de marcações no Clock In, total de marcações integradas, total de marcações a serem integradas e o total de marcações sem NSR gerada.

Ativação/Desativação da API

Por padrão esta API estará no sistema, porém será necessário realizar a devida configuração do serviço REST.

Configuração de Webservice Rest no Protheus no formato apresentado na seguinte documentação (Exemplo de Configuração de Webservice REST)

Controle de Ambiente

Exige que os seguintes pontos sejam revisados:

Protheus com sua arquitetura devidamente estruturada.

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância da linha Protheus.

Suporte

O suporte aos recursos da API será de responsabilidade da linha Protheus onde será analisada pela equipe de suporte da Totvs.

Fluxo das Informações

Esta API traz a funcionalidade exclusivamente para trazer o total de funcionários que estão com o ponto completo e o total de funcionários com o ponto incompleto.

Cadastro

Esta API contempla as consultas de marcações do Clock In e marcações integradas com o ERP.

Processos

O Dashboard RH realizará o consumo da API para buscar e exibir a quantidade total de marcações no Clock In, total de marcações integradas, total de marcações a serem integradas e o total de marcações sem NSR gerada.

Como realizar a chamada da API REST

Preenchimento do EndPoint da API PONAPIDSB;
Utilizar a chamada do método Post e do Serviço api/rh/v1/DbHrClockin;
Preenchimento dos parâmetros obrigatórios da API;

Internamente o Protheus identifica automaticamente o endereço do servidor REST, porém para que isso aconteça será necessário habilitar a porta multiprotocolo do Appserver. Para mais informações sobre a porta multiprotocolo acesse o link abaixo:
https://tdn.totvs.com/x/jIUoI

Formatos de Data

As Entradas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DD

Parâmetros de Entrada:

Parâmetro	Valor de Exemplo	Obrigatório	Tipo	Parâmetro	Descrição
startDate	2022-05-01	Sim	Date	Body	Data inicial do período.
endDate	2022-05-31	Sim	Date	Body	Data final do período.
branches	["D MG 01"] ["D MG 01","M SP 01"] ["todas"]	Sim	Array	Body	Filtro da filial.
accept	application/json	Sim	String	Header
content-type	application/json	Sim	String	Header

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta Postman e após a configuração do server protheus a API Rest, a requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}:{porta}/{endereço Rest}/api/rh/v1/DbHrClockin

Response da API:

Application/json

Bloco de código

title	Resposta API

{
    "1": {
        "branch": "Todas",
        "totalClockMarkings": 7,
        "totalDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 1,
                "dateTime": "01/03/2023 09:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 2,
                "dateTime": "01/03/2023 12:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 3,
                "dateTime": "01/03/2023 13:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 0,
                "dateTime": "01/03/2023 18:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 1,
                "dateTime": "01/03/2023 09:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 2,
                "dateTime": "01/03/2023 12:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 0,
                "dateTime": "01/03/2023 13:00"
            }
        ],
        "totalIntegrated": 3,
        "integratedDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 1,
                "dateTime": "01/03/2023 09:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 2,
                "dateTime": "01/03/2023 12:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 1,
                "dateTime": "01/03/2023 09:00"
            }
        ],
        "totalToBeIntegrated": 2,
        "toBeIntegratedDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 3,
                "dateTime": "01/03/2023 13:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 2,
                "dateTime": "01/03/2023 12:00"
            }
        ],
        "totalWhitoutnsr": 2,
        "whitoutnsrDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 0,
                "dateTime": "01/03/2023 18:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 0,
                "dateTime": "01/03/2023 18:00"
            }
        ]
    },
    "2": {
        "branch": "Filial A",
        "totalClockMarkings": 4,
        "totalDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 1,
                "dateTime": "01/03/2023 09:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 2,
                "dateTime": "01/03/2023 12:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 3,
                "dateTime": "01/03/2023 13:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 0,
                "dateTime": "01/03/2023 18:00"
            }
        ],
        "totalIntegrated": 2,
        "integratedDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 1,
                "dateTime": "01/03/2023 09:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 2,
                "dateTime": "01/03/2023 12:00"
            }
        ],
        "totalToBeIntegrated": 1,
        "clockMarkings": [
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 3,
                "dateTime": "01/03/2023 13:00"
            }
        ],
        "totalWhitoutnsr": 1,
        "whitoutnsrDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "44379500039",
                "pis": "61743152540",
                "branch": "Filial A",
                "name": "Func A",
                "device": "dispositivo A",
                "nsr": 0,
                "dateTime": "01/03/2023 18:00"
            }
        ]
    },
    "3": {
        "branch": "Filial B",
        "totalClockMarkings": 3,
        "totalDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 1,
                "dateTime": "01/03/2023 09:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 2,
                "dateTime": "01/03/2023 12:00"
            },
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 0,
                "dateTime": "01/03/2023 13:00"
            }
        ],
        "totalIntegrated": 1,
        "integratedDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 1,
                "dateTime": "01/03/2023 09:00"
            }
        ],
        "totalToBeIntegrated": 1,
        "toBeIntegratedDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 2,
                "dateTime": "01/03/2023 12:00"
            }
        ],
        "totalWhitoutnsr": 1,
        "whitoutnsrDetails": [
            {
                "cnpj": "99999999999999",
                "cpf": "88888888888",
                "pis": "77777777777",
                "branch": "Filial B",
                "name": "Func B",
                "device": "dispositivo B",
                "nsr": 0,
                "dateTime": "01/03/2023 13:00"
            }
        ]
    }
}

Observação

Caso os indicadores não possuam dados a serem exibido, será necessário enviar no retorno da API as propriedades da resposta com 0 e o detalhamento com um array vazio. Exemplo:

Bloco de código

{
    "1": {
        "branch": "Todas as Filiais",
        "totalClockMarkings": 0,
        "totalDetails": [],
        "totalIntegrated": 0,
        "integratedDetails": [],
        "totalToBeIntegrated": 0,
        "toBeIntegratedDetails": [],
        "totalWhitoutNSR": 0,
        "whitoutNsrDetails": []
    },
	"2": {
        "branch": "Filial A",
        "totalClockMarkings": 0,
        "totalDetails": [],
        "totalIntegrated": 0,
        "integratedDetails": [],
        "totalToBeIntegrated": 0,
        "toBeIntegratedDetails": [],
        "totalWhitoutNSR": 0,
        "whitoutNsrDetails": []
    },
	"3": {
        "branch": "Filial B",
        "totalClockMarkings": 0,
        "totalDetails": [],
        "totalIntegrated": 0,
        "integratedDetails": [],
        "totalToBeIntegrated": 0,
        "toBeIntegratedDetails": [],
        "totalWhitoutNSR": 0,
        "whitoutNsrDetails": []
    }
}

Observação

Caso seja selecionada 2 ou mais filiais, a primeira posição da resposta obrigatoriamente será o totalizador, para a demais posições serão as filiais e suas informações.
Se for selecionado apenas 1 filial no filtro só haverá 1 posição na resposta da API.

Chamada API:

Possíveis situações no envio dos filtros

Bloco de código

title	Todas as filiais

{
    "startDate":"2023-03-01",
    "endDate":"2023-03-31",
    "branches":[
        "todas"
    ]
}

Bloco de código

title	Apenas 1 filial

{
    "startDate":"2023-03-01",
    "endDate":"2023-03-31",
    "branches":[
        "D MG 01"
    ]
}

Bloco de código

title	Duas ou mais filiais

{
    "startDate":"2023-03-01",
    "endDate":"2023-03-31",
    "branches":[
        "D MG 01",
        "M SP 01"
    ]
}

Situações de Erros Tratados

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

Mensagens de Pré-Validação

Código	Erro	Detalhe
400	"Parâmetros inválidos: Verifique se os parâmetros startDate, endDate e filial foram enviados."

Totvs custom tabs box items

default	no
referencia	email

Integrações Clock In - api/rh/v1/DbHrEmail

API responsável por enviar um e-mail com as informações do dashboard.

Ativação/Desativação da API

Por padrão esta API estará no sistema, porém será necessário realizar a devida configuração do serviço REST.

Configuração de Webservice Rest no Protheus no formato apresentado na seguinte documentação (Exemplo de Configuração de Webservice REST)

Controle de Ambiente

Exige que os seguintes pontos sejam revisados:

Protheus com sua arquitetura devidamente estruturada.

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância da linha Protheus.

Suporte

O suporte aos recursos da API será de responsabilidade da linha Protheus onde será analisada pela equipe de suporte da Totvs.

Fluxo das Informações

Esta API traz a funcionalidade exclusivamente para enviar as informações exibidas no Dashboard por e-mail.

Cadastro

Esta API contempla os resultados das informações exibidas no Dashboard, no caso o resultado das APIs anteriores.

Processos

O Dashboard RH realizará o consumo da API para enviar um e-mail, contendo um HTML do Dashboard anexa.

Como realizar a chamada da API REST

Preenchimento do EndPoint da API PONAPIDSB;
Utilizar a chamada do método Post e do Serviço api/rh/v1/DbHrEmail;
Preenchimento dos parâmetros obrigatórios da API;

Internamente o Protheus identifica automaticamente o endereço do servidor REST, porém para que isso aconteça será necessário habilitar a porta multiprotocolo do Appserver. Para mais informações sobre a porta multiprotocolo acesse o link abaixo:
https://tdn.totvs.com/x/jIUoI

Formatos de Data

As Entradas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DD

Parâmetros de Entrada:

Parâmetro	Valor de Exemplo	Obrigatório	Tipo	Parâmetro	Descrição
updatedDate	09:31 (02/05/2023)	Sim	String	Body	Data da última atualizado do Dashboard.
startDate	2023-04-30	Sim	Date	Body	Data Inicial do filtro.
endDate	2023-05-01	Sim	Date	Body	Data final do filtro.
details	details: details[1]: branch (String): "Indicadores de funcionários - Todas as Filiais" informations (Array): informations[1] (totalEmployees): 6 informations[2] (clockMarkingsComplete): 2 informations[3] (clockMarkingsIncomplete): 2 informations[4] (withoutClockMarkings): 2 details[2]: branch (String): "Indicadores de marcações do Clock In - Todas as Filiais" informations (Array): informations[1] (totalClockMarkings): 10 informations[2] (totalIntegrated): 6 informations[3] (totalToBeIntegrated): 2 informations[4] (totalWhitoutNSR): 2 details[3]: branch (String): "Indicadores de funcionários - D MG 01" informations (Array): informations[1] (totalEmployees): 3 informations[2] (clockMarkingsComplete): 1 informations[3] (clockMarkingsIncomplete): 1 informations[4] (withoutClockMarkings): 1 details[4]: branch (String): "Indicadores de marcações do Clock In - D MG 01" informations (Array): informations[1] (totalClockMarkings): 5 informations[2] (totalIntegrated): 3 informations[3] (totalToBeIntegrated): 1 informations[4] (totalWhitoutNSR): 1 details[5]: branch (String): "Indicadores de funcionários - M SP 01" informations (Array): informations[1] (totalEmployees): 3 informations[2] (clockMarkingsComplete): 1 informations[3] (clockMarkingsIncomplete): 1 informations[4] (withoutClockMarkings): 1 details[6]: branch (String): "Indicadores de marcações do Clock In - M SP 01" informations (Array): informations[1] (totalClockMarkings): 5 informations[2] (totalIntegrated): 3 informations[3] (totalToBeIntegrated): 1 informations[4] (totalWhitoutNSR): 1	Sim	Array	Body	Array com os números dos indicadores.
accept	application/json	Sim	String	Header
content-type	application/json	Sim	String	Header

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta Postman e após a configuração do server protheus a API Rest, a requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}:{porta}/{endereço Rest}/api/rh/v1/DbHrEmail

Response da API:

Application/json
{
"Response": "E-mail enviado com sucesso."
}

Situações de Erros Tratados

O envio de dado inesperado no parâmetro de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

Mensagens de Pré-Validação

Código	Erro	Detalhe
400	"Falha no envio do e-mail, verifique as configurações do sistema para o envio de e-mails."
401	"Parâmetros inválidos: Verifique se todos os parâmetros foram enviados corretamente."

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 45

Nova versão 46

Chave

Ativação/Desativação da API

Controle de Ambiente

Controle de Versão

Suporte

Fluxo das Informações

Cadastro

Processos

Como realizar a chamada da API REST

Formatos de Data

Ativação/Desativação da API

Controle de Ambiente

Controle de Versão

Suporte

Fluxo das Informações

Cadastro

Processos

Como realizar a chamada da API REST

Formatos de Data

Observação

Observação

Chamada API:

Possíveis situações no envio dos filtros

Situações de Erros Tratados

Mensagens de Pré-Validação

Ativação/Desativação da API

Controle de Ambiente

Controle de Versão

Suporte

Fluxo das Informações

Cadastro

Processos

Como realizar a chamada da API REST

Formatos de Data

Observação

Observação

Chamada API:

Possíveis situações no envio dos filtros

Situações de Erros Tratados

Mensagens de Pré-Validação

Ativação/Desativação da API

Controle de Ambiente

Controle de Versão

Suporte

Fluxo das Informações

Cadastro

Processos

Como realizar a chamada da API REST

Formatos de Data

Situações de Erros Tratados

Mensagens de Pré-Validação