{ "openapi": "3.1.0", "info": { "title": "Burdaa API", "version": "1.3.0", "description": "Burdaa personel devam kontrol sisteminin dış sistemler (bordro, ERP, İK) için okuma API'si. Anahtar, Burdaa panelinde Şirket Ayarları > Entegrasyonlar > API anahtarları bölümünden oluşturulur. Ayrıntılı rehber: https://www.burdaa.co/dokumanlar/api", "contact": { "name": "Burdaa", "email": "info@burdaa.co", "url": "https://www.burdaa.co/iletisim" } }, "servers": [ { "url": "https://app.burdaa.co/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/employees": { "get": { "operationId": "listEmployees", "summary": "Çalışan listesi", "description": "Şirketin tüm çalışanları (işten ayrılanlar dahil, is_active ile ayrılır).", "responses": { "200": { "description": "Çalışanlar", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } }, "has_more": { "type": "boolean", "description": "true ise offset=next_offset ile sonraki sayfayı isteyin" }, "next_offset": { "type": [ "integer", "null" ] } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ] } }, "/timesheet": { "get": { "operationId": "getTimesheet", "summary": "Günlük puantaj", "description": "Kişi × gün puantajı. Yalnızca kapanmış günler (to bugünden önce olmalı); istek başına en fazla 63 gün.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Puantaj satırları", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimesheetDay" } }, "has_more": { "type": "boolean", "description": "true ise offset=next_offset ile sonraki sayfayı isteyin" }, "next_offset": { "type": [ "integer", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/pay-summary": { "get": { "operationId": "getPaySummary", "summary": "Aylık ücret özeti", "description": "Burdaa'nın ücret hesabı özeti. Yalnızca 'Ücret özetini de okuyabilsin' izni verilmiş anahtarla. Vergi ve SGK içermez; bordro programınız için girdidir.", "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "integer" }, "example": 2026 }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 9 }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Ücret özeti", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaySummary" } }, "has_more": { "type": "boolean", "description": "true ise offset=next_offset ile sonraki sayfayı isteyin" }, "next_offset": { "type": [ "integer", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/punches": { "get": { "operationId": "listPunches", "summary": "Ham okutmalar", "description": "Giriş-çıkış okutmaları, zaman sırasıyla. Bugün dahil; istek başına en fazla 63 gün. Gün sınırları şirketin saat diliminde.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Okutmalar", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Punch" } }, "has_more": { "type": "boolean", "description": "true ise offset=next_offset ile sonraki sayfayı isteyin" }, "next_offset": { "type": [ "integer", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/leaves": { "get": { "operationId": "listLeaves", "summary": "İzinler", "description": "Tarih aralığıyla kesişen izinler; ileri tarihli ve onay bekleyenler dahil. İstek başına en fazla 366 gün. Notlar ve ekler verilmez.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "İzinler", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Leave" } }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "webhooks": { "punchEvent": { "post": { "summary": "Okutma ve izin olayları", "description": "Panelde Şirket Ayarları > Entegrasyonlar > Webhook bölümünden eklenen adrese gönderilir. X-Burdaa-Signature: t=,v1=. 2xx dışındaki cevaplarda 1 dk, 5 dk, 15 dk, 1 sa, 3 sa, 6 sa, 12 sa sonra tekrar denenir.", "parameters": [ { "name": "X-Burdaa-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "punch.created", "punch.updated", "punch.deleted", "leave.created", "leave.updated", "leave.deleted", "ping" ] } }, { "name": "X-Burdaa-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Burdaa-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760593202,v1=5f2b…" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Alındı (herhangi bir 2xx)" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "brd_ ile başlayan API anahtarı" } }, "responses": { "Error": { "description": "Hata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Anahtar başına dakikada 60 istek aşıldı", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Saniye" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_API_KEY", "API_KEY_FORBIDDEN", "INVALID_RANGE", "RANGE_NOT_CLOSED", "RANGE_TOO_LONG", "INVALID_PERIOD", "INVALID_PAGINATION", "RATE_LIMITED", "INTERNAL" ] }, "message": { "type": "string" } } } } }, "Employee": { "type": "object", "properties": { "employee_id": { "type": "string", "format": "uuid" }, "full_name": { "type": "string" }, "employee_code": { "type": [ "string", "null" ], "description": "Sicil no" }, "department": { "type": [ "string", "null" ] }, "location_name": { "type": [ "string", "null" ], "description": "Bağlı olduğu lokasyon/mağaza" }, "store_code": { "type": [ "string", "null" ], "description": "Mağaza kodu" }, "pay_type": { "type": "string", "enum": [ "salaried", "hourly" ] }, "hire_date": { "type": [ "string", "null" ], "format": "date", "description": "İşe giriş tarihi" }, "is_active": { "type": "boolean" }, "deactivated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TimesheetDay": { "type": "object", "properties": { "employee_id": { "type": "string", "format": "uuid" }, "employee_code": { "type": [ "string", "null" ] }, "full_name": { "type": "string" }, "work_date": { "type": "string", "format": "date" }, "day_type": { "type": "string", "enum": [ "worked", "absent", "missing_punch", "off_day", "off_day_worked", "holiday", "holiday_worked", "leave_annual", "leave_sick", "leave_unpaid", "leave_other", "leave_marriage", "leave_bereavement", "leave_paternity", "leave_maternity", "leave_work_accident" ] }, "location_name": { "type": [ "string", "null" ] }, "store_code": { "type": [ "string", "null" ] }, "shift_start": { "type": [ "string", "null" ], "description": "Vardiya başlangıcı (yerel saat, HH:MM:SS)" }, "shift_end": { "type": [ "string", "null" ] }, "check_in": { "type": [ "string", "null" ], "description": "İlk giriş", "format": "date-time" }, "check_out": { "type": [ "string", "null" ], "description": "Son çıkış", "format": "date-time" }, "worked_minutes": { "type": "integer" }, "late_minutes": { "type": "integer" }, "early_leave_minutes": { "type": "integer" }, "overtime_minutes": { "type": "integer" }, "shortfall_minutes": { "type": "integer", "description": "Vardiyaya göre eksik çalışma" } } }, "PaySummary": { "type": "object", "properties": { "employee_id": { "type": "string", "format": "uuid" }, "employee_code": { "type": [ "string", "null" ] }, "full_name": { "type": "string" }, "is_active": { "type": "boolean" }, "base_salary": { "type": "number" }, "worked_minutes": { "type": "integer" }, "absent_days": { "type": "integer" }, "holiday_days": { "type": "integer" }, "weekday_overtime_pay": { "type": "number" }, "saturday_overtime_pay": { "type": "number" }, "sunday_overtime_pay": { "type": "number" }, "absent_deduction": { "type": "number" }, "long_absence_deduction": { "type": "number" }, "deactivation_deduction": { "type": "number" }, "shortfall_deduction": { "type": "number" }, "total_advance": { "type": "number" }, "net_amount": { "type": "number" } } }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Olay kimliği; tekrar denemelerde aynı kalır, çift kaydı bununla eleyin", "format": "uuid" }, "type": { "type": "string", "enum": [ "punch.created", "punch.updated", "punch.deleted", "leave.created", "leave.updated", "leave.deleted", "ping" ] }, "created_at": { "type": "string", "format": "date-time" }, "company_id": { "type": "string", "format": "uuid" }, "data": { "description": "punch.* için Punch alanları (+ punch.updated'da previous), leave.* için Leave alanları (+ leave.updated'da previous)", "oneOf": [ { "$ref": "#/components/schemas/Punch" }, { "$ref": "#/components/schemas/Leave" }, { "type": "object", "properties": { "message": { "type": "string" } } } ] } } }, "Punch": { "type": "object", "properties": { "punch_id": { "type": "string", "format": "uuid" }, "employee_id": { "type": "string", "format": "uuid" }, "employee_code": { "type": [ "string", "null" ] }, "full_name": { "type": "string" }, "type": { "type": "string", "enum": [ "check_in", "check_out" ] }, "method": { "type": "string", "enum": [ "qr_static", "qr_dynamic", "manual" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "location_id": { "type": "string", "format": "uuid" }, "location_name": { "type": [ "string", "null" ] }, "store_code": { "type": [ "string", "null" ] } } }, "Leave": { "type": "object", "properties": { "leave_id": { "type": "string", "format": "uuid" }, "employee_id": { "type": "string", "format": "uuid" }, "employee_code": { "type": [ "string", "null" ] }, "full_name": { "type": "string" }, "type": { "type": "string", "enum": [ "annual", "sick", "unpaid", "other", "marriage", "bereavement", "paternity", "maternity", "work_accident" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "days": { "type": "integer", "description": "Takvim günü" }, "deduct_from_pay": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "parameters": { "limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 }, "description": "Sayfa başına kayıt" }, "offset": { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Önceki cevabın next_offset değeri" } } } }