Pular para o conteúdo principal

Locations

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


Listar locations​

Endpoint para listar todos os locations (locais de payload) disponíveis para o participante.

O que são Locations:

Locations são URLs únicas onde ficam armazenados os dados das cobranças (payloads). Cada cobrança PIX possui um location associado que pode ser usado para consultar os dados da cobrança através de QR Code ou Pix Copia e Cola.

Informações Retornadas:
  • ID: Identificador único do location
  • Location: URL completa do location
  • Tipo: Tipo de cobrança (cob, cobv)
  • Data de Criação: Quando o location foi criado
  • Última Modificação: Última atualização do location
Dica!

Locations são automaticamente criados quando você cria cobranças.


GET /v1/loc
Requer autorização para o escopo: payload.location.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.

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

{
  "parametros": {
    "inicio": "2023-10-01T00:00:00Z",
    "fim": "2023-10-31T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeDeItens": 3
    }
  },
  "loc": [
    {
      "id": 789,
      "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
      "tipoCob": "cob",
      "criacao": "2023-10-15T14:30:00Z",
      "txid": "fb2761260e054c7a94fb7b7b"
    },
    {
      "id": 790,
      "location": "pix.example.com/qr/v2/cobv/ab1234567890123456789012",
      "tipoCob": "cobv",
      "criacao": "2023-10-16T09:15:00Z",
      "txid": "ab1234567890123456789012"
    },
    {
      "id": 791,
      "location": "pix.example.com/qr/v2/cobv/xyz789",
      "tipoCob": "cobv",
      "criacao": "2023-10-17T16:45:00Z",
      "txid": "xyz789"
    }
  ]
}

Consultar location específico​

Endpoint para consultar os detalhes de um location específico pelo seu ID.

O que você obtém:
  • Dados do Location: ID, URL, tipo de cobrança
  • Informações da Cobrança: Dados completos da cobrança associada
  • Status: Status atual da cobrança vinculada
  • Metadados: Datas de criação e modificação
Casos de Uso:
  • Validação de QR Code: Verificar se um location ainda é válido
  • Auditoria: Rastrear cobranças através de seus locations
  • Integração: Obter dados para sistemas externos
  • Debug: Investigar problemas em cobranças específicas
TipoDescriçãoURL Pattern
cobCobrança imediata/qr/v2/cob/:txid
cobvCobrança com vencimento/qr/v2/cobv/:txid
Importante!

O location retorna os dados atuais da cobrança, que podem ter sido modificados após a criação.


GET /v1/loc/:id
Requer autorização para o escopo: payload.location.read


Respostas

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

// Location de cobrança imediata
{
  "responseTime": 300,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "id": 789,
  "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
  "tipoCob": "cob",
  "criacao": "2023-10-15T14:30:00Z",
  "txid": "fb2761260e054c7a94fb7b7b"
}

OU

// Location de cobrança com vencimento
{
  "responseTime": 300,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "id": 790,
  "location": "pix.example.com/qr/v2/cobv/ab1234567890123456789012",
  "tipoCob": "cobv",
  "criacao": "2023-10-16T09:15:00Z",
  "txid": "ab1234567890123456789012"
}


Desvincular location​

Endpoint utilizado para remover a vinculação de um location, tornando-o indisponível para consultas via QR Code.

Operação Irreversível!

Esta operação NÃO PODE SER DESFEITA.

Consulte a equipe técnica para entender os impactos específicos desta operação no seu sistema.


Restrições:
  • Status: Apenas cobranças com status ATIVA podem ter location desvinculado
  • Permissões: Requer escopo específico para remoção
DELETE /v1/loc/:id/txid
Requer autorização para o escopo: payload.location.write


Respostas

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

// Location de cobrança imediata
{
  "responseTime": 300,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "id": 789,
  "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
  "tipoCob": "cob",
  "criacao": "2023-10-15T14:30:00Z",
  "txid": "fb2761260e054c7a94fb7b7b"
}

OU

// Location de cobrança com vencimento
{
  "responseTime": 300,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "id": 790,
  "location": "pix.example.com/qr/v2/cobv/ab1234567890123456789012",
  "tipoCob": "cobv",
  "criacao": "2023-10-16T09:15:00Z",
  "txid": "ab1234567890123456789012"
}

Última atualização em