Protocolo Integração TopPonto

Nesta página:

10 Eventos

A funcionalidade de exportação de eventos é realizada em quatro etapas principais. Abaixo, segue o detalhamento passo a passo de como utilizá-la:

1ª Etapa: Consultar o tipo de layout do evento
O primeiro passo consiste em identificar os layouts disponíveis para exportação. Para isso, realize uma requisição ao endpoint de consulta de layouts. Esse endpoint retorna informações como o id, descrição e formatos de cada layout disponível, permitindo que você selecione o mais adequado ao seu evento.
Recomendação: certifique-se de compreender a estrutura do layout antes de prosseguir para as próximas etapas.

2ª Etapa: Fazer a requisição para criar o processo de exportação
Com o idLayout em mãos, envie uma requisição ao endpoint de criação de processo. Nesta etapa, é necessário fornecer os parâmetros exigidos para a geração do evento, incluindo o identificador do layout (idLayout). Além disso, informe quaisquer filtros ou critérios específicos, conforme o evento que deseja exportar.
Observação: a exportação é assíncrona, ou seja, você receberá um identificador único (codigo) para acompanhar o progresso.

3ª Etapa: Acompanhar o andamento da geração
Com o codigo de exportação obtido na etapa anterior, utilize o endpoint de acompanhamento para verificar o estado atual do processo. Esse endpoint informa o andamento da geração, incluindo a porcentagem de conclusão.
Dica: realize essa verificação periodicamente (sugerido: a cada 5 segundos) para evitar sobrecarga no servidor.

4ª Etapa: Solicitar o arquivo final
Assim que o acompanhamento indicar que a geração foi concluída (100%), faça uma requisição ao endpoint de download utilizando o mesmo codigo de exportação.
Importante: confirme o recebimento e valide os dados do arquivo gerado antes de utilizá-lo.

10.1 Consultar layouts (lista)

Retorna uma lista de layouts cadastrados.

Endpoint

https://integracao.topponto.com.br/evento/layouts

Estrutura

Método	Cabeçalho	Body
GET	Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1	JSON

Parâmetros (Não se enquadra)

Não há parâmetros a serem passados na requisição.

Requisição (Não se enquadra)

Não há dados a serem enviados na requisição.

Resposta

{
    "message": "Consulta realizada com sucesso.",
    "body": [
        {
            "idLayout": 1,
            "descricao": "BANCO DE HORAS",
            "formato": " [E-X:1] [M:5] [{BH-C}VC:5] [{BH-D}VC:5] ",
            "formatoDataExportacao": "DD/MM/YYYY",
            "delimitador": "|",
            "delimitadorData": "/",
            "delimitadorHora": ",",
            "sabadoDiaUtil": false,
            "domingoDiaUtil": false,
            "horaSexagesimal": false,
            "porLinha": false,
            "exportarEventosZerados": true,
            "importacao": true,
            "exportacao": true,
            "formatoDataPeriodo": "DD/MM/YYYY"
        },
        ...
    ],
    "status": 200
}

Erros catalogados

Não há erros catalogados para este método.

10.2 Criar processo

Criar um novo evento de exportação de acordo com o layout.

Endpoint

https://integracao.topponto.com.br/evento

Estrutura

Método	Cabeçalho	Body
POST	Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1	JSON

Parâmetros

Campo	Tipo	Restrição	Obrigatório	Descrição
idLayout	Number	1 a N (Número Positivo)	Sim	Identificador único do layout.
idFuncionario	Number	1 a N (Número Positivo) ou NULL	Não	Identificador único do funcionario.
idCei	Number	1 a N (Número Positivo) ou NULL	Não	Identificador único do cei.
idDepartamento	Number	1 a N (Número Positivo) ou NULL	Não	Identificador único do departamento.
idEmpresa	Number	1 a N (Número Positivo) ou NULL	Não	Identificador único da Empresa.
empresaAtiva	Boolean	true ou false	Sim	true para empresas ativas e false para todas.
departamentoAtivo	Boolean	true ou false	Sim	true para deparatamentos ativos e false para todos.
funcionarioAtivo	Boolean	true ou false	Sim	true para funcionarios ativos e false para todos.
dataExportacao	String	Exatos 10 caracteres	Sim	Data de exportação do evento (formato DD/MM/AAAA), de acordo com a necessidade.
periodoInicio	String	Exatos 10 caracteres	Sim	Data de inicio do dados (formato DD/MM/AAAA).
periodoFim	String	Exatos 10 caracteres	Sim	Data final do dados (formato DD/MM/AAAA).

