Primeiros passos com sua integração

Você pode solicitar credenciais de API de membro da sandbox para construir e testar seu aplicativo. Essas credenciais permitem que você faça chamadas para a API membro do sandbox para ler, gravar e atualizar ORCID registros. O acesso ao ambiente de teste sandbox está disponível gratuitamente para qualquer pessoa, mesmo se você não for um ORCID organização membro.

Anote os: Se você estiver usando um sistema de terceiros que já oferece suporte ORCID, talvez você não precise se registrar para obter credenciais de API de sandbox. 

O sandbox permite que você crie contas de usuário de teste e desenvolva sua integração sem ter que se preocupar em afetar os dados ao vivo (produção) ORCID Registro. A sandbox se comporta da mesma maneira que a produção ORCID Registro com algumas exceções.

Criação de uma conta de teste

A fim de testar o ORCID API e chamadas de API, como leitura e adição de informações a um ORCID registro, você também precisará criar um teste ORCID gravar na caixa de areia. Isso pode ser feito por meio da interface do usuário, bem como na produção ORCID Registro. Vamos para https://sandbox.orcid.org/register e registre-se para uma conta.

Endereços de e-mail do Mailinator

O servidor sandbox envia e-mails de notificação apenas para Mailinator (@mailinator.com) endereços de e-mail para não enviar spam aos servidores de e-mail involuntariamente. Você não receberá um e-mail de verificação ou notificação de redefinição de senha, a menos que use um endereço @mailinator.com, e a verificação é necessária para fazer edições manuais nos registros do sandbox. Saiba mais sobre suas caixas de entrada públicas gratuitas Aqui. Se você não deseja usar um Mailinator endereço, anote seu nome de usuário e senha (pois você os usará para conceder autorização ao seu aplicativo durante o teste) e entre em contato conosco para solicitar assistência com a verificação.

Mailinator é um serviço de e-mail que possui um serviço público gratuito e um serviço privado pago. Para testar, você pode usar o serviço público totalmente gratuito. Saiba mais sobre seus níveis aqui.

Mailinator é um serviço de terceiros que não é gerenciado ou mantido por ORCID. Recomendamos que você analise como esse serviço funciona e suas limitações antes de usar esses endereços. 

Ao solicitar permissão para interagir com um ORCID registro do usuário, você especifica um ou mais 'escopos'. Cada escopo permite que você faça certas coisas, como ler o registro ou atualizar uma seção específica.

Escopos de três pernas (código de autorização)

3 pernas refere-se aos três atores envolvidos na obtenção de permissão de um usuário; ORCID, seu sistema e o próprio usuário.

/autenticar

Este escopo é usado para coletar o ORCID iD e ler informações públicas apenas no registro. Todos os outros escopos de três pernas incluem a permissão de autenticação, portanto, esse escopo pode ser omitido se for solicitado qualquer outro acesso. Este escopo está disponível na API de membros ou pública.

/ read-limited (Member API apenas)

Este escopo é usado para obter acesso para ler itens públicos e de visibilidade limitada em um ORCID registro. Este escopo está disponível apenas na API de membros.

/ atividades / atualização (apenas API de membro)

Este escopo é usado para escrever, atualizar e excluir itens na afiliação, financiamento, trabalhos e recursos de pesquisa e seções de revisão por pares de um ORCID registro. Este escopo está disponível apenas na API de membros.

/ pessoa / atualização (apenas API de membro)

Este escopo é usado para escrever, atualizar e excluir itens nas seções de outros nomes, palavras-chave, países, urls de pesquisador, sites e identificadores pessoais externos do registro. Este escopo está disponível apenas na API de membros.

código aberto

Este escopo é usado por integradores OpenID quando um id_token é necessário. Quando o escopo openid é incluído, o Registro retorna um id_token dentro da resposta do token e concede ao cliente permissão para acessar o endpoint de informações do usuário para aquele usuário. Este escopo está disponível na API pública e membro.

Observe que o escopo 'openid' não começa com '/' como o outro ORCID Escopos de API. Isso ocorre porque o escopo 'openid' não é definido por ORCID, mas em vez disso definido pela especificação OpenID Connect. Por favor, veja nosso Documentação OpenID para obter mais informações.

Múltiplos escopos

Vários escopos podem ser solicitados em uma única interação, listando os escopos no URL de autenticação com um espaço codificado entre cada um, como escopo = / leitura limitada% 20 / atividades / atualização% 20 / pessoa / atualização

Acesso completo

Se você deseja acesso total para ler e editar um registro, inclua três escopos em seu URL de autenticação: / read-limited, / Activities / update e / person / update. No URL, eles apareceriam como escopo = / leitura limitada% 20 / atividades / atualização% 20 / pessoa / atualização

Escopos de duas pernas (credencial do cliente)

Para algumas atividades, você não precisa pedir permissão ao usuário. Escopos OAuth de duas pernas são solicitados diretamente do ORCID API e não exigem que o pesquisador conceda permissão. Tokens com esses escopos são válidos por 20 anos e podem ser reutilizados

/ read-public

Este escopo é usado para ler informações públicas em um único ORCID iD ou procure por ORCID registros. Este escopo está disponível no membro ou API pública.

