Saltar al contenido
Documentación para desarrolladoresReferencia de la APICarga

Crear un trabajo de carga

Valida la solicitud, reserva de tus créditos el precio máximo posible y pone un trabajo en cola.

POSThttps://runner.cargoduo.com/v1/pack

Responde 202 con el trabajo; consulta GET /v1/jobs/{id} periódicamente o pasa ?wait= para mantener la respuesta abierta hasta que termine. Los errores de validación (422) son gratuitos y no crean ningún trabajo.

Autenticación

Clave de API Bearer con el permisopack:writeMás información

Parámetros de consulta

NombreTipoObligatorioDescripción
waitinteger
integer
No

Segundos que la respuesta espera a que el trabajo termine. Si termina a tiempo: 200 con el resultado incluido. Si no: 202.

Predeterminado 00–60

Parámetros de cabecera

NombreTipoObligatorioDescripción
Idempotency-Keystring
string
No

Cualquier cadena única, como un UUID o tu ID de pedido. La misma clave dentro de un plazo de 24 h devuelve el trabajo original en lugar de crear y cobrar uno nuevo.

≤ 128 chars

Parámetros del cuerpo

application/json
NombreTipoObligatorioDescripción
referencestring
string
No

Tu propia referencia (número de pedido, ID de envío…). Se devuelve en el trabajo.

≤ 128 chars
vehiclesVehicle[]obligatorio
Vehicle[]
Sí

Definiciones de vehículos. Cada una puede tener quantity > 1. Al menos una.

itemsItem[]obligatorio
Item[]
Sí

Definiciones de artículos. Cada una puede tener quantity > 1. Al menos una.

groupsGroup[]
Group[]
No

Grupos opcionales (clientes, paradas, pedidos). Obligatorios para cada grupo que indique un artículo cuando options.group_routing no es "none"; si no, los grupos se crean a partir de los nombres de grupo de los artículos, por orden de aparición.

optionsOptions
Options
No

Opciones de carga. Todos los campos son opcionales.

Ejemplo de solicitud

curl -X POST "https://runner.cargoduo.com/v1/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }'

Ejemplo de respuesta

202 Accepted · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "created_at": "2026-10-19T09:12:03Z",
  "started_at": null,
  "finished_at": null,
  "progress": {
    "stage": "queued",
    "vehicles_done": 0,
    "placed_items": 0
  },
  "summary": {
    "items_requested": 58,
    "items_placed": 0,
    "items_unplaced": 0,
    "vehicles_used": 0,
    "total_weight": 0,
    "volume_utilization": 0,
    "queue_ms": 0,
    "compute_ms": 0
  },
  "cost": {
    "credits": 0,
    "reserved_credits": 1.11,
    "rate_card_version": 1,
    "breakdown": {
      "base": 0,
      "vehicles": 0,
      "compute": 0,
      "large_load": 0
    }
  },
  "error": null,
  "warnings": [],
  "result_url": "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f/result",
  "pdf_url": "",
  "expires_at": "2026-11-02T09:12:03Z"
}

