# Endpoints de Estornos e Consultas

Esta referência detalha os endpoints usados para pesquisar o histórico de transações e processar estornos (tanto referenciados quanto com cartão presente).

## 1. Consultar Transações (`/consulta`)

Recupera o status e os detalhes de operações passadas.

* **URL (Teste):** `https://tpvpc-i.redsys.es:27443/TPV_PC/services/rest/tpvpcwss/v1/consulta`  
* **URL (Prod):** `https://tpvpc.redsys.es/TPV_PC/services/rest/tpvpcwss/v1/consulta`  
* **Método:** `POST`

### Parâmetros da Requisição (`datosOperacion`)

| Campo | Tipo | Obrigatório | Descrição |
| :--- | :--- | :--- | :--- |
| `fechaInicio` | String | Sim | Data de início (`YYYY-MM-DD HH:mm:ss` ou `YYYY-MM-DD-HH.mm.ss`). |
| `fechaFin` | String | Sim | Data de término. O intervalo máximo é de 30 dias a partir da data de início. |
| `pedido` | String | Não | Pesquisar pelo Order ID (ID do Pedido) do sistema. |
| `factura` | String | Não | Pesquisar pela sua Referência de Fatura. |
| `operacion` | String | Não | Filtrar por tipo: `PAGO`, `PREAUTORIZACION`, `CONFIRMACION`, `DEVOLUCION`. |
| `resultado` | String | Não | Filtrar por resultado: `AUTORIZADA`, `DENEGADA`. |
| `rts` | String | Não | Pesquisar por Transaction ID (ID da Transação). Substitui todos os outros filtros. |
| `pagina` | Int | Não | Número da página para paginação (começa em 0). |

### Resposta (resultadoConsulta)

| Campo | Tipo | Descrição |
| :--- | :--- | :--- |
| `numOperaciones` | Int | Total de registros encontrados. |
| `totalPaginas` | Int | Total de páginas disponíveis. |
| `operaciones` | Array | Lista de objetos de transação contendo `importe`, `estado`, `resultado`, etc. |

## 2. Estorno Referenciado (`/devolucion`)

Estorna uma transação usando seu Order ID (`pedidoBase`) sem interação com o cartão.

* **URL (Teste):** `https://tpvpc-i.redsys.es:27443/TPV_PC/services/rest/tpvpcwss/v1/devolucion`  
* **URL (Prod):** `https://tpvpc.redsys.es/TPV_PC/services/rest/tpvpcwss/v1/devolucion`  
* **Método:** `POST`

### Parâmetros da Requisição (`datosOperacion`)

| Campo | Tipo | Obrigatório | Comprimento Máx. | Descrição |
| :--- | :--- | :--- | :--- | :--- |
| `importe` | Double | Sim | 12 | Valor a ser estornado. |
| `factura` | String | Sim | 250 | Referência para o próprio estorno. |
| `pedidoBase` | String | Sim | 50 | O `pedido` (Order ID) da venda original. |

### Resposta (`resultadoDevolucion`)

Retornado apenas se `resultado.codigo` for `0`.

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `importe` | String | Valor estornado. |
| `resultado` | String | `Autorizada` ou `Denegada`. |
| `estado` | String | `F` (Finalizada). |

## 3. Estorno com Cartão Presente (`/devolucionTarjeta`)

Inicia um estorno que requer que o cliente insira o cartão.

* **URL (Teste):** `https://tpvpc-i.redsys.es:27443/TPV_PC/services/rest/tpvpcwss/v1/devolucionTarjeta` 
* **URL (Prod):** `https://tpvpc.redsys.es/TPV_PC/services/rest/tpvpcwss/v1/devolucionTarjeta`  
* **Método:** `POST`

### Parâmetros da Requisição (`datosOperacion`)

| Campo | Tipo | Obrigatório | Comprimento Máx. | Descrição |
| :---- | :---- | :---- | :---- | :---- |
| `importe` | Double | Sim | 12 | Valor a ser estornado. |
| `factura` | String | Sim | 250 | Referência para o estorno. |
| `pedidoBase` | String | Sim | 50 | O `pedido` (Order ID) da venda original. |

### Resposta (`info`)

Reconhecimento síncrono. O resultado final é enviado via notificação.

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `resultado.codigo` | String | `0` indica sucesso. |