Preguntas frecuentes sobre las API de Sendcloud

Tema: Preguntas frecuentes relacionadas con las integraciones de tiendas personalizadas que utilizan las API de Sendcloud.

¿Cuáles son los límites de nuestra API?

Límites de solicitudes de la API

Nuestra API tiene límites de velocidad que limitan el número de solicitudes que se pueden hacer por minuto. Ten en cuenta que hay diferentes límites para los endpoints relacionados con los envíos.

• Safe requests (solicitudes seguras) (GET): 1000 solicitudes por minuto.
• Unsafe requests (solicitudes no seguras) (POST/PATCH/PUT/DELETE): 100 solicitudes por minuto.
• Shipping-related safe requests (solicitudes seguras relacionadas con los envíos) (GET): 420 solicitudes por minuto.
• Shipping-related unsafe requests (solicitudes no seguras relacionadas con los envíos) (POST/PATCH/PUT/DELETE): 100 solicitudes por minuto.

Límite de ráfaga (maximum burst)

Los endpoints que se consideran "no seguros" tienen un límite de ráfaga establecido, que es el número máximo de solicitudes simultáneas que puede gestionar la API. Permite un aumento temporal de la cuota de solicitudes para acomodar periodos cortos de alto tráfico sin exceder los límites generales.

• Unsafe requests (solicitudes no seguras) (POST/PATCH/PUT/DELETE): 15 solicitudes por segundo
• Shipping-related unsafe requests (solicitudes no seguras relacionadas con los envíos) (POST/PATCH/PUT/DELETE): 15 solicitudes por segundo.

Lee más sobre la limitación de velocidad en nuestra documentación para desarrolladores.

Sendcloud se reserva el derecho a realizar cambios.

¿Cómo puedo utilizar la API de Sendcloud de forma eficiente?

Hay varias formas de hacer un uso eficiente de nuestra API. Por ejemplo, puedes crear Paquetes en masa, obtener Paquetes recién actualizados utilizando el parámetro updated_after o utilizar webhooks para recibir actualizaciones directamente en tu sistema.

Haz anuncios en masa en paralelo a nuestra API, en tandas más pequeñas. Para anunciar 100 paquetes podrías hacer 5 x series de 20 llamadas en paralelo a nuestra API.

Quiero crear etiquetas automáticamente cuando cree un paquete a través de la API. ¿Cómo puedo hacerlo? 

Para crear paquetes y etiquetas de envío en una sola llamada a la API, establece el campo request_label en 'true' en la solicitud al endpoint Crear un paquete. Este proceso se explica con más detalle en nuestra documentación. 

¿Cómo puedo mantener la idempotencia de los pedidos/envíos que importo o creo en Sendcloud?

En el contexto de las API, la idempotencia se refiere a cuando realizar varias solicitudes tiene el mismo efecto que una única solicitud. Esto se hace para evitar errores de usuario y, en el caso de las API de Sendcloud, la duplicación de pedidos en nuestro sistema. Hay dos puntos finales (endpoints) que intentan ser idempotentes:

• Actualiza un paquete
  Utiliza el campo external_reference para mantener la idempotencia.

• Crear/actualizar una lista de envíos
  Este es un punto final UPSERT, lo que significa que, si se comprueba que un envío ya existe en la base de datos de Sendcloud, se actualizará el envío. Si no hay ninguna coincidencia, se creará en su lugar. Para mantener la idempotencia has de utilizar una combinación de los campos external_order_id y external_shipment_id. Solo se actualizarán los envíos en los que se haya modificado el timestamp updated_at (ISO 8601 DateTime).

¿Por qué sender_address es un campo obligatorio al crear etiquetas a través de la API?

Los transportistas exigen que haya una dirección del remitente en cada etiqueta de envío para identificar de dónde procede cada paquete. Si no se especifica una dirección de remitente al crear un paquete a través de la API, se utilizará tu dirección predeterminada (la guardada en tu cuenta de Sendcloud) para imprimir la etiqueta. En nuestra documentación explicamos con más detalle cómo obtener un ID de dirección de remitente y la relación entre direcciones de remitente, etiquetas y marcas. 

¿Puedo utilizar reglas de envío cuando creo paquetes a través de la API?

