Histórico da Página

Portuguese (Brasil)

Esta documentação descreve os recursos da API de Apuração de Resultados do sistema Pontoweb. A API permite iniciar processos de apuração, acompanhar seu status, consultar os resultados apurados e gerenciar o re-consumo de eventos já processados.

As operações foram desenvolvidas para integração com sistemas de folha de pagamento, contabilidade ou outras aplicações corporativas que necessitam acessar dados de apuração de ponto e eventos contábeis dos colaboradores.

Todas as requisições exigem autenticação via HTTP Basic Auth, utilizando um usuário do tipo service. Algumas rotas também requerem cabeçalhos específicos de versionamento.

As respostas seguem o formato JSON, com mensagens claras de erro e sucesso para facilitar o tratamento por aplicações clientes.

Section

Deck of Cards

id	001

Card

label	Autenticação

ITG2.0-01 Autenticação

Card

label	1. Solicitar resultados apurados

Inicia o processo de apuração de eventos contábeis e marcações de ponto para colaboradores em um determinado período. Permite filtrar por localidade, colaboradores específicos e recursos opcionais como totais diários, batidas diárias e totais mensais.

Informações

title	Limitações de Uso

É permitido, no máximo, 3 processos diários para a "base full", para cada tipo de parâmetro "feature" consumido (daily.totals, daily.punches e monthly). Em chamadas informando o filtro de matrícula (não são "base full"), o consumo é livre.
É permitido o start de, no máximo, 4 processos simultâneos.

Item	Descrição
Fluxo:	Cliente → PontoWeb
URL API:	https://api.ahgora.com.br/reckons/process/start
Método:	POST
Autenticação:	Basic (ver)

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
registers	array	Situacional	Lista de matrículas dos colaboradores, se vazio, considera todos colaboradores. Quando o campo rescission for true, este campo se torna obrigatório e deve conter no mínimo uma matrícula.
rescission	boolean	Sim	Indica se deve considerar funcionários demitidos. Padrão: `false`.
month	string	Sim	Mês de apuração no formato `"MM".`
year	string	Sim	Ano de apuração no formato `"YYYY".`
paymentDate	string	Não	Data de pagamento no formato `"YYYY-MM-DD"`.
infotype	string	Não	Identificação do tipo do evento. Padrão: 0015.
allowEmpty	boolean	Não	Apresenta funcionários sem dados. Padrão: false.
locations	array	Não	Filtra funcionários por localização cadastrada no Pontoweb.
features	array	Não	Tipo de Processamento solicitado. Opções: `"daily.punches"(Batidas Diárias)`, `"daily.totals" (Total diário)`, `"monthly" (Mensal). Padrão: monthly. Pode solicitar um específico ou mais de um. Caso não informe, será gerado o padrão.`

Exemplos de Requisições (Requests)

Corpo da Requisição:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "registers": ["98a159Q"],
    "rescission": false,
    "month": "04",
    "year": "2025",
    "paymentDate": "2025-04-30",
    "infotype": "0015",
    "allowEmpty": false,
    "locations": [],
    "features": ["daily.punches", "daily.totals", "monthly"]
}

Exemplos de Respostas (Responses)

Resposta quando SUCESSO - Code 200:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "process": "6b28ff7e-dda5-415c-b5b4-ff776f92142b",
    "company": "a133595",
    "created_at": "2025-04-28T13:49:32.334Z"
}

ERRO de Autenticação - Code 401:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "code": 401,
        "message": "Unauthorized"
    }
}

ERRO de Permissão - Code 403:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "message": "Forbidden",
        "code": 403
    }
}

Observação: Verificar as permissões do usuário para acessar a rota/serviço.

ERRO de Validação - Code 400:

Bloco de código

theme	Emacs
linenumbers	true
collapse	true

{
    "error": "\"rescission\" is required"
}

Observação: Verifique os parâmetros obrigatórios do request.

Card

label	2. Verificar status do processo

Após a requisição do processamento, é possível consultar o status. Nesta consulta, retorna o status de um processo de apuração previamente iniciado. Informa se o processamento foi concluído, se houve erro e o progresso. É necessário fornecer o identificador do processo (process).

Item	Descrição
Fluxo:	Cliente → PontoWeb
URL API:	https://api.ahgora.com.br/reckons/process/status/:process
Método:	GET
Autenticação:	Basic (ver)
Parâmetro:	Process É o código identificador do processo iniciado, obtido no retorno da requisição de "Solicitar" Exemplo: 6b28ff7e-dda5-415c-b5b4-ff776f92142b

Query Params
Chave	Valor
Accept-Version	v1 v2

