La API de creación de pedidos de envío es una API RESTful que te permite crear un pedido de envío para generar una etiqueta de envío y un código de seguimiento para un paquete.

POST /v1/shipping-orders

Ejemplo de solicitud

{  "orderReferenceId": "EXMPL0001234",  "currency": "EUR",  "options": {    "weightUnit": "g",    "dimensionUnit": "mm",    "label": {      "format": "pdf"    }  },  "partner": {    "clientName": "ExampleCustomer"  },  "shippingMethod": {    "uid": "",    "carrier": "",    "tier": "standard"  },  "receiver": {    "person": {      "firstName": "Foo",      "lastName": "Bar",      "company": "",      "email": "[email protected]",      "phone": "01273552886"    },    "address": {      "country": "GB",      "state": "East Sussex",      "city": "Brighton",      "postcode": "BN1 8YQ",      "addressLine1": "11 London Rd",      "addressLine2": "",      "addressLine3": "",      "street": "London Rd",      "houseNumber": "11",      "suburb": null    },    "customs": {      "vatNumber": null    }  },  "sender": {    "person": {      "firstName": "",      "lastName": "",      "company": "Example Company",      "email": "[email protected]",      "phone": "01666 123456"    },    "address": {      "country": "DE",      "state": "",      "city": "Donauwörth",      "postcode": "86609",      "addressLine1": "Am Wassergraben 11",      "addressLine2": null,      "addressLine3": null,      "street": "Am Wassergraben",      "houseNumber": "11",      "suburb": null    },    "customs": {      "vatNumber": "DE123456789000",      "iossNumber": null,      "eoriNumber": "GB987654321000",      "pcccNumber": null,      "australianBusinessNumber": null    }  },  "packages": [    {      "packageReferenceId": "EXMPL0001234-0-1",      "grossWeight": 810,      "netWeight": 760,      "length": 229,      "width": 200,      "height": 36,      "boxType": "rectangle",      "volumetricWeight": 700,      "items": [        {          "itemReferenceId": "EXMPL0001234-0-1-ITEM1",          "description": "Mug",          "value": 18.42,          "quantity": 4,          "weight": 760,          "hsCode": "44199090",          "countryOfOrigin": "DE"        }      ]    }  ]}

Ejemplo de respuesta exitosa

{  "orderId": "fb7c0bf6-bdb1-4443-b5db-7263793be32b",  "orderReferenceId": "EXMPL0001234",  "shippingMethod": {    "carrier": "UPS",    "uid": "ups_standard_tariff"  },  "packages": [    {      "packageReferenceId": "EXMPL0001234-0-1",      "trackingNumber": "EXMPL0001234TRCKNUM",      "trackingUrl": "https://www.ups.com/track?track=yes&trackNums=EXMPL0001234TRCKNUM&loc=en_US&requester=ST",      "label": {        "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf",        "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf",        "contentType": "application/pdf"      },      "documents": [        {          "documentType": "invoice",          "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf",          "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf",          "contentType": "application/pdf"        }      ],      "totalCost": {        "value": 2.56,        "currency": "EUR"      }    }  ]}

Ejemplo de respuesta de error

{  "orderReferenceId": "EXMPL0001234",  "code": "PUBLIC_API_ERROR",  "message": "Processing error",  "detail": {    "code": "UPS_API_ERROR",    "message": {      "status": {        "title": "Bad Request",        "status": 400,        "detail": "0 of 1 shipment successfully created.",        "statusCode": 400      },      "items": [        {          "sstatus": {            "title": "Bad Request",            "status": 400,            "statusCode": 400          },          "validationMessages": [            {              "property": "packages[0].items[0].hsCode",              "validationMessage": "Parameter hsCode must be between 4 and 11 characters long.",              "validationState": "Error"            }          ]        }      ]    }  },  "errors": [    {      "code": "IS_BLANK_ERROR",      "reference": "receiver.address.country",      "message": "This value should not be blank."    },    {      "code": "IS_BLANK_ERROR",      "reference": "receiver.address.city",      "message": "This value should not be blank."    },    {      "code": "MISSING_FIELD_ERROR",      "reference": "packages[EXMPL0001234-0-1][length]",      "message": "This field is missing."    }  ]}

Solicitar

Parámetro	Tipo	Descripción
orderReferenceId (obligatorio)	cadena	Identificador único para el pedido de envío. Identificador proporcionada por ti.
moneda (obligatorio)	cadena	Moneda del pedido de envío en formato de 3 letras.
Opciones (opcional)	Opciones	Parámetros opcionales.
Socio (opcional)	Compañero	Detalles del socio.
Método de envío (obligatorio)	Método de envío	Detalles del método de envío.
receptor (obligatorio)	Receptor	Detalles del destinatario.
Remitente (obligatorio)	Remitente	Detalles del remitente.
paquetes (obligatorio)	Paquete[]	Detalles del paquete.

