Os endpoints listados nesta seção visam à facilitação do uso da API Pix para os clientes Efí . Com os endpoints a seguir você poderá obter e alterar informações da sua conta diretamente pela API, conforme a necessidade da sua integração.
Criar chave evp
Endpoint utilizado para criar uma chave Pix aleatória (evp
).
POST /v2/gn/evp
Requer autorização para o escopo: gn.pix.evp.write
Requisição
A requisição enviada para esse endpoint não precisa de um body, apenas os cabeçalhos de autorização OAuth e o certificado da conta, assim como os endpoints anteriores.
Respostas As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
{
"chave": "345e4568-e89b-12d3-a456-006655440001"
}
{
"nome": "limite_criacao_chave_atingido",
"mensagem": "O limite de criação de chaves foi atingido"
}
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao solicitar a criação da chave"
}
Listar chaves evp
Endpoint utilizado para listar as chaves Pix aleatórias (evp
). A listagem somente mostrará as chaves do tipo aleatória.
GET /v2/gn/evp
Requer autorização para o escopo: gn.pix.evp.read
Requisição
A requisição enviada para esse endpoint não precisa de um body, apenas os cabeçalhos de autorização OAuth e o certificado da conta, assim como os endpoints anteriores.
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
{
"chaves": [
"355e4568-e89b-1243-a456-006655440001",
"133e4568-e89b-1243-a456-006655440000"
]
}
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao buscar as chaves"
}
Remover chave evp
Endpoint utilizado para remover uma chave Pix aleatória (evp
). É importante destacar que, ao remover uma chave aleatória, não será possível criá-la novamente, pois o uuid
é gerado pelo DICT e cada solicitação de registro resulta em um hash diferente. Isso significa que as cobranças criadas para a chave removida não poderão mais ser pagas, pois o payload não será mais retornado.
DELETE /v2/gn/evp/:chave
Requer autorização para o escopo: gn.pix.evp.write
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
Chave aleatória removida.
{
"nome": "chave_nao_encontrada",
"mensagem": "A chave informada não foi encontrada"
}
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao solicitar a exclusão da chave"
}
Buscar o saldo da conta
Endpoint com a finalidade de consultar o saldo em sua conta Efí. Você pode habilitar o escopo nas configurações de sua aplicação em sua conta Efí.
GET /v2/gn/saldo/
Requer autorização para o escopo: gn.balance.read
Requisição
A requisição enviada para esse endpoint não precisa de um
body, com a opção de informar o parâmetro
bloqueios
igual a
true
ou
false
, como exibido no trecho de código abaixo. Esse parâmetro exibe ou não, os saldos bloqueados por MED ou ação judicial.
/v2/gn/saldo?bloqueios=true
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
{
"saldo": "100.00",
"bloqueios": {
"judicial": "0.00",
"med": "0.00",
"total": "0.00"
}
}
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao solicitar o saldo da conta"
}
Criar/modificar configurações da conta
Endpoint com a finalidade de criar e modificar as configurações da conta do cliente relacionados à API.
Por meio desse endpoint, é possível definir se deseja receber um Pix exclusivamente, por meio de uma transferência via chave (receberSemChave = false
), ou permitir recebimentos também por dados bancários (receberSemChave = true
). Além da configuração da conta, pode ser utilizado também, para modificar as configurações de recebimento de Pix associados a uma chave específica, como permitir um recebimento sem txid, ou bloquear o recebimento pelo tipo de documento CPF ou CNPJ, por exemplo, e as informações da tarifa e/ou pagador no webhook.
Para mais informações sobre esse endpoint, acesse o Módulo 5.1 do nosso curso online.
PUT /v2/gn/config
Requer autorização para o escopo: gn.settings.write
Requisição
{
"pix": {
"receberSemChave": true,
"chaves": {
"355e4568-e89b-1243-a456-006655440001": {
"recebimento": {
"txidObrigatorio": false,
"recusarTipoPessoa": "PF",
"qrCodeEstatico": {
"recusarTodos": false
},
"webhook": {
"notificacao": {
"tarifa": true,
"pagador": true
}
}
}
}
}
}
}
Respostas As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
Configurações criados / modificadas
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao buscar as configurações da conta"
}
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao validar a chave"
}
Listar configurações da conta
Endpoint com a finalidade de listar as configurações definidas na conta.
GET /v2/gn/config
Requer autorização para o escopo: gn.settings.read
Requisição
A requisição enviada para esse endpoint não precisa de um
body, apenas os cabeçalhos de autorização OAuth e o certificado da conta, assim como os endpoints anteriores.
Respostas As respostas abaixo representam Sucesso(200) do consumo.
{
"pix": {
"receberSemChave": true,
"chaves": {
"355e4568-e89b-1243-a456-006655440001": {
"recebimento": {
"txidObrigatorio": true,
"recusarTipoPessoa": "PF",
"qrCodeEstatico": {
"recusarTodos": false
}
}
}
}
}
}
Endpoint para solicitar extrato de conciliação.
POST /v2/gn/relatorios/extrato-conciliacao
Requer autorização para o escopo: gn.reports.write
Requisição
{
"dataMovimento": "2023-12-15",
"tipoRegistros": {
"pixRecebido": true,
"pixEnviadoChave": true,
"pixEnviadoDadosBancarios": true,
"estornoPixEnviado": true,
"pixDevolucaoEnviada": true,
"pixDevolucaoRecebida": true,
"tarifaPixEnviado": true,
"tarifaPixRecebido": true,
"estornoTarifaPixEnviado": true,
"saldoDiaAnterior": true,
"saldoDia": true,
"transferenciaEnviada": true,
"transferenciaRecebida": true,
"estornoTransferenciaEnviada": true,
"tarifaTransferenciaEnviada": true,
"estornoTarifaTransferenciaEnviada": true,
"estornoTarifaPixRecebido": true
}
}
{
"dataMovimento": "2022-04-24",
"tipoRegistros": {
"pixRecebido": true
}
}
Respostas As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
{
"id": "3d0ca315-aff9–4fc2-be61–3b76b9a2d798",
"dataSolicitacao": "“2022-02-14T14:42:51.013Z",
"status": "AGUARDANDO_PROCESSAMENTO"
}
{
"type": "https://api-pix.gerencianet.com.br/v2/gn/ExtratoConciliacaoConsultaInvalida",
"title": "Consulta inválida",
"status": 400,
"detail": "Os parâmetros de consulta não respeitam o schema ou não fazem sentido semanticamente",
"violacoes": [
{
"razao": "não são permitidas propriedades adicionais",
"propriedade": ".body.parametros"
},
{
"razao": "deve ter a propriedade obrigatória dataMovimento",
"propriedade": ".body"
}
]
}
{
"type": "https://api-pix.gerencianet.com.br/v2/gn/ExtratoConciliacaoConsultaInvalida",
"title": "Consulta inválida",
"status": 400,
"detail": "A data do extrato de conciliação deve ser anterior à data corrente"
}
{
"type": "https://api-pix.gerencianet.com.br/v2/gn/ErroInterno",
"title": "Erro Interno",
"status": 500,
"detail": "Ocorreu um erro interno ao processar a requisição"
}
Tipos de status retornado no body:- AGUARDANDO_PROCESSAMENTO: esse status indica que a solicitação de extrato foi recebida com sucesso e está na fila aguardando para iniciar o processamento;
- EM_PROCESSAMENTO: esse status indica que a geração do arquivo foi iniciada e está em etapa de processamento dos dados;
- CONCLUIDO: esse status indica que um extrato com os mesmos parâmetros foi solicitado anteriormente e um arquivo com o
id
retornado já se encontra passível para download.
Boa PráticaApós realizar a requisição POST, a API tem um tempo médio de espera de 30 segundos até processar o extrato. Então é recomendado esperar esse tempo para realizar a requisição GET.
Endpoint para solicitar download do extrato de conciliação.
GET /v2/gn/relatorios/:id
Requer autorização para o escopo: gn.reports.read
Atenção!Se consumir o endpoint GET e o extrato ainda não tiver sido processado, a resposta será sucesso(202) e o retorno será semelhante ao que é retornado na solicitação, informando em qual etapa de processamento está a solicitação.
RespostasAs respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
CA;Gerencianet;364;1;517613;João da Silva;2021-12-17;2021-12-10;Extrato de Conciliação API Pix;1.0
T;0;0;0;0;0;0
{
"id": "b02c2b3a-0ab2-4ab5-bc8e-b3ce607e7829",
"dataSolicitacao": "2022-06-02T20:08:39.000Z",
"status": "AGUARDANDO_PROCESSAMENTO"
}
{
"type": "https://api-pix.gerencianet.com.br/v2/gn/NaoEncontrado",
"title": "Não encontrado",
"status": 404,
"detail": "Recurso não encontrado ou não pertence à conta autenticada"
}
{
"type": "https://api-pix.gerencianet.com.br/v2/gn/ErroInterno",
"title": "Erro Interno",
"status": 500,
"detail": "Ocorreu um erro interno na geração do relatório. Tente solicitar um novo relatório."
}
Detalhamento de retornoPara mais informações sobre o documento .CSV que é retornado e a legenda dos campos, baixe o PDF disponível abaixo ou por meio deste link.