Payload Locations

O conjunto de endpoints a seguir são destinados a lidar com configuração e remoção de locations para uso dos payloads.

Configuração de locations para payloads

Esta seção reúne endpoints destinados a lidar com configuração e remoção de locations para uso dos payloads em cobranças imediatas e cobranças com vencimento.

Criar location do payload

Endpoint para criar location do payload. Necessário enviar no body da requisição o atributo tipoCob com o valor COB ou COBV.

POST /v2/loc

Requer autorização para o escopo: payloadlocation.write

Requisição

COB

{
  "tipoCob": "cob"
}

COBV

{
  "tipoCob": "cobv"
}

Respostas

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

🟢 201

{
  "id": 66,
  "location": "qrcodes-pix.gerencianet.com.br/v2/7796e273b8e447c2b2c0ac2c58fe1a13",
  "tipoCob": "cob",
  "criacao": "2021-01-15T20:13:39.462Z"
}

🔴 400

{
  "nome": "json_invalido",
  "mensagem": "Valores ou tipos de campo inválidos",
  "erros": [
    {
      "chave": "enum",
      "caminho": ".body.tipoCob",
      "mensagem": "deve ser igual a um dos valores predefinidos"
    }
  ]
}

Consultar locations cadastradas

Endpoint para consultar locations cadastradas.

GET /v2/loc

Requer autorização para o escopo: payloadlocation.read

Requisição

Para obter o resultado da consulta de locations é necessário informar os parâmetros inicio e fim, como exibido no trecho de código abaixo. Esses parâmetros restringem os resultados para os locations compreendidos nesse intervalo de datas.

/v2/loc/?inicio=2020-10-22T16:01:35Z&fim=2020-10-23T16:01:35Z

Respostas

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

🟢 200

{
  "parametros": {
    "inicio": "2022-01-22T16:01:35.000Z",
    "fim": "2024-01-22T16:01:35.000Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 3,
      "quantidadeTotalDeItens": 215
    }
  },
  "loc": [
    {
      "id": 1,
      "location": "qrcodes-pix.gerencianet.com.br/v2/05a9c9f346294ea1be67fb3dbac0fb9c",
      "tipoCob": "cob",
      "criacao": "2022-11-12T18:42:05.000Z"
    },
    {
      "id": 2,
      "location": "qrcodes-pix.gerencianet.com.br/v2/cobv/ba942526a50746cfae28e8d9af89afd0",
      "tipoCob": "cobv",
      "criacao": "2022-11-12T18:32:10.000Z",
      "txid": "31a0baG77448041d64352h4523459"
    },
    {
      "id": 3,
      "location": "qrcodes-pix.gerencianet.com.br/v2/de2fe49560c64a5fb70aa8249853279f",
      "tipoCob": "cob",
      "criacao": "2022-11-12T18:25:36.000Z",
      "txid": "31a0ba6a7a80g8d64352345334e5h7"
    }
  ]
}

🔴 400

{
  "nome": "valor_invalido",
  "mensagem": "Campo de data fim deve ser maior ou igual ao campo de data inicio"
}

Recuperar location do payload

Endpoint para recuperar a location do payload

GET /v2/loc/:id

Requer autorização para o escopo: payloadlocation.read

Respostas

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

🟢 200

{
  "id": 7716,
  "txid": "fda9460fe04e4f129b72863ae57ee22f",
  "location": "pix.example.com/qr/v2/cobv/2353c790eefb11eaadc10242ac120002",
  "tipoCob": "cobv",
  "criacao": "2020-03-11T21:19:51.013Z"
}

🔴 400

{
  "nome": "location_nao_encontrada",
  "mensagem": "Nenhuma location encontrado para o identificador informado"
}

Desvincular um txid de um location

Endpoint utilizado para desvincular uma cobrança de um location.

Se executado com sucesso, a entidade loc não apresentará mais um txid, como acontecia antes da chamada. Além disso, a entidade cob ou cobv associada ao txid desvinculado também não apresentará mais um location. Essa operação não altera o status da cob ou cobv em questão.

DELETE /v2/loc/:id/txid

Requer autorização para o escopo: payloadlocation.write

Respostas

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

🟢 200

{
  "id": 2316,
  "location": "qrcodes-pix.gerencianet.com.br/v2/a8534e273ecb47d3ac30613104544466",
  "tipoCob": "cob",
  "criacao": "2020-05-31T19:39:54.013Z"
}