Opciones

Parámetro	Tipo	Descripción
weightUnit (opcional)	cadena	Unidad de peso. Opciones disponibles: g, kg, oz, lb. Por defecto: g.
dimensionUnit (opcional)	cadena	Unidad de longitud. Opciones disponibles: mm, cm, in. Por defecto: mm.
Etiqueta (opcional)	Etiqueta	Configuración del formato de la etiqueta.

Etiqueta

Parámetro	Tipo	Descripción
formato (opcional)	cadena	Formato de etiqueta. Opciones disponibles: pdf, zpl (). Por defecto: pdf*.

Nota: Es posible que los formatos que no sean PDF no estén habilitados para determinados transportistas.

Compañero

Parámetro	Tipo	Descripción
Nombre del cliente (opcional)	cadena	Envío del perfil del cliente. Se utiliza para incluir un nombre de marca en la etiqueta (según las especificaciones del transportista).

Método de envío

Parámetro	Tipo	Descripción
uid (opcional)*	cadena	Para utilizar con un método de envío específico, por ejemplo, amazon_shipping_24.
Transportista (opcional)	cadena	Nombre de la empresa de transporte, por ejemplo, Amazon, DHL
Nivel (obligatorio)*	cadena	Nivel de opción de envío. Opciones disponibles: estándar, exprés. El nivel `standard` debe usarse cuando seleccionamos el método de envío `cheapest` para ti El nivel `express` debe usarse cuando seleccionamos el método de envío `más rápido` para ti

Nota: *Utiliza tier para la selección optimizada de transportistas de Gelato. Si utilizas tier, deja uid vacío y viceversa.

Receptor

Parámetro	Tipo	Descripción
persona (obligatorio)	ReceiverPerson	Datos personales del destinatario.
dirección (obligatorio)	Dirección	Detalles de la dirección del destinatario.
Aduanas (opcional)	Aduanas del destinatario	Detalles de aduanas del destinatario.

Remitente

Parámetro	Tipo	Descripción
persona (obligatorio)	SenderPerson	Detalles personales del remitente.
dirección (obligatorio)	Dirección	Detalles de la dirección del remitente.
Aduanas (requerido para envíos internacionales)	Aduanas del remitente	Detalles de aduanas del remitente.

ReceiverPerson

Parámetro	Tipo	Descripción
Nombre (obligatorio)	cadena	Nombre de pila de la persona receptora.
Apellido (obligatorio)	cadena	Apellido de la persona receptora.
empresa (opcional)	cadena	El título de la empresa.
Correo electrónico (opcional)*	cadena	Dirección de correo electrónico de la persona. Se puede utilizar para notificaciones de envío.
Teléfono (opcional)*	cadena	Número de teléfono de la persona. Se puede utilizar para notificaciones de envío.

Nota: *El correo electrónico y el teléfono pueden ser campos obligatorios según la empresa de transporte

SenderPerson

Parámetro	Tipo	Descripción
Nombre (opcional)	cadena	Nombre de pila de la persona remitente.
Apellido (opcional)	cadena	Apellido de la persona remitente.
empresa (obligatorio)	cadena	El título de la empresa remitente.
Correo electrónico (opcional)*	cadena	Dirección de correo electrónico de la persona o empresa remitente.
Teléfono (opcional)*	cadena	Número de teléfono de la persona o empresa remitente.

Nota: *El correo electrónico y el teléfono pueden ser campos obligatorios según la empresa de transporte

Dirección

Parámetro	Tipo	Descripción
país (obligatorio)	cadena	Código de país en formato de 2 letras.
Estado (opcional)*	cadena	Estado/condado/región.
ciudad (obligatorio)	cadena	Ciudad.
Código postal (obligatorio)	cadena	Código postal.
Dirección línea 1 (obligatorio)	cadena	Primera línea de la dirección postal. Debe incluir la calle y el número de la casa.
Dirección línea 2 (opcional)	cadena	Segunda línea de la dirección postal. Número de apartamento/oficina/piso.
Dirección línea 3 (opcional)	cadena	Tercera línea de la dirección postal.
calle (opcional)*	cadena	Calle (obligatorio para direcciones de Alemania).
Número de casa (opcional)*	cadena	Número de casa (obligatorio para direcciones de Alemania).
Suburbio (opcional)*	cadena	Suburb (obligatorio para direcciones de AU/NZ).

Nota: *Estos campos opcionales son obligatorios para determinados países y transportistas.

Aduanas del destinatario

Parámetro	Tipo	Descripción
Número de IVA (opcional)	cadena	Número de IVA del receptor.

Aduanas del remitente

Parámetro	Tipo	Descripción
Número de IVA (opcional)*	cadena	Número de IVA del remitente.
Número IOSS (opcional)*	cadena	Número IOSS del remitente.
Número EORI (opcional)*	cadena	Número EORI del remitente.
pcccNumber (opcional)*	cadena	Número PCCC del remitente.
australianBusinessNumber (opcional)*	cadena	Número de empresa australiano del remitente.

