As suas ofertas. Uma integração.

Qualquer conta principal de empresa verificada e em bom estado pode testar, mesmo antes de subscrever um plano de produção. Crie uma credencial Sandbox em Gerir credenciais.

Os dois ambientes têm os mesmos endpoints e validações. As categorias, regiões e opções são referências reais apenas de leitura; ofertas, chaves de idempotência e quotas de teste são separadas. Uma credencial de teste nunca funciona em produção, nem o contrário. As respostas identificam o ambiente em X-API-Environment.

A sandbox permite 100 ofertas por empresa e usa limites de pedidos separados. As ofertas de teste ficam pendentes; DELETE simula a retirada. Não há publicação pública, candidaturas, emails, destaques, consumo de quotas reais ou verificações geográficas de publicação. Use dados fictícios. Pode limpar as ofertas e as chaves de idempotência no painel, escrevendo RESET; as credenciais continuam válidas.

Depois de testar a criação, peça acesso à produção no painel. A equipa analisa e aprova cada empresa. É necessário um plano com API incluída. Pode preparar uma credencial de produção antecipadamente; os pedidos só serão autorizados quando o plano e a aprovação estiverem válidos. Depois, altere a URL e a credencial na integração. Nenhuma oferta de teste é promovida ou copiada automaticamente.

O painel de credenciais está disponível em todos os planos de empresa. O acesso de produção à API e ao MCP exige um plano elegível (Pro, VIP e Especial por defeito) e aprovação administrativa. O titular da conta cria uma credencial após confirmar a palavra-passe. As subcontas não podem emitir credenciais.

Envie a credencial em cada pedido: Authorization: Bearer be_test_… (sandbox) ou be_live_… (produção). Use exclusivamente HTTPS e guarde o segredo no servidor. Não utilize a palavra-passe da conta, cookies, parâmetros de URL ou código JavaScript público. Cada segredo é apresentado uma única vez, tem validade máxima de 365 dias e pode ser revogado imediatamente.

Escolha acesso de leitura ou leitura e escrita. Para rodar credenciais, crie uma nova, atualize a integração e revogue a anterior. Pode manter até cinco credenciais válidas por ambiente. A produção exige sempre aprovação administrativa individual, além do plano elegível.

Authorization: Bearer YOUR_TOKEN
Accept: application/json
Content-Type: application/json

Estas consultas devolvem os dados necessários para preencher uma oferta. Funcionam nos dois ambientes e devolvem a lista completa em data.

Consulte primeiro as categorias e regiões. Use uma especialidade ativa (categoria com parent_id) e envie o identificador da região em district_id. Os IDs abaixo são exemplos: substitua-os pelos valores devolvidos pela API.

curl 'https://www.bonsempregos.com/api/sandbox/v1/jobs' \
  -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ats-vaga-2026-001' \
  --data '{
    "title": "Programador PHP",
    "body": "<p>Procuramos uma pessoa para a nossa equipa.</p>",
    "contact_instructions": "Candidate-se através do Bons Empregos.",
    "category_id": 123,
    "district_id": 1,
    "application_method": "system",
    "work_modality": "hibrido"
  }'

A empresa proprietária é identificada pela credencial. Envie estes seis campos na criação.

Consulte todos os tipos, limites e esquemas na especificação OpenAPI.

URL base: https://www.bonsempregos.com/api/v1. Envie Accept: application/json e, nos pedidos com corpo, Content-Type: application/json.

As listagens de ofertas aceitam page, per_page (25 por defeito, máximo 100) e status (active, pending, inactive, expired). A resposta contém data e meta com current_page, per_page, total e last_page. As referências devolvem a lista completa em data.

As ofertas entram em revisão, exceto quando a empresa tem autorização de publicação automática. Atualizar uma oferta ativa volta a colocá-la em revisão se a empresa não tiver essa autorização. Ofertas retiradas ou expiradas não são republicadas pelo PATCH. A API não permite alterar o proprietário, estado de aprovação, destaques ou publicação anónima.

Cada criação exige um Idempotency-Key único por empresa, com 1–128 caracteres (letras, números, ponto, hífen, sublinhado ou dois-pontos). Repita a mesma chave e o mesmo JSON quando houver um timeout: não será criada outra oferta. Uma criação devolve 201; uma repetição devolve 200 com Idempotent-Replayed: true e o estado atual da oferta. Uma chave com conteúdo diferente devolve 409. A chave fica reservada mesmo que a oferta seja removida (410).

As publicações pelo site e pela API partilham o limite do plano. Retirar uma oferta não devolve a utilização. Consulte /account: -1 significa ilimitado. O acesso termina quando a subscrição deixa de ser elegível. São permitidos 60 pedidos por minuto por empresa, partilhados entre credenciais; existe também proteção por IP.

{"error":{"status":422,"message":"…","details":{"title":["…"]}}}

Em caso de 429, aguarde os segundos indicados em Retry-After. Após timeout ou erro 5xx, use espera progressiva e repita a criação com a mesma chave. Não repita automaticamente erros de validação.