Página Inicial>Relacionado com a programação>Outro código-fonte
Baixar

API pública de login do DfE

API para consumidores externos interagirem com login do DfE

Você precisa se autenticar com essas APIs

Para usar qualquer uma das APIs abaixo, você precisará fornecer um token de portador no cabeçalho da solicitação. Esse token de portador é simplesmente um JWT (consulte https://jwt.io) com uma carga simples que é assinada usando um segredo que apenas DfE Sign-in e você sabe.

Você deve criar um JWT no ponto de uso em seu aplicativo de chamada usando a biblioteca JWT padrão que vem com a tecnologia escolhida.

O corpo do token exigirá um emissor (seu ID de cliente de serviço) e um público da seguinte forma: 

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

O token deve ser assinado utilizando o algoritmo HS256 com seu API_SECRET. No ponto de integração com o DfE Sign-in, você teria recebido um API_SECRET (não confundir com o seu CLIENT_SECRET), se você não tiver esse contato, entre em contato com a equipe do DfE Sign-in e nós geraremos um novamente para você (estes são específico do serviço/ambiente.)

Usando o Postman para avaliar e testar as APIs

Visão geral do carteiro

Postman é uma ferramenta de plataforma API usada para construir e executar APIs. Postman simplifica cada etapa do ciclo de vida da API e é amplamente usado no desenvolvimento e documentação da API pública de login do DfE.

Um conjunto de coleções do Postman e seus ambientes de execução associados foram fornecidos para ajudá-lo a aprender, testar e depurar suas integrações com a plataforma DfE Sign-in por meio da API pública.

Introdução ao Postman e ao pacote de coleta DfE Sign-in

As ferramentas da plataforma Postman API estão disponíveis como cliente de desktop, aplicativo web hospedado e interface de linha de comando (CLI) em https://www.postman.com/api-platform/api-client/.

A coleção e os ambientes do DfE Sign-in Public API Postman estão disponíveis em https://github.com/DFE-Digital/login.dfe.public-api/tree/develop/Postman/.

Convidar usuário

Como um serviço integrado ao login do DfE, você pode usar a API para convidar usuários para o serviço.

A solicitação parece 

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"
}

Os itens de dados variáveis ​​são:

Nome Localização Obrigatório Descrição
ID de serviço URL S O identificador de login do DfE para o serviço para o qual você está convidando o usuário
token jwt Cabeçalho S O token JWT para autorização deve ser assinado usando o segredo da sua API, que será fornecido a você
ID de origem Corpo S O identificador do usuário em seu sistema. Será incluído na resposta do canal traseiro
nome dado Corpo S O nome dado aos usuários
nome de família Corpo S O sobrenome do usuário
e-mail Corpo S O endereço de e-mail do usuário. Este também é um identificador exclusivo de um usuário no login do DfE
organização Corpo
 O identificador de login do DfE ao qual o usuário deve estar associado
ligar de volta Corpo
 A URL para a qual a resposta do canal de retorno deve ser enviada. Veja detalhes da resposta do canal traseiro abaixo
usuárioRedirect Corpo
 A URL para a qual um usuário, se estiver passando pela integração, deve retornar após a conclusão. Se omitido, o redirecionamento padrão do seu cliente será usado
convidaSubjectOverride Corpo
 Substitui o assunto do e-mail de convite
convidaBodyOverride Corpo
 Substitui o conteúdo do e-mail de convite

Os possíveis códigos de resposta são:

Código de status HTTP Razão
202 Sua solicitação foi aceita
400 Sua solicitação é inválida. Detalhes adicionais serão fornecidos no corpo da resposta
401 Seu JWT está faltando ou não é válido.
404 O ID do serviço no uri não existe
500 Ocorreu um erro no servidor. Certifique-se de que segredos como segredos, chaves de API ou tokens estejam configurados corretamente. Se o problema persistir, entre em contato com a equipe de suporte para obter assistência

Quando a solicitação é feita, o usuário pode ou não existir no sistema; e pode ou não ter solicitados os mapeamentos de organização e serviços desejados. Por esse motivo, todos os detalhes do usuário são enviados por meio de uma resposta de canal secundário. Isso pode acontecer imediatamente se o usuário for encontrado (por e-mail) no DfE Sign-in; ou assim que o usuário aceitar o e-mail de convite que será enviado a ele.