Respuestas

  • 200OKTrabajo terminado dentro del plazo de ?wait, con el resultado incluido. También la repetición idempotente de un trabajo terminado.
    NombreTipoObligatorioDescripción
    idstringobligatorio
    string
    Sí

    ID del trabajo (job_…).

    objectstringobligatorio
    string
    Sí

    Siempre job.

    job
    statusstringobligatorio
    string
    Sí

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    No

    Tu referencia, tomada de la solicitud.

    sourcestring
    string
    No

    Dónde se creó el trabajo.

    apiplayground
    project_idstring
    string
    No

    El proyecto (prj_…) en el que un trabajo de POST /v1/projects/{id}/pack guarda su plan. Ausente en los demás trabajos.

    created_atstringobligatorio
    string
    Sí

    Marca de tiempo RFC 3339.

    started_atstring | null
    string | null
    No

    Cuándo empezó el cálculo (RFC 3339) o null.

    finished_atstring | null
    string | null
    No

    Cuándo terminó el trabajo (RFC 3339) o null.

    progressJobProgress
    JobProgress
    No

    Progreso en tiempo real mientras está en cola o en curso.

    summaryJobSummary
    JobSummary
    No

    Recuentos y tiempos.

    costJobCost
    JobCost
    No

    Créditos cobrados (definitivos cuando el trabajo termina) y la reserva retenida mientras se ejecutaba.

    errorJobError | null
    JobError | null
    No

    Por qué falló o se canceló el trabajo; null en otro caso.

    warningsWarning[]
    Warning[]
    No

    Observaciones no bloqueantes sobre la solicitud (también se repiten en el resultado).

    result_urlstring
    string
    No

    Haz una solicitud GET a esta URL para obtener el resultado completo cuando status sea succeeded.

    pdf_urlstring
    string
    No

    Enlace que, abierto en un navegador, genera el plan de carga en PDF (vistas 3D + pasos de carga). Válido hasta expires_at. Vacío tras la caducidad.

    expires_atstring
    string
    No

    Cuándo se eliminan los cuerpos de solicitud y de resultado y el enlace al PDF (RFC 3339). Los metadatos y los cargos del trabajo se conservan.

    resultResult
    Result
    No

    El resultado completo, incluido solo si se pide (?include=result) o si POST /v1/pack?wait= terminó a tiempo.

  • 202AcceptedTrabajo aceptado (en cola o en curso).
    NombreTipoObligatorioDescripción
    idstringobligatorio
    string
    Sí

    ID del trabajo (job_…).

    objectstringobligatorio
    string
    Sí

    Siempre job.

    job
    statusstringobligatorio
    string
    Sí

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    No

    Tu referencia, tomada de la solicitud.

    sourcestring
    string
    No

    Dónde se creó el trabajo.

    apiplayground
    project_idstring
    string
    No

    El proyecto (prj_…) en el que un trabajo de POST /v1/projects/{id}/pack guarda su plan. Ausente en los demás trabajos.

    created_atstringobligatorio
    string
    Sí

    Marca de tiempo RFC 3339.

    started_atstring | null
    string | null
    No

    Cuándo empezó el cálculo (RFC 3339) o null.

    finished_atstring | null
    string | null
    No

    Cuándo terminó el trabajo (RFC 3339) o null.

    progressJobProgress
    JobProgress
    No

    Progreso en tiempo real mientras está en cola o en curso.

    summaryJobSummary
    JobSummary
    No

    Recuentos y tiempos.

    costJobCost
    JobCost
    No

    Créditos cobrados (definitivos cuando el trabajo termina) y la reserva retenida mientras se ejecutaba.

    errorJobError | null
    JobError | null
    No

    Por qué falló o se canceló el trabajo; null en otro caso.

    warningsWarning[]
    Warning[]
    No

    Observaciones no bloqueantes sobre la solicitud (también se repiten en el resultado).

    result_urlstring
    string
    No

    Haz una solicitud GET a esta URL para obtener el resultado completo cuando status sea succeeded.

    pdf_urlstring
    string
    No

    Enlace que, abierto en un navegador, genera el plan de carga en PDF (vistas 3D + pasos de carga). Válido hasta expires_at. Vacío tras la caducidad.

    expires_atstring
    string
    No

    Cuándo se eliminan los cuerpos de solicitud y de resultado y el enlace al PDF (RFC 3339). Los metadatos y los cargos del trabajo se conservan.

    resultResult
    Result
    No

    El resultado completo, incluido solo si se pide (?include=result) o si POST /v1/pack?wait= terminó a tiempo.

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_jsonEl cuerpo no es JSON válido o un campo tiene un tipo incorrecto.
    • idempotency_key_invalidLa cabecera Idempotency-Key tiene más de 128 caracteres.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedClave de API ausente, mal formada o desconocida.
    • key_revokedLa clave se ha revocado.
    • key_expiredLa clave ha superado su fecha de caducidad.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 402Payment requiredinsufficient_credits
    • insufficient_creditsLos créditos disponibles no cubren el coste mínimo posible de este trabajo.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedLa IP de origen no está en la lista de IP permitidas de la clave.
    • subscription_inactiveLa organización no tiene ninguna suscripción activa que incluya la API.
    • account_inactiveLa organización está suspendida o no tiene ningún propietario con la cuenta activa.
    • scope_missingA la clave le falta un permiso que requiere este endpoint.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 413Payload too largepayload_too_large
    • payload_too_largeEl cuerpo de la solicitud supera los 10 MB.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 422Unprocessable entityvalidation_failed
    • validation_failedLa solicitud es JSON bien formado, pero describe un trabajo no válido. details[] enumera todos los problemas.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 429Too many requeststoo_many_jobsrate_limited
    • too_many_jobsLa organización ya tiene el número máximo de trabajos en cola + en curso.
    • rate_limitedDemasiadas solicitudes en el minuto, la hora o el día en curso (por clave o por organización), o más de 60 autenticaciones fallidas por minuto desde tu dirección IP.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 500Internal server errorinternal_error
    • internal_errorAlgo ha fallado por nuestra parte.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error
  • 503Service unavailableapi_disabled
    • api_disabledLa API está desactivada temporalmente (mantenimiento) o deshabilitada para la organización.
    NombreTipoObligatorioDescripción
    errorErrorBodyobligatorio
    ErrorBody
    Sí
    Todos los códigos de error