Personal Protektor - Documentación API
API REST Corporate Asíncrona x-api-key

Documentación de integración search corporate

Esta API permite a sistemas empresariales realizar consultas de riesgo mediante autenticación basada en API Key. El procesamiento se ejecuta de forma asíncrona, lo que permite escalabilidad, trazabilidad y una integración más robusta para flujos corporativos.

Autenticación
Header x-api-key
Tipo de respuesta
Inmediata con request_id
Ejecución
Procesamiento asíncrono
Notificación final
Correo y callback

1. Resumen funcional

En el flujo corporate, la empresa consumidora no envía los datos del solicitante en el body. Esa información es resuelta internamente a partir de la configuración asociada a la API Key autorizada.

Autenticación

La autenticación se realiza exclusivamente con el header x-api-key.

Procesamiento

El endpoint registra la solicitud, la envía a cola y devuelve un identificador único de seguimiento.

Requester automático

Los datos del solicitante se obtienen internamente desde la configuración corporativa autorizada.

Notificación final

Al finalizar el proceso, el resultado puede notificarse por correo y opcionalmente por callback HTTP.

2. Flujo general de funcionamiento

1
La empresa envía una solicitud con la información de la persona o entidad consultada.
2
El sistema valida la x-api-key y resuelve la organización asociada.
3
El sistema obtiene internamente la información del solicitante corporativo.
4
Se crea el registro de la solicitud y se devuelve una respuesta inmediata con request_id.
5
Una tarea asíncrona ejecuta validaciones y realiza la búsqueda en las fuentes correspondientes.
6
Cuando el procesamiento termina, el estado de la solicitud se actualiza y se envía la notificación final.
7
Si la API Key tiene un callback configurado, también se notifica al sistema cliente.

3. Endpoint

Método Ruta Descripción
POST /personalprotektor/search-corporate/ Recibe la solicitud corporate, valida la API Key, encola el proceso y devuelve un identificador de seguimiento.

4. Headers requeridos

Header Requerido Descripción
x-api-key Sí Llave de autenticación entregada a la empresa consumidora.
Content-Type Sí Debe enviarse como application/json.

5. Body de la solicitud

Importante: en este flujo no se debe enviar el bloque requester. Esa información es resuelta internamente por el sistema.

Ejemplo de request

{ "requested": { "identification_type": "CC", "identification": "123456789", "expedition_date": "01/01/2000" }, "email_notify": "mail@dominio.com", "is_personal": true, "external_id": "EMP-REQ-0001" }

Campos permitidos

Campo Tipo Requerido Descripción
requested.identification_type string Sí Tipo de identificación del consultado. Valores permitidos: CC, NIT.
requested.identification string Sí Número de identificación del consultado.
requested.expedition_date string Sí Fecha de expedición en formato DD/MM/YYYY.
email_notify string Sí Correo electrónico al cual se enviará la notificación final.
is_personal boolean Sí Indicador del tipo de consulta. Por defecto se espera true.
external_id string Sí Identificador propio del cliente para correlacionar la consulta en su sistema.

6. Respuesta inmediata

La API no devuelve el informe final en esta primera respuesta. En su lugar, responde con un acuse de recibo que confirma la recepción y el inicio del procesamiento.

{ "request_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "Processing", "is_corporate": true, "external_id": "EMP-REQ-0001" }
Campo Descripción
request_id Identificador único interno de la solicitud.
status Estado inicial del procesamiento. Normalmente Processing o equivalente.
is_corporate Indica que la solicitud fue procesada por el flujo corporate.
external_id Identificador enviado por el cliente, si fue suministrado.

7. Validaciones de negocio

  • La x-api-key debe ser válida y pertenecer a una organización activa.
  • La estructura requested debe existir y tener formato válido.
  • El tipo de documento permitido actualmente es CC o NIT.
  • La fecha de expedición debe enviarse en formato DD/MM/YYYY.
  • En el flujo corporate no se acepta el bloque requester en la solicitud.
  • La información del solicitante se obtiene internamente desde la configuración autorizada.

8. Estados del proceso

Estado Significado
Queued La solicitud fue registrada y quedó en cola para procesamiento.
Validating El sistema está validando datos antes de ejecutar la búsqueda.
Searching La búsqueda ya fue enviada a las fuentes externas.
Processed La consulta terminó correctamente y ya puede notificarse.
Failed La consulta terminó con error funcional o técnico.

9. Callback al sistema cliente

Si la API Key tiene configurado un callback_endpoint, el sistema enviará una notificación HTTP al finalizar el procesamiento. El callback puede incluir cabeceras personalizadas definidas previamente para la integración.

Ejemplo de callback exitoso

{ "event": "personalprotektor.search.completed", "request_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "external_id": "EMP-REQ-0001", "status": "Processed", "success": true, "is_corporate": true, "organization": "NombreOrganizacion", "requested": { "identification_type": "CC", "identification": "123456789", "expedition_date": "2000-01-01" }, "search_id": "abc123", "pdf_url": "url/abc123", "error": "" }

Ejemplo de callback con error

{ "event": "personalprotektor.search.failed", "request_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "external_id": "EMP-REQ-0001", "status": "Failed", "success": false, "is_corporate": true, "organization": "NombreOrganizacion", "requested": { "identification_type": "CC", "identification": "123456789", "expedition_date": "2000-01-01" }, "search_id": null, "error": "Validation failed for requested." }

10. Códigos de respuesta esperados

Código HTTP Descripción
202 Accepted La solicitud fue aceptada y enviada a procesamiento asíncrono.
400 Bad Request La estructura del request o algún dato enviado es inválido.
401 / 403 La API Key no es válida, no tiene permisos o no está habilitada.
500 Internal Server Error Error no controlado del servicio.

11. Ejemplo en cURL

curl --request POST 'https://TU-DOMINIO/personalprotektor/search-corporate/' \ --header 'Content-Type: application/json' \ --header 'x-api-key: TU_API_KEY' \ --data '{ "requested": { "identification_type": "CC", "identification": "123456789", "expedition_date": "01/01/2000" }, "email_notify": "mail@dominio.com", "is_personal": true, "external_id": "EMP-REQ-0001" }'

12. Consideraciones de la integración

  • Guardar el request_id y el external_id para asegurar trazabilidad completa.
  • No reenviar múltiples veces la misma solicitud sin un mecanismo de control de idempotencia del lado cliente.
  • Configurar previamente el callback con la URL correcta y las cabeceras necesarias.
  • Validar que el sistema cliente pueda recibir requests desde la infraestructura de la API.
  • El mecanismo principal de integración es el callback.

13. Contacto y soporte

Para soporte técnico, validación de credenciales, pruebas de integración o actualización del callback, la empresa consumidora debe coordinar directamente con el equipo responsable del servicio Personal Protektor.