PHP

[block:html] { "html": "<p>Nossa API é <a href=\"https://en.wikipedia.org/wiki/Representational_state_transfer\" target=\"_blank\" title=\"Link Externo\">RESTful</a> e responde em <a href=\"http://www.json.org/\" target=\"_blank\" title=\"Link Externo\">JSON</a>. A Gerencianet utiliza <a href=\"http://oauth.net/\" target=\"_blank\" title=\"Link Externo\">OAuth</a> para fornecer acesso autorizado à <abbr title=\"Application Programming Interface\">API</abbr>. Nossa SDK de PHP já está preparada para realizar essa autenticação automaticamente.</p>" } [/block] A seguir, confira os procedimentos para instalação da SDK da Gerencianet em PHP: # Instalando via <a href="https://packagist.org/packages/gerencianet/gerencianet-sdk-php" target="_blank" title="Link Externo">Packagist</a> com o <a href="https://getcomposer.org/" target="_blank" title="Link Externo">Composer</a>: [block:code] { "codes": [ { "code": "$ composer require gerencianet/gerencianet-sdk-php", "language": "text", "name": "Branch 2.x" }, { "code": "$ composer require gerencianet/gerencianet-sdk-php:^1.0.0", "language": "text", "name": "Branch 1.x" } ] } [/block] É importante frisar que as extensões <code>cURL</code>, <code>json</code> & <code>openssl</code> devem estar ativadas. [block:callout] { "type": "warning", "title": "IMPORTANTE", "body": "Atualmente, disponibilizamos duas versões da SDK. A versão 1.x é compatível com versões do PHP superiores à versão 5.4, no entanto, possui alguns componentes desatualizados, como o Guzzle. Caso você tenha uma versão do PHP superior à versão 5.5, sugerimos que instale a versão 2.x da nossa SDK." } [/block] Vá direto ao ponto - utilize o índice abaixo e veja diretamente o que você precisa: 1. [Pré-requisitos](https://dev.gerencianet.com.br/docs/instalacao-sdk-php#section-1-pr-requisitos) 2. [Instalação do Composer em Windows](https://dev.gerencianet.com.br/docs/instalacao-sdk-php#section-2-instala-o-do-composer-em-windows) 3. [Instalação do Composer em Linux](https://dev.gerencianet.com.br/docs/instalacao-sdk-php#section-3-instala-o-do-composer-em-linux) 4. [Instalação biblioteca PHP da Gerencianet sem o Composer](https://dev.gerencianet.com.br/docs/instalacao-sdk-php#section-4-instala-o-biblioteca-php-da-gerencianet-sem-o-composer) 5. [Erros Comuns (curl error 60 ou curl error 77)](https://dev.gerencianet.com.br/docs/instalacao-sdk-php#section-5-erros-comuns-curl-error-60-ou-curl-error-77-) 6. [Vídeo: Instalação da API](https://dev.gerencianet.com.br/docs/instalacao-sdk-php#section-6-v-deo-instala-o-da-api) 7. [Extra: timeout option](https://dev.gerencianet.com.br/docs/instalacao-sdk-php#section-7-extra-timeout-option) # 1. Pré-requisitos Os seguintes pré-requisitos devem ser considerados, de acordo com a *branch* utilizada: [block:parameters] { "data": { "h-0": "Versão da branch", "h-1": "Status", "0-1": "Mantido", "1-1": "Mantido", "h-2": "Packagist", "h-3": "Repositório", "h-4": "Versão do PHP", "0-0": "<a href=\"https://github.com/gerencianet/gn-api-sdk-php/tree/1.x\" target=\"_blank\">1.x</a>", "1-0": "<a href=\"https://github.com/gerencianet/gn-api-sdk-php\" target=\"_blank\">2.x</a>", "0-2": "<code>gerencianet/gerencianet-sdk-php</code>", "1-2": "<code>gerencianet/gerencianet-sdk-php</code>", "0-3": "<a href=\"https://github.com/gerencianet/gn-api-sdk-php/tree/1.x\" target=\"_blank\">v1</a>", "1-3": "<a href=\"https://github.com/gerencianet/gn-api-sdk-php\" target=\"_blank\">v2</a>", "0-4": "<code>> =</code> 5.4 (não é compatível com PHP 7.x)", "1-4": "<code>> =</code> 5.5 (compatível com PHP 7.x)" }, "cols": 5, "rows": 2 } [/block] [block:callout] { "type": "warning", "body": "Para a utilização da biblioteca em PHP, recomendamos a instalação através do <a href=\"https://getcomposer.org/\" target=\"_blank\" title=\"Link Externo\">Composer</a> (gerenciador de dependências).\n\nCaso prefira prosseguir sem o Composer, basta seguir os procedimentos descritos no título [4. Instalação biblioteca PHP da Gerencianet sem o Composer](https://dev.gerencianet.com.br/docs/instalacao-sdk-php#section-4-instala-o-biblioteca-php-da-gerencianet-sem-o-composer).", "title": "Nota:" } [/block] # 2. Instalação do Composer em Windows Instalaremos o Composer no Windows para baixar as nossas bibliotecas. Se preferir, pode seguir <a href="https://getcomposer.org/doc/00-intro.md#installation-windows" target="_blank" title="[link externo]">neste link</a> o tutorial do próprio site oficial do Composer. a) Primeiramente, vamos baixar o instalador do Composer para Windows <a href="https://getcomposer.org/Composer-Setup.exe" target="_blank" title="[link externo]">neste link</a> e, assim que o download for finalizado, execute-o; b) Você precisará informar o caminho de instalação do seu PHP. Caso você esteja utilizando um servidor Wamp, por exemplo, e na instalação surgir uma mensagem relacionada ao arquivo "openssl", você precisará informar seu arquivo <code>*.exe</code> do PHP contido no diretório raiz do Wamp (geralmente em <code>\wamp\bin\php\php.5.6.16\</code>). Cabe frisar que a pasta <code>php.5.6.16</code> refere-se a versão do PHP que está sendo utilizado na confecção dessas instruções, portanto, esse diretório poderá estar com outro nome, conforme a versão do seu PHP; c) Durante a instalação, após indicar o diretório do seu PHP, clique em <code>next</code>. A instalação *poderá* retornar uma mensagem de alerta relacionado à configuração do "openssl". Trata-se de uma mensagem comum que significa que o "openssl" está desabilitado, contudo, vamos resolver de forma rápida e fácil. [block:callout] { "type": "info", "title": "Observação", "body": "Caso não seja retornada nenhuma mensagem sobre o \"openssl\", apenas prossiga para o subtítulo [Baixando as dependências](https://dev.gerencianet.com.br/docs/instalacao-sdk-php#section-baixando-as-depend-ncias), localizado mais abaixo." } [/block] Para habilitar seu "openssl", será necessário alterar o arquivo <code>php.ini</code>. a) Abra o diretório de instalação do seu php e localize o arquivo <code>php.ini</code>; b) Abra o arquivo <code>php.ini</code> em um editor de texto (p. ex: notepad++, sublime, etc) e pressione <code>CTRL + F</code> e pesquise pela palavra “openssl” (sem as aspas); c) O sinal de ponto e vírgula ( ; ) desabilita o arquivo <code>php_openssl.dll</code>. Apague este sinal e ele habilitará o arquivo, ou seja: * Está assim: <code>;extension=php_openssl.dll</code> * Deve ficar assim: <code>extension=php_openssl.dll</code> Agora, salve o documento (pressione <code>CTRL + S</code>) e feche o arquivo. d) A extensão estará habilitada e você poderá continuar com a instalação. Para que a instalação seja atualizada em relação ao procedimento, é importante que você retorne uma tela e depois avance com a instalação normalmente. ## Baixando as dependências a) Crie uma pasta chamada <code>composer</code> no seu diretório Wamp, dentro da pasta <code>www</code>, de forma que tenha essa estrutura: <code>\wamp\www\composer</code> b) Agora, vamos realizar a instalação das dependências. Abra o *prompt* de comando do Windows (cmd) e navegue até o diretório raiz, em <code>\wamp\www\composer</code> c) Vamos executar o comando de instalação das dependências (SDK PHP da Gerencianet) dentro desse diretório. Para tal, execute o comando abaixo: [block:code] { "codes": [ { "code": "$ composer require gerencianet/gerencianet-sdk-php", "language": "text", "name": "Branch 2.x" }, { "code": "$ composer require gerencianet/gerencianet-sdk-php:^1.0.0", "language": "text", "name": "Branch 1.x" } ] } [/block] d) Após a execução do comando, todas as dependências serão instaladas em seu diretório, inclusive a pasta <code>vendor</code> com o arquivo <code>autoload.php</code>. Pronto, agora é só começar a utilizar as soluções de integração da Gerencianet. Veja a tabela com os <a href="https://dev.gerencianet.com.br/docs/tipos-integracoes" title="Link Interno">tipos de integrações</a>. # 3. Instalação do Composer em Linux É possível instalar o Composer em cada projeto (instalação local) ou ter acesso a ele em qualquer parte do sistema (instalação global). Se preferir, pode seguir <a href="https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx" target="_blank" title="[link externo]">neste link</a> o tutorial do próprio site oficial do Composer. Aqui, vamos efetuar a instalação global. Para tal, execute no Terminal o seguinte comando: <pre>$ curl -sS https://getcomposer.org/installer | php $ sudo mv composer.phar /usr/local/bin/composer</pre> ## Arquivo "composer.json" Um dos principais arquivos para se trabalhar com o Composer é o <code>composer.json</code>. É nele que as instruções sobre os pacotes que serão usados no projeto ficam contidas. Este é um arquivo de extensão <code>.json</code> comum que deve ficar na raiz de seu projeto. A diretiva <code>require</code> no arquivo <code>composer.json</code> informa ao Composer quais os pacotes necessários para o projeto - neste caso, o repositório central é o Packagist. Agora, vamos informar ao Composer que a Gerencianet fará parte do gerenciamento de dependências inserindo o conteúdo abaixo no final do arquivo <code>composer.json</code> (que deve ficar na raiz do projeto): [block:code] { "codes": [ { "code": "\"require\": {\n \"gerencianet/gerencianet-sdk-php\": \"2.*\"\n},", "language": "json", "name": "Branch 2.x" }, { "code": "\"require\": {\n \"gerencianet/gerencianet-sdk-php\": \"1.*\"\n},", "language": "json", "name": "Branch 1.x" } ] } [/block] É hora de instalar os pacotes. Vá até o diretório em que está seu projeto no Terminal e execute: <pre>$ composer install</pre> <br> E pronto! O download das dependências irá acontecer automaticamente, estas serão armazenadas em suas respectivas pastas e o Composer continuará com o restante do trabalho ao gerar o arquivo <code>composer.lock</code>. Cabe frisar que, caso você necessite, por exemplo, excluir um pacote, basta deletar sua referência do arquivo <code>composer.json</code> e atualizar o Composer através do seguinte comando: <pre>$ composer update</pre> <br> Dessa forma, o Composer será atualizado e, como não há mais a presença do pacote na diretiva <code>require</code>, ele será imediatamente "desinstalado". ## Resumo: - Instalar o Composer; - Informar, no arquivo <code>composer.json</code>, a SDK da Gerencianet que será instalada; - Executar o comando de instalação no diretório do projeto: <code>$ composer install</code>; - Pronto! # 4. Instalação biblioteca PHP da Gerencianet sem o Composer O uso do Composer (gerenciador de dependências) é recomendável, mas não obrigatório. Caso seja de seu interesse prosseguir sem utilizá-lo, você pode baixar diretamente uma de nossas <em>branches</em>, descompactar e subir a pasta (inclusive o arquivo "autoload.php") para o diretório de seu projeto. Atualmente, oferecemos duas <em>branches</em>, intituladas <code>master</code> e <code>1.x</code>, sendo: - <code>master</code>: utiliza versão recente do guzzle (^6.0.0) e é compatível com versões recentes do PHP (5.5, 5.6, 7.0 e 7.1). Esta é a versão padrão quando se baixa pelo Composer, sendo indicada para todos os projetos. <a href="https://gerencianet.com.br/material/api/php/api_v2.zip" target="_blank" title="Link Externo">Baixe neste link</a>. - <code>1.x</code>: versão anterior da SDK, compatível com PHP 5.4 e 5.5 e utiliza guzzle 5.3.0. <a href="https://gerencianet.com.br/material/api/php/api_v1.zip" target="_blank" title="Link Externo">Baixe neste link</a>. A branch <code>master</code> é a <em>default</em>, porém, você pode instalar a branch <code>1.x</code>. No decorrer desta página você encontrará orientações para as duas versões. Importante reforçar que o conteúdo presente neste .zip é apenas um requisito para que você possa começar a utilizar a SDK em PHP da Gerencianet. Esta pasta por si só não é um "exemplo pronto" de uso da API Gerencianet, mas a SDK em PHP da Gerencianet que permite a utilização da API. # 5. Erros Comuns (curl error 60 ou curl error 77) Os erros a seguir não são da API Gerencianet, mas relacionados à componentes de seu servidor. Confira abaixo os erros mais comuns durante a instalação de nossa API e veja as soluções: ## 5.1) curl error 60 Este erro está relacionado ao *curl* configurado em seu servidor (ou computador) estar exigindo um certificado (https/ssl) local. Geralmente ocorre em servidores Windows ou plataforma Wamp Server, por exemplo. Este erro também pode ser apresentado como <code>CURLE_SSL_CACERT (60) - Peer certificate cannot be authenticated with known CA certificates</code>. Para resolver, vamos configurar para que seu servidor tenha um certificado para testes: 1. Faça o download do arquivo <code>cacert.pem</code> em <a href="http://curl.haxx.se/docs/caextract.html" target="_blank" title="Link Externo">http://curl.haxx.se/docs/caextract.html</a> (não altere o nome do arquivo, deixe como <code>cacert.pem</code>); 1. Faça o download do <code>cacert.pem</code> em <a href="http://curl.haxx.se/docs/caextract.html" target="_blank" title="Link Externo">http://curl.haxx.se/docs/caextract.html</a> (copie e cole o texto todo em um arquivo chamado <code>cacert.pem</code>); 2. Salve este arquivo <code>cacert.pem</code> em qualquer lugar do seu sistema, de preferência na pasta do servidor (<code>C:\Wamp</code>, caso esteja utilizando-o); 3. Abra seu arquivo de configuração do PHP (para o WampServer, normalmente este arquivo está localizado em <code>C:\wamp\bin\php\phpX.Y.Z</code>, onde <code>X.Y.Z</code> é a versão do seu PHP) e faça a alteração a seguir: Procure pela linha abaixo: <pre>;curl.cainfo =</pre> <br> Mude para: <pre>curl.cainfo = "C:\caminho\onde\voce\salvou\seu\certificado\cacert.pem"</pre> <br> 4. Reinicie seu servidor Apache; 5. Teste novamente. Lembrando que estas configurações foram necessárias porque seu servidor está exigindo um certificado local (erro: <code>URL error: 60 - SSL certificate problem: unable to get local issuer certificate</code>) e sua máquina/servidor não possui. ## 5.2) curl error 77 Esse erro está associado ao caminho do certificado que está definido de forma incorreta no arquivo <code>php.ini</code>. Atualmente, deve estar assim: <pre>curl.cainfo = "C:\xampp\php\cacert.pem"</pre> <br> Deverá alterar e de forma que fique assim: <pre>curl.cainfo = "C:\xampp\php\cacert.pem.txt"</pre> <br> Adicionalmente, caso o método acima não solucione, outra possível solução está relacionada a referência do certificado. Ele pode até já estar instalado local em sua máquina, mas os certificados podem estar localizados em <code>/etc/ssl/certs/ca-certificates.crt</code> ao invés de <code>/etc/pki/tls/certs/ca-bundle.crt</code>. Neste caso, bastaria definir a variável de ambiente <code>CURL_CA_BUNDLE</code> para o caminho correto. # 6. Vídeo: Instalação da API Pensando em oferecer novos meios de transmitir informações, a Gerencianet disponibiliza os vídeos a seguir com o objetivo de explicar, de maneira clara e objetiva, como instalar o Composer no sistema operacional Windows e Linux. ## Instalando o Composer via Windows [block:html] { "html": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/bu9tUI3dHwI\" frameborder=\"0\" allowfullscreen></iframe>" } [/block] <br> ## Instalando o Composer via Linux [block:html] { "html": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/uQFhNJhbzdg\" frameborder=\"0\" allowfullscreen></iframe>" } [/block] <br> [block:callout] { "type": "info", "body": "Para acesso as demais aulas, de outros assuntos, acesse a página <a href=\"https://dev.gerencianet.com.br/docs/curso-online-gerencianet\" title=\"Link Interno\">Curso Online de Integrações</a>.", "title": "DICA" } [/block] <br> <hr> # 7. Extra: timeout option Este atributo está presente na SDK de PHP e permite que você defina no *request* do Guzzle em quanto tempo você quer que a resposta seja retornada. Para detalhes de como utilizar, consulte <a href="https://github.com/gerencianet/gn-api-sdk-php#getting-started" target="_blank" title="Link Externo">nosso repositório do Github</a>.

Documentação API Gerencianet - Boleto Registrado e Pagamentos Online

Visão Geral da API

Ambiente de Testes

Instalação da API (SDK's)

Pagar com Boleto

Pagar com Cartão

Assinaturas (Recorrência)

Carnês

Link de Pagamento

Marketplace

Checkout via Ligthbox

Notificações (callbacks)

Módulos e Plugins

Exemplos de Integrações

Vídeos sobre Integrações

Outros Recursos da API

Autenticação e Endpoints

Fluxos de Processos

Últimas Novidades

Dúvidas?