API

Importante: O público alvo deste tópico é o pessoal técnico e informático da sua organização. 

Funcionalidade API  

O API do Volunteer Impact permite-lhe obter dados de perfil do Volunteer Impact para serem utilizados num programa ou aplicação externa. 

Exemplo de Cliente API 

Está disponível um exemplo de Cliente API (implementado em C#) em: https://github.com/BetterImpact/ApiClient. 

Autenticação 

O nosso API utiliza autenticação básica HTTP em detrimento de HTTPS. 

Endpoints API: Listagem de Utilizadores 

• Coletivo: https://api.betterimpact.com/v1/enterprise/users/ 

• Organização: https://api.betterimpact.com/v1/organization/users/ 

Parâmetros: 

Nenhum. 

Parâmetros de Pesquisa: 

Parâmetro	Descrição	Valores Válidos / Pré-definidos
page_size	O número de resultados por página.	1 to 250    Default: 100
page_number	O número de página a obter.	1 to *    Default: 1
include_  custom_fields	Incluir ou não campos personalizados nos resultados	“true” or “false”    Default: “true”
include_  qualifications	Incluir ou não qualificações nos resultados	“true” or “false”    Default: “true”
include_  memberships	Incluir ou não informação sobre os membros nos resultados.	“true” or “false”    Default: “true”
include_  verified_volunteers_  background_check_  results	Incluir ou não informação de inquéritos realizados a Pessoas Voluntárias Verificadas nos resultados.	“true” or “false”    Default: “true”
organization_ids	APENAS ENDPOINT DO COLETIVO. Lista separada por vírgulas de IDs da organização para a qual devem ser devolvidos resultados. Isto irá devolver todos os utilizadores que pertençam a qualquer uma das organizações aprovadas.	Comma separated list of valid organization IDs (integers)    Default: All organizations in the enterprise.
modules	Uma lista separada por vírgulas dos membros do módulo que gostaria de devolver.	You may use the full, or short form for the module names:  volunteer / vol  client / cli  member / mem  donor / don  administrator / admin    Default: All modules. When left out, the modules will be inferred by any {module}_status parameters specified.
admin_status	Uma lista separada por vírgulas dos estatutos administrativos à qual gostaria de restringir os resultados.	active  inactive    Default: All statuses.
client_status	Uma lista separada por vírgulas dos estatutos de cliente à qual gostaria de restringir os resultados.	applicant  inprocess / in_process  accepted  inactive  archived    Default: All statuses.
donor_status	Uma lista separada por vírgulas dos estatutos dos doadores à qual gostaria de restringir os resultados.	prospect  active  inactive  archived    Default: All statuses.
member_status	Uma lista separada por vírgulas dos estatutos dos membros à qual gostaria de restringir os resultados.	applicant  inprocess / in_process  accepted  inactive  archived    Default: All statuses.
volunteer_status	Uma lista separada por vírgulas dos estatutos de pessoa voluntária Uma lista separada por vírgulas dos estatutos dos membros à qual gostaria de restringir os resultados. gostaria de se limitar.     Pode utilizar “arquivados” para incluir todos os subtipos arquivados e “inativos” para incluir todos os subtipos inativos.	applicant  inprocess  accepted  inactiveshortterm  (or: inactive_short_term)  inactivelongterm  (or: inactive_long_term)  archiveddidntstart  (or: archived_didnt_start)  archivedrejected  (or: archived_rejected)  archiveddismissed  (or: archived_dismissed)  archivedmoved  (or: archived_moved)  archivedquit  (or: archived_quit)  archiveddeceased  (or: archived_deceased)  archivedother  (or: archived_other)    Default: All statuses.
updated_since	Este parâmetro restringirá os resultados a perfis que tenham sido alterados desde a data especificada.	DateTimes are required to be in ISO 8601 format (using the format string: “yyyy’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffK”). Please see this documentation for more information: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier.    Default: Empty. Will return all profiles regardless of their last update.

Parâmetros de resposta: 

Propriedade	Tipo	Descrição
Cabeçalho	Objeto. Ver abaixo as propriedades	Informação de cabeçalho relacionada com a paginação e o conjunto de resultados.
Utilizadores	Array de objetos do utilizador. Ver secção de utilizador único para descrições de propriedade.	Uma lista dos utilizadores que correspondem aos parâmetros da pesquisa.

Propriedades do Cabeçalho: 

Propriedade	Tipo	Descrição
first_item_on_page	integer	O índice/index baseado em 1 do primeiro item da página devolvida da recolha de utilizadores.
has_next_page	boolean	True se houverem mais páginas a serem devolvidas
has_previous_page	boolean	True se houverem páginas antes da recolha de utilizadores devolvida.
is_first_page	boolean	True se a recolha devolvida é a página 1.
is_last_page	boolean	True se a recolha devolvida é a última página
last_item_on_page	integer	O índice/index baseado em 1 do último item da página devolvida da recolha de utilizadores.
page_count	integer	O número de páginas da colecção de utilizadores.
page_number	integer	O número da página devolvida.
page_size	integer	O tamanho da página devolvida.
total_items_count	integer	O número total de utilizadores que correspondem aos parâmetros de consulta em todas as páginas.

Endpoints API: Utilizador Único 

Coletivo: https://api.betterimpact.com/v1/enterprise/users/{user_id} 

Organização: https://api.betterimpact.com/v1/organization/users/{user_id} 

Parâmetros: 

Parâmetro	Descrição
{user_id}	A identificação do utilizador que deseja recuperar

Parâmetros de consulta: 

Nenhum 

Resposta: 

Um único documento de utilizador, contendo os seus próprios campos, bem como documentos de membros, documentos de campos personalizados, e documentos de qualificações. 

• As qualificações só serão incluídas se as suas credenciais de utilizador API derem acesso ao módulo de Pessoa Voluntária. 

• Os campos personalizados só serão incluídos se as suas credenciais de utilizador API derem acesso a pelo menos um módulo especificado no campo personalizado (a intersecção entre os seus módulos e os do campo personalizado). 

Propriedades do Utilizador: 

Propriedade	Tipo	Descrição / Notas
user_id	integer	Identificação de utilizador única
first_name	string	Primeiro nome
last_name	string	Último nome
legal_first_name	string	Legal first name
middle_name	string	Nome do meio
title	string	Título (saudação)
suffix	string	Sufixo
address_line_1	string	1º Endereço de  Morada
address_line_2	string	2º Endereço de  Morada
city	string	Cidade
zip_code	string	Código de Postal / Apartado
state	string	Distrito / Localidade
country	string	País
email_address	string	Endereço de e-mail
secondary_email_address	string	Endereço de e-mail secundário
mobile_email_address	string	Endereço de e-mail móvel
home_phone	string	Número de telefone de casa
work_phone	string	Número de telefone do trabalho
work_phone_ext	string	Extensão do número de telefone de trabalho
cell_phone	string	Número de telemóvel
phone_preference	string	Preferência telefónica
twitter_username	string	Nome de utilizador no Twitter
linkedIn_profile_url	string	URL de perfil no LinkedIn
Instagram_username	string	Nome de utilizador Instagram
username	string	Nome de utilizador
birthday	string	Dia de anos em formato ISO 8601 UTC (pode ser nulo)
date_created	string	O perfil de data foi criado no formato ISO 8601 UTC
date_updated	string	O perfil de data foi actualizado pela última vez no formato ISO 8601 UTC
region	string	Nome local da região
region_code	string	Código linguístico para região
is_group	boolean	Será que este perfil representa um grupo
group_name	string	Nome do grupo
photo_url_scaled	string	URL de uma versão em escala reduzida da fotografia do utilizador
photo_url_original	string	URL da fotografia original do utilizador
timeclock_qr_code_url	string	URL da imagem do código QR do utilizador
memberships	array de objetos dos membros	Ver abaixo as propriedades
custom_fields	array de objetos de campos personalizados	Ver abaixo as propriedades
qualifications	array de objetos de qualificação	Ver abaixo as propriedades
background_check_results	array de objetos de inquéritos	Ver abaixo as propriedades

Propriedades dos membros: 

Propriedade	Tipo	Descrição / Notas
organization_member_id	integer	Identificador único do objecto de adesão
organization_id	integer	Identificação da Organização
organization_name	string	Nome da Organização
date_created	string	Data em que a adesão foi criada em formato ISO 8601 UTC
date_updated	string	Data de adesão foi atualizada em formato ISO 8601 UTC
is_administrator	boolean	Verdadeiro se o utilizador faz parte do módulo administrador nesta organização
administrator_status	string	Estado localizado do utilizador no módulo de administrador (pode ser nulo)
administrator_type	string	Tipo localizado (Ilimitado, Módulo, Limitado) de administrador (pode ser nulo)
is_client	boolean	Verdadeiro se o utilizador faz parte do módulo cliente nesta organização
client_status	string	Estado localizado do utilizador no módulo de cliente (pode ser nulo)
client_date_joined	string	Data de adesão como cliente no formato ISO 8601 UTC (pode ser nulo)
client_last_status_change	string	Data da última alteração ao estatuto de cliente no formato ISO 8601UTC (pode ser nulo)
donor_date_joined	string	Data de adesão como doador no formato ISO 8601 UTC (pode ser nulo)
donor_last_status_change	string	Data da última alteração do estatuto de doador no formato ISO 8601UTC (pode ser nulo)
member_date_joined	string	Data de adesão como membro no formato ISO 8601 UTC (pode ser nulo)
member_last_status_change	string	Data da última alteração ao estatuto de membro no formato ISO 8601UTC (pode ser nulo)
is_donor	boolean	Verdadeiro se o utilizador faz parte do módulo de doador nesta organização
donor_status	string	Estado localizado do utilizador no módulo de doador (pode ser nulo)
is_member	boolean	Verdadeiro se o utilizador faz parte do módulo de membros nesta organização
member_status	string	Estado localizado do utilizador no módulo de membro (pode ser nulo)
is_volunteer	boolean	Verdadeiro se o utilizador faz parte do módulo de pessoa voluntária nesta organização
volunteer_status	string	Estado localizado do utilizador no módulo de pessoa voluntária (pode ser nulo)
volunteer_inactive_status_reason	string	Motivo de estatuto inativo de Pessoa Voluntária (pode ser nulo)
volunteer_archived_status_reason	string	Motivo pelo qual o estatuto de pessoa voluntária está arquivado (pode ser nulo)
volunteer_last_status_change	string	Data da última alteração do estatuto de pessoa voluntária no formato ISO 8601UTC (pode ser inexistente)
volunteer_notes	string	Notas da Pessoa Voluntária (pode ser nulo)
volunteer_application_form	integer	Número do Formulário de Candidatura da Pessoa Voluntária (pode ser nulo)
volunteer_date_joined	string	Data de adesão como pessoa voluntária no formato ISO 8601 UTC (pode ser nulo)
volunteer_total_hours	number	Total de horas registadas para a pessoa voluntária

Propriedades do Campo Personalizado: 

Propriedade	Tipo	Descrição / Notas
type	string / constant	Tipo de campos personalizados:  yes_no  short_text  number  long_text  file  drop_down  date  check_box
value  (varies based on type property)	yes_no (boolean)    short_text (string)    number (number)    long_text (string)    file (string)    drop_down (string)    date (string)	True = yes, False = No      string      Pode ser decimal      string      URL do recurso do ficheiro na API    Texto de valor selecionado      Data no formato ISO 8601 UTC
value_id	integer	Apenas para campos personalizados do tipo drop_down (a identificação do valor selecionado)
custom_field_id	integer	Identificação do Campo Personalizado
custom_field_name	string	Nome do Campo Personalizado
custom_field_category_id	integer	Identificação da Categoria do Campo Personalizado (pode ser nulo)
custom_field_category_name	string	Nome da Categoria do Campo Personalizado

Propriedades da Qualificação 

Propriedade	Tipo	Descrição / Notas
qualification_id	integer	Identificação da Qualificação
qualification_name	string	Nome da Qualificação
qualification_expires	boolean	True se a qualificação é uma qualificação a expirar
value	string	Texto do nível de qualificação selecionado
value_id	integer	Identificação do nível de qualificação selecionado
expiry_date	string	Data de validade no formato ISO 8601 UTC (pode ser nula)

Propriedades do Inquérito: 

Propriedade	Tipo	Descrição / Notas
result_type_id	integer	Identificação do tipo de resultado
result_type_name	string	Nome do tipo de resultado
result_type_expires	boolean	True se o tipo de resultado for um tipo de resultado expirado
state	string	Verificação do estado atual dos inquéritos a esta pessoa
needs_review_reason	string	String containing the reason that this person needs review (blank if state is not needs review)
effective_date	date	Data em que este inquérito está efetivamente em vigor
expiry_date	date	Data em que este inquérito deixa de estar em vigor (nulo caso não expire)

Ficheiros do Campo Personalizado 

Coletivo: https://api.betterimpact.com/v1/enterprise/users/{user_id}/custom_fields/{user_custom_field_id}/file 

Organização: https://api.betterimpact.com/v1/organization/users/{user_id}/custom_fields/{user_custom_field_id}/file 

• Estes URLs são especificados como o valor do campo personalizado quando os campos personalizados são recuperados como parte de um único, ou vários utilizadores. 

Parâmetros: 

Parâmetro	Descrição
{user_id}	A identificação do utilizador ao qual pertence o ficheiro do campo personalizado
{user_custom_field_id}	A identificação do valor do campo personalizado do utilizador

Parâmetros da Consulta: 

Nenhum. 

Resposta: 

O ficheiro que foi solicitado como um fluxo de bytes.