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.

🟢 201

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

🔴 400

{
  "nome": "limite_criacao_chave_atingido",
  "mensagem": "O limite de criação de chaves foi atingido"
}

🔴 500

{
  "nome": "erro_aplicacao",
  "mensagem": "Ocorreu um erro ao solicitar a criação da chave"
}

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.

🟢 200

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

🔴 500

{
  "nome": "erro_aplicacao",
  "mensagem": "Ocorreu um erro ao buscar as chaves"
}

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.

🟢 200

Chave aleatória removida.

🔴 400

{
  "nome": "chave_nao_encontrada",
  "mensagem": "A chave informada não foi encontrada"
}

🔴 500

{
  "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.

🟢 200

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

🟢 200

//Bloqueios = false
{
 "saldo": "100.00"
}

🔴 500

{
  "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.

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

Exemplo

{
  "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.

🟢 204

Configurações criados / modificadas

🔴 400

{
  "nome": "erro_aplicacao",
  "mensagem": "Ocorreu um erro ao buscar as configurações da conta"
}

🔴 500

{
  "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.

🟢 200

{
  "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.

🟢 200

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.

🟢 200

{

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

🔴 400

{
  "type": "https://pix.bcb.gov.br/api/v2/error/InfracoesConsultaInvalida",
  "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": "Algum dos parâmetros informados para a consulta não respeita o schema.",
      "propriedade": "infracoes.query.inicio" //O campo pode alterar de acordo com o campo informado errado
    }
  ]
}

🔴 403

{
  "error": "insufficient_scope", 
  "error_description": "Access token has insufficient scope"
}

🔴 500

{
  "type": "https://pix.bcb.gov.br/api/v2/error/InfracaoErroInterno", 
  "title": "Erro Interno", 
  "status": 500, 
  "detail": "Ocorreu um erro interno ao obter a listagem de infrações."
}

OU

{
  "type": "https://pix.bcb.gov.br/api/v2/error/InfracaoErroInterno", 
  "title": "Erro Interno", 
  "status": 500, 
  "detail": "Funcionalidade desabilitada em ambiente de homologação."
}

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

Exemplo 1

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

Exemplo 2

{
  "dataMovimento": "2022-04-24",
  "tipoRegistros": {
    "pixRecebido": true
  }
}

Respostas

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

🟢 202

{
  "id": "3d0ca315-aff9–4fc2-be61–3b76b9a2d798",
  "dataSolicitacao": "“2022-02-14T14:42:51.013Z",
  "status": "AGUARDANDO_PROCESSAMENTO"
}

🔴 400

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

🔴 400

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

🔴 500

{
  "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á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.

🟢 200

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

🟢 202

{
  "id": "b02c2b3a-0ab2-4ab5-bc8e-b3ce607e7829",
  "dataSolicitacao": "2022-06-02T20:08:39.000Z",
  "status": "AGUARDANDO_PROCESSAMENTO"
}

🔴 404

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

🔴 500

{
  "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 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.