Requisição (JSON)

{
    "idLayout": 5,
    "idFuncionario": null,
    "idCei": null,
    "idDepartamento": null,
    "idEmpresa": null,
    "empresaAtiva": true,
    "departamentoAtivo": true,
    "funcionarioAtivo": true,
    "dataExportacao": "19/11/2024",
    "periodoInicio": "01/11/2024",
    "periodoFim": "19/11/2024"
}

Resposta

{
    "message":  "Criado com sucesso.",
    "body": {
        "codigo": "2a11a912-9af3-4e0a-8039-ca543b3c1829",
        "descricao": "INICIANDO_PROCESSO",
        "dataAtualizacao": 1732217938809,
        "progresso": 0.0
    },
    "status": 201
}

Erros catalogados

Campo	Mensagem	Código Http
idLayout	O id do layout não pode ser nulo.	400 – Bad Request
	O id do layout deve ser maior que 0.	400 – Bad Request
	Layout informando não cadastrado.	404 – Not Found
	Layout do arquivo não encontrado.	404 – Not Found
idFuncionario	O id do funcionário deve ser maior que 0.	400 – Bad Request
idFuncionario	Funcionário não encontrado. Informe um id válido.	404 – Not Found
idCei	O id do cei deve ser maior que 0.	400 – Bad Request
idCei	Cei não encontrado. Informe um id válido.	404 – Not Found
idEmpresa	O id da empresa deve ser maior que 0.	400 – Bad Request
idEmpresa	Empresa não encontrada. Informe um id válido.	404 – Not Found
idDepartamento	O id do departamento deve ser maior que 0.	400 – Bad Request
idDepartamento	Departamento não encontrado. Informe um id válido.	404 – Not Found
empresaAtiva	O campo empresaAtiva não pode ser nulo.	400 – Bad Request
departamentoAtivo	O campo departamentoAtivo não pode ser nulo.	400 – Bad Request
funcionarioAtivo	O campo funcionarioAtivo não pode ser nulo.	400 – Bad Request
dataExportacao	O campo dataExportacao não pode ser vazio.	400 – Bad Request
	O campo dataExportacao ultrapassou o limite definido.	400 – Bad Request
	O campo dataExportacao deve estar no formato dd/MM/yyyy	400 – Bad Request
periodoInicio	O período de inicio não pode ser vazio.	400 – Bad Request
	O período de inicio ultrapassou o limite definido.	400 – Bad Request
	O período de inicio deve estar no formato dd/MM/yyyy	400 – Bad Request
	O período de inicio deve ser inferior ao período de fim.	400 – Bad Request
periodoFim	O período fim não pode ser vazio.	400 – Bad Request
	O período fim ultrapassou o limite definido.	400 – Bad Request
	O período fim deve estar no formato dd/MM/yyyy	400 – Bad Request
periodoInicio periodoFim	O intervalo entre as datas não pode ultrapassar 12 meses.	400 – Bad Request

10.3 Acompanhar processo

Retorna o processo de exportação de um evento específico com base no codigo informado no endpoint — este codigo é obtido na etapa 7.2 – Criar Processo.

Durante a operação:

O campo descricao refletirá o estado atual do processo, alternando entre mensagens como "INICIANDO_PROCESSO", "GERANDO_ARQUIVO" e, ao final, "CONCLUIDO".
O campo progresso indicará o percentual de conclusão, aumentando gradativamente até atingir "progresso": 100.0.

Quando o campo progresso alcançar 100%, o arquivo estará pronto para ser baixado. Para obter o arquivo final, faça uma solicitação na etapa 7.4 – Consultar, utilizando o mesmo codigo informado anteriormente.

