Ship.com

Conecta asistentes de IA a Ship.com para gestionar pedidos, comparar tarifas, comprar etiquetas, programar recogidas, administrar clientes y obtener informes de envío.

Ver en ship.com

Servidor MCP alojado

npx add-mcp 'https://app.ship.com/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

Servidor MCP de Ship.com

El servidor MCP de Ship.com permite que asistentes de IA y agentes trabajen con tu cuenta de Ship.com: consultar pedidos, comparar tarifas, comprar etiquetas, programar recogidas y más. Esta referencia cubre cómo conectar cualquier cliente MCP, cómo funciona la autenticación y todas las herramientas que ofrece el servidor.

Descripción general

El servidor MCP de Ship.com brinda a asistentes de IA, IDE y tu propio código acceso a una cuenta de Ship.com a través del Model Context Protocol. Ofrece herramientas para leer y crear pedidos, comparar tarifas, comprar y anular etiquetas, programar recogidas de transportistas, gestionar clientes, enviar correos electrónicos a clientes y obtener informes comerciales. Cada llamada se ejecuta bajo las mismas reglas de cuenta, saldos y controles de seguridad que la aplicación web de Ship.com.

Esta página es la referencia neutral respecto al cliente. Para la configuración paso a paso en Claude, consulta Conectar Claude a Ship.com.

Endpoint	`https://app.ship.com/mcp`
Transporte	MCP Streamable HTTP. Envía cada solicitud JSON-RPC 2.0 como un cuerpo `POST`; cada respuesta JSON-RPC es un único objeto `application/json` (las notificaciones reciben HTTP 202 sin cuerpo). El servidor no transmite en streaming y nunca envía eventos del servidor.
Versiones de protocolo	`2025-11-25` (predeterminada) y `2025-06-18`
Métodos	`initialize`, `ping`, `tools/list`, `tools/call`
Nombre del servidor	`ship-com`

Quién puede usarlo

El acceso MCP está incluido en todos los planes de Ship.com, incluida la prueba gratuita; no existe un plan MCP separado. Necesitas un inicio de sesión de Ship.com y una de las dos credenciales siguientes. Algunas herramientas también dependen de tu plan: la programación de recogidas de transportistas, la compra de etiquetas por lotes, los informes comerciales y el correo electrónico a clientes requieren un plan que incluya esa función. Esas herramientas siguen apareciendo listadas, y una llamada explica claramente cuando tu plan no las incluye. Consulta Características del plan.

Dos formas de conectarse

	Token de acceso	Inicio de sesión OAuth
Funciona con	Cualquier cliente MCP que pueda enviar un encabezado de solicitud: Claude Code, la API de Claude, Cursor, VS Code, Windsurf, scripts y plataformas de automatización	Aplicaciones web, de escritorio y móviles de Claude (conector personalizado o el directorio de Claude), y Claude Code cuando inicia sesión en lugar de usar un encabezado
Cómo autentica	Encabezado `Authorization: Bearer` con tu token de acceso de Ship.com, copiado desde Configuración	OAuth 2.1 con PKCE. Inicias sesión en Ship.com y apruebas la aplicación
Duración de la credencial	180 días	Tokens de acceso de 24 horas, renovados automáticamente. La aplicación permanece conectada mientras se renueve al menos una vez cada 180 días
Herramientas	40, el catálogo completo	38
Compra de etiquetas	Sí: buy_label y trigger_batch_purchase	No se ofrece. Tarifas, cotizaciones, anulaciones, pedidos y recogidas funcionan
Revocar	Reemplaza el token desde Configuración	Desconecta la aplicación en Aplicaciones conectadas en Configuración

Compra de etiquetas. Las conexiones realizadas mediante inicio de sesión OAuth, incluido el conector del directorio de Claude y los conectores personalizados de claude.ai, no ofrecen compra de etiquetas. Aún pueden cotizar tarifas, anular etiquetas, gestionar pedidos y clientes, y reservar recogidas. Las dos herramientas de compra de etiquetas se ofrecen solo en conexiones que se autentican con un token de acceso de Ship.com. El inicio de sesión OAuth de Ship.com actualmente acepta solo clientes de Claude, por lo que otras herramientas se conectan con un token de acceso. Los detalles están en Autenticación.

Inicio rápido

1. Obtén tu token de acceso.

Inicia sesión en app.ship.com, abre Configuración y elige la pestaña Integración de API. También puedes hacer clic en MCP en la barra lateral izquierda.
Busca la tarjeta Conecta Ship.com a tu asistente de IA. En Conectar desde otra herramienta, haz clic en Mostrar mi clave de conexión. La tarjeta muestra la URL del servidor y un valor de Encabezado, Authorization: Bearer seguido de tu token. Ship.com llama a este token tu clave de conexión.
Para Claude Code, ve a Conectar desde Claude en su lugar, haz clic en ¿Prefieres Claude Code o la terminal? Usa una clave de conexión en su lugar y luego Generar clave de conexión. La tarjeta muestra un comando listo para ejecutar con tu token incluido.

La tarjeta muestra cuándo expira el token ("Conexión válida hasta..."). Hacer clic en cualquiera de los botones nuevamente devuelve el mismo token mientras siga siendo válido, por lo que nunca rompe un cliente que ya hayas configurado. Trata el token como una contraseña: cualquiera que lo tenga puede actuar en tu cuenta.

2. Agrega Ship.com a tu cliente. Usa la configuración para tu herramienta a continuación y reemplaza YOUR_TOKEN solo con el token: la parte del valor de Encabezado de la tarjeta después de Bearer , que comienza con OAUTH2.. Si pegas todo el valor del Encabezado (incluido Authorization: Bearer) en un campo de encabezado, el servidor responde 401 invalid_token.

3. Pruébalo. Envía un pedido de principio a fin te guía a través de un primer pedido, desde la tarifa hasta la recogida.

Claude Code

Ejecuta el comando desde tu tarjeta de Configuración, o este con tu token completado:

claude mcp add --transport http shipcom https://app.ship.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

Mantén la parte --header para que Claude Code use tu token de acceso. Sin ella, Claude Code inicia sesión mediante OAuth y obtiene el conjunto de herramientas OAuth (consulta Herramientas por tipo de conexión).

Agrega --scope user para que Ship.com esté disponible en todos los proyectos. Sin ella, el servidor se agrega solo al proyecto actual.

Cursor

Agrega Ship.com a ~/.cursor/mcp.json (todos los proyectos) o .cursor/mcp.json en un proyecto. Este ejemplo lee el token de una variable de entorno SHIPCOM_TOKEN para que no quede en el archivo:

{
  "mcpServers": {
    "shipcom": {
      "url": "https://app.ship.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SHIPCOM_TOKEN}"
      }
    }
  }
}

Configura SHIPCOM_TOKEN en el entorno desde el que se inicia Cursor (por ejemplo, en tu perfil de shell y luego reinicia Cursor). Si no está configurada, el encabezado está vacío y el servidor responde 401 missing_bearer_token.

VS Code

Agrega Ship.com a .vscode/mcp.json en tu espacio de trabajo, o a tu configuración de usuario con el comando MCP: Abrir configuración de usuario. La entrada solicita el token cuando el servidor se inicia por primera vez, por lo que no se escribe en el archivo:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "shipcom-token",
      "description": "Ship.com access token",
      "password": true
    }
  ],
  "servers": {
    "shipcom": {
      "type": "http",
      "url": "https://app.ship.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:shipcom-token}"
      }
    }
  }
}

Windsurf

Abre la configuración MCP de Cascade y edita el mcp_config.json sin procesar. Windsurf usa serverUrl para servidores remotos. Al igual que con Cursor, SHIPCOM_TOKEN debe estar configurada en el entorno desde el que se inicia Windsurf, o el servidor responde 401 missing_bearer_token:

{
  "mcpServers": {
    "shipcom": {
      "serverUrl": "https://app.ship.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SHIPCOM_TOKEN}"
      }
    }
  }
}

Cualquier otro cliente MCP funciona de la misma manera: configura la URL del servidor en https://app.ship.com/mcp, elige el transporte HTTP (Streamable HTTP) y envía el encabezado Authorization.

HTTP sin procesar (curl)

El servidor no tiene estado: no hay ID de sesión que llevar entre llamadas, y cada solicitud se autentica por sí sola. Envía Content-Type: application/json; incluir text/event-stream en Accept es inofensivo, ya que las respuestas siempre son JSON plano.

export SHIPCOM_TOKEN="YOUR_TOKEN"

# 1. initialize
curl -s https://app.ship.com/mcp \
  -H "Authorization: Bearer $SHIPCOM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-script","version":"1.0"}}}'

# 2. list the tools
curl -s https://app.ship.com/mcp \
  -H "Authorization: Bearer $SHIPCOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. call a tool
curl -s https://app.ship.com/mcp \
  -H "Authorization: Bearer $SHIPCOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_balance","arguments":{}}}'

La respuesta initialize (instrucciones abreviadas):

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},"serverInfo":{"name":"ship-com","version":"1.0.0"},"instructions":"Ship.com lets you rate, purchase, and track shipping labels ..."}}

La respuesta tools/call. El bloque de texto lleva la misma carga útil que structuredContent, con formato legible:

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\n  \"balance\": 42.17, ..."}],"structuredContent":{"balance":42.17,"currency":"USD","auto_recharge_amount":25.0,"auto_recharge_enabled":true,"note":"If a label purchase drives the balance below zero, the card on file is auto-charged."},"isError":false}}

Se acepta un mensaje notifications/initialized (HTTP 202, cuerpo vacío) pero no es obligatorio.

Autenticación

Cada solicitud que lleva un id JSON-RPC, incluido initialize, necesita un token de portador en el encabezado Authorization. Ship.com acepta dos tipos: un token de acceso de Ship.com que copias desde Configuración, o un token de acceso OAuth que una aplicación obtiene cuando inicias sesión y la apruebas. Los tokens se aceptan solo en el encabezado, nunca en la URL ni en el cuerpo de la solicitud.

Authorization: Bearer YOUR_TOKEN

Una solicitud sin un token válido recibe HTTP 401 con este desafío, que los clientes MCP usan para iniciar el descubrimiento OAuth:

WWW-Authenticate: Bearer resource_metadata="https://app.ship.com/.well-known/oauth-protected-resource"

Tokens de acceso

Tu token de acceso es la misma credencial que usa la API REST de Ship.com. En la tarjeta MCP de Configuración se llama tu clave de conexión. La página Conectar Claude llama a la misma credencial tu código de acceso. Es una cadena larga que comienza con OAUTH2.; a pesar del prefijo, es un token de portador simple, no un token OAuth. Las conexiones que lo usan obtienen el catálogo completo de 40 herramientas, incluida la compra de etiquetas.

Obtenerlo	Configuración → Integración de API (o MCP en la barra lateral) → Mostrar mi clave de conexión o Generar clave de conexión. Consulta el Inicio rápido. También puedes obtenerlo desde el endpoint de tokens de la API REST, documentado en Generación de tokens.
Duración	180 días desde su emisión. La tarjeta muestra la fecha como "Conexión válida hasta...".
Reutilización	Mientras tu token sea válido, ambos botones devuelven el mismo token. Hacer clic en ellos nunca reemplaza un token que funciona.
Después de que expire	Las llamadas reciben HTTP 401 `expired_token`. Abre la tarjeta nuevamente y haz clic en cualquiera de los botones para obtener un nuevo token válido por otros 180 días y luego actualiza tus clientes.

Qué reemplaza tu token

Debido a que MCP y la API REST comparten una sola credencial, estas acciones terminan el token anterior de inmediato para ambos. Cualquier cliente MCP que aún lo use recibe HTTP 401 invalid_token hasta que le des el nuevo:

El botón Generar clave de API más abajo en la pestaña Integración de API. Emite un token completamente nuevo y un token de actualización.
Actualizar el token mediante el endpoint Actualización de tokens de la API REST. Emite un token nuevo y retira el anterior.

No existe una acción separada de "revocar" para tokens de acceso. Si un token queda expuesto, haz clic en Generar clave de API para reemplazarlo y luego actualiza cada cliente e integración REST que lo usaba.

Mantenerlo en secreto

Cualquiera con tu token puede actuar en tu cuenta, incluida la compra de etiquetas desde tu saldo postal. Trátalo como una contraseña.
Mantenlo fuera del control de versiones. Usa una variable de entorno o la solicitud secreta de tu cliente, como en los ejemplos de Cursor y VS Code.
Llama al servidor desde tu propia máquina o backend. El endpoint rechaza solicitudes de navegador desde otros sitios web, así que no pongas el token en código de páginas web.

Inicio de sesión OAuth 2.1

Con OAuth, la persona inicia sesión en Ship.com y aprueba la aplicación, y la aplicación nunca ve su contraseña. Ship.com es tanto el servidor de recursos como el servidor de autorización. Admite el flujo de código de autorización con PKCE (S256) para clientes públicos, sin secreto de cliente. Las conexiones autorizadas de esta manera obtienen 38 herramientas; la compra de etiquetas no se ofrece (consulta Herramientas por tipo de conexión).

Clientes compatibles. El inicio de sesión actualmente acepta solo clientes de Claude: las aplicaciones web, de escritorio y móviles de Claude, el conector del directorio de Claude y Claude Code. Otras herramientas, incluso las que admiten MCP OAuth, no pueden completar el inicio de sesión y deben conectarse con un token de acceso. Los pasos de configuración para Claude están en Conectar Claude a Ship.com.

Descubrimiento

Una solicitud no autenticada a /mcp devuelve HTTP 401 con el desafío resource_metadata mostrado anteriormente. Ambos documentos de metadatos son JSON público y no necesitan token.

Metadatos del recurso protegido (RFC 9728), en https://app.ship.com/.well-known/oauth-protected-resource y también en https://app.ship.com/.well-known/oauth-protected-resource/mcp:

{
  "resource": "https://app.ship.com/mcp",
  "authorization_servers": ["https://app.ship.com"],
  "scopes_supported": ["mcp:full"],
  "bearer_methods_supported": ["header"]
}

Metadatos del servidor de autorización (RFC 8414), en https://app.ship.com/.well-known/oauth-authorization-server:

{
  "issuer": "https://app.ship.com",
  "authorization_endpoint": "https://app.ship.com/oauth/authorize",
  "token_endpoint": "https://app.ship.com/oauth/token",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "client_id_metadata_document_supported": true,
  "scopes_supported": ["mcp:full"]
}

No hay endpoint de registro, revocación ni introspección, no hay JWKS ni configuración de OpenID Connect.

Registro de clientes

Opción	Cómo funciona
Cliente pre-registrado	`client_id` `claude`, utilizado por las aplicaciones alojadas de Claude. Sus URI de redirección son exactamente `https://claude.ai/api/mcp/auth_callback` y `https://claude.com/api/mcp/auth_callback`.
Documento de metadatos de ID de cliente	El `client_id` es una URL `https` cuyo host es exactamente `claude.ai` o `claude.com`. Ship.com obtiene el documento directamente (no se siguen redirecciones, tiempo de espera de 8 segundos). Debe devolver HTTP 200 con un objeto JSON cuyo `client_id` sea igual a la URL y cuyo `redirect_uris` sea una lista no vacía. Los documentos se almacenan en caché hasta 30 minutos. Una redirección de bucle local registrada `http` (`localhost`, `127.0.0.1` o `[::1]`) coincide en cualquier puerto, siempre que el esquema, el host, la ruta y la consulta coincidan.
Registro dinámico de clientes	No compatible.

Las URI de redirección deben coincidir exactamente con un valor registrado, sin comodines.

Solicitud de autorización

Envíe el navegador del usuario a GET https://app.ship.com/oauth/authorize con estos parámetros de consulta:

Parámetro	Valor
`response_type`	`code` (obligatorio)
`client_id`	Consulte Registro de cliente (obligatorio)
`redirect_uri`	Una URI de redirección registrada (obligatorio)
`code_challenge`	BASE64URL(SHA-256(code_verifier)) (obligatorio)
`code_challenge_method`	`S256` (obligatorio; `plain` se rechaza)
`state`	Recomendado. Se devuelve sin cambios en la redirección.
`scope`	Opcional. El único ámbito es `mcp:full`, y siempre se concede.

Si el usuario no ha iniciado sesión, Ship.com le pide que inicie sesión primero y luego muestra la pantalla de aprobación. Permitir redirige a redirect_uri?code=...&state=.... Denegar redirige con error=access_denied. Un client_id desconocido o un redirect_uri que no coincide muestra una página de error en Ship.com y no redirige. Otros problemas redirigen con error=unsupported_response_type o error=invalid_request y un error_description. El código es de un solo uso, caduca después de 5 minutos y está vinculado al client_id, al redirect_uri exacto y al desafío de código.

Solicitud de token

POST https://app.ship.com/oauth/token con un cuerpo codificado en formulario (application/x-www-form-urlencoded). Los clientes son públicos: envíe client_id en el cuerpo y sin secreto de cliente.

Intercambie el código de autorización:

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fclaude.ai%2Fapi%2Fmcp%2Fauth_callback
&client_id=claude
&code_verifier=CODE_VERIFIER

redirect_uri debe ser exactamente el valor utilizado en la solicitud de autorización. code_verifier debe tener de 43 a 128 caracteres de A-Z a-z 0-9 - . _ ~.

Actualización:

grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=claude

Una respuesta exitosa, para cualquiera de las dos concesiones:

{
  "access_token": "mcp_at_...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "mcp_rt_...",
  "scope": "mcp:full"
}

HTTP	`error`	Cuándo
429	`slow_down`	Más de 30 solicitudes de token por minuto desde una dirección IP. Espere `Retry-After` (60 segundos).
400	`invalid_request`	El cuerpo no está codificado en formulario, o falta `grant_type`.
400	`invalid_client`	El `client_id` falta o no se acepta.
400	`unsupported_grant_type`	Cualquier concesión distinta de `authorization_code` y `refresh_token`.
400	`invalid_grant`	El código o el token de actualización no es válido, caducó, ya se usó o se revocó; el `redirect_uri` no coincide; o la verificación PKCE falló. La descripción es deliberadamente la misma para cada caso.

Ciclos de vida y rotación

Los tokens de acceso duran 24 horas. Uno caducado recibe HTTP 401 expired_token en /mcp; use el token de actualización.
Los tokens de actualización duran 180 días y rotan en cada uso. Cada actualización devuelve un nuevo token de acceso y un nuevo token de actualización, válidos por otros 180 días, y retira inmediatamente el par anterior.
La reutilización se trata como robo. Presentar un token de actualización que ya se rotó, o canjear un código de autorización dos veces, revoca todas las conexiones que esa aplicación tiene con la cuenta. El usuario debe iniciar sesión y aprobar de nuevo. Guarde el token de actualización más reciente antes de usar el nuevo token de acceso, y no actualice el mismo token desde dos lugares a la vez.
Una vez que un token de actualización caduca, la actualización devuelve invalid_grant y el usuario debe iniciar sesión de nuevo.

Pantalla de aprobación y aplicaciones conectadas

La pantalla de aprobación nombra la aplicación, muestra qué cuenta de Ship.com tiene la sesión iniciada y enumera lo que una conexión de Ship.com puede hacer. La lista es la misma para cada aplicación y describe todo lo que una conexión de Ship.com puede incluir; las herramientas que una conexión OAuth realmente recibe se enumeran en Herramientas por tipo de conexión. El usuario elige Permitir o Denegar.

Las aplicaciones aprobadas aparecen en Aplicaciones conectadas en Configuración → Integración de API, con cuándo se usaron por última vez (la fecha de conexión mostrada se actualiza cada vez que la aplicación renueva su inicio de sesión). Desconectar revoca el acceso de esa aplicación de inmediato: sus tokens dejan de funcionar (HTTP 401 invalid_token) y debe aprobarse de nuevo para reconectarse. No hay un punto final público de revocación de tokens; desconectar en Configuración, o pedir ayuda al soporte de Ship.com, es cómo se retira el acceso.

Herramientas por tipo de conexión

Conexión	Herramientas	No ofrecidas
Token de acceso	40	Ninguna
Inicio de sesión OAuth	38	buy_label, trigger_batch_purchase

Una herramienta que no se ofrece en su conexión no aparece en tools/list, y llamarla devuelve el error JSON-RPC -32602: "La herramienta 'buy_label' no está disponible en este servidor. Llame a tools/list para ver las herramientas disponibles." Las conexiones OAuth conservan todas las demás herramientas, incluida la clasificación, cotización, anulación de etiquetas, cancelación de pedidos, marcado de etiquetas impresas, recogidas y get_batch_status. Las características del plan no cambian la lista; se verifican cuando se llama a una herramienta (consulte Características del plan).

