O que é um formulário de doação?
Os formulários de doação são uma infraestrutura que permite receber doações integrando-os no seu próprio site. Pode criar um formulário de doação acedendo à secção Doações > Formulário de Doação no menu à esquerda.
O que mudou em relação ao V1?
Os formulários de doação agora podem funcionar tanto incorporados no seu site quanto como pop-ups.
Não é necessário enviar parâmetros como valor, doação regular, moeda, etc.
A estrutura de Notificação de Resultado (Callback) foi alterada de JS para HTTP POST.
A testagem foi facilitada.
O endereço do site deve ser inserido como o endereço completo.
Adicionada a capacidade de oferecer opções de valor predefinidas.
Mensagens de erro adicionadas à consola do desenvolvedor.
O que deve ser considerado ao criar?
O ponto mais importante a ter em conta ao criar um formulário de doação é que deve introduzir o endereço completo do site onde irá utilizar o formulário. Ao introduzir o endereço, deve incluir https:// no início. E se o seu site tiver várias versões, deve torná-lo único.
Os formulários de doação funcionam apenas com HTTPS em ambiente de produção. Pode testar com HTTP em ambiente de teste.
Por exemplo;
https://www.alanadi.org/bagis/genel-bagis
Se o seu site funciona tanto como https://www.alanadi.org, quanto como https://alanadi.org, por favor, escolha apenas um e redirecione o domínio não escolhido para o outro.
Integração com o site
AVISO! Esta integração requer conhecimento de software. É necessário ter domínio básico de HTML e Javascript. Se não dominar estes tópicos, por favor, utilize as nossas páginas de doação padrão.
Primeiramente, o jQuery deve estar instalado no seu site. Se o jQuery não estiver carregado, o Fonzip irá gerar um erro.
Em segundo lugar, se o valor do cabeçalho Referrer-Policy da sua página for no-referrer , o Fonzip irá gerar um erro. É necessário usar um valor diferente deste.
Pode aceder às informações básicas de integração na secção Doações > Formulários de Doação > Ações > Informações de Integração.
<script type="text/javascript"> !function(e,t,s,n,c){e.fzv2||(n=e.fzv2=function(){n.callMethod?n.callMethod.apply(n,arguments):n.queue.push(arguments)},e._fzv2||(e._fzv2=n),(n.push=n).loaded=!0,n.version="1.0",n.queue=[],fzv2.script_element=t.createElement(s),fzv2.script_element.async=!0,fzv2.script_element.src="https://s.fonzip.com/js/fzembed.v1.js",(c=t.getElementsByTagName(s)[0]).parentNode.insertBefore(fzv2.script_element,c))}(window,document,"script"); </script>Adicione o nosso script à página da seguinte forma.
Se deseja executar o formulário relevante como incorporado, dentro do bloco <script>
fzv2("embed", "ANAHTAR", "EKLENECEK-ID");Se deseja executar como popup , dentro do bloco <script>
fzv2("popup", "ANAHTAR", "BUTON-ID");Deve adicionar o código.
Se deseja iniciar um formulário incorporado, mas que permaneça oculto:
fzv2("embed", "ANAHTAR", "EKLENECEK-ID", true);
Basta enviar o 4º parâmetro como true.
A tag HTML onde o formulário incorporado será adicionado deve ser <body>, <div> ou <section>.
A tag HTML que irá acionar o formulário popup deve ser <button> ou <a>.
Os formulários de doação funcionam automaticamente no idioma do navegador. Se o parâmetro lang estiver definido no bloco html da sua página web, ele considerará esse idioma. Se você quiser forçar um idioma específico, antes das funções embed e popup;
fzv2("lang", "IDIOMA")Pode fazer a seleção de idioma da seguinte forma.
Idiomas válidos
tr (Turco)
en (Inglês)
de (Alemão)
fr (Francês)
es (Espanhol)
it (Italiano)
pt (Português)
nl (Holandês)
ru (Russo)
Transferência de Dados para o Formulário
Se deseja adicionar um valor predefinido ao formulário popup, pode adicionar as seguintes propriedades ao botão correspondente. Ou pode fornecer transferência de dados para qualquer formulário a qualquer momento com a função "data". Pode usar a função "data" removendo a propriedade "fz-data". Por exemplo;
fzv2("data", "embed", "KEY", "currency", "USD")Propriedades | Descrição | Valor |
fz-data-currency | Moeda | ISO 4217 |
fz-data-recurring | Recorrente / Única | true|false |
fz-data-amount | Valor da Doação | Número |
fz-data-recurring-limit | Doação Recorrente com Limite | 0 - 60 |
fz-data-donor-type | Tipo de Doador | corporate|personal |
fz-data-first-name | Nome / Nome da Instituição | Alfanumérico{0,200} |
fz-data-last-name | Sobrenome | Alfanumérico{0,200} |
fz-data-email | Email{0,200} | |
fz-data-phone | Telefone | Telefone{0,25} |
fz-data-birthday | Data de Nascimento | Data (Dia/Mês/Ano) |
fz-data-city | Cidade | Alfanumérico{0,200} |
fz-data-district | Distrito | Alfanumérico{0,200} |
fz-data-address | Endereço | Alfanumérico |
fz-data-tckno | N.º ID Turco / N.º de Contribuinte | Número{11,13} |
fz-data-details | Detalhes | Alfanumérico{0,300} |
fz-data-referring | Em nome de alguém | true|false |
fz-data-referring-name | Pessoa em cujo nome a doação é feita | Alfanumérico{0,100} |
fz-data-referring-email | E-mail da pessoa em cujo nome a doação é feita | Email{0,100} |
fz-data-news-via-phone | Permissão de Contacto por Telefone | true|false |
fz-data-news-via-sms | Permissão de Contacto por SMS | true|false |
fz-data-news-via-email | Permissão de Contacto por E-mail | true|false |
fz-data-fundraising-campaign-id | Campanha de Angariação de Fundos | Número |
fz-data-name-hidden | Nome oculto | true|false |
fz-data-amount-visible | Valor da doação visível | true|false |
fz-data-api-tracking-id | ID de Rastreamento da API | Alfanumérico{0,20} |
fz-data-custom-parameters | Parâmetros Personalizados |
|
Se as propriedades adicionadas preencherem todo o formulário, o formulário avança automaticamente para as próximas etapas. Ou seja, se houver informações de valor, ele é automaticamente direcionado para a secção de informações do doador; e se houver informações do doador, é direcionado diretamente para a secção de informações do cartão.
Parâmetros Personalizados
Pode utilizar a funcionalidade de parâmetros personalizados para transferir para o Fonzip qualquer campo que não esteja definido no Fonzip, mas que utilize ao receber doações.
Criação de Parâmetros Personalizados
Pode criar parâmetros clicando em Adicionar parâmetro na secção Parâmetros Personalizados, localizada na parte inferior da página de criação/edição do formulário de doação.
No ecrã que aparece, escreva o valor da chave que irá passar no parâmetro na secção Nome do campo, e o valor que deseja que apareça no sistema na secção Descrição, e guarde.
Por exemplo, criamos um parâmetro com o nome de campo recibo e a descrição Pedido de Recibo. Se o doador solicitar um recibo adicional, preencheremos este campo como "Sim", caso contrário, como "Não".
Nota: Não há restrições nos valores a serem passados nos parâmetros.
Você deve passar uma string JSON para a propriedade fz-data-custom-parameters. Exemplo
<button id="fonzip-button" fz-data-custom-parameters="{'makbuz': 'makbuz_degeri'}"/>Após a conclusão da doação, se a opção de recibo for selecionada, você poderá ver os dados relevantes nos detalhes da doação, conforme abaixo.
Alertas de Parâmetros Personalizados
O envio de um parâmetro não definido nas configurações do formulário causará um erro no sistema.
O envio de dados em um formato diferente de JSON causará um erro no sistema.
Ao alterar/excluir o nome de campo de um parâmetro que você adicionou anteriormente, você pode perder os dados nas doações correspondentes.
Política de Segurança de Conteúdo
Se você está protegendo seu site com CSP para fins de segurança, precisa adicionar as seguintes definições.
script-src: https://s.fonzip.com
connect-src: https://fonzip.com
style-src: https://s.fonzip.com
img-src: https://s.fonzip.com https://cdn.fonzip.com
frame-src: https://fonzip.com
Se você está usando Nonce, pode definir o valor Nonce antes da função embed ou popup
fzv2("nonce", "NONCE-VALUE");Dessa forma.
Notificações de Retorno de Resultado
Se não definir um URL de Retorno de Resultado ao criar/editar o seu formulário, o Fonzip mostrará o ecrã de resultado padrão de sucesso/falha e, em seguida, redirecionará o doador para o Endereço de Página que definiu.
Se o definiu, o resultado da transação será enviado como HTTP POST para o URL que definiu. Pode encontrar os parâmetros a serem enviados na tabela abaixo.
Se houver proteção CSRF contra solicitações POST feitas no URL que você definiu, essa proteção precisa ser removida. Como alternativa, você pode fornecer uma verificação no parâmetro hash para verificar se a solicitação veio do Fonzip. É altamente recomendável que você faça esta verificação.
Cálculo do Parâmetro Hash
Para calcular o parâmetro hash, o conversation_id e a Secret Key são hashados com o algoritmo sha256 e convertidos para base 16.
hash = sha256(conversation_id + Secret Key)
Exemplo:
conversation_id = 123456
Secret Key = gizlianahtar
hash = sha256(12345gizlianahtar) = 823b922b1bf0560b383e50e57e265172757d7718a85cd87497820ae1530e44f6
Parâmetro | Descrição |
donation_id | N.º de Registo |
donor_type | Tipo de Doador |
name | Nome Completo do Doador |
first_name | Nome / Nome da Instituição |
last_name | Sobrenome |
phone | Telefone |
birthday | Data de Nascimento |
city | Cidade |
district | Distrito |
address | Endereço |
details | Detalhes |
tckno | N.º de Identidade Turco / N.º de Contribuinte |
referring | Em nome de alguém |
referring_name | Pessoa em cujo nome a doação é feita |
referring_email | E-mail da pessoa em cujo nome a doação é feita |
recurring | Recorrente / Única |
recurring_limit | Doação Recorrente com Limite |
recurring_order_id | N.º de Instrução de Doação Recorrente |
category_id | ID da Categoria de Doação |
category | Categoria de Doação |
name_hidden | Nome oculto |
amount_visible | Valor da doação visível |
custom_parameters | Parâmetros Personalizados |
donation_form_id | ID do Formulário de Doação |
donation_form | Formulário de Doação |
news_via_phone | Permissão de Contacto por Telefone |
news_via_sms | Permissão de Contacto por SMS |
news_via_email | Permissão de Contacto por E-mail |
lang | Idioma |
complete_date | Data da Transação (ISO 8601) |
amount | Valor da Doação |
currency | Moeda (ISO 4217) |
ip_address | Endereço IP |
payment_status | Estado do Pagamento
3: Sucesso
5: Falha |
payment_method | Método de Pagamento
0: Cartão
8: BKM Express
9: iDEAL
10: Pagar com İyzico |
payment_settings_id | ID do POS Virtual |
api_tracking_id | ID de Rastreamento da API |
order_id | N.º de Pedido do Banco |
conversation_id | ID de Rastreamento |
last_four | Últimos 4 Dígitos do Cartão |
bin_number | Número BIN do Cartão |
transaction_id | N.º de Transação do Banco |
provision_no | N.º de Provisão Bancária |
auth_code | N.º de Aprovação |
reference_id | N.º de Referência |
error_code | Código de Erro |
error_text | Mensagem de Erro |
hash | Hash |
Configurações Avançadas
Se deseja remover um formulário da sua página, precisa usar a função "destroy".
fzv2("destroy", "popup", "ANAHTAR")
fzv2("destroy", "embed", "ANAHTAR")
Se deseja mostrar um formulário oculto, pode usar a função "show".
fzv2("show", "popup", "ANAHTAR")
fzv2("show", "embed", "ANAHTAR")
Se deseja ocultar um formulário visível, pode usar a função "hide".
fzv2("hide", "popup", "ANAHTAR")
fzv2("hide", "embed", "ANAHTAR")
Se deseja receber feedback quando um formulário popup é fechado, precisa definir a função que deseja que seja chamada com a função "callback".
function close_function(ANAHTAR) {
console.log("popup closed", ANAHTAR)
}
fzv2("callback", "popup", "ANAHTAR", "close", close_function)
Transição de V1 para V2
Primeiro, crie um formulário de doação para V2. Como ele funcionará como um popup, assim como antes, na sua página
fzv2("popup", "ANAHTAR", "BUTON-ID");você precisa iniciá-lo assim.
Você pode refletir os eventos de alterações de valor, recorrência e moeda para as propriedades que começam com fz-data-* antes de iniciar as operações feitas com o popup do V1, enviando os parâmetros de valor, recorrência e moeda com fz.bagis().
Por exemplo, anteriormente
<script>
function bagis_yap() {
var miktar = document.getElementById("miktar").value;
var duzenli = document.getElementById("duzenli").checked;
fz.bagis({
amount: miktar,
recurring: duzenli
//Outros parâmetros
})
}
</script>
<input id="miktar" type="number" step="0.01" placeholder="Valor da Doação"/>
<input id="duzenli" type="checkbox" />
<label for="duzenli">Fazer Doação Regular</label>
<a onclick="bagis_yap();" href="javascript:;>Fazer Doação</a>
Em vez de obter valores como estes e chamar fz.bagis() ao clicar no botão, você deve refletir as alterações dos valores correspondentes nas propriedades fz-data-* quando eles mudarem. Por exemplo
<script>
document.getElementById("miktar").addEventListener("change", function(event) {
this.setAttribute("fz-data-amount", this.value);
});
document.getElementById("duzenli").addEventListener("change", function(event) {
this.setAttribute("fz-data-recurring", this.checked);
})
</script>
<input id="miktar" type="number" step="0.01" placeholder="Valor da Doação"/>
<input id="duzenli" type="checkbox" />
<label for="duzenli">Fazer Doação Regular</label>
<a id="fonzip-button" fz-data-amount="" fz-data-recurring="">Fazer Doação</a>