Nota: *Dependiendo del país del remitente y del destinatario, estos campos pueden ser obligatorios.

Paquete

Parámetro	Tipo	Descripción
packageReferenceId (obligatorio)	cadena	Identificador del paquete proporcionado por el socio.
Peso bruto (obligatorio)	número	Peso del embalaje + peso de los artículos (en gramos por defecto).
netWeight (opcional)	número	Peso de los artículos (en gramos de forma predeterminada).
Longitud (obligatorio)	número	Longitud del paquete (en mm por defecto).
Ancho (obligatorio)	número	Ancho del paquete (en mm por defecto).
altura (obligatorio)	número	Altura del paquete (en mm por defecto).
volumetricWeight (opcional)	número	Peso calculado en función del tamaño del paquete (en gramos de forma predeterminada).
Tipo de caja (opcional)	cadena	Forma de la caja (por ejemplo, rectángulo, tubo).
valor (obligatorio para envíos internacionales)	número	Valor total de todos los artículos del paquete (en la divisa seleccionada).
artículos (obligatorio para envíos internacionales)	Artículo[]	Lista de artículos del paquete.

Artículo*

Parámetro	Tipo	Descripción
itemReferenceId (obligatorio)	cadena	Identificador del artículo del paquete proporcionado por el socio.
Descripción (obligatorio)	cadena	Descripción del artículo.
Cantidad (obligatorio)	número	Cantidad del artículo.
valor (obligatorio)	número	Valor del artículo (en la divisa seleccionada).
peso (obligatorio)	número	Peso del artículo (en gramos por defecto).
hsCode (obligatorio)	cadena	Código del Sistema Armonizado (Wiki).
countryOfOrigin (obligatorio)	cadena	Código de país en formato de 2 letras donde se produjo el artículo.

Nota: *Todos los parámetros del artículo solo son necesarios para el envío internacional.

Respuesta satisfactoria

Parámetro	Tipo	Descripción
orderId	cadena	Identificador único del pedido de envío en nuestro sistema.
ID de referencia de pedido	cadena	Identificador único del pedido de envío proporcionado por ti.
Método de envío	Método de envío de respuesta	Método de envío utilizado para el pedido de envío.
Paquetes	ResponsePackage[]	Paquetes utilizados para el pedido de envío.

Método de envío de respuesta

Parámetro	Tipo	Descripción
transportista	cadena	Transportista utilizado para crear un pedido.
uid	cadena	UID del método de envío utilizado para crear un pedido.

ResponsePackage

Parámetro	Tipo	Descripción
packageReferenceId	cadena	Identificador del paquete proporcionado por el socio.
Número de seguimiento	cadena	Número de seguimiento proporcionado por la empresa de transporte.
trackingUrl	cadena	URL de seguimiento proporcionada por la empresa de transporte.
etiqueta	Etiqueta de respuesta	Etiqueta de envío para el pedido de envío.
Documentos (opcional)	ResponseDocument[]	Documentos para el pedido de envío.
totalCost (opcional)	Coste total de la respuesta	Coste estimado del envío del paquete.

Etiqueta de respuesta

Parámetro	Tipo	Descripción
fileName	cadena	Nombre del archivo de la etiqueta.
fileUrl	cadena	URL para descargar la etiqueta.
Tipo de contenido	cadena	Tipo de contenido de la etiqueta.

ResponseDocument

Parámetro	Tipo	Descripción
documentType	cadena	Tipo de documento (por ejemplo, factura).
fileName	cadena	Nombre del archivo del documento.
fileUrl	cadena	URL para descargar el documento.
Tipo de contenido	cadena	Tipo de contenido del documento.

ResponseTotalCost

Parámetro	Tipo	Descripción
valor (opcional)	número	Coste estimado del envío del paquete. (opcional)
moneda (opcional)	cadena	Moneda

Respuesta de error

Parámetro	Tipo	Descripción
ID de referencia de pedido	cadena	Identificador único del pedido de envío proporcionado por ti.
código	cadena	Código de error.
mensaje	cadena	Mensaje de error.
detalle (opcional)	objeto	Mensaje de error detallado (objeto JSON de una estructura arbitraria ).
Errores (opcional)	ResponseErrorDetails[]	Lista de errores.

Detalles del error de respuesta

Parámetro	Tipo	Descripción
código	cadena	Código de error.
mensaje	cadena	Mensaje de error
Referencia (opcional)	cadena	ID de referencia.

Siguiente paso: 🔗[GCL] API de logística: crear borrador de pedido de envío

📝 ¿No era esto lo que buscabas?

Ayúdanos a mejorar este artículo, envíanos un correo a [email protected] — por favor, incluye el título del artículo.

[GCL] API de logística: creación de pedido de envío