/ webhook

Este escopo permite que um aplicativo cliente registre um webhook em um ORCID registro, a fim de receber notificações quando um registro é atualizado. Este escopo está disponível para premium ORCID apenas membros. Se você não é um membro premium, mas deseja testar esta função no Developer's Sandbox, por favor entrar em ORCID Comunidade.

• No passado ORCID apoiou outros escopos, que agora foram extinto.
• Você pode descobrir quais escopos são necessários para adicionar ou atualizar uma seção específica aqui.

As integrações precisam armazenar mais do que apenas ORCID registros. Seu sistema deverá ser capaz de:

• Aceitar e armazenar ORCID IDs: Seu sistema precisará saber o iD da ORCID registro para atualizar. Armazene-o junto com as informações do pesquisador. Nossa recomendação é armazenar o URI https completo: https://orcid.org/0000-0001-5727-2427.
• Aceitar e armazenar persistente tokens de acesso e tokens de atualização: Os tokens de acesso podem ser usados ​​para ler e atualizar registros, bem como indicar que o iD foi autenticado. Os tokens persistentes são válidos por aproximadamente 20 anos ou até que o usuário os revogue. Os tokens de atualização podem ser usados ​​para criar novos tokens de acesso com escopos iguais ou limitados. Armazene os tokens junto com as informações do pesquisador. Também recomendamos que você armazene o escopo de token, e as,expiração de token.
• Aceitar e armazenar colocar códigos (se atualizando ORCID registros): cada item que você adiciona ao ORCID O registro será retornado com um código colocado pelo ORCID API. Salve este código junto com o item em seu sistema, é assim que você identificará qual item precisa ser lido ou atualizado.
• Log de interações: Seu sistema deve registrar ambas as chamadas feitas para o ORCID API e respostas recebidas. Isso é necessário então ORCID pode ajudar se um problema surgir mais tarde.
• Fornece mensagens de erro e um contato de suporte quando uma interação não ocorre conforme o esperado.

Para garantir que você construa a melhor integração possível para sua instituição, seus pesquisadores e a comunidade em geral, recomendamos que você considere as seguintes práticas recomendadas:

• Personalize a experiência do usuário: Use os dados que seu sistema armazenou para preencher previamente a tela de login / registro do OAuth. Você também pode incluir parâmetros de estado para identificar o usuário em seu sistema ou alterar o idioma de exibição em ORCID.
• Forneça um fluxo de trabalho para os usuários se eles negarem a permissão do seu sistema: Forneça uma mensagem aos usuários que explique claramente o que ORCID é, por que seu sistema está solicitando permissão para seus ORCID gravar e o que você fará com essa permissão e oferecer a opção de conceder permissão novamente.
• Fornece uma opção para os usuários removerem seus ORCID iD e dados de seu sistema: Em casos raros, um usuário pode desejar remover seu iD do seu sistema, ou eles podem ter conectado o ORCID iD Certifique-se de que quaisquer tokens de acesso ativos também sejam revogados pelo seu sistema ao mesmo tempo.
• Atualize os itens adicionados quando forem necessárias correções usando o código de inserção exclusivo do item.
• Forneça mensagens de erro descritivas e um contato de suporte para seus usuários quando uma interação não ocorrer conforme o esperado.
• Exibem o ORCID logotipo do membro (entre em contato para recebê-lo)
• Crie uma experiência de usuário consistente associando o iD ícone com um processo de afirmação confiável. Nosso ORCID Diretrizes da marca para membros e parceiross irá guiá-lo através do processo de configuração da exibição do iD ícone em seu sistema, bem como o que fazer e o que não fazer na exibição do ORCID marca.
• Use o token de acesso para verificar as permissões existentes: depois de receber as permissões do usuário uma vez, não será necessário solicitá-las novamente.

Para apoiar o componente social, oferecemos um kit de ferramentas de Recursos de divulgação para ajudá-lo a desenvolver uma campanha para apoiar sua integração e se comunicar com seus pesquisadores:

• O que ORCID é.
• Por que seu sistema coleta IDs e como seu sistema executará tarefas, como atualizar seus registros.
• Por que seus pesquisadores se beneficiarão com a criação de um ORCID iD e conectando seus iDs ao seu sistema.
• Como funciona o dobrador de carta de canal ORCID beneficia a comunidade de pesquisa global mais ampla.

Estaremos construindo continuamente essa “biblioteca” de recursos com base no feedback da comunidade. Se você tiver uma ideia sobre algo que gostaria de ver, não hesite em nos contatar.

Solicitação de organizações membros ORCID Credenciais de API de membro no servidor de produção (ao vivo) ao preencher o Formulário de inscrição do cliente da API do membro de produção. Antes de emitir credenciais de API de membro de produção, o ORCID A equipe de engajamento analisará uma demonstração de sua integração no ORCID caixa de areia. Isso nos dá a chance de ver as grandes integrações que você construiu e oferecer melhorias no fluxo de trabalho, bem como verificar se todas as integrações atendem às nossas melhores práticas.

