GET /v1/jobs/{job_id}

Consulta el estado de un trabajo creado por tu plataforma.

Descripción

Este endpoint te permite consultar el estado actual de un trabajo que fue creado usando tu API key. Solo puedes ver trabajos creados por tu plataforma.

Importante: Solo puedes consultar trabajos que fueron creados con tu API key. Si intentas acceder a un trabajo creado por otro partner o directamente en la app, recibirás un error 403 Forbidden.

Endpoint

GET https://api.recigo.es/v1/jobs/{job_id}

Headers

X-API-Key: recigo_live_abc123...

Parámetros de URL

job_idrequerido

string (UUID)

ID del trabajo que deseas consultar. Este es el job_id que recibiste al crear el trabajo con POST /v1/jobs.

Ejemplo de Request

GET /v1/jobs/550e8400-e29b-41d4-a716-446655440000

curl -X GET \
  https://api.recigo.es/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: recigo_live_abc123..."

Respuesta Exitosa (200 OK)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_reference": "blocket-listing-12345",
  "status": "posted",
  "created_at": "2026-02-21T09:00:00Z",
  "updated_at": "2026-02-21T09:15:00Z"
}

Campos de la Respuesta

job_id

ID único del trabajo en ReciGo

external_reference

Tu referencia externa que proporcionaste al crear el trabajo (puede ser null)

status

Estado actual del trabajo. Ver sección "Estados del Trabajo" abajo.

created_at

Fecha y hora de creación del trabajo (formato ISO 8601)

updated_at

Fecha y hora de última actualización del trabajo (formato ISO 8601)

Estados del Trabajo

draftBorrador

El trabajo ha sido creado y el SMS ha sido enviado al cliente. El cliente aún no ha completado el pago en la app. El trabajo expira automáticamente después de 48 horas si no se completa.

postedPublicado

El cliente ha completado el pago y publicado el trabajo. Ahora es visible para transportistas cercanos en la app ReciGo.

acceptedAceptado

Un transportista ha aceptado el trabajo y está en camino.

completedCompletado

El trabajo ha sido completado exitosamente. El transportista ha entregado el objeto y el pago ha sido procesado.

cancelledCancelado

El trabajo ha sido cancelado por el cliente o el transportista.

Códigos de Error

401Unauthorized

API key inválida o faltante

{
  "error": "unauthorized",
  "message": "API key inválida o faltante"
}

403Forbidden

Intentaste acceder a un trabajo que no fue creado con tu API key

{
  "error": "unauthorized",
  "message": "Solo puedes ver trabajos creados con tu API key"
}

404Not Found

El trabajo no existe o ha sido eliminado

{
  "error": "not_found",
  "message": "Trabajo no encontrado"
}

429Too Many Requests

Límite de tasa excedido

{
  "error": "rate_limit_exceeded",
  "message": "Has excedido el límite de solicitudes",
  "retry_after_seconds": 60
}

Notas Importantes

🔒 Autorización

Solo puedes consultar trabajos que fueron creados con tu API key. Esta restricción protege la privacidad de los clientes y otros partners.

🔄 Modelo Fire-and-Forget

ReciGo utiliza un modelo "fire-and-forget" para la integración de partners. Esto significa que NO enviamos webhooks cuando el estado del trabajo cambia. Si necesitas conocer el estado actual de un trabajo, debes usar este endpoint para consultarlo.

⏱️ Expiración de Borradores

Los trabajos en estado "draft" expiran automáticamente después de 48 horas si el cliente no completa el pago. Después de la expiración, el trabajo es eliminado y este endpoint devolverá un error 404.

📊 Polling vs Webhooks

Si necesitas rastrear cambios de estado en tiempo real, puedes implementar polling (consultar el endpoint periódicamente). Sin embargo, ten en cuenta el límite de tasa de 100 solicitudes por minuto. Para la mayoría de casos de uso, no es necesario rastrear el estado después de la creación.

Ejemplo de Uso Completo

Aquí hay un ejemplo de cómo podrías usar este endpoint después de crear un trabajo:

ejemplo-consulta-estado.js

// Paso 1: Crear el trabajo
const createResponse = await fetch('https://api.recigo.es/v1/jobs', {
  method: 'POST',
  headers: {
    'X-API-Key': 'recigo_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    external_reference: 'blocket-listing-12345',
    title: 'Mover sofá de 2 plazas',
    // ... otros campos
  })
});

const job = await createResponse.json();
console.log('Trabajo creado:', job.job_id);

// Paso 2: Esperar un tiempo (ej: 1 hora después)
// El cliente debería haber recibido el SMS y completado el pago

// Paso 3: Consultar el estado del trabajo
const statusResponse = await fetch(
  `https://api.recigo.es/v1/jobs/${job.job_id}`,
  {
    headers: {
      'X-API-Key': 'recigo_live_abc123...'
    }
  }
);

const status = await statusResponse.json();

if (status.status === 'posted') {
  console.log('¡El cliente completó el pago! El trabajo está publicado.');
} else if (status.status === 'draft') {
  console.log('El cliente aún no ha completado el pago.');
} else if (status.status === 'completed') {
  console.log('¡El trabajo ha sido completado!');
}

// Actualizar tu base de datos con el estado
await updateJobInDatabase(job.external_reference, status.status);