# 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)