დეველოპერის გზამკვლევი გზამკვლევი 1 / 5

HourSquare API — პირველი ნაბიჯები

HourSquare API თქვენს პროგრამულ უზრუნველყოფას საშუალებას აძლევს, ესაუბროს თქვენი კომპანიის ანგარიშს: დროის აღრიცხვის მოწყობილობა, რომელიც შემოსვლა-გასვლას აფიქსირებს; სკრიპტი, რომელიც საათებს ადარებს; ინსტრუმენტი, რომელიც თანამშრომლების სიას კითხულობს. ეს არის ჩვეულებრივი HTTPS და JSON API ერთ ჰოსტზე, https://api.hoursquare.com, და ყველა მოთხოვნა კომპანიის API გასაღებით სრულდება.

რა არის API

ყველა საჯარო ენდპოინტი განთავსებულია https://api.hoursquare.com/api/public/v1 მისამართზე. მთელი პროდუქტისთვის ერთი ჰოსტია, ამიტომ მისამართი, რომელთანაც ინტეგრაციას აკეთებთ, HourSquare-ის ზრდასთან ერთად არ იცვლება. მოთხოვნები და პასუხები JSON ფორმატშია; შეცდომები ბრუნდება როგორც application/problem+json სტაბილური error სტრიქონით, რომელიც საიმედოობის გზამკვლევშია აღწერილი.

გასაღები კომპანიას ეკუთვნის და არა იმ ადამიანს, ვინც ის შექმნა. თუ ეს ადამიანი კომპანიას დატოვებს, გასაღები მუშაობას განაგრძობს, სანამ ვინმე არ გააუქმებს, და ყველაფერი, რასაც გასაღები აკეთებს, ამ გასაღების სახელზე ფიქსირდება.

ვის შეუძლია გასაღების შექმნა

ადმინისტრატორი, რომელსაც API გასაღებების მართვის უფლება აქვს, ხსნის Hub › პარამეტრები › API და ინტეგრაციები გვერდს და აჭერს „შექმნას“. გასაღებს ენიჭება სახელი, ერთი ან მეტი წვდომის არე (რისი გაკეთება შეუძლია), სურვილისამებრ ვადის გასვლის თარიღი და, ასევე სურვილისამებრ, დაშვებული IP დიაპაზონების სია.

გასაღებს მხოლოდ ის წვდომის არეები ენიჭება, რომელთა მინიჭების უფლება მის შემქმნელს აქვს. მანქანური არეები, მაგალითად attendance.record, ყოველთვის ხელმისაწვდომია; ადამიანური არეები, მაგალითად employees.read, მოითხოვს, რომ შემქმნელს შესაბამისი უფლება ჰქონდეს ან სუპერადმინისტრატორი იყოს.

ორი მნიშვნელობა, რომელსაც იღებთ

გასაღების შექმნისას ორი მნიშვნელობა ჩანს, მხოლოდ ერთხელ:

Client ID — hsq_k7Qm3xZp. საიდუმლო არ არის. გასაღებების სიაშიც ჩანს, ამიტომ მისი ხელახლა ნახვა ყოველთვის შეგიძლიათ.
Client secret — სრული გასაღები, hsq_k7Qm3xZp_…. ჩანს მხოლოდ ერთხელ. HourSquare მხოლოდ მის ჰეშს ინახავს; თუ დაკარგავთ, გააკეთეთ გასაღების როტაცია და შეინახეთ ახალი.

ტოკენის მიღება

API იყენებს OAuth 2.0-ის client_credentials ნაკადს. გაცვალეთ გასაღები მოკლევადიან წვდომის ტოკენზე ტოკენის ენდპოინტზე, შემდეგ კი ეს ტოკენი ყველა მოთხოვნას Bearer ჰედერით დაურთეთ. ქვემოთ მოცემული ორი ფორმა ერთმანეთის ტოლფასია; $HSQ_KEY ცვლადში საიდუმლო გასაღები ინახება.

HTTP Basic-ით

curl -s -X POST https://api.hoursquare.com/api/public/v1/oauth/token \
  -u "hsq_k7Qm3xZp:$HSQ_KEY" \
  -d grant_type=client_credentials

ფორმის ველებით

curl -s -X POST https://api.hoursquare.com/api/public/v1/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d client_id=hsq_k7Qm3xZp \
  --data-urlencode "client_secret=$HSQ_KEY"

პასუხი

{
  "access_token": "eyJhbGciOiJIUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 900
}

ტოკენი 15 წუთი მოქმედებს (expires_in წამებშია). შეინახეთ ის მეხსიერებაში და გამოიყენეთ, სანამ ვადა არ გაუვა ან რომელიმე მოთხოვნა 401-ს არ დააბრუნებს; შემდეგ მოითხოვეთ ახალი. განახლების ტოკენი არ არსებობს: სწორედ გასაღებია ის, რითაც ტოკენს ანახლებთ. ტოკენის ენდპოინტი თითო გასაღებზე წუთში 60 მოთხოვნას იღებს, რაც ქეშირების პირობებში სავსებით საკმარისია.

ტოკენის ენდპოინტი არასწორად შედგენილ მოთხოვნაზე პასუხობს 400 invalid_request ან unsupported_grant_type კოდით, ხოლო არასწორ, ვადაგასულ ან გაუქმებულ გასაღებზე — 401 invalid_client კოდით.

თქვენი პირველი მოთხოვნა

GET /api/public/v1/me ნებისმიერ მოქმედ ტოკენს პასუხობს და გეუბნებათ, რისი უფლება აქვს ტოკენს, როდის გასდის ვადა და რა ლიმიტი გაქვთ.

curl -s https://api.hoursquare.com/api/public/v1/me \
  -H "Authorization: Bearer $TOKEN"

პასუხი

{
  "principal": "api_key",
  "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "publicId": "hsq_k7Qm3xZp",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "scopes": [
    {
      "id": "attendance.record",
      "permission": 86,
      "label": "Record clock events and completed shifts; set employee external ids"
    }
  ],
  "tokenExpiresAt": "2026-09-15T10:15:00+00:00",
  "rateLimit": { "requestsPerMinute": 300, "tokenRequestsPerMinute": 60 },
  "dryRunHeader": "X-HourSquare-Dry-Run"
}

ყველა პასუხს თან ახლავს RateLimit ჰედერებიც, ამიტომ დარჩენილი ლიმიტის სანახავად ცალკე მოთხოვნა არ გჭირდებათ.

გაეცანით საცნობაროს

ინტერაქტიული საცნობარო მისამართზე api.hoursquare.com/docs ყველა ენდპოინტს მოთხოვნისა და პასუხის სქემებით ჩამოთვლის და API-ს პირდაპირ გვერდიდან გამოძახების საშუალებას გაძლევთ. ჩასვით Client ID და საიდუმლო მის დაკავშირების პანელში (ტოკენი მხოლოდ მეხსიერებაში რჩება, საცავში არასდროს იწერება) და სცადეთ მოთხოვნა. ჩაწერის ოპერაციები იქ ნაგულისხმევად X-HourSquare-Dry-Run: true ჰედერით იგზავნება, ამიტომ არაფერი ჩაიწერება, სანამ თავად არ გამორთავთ.

შემდეგი ნაბიჯი: ავთენტიფიკაცია და წვდომის არეები, შემდეგ კი დროის აღრიცხვის გზამკვლევი.

შემდეგი გზამკვლევიავთენტიფიკაცია და წვდომის არეები