Publicar un puesto desde tu propio sistema

Actualizado 8 de septiembre de 2026

Si tus puestos ya viven en otro sitio —un ATS, una herramienta interna, una hoja de cálculo que alguien custodia— así es como llegan a Orbit sin que nadie los vuelva a teclear.

Qué necesitas

Una clave con el permiso de leer y gestionar empleos, creada en Orbit → Configuración → Claves de API. Una clave de solo lectura responde 403 en todas las peticiones de esta página, a propósito: publicar gasta tus créditos, y la clave que alimenta una página de empleo no debería además poder publicar anuncios.

export ORBIT_API_KEY="…una clave con leer y gestionar empleos…"

La forma: dos llamadas

Crear y publicar están separados.

POST /v1/jobs crea un borrador. Nada es público. No se cobra nada.
POST /v1/jobs/{jobId}/publish lo pone en marcha y cobra la tarifa de publicación.

Es deliberado. Publicar pone el puesto en tu página de vacante alojada, permite que la gente se postule, lo incorpora al feed de personas que buscan empleo en Wipperoz y arranca la ronda de emparejamiento con IA. Una sola llamada que hiciera todo eso significaría que una clave en un bucle mal configurado gasta tu saldo antes de que nadie mire un log.

También deja a una persona en el circuito cuando la quieres: crea los borradores desde tu sistema y deja que alguien de selección los publique desde Orbit después de leerlos. Si no la quieres, llama tú a publish. Ambas cosas están soportadas; la decisión es tuya, no nuestra.

Crear el borrador

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": "Ingeniera de Backend Senior",
    "description": "<p>Responsable de los servicios detrás de nuestro proceso de contratación.</p>",
    "responsibilities": ["Diseñar y desplegar servicios en AWS Lambda y 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": "Ingeniera de Backend Senior",
    "applyLink": "https://www.wipperoz.com/es/apply/job_01J9A0B1C2EXAMPLE?src=careers&account=acc_01J8Z3EXAMPLE"
  }
}

Guarda el id. Es con lo que después publicas, editas y cierras el puesto, y es el identificador que deberías guardar junto al puesto en tu propio sistema.

Solo title es obligatorio. Todo lo demás es opcional aquí: description pasa a ser obligatorio al publicar, y nada más bloquea nunca la publicación. description acepta HTML, que es lo que produce el editor de Orbit; el texto plano también vale.

Publicarlo

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 es 30, 60, 90 o null para sin caducidad. null es el valor por defecto: un puesto que desaparece en una fecha que nadie eligió es peor que uno que se queda.
creditsCharged es lo que costó esta llamada. Volver a publicar un puesto que ya estuvo activo —un puesto cerrado que reabres— conserva su URL y no cuesta nada; firstPublish te dice cuál de las dos cosas pasó.
Sin créditos suficientes responde 402 con el saldo, y no se escribe nada. Recarga y vuelve a llamar al mismo endpoint.
Un puesto al que le falta el título o la descripción responde 422 con una lista missing, en lugar de un 400 impreciso.

Editar un puesto

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"}}'

Envía solo los campos que cambias; el resto se queda como está.

En un borrador el cambio se aplica al momento. En un puesto publicado las palabras nuevas quedan en espera en lugar de sustituir lo que la gente está leyendo ahora mismo, y la respuesta lo dice:

{"job": {"…": "…tal y como sigue leyéndose hoy"}, "pendingRevision": true}

Quienes se postulan lo hacen sobre las palabras que hay en la página, y cambiarlas por debajo de una candidatura abierta cambia lo que alguien aceptó después de que lo aceptara. Así que alguien de selección promueve la edición en Orbit, o la promueves tú en la misma llamada:

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

Dos campos se saltan la cola y se aplican siempre al momento: expiresAt y maxMatches. Ambos existen para detener algo, y dejar “para en cincuenta coincidencias” a la espera de una promoción seguiría gastando los créditos que el límite se puso para ahorrar.

Cerrar un puesto

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

La página alojada deja de aceptar candidaturas y dice que el puesto se ha cerrado, el puesto sale del feed de búsqueda de empleo, y el acceso a los CV que ese puesto concedió a tu equipo termina con él: la razón de ese acceso era una candidatura abierta.

Las candidaturas que ya recibiste se quedan, y se siguen pudiendo leer en Orbit. Cerrar no es borrar, y esta API no tiene borrado. Solo se puede cerrar un puesto publicado; un borrador o un puesto ya cerrado responden 409.

Reintentos que no te cobran dos veces

Envía una Idempotency-Key en cada POST. Cualquier valor que identifique la intención sirve; el identificador del puesto en tu propio sistema es ideal.

Un reintento con la misma clave devuelve la primera respuesta, con Idempotent-Replay: true. Ni un segundo anuncio ni un segundo cobro.
La misma clave con un cuerpo distinto responde 409. Dos intenciones con un mismo nombre son un error del que conviene enterarse.
Las claves se recuerdan 24 horas, por cuenta.
Una petición rechazada libera su clave, así que un 402 que resuelves recargando se puede reintentar con la misma clave.

Sin la cabecera, dos creaciones idénticas hacen dos anuncios. Las redes dan timeout: envía la cabecera.

Mantener honesta una sincronización

Guarda nuestro id junto a tu puesto. Es el único identificador estable.
Cierra lo que se cerró en origen. Un anuncio caducado le cuesta la tarde a alguien, lo que es peor que no tener anuncio.
No vuelvas a crear en cada sincronización. Haz PATCH sobre el puesto que ya creaste; un POST nuevo hace un segundo anuncio con una segunda tarifa y una segunda URL.
Límite de peticiones: 120 por minuto y clave. Cuarenta puestos son cuarenta llamadas, holgadamente dentro.

Referencia

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