Visão geral

Resumo dos recursos da API documentados e das operações disponíveis.

Recurso	Endpoints	Caminho base	Funcionalidades
CV e análise	7	`/api/v2/resumes`	Análise estendida, ficheiros e gestão de CV
Ofertas	6	`/api/v2/jobs`	Análise de ficheiros, filtros e gestão de ofertas
Pontuações	4	`/api/v2/recruiter-scores`	Matching de recursos guardados e webhooks de classificação
Geração de PDF	3	`/api/v2/pdf-generation`	Definições, PDFs individuais e lotes por webhook

20 endpoints documentadosAutenticação por chave de APIRespostas JSON, multipart e PDF

Plano de testes do Postman

A coleção backend contém 27 pedidos para 20 rotas distintas. Treze rotas são executadas por predefinição; sete pedidos opcionais ficam desativados até existirem ficheiros locais, permissões do parser ou um webhook configurado. Execute a coleção pela ordem indicada para que os IDs das fixtures e os passos de limpeza funcionem corretamente.

Esquemas e modelos JSON

Estes modelos correspondem aos DTOs, entidades, nomes de propriedades Jackson e envelopes de resposta do backend usados nesta página.

DocumentationResumeRequest → UpdateResumeDto

Pedido para criar ou atualizar um CV

Usado por POST e PUT /api/v2/resumes. O conteúdo do CV deve estar sempre dentro da propriedade resume.

ParserResponseDTO

Resposta do parser de CV

Devolvida por POST /api/v2/resumes/parser. É a resposta normalizada do parser, não o recurso CVXml devolvido por GET /api/v2/resumes/{resumeId}.

DocumentationService

Envelopes de recursos de CV

A criação e a leitura devolvem CVXml em resume. A atualização devolve UpdateResumeDto normalizado em resume. CVXml usa nomes de campos históricos em francês.

Job entity

Pedido e resposta de oferta

POST e PUT aceitam a entidade Job. PUT substitui os campos documentados; envie todos os valores que pretende manter. As respostas também podem incluir id, filePath, pauseReason, jobskills, createdAt e updatedAt.

DocumentationService / DocumentationJobService

Envelopes de listas de CV e ofertas

Ambos os endpoints de lista usam as mesmas chaves de paginação. A chave da coleção varia consoante o recurso.

RecruiterScoreDto

Resposta da pontuação de recrutamento

Devolvida por ambos os endpoints de matching síncrono e incluída nos dados dos webhooks de classificação.

ResumeSettings, ColorSettings, SectionSettings, ResumeCanvasImage

Definições de geração de PDF

Usadas por PUT /api/v2/pdf-generation/settings. O ID da secção é só de leitura; o servidor gera o ID da imagem de fundo.

WebhookController.WebhookSettingsDto / DocumentationPdfService

Definições de webhook e respostas em fila

O registo de webhooks usa autenticação de sessão de recrutador. O endpoint webhook PDF v2 devolve a resposta de lote aceite apresentada abaixo.

CV e análise

Analisa, cria, consulta, atualiza e elimina os CV do utilizador associado à chave API.

Respostas do cliente CV: os 3 esquemas necessários

Estas são as formas exatas das respostas bem-sucedidas que o cliente deve desserializar. Os campos detalhados de CVXml e UpdateResumeDto estão na secção Esquemas.

POST /api/v2/resumes/parser

1. Analisar um ficheiro

Enviar:Envie multipart/form-data: file (obrigatório), parserType (opcional).

Receber:Leia a resposta ParserResponseDTO guardada.

POST /api/v2/resumes

2. Criar um CV estruturado

Enviar:Envie application/json. O envelope resume é obrigatório.

Receber:Guarde o id do envelope CVXml criado; será resumeId nos pedidos seguintes.

PUT /api/v2/resumes/{resumeId}

3. Atualizar um CV

Enviar:Use o mesmo envelope obrigatório { resume: ... } da criação.

Receber:A resposta contém o id e o UpdateResumeDto guardado.

