Português | Inglês
SDK em PHP para integração com a API da Gerencianet. Para mais informações sobre parâmetros e valores, consulte a documentação da Gerencianet.
Ir para:
- Requisitos
- Testado com
- Instalação
- Começando
- Executar exemplos
- Guia de versão
- Documentação Adicional
- Licença
- PHP >= 7.2
- Guzzle >= 7.0
- Extensão ext-simplexml
PHP 7.2, 7.4 e 8.0
Clone este repositório e execute o seguinte comando para instalar as dependências
$ composer install
Se você já tem um projeto gerenciado com Composer, inclua a dependência em seu arquivo composer.json
:
...
"require": {
"gerencianet/gerencianet-sdk-php": "^4"
},
...
Ou baixe este pacote com Composer:
$ composer require gerencianet/gerencianet-sdk-php
Requer o módulo e os namespaces:
require __DIR__ . '/vendor/autoload.php';
use Gerencianet\Gerencianet;
Embora as respostas dos serviços da web estejam no formato json, a SDK converterá qualquer resposta do servidor em array. O código deve estar dentro de um try-catch, e podem ser tratadas da seguinte forma:
try {
/* code */
} catch(GerencianetException $e) {
/* Gerencianet's api errors will come here */
} catch(Exception $ex) {
/* Other errors will come here */
}
Para começar, você deve configurar os parâmetros no arquivo config.json
. Instancie as informações client_id
, client_secret
para autenticação e sandbox
igual a true, se seu ambiente for Homologação, ou false, se for Produção. Se você usa cobrança Pix, informe no atributo pix_cert
o diretório relativo e o nome do seu certificado no formato .pem.
Veja exemplos de configuração a seguir:
Instancie os parâmetros do módulo usando client_id, client_secret, sandbox igual a true
e pix_cert como o nome do certificado de homologação:
$options = [
'client_id' => 'client_id',
'client_secret' => 'client_secret',
'pix_cert' => '../certs/developmentCertificate.pem',
'sandbox' => true,
'debug' => false,
'timeout' => 30
];
$api = new Gerencianet($options);
Instancie os parâmetros do módulo usando client_id, client_secret, sandbox igual a false
e pix_cert como o nome do certificado de produção:
$options = [
'client_id' => 'client_id',
'client_secret' => 'client_secret',
'pix_cert' => '../certs/productionCertificate.pem',
'sandbox' => false,
'debug' => false,
'timeout' => 30
];
$api = new Gerencianet($options);
- Acesse o painel da Gerencianet no menu API.
- No canto esquerdo, clique em Minhas Aplicações depois em Nova Aplicação.
- Insira um nome para a aplicação, ative a API de emissões (Boletos e Carnês) e API Pix, e escolha os escopos que deseja liberar em Produção e/ou Homologação conforme sua necessidade (lembrando que estes podem ser alterados posteriormente).
- Clique em Criar Nova aplicação.
- Acesse o painel da Gerencianet no menu API.
- No canto esquerdo, clique em Minhas Aplicações, escolha a sua aplicação e clique no botão Editar (Botão laranja).
- Ative API Pix e escolha os escopos que deseja liberar em Produção e/ou Homologação conforme sua necessidade (lembrando que estes podem ser alterados posteriormente)
- Clique em Atualizar aplicação.
Todas as requisições do Pix devem conter um certificado de segurança que será fornecido pela Gerencianet dentro da sua conta, no formato PFX(.p12). Essa exigência está descrita na íntegra no manual de segurança do PIX.
Para gerar seu certificado:
- Acesse o painel da Gerencianet no menu API.
- No canto esquerdo, clique em Meus Certificados e escolha o ambiente em que deseja o certificado: Produção ou Homologação.
- Clique em Novo Certificado.
.pem
.
Você pode baixar o conversor de certificados disponibilizado pela Gerencianet.
Ou utilize do exemplo abaixo, executando o comando OpenSSL para conversão.
// Gerar certificado e chave em único arquivo
openssl pkcs12 -in certificado.p12 -out certificado.pem -nodes
O cadastro das chaves Pix pode ser feito através do aplicativo da Gerencianet ou por um endpoint da API. A seguir você encontra os passos de como registrá-las.
Caso ainda não tenha nosso aplicativo instalado, clique em Android ou iOS, de acordo com o sistema operacional do seu smartphone, para fazer o download.
Para registrar suas chaves Pix por meio do aplicativo:
- Acesse sua conta através do app Gerencianet.
- No menu lateral, toque em Pix para iniciar seu registro.
- Leia as informações que aparecem na tela e clique em Registrar Chave. Se este não for mais seu primeiro registro, toque em Minhas Chaves e depois no ícone (➕).
- Selecione os dados que você vai cadastrar como Chave do Pix e toque em avançar – você deve escolher pelo menos 1 das 4 opções de chaves disponíveis (celular, e-mail, CPF e/ou chave aleatória).
- Após cadastrar as chaves do Pix desejadas, clique em concluir.
- Pronto! Suas chaves já estão cadastradas com a gente.
O endpoint utilizado para criar uma chave Pix aleatória (evp), é o POST /v2/gn/evp
(Criar chave evp). Um detalhe é que, através deste endpoint é realizado o registro somente de chaves Pix do tipo aleatória.
Para consumí-lo, basta executar o exemplo /examples/pix/key/create.php
da nossa SDK. A requisição enviada para esse endpoint não precisa de um body.
A resposta de exemplo abaixo representa Sucesso (201), apresentando a chave Pix registrada.
{
"chave": "345e4568-e89b-12d3-a456-006655440001"
}
Você pode executar usando qualquer servidor web, como Apache ou nginx, ou simplesmente iniciar um servidor php da seguinte forma:
php -S localhost:9000
Ou abra qualquer exemplo em seu navegador.
examples/charge/oneStepBillet.php
ou examples/pix/charge/create.php
onde você deve alterar o parâmetro id
.
Versão | Status | Packagist | Repo | Versão PHP |
---|---|---|---|---|
1.x | Mantido | gerencianet/gerencianet-sdk-php |
v1 | >= 5.4 |
2.x | Mantido | gerencianet/gerencianet-sdk-php |
v2 | >= 5.5 |
3.x | Mantido | gerencianet/gerencianet-sdk-php |
v3 | >= 5.6 |
4.x | Mantido | gerencianet/gerencianet-sdk-php |
v4 | >= 7.2 |
A documentação completa com todos os endpoints e detalhes da API está disponível em https://dev.gerencianet.com.br/.
Se você ainda não tem uma conta digital da Gerencianet, abra a sua agora!