Panoramica

Riepilogo di tutte le risorse API documentate e delle operazioni disponibili.

Risorsa	Endpoint	Percorso di base	Funzionalità
CV e parsing	7	`/api/v2/resumes`	Parsing esteso, analisi file e gestione CV
Offerte	6	`/api/v2/jobs`	Analisi file, filtri e gestione offerte
Score recruiter	4	`/api/v2/recruiter-scores`	Matching di risorse salvate e webhook di ranking
Generazione PDF	3	`/api/v2/pdf-generation`	Impostazioni, PDF singoli e batch via webhook

20 endpoint documentatiAutenticazione con chiave APIRisposte JSON, multipart e PDF

Piano di test Postman

La raccolta backend contiene 27 richieste per 20 route distinte. Tredici route vengono eseguite per impostazione predefinita; sette richieste facoltative restano disabilitate finché non sono disponibili file locali, autorizzazioni del parser o un webhook configurato. Esegui la raccolta nell’ordine previsto affinché funzionino gli ID delle fixture e i passaggi di pulizia.

Schemi e modelli JSON

Questi modelli corrispondono ai DTO backend, alle entità, ai nomi delle proprietà Jackson e agli involucri delle risposte usati in questa pagina.

DocumentationResumeRequest → UpdateResumeDto

Richiesta per creare o aggiornare un CV

Usata da POST e PUT /api/v2/resumes. Il contenuto del CV deve essere sempre annidato nella proprietà resume.

ParserResponseDTO

Risposta del parser CV

Restituita da POST /api/v2/resumes/parser. È la risposta normalizzata del parser, non la risorsa CVXml restituita da GET /api/v2/resumes/{resumeId}.

DocumentationService

Envelope delle risorse CV

Creazione e lettura restituiscono CVXml in resume. L’aggiornamento restituisce UpdateResumeDto normalizzato in resume. CVXml usa nomi di campo storici in francese.

Job entity

Richiesta e risposta dell’offerta

POST e PUT accettano l’entità Job. PUT sostituisce i campi documentati: invia tutti i valori da conservare. Le risposte possono includere anche id, filePath, pauseReason, jobskills, createdAt e updatedAt.

DocumentationService / DocumentationJobService

Envelope degli elenchi di CV e offerte

Entrambi gli endpoint di elenco usano le stesse chiavi di paginazione. La chiave della raccolta varia in base alla risorsa.

RecruiterScoreDto

Risposta dello score recruiter

Restituita da entrambi gli endpoint di matching sincrono e inclusa nei payload dei webhook di ranking.

ResumeSettings, ColorSettings, SectionSettings, ResumeCanvasImage

Impostazioni di generazione PDF

Usate da PUT /api/v2/pdf-generation/settings. L’ID della sezione è di sola lettura; l’ID dell’immagine canvas è generato dal server.

WebhookController.WebhookSettingsDto / DocumentationPdfService

Impostazioni webhook e risposte in coda

La registrazione di un webhook usa l’autenticazione della sessione recruiter. L’endpoint webhook PDF v2 restituisce la risposta di batch accettato mostrata qui sotto.

CV e parsing

Analizza, crea, consulta, aggiorna ed elimina i CV dell’utente associato alla chiave API.

Risposte del client CV: i 3 schemi necessari

Queste sono le forme esatte delle risposte riuscite da deserializzare nel client. I campi dettagliati di CVXml e UpdateResumeDto sono nella sezione Schemi.

POST /api/v2/resumes/parser

1. Analizzare un file

Invia:Invia multipart/form-data: file (obbligatorio), parserType (facoltativo).

Ricevi:Leggi la risposta ParserResponseDTO salvata.

POST /api/v2/resumes

2. Creare un CV strutturato

Invia:Invia application/json. Il wrapper resume è obbligatorio.

Ricevi:Salva l’id dell’envelope CVXml creato: sarà resumeId per le chiamate successive.

PUT /api/v2/resumes/{resumeId}

3. Aggiornare un CV

Invia:Usa lo stesso wrapper obbligatorio { resume: ... } della creazione.