Para fornecer uma demonstração de seu sistema, você precisará configurar uma integração funcional com o ORCID caixa de areia que o ORCID equipe pode visualizar. Existem algumas maneiras de compartilhar sua integração de sandbox de trabalho:

1. Recomendado: Demonstração ao vivo: Entre em contato para agendar uma demonstração ao vivo. Forneceremos um software de reunião que permite que você compartilhe sua tela para demonstrar sua integração. Isso também nos dá a oportunidade de aprender mais sobre como seu sistema funciona e como você está explicando os benefícios de seu ORCID integração, para que possamos fornecer um suporte melhor para você e seus usuários.
2. Site de teste: Se o seu site de desenvolvimento for público, envie-nos o URL junto com credenciais de teste (se necessário) para acessar seu sistema e instruções que descrevem como usar o seu sistema ORCID recursos. Forneça documentação adicional para verificar o que não poderíamos ver do usuário final, por exemplo, a versão da API usada, quais dados são armazenados pelo seu sistema, etc.
3. Screencast ou capturas de tela (recomendado para ORCID- sistemas habilitados que requerem uma demonstração): Envie uma gravação ou um conjunto de capturas de tela com descrições explicando e demonstrando claramente como sua integração funciona em cada etapa, incluindo o que acontece se um usuário negar acesso ou desconectar seu iD. Certifique-se de fornecer documentação adicional para verificar tudo o que não poderíamos ver do usuário final, como a versão da API usada e como os dados são armazenados.¬¨‚

Se você estiver usando um dos ORCID- sistemas habilitados que não requerem uma demonstração, você pode diretamente solicitar credenciais de API de membro de produção. Certifique-se de especificar qual sistema (e, se aplicável, versão) você está usando nas notas.

Há uma série de requisitos que esperamos que todas as integrações de membros atendam. O ORCID a equipe garantirá que esses requisitos tenham sido atendidos como parte do processo de revisão da integração. 

• Use OAuth para autenticar ORCID IDs (não permitir que os usuários pesquisem ou digitem ORCID IDs.)
• Inclua um ORCID botão ou link de marca em seu site para iniciar a autenticação do iD.
• Apresente a tela de autorização OAuth de acordo com nosso orientações
• Use HTTPS para URIs de redirecionamento do seu site e assim por diante ORCID Chamadas de API
• Aceite e armazene todos os dados retornados na troca de tokens junto com os dados do usuário em seu sistema
• Use apropriado escopos e métodos de solicitação (por exemplo, chamadas POST para adicionar novas informações e chamadas PUT para atualizar as informações existentes)
• Exibir publicamente o autenticado ORCID IDs. IDs devem ser exibidos seguindo nosso marca registrada e iD orientações de exibição.

Melhores práticas

Certifique-se de que sua integração segue as práticas recomendadas

Você precisará preencher o formulário para registrar um aplicativo cliente. Abaixo está uma visão geral rápida dos campos solicitados:

Notas para ORCID para: Use este campo para permitir ORCID saber se você está usando um sistema de fornecedor, as integrações foram revisadas etc.

Endereço de email do contato: Enviaremos as credenciais para este endereço. Este deve ser o contato com o qual temos trabalhado na integração ou o contato técnico que mantemos para sua organização.

Contato para recebimento de PIN para acesso a credenciais: Enviamos todas as credenciais para você de maneira segura. Enviaremos uma senha de acesso às suas credenciais de API para este contato. Ele precisa ser um contato diferente do contato anterior listado.

Breve descrição de seu aplicativo cliente: Este texto será exibido na tela de autorização com um ícone de ponto de interrogação para seus usuários de integração. É necessária uma breve descrição de sua integração.

URL da página inicial do seu aplicativo: Exibido como um link na lista de organizações confiáveis ​​dentro dos usuários ORCID página de partes confiáveis. Este deve ser um link para sua organização ou para a página principal do seu aplicativo.

URIs de redirecionamento OAuth2 ou URLs de retorno de chamada para o cliente: URL (s) permitido (s) em seu aplicativo da web para onde os usuários retornarão depois de autorizarem o acesso a seus ORCID dados de registro. Todos os URIs de redirecionamento devem ser HTTPS para clientes de servidor de produção (ativos). 

Depois de fazer sua solicitação, um processo manual acontece para emitir suas credenciais e você receberá um e-mail com seu cliente iD e segredo do cliente. Normalmente, essas solicitações são processadas em menos de 48 horas.

Para apoiar o componente social, oferecemos um kit de ferramentas de Recursos de divulgação para ajudá-lo a desenvolver uma campanha para apoiar sua integração e se comunicar com seus pesquisadores:

• O que ORCID é.
• Por que seu sistema coleta IDs e como seu sistema executará tarefas, como atualizar seus registros.
• Por que seus pesquisadores se beneficiarão com a criação de um ORCID iD e conectando seus iDs ao seu sistema.
• Como funciona o dobrador de carta de canal ORCID beneficia a comunidade de pesquisa global mais ampla.

Estaremos construindo continuamente essa “biblioteca” de recursos com base no feedback da comunidade. Se você tiver uma ideia sobre algo que gostaria de ver, não hesite em nos contatar.