Documentation
¶
Overview ¶
Package tangerino provides a client library for the Tangerino employer API.
Create a client with NewClient, then use its service fields to access API resources:
client, err := tangerino.NewClient("username", "password")
if err != nil {
log.Fatal(err)
}
page, err := client.Employees.List(ctx, tangerino.ListEmployeesParams{PageSize: 20})
punches, err := client.Punches.GetEmployeePunches(ctx, employeeID)
Index ¶
- func IsForbidden(err error) bool
- func IsNotFound(err error) bool
- func IsRateLimited(err error) bool
- func IsServerError(err error) bool
- func IsUnauthorized(err error) bool
- type APIError
- type Client
- type CompaniesService
- type Company
- type DayOffset
- type Employee
- type EmployeesService
- type EntityRef
- type Environment
- type Holiday
- type HolidayCalendar
- type HolidayCalendarsService
- type ListCompaniesParams
- type ListEmployeesParams
- type Option
- type Page
- type UnixMilliTime
- type WorkSchedule
- type WorkScheduleRef
- type WorkScheduleTimetable
- type WorkSchedulesService
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsForbidden ¶
IsForbidden reports whether err is a 403 Forbidden API error.
func IsNotFound ¶
IsNotFound reports whether err is a 404 Not Found API error.
func IsRateLimited ¶
IsRateLimited reports whether err is a 429 Too Many Requests API error.
func IsServerError ¶
IsServerError reports whether err is a 5xx server-side API error.
func IsUnauthorized ¶
IsUnauthorized reports whether err is a 401 Unauthorized API error.
Types ¶
type APIError ¶
type APIError struct {
// StatusCode is the HTTP status code from the response.
StatusCode int
// Body contains the raw response body, available for debugging or custom parsing.
Body []byte
}
APIError represents an HTTP error returned by the Tangerino API.
type Client ¶
type Client struct {
// Employees provides access to employee management endpoints.
Employees *EmployeesService
// HolidayCalendars provides access to holiday calendar endpoints.
HolidayCalendars *HolidayCalendarsService
// WorkSchedules provides access to work schedule endpoints.
WorkSchedules *WorkSchedulesService
// Companies provides access to company endpoints.
Companies *CompaniesService
// contains filtered or unexported fields
}
Client is the Tangerino API client. Use its service fields to call specific API resources.
type CompaniesService ¶
type CompaniesService struct {
// contains filtered or unexported fields
}
CompaniesService handles communication with the company endpoints.
func (*CompaniesService) List ¶
func (s *CompaniesService) List(ctx context.Context, params ListCompaniesParams) (*Page[Company], error)
List retrieves a single page of companies matching the given parameters. All parameters are optional; omit them by using a zero-value ListCompaniesParams.
GET /companies
type Company ¶
type Company struct {
// ID is the unique identifier of the company.
ID int `json:"id"`
// CNPJ is the company's Brazilian federal tax registration number, formatted with punctuation.
CNPJ string `json:"cnpj"`
// ExternalID is an optional identifier assigned by an external system.
ExternalID string `json:"externalId"`
// SocialReason is the company's registered legal name.
SocialReason string `json:"socialReason"`
// FantasyName is the company's trade name used in day-to-day operations.
FantasyName string `json:"fantasyName"`
// DescriptionName is the display name used in the Tangerino interface.
DescriptionName string `json:"descriptionName"`
}
Company represents a single company record returned by the API.
type DayOffset ¶
type DayOffset int64
DayOffset is a time offset from midnight stored as milliseconds, as received from the API. It is used for shift and interval fields in work schedule timetables. Values may exceed 86400000 (24 h) when a shift extends past midnight into the next day.
type Employee ¶
type Employee struct {
// ID is the unique identifier of the employee.
ID int `json:"id"`
// Name is the employee's full legal name.
Name string `json:"name"`
// SocialName is the employee's preferred or social name, if provided.
SocialName string `json:"socialName"`
// Email is the employee's contact email address.
Email string `json:"email"`
// CPF is the employee's Brazilian tax identification number.
CPF string `json:"cpf"`
// PIS is the employee's Social Integration Program number, if provided.
PIS string `json:"pis"`
// Gender is the employee's gender as reported by the API (e.g. "MASCULINO", "FEMININO").
Gender string `json:"gender"`
// BirthDate is the employee's date of birth as a Unix millisecond timestamp.
// It is nil when the value is not present in the API response.
BirthDate *UnixMilliTime `json:"birthDate"`
// AdmissionDate is the employee's hiring date as a Unix millisecond timestamp.
AdmissionDate UnixMilliTime `json:"admissionDate"`
// EffectiveDate is the date the current record became effective, as a Unix millisecond timestamp.
EffectiveDate UnixMilliTime `json:"effectiveDate"`
// ExternalID is an optional identifier assigned by an external system.
ExternalID string `json:"externalId"`
// CurrentWorkSchedule is a reference to the work schedule currently active for the employee.
CurrentWorkSchedule WorkScheduleRef `json:"currentWorkSchedule"`
// Company is a reference to the company the employee belongs to.
Company EntityRef `json:"company"`
// JobRole is a reference to the employee's current job role.
JobRole EntityRef `json:"jobRoleDTO"`
// LastManager is a reference to the employee's most recent manager.
LastManager EntityRef `json:"lastManager"`
// Managers holds references to all current managers for the employee.
Managers []EntityRef `json:"managers"`
// WorkplaceList holds references to all workplaces assigned to the employee.
WorkplaceList []EntityRef `json:"workplaceList"`
// Fired indicates whether the employee has been terminated.
Fired bool `json:"fired"`
// CanViewWorkgroup indicates whether the employee has workgroup visibility permissions.
CanViewWorkgroup bool `json:"canViewWorkgroup"`
// Status is the numeric status code for the employee record.
Status int `json:"status"`
// DoubleBindEmployee indicates whether the employee is shared across multiple companies.
DoubleBindEmployee bool `json:"doubleBindEmployee"`
// RecordsPunch indicates whether the employee uses the punch clock system.
RecordsPunch bool `json:"recordsPunch"`
}
Employee represents a single employee record returned by the API.
type EmployeesService ¶
type EmployeesService struct {
// contains filtered or unexported fields
}
EmployeesService handles communication with the employee endpoints.
func (*EmployeesService) List ¶
func (s *EmployeesService) List(ctx context.Context, params ListEmployeesParams) (*Page[Employee], error)
List retrieves a single page of employees matching the given parameters. All parameters are optional; omit them by using a zero-value ListEmployeesParams.
GET /employee/find-all
type EntityRef ¶
type EntityRef struct {
// ID is the unique identifier of the referenced entity.
ID int `json:"id"`
}
EntityRef is a lightweight reference to a related entity identified by its ID. It is used for nested objects where the API returns only the identifier.
type Environment ¶
type Environment struct {
// contains filtered or unexported fields
}
Environment holds the API base URL for a deployment target.
type Holiday ¶
type Holiday struct {
// ID is the unique identifier of the holiday.
ID int `json:"id"`
// Description is the name or label of the holiday.
Description string `json:"description"`
// Date is the calendar date of the holiday in YYYY-MM-DD format.
Date string `json:"date"`
}
Holiday represents a single public or regional holiday entry within a calendar.
type HolidayCalendar ¶
type HolidayCalendar struct {
// ID is the unique identifier of the calendar.
ID int `json:"id"`
// Name is the human-readable label assigned to the calendar.
Name string `json:"name"`
// Description is an optional extended description of the calendar.
Description string `json:"description"`
// Year is the year this calendar applies to.
Year int `json:"year"`
// Holidays lists the individual holiday entries contained in this calendar.
Holidays []Holiday `json:"holidays"`
}
HolidayCalendar represents a named collection of holidays for a specific year. Each calendar may cover a national, regional, or custom set of holidays.
type HolidayCalendarsService ¶
type HolidayCalendarsService struct {
// contains filtered or unexported fields
}
HolidayCalendarsService handles communication with the holiday calendar endpoints.
func (*HolidayCalendarsService) List ¶
func (s *HolidayCalendarsService) List(ctx context.Context) ([]HolidayCalendar, error)
List retrieves all holiday calendars available for the authenticated employer.
GET /holiday-calendar/
type ListCompaniesParams ¶
type ListCompaniesParams struct {
// Offset is the item offset within the result set.
Offset int
// PageNumber is the zero-based page index to retrieve.
PageNumber int
// PageSize is the number of items per page.
PageSize int
}
ListCompaniesParams holds optional filter and pagination parameters for the companies endpoint. All fields are optional; zero values are omitted from the request.
type ListEmployeesParams ¶
type ListEmployeesParams struct {
// BranchExternalID filters employees by the external identifier of their branch.
BranchExternalID string
// ManagerExternalID filters employees by the external identifier of their manager.
ManagerExternalID string
// LastUpdate filters employees modified after this Unix timestamp in milliseconds.
LastUpdate int64
// Page is the zero-based page index to retrieve.
Page int
// PageNumber is an alias for Page accepted by the API.
PageNumber int
// PageSize is the number of items per page (used alongside PageNumber).
PageSize int
// Size is the number of items per page (used alongside Page).
Size int
// Offset is the item offset within the result set.
Offset int
// ShowFired controls whether terminated employees are included (0 = exclude, 1 = include).
ShowFired int
}
ListEmployeesParams holds optional filter and pagination parameters for the employee list endpoint. All fields are optional; zero values are omitted from the request.
type Option ¶
type Option func(*Client)
Option is a functional option for configuring a Client.
func WithBaseURL ¶
WithBaseURL overrides the API base URL. Returns an error if the provided value is not a valid URL.
func WithHTTPClient ¶
WithHTTPClient replaces the default HTTP client with a custom one. Use this to configure custom timeouts, TLS settings, or proxies.
func WithStagingEnv ¶
func WithStagingEnv() Option
WithStagingEnv points the client at the staging environment.
type Page ¶
type Page[T any] struct { // Content holds the items on the current page. Content []T `json:"content"` // First indicates whether this is the first page. First bool `json:"first"` // Last indicates whether this is the last page. Last bool `json:"last"` // TotalElements is the total number of items across all pages. TotalElements int `json:"totalElements"` // TotalPages is the total number of pages available. TotalPages int `json:"totalPages"` // NumberOfElements is the number of items on this page. NumberOfElements int `json:"numberOfElements"` // Size is the maximum number of items per page as requested. Size int `json:"size"` // Number is the zero-based index of the current page. Number int `json:"number"` }
Page is a generic paginated response from the Tangerino API. It wraps a slice of T alongside Spring-style pagination metadata. Any endpoint that returns a paginated collection uses this type as its response.
Example:
page, err := client.Employees.List(ctx, tangerino.ListEmployeesParams{PageSize: 20})
for !page.IsLast() {
// process page.Content ...
params.Page++
page, err = client.Employees.List(ctx, params)
}
func (*Page[T]) NextPageNumber ¶
NextPageNumber returns the number to pass as Page in the next request. Returns -1 when the current page is the last one.
type UnixMilliTime ¶
type UnixMilliTime int64
UnixMilliTime is an absolute timestamp stored as milliseconds since the Unix epoch, exactly as received from the API. It provides helpers to access the raw value or convert to standard Go types without losing precision.
func (UnixMilliTime) Format ¶
func (t UnixMilliTime) Format(layout string) string
Format formats the timestamp using the given layout (same syntax as time.Time.Format).
Example:
t.Format("02/01/2006") // "01/01/2025"
t.Format("15:04") // "09:00"
t.Format(time.RFC3339)
func (UnixMilliTime) Raw ¶
func (t UnixMilliTime) Raw() int64
Raw returns the original Unix millisecond value as received from the API.
func (UnixMilliTime) String ¶
func (t UnixMilliTime) String() string
String returns the timestamp formatted as "2006-01-02 15:04:05 UTC".
func (UnixMilliTime) Time ¶
func (t UnixMilliTime) Time() time.Time
Time converts the value to a time.Time in UTC.
type WorkSchedule ¶
type WorkSchedule struct {
// ID is the unique identifier of the work schedule.
ID int `json:"id"`
// Name is the human-readable label for the work schedule.
Name string `json:"name"`
// Standard indicates whether this is the default system schedule.
Standard bool `json:"standard"`
// Timetable holds the per-day time configurations for this schedule.
Timetable []WorkScheduleTimetable `json:"workScheduleTimetableList"`
// AlterationDate is the Unix millisecond timestamp of the last modification.
AlterationDate UnixMilliTime `json:"alterationDate"`
// PreAssignedInterval indicates whether break intervals are pre-assigned across the schedule.
PreAssignedInterval bool `json:"preAssignedInterval"`
// ShowIntradayInTimeSheet indicates whether intraday entries appear in the time sheet.
ShowIntradayInTimeSheet bool `json:"showIntradayInTimeSheet"`
// IgnoreHoliday indicates whether this schedule applies on public holidays.
IgnoreHoliday bool `json:"ignoreHoliday"`
// Inactive indicates whether the schedule has been deactivated.
Inactive bool `json:"inactive"`
}
WorkSchedule represents a full work schedule definition including its daily timetables.
type WorkScheduleRef ¶
type WorkScheduleRef struct {
// ID is the unique identifier of the work schedule.
ID int `json:"id"`
// StartDate is the Unix timestamp (milliseconds) when the schedule became effective for the employee.
StartDate UnixMilliTime `json:"startDate"`
// Inactive indicates whether the schedule has been deactivated.
Inactive bool `json:"inactive"`
}
WorkScheduleRef is a lightweight reference to a work schedule as embedded in an employee record. For the full work schedule details use WorkSchedule, returned by WorkSchedulesService.
type WorkScheduleTimetable ¶
type WorkScheduleTimetable struct {
// ID is the unique identifier of this timetable entry.
ID int `json:"id"`
// Day is the day of the week this entry applies to (1=Sunday, 2=Monday, ..., 7=Saturday).
Day int `json:"day"`
// StartMainInterval is the start of the main break period as a day offset.
StartMainInterval DayOffset `json:"startMainInterval"`
// EndMainInterval is the end of the main break period as a day offset.
// It is nil when the schedule has no defined end for the main interval.
EndMainInterval *DayOffset `json:"endMainInterval"`
// StartShift1 is the start of the first shift as a day offset.
StartShift1 DayOffset `json:"startShift1"`
// EndShift1 is the end of the first shift as a day offset.
// It is nil when the first shift has no defined end time.
EndShift1 *DayOffset `json:"endShift1"`
// StartShift2 is the start of the second shift as a day offset.
// It is nil when there is no second shift.
StartShift2 *DayOffset `json:"startShift2"`
// EndShift2 is the end of the second shift as a day offset.
// It is nil when there is no second shift.
EndShift2 *DayOffset `json:"endShift2"`
// IntervalPreAssigned1And2 indicates whether the interval between shifts 1 and 2 is pre-assigned.
IntervalPreAssigned1And2 bool `json:"intervalPreAssigned1And2"`
// IntervalPreAssigned2And3 indicates whether the interval between shifts 2 and 3 is pre-assigned.
IntervalPreAssigned2And3 bool `json:"intervalPreAssigned2And3"`
// IntervalPreAssigned3And4 indicates whether the interval between shifts 3 and 4 is pre-assigned.
IntervalPreAssigned3And4 bool `json:"intervalPreAssigned3And4"`
// IntervalPreAssigned4And5 indicates whether the interval between shifts 4 and 5 is pre-assigned.
IntervalPreAssigned4And5 bool `json:"intervalPreAssigned4And5"`
// IntervalPreAssigned5And6 indicates whether the interval between shifts 5 and 6 is pre-assigned.
IntervalPreAssigned5And6 bool `json:"intervalPreAssigned5And6"`
}
WorkScheduleTimetable represents the time configuration for a single day within a work schedule. All interval values are milliseconds elapsed since midnight.
type WorkSchedulesService ¶
type WorkSchedulesService struct {
// contains filtered or unexported fields
}
WorkSchedulesService handles communication with the work schedule endpoints.
func (*WorkSchedulesService) List ¶
func (s *WorkSchedulesService) List(ctx context.Context) (*Page[WorkSchedule], error)
List retrieves all work schedules available for the authenticated employer.
GET /work-schedule