Cómo se comportan las herramientas

Estas reglas se aplican a cada herramienta. La referencia de herramientas cubre los parámetros y resultados de cada herramienta.

Formato de resultado

Un tools/call que llega a una herramienta siempre devuelve un result JSON-RPC, incluso cuando la herramienta rechaza o falla. El resultado tiene una de dos formas:

Éxito con datos: content contiene un bloque de texto con la carga útil como JSON con sangría, structuredContent contiene la misma carga útil como objeto, y isError es false.
Mensaje: content contiene un bloque de texto con un mensaje en lenguaje natural, sin structuredContent. Cada error de herramienta usa esta forma, con isError: true.

{"jsonrpc":"2.0","id":7,"result":{"content":[{"type":"text","text":"Order 48213 was not found in this account."}],"isError":true}}

Los errores de herramienta cubren argumentos incorrectos o faltantes, registros que no se encuentran, características del plan que no tiene, rechazos comerciales como un precio superior a su max_cost, y mensajes del transportista, que se transmiten palabra por palabra. Los argumentos los verifica cada herramienta en lugar de contra inputSchema, por lo que un argumento faltante devuelve un mensaje isError como "order_id es obligatorio." Un valor del tipo incorrecto, como el texto order_number donde order_id espera un entero, devuelve el mensaje de error inesperado general. Los ID son siempre el entero order_id, pickup_id, batch_id o job_id, nunca números de visualización. Los mensajes están escritos para mostrarse al usuario o para que el asistente actúe sobre ellos. Un error JSON-RPC está reservado para problemas de protocolo; consulte Errores.

Los registros fuera de su cuenta nunca son visibles. Un mensaje de no encontrado se lee igual si el registro no existe o pertenece a otra persona.

Vista previa, luego confirmar

Las herramientas que gastan dinero, envían correo electrónico, cancelan algo o aceptan un acuerdo funcionan en dos pasos, controlados por un argumento booleano confirm:

Vista previa. Llame a la herramienta sin confirm (o con false). No se compra, cobra, anula, programa ni envía nada. (Una excepción a "nada cambia": una vista previa de trigger_batch_purchase clasifica cada pedido y guarda el peso y la dirección que usó, igual que get_rates). El resultado incluye "preview": true, lo que sucedería (precios, saldos, destinatarios, pedidos afectados) y un note sobre cómo proceder (buy_label lo llama message).
Confirmar. Muestre la vista previa al usuario. Una vez que acepte, repita la misma llamada con "confirm": true.

Ship.com no guarda nada entre las dos llamadas. La mayoría de las herramientas releen todo al confirmar, por lo que el resultado refleja el momento en que confirma. buy_label es la excepción: cobra el precio sellado en el rate_id que obtuvo de get_rates. Ese token está firmado por Ship.com y no se puede editar, por lo que el precio nunca proviene del cliente. El servidor no requiere una vista previa antes de una confirmación, por lo que previsualizar primero depende del cliente. Envíe confirm como un booleano JSON.

Herramientas de dos pasos	Escrituras de un solo paso (surten efecto de inmediato)
buy_label, trigger_batch_purchase, cancel_shipping_label, cancel_order, mark_labels_printed, schedule_pickup, cancel_pickup, send_customer_email, send_mass_marketing_email, redeem_referral_credit, register_ups	create_order, bulk_create_orders, update_order, update_order_address, create_or_update_customer, sync_platform_orders

register_ups es más estricto. Su vista previa devuelve el Acuerdo de Tecnología completo de UPS y un agreement_token, y la llamada de confirmación debe enviar ese token de vuelta. El usuario debe leer y aceptar el acuerdo por sí mismo; un asistente nunca debe aceptarlo en su nombre.

Cada herramienta en tools/list lleva annotations con un title y readOnlyHint. Las herramientas de escritura también llevan destructiveHint. Esto es cierto para cada herramienta de escritura excepto create_order, bulk_create_orders y sync_platform_orders, que solo agregan nuevos registros. mark_labels_printed se considera destructiva porque confirmarla envía correos electrónicos a sus clientes. Los clientes MCP usan estas pistas para decidir cuándo preguntar al usuario antes de ejecutar una herramienta. get_rates está marcada como de solo lectura, pero puede guardar el peso que pasa y los resultados de verificación de dirección en el pedido.

Seguridad del dinero

Solo dos herramientas gastan dinero, buy_label y trigger_batch_purchase, y ambas se ofrecen solo en conexiones de token de acceso. Aquí es de donde proviene el dinero:

Primero, el saldo de portes. Las etiquetas se pagan con tu saldo de portes de Ship.com. buy_label añade una tarifa de pago por uso de $0.30 por etiqueta cuando tu monto de recarga automática es de $0.01 o menos. El seguro de envío, cuando está activado, se cobra además de los portes.
Recarga automática. Si tu saldo no cubre los portes y el seguro, lo que sucede depende de tu monto de recarga automática. Por encima de $0.01, se cobra a tu método de pago registrado el mayor entre ese monto y el déficit antes de crear la etiqueta. A $0.01 (pago por uso), se cobra el déficit más la tarifa de $0.30, al menos $1. A $0, la compra falla. Esos fondos permanecen en tu saldo incluso si la compra luego falla. Un lote se recarga una vez, antes de comprar cualquier etiqueta.
Las vistas previas muestran el costo. La vista previa de buy_label devuelve total_charge, current_balance, balance_after y auto_recharge_would_fire. La vista previa del lote devuelve precios por pedido y un total_cost de portes.
Límites de precio. Pasa max_cost a buy_label o max_total a trigger_batch_purchase. Un precio por encima del límite se rechaza y no se cobra nada. Ambos límites cubren solo portes, no tarifas ni seguros.
Sin compras dobles. Si un pedido ya tiene una etiqueta, buy_label devuelve esa etiqueta y no cobra nada. Su respuesta aún dice purchased: true, así que verifica get_label primero cuando no estés seguro.
Los lotes se ejecutan en segundo plano. Un lote confirmado se pone en cola, y sus etiquetas generalmente se compran en aproximadamente un minuto. Síguelo con get_batch_status. Solo un lote puede ejecutarse a la vez.
Los reembolsos van a tu saldo de portes. Anular una etiqueta (cancel_shipping_label, o cancel_order en un pedido no enviado) acredita tu saldo de portes una vez que el transportista acepta la anulación, típicamente dentro de unos 14 días, si el paquete nunca fue escaneado. Los reembolsos se acreditan a tu saldo de portes, no a una tarjeta.
Todo lo demás es gratis. Las recogidas reservadas con schedule_pickup no cuestan nada, y redeem_referral_credit mueve crédito de referidos a portes sin cobrar una tarjeta. Para agregar fondos o cambiar la recarga automática, usa la aplicación web de Ship.com.

Los correos enviados con send_customer_email y send_mass_marketing_email son reales y no se pueden recuperar, así que trátalos con el mismo cuidado.

Características del plan

Cada herramienta está listada en todos los planes. Algunas verifican una característica del plan al ser llamadas y se rechazan con un mensaje isError si tu plan no la incluye (las herramientas de correo aún muestran una vista previa y reportan el resultado en limit_check):

Característica	Herramientas	Incluida en	Mensaje sin ella
Recogida de transportista	schedule_pickup	Actualmente Growth, Executive, Ultra	"Tu plan actual de Ship.com no incluye la programación de recogidas de transportista. Mejora la suscripción para usar esta herramienta."
Envío por lotes	trigger_batch_purchase, get_batch_status	Actualmente Growth, Executive, Ultra	"Tu plan actual de Ship.com no incluye la compra de etiquetas por lotes. Mejora la suscripción para usar esta herramienta."
Informes de negocio	get_shipping_report, get_tax_report, get_shipping_analytics	Actualmente Executive, Ultra	"Tu plan actual de Ship.com no incluye informes de negocio. Mejora la suscripción para usar esta herramienta."
Correo de marketing	send_customer_email, send_mass_marketing_email	Actualmente Growth y Executive (asignación mensual), Ultra (ilimitado); los períodos de prueba tienen un límite separado. Ver Asignación de correo de marketing	El `limit_check` de la vista previa muestra `allowed: false` y `reason: "no_entitlement"`; confirmar se rechaza con "Las campañas de correo de marketing no están incluidas con tu suscripción actual."

El contenido del plan puede cambiar; get_subscription_info muestra lo que tu plan incluye hoy.

Las características siguen el plan actualmente seleccionado en tu cuenta. Una cuenta sin plan seleccionado aún, o en un plan anterior que ya no se vende, se trata como si no las incluyera. Llama a get_subscription_info para verificar: tier.features muestra carrier_pickup, batch y business_reporting. La cancelación de recogidas, las consultas de recogidas y todas las demás herramientas no tienen requisito de plan. Las asignaciones de correo se cubren en Asignación de correo de marketing.

Las compras de etiquetas también siguen el límite mensual de envíos de tu plan, si tiene uno. Pasado el límite, buy_label devuelve "Compra de etiqueta fallida — Límite alcanzado: " seguido del límite.

Errores

Los errores provienen de tres capas. Los problemas de autenticación, origen y límite de velocidad son respuestas HTTP simples con un cuerpo JSON {"error": "...", "message": "..."}, no JSON-RPC. Cada 401 también lleva el desafío WWW-Authenticate descrito en Autenticación.

HTTP	`error`	Significado
401	`missing_bearer_token`	Sin encabezado `Authorization: Bearer`, o uno vacío.
401	`invalid_token`	El token no es reconocido: fue reemplazado, o la aplicación fue desconectada. También se devuelve cuando la cuenta del token ya no existe, y cuando el valor del encabezado está mal formado, por ejemplo `Bearer Authorization: Bearer ...`.
401	`expired_token`	El token ha expirado. Refresca un token OAuth, u obtén un nuevo token de acceso desde Configuración.
401	`invalid_information`	La solicitud no pudo ser autorizada. Contacta a help@ship.com si crees que esto es un error.
403	`forbidden_origin`	La solicitud provino de una página de navegador en un sitio web que Ship.com no permite. Las solicitudes sin encabezado `Origin`, como llamadas del lado del servidor, no se ven afectadas.
429	`rate_limited`	Más de 60 solicitudes en un minuto para este token. Ver Límites de velocidad.
405		`GET` en `/mcp` (cuerpo de texto plano). Solo se admite `POST`, y no hay flujo de eventos enviados por el servidor.
202		No es un error: se aceptó una notificación (un mensaje sin `id`). Nunca se responde.

Los problemas de protocolo devuelven HTTP 200 con un objeto JSON-RPC error que contiene code y message:

Código	Significado
`-32700`	El cuerpo está vacío o no es JSON válido.
`-32600`	Solicitud inválida: el cuerpo no es un objeto JSON único (los arreglos por lotes no son compatibles), o falta `method`.
`-32601`	Método desconocido. Los métodos admitidos son `initialize`, `ping`, `tools/list` y `tools/call`; los nombres distinguen mayúsculas y minúsculas.
`-32602`	`tools/call` no tiene herramienta `name`, nombra una herramienta que no existe (los nombres distinguen mayúsculas y minúsculas), o nombra una herramienta no ofrecida en esta conexión.
`-32603`	Un error inesperado del lado de Ship.com. Intenta de nuevo, y contacta a help@ship.com si continúa.

Todo lo que sucede dentro de una herramienta, incluyendo rechazos de plan y fallos, es un resultado con isError: true (ver Formato de resultado). Si una herramienta encuentra un error inesperado, su mensaje dice si algún trabajo pudo haberse guardado. Relee el estado actual, por ejemplo con get_order, get_label o get_balance, antes de reintentar cualquier cosa que gaste dinero.

Límites de velocidad

Endpoint MCP: 60 solicitudes por minuto por token. La ventana se reinicia al inicio de cada minuto (UTC). Cada solicitud autenticada cuenta, incluyendo initialize y tools/list; las notificaciones no cuentan. Sobre el límite obtienes HTTP 429 con Retry-After: 60. Cada token tiene su propia asignación, así que un token OAuth refrescado comienza un conteo nuevo.
Endpoint de token OAuth: 30 solicitudes por minuto por dirección IP, también con Retry-After: 60.
Los límites de negocio son separados: las asignaciones mensuales de envíos y correos de tu plan, y un lote a la vez.

Convenciones compartidas

Ejemplos: el ejemplo de cada herramienta a continuación es el objeto arguments. Envíalo como {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_rates","arguments":{...}}}. Ver Enviar un pedido de principio a fin.
Nombres: los argumentos y campos de resultado usan snake_case.
Tipos: envía tipos JSON reales: enteros para IDs, booleanos para confirm, números para dinero y pesos.
Dinero: dólares estadounidenses como números JSON simples.
Pesos: onzas (weight_oz).
Fechas: YYYY-MM-DD. Las marcas de tiempo en los resultados están en UTC. La mayoría no tiene sufijo de zona horaria; algunas, como ship_date de get_rates, terminan en Z.
Paginación: las herramientas de listas toman page (desde 1) y page_size (hasta 50), o limit; cada herramienta lista sus valores predeterminados. tools/list devuelve todo el catálogo en una sola respuesta.
Estados de pedido: los filtros de estado toman nombres como ChooseShipping (listo para enviar) y LabelPrinted. Algunos resultados muestran la etiqueta de visualización, como "Listo para enviar", en su lugar. Ver Estados de pedido.

Herramientas

Las conexiones con token de acceso obtienen las 40 herramientas. Las conexiones OAuth obtienen 38: todo excepto buy_label y trigger_batch_purchase.

Acceso es lo que una herramienta puede hacer: Solo lectura no cambia nada; Cambia datos actualiza tus registros o los del transportista; Gasta dinero cobra tu saldo de portes y posiblemente tu método de pago; Envía correo envía correos a tus clientes. Característica del plan es la característica que una llamada necesita (ver Características del plan); para las herramientas de correo se aplica al envío. OAuth dice si la herramienta se ofrece en conexiones de inicio de sesión OAuth. tools/list es siempre la lista definitiva para tu conexión.

Herramienta	Qué hace	Acceso	Función del plan	OAuth
Pedidos y productos
`list_orders`	Lista pedidos, listos para enviar por defecto	Solo lectura	Ninguna	Sí
`get_order`	Detalle completo de un pedido	Solo lectura	Ninguna	Sí
`get_label`	Archivos de etiqueta y seguimiento de una etiqueta comprada	Solo lectura	Ninguna	Sí
`track_order`	Último estado de seguimiento almacenado	Solo lectura	Ninguna	Sí
`list_products`	Tu catálogo de productos guardado	Solo lectura	Ninguna	Sí
Crear y modificar pedidos
`create_order`	Crea un pedido	Modifica datos	Ninguna	Sí
`bulk_create_orders`	Crea hasta 100 pedidos	Modifica datos	Ninguna	Sí
`update_order`	Edita un pedido no enviado	Modifica datos	Ninguna	Sí
`update_order_address`	Cambia y valida una dirección de envío	Modifica datos	Ninguna	Sí
`cancel_order`	Cancela un pedido, anulando su etiqueta si es posible	Modifica datos	Ninguna	Sí
`cancel_shipping_label`	Anula una etiqueta; reembolso al saldo postal	Modifica datos	Ninguna	Sí
Tarifas, etiquetas y direcciones
`quote_shipping`	Tarifas para un destino, sin necesidad de pedido	Solo lectura	Ninguna	Sí
`get_rates`	Tarifas para un pedido	Modifica datos	Ninguna	Sí
`buy_label`	Compra una etiqueta	Gasta dinero	Ninguna	No
`validate_address`	Verifica y estandariza una dirección de EE. UU.	Solo lectura	Ninguna	Sí
`register_ups`	Abre o vincula una cuenta UPS	Modifica datos	Ninguna	Sí
Recogidas
`mark_labels_printed`	Marca etiquetas compradas como impresas para que una recogida las recoja; previsualiza y luego confirma	Modifica datos, envía correo electrónico	Ninguna	Sí
`check_pickup_availability`	¿Puede el transportista recoger en una fecha?	Solo lectura	Ninguna	Sí
`schedule_pickup`	Reserva una recogida gratuita del transportista	Modifica datos	Recogida del transportista	Sí
`cancel_pickup`	Cancela una recogida gratuita	Modifica datos	Ninguna	Sí
`list_pickups`	Tus recogidas recientes	Solo lectura	Ninguna	Sí
`get_pickup`	Una recogida y sus pedidos	Solo lectura	Ninguna	Sí
Envío por lotes y sincronización de plataformas
`trigger_batch_purchase`	Compra etiquetas para muchos pedidos	Gasta dinero	Envío por lotes	No
`get_batch_status`	Progreso de un lote	Solo lectura	Envío por lotes	Sí
`list_connected_platforms`	Tus plataformas de venta conectadas	Solo lectura	Ninguna	Sí
`sync_platform_orders`	Importa pedidos recientes de Shopify o Etsy	Modifica datos	Ninguna	Sí
`get_sync_status`	Estado de los trabajos de importación	Solo lectura	Ninguna	Sí
Clientes y correo electrónico
`list_customers`	Busca en tu libreta de direcciones	Solo lectura	Ninguna	Sí
`get_customer`	Registro completo de un cliente	Solo lectura	Ninguna	Sí
`create_or_update_customer`	Añade o edita un cliente	Modifica datos	Ninguna	Sí
`send_customer_email`	Envía un correo electrónico a un cliente	Envía correo electrónico	Marketing email	Sí
`send_mass_marketing_email`	Enviar correo electrónico a un segmento de clientes	Envía correo electrónico	Correo electrónico de marketing	Sí
`list_lapsed_customers`	Clientes que no han pedido recientemente	Solo lectura	Ninguno	Sí
Cuenta, créditos e informes
`get_balance`	Saldo de franqueo y recarga automática	Solo lectura	Ninguno	Sí
`get_subscription_info`	Tu plan, límites y funciones	Solo lectura	Ninguno	Sí
`get_referral_info`	Crédito por referidos y referidos	Solo lectura	Ninguno	Sí
`redeem_referral_credit`	Mover crédito por referidos a franqueo	Cambia datos	Ninguno	Sí
`get_shipping_report`	Gasto en envíos por mes	Solo lectura	Informes empresariales	Sí
`get_tax_report`	Impuesto sobre ventas recaudado	Solo lectura	Informes empresariales	Sí
`get_shipping_analytics`	Volumen, transportistas y destinos	Solo lectura	Informes empresariales	Sí

Envíe un pedido de principio a fin

Este recorrido lleva un pedido desde "Listo para enviar" hasta una recogida reservada con el transportista. Cada paso es un tools/call, y el JSON mostrado es su objeto arguments. Conserve los IDs exactamente como se devuelven. Los pasos 4 y 5 usan buy_label, que solo se ofrece en conexiones con token de acceso (consulte Herramientas por tipo de conexión).

Encuentre el pedido. list_orders con {} devuelve pedidos listos para enviar. Conserve el order_id.
Lea su peso. get_order con {"order_id": 48213}. Lea totals.weight_oz; si está vacío, pese el paquete.
Cotice el envío. get_rates con {"order_id": 48213, "weight_oz": 14, "length": 10, "width": 8, "height": 4}. Pase el peso explícitamente; el peso guardado no se usa para el precio. Conserve el package_id de nivel superior, luego elija una fila y conserve su rate_id, method y service_level.
Vista previa de la compra. buy_label con esos cuatro valores y un max_cost, sin confirm. Verifique total_charge y balance_would_go_negative, y muéstrelos al usuario.
Compre. Repita la misma llamada a buy_label con "confirm": true. Conserve label_url y tracking_number. Si falla, consulte errores de buy_label.
Imprima la etiqueta y luego márquela como impresa. Imprima label_url (y form_url, el formulario de aduanas, cuando lo haya). Luego llame a mark_labels_printed con {"order_ids": [48213]} para obtener una vista previa, y nuevamente con "confirm": true. El pedido pasa de "Etiqueta comprada" a "Etiqueta impresa", que es lo que recoge una recogida. Su cliente recibe su correo de seguimiento de "Etiqueta impresa" si lo tiene activado.
Verifique una fecha de recogida. check_pickup_availability con {"date": "2026-10-06"}.
Vista previa de la recogida. schedule_pickup con {"date": "2026-10-06", "location": "Front Door"}. Confirme que eligible_order_ids incluye su pedido.
Resérvela. Repita la llamada con "confirm": true y conserve el pickup_id.

Paso 3 como solicitud completa:

curl -s https://app.ship.com/mcp \
  -H "Authorization: Bearer $SHIPCOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_rates","arguments":{"order_id":48213,"weight_oz":14,"length":10,"width":8,"height":4}}}'

