Pular para o conteúdo principal

Endpoints exclusivos EfÍ

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 pix aleatória

Endpoint utilizado para criar uma chave pix aleatória.

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.

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

{
"chave": "345e4568-e89b-12d3-a456-006655440001"
}

Listar chaves pix aleatórias

Endpoint utilizado para listar as chaves pix aleatórias. 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.

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

{
"chaves": [
"355e4568-e89b-1243-a456-006655440001",
"133e4568-e89b-1243-a456-006655440000"
]
}

Remover chave pix aleatória

Endpoint utilizado para remover uma chave pix aleatória. É 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.

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.

//Bloqueios = true
{
"saldo": "100.00",
"bloqueios": {
"judicial": "0.00",
"med": "0.00",
"total": "0.00"
}
}

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.

Configuração para bloquear recebimento quando o documento do Devedor for diferente do documento do Pagador

  • Essa configuração ("documentoPagadorIgualDevedor": true) valida tanto CPF quanto CNPJ, ou seja, verifica o documento do pagador.
  • É uma configuração aplicada a nível de chave, ou seja, pode haver uma chave com a configuração habilitada (true), outra com a configuração desabilitada (false) e uma terceira sem a configuração definida, sendo interpretada como false.
  • Quando a configuração está como "documentoPagadorIgualDevedor": true, para qualquer pagamento de COB ou COBV recebido nesta chave, o CPF do pagador é comparado com o CPF do devedor especificado na emissão da cobrança.
    • Se os CPFs forem diferentes, o pagamento não será efetivado, e a cobrança permanecerá com o status ativa, podendo ser paga somente pela pessoa definida como devedora.
    • Se os CPFs forem iguais, o pagamento será concluído normalmente.
  • Se a configuração estiver como "documentoPagadorIgualDevedor": true, mas a COB não tiver o campo devedor preenchido, o pagamento será realizado normalmente. No entanto, esse caso não ocorre para COBV, pois o campo devedor é obrigatório em COBV, garantindo que a checagem dos documentos seja feita.

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
},
"documentoPagadorIgualDevedor": true,
"webhook": {
"notificacao": {
"tarifa": true,
"pagador": true
},
"notificar": {
"pixSemTxid": true
}
}
},
"envio": {
"webhook": {
"notificacao": {
"tarifa": true,
"favorecido": true
}
}
}
}
}
}
}

Respostas

As respostas abaixo representam Sucesso(204) e Falhas/erros do consumo.

Configurações criados / modificadas

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
}
}
}
}
}
}

Obter comprovantes

Endpoint com a finalidade de obter comprovantes de transações Pix realizadas via API.

GET /v2/gn/pix/comprovantes
Requer autorização para o escopo: gn.receipts.read


Requisição

Para obter o resultado da consulta é necessário informar pelo menos um parâmetro com o id da transação desejada. O parâmetro da consulta pode ser e2eId, idEnvio, rtrId ou txid e só pode ser utilizado um único identificador por requisição.

Respostas

A resposta abaixo representa Sucesso(200) do consumo.


Listar infrações MED da conta

Endpoint para listar as infrações abertas em uma conta.

GET /v2/gn/infracoes
Requer autorização para o escopo: gn.infractions.read


Requisição

O trecho de código abaixo ilustra o consumo do endpoint em uma requisição com o mínimo de parâmetros possível (o intervalo de datas inicio e fim) e o formato em que esses parâmetros devem ser repassados.

/v2/gn/infracoes?inicio=2020-10-22T00:00:00Z&fim=2023-12-30T23:00:00Z

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

{

"parametros":{
"inicio":"2023-11-22T16:01:35Z",
"fim":"2023-12-22T16:01:35Z",
"paginacao":{
"paginaAtual":0,
"itensPorPagina":10,
"quantidadeDePaginas":2,
"quantidadeTotalDeItens":20
}
},
"infracoes":[
{
"idInfracao":"8ad75c93-6150-422c-929e-822f361c7a6b",
"endToEndId":"E09089356202312181249APId91a6304",
"protocolo":1313,
"dataTransacao":"2023-12-22T16:01:35Z",
"valor":100,
"chave": "[email protected]", //OPCIONAL
"status": "ABERTA", //ENUM["ABERTA", "ACEITA", "CANCELADA_EFI", "CANCELADA_EFI", "EM_DEFESA", "REJEITADA"]"razao":"Solicitacao de devolução",
"tipoSituacao": "golpe", //OPCIONAL. ENUM["golpe", "aquisição da conta", "coerção", "acesso fraudulento", "outro", "desconhecido"]
"tipoFraude": "aplicativo fraudulento", //OPCIONAL.
"comentario": "Transação feita através de Qrcode falso em boleto", //OPCIONAL
"defesa": "Comentario de defesa", //OPCIONAL
"justificativaAnalista": "Não foi identificado a fraude", //OPCIONAL
"identificadorTicket":[
94,
95
],
"dadosAnalise":{
"abertura":"2023-12-22T16:01:35Z",
"prazoFinalizacao":"2023-12-22T16:01:35Z",
"recebimentoDefesa": "2023-12-22T16:01:35Z", //OPCIONAL
"finalizacao": "2023-12-22T16:01:35Z" //OPCIONAL
},
"origem":{
"nomeParticipante":"BANCO XYZ",
"conta":10001,
"nome":"Fulano de Tal",
"documento":"800000000000000"
},
"destino":{
"nomeParticipante":"Efí S/A",
"conta":10001,
"nome":"Fulano de Tal",
"documento":"800000000000000"
},
"criadoEm":"2023-12-22T16:01:35Z",
"atualizadoEm":"2023-12-22T16:01:35Z"
}
]
}

Requisitar Extrato Conciliação

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
}
}

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"
}

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ática

Apó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.


Solicitar Download Extrato Conciliação

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.


Respostas
As 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

Detalhamento de retorno

Para 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.