POST/api/v2/resumes/parser

Analisar um ficheiro de CV

Analisa e guarda um CV enviado como ficheiro multipart.

Pedido

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

Sucesso

200 · JSON ou XML · ParserResponseDTO guardado

400 — Ficheiro de CV inválido401 — Chave API inválida ou em falta402 — Créditos insuficientes403 — A análise de ficheiros não é permitida

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 da resposta

ParserResponseDTO

DocumentationResumeController.parseResume

POST/api/v2/resumes/extended-parser

Executar o parser de CV estendido

Analisa um ficheiro de CV carregado ou um campo de texto com o parser estendido. Esta rota requer uma chave API autorizada e consome créditos premium de análise.

Pedido

multipart/form-data · file? (ficheiro) ou text? (cadeia) · indicar exatamente uma entrada

Sucesso

200 · objeto JSON com os dados estendidos do CV

400 — Falta o ficheiro ou o texto, ou não é válido401 — Chave API inválida ou em falta402 — Créditos insuficientes403 — É necessária uma subscrição ou período de teste do parser422 — Não foi possível analisar o documento429 — Limite de pedidos do parser estendido excedido

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 da resposta

Objeto JSON do parser estendido

DocumentationService.parseExtended

GET/api/v2/resumes

Listar os CV do utilizador

Devolve uma coleção paginada que inclui apenas os CV do utilizador associado à chave API.

Pedido

parâmetros de consulta · page? (número, predefinição 0) · size? (número, predefinição 10)

Sucesso

200 · coleção 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 da resposta

Coleção paginada de CV

DocumentationService.getResumes

POST/api/v2/resumes

Criar um CV

Cria um CV estruturado. Envie DocumentationResumeRequest ({ resume: UpdateResumeDto }); também é aceite um recurso em formato CVXml obtido numa resposta de leitura.

Pedido

application/json · DocumentationResumeRequest

Sucesso

201 · cabeçalho Location: /api/v2/resumes/{id} · { id, resume: CVXml }

400 — Dados do CV inválidos401 — Chave API inválida ou em 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 da resposta

Envelope do CV criado

DocumentationService.createResume

GET/api/v2/resumes/{resumeId}

Obter um CV do utilizador

Devolve o CV se o UUID existir e pertencer ao utilizador da chave API.

Pedido

parâmetro do caminho · resumeId (UUID)

Sucesso

200 · recurso CV { id, resume: CVXml }

401 — Chave API inválida ou em falta403 — O recurso não pertence ao utilizador desta chave API404 — Recurso não encontrado

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

Esquema da resposta

Envelope do CV

DocumentationService.getResume

PUT/api/v2/resumes/{resumeId}

Atualizar um CV do utilizador

Atualiza um CV com o mesmo wrapper DocumentationResumeRequest usado na criação.

Pedido

parâmetro do caminho · resumeId (UUID) · application/json · DocumentationResumeRequest

Sucesso

200 · { id, resume: UpdateResumeDto } atualizado

401 — Chave API inválida ou em falta403 — O recurso não pertence ao utilizador desta chave API404 — Recurso não encontrado

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 da resposta

Envelope do CV atualizado

DocumentationService.updateResume

DELETE/api/v2/resumes/{resumeId}

Eliminar um CV do utilizador

Elimina um CV que pertence ao utilizador da chave API.

Pedido

parâmetro do caminho · resumeId (UUID)

Sucesso

204 · sem conteúdo

401 — Chave API inválida ou em falta404 — Recurso não encontrado

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

Esquema da resposta

Sem corpo de resposta

DocumentationService.deleteResume

Ofertas

Analisa ficheiros de ofertas e gere as ofertas estruturadas do utilizador autenticado.

POST/api/v2/jobs/parser

Analisar e guardar um ficheiro de oferta

Analisa uma descrição de emprego enviada como ficheiro multipart e cria a oferta para o utilizador autenticado.

Pedido

multipart/form-data · file (ficheiro)

