Resumen

Vista general de los recursos de API documentados y sus operaciones disponibles.

Recurso	Endpoints	Ruta base	Funciones
CV y análisis	7	`/api/v2/resumes`	Análisis extendido, archivos y gestión de CV
Ofertas	6	`/api/v2/jobs`	Análisis de archivos, filtros y gestión de ofertas
Puntuaciones	4	`/api/v2/recruiter-scores`	Matching de recursos guardados y webhooks de clasificación
Generación de PDF	3	`/api/v2/pdf-generation`	Ajustes, PDF individuales y lotes por webhook

20 endpoints documentadosAutenticación mediante clave APIRespuestas JSON, multipart y PDF

Plan de pruebas de Postman

La colección del backend contiene 27 solicitudes que cubren 20 rutas distintas. Trece rutas se ejecutan de forma predeterminada; siete solicitudes opcionales quedan desactivadas hasta que proporciones archivos locales, permisos del parser o un webhook configurado. Ejecuta la colección en orden para que funcionen los identificadores de prueba y los pasos de limpieza.

Esquemas y modelos JSON

Estas plantillas coinciden con los DTO, entidades, nombres de propiedades Jackson y envoltorios de respuesta del backend usados en esta página.

DocumentationResumeRequest → UpdateResumeDto

Solicitud para crear o actualizar un CV

Se usa en POST y PUT /api/v2/resumes. El contenido del CV siempre debe ir dentro de la propiedad resume.

ParserResponseDTO

Respuesta del parser de CV

La devuelve POST /api/v2/resumes/parser. Es la respuesta normalizada del parser, no el recurso CVXml que devuelve GET /api/v2/resumes/{resumeId}.

DocumentationService

Envoltorios de recursos de CV

Crear y consultar devuelven CVXml dentro de resume. Actualizar devuelve UpdateResumeDto normalizado dentro de resume. CVXml usa nombres de campos históricos en francés.

Job entity

Solicitud y respuesta de oferta

POST y PUT aceptan la entidad Job. PUT sustituye los campos documentados; envía todos los valores que quieras conservar. Las respuestas también pueden incluir id, filePath, pauseReason, jobskills, createdAt y updatedAt.

DocumentationService / DocumentationJobService

Envoltorios de listas de CV y ofertas

Los dos endpoints de lista utilizan las mismas claves de paginación. La clave de colección cambia según el recurso.

RecruiterScoreDto

Respuesta de puntuación de selección

La devuelven ambos endpoints de matching síncrono y se incluye en los datos de los webhooks de clasificación.

ResumeSettings, ColorSettings, SectionSettings, ResumeCanvasImage

Ajustes de generación de PDF

Se usa en PUT /api/v2/pdf-generation/settings. El ID de sección es de solo lectura; el servidor genera el ID de la imagen del lienzo.

WebhookController.WebhookSettingsDto / DocumentationPdfService

Ajustes de webhook y respuestas en cola

Registrar un webhook requiere autenticación de sesión de reclutador. El endpoint de webhook PDF v2 devuelve la respuesta de lote aceptado que se muestra abajo.

CV y análisis

Analiza, crea, consulta, actualiza y elimina los CV del usuario de la clave API.

Respuestas del cliente CV: los 3 esquemas necesarios

Estas son las formas exactas de las respuestas correctas que debe deserializar el cliente. Los campos detallados de CVXml y UpdateResumeDto están en la sección Esquemas.

POST /api/v2/resumes/parser

1. Analizar un archivo

Enviar:Envía multipart/form-data: file (obligatorio), parserType (opcional).

Recibir:Lee la respuesta ParserResponseDTO guardada.

POST /api/v2/resumes

2. Crear un CV estructurado

Enviar:Envía application/json. El envoltorio resume es obligatorio.

Recibir:Guarda el id del envoltorio CVXml creado; será resumeId en las siguientes llamadas.

PUT /api/v2/resumes/{resumeId}

3. Actualizar un CV

Enviar:Usa el mismo envoltorio obligatorio { resume: ... } que al crear.

