Crear Orden con Etiqueta Previa

Crea un nuevo orden de fulfillment proporcionando una etiqueta de envío creada previamente. Este endpoint también permite adjuntar archivos relacionados con la orden en formato PDF que serán incluidos en el envío.

Formato de Solicitud

Este endpoint usa multipart/form-data en lugar de JSON. Asegúrate de configurar correctamente tu cliente HTTP.

POST/shipment/create_with_label

Este endpoint te permite crear un nuevo orden de fulfillment proporcionando una etiqueta de envío creada previamente. Debes incluir el token Bearer obtenido anteriormente en el encabezado de la solicitud.

Encabezados

Parámetro	Tipo	Requerido	Descripción
Authorization	string	✅ Sí	Token Bearer obtenido del endpoint /token/generate
Content-Type	string	✅ Sí	Debe ser multipart/form-data
Accept	string	✅ Sí	Debe ser application/json

Parámetros del Body

Parámetro	Tipo	Requerido	Descripción
cod	boolean	✅ Sí	Define si la orden es COD (contra entrega) o regular
unique_order_number	string	✅ Sí	Código de identificación proporcionado por el vendedor (máx: 12)
invoice	string	❌ No	Define el número de factura para la orden (máx: 45)
shipping_service	string	✅ Sí	Nombre del servicio de envío con el que se generó previamente la etiqueta (máx: 20)
warehouse_id	integer	✅ Sí	El ID del almacén desde el cual se surtirá la orden (máx: 10)
shipment_number	string	✅ Sí	Número de guía para la orden proporcionado por el servicio de envío (máx: 45)
label	file	✅ Sí	Archivo PNG de la guía proporcionado por el servicio de envío (máx. 3MB)
consignee_name	string	✅ Sí	Nombre del cliente (máx: 70)
consignee_country	string	✅ Sí	País de origen del cliente, será México por defecto (máx: 20)
consignee_state	string	✅ Sí	Ciudad/estado de residencia del cliente (máx: 45)
consignee_municipality	string	✅ Sí	Dirección del municipio del cliente (máx: 35)
consignee_neighborhood	string	❌ No	Dirección de la colonia del cliente (máx: 35)
consignee_street	string	✅ Sí	Dirección de la calle del cliente (máx: 25)
consignee_external_number	string	✅ Sí	Número exterior del departamento o casa del cliente (máx: 5)
consignee_internal_number	string	❌ No	Número interior del departamento o casa del cliente (máx: 5)
consignee_zipcode	string	✅ Sí	Código postal del cliente (máx: 10)
consignee_email	string	❌ No	Email del cliente (máx: 80)
consignee_phone	string	❌ No	Teléfono del cliente (máx: 15)
consignee_comments	string	❌ No	Comentarios del cliente sobre la orden (máx: 80)
order_details	string	✅ Sí	En este campo se agregará un JSON en formato STRING con los detalles de la orden
total_price	float	✅ Sí	Precio total de la orden, se debe ingresar el monto total del envío (máx: 5)
attached_files[]	array	❌ No	Un arreglo de archivos relacionados con la orden en formato PDF (máx. 5 archivos)

Ejemplos

cURL

curl -X POST https://apisandbox.eonwms.com/shipment/create_with_label \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-F "cod=false" \
-F "unique_order_number=TESTORDER02" \
-F "invoice=invoice01" \
-F "shipping_service=FEDEX" \
-F "warehouse_id=1" \
-F "shipment_number=0000000001" \
-F "label=@/ruta/a/tu/etiqueta.png" \
-F "consignee_name=CLIENTE PRUEBA" \
-F "consignee_country=Mexico" \
-F "consignee_state=Ciudad de Mexico" \
-F "consignee_municipality=Benito Juarez" \
-F "consignee_neighborhood=Del Valle" \
-F "consignee_street=Insurgentes Sur" \
-F "consignee_external_number=100" \
-F "consignee_internal_number=" \
-F "consignee_zipcode=03100" \
-F "consignee_email=test@test.com" \
-F "consignee_phone=5555555555" \
-F "consignee_comments=Entregar en recepción" \
-F 'order_details=[{"quantity":1,"sku":"PRODUCTO01","unit_price":100.0}]' \
-F "total_price=100.0" \
-F "attached_files[]=@/ruta/a/factura.pdf"

JavaScript

// Crear FormData para multipart/form-data
const formData = new FormData();

// Agregar campos básicos
formData.append('cod', 'false');
formData.append('unique_order_number', 'TESTORDER02');
formData.append('invoice', 'invoice01');
formData.append('shipping_service', 'FEDEX');
formData.append('warehouse_id', '1');
formData.append('shipment_number', '0000000001');

// Agregar archivo de etiqueta
const labelFile = document.getElementById('labelInput').files[0];
formData.append('label', labelFile);