Sucesso

200 · application/json · oferta criada

400 — Ficheiro da oferta inválido401 — Chave API inválida ou em falta

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

Esquema da resposta

Oferta

DocumentationJobController.parseJob

GET/api/v2/jobs

Listar as ofertas do utilizador

Devolve uma coleção paginada e filtrável das ofertas que pertencem ao utilizador da chave API.

Pedido

parâmetros · page? · size? · status? · source? · reference? · title? · postedFrom? · postedTo? (data e hora ISO)

Sucesso

200 · coleção paginada { jobs, currentPage, totalItems, totalPages }

401 — Chave API inválida ou em falta

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

Esquema da resposta

Coleção paginada de ofertas

DocumentationJobService.getJobs

POST/api/v2/jobs

Criar uma oferta

Cria uma oferta estruturada a partir da entidade Job. O modelo JSON completo está em Esquemas; a resposta acrescenta campos gerados pelo servidor.

Pedido

application/json · objeto Job

Sucesso

201 · oferta criada

401 — Chave API inválida ou em 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 da resposta

Oferta

DocumentationJobService.createJob

GET/api/v2/jobs/{jobIdOrReference}

Obter uma oferta do utilizador

Procura uma oferta pelo UUID ou referência e só a devolve se pertencer ao utilizador da chave API.

Pedido

parâmetro do caminho · jobIdOrReference (UUID ou referência de texto)

Sucesso

200 · recurso de oferta

401 — Chave API inválida ou em falta403 — O recurso não pertence ao utilizador desta chave API404 — Recurso não encontrado

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

Esquema da resposta

Oferta

DocumentationJobService.getJob

PUT/api/v2/jobs/{jobIdOrReference}

Atualizar uma oferta do utilizador

Atualiza uma oferta identificada por UUID ou referência. O backend define todos os campos Job editáveis documentados; envie o objeto completo para não limpar valores.

Pedido

parâmetro do caminho · jobIdOrReference · application/json · objeto Job

Sucesso

200 · recurso de oferta atualizado

401 — Chave API inválida ou em falta403 — O recurso não pertence ao utilizador desta chave API404 — Recurso não encontrado

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 da resposta

Oferta

DocumentationJobService.updateJob

DELETE/api/v2/jobs/{jobIdOrReference}

Eliminar uma oferta do utilizador

Elimina uma oferta identificada por UUID ou referência.

Pedido

parâmetro do caminho · jobIdOrReference (UUID ou referência de texto)

Sucesso

204 · sem conteúdo

401 — Chave API inválida ou em falta403 — O recurso não pertence ao utilizador desta chave API404 — Recurso não encontrado

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

Esquema da resposta

Sem corpo de resposta

DocumentationJobService.deleteJob

Pontuações de recrutamento

Calcula matching detalhado e envia classificações através de webhooks.

POST/api/v2/recruiter-scores/match

Calcular o matching completo dos recursos guardados

Calcula uma pontuação detalhada para uma oferta e um CV guardados.

Pedido

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

Sucesso

200 · RecruiterScoreDto, incluindo o ID da pontuação final

400 — jobId e candidateId são obrigatórios401 — Chave API inválida ou em 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 da resposta

RecruiterScoreDto

DocumentationRecruiterScoreController.fullMatch

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

Analisar e comparar dois ficheiros

Analisa e guarda o CV e a oferta enviados e calcula a pontuação detalhada de matching para o par criado.

Pedido

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

Sucesso

200 · RecruiterScoreDto

401 — Chave API inválida ou em 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 da resposta

RecruiterScoreDto

DocumentationRecruiterScoreController.fullMatchFiles

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

Colocar o webhook dos melhores candidatos na fila

Atualiza as pontuações e coloca na fila os 10 candidatos mais bem classificados, com todos os detalhes, para uma oferta.

Pedido

parâmetro do caminho · jobId (UUID)

Sucesso

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

401 — Chave API inválida ou em falta

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

Esquema da resposta

