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

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

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

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

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
          },
          "webhook": {
            "notificacao": {
              "tarifa": true,
              "pagador": true
            }
          }
        }
      }
    }
  }
}

Respostas

As respostas abaixo representam Sucesso(201) 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
          }
        }
      }
    }
  }
}

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.