Corpo da Resposta:

Campo	Tipo	Descrição
process	string	Código do processo iniciado.
company	string	Código da empresa no sistema PontoWeb.
status	string	Status atual do processo: `processing` – Processamento em andamento; `done` – Processamento finalizado com sucesso; `error` – Processamento finalizado com erro.
unique	string	Código identificador único para controle do processo.
progress.done	number	Quantidade de colaboradores com processamento finalizado.
progress.total	number	Quantidade total de colaboradores a serem processados.

Exemplos de Respostas (Responses)

Resposta quando em PROCESSAMENTO - Code 200:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "status": "processing",
    "unique": "323256d",
    "process": "323256d-d0df-4c0d-a6c1-8d9ca6fed06b",
    "company": "a133595",
     "progress": {
        "done": 0,
        "total": 0
    }
}

Resposta quando SUCESSO - Code 200:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "status": "done",
    "unique": "3234ca5d",
    "process": "3234ca5d-d0df-4c0d-a6c1-8d9ca6fed06b",
    "company": "a133595",
    "progress": {
        "done": 1,
        "total": 1
    }
}

ERRO de Validação - Code 400:

Accept-Version v1

Bloco de código

theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "message": "Process not found",
        "code": 400
    }
}

Observação: Verifique o unique informado.

ERRO de Validação - Code 400:

Accept-Version v2:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": "Process not found"
}

Observação: Verifique o unique informado.

ERRO de Autenticação - Code 401:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "code": 401,
        "message": "Unauthorized"
    }
}

Observação: Verifique usuário e senha.

ERRO de Permissão - Code 403:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "message": "Forbidden",
        "code": 403
    }
}

Observação: Verificar as permissões do usuário para acessar a rota/serviço.

Card

label	3. Obter resultados apurados

Obtém os resultados gerados do processamento, com base no código identificador único (unique). Os dados retornados podem incluir eventos mensais, totais diários e marcações de ponto, conforme definido na requisição solicitando os resultados apurados.
Os dados ficam disponíveis por 72 horas para consumo; após esse período, expiram automaticamente.

Importante: uma vez que os dados do processo são consultados com sucesso, os eventos retornados são marcados como "consumidos" e não serão exibidos novamente em chamadas futuras.
Para obter os mesmos eventos, será necessário ativar o re-consumo dos eventos através da rota 4. Habilitar re-consumo dos eventos.

Item	Descrição
Fluxo:	Cliente → PontoWeb
URL API:	https://api.ahgora.com.br/reckons/:unique
Método:	GET
Autenticação:	Basic (ver)
Parâmetro:	Unique (string): é o código identificador único para controle . Exemplo: 3234ca5d
Parâmetro:	Limit (number) (opcional): é o limite de registros/eventos que irão retornar na resposta. Padrão: 1000. Máximo: 1000.

Exemplos de Respostas (Responses)

Resposta - monthly

Exemplo de resposta quando o campo "features" é informado com "monthly" na solicitação de resultados apurados:

Campo	Tipo	Descrição
unique	string	Código único identificador do processo.
company	string	Código da empresa no sistema PontoWeb.
total	number	Quantidade total de colaboradores.
data	array	Contém a lista com as informações do colaborador e dos eventos.
data.employee	string	Matrícula do colaborador.
data.paymentDate	string	Data de pagamento no formato "YYYY-MM-DD".
data.infotype	string	Identificação do tipo do evento.
data.results	array	Contém a lista dos eventos mensais.
data.results.name	string	Nome do código contábil.
data.results.event	string	Código contábil do evento.
data.results.value	string/number	Valor do evento contábil. Exemplos: Eventos em Dias: 2; Eventos em Horas: "16:30" (Sexagesimais) Eventos em Horas: "16,50" (Centesimais)
data.results.type	string	Tipo do evento contábil. Pode conter: "days" - Para dias; "hours" - Para horas.

Resposta com SUCESSO - Code 200:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
	"company": "a133595",
    "unique": "3234ca5d",
    "total": 1,
    "data": [
        {
            "employee": "98a159Q",
            "paymentDate": "2025-04-30",
            "infotype": "0015",
            "results": [
                {
                      "name": "Horas previstas",
                      "event": "9077",
                      "value": "71:20",
                      "type": "hours"
                  },
                  {
                      "name": "Dias previstos",
                      "event": "9078",
                      "value": 1,
                      "type": "days"
                  }
            ]
        }
    ]
}

Resposta - daily.punches

Exemplo de resposta quando o campo "features" é informado com "daily.punches" na solicitação de resultados apurados:

Campo	Tipo	Descrição
unique	string	Código único identificador do processo.
company	string	Código da empresa no sistema PontoWeb.
total	number	Quantidade total de dias com marcação.
data	array	Contém a lista com as informações do colaborador e das marcações de ponto.
data.employee	string	Matrícula do colaborador.
data.paymentDate	string	Data de pagamento no formato "YYYY-MM-DD".
data.infotype	string	Identificação do tipo do evento.
data.daily	array	Contém a lista das marcações de ponto
data.daily.day	string	Dia em que ocorreu a marcação de ponto no formato "YYYY-MM-DD".
data.daily.punches	array	Lista com as informações das marcações de ponto.
data.daily.punches.date	string	Data efetiva do registro da marcação de ponto.
data.daily.punches.hour	string	Hora do registro da marcação de ponto no formato "HHMM".
data.daily.punches.type	string	Tipo de registro. Pode conter: "O" - REP ou Batida Online. "I" - Inclusão Manual. "BI" - Registros de Pausas.
data.daily.punches.label	string	Indica se o registro é de entrada ou saída.

Resposta com SUCESSO - Code 200:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
	"company": "a133595",
    "unique": "3234ca5d", 
    "total": 1,
    "data": [
        {
            "employee": "98a159Q",
            "paymentDate": "2022-08-08",
            "infotype": "0015",
            "daily": [
                {
                    "day": "2022-07-29",
                    "punches": [
                        {
                            "date": "2022-07-28",
                            "hour": "0800",
                            "type": "O",
                            "label": "entrada-1"
                        },
                        {
                            "date": "2022-07-28",
                            "hour": "0900",
                            "type": "I",
                            "label": "saida-1"
                        }
                    ]
                }
            ]
        }
    ]
}

Resposta - daily.totals

Exemplo de resposta quando o campo "features" é informado com "daily.totals" na solicitação de resultados apurados:

Campo	Tipo	Descrição
unique	string	Código único identificador do processo.
company	string	Código da empresa no sistema PontoWeb.
total	number	Quantidade total de dias apurados.
data	array	Contém a lista com as informações do colaborador e dos eventos diários
data.employee	string	Matrícula do colaborador.
data.paymentDate	string	Data de pagamento no formato "YYYY-MM-DD".
data.infotype	string	Identificação do tipo do evento.
data.daily	array	Contém a lista das batidas (Marcações de Ponto)
data.daily.day	string	Dia em que ocorreu a batida no formato "YYYY-MM-DD".
data.daily.results	array	Contém a lista dos eventos diários.
data.daily.results.name	string	Nome do código contábil.
data.daily.results.event	string	Código contábil do evento.
data.daily.results.value	string	Valor do evento contábil. Eventos em Dias: 2; Eventos em Horas: "16:30" (Sexagesimais) Eventos em Horas: "16,50" (Centesimais)
data.daily.results.type	string	Tipo do evento contábil. Pode conter: "days" - Para dias; "hours" - Para horas.

Resposta com SUCESSO - Code 200:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "company": "a133595",
    "unique": "3234ca5d",
    "total": 1,
    "data": [
        {
            "employee": "98a159Q",
            "paymentDate": "2022-08-08",
            "infotype": "0015",
            "daily": [
                {
                    "day": "2022-08-08",
                    "results": [
                        {
                            "name": "Horas previstas",
                            "event": "9077",
                            "value": "71:20",
                            "type": "hours"
                        },
                        {
                            "name": "Dias previstos",
                            "event": "9078",
                            "value": 1,
                            "type": "days"
                        }
                    ]
                }
            ]
        }
    ]
}

Resposta - daily.totals, daily.punches e monthly

Exemplo de resposta quando o campo "features" contém todas as opções.

Resposta com SUCESSO - Code 200:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "company": "a133595",
    "unique": "3234ca5d",
    "total": 2,
    "data": [
        {
            "employee": "98a159Q",
            "paymentDate": "2022-08-08",
            "infotype": "0015",
            "daily": [
                {
                    "day": "2022-08-08",
                    "results": [
                        {
                            "name": "Horas previstas",
                            "event": "9077",
                            "value": "71:20",
                            "type": "hours"
                        },
                        {
                            "name": "Dias previstos",
                            "event": "9078",
                            "value": 1,
                            "type": "days"
                        }
                    ],
                    "punches": [
                        {
                            "date": "2022-07-28",
                            "hour": "0800",
                            "type": "O",
                            "label": "entrada-1"
                        },
                        {
                            "date": "2022-07-28",
                            "hour": "0900",
                            "type": "I",
                            "label": "saida-1"
                        }
                    ]
                }
            ]
        },
        {
            "employee": "98a159Q",
            "paymentDate": "2022-08-08",
            "infotype": "0015",
            "results": [
                {
                    "name": "Horas previstas",
                    "event": "9077",
                    "value": "71:20",
                    "type": "hours"
                },
                {
                    "name": "Dias previstos",
                    "event": "9078",
                    "value": 1,
                    "type": "days"
                }
            ]
        }
    ]
}