Entrega de webhook na fila

DocumentationRecruiterScoreController.queueWebhook

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

Colocar o webhook das melhores ofertas na fila

Coloca na fila as 10 ofertas detalhadas com melhor classificação para um CV no webhook configurado.

Pedido

parâmetro do caminho · resumeId (UUID)

Sucesso

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

401 — Chave API inválida ou em falta

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

Esquema da resposta

Entrega de webhook na fila

DocumentationRecruiterScoreController.queueWebhook

Geração de PDF

Atualiza as definições de apresentação e gera um ou mais PDFs de CV.

PUT/api/v2/pdf-generation/settings

Atualizar as definições de geração de PDF

Atualiza as ResumeSettings do utilizador autenticado usadas na geração de PDF. Envie o modelo completo para preservar os valores atuais; inclui layout, tipografia, margens, cores, secções, imagens e identidade da agência.

Pedido

application/json · objeto ResumeSettings

Sucesso

200 · ResumeSettings atualizadas

401 — Chave API inválida ou em 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 da resposta

ResumeSettings

DocumentationPdfService.updateSettings

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

Gerar um PDF de CV

Gera um PDF de um CV do utilizador com as definições atuais.

Pedido

parâmetro do caminho · resumeId (UUID)

Sucesso

200 · application/pdf · documento PDF

401 — Chave API inválida ou em falta404 — Recurso não encontrado

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 da resposta

Ficheiro PDF

DocumentationPdfService.generateResumePdf

POST/api/v2/pdf-generation/webhook

Colocar vários PDFs na fila através de um webhook

Coloca na fila a geração de PDFs para uma lista de UUID de CV do utilizador e envia os ficheiros pelo webhook configurado.

Pedido

application/json · lista de cadeias UUID

Sucesso

202 · lote na fila { jobId, status, total, message, webhookSecurity }

400 — Lista vazia, duplicada ou demasiado grande, ou webhook pdf.generated em falta401 — Chave API inválida ou em falta403 — O recurso não pertence ao utilizador desta chave API404 — Recurso não encontrado429 — Fila de entrega de webhooks cheia

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 da resposta

Lote PDF na fila

DocumentationPdfService.generatePdfsWithWebhook

Webhooks

Configure entregas de eventos assinadas para análise assíncrona, matching e geração de PDF.

Operação	Endpoint	Autenticação
Entrega dos melhores candidatos	`POST /api/v2/recruiter-scores/jobs/{jobId}/top-candidates/webhook`	ApiKey
Entrega das melhores ofertas	`POST /api/v2/recruiter-scores/resumes/{resumeId}/top-jobs/webhook`	ApiKey
Entrega do lote de PDF	`POST /api/v2/pdf-generation/webhook`	ApiKey

Os pedidos opcionais do Postman pressupõem que o utilizador da chave API já tem um webhook HTTPS configurado. Subscreva-o a resume.parsed, resume.matched, or pdf.generated. A coleção backend não regista nem renova webhooks; configure-os antes de ativar pedidos opcionais de classificação ou PDF. As entregas incluem um ID, uma data e hora, um cabeçalho de evento e uma assinatura HMAC-SHA256.

Pré-requisitos dos pedidos opcionais do Postman

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

Cabeçalhos de entrega

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

Verifique a assinatura de <timestamp>.<raw-json-body> com HMAC-SHA256, devolva uma resposta 2xx para confirmar a entrega e use o ID da entrega para garantir a idempotência, pois as tentativas podem repetir o mesmo evento.

Explorar um exemplo sintético

Descarregue os CV de entrada e as saídas API capturadas. Todas as pessoas, empresas e vagas são fictícias. Os documentos de exemplo estão em inglês; os resultados dependem do documento e do parser e exigem revisão humana.

CV de exemplo (PDF)CV de exemplo IA (PDF)Vaga de exemplo (PDF)Resultado Rule-Based (JSON)Resultado IA 56 (JSON)CV gerado (PDF)Coleção Postman API V2