Saltar al contenido
Documentación para desarrolladoresReferencia de la APIPlantillas

Crear una plantilla

Guarda un artículo como plantilla (también aparece en la aplicación).

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

Admite los mismos campos que un artículo de /v1/pack y se valida igual. Gratis: no se cobran créditos.

Autenticación

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

Parámetros del cuerpo

application/json
NombreTipoObligatorioDescripción
labelstringobligatorio
string
Sí

Etiqueta visible.

≤ 255 chars
shapestring
string
No

Forma del artículo. cylinder y drum usan radius + height en lugar de length + width; pallet y drum siempre se mantienen en vertical.

boxcylinderpalletbagdrumPredeterminado "box"
lengthnumber · cm
number · cm
No

Largo. Obligatorio salvo que shape sea cylinder o drum.

widthnumber · cm
number · cm
No

Ancho. Obligatorio salvo que shape sea cylinder o drum.

heightnumber · cmobligatorio
number · cm
Sí

Alto (el lado vertical cuando el artículo está colocado tal como se definió).

radiusnumber · cm
number · cm
No

Radio. Obligatorio cuando shape es cylinder o drum.

weightnumber · kgobligatorio
number · kg
Sí

Peso de UNA unidad.

stackableboolean
boolean
No

Se pueden colocar otros artículos encima.

Predeterminado true
max_stack_weightnumber · kg
number · kg
No

Peso máximo que puede soportar una unidad. 0 = ilimitado.

Predeterminado 0
rotationstring
string
No

all = cualquiera de las seis orientaciones; upright = solo puede girar sobre el eje vertical (este lado arriba); fixed = nunca se gira.

alluprightfixedPredeterminado "all"
hazardousboolean
boolean
No

Mercancía peligrosa: se mantiene cerca del suelo y separada de otros artículos peligrosos.

Predeterminado false
priorityinteger
integer
No

Prioridad de carga. Mayor = se carga antes y se mantiene cuando falta espacio. 0 = ninguna.

Predeterminado 0
colorstring
string
No

Color de visualización en formato #rrggbb (solo visor y PDF).

nesting_heightnumber · cm
number · cm
No

Solapamiento telescópico cuando se apilan unidades idénticas (cajas o cubos encajables).

Predeterminado 0

Ejemplo de solicitud

curl -X POST "https://runner.cargoduo.com/v1/templates" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Euro pallet",
    "length": 120,
    "width": 80,
    "height": 140,
    "weight": 450,
    "stackable": false,
    "color": "#3b82f6"
  }'

Ejemplo de respuesta

201 · Template
{
  "id": "tpl_42",
  "object": "template",
  "label": "Euro pallet",
  "shape": "box",
  "length": 120,
  "width": 80,
  "height": 140,
  "radius": 0,
  "weight": 450,
  "stackable": false,
  "max_stack_weight": 0,
  "rotation": "all",
  "hazardous": false,
  "priority": 0,
  "color": "#3b82f6",
  "nesting_height": 0,
  "created_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "updated_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "created_at": "2026-09-28T14:05:52Z",
  "updated_at": "2026-09-28T14:05:52Z"
}

Respuestas

  • 201La plantilla nueva.
    NombreTipoObligatorioDescripción
    idstring
    string
    No

    ID de la plantilla (tpl_…).

    objectstring
    string
    No
    template
    labelstring
    string
    No

    Etiqueta visible.

    shapestring
    string
    No

    Forma del artículo. cylinder y drum usan radius + height en lugar de length + width; pallet y drum siempre se mantienen en vertical.

    boxcylinderpalletbagdrum
    lengthnumber · cm
    number · cm
    No

    Largo. Obligatorio salvo que shape sea cylinder o drum.

    widthnumber · cm
    number · cm
    No

    Ancho. Obligatorio salvo que shape sea cylinder o drum.

    heightnumber · cm
    number · cm
    No

    Alto (el lado vertical cuando el artículo está colocado tal como se definió).

    radiusnumber · cm
    number · cm
    No

    Radio. Obligatorio cuando shape es cylinder o drum.

    weightnumber · kg
    number · kg
    No

    Peso de UNA unidad.

    stackableboolean
    boolean
    No

    Se pueden colocar otros artículos encima.

    max_stack_weightnumber · kg
    number · kg
    No

    Peso máximo que puede soportar una unidad. 0 = ilimitado.

    rotationstring
    string
    No

    all = cualquiera de las seis orientaciones; upright = solo puede girar sobre el eje vertical (este lado arriba); fixed = nunca se gira.

    alluprightfixed
    hazardousboolean
    boolean
    No

    Mercancía peligrosa: se mantiene cerca del suelo y separada de otros artículos peligrosos.

    priorityinteger
    integer
    No

    Prioridad de carga. Mayor = se carga antes y se mantiene cuando falta espacio. 0 = ninguna.

    colorstring
    string
    No

    Color de visualización en formato #rrggbb (solo visor y PDF).

    nesting_heightnumber · cm
    number · cm
    No

    Solapamiento telescópico cuando se apilan unidades idénticas (cajas o cubos encajables).

    created_byUserRef | null
    UserRef | null
    No

    El miembro que lo creó (en las llamadas a la API: el miembro que creó la clave). null si se desconoce.

    updated_byUserRef | null
    UserRef | null
    No

    El último miembro que lo modificó.

    created_atstring
    string
    No

    RFC 3339.

    updated_atstring
    string
    No

    RFC 3339.

  • 400Bad requestinvalid_json
    • invalid_jsonEl cuerpo no es JSON válido o un campo tiene un tipo incorrecto.
    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
  • 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 requestsrate_limited
    • 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