Recibir:La respuesta contiene el id y el UpdateResumeDto guardado.

POST/api/v2/resumes/parser

Analizar un archivo de CV

Analiza y guarda un CV enviado como archivo multipart.

Solicitud

multipart/form-data · file (archivo) · parserType? (BASIC | ADVANCED)

Correcto

200 · JSON o XML · ParserResponseDTO guardado

400 — Archivo de CV no válido401 — La clave API no es válida o falta402 — Créditos insuficientes403 — No se permite analizar archivos

curl -X POST "https://cvreaderpro.com/api/v2/resumes/parser" \
  -H "Authorization: ApiKey YOUR_API_KEY" -H "Accept: application/json" \
  -F "file=@resume.pdf" -F "parserType=ADVANCED"

Esquema de respuesta

ParserResponseDTO

DocumentationResumeController.parseResume

POST/api/v2/resumes/extended-parser

Ejecutar el parser de CV extendido

Analiza un archivo de CV subido o un campo de texto con el parser extendido. Esta ruta requiere una clave API autorizada y consume créditos de análisis premium.

Solicitud

multipart/form-data · file? (archivo) o text? (cadena) · indica exactamente una entrada

Correcto

200 · objeto JSON con los datos extendidos del CV

400 — Falta el archivo o el texto, o no es válido401 — La clave API no es válida o falta402 — Créditos insuficientes403 — Se requiere una suscripción o prueba del parser422 — No se pudo analizar el documento429 — Se superó el límite del parser extendido

file

curl --fail-with-body -X POST "https://cvreaderpro.com/api/v2/resumes/extended-parser" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "file=@resume.pdf"

text

curl --fail-with-body -X POST "https://cvreaderpro.com/api/v2/resumes/extended-parser" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Accept: application/json" \
  --form-string "text=Alex Sample
QA engineer with API testing experience."

Esquema de respuesta

Objeto JSON del parser extendido

DocumentationService.parseExtended

GET/api/v2/resumes

Listar los CV del usuario

Devuelve una colección paginada que solo incluye los CV del usuario de la clave API.

Solicitud

parámetros de consulta · page? (número, por defecto 0) · size? (número, por defecto 10)

Correcto

200 · colección paginada { resumes, currentPage, totalItems, totalPages }

curl -X GET "https://cvreaderpro.com/api/v2/resumes?page=0&size=10" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Esquema de respuesta

Colección paginada de CV

DocumentationService.getResumes

POST/api/v2/resumes

Crear un CV

Crea un CV estructurado. Envía DocumentationResumeRequest ({ resume: UpdateResumeDto }); también se acepta un recurso con formato CVXml obtenido de una respuesta de lectura.

Solicitud

application/json · DocumentationResumeRequest

Correcto

201 · cabecera Location: /api/v2/resumes/{id} · { id, resume: CVXml }

400 — Datos del CV no válidos401 — La clave API no es válida o falta

curl -X POST "https://cvreaderpro.com/api/v2/resumes" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resume": {"candidate": { "firstName": "Ada", "lastName": "Lovelace", "personalEmail": "ada@example.com" },"profile": "Backend engineer","experiences": [], "educations": [], "languages": [], "skills": [],"softSkills": [], "references": []}}'

Esquema de respuesta

Envoltorio del CV creado

DocumentationService.createResume

GET/api/v2/resumes/{resumeId}

Obtener un CV del usuario

Devuelve el CV si existe el UUID y pertenece al usuario de la clave API.

Solicitud

parámetro de ruta · resumeId (UUID)

Correcto

200 · recurso CV { id, resume: CVXml }

401 — La clave API no es válida o falta403 — El recurso no pertenece al usuario de esta clave API404 — No se encontró el recurso

curl -X GET "https://cvreaderpro.com/api/v2/resumes/RESUME_UUID" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Esquema de respuesta

Envoltorio del CV

DocumentationService.getResume

PUT/api/v2/resumes/{resumeId}

Actualizar un CV del usuario

