Cadastrar ou editar uma vaga externa

Escreve na sua lista. Com um id novo (um uuid v4 aleatório que você gera com crypto.randomUUID(), nunca derivado do link ou de outro dado: o id é global, e um previsível colidiria com o de outra conta e diria se ele já existe), cria a vaga externa e responde 201; com o id de uma que já é sua, edita e responde 200, e campo omitido fica como está. Repetir o mesmo PUT não cria outra: é assim que a criação é idempotente sem POST. Na criação, empresa e cargo são obrigatórios, mas o link pode trazê-los: link de vaga do Ashby, do Greenhouse ou do Lever é lido na API pública do ATS (timeout de poucos segundos) e preenche o que você não mandou; se não der, a resposta é 422 pedindo o campo. Link de uma vaga que já está no catálogo responde 409 in_catalog com o slug dela: acompanhe com PUT /api/v1/eu/vagas/{slug}. O mesmo link duas vezes na sua lista responde 409 conflict. link com null (ou texto vazio) apaga. Mudar só a etapa é mandar só etapa; ela só mexe em atualizada_em quando muda. nota_no_historico vai no histórico da vaga (na criação, no evento de entrada; sem etapa, como nota solta). nota é o nome antigo do mesmo campo, aceito por compatibilidade: a primeira nota, que vai pro histórico (desde 2026-10-12 a vaga externa não tem mais nota à parte), e na resposta nota é a nota mais antiga do histórico. desfecho só vale com a etapa encerrada (a mandada ou a atual; fora dela, 422), e sair de Encerrada limpa. Até 500 externas por conta, e até 200 em andamento (toda etapa menos encerrada): criar além de um dos dois responde 409 conflict; editar, inclusive reabrir uma encerrada, nunca é recusado pelo teto. Criar e editar têm limite próprio por conta, além do geral: 60 a cada 10 minutos e 200 por dia (passou, 429 rate_limited com Retry-After). Campo desconhecido no corpo responde 422.