Cuerpo de la solicitud del paso 5, con los tokens abreviados:

{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"buy_label","arguments":{"order_id":48213,"rate_id":"eyJhbGciOi...","package_id":"eyJhbGciOi...","method":"USPS Ground Advantage","service_level":"usps_ground_advantage","max_cost":8.00,"confirm":true}}}

Si cambia la dirección, el peso o las dimensiones del pedido después del paso 3, cotice nuevamente antes de comprar: el rate_id y el package_id conservan los valores del momento en que cotizó.

Pedidos y productos

Estas herramientas leen sus pedidos, etiquetas compradas, seguimiento y catálogo de productos. Un flujo típico comienza con list_orders para ver qué está listo para enviar y abre uno con get_order; una vez que se compra una etiqueta, get_label la devuelve y track_order sigue la entrega, mientras que list_products busca nombres y precios de productos al armar un pedido. Las cinco son de solo lectura, funcionan en todos los planes y tipos de conexión, devuelven solo los datos de su propia cuenta y leen lo que Ship.com tiene almacenado sin contactar a transportistas ni plataformas de venta.

list_orders

Solo lectura

Lista los pedidos de su cuenta, del más reciente al más antiguo por fecha de pedido. Sin filtro, devuelve los pedidos listos para enviar, la cola de trabajo sin enviar donde suele comenzar la cotización y la compra de etiquetas. Las filas son compactas; llame a get_order para obtener el detalle completo de un pedido.

Parámetro	Tipo	Obligatorio	Descripción
`status`	string	No	Qué pedidos devolver. Omita para pedidos listos para enviar (`ChooseShipping`). Envíe `active` para todos los pedidos excepto los cancelados y fusionados, o un nombre de estado de la tabla siguiente, como `PrintLabel`, `InTransit` o `Delivered`. Un estado por llamada.
`page`	integer	No	Número de página basado en 1. Valor predeterminado: 1. Los valores inferiores a 1 se tratan como 1. Una página más allá del final devuelve una lista vacía.
`page_size`	integer	No	Filas por página, de 1 a 50. Valor predeterminado: 25. Los valores fuera de ese rango se ajustan, no se rechazan.

Devuelve: orders, más page y page_size según se apliquen, total (todos los pedidos que coinciden, no solo esta página) y status (el filtro aplicado, como nombre de estado o active). Cada fila tiene order_id (úsalo con las otras herramientas de esta sección), order_number, name (el nombre de envío almacenado en el pedido; puede estar vacío), city, state, zip, country (US cuando está en blanco), total, status y tracking_number.

Bueno saber: El filtro toma un nombre de estado, pero el status de cada fila es la etiqueta de visualización, por lo que las filas listas para enviar dicen "Listo para enviar", no ChooseShipping. active aún incluye pedidos finalizados, como entregados y reembolsados. No hay filtro por fecha, cliente ni búsqueda de texto. Un estado no reconocido devuelve un error que enumera los nombres aceptados, así que envíe exactamente un nombre, escrito como se muestra a continuación. Las filas se ordenan solo por fecha de pedido y pueden cambiar si se importan nuevos pedidos mientras navega por páginas. El name de la fila es exactamente lo que está en el pedido (un marcador de posición como "Invitado" se muestra tal cual), por lo que puede diferir del ship_to.name en get_order.

Estados de pedido: filtre por nombre; los resultados muestran la etiqueta.

Nombre de estado	Mostrado en resultados como
`MissingEmail_InvoiceDraft`	Falta correo electrónico
`InvoiceDraft`	Borrador de factura
`WaitingForPayment`	Esperando pago
`BackOrderedLiveSelling`	Pedido solicitado
`BackOrdered`	Pedido pendiente
`ChooseShipping`	Listo para enviar
`LabelRefunded`	Etiqueta reembolsada
`PrintLabel`	Etiqueta comprada
`LabelPrinted`	Etiqueta impresa
`WaitingForPickup`	Esperando recogida
`InTransit`	En tránsito
`DeliveryFailure`	Fallo de entrega
`ReturnedToSender`	Devuelto al remitente
`DeliveryFailureWait`	Esperando devolución
`Delivered`	Entregado
`PrintReturnLabel`	Comprar etiqueta de devolución
`ReturnLabelRefunded`	Etiqueta de devolución reembolsada
`WaitingForReturn`	Esperando devolución
`ReturnInTransit`	Devolución en tránsito
`ReturnDelivered`	Devolución entregada
`ReturnReceived`	Devolución recibida
`ReturnComplete`	Devolución completa
`Refunded`	Reembolsado
`WaitingForMerge`	Fusión en curso
`Merged`	Fusionado
`Deleted`	Cancelado

Las etiquetas no son únicas: DeliveryFailureWait y WaitingForReturn se muestran ambas como "Esperando devolución", así que filtre por nombre. El nombre de estado de un pedido cancelado es Deleted.

{"status": "active", "page": 1, "page_size": 2}

get_order

Solo lectura

Devuelve el detalle completo de un pedido de su cuenta: dirección de envío, totales, campos de envío y seguimiento, y artículos de línea. Funciona para un pedido en cualquier estado, incluidos los cancelados y fusionados.

Parámetro	Tipo	Obligatorio	Descripción
`order_id`	integer	Sí	El ID del pedido, de list_orders.

Devuelve: order_id, order_number, status (etiqueta de visualización) y date (la fecha del pedido); ship_to con name, company, street1, street2, city, state, zip, country (US cuando está en blanco), phone y email; totals con subtotal, shipping (cargado a su comprador), tax, total y weight_oz; shipping con method (el servicio del transportista de la etiqueta comprada), cost (lo que pagó por la etiqueta), ship_date y label_url, donde method y label_url permanecen nulos hasta que se compra una etiqueta (antes de eso, cost puede ser nulo o contener un monto importado o estimado, así que verifique label_url en lugar de cost); tracking_number y tracking_url (una página de seguimiento de Ship.com para etiquetas compradas a través de Ship.com); y items, uno por artículo de línea, cada uno con sku, upc, quantity y price.

Bueno saber: Un ID que no existe y un pedido de otra cuenta devuelven el mismo error, Order {order_id} was not found in this account.. Omitir order_id devuelve order_id is required.. Los artículos de línea no tienen un campo separado de nombre de producto, estilo o talla. sku es el código de artículo almacenado en la línea, que puede ser nulo o, para algunas plataformas de venta, el nombre del producto. upc suele ser nulo y no siempre es un código de barras real: los pedidos importados de algunas plataformas de venta llevan un valor de marcador de posición allí. price es el precio registrado en la línea; según el origen del pedido, puede ser un precio unitario o un total de línea, así que no asuma ninguno. ship_to usa la dirección de envío guardada del pedido cuando la tiene. De lo contrario, se construye a partir del pedido, completando un nombre faltante o de marcador de posición (como "Invitado") y un correo electrónico o teléfono faltante del registro del cliente, y usa "Residente actual" cuando no se puede encontrar ningún nombre. company suele ser nulo. Si se cancela una etiqueta, el pedido vuelve a "Listo para enviar" y los campos de etiqueta y seguimiento vuelven a nulos, aunque ship_date puede conservar la fecha anterior.

{"order_id": 4815162}

get_label

Solo lectura

Devuelve los archivos de etiqueta y los detalles de seguimiento de la etiqueta comprada de un pedido. Devuelve solo enlaces almacenados y nunca regenera, vuelve a comprar ni obtiene nada del transportista. Llamarlo para un pedido sin etiqueta no es un error: obtiene has_label: false y enlaces nulos.

Parámetro	Tipo	Obligatorio	Descripción
`order_id`	integer	Sí	El pedido cuya etiqueta desea.

Devuelve: order_id; label_url, la etiqueta imprimible formateada según la configuración de impresión de su cuenta (si su cuenta imprime por código QR, las etiquetas de USPS se devuelven como una imagen QR escaneable en lugar de un PDF de etiqueta); raw_label_url, el archivo de etiqueta 4x6 original del transportista, presente solo para algunas etiquetas PDF de transportistas (actualmente ciertas etiquetas de USPS) y nulo de lo contrario; form_url, un PDF de formulario de aduanas separado cuando el transportista lo proporciona (actualmente envíos internacionales de UPS); receipt_url, un recibo del transportista cuando el transportista lo proporciona (actualmente UPS); tracking_number; tracking_url; y has_label, verdadero cuando label_url está presente.

Bueno saber: Use has_label para decidir si un pedido tiene una etiqueta activa. Cancelar una etiqueta borra label_url, tracking_number y tracking_url, pero los otros enlaces pueden seguir apuntando a los archivos de la etiqueta anulada, así que ignore raw_label_url, form_url y receipt_url cuando has_label sea falso. Los enlaces de etiqueta son URL de archivo HTTPS; trátelos como opacos en lugar de depender de su host o formato. Esta herramienta funciona en todos los tipos de conexión y devuelve la etiqueta sin importar cómo se compró, incluso en la aplicación web de Ship.com. Los IDs desconocidos y los pedidos de otras cuentas devuelven el mismo error de no encontrado que get_order.

{"order_id": 4815101}

track_order

Solo lectura

Devuelve el último estado de seguimiento almacenado por Ship.com para un pedido. Ship.com lo mantiene actualizado automáticamente en segundo plano; la herramienta no consulta al transportista en vivo, por lo que llamarla nuevamente no actualizará nada. Un pedido sin etiqueta devuelve un resultado exitoso con campos de seguimiento nulos.

Parámetro	Tipo	Obligatorio	Descripción
`order_id`	integer	Sí	El pedido para verificar el seguimiento.
Devuelve: `order_id`; `status`, el estado de visualización del pedido, como "En tránsito", "Entregado", "Fallo de entrega" o "Devuelto al remitente" (un estado de pedido, no un evento bruto del transportista); `tracking_number`; `tracking_url`; `ship_date`, `in_transit_date`, `delivered_date` y `exception_date`; `exception`, el texto de excepción del transportista; y `last_tracking_update`, cuando Ship.com almacenó por última vez una actualización de seguimiento para el pedido, en UTC.

Bueno saberlo: Consulta last_tracking_update para ver qué tan frescos están los datos. No todas las actualizaciones en segundo plano lo establecen, por lo que puede ser nulo incluso después de que status se haya movido; trata el valor nulo como "frescura desconocida", no como "nunca actualizado". Otros sellos de tiempo no llevan zona horaria. Si una etiqueta se cancela, el estado vuelve a "Listo para enviar" y tracking_number, tracking_url y in_transit_date se borran, pero las otras fechas y exception pueden conservar valores antiguos, así que lee status y tracking_number primero. Los IDs desconocidos y los pedidos de otras cuentas devuelven el mismo error de no encontrado que get_order.

{"order_id": 4815101}

list_products

Solo lectura

Lista los productos activos en tu catálogo de productos guardado de Ship.com, ordenados por nombre de la A a la Z. Úsalo para buscar nombres de productos, descripciones y precios cuando crees o edites un pedido. Solo lee tu catálogo guardado y no extrae productos en vivo de tiendas conectadas.

Parámetro	Tipo	Obligatorio	Descripción
`query`	string	No	Texto para coincidir con el nombre o la descripción del producto, sin distinguir mayúsculas de minúsculas. Es una coincidencia de subcadena simple: el texto completo debe aparecer tal como está escrito, sin comodines. Se ignoran los espacios iniciales y finales. Omítelo para listar todos los productos activos.
`page`	integer	No	Número de página basado en 1. Valor predeterminado 1. Los valores por debajo de 1 se tratan como 1. Una página más allá del final devuelve una lista vacía.
`page_size`	integer	No	Filas por página, de 1 a 50. Valor predeterminado 25. Los valores fuera de ese rango se ajustan, no se rechazan.

Devuelve: products, más page y page_size según se aplicaron y total (todos los productos activos que coinciden, no solo esta página). Cada producto tiene product_id, name, catalog (una etiqueta de agrupación opcional), description y price.

Bueno saberlo: Los productos inactivos nunca aparecen. Los productos se identifican por nombre: los resultados no tienen SKU, imagen, stock, costo ni campos de peso. Los artículos de línea en get_order sí llevan un sku.

{"query": "candle", "page": 1, "page_size": 10}

Crear y cambiar pedidos

Estas herramientas crean pedidos y los cambian antes de que se envíen. Un flujo típico: crea un pedido (o hasta 100 a la vez), ajusta sus detalles o la dirección de envío mientras aún está en "Listo para enviar", luego cotiza el envío y compra la etiqueta. Si los planes cambian, anula solo la etiqueta con cancel_shipping_label, o cancela todo el pedido con cancel_order.

Cada búsqueda de pedido y cliente está limitada a tu propia cuenta. Un ID de otra cuenta recibe la misma respuesta de "no se encontró en esta cuenta" que uno que no existe. Ship.com mantiene un registro de los cambios realizados a través de MCP, igual que hace con los cambios realizados en la aplicación. Envía números y booleanos como números y booleanos JSON reales, y envía los códigos postales como cadenas: un código postal enviado como número pierde su cero inicial.

create_order

Cambia datos

Crea un nuevo pedido en estado "Listo para enviar". Envía a un cliente que ya esté en tu libreta de direcciones con customer_id, o pasa el destinatario en línea con ship_to para importar un pedido desde cualquier lugar, como una hoja de cálculo, un correo electrónico o un mercado. Agrega artículos de línea y un peso de paquete ahora o más tarde. Pasa external_order_id para que un reintento o una reimportación devuelva el pedido existente en lugar de crear un duplicado.

Parámetro	Tipo	Obligatorio	Descripción
`customer_id`	integer	Uno de dos	Un cliente de la libreta de direcciones (de list_customers o get_customer). El pedido copia el nombre, la empresa, la dirección, el correo electrónico y el teléfono guardados del cliente. Proporciona exactamente uno de `customer_id` o `ship_to`.
`ship_to`	object	Uno de dos	Destinatario en línea. Si tu libreta de direcciones ya tiene un contacto con el mismo nombre y línea 1 de dirección (ignorando mayúsculas) y el mismo código postal, ese contacto se reutiliza sin cambios y su correo electrónico y teléfono guardados se copian al pedido; de lo contrario, se crea un nuevo contacto.
`ship_to.name`	string	Con `ship_to`	Nombre completo del destinatario, dividido en el primer espacio en nombre y apellido.
`ship_to.company`	string	No	Nombre de la empresa.
`ship_to.street1`	string	Con `ship_to`	Línea 1 de la dirección.
`ship_to.street2`	string	No	Apartamento, suite o unidad.
`ship_to.city`	string	Con `ship_to`	Ciudad.
`ship_to.state`	string	Con `ship_to`	Código de estado o provincia.
`ship_to.zip`	string	Con `ship_to`	Código postal o ZIP. Envíalo como cadena.
`ship_to.country`	string	No	Código de país de dos letras. Valor predeterminado `US`.
`items`	array	No	Artículos de línea. Omítelo, o envía `[]`, para un pedido sin artículos de línea.
`items[].name`	string	Sí	Nombre del producto. También agrega el producto a tu catálogo de productos General, o actualiza el producto con el mismo nombre allí.
`items[].quantity`	integer	No	Al menos 1. Valor predeterminado 1.
`items[].price`	number	No	Precio unitario en dólares, 0 o más. Valor predeterminado 0.
`items[].sku`	string	No	SKU o UPC, texto libre.
`items[].notes`	string	No	Notas para este artículo.
`weight_oz`	number	No	Peso del paquete en onzas, mayor que 0. Guardado en el pedido. trigger_batch_purchase lo cotiza. get_rates no: pasa `weight_oz` a get_rates explícitamente (puedes leerlo de vuelta desde el `totals.weight_oz` de get_order).
`external_order_id`	string	No	El número de pedido o PO de tu sistema de origen. Si un pedido en vivo en tu cuenta ya lo lleva, ese pedido se devuelve en lugar de crear uno nuevo.

Devuelve: created: true, order_id, un order_number generado de 6 caracteres, status ("Listo para enviar"), el ship_to utilizado y items_count. Con artículos agrega subtotal (suma de precio × cantidad) y un total igual; con ship_to agrega customer_id y customer_created. weight_oz y external_order_id se repiten cuando los envías, y cada resultado termina con un note. Un reenvío duplicado devuelve created: false, skipped_existing: true, el order_id del pedido existente, order_number y el status actual, y un note.

Bueno saberlo: Se ejecuta de inmediato. Toda la entrada se verifica antes de guardar cualquier cosa, por lo que un error de validación no crea nada. No se cobra franqueo ni se contacta a ningún transportista; la dirección se valida cuando cotizas el pedido. La protección contra duplicados ignora los pedidos cancelados y fusionados, por lo que una importación cancelada se puede reimportar. Un reenvío no se compara con el original ni lo actualiza. El ID se mantiene en las notas del pedido como [ext:YOUR-ID], por lo que reemplazar las notas con update_order desactiva la protección contra duplicados para ese pedido. Envía reintentos uno a la vez: dos llamadas simultáneas con el mismo ID pueden crear ambas un pedido. Un producto del catálogo que coincide por nombre (ignorando mayúsculas) toma el nuevo precio y su costo se restablece a 0. Si ejecutas un programa de recompensas, el pedido gana puntos de cliente como de costumbre.

{"ship_to": {"name": "Maria Delgado", "street1": "1420 Maple Ave", "street2": "Apt 3B", "city": "Springfield", "state": "IL", "zip": "62704"}, "items": [{"name": "Lavender Soy Candle", "quantity": 2, "price": 18.50, "sku": "CND-LAV-08"}, {"name": "Gift Wrap", "price": 3.00}], "weight_oz": 22, "external_order_id": "SHOP-10482"}

bulk_create_orders

Cambia datos

Crea hasta 100 pedidos en una sola llamada. Cada entrada toma los mismos campos que create_order y pasa por las mismas verificaciones, incluida la protección contra duplicados con external_order_id. Una entrada incorrecta no detiene al resto: cada entrada obtiene su propia fila de resultado, en orden de entrada, más un resumen. Úsalo en lugar de llamar a create_order en un bucle.

Parámetro	Tipo	Obligatorio	Descripción
`orders`	array	Sí	De 1 a 100 entradas de pedido. Una lista faltante, vacía o demasiado grande se rechaza y no se crea nada. Divide importaciones más grandes en varias llamadas.
`orders[]`	object	Sí	Un pedido con los campos de create_order: exactamente uno de `customer_id` o `ship_to`, más opcional `items`, `weight_oz` y `external_order_id`.

Devuelve: results, una fila por entrada con index y ok. Una fila exitosa tiene order_id y order_number, más skipped_existing: true cuando se devolvió un pedido existente; una fila fallida tiene error, el mismo mensaje que daría create_order. También summary (created, skipped, failed) y un note. Las filas no incluyen estado, dirección ni totales; usa get_order para esos.

Bueno saberlo: Toda la llamada cuenta como una solicitud contra el límite de velocidad de 60 solicitudes por minuto. No es todo o nada: cada entrada se guarda a medida que se procesa. Un external_order_id repetido dentro del mismo lote se crea una vez y se informa como omitido en la entrada posterior. Envía números como números JSON: un valor del tipo incorrecto (como "two" para una cantidad) detiene toda la llamada con un resultado de error inesperado después de que las entradas anteriores ya se guardaron. Después de cualquier error inesperado, verifica con list_orders. Reenviar el mismo lote con un external_order_id en cada entrada es seguro, porque las entradas ya creadas vuelven como omitidas.

{"orders": [{"customer_id": 918274, "weight_oz": 8, "external_order_id": "SHOP-10483"}, {"ship_to": {"name": "Maria Delgado", "street1": "1420 Maple Ave", "street2": "Apt 3B", "city": "Springfield", "state": "IL", "zip": "62704"}, "items": [{"name": "Lavender Soy Candle", "quantity": 2, "price": 18.50}], "external_order_id": "SHOP-10482"}]}

update_order

Cambia datos

Edita un pedido que aún está en "Listo para enviar" o en un estado anterior: notas, número de pedido de visualización, los montos que cobras a tu cliente, artículos de línea y peso del paquete. Envía solo los campos que quieras cambiar, al menos uno. El total se recalcula cada vez como subtotal - descuento + impuesto + envío + manejo, usando el valor guardado para cualquier monto que no envíes.