// Agregar datos del destinatario
formData.append('consignee_name', 'CLIENTE PRUEBA');
formData.append('consignee_country', 'Mexico');
formData.append('consignee_state', 'Ciudad de Mexico');
formData.append('consignee_municipality', 'Benito Juarez');
formData.append('consignee_neighborhood', 'Del Valle');
formData.append('consignee_street', 'Insurgentes Sur');
formData.append('consignee_external_number', '100');
formData.append('consignee_internal_number', '');
formData.append('consignee_zipcode', '03100');
formData.append('consignee_email', 'test@test.com');
formData.append('consignee_phone', '5555555555');
formData.append('consignee_comments', 'Entregar en recepción');

// Agregar detalles de la orden como STRING
const orderDetails = JSON.stringify([
{
  quantity: 1,
  sku: 'PRODUCTO01',
  unit_price: 100.0
}
]);
formData.append('order_details', orderDetails);
formData.append('total_price', '100.0');

// Agregar archivos adjuntos (opcional)
const attachedFile = document.getElementById('attachmentInput').files[0];
if (attachedFile) {
formData.append('attached_files[]', attachedFile);
}

// Enviar solicitud
const response = await fetch('https://apisandbox.eonwms.com/shipment/create_with_label', {
method: 'POST',
headers: {
  'Authorization': 'Bearer TU_TOKEN',
  'Accept': 'application/json'
},
body: formData
});

const result = await response.json();

Python

import requests

# Preparar archivos
files = {
  'label': ('etiqueta.png', open('/ruta/a/tu/etiqueta.png', 'rb'), 'image/png'),
  'attached_files[]': ('factura.pdf', open('/ruta/a/factura.pdf', 'rb'), 'application/pdf')
}

# Preparar datos del formulario
data = {
  'cod': 'false',
  'unique_order_number': 'TESTORDER02',
  'invoice': 'invoice01',
  'shipping_service': 'FEDEX',
  'warehouse_id': '1',
  'shipment_number': '0000000001',
  'consignee_name': 'CLIENTE PRUEBA',
  'consignee_country': 'Mexico',
  'consignee_state': 'Ciudad de Mexico',
  'consignee_municipality': 'Benito Juarez',
  'consignee_neighborhood': 'Del Valle',
  'consignee_street': 'Insurgentes Sur',
  'consignee_external_number': '100',
  'consignee_internal_number': '',
  'consignee_zipcode': '03100',
  'consignee_email': 'test@test.com',
  'consignee_phone': '5555555555',
  'consignee_comments': 'Entregar en recepción',
  'order_details': '[{"quantity":1,"sku":"PRODUCTO01","unit_price":100.0}]',
  'total_price': '100.0'
}

# Enviar solicitud
response = requests.post(
  'https://apisandbox.eonwms.com/shipment/create_with_label',
  headers={
      'Authorization': 'Bearer TU_TOKEN',
      'Accept': 'application/json'
  },
  data=data,
  files=files
)

# Cerrar archivos
files['label'][1].close()
files['attached_files[]'][1].close()

result = response.json()

Respuestas

200Éxito - Orden creado con etiqueta

{
"status": "PLACED",
"message": "la orden ha sido creado con la etiqueta proporcionada"
}

401No autorizado - Token inválido

{
"v": "EON_V2.0",
"fault": {
  "arguments": {
    "Authorization": "invalid"
  },
  "type": "InvalidAuthorizationException",
  "message": "La solicitud no está autorizada, el token de acceso es inválido."
}
}

422Entidad no procesable - Error de validación

{
"fault": {
  "error": "invalid_label",
  "error_description": "El archivo de etiqueta no es válido o excede el tamaño máximo"
}
}

Consideraciones Importantes

Formato de order_details

El campo order_details debe ser un JSON válido pero enviado como STRING. Ejemplo:

"[{\"quantity\":1,\"sku\":\"PRODUCTO01\",\"unit_price\":100.0}]"

Archivos Adjuntos

• La etiqueta debe ser en formato PNG con un tamaño máximo de 3MB
• Los archivos adjuntos deben ser PDF
• Puedes adjuntar hasta 5 archivos PDF adicionales
• Los archivos adjuntos serán incluidos físicamente en el paquete

Diferencias con el endpoint regular

Este endpoint es útil cuando:

• Ya tienes una etiqueta generada por el transportista
• Necesitas incluir documentos físicos en el envío
• Manejas tu propia integración con transportistas

Ejemplo de Caso de Uso

Este endpoint es ideal para situaciones donde:

1. Integración directa con transportistas: Ya tienes una cuenta directa con FedEx, UPS, etc., y generas tus propias etiquetas
2. Documentación especial: Necesitas incluir facturas, permisos o documentación aduanal física
3. Reenvíos: Cuando necesitas usar una etiqueta previamente generada para un reenvío

Validaciones

• El número de guía (shipment_number) debe ser único
• La etiqueta debe ser legible y en formato PNG
• El servicio de envío debe coincidir con el transportista de la etiqueta
• Los archivos PDF no deben exceder 5MB cada uno