ERRO de Autenticação - Code 401

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "code": 401,
        "message": "Unauthorized"
    }
}

Observação: Verificar usuário e senha informado.

ERRO de Permissão - Code 403

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "message": "Forbidden",
        "code": 403
    }
}

Observação: Verificar as permissões do usuário para acessar a rota/serviço.

Card

label	4. Habilitar re-consumo dos eventos

Restaura a disponibilidade dos eventos previamente consumidos em um processo de apuração. Após a execução desta rota, os dados associados ao identificador informado poderão ser obtidos novamente por meio da rota de consulta de resultados.

Item	Descrição
Fluxo:	Cliente → PontoWeb
URL API:	https://api.ahgora.com.br/reckons/reconsume/:unique
Método:	GET
Autenticação:	Basic (ver)
Parâmetro:	Unique (string): é o código identificador único para controle. Exemplo: 3234ca5d
Limite Máximo:	1000 vezes (A apuração identificada pelo unique) Cada apuração fica disponível por 72 horas, para re-consumo. Depois deste tempo ela não é mais acessível.

Corpo da Resposta:

Campo	Tipo	Descrição
company	string	Código da empresa no sistema PontoWeb.
unique	string	Código único identificador do processo.

Exemplos de Respostas (Responses)

Resposta quando SUCESSO - Code 200:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "company": "a133595",
    "unique": "3234ca5d"
}

ERRO de Validação - Code 400:

Accept-Version v1

Bloco de código

theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "message": "Process not found",
        "code": 400
    }
}

Observação: O processo é inexistente ou pode estar inexistente.

ERRO de Validação - Code 400:

Accept-Version v2:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": "Process not found"
}

Observação: O processo é inexistente ou pode estar inexistente.

ERRO de Autenticação - Code 401:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "code": 401,
        "message": "Unauthorized"
    }
}

Observação: Verifique usuário e senha.

ERRO de Permissão - Code 403:

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "message": "Forbidden",
        "code": 403
    }
}

Observação: Verificar as permissões do usuário para acessar a rota/serviço.

ERRO de Limite diário de requisições excedido - Code 429:

Accept-Version v1

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": {
        "message": "The daily limit of 3 has been exceeded for the following features: daily.punches, daily.totals, monthly.",
        "code": 429
    }
}

Accept-Version v2

Bloco de código

language	text
theme	Emacs
linenumbers	true
collapse	true

{
    "error": "The daily limit of 3 has been exceeded for the following features: daily.punches, daily.totals, monthly."
}

Card

label	5. FAQ

Em Construção

Composition Setup
deck.tab.inactive.background = #fffffff deck.tab.active.background = #b3a5ef

...

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 28

Nova versão 29

Chave

Corpo da Requisição:

Exemplos de Requisições (Requests)

Corpo da Requisição:

Exemplos de Respostas (Responses)

Resposta quando SUCESSO - Code 200:

ERRO de Autenticação - Code 401:

ERRO de Permissão - Code 403:

ERRO de Validação - Code 400:

Corpo da Resposta:

Exemplos de Respostas (Responses)

Resposta quando em PROCESSAMENTO - Code 200:

Resposta quando SUCESSO - Code 200:

ERRO de Validação - Code 400:

Accept-Version v1

ERRO de Validação - Code 400:

Accept-Version v2:

ERRO de Autenticação - Code 401:

ERRO de Permissão - Code 403:

Exemplos de Respostas (Responses)

Resposta - monthly

Resposta com SUCESSO - Code 200:

Resposta - daily.punches

Resposta com SUCESSO - Code 200:

Resposta - daily.totals

Resposta com SUCESSO - Code 200:

Resposta - daily.totals, daily.punches e monthly

Resposta com SUCESSO - Code 200:

ERRO de Autenticação - Code 401

ERRO de Permissão - Code 403

Corpo da Resposta:

Exemplos de Respostas (Responses)

Resposta quando SUCESSO - Code 200:

ERRO de Validação - Code 400:

Accept-Version v1

ERRO de Validação - Code 400:

Accept-Version v2:

ERRO de Autenticação - Code 401:

ERRO de Permissão - Code 403:

ERRO de Limite diário de requisições excedido - Code 429:

Accept-Version v1

Accept-Version v2