> For the complete documentation index, see [llms.txt](https://docs.pagou.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-boleto/consultando-um-boleto.md). # Consultando um Boleto ## Consultando um Boleto A consulta de um boleto na API do Pagou permite recuperar detalhes de um boleto existente, como status, valor, código de barras e data de pagamento, usando seu ID único. ### Visão Geral Técnica O endpoint `GET`` ``/v1/charges/{id}` retorna os detalhes completos de um boleto, incluindo informações do pagador, multas, juros, descontos e status. A operação é síncrona e ideal para verificar o estado de um boleto sem depender de webhooks, embora o uso de webhooks (ex.: evento `ChargePaid`) seja recomendado para atualizações automáticas. `GET` /v1/charges/{id} ### Cabeçalhos | Cabeçalho | Valor | Descrição | | -------------- | ------------------------ | ------------------------------------------------------------ | | `X-API-KEY` | `sua_chave_api` | Chave de autenticação (encontrada em *Configurações > API*). | | `Content-Type` | `application/json` | Formato JSON para a requisição. | | `User-Agent` | `NomeDaSuaAplicacao/1.0` | Identifica sua aplicação (ex.: `MinhaLoja/1.0`). | ### Parâmetros da URL | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | --------------------------------------------------------------- | | `id` | string | Sim | ID único do boleto (ex.: 8325a4b3-579c-45df-b475-0ce57df2478d). | **Validações**: * `id`: Deve ser um ID válido retornado pelo endpoint de criação (`POST`` ``/v1/charges`). ### Resposta * **Status**: `200 OK` * **Corpo**: JSON com os detalhes do boleto. **Exemplo de Resposta**: ```json { "id": "8325a4b3-579c-45df-b475-0ce57df2478d", "status": 2, "due_date": "2024-12-31", "grace_period": 15, "amount": 100.50, "description": "Payment for services rendered", "metadata": [ { "key": "order_id", "value": "ORD-2024-001" }, { "key": "reference", "value": "REF-12345" } ], "payer": { "name": "João Silva", "document": "12345678901", "zip": "01234567", "street": "Rua das Flores", "city": "São Paulo", "state": "SP", "number": "123", "neighborhood": "Centro" }, "fine": 2.5, "interest": 1.0, "discount": { "type": "fixed", "amount": 10.00, "limit_date": "2024-12-25" }, "notification_url": "https://your-webhook.com/notifications", "customer_code": "CUST-001", "created_at": "2025-07-23T09:30:00-03:00", "paid_at": null } ``` **Campos da Resposta**: | Campo | Tipo | Descrição | | --------------------- | ------ | --------------------------------------------------------------------------- | | `id` | string | ID único do boleto (ex.: 8325a4b3-579c-45df-b475-0ce57df2478d). | | `status` | number | Status do boleto (`1, 2, 3, 4, 5`). | | `due_date` | string | Data de vencimento (formato `YYYY-MM-DD`). | | `grace_period` | number | Dias de tolerância após o vencimento (ex.: 15). | | `amount` | number | Valor do boleto em reais (ex.: 100.50 para R$ 100,50). | | `description` | string | Descrição do boleto (máx. 255 caracteres). | | `metadata` | array | Pares chave-valor para dados adicionais (ex.: ID do pedido). | | `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). | | `payer.zip` | string | CEP (8 dígitos, sem hífen). | | `payer.street` | string | Rua ou avenida (máx. 200 caracteres). | | `payer.city` | string | Cidade (máx. 100 caracteres). | | `payer.state` | string | UF (2 letras, ex.: `SP`). | | `payer.number` | string | Número do endereço (máx. 20 caracteres). | | `payer.neighborhood` | string | Bairro (máx. 100 caracteres). | | `fine` | number | Multa por atraso em percentual (ex.: 2.5 para 2,5%). | | `interest` | number | Juros por dia de atraso em percentual (ex.: 1.0 para 1%). | | `discount` | object | Desconto para pagamento antecipado. | | `discount.type` | string | Tipo de desconto (`fixed` ou `percentage`). | | `discount.amount` | number | Valor do desconto (em reais para `fixed`, ou percentual para `percentage`). | | `discount.limit_date` | string | Data limite para o desconto (formato `YYYY-MM-DD`). | | `notification_url` | string | URL HTTPS para webhooks (ex.: `https://your-webhook.com/notifications`). | | `customer_code` | string | Código interno do cliente (máx. 50 caracteres). | | `created_at` | string | Data de criação do boleto (ISO 8601). | | `paid_at` | string | Data de pagamento do boleto (ISO 8601, ou `null` se não pago). | ### Exemplos de Código {% tabs %} {% tab title="cURL" %} ```bash curl -X GET https://sandbox-api.pagou.com.br/v1/charges/8325a4b3-579c-45df-b475-0ce57df2478d \ -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'); const { validate } = require('jsonschema'); // Esquema de validação da resposta const schema = { type: 'object', required: ['id', 'status', 'due_date', 'amount', 'description', 'payer'], properties: { id: { type: 'string' }, status: { type: 'number', enum: [1, 2, 3, 4, 5] }, due_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$' }, grace_period: { type: 'integer', minimum: 0 }, amount: { type: 'number', minimum: 1.00 }, description: { type: 'string', maxLength: 255 }, metadata: { type: 'array', items: { type: 'object', required: ['key', 'value'], properties: { key: { type: 'string' }, value: { type: 'string' } } } }, payer: { type: 'object', required: ['name', 'document', 'zip', 'street', 'city', 'state', 'number', 'neighborhood'], properties: { name: { type: 'string', maxLength: 100 }, document: { type: 'string', pattern: '^\\d{11}|\\d{14}$' }, zip: { type: 'string', pattern: '^\\d{8}$' }, street: { type: 'string', maxLength: 200 }, city: { type: 'string', maxLength: 100 }, state: { type: 'string', pattern: '^[A-Z]{2}$' }, number: { type: 'string', maxLength: 20 }, neighborhood: { type: 'string', maxLength: 100 } } }, fine: { type: 'number', minimum: 0, maximum: 100 }, interest: { type: 'number', minimum: 0, maximum: 100 }, discount: { type: 'object', required: ['type', 'amount', 'limit_date'], properties: { type: { type: 'string', enum: ['fixed', 'percentage'] }, amount: { type: 'number', minimum: 0 }, limit_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$' } } }, notification_url: { type: 'string', format: 'uri' }, customer_code: { type: 'string', maxLength: 50 }, barcode: { type: 'string' }, pdf_url: { type: 'string', format: 'uri' }, created_at: { type: 'string', format: 'date-time' }, paid_at: { type: ['string', 'null'], format: 'date-time' } } }; // Consultar boleto const boletoId = '8325a4b3-579c-45df-b475-0ce57df2478d'; fetch(`https://sandbox-api.pagou.com.br/v1/charges/${boletoId}`, { method: 'GET', headers: { 'X-API-KEY': 'sua_chave_api', 'Content-Type': 'application/json', 'User-Agent': 'MinhaLoja/1.0' } }) .then(response => { if (!response.ok) { throw new Error(`Erro ${response.status}: ${response.statusText}`); } return response.json(); }) .then(data => { // Validar resposta const validation = validate(data, schema); if (!validation.valid) { throw new Error(`Erro de validação: ${validation.errors}`); } console.log(`Boleto ID: ${data.id}`); console.log(`Status: ${data.status}`); }) .catch(error => console.error('Erro na requisição:', error)); ``` {% endtab %} {% tab title="Python" %} ```python import requests from jsonschema import validate, ValidationError # Esquema de validação da resposta schema = { "type": "object", "required": ["id", "status", "due_date", "amount", "description", "payer"], "properties": { "id": {"type": "string"}, "status": {"type": "number", "enum": [1, 2, 3, 4, 5]}, "due_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}, "grace_period": {"type": "integer", "minimum": 1}, "amount": {"type": "number", "minimum": 1.00}, "description": {"type": "string", "maxLength": 255}, "metadata": { "type": "array", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": {"type": "string"}, "value": {"type": "string"} } } }, "payer": { "type": "object", "required": ["name", "document", "zip", "street", "city", "state", "number", "neighborhood"], "properties": { "name": {"type": "string", "maxLength": 100}, "document": {"type": "string", "pattern": "^\\d{11}|\\d{14}$"}, "zip": {"type": "string", "pattern": "^\\d{8}$"}, "street": {"type": "string", "maxLength": 200}, "city": {"type": "string", "maxLength": 100}, "state": {"type": "string", "pattern": "^[A-Z]{2}$"}, "number": {"type": "string", "maxLength": 20}, "neighborhood": {"type": "string", "maxLength": 100} } }, "fine": {"type": "number", "minimum": 0, "maximum": 100}, "interest": {"type": "number", "minimum": 0, "maximum": 100}, "discount": { "type": "object", "required": ["type", "amount", "limit_date"], "properties": { "type": {"type": "string", "enum": ["fixed", "percentage"]}, "amount": {"type": "number", "minimum": 0}, "limit_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"} } }, "notification_url": {"type": "string", "format": "uri"}, "customer_code": {"type": "string", "maxLength": 50}, "barcode": {"type": "string"}, "pdf_url": {"type": "string", "format": "uri"}, "created_at": {"type": "string", "format": "date-time"}, "paid_at": {"type": ["string", "null"], "format": "date-time"} } } # Consultar boleto boleto_id = "8325a4b3-579c-45df-b475-0ce57df2478d" url = f"https://sandbox-api.pagou.com.br/v1/charges/{boleto_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() # Validar resposta try: validate(instance=data, schema=schema) except ValidationError as e: print(f"Erro de validação na resposta: {e}") exit(1) print(f"Boleto ID: {data['id']}") print(f"Status: {data['status']}") except requests.RequestException as e: print(f"Erro na requisição: {e}") ``` {% endtab %} {% endtabs %} ### Tratamento de Erros | Código HTTP | Descrição | Possível Causa | Solução | | ----------- | --------------------- | -------------------------------- | ----------------------------------------- | | `400` | Bad Request | ID do boleto malformado. | Verificar formato do `id`. | | `401` | Unauthorized | `X-API-KEY` inválido ou ausente. | Verificar chave.. | | `404` | Not Found | Boleto não existe. | Confirmar ID do boleto. | | `429` | Too Many Requests | Limite de requisições excedido. | Implementar rate limiting e retentativas. | | `500` | Internal Server Error | Erro interno da API. | Tentar novamente e contatar suporte. | **Exemplo de Resposta de Erro**: ```json { "error": "Boleto not found" } ``` ### Boas Práticas Técnicas * **Segurança**: Armazene `X-API-KEY` em variáveis de ambiente e use HTTPS para todas as requisições. * **Webhooks como Alternativa**: Para atualizações em tempo real, configure o evento `ChargePaid` em vez de consultas frequentes. Veja Webhooks para Interações com Boleto. * **Testes no Sandbox**: Use `https://sandbox-api.pagou.com.br/v1/charges/{id}` para simular consultas sem custos reais. * **Monitoramento**: Registre todas as requisições e respostas em logs, incluindo `id`, `status` e `paid_at`, para auditoria e depuração. * **Cache**: Considere armazenar respostas em cache (ex.: Redis, com TTL de 5 minutos) para reduzir chamadas à API em sistemas de alto tráfego. ## Get a Charge > This endpoint return a charge. ```json {"openapi":"3.1.1","info":{"title":"Pagou API","version":"0.0.1"},"servers":[{"url":"https://sandbox-api.pagou.com.br"}],"security":[{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"XApiKeyAuth":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/v1/charges/{chargeID}":{"get":{"description":"This endpoint return a charge.","tags":["charges"],"summary":"Get a Charge","parameters":[{"type":"string","description":"Client Identifier","name":"User-Agent","in":"header"},{"type":"string","description":"Charge ID","name":"chargeID","in":"path","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}} ```