Actualiza un CV usando el mismo contenedor DocumentationResumeRequest que se utiliza al crearlo.

Solicitud

parámetro de ruta · resumeId (UUID) · application/json · DocumentationResumeRequest

Correcto

200 · { id, resume: UpdateResumeDto } actualizado

401 — La clave API no es válida o falta403 — El recurso no pertenece al usuario de esta clave API404 — No se encontró el recurso

curl -X PUT "https://cvreaderpro.com/api/v2/resumes/RESUME_UUID" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resume": {"candidate": { "firstName": "Ada", "lastName": "Lovelace", "personalEmail": "ada@example.com" },"profile": "Backend engineer","experiences": [], "educations": [], "languages": [], "skills": [],"softSkills": [], "references": []}}'

Esquema de respuesta

Envoltorio del CV actualizado

DocumentationService.updateResume

DELETE/api/v2/resumes/{resumeId}

Eliminar un CV del usuario

Elimina un CV que pertenece al usuario de la clave API.

Solicitud

parámetro de ruta · resumeId (UUID)

Correcto

204 · sin contenido

401 — La clave API no es válida o falta404 — No se encontró el recurso

curl -X DELETE "https://cvreaderpro.com/api/v2/resumes/RESUME_UUID" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Esquema de respuesta

Sin cuerpo de respuesta

DocumentationService.deleteResume

Ofertas

Analiza archivos de ofertas y gestiona las ofertas estructuradas del usuario autenticado.

POST/api/v2/jobs/parser

Analizar y guardar un archivo de oferta

Analiza una descripción de empleo subida como archivo multipart y crea la oferta para el usuario autenticado.

Solicitud

multipart/form-data · file (archivo)

Correcto

200 · application/json · oferta creada

400 — Archivo de oferta no válido401 — La clave API no es válida o falta

curl -X POST "https://cvreaderpro.com/api/v2/jobs/parser" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -F "file=@job-description.pdf"

Esquema de respuesta

Oferta

DocumentationJobController.parseJob

GET/api/v2/jobs

Listar las ofertas del usuario

Devuelve una colección paginada y filtrable de ofertas que pertenecen al usuario de la clave API.

Solicitud

parámetros · page? · size? · status? · source? · reference? · title? · postedFrom? · postedTo? (fecha y hora ISO)

Correcto

200 · colección paginada { jobs, currentPage, totalItems, totalPages }

401 — La clave API no es válida o falta

curl "https://cvreaderpro.com/api/v2/jobs?page=0&size=20&status=ACTIVE&title=engineer" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Esquema de respuesta

Colección paginada de ofertas

DocumentationJobService.getJobs

POST/api/v2/jobs

Crear una oferta

Crea una oferta estructurada a partir de la entidad Job. La plantilla JSON completa está en Esquemas; la respuesta añade campos generados por el servidor.

Solicitud

application/json · objeto Job

Correcto

201 · oferta creada

401 — La clave API no es válida o falta

curl -X POST "https://cvreaderpro.com/api/v2/jobs" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data @job.json

Esquema de respuesta

Oferta

DocumentationJobService.createJob

GET/api/v2/jobs/{jobIdOrReference}

Obtener una oferta del usuario

Busca una oferta por UUID o referencia y solo la devuelve si pertenece al usuario de la clave API.

Solicitud

parámetro de ruta · jobIdOrReference (UUID o referencia de texto)

Correcto

200 · recurso de oferta

401 — La clave API no es válida o falta403 — El recurso no pertenece al usuario de esta clave API404 — No se encontró el recurso

curl "https://cvreaderpro.com/api/v2/jobs/JAVA-001" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Esquema de respuesta

Oferta

DocumentationJobService.getJob

PUT/api/v2/jobs/{jobIdOrReference}

Actualizar una oferta del usuario

Actualiza una oferta por UUID o referencia. El backend asigna todos los campos editables documentados; envía el objeto Job completo para evitar borrar valores.

Solicitud

parámetro de ruta · jobIdOrReference · application/json · objeto Job

Correcto

200 · recurso de oferta actualizado