Ricevi:La risposta contiene l’id e l’UpdateResumeDto salvato.

POST/api/v2/resumes/parser

Analizzare un file CV

Analizza e salva un CV caricato come file multipart.

Richiesta

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

Esito positivo

200 · JSON o XML · ParserResponseDTO salvato

400 — File CV non valido401 — Chiave API non valida o mancante402 — Crediti insufficienti403 — Il parsing dei file non è consentito

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"

Schema della risposta

ParserResponseDTO

DocumentationResumeController.parseResume

POST/api/v2/resumes/extended-parser

Eseguire il parser CV esteso

Analizza un file CV caricato oppure un campo di testo con il parser esteso. Questa route richiede una chiave API abilitata e consuma crediti premium di parsing.

Richiesta

multipart/form-data · file? (file) o text? (stringa) · fornire esattamente un input

Esito positivo

200 · oggetto JSON con i dati CV estesi

400 — File o testo mancante o non valido401 — Chiave API non valida o mancante402 — Crediti insufficienti403 — È necessario un abbonamento o un periodo di prova del parser422 — Non è stato possibile analizzare il documento429 — Limite di richieste del parser esteso superato

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

Schema della risposta

Oggetto JSON del parser esteso

DocumentationService.parseExtended

GET/api/v2/resumes

Elencare i CV dell’utente

Restituisce una raccolta paginata che include solo i CV dell’utente associato alla chiave API.

Richiesta

parametri query · page? (numero, predefinito 0) · size? (numero, predefinito 10)

Esito positivo

200 · raccolta paginata { resumes, currentPage, totalItems, totalPages }

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

Schema della risposta

Raccolta CV paginata

DocumentationService.getResumes

POST/api/v2/resumes

Creare un CV

Crea un CV strutturato. Inviare DocumentationResumeRequest ({ resume: UpdateResumeDto }); è accettata anche una risorsa CVXml ottenuta da una risposta di lettura.

Richiesta

application/json · DocumentationResumeRequest

Esito positivo

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

400 — Dati del CV non validi401 — Chiave API non valida o mancante

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": []}}'

Schema della risposta

Envelope del CV creato

DocumentationService.createResume

GET/api/v2/resumes/{resumeId}

Recuperare un CV dell’utente

Restituisce il CV se l’UUID esiste e appartiene all’utente della chiave API.

Richiesta

parametro del percorso · resumeId (UUID)

Esito positivo

200 · risorsa CV { id, resume: CVXml }

401 — Chiave API non valida o mancante403 — La risorsa non appartiene all’utente di questa chiave API404 — Risorsa non trovata

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

Schema della risposta

Envelope del CV

DocumentationService.getResume

PUT/api/v2/resumes/{resumeId}

Aggiornare un CV dell’utente

Aggiorna un CV usando lo stesso wrapper DocumentationResumeRequest previsto per la creazione.

Richiesta

parametro del percorso · resumeId (UUID) · application/json · DocumentationResumeRequest

Esito positivo

200 · { id, resume: UpdateResumeDto } aggiornato

401 — Chiave API non valida o mancante403 — La risorsa non appartiene all’utente di questa chiave API404 — Risorsa non trovata

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": []}}'

Schema della risposta

Envelope del CV aggiornato

DocumentationService.updateResume

DELETE/api/v2/resumes/{resumeId}

Eliminare un CV dell’utente

Elimina un CV appartenente all’utente della chiave API.

Richiesta

parametro del percorso · resumeId (UUID)

Esito positivo

204 · nessun contenuto

401 — Chiave API non valida o mancante404 — Risorsa non trovata

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

Schema della risposta

Nessun corpo della risposta

DocumentationService.deleteResume

Offerte

Analizza file di offerte e gestisce le offerte strutturate dell’utente autenticato.

POST/api/v2/jobs/parser

Analizzare e salvare un file di offerta

Analizza una descrizione di lavoro caricata come file multipart e crea l’offerta per l’utente autenticato.

Richiesta

multipart/form-data · file (file)

Esito positivo

200 · application/json · offerta creata