Parámetro	Tipo	Obligatorio	Descripción
`order_id`	integer	Sí	El pedido a editar. Los pedidos en "Etiqueta reembolsada" o cualquier estado posterior (etiqueta comprada, impresa, en tránsito, entregado, etc.) se rechazan. Los pedidos cancelados y fusionados no se rechazan; editarlos no los reabre.
`notes`	string	No	Reemplaza todo el campo de notas. Una cadena vacía lo borra.
`order_number`	string	No	Número de pedido de visualización. Una cadena vacía lo borra. No se verifica su unicidad.
`subtotal`	number	No	Subtotal de artículos. Se ignora cuando `items` se envía en la misma llamada.
`shipping`	number	No	Envío que cobras a tu cliente (no franqueo).
`tax`	number	No	Impuesto a las ventas.
`discount`	number	No	Descuento a nivel de pedido, restado del total.
`handling`	number	No	Tarifa de manejo.
`items`	array	No	Reemplaza todos los artículos de línea (no una fusión). Cada artículo toma `name` (obligatorio), `quantity`, `price`, `sku` y `notes`, como en create_order. `[]` elimina todos los artículos. El subtotal se recalcula a partir de los artículos.
`weight_oz`	number	No	Peso del paquete en onzas, mayor que 0. Guardado en el pedido. trigger_batch_purchase lo cotiza. get_rates no: pasa `weight_oz` a get_rates explícitamente (puedes leerlo de vuelta desde el `totals.weight_oz` de get_order).

Devuelve: updated: true, order_id, order_number, totals (subtotal, shipping, tax, discount, handling, total), más items_count y weight_oz cuando los enviaste, y un note. Bueno saber: Se ejecuta de inmediato y no cambia el estado del pedido. Las tarifas que obtuviste antes del cambio aún conservan el peso anterior; vuelve a llamar a get_rates antes de comprar. Los montos se guardan tal como se enviaron y no se verifican rangos. Los artículos actualizan tu catálogo de productos General de la misma manera que create_order. Reemplazar las notas de un pedido creado con external_order_id elimina su referencia [ext:...] y con ella la protección contra duplicados; incluye esa referencia en las nuevas notas para mantenerla. Si ejecutas un programa de recompensas, los puntos del cliente se recalculan. Las facturas no se pueden crear ni enviar a través de MCP; usa la aplicación Ship.com para eso.

{"order_id": 4821937, "items": [{"name": "Lavender Soy Candle", "quantity": 3, "price": 18.50, "sku": "CND-LAV-08"}], "shipping": 6.95, "tax": 3.30, "discount": 5.00, "weight_oz": 30}

update_order_address

Cambia datos

Cambia la dirección postal de envío en un pedido que aún está en Listo para enviar o en un estado anterior. La nueva dirección se valida antes de guardarse; si no valida, nada cambia. Solo se actualiza este pedido: la entrada de la libreta de direcciones del cliente y el nombre, empresa, teléfono y correo electrónico del destinatario permanecen como están.

Parámetro	Tipo	Obligatorio	Descripción
`order_id`	entero	Sí	El pedido a re-direccionar. Los pedidos en Reembolso de etiqueta o cualquier estado posterior se rechazan. Los pedidos cancelados y fusionados no se rechazan; editarlos no los reabre.
`street1`	cadena	Sí	Línea 1 de la dirección postal. Se guarda tal como se envió.
`street2`	cadena	No	Apartamento, suite o unidad. Si se omite, cualquier línea 2 existente en el pedido se borra, así que reenvíala para conservarla.
`city`	cadena	Sí	Ciudad. Se guarda la ciudad validada.
`state`	cadena	Sí	Código de estado de dos letras. Se guarda el estado validado.
`zip`	cadena	Sí	Código postal, enviado como cadena. El código postal validado se guarda y puede diferir del que enviaste.

Devuelve: updated: true, order_id, el ship_to guardado (street1, street2, city, state, zip, con la ciudad, estado y código postal corregidos) y un note.

Bueno saber: Se ejecuta de inmediato. Las tarifas que obtuviste antes del cambio aún conservan la dirección anterior; vuelve a llamar a get_rates antes de comprar. Solo direcciones de EE. UU.: la dirección siempre se valida como una dirección de EE. UU. Si el servicio de validación no está disponible brevemente, recibirás el mismo error de "no se pudo validar", por lo que un reintento posterior puede tener éxito.

{"order_id": 4821937, "street1": "1420 Maple Ave", "street2": "Apt 3B", "city": "Springfield", "state": "IL", "zip": "62704"}

cancel_order

Cambia datosVista previa, luego confirmar

Cancela un pedido por completo. Su estado pasa a Cancelado y permanece visible en tu cuenta. Si el pedido aún no se ha enviado y su etiqueta está dentro de los 29 días de su fecha de envío, la etiqueta se anula primero, con el mismo manejo de reembolsos que cancel_shipping_label. Los puntos de recompensa del cliente obtenidos en el pedido se revierten. Para anular solo la etiqueta y mantener el pedido abierto, usa cancel_shipping_label en su lugar.

Parámetro	Tipo	Obligatorio	Descripción
`order_id`	entero	Sí	El pedido a cancelar. Se aceptan pedidos en cualquier estado.
`confirm`	booleano	No	Omite o `false` para obtener una vista previa; nada cambia. `true` cancela el pedido.

Devuelve: Una vista previa devuelve preview: true, order_id, current_status (por ejemplo, "Etiqueta comprada"), would_void_label, would_reverse_reward_points, refund_note y note. Una llamada confirmada devuelve canceled: true, order_id, status ("Cancelado"), label_voided, postage_balance (tu saldo actual, no un crédito de esta llamada) y refund_note (nulo cuando no había etiqueta).

Bueno saber: Llámala una vez sin confirm para ver qué sucederá, luego otra vez con confirm: true. Una etiqueta no se anula una vez que el pedido está en tránsito, entregado o en proceso de devolución, o cuando la etiqueta tiene más de 29 días desde su fecha de envío; la etiqueta y el seguimiento permanecen en el pedido cancelado y no se emite ningún reembolso de franqueo. Para un pedido que ya se envió, la nota de reembolso puede describir esto como sin etiqueta para anular o como fuera de la ventana de anulación. Si el transportista rechaza la anulación, el pedido aún se cancela, label_voided es falso y no se pone en cola ningún reembolso; contacta a help@ship.com si esperabas uno. would_reverse_reward_points siempre es verdadero en una vista previa, incluso cuando el pedido no obtuvo puntos. La cancelación no se envía a las plataformas de venta conectadas; solo una etiqueta anulada envía una actualización de seguimiento. Cancela cada pedido una vez. Un pedido cancelado se puede importar nuevamente con create_order usando el mismo external_order_id.

{"order_id": 4821937, "confirm": true}

cancel_shipping_label

Cambia datosVista previa, luego confirmar

Anula una etiqueta de envío comprada y devuelve el pedido a Listo para enviar, para que puedas editarlo o volver a tarificarlo. Una etiqueta se puede anular dentro de los 29 días de su fecha de envío. El reembolso del franqueo no es inmediato: normalmente se acredita a tu saldo de franqueo de Ship.com unos 14 días después de la anulación, y está sujeto a que el transportista acepte la anulación.

Parámetro	Tipo	Obligatorio	Descripción
`order_id`	entero	Sí	El pedido cuya etiqueta se va a anular. Debe tener una etiqueta comprada.
`confirm`	booleano	No	Omite o `false` para obtener una vista previa; nada se anula. `true` anula la etiqueta.

Devuelve: Una vista previa devuelve preview: true, order_id, tracking_number, ship_date, within_void_window, shipping_cost, refund_note y note. Una llamada confirmada devuelve canceled: true, order_id, status ("Listo para enviar") y refund_note.

Bueno saber: Una etiqueta más allá de la ventana de 29 días devuelve un error en lugar de una vista previa. Cuando la anulación se realiza, el número de seguimiento, la etiqueta, la tarifa y el seguro se borran, y el seguro comprado con la etiqueta se anula. Los correos electrónicos de seguimiento no enviados a tu cliente que fueron activados por la etiqueta impresa se cancelan. El pedido sale de cualquier recogida programada, pero la recogida en sí permanece reservada. Si el pedido proviene de una plataforma de venta conectada que sincroniza el seguimiento, el cambio se envía allí. Cuando el reembolso vence, el costo de la etiqueta y cualquier tarifa de seguro se acreditan a tu saldo de franqueo, incluso si pagaste con tarjeta, y recibes un correo electrónico de confirmación. Si el transportista ha escaneado el paquete para entonces, no se emite ningún crédito y se restaura el número de seguimiento. Si el transportista rechaza la anulación, generalmente porque el paquete ya está en tránsito, nada cambia y no se pone en cola ningún reembolso. El transportista no da ninguna razón, y un reintento el mismo día puede ser rechazado nuevamente. Contacta a help@ship.com si la etiqueta debería haber sido reembolsable. Las etiquetas de devolución no son manejadas por esta herramienta.

{"order_id": 4821937, "confirm": true}

Tarifas, etiquetas y direcciones

Estas herramientas cotizan envíos, compran etiquetas y verifican direcciones. Un flujo típico: estima un costo con quote_shipping (no se necesita pedido), tarifica un pedido específico con get_rates, luego obtén una vista previa y confirma la compra con buy_label. validate_address verifica una dirección de EE. UU. por sí sola, y register_ups conecta UPS para que puedas comprar etiquetas de UPS. buy_label está disponible en conexiones con token de acceso; las otras cuatro funcionan en cada conexión y cada plan.

Los pesos siempre están en onzas y las dimensiones en pulgadas. El dinero está en dólares estadounidenses como números JSON simples. rate_id y package_id son tokens opacos largos (a menudo de 1 a 2 KB): pásalos de vuelta exactamente como los recibiste, y toma ambos de la misma respuesta de get_rates. Capturan el precio, servicio, paquete y dirección de envío en el momento en que tarificas. Si cambias la dirección, peso o dimensiones del pedido, vuelve a llamar a get_rates y usa los nuevos valores. Las tarifas de quote_shipping no se pueden comprar. Algunos problemas de tarificación se devuelven como errores incluso cuando los transportistas cotizaron opciones: una dirección de origen faltante o inválida ("La tarificación falló: la dirección de origen de la cuenta falta o es inválida. Corrígela en Configuración antes de tarificar o comprar etiquetas.") y, para get_rates, un destino que falló la validación de dirección o necesita una declaración de aduana. Cualquier otro problema que aún deje opciones cotizadas vuelve como un warning junto a las tarifas. Una advertencia siempre comienza con "La tarificación falló: ", incluso cuando es solo un aviso informativo del transportista como un recargo de UPS, así que léela antes de comprar.

quote_shipping

Solo lectura

Obtiene tarifas de envío para un destino sin un pedido, por ejemplo, para estimar cuánto costará un paquete. Cada llamada obtiene cotizaciones en vivo de los transportistas y omite la caché de tarifas de corta duración; los precios de Flat Rate siguen una lista de precios de USPS que se actualiza diariamente. Nada se guarda y no se mueve dinero. Para comprar una etiqueta necesitas un pedido: usa get_rates y buy_label.

Parámetro	Tipo	Obligatorio	Descripción
`zip`	cadena	Sí	Código postal de destino. Para destinos en EE. UU., envía un ZIP de 5 dígitos o ZIP+4 como cadena, conservando los ceros iniciales. Cualquier otro formato se tarifica como destino internacional, incluso cuando `country` es US.
`country`	cadena	No	Código de país de destino de dos letras. Predeterminado `US`. Cualquier otro país obtiene servicios internacionales de USPS y servicios UPS Worldwide.
`weight_oz`	número	Sí	Peso del paquete en onzas. Debe ser mayor que 0.
`length`	número	No	Largo en pulgadas, usado para precios dimensionales y cúbicos. Predeterminado: desconocido.
`width`	número	No	Ancho en pulgadas. Predeterminado: desconocido.
`height`	número	No	Alto en pulgadas. Predeterminado: desconocido.
`from_zip`	cadena	No	Código postal de origen. Predeterminado: la dirección de origen de tu cuenta. Cuando se establece, la cotización usa un origen de EE. UU. con solo este ZIP.

Devuelve: destination (zip y country, después del predeterminado de EE. UU.), weight_oz, rates y, cuando está presente, warning. Cada fila de tarifa tiene method (nombre para mostrar, como "USPS Ground Advantage"), rate_id, service_level (usps_ground_advantage, usps_priority, usps_priority_express, usps_intl_express, usps_intl_priority, usps_intl_first_class_package, o un código de servicio de UPS como "03" Ground, "01" Next Day Air, "02" 2nd Day Air, "93" Ground Saver o "11" Standard), rate (lo que paga tu cuenta, incluido cualquier cargo por etiqueta que tu plan agregue), retail_rate (precio minorista para comparar, o nulo), delivery_date (la estimación del transportista como fecha-hora ISO sin zona horaria; siempre nulo en filas de UPS), is_cubic, y variant y max_weight_oz (establecidos en filas de bandas de peso de Ground Advantage, como "hasta 12 oz" y 12; de lo contrario, nulos).

Bueno saber: Las filas vienen en un orden fijo: productos Priority Mail Flat Rate, luego Priority Mail, Priority Mail Express (mostrado como "USPS Express Mail") y Ground Advantage, luego las bandas de peso de Ground Advantage, luego los servicios internacionales de USPS, luego UPS. Las opciones que no cotizaron se omiten, y las filas similares no se fusionan: Ground Advantage puede aparecer dos veces, una como fila cúbica ("(Cubic)" o "(Cubic Soft Pack)" en method) y otra simple. Las filas de bandas de peso cuyo límite está por debajo de tu peso se descartan, y también todas las filas de bandas cuando un lado tiene más de 22 pulgadas o el volumen supera las 1,728 pulgadas cúbicas. Las filas de UPS pueden aparecer antes de que tu cuenta esté registrada con UPS, pero comprar una etiqueta de UPS requiere register_ups. Un peso sin dimensiones puede cotizar más bajo de lo que el transportista factura después, porque los cargos dimensionales vuelven como ajustes de franqueo, así que da dimensiones reales cuando las tengas. Un paquete por llamada, envío hoy, sin firma, entrega el sábado u opciones de tipo de paquete. Errores: "zip is required.", "weight_oz must be greater than 0.", el error de origen, o "La tarificación falló: " con el mensaje del transportista cuando nada cotizó.

{"zip": "30309", "weight_oz": 12, "length": 10, "width": 8, "height": 4}

get_rates

Cambia datos Obtiene las tarifas de envío para una de tus órdenes, utilizando la dirección de envío de la orden y tu dirección de origen. Devuelve un package_id y una lista de opciones con precio. Para comprar una, pasa el rate_id, method y service_level de esa opción, junto con el package_id, a buy_label exactamente como se devolvieron. Puedes anular el peso y las dimensiones del paquete.

Parámetro	Tipo	Obligatorio	Descripción
`order_id`	entero	Sí	La orden a cotizar. Debe pertenecer a tu cuenta.
`weight_oz`	número	No	Peso del paquete en onzas. El peso guardado en la orden no se usa para el precio, así que pásalo aquí (get_order lo devuelve como `totals.weight_oz`). Omítelo o envía 0 para una cotización sin peso (solo opciones de precio fijo). Un valor positivo obtiene una cotización completa y se guarda como el peso del paquete de la orden. Los valores negativos no se rechazan, así que envía solo pesos positivos. Valor predeterminado: 0.
`length`	número	No	Largo en pulgadas. Omítelo, o envía 0 o menos, para usar el largo guardado en la orden, si existe.
`width`	número	No	Ancho en pulgadas. Mismo respaldo que `length`.
`height`	número	No	Alto en pulgadas. Mismo respaldo que `length`.
`ship_date`	cadena	No	Fecha de envío como `YYYY-MM-DD`. Valor predeterminado: hoy. Un valor que no se pueda leer se convierte silenciosamente en la hora actual. buy_label usa su propio `ship_date` cuando compras.

Devuelve: order_id, package_id (un token opaco para buy_label), ship_date (fecha-hora ISO en UTC), rates (los mismos campos de fila que quote_shipping), un note que te recuerda pasar los valores elegidos a buy_label textualmente, y warning cuando esté presente.

Bueno saber: Sin un peso, obtienes solo las opciones de precio fijo: los seis productos de tarifa plana de Priority Mail y las cuatro bandas de peso de Ground Advantage, menos cualquier banda por debajo del peso guardado de la orden (una orden guardada por encima de 15.9 oz puede obtener solo filas de tarifa plana). Para ver Priority Mail, Priority Mail Express, Ground Advantage al peso real, UPS y servicios internacionales, pasa un weight_oz positivo. Los precios de cajas de tarifa plana y bandas de peso pueden servirse desde una caché de tarifas por hasta 3 horas, y los precios de tarifa plana siguen una lista de precios de USPS que se actualiza diariamente.

Nunca compra nada ni mueve dinero, pero como la cotización en la aplicación web de Ship.com, guarda en la orden: un weight_oz positivo se convierte en el peso del paquete de la orden, y para destinos en EE. UU., la dirección de envío se verifica con la validación de dirección del transportista y el resultado se almacena en la orden. Una dirección válida puede tener su ciudad y estado corregidos. No se guarda nada cuando el servicio de validación no está disponible. Está anotado como solo lectura en tools/list porque nunca compra.

Elige una fila de banda de peso de Ground Advantage solo si el paquete pesa no más que su max_weight_oz. La etiqueta se compra al peso de la banda y con un tamaño de caja estándar, por lo que un paquete más pesado o más grande se factura por la diferencia más tarde como un ajuste de franqueo. Las bandas que no caben se eliminan cuando se conocen el peso o las dimensiones; con ninguno conocido, las cuatro regresan. Las filas de UPS pueden aparecer antes de que tu cuenta esté registrada en UPS (comprar una requiere register_ups), y un destino de apartado postal obtiene solo UPS Ground Saver de UPS.

Una orden que no existe o no es tuya devuelve "Order <id> was not found in this account." Un destino que falla la validación de dirección devuelve "Rating failed: the destination address failed validation. Correct it with update_order_address before buying a label." (ver update_order_address). Los envíos que necesitan una declaración de aduana no se pueden cotizar ni comprar a través de MCP todavía: destinos fuera de EE. UU.; direcciones APO, FPO y DPO; territorios de EE. UU. y estados libremente asociados (Guam, las Islas Vírgenes de EE. UU., Samoa Americana, las Islas Marianas del Norte, Micronesia, las Islas Marshall y Palaos); y cualquier orden cuando tu propia dirección de origen es APO, FPO o DPO. Envía esos desde la aplicación web de Ship.com. Un paquete por orden por llamada, sin firma, entrega en sábado, etiqueta de devolución u opciones de paquete personalizadas.

{"order_id": 48213, "weight_oz": 14, "length": 10, "width": 8, "height": 4}

Respuesta (tokens acortados). package_id es compartido por cada fila; rate_id, method y service_level provienen de la fila que elijas. Las filas de banda de peso establecen variant y max_weight_oz:

{
  "order_id": 48213,
  "package_id": "eyJhbGciOi...",
  "ship_date": "2026-10-05T14:02:11Z",
  "rates": [
    {"method": "USPS Ground Advantage", "rate_id": "eyJhbGciOi...", "service_level": "usps_ground_advantage", "rate": 7.42, "retail_rate": 9.35, "delivery_date": "2026-10-08T00:00:00", "is_cubic": false, "variant": null, "max_weight_oz": null},
    {"method": "USPS Priority", "rate_id": "eyJhbGciOi...", "service_level": "usps_priority", "rate": 10.15, ...}
  ],
  "note": "Pass a chosen rate's rate_id + this package_id + its method + service_level verbatim into buy_label."
}

buy_label

Cambia datosGasta dineroVista previa, luego confirmarSolo conexiones con token de acceso

Compra una etiqueta de envío real de USPS o UPS para una orden, pagada desde tu saldo de franqueo. Pasa los valores de get_rates exactamente como se devolvieron. Sin confirm devuelve una vista previa del precio, tu saldo y si se ejecutaría una recarga automática, y no compra nada. Llama de nuevo con confirm: true para comprar.