401 — La clave API no es válida o falta403 — El recurso no pertenece al usuario de esta clave API404 — No se encontró el recurso

curl -X PUT "https://cvreaderpro.com/api/v2/jobs/JAVA-001" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data @job.json

Esquema de respuesta

Oferta

DocumentationJobService.updateJob

DELETE/api/v2/jobs/{jobIdOrReference}

Eliminar una oferta del usuario

Elimina una oferta identificada por UUID o referencia.

Solicitud

parámetro de ruta · jobIdOrReference (UUID o referencia de texto)

Correcto

204 · sin contenido

401 — La clave API no es válida o falta403 — El recurso no pertenece al usuario de esta clave API404 — No se encontró el recurso

curl -X DELETE "https://cvreaderpro.com/api/v2/jobs/JAVA-001" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Esquema de respuesta

Sin cuerpo de respuesta

DocumentationJobService.deleteJob

Puntuaciones de selección

Calcula matching detallado y entrega clasificaciones mediante webhooks.

POST/api/v2/recruiter-scores/match

Calcular el matching completo de recursos guardados

Calcula una puntuación detallada para una oferta y un CV guardados.

Solicitud

application/json · jobId (UUID) · candidateId (UUID)

Correcto

200 · RecruiterScoreDto, incluido el ID de la puntuación final

400 — jobId y candidateId son obligatorios401 — La clave API no es válida o falta

curl -X POST "https://cvreaderpro.com/api/v2/recruiter-scores/match" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobId":"JOB_UUID","candidateId":"RESUME_UUID"}'

Esquema de respuesta

RecruiterScoreDto

DocumentationRecruiterScoreController.fullMatch

POST/api/v2/recruiter-scores/match/files

Analizar y comparar dos archivos

Analiza y guarda el CV y la oferta enviados, y calcula la puntuación detallada de matching para el par creado.

Solicitud

multipart/form-data · resumeFile (archivo) · jobFile (archivo)

Correcto

200 · RecruiterScoreDto

401 — La clave API no es válida o falta

curl -X POST "https://cvreaderpro.com/api/v2/recruiter-scores/match/files" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -F "resumeFile=@resume.pdf" \
  -F "jobFile=@job.pdf"

Esquema de respuesta

RecruiterScoreDto

DocumentationRecruiterScoreController.fullMatchFiles

POST/api/v2/recruiter-scores/jobs/{jobId}/top-candidates/webhook

Encolar el webhook de mejores candidatos

Actualiza las puntuaciones y encola los 10 candidatos mejor clasificados, con todos sus detalles, para una oferta.

Solicitud

parámetro de ruta · jobId (UUID)

Correcto

202 · entrega encolada { deliveryId, eventType: "resume.matched", status: "QUEUED", resultCount }

401 — La clave API no es válida o falta

curl -X POST "https://cvreaderpro.com/api/v2/recruiter-scores/jobs/JOB_UUID/top-candidates/webhook" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Esquema de respuesta

Entrega de webhook en cola

DocumentationRecruiterScoreController.queueWebhook

POST/api/v2/recruiter-scores/resumes/{resumeId}/top-jobs/webhook

Encolar el webhook de mejores ofertas

Encola las 10 ofertas detalladas mejor clasificadas para un CV en el webhook configurado.

Solicitud

parámetro de ruta · resumeId (UUID)

Correcto

202 · entrega encolada { deliveryId, eventType: "resume.matched", status: "QUEUED", resultCount }

401 — La clave API no es válida o falta

curl -X POST "https://cvreaderpro.com/api/v2/recruiter-scores/resumes/RESUME_UUID/top-jobs/webhook" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Esquema de respuesta

Entrega de webhook en cola

DocumentationRecruiterScoreController.queueWebhook

Generación de PDF

Actualiza los ajustes de representación y genera uno o varios PDF de CV.

PUT/api/v2/pdf-generation/settings

Actualizar los ajustes de generación de PDF

