TOTVS RH Linha Ahgora Integrador

Árvore de páginas

This documentation describes the features of the Pontoweb system's Results Calculation API. The API allows you to start calculation processes, monitor their status, consult the results calculated and manage the re-consumption of events that have already been processed.

The operations have been developed for integration with payroll systems, accounting systems or other corporate applications that need to access employees' time and attendance data and accounting events.

All requests require authentication via HTTP Basic Auth, using a service type user. Some routes also require specific versioning headers.

Responses are in JSON format, with clear error and success messages to facilitate handling by client applications.


ITG2.0-01 Authentication

Starts the process of calculating accounting events and clockings for employees in a given period. It allows you to filter by location, specific employees and optional features such as daily totals, daily punches and monthly totals.


Limitations of Use

  • A maximum of 3 daily processes are allowed for the “full base” for each type of ‘feature’ parameter consumed (daily.totals, daily.punches, and monthly). In calls informing the registration filter (not “full base”), consumption is free.
  • A maximum of 4 simultaneous processes are allowed to start.

Item

Description
Flow: Client → PontoWeb
URL API: https://api.ahgora.com.br/reckons/process/start
Method: POST
Auth: Basic (show)


Body Request:

Field Type Required Description
registers array Situational List of employee registrations, if empty, considers all employees. When the rescission field is true, this field becomes mandatory and must contain at least one register.
rescission boolean Yes Indicates whether to consider dismissed employees. Default: false.
month string Yes Calculation month, expected format: “MM”.
year string Yes Calculation year, expected format: “YYYY”.
paymentDate string No Date of payment, expected format: “YYYY-MM-DD”.
infotype string No Identification of the event type. Default: 0015.
allowEmpty boolean No Displays employees without data. Default: false.
locations array  No Filters employees by location registered with Pontoweb.
features array No

Type of processing requested. Options:

  • "daily.punches"
  • "daily.totals"
  • "monthly"

    Default: monthly.
    You can request a specific one or more than one. If you don't enter one, the default one will be generated.
includeEmptyCode boolean No

Indicates to the flow that events without an accounting code should also be included in the result response. Default: false.

Note: When set to true, the returned events may include negative values if the original event value is negative.


Request examples:


Body Request:

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


Responses examples:


Response when SUCCESS - Code 200:

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


Authentication ERROR - Code 401:

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


Permission ERROR - Code 403:

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

Note: Check the user's permissions to access the route/service.


Validation ERROR - Code 400:

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

Note: Check the mandatory parameters of the request.

Once you have requested processing, you can query the status. This query returns the status of a previously initiated calculation process. It informs you whether processing has been completed, whether there have been any errors and the progress. You must provide the process identifier.


Item

Description
Flow: Client → PontoWeb
URL API: https://api.ahgora.com.br/reckons/process/status/:process
Method: GET
Auth: Basic (show)
Parameters: Process

This is the identifier code of the initiated process, obtained on the response from the start process request.

Example: 6b28ff7e-dda5-415c-b5b4-ff776f92142b



Query Params
Key Value
Accept-Version v1
v2


Response body:

Field Type Description
process string Initiated process code.
company string Company code in the PontoWeb system.
status string

Current process status:

"processing" – Processing in progress;

"done" – Processing completed successfully;

"error" – Processing completed with error.
unique string Unique identifier code for process control.
progress.done number Number of employees with completed processing.
progress.total number Total number of employees to be processed.


Response examples:


Response when in PROCESS - Code 200:

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


Response when SUCCESS - Code 200:

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


Validation ERROR - Code 400:

Accept-Version v1
{
    "error": {
        "message": "Process not found",
        "code": 400
    }
}

Note: Check the unique code entered.


Validation ERROR - Code 400:

Accept-Version v2:
{
    "error": "Process not found"
}

Note: Check the unique code entered.


Authentication ERROR - Code 401:

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

Note: Check the username and password entered.

Permission ERROR - Code 403:

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

Note: Check the user's permissions to access the route/service.

Obtains the generated processing results, based on the unique identifier code. The data returned can include monthly events, daily totals and punches (clockings), as defined in the request asking for the results.
The data is available for 72 hours for consumption; after this period, it automatically expires.


Important: once the process data has been successfully queried, the events returned are marked as “consumed” and will not be displayed again in future calls.
To obtain the same events, you will need to enable the re-consumption of events via route 4. Enable re-consumption of events.


Item

Description
Flow: Client → PontoWeb
URL API: https://api.ahgora.com.br/reckons/:unique
Method: GET
Auth: Basic (show)
Parameter:
  • Unique (string): is the unique identifier code for control.

    Example: 3234ca5d
  • Limit (number) (optional): is the limit of records that will be returned in the response.
    • Default: 1000.
    • Max: 1000.


Response examples:


Response - monthly

Example of a response when the “features” field is entered with “monthly” in the request for calculated results:

Field Type Description

unique

 string Unique process identifier code.
company string Company code in the PontoWeb system.
total number Total number of employees.
data array Contains a list of employee and event information.
data.employee string Employee's registration.
data.paymentDate string Date of payment, expected format: “YYYY-MM-DD”.
data.infotype string Identifying the type of event.
data.results array It contains a list of monthly events.
data.results.name string Name of the accounting code.
data.results.event string