Las reglas de envío se aplicarán a los paquetes que crees a través de tu panel de Sendcloud, siempre que el campo apply_shipping_rulesesté configurado como true. Te recomendamos que utilices el método de envío "Unstamped letter" para crear tus paquetes si quieres que las reglas de envío se apliquen correctamente. Esto te permitirá omitir los campos obligatorios de shipping_method. De este modo, cualquier regla que hayas configurado que afecte a la selección del método de envío se aplicará correctamente a tu paquete.

¿Puedo probar la API sin que me cobren por las etiquetas que cree?

Puedes utilizar el método de envío "Unstamped letter" de Sendcloud para crear tus paquetes. Esto te permite probar la API sin correr el riesgo de que se te cobre por las etiquetas que crees.

Ten en cuenta que no es posible utilizar este método para probar la creación de etiquetas de devolución. Para probar las etiquetas de devolución, utiliza un método de envío que admita solicitudes de cancelación de Sendcloud y cancela la etiqueta antes de las 23:59 del día de creación. Consulta nuestra documentación sobre etiquetas de prueba para más información. 

Recibo el mensaje de error “User is not allowed to announce”. ¿Qué está fallando?

Asegúrate de que has seguido todos los pasos de la configuración básica de la cuenta y has activado un método de pago por domiciliación bancaria. Ver: Bienvenido a Sendcloud.

¿Puedo ver todos mis métodos de envío a través de la API cuando conecto un contrato directo con un transportista?

Sí, si has conectado tu propio contrato con un transportista, podrás recuperar tus propios métodos junto con los métodos de Sendcloud a través de una solicitud GET al punto final Retrieve a list of shipping methods. Ten en cuenta que los precios de tu contrato no se recuperarán a menos que hayas subido los precios. 

¿Puedo ver los precios de mis contratos directos con los transportistas cuando utilizo la API para comprobar tarifas y comparar métodos?

Sí, si has subido tus propios precios a tu cuenta de Sendcloud siguiendo los pasos de este artículo.  

Recibo el mensaje de error "Invalid shipment ID" cuando intento crear un paquete a través de la API. ¿Qué está fallando?

Es probable que el shipping_method_idque estás utilizando se refiera a un método que no admite envíos a o desde la dirección indicada, por ejemplo, si estás utilizando un método nacional para un envío internacional. También puede ser que estés intentando utilizar un método de devolución para un envío saliente, o viceversa. Puedes utilizar el endpoint "Shipping products" para encontrar un método adecuado para tu paquete en función de los parámetros que definas en la solicitud.

Por último, asegúrate de que el nombre del método de envío sigue correspondiendo al método que quieres utilizar. Los nombres de método de envío de nuestra base de datos son volátiles y no deberían guardarse en caché durante más de una hora. 

He creado correctamente una solicitud de paquete, pero el paquete no aparece en mi cuenta de Sendcloud. ¿Qué está fallando?

Es probable que la solicitud no haya incluido un valor para el campo "booleano" request_label.

• Cuando este campo es true, la etiqueta se imprimirá junto a la solicitud para crear un paquete, y el paquete aparecerá en la pestaña Etiquetas creadas en Sendcloud.
• Cuando el valor es false, el objeto paquete se crea, pero aparecerá en la vista general de pedidos recibidos, a la espera de ser procesado.
• Si no has añadido un valor, puedes utilizar el endpoint Actualizar un paquete para cambiar el campo request_label a true or false. Puedes encontrar el identificador único del paquete (que necesitarás en tu solicitud) a través del punto final Recuperar todos los paquetes. 

¿La API admite la importación de notas o campos de observaciones en los pedidos?

Sí. Por ejemplo, esto podría utilizarse para añadir notas a los pedidos, como "Por favor, envuelve este artículo para regalo". También aparecerán en los albaranes o listas de recogida si utilizas Pack & Go. 

He creado un informe desde la API, pero mi archivo CSV está en blanco. ¿Qué ocurre?

Ten en cuenta el filtro direction cuando crees la solicitud al endpoint de informes. Si especificas la direction como incoming, solo verás los paquetes de retorno. Si no tienes ningún paquete de devolución entrante, el informe estará vacío.

