Attendance Capture and Punch API
Summary
Five direct operations submit, list, approve, and reject punches. No punch edit/delete/correction or device-ingestion endpoint exists.
Audience
Frontend/backend developers, QA engineers, support engineers, and implementation partners.
Reference Content
Authentication: Bearer/self or approver context expected; exact route enforcement requires confirmation. Tenant: required by punch workflow. Maturity: Direct/Shadow. Response: ApiResponse<T> with 200 success; 400 validation/missing tenant, 404 missing punch.
| Operation | Method and public route | Parameters/body | Response | Behavior, side effects, and examples |
|---|---|---|---|---|
| Today's punches | GET /attendance/punch/today | Optional query laborId; otherwise self context | ApiResponse<PunchLogDto[]>, 200 | Current-date punches, ordered by time; no side effect. Example GET …?laborId=4242 → data:[]; handled tenant failure → 400. |
| Personal weekly attendance | GET /attendance/punch/weekly | Required start, end; employee comes from self context | ApiResponse<AttendanceDto[]>, 200 | Personal date-range attendance; no side effect. Example fictional date range → 200; binding failure → framework 400. |
| Submit punch | POST /attendance/punch | PunchRequest | ApiResponse<PunchLogDto>, 200 | Persists punch, audits it, raises high-level punch event; sufficient duration can create/update attendance and corresponding attendance event. Missing employee → 400. Example body {"laborId":4242,"type":"Punch Out","time":"2030-01-02T17:00:00Z","mode":"Web","workHours":7.5,"note":"Fictional test"}; success returns fictional punch DTO; error envelope contains no personal data. |
| Approve punch | POST /attendance/punch/{id:int}/approve | Integer id; no body | ApiResponse<PunchLogDto>, 200 | Marks punch approved, can recalculate/approve related attendance, audits; missing punch → 404. Example POST …/9001/approve → 200; unknown id → 404. |
| Reject punch | POST /attendance/punch/{id:int}/reject | Integer id; no body | ApiResponse<PunchLogDto>, 200 | Rejects punch; clears matching attendance only when unapproved; audits; missing punch → 404. Example POST …/9001/reject → 200; unknown id → 404. |
PunchRequest fields: laborId, type, time, mode, optional workHours, optional overtimeHours, optional note. Source validation requires a resolved positive employee; aggregate rules validate tenant/employee and normalize punch values. Work duration uses explicit hours or a supported out-to-first-in pairing. Multiple punch rows are supported. Duplicate ordering, missing-punch correction, invalid sequence, biometric/device capture, and import are Not implemented or Requires confirmation.
PunchLogDto returns punch identity, employee reference/display label, type/time/mode, work/overtime hours, note, approval flag, and punch status. Payroll lock is not consulted by these operations.
Source References
microservices/src/attendance-service/Api/AttendanceDirectEndpoints.csmicroservices/src/attendance-service/Application/Dtos.csmicroservices/src/attendance-service/Application/Services/PunchWorkflow.csmicroservices/src/attendance-service/Domain/Attendance/AttendancePunchRecord.cs
Related Articles
See Also
Keywords
- Attendance API
- Attendance Capture and Punch API
Revision Information
- Status: Draft
- Last reviewed: 2026-07-15
- Review cycle: Quarterly