Accounting code for the event.

Note: When the includeEmptyCode parameter in the body is set to true, this field may be returned with an empty value.
data.results.value string/number

Value of the accounting event.

Example:
Events in Days: 2;
Events in Hours: "16:00" (For Sexagesimals)
Events in Hours: "16,60" (For Centesimals)
data.results.type string Type of accounting event. Can be:
  • "days"
  • "hours"

By default, Absent Time are sent in hours (value and type).



Response when SUCCESS - Code 200:

{
	"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"
                  }
            ]
        }
    ]
}


Response - daily.punches

Example of a response when the “features” field is entered with “daily.punches” in the request for calculated results:

Field Type Description

unique

 string Unique process identifier code.
company string Company code in the PontoWeb system.
total number Total number of days counted.
data array Contains a list of employee and clock-in information.
data.employee string Matrícula do colaborador.
data.paymentDate string Date of payment, expected format: “YYYY-MM-DD”.
data.infotype string Identifying the type of event.
data.daily array Contains the list of clockings.
data.daily.day string Day on which the clock-in occurred, expected format: “YYYY-MM-DD”.
data.daily.punches array List of appointment information.
data.daily.punches.date string Effective date of clock-in.
data.daily.punches.hour string Time of clocking in, expected format:  "HHMM".
data.daily.punches.type string

Record type. Can be:

  • "O" - ETR (Electronic Time Recording) or Online Clocking.
  • "I"   - Manual Entry.
  • "BI" - Break Records.
data.daily.punches.label string Indicates whether the record is incoming or outgoing.


Response when SUCCESS - Code 200:

{
	"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"
                        }
                    ]
                }
            ]
        }
    ]
}


Response - daily.totals

Example response when the “features” field is entered with “daily.totals” in the request for calculated results:

Field Type Description

unique

 string Unique process identification code.
company string Company code in the PontoWeb system.
total number Total number of days counted.
data array Contains a list of employee information and daily events
data.employee string Employee's registration.
data.paymentDate string Date of payment, expected format: “YYYY-MM-DD”.
data.infotype string Identification of the event type.
data.daily array Contains a list of the punches (clockings).
data.daily.day string Day of the punches (clock-in), expected format: "YYYY-MM-DD".
data.daily.results array It contains a list of daily events.
data.daily.results.name string Name of the accounting code.
data.daily.results.event string

Accounting code for the event.

Note: When the includeEmptyCode parameter in the body is set to true, this field may be returned with an empty value.
data.daily.results.value string

Value of the accounting event.

Example:
Events in Days: 2;
Events in Hours: "16:00" (For Sexagesimals)
Events in Hours: "16,60" (For Centesimals)
data.daily.results.type string

Type of accounting event. Can be:

  • "days"
  • "hours"


Response when SUCESSO - Code 200:

{
    "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"
                        }
                    ]
                }
            ]
        }
    ]
}


Response - daily.totals, daily.punches e monthly

Example answer when the “features” field contains all the options.

Resposta when SUCESSO - Code 200:

{
    "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"
                }
            ]
        }
    ]
}

Authentication ERROR - Code 401

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

Note: Check the username and password entered.


ERRO de Permissão - Code 403

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

Note: Check the user's permissions to access the route/service.

Restores the availability of events previously consumed in a calculation process. After executing this route, the data associated with the identifier entered can be obtained again via the results query route.


Item

Description
Flow:

Client → PontoWeb
URL API: https://api.ahgora.com.br/reckons/reconsume/:unique
Method: GET
Auth: Basic (show)
Parameter:
  • Unique (string): is the unique identification code for control.

    Example: 3234ca5d
Max limit: 1000 times (The results calculation identified by unique)

Each refill is available for 72 hours for re-consumption.
After this time it is no longer accessible.


Response Body:

Field Type Description
company string Company code in the PontoWeb system.
unique string Unique process identification code.

Response examples:

Response when SUCESSO - Code 200:

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


Validation ERROR - Code 400:

Accept-Version v1
{
    "error": {
        "message": "Process not found",
        "code": 400
    }
}

Note: Check the unique code entered.


Validation ERROR - Code 400:

Accept-Version v2:
{
    "error": "Process not found"
}

Note: Check the unique code entered.


Authentication ERROR - Code 401:

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

Note: Check the username and password entered.


Permission ERROR - Code 403:

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

Note: Check the user's permissions to access the route/service.


Daily requisition limit exceeded ERROR - Code 429:

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


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



Under construction


  1. How to identify the limit of 1000 records per page, what is considered a record?

    Answer: Each record is an Object returned in the "data" property in the body of the request. In the example below, we have 2 objects within "data", one referring to the daily (daily.totals and punches) and the second referring to the monthly (results), so we have two (2) records:

    "company": "a123456",
"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"
                    }
                ],
                "punches": [
                    {
                        "date": "2022-07-28",
                        "hour": "0800",
                        "type": "O",
                        "label": "entrada-1"
                    }
                ]
            }
        ]
    },
    {
        "employee": "98a159Q",
        "paymentDate": "2022-08-08",
        "infotype": "0015",
        "results": [
            {
                "name": "Horas previstas",
                "event": "9077",
                "value": "71:20",
                "type": "hours"
            }
        ]
    }
]
}