🔴 400

{
  "nome": "location_nao_encontrada",
  "mensagem": "Nenhuma location encontrado para o identificador informado"
}

Configuração de locations para payloads de recorrências de Pix Automático

Esta seção reúne endpoints destinados a lidar com configuração e remoção de locations para uso dos payloads de recorrências de Pix Automático.

Criar location do payload de recorrência de Pix Automático

Endpoint para criar location do payload de recorrência de Pix Automático.

POST /v2/locrec

Requer autorização para o escopo: payloadlocationrec.write

Respostas

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

🟢 201

{
  "id": 12069,
  "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
  "criacao": "2023-12-20T12:38:28.774Z"
}

🔴 403

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

🔴 503

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Consultar locations de recorrência de Pix Automático cadastradas

Endpoint para consultar locations de recorrência de Pix Automático cadastradas.

GET /v2/locrec

Requer autorização para o escopo: payloadlocationrec.read

Requisição

Para obter o resultado da consulta de locations é necessário informar os parâmetros inicio e fim, como exibido no trecho de código abaixo. Esses parâmetros restringem os resultados para os locations compreendidos nesse intervalo de datas.

/v2/locrec/?inicio=2020-10-22T16:01:35Z&fim=2020-10-23T16:01:35Z

Respostas

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

🟢 200

{
  "parametros": {
    "inicio": "2023-12-01T00:00:00Z",
    "fim": "2024-04-01T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 1
    }
  },
  "loc": [
    {
      "id": 12069,
      "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
      "criacao": "2023-12-20T12:38:28.774Z",
      "idRec": "RR123456782024011510056892226"
    }
  ]
}

🔴 403

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

🔴 503

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Recuperar location do payload de recorrência de Pix Automático

Endpoint para recuperar a location do payload de recorrência de Pix Automático

GET /v2/locrec/:id

Requer autorização para o escopo: payloadlocationrec.read

Respostas

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

🟢 200

{
  "id": 12069,
  "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
  "criacao": "2023-12-20T12:38:28.774Z",
  "idRec": "RR123456782024011510056892226"
}

🔴 403

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Desvincular uma recorrência de Pix Automático de um location

Endpoint utilizado para desvincular uma recorrência de Pix Automático de um location.

DELETE /v2/locrec/:id/idRec

Requer autorização para o escopo: payloadlocationrec.write

Respostas

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

🟢 200

{
  "id": 12069,
  "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
  "criacao": "2023-12-20T12:38:28.774Z"
}

🔴 403

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Gerar QR Code de um location

Endpoint para gerar QR Code de um location.

GET /v2/loc/:id/qrcode

Requer autorização para o escopo: payloadlocation.read

Respostas

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

Atenção: O link de Visualização funciona apenas para cobranças Pix emitidas em ambiente de produção.

🟢 200

{
  "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode ou copia e cola
  "imagemQrcode": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." ,
  "linkVisualizacao": "https://pix.sejaefi.com.br/cob/pagar/c0a68af7ece6468cbb8e120e29a27cb5"
}

🔴 400

{
  "nome": "location_nao_encontrada",
  "mensagem": "Nenhuma location encontrado para o identificador informado"
}

Link responsivo para cobrança Pix

Conheça o link responsivo para cobranças Pix

Este link visa facilitar o compartilhamento das cobranças Pix emitidas via API, mostrando os detalhes da cobrança, bem como a imagem do QR Code e Pix Copia e Cola. E mais! É possível customizá-la utilizando a logo e cor primária definidas nas configurações da sua conta.

Saiba mais

Para obter este link da sua cobrança Pix emitida via API, basta acessar o retorno da API no endpoint de criação da cobrança e copiar o id do location gerado.

Em seguida, você deve consumir o endpoint de QR Code, utilizando o id copiado: https://pix.api.efipay.com.br/v2/loc/:id/qrcode

No endpoint, localize o campo linkVisualizacao e copie a URL gerada.

Pronto! Com essa URL gerada, basta enviá-la para quem for pagar, conforme exemplo a seguir:

Links de exemplo:
Cobrança imediata: https://pix.sejaefi.com.br/cob/pagar/c0a68af7ece6468cbb8e120e29a27cb5
Cobrança com vencimento: https://pix.sejaefi.com.br/cobv/pagar/3d89b1ae52604ed5b8accc78f3abd0aa

Atenção: Estes links só funcionam para cobranças Pix emitidas em ambiente de produção.