400 — File dell’offerta non valido401 — Chiave API non valida o mancante

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

Schema della risposta

Offerta

DocumentationJobController.parseJob

GET/api/v2/jobs

Elencare le offerte dell’utente

Restituisce una raccolta paginata e filtrabile delle offerte appartenenti all’utente della chiave API.

Richiesta

parametri · page? · size? · status? · source? · reference? · title? · postedFrom? · postedTo? (data e ora ISO)

Esito positivo

200 · raccolta paginata { jobs, currentPage, totalItems, totalPages }

401 — Chiave API non valida o mancante

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

Schema della risposta

Raccolta offerte paginata

DocumentationJobService.getJobs

POST/api/v2/jobs

Creare un’offerta

Crea un’offerta strutturata dall’entità Job. Il modello JSON completo è nella sezione Schemi; la risposta aggiunge i campi generati dal server.

Richiesta

application/json · oggetto Job

Esito positivo

201 · offerta creata

401 — Chiave API non valida o mancante

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

Schema della risposta

Offerta

DocumentationJobService.createJob

GET/api/v2/jobs/{jobIdOrReference}

Recuperare un’offerta dell’utente

Cerca un’offerta tramite UUID o riferimento e la restituisce solo se appartiene all’utente della chiave API.

Richiesta

parametro del percorso · jobIdOrReference (UUID o riferimento testuale)

Esito positivo

200 · risorsa offerta

401 — Chiave API non valida o mancante403 — La risorsa non appartiene all’utente di questa chiave API404 — Risorsa non trovata

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

Schema della risposta

Offerta

DocumentationJobService.getJob

PUT/api/v2/jobs/{jobIdOrReference}

Aggiornare un’offerta dell’utente

Aggiorna un’offerta identificata da UUID o riferimento. Il backend assegna ogni campo Job modificabile documentato: invia l’oggetto Job completo per evitare di cancellare valori.

Richiesta

parametro del percorso · jobIdOrReference · application/json · oggetto Job

Esito positivo

200 · risorsa offerta aggiornata

401 — Chiave API non valida o mancante403 — La risorsa non appartiene all’utente di questa chiave API404 — Risorsa non trovata

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

Schema della risposta

Offerta

DocumentationJobService.updateJob

DELETE/api/v2/jobs/{jobIdOrReference}

Eliminare un’offerta dell’utente

Elimina un’offerta identificata da UUID o riferimento.

Richiesta

parametro del percorso · jobIdOrReference (UUID o riferimento testuale)

Esito positivo

204 · nessun contenuto

401 — Chiave API non valida o mancante403 — La risorsa non appartiene all’utente di questa chiave API404 — Risorsa non trovata

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

Schema della risposta

Nessun corpo della risposta

DocumentationJobService.deleteJob

Score recruiter

Calcola matching dettagliati e invia le classifiche migliori tramite webhook.

POST/api/v2/recruiter-scores/match

Calcolare il matching completo delle risorse salvate

Calcola uno score dettagliato per un’offerta e un CV salvati.

Richiesta

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

Esito positivo

200 · RecruiterScoreDto, incluso l’ID dello score finale

400 — jobId e candidateId sono obbligatori401 — Chiave API non valida o mancante

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"}'

Schema della risposta

RecruiterScoreDto

DocumentationRecruiterScoreController.fullMatch

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

Analizzare e confrontare due file

Analizza e salva il CV e l’offerta forniti, quindi calcola lo score dettagliato di matching per la coppia creata.

Richiesta

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

Esito positivo

200 · RecruiterScoreDto

401 — Chiave API non valida o mancante

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"

Schema della risposta

RecruiterScoreDto

DocumentationRecruiterScoreController.fullMatchFiles

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

Accodare il webhook dei candidati migliori

Aggiorna gli score e accoda i 10 candidati più qualificati, con tutti i dettagli, per un’offerta.

Richiesta

parametro del percorso · jobId (UUID)

Esito positivo

202 · consegna accodata { deliveryId, eventType: "resume.matched", status: "QUEUED", resultCount }

401 — Chiave API non valida o mancante

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