A resposta do canal traseiro é semelhante a: 

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

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

Os itens de dados na solicitação são:

Nome Localização Descrição
token jwt Cabeçalho Um token jwt, assinado com o mesmo segredo da solicitação
sub Corpo Identificador de login do DfE para o usuário. Isso não mudará e será incluído na resposta do OIDC como sub-reivindicação
ID de origem Corpo O sourceId usado na solicitação original

Gerenciar anúncios

Os anúncios podem ser publicados e não publicados para uma organização.

Os anúncios podem ser publicados por: 

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"
}

A estrutura de um anúncio é a seguinte:

Atributo Obrigatório Descrição Tipo
mensagemId S Identificador da mensagem no sistema de origem. Deve ser único UUID
urna Y (ou uid) URN do estabelecimento Numérico
UID Y (ou urna) UID do grupo UUID
tipo S O código do tipo numérico da mensagem (veja abaixo) Inteiro
título S Título do anúncio. Limite máximo de caracteres 255 Texto ou HTML
resumo S Resumo do anúncio. Máximo de caracteres Limite 340 Texto ou HTML
corpo S Corpo do anúncio. Máximo de caracteres Limite 5.000 Texto ou HTML
publicadoEm S Anúncio de data/hora publicado em ISO8601
expira em
 O anúncio de data/hora deve expirar às ISO8601

os possíveis códigos de resposta são:

Código de status HTTP Razão
202 Sua solicitação foi aceita
400 Sua solicitação é inválida. Detalhes adicionais serão fornecidos no corpo da resposta
401 Seu JWT está faltando ou não é válido.
500 Ocorreu um erro no servidor. Certifique-se de que segredos como segredos, chaves de API ou tokens estejam configurados corretamente. Se o problema persistir, entre em contato com a equipe de suporte para obter assistência

Os tipos válidos de anúncio são:

código significado
1 Aviso sobre registro de estabelecimento
2 Problema com registro de estabelecimento
4 Aviso sobre registro de governança
5 Problema com registro de governança

Os anúncios poderão ser posteriormente despublicados por: 

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

Onde your-unique-idenitifer é o messageId que foi enviado ao publicar a mensagem.

Os possíveis códigos de resposta são:

Código de status HTTP Razão
204 O anúncio não foi publicado
401 Seu JWT está faltando ou não é válido.
404 O ID da mensagem no uri não existe
500 Ocorreu um erro no servidor. Certifique-se de que segredos como segredos, chaves de API ou tokens estejam configurados corretamente. Se o problema persistir, entre em contato com a equipe de suporte para obter assistência

Criar aplicativos filhos

Se seu aplicativo estiver habilitado, você poderá criar aplicativos filhos por meio da API. Esses aplicativos filhos devem ser usados ​​quando você tiver aplicativos de terceiros que usarão o fluxo de consentimento do OIDC para permitir que eles chamem uma API dentro do seu aplicativo no contexto de um usuário.

Aplicativos filhos podem ser criados por: 

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"
	]
}

Observação sobre substituições de modelo de consentimento
Dois parâmetros permitem substituir o conteúdo exibido aos usuários na Tela de Consentimento, o título e o corpo (todo o resto é estático de acordo com o design atual do formulário). O valor de substituição é uma sequência que possui dois valores dinâmicos (opcionais). por exemplo, consentTitle="Do you want to allow {{applicationName}} to send data to us for {{roleScope}}"

A estrutura de um aplicativo é a seguinte:

Atributo Obrigatório Descrição
nome S Um nome amigável para o aplicativo. Isso será usado ao solicitar o consentimento do usuário
descrição N Uma descrição do aplicativo
redirecionarUris S Uma matriz de uris de redirecionamento que pode ser usada durante o fluxo de login/consentimento do OIDC

Os possíveis códigos de resposta são:

Código de status HTTP Razão
201 Seu aplicativo filho foi criado
400 Sua solicitação é inválida. Detalhes adicionais serão fornecidos no corpo da resposta
403 Seu aplicativo não tem permissão para criar aplicativos filhos

