> For the complete documentation index, see [llms.txt](https://tafi.gitbook.io/tafi-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tafi.gitbook.io/tafi-api/api-rest/consultar-estado-del-credito-polling.md).

# Consultar Estado del Crédito (Polling)

## Consultar Estado del Crédito (Polling)

Consulta el estado actual de una venta a crédito previamente registrada. Este endpoint está diseñado para ser invocado de forma periódica (polling) cuando el estado del crédito puede cambiar de manera asíncrona, permitiendo al comercio validar si una transacción fue aprobada, anulada o sigue pendiente.

### Endpoint

<mark style="color:green;">`GET`</mark>` ``/creditos-ventas/detalledeventa`

### Headers

| Nombre         | Tipo   | Requerido | Descripción                                             |
| -------------- | ------ | --------- | ------------------------------------------------------- |
| `TAFI-API-KEY` | string | Sí        | Clave de autenticación de la API proporcionada por TAFI |

### Query Parameters

| Campo                | Tipo          | Requerido | Descripción                                                      |
| -------------------- | ------------- | --------- | ---------------------------------------------------------------- |
| `idComercio`         | string (UUID) | Sí        | Identificador único del comercio donde se realizó la venta       |
| `numeroAutorizacion` | string        | Sí        | Número de autorización generado al momento de registrar la venta |
| `idTransaccion`      | string        | Sí        | Identificador único de la transacción a consultar                |

### Ejemplo de Request

```bash
curl --location 'https://api.tafitech.io/dev/creditos-ventas/detalledeventa?idComercio={TU_ID_COMERCIO}&numeroAutorizacion=000000&idTransaccion=0000000000' \
--header 'TAFI-API-KEY: {TU_API_KEY}'
```

### Condición de Aprobación

> ✅ **Un crédito se considera APROBADO únicamente cuando se cumplen ambas condiciones:**
>
> * `codigoRespuesta` igual a **`1`**
> * `creditoFirmado` igual a **`true`**
>
> Si cualquiera de las dos condiciones no se cumple, el crédito **no debe considerarse aprobado**.

### Patrón de Polling Recomendado

> ℹ️ **¿Qué es polling?** Es la práctica de consultar periódicamente el estado de un recurso hasta obtener una respuesta definitiva. Se utiliza cuando el resultado de una operación no es inmediato y depende de procesos asíncronos como la firma del crédito por parte del cliente.

Para validar el estado de un crédito de manera eficiente, se recomienda seguir este patrón:

1. **Intervalo de consulta:** Realizar la primera consulta entre **5 y 10 segundos** después de iniciada la transacción.
2. **Frecuencia:** Repetir la consulta cada **5 a 10 segundos** mientras el crédito no haya sido firmado.
3. **Tiempo máximo de espera:** El cliente dispone de **5 minutos** para firmar el crédito. Si transcurrido este tiempo el crédito sigue sin firmar, detener el polling y notificar al usuario.
4. **Condición de salida:** Detener el polling cuando se cumpla la condición de aprobación (`codigoRespuesta === 1` y `creditoFirmado === true`).

⚠️ **Evite el polling agresivo.** Realizar consultas con intervalos menores a 5 segundos puede generar bloqueos por rate limiting y degradar la experiencia. Implemente siempre un mecanismo de *backoff* ante errores consecutivos.

#### Diagrama de flujo

<figure><img src="https://3731400750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx1iY0PT7MSAqRhK9XlbU%2Fuploads%2FAOFfCIXME1DJS5lgq3Nu%2FCr%C3%A9dito%20Aprobado-2026-05-07-170235.png?alt=media&amp;token=0472df72-5083-4409-8a37-161bb80e6993" alt="" width="375"><figcaption></figcaption></figure>

### Respuesta Exitosa

```json
{
    "codigoRespuesta": 1,
    "idTransaccion": "0000000000",
    "valor": 0,
    "numeroAutorizacion": "000000",
    "vendedor": "NOMBREVENDEDOR",
    "sucursal": "Nombre de la Sucursal",
    "estadoCredito": "Aprobado",
    "creditoFirmado": true,
    "fechaSolicitud": "AAAA-MM-DD HH:MM:SS",
    "descripcionError": ""
}
```

### Campos de Respuesta

| Campo                | Tipo    | Descripción                                                        |
| -------------------- | ------- | ------------------------------------------------------------------ |
| `codigoRespuesta`    | integer | Código de respuesta de la operación. `1` indica éxito              |
| `idTransaccion`      | string  | Identificador único de la transacción consultada                   |
| `valor`              | number  | Monto de la venta a crédito                                        |
| `numeroAutorizacion` | string  | Número de autorización de la venta                                 |
| `vendedor`           | string  | Usuario o vendedor que registró la transacción                     |
| `sucursal`           | string  | Sucursal del comercio donde se realizó la venta                    |
| `estadoCredito`      | string  | Estado actual del crédito (ej. `Aprobado`, `Anulado`, `Pendiente`) |
| `creditoFirmado`     | boolean | Indica si el cliente ya firmó el crédito                           |
| `fechaSolicitud`     | string  | Fecha y hora en que se solicitó el crédito                         |
| `descripcionError`   | string  | Mensaje descriptivo en caso de error. Vacío si no hay errores      |

### Respuestas de Error

| Código | Descripción                                  |
| ------ | -------------------------------------------- |
| `400`  | Parámetros inválidos o faltantes             |
| `401`  | API Key inválida o no proporcionada          |
| `404`  | Transacción o comercio no encontrado         |
| `429`  | Demasiadas solicitudes (rate limit excedido) |
| `500`  | Error interno del servidor                   |

### Ejemplo de Implementación

```javascript
async function consultarEstadoCredito(idComercio, numeroAutorizacion, idTransaccion) {
    const url = `https://api.tafitech.io/dev/creditos-ventas/detalledeventa?idComercio=${idComercio}&numeroAutorizacion=${numeroAutorizacion}&idTransaccion=${idTransaccion}`;
    
    const intervaloMs = 7000;      // 7 segundos entre consultas
    const tiempoMaxMs = 300000;    // 5 minutos máximo
    const inicio = Date.now();

    while (Date.now() - inicio < tiempoMaxMs) {
        const response = await fetch(url, {
            headers: { 'TAFI-API-KEY': '{TU_API_KEY}' }
        });
        const data = await response.json();

        // Condición de aprobación
        if (data.codigoRespuesta === 1 && data.creditoFirmado === true) {
            return { aprobado: true, data };
        }

        // Estado final no aprobado (ej. Anulado)
        if (data.estadoCredito === 'Anulado') {
            return { aprobado: false, data };
        }

        await new Promise(resolve => setTimeout(resolve, intervaloMs));
    }

    throw new Error('Tiempo de espera agotado: el crédito no fue firmado');
}
```