Envíos | Conector de Redes

Consulta antes de crear

Obtén las conexiones disponibles y consulta los artículos de la conexión elegida. Esa respuesta contiene las opciones, cobertura, pesos, dimensiones y datos obligatorios aplicables a tu contrato. Revisá code_system: si indica connection_service_code, usá el código propio publicado para esa conexión, no un artículo del catálogo global.

Scope shipments:write para crear.
Scope shipments:read para consultar el resultado.
Una clave de idempotencia estable por intención de envío.

POST/v1/shipments

shipments:write

Crear un envío

Genera una clave entre 8 y 128 caracteres y reutilízala únicamente para reintentos de la misma petición.

Solicitud cURL

curl --request POST \
  --url "$API_BASE_URL/v1/shipments" \
  --header "Authorization: Bearer $SENDINGBAY_API_TOKEN" \
  --header "Idempotency-Key: pedido-9842-envio-1" \
  --header "Content-Type: application/json" \
  --data '{
    "carrier_connection_id": "11111111-1111-4111-8111-111111111111",
    "article_code": "24",
    "option_codes": ["SATURDAY_DELIVERY"],
    "origin_code": "WAREHOUSE_MADRID",
    "sender": {
      "name": "Tienda de prueba",
      "address_line1": "Calle Origen 1",
      "city": "Madrid",
      "postal_code": "28001",
      "country_code": "ES",
      "phone": "600000001"
    },
    "recipient": {
      "name": "Cliente de prueba",
      "address_line1": "Calle Destino 1",
      "city": "Madrid",
      "postal_code": "28002",
      "country_code": "ES",
      "phone": "600000002"
    },
    "packages": [{
      "weight_kg": 1.25,
      "length_cm": 20,
      "width_cm": 15,
      "height_cm": 10
    }],
    "shipping_date": "2026-09-10",
    "external_reference": "PED-9842"
  }'

Campo	Obligatorio	Uso
`carrier_connection_id`	Sí	UUID de una conexión activa del cliente.
`article_code`	Sí	Código publicado para la conexión: canónico o propio según code_system.
`recipient`	Sí	Nombre, dirección, ciudad, código postal y país ISO de dos letras.
`packages`	Sí	Entre 1 y 100 bultos; cada uno necesita weight_kg.
`sender`	Según red	Remitente completo. Algunas redes lo exigen aunque sea opcional en el contrato común.
`option_codes`	No	Hasta 20 opciones canónicas habilitadas para artículo y conexión.
`origin_code`	No	Origen técnico habilitado; nunca sustituye a sender.
`shipping_date`	Según red	Fecha de expedición en formato YYYY-MM-DD.
`external_reference`	Según red	Referencia propia del cliente, con un máximo de 100 caracteres.

Interpretar el resultado

Un alta nueva responde con 201. El estado puede sercreated o accepted; en una operación asíncrona, el tracking y la etiqueta pueden ser nulos hasta la conciliación.

Respuesta de ejemplo

HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replayed: false
X-Correlation-ID: 45b026cb-80e3-4f1e-a565-84422192f503

{
  "id": "274a2a5d-fef4-4fc6-9057-39d8df258367",
  "carrier_connection_id": "11111111-1111-4111-8111-111111111111",
  "carrier_code": "MOCK",
  "carrier_reference": "MOCK-9842",
  "tracking_number": "TRACK-9842",
  "status": "created",
  "article_code": "24",
  "article_mapping_version": 1,
  "option_codes": ["SATURDAY_DELIVERY"],
  "origin_code": "WAREHOUSE_MADRID",
  "external_reference": "PED-9842",
  "label": {
    "format": "ZPL",
    "content_base64": "XlhBXkZPNTAsNTBeRkQ..."
  },
  "created_at": "2026-09-10T10:30:00Z"
}

HTTP	Resultado	Acción
`201`	Alta nueva	Conserva el id del envío y revisa status, tracking_number y label.
`200`	Resultado reproducido	La misma intención ya terminó; Idempotent-Replayed vale true.
`409`	Clave en conflicto o en curso	Actúa según el code y conserva la misma clave.
`422`	Petición corregible	Corrige campos, artículo, opciones, origen o restricciones.
`503`	Servicio no disponible o resultado incierto	No repitas a ciegas; consulta la guía de errores.

GET/v1/shipments/{shipment_id}

shipments:read

Consultar un envío

Usa el id del Conector, no la referencia del transportista ni tu external_reference. Un envío inexistente o de otro cliente devuelve el mismo shipment_not_found.

Solicitud cURL

curl --request GET \
  --url "$API_BASE_URL/v1/shipments/274a2a5d-fef4-4fc6-9057-39d8df258367" \
  --header "Authorization: Bearer $SENDINGBAY_API_TOKEN"

Siguiente lectura

Cómo reintentar sin duplicar una expedición.

Ir a idempotencia →