Publicar uma vaga a partir do seu próprio sistema

Atualizado 29 de setembro de 2026

Se as suas vagas já vivem noutro sítio — um ATS, uma ferramenta interna, uma folha de cálculo que alguém guarda — é assim que chegam à Orbit sem que ninguém as volte a escrever.

O que precisa

Uma chave com o âmbito ler e gerir vagas, criada em Orbit → Definições → Chaves de API. Uma chave apenas de leitura responde 403 a todos os pedidos desta página, de propósito: publicar coloca um anúncio diante do público, e a chave que alimenta uma página de carreiras não deve poder, além disso, publicar anúncios.

export ORBIT_API_KEY="…uma chave com ler e gerir vagas…"

A forma: duas chamadas

Criar e publicar estão separados.

1. POST /v1/jobs cria um rascunho. Nada é público.
2. POST /v1/jobs/{jobId}/publish põe-no no ar. Publicar é grátis.

É deliberado. Publicar coloca a vaga na sua página de vaga alojada, deixa os candidatos candidatarem-se e entra no feed de quem procura emprego na Wipperoz. Uma única chamada que fizesse tudo isso significaria que uma chave num ciclo mal configurado publica anúncios antes de alguém ler um log.

Também deixa uma pessoa no circuito quando a quer: crie os rascunhos a partir do seu sistema e deixe um recrutador publicá-los na Orbit depois de os ler. Se não a quiser, chame publish você mesmo. As duas coisas são suportadas; a escolha é sua, não nossa.

Anúncios geridos

Um anúncio publicado recebe candidaturas e lista-as pela ordem em que chegaram. Gerir um anúncio é o serviço pago da Orbit por cima disso: os candidatos são ordenados, o seu pool de candidatos é comparado com o anúncio e pode fazer a triagem, na Orbit ou pela API (veja Fazer a triagem de um candidato). Um recrutador ativa-o anúncio a anúncio, na Orbit — o âmbito ler e gerir vagas cria, edita, publica e fecha vagas, e não gere anúncios.

Só uma coisa chega a esta API: o título e a categoria de um anúncio gerido estão bloqueados, como explica Editar uma vaga mais abaixo.

Criar o rascunho

curl -X POST https://api.wipperoz.com/v1/jobs \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ats-job-4471" \
  -d '{
    "title": "Engenheiro de Backend Sénior",
    "category": "engineering",
    "description": "<p>Responsável pelos serviços por trás do nosso processo de contratação.</p>",
    "responsibilities": ["Desenhar e lançar serviços em AWS Lambda e DynamoDB"],
    "skills": [
      {"name": "TypeScript", "level": "required"},
      {"name": "DynamoDB", "level": "nice_to_have"}
    ],
    "employmentType": "full_time",
    "contractType": "permanent",
    "salary": {"min": 150000, "max": 180000, "currency": "AUD", "period": "year"},
    "location": {"country": "AU", "state": "NSW", "city": "Sydney", "remotePolicy": "hybrid"}
  }'

{
  "job": {
    "id": "job_01J9A0B1C2EXAMPLE",
    "status": "draft",
    "title": "Engenheiro de Backend Sénior",
    "category": "engineering",
    "applyLink": "https://www.wipperoz.com/pt/apply/job_01J9A0B1C2EXAMPLE?src=careers&account=acc_01J8Z3EXAMPLE"
  }
}

Guarde o id. É com ele que depois publica, edita e fecha a vaga, e é o identificador que deve guardar junto à vaga no seu próprio sistema.

Aqui só title é obrigatório. Para publicar é preciso ainda uma description e, da primeira vez que uma vaga vai para o ar, uma category; mais nada alguma vez bloqueia a publicação. description aceita HTML, que é o que o editor da Orbit produz; texto simples também serve.

Categorias

category diz que tipo de emprego é, a partir de uma lista fixa. Envie o valor; a etiqueta é o que a Orbit mostra.

Qualquer outro valor responde 400 nomeando os que aceita. other é para a vaga que não cabe em nenhum.

Publicá-la

curl -X POST https://api.wipperoz.com/v1/jobs/job_01J9A0B1C2EXAMPLE/publish \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ats-job-4471-publish" \
  -d '{"expiryDays": 30}'

{
  "job": {"id": "job_01J9A0B1C2EXAMPLE", "status": "published", "url": "…"},
  "firstPublish": true
}

• expiryDays é 30, 60, 90, ou null para sem expiração. null é o valor por omissão: uma vaga que desaparece numa data que ninguém escolheu é pior do que uma que fica no ar.
• firstPublish é false quando a vaga já tinha estado no ar — uma vaga fechada que reabre mantém o seu URL.
• Uma vaga a que falta o que a publicação exige responde 422 com uma lista missing, em vez de um 400 vago: title ou description em qualquer publicação, e category na primeira.

