> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ecorpa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consulta de antecedentes

> Consulta de antecedentes por lote: autenticación, POST, GET y cómo leer la respuesta.

Consulta antecedentes enviando uno o varios registros en una sola solicitud.

El flujo es **asíncrono**: creas el lote con `POST`, guardas el `IdSolicitud` y consultas con `GET` hasta que cada ítem quede en `completado`.

Cada tipo de consulta pide datos distintos y devuelve un resultado distinto. Eso va en su página.

<CardGroup cols={2}>
  <Card title="Persona natural" icon="user" href="/consulta-antecedentes/persona-natural">
    Tipo y número de documento, fuentes e informe.
  </Card>
</CardGroup>

<Info>
  Scope: `consulta_antecedentes`. Auth en [Autenticación](/authentication).
</Info>

## Endpoints

| Método | Ruta                                      | Descripción         |
| ------ | ----------------------------------------- | ------------------- |
| `POST` | `/v2/consulta/antecedentes`               | Crea la solicitud   |
| `GET`  | `/v2/consulta/antecedentes/{IdSolicitud}` | Estado y resultados |

```text theme={"system"}
https://apis.ecorpa.com/v2
```

`IdSolicitud` es un UUID. Si el path no es un UUID válido, la ruta no existe.

## Conceptos

| Concepto  | Significado                                                           |
| --------- | --------------------------------------------------------------------- |
| Solicitud | Un `POST` puede devolver un `IdSolicitud` con las consultas aceptadas |
| Consulta  | Un ítem del lote. Los campos dependen del tipo de consulta            |
| Fuente    | Cada consulta dentro del resultado (`Fuentes[]`)                      |
| Crédito   | Cada ítem **aceptado** consume 1 crédito. Las omitidas no             |
| Omitida   | No se procesa; aparece en `ConsultasOmitidas` con `Motivo`            |
| Informe   | URL al PDF consolidado, cuando está listo                             |
| Evidencia | URL de respaldo por fuente, cuando existe                             |

## POST — Crear solicitud

El body común es `AceptarTerminos` y `Consultas`. Qué va dentro de cada ítem lo define el tipo de consulta. Ver [Persona natural](/consulta-antecedentes/persona-natural).

<Accordion title="Texto que respalda AceptarTerminos">
  Al enviar `AceptarTerminos: true`, declaras:

  > Dando cumplimiento al Régimen General de Hábeas Data (Ley 1581 de 2012) y en calidad de Responsable, declaro que para efectuar la siguiente consulta de información personal, cuento con el consentimiento o autorización previa, expresa e informada del titular de los datos personales que serán consultados en tiempo real a través de esta plataforma. Así mismo, declaro que la consulta efectuada corresponde a una finalidad legitima, consistente en el cumplimiento de los procesos de debida diligencia, seguridad y/o normas sobre prevención y lucha contra el lavado de activos, el terrorismo y corrupción que la organización debe cumplir por mandato legal o como buena práctica empresarial.
</Accordion>

### Respuesta con solicitud creada (`200`)

```json theme={"system"}
{
  "Success": true,
  "Message": "Su solicitud fue recibida y está en proceso.",
  "Data": {
    "Total": 2,
    "IdSolicitud": "f76d9c31-813c-4346-b0ec-f94b9f25a01c",
    "ConsultasAProcesar": [],
    "ConsultasOmitidas": []
  }
}
```

| Campo                | Descripción                                         |
| -------------------- | --------------------------------------------------- |
| `IdSolicitud`        | UUID de la solicitud (solo si hubo ítems aceptados) |
| `ConsultasAProcesar` | Encolados. Consumen crédito                         |
| `ConsultasOmitidas`  | No procesados, con `Motivo`                         |

Si no hay ítems para procesar, la respuesta es `200` **sin** `IdSolicitud` y **sin** débito de créditos.

### Errores del POST

| HTTP | Message                                                             | Cuándo                   |
| ---: | ------------------------------------------------------------------- | ------------------------ |
|  400 | `Cuerpo de solicitud inválido`                                      | JSON mal formado         |
|  400 | `Debe aceptar los términos (AceptarTerminos).`                      | Términos no aceptados    |
|  400 | `Consultas es obligatorio y debe incluir al menos un documento.`    | Sin consultas            |
|  400 | `El máximo permitido es 100 documentos por solicitud…`              | Más de 100               |
|  401 | `No se pudo autenticar la solicitud.`                               | Key inválida             |
|  403 | `No tiene permisos para realizar esta consulta.`                    | Sin scope                |
|  403 | `No tiene créditos disponibles para procesar esta solicitud.`       | Sin cupo                 |
|  404 | `Ruta no encontrada`                                                | Path o método incorrecto |
|  500 | `No se pudo registrar la solicitud…` / `Error interno del servidor` | Error interno            |

## GET — Consultar por IdSolicitud

```bash theme={"system"}
curl -sS -X GET "https://apis.ecorpa.com/v2/consulta/antecedentes/{IdSolicitud}" \
  -H "Authorization: Bearer ecorpa_key_xxxxxxxx"
```

### Estados

| Valor        | Significado                                    |
| ------------ | ---------------------------------------------- |
| `procesando` | Aún no hay resultado final; vuelve a consultar |
| `completado` | Resultado listo                                |
| `error`      | Falló el procesamiento de ese ítem             |

La forma de `Consultas[]` depende del tipo. Ver [Persona natural](/consulta-antecedentes/persona-natural).

Si `InformePdf` o una evidencia deja de funcionar, vuelve a llamar el `GET`.

### Errores del GET

| HTTP | Message                                          | Cuándo                   |
| ---: | ------------------------------------------------ | ------------------------ |
|  400 | `IdSolicitud inválido.`                          | UUID vacío o mal formado |
|  401 | `No se pudo autenticar la solicitud.`            | Key inválida             |
|  403 | `No tiene permisos para realizar esta consulta.` | Falta scope              |
|  404 | `No se encontró la solicitud indicada.`          | UUID inexistente         |
|  404 | `Ruta no encontrada`                             | Path incorrecto          |
|  500 | `Error interno del servidor`                     | Error interno            |

## Flujo

<Steps>
  <Step title="POST">
    Envía `Consultas` según el tipo. Guarda `Data.IdSolicitud` y revisa `ConsultasOmitidas`.
  </Step>

  <Step title="GET">
    Mientras algún ítem esté en `procesando`, vuelve a consultar.
  </Step>

  <Step title="Resultado">
    Lee el detalle en la página del tipo. [Persona natural](/consulta-antecedentes/persona-natural).
  </Step>
</Steps>

## Checklist

* API Key solo en backend
* Scope `consulta_antecedentes`
* Máximo 100 ítems por POST
* Maneja aceptadas y omitidas en la misma respuesta
* Persiste `IdSolicitud` y consulta hasta `completado`
* Distingue error HTTP de un resultado con hallazgos
* Los créditos son los ítems aceptados, no el tamaño del array enviado


## Related topics

- [Introducción](/introduction.md)
- [Persona natural](/consulta-antecedentes/persona-natural.md)
- [Inicio](/index.md)
- [Autenticación](/authentication.md)
- [Empezar](/quickstart.md)