Parámetro	Tipo	Obligatorio	Descripción
`order_id`	entero	Sí	La orden para la que comprar una etiqueta. Debe pertenecer a tu cuenta.
`rate_id`	cadena	Sí	El `rate_id` de la opción elegida. Decide lo que se compra: transportista, servicio, precio y paquete.
`package_id`	cadena	Sí	El `package_id` de la misma respuesta de get_rates.
`method`	cadena	Sí	El `method` de la opción, guardado en la orden como el nombre del método de envío. No cambia lo que se compra.
`service_level`	cadena	Sí	El `service_level` de la opción. No cambia lo que se compra.
`ship_date`	cadena	No	`YYYY-MM-DD`. Valor predeterminado: hoy; los valores ilegibles se convierten en hoy. Se rechaza una fecha de más de 24 horas en el pasado. Para USPS, la fecha de envío se mantiene entre hoy y 7 días adelante (hora del Este de EE. UU.).
`confirm`	booleano	No	`true` para comprar. Omítelo o `false` para una vista previa. Valor predeterminado: `false`.
`max_cost`	número	No	Tope en dólares para el precio del franqueo (seguros y tarifas no contados). Una tarifa más alta se rechaza, en vista previa y confirmación, antes de que se cobre algo. Una tarifa igual pasa.
`insurance`	booleano	No	Anula la configuración de asegurar-todos-los-envíos de tu cuenta para esta etiqueta. Valor predeterminado: esa configuración.
`insured_value`	número	No	Valor en dólares a asegurar cuando el seguro está activado. Valor predeterminado: el subtotal de mercancía de la orden, si no, su total. Sin un valor positivo para asegurar, la etiqueta se envía sin seguro.

