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.


Consultar baldes de fichas​

Endpoint para consultar a quantidade de fichas para cada balde de fichas da conta integradora. Existem dois tipos de baldes, o balde de fichas para chaves do tipo documento e evp, chamado de baldeA e o balde de fichas para chaves do tipo telefone e email, chamado de baldeB.

GET /v2/gn/chaves/balde
Requer autorização para o escopo: gn.keys.bucket.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.

{
  "baldeA": {
      "tiposChave": [
          "cpf",
          "cnpj",
          "evp"
      ],
      "capacidade": "number",
      "fichasDisponiveis": "number",
      "taxaDeReposicaoFichas": "number",
      "periodoReposicaoEmSegundos": "number",
  },
  "baldeB": {
      "tiposChave": [
          "telefone",
          "email"
      ],
      "capacidade": "number",
      "fichasDisponiveis": "number",
      "taxaDeReposicaoFichas": "number",
      "periodoReposicaoEmSegundos": "number",
  }
}

Listar infrações MED da conta​

Endpoint para listar as infrações abertas em todas as contas associadas ao documento vinculado à conta autenticada.

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, //Número da conta sem dígito verificador
          "nome":"Fulano de Tal",
          "documento":"800000000000000"
      },
      "destino":{
          "nomeParticipante":"Efí S/A",
          "conta":10001, //Número da conta sem dígito verificador
          "nome":"Fulano de Tal",
          "documento":"800000000000000"
      },
      "criadoEm":"2023-12-22T16:01:35Z",
      "atualizadoEm":"2023-12-22T16:01:35Z"
    }
  ]
}

Submeter defesa de infração MED​

Endpoint que permite criar uma defesa para uma infração específica.

Importante!

Reforçamos que as informações enviadas por este endpoint não substituem o envio do ticket. Nosso analista poderá entrar em contato através do ticket para solicitar documentos ou informações complementares, caso necessário.

Os dados enviados por este endpoint servem apenas para complementar a análise, mas não eliminam a necessidade de acompanhamento via ticket, especialmente porque o endpoint de defesa não permite o envio de anexos atualmente.


POST /v2/gn/infracoes/:idInfracao/defesa
Requer autorização para o escopo: gn.infractions.write


Requisição

{
  "analise": "rejeitado",
  "justificativa": "Justificativa"
}

Respostas

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

Defesa de infração MED criada

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.


Última atualização em