Actualiza los ResumeSettings del usuario autenticado para generar PDF. Envía el modelo completo para conservar valores existentes; incluye diseño, tipografía, márgenes, colores, secciones, imágenes y marca de la agencia.

Solicitud

application/json · objeto ResumeSettings

Correcto

200 · ResumeSettings actualizado

401 — La clave API no es válida o falta

curl -X PUT "https://cvreaderpro.com/api/v2/pdf-generation/settings" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data @resume-settings.json

Esquema de respuesta

ResumeSettings

DocumentationPdfService.updateSettings

POST/api/v2/pdf-generation/resumes/{resumeId}

Generar un PDF de CV

Genera un PDF de un CV del usuario con los ajustes actuales.

Solicitud

parámetro de ruta · resumeId (UUID)

Correcto

200 · application/pdf · documento PDF

401 — La clave API no es válida o falta404 — No se encontró el recurso

curl -X POST "https://cvreaderpro.com/api/v2/pdf-generation/resumes/RESUME_UUID" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Accept: application/pdf" \
  --fail --show-error -o resume.pdf

Esquema de respuesta

Archivo PDF

DocumentationPdfService.generateResumePdf

POST/api/v2/pdf-generation/webhook

Encolar varios PDF mediante un webhook

Encola la generación de PDF para una lista de UUID de CV del usuario y entrega los archivos mediante el webhook configurado.

Solicitud

application/json · matriz de cadenas UUID

Correcto

202 · lote encolado { jobId, status, total, message, webhookSecurity }

400 — Lista vacía, duplicada o demasiado grande, o falta el webhook pdf.generated401 — La clave API no es válida o falta403 — El recurso no pertenece al usuario de esta clave API404 — No se encontró el recurso429 — La cola de webhooks está llena

curl -X POST "https://cvreaderpro.com/api/v2/pdf-generation/webhook" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["RESUME_UUID_1", "RESUME_UUID_2"]'

Esquema de respuesta

Lote PDF en cola

DocumentationPdfService.generatePdfsWithWebhook

Webhooks

Configura entregas de eventos firmadas para el análisis asíncrono, el matching y la generación de PDF.

Operación	Endpoint	Autenticación
Entrega de mejores candidatos	`POST /api/v2/recruiter-scores/jobs/{jobId}/top-candidates/webhook`	ApiKey
Entrega de mejores ofertas	`POST /api/v2/recruiter-scores/resumes/{resumeId}/top-jobs/webhook`	ApiKey
Entrega del lote de PDF	`POST /api/v2/pdf-generation/webhook`	ApiKey

Las solicitudes opcionales de Postman presuponen que el usuario de la clave API ya tiene configurado un webhook HTTPS. Suscríbelo a resume.parsed, resume.matched, or pdf.generated. La colección del backend no registra ni renueva webhooks; configúralos antes de activar las solicitudes opcionales de clasificación o PDF. Las entregas incluyen un ID, una marca de tiempo, una cabecera de evento y una firma HMAC-SHA256.

Requisitos para solicitudes opcionales de Postman

cvFilePath=/path/to/resume.pdf
jobFilePath=/path/to/job-description.pdf
webhookExpectedStatus=202

Cabeceras de entrega

X-CVReader-Event: resume.matched
X-CVReader-Delivery-Id: <uuid>
X-CVReader-Timestamp: <unix-seconds>
X-CVReader-Signature: v1=<hmac-sha256>

Verifica la firma usando <timestamp>.<raw-json-body> con HMAC-SHA256, responde con cualquier código 2xx para confirmar la entrega y usa el ID de entrega para garantizar la idempotencia si se repite el evento.

Explorar un ejemplo sintético

Descarga los CV de entrada y las salidas API capturadas. Todas las personas, empresas y ofertas son ficticias. Los documentos de ejemplo están en inglés; los resultados dependen del documento y del parser y requieren revisión humana.

CV de ejemplo (PDF)CV de ejemplo IA (PDF)Oferta de ejemplo (PDF)Resultado Rule-Based (JSON)Resultado IA 56 (JSON)CV generado (PDF)Colección Postman API V2