Após a criação bem-sucedida de um aplicativo filho, você receberá uma resposta como: 

{
	"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"
	]
}

O name , description e redirectUris são uma confirmação do que foi recebido da sua solicitação. O clientId e clientSecret são o que o aplicativo filho precisará usar ao executar processos OIDC. Você também precisará do clientId para qualquer gerenciamento posterior do aplicativo.

Se o segredo de um aplicativo filho for comprometido, você poderá solicitar que o segredo seja regenerado: 

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

Os possíveis códigos de resposta são:

Código de status HTTP Razão
200 O segredo foi regenerado
403 O ID do cliente especificado não é filho do seu aplicativo
404 Nenhum aplicativo pode ser encontrado com o ID do cliente especificado

Após a regeneração bem-sucedida do segredo, você receberá uma resposta como: 

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

Concessões e Tokens de aplicativos infantis

Os aplicativos filhos seguem um fluxo de consentimento explícito que, em última análise, gera um código de autorização (uma concessão) que pode ser trocado por um token de acesso de curta duração e um token de atualização de vida mais longa, a fim de permitir que os proprietários de aplicativos filhos gerenciem o ciclo de vida dos tokens emitidos que fornecemos uma API conveniente para listar concessões e problemas de token para um aplicativo filho governamental.

Esses tokens podem então ser inspecionados e revogados usando os endpoints de conexão de identificação aberta padrão (intropecção e revogação).

Para obter uma lista de subsídios para um determinado serviço infantil: 

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

Para obter uma lista de tokens emitidos para uma determinada concessão de serviço infantil: 

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

Obtenha acesso do usuário ao serviço

Você pode usar esta API para obter acesso de um usuário a um serviço de uma organização. A solicitação parece 

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

Os itens de dados variáveis ​​são:

Nome Localização Obrigatório Descrição
ID de serviço URL S O identificador de login do DfE para o serviço
ID da organização URL S O identificador de login do DfE para a organização
ID do usuário URL S O identificador de login do DfE para o usuário
token jwt Cabeçalho S O token JWT para autorização deve ser assinado usando o segredo da sua API, que será fornecido a você

Isso retornará uma resposta no seguinte formato 

{
    "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"
        }
    ]
}

Nota: Se o Usuário não tiver o Serviço especificado ou não estiver na Organização indicada, ele retornará o código de status 404 (Não Encontrado) .

Obtenha organizações para o usuário

Você pode usar esta API para obter as organizações associadas a um usuário. A solicitação se parece com 

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

Os itens de dados variáveis ​​são:

Nome Localização Obrigatório Descrição
ID do usuário URL S O identificador de login do DfE para o usuário
token jwt Cabeçalho S O token JWT para autorização deve ser assinado usando o segredo da sua API, que será fornecido a você

Isso retornará uma resposta no seguinte formato 

[
    {
        "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
    },
]

Obtenha funções para serviço

Você pode usar esse endpoint de API para obter as funções associadas ao seu serviço ou a um de seus serviços filho. A solicitação se parece com: 

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

Os itens de dados variáveis ​​são:

Nome Localização Obrigatório Descrição
ID do cliente URL S O identificador do cliente de login do DfE para o serviço
token jwt Cabeçalho S O token JWT para autorização deve ser assinado usando o segredo da sua API, que será fornecido a você

Os possíveis códigos de resposta são:

Código de status HTTP Razão
200 Uma lista (possivelmente vazia) de funções foi recuperada com sucesso para o ID do cliente solicitado.
403 O ID do cliente especificado não é seu serviço nem é filho de seu serviço.
404 Nenhum serviço pode ser localizado com o ID do cliente especificado.

Isso retornará uma resposta no seguinte formato: 

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

ou o seguinte se nenhuma função for encontrada: 

[]

Obtenha organizações para o usuário, incluindo atributos de organização do perfil do provedor

Você pode usar esta API para obter as organizações associadas a um usuário. A solicitação se parece com 

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

Os itens de dados variáveis ​​são:

Nome Localização Obrigatório Descrição
ID do usuário URL S O identificador de login do DfE para o usuário
token jwt Cabeçalho S O token JWT para autorização deve ser assinado usando o segredo da sua API, que será fornecido a você