Como se trata de um processo assíncrono, recomenda-se realizar consultas ao endpoint em intervalos de pelo menos 5 segundos, a fim de evitar sobrecarga no servidor por excesso de requisições.

Endpoint

https://integracao.topponto.com.br/evento/codigo

Estrutura

Método	Cabeçalho	Path Variable
GET	Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1	Integer

Parâmetros

Campo	Tipo	Restrição	Obrigatório	Descrição
codigo	String	Gerado e retornado no processo de exportação. Não deve ser informado manualmente.	Sim	Identificador único do processo de exportação.

Requisição (URL)

https://integracao.topponto.com.br/evento/2a11a912-9af3-4e0a-8039-ca543b3c1829

Resposta

{
    "message": "Consulta realizada com sucesso.",
    "body": {
        "codigo": "2a11a912-9af3-4e0a-8039-ca543b3c1829",
        "descricao": "CONCLUIDO",
        "dataAtualizacao": 1732021779983,
        "progresso": 100.0
    },
    "status": 200
}

Erros catalogados

Campo	Mensagem	Código Http
codigo	Processo cancelado, realize uma nova solicitação.	200 – OK
	Código informado não pode ser nulo ou vazio.	400 – Bad Request
	Verifique o código informado, não foram encontrados processos.	404 – Not Found

10.4 Cancelar processo

A partir do código, encerra o processo de geração do arquivo caso ele ainda esteja em andamento.

Endpoint

https://integracao.topponto.com.br/evento/codigo

Estrutura

Método	Cabeçalho	Path Variable
DELETE	Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1	Integer

Parâmetros

Campo	Tipo	Restrição	Obrigatório	Descrição
codigo	String	Gerado e retornado no processo de criação do processo.	Sim	Identificador único do processo de exportação.

Requisição (URL)

https://integracao.topponto.com.br/evento/2a11a912-9af3-4e0a-8039-ca543b3c1829

Resposta

{
    "message": "Cancelado com sucesso.",
    "body": {
        "codigo": "2a11a912-9af3-4e0a-8039-ca543b3c1829",
        "descricao": "CARREGANDO_DADOS_GERA_FREQUENCIA",
        "dataAtualizacao": 1734520976153,
        "progresso": 6.523579201934719
    },
    "status": 200
}

Erros catalogados

Campo	Mensagem	Código Http
codigo	Código informado não pode ser nulo ou vazio.	404 – Not Found

10.5 Consultar

Apartir do codigo, busca o arquivo gerado correspondente e retorna seu conteúdo diretamente na resposta da requisição.

Endpoint

https://integracao.topponto.com.br/evento/arquivo/codigo

Estrutura

Método	Cabeçalho	Path Variable
GET	Content-Type: application/json X-Auth-Token: “token”X-Api-Version: 1	Integer

Parâmetros

Campo	Tipo	Restrição	Obrigatório	Descrição
codigo	String	Gerado e retornado no processo de criação do processo.	Sim	Identificador único do processo de exportação.

Requisição (URL)

https://integracao.topponto.com.br/evento/arquivo/2a11a912-9af3-4e0a-8039-ca543b3c1829

Resposta

{
    "message": "Consulta realizada com sucesso.",
    "body": "2|5979 |00000|00000|\r\n2|5983 |00000|00000|\r\n1|15377|00000|00000|",
    "status": 200
}

Erros catalogados

Campo	Mensagem	Código Http
codigo	Código informado não pode ser nulo ou vazio.	400 – Bad Request
	O arquivo solicitado ainda não foi processado. Tente novamente mais tarde.	400 – Bad Request
	Verifique o código informado, não foram encontrados processos.	404 – Not Found
	Não foram encontrados arquivos com o codigo informado.	404 – Not Found
	O arquivo está vazio. Nenhum dado encontrado para os parâmetros informados.	404 – Not Found

Mais páginas

Mais Páginas

Introdução
Cadastros
Cálculos
Marcações
Painel
Erros Catalogados

Páginas: 1 2 3 4 5 6 7

« Anterior 1 2 3 4 5 ... 7 Próxima »

Esse artigo foi útil?

Sim Não