Beranda>Terkait pemrograman>Kode sumber lainnya
Unduh

API Publik Masuk DfE

API bagi konsumen eksternal untuk berinteraksi dengan login DfE

Anda perlu mengautentikasi dengan API ini

Untuk menggunakan salah satu API di bawah ini, Anda perlu menyediakan token Pembawa di header permintaan, token pembawa ini hanyalah JWT (lihat https://jwt.io) dengan payload sederhana yang ditandatangani menggunakan rahasia yang hanya DfE Masuk dan Anda tahu.

Anda harus membuat JWT saat digunakan dalam aplikasi panggilan Anda menggunakan perpustakaan JWT standar yang disertakan dengan teknologi pilihan Anda.

Badan token akan memerlukan penerbit (ID klien layanan Anda) dan audiens sebagai berikut: 

{
  "iss": "REPLACE_WITH_YOUR_CLIENT_ID",
  "aud": "signin.education.gov.uk"
}

Token harus ditandatangani menggunakan algoritma HS256 dengan API_SECRET Anda. Pada titik integrasi dengan DfE Sign-in, Anda akan diberikan API_SECRET (jangan salah mengira CLIENT_SECRET Anda), jika Anda tidak memilikinya, hubungi tim DfE Sign-in dan kami akan membuatkan satu lagi untuk Anda (ini adalah spesifik layanan/lingkungan.)

Menggunakan Tukang Pos untuk mengevaluasi dan menguji API

Sekilas tentang Tukang Pos

Tukang pos adalah alat platform API yang digunakan untuk membangun dan mengeksekusi API. Tukang pos menyederhanakan setiap langkah siklus hidup API dan digunakan secara luas dalam pengembangan dan dokumentasi DfE Sign-in Public API.

Serangkaian koleksi Postman dan lingkungan eksekusi terkait telah disediakan untuk membantu Anda mempelajari, menguji, dan men-debug integrasi Anda dengan platform DfE Sign-in melalui API Publik.

Memulai Postman dan rangkaian koleksi DfE Sign-in

Alat platform Postman API tersedia sebagai klien desktop, aplikasi web yang dihosting, dan antarmuka baris perintah (CLI) di https://www.postman.com/api-platform/api-client/.

Koleksi dan lingkungan DfE Sign-in Public API Postman tersedia di https://github.com/DFE-Digital/login.dfe.public-api/tree/develop/Postman/.

Undang Pengguna

Sebagai layanan yang terintegrasi dengan DfE Sign-in, Anda dapat menggunakan API untuk mengundang pengguna ke layanan.

Permintaannya sepertinya 

POST https://environment-url/services/{service-id}/invitations
Authorization: bearer {jwt-token}

{
    "sourceId": "user_id_in_your_service",
	"given_name": "John",
	"family_name": "Smith",
	"email": "[email protected]",
	"callback": "https://me.service.url/users/signup-complete"
}

Item data variabelnya adalah:

Nama Lokasi Diperlukan Keterangan
id layanan URL Y Pengidentifikasi Masuk DfE untuk layanan yang Anda undang ke pengguna
jwt-token Tajuk Y Token JWT untuk otorisasi harus ditandatangani menggunakan rahasia API Anda, yang akan diberikan kepada Anda
sourceId Tubuh Y Pengidentifikasi pengguna di sistem Anda. Akan disertakan dalam respons saluran belakang
nama_yang diberikan Tubuh Y Nama yang diberikan pengguna
nama_keluarga Tubuh Y Nama keluarga pengguna
e-mail Tubuh Y Alamat email pengguna. Ini juga merupakan pengidentifikasi unik pengguna di DfE Sign-in
organisasi Tubuh
 Pengidentifikasi Masuk DfE yang harus dikaitkan dengan pengguna
panggilan balik Tubuh
 URL tujuan pengiriman respons saluran belakang. Lihat detail respons saluran belakang di bawah
pengalihan pengguna Tubuh
 URL tempat pengguna, jika melakukan orientasi, harus dikembalikan setelah selesai. Jika dihilangkan, pengalihan default untuk klien Anda akan digunakan
mengundangSubjectOverride Tubuh
 Mengganti subjek email undangan
undangBodyOverride Tubuh
 Menggantikan isi email undangan

Kode respons yang mungkin adalah:

Kode Status HTTP Alasan
202 Permintaan Anda telah diterima
400 Permintaan Anda tidak valid. Rincian tambahan akan diberikan di badan respons
401 JWT Anda hilang atau tidak valid.
404 Id layanan di uri tidak ada
500 Terjadi kesalahan pada server. Harap pastikan bahwa rahasia seperti rahasia, kunci API, atau token dikonfigurasi dengan benar. Jika masalah masih berlanjut, harap hubungi tim dukungan untuk mendapatkan bantuan

Ketika permintaan dibuat, pengguna mungkin ada atau tidak ada dalam sistem; dan mungkin atau mungkin tidak meminta pemetaan organisasi dan layanan yang diinginkan. Karena alasan ini, semua detail pengguna dikirim melalui respons saluran belakang. Hal ini dapat terjadi segera jika pengguna ditemukan (melalui email) di DfE Sign-in; atau setelah pengguna menerima email undangan yang akan dikirimkan kepada mereka.

Respons saluran belakang terlihat seperti: 

POST https://callback.url/from/request
Authorization: bearer {jwt-token}

{
    "sub": "some-uuid",
    "sourceId: "source-id-from-request"
}

Item data dalam permintaan adalah:

Nama Lokasi Keterangan
jwt-token Tajuk Token jwt, ditandatangani dengan rahasia yang sama dengan permintaan
sub Tubuh Pengidentifikasi masuk DfE untuk pengguna. Hal ini tidak akan berubah dan akan dimasukkan dalam tanggapan OIDC sebagai subklaim
sourceId Tubuh sourceId yang digunakan dalam permintaan asli

Kelola pengumuman

Pengumuman dapat dipublikasikan dan tidak dipublikasikan untuk suatu organisasi.

Pengumuman dapat dipublikasikan oleh: 

POST https://environment-url/organisations/announcements
Authorization: bearer {jwt-token}

{
    "messageId": "your-unique-idenitifer",
	"urn": "12345",
	"type": 1,
	"title": "Title of announcement",
	"summary": "summary of announcement",
	"body": "body of announcement",
	"publishedAt": "2019-01-31T20:30:40Z",
	"expiresAt": "2020-01-31T20:30:40Z"
}

Struktur pengumuman adalah sebagai berikut:

Atribut Diperlukan Keterangan Jenis
pesanId Y Pengidentifikasi untuk pesan di sistem asal. Harus unik UUID
pasu Y (Atau uid) Guci Pendirian numerik
uid Y (Atau guci) Grup UID UUID
jenis Y Kode tipe numerik pesan (lihat di bawah) Bilangan bulat
judul Y Judul pengumuman. Batas maksimal karakter adalah 255 Teks atau HTML
ringkasan Y Ringkasan pengumuman. Batas karakter maksimal 340 Teks atau HTML
tubuh Y Isi pengumuman. Batas karakter maksimal 5000 Teks atau HTML
diterbitkanDi Y Tanggal/waktu pengumuman diterbitkan pada ISO8601
kadaluarsaPada
 Tanggal/waktu pengumuman akan berakhir pada ISO8601

kode respons yang mungkin adalah:

Kode Status HTTP Alasan
202 Permintaan Anda telah diterima
400 Permintaan Anda tidak valid. Rincian tambahan akan diberikan di badan respons
401 JWT Anda hilang atau tidak valid.
500 Terjadi kesalahan pada server. Harap pastikan bahwa rahasia seperti rahasia, kunci API, atau token dikonfigurasi dengan benar. Jika masalah masih berlanjut, harap hubungi tim dukungan untuk mendapatkan bantuan

Jenis pengumuman yang sah adalah:

kode arti
1 Peringatan tentang rekor pendirian
2 Masalah dengan catatan pendirian
4 Peringatan tentang catatan tata kelola
5 Masalah dengan catatan tata kelola

Pengumuman selanjutnya dapat dibatalkan publikasinya oleh: 

DELETE https://environment-url/organisations/announcements/your-unique-idenitifer
Authorization: bearer {jwt-token}

Di mana your-unique-idenitifer adalah messageId yang dikirim saat memublikasikan pesan.

Kode respons yang mungkin adalah:

Kode Status HTTP Alasan
204 Pengumuman belum dipublikasikan
401 JWT Anda hilang atau tidak valid.
404 Id pesan di uri tidak ada
500 Terjadi kesalahan pada server. Harap pastikan bahwa rahasia seperti rahasia, kunci API, atau token dikonfigurasi dengan benar. Jika masalah masih berlanjut, harap hubungi tim dukungan untuk mendapatkan bantuan

Buat aplikasi anak

Jika aplikasi Anda telah diaktifkan, Anda dapat membuat aplikasi anak melalui API. Aplikasi turunan ini dimaksudkan untuk digunakan ketika Anda memiliki aplikasi pihak ketiga yang akan menggunakan alur persetujuan OIDC untuk memungkinkan aplikasi tersebut memanggil API dalam aplikasi Anda dalam konteks pengguna.

Aplikasi anak dapat dibuat dengan: 

POST https://environment-url/services
Authorization: bearer {jwt-token}

{
	"name": "The display name of the application",
	"description": "A description of what the application does",
	"consentTitle": "Override for the content at the top of the Consent Screen",
	"consentBody": "Override for the content of the Consent Screen",
	"redirectUris": [
	    "https://endpoint.one/auth/cb",
	    "https://endpoint.two/login/callback"
	]
}

Catatan tentang Penggantian Template Persetujuan
Dua parameter memungkinkan untuk mengesampingkan konten yang ditampilkan kepada pengguna di Layar Persetujuan, judul dan isi (segala sesuatunya statis sesuai desain formulir saat ini). Nilai override adalah string yang memiliki dua nilai dinamis (opsional). misalnya consentTitle="Do you want to allow {{applicationName}} to send data to us for {{roleScope}}"

Struktur aplikasi adalah sebagai berikut:

Atribut Diperlukan Keterangan
nama Y Nama yang ramah pengguna untuk aplikasi tersebut. Ini akan digunakan saat meminta persetujuan pengguna
keterangan N Deskripsi aplikasi
redirectUris Y Serangkaian uris pengalihan yang dapat digunakan selama alur masuk/persetujuan OIDC

Kode respons yang mungkin adalah:

Kode Status HTTP Alasan
201 Aplikasi anak Anda telah dibuat
400 Permintaan Anda tidak valid. Rincian tambahan akan diberikan di badan tanggapan
403 Aplikasi Anda tidak memiliki izin untuk membuat aplikasi anak

Setelah berhasil membuat aplikasi anak, Anda akan menerima respons seperti: 

{
	"name": "The display name of the application",
	"description": "A description of what the application does",
	"clientId": "child-application-clientid",
	"clientSecret": "child-application-clientsecret",
	"redirectUris": [
	    "https://endpoint.one/auth/cb",
	    "https://endpoint.two/login/callback"
	]
}

name , description , dan redirectUris adalah konfirmasi atas apa yang diterima dari permintaan Anda. clientId dan clientSecret adalah aplikasi anak yang perlu digunakan saat melakukan proses OIDC. Anda juga memerlukan clientId untuk pengelolaan aplikasi selanjutnya.

Jika rahasia aplikasi anak disusupi, Anda dapat meminta agar rahasia tersebut dibuat ulang dengan: 

POST https://environment-url/services/client-id-of-child-application/regenerate-secret
Authorization: bearer {jwt-token}

Kode respons yang mungkin adalah:

Kode Status HTTP Alasan
200 Rahasia telah dibuat ulang
403 ID klien yang ditentukan bukan merupakan turunan dari aplikasi Anda
404 Tidak ada aplikasi yang dapat ditemukan dengan id klien yang ditentukan

Setelah regenerasi rahasia berhasil, Anda akan menerima respons seperti: 

{
    "clientSecret": "regenerated-client-secret"
}

Hibah dan Token aplikasi anak

Aplikasi anak mengikuti alur persetujuan eksplisit yang pada akhirnya menghasilkan kode Otorisasi (Hibah) yang dapat ditukar dengan Token Akses yang berumur pendek dan Token Refresh yang berumur lebih panjang, untuk memungkinkan pemilik aplikasi anak mengelola siklus hidup token yang diterbitkan yang kami sediakan. api yang nyaman untuk mencantumkan masalah hibah dan token untuk aplikasi anak yang dikelola.

Token ini kemudian dapat diperiksa dan dicabut menggunakan titik akhir koneksi id terbuka standar (intropeksi dan pencabutan).

Untuk mendapatkan daftar hibah untuk layanan anak tertentu: 

GET https://environment-url/services/{service-id}/grants

Untuk mendapatkan daftar token yang diterbitkan untuk hibah layanan anak tertentu: 

GET https://environment-url/services/{service-id}/grants/{grant-id}/tokens

Dapatkan akses pengguna ke layanan

Anda dapat menggunakan API ini untuk mendapatkan akses pengguna ke layanan organisasi. Permintaannya sepertinya 

GET https://environment-url/services/{service-id}/organisations/{organisation-id}/users/{user-id}
Authorization: bearer {jwt-token}

Item data variabelnya adalah:

Nama Lokasi Diperlukan Keterangan
id layanan URL Y Pengidentifikasi Masuk DfE untuk layanan
organisasi-id URL Y Pengidentifikasi Masuk DfE untuk organisasi
id pengguna URL Y Pengidentifikasi Masuk DfE untuk pengguna
jwt-token Tajuk Y Token JWT untuk otorisasi harus ditandatangani menggunakan rahasia API Anda, yang akan diberikan kepada Anda

Ini akan mengembalikan respons dalam format berikut 

{
    "userId": "user-id",
    "serviceId": "service-id",
    "organisationId": "organisation-id",
    "roles": [
        {
            "id": "role-id",
            "name": "The name of the role",
            "code": "The code of the role",
            "numericId": "9999",
            "status": {
                "id": 1
            }
        }
    ],
    "identifiers": [
        {
            "key": "identifier-key",
            "value": "identifier-value"
        }
    ]
}

Catatan: Jika Pengguna tidak memiliki Layanan yang ditentukan atau tidak tercantum dalam Organisasi, ia akan mengembalikan kode status 404 (Tidak Ditemukan) .

Dapatkan organisasi untuk pengguna

Anda dapat menggunakan API ini untuk mengaitkan organisasi dengan pengguna. Seperti apa permintaannya 

GET https://environment-url/users/{user-id}/organisations
Authorization: bearer {jwt-token}

Item data variabelnya adalah:

Nama Lokasi Diperlukan Keterangan
id pengguna URL Y Pengidentifikasi Masuk DfE untuk pengguna
jwt-token Tajuk Y Token JWT untuk otorisasi harus ditandatangani menggunakan rahasia API Anda, yang akan diberikan kepada Anda

Ini akan mengembalikan respons dalam format berikut 

[
    {
        "id": "org-id",
        "name": "Organisation name",
        "category": {
            "id": "004",
            "name": "Early Year Setting"
        },
        "urn": "org-urn",
        "uid": null,
        "ukprn": null,
        "establishmentNumber": null,
        "status": {
            "id": 1,
            "name": "Open"
        },
        "closedOn": null,
        "address": null,
        "telephone": null,
        "statutoryLowAge": null,
        "statutoryHighAge": null,
        "legacyId": "legacy-id",
        "companyRegistrationNumber": null
    },
]

Dapatkan peran untuk layanan

Anda dapat menggunakan titik akhir API ini untuk mendapatkan peran yang terkait dengan layanan Anda, atau salah satu layanan anak Anda. Permintaannya terlihat seperti: 

GET https://environment-url/services/{client-id}/roles
Authorization: bearer {jwt-token}

Item data variabelnya adalah:

Nama Lokasi Diperlukan Keterangan
id klien URL Y Pengidentifikasi klien Masuk DfE untuk layanan
jwt-token Tajuk Y Token JWT untuk otorisasi harus ditandatangani menggunakan rahasia API Anda, yang akan diberikan kepada Anda

Kode respons yang mungkin adalah:

Kode Status HTTP Alasan
200 Daftar peran (mungkin kosong) telah berhasil diambil untuk ID klien yang diminta.
403 ID klien yang ditentukan bukanlah layanan Anda, atau turunan dari layanan Anda.
404 Tidak ada layanan yang dapat ditemukan dengan ID klien yang ditentukan.

Ini akan mengembalikan respons dalam format berikut: 

[
    {
        "name": "Role 1 Name",
        "code": "Role1Code",
        "status": "Active"
    },
    {
        "name": "Role 2 Name",
        "code": "Role2Code",
        "status": "Inactive"
    }
]

atau yang berikut ini jika tidak ditemukan peran: 

[]

Dapatkan organisasi untuk pengguna termasuk atribut organisasi Profil Penyedia

Anda dapat menggunakan API ini untuk mengaitkan organisasi dengan pengguna. Seperti apa permintaannya 

GET https://environment-url/users/{user-id}/v2/organisations
Authorization: bearer {jwt-token}

Item data variabelnya adalah:

Nama Lokasi Diperlukan Keterangan
id pengguna URL Y Pengidentifikasi Masuk DfE untuk pengguna
jwt-token Tajuk Y Token JWT untuk otorisasi harus ditandatangani menggunakan rahasia API Anda, yang akan diberikan kepada Anda

Ini akan mengembalikan respons dalam format berikut 

[
    {
        "id": "org-id",
        "name": "Organisation name",
        "category": {
            "id": "001",
            "name": "Establishment"
        },
        "urn": null,
        "uid": null,
        "upin": "111111",
        "ukprn": "21133510",
        "establishmentNumber": null,
        "status": {
            "id": 1,
            "name": "Open"
        },
        "closedOn": null,
        "address": "Organisation address",
        "telephone": null,
        "statutoryLowAge": null,
        "statutoryHighAge": null,
        "legacyId": "1111",
        "companyRegistrationNumber": null,
        "DistrictAdministrativeCode": null,
        "DistrictAdministrative_code": null,
        "providerTypeName": "Commercial and Charitable Provider",
        "ProviderProfileID": "7777777",
        "OpenedOn": null,
        "SourceSystem": "PIMS",
        "GIASProviderType": null,
        "PIMSProviderType": "Private Limited Company",
        "PIMSProviderTypeCode": 11,
        "PIMSStatus": "1",
        "masteringCode": null,
        "PIMSStatusName": "",
        "GIASStatus": null,
        "GIASStatusName": null,
        "MasterProviderStatusCode": 1,
        "MasterProviderStatusName": "Active",
        "LegalName": "Org Legal Name"
    },
]

Pengguna Layanan tanpa filter

Anda bisa mendapatkan daftar pengguna tanpa filter seperti yang ditentukan dalam token Otorisasi (atribut iss)
Permintaannya terlihat seperti: 

GET https://environment-url/users?page=1&pageSize=25
Authorization: bearer {jwt-token}

Variabel page dan pageSize bersifat opsional dan default masing-masing 1 dan 25, variabel ini memungkinkan pemanggil untuk mengulangi halaman hasil (menggunakan atribut di badan respons untuk menghitung jumlah catatan dan halaman).

Isi respons berisi atribut berikut (contoh respons di bawah):

Nama Keterangan
pengguna Serangkaian detail pengguna (termasuk objek organisasi anak)
jumlah Catatan Jumlah total catatan yang dilaporkan
halaman Nomor halaman saat ini
jumlahHalaman Jumlah total halaman

Contoh Respon

 { "pengguna": [
        { "approvedAt": "2019-06-19T15:09:58.683Z", "updatedAt": "2019-06-19T15:09:58.683Z", "organisasi": { "id": "13F20E54-79EA-4146 -8E39-18197576F023", "nama": "Departemen untuk Pendidikan", "Kategori": "002", "Jenis": null, "URN": null, "UID": null, "UKPRN": null, "EstablishmentNumber": "001", "Status": 1, " ClosedOn": null, "Alamat": null, "phaseOfEducation": null, "statutoryLowAge": null, "statutoryHighAge": null, "telepon": null, "regionCode": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID": "", "UPIN": "", "PIMSProviderType": "Departemen Pemerintah Pusat", "PIMSStatus": "", "DistrictAdministrativeName" : "", "DibukaPada": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "Badan Pemerintah", "GIASProviderType": "", "PIMSProviderTypeCode": "", "createdAt": "2019- 20-02T14:27:59.020Z", "diperbaruiPada": "20-02-2019T14:28:38.223Z"
            }, "roleName": "Penyetuju", "roleId": 10000, "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "Johnson", "givenName": "Roger"
        }
    ], "numberOfRecords": 1, "halaman": 1, "numberOfPages": 1}

Pengguna Layanan dengan filter

Anda bisa mendapatkan daftar pengguna dengan filter seperti yang ditentukan dalam token Otorisasi (atribut iss)
Permintaannya terlihat seperti: 

GET https://environment-url/users?page=1&pageSize=25&status=0&from=2021%2F02%2F11%2002%3A22%3A06&to=2021%2F11%2F03%2002%3A22%3A06
Authorization: bearer {jwt-token}

Variabel page dan pageSize bersifat opsional dan default masing-masing 1 dan 25, variabel ini memungkinkan pemanggil untuk mengulangi halaman hasil (menggunakan atribut di badan respons untuk menghitung jumlah catatan dan halaman). Status, dari dan ke adalah status opsional yang menerima 0 saat ini. rentang tanggal hanya menerima 7 hari, tanggal harus dalam bentuk kode URL seperti yang ditunjukkan dalam contoh

Validasi rentang tanggal Kirim pesan kesalahan ketika rentang tanggal lebih dari 7 hari. Hanya tanggal mulai di filter yang membuat pengguna diperbarui 7 hari setelah tanggal mulai. Hanya sampai saat ini di filter yang membuat pengguna diperbarui 7 hari sebelum tanggal tersebut. Jika tidak ada tanggal yang ditentukan, berikan informasi terbaru kepada pengguna dari sekarang hingga 7 hari sebelumnya.

Isi respons berisi atribut berikut (contoh respons di bawah):

Nama Keterangan
pengguna Serangkaian detail pengguna (termasuk objek organisasi anak)
numberOfRecords Jumlah total catatan yang dilaporkan
halaman Nomor halaman saat ini
jumlahHalaman Jumlah total halaman
peringatan (opsional) hanya muncul saat mengambil pengguna 7 hari saja

Contoh Respon

 { "pengguna": [
        { "approvedAt": "2019-06-19T15:09:58.683Z", "updatedAt": "2019-06-19T15:09:58.683Z", "organisasi": { "id": "13F20E54-79EA-4146 -8E39-18197576F023", "nama": "Departemen untuk Pendidikan", "Kategori": "002", "Jenis": null, "URN": null, "UID": null, "UKPRN": null, "EstablishmentNumber": "001", "Status": 1, " ClosedOn": null, "Alamat": null, "phaseOfEducation": null, "statutoryLowAge": null, "statutoryHighAge": null, "telepon": null, "regionCode": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID": "", "UPIN": "", "PIMSProviderType": "Departemen Pemerintah Pusat", "PIMSStatus": "", "DistrictAdministrativeName" : "", "DibukaPada": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "Badan Pemerintah", "GIASProviderType": "", "PIMSProviderTypeCode": "", "createdAt": "2019- 20-02T14:27:59.020Z", "diperbaruiPada": "20-02-2019T14:28:38.223Z"
            }, "roleName": "Approver", "roleId": 10000, "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "Johnson", "givenName": "Roger"
        }
    ], "numberOfRecords": 1, "page": 1, "numberOfPages": 1, "warning": "Hanya data 7 hari yang dapat diambil"}

Untuk menafsirkan id kategori, lihat di sini.

Pemberi persetujuan untuk organisasi

Anda bisa mendapatkan daftar pemberi persetujuan untuk organisasi yang berada dalam cakupan layanan Anda (berdasarkan ketentuan kebijakan peran) jika layanan Anda memiliki izin untuk melakukannya.

Permintaannya terlihat seperti: 

GET https://environment-url/users/approvers?page=1&pageSize=25
Authorization: bearer {jwt-token}

Variabel page dan pageSize bersifat opsional dan default masing-masing 1 dan 25, variabel ini memungkinkan pemanggil untuk mengulangi halaman hasil (menggunakan atribut di badan respons untuk menghitung jumlah catatan dan halaman).

Isi respons berisi atribut berikut (contoh respons di bawah):

Nama Keterangan
pengguna Serangkaian detail pengguna (termasuk objek organisasi anak)
jumlah Catatan Jumlah total catatan yang dilaporkan
halaman Nomor halaman saat ini
jumlahHalaman Jumlah total halaman

Contoh Respon

kode respons yang mungkin adalah:

Kode Status HTTP Alasan
200 Permintaan Anda telah diterima
400 Permintaan Anda tidak valid. Rincian tambahan akan diberikan di badan respons
401 JWT Anda hilang atau tidak valid.
403 Aplikasi Anda tidak memiliki izin untuk mendapatkan persetujuan bagi organisasi
500 Terjadi kesalahan pada server. Harap pastikan bahwa rahasia seperti rahasia, kunci API, atau token dikonfigurasi dengan benar. Jika masalah masih berlanjut, harap hubungi tim dukungan untuk mendapatkan bantuan
 { "pengguna": [
        { "organisasi": { "id": "13F20E54-79EA-4146-8E39-18197576F023", "nama": "Departemen Pendidikan", "kategori": { "id": "002", "nama": " Otoritas Lokal"
                }, "urn": null, "uid": null, "ukprn": null, "buildingNumber": "001", "status": { "id": 1, "name": "Open"
                }, "closedOn": null, "alamat": null, "telepon": null, "statutoryLowAge": null, "statutoryHighAge": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID ": "", "UPIN": "", "PIMSProviderType": "Departemen Pemerintah Pusat", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "Badan Pemerintah", "GIASProviderType": "", "PIMSProviderTypeCode": ""
            }, "roleId": 10000, "roleName": "Approver", "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "Johnson", "givenName": "Roger"
        }
    ], "numberOfRecords": 1, "halaman": 1, "numberOfPages": 1}

Dapatkan pengguna organisasi berdasarkan peran menggunakan UKPRN

Anda dapat menggunakan API ini untuk membuat pengguna organisasi memfilter berdasarkan peran 

GET https://environment-url/organisations/{UKPRN}/users?roles=role1,role2
Authorization: bearer {jwt-token}

Item data variabelnya adalah:

Nama Lokasi Diperlukan Keterangan
UKPRN URL Y UKPRN untuk organisasi
peran URL N Kode peran pengguna untuk memfilter daftar pengguna organisasi
jwt-token Tajuk Y Token JWT untuk otorisasi harus ditandatangani menggunakan rahasia API Anda, yang akan diberikan kepada Anda

Kode respons yang mungkin meliputi:

Kode Status HTTP Alasan
200 Peran berhasil diambil untuk organisasi yang diminta
400 Permintaan Anda tidak valid. Rincian tambahan akan diberikan di badan tanggapan
401 JWT Anda hilang atau tidak valid
403 Aplikasi Anda tidak memiliki izin untuk mengambil pengguna untuk organisasi ini
404 Tidak ada pengguna yang ditemukan dengan peran tertentu untuk organisasi yang diminta, sehingga menghasilkan array kosong
500 Terjadi kesalahan pada server. Harap pastikan bahwa rahasia seperti rahasia, kunci API, atau token dikonfigurasi dengan benar. Jika masalah masih berlanjut, harap hubungi tim dukungan untuk mendapatkan bantuan

Ini akan mengembalikan respons dalam format berikut 

{
    "ukprn": "organisation-ukprn-id",
    "users": [
        {
            "email": "[email protected]",
            "firstName": "user1",
            "lastName": "test",
            "userStatus": 1,
            "roles": [
                "role1"
            ]
        },
        {
            "email": "[email protected]",
            "firstName": "user2",
            "lastName": "test",
            "roles": [
                "role1",
                "role2"
            ]
        }
    ]
}

Ambil Pengguna Organisasi berdasarkan Kriteria yang Difilter

Anda juga dapat menggunakan API di atas untuk mengambil pengguna organisasi berdasarkan kriteria yang difilter seperti alamat email atau userId. Permintaannya sepertinya 

GET https://environment-url/organisations/{UKPRN}/[email protected]
Authorization: bearer {jwt-token}

Item data variabelnya adalah:

Nama Lokasi Diperlukan Keterangan
UKPRN URL Y UKPRN untuk organisasi
e-mail URL N Alamat email pengguna untuk pemfilteran
jwt-token Tajuk Y Token JWT untuk Otorisasi harus ditandatangani menggunakan rahasia API Anda, yang akan diberikan kepada Anda

Format responsnya tetap sama dengan panggilan API sebelumnya, sehingga memungkinkan pemfilteran berdasarkan kriteria tertentu.

Dapatkan pengguna organisasi berdasarkan peran menggunakan UPIN

Anda dapat menggunakan API ini untuk membuat pengguna organisasi memfilter berdasarkan peran 

GET https://environment-url/organisations/{UPIN}/users?roles=role1,role2
Authorization: bearer {jwt-token}

Item data variabelnya adalah:

Nama Lokasi Diperlukan Keterangan
UPIN URL Y UPIN untuk organisasi
peran URL N Kode peran pengguna untuk memfilter daftar pengguna organisasi
jwt-token Tajuk Y Token JWT untuk Otorisasi harus ditandatangani menggunakan rahasia API Anda, yang akan diberikan kepada Anda

Kode respons yang mungkin meliputi:

Kode Status HTTP Alasan
200 Peran berhasil diambil untuk organisasi yang diminta
400 Permintaan Anda tidak valid. Rincian tambahan akan diberikan di badan tanggapan
401 JWT Anda hilang atau tidak valid
403 Aplikasi Anda tidak memiliki izin untuk mengambil pengguna untuk organisasi ini
404 Tidak ada pengguna yang ditemukan dengan peran tertentu untuk organisasi yang diminta, sehingga menghasilkan array kosong
500 Terjadi kesalahan pada server. Harap pastikan bahwa rahasia seperti rahasia, kunci API, atau token dikonfigurasi dengan benar. Jika masalah masih berlanjut, harap hubungi tim dukungan untuk mendapatkan bantuan

Ini akan mengembalikan respons dalam format berikut 

{
    "upin": "organisation-upin-id",
    "users": [
        {
            "email": "[email protected]",
            "firstName": "user1",
            "lastName": "test",
            "userStatus": 1,
            "roles": [
                "role1"
            ]
        },
        {
            "email": "[email protected]",
            "firstName": "user2",
            "lastName": "test",
            "roles": [
                "role1",
                "role2"
            ]
        }
    ]
}

Ambil Pengguna Organisasi berdasarkan Kriteria yang Difilter

Anda juga dapat menggunakan API di atas untuk mengambil pengguna organisasi berdasarkan kriteria yang difilter seperti alamat email atau userId. Permintaannya sepertinya 

GET https://environment-url/organisations/{UPIN}/[email protected]
Authorization: bearer {jwt-token}

Item data variabelnya adalah:

Nama Lokasi Diperlukan Keterangan
UPIN URL Y UPIN untuk organisasi
e-mail URL N Alamat email pengguna untuk pemfilteran
jwt-token Tajuk Y Token JWT untuk Otorisasi harus ditandatangani menggunakan rahasia API Anda, yang akan diberikan kepada Anda

Format responsnya tetap sama dengan panggilan API sebelumnya, sehingga memungkinkan pemfilteran berdasarkan kriteria tertentu.

Bagaimana id dipetakan ke kategori dan tipe?

Kategori Organisasi

pengenal Keterangan
001 Pendirian (lihat Jenis Pendirian di bawah)
002 Otoritas Lokal
003 Organisasi Warisan Lainnya
004 Setting Awal Tahun
008 Pemangku Kepentingan Lainnya
009 Penyedia Pelatihan
010 Kepercayaan Multi-Akademi
011 Pemerintah
012 Pemangku Kepentingan GIAS lainnya
013 Kepercayaan Akademi Tunggal
050 Pemasok Perangkat Lunak
051 Pendidikan Lanjutan

Jenis Pendirian

pengenal Keterangan
001 Sekolah Komunitas
002 Sekolah Bantuan Sukarela
003 Sekolah Terkendali Sukarela
005 Sekolah Yayasan
006 Perguruan Tinggi Teknologi Kota
007 Sekolah Khusus Komunitas
008 Sekolah Luar Biasa Tidak Terpelihara
010 Sekolah Luar Biasa Mandiri Lainnya
011 Sekolah INdependen Lainnya
012 Sekolah Khusus Fondasi
014 Unit Rujukan Murid
015 Sekolah Taman Kanak-Kanak LA
018 Pendidikan Lanjutan
024 Unit Aman
025 Sekolah Lepas Pantai
026 Layanan Pendidikan Anak
027 Lain-lain
028 Pimpinan Sponsor Akademi
029 Institusi Pendidikan Tinggi
030 Pendirian Welsh
031 Pusat Bentuk Keenam
032 Lembaga Pos Khusus 16
033 Pimpinan Sponsor Khusus Akademi
034 Konverter Akademi
035 Sekolah Gratis
036 Sekolah Khusus Gratis
037 Sekolah Luar Negeri Inggris
038 Sekolah Gratis - Penyediaan Alternatif
039 Sekolah Gratis - 16-19
040 Perguruan Tinggi Keguruan Universitas
041 Sekolah Studio
042 Konverter Ketentuan Alternatif Akademi
043 Dipimpin Sponsor Penyediaan Alternatif Akademi
044 Konverter Khusus Akademi
045 Konverter Akademi 16-19
046 Akademi 16-19 Dipimpin Sponsor
047 Anak-anak
Memperluas
Informasi Tambahan
Aplikasi Terkait
Direkomendasikan untuk Anda
Informasi Terkait Semua