# Cancelando um QRCode

## Cancelando um QRCode

O cancelamento de um QRCode na API do Pagou permite invalidar um QRCode Pix ativo (com ou sem vencimento), tornando-o não mais utilizável para pagamento. .

### Visão Geral Técnica

O endpoint <mark style="color:red;">`DELETE`</mark>` ``/v1/pix/{id}` solicita o cancelamento de um QRCode identificado por seu ID único no formato UUID (ex.: 550e8400-e29b-41d4-a716-446655440000). A operação é síncrona, retornando `204 No Content` para indicar que o cancelamento foi bem-sucedido, e o status do QRCode é alterado para <mark style="color:orange;">`StatusCanceled`</mark>. Este endpoint é útil para invalidar QRCodes antes de sua expiração ou em caso de erro na criação.

**Especificações**:

* **Método**: <mark style="color:red;">`DELETE`</mark>
* **URL**:
  * Produção: `https://api.pagou.com.br/v1/pix/{id}`
  * Sandbox: `https://sandbox.api.pagou.com.br/v1/pix/{id}`
* **Autenticação**: Cabeçalho `X-API-KEY` com chave do painel.
* **Content-Type**: `application/json`
* **Resposta**: Status `204 No Content` sem corpo.
* **Erros**: 400 Bad Request, 401 Unauthorized, 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**:

* O QRCode deve estar no status <mark style="color:orange;">`StatusActive`</mark> para ser cancelado. QRCodes em <mark style="color:orange;">`StatusEmpty`</mark>, <mark style="color:orange;">`StatusCanceled`</mark>, <mark style="color:orange;">`StatusCompleted`</mark> ou <mark style="color:orange;">`StatusRefunded`</mark> não podem ser cancelados.

**Notas Técnicas**:

* O endpoint <mark style="color:red;">`DELETE`</mark>` ``/v1/pix/{id}` transita o status do QRCode de <mark style="color:orange;">`StatusActive`</mark> para StatusCanceled.
* QRCodes em estados diferentes de <mark style="color:orange;">`StatusActive`</mark> (ex.: <mark style="color:orange;">`StatusCompleted`</mark>, <mark style="color:orange;">`StatusCanceled`</mark>) resultarão em erro 400 Bad Request.

### Resposta

* **Status**: 204 No Content
* **Corpo**: Nenhum (a resposta não contém corpo, indicando sucesso no cancelamento).

### Exemplos de Código

{% tabs %}
{% tab title="cURL" %}

```ruby
curl -X DELETE 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: 'DELETE',
    headers: headers
})
    .then(response => {
        if (!response.ok) {
            return response.json().then(err => { throw new Error(`Erro ${response.status}: ${err.error.message}`); });
        }
        console.log(`QRCode ${qrcodeId} cancelado com sucesso`);
    })
    .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.delete(url, headers=headers)
    response.raise_for_status()
    print(f"QRCode {qrcode_id} cancelado com sucesso")
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 ou QRCode não está no status StatusActive. | Verificar formato do id e consultar status com <mark style="color:purple;">`GET`</mark>` ``/v1/pix/{id}`. |
| 401         | Unauthorized          | `X-API-KEY` inválido ou ausente.                                   | Verificar chave.                                                                                          |
| 500         | Internal Server Error | Erro interno da API.                                               | Tentar novamente e contatar <contato@pagou.com.br>.                                                       |

**Exemplo de Resposta de Erro**:

```json
{
  "error": "QRCode is not in active status"
}
```

### Boas Práticas Técnicas

* **Verificação Prévia**: Consulte o status do QRCode com GET /v1/pix/{id} (veja Consultando um QRCode) para confirmar que está em StatusActive antes de tentar cancelar.
* **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 e código de status HTTP) em logs para auditoria e depuração.
* **Confirmação de Cancelamento**: Após o cancelamento, use <mark style="color:purple;">`GET`</mark>` ``/v1/pix/{id}` para verificar se o status mudou para StatusCanceled.
* **Testes no Sandbox**: Use `https://sandbox.api.pagou.com.br/v1/pix/{id}` para simular cancelamentos sem impacto em produção.
* **Gestão de Erros**: Trate erros 400 para evitar tentativas de cancelamento de QRCodes já pagos (<mark style="color:orange;">`StatusCompleted`</mark>) ou cancelados (<mark style="color:orange;">`StatusCanceled`</mark>).


---

# 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/cancelando-um-qrcode.md?ask=<question>
```

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.