Editar uma vaga

curl -X PATCH https://api.wipperoz.com/v1/jobs/job_01J9A0B1C2EXAMPLE \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"salary": {"min": 170000, "max": 200000, "currency": "AUD", "period": "year"}}'

Envie apenas os campos que está a mudar; os restantes ficam como estão.

Num rascunho a alteração aplica-se de imediato. Numa vaga publicada as novas palavras ficam em espera em vez de substituírem o que os candidatos estão a ler agora, e a resposta di-lo:

{"job": {"…": "…tal como ainda se lê hoje"}, "pendingRevision": true}

Quem se candidata fá-lo perante as palavras que estão na página, e mudá-las por baixo de uma candidatura aberta muda aquilo que alguém aceitou depois de o ter aceitado. Por isso um recrutador promove a edição na Orbit — ou promove-a você mesmo na mesma chamada:

-d '{"salary": {...}, "publishEdits": true}'

Dois campos saltam a fila e aplicam-se sempre de imediato: expiresAt e maxMatches. Ambos existem para parar alguma coisa, e manter “parar às cinquenta correspondências” à espera de uma promoção deixaria a correspondência a correr para além do limite que definiu.

Um anúncio gerido mantém o título e a categoria

Quando um anúncio é gerido, uma edição que muda o seu title ou a sua category — diretamente, ou ao promover uma edição em espera com publishEdits — responde 409 e não muda nada: nem o anúncio no ar, nem o que está em espera. A resposta:

{
  "error": {
    "code": "managed_ad_locked",
    "message": "This job is a managed ad, so its title cannot change. Post the new role as a new job.",
    "requestId": "5f7a9c1e-2b3d-4e5f-8a9b-0c1d2e3f4a5b",
    "fields": ["title"]
  }
}

fields nomeia o que a edição teria mudado. Voltar a enviar o valor atual não é uma mudança, por isso uma sincronização que envia todos os campos em cada passagem continua a funcionar.

O bloqueio é o que impede que um anúncio gerido seja renomeado para passar a ser outro emprego. Se a vaga na origem passou mesmo a ser outro emprego, publique-a como uma nova. Se o novo título é simplesmente o certo, um recrutador deixa de gerir o anúncio na Orbit, no separador Configurações da vaga, e a edição passa. Esta API não diz se um anúncio é gerido; este 409 é onde uma integração o descobre.

Fechar uma vaga

curl -X POST https://api.wipperoz.com/v1/jobs/job_01J9A0B1C2EXAMPLE/close \
  -H "Authorization: Bearer $ORBIT_API_KEY"

A página alojada deixa de aceitar candidaturas e diz que a vaga fechou, a vaga sai do feed de procura de emprego, e o acesso aos CV que a vaga concedeu aos seus recrutadores termina com ela — a razão desse acesso era uma candidatura aberta. Fechar um anúncio gerido também devolve o lugar gerido ao seu plano.

As candidaturas que já recebeu ficam, e continuam legíveis na Orbit. Fechar não é apagar, e esta API não tem apagar. Só uma vaga publicada pode ser fechada; um rascunho ou uma vaga já fechada respondem 409.

Repetições que não publicam duas vezes

Envie uma Idempotency-Key em cada POST. Qualquer valor que identifique a intenção serve — o identificador da vaga no seu próprio sistema é o ideal.

• Uma repetição com a mesma chave devolve a primeira resposta, com Idempotent-Replay: true. Sem segundo anúncio, sem segunda publicação.
• A mesma chave com um corpo diferente responde 409. Duas intenções com um só nome são um erro que vale a pena saber.
• As chaves são recordadas durante 24 horas, por conta.
• Um pedido recusado liberta a sua chave, por isso um 422 que resolve acrescentando o que faltava pode ser repetido com a mesma chave.

Sem o cabeçalho, duas criações iguais fazem dois anúncios. As redes expiram: envie o cabeçalho.

Manter uma sincronização honesta

• Guarde o nosso id junto à sua vaga. É a única referência estável.
• Feche o que fechou na origem. Um anúncio desatualizado custa uma tarde a um candidato, o que é pior do que não haver anúncio.
• Não volte a criar em cada sincronização. Faça PATCH à vaga que já criou; um POST novo faz um segundo anúncio com um segundo URL.
• Atribua uma category a cada família de vagas de uma vez por todas, e envie-a em cada criação. Um rascunho sem ela não pode ir para o ar.
• Trate managed_ad_locked como uma decisão, não como uma repetição. Repetir a mesma mudança de nome recebe o mesmo 409.
• Limite de pedidos: 120 por minuto por chave. Quarenta vagas são quarenta chamadas, folgadamente dentro do limite.

Referência