ORCID oferece várias APIs que permitem que seus sistemas se conectem ao ORCID registro, incluindo leitura e gravação para ORCID registros. Algumas funções da API estão disponíveis gratuitamente para qualquer pessoa (API pública); outros estão disponíveis apenas para ORCID organizações membros (API de membro e membro premium) Qualquer pessoa está livre para testar qualquer uma de nossas APIs em nosso servidor de teste sandbox.
Antes de começar
Ao iniciar seu planejamento de integração, você deve considerar:
- O que você quer fazer com o ORCID API— visite nosso fluxos de trabalho.
- Se sua organização é já um ORCID membro ou é planejando se tornar um. Apenas ORCID membros podem adicionar itens a ORCID Registros.
- Se você está usando um sistema que já suporta ORCID. Se estiver, pode ser tão simples quanto configurar seu sistema para trabalhar com ORCID.
- Como você se comunicará com seus pesquisadores sobre as mudanças que estão sendo implementadas, o que você precisará deles, os benefícios para eles e o que eles precisarão fazer. Visite nosso Recursos de divulgação página para idéias sobre como construir uma campanha de comunicação em torno de sua nova integração.
Registre-se para credenciais de sandbox e crie um teste ORCID iD
Exigimos que você primeiro crie ferramentas que interajam com do ORCID sandbox para evitar afetar quaisquer dados no registro de produção durante o teste - ou em seus próprios sistemas.
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.
Determine as permissões de usuário de que você precisa
O ORCID A API de membro pode ser usada para ler, adicionar ou atualizar informações sobre um usuário ORCID registro - você só precisa solicitar permissão de seus pesquisadores. Os escopos de que você precisa afetarão amplamente qual API melhor se adapta ao seu sistema.
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.
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 Community.
- 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.
Certifique-se de que você pode armazenar os dados com segurança
É importante que seu sistema seja capaz de armazenar informações de maneira segura.
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.
Verifique com o ORCID equipe para demonstrar como seu aplicativo funciona
Antes que sua integração possa ir ao ar no ORCID registro de produção, nossa equipe de engajamento verificará se tudo o que você construiu no sandbox também funcionará na produção. Se você estiver usando um sistema com ORCID suporte, esta etapa pode ser ignorada.
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:
- 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.
- 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.
- 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.
Solicite credenciais no servidor de produção
Você pode se inscrever para credenciais de membro API, uma vez que sua integração foi revisada pelo ORCID equipe ou se você estiver usando um sistema de provedor de serviços que possui um ORCID integração.
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.
Transfira seu aplicativo para o ORCID Registro de Produção
Assim que tiver suas credenciais, você estará pronto para colocá-lo ao vivo. Se você gostaria de testar sua integração antes de lançar ao público, use o próprio testador ORCID registro ou de um colega ORCID registro.
Lance - e deixe todos saberem
Colocar um aplicativo no ar não é a última etapa - você precisa continuar a se comunicar com seus usuários para que eles saibam como conectar seus ORCID iD ao seu sistema de forma rápida e fácil. As integrações eficazes contêm tanto um componente técnico (que este guia cobre) quanto um componente social. Os pesquisadores precisam ser informados sobre o que ORCID é, por que você está solicitando acesso a seus ORCID registro e o que você fará com seus dados.
- Crie um cronograma de comunicação: certifique-se de que as partes interessadas estejam cientes de sua ORCID projeto bem antes do lançamento.
- Use uma combinação de comunicações de cima para baixo e de baixo para cima.
- Promova seu ORCID integração frequente e para diferentes públicos.
- Crie recursos locais para oferecer suporte aos seus usuários, como FAQs, libguides, páginas da web, tutoriais e vídeos.
- Indique uma pessoa de contato local para ORCID-Perguntas relacionadas.
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 Quê 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.