{ "components" : { "headers" : { "Retry-After" : { "description" : "Seconds until the next request is allowed (429); 1 on 409 idempotency_in_progress", "schema" : { "format" : "int32", "type" : "integer" } }, "X-RateLimit-Limit" : { "description" : "The key's requests per minute; present once the key is accepted (not on 401, nor on 403 ip_not_allowed)", "schema" : { "format" : "int32", "type" : "integer" } }, "X-RateLimit-Remaining" : { "description" : "Requests the key has left in the current minute after this one; present with X-RateLimit-Limit", "schema" : { "format" : "int32", "type" : "integer" } }, "X-Request-Id" : { "description" : "A UUID the server made for this request, also in every error body (requestId); quote it when you report a problem. A request id the client sends is ignored", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } }, "schemas" : { "IntegrationCard" : { "properties" : { "cardNumber" : { "description" : "The card's identifier, as the MASK web app shows it", "type" : "string" }, "cardSerial" : { "type" : "string" }, "createdAt" : { "description" : "Epoch seconds, UTC", "format" : "int32", "type" : "integer" }, "description" : { "type" : "string" }, "employeeId" : { "format" : "int32", "type" : "integer" }, "id" : { "format" : "int32", "type" : "integer" }, "status" : { "description" : "active, inactive or lost; a person has at most one active card", "type" : "string" }, "updatedAt" : { "format" : "int32", "type" : "integer" } }, "type" : "object" }, "IntegrationEmployee" : { "properties" : { "createdAt" : { "description" : "Epoch seconds, UTC", "format" : "int32", "type" : "integer" }, "email" : { "type" : "string" }, "firstName" : { "type" : "string" }, "id" : { "format" : "int32", "type" : "integer" }, "language" : { "description" : "en, bs or tr", "type" : "string" }, "lastName" : { "type" : "string" }, "memberships" : { "description" : "Memberships in the key's institutions, active and ended", "items" : { "$ref" : "#/components/schemas/IntegrationMembership" }, "type" : "array" }, "personalId" : { "type" : "string" }, "status" : { "description" : "active, inactive or terminated", "type" : "string" }, "updatedAt" : { "format" : "int32", "type" : "integer" } }, "type" : "object" }, "IntegrationEmployeeCreateRequest" : { "properties" : { "email" : { "maxLength" : 255, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" }, "firstName" : { "maxLength" : 100, "minLength" : 0, "type" : "string" }, "language" : { "description" : "en, bs or tr; en when omitted", "pattern" : "en|bs|tr", "type" : "string" }, "lastName" : { "maxLength" : 100, "minLength" : 0, "type" : "string" }, "memberships" : { "items" : { "$ref" : "#/components/schemas/IntegrationMembershipCreateRequest" }, "minItems" : 1, "type" : "array" }, "personalId" : { "maxLength" : 50, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" } }, "required" : [ "firstName", "lastName", "memberships" ], "type" : "object" }, "IntegrationEmployeeReport" : { "properties" : { "employeeId" : { "format" : "int32", "type" : "integer" }, "from" : { "format" : "date", "type" : "string" }, "rows" : { "items" : { "$ref" : "#/components/schemas/IntegrationEmployeeReportRow" }, "type" : "array" }, "to" : { "format" : "date", "type" : "string" }, "totalWorkSeconds" : { "description" : "The closed shifts' work; a shift still in progress adds nothing yet", "format" : "int64", "type" : "integer" } }, "type" : "object" }, "IntegrationEmployeeReportRow" : { "properties" : { "businessDate" : { "format" : "date", "type" : "string" }, "endedAt" : { "description" : "Absent while the shift is open or when the clock-out was forgotten", "format" : "int32", "type" : "integer" }, "institutionId" : { "format" : "int32", "type" : "integer" }, "sessionId" : { "format" : "int64", "type" : "integer" }, "startedAt" : { "description" : "Epoch seconds, UTC", "format" : "int32", "type" : "integer" }, "status" : { "description" : "in_progress, complete or incomplete", "type" : "string" }, "workSeconds" : { "description" : "The shift's closed work; absent while it is in progress", "format" : "int64", "type" : "integer" } }, "type" : "object" }, "IntegrationEmployeeUpdateRequest" : { "properties" : { "email" : { "maxLength" : 255, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" }, "firstName" : { "maxLength" : 100, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" }, "language" : { "pattern" : "en|bs|tr", "type" : "string" }, "lastName" : { "maxLength" : 100, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" }, "personalId" : { "maxLength" : 50, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" }, "status" : { "description" : "active, inactive or terminated; leaving active signs the person out of the employee portal. Refused (403 admin_linked_employee) for a protected employee record", "pattern" : "active|inactive|terminated", "type" : "string" } }, "type" : "object" }, "IntegrationError" : { "description" : "The one error body of the integration API. Program against code; message is for people and may be reworded. New codes may be added in v1: treat an unknown code by its HTTP status", "properties" : { "code" : { "enum" : [ "validation_failed", "idempotency_required", "event_too_old", "invalid_api_key", "key_expired", "key_revoked", "ip_not_allowed", "scope_missing", "institution_not_allowed", "not_api_event", "admin_linked_employee", "not_found", "method_not_allowed", "not_acceptable", "unsupported_media_type", "conflict", "idempotency_in_progress", "idempotency_mismatch", "rate_limited", "internal_error", "unavailable" ], "type" : "string" }, "message" : { "type" : "string" }, "requestId" : { "description" : "The X-Request-Id of this answer; quote it when you report a problem", "format" : "uuid", "type" : "string" }, "status" : { "enum" : [ "error" ], "type" : "string" }, "violations" : { "description" : "Only on validation_failed", "items" : { "$ref" : "#/components/schemas/IntegrationErrorViolation" }, "type" : "array" } }, "required" : [ "status", "code", "message", "requestId" ], "type" : "object" }, "IntegrationErrorViolation" : { "description" : "One field of a validation_failed answer", "properties" : { "field" : { "description" : "The body field, parameter or header", "type" : "string" }, "message" : { "type" : "string" } }, "required" : [ "field", "message" ], "type" : "object" }, "IntegrationEvent" : { "properties" : { "anomalies" : { "description" : "Rollup flags, e.g. duplicate, no_open_session; empty when clean", "items" : { "type" : "string" }, "type" : "array" }, "businessDate" : { "description" : "The business date at the institution (local time minus its day boundary), ISO date", "format" : "date", "type" : "string" }, "correctsEventId" : { "description" : "For a correction: the id of the event it replaces", "format" : "int64", "type" : "integer" }, "createdAt" : { "format" : "int32", "type" : "integer" }, "employeeId" : { "format" : "int32", "type" : "integer" }, "eventCode" : { "type" : "string" }, "eventTime" : { "description" : "Epoch seconds, UTC", "format" : "int32", "type" : "integer" }, "id" : { "format" : "int64", "type" : "integer" }, "institutionId" : { "format" : "int32", "type" : "integer" }, "note" : { "type" : "string" }, "source" : { "description" : "manual, controller, api, portal or mobile", "type" : "string" }, "status" : { "description" : "active, corrected or voided", "type" : "string" }, "updatedAt" : { "format" : "int32", "type" : "integer" } }, "type" : "object" }, "IntegrationEventCode" : { "properties" : { "closesSession" : { "description" : "Ends a shift (clock_out)", "type" : "boolean" }, "code" : { "type" : "string" }, "countsAsWork" : { "type" : "boolean" }, "displayName" : { "type" : "string" }, "opensInterval" : { "description" : "The interval kind it opens: work, break, personal or business; absent when it only closes", "type" : "string" }, "opensSession" : { "description" : "Starts a shift (clock_in)", "type" : "boolean" }, "sortOrder" : { "format" : "int32", "type" : "integer" } }, "type" : "object" }, "IntegrationEventCorrectRequest" : { "properties" : { "eventCode" : { "maxLength" : 50, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" }, "eventTime" : { "description" : "Epoch seconds, UTC; at most 300 s in the future and at most 62 days back (business date)", "format" : "int32", "type" : "integer" }, "note" : { "maxLength" : 500, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" } }, "type" : "object" }, "IntegrationEventCreateRequest" : { "properties" : { "employeeId" : { "format" : "int32", "type" : "integer" }, "eventCode" : { "description" : "A code from GET /integration/event-codes that is enabled at the institution", "maxLength" : 50, "minLength" : 0, "type" : "string" }, "eventTime" : { "description" : "Epoch seconds, UTC; at most 300 s in the future and at most 62 days back (business date)", "format" : "int32", "type" : "integer" }, "institutionId" : { "format" : "int32", "type" : "integer" }, "note" : { "maxLength" : 500, "minLength" : 0, "type" : "string" } }, "required" : [ "employeeId", "eventCode", "eventTime", "institutionId" ], "type" : "object" }, "IntegrationInstitution" : { "properties" : { "dayBoundaryMinutes" : { "description" : "Minutes after local midnight when its business day starts (240 = 04:00)", "format" : "int32", "type" : "integer" }, "displayName" : { "type" : "string" }, "enabledEventCodes" : { "description" : "The event codes enabled here; an event with another code is refused", "items" : { "type" : "string" }, "type" : "array" }, "id" : { "format" : "int32", "type" : "integer" }, "name" : { "type" : "string" }, "shortName" : { "type" : "string" }, "status" : { "description" : "active, inactive or archived", "type" : "string" }, "timezone" : { "description" : "IANA zone of its business dates, e.g. Europe/Sarajevo", "type" : "string" } }, "type" : "object" }, "IntegrationInstitutionReport" : { "properties" : { "from" : { "format" : "date", "type" : "string" }, "institutionId" : { "format" : "int32", "type" : "integer" }, "rows" : { "items" : { "$ref" : "#/components/schemas/IntegrationInstitutionReportRow" }, "type" : "array" }, "to" : { "format" : "date", "type" : "string" }, "totalWorkSeconds" : { "format" : "int64", "type" : "integer" }, "workingDays" : { "description" : "Business dates on which anyone worked there", "format" : "int32", "type" : "integer" } }, "type" : "object" }, "IntegrationInstitutionReportRow" : { "properties" : { "absenceDays" : { "description" : "Approved absence days in the period; a half day counts 0.5", "format" : "double", "type" : "number" }, "daysWorked" : { "description" : "Business dates with closed work in the period", "format" : "int32", "type" : "integer" }, "employeeId" : { "format" : "int32", "type" : "integer" }, "firstName" : { "type" : "string" }, "lastName" : { "type" : "string" }, "workSeconds" : { "description" : "Closed shifts' work in the period", "format" : "int64", "type" : "integer" } }, "type" : "object" }, "IntegrationInterval" : { "properties" : { "endedAt" : { "description" : "Absent while the stretch is open", "format" : "int32", "type" : "integer" }, "kind" : { "description" : "work, break, personal or business", "type" : "string" }, "seconds" : { "description" : "Absent while the stretch is open", "format" : "int32", "type" : "integer" }, "startedAt" : { "description" : "Epoch seconds, UTC", "format" : "int32", "type" : "integer" } }, "type" : "object" }, "IntegrationKeyInfo" : { "properties" : { "allInstitutions" : { "description" : "true = every institution, including ones created later; institutionIds is then empty", "type" : "boolean" }, "expiresAt" : { "description" : "Epoch seconds; absent when the key does not expire", "format" : "int32", "type" : "integer" }, "id" : { "format" : "int32", "type" : "integer" }, "institutionIds" : { "items" : { "format" : "int32", "type" : "integer" }, "type" : "array" }, "name" : { "type" : "string" }, "rateLimitPerMinute" : { "description" : "Requests per minute; also sent as X-RateLimit-Limit", "format" : "int32", "type" : "integer" }, "scopes" : { "description" : "Canonical scope strings, e.g. events:read", "items" : { "type" : "string" }, "type" : "array" } }, "type" : "object" }, "IntegrationMembership" : { "properties" : { "contractType" : { "type" : "string" }, "createdAt" : { "description" : "Epoch seconds, UTC", "format" : "int32", "type" : "integer" }, "endedOn" : { "format" : "date", "type" : "string" }, "hourlyRate" : { "description" : "Two decimals; absent when not set", "type" : "number" }, "institutionId" : { "format" : "int32", "type" : "integer" }, "startedOn" : { "format" : "date", "type" : "string" }, "status" : { "description" : "active or ended", "type" : "string" }, "updatedAt" : { "format" : "int32", "type" : "integer" } }, "type" : "object" }, "IntegrationMembershipCreateRequest" : { "properties" : { "contractType" : { "maxLength" : 50, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" }, "hourlyRate" : { "description" : "At least 0, at most two decimals", "minimum" : 0, "type" : "number" }, "institutionId" : { "format" : "int32", "type" : "integer" }, "startedOn" : { "description" : "ISO date", "format" : "date", "type" : "string" } }, "required" : [ "institutionId" ], "type" : "object" }, "IntegrationMembershipUpdateRequest" : { "properties" : { "contractType" : { "maxLength" : 50, "minLength" : 0, "pattern" : "(?s).*\\S.*", "type" : "string" }, "endedOn" : { "format" : "date", "type" : "string" }, "hourlyRate" : { "description" : "At least 0, at most two decimals", "minimum" : 0, "type" : "number" }, "startedOn" : { "format" : "date", "type" : "string" }, "status" : { "description" : "active or ended; ended needs an endedOn (in the request or already on the membership)", "pattern" : "active|ended", "type" : "string" } }, "type" : "object" }, "IntegrationPayrollReport" : { "properties" : { "institutionId" : { "format" : "int32", "type" : "integer" }, "month" : { "format" : "int32", "type" : "integer" }, "rows" : { "items" : { "$ref" : "#/components/schemas/IntegrationPayrollReportRow" }, "type" : "array" }, "totalWorkSeconds" : { "format" : "int64", "type" : "integer" }, "year" : { "format" : "int32", "type" : "integer" } }, "type" : "object" }, "IntegrationPayrollReportRow" : { "properties" : { "email" : { "description" : "Absent when the person has none", "type" : "string" }, "employeeId" : { "format" : "int32", "type" : "integer" }, "firstName" : { "type" : "string" }, "lastName" : { "type" : "string" }, "workSeconds" : { "description" : "The month's closed work, no lunch deducted", "format" : "int64", "type" : "integer" }, "workingDays" : { "description" : "Business dates with work in the month", "format" : "int32", "type" : "integer" } }, "type" : "object" }, "IntegrationSession" : { "properties" : { "anomalyCount" : { "format" : "int32", "type" : "integer" }, "breakSeconds" : { "format" : "int64", "type" : "integer" }, "businessDate" : { "description" : "The business date at the institution (local start time minus its day boundary), ISO date", "format" : "date", "type" : "string" }, "businessSeconds" : { "format" : "int64", "type" : "integer" }, "computedAt" : { "description" : "When the shift was last recomputed from its events, epoch seconds", "format" : "int32", "type" : "integer" }, "employeeId" : { "format" : "int32", "type" : "integer" }, "endedAt" : { "description" : "Absent unless a clock_out closed the shift", "format" : "int32", "type" : "integer" }, "id" : { "format" : "int64", "type" : "integer" }, "institutionId" : { "format" : "int32", "type" : "integer" }, "intervals" : { "items" : { "$ref" : "#/components/schemas/IntegrationInterval" }, "type" : "array" }, "personalSeconds" : { "format" : "int64", "type" : "integer" }, "startedAt" : { "description" : "Epoch seconds, UTC", "format" : "int32", "type" : "integer" }, "status" : { "description" : "in_progress, complete or incomplete (left open past the institution's maximum shift length)", "type" : "string" }, "workSeconds" : { "format" : "int64", "type" : "integer" } }, "type" : "object" }, "PaginatedResultIntegrationCard" : { "properties" : { "count" : { "format" : "int64", "type" : "integer" }, "list" : { "items" : { "$ref" : "#/components/schemas/IntegrationCard" }, "type" : "array" }, "page" : { "format" : "int32", "type" : "integer" }, "pageSize" : { "format" : "int32", "type" : "integer" }, "totalPages" : { "format" : "int32", "type" : "integer" } }, "type" : "object" }, "PaginatedResultIntegrationEmployee" : { "properties" : { "count" : { "format" : "int64", "type" : "integer" }, "list" : { "items" : { "$ref" : "#/components/schemas/IntegrationEmployee" }, "type" : "array" }, "page" : { "format" : "int32", "type" : "integer" }, "pageSize" : { "format" : "int32", "type" : "integer" }, "totalPages" : { "format" : "int32", "type" : "integer" } }, "type" : "object" }, "PaginatedResultIntegrationEvent" : { "properties" : { "count" : { "format" : "int64", "type" : "integer" }, "list" : { "items" : { "$ref" : "#/components/schemas/IntegrationEvent" }, "type" : "array" }, "page" : { "format" : "int32", "type" : "integer" }, "pageSize" : { "format" : "int32", "type" : "integer" }, "totalPages" : { "format" : "int32", "type" : "integer" } }, "type" : "object" }, "PaginatedResultIntegrationSession" : { "properties" : { "count" : { "format" : "int64", "type" : "integer" }, "list" : { "items" : { "$ref" : "#/components/schemas/IntegrationSession" }, "type" : "array" }, "page" : { "format" : "int32", "type" : "integer" }, "pageSize" : { "format" : "int32", "type" : "integer" }, "totalPages" : { "format" : "int32", "type" : "integer" } }, "type" : "object" } }, "securitySchemes" : { "integrationApiKey" : { "description" : "An API key your MASK administrator issues, a long random token that starts with tna_api_. Send it as Authorization: Bearer ", "scheme" : "bearer", "type" : "http" } } }, "externalDocs" : { "description" : "Guides and examples", "url" : "https://docs.mask.ba/api/" }, "info" : { "contact" : { "email" : "dev@mask.ba", "name" : "MASK", "url" : "https://docs.mask.ba/api/" }, "description" : "The integration API of MASK for payroll, HR, ERP and access-control systems: pull attendance, push employee master data and push clock events. Every request carries Authorization: Bearer , with an API key your MASK administrator issues. Guides, examples and the change policy: https://docs.mask.ba/api/", "title" : "MASK Integration API", "version" : "v1" }, "openapi" : "3.1.0", "paths" : { "/integration/cards" : { "get" : { "operationId" : "listCards", "parameters" : [ { "description" : "Only this person's cards; a person the key cannot see gives an empty list", "in" : "query", "name" : "employeeId", "required" : false, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "One of the key's institutions; omitted = all of them", "in" : "query", "name" : "institutionId", "required" : false, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "active | all (adds inactive and lost cards)", "in" : "query", "name" : "status", "required" : false, "schema" : { "default" : "active", "type" : "string" } }, { "description" : "1-based", "in" : "query", "name" : "page", "required" : false, "schema" : { "default" : 1, "format" : "int32", "type" : "integer" } }, { "description" : "1-200", "in" : "query", "name" : "pageSize", "required" : false, "schema" : { "default" : 50, "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaginatedResultIntegrationCard" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "cards:read" ] } ], "summary" : "The cards of the people of the key's institutions (or of one, or of one person), oldest first. 403 institution_not_allowed for an institutionId outside the key", "tags" : [ "Cards" ] } }, "/integration/employees" : { "get" : { "operationId" : "listEmployees", "parameters" : [ { "description" : "One of the key's institutions; omitted = all of them", "in" : "query", "name" : "institutionId", "required" : false, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "active | inactive | terminated | all", "in" : "query", "name" : "status", "required" : false, "schema" : { "default" : "all", "type" : "string" } }, { "description" : "1-based", "in" : "query", "name" : "page", "required" : false, "schema" : { "default" : 1, "format" : "int32", "type" : "integer" } }, { "description" : "1-200", "in" : "query", "name" : "pageSize", "required" : false, "schema" : { "default" : 50, "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaginatedResultIntegrationEmployee" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "employees:read" ] } ], "summary" : "The people of the key's institutions (or of one), oldest first, with their memberships there. 403 institution_not_allowed for an institutionId outside the key", "tags" : [ "Employees" ] }, "post" : { "operationId" : "createEmployee", "parameters" : [ { "description" : "Optional. 1 to 128 visible ASCII characters. A retry with the same key and request within 24 h gets the first reply back (Idempotent-Replayed: true) instead of writing again", "in" : "header", "name" : "Idempotency-Key", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEmployeeCreateRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEmployee" } } }, "description" : "The employee as the key sees it", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Conflict; code: conflict | idempotency_in_progress", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "422" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unprocessable Content; code: idempotency_mismatch", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "employees:write" ] } ], "summary" : "Create an active employee with at least one membership, each in an institution of the key", "tags" : [ "Employees" ] } }, "/integration/employees/{id}" : { "get" : { "operationId" : "getEmployee", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEmployee" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "employees:read" ] } ], "summary" : "One person with their memberships in the key's institutions; 404 when unknown or outside the key", "tags" : [ "Employees" ] }, "patch" : { "operationId" : "updateEmployee", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "Optional. 1 to 128 visible ASCII characters. A retry with the same key and request within 24 h gets the first reply back (Idempotent-Replayed: true) instead of writing again", "in" : "header", "name" : "Idempotency-Key", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEmployeeUpdateRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEmployee" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Conflict; code: conflict | idempotency_in_progress", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "422" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unprocessable Content; code: idempotency_mismatch", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "employees:write" ] } ], "summary" : "Change an employee's master data or status; every active membership of the person must lie in the key's institutions, and the status of a protected employee record cannot change", "tags" : [ "Employees" ] } }, "/integration/employees/{id}/memberships" : { "post" : { "operationId" : "addMembership", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "Optional. 1 to 128 visible ASCII characters. A retry with the same key and request within 24 h gets the first reply back (Idempotent-Replayed: true) instead of writing again", "in" : "header", "name" : "Idempotency-Key", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationMembershipCreateRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEmployee" } } }, "description" : "The employee as the key sees it", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Conflict; code: conflict | idempotency_in_progress", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "422" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unprocessable Content; code: idempotency_mismatch", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "employees:write" ] } ], "summary" : "Add a membership in an institution of the key (409 if the employee already has one there)", "tags" : [ "Employees" ] } }, "/integration/employees/{id}/memberships/{institutionId}" : { "patch" : { "operationId" : "updateMembership", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } }, { "in" : "path", "name" : "institutionId", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "Optional. 1 to 128 visible ASCII characters. A retry with the same key and request within 24 h gets the first reply back (Idempotent-Replayed: true) instead of writing again", "in" : "header", "name" : "Idempotency-Key", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationMembershipUpdateRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEmployee" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Conflict; code: conflict | idempotency_in_progress", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "422" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unprocessable Content; code: idempotency_mismatch", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "employees:write" ] } ], "summary" : "Change a membership, or end it with {\"status\":\"ended\",\"endedOn\":\"…\"}", "tags" : [ "Employees" ] } }, "/integration/event-codes" : { "get" : { "operationId" : "listEventCodes", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/IntegrationEventCode" }, "type" : "array" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ ] } ], "summary" : "The event catalog: every code with what it does to a shift", "tags" : [ "Reference data" ] } }, "/integration/events" : { "get" : { "operationId" : "listEvents", "parameters" : [ { "description" : "First business date, ISO yyyy-MM-dd, from 2000-01-01 to 2037-12-31", "in" : "query", "name" : "from", "required" : true, "schema" : { "format" : "date", "type" : "string" } }, { "description" : "Last business date, ISO yyyy-MM-dd, from 2000-01-01 to 2037-12-31; from..to spans at most 31 days, both included", "in" : "query", "name" : "to", "required" : true, "schema" : { "format" : "date", "type" : "string" } }, { "description" : "One of the key's institutions; omitted = all of them", "in" : "query", "name" : "institutionId", "required" : false, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "Only this person's events; a person the key cannot see gives an empty list", "in" : "query", "name" : "employeeId", "required" : false, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "active | all (adds corrected and voided rows, so a mirror can apply corrections)", "in" : "query", "name" : "status", "required" : false, "schema" : { "default" : "active", "type" : "string" } }, { "description" : "1-based", "in" : "query", "name" : "page", "required" : false, "schema" : { "default" : 1, "format" : "int32", "type" : "integer" } }, { "description" : "1-200", "in" : "query", "name" : "pageSize", "required" : false, "schema" : { "default" : 50, "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaginatedResultIntegrationEvent" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "events:read" ] } ], "summary" : "Clock events between two business dates (inclusive, at most 31 days; each institution's own timezone and day boundary), oldest first (eventTime, id). 403 institution_not_allowed for an institutionId outside the key", "tags" : [ "Events" ] }, "post" : { "operationId" : "createEvent", "parameters" : [ { "description" : "Required. 1 to 128 visible ASCII characters. A retry with the same key and request within 24 h gets the first reply back (Idempotent-Replayed: true) instead of writing again", "in" : "header", "name" : "Idempotency-Key", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEventCreateRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEvent" } } }, "description" : "The event as stored", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Conflict; code: conflict | idempotency_in_progress", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "422" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unprocessable Content; code: idempotency_mismatch", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "events:write" ] } ], "summary" : "Record a clock event (source api) for an employee at an institution of the key; the Idempotency-Key header is required", "tags" : [ "Events" ] } }, "/integration/events/{id}" : { "delete" : { "operationId" : "voidEvent", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "format" : "int64", "type" : "integer" } }, { "description" : "Optional. 1 to 128 visible ASCII characters. A retry with the same key and request within 24 h gets the first reply back (Idempotent-Replayed: true) instead of writing again", "in" : "header", "name" : "Idempotency-Key", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "204" : { "description" : "Voided", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Conflict; code: conflict | idempotency_in_progress", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "422" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unprocessable Content; code: idempotency_mismatch", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "events:write" ] } ], "summary" : "Void an event the integration API created", "tags" : [ "Events" ] }, "get" : { "operationId" : "getEvent", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "format" : "int64", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEvent" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "events:read" ] } ], "summary" : "One clock event, whatever its status; 404 when unknown or outside the key's institutions", "tags" : [ "Events" ] }, "patch" : { "operationId" : "correctEvent", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "format" : "int64", "type" : "integer" } }, { "description" : "Optional. 1 to 128 visible ASCII characters. A retry with the same key and request within 24 h gets the first reply back (Idempotent-Replayed: true) instead of writing again", "in" : "header", "name" : "Idempotency-Key", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEventCorrectRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEvent" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Conflict; code: conflict | idempotency_in_progress", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "422" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unprocessable Content; code: idempotency_mismatch", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "events:write" ] } ], "summary" : "Correct an event the integration API created: a new api event replaces it (correctsEventId = id), the original becomes corrected", "tags" : [ "Events" ] } }, "/integration/institutions" : { "get" : { "operationId" : "listInstitutions", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/IntegrationInstitution" }, "type" : "array" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ ] } ], "summary" : "The institutions the key covers, by id, with their timezone, day boundary, status and enabled event codes", "tags" : [ "Reference data" ] } }, "/integration/institutions/{id}" : { "get" : { "operationId" : "getInstitution", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationInstitution" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ ] } ], "summary" : "One institution the key covers; 404 for any other", "tags" : [ "Reference data" ] } }, "/integration/key" : { "get" : { "operationId" : "getKey", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationKeyInfo" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ ] } ], "summary" : "The calling key's own name, scopes, institutions, rate limit and expiry", "tags" : [ "Reference data" ] } }, "/integration/reports/employee" : { "get" : { "operationId" : "getEmployeeReport", "parameters" : [ { "description" : "A person the key can see (404 otherwise)", "in" : "query", "name" : "employeeId", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "First business date, ISO yyyy-MM-dd, from 2000-01-01 to 2037-12-31", "in" : "query", "name" : "from", "required" : true, "schema" : { "format" : "date", "type" : "string" } }, { "description" : "Last business date, ISO yyyy-MM-dd, from 2000-01-01 to 2037-12-31; from..to spans at most 366 days, both included", "in" : "query", "name" : "to", "required" : true, "schema" : { "format" : "date", "type" : "string" } }, { "description" : "One of the key's institutions; omitted = all of them", "in" : "query", "name" : "institutionId", "required" : false, "schema" : { "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationEmployeeReport" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "reports:read" ] } ], "summary" : "One person's shifts in the key's institutions (or one of them) over a period, with the work of each. 404 for a person outside the key, 403 institution_not_allowed for an institutionId outside it", "tags" : [ "Reports" ] } }, "/integration/reports/institution" : { "get" : { "operationId" : "getInstitutionReport", "parameters" : [ { "description" : "One of the key's institutions (403 institution_not_allowed otherwise)", "in" : "query", "name" : "institutionId", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "First business date, ISO yyyy-MM-dd, from 2000-01-01 to 2037-12-31", "in" : "query", "name" : "from", "required" : true, "schema" : { "format" : "date", "type" : "string" } }, { "description" : "Last business date, ISO yyyy-MM-dd, from 2000-01-01 to 2037-12-31; from..to spans at most 366 days, both included", "in" : "query", "name" : "to", "required" : true, "schema" : { "format" : "date", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationInstitutionReport" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "reports:read" ] } ], "summary" : "One institution over a period: days worked, absence days and work per person. 403 institution_not_allowed for an institution outside the key", "tags" : [ "Reports" ] } }, "/integration/reports/payroll" : { "get" : { "operationId" : "getPayrollReport", "parameters" : [ { "description" : "One of the key's institutions (403 institution_not_allowed otherwise)", "in" : "query", "name" : "institutionId", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "2000-2037: every day of the month must lie from 2000-01-01 to 2037-12-31", "in" : "query", "name" : "year", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "1-12", "in" : "query", "name" : "month", "required" : true, "schema" : { "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationPayrollReport" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "reports:read" ] } ], "summary" : "One calendar month at one institution: working days and work per person (the Abacus payroll numbers, no lunch deducted). 403 institution_not_allowed for an institution outside the key", "tags" : [ "Reports" ] } }, "/integration/sessions" : { "get" : { "operationId" : "listSessions", "parameters" : [ { "description" : "First business date, ISO yyyy-MM-dd, from 2000-01-01 to 2037-12-31", "in" : "query", "name" : "from", "required" : true, "schema" : { "format" : "date", "type" : "string" } }, { "description" : "Last business date, ISO yyyy-MM-dd, from 2000-01-01 to 2037-12-31; from..to spans at most 92 days, both included", "in" : "query", "name" : "to", "required" : true, "schema" : { "format" : "date", "type" : "string" } }, { "description" : "One of the key's institutions; omitted = all of them", "in" : "query", "name" : "institutionId", "required" : false, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "Only this person's shifts; a person the key cannot see gives an empty list", "in" : "query", "name" : "employeeId", "required" : false, "schema" : { "format" : "int32", "type" : "integer" } }, { "description" : "all | in_progress | complete | incomplete", "in" : "query", "name" : "status", "required" : false, "schema" : { "default" : "all", "type" : "string" } }, { "description" : "1-based", "in" : "query", "name" : "page", "required" : false, "schema" : { "default" : 1, "format" : "int32", "type" : "integer" } }, { "description" : "1-200", "in" : "query", "name" : "pageSize", "required" : false, "schema" : { "default" : 50, "format" : "int32", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaginatedResultIntegrationSession" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "sessions:read" ] } ], "summary" : "Shifts by business date (inclusive, at most 92 days), oldest first (businessDate, startedAt, id), with intervals and totals. 403 institution_not_allowed for an institutionId outside the key", "tags" : [ "Sessions" ] } }, "/integration/sessions/{id}" : { "get" : { "operationId" : "getSession", "parameters" : [ { "in" : "path", "name" : "id", "required" : true, "schema" : { "format" : "int64", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationSession" } } }, "description" : "OK", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Bad Request; code: validation_failed | idempotency_required | event_too_old", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Unauthorized; code: invalid_api_key | key_expired | key_revoked", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Forbidden; code: ip_not_allowed | scope_missing | institution_not_allowed | not_api_event | admin_linked_employee", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Not Found; code: not_found", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "429" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Too Many Requests; code: rate_limited", "headers" : { "Retry-After" : { "$ref" : "#/components/headers/Retry-After" }, "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Internal Server Error; code: internal_error", "headers" : { "X-RateLimit-Limit" : { "$ref" : "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining" : { "$ref" : "#/components/headers/X-RateLimit-Remaining" }, "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } }, "503" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IntegrationError" } } }, "description" : "Service Unavailable; code: unavailable", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/X-Request-Id" } } } }, "security" : [ { "integrationApiKey" : [ "sessions:read" ] } ], "summary" : "One shift with its intervals and totals; 404 when unknown or outside the key's institutions", "tags" : [ "Sessions" ] } } }, "security" : [ { "integrationApiKey" : [ ] } ], "servers" : [ { "description" : "Your MASK system", "url" : "https://{host}/api/v1", "variables" : { "host" : { "default" : "mask.example.com", "description" : "The address of your MASK system; your administrator gives it to you" } } } ], "tags" : [ { "description" : "The calling key, its institutions and the event catalog: what you need to read everything else. Any valid key", "name" : "Reference data" }, { "description" : "People and their memberships, one per institution they work at, with contract type, hourly rate and dates. Reads need employees:read, writes employees:write", "name" : "Employees" }, { "description" : "The RFID cards of the people the key can see. Cards are issued in MASK, not through the API. Needs cards:read", "name" : "Cards" }, { "description" : "Clock events from the terminals, from administrators and from API keys, with their corrections and voids. Reads need events:read, writes events:write", "name" : "Events" }, { "description" : "Shifts derived from the events, from a clock-in to the next clock-out, with work, break, personal and business time. Needs sessions:read", "name" : "Sessions" }, { "description" : "Totals per institution over a period, per payroll month and per person. Needs reports:read", "name" : "Reports" } ] }