Processamento em segundo plano e retornos de chamada

Parser um lote de currículos ou analisar uma entrevista de uma hora não deve manter uma conexão aberta. Os endpoints assíncronos aceitam links ou uploads, respondem imediatamente com um task_ide executam o trabalho em nosso lado. Coletar o resultado por polling ou recebê-lo em seu servidor.

Endpoints assíncronos

Cada solicitação assíncrona também pode incluir um callback_url.

Envio de tarefa

Envie application/json com uma lista de links ou multipart/form-data com uploads. Em multipart, um campo de link pode ser repetido ou enviado um link por linha.

curl -X POST https://api.curriculo.me/public/parse/async \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -H 'Content-Type: application/json' \
  -d '{"file_urls": ["https://example.com/cvs/candidate_a.pdf", "https://example.com/cvs/candidate_b.pdf"], "callback_url": "https://example.com/curriculo/callback"}'

curl -X POST https://api.curriculo.me/public/summary/async \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -H 'Content-Type: application/json' \
  -d '{"media_url": "https://example.com/interviews/interview.mp4", "interview_id": "int_0042", "language": "ko"}'

curl -X POST https://api.curriculo.me/public/translate/async \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -H 'Content-Type: application/json' \
  -d '{"texts": ["Senior backend engineer", "Remote within Europe"], "source_language": "en", "target_language": "fr"}'

Para requisições de JSON para /translate/async,source_language é obrigatório. Para /evaluate/async, envie o trabalho como job_details ou job_id.

O API responde de uma vez com 202:

{ "task_id": "…", "status": "queued", "callback_secret": "whsec_…" }

callback_secret é retornado apenas quando você enviou um callback_url. É exibido exatamente uma vez, como uma chave API, então armazene-o.

Obtendo o resultado

Polling

curl https://api.curriculo.me/public/parse/tasks/<task_id> \
  -H 'Authorization: Bearer key_abc123_yoursecret'

Uma tarefa é legível com a mesma chave que a criou, independentemente de um callback ter sido entregue. A resposta nunca inclui o callback URL ou segredo.

Retornos de Chamada

Se você enviou uma callback_url, a tarefa concluída é POSTada lá como application/json com estes cabeçalhos:

O corpo é {task_id, op, status, status_code, result, error, completed_at}.

Não há cabeçalho de carimbo de data/hora, portanto, deduplicar entregas em task_id: a mesma tarefa pode chegar mais de uma vez se o servidor respondeu lentamente ou com um erro.

Verificar a assinatura

Calcular o HMAC-SHA256 do corpo da solicitação bruta, usando sua callback_secret exatamente como retornado (incluindo o prefixo whsec_ ) como a chave. Comparar sha256= mais o resumo hexadecimal em minúsculas com X-Curriculo-Signature em tempo constante. Usar os bytes brutos como recebidos, antes de qualquer análise JSON, e rejeitar qualquer coisa que não corresponda.

Python:

import hashlib
import hmac

def is_valid(raw_body: bytes, signature_header: str, callback_secret: str) -> bool:
    # callback_secret is used as-is, including the "whsec_" prefix
    expected = "sha256=" + hmac.new(
        callback_secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

JavaScript (Node.js):

import crypto from "node:crypto";

// rawBody must be the unparsed request body (a Buffer)
export function isValid(rawBody, signatureHeader, callbackSecret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", callbackSecret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Em seguida, deduplicar no cabeçalho X-Curriculo-Task-Id (ou task_id no corpo) e responder 2xx.

Entrega e reenvios

• Qualquer resposta não-2xx é considerada uma entrega falha, e redirecionamentos não são seguidos.
• Reenvios de entrega com atrasos crescentes (1, 5, 15 e 60 minutos, então 4 horas), por cerca de 5 horas e 21 minutos no total, antes que a entrega seja marcada dead.
• O resultado permanece legível em GET /{op}/tasks/{task_id} de qualquer forma, portanto, nada se perde devido a uma entrega perdida.

Requisitos para URLs

Os URLs de callback devem ser https, acessíveis publicamente e não devem conter credenciais. Endereços em redes privadas são recusados.

• Os links que você envia (file_urls,resume_urls,media_url) devem ser links públicos https . Um link público ou um armazenamento pré-assinado URL (por exemplo S3) também funcionam.
• Links que redirecionam são recusados.
• Gravações por link podem ter até 1 GB e 2 horas. Arquivos carregados são limitados a 12 MB cada.

Faturamento

• Uma tarefa é cobrada uma vez, em seu resultado final, como uma solicitação de sua operação: uma análise assíncrona de 25 links custa $0.01.
• Uma tarefa que falha (um link morto, um arquivo ilegível) nunca é cobrada.
• Tarefas de gravação (/summary/async,/transcribe/async) reservam a cobrança para o máximo de 2 horas quando a tarefa é aceita. Sem crédito suficiente para essa reserva, a solicitação retorna 400. A reserva é liberada se a tarefa falhar.

Consulte Preços e cobrança.

Dados mantidos pelas tarefas

Ao contrário das operações síncronas, uma tarefa em segundo plano mantém seu resultado para que você possa pesquisá-lo, e arquivos carregados são armazenados em sua conta. Consulte Manipulação de dados.