En segundo lugar, tendrás que especificar el ID de integración en tu solicitud. No es posible crear un informe para todas tus integraciones juntas, así que asegúrate de especificar el ID correcto para ver tus paquetes salientes o entrantes por integración. 

¿Cómo puedo encontrar mi integration_id?

Puedes encontrar tu integration_id a través del endpoint Recuperar una lista de integraciones, o desde tu panel de Sendcloud (Configuración > Integraciones > encuentra tu integración en la lista > Editar). El ID de integración aparecerá al final de la URL, por ejemplo 'https://app.sendcloud.com/v2/settings/integrations/api/95977'.

¿Cómo puedo encontrar mi sender_address_id? 

A través del endpoint Recuperar una lista de direcciones de remitente, o desde tu panel de Sendcloud (Configuración > Direcciones > Editar una dirección). El ID aparecerá al final de la URL, por ejemplo 'https://app.sendcloud.com/v2/settings/addresses/sender/132258'.

¿Cómo puedo encontrar mi brand_id?

A través del endpoint Recuperar marcas configuradas, o en tu panel de Sendcloud (Configuración > Marcas > Editar una marca). El ID se mostrará al final de la URL, por ejemplo "https://app.sendcloud.com/v2/settings/brands/86054".

Recibo el mensaje de error "Service point delivery is not enabled for this integration". ¿Qué está fallando?

Tienes que activar la entrega de puntos de servicio en el panel de Sendcloud, yendo a Configuración > Integraciones > API > Editar > Marca la casilla para activar la entrega de puntos de servicio. Esto se describe con más detalle aquí. 

No veo los métodos de todos los transportistas cuando realizo una solicitud GET para recuperar una lista de métodos de envío.

En primer lugar, comprueba que has habilitado todos los transportistas que deseas utilizar yendo a Envios > Transportistas en tu cuenta de Sendcloud. Utiliza el menú desplegable para seleccionar más transportistas por cada uno de los países en los que tengas una dirección de remitente activa.

En segundo lugar, tendrás que especificar una de tus direcciones de remitente en tu llamada API a los puntos finales de Métodos de envío para ver los métodos para países distintos del país de tu dirección de remitente predeterminada. Por ejemplo, si tu dirección de remitente predeterminada está en España, pero quieres ver métodos de Royal Mail (Reino Unido), tendrás que especificar el ID de dirección de remitente de tu dirección de remitente de Reino Unido para recuperar los métodos aplicables en ese país. Esto se explica con más detalle en nuestra documentación. 

Los números de casa se duplican en mis etiquetas de envío cuando creo paquetes a través de la API. ¿Qué ocurre?

El formato de dirección más utilizado es el siguiente:

• address : Calle de Salamanca
• house_number: 10

Otro formato común es

• address: Calle de Salamanca 10

¿Puedo crear envíos multibulto (multicollo) a través de la API?

Sí, puedes; esto se describe con más detalle en nuestra documentación. 

¿Puedo asignar la misma marca a varias direcciones de remitente?

Sí, puedes asignar la misma marca a varias o a todas tus direcciones de remitente.

¿Puedo asignar varias marcas a la misma dirección de remitente?

Solo se puede asignar una marca por dirección de remitente. La solución es crear una dirección de remitente duplicada y asignar una marca diferente a cada una. Solo se puede especificar una como dirección predeterminada, por lo que recomendamos dar un nombre fácil de distinguir a la duplicada para que así puedas identificarla más fácilmente en el panel.

¿Puedo crear envíos internacionales a través de la API?

Sí, absolutamente. Tus documentos aduaneros se generarán automáticamente, siempre que los campos obligatorios (ver más abajo) se especifiquen correctamente para cada producto incluido en el envío. Esto se explica con más detalle en nuestra documentación: Envíos internacionales.

¿Qué campos son obligatorios para realizar envíos internacionales?

• customs_invoice_number
• customs_shipment_type
• country_state(Solo para Australia, Canadá, Italia y EE.UU.)
• parcel_items
  • origin_country (ISO 2) 
  • hs_code

Artículos y recursos relacionados

→ Documentación de la API y Guía de inicio rápido

→ Guía de referencia de la API de Sendcloud

→ Portal de desarrolladores de Sendcloud

→ Puntos de servicio para las integraciones API