# Consultando um QRCode A consulta de um QRCode na API do Pagou permite obter os detalhes de um QRCode Pix (com ou sem vencimento), incluindo seu status, valor, pagador e código Pix. ### Visão Geral Técnica O endpoint `GET`` ``/v1/pix/{id}` retorna os detalhes de um QRCode identificado por seu ID único no formato UUID (ex.: 550e8400-e29b-41d4-a716-446655440000). A operação é síncrona, retornando `200 OK` com um corpo JSON contendo informações como status, valor, pagador, código Pix e imagem em base64. Este endpoint é útil para verificar o estado de um pagamento Pix (ex.: pago ou expirado) ou recuperar o código Pix para exibição. **Especificações**: * **Método**: GET * **URL**: * Produção: * Sandbox: * **Autenticação**: Cabeçalho X-API-KEY com chave do painel. * **Content-Type**: application/json * **Resposta**: Status 200 OK com corpo JSON contendo os detalhes do QRCode. * **Erros**: 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error. ### Cabeçalhos | Cabeçalho | Valor | Descrição | | -------------- | ---------------------- | ------------------------------------------------ | | `X-API-KEY` | sua\_chave\_api | Chave de autenticação. | | `Content-Type` | application/json | Formato JSON para a requisição. | | `User-Agent` | NomeDaSuaAplicacao/1.0 | Identificador da aplicação (ex.: MinhaLoja/1.0). | ### Parâmetros da URL | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | ------------------------------------------------------------------------------- | | `id` | string | Sim | ID único do QRCode no formato UUID (ex.: 550e8400-e29b-41d4-a716-446655440000). | **Validações**: * qrcodeID: Deve ser um UUID válido (ex.: 550e8400-e29b-41d4-a716-446655440000). **Notas Técnicas**: * Configure o `notification_url` ao criar o QRCode para receber o evento `QRCodeCompleted` quando o status mudar para `StatusCompleted` ou `QRCodeRefunded` quando o status mudar para `StatusRefunded`. ### Resposta * **Status**: 200 OK * **Corpo**: JSON com os detalhes do QRCode, incluindo status, valor, pagador, código Pix e imagem em base64. **Exemplo de Resposta**: ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "customer_id": "cust-12345", "amount": 100.00, "description": "Payment with due date", "expiration": 30, "due_date": "2024-12-31", "status": "active", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "metadata": [ { "key": "order_id", "value": "ORD-2024-001" } ], "payer": { "name": "João Silva", "document": "12345678901" }, "discount": { "type": "fixed", "amount": 10.00, "limit_date": "2024-12-25" }, "fine": { "type": "percentage", "amount": 2.5 }, "interest": { "type": "percentage_calendar_days", "amount": 1.0 }, "notification_url": "https://your-webhook.com/notifications", "payload": { "payload_id": 12345, "data": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540100.005802BR5913JOAO SILVA6008SAO PAULO62070503***63041234", "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAAdgAAAHYBTnsmCAAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAANCSURBVHic7doxAQAAAMKg9U9tCj+gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA4GvAAAEAAQ==" } } ``` **Campos da Resposta**: | **Campo** | **Tipo** | **Descrição** | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------- | | `id` | string | UUID único do QRCode (ex.: 550e8400-e29b-41d4-a716-446655440000). | | `customer_id` | string | Identificador interno do cliente (ex.: cust-12345). | | `amount` | number | Valor do pagamento em reais (ex.: 100.00). | | `description` | string | Descrição do pagamento (máx. 255 caracteres). | | `expiration` | number | Tempo de expiração do QRCode (em dias para QRCodes com vencimento, ou segundos para QRCodes simples). | | `due_date` | string | Data de vencimento, se aplicável (formato YYYY-MM-DD). | | `status` | string | Status atual do QRCode (empty, active, canceled, completed, refunded). | | `created_at` | string | Data de criação do QRCode (formato ISO 8601). | | `updated_at` | string | Data da última atualização (formato ISO 8601). | | `metadata` | array | Pares chave-valor para dados adicionais. | | `metadata[].key` | string | Chave do metadado (ex.: order\_id). | | `metadata[].value` | string | Valor do metadado (ex.: ORD-2024-001). | | `payer` | object | Dados do pagador. | | `payer.name` | string | Nome completo do pagador (máx. 100 caracteres). | | payer.document | string | CPF (11 dígitos) ou CNPJ (14 dígitos). | | `discount` | object | Desconto para pagamento antecipado, se aplicável. | | `discount.type` | string | Tipo de desconto (fixed, percentage, fixed\_calendar\_days). | | `discount.amount` | number | Valor do desconto (em reais ou percentual). | | `discount.limit_date` | string | Data limite para o desconto (formato YYYY-MM-DD). | | `fine` | object | Multa por atraso, se aplicável. | | `fine.type` | string | Tipo de multa (percentage, fixed, etc.). | | `fine.amount` | number | Valor da multa (em percentual ou reais). | | `interest` | object | Juros por atraso, se aplicável. | | `interest.type` | string | Tipo de juros (percentage\_calendar\_days, fixed, percentage.). | | `interest.amount` | number | Valor dos juros (em percentual ou reais). | | `notification_url` | string | URL HTTPS para webhooks. | | `payload` | object | Dados do QRCode Pix. | | `payload.payload_id` | number | ID interno do payload Pix. | | `payload.data` | string | Código Pix para pagamento (copia-e-cola). | | `payload.image` | string | Imagem do QRCode em base64 (formato data:image/png;base64,...). | ### Exemplos de Código {% tabs %} {% tab title="cURL" %} ```ruby curl -X GET https://sandbox.api.pagou.com.br/v1/pix/550e8400-e29b-41d4-a716-446655440000 \ -H "X-API-KEY: sua_chave_api" \ -H "Content-Type: application/json" \ -H "User-Agent: MinhaLoja/1.0" ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const fetch = require('node-fetch'); // Configuração const qrcodeId = '550e8400-e29b-41d4-a716-446655440000'; const url = `https://sandbox.api.pagou.com.br/v1/pix/${qrcodeId}`; const headers = { 'X-API-KEY': 'sua_chave_api', 'Content-Type': 'application/json', 'User-Agent': 'MinhaLoja/1.0' }; fetch(url, { method: 'GET', headers: headers }) .then(response => { if (!response.ok) { return response.json().then(err => { throw new Error(`Erro ${response.status}: ${err.error.message}`); }); } return response.json(); }) .then(data => { console.log(`QRCode ID: ${data.id}`); console.log(`Status: ${data.status}`); console.log(`Valor: ${data.amount}`); console.log(`Código Pix: ${data.payload.data}`); console.log(`Imagem Base64: ${data.payload.image}`); }) .catch(error => console.error('Erro na requisição:', error)); ``` {% endtab %} {% tab title="Python" %} ```python import requests import re # Configuração qrcode_id = "550e8400-e29b-41d4-a716-446655440000" url = f"https://sandbox.api.pagou.com.br/v1/pix/{qrcode_id}" headers = { "X-API-KEY": "sua_chave_api", "Content-Type": "application/json", "User-Agent": "MinhaLoja/1.0" } try: response = requests.get(url, headers=headers) response.raise_for_status() data = response.json() print(f"QRCode ID: {data['id']}") print(f"Status: {data['status']}") print(f"Valor: {data['amount']}") print(f"Código Pix: {data['payload']['data']}") print(f"Imagem Base64: {data['payload']['image']}") except requests.RequestException as e: print(f"Erro na requisição: {e}") if e.response: print(f"Detalhes: {e.response.json()}") ``` {% endtab %} {% endtabs %} ### Tratamento de Erros | Código HTTP | Descrição | Possível Causa | Solução | | ----------- | --------------------- | ------------------------------ | --------------------------------------------------- | | 400 | Bad Request | id não é um UUID válido. | Verificar formato do id. | | 401 | Unauthorized | X-API-KEY inválido ou ausente. | Verificar chave. | | 404 | Not Found | QRCode com o id não existe. | Verificar o id fornecido. | | 500 | Internal Server Error | Erro interno da API. | Tentar novamente e contatar . | **Exemplo de Resposta de Erro**: ```json { "error": "QRCode not found" } ``` ### Boas Práticas Técnicas * **Validação de Dados**: Valide o id como UUID antes de enviar a requisição. * **Segurança**: Armazene `X-API-KEY` em variáveis de ambiente e use HTTPS para todas as requisições. * **Monitoramento**: Registre todas as requisições e respostas (incluindo id, status, payload.data e payload.image) em logs para auditoria e depuração. * **Testes no Sandbox**: Use `https://sandbox.api.pagou.com.br/v1/pix/{id}` para simular consultas sem impacto em produção. * **Uso da Imagem**: Converta o campo payload.image (base64) em uma imagem PNG para exibição em interfaces (ex.: \ em HTML). * **Verificação de Status**: Use o campo status para determinar ações subsequentes (ex.: exibir o código Pix se active, ou notificar o usuário se canceled) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-pix/consultando-um-qrcode.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.