> 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/referencia-de-errores.md).

# Referencia de Errores

## API Referencia de Errores

|              |                                               |
| ------------ | --------------------------------------------- |
| **Base URL** | `https://api.tafitech.io/dev/creditos-ventas` |
| **Versión**  | 1.0                                           |
| **Fecha**    | Abril 2026                                    |

**Propósito:** Referencia completa de códigos de error, escenarios de prueba y validaciones esperadas para la integración con la API de Créditos-Ventas de TafiTech.

***

### 1. SolicitarCredito

#### Endpoint

**Método / URL:** `POST https://api.tafitech.io/dev/creditos-ventas/solicitarCredito`

#### Tabla de errores y casos de prueba

<table data-first-column-sticky><thead><tr><th>HTTP</th><th>Escenario</th><th>descripcionError</th><th>Validación esperada</th></tr></thead><tbody><tr><td>400</td><td>InvalidIdComercio — request body ausente / mal formado</td><td><code>The request field is required.</code></td><td>Validation error del binder cuando falta el objeto <code>request</code>.</td></tr><tr><td>400</td><td>Missing celular — falta <code>NumeroCelularComprador</code></td><td><code>The NumeroCelularComprador field is required.</code></td><td>Campo <code>NumeroCelularComprador</code> requerido; el error referencia el nombre del campo.</td></tr><tr><td>400</td><td>Invalid celular (no numérico / muy corto)</td><td><code>comprador no encontrado por numero de celular</code></td><td>Formato de celular inválido → el sistema no encuentra comprador asociado.</td></tr><tr><td>400</td><td><code>valor = 0</code></td><td><code>Monto por debajo del mínimo permitido</code></td><td><code>valor</code> debe ser positivo y superar el mínimo configurado.</td></tr><tr><td>400</td><td>Valor negativo (ej. <code>-25.01</code>)</td><td><code>Monto por debajo del mínimo permitido</code></td><td>Valores negativos son rechazados con el mismo mensaje que el mínimo.</td></tr><tr><td>400</td><td>Valor supera <code>cupoDisponible</code> del cliente (577.73 > 577.72 cupo)</td><td><code>Monto supera limite aprobado</code></td><td><code>codigoRespuesta=0</code>, <code>numeroAutorizacion</code> vacío. Límite exclusivo: 1 centavo sobre el cupo dispara el rechazo.</td></tr><tr><td>200 (éxito)</td><td>Valor exactamente igual al <code>cupoDisponible</code> (577.72 = cupo — borde superior exitoso)</td><td><code>""</code></td><td><code>codigoRespuesta=1</code>, <code>numeroAutorizacion="983018"</code>. El monto igual al cupo es aceptado (límite inclusivo).</td></tr><tr><td>400</td><td>ClienteNoExiste — celular válido pero sin comprador registrado</td><td><code>comprador no encontrado por numero de celular</code></td><td>Mismo <code>descripcionError</code> que TC-SC-06 pero por causa diferente: formato válido, cliente inexistente.</td></tr><tr><td>400</td><td>Monto edge case $19.99 — 1 centavo por debajo del mínimo ($20.00)</td><td><code>Monto por debajo del mínimo permitido</code></td><td><code>codigoRespuesta=0</code>. Mínimo inclusivo: $20.00 pasa, $19.99 es rechazado.</td></tr><tr><td>400</td><td>Valor sobre la venta máxima del comercio (1500.01)</td><td><code>Comercio no autorizado para vender</code></td><td><code>codigoRespuesta=0</code>. Restricción del comercio, distinto de límite del comprador.</td></tr><tr><td>400</td><td>Cliente con créditos en mora</td><td><code>Comprador no elegible para créditos</code></td><td><code>codigoRespuesta=0</code>. Se activa cuando el comprador tiene mora activa en otros créditos TafiTech.</td></tr><tr><td>404</td><td><code>idComercio</code> no existe en el sistema</td><td><code>Comercio no encontrado</code></td><td><code>codigoRespuesta=0</code>, <code>numeroAutorizacion</code> vacío. UUID de comercio desconocido o inactivo.</td></tr></tbody></table>

***

### 3. RevertirVenta

#### Endpoint

**Método / URL:** `POST https://api.tafitech.io/dev/creditos-ventas/revertirventa`

#### Tabla de errores y casos de prueba

| HTTP | Escenario                                                 | descripcionError                 | Validación esperada                                                                               |
| ---- | --------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------- |
| 400  | Missing `idComercio` — request body ausente / mal formado | `The request field is required.` | `idComercio` es requerido; cuando falta el body completo el error referencia el objeto `request`. |
| 400  | Missing `Motivo`                                          | `The Motivo field is required.`  | Campo `Motivo` requerido para poder revertir la venta.                                            |

***

### 4. DetalleVenta (estados de crédito)

#### Endpoint

**Método / URL:** `GET https://api.tafitech.io/dev/creditos-ventas/detalledeventa`

El crédito tiene estos estados posibles:

1. **Creado**
2. **Aceptado** (EsperandoFirma)
3. **Finalizado** (luego de que el cliente ingresa el token)

> De los cuales **ninguna** de las transiciones se registra en el webhook.

#### Tabla de resultados y estados

| estadoCredito | codigoRespuesta | creditoFirmado | Escenario                                                                          | Validación                                                                                                                                           |
| ------------- | --------------- | -------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rechazado     | 1               | false          | Crédito aceptado por la API pero rechazado durante el proceso de firma del cliente | `codigoRespuesta=1` indica consulta exitosa; el estado de negocio viene en `estadoCredito`. `creditoFirmado=false` confirma que el cliente no firmó. |

***

### 5. Webhook — Notificación de firma de crédito

El Webhook notifica al comercio cuando el cliente firma (o rechaza) el crédito. El payload siempre incluye `creditoFirmado` para indicar si el cliente completó la firma.

#### Campos del payload

| Campo                | Tipo    | Descripción                                                        |
| -------------------- | ------- | ------------------------------------------------------------------ |
| `numeroAutorizacion` | string  | Número de autorización del crédito (mismo que en SolicitarCredito) |
| `idTransaccion`      | string  | ID de transacción generado por el comercio                         |
| `valor`              | number  | Monto de la venta                                                  |
| `creditoFirmado`     | boolean | `true` = cliente firmó; `false` = cliente rechazó o no firmó       |

{% hint style="info" %}
**Nota:** `creditoFirmado: false` en el Webhook equivale a un `estadoCredito="Rechazado"` en `DetalleVenta`. El integrador debe manejar **ambos mecanismos** para detectar rechazos de firma.
{% endhint %}