Devuelve: Una vista previa devuelve preview: true, order_id, method, service_level, price (franqueo), pay_as_you_go_fee, insurance, insured_value, insurance_cost, total_charge, current_balance, balance_after, balance_would_go_negative, auto_recharge_amount, auto_recharge_would_fire y un message. Una compra devuelve purchased: true, order_id, cost (franqueo), insurance, insured_value, insurance_cost, label_url (Tamaño completo: una etiqueta de 4x6 en una página Carta de EE. UU.), tracking_number, tracking_url (https://app.ship.com/tracker/ más el número de seguimiento), form_url (un formulario de aduana cuando corresponde, de lo contrario nulo), balance_after, un message, status (el estado de la orden, normalmente "Label purchased") y next_step. Mientras la etiqueta no esté impresa, next_step dice marcarla como impresa una vez que se imprima, luego reservar una recogida si tu plan incluye recogida del transportista o dejarla; para una etiqueta de UPS apunta a la recogida de UPS pagada en la aplicación web de Ship.com. De lo contrario, es nulo.

Bueno saber: Disponible en conexiones con token de acceso. No se ofrece en conexiones autorizadas mediante el inicio de sesión de Ship.com (OAuth), como el conector del directorio de Claude y los conectores personalizados de claude.ai; allí está ausente de tools/list, y una llamada devuelve el error JSON-RPC -32602 diciendo que la herramienta no está disponible. La confirmación no necesita una vista previa anterior, y la vista previa no verifica package_id, límites del plan, facturación, fecha de envío, dirección o estado de la cuenta, por lo que una vista previa limpia aún puede fallar en la confirmación.

El franqueo sale de tu saldo de franqueo, más una tarifa de pago por uso de $0.30 cuando tu monto de recarga automática es de $0.01 o menos. El seguro es un cargo separado: $0.99 por cada $100, o parte de $100, del valor asegurado en órdenes a EE. UU. ($40 cuesta $0.99, $120 cuesta $1.98), y $1.25 por $100 de lo contrario. Si tu saldo no puede cubrir el franqueo y el seguro, se cobra tu método de pago registrado antes de crear la etiqueta, por el mayor entre tu monto de recarga automática y el déficit. Con un monto de recarga automática de $0.01 (pago por uso), el cargo es el déficit más $0.30, al menos $1, y el auto_recharge_would_fire de la vista previa aún lee falso. Con un monto de $0, la compra falla en su lugar. Una recarga permanece en tu saldo incluso si la compra luego falla, por ejemplo, en el límite mensual de envíos de tu plan.

En caso de éxito, la orden pasa a Label purchased con su número de seguimiento y etiqueta guardados. Pasa a Label printed cuando se imprime desde la página de Órdenes o la página de compra de un lote en la aplicación web de Ship.com. Las etiquetas impresas directamente desde label_url, o con imprimir-todo de Ship Mode, necesitan una llamada a mark_labels_printed una vez que se impriman. Las recogidas del transportista recogen solo etiquetas impresas (ver Pickups). Una orden que aún espera pago se marca como pagada fuera de Ship.com. El número de seguimiento se envía a la plataforma de ventas de la orden, como Shopify, Etsy, eBay, WooCommerce, Square, Squarespace, Wix o PayPal. Los correos electrónicos al cliente y los webhooks de seguimiento salen más tarde, cuando la etiqueta se marca como impresa. Tu formato de etiqueta guardado se establece en Tamaño completo. Si la orden ya tiene una etiqueta, esa etiqueta se devuelve y no se cobra nada; la respuesta aún muestra purchased: true, con cost de la tarifa que pasaste. Las compras simultáneas para una orden devuelven la primera etiqueta.

Errores: Un token que no se puede leer devuelve "rate_id is invalid or has expired. Call get_rates again and use a fresh rate_id." Una tarifa superior a max_cost devuelve "Refusing to buy: rate is $<price> which exceeds max_cost $<max>. Nothing was purchased." Los fallos de compra leen Label purchase failed — <Code>, a veces seguidos de : <detail>. Los códigos comunes:

Código	Significado	Qué hacer
`NeedsFromAddress`	Tu cuenta no tiene dirección de origen.	Agrega una en Configuración en la aplicación web de Ship.com.
`MissingBilling`	Tu saldo es demasiado bajo y no hay método de pago registrado.	Agrega un método de pago en la aplicación web.
`AutoRechargeOff`	Tu saldo es demasiado bajo y tu monto de recarga automática es $0.	Agrega fondos o establece un monto de recarga automática en la aplicación web.
`NeedPayment`, `ChargeFailed`	Se rechazó un cargo de tarjeta, o un pago de suscripción está vencido.	Actualiza tu método de pago en la aplicación web.
`CooldownNeeded`	Rechazos repetidos de tarjeta.	Espera 60 segundos, luego corrige la tarjeta antes de reintentar.
`Limit reached`	El límite mensual de envíos de tu plan; el detalle es el límite.	Mejora el plan, o espera al próximo mes.
`Unauthorized`	El `package_id` es de una respuesta de get_rates diferente que el `rate_id`.	Cotiza de nuevo y usa ambos valores de una sola respuesta.
`UPSError`	UPS no pudo crear la etiqueta, incluso cuando tu cuenta no está registrada en UPS.	Lee el detalle; ejecuta register_ups si no te has registrado.
`Suspended`	Tu cuenta está en espera por revisión.	Contacta a help@ship.com.
La vista previa no comprueba nada de esto. Si `balance_would_go_negative` es verdadero y `auto_recharge_amount` es 0, la confirmación fallará con `AutoRechargeOff` (o `MissingBilling` cuando no hay un método de pago registrado). Otros códigos, como `DateError`, `RateError` o `ShippingError`, vienen con un detalle que describe el problema, a menudo el mensaje propio del transportista. Una etiqueta que no se puede almacenar se anula automáticamente. Si un fallo indica que no es seguro si se compró una etiqueta, o si recibes un error inesperado, consulta get_label y get_balance antes de reintentar.

{"order_id": 48213, "rate_id": "<rate_id from get_rates>", "package_id": "<package_id from get_rates>", "method": "USPS Ground Advantage", "service_level": "usps_ground_advantage", "max_cost": 8.00}

{"order_id": 48213, "rate_id": "<same rate_id>", "package_id": "<same package_id>", "method": "USPS Ground Advantage", "service_level": "usps_ground_advantage", "max_cost": 8.00, "confirm": true}

validate_address

Solo lectura

Comprueba una dirección de EE. UU. con la validación de direcciones del transportista, la misma comprobación que Ship.com ejecuta en los pedidos, y devuelve una versión estandarizada. No guarda nada, así que úsalo para verificar una dirección antes de crear o actualizar un pedido. Solo direcciones de EE. UU.

Parámetro	Tipo	Obligatorio	Descripción
`street`	string	Sí	Línea 1 de la dirección, como "1600 Pennsylvania Ave NW". Se devuelve sin cambios.
`street2`	string	No	Segunda línea: apartamento, suite o unidad. Se devuelve sin cambios, o null si se omite.
`city`	string	Sí	Ciudad.
`state`	string	Sí	Código de estado de dos letras, como `DC`.
`zip`	string	Sí	Código postal de EE. UU. de 5 o 9 dígitos. Solo se usan los primeros 5 dígitos para la coincidencia.

Devuelve: is_valid (booleano), standardized (street, street2, city, state, zip) y, solo cuando is_valid es falso, un note. Cuando la dirección es válida, city, state y zip son los valores estándar del validador: la ciudad suele estar en mayúsculas y el código postal puede devolverse como ZIP+4 y puede diferir del que enviaste. Cuando no es válida, reflejan tu entrada.

Bueno saber: Una dirección es válida solo cuando hay una coincidencia única e inequívoca. Las líneas de dirección nunca se corrigen. is_valid: false significa que no existe ninguna coincidencia o que el servicio de validación no estuvo disponible brevemente; el resultado no indica cuál de los dos, así que reintenta más tarde una dirección que sepas que es correcta. Los campos faltantes se informan juntos, por ejemplo "street is required." o "city, zip are required." Para corregir la dirección guardada de un pedido, usa update_order_address.

{"street": "742 Evergreen Ter", "street2": "Apt 2", "city": "Springfield", "state": "IL", "zip": "62704"}

register_ups

Cambia datosVista previa, luego confirmar

Registra tu cuenta de Ship.com con UPS, lo cual es necesario antes de poder comprar etiquetas de UPS. Puede abrir una nueva cuenta de UPS o vincular una que ya tengas. El registro acepta el Acuerdo de Tecnología de UPS, un contrato legalmente vinculante con UPS Market Driver, Inc. Llámalo sin confirm para obtener el acuerdo y un token, muestra el acuerdo al titular de la cuenta y confirma con el token solo después de que lo acepte explícitamente. Un asistente de IA o una integración nunca debe aceptar en su nombre.

Parámetro	Tipo	Obligatorio	Descripción
`confirm`	booleano	No	Omítelo o usa `false` para obtener una vista previa; no se registra nada. `true` para registrar. Valor predeterminado `false`.
`accepted_agreement_token`	string	Con `confirm`	El `agreement_token` de la vista previa. Envíalo solo después de que el titular de la cuenta haya visto el acuerdo y lo haya aceptado.
`company`	string	No	Nombre comercial. Valor predeterminado: el nombre comercial de tu cuenta; si no, el nombre de contacto.
`name`	string	No	Nombre y apellido del contacto (al menos dos palabras; la última palabra es el apellido). Valor predeterminado: el nombre del titular de la cuenta.
`email`	string	No	Correo electrónico del contacto. Valor predeterminado: el correo de tu cuenta.
`phone`	string	No	Teléfono del contacto. Valor predeterminado: el teléfono de tu cuenta.
`street1`	string	No	Línea 1 de la dirección de recogida (solo se usa la línea 1). Valor predeterminado: la dirección de tu cuenta.
`city`	string	No	Ciudad. Valor predeterminado: la dirección de tu cuenta.
`state`	string	No	Código de estado de dos letras. Valor predeterminado: la dirección de tu cuenta.
`zip`	string	No	Código postal. Valor predeterminado: la dirección de tu cuenta.
`existing_ups_account`	string	No	Un número de cuenta UPS existente (exactamente 6 letras o dígitos) para vincular en lugar de abrir una cuenta nueva. UPS lo verifica primero sin costo: un número que UPS rechaza es denegado, y si UPS no puede dar una respuesta, se vincula de todos modos.
`existing_ups_postal_code`	string	No	El código postal que UPS tiene registrado para esa cuenta. Valor predeterminado: `zip`.

Devuelve: Una vista previa devuelve preview: true, registered (si la cuenta ya está registrada), note, agreement_version (como UTA10072022), agreement_token (64 caracteres hexadecimales), prefill (los detalles que se enviarían: company, name, email, phone, street1, city, state, zip, country "US"), missing_fields y, por último, agreement_text (el acuerdo completo como texto plano, de unos 71 KB). Una confirmación devuelve registered: true, ups_account_last3 (un número de cuenta enmascarado como ***2C3), agreement_version y un note.

Bueno saber: El token es específico de tu cuenta y solo proviene de una vista previa. Puede cambiar, por ejemplo cuando se actualiza el acuerdo, así que si una confirmación rechaza el token, haz una vista previa de nuevo. Los campos de contacto y dirección son obligatorios tanto si abres como si vinculas una cuenta; los faltantes se enumeran en missing_fields, y una confirmación sin ellos es rechazada. Abrir una cuenta nueva envía a UPS tu empresa, nombre de contacto, correo electrónico, teléfono, dirección y la dirección IP de la solicitud. No hay cargo. El registro no se puede deshacer a través de MCP, y una cuenta que ya está registrada es rechazada (la vista previa muestra registered: true). Las filas de UPS pueden aparecer en quote_shipping y get_rates antes de registrarte, pero comprarlas falla hasta que lo hagas. Solo direcciones de EE. UU. Los problemas del lado de UPS se devuelven como "UPS registration failed: " seguido del motivo.

{"confirm": true, "accepted_agreement_token": "<agreement_token from the preview>", "existing_ups_account": "A1B2C3", "existing_ups_postal_code": "30309"}

Recogidas

Estas herramientas reservan recogidas gratuitas de USPS, para que el transportista recoja tus paquetes con etiqueta impresa en lugar de que los dejes en un punto de entrega. Un flujo típico: marca las etiquetas que has impreso con mark_labels_printed, comprueba una fecha con check_pickup_availability, haz una vista previa y luego reserva con schedule_pickup, revisa con list_pickups y get_pickup, y cancela con cancel_pickup si los planes cambian. Reservar una recogida requiere un plan que incluya recogida del transportista; las otras cinco herramientas funcionan en todos los planes.

Imprime y marca primero. Una recogida solo recoge pedidos en estado Label printed. Las etiquetas compradas con buy_label o trigger_batch_purchase permanecen en Label purchased hasta que se marcan como impresas. En la aplicación web de Ship.com, imprimir desde la página de Pedidos o desde la página de compra de un lote marca una etiqueta, y también lo hace la ventana de envío al abrirla automáticamente (excepto para pedidos con formulario de aduanas). Las etiquetas impresas directamente desde label_url, o con la impresión total de Ship Mode, permanecen en Label purchased; llama a mark_labels_printed para esas antes de schedule_pickup. Aquí solo se reservan o cancelan recogidas gratuitas. Los paquetes con etiqueta de UPS nunca son recogidos por estas recogidas: una recogida de UPS es una visita paga separada que programas y cancelas en la aplicación web de Ship.com. Las recogidas pagas de UPS aún aparecen en list_pickups y get_pickup, con carrier "UPS" y un fee_amount. Las recogidas usan la dirección de recogida de tu cuenta, o tu dirección de envío si no has configurado una separada. Refiérete a una recogida por su pickup_id, no por el número de confirmación del transportista. Cada búsqueda de recogida se limita a tu propia cuenta, y un ID de otra cuenta recibe la misma respuesta de "was not found in this account" que uno que no existe. Envía las fechas solo como YYYY-MM-DD. Los nombres de transportista difieren según la herramienta: check_pickup_availability, schedule_pickup y cancel_pickup informan USPSDirect o MoveMethod (ambos son recogidas de USPS; trata el valor como informativo), mientras que list_pickups y get_pickup informan cada recogida gratuita como USPS/MoveMethod.

mark_labels_printed

Cambia datosEnvía correo electrónicoVista previa, luego confirmar

Marca las etiquetas compradas como impresas, igual que imprimirlas en la aplicación web de Ship.com. Los pedidos pasan de Label purchased a Label printed, que es lo que recoge una recogida del transportista. Llámalo después de buy_label o trigger_batch_purchase, una vez que las etiquetas estén realmente impresas. get_label proporciona los archivos: label_url, más form_url para pedidos internacionales, cuyo formulario de aduanas también debe imprimirse.

Parámetro	Tipo	Obligatorio	Descripción
`order_ids`	array de enteros	Esto o `batch_id`	Los pedidos cuyas etiquetas imprimiste, hasta 100. Los duplicados se ignoran; cada entrada debe ser un número entero.
`batch_id`	entero	Esto o `order_ids`	Un `batch_id` de trigger_batch_purchase o get_batch_status. Marca las etiquetas compradas pero sin imprimir de ese lote, hasta 100 por llamada; llama de nuevo para continuar.
`confirm`	booleano	No	Omítelo o usa `false` para obtener una vista previa; nada cambia. `true` marca las etiquetas como impresas.

Devuelve: Una vista previa devuelve preview: true, would_mark_count, would_mark_order_ids, already_printed_order_ids, skipped (cada uno con order_id, status y un reason), free_pickup_order_ids (etiquetas que una recogida gratuita recogerá una vez impresas), ups_order_ids, outside_pickup_window_order_ids, customs_form_order_ids (etiquetas con un formulario de aduanas que también debe imprimirse), not_found_order_ids (con order_ids), batch_id y remaining_unprinted_in_batch (con batch_id) y un note. Una llamada confirmada devuelve marked_count, marked_order_ids, already_printed_order_ids, skipped, failed (cada uno con order_id y un reason), not_found_order_ids, batches_marked_printed, free_pickup_eligible_count, status ("Label printed" cuando al menos un pedido fue marcado o ya estaba impreso, de lo contrario null), batch_id y remaining_unprinted_in_batch (con batch_id) y next_step: qué hacer a continuación, o null. Si quedan etiquetas sin imprimir en el lote, indica que primero termines de marcarlas: una recogida solo recoge etiquetas ya marcadas como impresas, y puedes reservar una recogida gratuita por fecha. De lo contrario, cuando una recogida gratuita recogería las etiquetas, sugiere schedule_pickup si tu plan incluye recogida del transportista, o dejarlas en un punto de entrega del transportista.

Marcar una etiqueta como impresa tiene los mismos efectos que imprimirla en la aplicación web. Cada cliente recibe tu correo de seguimiento Label Printed de tu cuenta aproximadamente una hora después, si tienes ese correo activado. Los webhooks de seguimiento de socios se activan, y también cualquier automatización configurada para ejecutarse cuando se imprime una etiqueta. Por eso primero se muestra una vista previa: confirma solo después de que las etiquetas estén realmente impresas. Por la misma razón, la herramienta está anotada como destructiveHint: true, para que tu cliente pueda preguntar antes de ejecutarla. No se mueve dinero. Bueno saber: Solo los pedidos en Etiqueta comprada con una etiqueta registrada cambian. Los pedidos que ya están en Etiqueta impresa se enumeran en already_printed_order_ids y se dejan en paz, por lo que repetir una llamada es seguro. Todo lo demás se omite con un motivo y nunca se mueve hacia atrás: pedidos cancelados o fusionados, pedidos sin etiqueta comprada (incluidas las etiquetas anuladas) y pedidos más allá de la impresión, como En espera de recogida, En tránsito o Entregado. Las etiquetas de UPS no se recogen con schedule_pickup; reserve la recogida de UPS pagada en la aplicación web de Ship.com. Una etiqueta cuya fecha de envío tiene más de 3 días, o que ya está en una recogida, no la recoge ninguna recogida de transportista, así que entréguela en persona. La llamada confirmada vuelve a verificar cada pedido, por lo que puede diferir de la vista previa. Un pedido fallido no detiene al resto; vuelva a llamar para los IDs en failed. Mientras las etiquetas de un lote aún se están comprando, ambas llamadas devuelven marked_count: 0 y una nota para consultar get_batch_status, y nada cambia. Funciona en todos los planes y todos los tipos de conexión. Los IDs que no son suyos se enumeran en not_found_order_ids; si ninguno es suyo, obtiene None of those orders were found in this account., y un lote desconocido devuelve Batch {batch_id} was not found in this account.. Enviar tanto order_ids como batch_id, o ninguno, devuelve un error.

{"order_ids": [48213, 48214]}
{"batch_id": 91544, "confirm": true}

check_pickup_availability

Solo lectura

Pregunta al transportista si puede recoger en su dirección de recogida en una fecha determinada. No reserva nada ni cambia nada en Ship.com. El transportista se elige de la misma manera que schedule_pickup, a partir de los paquetes con etiqueta impresa que recogería una recogida. A diferencia de la vista previa de schedule_pickup, también devuelve el motivo del transportista cuando una dirección no es elegible.

Parámetro	Tipo	Obligatorio	Descripción
`date`	string	Sí	La fecha de recogida que desea, como `YYYY-MM-DD`.

Devuelve: available (booleano), pickup_date (YYYY-MM-DD, o nulo), carrier (USPSDirect o MoveMethod) y error (la explicación del transportista cuando la recogida no está disponible; de lo contrario, nulo).

Bueno saber: Para USPS, el transportista habitual, una verificación exitosa significa que su dirección es elegible para la recogida del transportista. No reserva la fecha: USPS normalmente no devuelve una fecha propia, por lo que pickup_date repite la fecha que solicitó, y USPS acepta o rechaza la fecha cuando reserva. Si USPS sugiere una próxima fecha elegible, pickup_date es esa fecha y available es verdadero solo cuando cae en o antes de su fecha solicitada. Una dirección no elegible o un problema del transportista es un resultado normal, no un error: available: false, pickup_date: null y el texto del transportista en error. Ship.com no verifica fechas pasadas ni fines de semana; el transportista decide. Sin paquetes con etiqueta impresa en espera, o solo de UPS, normalmente verifica USPS Direct. Las etiquetas compradas pero no marcadas como impresas no cuentan; márquelas con mark_labels_printed primero. Funciona en todos los planes, incluidos los planes sin recogida del transportista. Una fecha faltante o ilegible devuelve date is required, formatted YYYY-MM-DD..

{"date": "2026-10-06"}

schedule_pickup

Cambia datosVista previa, luego confirmarRequiere: Recogida del transportista

Reserva una recogida gratuita del transportista en su dirección de recogida. Una recogida recoge todos los paquetes elegibles a la vez, y no puede elegir un subconjunto. Cada pedido recogido pasa a En espera de recogida. Los paquetes con etiqueta de UPS nunca se incluyen; reserve una recogida de UPS pagada en la aplicación web de Ship.com en su lugar.

Un paquete es elegible cuando su pedido está en Etiqueta impresa, no está ya en una recogida, no tiene una etiqueta de UPS y tiene una fecha de envío no anterior a hace 72 horas (las fechas de envío futuras cuentan). Los paquetes en un formulario SCAN califican de la misma manera. Un pedido cuya etiqueta se compró pero aún no se marcó como impresa permanece en Etiqueta comprada y no se recoge. La vista previa enumera esas etiquetas en unprinted_order_ids y lo indica en su nota; una vez impresas, márquelas con mark_labels_printed y vuelva a previsualizar. No hay límite en cuántos paquetes recoge una recogida.

Parámetro	Tipo	Obligatorio	Descripción
`date`	string	Sí	La fecha de recogida, como `YYYY-MM-DD`.
`location`	string	Sí	Dónde debe recoger el transportista los paquetes. Uno de `In/At Mailbox`, `Front Door`, `Back Door`, `Side Door`, `Knock on Door/Ring Bell`, `Mail Room`, `Office`, `Reception` o `Other`. No importan las mayúsculas, pero el texto debe coincidir exactamente, sin espacios adicionales. Use `Other` junto con `special_instructions` que describen el lugar. Se guarda tal como se envió.
`special_instructions`	string	No	Una nota para el transportista. Para recogidas de `USPSDirect`, los emojis y otros caracteres no ASCII se eliminan y la puntuación que no sea `- . , ' &` se convierte en un espacio antes de enviarse, porque USPS rechaza caracteres como `!` y `?`. Su cuenta conserva la nota tal como la escribió.
`confirm`	booleano	No	Omita o `false` para previsualizar; no se reserva nada. `true` reserva la recogida.

Devuelve: Una vista previa devuelve preview: true, would_schedule, pickup_date (su fecha solicitada), location, carrier, available, eligible_order_count, eligible_order_ids, ups_eligible_count (paquetes con etiqueta de UPS en espera que esta recogida no recogerá), already_scheduled_on_date, unprinted_label_count y unprinted_order_ids (etiquetas compradas que esta recogida recogería una vez marcadas como impresas) y un note. Una llamada confirmada devuelve scheduled: true, pickup_id (úselo con get_pickup y cancel_pickup), carrier_confirmation (el número de confirmación del transportista; rara vez nulo cuando el transportista no devuelve ninguno, y list_pickups muestra "0"), carrier, pickup_date, order_ids, order_count y status ("En espera de recogida", el nuevo estado de los pedidos recogidos).

Bueno saber: Su plan debe incluir recogida del transportista (Growth, Executive o Ultra). El plan se verifica primero, incluso para una vista previa, y de lo contrario obtiene Your current Ship.com plan does not include carrier pickup scheduling. Upgrade the subscription to use this tool.. Llame una vez sin confirm para ver qué se recogería, luego nuevamente con confirm: true. La llamada confirmada vuelve a verificar todo en ese momento, por lo que sus recuentos pueden diferir de la vista previa si los pedidos cambiaron en el medio. would_schedule es verdadero cuando hay paquetes elegibles y aún no hay recogida gratuita en esa fecha; no refleja available, y la vista previa no incluye el motivo del transportista, así que use check_pickup_availability para ver por qué. Puede tener una recogida gratuita por fecha; una segunda se rechaza hasta que cancele la primera. Una recogida de UPS pagada en la misma fecha no cuenta. Una reserva se ejecuta a la vez por cuenta. Una segunda llamada confirmada espera a que la primera termine y luego ejecuta sus propias verificaciones, por lo que un duplicado para la misma fecha se rechaza. Si la primera aún se está ejecutando después de unos 20 segundos, la segunda devuelve un error y no reserva nada. Sin nada elegible, la llamada confirmada devuelve No orders can be set to pickup.. Si hay etiquetas compradas pero sin imprimir en espera, ese error también enumera sus IDs de pedido para marcar como impresas: los primeros 100, luego cuántos más, ya que mark_labels_printed toma hasta 100 por llamada. Otros errores no incluyen la lista. Un rechazo del transportista, como una fecha inválida o caracteres que USPS no acepta, regresa palabra por palabra y no se reserva nada. Para reservar la visita, el transportista recibe sus datos de contacto, como su nombre, nombre comercial, correo electrónico y teléfono. Las recogidas son gratuitas: no se cobra nada a su saldo de franqueo o tarjeta, y Ship.com no envía correos electrónicos.

{"date": "2026-10-06", "location": "Front Door", "special_instructions": "Packages on the bench by the garage"}
{"date": "2026-10-06", "location": "Front Door", "special_instructions": "Packages on the bench by the garage", "confirm": true}

cancel_pickup

Cambia datosVista previa, luego confirmar

Cancela una recogida gratuita con el transportista. Cada pedido vinculado a la recogida vuelve a Etiqueta impresa y se desvincula de ella, por lo que una recogida posterior puede recogerlo. Las recogidas de UPS pagadas se rechazan tanto en la vista previa como en la llamada confirmada; cancele esas en la aplicación web de Ship.com, donde la tarifa se reembolsa a su saldo de franqueo.

Parámetro	Tipo	Obligatorio	Descripción
`pickup_id`	entero	Sí	El `pickup_id` de la recogida, de schedule_pickup, list_pickups o get_pickup. No es el número de confirmación del transportista.
`confirm`	booleano	No	Omita o `false` para previsualizar; nada cambia. `true` cancela la recogida.

Devuelve: Una vista previa devuelve preview: true, pickup_id, carrier_confirmation, pickup_date, status (el estado del transportista, como "programada" o "cancelada"), canceled, linked_order_count (pedidos actualmente vinculados, en cualquier estado) y un note. Una llamada confirmada devuelve canceled: true, pickup_id, carrier (USPSDirect o MoveMethod), reverted_order_ids, reverted_order_count y status ("Etiqueta impresa", el nuevo estado de esos pedidos).

Bueno saber: Llame una vez sin confirm para ver la recogida y cuántos pedidos se revertirían, luego nuevamente con confirm: true. La vista previa no contacta al transportista. Los pedidos cambian solo después de que el transportista confirme la cancelación; si el transportista se niega, su error regresa y la recogida permanece programada sin cambios. Cada pedido vinculado se restablece a Etiqueta impresa sea cual sea su estado actual, así que cancele solo recogidas que aún no han ocurrido. Una recogida ya cancelada se previsualiza normalmente, con la nota "Esta recogida ya está cancelada."; confirmarla devuelve Pickup {pickup_id} is already canceled. sin contactar al transportista. Un ID que no existe o pertenece a otra cuenta devuelve Pickup {pickup_id} was not found in this account.. Funciona en todos los planes. No se mueve dinero y Ship.com no envía correos electrónicos.

{"pickup_id": 51874, "confirm": true}

list_pickups

Solo lectura

Enumera sus recogidas más recientes, de la más nueva a la más antigua, incluidas las recogidas canceladas y las recogidas de UPS pagadas. Use el pickup_id de una fila con get_pickup para ver sus pedidos, o con cancel_pickup para cancelar una gratuita.

Parámetro	Tipo	Obligatorio	Descripción
`limit`	entero	No	Cuántas recogidas devolver, de 1 a 50. Predeterminado 10. Los valores fuera de ese rango se ajustan, no se rechazan.

Devuelve: pickups y count (las filas devueltas, no un total de cuenta). Cada fila tiene pickup_id, carrier_confirmation, date (YYYY-MM-DD), status (el texto de estado del transportista), canceled, created, location, special_instructions (como lo escribió, o nulo), carrier (USPS/MoveMethod para recogidas gratuitas, UPS para pagadas) y fee_amount (la tarifa de UPS cargada a su saldo de franqueo; nulo para recogidas gratuitas).

Bueno saber: Las filas se ordenan por cuándo se creó la recogida, no por fecha de recogida. No hay paginación, por lo que solo se pueden alcanzar sus 50 recogidas más recientes. El campo de fecha es date aquí pero pickup_date en las otras herramientas de recogida. created es una hora UTC sin designador de zona, como 2026-10-05T18:42:11.523. Las filas no incluyen pedidos. Lee solo los registros de Ship.com y no contacta al transportista. Funciona en todos los planes.

{"limit": 5}

get_pickup

Solo lectura

Devuelve una recogida y los pedidos vinculados a ella. Úselo para ver qué paquetes recogerá una recogida, o para verificar una recogida antes de cancelarla con cancel_pickup.

Parámetro	Tipo	Obligatorio	Descripción
`pickup_id`	entero	Sí	El `pickup_id` de la recogida, de schedule_pickup o list_pickups. No es el número de confirmación del transportista.
Devuelve: `pickup_id`, `carrier_confirmation`, `pickup_date` (`YYYY-MM-DD`), `status` (el texto de estado del transportista), `location`, `special_instructions`, `created`, `canceled`, `canceled_date` (nulo a menos que se cancele), `carrier` (`USPS/MoveMethod` para recogidas gratuitas, `UPS` para las de pago), `fee_amount` (la tarifa de UPS cobrada a tu saldo de franqueo; nulo para recogidas gratuitas), `orders` y `order_count`. `orders` enumera cada pedido vinculado a la recogida, con la fecha de pedido más reciente primero, cada uno con `order_id`, `status` (la etiqueta de visualización, como "Esperando recogida", "En tránsito" o "Entregado") y `tracking_number`.

Bueno saber: Una recogida cancelada normalmente muestra una lista orders vacía, porque la cancelación desvincula sus pedidos. created y canceled_date son horas UTC sin designador de zona. Una ID que no existe o pertenece a otra cuenta devuelve Pickup {pickup_id} was not found in this account., y una ID faltante devuelve pickup_id is required.. Solo lee los registros de Ship.com y no contacta al transportista. Funciona en todos los planes.

{"pickup_id": 51874}

Envíos por lotes y sincronización de plataformas

Estas herramientas manejan trabajo en volumen: traer pedidos nuevos de una tienda conectada y comprar etiquetas para muchos pedidos a la vez. Un flujo típico: revisa tus tiendas con list_connected_platforms, importa pedidos recientes con sync_platform_orders y sigue el trabajo con get_sync_status, luego previsualiza y confirma un lote con trigger_batch_purchase (solo conexiones con token de acceso) y síguelo con get_batch_status. Ambos tipos de trabajo se ejecutan en segundo plano, por lo que cada uno comienza con una llamada que devuelve una ID y termina con una herramienta de estado que consultas.

Cada solicitud cuenta para el límite de 60 solicitudes por minuto por token, incluyendo initialize y tools/list. Al consultar una herramienta de estado, espera unos segundos entre llamadas. Si superas el límite, obtienes HTTP 429 con Retry-After: 60. Los lotes y trabajos de sincronización están limitados a tu propia cuenta: una ID de otra cuenta se trata como si no existiera.

trigger_batch_purchase

Cambia datosGasta dineroPrevisualiza, luego confirmaRequiere: Envíos por lotesSolo conexiones con token de acceso

Compra etiquetas USPS Ground Advantage para muchos pedidos listos para enviar a la vez. Sin confirm cotiza cada pedido elegible y devuelve precios por pedido y un total de franqueo, sin comprar nada. Con confirm: true vuelve a cotizar los pedidos y pone el lote en cola. Un trabajador en segundo plano luego compra una etiqueta por pedido cotizado, generalmente en aproximadamente un minuto; síguelo con get_batch_status. Las etiquetas compradas no se marcan como impresas: una vez impresas, llama a mark_labels_printed con el batch_id para que una recogida del transportista pueda recogerlas.

Parámetro	Tipo	Requerido	Descripción
`order_ids`	matriz de enteros	No	Pedidos a incluir. Omítelo para incluir cada pedido Listo para enviar. Solo se usan pedidos en estado Listo para enviar con dirección postal; otras IDs (estado incorrecto, sin dirección, no encontrado) se omiten sin fila ni error. Las entradas que no se pueden leer como número entero, incluidos decimales como 12.0, se ignoran. Una matriz vacía, una matriz sin IDs utilizables o un valor que no sea una matriz también incluye cada pedido Listo para enviar.
`max_total`	número	No	Tope de gasto en dólares para el franqueo del lote (las primas de seguro no se cuentan). En una previsualización, superarlo establece `over_max_total: true`. Al confirmar, se verifica el total fresco y se rechaza el lote si es mayor. 0 o menos rechaza cualquier lote que cueste algo. Predeterminado: sin tope.
`weight_oz`	número	No	Peso de paquete de respaldo en onzas, usado solo para pedidos sin peso guardado. Los pedidos que tienen peso siempre cotizan con el suyo. Sin esto, un pedido sin peso obtiene un error por pedido.
`confirm`	booleano	No	Omítelo o `false` para previsualizar. `true` para poner el lote en cola de compra. Predeterminado `false`.
`insurance`	booleano	No	Anula la configuración de asegurar todos los envíos de tu cuenta para este lote. Cuando está activado, cada pedido se asegura por su total de pedido; los pedidos con total de $0 se envían sin seguro. Predeterminado: configuración de tu cuenta.

Devuelve: Una previsualización devuelve preview: true, orders, rated_count, failed_count, total_cost (franqueo para los pedidos cotizados), insurance, over_max_total, in_progress_batch (siempre null) y un note. Cada fila de pedido tiene order_id, name, city, state y ya sea rate, method ("USPS Ground Advantage", más " (Cubic)" o " (Cubic Soft Pack)" cuando aplica precio cúbico) y service_level (como usps_ground_advantage), o un error que explica por qué no se pudo cotizar, como peso faltante o dirección APO/FPO. Las filas se ordenan por nombre del destinatario. Una confirmación devuelve batch_id, requested_count (pedidos en cola), total_cost (franqueo de la cotización fresca), insurance y un note.

Bueno saber: Disponible en conexiones con token de acceso. No se ofrece en conexiones autorizadas mediante inicio de sesión de Ship.com (OAuth), como el conector de directorio de Claude y los conectores personalizados de claude.ai; allí está ausente de tools/list, y una llamada devuelve el error JSON-RPC -32602 indicando que la herramienta no está disponible. get_batch_status funciona en cada conexión. Nada vincula una confirmación a una previsualización anterior: la confirmación cotiza cada pedido desde cero, por lo que su total puede diferir, y los pedidos que fallan al cotizar se omiten sin listarse. Si ningún pedido se puede cotizar, la confirmación devuelve un error y no pone nada en cola. Para fijar tanto los pedidos como el gasto, confirma con el mismo order_ids y un max_total cercano al total previsualizado. Un lote puede estar en progreso por cuenta, incluidos lotes iniciados en la aplicación web de Ship.com; hasta que termine, la previsualización y la confirmación devuelven un error que nombra su ID de lote.

El dinero se mueve cuando el trabajador compra las etiquetas. El franqueo de cada etiqueta sale de tu saldo de franqueo, y las primas de seguro, cuando están activadas, se cobran además del total de franqueo y no están en la previsualización. Con recarga automática activada, si tu saldo no puede cubrir el franqueo del lote, tu método de pago registrado se cobra una vez por adelantado por el faltante o tu monto de recarga automática, lo que sea mayor; si ese cobro no se puede hacer porque no hay método de pago o la cuenta está suspendida, no se compran etiquetas. Si una etiqueta falla por razón de pago, el trabajador se detiene y marca los pedidos restantes como No intentado para evitar cobros repetidos. Cada etiqueta cuenta para el límite mensual de envíos de tu plan, que la previsualización no verifica. Un pedido que ya tiene etiqueta no se compra dos veces.

Cada llamada, incluida la previsualización, solicita una cotización USPS en vivo para cada pedido, por lo que los lotes grandes son lentos. No hay límite de tamaño de lote ni opción de servicio. Las etiquetas son paquetes sin firma, con fecha de envío cuando el lote se pone en cola, en tu formato de etiqueta guardado. La cotización, incluso en una previsualización, guarda la dirección del destinatario y el peso que usó (incluido un respaldo weight_oz) en cada pedido. La cotización por lotes no ejecuta validación de dirección; si un pedido falla al cotizar, prueba get_rates solo para ver la razón del transportista.

{"order_ids": [48210551, 48210554, 48210560], "max_total": 25.00, "weight_oz": 8}

{"order_ids": [48210551, 48210554, 48210560], "max_total": 25.00, "weight_oz": 8, "confirm": true}

get_batch_status

Solo lecturaRequiere: Envíos por lotes

Informa el progreso o resultado de una compra por lotes. Omite batch_id para obtener el lote en progreso, o tu lote más reciente si ninguno está en ejecución. Lee cada lote en tu cuenta, incluidos lotes iniciados en la aplicación web de Ship.com, y funciona en cada tipo de conexión.

Parámetro	Tipo	Requerido	Descripción
`batch_id`	entero	No	El `batch_id` de trigger_batch_purchase. Predeterminado: el lote en progreso, si no, el lote más reciente.

Devuelve: Mientras se compran etiquetas: complete: false, batch_id, requested, completed (pedidos intentados hasta ahora, incluidos fallos; 0 hasta que el trabajador comience) y un note. Cuando termina: complete: true, batch_id, orders, purchase_success, purchase_failed, requested, total (franqueo más seguro) y shipping_balance (tu saldo de franqueo). Cada pedido tiene order_id, name, city, state, shipping_cost (franqueo más seguro), tracking_number y status (como "Etiqueta comprada" o "Etiqueta impresa"), ordenados por fecha de pedido. unprinted_count dice cuántos están comprados pero aún no marcados como impresos; cuando está por encima de 0, next_step te indica llamar a mark_labels_printed con este batch_id una vez impresos. Si las etiquetas fallaron, failed_orders enumera cada order_id con un reason; los lotes más antiguos en cambio devuelven una cadena errors combinada y un indicador limit_reached. Una razón es un código corto, opcionalmente seguido de " - " y detalle, por ejemplo "Límite alcanzado - 100" cuando se alcanzó el límite mensual de envíos, o "No intentado -..." para pedidos omitidos después de que un problema de pago detuviera el lote. Sin lotes, o con un batch_id desconocido, obtienes no_status: true y un note como resultado normal, no un error.

Bueno saber: Requiere la misma característica de plan que trigger_batch_purchase, por lo que después de cambiar a un plan sin envíos por lotes no puedes leer lotes pasados aquí. orders y purchase_success cubren los pedidos del lote desde Etiqueta comprada hasta Entregado, por lo que los pedidos impresos, recogidos y enviados permanecen listados. Los pedidos cuya etiqueta fue anulada o que fueron cancelados salen, al igual que los pedidos en devolución, por lo que purchase_success más purchase_failed pueden no igualar requested. Un lote que se detuvo antes de comprar algo, por ejemplo porque el pago por adelantado no se pudo hacer, reporta complete: true sin pedidos ni detalle de fallo. Un lote cancelado también reporta complete: true; sus pedidos anulados salen de orders. Raramente, un lote que falló antes de que comenzara el procesamiento sigue reportando complete: false; si completed permanece en 0 durante varios minutos, verifica los pedidos con list_orders. Sin archivos de etiquetas aquí: usa get_label por pedido, y get_balance para tu saldo actual.

{"batch_id": 91544}

list_connected_platforms

Solo lectura

Enumera las plataformas de venta conectadas a tu cuenta, con el estado de cada conexión y la última hora de sincronización. Lee lo que Ship.com tiene almacenado y no contacta a las plataformas.

Sin parámetros.

Devuelve: platforms y count. Cada plataforma tiene name, status, error y last_sync. Solo aparecen plataformas conectadas, en este orden y escritas exactamente: PayPal, Bomb Party, Shopify, Etsy, Ebay, SquareSpace, Wix, TikTok, WooCommerce, Maverick, Walmart. status es usualmente Active, Issues o Disconnected, o una cadena vacía si nunca se estableció. error es un mensaje de error de conexión, actualmente reportado solo para Walmart y de otro modo null. last_sync es UTC, ISO-8601 sin desplazamiento, o null si la tienda nunca se ha sincronizado; WooCommerce muestra 0001-01-01T00:00:00 en lugar de null. Con nada conectado: platforms: [], count: 0. Ten en cuenta: Una entrada por plataforma, incluso si has conectado varias tiendas en ella. Las importaciones de Square, Jotform y de hojas de cálculo o correo electrónico no aparecen. Una tienda de Shopify que haya revocado el acceso de Ship.com aún puede aparecer, como Disconnected; reconéctala en Configuración → Integraciones antes de sincronizar. Lee last_sync junto con status: en una entrada de Shopify Disconnected puede ser el momento en que se encontró el problema en lugar de una sincronización exitosa.

sync_platform_orders

Cambia datos

Inicia una importación en segundo plano de pedidos recientes desde tu tienda conectada de Shopify o Etsy y regresa de inmediato con un job_id. Un trabajador de sincronización recoge el trabajo, generalmente en segundos; continúa con get_sync_status. La importación solo agrega pedidos que Ship.com aún no tiene, por lo que ejecutarla de nuevo es seguro.

Parámetro	Tipo	Obligatorio	Descripción
`platform`	string	Sí	`shopify` o `etsy`. No distingue mayúsculas de minúsculas; los espacios circundantes se ignoran. Cualquier otro valor, o ninguno, devuelve un error de "Plataforma desconocida".

Devuelve: job_id, platform (en minúsculas), status y un note que indica si se puso en cola un nuevo trabajo o se devolvió uno existente. status es siempre queued, incluso cuando el trabajo devuelto ya se está ejecutando.

Ten en cuenta: La plataforma ya debe estar conectada en Configuración → Integraciones; para Shopify, la conexión también debe estar activa, no desinstalada o revocada. Si ya hay una sincronización para esa plataforma en cola o en ejecución, incluida una iniciada fuera de MCP, como la importación que se ejecuta cuando conectas una tienda por primera vez, se devuelve ese trabajo en lugar de uno segundo. Shopify importa pedidos creados en los últimos 7 días (30 días si la tienda nunca ha completado una sincronización), además de nuevos clientes de la misma ventana. Etsy importa pedidos de los últimos 7 días. Los pedidos existentes de Ship.com no se modifican y no se escribe nada de vuelta a la tienda. Los pedidos recién importados pueden activar tus propias reglas de automatización para pedidos importados y ganar puntos de recompensa, como cualquier otra importación. Si la tienda ha revocado el acceso de Ship.com, la conexión de Shopify se marca como desconectada o se elimina la conexión de Etsy, y deberás reconectarla. No se mueve dinero ni se envía correo electrónico. En el raro caso de que el trabajo no se pueda poner en cola, recibirás "No se pudo poner en cola el trabajo de sincronización"; inténtalo de nuevo en un momento.

{"platform": "shopify"}

get_sync_status

Solo lectura

Comprueba tus trabajos de importación de pedidos en segundo plano. Pasa un job_id de sync_platform_orders para ver ese trabajo, u omítelo para listar tus 10 trabajos más recientes, del más nuevo al más antiguo.

Parámetro	Tipo	Obligatorio	Descripción
`job_id`	integer	No	El trabajo a consultar. Omítelo para listar trabajos recientes. Envía un número entero; un valor que no se pueda leer como número devuelve "job_id debe ser un entero."; un ID que no existe o pertenece a otra cuenta devuelve un error de no encontrado.

Devuelve: Con job_id, los campos de ese trabajo directamente (sin envoltorio): job_id, service, platform, status (queued, running, completed o error), queued, started, completed, error y last_sync. Sin él, jobs (hasta 10 de esos objetos) y count. Las horas están en UTC, ISO-8601 sin desfase; started y completed son null hasta que se alcanzan. error es el detalle de fallo en texto libre, o null. Para trabajos de Shopify y Etsy, platform es shopify o etsy y last_sync es la última hora de sincronización actual de la conexión, la misma en cada fila para esa plataforma en lugar de por trabajo. Para otros trabajos, platform repite el valor de service y last_sync es null.

Ten en cuenta: La lista cubre todo el trabajo de importación en segundo plano de tu cuenta, no solo Shopify y Etsy: las cargas de hojas de cálculo, los pedidos reenviados por correo electrónico, otras plataformas y las actualizaciones de seguimiento también aparecen. completed significa que el trabajo se ejecutó, no que llegaron pedidos; una importación que encontró un problema aún puede terminar como completed sin error. Para confirmar que los pedidos llegaron, verifica que last_sync avanzó y que la conexión sigue Active en list_connected_platforms, o lista tus pedidos. Un trabajo de Shopify o Etsy que aún se ejecuta unos 10 minutos después de comenzar, o uno que sufre un fallo temporal, se cierra con un error y se reintenta como un trabajo nuevo, hasta 5 veces por bloqueos. El texto del error nombra el ID del nuevo trabajo, por lo que una fila error puede tener un seguimiento más reciente encima. Un trabajo se marca como completed unos 10 segundos después de que su importación termina.

{"job_id": 73120458}

Clientes y correo electrónico

Estas herramientas trabajan con tu libreta de direcciones de clientes y te permiten contactar a los clientes por correo electrónico. Un flujo típico: encuentra a alguien con list_customers, lee sus detalles e historial de pedidos con get_customer, corrige sus datos de contacto o dirección con create_or_update_customer, luego escríbele con send_customer_email. Para campañas de recuperación, list_lapsed_customers encuentra clientes que no han pedido recientemente y send_mass_marketing_email envía correos a todo un segmento a la vez.

Enviar correos electrónicos es un flujo de dos pasos. Llama a una herramienta de envío sin confirm para previsualizarla (no se envía nada), luego llama de nuevo con "confirm": true para enviar. Los correos cuentan contra el límite de correos de marketing de tu plan, y cada herramienta aquí solo ve a tus propios clientes. Consulta Límite de correos de marketing y Marcadores de combinación.

list_customers

Solo lectura

Lista los clientes en tu libreta de direcciones de Ship.com, excluyendo los eliminados. Filtra por nombre o correo electrónico y ordena alfabéticamente o por pedido más reciente. Las filas son compactas; llama a get_customer para detalles completos e historial de pedidos. A diferencia de las herramientas de segmentos de correo, esta lista incluye clientes que no tienen dirección de correo electrónico.

Parámetro	Tipo	Obligatorio	Descripción
`query`	string	No	Filtro que no distingue mayúsculas de minúsculas. Coincide con clientes cuyo nombre o apellido comienza con el texto, o cuyo correo electrónico lo contiene. Solo un término: `"jane doe"` no se divide en nombre y apellido. No se buscan teléfono, ciudad ni empresa.
`sort`	string	No	`name` (predeterminado): por apellido, luego por nombre; los clientes sin apellido van al final. `recent`: clientes con los pedidos más nuevos primero, ignorando pedidos cancelados y combinados; los clientes sin pedidos van al final. Cualquier otro valor ordena por nombre.
`page`	integer	No	Número de página, comenzando en 1. Predeterminado 1.
`page_size`	integer	No	Filas por página, de 1 a 50. Predeterminado 25. Los valores fuera de ese rango se ajustan a él.

Devuelve: customers, cada uno con customer_id, name, email, phone, city y state (null cuando no está registrado); además page y page_size según se aplicaron, total (coincidencias en todas las páginas) y sort (la ordenación realmente utilizada).

Ten en cuenta: Una página más allá del final devuelve una lista customers vacía con el total real. Los clientes que empatan en el orden de clasificación no tienen un orden garantizado entre ellos.

{ "query": "jen", "sort": "recent", "page": 1, "page_size": 10 }

get_customer

Solo lectura

Devuelve el registro completo de un cliente: nombre, empresa, datos de contacto, cumpleaños, dirección postal, cantidad de pedidos y gasto de por vida, y sus pedidos más recientes.

Parámetro	Tipo	Obligatorio	Descripción
`customer_id`	integer	Sí	El ID del cliente, de list_customers.

Devuelve: customer_id, name, first_name, last_name, company, email, phone, birthday, address (street1, street2, street3, city, state, zip, country), order_count, total_spent y recent_orders. Cada pedido reciente tiene order_id, order_number, date, status (por ejemplo "Ready to ship", "Label printed", "In transit", "Delivered"), total y tracking_number.

Ten en cuenta: Ship.com almacena los cumpleaños solo con mes y día, por lo que birthday regresa con el año 1900 (por ejemplo "1900-04-12T00:00:00"); ignora el año. recent_orders lista hasta 20 pedidos, del más nuevo al más antiguo. order_count, total_spent y recent_orders omiten pedidos cancelados y combinados, pero incluyen pedidos que aún no se han enviado; el conteo y el total cubren cada uno de esos pedidos, no solo los 20 listados. order_number es null cuando un pedido no tiene número, y country es "US" cuando no se almacena ninguno. Un ID de cliente que no está en tu cuenta devuelve un error como Customer 482913 was not found in this account.

{ "customer_id": 482913 }

create_or_update_customer

Cambia datos

Agrega un cliente a tu libreta de direcciones o actualiza uno que ya tienes. Omite customer_id (o pasa 0) para crear un cliente; pasa el ID de un cliente existente para actualizarlo. Los cambios se aplican de inmediato, sin paso de confirmación.

Parámetro	Tipo	Obligatorio	Descripción
`customer_id`	integer	No	El cliente a actualizar. Omítelo o pasa 0 para crear un cliente nuevo. Los clientes eliminados no se pueden editar.
`first_name`	string	Sí	Nombre. No puede estar en blanco.
`last_name`	string	Sí	Apellido. No puede estar en blanco.
`email`	string	No	Dirección de correo electrónico. El formato no se verifica.
`phone`	string	No	Número de teléfono, almacenado tal como se proporciona.
`birthday`	string	No	Mes y día, mes primero, como `"04/12"` o `"4/12"`. No se almacena año. Debido a que el mes va primero, `"12/04"` es el 4 de diciembre. Un valor con año, una fecha con día primero como `"25/12"`, el 29 de febrero o una cadena vacía causa un error y no se guarda nada.
`street1`	string	No	Línea de dirección 1. Si está en blanco y `street2` está configurado, `street2` sube a la línea 1.
`street2`	string	No	Línea de dirección 2, como un apartamento o suite.
`street3`	string	No	Línea de dirección 3.
`city`	string	No	Ciudad.
`state`	string	No	Código de estado o provincia, como `"TX"`. Se verifica contra la lista de códigos del país. Un valor que no es un código válido (por ejemplo `"Texas"`) se descarta sin error, así que verifica `address.state` en el resultado.
`zip`	string	No	Código postal o ZIP. Envíalo como cadena para que se conserven los ceros iniciales.
`country`	string	No	Código de país de dos letras, como `US` o `CA`. Predeterminado `US`.
`company`	string	No	Nombre de la empresa.

Devuelve: customer_id (nuevo o existente), created (true cuando se agregó un cliente), name, email, phone, company, birthday, address, orders_updated y note. Los valores se devuelven tal como se almacenaron, después de la verificación del estado, la promoción de la línea 2 y el país predeterminado. orders_updated cuenta los pedidos cambiados para coincidir (siempre 0 al crear), y note los resume o es null. Bueno saber: Una actualización reemplaza todo el registro. Cualquier campo opcional que omitas se borra, y country vuelve a US. Para cambiar un campo, primero lee al cliente con get_customer y luego envía todos los campos de vuelta con tu cambio aplicado.

Cada actualización, incluso una que no cambia el nombre, también actualiza los pedidos del cliente que aún no tienen etiqueta y que todavía llevan el nombre que el cliente tenía antes de la actualización. Esos pedidos reciben el nuevo nombre, empresa, correo electrónico, teléfono y dirección del cliente, de modo que la siguiente etiqueta imprima los datos corregidos. Los campos que omitiste también se borran en esos pedidos, por lo que una actualización parcial puede eliminar su dirección de envío. Los pedidos con una etiqueta comprada, impresa o enviada nunca se modifican, y los pedidos con un nombre de destinatario diferente se dejan intactos.

Crear un cliente no verifica duplicados; crear a alguien que ya está en tu libreta de direcciones añade un segundo registro. Los nombres faltantes devuelven first_name and last_name are required., y un customer_id que no esté en tu cuenta devuelve el error de no encontrado descrito en get_customer.

{
  "customer_id": 482913,
  "first_name": "Jennifer",
  "last_name": "Alvarez-Reyes",
  "email": "jen.alvarez@example.com",
  "phone": "(512) 555-0142",
  "birthday": "04/12",
  "street1": "1208 Maple Ridge Dr",
  "street2": "Apt 4B",
  "city": "Austin",
  "state": "TX",
  "zip": "78704",
  "country": "US"
}

send_customer_email

Envía emailPreview, luego confirmRequiere: Correo de marketing

Envía un correo de marketing a uno de tus clientes, bajo tu nombre. Identifica al destinatario con customer_id o order_id; la dirección de correo proviene de ese cliente o pedido. El asunto y el mensaje pueden usar placeholders de combinación como {First Name}, completados para el destinatario.

Parámetro	Tipo	Obligatorio	Descripción
`customer_id`	entero	Uno de estos dos	El ID del cliente destinatario. Envía esto o `order_id`, no ambos.
`order_id`	entero	Uno de estos dos	Un pedido en tu cuenta, en cualquier estado. El correo va a la dirección del pedido; los pedidos guardados sin una dirección recurren a la dirección del cliente vinculado. Usar un pedido también completa placeholders de pedido como `{Invoice Number}`, `{Tracking Link}` y `{Order Total}`, y toma `{First Name}` y `{Last Name}` del nombre de destinatario del pedido.
`subject`	cadena	Sí	Línea de asunto. Admite placeholders de combinación.
`message`	cadena	Sí	Cuerpo del correo. Se permite HTML. Admite placeholders de combinación.
`confirm`	booleano	No	Omite o `false` para previsualizar; no se pone en cola nada. `true` envía el correo.

Devuelve: Una vista previa devuelve preview (verdadero), recipient_name, recipient_email, subject, limit_check y un note. Un envío confirmado devuelve queued (verdadero), recipient (name, email), subject y un note. El asunto se repite tal como lo escribiste, con placeholders aún sin completar. limit_check tiene allowed, reason, limit, used y message; los últimos cuatro son nulos cuando el envío está permitido (consulta Asignación de correo de marketing).

Bueno saber: La vista previa verifica el destinatario y tu asignación; no renderiza el correo. Con "confirm": true, se vuelven a ejecutar las mismas comprobaciones, luego el correo se pone en cola y sale aproximadamente un minuto después. Los placeholders se completan cuando el correo se pone en cola. No hay opción de programación en esta herramienta; usa send_mass_marketing_email con scheduled_at para envíos programados.

No se requiere una vista previa antes de "confirm": true, y no hay protección contra duplicados: confirmar dos veces envía dos correos. Ninguna herramienta cancela un correo en cola. Cada correo incluye un enlace de cancelación de suscripción, y las direcciones que se han dado de baja de los correos de marketing de Ship.com se omiten. Si tu configuración de correo te copia en los correos que envías, esto también aplica aquí.

Los errores incluyen Provide exactly one of customer_id or order_id to identify the recipient., subject and message are required., un error de no encontrado para un cliente o pedido que no esté en tu cuenta, y That recipient has no email address on file.. Si ese último aparece para un pedido cuyo cliente sí tiene correo, envía por customer_id en su lugar. Cuando tu asignación se agota, la llamada de confirmación se rechaza con el mensaje de asignación.

{
  "customer_id": 482913,
  "subject": "A little thank-you, {First Name}",
  "message": "<p>Hi {First Name},</p><p>Thanks for being such a loyal customer! Use code THANKS10 for 10% off your next order.</p><p>{Your Name}</p>",
  "confirm": true
}

send_mass_marketing_email

Envía emailPreview, luego confirmRequiere: Correo de marketing

Envía una campaña de correo de marketing a un segmento de tus clientes, o a toda tu lista de correos disponibles. Los filtros reducen la audiencia según el historial de compras. Esto envía correos reales y no se puede deshacer una vez que comienza el envío, así que siempre previsualiza primero y verifica el número de destinatarios.

Parámetro	Tipo	Obligatorio	Descripción
`filters`	matriz de cadenas	No	Filtros de segmento, aplicados en orden; cada uno reduce la lista. Valores permitidos: `"has purchased anything"`, `"has not purchased anything"`, `"has purchased product"`, `"has not purchased product"`. Omite para enviar a cada cliente con una dirección de correo.
`days`	matriz de enteros	No	La ventana de retroceso en días para cada filtro, emparejada por posición: `days[0]` va con `filters[0]`. Da un número positivo para cada filtro. Una entrada faltante cuenta como 0, lo que hace que `"has purchased anything"` no coincida con nadie y `"has not purchased anything"` coincida con todos.
`products`	matriz de cadenas	No	El producto para cada filtro `"...product"`, emparejado por posición. Coincidencia parcial sin distinción de mayúsculas en los nombres de los artículos pedidos, como `"lavender"`. Se ignora para los filtros `"...anything"`. Una entrada faltante o vacía coincide con cualquier artículo.
`subject`	cadena	Sí	Línea de asunto. Admite placeholders de combinación.
`message`	cadena	Sí	Cuerpo del correo. Se permite HTML. Admite placeholders de cliente; los placeholders de pedido no aplican a campañas.
`scheduled_at`	cadena	No	Cuándo enviar, en ISO 8601, como `"2026-10-06T15:00:00Z"`. Una hora sin desfase se lee como UTC. Predeterminado: ahora. Un valor que no se pueda leer también significa ahora, así que verifica `scheduled_for` en el resultado.
`confirm`	booleano	No	Omite o `false` para previsualizar; no se guarda nada. `true` crea la campaña.

Devuelve: Una vista previa devuelve preview (verdadero), recipient_count, sample (hasta 10 destinatarios, cada uno con name, email y last_purchase), subject, limit_check y un note. Un envío confirmado devuelve queued (verdadero), recipient_count, marketing_email_id (el ID de la campaña), scheduled_for (UTC) y un note.

Bueno saber: La audiencia son los clientes en tu libreta de direcciones que tienen una dirección de correo, uno por dirección. Cuando varios clientes comparten una dirección idéntica, se mantiene el más recientemente añadido; las direcciones con mayúsculas diferentes cuentan como distintas. Los clientes sin correo nunca se incluyen. Cualquier pedido cuenta como compra para los filtros, incluidos los cancelados.

Siempre pasa filters, days y products como matrices JSON, incluso para un solo filtro. Un valor que no sea una matriz se ignora, y también se ignora una cadena de filtro no reconocida. Los filtros ignorados no reducen nada, por lo que la campaña podría ir a toda tu lista. Verifica recipient_count en la vista previa antes de confirmar.

Al confirmar, el segmento se calcula de nuevo, por lo que el número puede diferir de la vista previa. La campaña se rechaza si nadie coincide o si superaría tu asignación de correo de marketing restante; no hay envíos parciales. La lista de destinatarios se fija al confirmar. Cada correo va a la dirección del cliente tal como está en el momento del envío, los clientes eliminados se omiten, y cada cliente recibe como máximo un correo por campaña. recipient_count puede incluir direcciones que se han dado de baja; se omiten al enviar.

No se requiere una vista previa antes de "confirm": true, y no hay protección contra duplicados: confirmar dos veces crea dos campañas. Ninguna herramienta cancela una campaña. Las campañas aparecen con tus otras campañas de correo en la aplicación web de Ship.com. Si tu configuración de correo te copia en los correos que envías, recibes una copia de cada correo de la campaña.

{
  "filters": ["has not purchased anything", "has purchased product"],
  "days": [90, 365],
  "products": ["", "lavender"],
  "subject": "We miss you, {First Name}!",
  "message": "<p>Hi {First Name},</p><p>It's been a little while! Our new lavender collection just landed. Take 15% off with code COMEBACK15.</p><p>{Your Name}</p>",
  "scheduled_at": "2026-10-06T15:00:00Z",
  "confirm": true
}

list_lapsed_customers

Solo lectura

Encuentra candidatos para recuperación: clientes que no han pedido en los últimos N días (60 por defecto). No envía nada y no usa tu asignación de correo de marketing. Combínalo con send_mass_marketing_email o send_customer_email para llegar a ellos.

Parámetro	Tipo	Obligatorio	Descripción
`days`	entero	No	Ventana de retroceso en días. Se listan los clientes sin pedidos en esta ventana. Predeterminado 60. Usa un número positivo.
`product`	cadena	No	Lista clientes que no han comprado este producto en la ventana en su lugar (coincidencia parcial sin distinción de mayúsculas en los nombres de los artículos pedidos). Los clientes que compraron otras cosas recientemente se incluyen, por lo que esto ya no es una lista puramente de inactivos.
`page`	entero	No	Número de página, comenzando en 1. Predeterminado 1.
`page_size`	entero	No	Filas por página, de 1 a 50. Predeterminado 20.

Devuelve: customers, cada uno con customer_id, name, email y last_purchase (la fecha de su pedido más reciente de cualquier tipo, o nulo); además count (filas en esta página), total (todas las coincidencias), page, page_size y days.

Bueno saber: Usa las mismas reglas de audiencia que send_mass_marketing_email: solo clientes con dirección de correo, uno por dirección, clientes añadidos más recientemente primero. Cualquier pedido cuenta como compra, incluidos los cancelados. total coincide con el recipient_count que una vista previa de campaña mostraría para el mismo segmento: ["has not purchased anything"] con days [N], o ["has not purchased product"] con los mismos días y producto. Para alcance por correo postal o teléfono, usa list_customers, que incluye clientes sin dirección de correo.

{ "days": 90, "page": 1, "page_size": 25 }

Asignación de correo de marketing

Ambas herramientas de envío cuentan contra la asignación de correo de marketing de tu plan. El uso mensual es el número de correos de marketing que tu cuenta ha enviado en el mes calendario actual (UTC). Un envío que superaría el límite se rechaza en su totalidad; no hay envíos parciales.

Plan	Correos de marketing
Starter, y planes antiguos ya no vendidos	No incluido
Growth	1,000 por mes
Executive	25,000 por mes
Ultra	Ilimitado
Prueba gratuita	10 en total para toda la prueba (el límite mensual del plan también aplica)

La asignación nunca bloquea una vista previa; la vista previa informa el resultado en limit_check. Cuando el envío está bloqueado, allowed es falso y reason y message dicen por qué; la llamada de confirmación se rechaza entonces con el mismo mensaje. Para trial_limit y tier_limit, limit y used muestran el límite y cuánto se ha usado; para no_entitlement son nulos.

`reason`	Mensaje
`trial_limit`	Has alcanzado el número máximo de correos de marketing permitidos durante tu período de prueba.
`tier_limit`	Has alcanzado el número máximo de correos de marketing permitidos con tu suscripción.
`no_entitlement`	Las campañas de correo de marketing no están incluidas con tu suscripción actual.

Placeholders de combinación

Los placeholders funcionan tanto en el asunto como en el mensaje. Escríbelos exactamente como se muestran, incluyendo mayúsculas, espacios y llaves; cualquier cosa no reconocida se deja tal como se escribió.

Marcador	Se rellena con
`{First Name}`	El nombre de pila del cliente, o "there" cuando no hay ninguno registrado. Al enviar por `order_id`: el nombre de pila de envío del pedido, o "Friend".
`{Last Name}`	El apellido del cliente (el apellido de envío al enviar por `order_id`).
`{Your Name}`, `{Business Name}`, `{Sign-Off}`	Tu nombre, el nombre de tu negocio (o tu nombre si no hay ninguno configurado) y tu firma de correo guardada.
`{Birthday}`, `{Birthday Short}`, `{Birthday Long}`, `{Birthday Month}`	El cumpleaños del cliente como 04/12, 4/12, 12 de abril o abril. Vacío cuando no hay cumpleaños registrado.
`{Reward Points Balance}`, `{Reward Points Remaining}`, `{Reward Points Required}`, `{Reward Text}`, `{Reward Icon}`	Detalles de tu programa de recompensas: el saldo de puntos del cliente, los puntos que aún necesita, los puntos requeridos para una recompensa, la recompensa en sí y tu ícono de recompensas.
`{Reward Message}`	Un resumen breve de recompensas. Se muestra solo en los planes Executive y Ultra con un programa de recompensas activo, para clientes con historial de puntos.
`{Invoice Number}`, `{Tracking Link}`, `{Order Quantity}`, `{Order Total}`, `{Order Date Short}`, `{Order Date Long}`, `{Reward Points Earned}`	Detalles del pedido. Se rellenan solo con send_customer_email y `order_id`. De lo contrario, `{Tracking Link}` muestra "Unknown", `{Order Total}` "$0.00", `{Order Quantity}` "0 items", y el resto quedan vacíos.

Cuenta, créditos e informes

Estas herramientas cubren el aspecto de dinero y plan de tu cuenta. Consulta tu saldo de franqueo con get_balance y lo que incluye tu plan con get_subscription_info. Mira a quién has referido con get_referral_info y transfiere el crédito de referidos a franqueo con redeem_referral_credit. Luego revisa el gasto, el impuesto a las ventas y las tendencias de envío con get_shipping_report, get_tax_report y get_shipping_analytics.

Las tres herramientas de informes requieren un plan que incluya informes comerciales, como Executive; Starter y Growth no lo incluyen. Siempre aparecen en tools/list, y el plan se verifica en cada llamada antes que los argumentos, por lo que una cuenta sin la función recibe este error sin importar lo que envíe: "Your current Ship.com plan does not include business reporting. Upgrade the subscription to use this tool." Verifica tier.features.business_reporting desde get_subscription_info primero. Cada herramienta aquí funciona solo en tu propia cuenta. El dinero está en dólares estadounidenses como números JSON simples, y las marcas de tiempo están en UTC sin sufijo de zona horaria.

get_balance

Solo lectura

Devuelve tu saldo de franqueo actual y tu configuración de recarga automática. Verifícalo antes de comprar etiquetas para explicar los costos y ver si una compra llevaría el saldo por debajo de cero. Con la recarga automática activada, esto repone el saldo desde el método de pago registrado.

Sin parámetros.

Devuelve: balance (saldo de franqueo en USD; puede ser negativo), currency (USD), auto_recharge_amount (el mínimo agregado cada vez que se repone el saldo), auto_recharge_enabled (true cuando auto_recharge_amount es mayor que 0.01) y note, un resumen de una línea sobre lo que significa la configuración de recarga automática para las compras de etiquetas.

Bueno saber: Este es el mismo saldo del que se descuentan las compras de etiquetas, por lo que coincide con lo que verá una compra. Cuando el monto es $0.01 (pago por uso), un faltante se cobra por compra más una tarifa de tarjeta de $0.30. En $0, la recarga automática está desactivada: la tarifa de $0.30 aún se aplica, y una compra que tu saldo no pueda cubrir falla. auto_recharge_enabled es falso en ambos casos.

get_subscription_info

Solo lectura

Devuelve tu plan con sus precios, límites y banderas de funciones, más tus pagos recientes de suscripción. Llámalo primero para verificar si una herramienta restringida por plan se ejecutará: business_reporting cubre las herramientas de informes en esta sección, batch cubre la compra por lotes y carrier_pickup cubre la programación de recogidas.

Sin parámetros.

Devuelve:

subscription_level: el plan registrado, como starter, growth o executive. Las cuentas más antiguas pueden mostrar un plan heredado, y es null cuando no hay ningún plan registrado.
is_annual: true para facturación anual; null cuando la cuenta no tiene registro de facturación de suscripción.
tier: name, month_price, annual_price (precio de año completo), month_shipment_limit y month_email_limit (-1 significa ilimitado), platform_integration_limit, y features, un conjunto de booleanos: batch, business_reporting, year_end_reporting, tracking, carrier_pickup, api_access, ai_features, custom_integrations, email_support, priority_email_support, phone_support, chat_support y dedicated_support.
note: presente solo cuando tier es null.
recent_payments: hasta 12 pagos de suscripción, del más reciente al más antiguo. Cada uno tiene date, reason, amount_due, amount_paid, refund (0 o un monto negativo), charge_id (la referencia de pago, o unknown), reference_id, status (Succeeded o Pending), failed_reason y note.

Bueno saber: Los planes heredados y las cuentas sin plan registrado devuelven tier: null con una nota de que las funciones y límites por plan no están disponibles; las herramientas restringidas por plan tratan esas cuentas como no autorizadas. subscription_level no refleja la cancelación, y no hay campo de cancelación. Solo batch, business_reporting y carrier_pickup deciden si las herramientas MCP se ejecutan; las otras banderas describen el plan, y api_access y ai_features no restringen el acceso a MCP. Los cargos fallidos se omiten, y varios registros de un solo cargo se combinan en una entrada, con cualquier reembolso totalizado en refund. En registros más antiguos, status puede ser null, y las entradas con charge_id unknown tienen un reference_id vacío. Sin paginación.

get_referral_info

Solo lectura

Devuelve tu saldo de crédito de referidos y todos los que has referido, incluidos sus datos de contacto, plan y lo que cada referido te ha ganado. Para gastar el saldo en franqueo, usa redeem_referral_credit.

Sin parámetros.

Devuelve: credit_balance (crédito de referidos en USD), currency (USD) y referrals, una entrada por cuenta referida con name, email (puede ser null), signup_date (cuando actualizaron, o cuando se registraron si no han actualizado), subscription_level (su plan, como growth), canceled (true si su cuenta está cancelada), has_paid (si el bono de referido único para ellos se ha pagado) y total_payments (crédito de referidos ganado de ellos; 0 si ninguno).

Bueno saber: referrals lista cada cuenta que has referido, incluidas las canceladas, en ningún orden particular, sin paginación; es una lista vacía si no has referido a nadie. name puede ser una cadena vacía cuando una cuenta referida tiene parte de su nombre faltante.

redeem_referral_credit

Cambia datosVista previa, luego confirmar

Mueve todo tu saldo de crédito de referidos a tu saldo de franqueo para que puedas gastarlo en etiquetas. Llámalo sin confirm para previsualizar los dos saldos, luego llámalo de nuevo con confirm: true para hacer el movimiento. Nunca cobra una tarjeta o cuenta bancaria.

Parámetro	Tipo	Requerido	Descripción
`confirm`	booleano	No	Omítelo o envía `false` para previsualizar; nada se mueve. Envía el booleano `true` para canjear todo el saldo de referidos. No hay parámetro de monto.

Devuelve: Una vista previa devuelve preview: true, referral_credit_balance, shipping_balance (tu saldo de franqueo) y un note. Una llamada confirmada devuelve redeemed (el monto movido), referral_balance_after (normalmente 0), shipping_balance_after (tu nuevo saldo de franqueo) y un note como "Moved $30.00 of referral credit into the postage balance."

Bueno saber: Siempre canjea todo el saldo; no se admite el canje parcial. La vista previa y la confirmación no están vinculadas, por lo que el monto movido es el saldo en el momento de confirmar, que puede diferir de la vista previa. Una vista previa con un saldo de $0 devuelve un error de que no hay nada que canjear. Raramente, $0 significa que el saldo no se pudo leer, así que inténtalo de nuevo más tarde si esperabas crédito. Confirmar con $0 tiene éxito con redeemed: 0 y no mueve nada. El movimiento no se puede deshacer a través de MCP, y aparece como crédito de referidos en get_shipping_report. Si una confirmación informa que el saldo de franqueo no aumentó, verifica ambos saldos con get_balance y get_referral_info antes de intentarlo de nuevo, y envía una confirmación a la vez.

{"confirm": true}

get_shipping_report

Solo lecturaRequiere: Informes comerciales

Devuelve tu gasto en envíos para un año calendario, desglosado por mes, más un total anual. Se construye a partir de la actividad de tu saldo de franqueo (cargos de etiquetas, créditos y recargas), no de pedidos.

Parámetro	Tipo	Requerido	Descripción
`year`	entero	Sí	Año calendario para informar, como `2026`. Los meses y el límite del año están en UTC.

Devuelve: year, months (una entrada por mes con actividad, en orden calendario) y total (todo el año). Cada entrada tiene estos campos:

Campo	Tipo	Significado
`date`	cadena	Una fecha en ese mes, `MM/dd/yyyy`; no siempre el día 1. `null` en el total.
`month`	cadena	Nombre del mes, como `January`. `TOTAL` en el total.
`shipments`	entero	Pedidos con al menos una entrada de saldo en el período que no esté marcada como cancelada, cada uno contado una vez.
`postage`	número	Franqueo de etiquetas, incluidas las tarifas de tarjeta de pago por uso, neto de créditos por etiquetas canceladas.
`returnPostage`	número	Franqueo de etiquetas de devolución.
`surcharge`	número	Recargo de First Class.
`upsAdjustments`	número	Ajustes netos de facturación de UPS.
`payments`	número	Recargas automáticas agregadas a tu saldo.
`refunds`	número	Créditos por etiquetas canceladas.
`pending`	número	Cargos de etiquetas cuya cancelación aún espera un reembolso.
`referral`	número o nulo	Crédito de referidos movido a franqueo; `null` cuando no hay ninguno.
`promotional`	número o nulo	Créditos promocionales; `null` cuando no hay ninguno.
`total`	número	Gasto neto: todos los cargos menos todos los créditos, sin contar las recargas automáticas.

Bueno saber: Dos claves están en camelCase, returnPostage y upsAdjustments, a diferencia del snake_case usado por otras herramientas. postage ya tiene refunds eliminado, y los cargos en pending ya están contados en los campos de cargos, así que no apliques ninguno de nuevo. Otra actividad de saldo también puede afectar total, por lo que puede no ser igual a la suma de los campos nombrados. El shipments del año cuenta cada pedido una vez, por lo que puede ser menor que la suma de los meses. Un año sin actividad devuelve una lista months vacía y un total de ceros, con referral y promotional null. Sin year la herramienta devuelve "year is required."

{"year": 2026}

get_tax_report

Solo lecturaRequiere: Informes comerciales Devuelve el impuesto sobre las ventas que recaudaste a través de facturas pagadas de Ship.com, totalizado por trimestre y por mes, en todos los años con facturas pagadas. Útil al presentar el impuesto sobre las ventas.

Sin parámetros.

Devuelve: taxes, un objeto cuyas claves son etiquetas de período y cuyos valores son el impuesto sobre las ventas recaudado en USD. Las claves de trimestre se ven como Q3 2026 y las claves de mes como September 2026. Las claves van del año más reciente al más antiguo; dentro de un año van de diciembre hacia atrás hasta enero, con cada trimestre justo antes de su último mes (Q4 2025, December 2025, November 2025, October 2025, Q3 2025,...). Solo aparecen los períodos con facturas pagadas, y taxes es {} cuando no hay ninguna.

Bueno saber: El impuesto se cuenta en el mes y trimestre en que se pagó la factura (UTC). Solo se incluyen pedidos con una factura pagada de Ship.com, por lo que los pedidos de plataformas de venta que no se facturaron a través de Ship.com no se incluyen. Una factura pagada aún cuenta si su pedido se canceló posteriormente. Cuando el mes actual tiene facturas pagadas, su clave y cada clave de trimestre del año actual terminan en To Date (por ejemplo October 2026 To Date y Q2 2026 To Date); cuando aún no tiene ninguna, ninguna clave lo hace. Lee el período desde el inicio de la clave y trata To Date como una etiqueta. No hay filtros de fecha.

get_shipping_analytics

Solo lecturaRequiere: Informes comerciales

Devuelve análisis de envío para un rango de fechas en una sola llamada: totales, volumen diario de pedidos, estados de pedidos, combinación de transportistas, principales destinos y canales de venta. Los pedidos se agrupan por el día en que se crearon (UTC). Sin fechas, cubre los últimos 90 días hasta hoy.

Parámetro	Tipo	Requerido	Descripción
`start_date`	string	No	Primer día del rango, `YYYY-MM-DD`, inclusivo. Predeterminado: 90 días antes de `end_date`.
`end_date`	string	No	Último día del rango, `YYYY-MM-DD`, inclusivo; se cuenta el día completo. Predeterminado: hoy (UTC). Debe ser el mismo día o posterior a `start_date`, y no más de 366 días después.

Devuelve:

start_date, end_date: el rango utilizado, YYYY-MM-DD.
totals: orders (cada pedido creado en el rango, cualquier estado), shipped (pedidos que actualmente tienen una etiqueta comprada) y postage_spent (los precios de las etiquetas en esos pedidos enviados).
daily_volume: {date, orders} por día, del más antiguo al más reciente. Los días sin pedidos se omiten.
status_distribution: {status, count}, usando los nombres de estado de la tabla de estados de pedidos (como ChooseShipping o Deleted), no las etiquetas de visualización.
carrier_mix: {carrier, count}. carrier es USPS, MoveMethod (etiquetas de USPS compradas a través de una segunda ruta de compra de Ship.com; cuéntalas como USPS), UPS, unshipped o other (etiquetas que no coinciden con ninguna de estas, como las muy antiguas).
top_destinations: hasta 10 entradas de {state, country, count} para el estado y país de envío más comunes. state está vacío cuando falta, y un país en blanco se lee como US.
sales_channels: {channel, count}, donde channel es la fuente del pedido según lo registrado, como Shopify, Etsy, Square o Jotform. Los pedidos creados a través de la API REST de Ship.com muestran un valor que comienza con API-, los pedidos sin fuente registrada muestran manual, y algunos pueden mostrar None.
truncated y note: presentes solo cuando el rango tuvo más de 100,000 pedidos. Solo se contaron los 100,000 más recientes; reduce el rango para números exactos.

Los estados, transportistas y canales se ordenan por recuento, de mayor a menor, con empates en orden de nombre; los destinos rompen empates por estado.

Bueno saber: No se aplica ningún filtro de estado, por lo que los pedidos cancelados y fusionados cuentan para cada total y desglose. list_orders, en contraste, filtra por estado. "Enviado" significa que el pedido tiene una etiqueta en este momento: anular una etiqueta mueve el pedido de vuelta a no enviado. Los destinos incluyen pedidos no enviados, porque usan la dirección de envío de cada pedido. El límite de 366 días permite hasta 367 días calendario, contando ambos extremos, y el rango predeterminado abarca 91 días. Errores: "end_date must be an ISO date (YYYY-MM-DD).", lo mismo para start_date, "end_date must be on or after start_date." y "The date range is too large — keep it to 366 days or fewer." Un start_date futuro sin end_date falla la verificación de mismo día o posterior.

{"start_date": "2026-07-01", "end_date": "2026-09-30"}

Cambios y soporte

Versiones y cambios

El servidor negocia la versión del protocolo MCP 2025-11-25 o 2025-06-18 durante initialize. Si solicitas cualquier otra versión, responde con 2025-11-25.
Ship.com puede agregar herramientas, agregar argumentos opcionales y campos de resultado, y mejorar las descripciones de herramientas y mensajes. Crea clientes que ignoren campos que no reconozcan.
tools/list es la fuente de verdad para las herramientas y esquemas de argumentos disponibles para tu conexión. El servidor no envía notificaciones de cambios en la lista, así que lee tools/list cada vez que te conectes en lugar de codificar el catálogo.
Esta página describe el servidor de producción en https://app.ship.com/mcp. Donde este y tools/list difieran, tools/list gana.

Tus datos

Una conexión solo puede ver y cambiar la cuenta de Ship.com a la que pertenece su token.
Ship.com registra el nombre, la hora y la duración de cada llamada de herramienta, y si falló. Solo para llamadas fallidas, también conserva el error y los argumentos enviados, para ayudar a solucionar problemas. Estos registros se eliminan después de unos 90 días. Los argumentos y resultados de llamadas exitosas no se almacenan en este registro.
Los tokens de acceso OAuth, tokens de actualización y códigos de autorización se almacenan solo en forma hash.
Los pedidos, etiquetas, recogidas y correos electrónicos creados a través de MCP son actividad normal de la cuenta y aparecen en la aplicación web de Ship.com como cualquier otro cambio.

Obtener ayuda

Envía un correo a help@ship.com. Para ayudarnos a encontrar el problema rápidamente, incluye el nombre de la herramienta, aproximadamente cuándo ocurrió (con zona horaria), si te conectas con un token de acceso o inicio de sesión OAuth, y el mensaje de error exacto. Nunca envíes tu token.

Conectar Claude	www.ship.com/api/claude
API REST	www.ship.com/api/overview
Política de privacidad	app.ship.com/privacy
Términos de servicio	app.ship.com/terms