Isso retornará uma resposta no seguinte formato 

[
    {
        "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"
    },
]

Usuários de serviço sem filtros

Você pode obter uma lista de usuários sem filtros conforme definido no token de autorização (atributo iss)
A solicitação se parece com: 

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

As variáveis ​​page e pageSize são opcionais e têm como padrão 1 e 25, respectivamente. Essas variáveis ​​permitem que o chamador itere nas páginas de resultados (usando atributos no corpo da resposta para calcular o número de registros e páginas).

O corpo da resposta contém os seguintes atributos (exemplo de resposta abaixo):

Nome Descrição
Usuários Uma série de detalhes do usuário (incluindo um objeto de organização filho)
número de registros Número total de registros relatados
página Número da página atual
número de páginas Número total de páginas

Exemplo de resposta

 {    "Usuários": [
        { "approvedAt": "2019-06-19T15:09:58.683Z", "updatedAt": "2019-06-19T15:09:58.683Z", "organização": { "id": "13F20E54-79EA-4146 -8E39-18197576F023", "nome": "Departamento de Educação", "Categoria": "002", "Tipo": nulo, "URN": nulo, "UID": nulo, "UKPRN": nulo, "EstablishmentNumber": "001", "Status": 1, "ClosedOn": nulo, "Endereço": nulo, "phaseOfEducation": nulo, "statutoryLowAge": nulo, "statutoryHighAge": nulo, "telefone": nulo, "regionCode": nulo, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID": "", "UPIN": "", "PIMSProviderType ": "Departamento do Governo Central", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "Órgão governamental", "GIASProviderType": "", "PIMSProviderTypeCode": "", "criadoAt": "2019-02-20T14:27:59.020Z", "atualizadoAt": "2019-02-20T14:28:38.223Z"
            }, "roleName": "Aprovador", "roleId": 10000, "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "Johnson", "givenName": "Roger"
        }
    ], "numberOfRecords": 1, "página": 1, "numberOfPages": 1}

Usuários de serviço com filtros

Você pode obter uma lista de usuários com filtros conforme definido no token de autorização (atributo iss)
A solicitação se parece com: 

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}

As variáveis ​​page e pageSize são opcionais e têm como padrão 1 e 25, respectivamente. Essas variáveis ​​permitem que o chamador itere nas páginas de resultados (usando atributos no corpo da resposta para calcular o número de registros e páginas). O status de e para é opcional e aceita 0 no momento. o intervalo de datas aceita apenas 7 dias. As datas devem estar no formato codificado por URL, conforme mostrado no exemplo

Validação do intervalo de datas Enviar mensagem de erro quando o intervalo de datas for superior a 7 dias. Somente a partir da data no filtro os usuários são atualizados 7 dias após a data inicial. Somente a data no filtro faz com que os usuários sejam atualizados 7 dias antes da data. Quando nenhuma data é especificada, os usuários são atualizados de agora até 7 dias antes.

O corpo da resposta contém os seguintes atributos (exemplo de resposta abaixo):

Nome Descrição
Usuários Uma série de detalhes do usuário (incluindo um objeto de organização filho)
número de registros Número total de registros relatados
página Número da página atual
número de páginas Número total de páginas
aviso (opcional) aparece apenas ao buscar apenas 7 dias de usuários

Exemplo de resposta

 {    "Usuários": [
        { "approvedAt": "2019-06-19T15:09:58.683Z", "updatedAt": "2019-06-19T15:09:58.683Z", "organização": { "id": "13F20E54-79EA-4146 -8E39-18197576F023", "nome": "Departamento de Educação", "Categoria": "002", "Tipo": nulo, "URN": nulo, "UID": nulo, "UKPRN": nulo, "EstablishmentNumber": "001", "Status": 1, "ClosedOn": nulo, "Endereço": nulo, "phaseOfEducation": nulo, "statutoryLowAge": nulo, "statutoryHighAge": nulo, "telefone": nulo, "regionCode": nulo, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID": "", "UPIN": "", "PIMSProviderType ": "Departamento do Governo Central", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "Órgão governamental", "GIASProviderType": "", "PIMSProviderTypeCode": "", "criadoAt": "2019-02-20T14:27:59.020Z", "atualizadoAt": "2019-02-20T14:28:38.223Z"
            }, "roleName": "Aprovador", "roleId": 10000, "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "Johnson", "givenName": "Roger"
        }
    ], "numberOfRecords": 1, "page": 1, "numberOfPages": 1, "warning": "Apenas 7 dias de dados podem ser obtidos"}