Schema della risposta

Consegna webhook accodata

DocumentationRecruiterScoreController.queueWebhook

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

Accodare il webhook delle offerte migliori

Accoda le 10 offerte dettagliate con lo score più alto per un CV al webhook configurato.

Richiesta

parametro del percorso · resumeId (UUID)

Esito positivo

202 · consegna accodata { deliveryId, eventType: "resume.matched", status: "QUEUED", resultCount }

401 — Chiave API non valida o mancante

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

Schema della risposta

Consegna webhook accodata

DocumentationRecruiterScoreController.queueWebhook

Generazione PDF

Aggiorna le impostazioni di rendering e genera uno o più PDF dei CV.

PUT/api/v2/pdf-generation/settings

Aggiornare le impostazioni di generazione PDF

Aggiorna le ResumeSettings dell’utente autenticato usate per generare PDF. Per conservare i valori esistenti invia il modello completo: layout, tipografia, margini, colori, sezioni, immagini e branding dell’agenzia.

Richiesta

application/json · oggetto ResumeSettings

Esito positivo

200 · ResumeSettings aggiornate

401 — Chiave API non valida o mancante

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

Schema della risposta

ResumeSettings

DocumentationPdfService.updateSettings

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

Generare un PDF per un CV

Genera un PDF per un CV dell’utente usando le impostazioni correnti.

Richiesta

parametro del percorso · resumeId (UUID)

Esito positivo

200 · application/pdf · documento PDF

401 — Chiave API non valida o mancante404 — Risorsa non trovata

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

Schema della risposta

File PDF

DocumentationPdfService.generateResumePdf

POST/api/v2/pdf-generation/webhook

Accodare più PDF tramite webhook

Accoda la generazione PDF per una lista di UUID di CV dell’utente e invia i file tramite il webhook configurato.

Richiesta

application/json · array di stringhe UUID

Esito positivo

202 · batch accodato { jobId, status, total, message, webhookSecurity }

400 — Elenco vuoto, duplicato o troppo grande, oppure webhook pdf.generated mancante401 — Chiave API non valida o mancante403 — La risorsa non appartiene all’utente di questa chiave API404 — Risorsa non trovata429 — Coda di consegna webhook piena

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"]'

Schema della risposta

Batch PDF accodato

DocumentationPdfService.generatePdfsWithWebhook

Webhook

Configura l’invio di eventi firmati per parsing asincrono, matching e generazione PDF.

Operazione	Endpoint	Autenticazione
Consegna dei candidati migliori	`POST /api/v2/recruiter-scores/jobs/{jobId}/top-candidates/webhook`	ApiKey
Consegna delle offerte migliori	`POST /api/v2/recruiter-scores/resumes/{resumeId}/top-jobs/webhook`	ApiKey
Consegna del batch PDF	`POST /api/v2/pdf-generation/webhook`	ApiKey

Le richieste Postman facoltative presuppongono che sia già configurato un webhook HTTPS per il proprietario della chiave API. Iscrivilo a resume.parsed, resume.matched, or pdf.generated. La raccolta backend non registra né rinnova i webhook; configura queste impostazioni prima di abilitare le richieste facoltative di ranking o PDF. Le consegne includono ID, timestamp, header dell’evento e firma HMAC-SHA256.

Prerequisiti delle richieste Postman facoltative

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

Header di consegna

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

Verifica la firma su <timestamp>.<raw-json-body> con HMAC-SHA256, restituisci una risposta 2xx per confermare la consegna e usa l’ID di consegna per l’idempotenza, perché i tentativi possono ripetere lo stesso evento.

Esplora un esempio sintetico

Scarica i CV di input e gli output API acquisiti. Tutte le persone, aziende e offerte sono fittizie. I documenti di esempio sono in inglese; i risultati dipendono dal documento e dal parser e richiedono una revisione umana.

CV di esempio (PDF)CV di esempio IA (PDF)Offerta di esempio (PDF)Risultato Rule-Based (JSON)Risultato IA 56 (JSON)CV generato (PDF)Collezione Postman API V2