Publicar uma vaga a partir do seu próprio sistema

Atualizado 8 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 gasta os seus créditos, 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.

POST /v1/jobs cria um rascunho. Nada é público. Nada é cobrado.
POST /v1/jobs/{jobId}/publish põe-no no ar e cobra a taxa de publicação.

É deliberado. Publicar coloca a vaga na sua página de vaga alojada, deixa os candidatos candidatarem-se, entra no feed de quem procura emprego na Wipperoz e arranca a ronda de correspondência por IA. Uma única chamada que fizesse tudo isso significaria que uma chave num ciclo mal configurado gasta o seu saldo 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.

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

Só title é obrigatório. Tudo o resto é opcional aqui — description passa a ser obrigatório na publicação, e mais nada alguma vez a bloqueia. description aceita HTML, que é o que o editor da Orbit produz; texto simples também serve.

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": "…"},
  "creditsCharged": 500,
  "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.
creditsCharged é o que esta chamada custou. Voltar a publicar uma vaga que já esteve no ar — uma vaga fechada que reabre — mantém o seu URL e não custa nada; firstPublish diz-lhe qual dos casos aconteceu.
Créditos insuficientes respondem 402 com o saldo, e nada é escrito. Carregue e chame o mesmo endpoint outra vez.
Uma vaga sem título ou sem descrição responde 422 com uma lista missing, em vez de um 400 vago.

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 continuaria a gastar os créditos que o limite foi definido para poupar.

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.

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 lhe cobram 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 cobrança.
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 402 que resolve carregando saldo 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 uma segunda taxa e um segundo URL.
Limite de pedidos: 120 por minuto por chave. Quarenta vagas são quarenta chamadas, folgadamente dentro do limite.

Referência

Create a draft jobPOST /v1/jobs Publish a jobPOST /v1/jobs/{jobId}/publish Edit a jobPATCH /v1/jobs/{jobId} Close a jobPOST /v1/jobs/{jobId}/close