Para interpretar o id da categoria, veja aqui.

Aprovadores para organizações

Você poderá obter uma lista de aprovadores para organizações que estão dentro do seu escopo de serviços (com base nas condições da política de função) se o seu serviço tiver permissão para fazê-lo.

A solicitação se parece com: 

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

As variáveis ​​page e pageSize são opcionais e têm como padrão 1 e 25, respectivamente. Essas variáveis ​​permitem que o chamador itere nas páginas de resultados (usando atributos no corpo da resposta para calcular o número de registros e páginas).

O corpo da resposta contém os seguintes atributos (exemplo de resposta abaixo):

Nome Descrição
Usuários Uma série de detalhes do usuário (incluindo um objeto de organização filho)
número de registros Número total de registros relatados
página Número da página atual
número de páginas Número total de páginas

Exemplo de resposta

os possíveis códigos de resposta são:

Código de status HTTP Razão
200 Sua solicitação foi aceita
400 Sua solicitação é inválida. Detalhes adicionais serão fornecidos no corpo da resposta
401 Seu JWT está faltando ou não é válido.
403 Seu aplicativo não tem permissão para obter aprovadores para organizações
500 Ocorreu um erro no servidor. Certifique-se de que segredos como segredos, chaves de API ou tokens estejam configurados corretamente. Se o problema persistir, entre em contato com a equipe de suporte para obter assistência
 {    "Usuários": [
        { "organização": { "id": "13F20E54-79EA-4146-8E39-18197576F023", "nome": "Departamento de Educação", "categoria": { "id": "002", "nome": " Autoridade Local"
                }, "urna": nulo, "uid": nulo, "ukprn": nulo, "estabelecimentoNumber": "001", "status": { "id": 1, "nome": "Aberto"
                }, "closedOn": null, "address": null, "telephone": null, "statutoryLowAge": null, "statutoryHighAge": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID ": "", "UPIN": "", "PIMSProviderType": "Central Departamento Governamental", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "Órgão Governamental" , "GIASProviderType": "", "PIMSProviderTypeCode": ""
            }, "roleId": 10000, "roleName": "Aprovador", "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "Johnson", "givenName": "Roger"
        }
    ], "numberOfRecords": 1, "página": 1, "numberOfPages": 1}

Obtenha usuários da organização por funções usando UKPRN

Você pode usar esta API para fazer com que os usuários da organização filtrem por funções. A solicitação se parece com 

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

Os itens de dados variáveis ​​são:

Nome Localização Obrigatório Descrição
UKPRN URL S UKPRN para a organização
papéis URL N Códigos de função de usuário para filtrar a lista de usuários da organização
token jwt Cabeçalho S O token JWT para autorização deve ser assinado usando o segredo da sua API, que será fornecido a você

Os possíveis códigos de resposta incluem:

Código de status HTTP Razão
200 Funções recuperadas com sucesso para a organização solicitada
400 Sua solicitação é inválida. Detalhes adicionais serão fornecidos no corpo da resposta
401 Seu JWT está faltando ou não é válido
403 Seu aplicativo não tem permissão para recuperar usuários desta organização
404 Nenhum usuário foi encontrado com as funções especificadas para a organização solicitada, resultando em uma matriz vazia
500 Ocorreu um erro no servidor. Certifique-se de que segredos como segredos, chaves de API ou tokens estejam configurados corretamente. Se o problema persistir, entre em contato com a equipe de suporte para obter assistência

Isso retornará uma resposta no seguinte formato 

{
    "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"
            ]
        }
    ]
}

Recuperar usuários da organização por critérios filtrados

Você também pode usar a API acima para recuperar usuários da organização com base em critérios filtrados, como endereço de e-mail ou ID do usuário. A solicitação parece 

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

Os itens de dados variáveis ​​são:

Nome Localização Obrigatório Descrição
UKPRN URL S UKPRN para a organização
e-mail URL N O endereço de e-mail do usuário para filtragem
token jwt Cabeçalho S O token JWT para autorização deve ser assinado usando o segredo da API, que será fornecido a você

O formato da resposta permanece o mesmo da chamada de API anterior, permitindo a filtragem por critérios específicos.

Obtenha usuários da organização por funções usando UPIN

Você pode usar esta API para fazer com que os usuários da organização filtrem por funções. A solicitação se parece com 

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

Os itens de dados variáveis ​​são:

Nome Localização Obrigatório Descrição
UPIN URL S UPIN para a organização
papéis URL N Códigos de função de usuário para filtrar a lista de usuários da organização
token jwt Cabeçalho S O token JWT para autorização deve ser assinado usando o segredo da API, que será fornecido a você

Os possíveis códigos de resposta incluem:

Código de status HTTP Razão
200 Funções recuperadas com sucesso para a organização solicitada
400 Sua solicitação é inválida. Detalhes adicionais serão fornecidos no corpo da resposta
401 Seu JWT está faltando ou não é válido
403 Seu aplicativo não tem permissão para recuperar usuários desta organização
404 Nenhum usuário foi encontrado com as funções especificadas para a organização solicitada, resultando em uma matriz vazia
500 Ocorreu um erro no servidor. Certifique-se de que segredos como segredos, chaves de API ou tokens estejam configurados corretamente. Se o problema persistir, entre em contato com a equipe de suporte para obter assistência

Isso retornará uma resposta no seguinte formato 

{
    "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"
            ]
        }
    ]
}

Recuperar usuários da organização por critérios filtrados

Você também pode usar a API acima para recuperar usuários da organização com base em critérios filtrados, como endereço de e-mail ou ID do usuário. A solicitação parece 

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

Os itens de dados variáveis ​​são:

Nome Localização Obrigatório Descrição
UPIN URL S UPIN para a organização
e-mail URL N O endereço de e-mail do usuário para filtragem
token jwt Cabeçalho S O token JWT para autorização deve ser assinado usando o segredo da API, que será fornecido a você

O formato da resposta permanece o mesmo da chamada de API anterior, permitindo a filtragem por critérios específicos.

Como os IDs são mapeados para categorias e tipos?

Categorias de organização

eu ia Descrição
001 Estabelecimento (ver Tipos de Estabelecimento abaixo)
002 Autoridade Local
003 Outras organizações legadas
004 Configuração de início de ano
008 Outras partes interessadas
009 Provedores de treinamento
010 Confiança Multi-Academia
011 Governo
012 Outras partes interessadas do GIAS
013 Confiança de Academia Única
050 Fornecedores de software
051 Educação Adicional

Tipos de estabelecimento

eu ia Descrição
001 Escola Comunitária
002 Escola assistida voluntária
003 Escola Voluntária Controlada
005 Escola Fundação
006 Faculdade de Tecnologia da Cidade
007 Escola Especial Comunitária
008 Escola Especial Não Mantida
010 Outra escola especial independente
011 Outra escola independente
012 Escola Especial da Fundação
014 Unidade de Referência de Alunos
015 Escola maternal de Los Angeles
018 Educação Continuada
024 Unidades Seguras
025 Escolas offshore
026 Serviço de educação infantil
027 Diversos
028 Patrocinador da Academia Liderado
029 Instituição de Ensino Superior
030 Estabelecimento galês
031 Centros do sexto formulário
032 Instituição Especial Post 16
033 Patrocinador Especial da Academia Liderado
034 Conversor de Academia
035 Escolas Gratuitas
036 Especial Escolas Gratuitas
037 Escolas Britânicas no Exterior
038 Escolas Gratuitas - Oferta Alternativa
039 Escolas Gratuitas - 16-19
040 Faculdade de Ensino Universitário
041 Escolas de estúdio
042 Conversor de Provisão Alternativa da Academia
043 Patrocinador de fornecimento alternativo da Academia liderado
044 Conversor Especial da Academia
045 Conversor Academia 16-19
046 Patrocinador da Academia 16-19 liderado
047 Criança
Expandir
Informações adicionais
Aplicativos Relacionados
Recomendado para você
Informações Relacionadas Todos