Consulta de antecedentes

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.

Persona natural

Tipo y número de documento, fuentes e informe.

Scope: consulta_antecedentes. Auth en Autenticación.

Endpoints

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

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.

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.

Respuesta con solicitud creada (`200`)

{
  "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

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. 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

POST

Envía Consultas según el tipo. Guarda Data.IdSolicitud y revisa ConsultasOmitidas.

GET

Mientras algún ítem esté en procesando, vuelve a consultar.

Resultado

Lee el detalle en la página del tipo. Persona natural.

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

Guía

Servicios

Consulta de antecedentes

Persona natural

Endpoints

Conceptos

POST — Crear solicitud

Respuesta con solicitud creada (`200`)

Errores del POST

GET — Consultar por IdSolicitud

Estados

Errores del GET

Flujo

Checklist

Persona natural

​Endpoints

​Conceptos

​POST — Crear solicitud

​Respuesta con solicitud creada (200)

​Errores del POST

​GET — Consultar por IdSolicitud

​Estados

​Errores del GET

​Flujo

​Checklist

Endpoints

Conceptos

POST — Crear solicitud

Respuesta con solicitud creada (`200`)

Errores del POST

GET — Consultar por IdSolicitud

Estados

Errores del GET

Flujo

Checklist