Ship.com

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

Servidor MCP Ship.com

O servidor MCP Ship.com permite que assistentes de IA e agentes trabalhem com sua conta Ship.com: consultar pedidos, comparar tarifas, comprar etiquetas, agendar coletas e muito mais. Esta referência cobre como conectar qualquer cliente MCP, como funciona a autenticação e todas as ferramentas que o servidor oferece.

Visão geral

O servidor MCP Ship.com dá a assistentes de IA, IDEs e seu próprio código acesso a uma conta Ship.com por meio do Model Context Protocol. Ele oferece ferramentas para ler e criar pedidos, comparar tarifas, comprar e cancelar etiquetas, agendar coletas de transportadoras, gerenciar clientes, enviar e-mails para clientes e gerar relatórios de negócios. Cada chamada é executada sob as mesmas regras de conta, saldos e verificações de segurança do aplicativo web Ship.com.

Esta página é a referência neutra em relação ao cliente. Para configuração passo a passo no Claude, consulte Conecte o Claude ao Ship.com.

Endpoint	https://app.ship.com/mcp
Transporte	MCP Streamable HTTP. Envie cada solicitação JSON-RPC 2.0 como um corpo POST; cada resposta JSON-RPC é um único objeto application/json (notificações recebem HTTP 202 sem corpo). O servidor não faz streaming e nunca envia eventos server-sent.
Versões de protocolo	2025-11-25 (padrão) e 2025-06-18
Métodos	initialize, ping, tools/list, tools/call
Nome do servidor	ship-com

Quem pode usar

O acesso MCP está incluído em todos os planos Ship.com, incluindo o teste gratuito; não há um plano MCP separado. Você precisa de um login Ship.com e uma das duas credenciais abaixo. Algumas ferramentas também dependem do seu plano: agendamento de coleta de transportadora, compra de etiquetas em lote, relatórios de negócios e e-mail para clientes exigem um plano que inclua esse recurso. Essas ferramentas ainda estão listadas, e uma chamada explica claramente quando seu plano não as inclui. Consulte Recursos do plano.

Duas formas de conectar

	Token de acesso	Login OAuth
Funciona com	Qualquer cliente MCP que possa enviar um cabeçalho de solicitação: Claude Code, API Claude, Cursor, VS Code, Windsurf, scripts e plataformas de automação	Aplicativos web, desktop e mobile do Claude (conector personalizado ou diretório Claude), e Claude Code quando faz login em vez de usar um cabeçalho
Como autentica	Cabeçalho Authorization: Bearer com seu token de acesso Ship.com, copiado das Configurações	OAuth 2.1 com PKCE. Você faz login no Ship.com e aprova o aplicativo
Duração da credencial	180 dias	Tokens de acesso de 24 horas, renovados automaticamente. O aplicativo permanece conectado enquanto renovar pelo menos uma vez a cada 180 dias
Ferramentas	40, o catálogo completo	38
Compra de etiquetas	Sim: buy_label e trigger_batch_purchase	Não oferecido. Tarifas, cotações, cancelamentos, pedidos e coletas funcionam
Revogar	Substitua o token nas Configurações	Desconecte o aplicativo em Aplicativos conectados nas Configurações

Compra de etiquetas. Conexões feitas por login OAuth, incluindo o conector do diretório Claude e conectores personalizados do claude.ai, não oferecem compra de etiquetas. Elas ainda podem calcular tarifas e cotações, cancelar etiquetas, gerenciar pedidos e clientes e reservar coletas. As duas ferramentas de compra de etiquetas são oferecidas apenas em conexões que autenticam com um token de acesso Ship.com. O login OAuth do Ship.com atualmente aceita apenas clientes Claude, então outras ferramentas se conectam com um token de acesso. Detalhes estão em Autenticação.

Início rápido

1. Obtenha seu token de acesso.

1. Entre em app.ship.com, abra Configurações e escolha a aba Integração de API. Você também pode clicar em MCP na barra lateral esquerda.
2. Encontre o cartão Conecte o Ship.com ao seu assistente de IA. Em Conectar de outra ferramenta, clique em Mostrar minha chave de conexão. O cartão mostra a URL do servidor e um valor de Cabeçalho, Authorization: Bearer seguido pelo seu token. O Ship.com chama esse token de sua chave de conexão.
3. Para Claude Code, vá em Conectar do Claude, clique em Prefere Claude Code ou terminal? Use uma chave de conexão e depois em Gerar chave de conexão. O cartão mostra um comando pronto para executar com seu token incluído.

O cartão mostra quando o token expira ("Conexão válida até..."). Clicar em qualquer um dos botões novamente retorna o mesmo token enquanto ele for válido, então nunca quebra um cliente que você já configurou. Trate o token como uma senha: qualquer pessoa que o tiver pode agir em sua conta.

2. Adicione o Ship.com ao seu cliente. Use a configuração da sua ferramenta abaixo e substitua YOUR_TOKEN apenas pelo token: a parte do valor do Cabeçalho do cartão após Bearer , começando com OAUTH2.. Se você colar o valor inteiro do Cabeçalho (incluindo Authorization: Bearer) em um campo de cabeçalho, o servidor responde 401 invalid_token.

3. Experimente. Envie um pedido de ponta a ponta mostra um primeiro pedido, da cotação à coleta.

Claude Code

Execute o comando do seu cartão de Configurações, ou este com seu token preenchido:

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

Mantenha a parte --header para que o Claude Code use seu token de acesso. Sem ela, o Claude Code faz login via OAuth e obtém o conjunto de ferramentas OAuth (veja Ferramentas por tipo de conexão).

Adicione --scope user para disponibilizar o Ship.com em todos os projetos. Sem ela, o servidor é adicionado apenas ao projeto atual.

Cursor

Adicione o Ship.com a ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json em um projeto. Este exemplo lê o token de uma variável de ambiente SHIPCOM_TOKEN para que ele não fique no arquivo:

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

Defina SHIPCOM_TOKEN no ambiente a partir do qual o Cursor inicia (por exemplo, no seu perfil de shell e depois reinicie o Cursor). Se não estiver definida, o cabeçalho fica vazio e o servidor responde 401 missing_bearer_token.

VS Code

Adicione o Ship.com a .vscode/mcp.json no seu workspace, ou à sua configuração de usuário com o comando MCP: Open User Configuration. A entrada solicita o token quando o servidor inicia pela primeira vez, então ele não é gravado no arquivo:

{
  "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

Abra as configurações MCP do Cascade e edite o mcp_config.json bruto. O Windsurf usa serverUrl para servidores remotos. Como no Cursor, SHIPCOM_TOKEN deve estar definido no ambiente a partir do qual o Windsurf inicia, ou o servidor responde 401 missing_bearer_token:

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

Qualquer outro cliente MCP funciona da mesma forma: defina a URL do servidor como https://app.ship.com/mcp, escolha o transporte HTTP (Streamable HTTP) e envie o cabeçalho Authorization.

HTTP bruto (curl)

O servidor não tem estado: não há ID de sessão para carregar entre chamadas, e cada solicitação é autenticada individualmente. Envie Content-Type: application/json; incluir text/event-stream em Accept é inofensivo, pois as respostas são sempre JSON simples.

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":{}}}'

A resposta initialize (instruções 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 ..."}}

A resposta tools/call. O bloco de texto carrega o mesmo payload que structuredContent, formatado:

{"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}}

Uma mensagem notifications/initialized é aceita (HTTP 202, corpo vazio), mas não é obrigatória.

Autenticação

Toda solicitação que carrega um id JSON-RPC, incluindo initialize, precisa de um token bearer no cabeçalho Authorization. O Ship.com aceita dois tipos: um token de acesso Ship.com que você copia das Configurações, ou um token de acesso OAuth que um aplicativo obtém quando você faz login e o aprova. Tokens são aceitos apenas no cabeçalho, nunca na URL ou no corpo da solicitação.

Authorization: Bearer YOUR_TOKEN

Uma solicitação sem token válido recebe HTTP 401 com este desafio, que os clientes MCP usam para iniciar a descoberta OAuth:

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

Tokens de acesso

Seu token de acesso é a mesma credencial usada pela API REST Ship.com. No cartão MCP nas Configurações, ele é chamado de sua chave de conexão. A página Conecte o Claude chama a mesma credencial de seu código de acesso. É uma string longa que começa com OAUTH2.; apesar do prefixo, é um token bearer simples, não um token OAuth. Conexões que o usam obtêm o catálogo completo de 40 ferramentas, incluindo compra de etiquetas.

Obter	Configurações → Integração de API (ou MCP na barra lateral) → Mostrar minha chave de conexão ou Gerar chave de conexão. Veja o Início rápido. Você também pode obtê-lo no endpoint de token da API REST, documentado em Geração de Token.
Duração	180 dias a partir da emissão. O cartão mostra a data como "Conexão válida até...".
Reutilização	Enquanto seu token for válido, ambos os botões retornam o mesmo token. Clicar neles nunca substitui um token em funcionamento.
Após expirar	Chamadas recebem HTTP 401 expired_token. Abra o cartão novamente e clique em qualquer botão para obter um novo token válido por mais 180 dias e atualize seus clientes.

O que substitui seu token

Como MCP e API REST compartilham uma credencial, estas ações encerram o token antigo imediatamente para ambos. Qualquer cliente MCP que ainda o use recebe HTTP 401 invalid_token até que você forneça o novo:

• O botão Generate API Key mais abaixo na aba Integração de API. Ele emite um token totalmente novo e um refresh token.
• Atualizar o token pelo endpoint Token Refresh da API REST. Ele emite um novo token e aposenta o antigo.

Não há uma ação separada de "revogar" para tokens de acesso. Se um token for exposto, clique em Generate API Key para substituí-lo e atualize todos os clientes e integrações REST que o usavam.

Mantendo-o em segredo

• Qualquer pessoa com seu token pode agir em sua conta, incluindo comprar etiquetas do seu saldo de postagem. Trate-o como uma senha.
• Mantenha-o fora do controle de versão. Use uma variável de ambiente ou o prompt de segredo do seu cliente, como nos exemplos Cursor e VS Code.
• Chame o servidor da sua própria máquina ou backend. O endpoint recusa solicitações de navegador de outros sites, então não coloque o token em código de página web.

Login OAuth 2.1

Com OAuth, a pessoa faz login no Ship.com e aprova o aplicativo, e o aplicativo nunca vê a senha dela. O Ship.com é tanto o servidor de recursos quanto o servidor de autorização. Ele suporta o fluxo de código de autorização com PKCE (S256) para clientes públicos, sem client secret. Conexões autorizadas dessa forma obtêm 38 ferramentas; compra de etiquetas não é oferecida (veja Ferramentas por tipo de conexão).

Clientes suportados. O login atualmente aceita apenas clientes Claude: aplicativos web, desktop e mobile do Claude, o conector do diretório Claude e Claude Code. Outras ferramentas, mesmo as que suportam MCP OAuth, não conseguem concluir o login e devem se conectar com um token de acesso. Etapas de configuração para Claude estão em Conecte o Claude ao Ship.com.

Descoberta

Uma solicitação não autenticada para /mcp retorna HTTP 401 com o desafio resource_metadata mostrado acima. Ambos os documentos de metadados são JSON públicos e não precisam de token.

Metadados de recurso protegido (RFC 9728), em https://app.ship.com/.well-known/oauth-protected-resource e também em 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"]
}

Metadados do servidor de autorização (RFC 8414), em 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"]
}

Não há endpoint de registro, revogação ou introspecção, nem JWKS ou configuração OpenID Connect.

Registro de cliente

Opção	Como funciona
Cliente pré-registrado	client_id claude, usado pelos aplicativos hospedados do Claude. Seus URIs de redirecionamento são exatamente https://claude.ai/api/mcp/auth_callback e https://claude.com/api/mcp/auth_callback.
Documento de metadados do ID do cliente	O client_id é uma URL https cujo host é exatamente claude.ai ou claude.com. A Ship.com busca o documento diretamente (redirecionamentos não são seguidos, tempo limite de 8 segundos). Ele deve retornar HTTP 200 com um objeto JSON cujo client_id é igual à URL e cujo redirect_uris é uma lista não vazia. Os documentos são armazenados em cache por até 30 minutos. Um redirecionamento de loopback registrado http (localhost, 127.0.0.1 ou [::1]) corresponde em qualquer porta, desde que o esquema, host, caminho e consulta correspondam.
Registro dinâmico de cliente	Não suportado.

Os URIs de redirecionamento devem corresponder exatamente a um valor registrado, sem curingas.

Solicitação de autorização

Envie o navegador do usuário para GET https://app.ship.com/oauth/authorize com estes parâmetros de consulta:

Parâmetro	Valor
response_type	code (obrigatório)
client_id	Consulte Registro de cliente (obrigatório)
redirect_uri	Um URI de redirecionamento registrado (obrigatório)
code_challenge	BASE64URL(SHA-256(code_verifier)) (obrigatório)
code_challenge_method	S256 (obrigatório; plain é recusado)
state	Recomendado. Retornado inalterado no redirecionamento.
scope	Opcional. O único escopo é mcp:full, e ele é sempre concedido.

Se o usuário não estiver conectado, a Ship.com pede que ele faça login primeiro e, em seguida, mostra a tela de aprovação. Permitir redireciona para redirect_uri?code=...&state=.... Negar redireciona com error=access_denied. Um client_id desconhecido ou um redirect_uri que não corresponde mostra uma página de erro na Ship.com e não redireciona. Outros problemas redirecionam com error=unsupported_response_type ou error=invalid_request e um error_description. O código é de uso único, expira após 5 minutos e está vinculado ao client_id, ao redirect_uri exato e ao desafio de código.

Solicitação de token

POST https://app.ship.com/oauth/token com um corpo codificado em formulário (application/x-www-form-urlencoded). Os clientes são públicos: envie client_id no corpo e nenhum segredo de cliente.

Troque o código de autorização:

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 deve ser exatamente o valor usado na solicitação de autorização. code_verifier deve ter de 43 a 128 caracteres de A-Z a-z 0-9 - . _ ~.

Atualize:

grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=claude

Uma resposta bem-sucedida, para qualquer uma das concessões:

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

HTTP	error	Quando
429	slow_down	Mais de 30 solicitações de token por minuto de um único endereço IP. Aguarde Retry-After (60 segundos).
400	invalid_request	O corpo não está codificado em formulário, ou grant_type está ausente.
400	invalid_client	O client_id está ausente ou não é aceito.
400	unsupported_grant_type	Qualquer concessão diferente de authorization_code e refresh_token.
400	invalid_grant	O código ou token de atualização é inválido, expirado, já usado ou revogado; o redirect_uri não corresponde; ou a verificação PKCE falhou. A descrição é deliberadamente a mesma para cada caso.

Tempos de vida e rotação

• Tokens de acesso duram 24 horas. Um token expirado recebe HTTP 401 expired_token em /mcp; use o token de atualização.
• Tokens de atualização duram 180 dias e giram a cada uso. Cada atualização retorna um novo token de acesso e um novo token de atualização, válidos por mais 180 dias, e aposenta imediatamente o par antigo.
• Reutilização é tratada como roubo. Apresentar um token de atualização que já foi rotacionado, ou resgatar um código de autorização duas vezes, revoga todas as conexões que esse aplicativo tem com a conta. O usuário então precisa fazer login e aprovar novamente. Armazene o token de atualização mais recente antes de usar o novo token de acesso e não atualize o mesmo token de dois lugares ao mesmo tempo.
• Depois que um token de atualização expira, a atualização retorna invalid_grant e o usuário deve fazer login novamente.

Tela de aprovação e aplicativos conectados

A tela de aprovação nomeia o aplicativo, mostra qual conta da Ship.com está conectada e lista o que uma conexão da Ship.com pode fazer. A lista é a mesma para todos os aplicativos e descreve tudo o que uma conexão da Ship.com pode incluir; as ferramentas que uma conexão OAuth realmente recebe estão listadas em Ferramentas por tipo de conexão. O usuário escolhe Permitir ou Negar.

Os aplicativos aprovados aparecem em Aplicativos conectados em Configurações → Integração de API, com quando foram usados pela última vez (a data de conexão exibida é atualizada cada vez que o aplicativo renova seu login). Desconectar revoga o acesso desse aplicativo imediatamente: seus tokens param de funcionar (HTTP 401 invalid_token) e ele deve ser aprovado novamente para reconectar. Não há endpoint público de revogação de token; desconectar em Configurações, ou pedir ao suporte da Ship.com, é como o acesso é retirado.

Ferramentas por tipo de conexão

Conexão	Ferramentas	Não oferecidas
Token de acesso	40	Nenhuma
Login OAuth	38	buy_label, trigger_batch_purchase

Uma ferramenta que não é oferecida na sua conexão não aparece em tools/list, e chamá-la retorna o erro JSON-RPC -32602: "A ferramenta 'buy_label' não está disponível neste servidor. Chame tools/list para ver as ferramentas disponíveis." Conexões OAuth mantêm todas as outras ferramentas, incluindo classificação, cotação, cancelamento de etiquetas, cancelamento de pedidos, marcação de etiquetas como impressas, coletas e get_batch_status. Os recursos do plano não mudam a lista; eles são verificados quando uma ferramenta é chamada (consulte Recursos do plano).

Como as ferramentas se comportam

Estas regras se aplicam a todas as ferramentas. A referência de ferramentas cobre os parâmetros e resultados de cada ferramenta.

Formato do resultado

Um tools/call que chega a uma ferramenta sempre retorna um result JSON-RPC, mesmo quando a ferramenta recusa ou falha. O resultado tem uma de duas formas:

• Sucesso com dados: content contém um bloco de texto com o payload como JSON bem formatado, structuredContent contém o mesmo payload como um objeto, e isError é false.
• Mensagem: content contém um bloco de texto com uma mensagem em linguagem simples, sem structuredContent. Todo erro de ferramenta usa esta forma, com isError: true.

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

Erros de ferramenta cobrem argumentos ruins ou ausentes, registros não encontrados, recursos de plano que você não tem, recusas de negócio como um preço acima do seu max_cost, e mensagens de transportadora, que são repassadas palavra por palavra. Os argumentos são verificados por cada ferramenta em vez de contra inputSchema, então um argumento ausente retorna uma mensagem isError como "order_id é obrigatório." Um valor do tipo errado, como o texto order_number onde order_id espera um inteiro, retorna a mensagem geral de erro inesperado. IDs são sempre o inteiro order_id, pickup_id, batch_id ou job_id, nunca números de exibição. As mensagens são escritas para serem mostradas ao usuário ou agidas pelo assistente. Um error JSON-RPC é reservado para problemas de protocolo; consulte Erros.

Registros fora da sua conta nunca são visíveis. Uma mensagem de não encontrado lê o mesmo, quer o registro não exista ou pertença a outra pessoa.

Visualizar, depois confirmar

Ferramentas que gastam dinheiro, enviam e-mail, cancelam algo ou aceitam um acordo funcionam em duas etapas, controladas por um argumento booleano confirm:

1. Visualizar. Chame a ferramenta sem confirm (ou com false). Nada é comprado, cobrado, anulado, agendado ou enviado. (Uma exceção a "nada muda": uma visualização de trigger_batch_purchase classifica cada pedido e salva o peso e o endereço que usou, o mesmo que get_rates.) O resultado inclui "preview": true, o que aconteceria (preços, saldos, destinatários, pedidos afetados) e um note sobre como proceder (buy_label o chama de message).
2. Confirmar. Mostre a visualização ao usuário. Depois que ele concordar, repita a mesma chamada com "confirm": true.

A Ship.com não guarda nada entre as duas chamadas. A maioria das ferramentas relê tudo na confirmação, então o resultado reflete o momento em que você confirma. buy_label é a exceção: ela cobra o preço selado no rate_id que você obteve de get_rates. Esse token é assinado pela Ship.com e não pode ser editado, então o preço ainda nunca vem do cliente. O servidor não exige uma visualização antes de uma confirmação, então visualizar primeiro fica a cargo do cliente. Envie confirm como um booleano JSON.

Ferramentas de duas etapas	Gravações de etapa única (entram em vigor imediatamente)
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 é mais rigoroso. Sua visualização retorna o Acordo de Tecnologia completo da UPS e um agreement_token, e a chamada de confirmação deve enviar esse token de volta. O usuário deve ler e aceitar o acordo por conta própria; um assistente nunca deve aceitá-lo em nome dele.

Cada ferramenta em tools/list carrega annotations com um title e readOnlyHint. Ferramentas de gravação também carregam destructiveHint. Isso é verdade para toda ferramenta de gravação, exceto create_order, bulk_create_orders e sync_platform_orders, que apenas adicionam novos registros. mark_labels_printed conta como destrutiva porque confirmar envia e-mails aos seus clientes. Os clientes MCP usam essas dicas para decidir quando perguntar ao usuário antes de executar uma ferramenta. get_rates é marcada como somente leitura, mas pode salvar o peso que você passa e os resultados da verificação de endereço no pedido.

Segurança do dinheiro

Apenas duas ferramentas gastam dinheiro, buy_label e trigger_batch_purchase, e ambas são oferecidas apenas em conexões de token de acesso. Aqui está de onde vem o dinheiro:

• Saldo de postagem primeiro. As etiquetas são pagas com o saldo de postagem da sua conta Ship.com. buy_label adiciona uma taxa de pagamento conforme o uso de $0,30 por etiqueta quando o valor de recarga automática é $0,01 ou menos. O seguro de envio, quando ativado, é cobrado além da postagem.
• Recarga automática. Se o seu saldo não cobrir postagem e seguro, o que acontece depende do valor de recarga automática. Acima de $0,01, o método de pagamento cadastrado é cobrado pelo maior valor entre esse valor e a diferença antes da etiqueta ser criada. Em $0,01 (pagamento conforme o uso), é cobrada a diferença mais a taxa de $0,30, no mínimo $1. Em $0, a compra falha. Esses fundos permanecem no seu saldo mesmo se a compra falhar. Um lote é recarregado uma vez, antes de qualquer etiqueta ser comprada.
• Prévias mostram o custo. A prévia de buy_label retorna total_charge, current_balance, balance_after e auto_recharge_would_fire. A prévia de lote retorna preços por pedido e um total_cost de postagem.
• Limites de preço. Passe max_cost para buy_label ou max_total para trigger_batch_purchase. Um preço acima do limite é recusado e nada é cobrado. Ambos os limites cobrem apenas postagem, não taxas ou seguro.
• Sem compras duplicadas. Se um pedido já tem uma etiqueta, buy_label retorna essa etiqueta e não cobra nada. A resposta ainda lê purchased: true, então verifique get_label primeiro quando não tiver certeza.
• Lotes rodam em segundo plano. Um lote confirmado é colocado na fila, e suas etiquetas geralmente são compradas em cerca de um minuto. Acompanhe com get_batch_status. Apenas um lote pode rodar por vez.
• Reembolsos vão para o saldo de postagem. Anular uma etiqueta (cancel_shipping_label, ou cancel_order em um pedido não enviado) credita seu saldo de postagem assim que a transportadora aceitar a anulação, normalmente em cerca de 14 dias, se o pacote nunca foi escaneado. Reembolsos são creditados no saldo de postagem, não em um cartão.
• Todo o resto é grátis. Coletas agendadas com schedule_pickup não custam nada, e redeem_referral_credit move crédito de indicação para postagem sem cobrar um cartão. Para adicionar fundos ou alterar a recarga automática, use o aplicativo web Ship.com.

E-mails enviados com send_customer_email e send_mass_marketing_email são reais e não podem ser lembrados, então trate-os com o mesmo cuidado.

Recursos do plano

Toda ferramenta está listada em todos os planos. Algumas verificam um recurso do plano quando chamadas e recusam com uma mensagem isError se seu plano não o incluir (as ferramentas de e-mail ainda pré-visualizam e relatam o resultado em limit_check):

Recurso	Ferramentas	Incluído em	Mensagem sem ele
Coleta de transportadora	schedule_pickup	Atualmente Growth, Executive, Ultra	"Seu plano Ship.com atual não inclui agendamento de coleta de transportadora. Atualize a assinatura para usar esta ferramenta."
Envio em lote	trigger_batch_purchase, get_batch_status	Atualmente Growth, Executive, Ultra	"Seu plano Ship.com atual não inclui compra de etiquetas em lote. Atualize a assinatura para usar esta ferramenta."
Relatórios de negócios	get_shipping_report, get_tax_report, get_shipping_analytics	Atualmente Executive, Ultra	"Seu plano Ship.com atual não inclui relatórios de negócios. Atualize a assinatura para usar esta ferramenta."
E-mail de marketing	send_customer_email, send_mass_marketing_email	Atualmente Growth e Executive (cota mensal), Ultra (ilimitado); testes têm um limite separado. Veja Cota de e-mail de marketing	O limit_check da prévia mostra allowed: false e reason: "no_entitlement"; confirmar é recusado com "Campanhas de e-mail de marketing não estão incluídas na sua assinatura atual."

O conteúdo do plano pode mudar; get_subscription_info mostra o que seu plano inclui hoje.

Os recursos seguem o plano atualmente selecionado na sua conta. Uma conta sem plano selecionado ainda, ou em um plano antigo que não é mais vendido, é tratada como não os incluindo. Chame get_subscription_info para verificar: tier.features mostra carrier_pickup, batch e business_reporting. Cancelamento de coleta, consultas de coleta e todas as outras ferramentas não têm requisito de plano. As cotas de e-mail são cobertas em Cota de e-mail de marketing.

As compras de etiquetas também seguem o limite mensal de envios do seu plano, se houver. Além do limite, buy_label retorna "Falha na compra de etiqueta — Limite atingido: " seguido do limite.

Erros

Os erros vêm de três camadas. Problemas de autenticação, origem e limite de taxa são respostas HTTP simples com um corpo JSON {"error": "...", "message": "..."}, não JSON-RPC. Cada 401 também carrega o desafio WWW-Authenticate descrito em Autenticação.

HTTP	error	Significado
401	missing_bearer_token	Sem cabeçalho Authorization: Bearer, ou um vazio.
401	invalid_token	O token não é reconhecido: foi substituído, ou o aplicativo foi desconectado. Também retornado quando a conta do token não existe mais, e quando o valor do cabeçalho é malformado, por exemplo Bearer Authorization: Bearer ....
401	expired_token	O token expirou. Atualize um token OAuth, ou obtenha um novo token de acesso nas Configurações.
401	invalid_information	A solicitação não pôde ser autorizada. Contate help@ship.com se você acredita que isso é um erro.
403	forbidden_origin	A solicitação veio de uma página de navegador em um site que a Ship.com não permite. Solicitações sem cabeçalho Origin, como chamadas do lado do servidor, não são afetadas.
429	rate_limited	Mais de 60 solicitações em um minuto para este token. Veja Limites de taxa.
405		GET em /mcp (corpo de texto simples). Apenas POST é suportado, e não há fluxo de eventos enviados pelo servidor.
202		Não é um erro: uma notificação (uma mensagem sem id) foi aceita. Nunca é respondida.

Problemas de protocolo retornam HTTP 200 com um objeto JSON-RPC error contendo code e message:

Código	Significado
-32700	O corpo está vazio ou não é JSON válido.
-32600	Solicitação inválida: o corpo não é um único objeto JSON (arrays de lote não são suportados), ou method está ausente.
-32601	Método desconhecido. Métodos suportados são initialize, ping, tools/list e tools/call; nomes diferenciam maiúsculas de minúsculas.
-32602	tools/call não tem ferramenta name, nomeia uma ferramenta que não existe (nomes diferenciam maiúsculas de minúsculas), ou nomeia uma ferramenta não oferecida nesta conexão.
-32603	Um erro inesperado no lado da Ship.com. Tente novamente e contate help@ship.com se continuar.

Tudo o que acontece dentro de uma ferramenta, incluindo recusas de plano e falhas, é um resultado com isError: true (veja Formato de resultado). Se uma ferramenta encontrar um erro inesperado, sua mensagem diz se algum trabalho pode ter sido salvo. Releia o estado atual, por exemplo com get_order, get_label ou get_balance, antes de tentar novamente qualquer coisa que gaste dinheiro.

Limites de taxa

• Endpoint MCP: 60 solicitações por minuto por token. A janela reinicia no início de cada minuto (UTC). Cada solicitação autenticada conta, incluindo initialize e tools/list; notificações não contam. Acima do limite, você recebe HTTP 429 com Retry-After: 60. Cada token tem sua própria cota, então um token OAuth atualizado começa uma contagem nova.
• Endpoint de token OAuth: 30 solicitações por minuto por endereço IP, também com Retry-After: 60.
• Os limites de negócios são separados: as cotas mensais de envios e e-mails do seu plano, e um lote por vez.

Convenções compartilhadas

• Exemplos: o exemplo de cada ferramenta abaixo é o objeto arguments. Envie-o como {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_rates","arguments":{...}}}. Veja Envie um pedido de ponta a ponta.
• Nomes: argumentos e campos de resultado usam snake_case.
• Tipos: envie tipos JSON reais: inteiros para IDs, booleanos para confirm, números para dinheiro e pesos.
• Dinheiro: dólares americanos como números JSON simples.
• Pesos: onças (weight_oz).
• Datas: YYYY-MM-DD. Carimbos de data/hora nos resultados estão em UTC. A maioria não tem sufixo de fuso horário; alguns, como ship_date de get_rates, terminam em Z.
• Paginação: ferramentas de lista aceitam page (de 1) e page_size (até 50), ou limit; cada ferramenta lista seus padrões. tools/list retorna o catálogo inteiro em uma resposta.
• Status de pedidos: filtros de status aceitam nomes como ChooseShipping (pronto para envio) e LabelPrinted. Alguns resultados mostram o rótulo de exibição, como "Pronto para envio", em vez disso. Veja Status de pedidos.

Ferramentas

Conexões com token de acesso obtêm todas as 40 ferramentas. Conexões OAuth obtêm 38: tudo exceto buy_label e trigger_batch_purchase.

Acesso é o que uma ferramenta pode fazer: Somente leitura não muda nada; Altera dados atualiza seus registros ou os da transportadora; Gasta dinheiro cobra seu saldo de postagem e possivelmente seu método de pagamento; Envia e-mail envia e-mails aos seus clientes. Recurso do plano é o recurso que uma chamada precisa (veja Recursos do plano); para ferramentas de e-mail, aplica-se ao envio. OAuth diz se a ferramenta é oferecida em conexões de login OAuth. tools/list é sempre a lista definitiva para sua conexão.

Ferramenta	O que faz	Acesso	Recurso do plano	OAuth
Pedidos e produtos
list_orders	Lista pedidos, prontos para envio por padrão	Somente leitura	Nenhum	Sim
get_order	Detalhes completos de um pedido	Somente leitura	Nenhum	Sim
get_label	Arquivos de etiqueta e rastreamento de uma etiqueta comprada	Somente leitura	Nenhum	Sim
track_order	Último status de rastreamento armazenado	Somente leitura	Nenhum	Sim
list_products	Seu catálogo de produtos salvo	Somente leitura	Nenhum	Sim
Criando e alterando pedidos
create_order	Cria um pedido	Altera dados	Nenhum	Sim
bulk_create_orders	Cria até 100 pedidos	Altera dados	Nenhum	Sim
update_order	Edita um pedido não enviado	Altera dados	Nenhum	Sim
update_order_address	Altera e valida um endereço de entrega	Altera dados	Nenhum	Sim
cancel_order	Cancela um pedido, anulando a etiqueta se possível	Altera dados	Nenhum	Sim
cancel_shipping_label	Anula uma etiqueta; reembolso para o saldo de postagem	Altera dados	Nenhum	Sim
Tarifas, etiquetas e endereços
quote_shipping	Tarifas para um destino, sem necessidade de pedido	Somente leitura	Nenhum	Sim
get_rates	Tarifas para um pedido	Altera dados	Nenhum	Sim
buy_label	Compra uma etiqueta	Gasta dinheiro	Nenhum	Não
validate_address	Verifica e padroniza um endereço dos EUA	Somente leitura	Nenhum	Sim
register_ups	Abre ou vincula uma conta UPS	Altera dados	Nenhum	Sim
Coletas
mark_labels_printed	Marca etiquetas compradas como impressas para que uma coleta as recolha; visualize e depois confirme	Altera dados, envia e-mail	Nenhum	Sim
check_pickup_availability	A transportadora pode fazer a coleta em uma data?	Somente leitura	Nenhum	Sim
schedule_pickup	Agenda uma coleta gratuita da transportadora	Altera dados	Coleta da transportadora	Sim
cancel_pickup	Cancela uma coleta gratuita	Altera dados	Nenhum	Sim
list_pickups	Suas coletas recentes	Somente leitura	Nenhum	Sim
get_pickup	Uma coleta e seus pedidos	Somente leitura	Nenhum	Sim
Envio em lote e sincronização de plataformas
trigger_batch_purchase	Compra etiquetas para vários pedidos	Gasta dinheiro	Envio em lote	Não
get_batch_status	Progresso de um lote	Somente leitura	Envio em lote	Sim
list_connected_platforms	Suas plataformas de vendas conectadas	Somente leitura	Nenhum	Sim
sync_platform_orders	Importa pedidos recentes do Shopify ou Etsy	Altera dados	Nenhum	Sim
get_sync_status	Status dos trabalhos de importação	Somente leitura	Nenhum	Sim
Clientes e e-mail
list_customers	Pesquisa seu catálogo de endereços	Somente leitura	Nenhum	Sim
get_customer	Registro completo de um cliente	Somente leitura	Nenhum	Sim
create_or_update_customer	Adiciona ou edita um cliente	Altera dados	Nenhum	Sim
send_customer_email	Envia e-mail para um cliente	Envia e-mail	Marketing email	Sim
send_mass_marketing_email	Enviar e-mail para um segmento de clientes	Envia e-mail	E-mail de marketing	Sim
list_lapsed_customers	Clientes que não compram há algum tempo	Somente leitura	Nenhum	Sim
Conta, créditos e relatórios
get_balance	Saldo de postagem e recarga automática	Somente leitura	Nenhum	Sim
get_subscription_info	Seu plano, limites e recursos	Somente leitura	Nenhum	Sim
get_referral_info	Crédito de indicação e indicações	Somente leitura	Nenhum	Sim
redeem_referral_credit	Transferir crédito de indicação para postagem	Altera dados	Nenhum	Sim
get_shipping_report	Gastos com envio por mês	Somente leitura	Relatórios de negócios	Sim
get_tax_report	Imposto sobre vendas coletado	Somente leitura	Relatórios de negócios	Sim
get_shipping_analytics	Volume, transportadoras e destinos	Somente leitura	Relatórios de negócios	Sim

Envie um pedido de ponta a ponta

Este passo a passo leva um pedido de "Pronto para envio" até uma coleta de transportadora agendada. Cada etapa é um tools/call, e o JSON mostrado é seu objeto arguments. Leve os IDs adiante exatamente como retornados. As etapas 4 e 5 usam buy_label, que é oferecido apenas em conexões com token de acesso (veja Ferramentas por tipo de conexão).

1. Encontre o pedido. list_orders com {} retorna pedidos prontos para envio. Guarde o order_id.
2. Leia o peso. get_order com {"order_id": 48213}. Leia totals.weight_oz; se estiver vazio, pese o pacote.
3. Faça a cotação. get_rates com {"order_id": 48213, "weight_oz": 14, "length": 10, "width": 8, "height": 4}. Passe o peso explicitamente; o peso salvo não é usado para precificação. Guarde o package_id de nível superior, depois escolha uma linha e guarde seu rate_id, method e service_level.
4. Pré-visualize a compra. buy_label com esses quatro valores e um max_cost, sem confirm. Verifique total_charge e balance_would_go_negative, e mostre-os ao usuário.
5. Compre. Repita a mesma chamada buy_label com "confirm": true. Guarde label_url e tracking_number. Se falhar, veja erros de buy_label.
6. Imprima a etiqueta e marque como impressa. Imprima label_url (e form_url, o formulário aduaneiro, quando houver). Depois chame mark_labels_printed com {"order_ids": [48213]} para pré-visualizar, e novamente com "confirm": true. O pedido passa de "Etiqueta comprada" para "Etiqueta impressa", que é o que uma coleta coleta. Seu cliente recebe o e-mail de rastreamento "Etiqueta impressa" se você tiver isso ativado.
7. Verifique uma data de coleta. check_pickup_availability com {"date": "2026-10-06"}.
8. Pré-visualize a coleta. schedule_pickup com {"date": "2026-10-06", "location": "Front Door"}. Confirme que eligible_order_ids inclui seu pedido.
9. Agende. Repita a chamada com "confirm": true e guarde o pickup_id.

Etapa 3 como uma solicitação 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}}}'

Corpo da solicitação da etapa 5, com os 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}}}

Se você alterar o endereço, peso ou dimensões do pedido após a etapa 3, faça a cotação novamente antes de comprar: o rate_id e o package_id mantêm os valores de quando você fez a cotação.

Pedidos e produtos

Estas ferramentas leem seus pedidos, etiquetas compradas, rastreamento e catálogo de produtos. Um fluxo típico começa com list_orders para ver o que está pronto para envio e abre um com get_order; depois que uma etiqueta é comprada, get_label a retorna e track_order acompanha a entrega, enquanto list_products consulta nomes e preços de produtos ao montar um pedido. Todas as cinco são somente leitura, funcionam em todos os planos e tipos de conexão, retornam apenas dados da sua própria conta e leem o que a Ship.com tem armazenado sem contatar transportadoras ou plataformas de vendas.

list_orders

Somente leitura

Lista os pedidos da sua conta, do mais recente para o mais antigo por data do pedido. Sem filtro, retorna os pedidos prontos para envio, a fila de trabalho não enviado onde a cotação e a compra de etiquetas geralmente começam. As linhas são compactas; chame get_order para obter o detalhe completo de um pedido.

Parâmetro	Tipo	Obrigatório	Descrição
status	string	Não	Quais pedidos retornar. Omita para pedidos prontos para envio (ChooseShipping). Envie active para todos os pedidos, exceto cancelados e mesclados, ou um nome de status da tabela abaixo, como PrintLabel, InTransit ou Delivered. Um status por chamada.
page	inteiro	Não	Número da página baseado em 1. Padrão 1. Valores abaixo de 1 são tratados como 1. Uma página além do final retorna uma lista vazia.
page_size	inteiro	Não	Linhas por página, de 1 a 50. Padrão 25. Valores fora desse intervalo são ajustados, não rejeitados.

Retorna: orders, além de page e page_size conforme aplicados, total (todos os pedidos correspondentes, não apenas esta página) e status (o filtro aplicado, como nome de status ou active). Cada linha tem order_id (use com as outras ferramentas desta seção), order_number, name (o nome de envio armazenado no pedido; pode estar vazio), city, state, zip, country (US quando em branco), total, status e tracking_number.

Bom saber: O filtro aceita um nome de status, mas o status de cada linha é o rótulo de exibição, então linhas prontas para envio aparecem como "Pronto para envio", não ChooseShipping. active ainda inclui pedidos finalizados, como entregues e reembolsados. Não há filtro por data, cliente ou busca de texto. Um status não reconhecido retorna um erro que lista os nomes aceitos, então envie exatamente um nome, escrito como mostrado abaixo. As linhas são ordenadas apenas por data do pedido e podem mudar se novos pedidos forem importados enquanto você navega pelas páginas. O name da linha é exatamente o que está no pedido (um espaço reservado como "Convidado" aparece como está), então pode diferir do ship_to.name em get_order.

Status dos pedidos: filtre pelo nome; os resultados mostram o rótulo.

Nome do status	Mostrado nos resultados como
MissingEmail_InvoiceDraft	E-mail ausente
InvoiceDraft	Rascunho de fatura
WaitingForPayment	Aguardando pagamento
BackOrderedLiveSelling	Pedido solicitado
BackOrdered	Em espera
ChooseShipping	Pronto para envio
LabelRefunded	Etiqueta reembolsada
PrintLabel	Etiqueta comprada
LabelPrinted	Etiqueta impressa
WaitingForPickup	Aguardando coleta
InTransit	Em trânsito
DeliveryFailure	Falha na entrega
ReturnedToSender	Devolvido ao remetente
DeliveryFailureWait	Aguardando devolução
Delivered	Entregue
PrintReturnLabel	Comprar etiqueta de devolução
ReturnLabelRefunded	Etiqueta de devolução reembolsada
WaitingForReturn	Aguardando devolução
ReturnInTransit	Devolução em trânsito
ReturnDelivered	Devolução entregue
ReturnReceived	Devolução recebida
ReturnComplete	Devolução concluída
Refunded	Reembolsado
WaitingForMerge	Mesclagem em andamento
Merged	Mesclado
Deleted	Cancelado

As etiquetas não são únicas: DeliveryFailureWait e WaitingForReturn aparecem ambos como "Aguardando devolução", então filtre pelo nome. O nome do status de um pedido cancelado é Deleted.

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

get_order

Somente leitura

Retorna o detalhe completo de um pedido da sua conta: endereço de envio, totais, campos de envio e rastreamento, e itens de linha. Funciona para um pedido em qualquer status, incluindo cancelados e mesclados.

Parâmetro	Tipo	Obrigatório	Descrição
order_id	inteiro	Sim	O ID do pedido, de list_orders.

Retorna: order_id, order_number, status (rótulo de exibição) e date (a data do pedido); ship_to com name, company, street1, street2, city, state, zip, country (US quando em branco), phone e email; totals com subtotal, shipping (cobrado do seu comprador), tax, total e weight_oz; shipping com method (o serviço da transportadora da etiqueta comprada), cost (o que você pagou pela etiqueta), ship_date e label_url, onde method e label_url permanecem nulos até uma etiqueta ser comprada (antes disso, cost pode ser nulo ou conter um valor importado ou estimado, então verifique label_url em vez de cost); tracking_number e tracking_url (uma página de rastreamento da Ship.com para etiquetas compradas pela Ship.com); e items, um por item de linha, cada um com sku, upc, quantity e price.

Bom saber: Um ID que não existe e um pedido de outra conta retornam o mesmo erro, Order {order_id} was not found in this account. Omitir order_id retorna order_id is required. Itens de linha não têm campo separado de nome de produto, estilo ou tamanho. sku é o código do item armazenado na linha, que pode ser nulo ou, para algumas plataformas de vendas, o nome do produto. upc geralmente é nulo e nem sempre é um código de barras real: pedidos importados de algumas plataformas de vendas carregam um valor de espaço reservado ali. price é o preço registrado na linha; dependendo de onde o pedido veio, pode ser um preço unitário ou um total de linha, então não assuma nenhum dos dois. ship_to usa o endereço de envio salvo do pedido quando houver um. Caso contrário, é construído a partir do pedido, preenchendo um nome ausente ou de espaço reservado (como "Convidado") e um e-mail ou telefone ausente do registro do cliente, e usa "Residente Atual" quando nenhum nome pode ser encontrado. company geralmente é nulo. Se uma etiqueta for cancelada, o pedido volta para "Pronto para envio" e os campos de etiqueta e rastreamento voltam a nulos, embora ship_date possa manter a data antiga.

{"order_id": 4815162}

get_label

Somente leitura

Retorna os arquivos da etiqueta e os detalhes de rastreamento da etiqueta comprada de um pedido. Retorna apenas links armazenados e nunca regenera, recompra ou busca nada da transportadora. Chamá-lo para um pedido sem etiqueta não é um erro: você recebe has_label: false e links nulos.

Parâmetro	Tipo	Obrigatório	Descrição
order_id	inteiro	Sim	O pedido cuja etiqueta você deseja.

Retorna: order_id; label_url, a etiqueta imprimível formatada para a configuração de impressão da sua conta (se sua conta imprime por código QR, etiquetas USPS retornam como uma imagem QR escaneável em vez de um PDF de etiqueta); raw_label_url, o arquivo original 4x6 da transportadora, presente apenas para algumas etiquetas PDF de transportadora (atualmente certas etiquetas USPS) e nulo caso contrário; form_url, um PDF de formulário aduaneiro separado quando a transportadora fornece um (atualmente remessas internacionais UPS); receipt_url, um recibo da transportadora quando ela fornece um (atualmente UPS); tracking_number; tracking_url; e has_label, verdadeiro quando label_url está presente.

Bom saber: Use has_label para decidir se um pedido tem uma etiqueta ativa. Cancelar uma etiqueta limpa label_url, tracking_number e tracking_url, mas os outros links podem continuar apontando para os arquivos da etiqueta anulada, então ignore raw_label_url, form_url e receipt_url quando has_label for falso. Links de etiqueta são URLs de arquivo HTTPS; trate-os como opacos em vez de confiar no host ou formato. Esta ferramenta funciona em todos os tipos de conexão e retorna a etiqueta como foi comprada, inclusive no aplicativo web da Ship.com. IDs desconhecidos e pedidos de outras contas retornam o mesmo erro de não encontrado que get_order.

{"order_id": 4815101}

track_order

Somente leitura

Retorna o status de rastreamento armazenado mais recente da Ship.com para um pedido. A Ship.com o mantém atualizado automaticamente em segundo plano; a ferramenta não consulta a transportadora ao vivo, então chamá-la novamente não atualizará nada. Um pedido sem etiqueta retorna com sucesso com campos de rastreamento nulos.

Parâmetro	Tipo	Obrigatório	Descrição
order_id	inteiro	Sim	O pedido para verificar o rastreamento.
Retorna: order_id; status, o status de exibição do pedido, como "Em trânsito", "Entregue", "Falha na entrega" ou "Devolvido ao remetente" (um status do pedido, não um evento bruto da transportadora); tracking_number; tracking_url; ship_date, in_transit_date, delivered_date e exception_date; exception, o texto de exceção da transportadora; e last_tracking_update, quando a Ship.com armazenou pela última vez uma atualização de rastreamento para o pedido, em UTC.

Bom saber: Verifique last_tracking_update para ver quão recentes são os dados. Nem toda atualização em segundo plano define esse campo, então ele pode ser nulo mesmo depois que status foi movido; trate nulo como "atualização desconhecida", não como "nunca atualizado". Outros carimbos de data/hora não trazem fuso horário. Se uma etiqueta for cancelada, o status volta para "Pronto para envio" e tracking_number, tracking_url e in_transit_date são limpos, mas as outras datas e exception podem manter valores antigos, então leia status e tracking_number primeiro. IDs desconhecidos e pedidos de outras contas retornam o mesmo erro de não encontrado que get_order.

{"order_id": 4815101}

list_products

Somente leitura

Lista os produtos ativos no seu catálogo de produtos salvo na Ship.com, ordenados por nome de A a Z. Use para consultar nomes de produtos, descrições e preços ao montar ou editar um pedido. Ele lê apenas o catálogo salvo e não busca produtos ao vivo das lojas conectadas.

Parâmetro	Tipo	Obrigatório	Descrição
query	string	Não	Texto para corresponder ao nome ou à descrição do produto, sem diferenciar maiúsculas de minúsculas. É uma correspondência simples de substring: o texto inteiro deve aparecer como digitado, sem curingas. Espaços no início e no fim são ignorados. Omita para listar todos os produtos ativos.
page	inteiro	Não	Número da página com base em 1. Padrão 1. Valores abaixo de 1 são tratados como 1. Uma página além do final retorna uma lista vazia.
page_size	inteiro	Não	Linhas por página, de 1 a 50. Padrão 25. Valores fora desse intervalo são limitados, não rejeitados.

Retorna: products, além de page e page_size conforme aplicados e total (todos os produtos ativos correspondentes, não apenas esta página). Cada produto tem product_id, name, catalog (um rótulo de agrupamento opcional), description e price.

Bom saber: Produtos inativos nunca aparecem. Os produtos são identificados pelo nome: os resultados não têm SKU, imagem, estoque, custo ou peso. Os itens de linha em get_order carregam um sku.

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

Criando e alterando pedidos

Estas ferramentas criam pedidos e os alteram antes do envio. Um fluxo típico: crie um pedido (ou até 100 de uma vez), ajuste os detalhes ou o endereço de entrega enquanto ele ainda está como Pronto para envio, depois faça a cotação e compre a etiqueta. Se os planos mudarem, cancele apenas a etiqueta com cancel_shipping_label, ou cancele o pedido inteiro com cancel_order.

Toda consulta de pedido e cliente é limitada à sua própria conta. Um ID de outra conta recebe a mesma resposta de "não encontrado nesta conta" que um ID inexistente. A Ship.com mantém um registro das alterações feitas pelo MCP, assim como faz para alterações feitas no aplicativo. Envie números e booleanos como números e booleanos JSON reais, e envie códigos ZIP como strings: um ZIP enviado como número perde o zero à esquerda.

create_order

Altera dados

Cria um novo pedido como Pronto para envio. Envie para um cliente já presente na sua agenda de endereços com customer_id, ou passe o destinatário inline com ship_to para importar um pedido de qualquer lugar, como uma planilha, um e-mail ou um marketplace. Adicione itens de linha e peso do pacote agora ou depois. Passe external_order_id para que uma nova tentativa ou reimportação retorne o pedido existente em vez de criar uma duplicata.

Parâmetro	Tipo	Obrigatório	Descrição
customer_id	inteiro	Um de dois	Um cliente da agenda de endereços (de list_customers ou get_customer). O pedido copia o nome, a empresa, o endereço, o e-mail e o telefone salvos do cliente. Forneça exatamente um de customer_id ou ship_to.
ship_to	objeto	Um de dois	Destinatário inline. Se a sua agenda de endereços já tiver um contato com o mesmo nome e a mesma linha 1 do endereço (ignorando maiúsculas/minúsculas) e o mesmo ZIP, esse contato é reutilizado sem alterações e o e-mail e o telefone salvos são copiados para o pedido; caso contrário, um novo contato é criado.
ship_to.name	string	Com ship_to	Nome completo do destinatário, dividido no primeiro espaço em nome e sobrenome.
ship_to.company	string	Não	Nome da empresa.
ship_to.street1	string	Com ship_to	Linha 1 do endereço.
ship_to.street2	string	Não	Apartamento, suíte ou unidade.
ship_to.city	string	Com ship_to	Cidade.
ship_to.state	string	Com ship_to	Código do estado ou província.
ship_to.zip	string	Com ship_to	Código ZIP ou postal. Envie como string.
ship_to.country	string	Não	Código de país com duas letras. Padrão US.
items	array	Não	Itens de linha. Omita, ou envie [], para um pedido sem itens de linha.
items[].name	string	Sim	Nome do produto. Também adiciona o produto ao seu catálogo geral de produtos, ou atualiza o produto com o mesmo nome lá.
items[].quantity	inteiro	Não	Pelo menos 1. Padrão 1.
items[].price	número	Não	Preço unitário em dólares, 0 ou mais. Padrão 0.
items[].sku	string	Não	SKU ou UPC, texto livre.
items[].notes	string	Não	Notas para este item.
weight_oz	número	Não	Peso do pacote em onças, maior que 0. Salvo no pedido. trigger_batch_purchase faz a cotação com ele. get_rates não: passe weight_oz para get_rates explicitamente (você pode ler de volta do totals.weight_oz de get_order).
external_order_id	string	Não	O número do pedido ou PO do seu sistema de origem. Se um pedido ativo na sua conta já tiver esse número, esse pedido é retornado em vez de criar um novo.

Retorna: created: true, order_id, um order_number gerado de 6 caracteres, status ("Pronto para envio"), o ship_to usado e items_count. Com itens, adiciona subtotal (soma de preço × quantidade) e um total igual; com ship_to, adiciona customer_id e customer_created. weight_oz e external_order_id são ecoados quando você os envia, e todo resultado termina com um note. Um reenvio duplicado retorna created: false, skipped_existing: true, o order_id do pedido existente, order_number e o status atual, e um note.

Bom saber: Executa imediatamente. Toda a entrada é verificada antes de qualquer coisa ser salva, então um erro de validação não cria nada. Nenhum porte é cobrado e nenhuma transportadora é contatada; o endereço é validado quando você faz a cotação do pedido. A proteção contra duplicatas ignora pedidos cancelados e mesclados, então uma importação cancelada pode ser reimportada. Um reenvio não é comparado com o original e não o atualiza. O ID é mantido nas notas do pedido como [ext:YOUR-ID], então substituir as notas com update_order desativa a proteção contra duplicatas para esse pedido. Envie novas tentativas uma de cada vez: duas chamadas simultâneas com o mesmo ID podem criar um pedido cada. Um produto do catálogo correspondido pelo nome (ignorando maiúsculas/minúsculas) assume o novo preço e o custo dele é redefinido para 0. Se você tiver um programa de recompensas, o pedido ganha pontos do cliente como de costume.

{"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

Altera dados

Cria até 100 pedidos em uma única chamada. Cada entrada aceita os mesmos campos de create_order e passa pelas mesmas verificações, incluindo a proteção contra duplicatas com external_order_id. Uma entrada inválida não impede as demais: cada entrada recebe sua própria linha de resultado, na ordem de entrada, além de um resumo. Use em vez de chamar create_order em um loop.

Parâmetro	Tipo	Obrigatório	Descrição
orders	array	Sim	De 1 a 100 entradas de pedido. Uma lista ausente, vazia ou grande demais é rejeitada e nada é criado. Divida importações maiores em várias chamadas.
orders[]	objeto	Sim	Um pedido com os campos de create_order: exatamente um de customer_id ou ship_to, além de items opcional, weight_oz e external_order_id.

Retorna: results, uma linha por entrada com index e ok. Uma linha bem-sucedida tem order_id e order_number, além de skipped_existing: true quando um pedido existente foi retornado; uma linha com falha tem error, a mesma mensagem que create_order daria. Também summary (created, skipped, failed) e um note. As linhas não incluem status, endereço ou totais; use get_order para isso.

Bom saber: A chamada inteira conta como uma única requisição contra o limite de 60 requisições por minuto. Não há tudo-ou-nada: cada entrada é salva conforme é processada. Um external_order_id repetido dentro do mesmo lote é criado uma vez e reportado como ignorado na entrada posterior. Envie números como números JSON: um valor do tipo errado (como "two" para uma quantidade) interrompe a chamada inteira com um resultado de erro inesperado depois que entradas anteriores já foram salvas. Após qualquer erro inesperado, verifique com list_orders. Reenviar o mesmo lote com um external_order_id em cada entrada é seguro, porque entradas já criadas voltam como ignoradas.

{"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

Altera dados

Edita um pedido que ainda está como Pronto para envio ou em um status anterior: notas, número de exibição do pedido, os valores que você cobra do cliente, itens de linha e peso do pacote. Envie apenas os campos que deseja alterar, pelo menos um. O total é recalculado a cada vez como subtotal - desconto + imposto + frete + taxa de manuseio, usando o valor salvo para qualquer valor que você não enviar.

Parâmetro	Tipo	Obrigatório	Descrição
order_id	inteiro	Sim	O pedido a editar. Pedidos com etiqueta reembolsada ou qualquer status posterior (etiqueta comprada, impressa, em trânsito, entregue e assim por diante) são rejeitados. Pedidos cancelados e mesclados não são rejeitados; editá-los não os reabre.
notes	string	Não	Substitui o campo inteiro de notas. Uma string vazia limpa o campo.
order_number	string	Não	Número de exibição do pedido. Uma string vazia limpa o campo. Não é verificado quanto à exclusividade.
subtotal	número	Não	Subtotal dos itens. Ignorado quando items é enviado na mesma chamada.
shipping	número	Não	Frete que você cobra do cliente (não o porte).
tax	número	Não	Imposto sobre vendas.
discount	número	Não	Desconto no nível do pedido, subtraído do total.
handling	número	Não	Taxa de manuseio.
items	array	Não	Substitui todos os itens de linha (não é uma mesclagem). Cada item aceita name (obrigatório), quantity, price, sku e notes, como em create_order. [] remove todos os itens. O subtotal é recalculado a partir dos itens.
weight_oz	número	Não	Peso do pacote em onças, maior que 0. Salvo no pedido. trigger_batch_purchase faz a cotação com ele. get_rates não: passe weight_oz para get_rates explicitamente (você pode ler de volta do totals.weight_oz de get_order).

Retorna: updated: true, order_id, order_number, totals (subtotal, shipping, tax, discount, handling, total), além de items_count e weight_oz quando você os enviou, e um note. Bom saber: É executado imediatamente e não altera o status do pedido. As tarifas obtidas antes da alteração ainda mantêm o peso antigo; chame get_rates novamente antes de comprar. Os valores são salvos como enviados e não passam por verificação de faixa. Os itens atualizam seu catálogo de produtos Geral da mesma forma que create_order. Substituir as notas de um pedido criado com external_order_id remove a referência [ext:...] e, com ela, a proteção contra duplicatas; inclua essa referência nas novas notas para mantê-la. Se você tiver um programa de recompensas, os pontos do cliente são recalculados. Faturas não podem ser criadas ou enviadas pelo MCP; use o aplicativo Ship.com para isso.

{"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

Altera dados

Altera o endereço de entrega de um pedido que ainda está em Pronto para envio ou em um status anterior. O novo endereço é validado antes de ser salvo; se não for validado, nada muda. Apenas este pedido é atualizado: a entrada do endereço no catálogo do cliente e o nome, empresa, telefone e e-mail do destinatário permanecem como estão.

Parâmetro	Tipo	Obrigatório	Descrição
order_id	inteiro	Sim	O pedido a ser reendereçado. Pedidos com status Reembolso de etiqueta ou qualquer status posterior são rejeitados. Pedidos cancelados e mesclados não são rejeitados; editá-los não os reabre.
street1	string	Sim	Linha 1 do endereço. Salvo como enviado.
street2	string	Não	Apartamento, suíte ou unidade. Se omitido, qualquer linha 2 existente no pedido é limpa, então reenvie-a para mantê-la.
city	string	Sim	Cidade. A cidade validada é salva.
state	string	Sim	Código de estado com duas letras. O estado validado é salvo.
zip	string	Sim	CEP, enviado como string. O CEP validado é salvo e pode diferir do que você enviou.

Retorna: updated: true, order_id, o ship_to salvo (street1, street2, city, state, zip, com a cidade, estado e CEP corrigidos) e um note.

Bom saber: É executado imediatamente. As tarifas obtidas antes da alteração ainda mantêm o endereço antigo; chame get_rates novamente antes de comprar. Apenas endereços nos EUA: o endereço é sempre validado como um endereço dos EUA. Se o serviço de validação estiver brevemente indisponível, você receberá o mesmo erro "não foi possível validar", então uma nova tentativa posterior pode ter sucesso.

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

cancel_order

Altera dados — Visualizar e depois confirmar

Cancela um pedido por completo. O status dele se torna Cancelado e ele permanece visível na sua conta. Se o pedido ainda não foi enviado e a etiqueta está dentro de 29 dias da data de envio, a etiqueta é anulada primeiro, com o mesmo tratamento de reembolso de cancel_shipping_label. Os pontos de recompensa do cliente ganhos no pedido são revertidos. Para anular apenas a etiqueta e manter o pedido aberto, use cancel_shipping_label.

Parâmetro	Tipo	Obrigatório	Descrição
order_id	inteiro	Sim	O pedido a ser cancelado. Pedidos em qualquer status são aceitos.
confirm	booleano	Não	Omita ou use false para visualizar; nada muda. true cancela o pedido.

Retorna: Uma visualização retorna preview: true, order_id, current_status (por exemplo, "Etiqueta comprada"), would_void_label, would_reverse_reward_points, refund_note e note. Uma chamada confirmada retorna canceled: true, order_id, status ("Cancelado"), label_voided, postage_balance (seu saldo atual, não um crédito desta chamada) e refund_note (nulo quando não havia etiqueta).

Bom saber: Chame uma vez sem confirm para ver o que acontecerá e depois novamente com confirm: true. Uma etiqueta não é anulada quando o pedido está em trânsito, entregue ou sendo devolvido, ou quando a etiqueta está a mais de 29 dias da data de envio; a etiqueta e o rastreamento permanecem no pedido cancelado e nenhum reembolso de postagem é emitido. Para um pedido já enviado, a nota de reembolso pode descrever isso como sem etiqueta para anular ou como fora da janela de anulação. Se a transportadora recusar a anulação, o pedido ainda é cancelado, label_voided é falso e nenhum reembolso é enfileirado; entre em contato com help@ship.com se você esperava um. would_reverse_reward_points é sempre verdadeiro em uma visualização, mesmo quando o pedido não ganhou pontos. O cancelamento não é enviado às plataformas de vendas conectadas; apenas uma etiqueta anulada envia uma atualização de rastreamento. Cancele cada pedido uma vez. Um pedido cancelado pode ser importado novamente com create_order usando o mesmo external_order_id.

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

cancel_shipping_label

Altera dados — Visualizar e depois confirmar

Anula uma etiqueta de envio comprada e retorna o pedido para Pronto para envio, para que você possa editá-lo ou reavaliá-lo. Uma etiqueta pode ser anulada dentro de 29 dias da data de envio. O reembolso da postagem não é imediato: normalmente é creditado no seu saldo de postagem do Ship.com cerca de 14 dias após a anulação e está sujeito à aceitação da anulação pela transportadora.

Parâmetro	Tipo	Obrigatório	Descrição
order_id	inteiro	Sim	O pedido cuja etiqueta deve ser anulada. Ele deve ter uma etiqueta comprada.
confirm	booleano	Não	Omita ou use false para visualizar; nada é anulado. true anula a etiqueta.

Retorna: Uma visualização retorna preview: true, order_id, tracking_number, ship_date, within_void_window, shipping_cost, refund_note e note. Uma chamada confirmada retorna canceled: true, order_id, status ("Pronto para envio") e refund_note.

Bom saber: Uma etiqueta além da janela de 29 dias retorna um erro em vez de uma visualização. Quando a anulação é concluída, o número de rastreamento, a etiqueta, a tarifa e o seguro são limpos, e o seguro comprado com a etiqueta é anulado. E-mails de acompanhamento não enviados ao seu cliente que foram acionados pela etiqueta impressa são cancelados. O pedido sai de qualquer coleta agendada, mas a coleta em si permanece reservada. Se o pedido veio de uma plataforma de vendas conectada que sincroniza rastreamento, a alteração é enviada para lá. Quando o reembolso vencer, o custo da etiqueta e qualquer taxa de seguro são creditados no seu saldo de postagem, mesmo se você pagou com cartão, e você recebe um e-mail de confirmação. Se a transportadora já escaneou o pacote até lá, nenhum crédito é emitido e o número de rastreamento é restaurado. Se a transportadora recusar a anulação, na maioria das vezes porque o pacote já está em trânsito, nada muda e nenhum reembolso é enfileirado. A transportadora não dá motivo, e uma nova tentativa no mesmo dia pode ser recusada novamente. Entre em contato com help@ship.com se a etiqueta deveria ter sido reembolsável. Etiquetas de devolução não são tratadas por esta ferramenta.

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

Tarifas, etiquetas e endereços

Estas ferramentas precificam envios, compram etiquetas e verificam endereços. Um fluxo típico: estime um custo com quote_shipping (sem necessidade de pedido), avalie um pedido específico com get_rates e depois visualize e confirme a compra com buy_label. validate_address verifica um endereço dos EUA por conta própria, e register_ups conecta a UPS para que você possa comprar etiquetas UPS. buy_label está disponível em conexões com token de acesso; as outras quatro funcionam em todas as conexões e em todos os planos.

Os pesos são sempre em onças e as dimensões em polegadas. O dinheiro está em dólares americanos como números JSON simples. rate_id e package_id são tokens opacos longos (geralmente de 1 a 2 KB): passe-os de volta exatamente como recebidos e pegue ambos da mesma resposta de get_rates. Eles capturam o preço, serviço, pacote e endereço de entrega no momento em que você avalia. Se você alterar o endereço, peso ou dimensões do pedido, chame get_rates novamente e use os novos valores. Tarifas de quote_shipping não podem ser compradas. Alguns problemas de avaliação são retornados como erros mesmo quando as transportadoras precificaram opções: um endereço de origem ausente ou inválido ("Falha na avaliação: o endereço de origem da conta está ausente ou inválido. Corrija-o em Configurações antes de avaliar ou comprar etiquetas.") e, para get_rates, um destino que falhou na validação de endereço ou precisa de uma declaração alfandegária. Qualquer outro problema que ainda deixe opções precificadas retorna como um warning ao lado das tarifas. Um aviso sempre começa com "Falha na avaliação: ", mesmo quando é apenas um aviso informativo da transportadora, como uma sobretaxa da UPS, então leia-o antes de comprar.

quote_shipping

Somente leitura

Obtém tarifas de envio para um destino sem um pedido, por exemplo, para estimar quanto custará um pacote. Cada chamada obtém cotações ao vivo das transportadoras e ignora o cache de tarifas de curta duração; os preços Flat Rate seguem uma lista de preços dos USPS que é atualizada diariamente. Nada é salvo e nenhum dinheiro é movimentado. Para comprar uma etiqueta, você precisa de um pedido: use get_rates e buy_label.

Parâmetro	Tipo	Obrigatório	Descrição
zip	string	Sim	Código postal do destino. Para destinos nos EUA, envie um CEP de 5 dígitos ou CEP+4 como string, mantendo os zeros à esquerda. Qualquer outro formato é avaliado como destino internacional, mesmo quando country é US.
country	string	Não	Código de país do destino com duas letras. Padrão US. Qualquer outro país recebe serviços internacionais dos USPS e serviços UPS Worldwide.
weight_oz	número	Sim	Peso do pacote em onças. Deve ser maior que 0.
length	número	Não	Comprimento em polegadas, usado para precificação dimensional e cúbica. Padrão: desconhecido.
width	número	Não	Largura em polegadas. Padrão: desconhecido.
height	número	Não	Altura em polegadas. Padrão: desconhecido.
from_zip	string	Não	CEP de origem. Padrão: o endereço de origem da sua conta. Quando definido, a cotação usa uma origem nos EUA com apenas este CEP.

Retorna: destination (zip e country, após o padrão dos EUA), weight_oz, rates e, quando presente, warning. Cada linha de tarifa tem method (nome de exibição, 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, ou um código de serviço UPS como "03" Ground, "01" Next Day Air, "02" 2nd Day Air, "93" Ground Saver ou "11" Standard), rate (o que sua conta paga, incluindo qualquer taxa por etiqueta que seu plano adiciona), retail_rate (preço de varejo para comparação, ou nulo), delivery_date (a estimativa da transportadora como data-hora ISO sem fuso horário; sempre nulo em linhas UPS), is_cubic e variant e max_weight_oz (definidos em linhas de faixa de peso do Ground Advantage, como "até 12 oz" e 12; caso contrário, nulo).

Bom saber: As linhas vêm em uma ordem fixa: produtos Priority Mail Flat Rate, depois Priority Mail, Priority Mail Express (mostrado como "USPS Express Mail") e Ground Advantage, depois as faixas de peso do Ground Advantage, depois serviços internacionais dos USPS e depois UPS. Opções que não foram precificadas são omitidas, e linhas semelhantes não são mescladas: o Ground Advantage pode aparecer duas vezes, uma como linha cúbica ("(Cubic)" ou "(Cubic Soft Pack)" em method) e outra simples. Linhas de faixa de peso cujo limite está abaixo do seu peso são descartadas, assim como todas as linhas de faixa quando um lado tem mais de 22 polegadas ou o volume é superior a 1.728 polegadas cúbicas. Linhas UPS podem aparecer antes de sua conta ser registrada na UPS, mas comprar uma etiqueta UPS requer register_ups. Um peso sem dimensões pode cotar mais barato do que a transportadora cobra depois, porque cobranças dimensionais retornam como ajustes de postagem, então forneça dimensões reais quando tiver. Um pacote por chamada, envio para hoje, sem assinatura, entrega no sábado ou opções de tipo de pacote. Erros: "zip is required.", "weight_oz must be greater than 0.", o erro de origem ou "Falha na avaliação: " com a mensagem da transportadora quando nada foi precificado.

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

get_rates

Altera dados Obtém as tarifas de envio para um dos seus pedidos, usando o endereço de entrega do pedido e seu endereço de remetente. Retorna um package_id e uma lista de opções com preço. Para comprar uma, passe o rate_id, method e service_level dessa opção, além do package_id, para buy_label exatamente como retornados. Você pode substituir o peso e as dimensões do pacote.

Parâmetro	Tipo	Obrigatório	Descrição
order_id	inteiro	Sim	O pedido a ser cotado. Ele deve pertencer à sua conta.
weight_oz	número	Não	Peso do pacote em onças. O peso salvo no pedido não é usado para precificação, então passe-o aqui (get_order o retorna como totals.weight_oz). Omita-o ou envie 0 para uma cotação sem peso (somente opções de preço fixo). Um valor positivo gera uma cotação completa e é salvo como o peso do pacote do pedido. Valores negativos não são rejeitados, então envie apenas pesos positivos. Padrão 0.
length	número	Não	Comprimento em polegadas. Omita-o, ou envie 0 ou menos, para usar o comprimento salvo no pedido, se houver.
width	número	Não	Largura em polegadas. Mesmo fallback que length.
height	número	Não	Altura em polegadas. Mesmo fallback que length.
ship_date	string	Não	Data de envio como YYYY-MM-DD. Padrão hoje. Um valor que não pode ser lido silenciosamente se torna a hora atual. buy_label usa seu próprio ship_date quando você compra.

Retorna: order_id, package_id (um token opaco para buy_label), ship_date (data-hora ISO em UTC), rates (os mesmos campos de linha que quote_shipping), um note lembrando você de passar os valores escolhidos para buy_label literalmente, e warning quando presente.

Bom saber: Sem um peso, você obtém apenas as opções de preço fixo: os seis produtos Flat Rate do Priority Mail e as quatro faixas de peso do Ground Advantage, menos qualquer faixa abaixo do peso salvo do pedido (um pedido salvo acima de 15,9 oz pode obter apenas linhas Flat Rate). Para ver Priority Mail, Priority Mail Express, Ground Advantage no peso real, UPS e serviços internacionais, passe um weight_oz positivo. Os preços das caixas Flat Rate e das faixas de peso podem ser servidos de um cache de tarifas por até 3 horas, e os preços Flat Rate seguem uma lista de preços dos USPS que é atualizada diariamente.

Ele nunca compra nada nem movimenta dinheiro, mas, como a cotação no aplicativo web Ship.com, salva no pedido: um weight_oz positivo se torna o peso do pacote do pedido, e para destinos nos EUA o endereço de entrega é verificado com validação de endereço da transportadora e o resultado é armazenado no pedido. Um endereço válido pode ter sua cidade e estado corrigidos. Nada é salvo quando o serviço de validação está indisponível. Está anotado como somente leitura em tools/list porque nunca compra.

Escolha uma linha de faixa de peso do Ground Advantage somente se o pacote pesar no máximo seu max_weight_oz. A etiqueta é comprada no peso da faixa e em um tamanho de caixa padrão, então um pacote mais pesado ou maior é cobrado pela diferença depois como um ajuste de postagem. Faixas que não cabem são descartadas quando o peso ou as dimensões são conhecidos; com nenhum conhecido, todas as quatro retornam. Linhas da UPS podem aparecer antes de sua conta ser registrada na UPS (comprar uma requer register_ups), e um destino com caixa postal recebe apenas Ground Saver da UPS.

Um pedido que não existe ou não é seu retorna "Order <id> was not found in this account." Um destino que falha na validação de endereço retorna "Rating failed: the destination address failed validation. Correct it with update_order_address before buying a label." (veja update_order_address). Remessas que precisam de declaração alfandegária não podem ser cotadas ou compradas pelo MCP ainda: destinos fora dos EUA; endereços APO, FPO e DPO; territórios dos EUA e estados livremente associados (Guam, Ilhas Virgens Americanas, Samoa Americana, Ilhas Marianas do Norte, Micronésia, Ilhas Marshall e Palau); e qualquer pedido quando seu próprio endereço de remetente é APO, FPO ou DPO. Envie esses pelo aplicativo web Ship.com. Um pacote por pedido por chamada, sem assinatura, entrega no sábado, etiqueta de devolução ou opções personalizadas de pacote.

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

Resposta (tokens encurtados). package_id é compartilhado por cada linha; rate_id, method e service_level vêm da linha que você escolhe. Linhas de faixa de peso definem variant e 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

Altera dadosGasta dinheiroVisualizar, depois confirmarSomente conexões com token de acesso

Compra uma etiqueta de envio real dos USPS ou UPS para um pedido, paga do seu saldo de postagem. Passe os valores de get_rates exatamente como retornados. Sem confirm retorna uma prévia do preço, seu saldo e se uma recarga automática seria executada, e não compra nada. Chame novamente com confirm: true para comprar.

Parâmetro	Tipo	Obrigatório	Descrição
order_id	inteiro	Sim	O pedido para comprar uma etiqueta. Ele deve pertencer à sua conta.
rate_id	string	Sim	O rate_id da opção escolhida. Ele decide o que é comprado: transportadora, serviço, preço e pacote.
package_id	string	Sim	O package_id da mesma resposta de get_rates.
method	string	Sim	O method da opção, salvo no pedido como o nome do método de envio. Não muda o que é comprado.
service_level	string	Sim	O service_level da opção. Não muda o que é comprado.
ship_date	string	Não	YYYY-MM-DD. Padrão hoje; valores ilegíveis se tornam hoje. Uma data com mais de 24 horas no passado é recusada. Para USPS, a data de postagem é mantida entre hoje e 7 dias à frente (horário do leste dos EUA).
confirm	booleano	Não	true para comprar. Omita ou false para uma prévia. Padrão false.
max_cost	número	Não	Teto em dólares para o preço da postagem (seguro e taxas não contados). Uma tarifa maior é recusada, na prévia e na confirmação, antes que qualquer coisa seja cobrada. Uma tarifa igual passa.
insurance	booleano	Não	Substitui a configuração de sua conta de segurar todas as remessas para esta etiqueta. Padrão: essa configuração.
insured_value	número	Não	Valor em dólares a segurar quando o seguro está ativo. Padrão: o subtotal de mercadorias do pedido, senão seu total. Sem valor positivo a segurar, a etiqueta é enviada sem seguro.

Retorna: Uma prévia retorna preview: true, order_id, method, service_level, price (postagem), 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 e um message. Uma compra retorna purchased: true, order_id, cost (postagem), insurance, insured_value, insurance_cost, label_url (Tamanho completo: uma etiqueta 4x6 em uma página de carta dos EUA), tracking_number, tracking_url (https://app.ship.com/tracker/ mais o número de rastreamento), form_url (um formulário alfandegário quando aplicável, caso contrário nulo), balance_after, um message, status (o status do pedido, normalmente "Label purchased") e next_step. Enquanto a etiqueta não é impressa, next_step diz para marcá-la como impressa uma vez que for impressa, então agende uma coleta se seu plano incluir coleta da transportadora ou deixe-a; para uma etiqueta UPS aponta para a coleta UPS paga no aplicativo web Ship.com. Caso contrário, é nulo.

Bom saber: Disponível em conexões com token de acesso. Não é oferecido em conexões autorizadas pelo login Ship.com (OAuth), como o conector de diretório Claude e conectores personalizados claude.ai; lá está ausente de tools/list, e uma chamada retorna erro JSON-RPC -32602 dizendo que a ferramenta não está disponível. Confirmar não precisa de uma prévia anterior, e a prévia não verifica package_id, limites do plano, cobrança, data de envio, endereço ou situação da conta, então uma prévia limpa ainda pode falhar na confirmação.

A postagem sai do seu saldo de postagem, mais uma taxa de pagamento conforme o uso de $0,30 quando seu valor de recarga automática é $0,01 ou menos. O seguro é uma cobrança separada: $0,99 para cada $100, ou parte de $100, do valor segurado em pedidos para os EUA ($40 custa $0,99, $120 custa $1,98), e $1,25 por $100 caso contrário. Se seu saldo não cobrir postagem e seguro, seu método de pagamento registrado é cobrado antes de a etiqueta ser criada, pelo maior entre seu valor de recarga automática e o déficit. Com um valor de recarga automática de $0,01 (pagamento conforme o uso), a cobrança é o déficit mais $0,30, no mínimo $1, e o auto_recharge_would_fire da prévia ainda lê falso. Com um valor de $0, a compra falha em vez disso. Uma recarga permanece no seu saldo mesmo se a compra falhar depois, por exemplo, no limite mensal de remessas do seu plano.

Em caso de sucesso, o pedido passa para Label purchased com seu número de rastreamento e etiqueta salvos. Ele passa para Label printed quando é impresso na página de Pedidos ou na página de compra de um lote no aplicativo web Ship.com. Etiquetas impressas diretamente de label_url, ou com a impressão de tudo do Ship Mode, precisam de uma chamada para mark_labels_printed uma vez que forem impressas. Coletas da transportadora coletam apenas etiquetas impressas (veja Pickups). Um pedido ainda aguardando pagamento é marcado como pago fora do Ship.com. O número de rastreamento é enviado à plataforma de vendas do pedido, como Shopify, Etsy, eBay, WooCommerce, Square, Squarespace, Wix ou PayPal. E-mails ao cliente e webhooks de rastreamento saem depois, quando a etiqueta é marcada como impressa. Seu formato de etiqueta salvo é definido como Tamanho completo. Se o pedido já tem uma etiqueta, essa etiqueta é retornada e nada é cobrado; a resposta ainda mostra purchased: true, com cost da tarifa que você passou. Compras simultâneas para um pedido retornam a primeira etiqueta.

Erros: Um token que não pode ser lido retorna "rate_id is invalid or has expired. Call get_rates again and use a fresh rate_id." Uma tarifa acima de max_cost retorna "Refusing to buy: rate is $<price> which exceeds max_cost $<max>. Nothing was purchased." Falhas de compra leem Label purchase failed — <Code>, às vezes seguidas por : <detail>. Os códigos comuns:

Código	Significado	O que fazer
NeedsFromAddress	Sua conta não tem endereço de remetente.	Adicione um em Configurações no aplicativo web Ship.com.
MissingBilling	Seu saldo está muito baixo e nenhum método de pagamento está registrado.	Adicione um método de pagamento no aplicativo web.
AutoRechargeOff	Seu saldo está muito baixo e seu valor de recarga automática é $0.	Adicione fundos ou defina um valor de recarga automática no aplicativo web.
NeedPayment, ChargeFailed	Uma cobrança no cartão foi recusada, ou um pagamento de assinatura está vencido.	Atualize seu método de pagamento no aplicativo web.
CooldownNeeded	Recusas repetidas de cartão.	Aguarde 60 segundos, então corrija o cartão antes de tentar novamente.
Limit reached	O limite mensal de remessas do seu plano; o detalhe é o limite.	Faça upgrade, ou aguarde o próximo mês.
Unauthorized	O package_id é de uma resposta de get_rates diferente do rate_id.	Cote novamente e use ambos os valores de uma resposta.
UPSError	A UPS não conseguiu criar a etiqueta, incluindo quando sua conta não está registrada na UPS.	Leia o detalhe; execute register_ups se você não registrou.
Suspended	Sua conta está em espera para revisão.	Contate help@ship.com.
A pré-visualização não verifica nenhuma dessas condições. Se balance_would_go_negative for verdadeiro e auto_recharge_amount for 0, a confirmação falhará com AutoRechargeOff (ou MissingBilling quando não houver método de pagamento cadastrado). Outros códigos, como DateError, RateError ou ShippingError, vêm com um detalhe que descreve o problema, geralmente a mensagem da própria transportadora. Uma etiqueta que não pode ser armazenada é cancelada automaticamente. Se uma falha disser que não é certo se uma etiqueta foi comprada, ou se você receber um erro inesperado, verifique get_label e get_balance antes de tentar novamente.

{"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

Somente leitura

Verifica um endereço dos EUA com a validação de endereço da transportadora, a mesma verificação que o Ship.com executa em pedidos, e retorna uma versão padronizada. Não salva nada, então use para verificar um endereço antes de criar ou atualizar um pedido. Somente endereços dos EUA.

Parâmetro	Tipo	Obrigatório	Descrição
street	string	Sim	Linha 1 do endereço, como "1600 Pennsylvania Ave NW". Retornado inalterado.
street2	string	Não	Segunda linha: apartamento, suíte ou unidade. Retornado inalterado, ou nulo se omitido.
city	string	Sim	Cidade.
state	string	Sim	Código de estado com duas letras, como DC.
zip	string	Sim	CEP dos EUA com 5 ou 9 dígitos. Apenas os primeiros 5 dígitos são usados para correspondência.

Retorna: is_valid (booleano), standardized (street, street2, city, state, zip) e, somente quando is_valid for falso, um note. Quando o endereço é válido, city, state e zip são os valores padrão do validador: a cidade geralmente fica em maiúsculas, e o CEP pode voltar como CEP+4 e pode diferir do que você enviou. Quando não é válido, eles ecoam sua entrada.

Bom saber: Um endereço é válido somente quando há uma correspondência única e inequívoca. As linhas do endereço nunca são corrigidas. is_valid: false significa que não existe correspondência ou que o serviço de validação esteve brevemente indisponível; o resultado não diz qual, então tente novamente mais tarde com um endereço que você sabe que é bom. Campos ausentes são relatados juntos, por exemplo "street is required." ou "city, zip are required." Para corrigir o endereço salvo de um pedido, use update_order_address.

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

register_ups

Altera dadosPré-visualização, depois confirmação

Registra sua conta Ship.com com a UPS, o que é necessário antes de comprar etiquetas da UPS. Pode abrir uma nova conta UPS ou vincular uma que você já tenha. O registro aceita o Acordo de Tecnologia da UPS, um contrato juridicamente vinculativo com a UPS Market Driver, Inc. Chame sem confirm para obter o acordo e um token, mostre o acordo ao titular da conta e confirme com o token somente depois que ele aceitar explicitamente. Um assistente de IA ou integração nunca deve aceitar em nome deles.

Parâmetro	Tipo	Obrigatório	Descrição
confirm	booleano	Não	Omita ou use false para pré-visualizar; nada é registrado. true para registrar. Padrão false.
accepted_agreement_token	string	Com confirm	O agreement_token da pré-visualização. Envie somente depois que o titular da conta viu o acordo e o aceitou.
company	string	Não	Nome da empresa. Padrão: o nome da empresa da sua conta, caso contrário o nome do contato.
name	string	Não	Primeiro e último nome do contato (pelo menos duas palavras; a última palavra é o sobrenome). Padrão: o nome do titular da conta.
email	string	Não	E-mail do contato. Padrão: o e-mail da sua conta.
phone	string	Não	Telefone do contato. Padrão: o telefone da sua conta.
street1	string	Não	Linha 1 do endereço de coleta (apenas a linha 1 é usada). Padrão: o endereço da sua conta.
city	string	Não	Cidade. Padrão: o endereço da sua conta.
state	string	Não	Código de estado com duas letras. Padrão: o endereço da sua conta.
zip	string	Não	CEP. Padrão: o endereço da sua conta.
existing_ups_account	string	Não	Um número de conta UPS existente (exatamente 6 letras ou dígitos) para vincular em vez de abrir uma nova conta. A UPS verifica primeiro sem custo: um número que a UPS rejeita é recusado, e se a UPS não puder dar uma resposta, ele é vinculado mesmo assim.
existing_ups_postal_code	string	Não	O código postal que a UPS tem registrado para essa conta. Padrão: zip.

Retorna: Uma pré-visualização retorna preview: true, registered (se a conta já está registrada), note, agreement_version (como UTA10072022), agreement_token (64 caracteres hexadecimais), prefill (os detalhes que seriam enviados: company, name, email, phone, street1, city, state, zip, country "US"), missing_fields e, por último, agreement_text (o acordo completo como texto simples, cerca de 71 KB). Uma confirmação retorna registered: true, ups_account_last3 (um número de conta mascarado como ***2C3), agreement_version e um note.

Bom saber: O token é específico da sua conta e vem somente de uma pré-visualização. Ele pode mudar, por exemplo quando o acordo é atualizado, então se uma confirmação recusar o token, pré-visualize novamente. Os campos de contato e endereço são obrigatórios, quer você abra ou vincule uma conta; os ausentes são listados em missing_fields, e uma confirmação sem eles é recusada. Abrir uma nova conta envia à UPS sua empresa, nome do contato, e-mail, telefone, endereço e o endereço IP da solicitação. Não há cobrança. O registro não pode ser desfeito pelo MCP, e uma conta já registrada é recusada (a pré-visualização mostra registered: true). Linhas da UPS podem aparecer em quote_shipping e get_rates antes de você registrar, mas comprá-las falha até que você registre. Somente endereços dos EUA. Problemas do lado da UPS voltam como "UPS registration failed: " seguido do motivo.

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

Coletas

Estas ferramentas agendam coletas gratuitas da USPS, para que a transportadora colete seus pacotes com etiquetas impressas em vez de você deixá-los em um ponto de coleta. Um fluxo típico: marque as etiquetas que você imprimiu com mark_labels_printed, verifique uma data com check_pickup_availability, pré-visualize e depois agende com schedule_pickup, revise com list_pickups e get_pickup, e cancele com cancel_pickup se os planos mudarem. Agendar uma coleta exige um plano que inclua coleta pela transportadora; as outras cinco ferramentas funcionam em todos os planos.

Imprima e marque primeiro. Uma coleta coleta apenas pedidos com etiqueta impressa. Etiquetas compradas com buy_label ou trigger_batch_purchase permanecem como Etiqueta comprada até serem marcadas como impressas. No aplicativo web do Ship.com, imprimir pela página de Pedidos ou pela página de compra de um lote marca uma etiqueta, e a janela de envio também a marca automaticamente (exceto para pedidos com formulário aduaneiro). Etiquetas impressas diretamente de label_url, ou com o imprimir-tudo do Ship Mode, permanecem como Etiqueta comprada; chame mark_labels_printed para essas antes de schedule_pickup. Apenas coletas gratuitas são agendadas ou canceladas aqui. Pacotes com etiqueta da UPS nunca são coletados por estas coletas: uma coleta da UPS é uma visita paga separada que você agenda e cancela no aplicativo web do Ship.com. Coletas pagas da UPS ainda aparecem em list_pickups e get_pickup, com carrier "UPS" e um fee_amount. As coletas usam o endereço de coleta da sua conta, ou seu endereço de remessa se você não definiu um separado. Refira-se a uma coleta pelo seu pickup_id, não pelo número de confirmação da transportadora. Toda consulta de coleta é limitada à sua própria conta, e um ID de outra conta recebe a mesma resposta "was not found in this account" que um que não existe. Envie datas apenas como YYYY-MM-DD. Os nomes das transportadoras diferem por ferramenta: check_pickup_availability, schedule_pickup e cancel_pickup relatam USPSDirect ou MoveMethod (ambas são coletas da USPS; trate o valor como informativo), enquanto list_pickups e get_pickup relatam toda coleta gratuita como USPS/MoveMethod.

mark_labels_printed

Altera dadosEnvia e-mailPré-visualização, depois confirmação

Marca etiquetas compradas como impressas, o mesmo que imprimi-las no aplicativo web do Ship.com. Os pedidos passam de Etiqueta comprada para Etiqueta impressa, que é o que uma coleta da transportadora coleta. Chame após buy_label ou trigger_batch_purchase, assim que as etiquetas estiverem realmente impressas. get_label fornece os arquivos: label_url, além de form_url para pedidos internacionais, cujo formulário aduaneiro também deve ser impresso.

Parâmetro	Tipo	Obrigatório	Descrição
order_ids	matriz de inteiros	Este ou batch_id	Os pedidos cujas etiquetas você imprimiu, até 100. Duplicatas são ignoradas; cada entrada deve ser um número inteiro.
batch_id	inteiro	Este ou order_ids	Um batch_id de trigger_batch_purchase ou get_batch_status. Marca as etiquetas compradas mas não impressas desse lote, até 100 por chamada; chame novamente para continuar.
confirm	booleano	Não	Omita ou use false para pré-visualizar; nada muda. true marca as etiquetas como impressas.

Retorna: Uma pré-visualização retorna preview: true, would_mark_count, would_mark_order_ids, already_printed_order_ids, skipped (cada um com order_id, status e um reason), free_pickup_order_ids (etiquetas que uma coleta gratuita coletará uma vez impressas), ups_order_ids, outside_pickup_window_order_ids, customs_form_order_ids (etiquetas com formulário aduaneiro para imprimir também), not_found_order_ids (com order_ids), batch_id e remaining_unprinted_in_batch (com batch_id) e um note. Uma chamada confirmada retorna marked_count, marked_order_ids, already_printed_order_ids, skipped, failed (cada um com order_id e um reason), not_found_order_ids, batches_marked_printed, free_pickup_eligible_count, status ("Label printed" quando pelo menos um pedido foi marcado ou já estava impresso, caso contrário nulo), batch_id e remaining_unprinted_in_batch (com batch_id) e next_step: o que fazer a seguir, ou nulo. Se etiquetas não impressas permanecerem no lote, ele diz para terminar de marcá-las primeiro: uma coleta coleta apenas etiquetas já marcadas como impressas, e você pode agendar uma coleta gratuita por data. Caso contrário, quando uma coleta gratuita coletaria as etiquetas, ele sugere schedule_pickup se seu plano incluir coleta pela transportadora, ou deixá-las com a transportadora.

Marcar uma etiqueta como impressa tem os mesmos efeitos que imprimi-la no aplicativo web. Cada cliente recebe seu e-mail de rastreamento de Etiqueta Impressa da conta cerca de uma hora depois, se você tiver esse e-mail ativado. Webhooks de rastreamento de parceiros são acionados, assim como quaisquer automações configuradas para rodar quando uma etiqueta é impressa. É por isso que há pré-visualização primeiro: confirme somente depois que as etiquetas estiverem realmente impressas. Pelo mesmo motivo, a ferramenta é anotada como destructiveHint: true, para que seu cliente possa perguntar antes de executá-la. Nenhum dinheiro é movimentado. Bom saber: Somente pedidos com etiqueta comprada com uma etiqueta registrada mudam. Pedidos que já estão com etiqueta impressa são listados em already_printed_order_ids e deixados como estão, então repetir uma chamada é seguro. Todo o resto é ignorado com um motivo e nunca é movido para trás: pedidos cancelados ou mesclados, pedidos sem etiqueta comprada (incluindo etiquetas anuladas) e pedidos além da impressão, como Aguardando retirada, Em trânsito ou Entregue. Etiquetas UPS não são coletadas por schedule_pickup; agende a retirada UPS paga no aplicativo web Ship.com. Uma etiqueta cuja data de envio tenha mais de 3 dias, ou que já esteja em uma retirada, não é coletada por nenhuma retirada de transportadora, então deixe-a em vez disso. A chamada confirmada verifica cada pedido novamente, então pode diferir da prévia. Um pedido com falha não impede o restante; chame novamente para os IDs em failed. Enquanto as etiquetas de um lote ainda estão sendo compradas, ambas as chamadas retornam marked_count: 0 e uma nota para verificar get_batch_status, e nada muda. Funciona em todos os planos e todos os tipos de conexão. IDs que não são seus são listados em not_found_order_ids; se nenhum for seu, você recebe None of those orders were found in this account., e um lote desconhecido retorna Batch {batch_id} was not found in this account.. Enviar ambos order_ids e batch_id, ou nenhum, retorna um erro.

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

check_pickup_availability

Somente leitura

Pergunta à transportadora se ela pode fazer a retirada no seu endereço de retirada em uma data específica. Não agenda nada e não muda nada no Ship.com. A transportadora é escolhida da mesma forma que schedule_pickup escolhe, a partir dos pacotes com etiqueta impressa que uma retirada coletaria. Diferente da prévia de schedule_pickup, também retorna o motivo da transportadora quando um endereço não é elegível.

Parâmetro	Tipo	Obrigatório	Descrição
date	string	Sim	A data de retirada desejada, como YYYY-MM-DD.

Retorna: available (booleano), pickup_date (YYYY-MM-DD, ou nulo), carrier (USPSDirect ou MoveMethod) e error (a explicação da transportadora quando a retirada não está disponível, caso contrário nulo).

Bom saber: Para USPS, a transportadora usual, uma verificação bem-sucedida significa que seu endereço é elegível para retirada pela transportadora. Não reserva a data: USPS normalmente não retorna uma data própria, então pickup_date ecoa a data que você pediu, e USPS aceita ou recusa a data quando você agenda. Se USPS sugerir uma próxima data elegível, pickup_date é essa data e available é verdadeiro somente quando ela cai em ou antes da data solicitada. Um endereço inelegível ou um problema da transportadora é um resultado normal, não um erro: available: false, pickup_date: null e o texto da transportadora em error. Ship.com não verifica datas passadas ou fins de semana; a transportadora decide. Sem pacotes com etiqueta impressa aguardando, ou apenas pacotes UPS, normalmente verifica USPS Direct. Etiquetas compradas mas não marcadas como impressas não contam; marque-as com mark_labels_printed primeiro. Funciona em todos os planos, incluindo planos sem retirada pela transportadora. Uma data ausente ou ilegível retorna date is required, formatted YYYY-MM-DD..

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

schedule_pickup

Altera dadosPrévia, depois confirmaRequer: Retirada pela transportadora

Agenda uma retirada gratuita pela transportadora no seu endereço de retirada. Uma retirada coleta todos os pacotes elegíveis de uma vez, e você não pode escolher um subconjunto. Cada pedido coletado muda para Aguardando retirada. Pacotes com etiqueta UPS nunca são incluídos; agende uma retirada UPS paga no aplicativo web Ship.com em vez disso.

Um pacote é elegível quando seu pedido está em Etiqueta impressa, não está já em uma retirada, não tem etiqueta UPS e tem uma data de envio não anterior a 72 horas atrás (datas de envio futuras contam). Pacotes em um formulário SCAN qualificam da mesma forma. Um pedido cuja etiqueta foi comprada mas ainda não marcada como impressa permanece em Etiqueta comprada e não é coletado. A prévia lista essas etiquetas em unprinted_order_ids e diz isso na nota; uma vez impressas, marque-as com mark_labels_printed e faça a prévia novamente. Não há limite de quantos pacotes uma retirada coleta.

Parâmetro	Tipo	Obrigatório	Descrição
date	string	Sim	A data de retirada, como YYYY-MM-DD.
location	string	Sim	Onde a transportadora deve coletar os pacotes. Um de In/At Mailbox, Front Door, Back Door, Side Door, Knock on Door/Ring Bell, Mail Room, Office, Reception ou Other. Maiúsculas e minúsculas não importam, mas o texto deve corresponder exatamente, sem espaços extras. Use Other junto com special_instructions que descrevem o local. Salvo como enviado.
special_instructions	string	Não	Uma nota para a transportadora. Para retiradas USPSDirect, emojis e outros caracteres não ASCII são removidos e pontuação diferente de - . , ' & vira um espaço antes do envio, porque USPS rejeita caracteres como ! e ?. Sua conta mantém a nota como você escreveu.
confirm	booleano	Não	Omita ou false para prévia; nada é agendado. true agenda a retirada.

Retorna: Uma prévia retorna preview: true, would_schedule, pickup_date (sua data solicitada), location, carrier, available, eligible_order_count, eligible_order_ids, ups_eligible_count (pacotes com etiqueta UPS aguardando que esta retirada não coletará), already_scheduled_on_date, unprinted_label_count e unprinted_order_ids (etiquetas compradas que esta retirada coletaria uma vez marcadas como impressas) e um note. Uma chamada confirmada retorna scheduled: true, pickup_id (use com get_pickup e cancel_pickup), carrier_confirmation (o número de confirmação da transportadora; raramente nulo quando a transportadora não retorna nenhum, e list_pickups então mostra "0"), carrier, pickup_date, order_ids, order_count e status ("Aguardando retirada", o novo status dos pedidos coletados).

Bom saber: Seu plano deve incluir retirada pela transportadora (Growth, Executive ou Ultra). O plano é verificado primeiro, mesmo para uma prévia, e caso contrário você recebe Your current Ship.com plan does not include carrier pickup scheduling. Upgrade the subscription to use this tool.. Chame uma vez sem confirm para ver o que seria coletado, depois novamente com confirm: true. A chamada confirmada re-verifica tudo naquele momento, então suas contagens podem diferir da prévia se os pedidos mudaram entre eles. would_schedule é verdadeiro quando há pacotes elegíveis e nenhuma retirada gratuita nessa data ainda; não reflete available, e a prévia não inclui o motivo da transportadora, então use check_pickup_availability para ver o porquê. Você pode ter uma retirada gratuita por data; uma segunda é recusada até você cancelar a primeira. Uma retirada UPS paga na mesma data não conta. Uma reserva é executada por vez por conta. Uma segunda chamada confirmada espera a primeira terminar e então executa suas próprias verificações, então uma duplicata para a mesma data é recusada. Se a primeira ainda estiver em execução após cerca de 20 segundos, a segunda retorna um erro e não agenda nada. Com nada elegível, a chamada confirmada retorna No orders can be set to pickup.. Se etiquetas compradas mas não impressas estiverem aguardando, esse erro também lista seus IDs de pedido para marcar como impressas: os primeiros 100, depois quantos mais, já que mark_labels_printed aceita até 100 por chamada. Outros erros não incluem a lista. Uma recusa da transportadora, como uma data inválida ou caracteres que USPS não aceita, volta palavra por palavra e nada é agendado. Para agendar a visita, a transportadora recebe seus dados de contato, como nome, nome comercial, e-mail e telefone. Retiradas são gratuitas: nada é cobrado do seu saldo de postagem ou cartão, e Ship.com não envia e-mail.

{"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

Altera dadosPrévia, depois confirma

Cancela uma retirada gratuita com a transportadora. Cada pedido vinculado à retirada volta para Etiqueta impressa e é desvinculado dela, então uma retirada posterior pode coletá-lo. Retiradas UPS pagas são recusadas tanto na prévia quanto na chamada confirmada; cancele-as no aplicativo web Ship.com, onde a taxa é reembolsada ao seu saldo de postagem.

Parâmetro	Tipo	Obrigatório	Descrição
pickup_id	inteiro	Sim	O pickup_id da retirada, de schedule_pickup, list_pickups ou get_pickup. Não é o número de confirmação da transportadora.
confirm	booleano	Não	Omita ou false para prévia; nada muda. true cancela a retirada.

Retorna: Uma prévia retorna preview: true, pickup_id, carrier_confirmation, pickup_date, status (o status da transportadora, como "agendada" ou "cancelada"), canceled, linked_order_count (pedidos atualmente vinculados, em qualquer status) e um note. Uma chamada confirmada retorna canceled: true, pickup_id, carrier (USPSDirect ou MoveMethod), reverted_order_ids, reverted_order_count e status ("Etiqueta impressa", o novo status desses pedidos).

Bom saber: Chame uma vez sem confirm para ver a retirada e quantos pedidos reverteriam, depois novamente com confirm: true. A prévia não contata a transportadora. Pedidos mudam somente após a transportadora confirmar o cancelamento; se a transportadora recusar, seu erro volta e a retirada permanece agendada sem nada mudado. Cada pedido vinculado é definido de volta para Etiqueta impressa qualquer que seja seu status atual, então cancele apenas retiradas que ainda não aconteceram. Uma retirada já cancelada faz prévia normalmente, com a nota "Esta retirada já está cancelada."; confirmar retorna Pickup {pickup_id} is already canceled. sem contatar a transportadora. Um ID que não existe ou pertence a outra conta retorna Pickup {pickup_id} was not found in this account.. Funciona em todos os planos. Nenhum dinheiro é movido e Ship.com não envia e-mail.

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

list_pickups

Somente leitura

Lista suas retiradas mais recentes, das mais novas para as mais antigas, incluindo retiradas canceladas e retiradas UPS pagas. Use o pickup_id de uma linha com get_pickup para ver seus pedidos, ou com cancel_pickup para cancelar uma gratuita.

Parâmetro	Tipo	Obrigatório	Descrição
limit	inteiro	Não	Quantas retiradas retornar, de 1 a 50. Padrão 10. Valores fora desse intervalo são limitados, não rejeitados.

Retorna: pickups e count (as linhas retornadas, não um total da conta). Cada linha tem pickup_id, carrier_confirmation, date (YYYY-MM-DD), status (o texto de status da transportadora), canceled, created, location, special_instructions (como você escreveu, ou nulo), carrier (USPS/MoveMethod para retiradas gratuitas, UPS para pagas) e fee_amount (a taxa UPS cobrada do seu saldo de postagem; nulo para retiradas gratuitas).

Bom saber: Linhas são ordenadas por quando a retirada foi criada, não pela data de retirada. Não há paginação, então apenas suas 50 retiradas mais recentes podem ser acessadas. O campo de data é date aqui, mas pickup_date nas outras ferramentas de retirada. created é um horário UTC sem designador de fuso, como 2026-10-05T18:42:11.523. Linhas não incluem pedidos. Lê apenas os registros do Ship.com e não contata a transportadora. Funciona em todos os planos.

{"limit": 5}

get_pickup

Somente leitura

Retorna uma retirada e os pedidos vinculados a ela. Use para ver quais pacotes uma retirada coletará, ou para verificar uma retirada antes de cancelá-la com cancel_pickup.

Parâmetro	Tipo	Obrigatório	Descrição
pickup_id	inteiro	Sim	O pickup_id da retirada, de schedule_pickup ou list_pickups. Não é o número de confirmação da transportadora.
Retorna: pickup_id, carrier_confirmation, pickup_date (YYYY-MM-DD), status (o texto de status da transportadora), location, special_instructions, created, canceled, canceled_date (nulo, a menos que cancelado), carrier (USPS/MoveMethod para retiradas gratuitas, UPS para pagas), fee_amount (a taxa da UPS cobrada do seu saldo de postagem; nulo para retiradas gratuitas), orders e order_count. orders lista cada pedido vinculado à retirada, com a data do pedido mais recente primeiro, cada um com order_id, status (o rótulo de exibição, como "Aguardando retirada", "Em trânsito" ou "Entregue") e tracking_number.

Bom saber: Uma retirada cancelada normalmente mostra uma lista orders vazia, porque o cancelamento desanexa seus pedidos. created e canceled_date são horários UTC sem designador de fuso. Um ID que não existe ou pertence a outra conta retorna Pickup {pickup_id} was not found in this account., e um ID ausente retorna pickup_id is required.. Ele lê apenas os registros do Ship.com e não contata a transportadora. Funciona em todos os planos.

{"pickup_id": 51874}

Envio em lote e sincronização de plataforma

Estas ferramentas lidam com trabalho em massa: buscar novos pedidos de uma loja conectada e comprar etiquetas para muitos pedidos de uma vez. Um fluxo típico: verifique suas lojas com list_connected_platforms, importe pedidos recentes com sync_platform_orders e acompanhe o trabalho com get_sync_status, depois visualize e confirme um lote com trigger_batch_purchase (somente conexões com token de acesso) e acompanhe com get_batch_status. Ambos os tipos de trabalho são executados em segundo plano, então cada um começa com uma chamada que retorna um ID e termina com uma ferramenta de status que você consulta.

Cada solicitação conta para o limite de 60 solicitações por minuto por token, incluindo initialize e tools/list. Ao consultar uma ferramenta de status, aguarde alguns segundos entre as chamadas. Acima do limite, você recebe HTTP 429 com Retry-After: 60. Lotes e trabalhos de sincronização são limitados à sua própria conta: um ID de outra conta é tratado como se não existisse.

trigger_batch_purchase

Altera dadosGasta dinheiroVisualizar, depois confirmarRequer: Envio em loteSomente conexões com token de acesso

Compra etiquetas USPS Ground Advantage para muitos pedidos prontos para envio de uma vez. Sem confirm, ele avalia cada pedido elegível e retorna preços por pedido e um total de postagem, sem comprar nada. Com confirm: true, ele avalia os pedidos novamente e coloca o lote na fila. Um trabalhador em segundo plano então compra uma etiqueta por pedido avaliado, geralmente em cerca de um minuto; acompanhe com get_batch_status. Etiquetas compradas não são marcadas como impressas: depois de impressas, chame mark_labels_printed com o batch_id para que uma retirada da transportadora possa coletá-las.

Parâmetro	Tipo	Obrigatório	Descrição
order_ids	matriz de inteiros	Não	Pedidos a incluir. Omita para incluir todos os pedidos Prontos para envio. Apenas pedidos com status Pronto para envio e com endereço físico são usados; outros IDs (status errado, sem endereço, não encontrado) são ignorados sem linha e sem erro. Entradas que não podem ser lidas como um número inteiro, incluindo decimais como 12.0, são ignoradas. Uma matriz vazia, uma matriz sem IDs utilizáveis ou um valor que não seja uma matriz também inclui todos os pedidos Prontos para envio.
max_total	número	Não	Teto de gastos em dólares para a postagem do lote (prêmios de seguro não contados). Em uma visualização, exceder define over_max_total: true. Na confirmação, o total atualizado é verificado e o lote é recusado se for maior. 0 ou menos recusa qualquer lote que custe algo. Padrão: sem teto.
weight_oz	número	Não	Peso de pacote substituto em onças, usado apenas para pedidos sem peso salvo. Pedidos que têm peso sempre são avaliados com o próprio peso. Sem isso, um pedido sem peso recebe um erro por pedido.
confirm	booleano	Não	Omita ou false para visualizar. true para colocar o lote na fila de compra. Padrão false.
insurance	booleano	Não	Substitui a configuração da sua conta de segurar todos os envios para este lote. Quando ativado, cada pedido é segurado pelo total do pedido; pedidos com total de $0 são enviados sem seguro. Padrão: configuração da sua conta.

Retorna: Uma visualização retorna preview: true, orders, rated_count, failed_count, total_cost (postagem para os pedidos avaliados), insurance, over_max_total, in_progress_batch (sempre null) e um note. Cada linha de pedido tem order_id, name, city, state e ou rate, method ("USPS Ground Advantage", mais " (Cubic)" ou " (Cubic Soft Pack)" quando o preço cúbico se aplica) e service_level (como usps_ground_advantage), ou um error explicando por que não pôde ser avaliado, como peso ausente ou endereço APO/FPO. As linhas são ordenadas pelo nome do destinatário. Uma confirmação retorna batch_id, requested_count (pedidos na fila), total_cost (postagem da avaliação atualizada), insurance e um note.

Bom saber: Disponível em conexões com token de acesso. Não é oferecido em conexões autorizadas pelo login do Ship.com (OAuth), como o conector de diretório do Claude e conectores personalizados do claude.ai; lá está ausente de tools/list, e uma chamada retorna erro JSON-RPC -32602 dizendo que a ferramenta não está disponível. get_batch_status funciona em todas as conexões. Nada vincula uma confirmação a uma visualização anterior: a confirmação avalia cada pedido do zero, então o total pode diferir, e pedidos que falham na avaliação são deixados de fora sem serem listados. Se nenhum pedido puder ser avaliado, a confirmação retorna um erro e não coloca nada na fila. Para fixar tanto os pedidos quanto o gasto, confirme com o mesmo order_ids e um max_total próximo ao total visualizado. Um lote pode estar em andamento por conta, incluindo lotes iniciados no aplicativo web do Ship.com; até terminar, visualização e confirmação retornam um erro que nomeia o ID do lote.

O dinheiro é movimentado quando o trabalhador compra as etiquetas. A postagem de cada etiqueta sai do seu saldo de postagem, e prêmios de seguro, quando ativados, são cobrados além do total de postagem e não estão na visualização. Com recarga automática ativada, se seu saldo não cobrir a postagem do lote, seu método de pagamento registrado é cobrado uma vez antecipadamente pela diferença ou pelo valor da sua recarga automática, o que for maior; se essa cobrança não puder ser feita porque não há método de pagamento ou a conta está suspensa, nenhuma etiqueta é comprada. Se uma etiqueta falhar por motivo de pagamento, o trabalhador para e marca os pedidos restantes como Não tentados para evitar cobranças repetidas. Cada etiqueta conta para o limite mensal de envios do seu plano, que a visualização não verifica. Um pedido que já tem etiqueta não é comprado duas vezes.

Cada chamada, incluindo a visualização, solicita uma tarifa USPS ao vivo para cada pedido, então lotes grandes são lentos. Não há limite de tamanho de lote e nenhuma escolha de serviço. Etiquetas são pacotes sem assinatura, com data de envio quando o lote é colocado na fila, no formato de etiqueta salvo. A avaliação, mesmo na visualização, salva o endereço do destinatário e o peso usado (incluindo um fallback weight_oz) em cada pedido. A avaliação em lote não executa validação de endereço; se um pedido falhar na avaliação, tente get_rates nele sozinho para ver o motivo da transportadora.

{"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

Somente leituraRequer: Envio em lote

Relata o progresso ou resultado de uma compra em lote. Omita batch_id para obter o lote em andamento, ou seu lote mais recente se nenhum estiver em execução. Ele lê todos os lotes da sua conta, incluindo lotes iniciados no aplicativo web do Ship.com, e funciona em todos os tipos de conexão.

Parâmetro	Tipo	Obrigatório	Descrição
batch_id	inteiro	Não	O batch_id de trigger_batch_purchase. Padrão: o lote em andamento, caso contrário o lote mais recente.

Retorna: Enquanto as etiquetas estão sendo compradas: complete: false, batch_id, requested, completed (pedidos tentados até agora, falhas incluídas; 0 até o trabalhador começar) e um note. Quando concluído: complete: true, batch_id, orders, purchase_success, purchase_failed, requested, total (postagem mais seguro) e shipping_balance (seu saldo de postagem). Cada pedido tem order_id, name, city, state, shipping_cost (postagem mais seguro), tracking_number e status (como "Etiqueta comprada" ou "Etiqueta impressa"), ordenados por data do pedido. unprinted_count diz quantos estão comprados mas ainda não marcados como impressos; quando está acima de 0, next_step diz para você chamar mark_labels_printed com este batch_id depois de impressos. Se etiquetas falharam, failed_orders lista cada order_id com um reason; lotes mais antigos em vez disso retornam uma string errors combinada e um sinalizador limit_reached. Um motivo é um código curto, opcionalmente seguido por " - " e detalhes, por exemplo "Limite atingido - 100" quando o limite mensal de envios foi atingido, ou "Não tentado -..." para pedidos pulados após um problema de pagamento parar o lote. Sem lotes, ou com um batch_id desconhecido, você recebe no_status: true e um note como resultado normal, não um erro.

Bom saber: Requer o mesmo recurso de plano que trigger_batch_purchase, então depois de mudar para um plano sem envio em lote, você não pode ler lotes passados aqui. orders e purchase_success cobrem os pedidos do lote de Etiqueta comprada até Entregue, então pedidos impressos, retirados e enviados permanecem listados. Pedidos cuja etiqueta foi anulada ou que foram cancelados saem, assim como pedidos em devolução, então purchase_success mais purchase_failed podem não ser iguais a requested. Um lote que parou antes de comprar qualquer coisa, por exemplo porque o pagamento antecipado não pôde ser feito, relata complete: true sem pedidos e sem detalhes de falha. Um lote cancelado também relata complete: true; seus pedidos anulados saem de orders. Raramente, um lote que falhou antes do processamento começar continua relatando complete: false; se completed permanecer em 0 por vários minutos, verifique os pedidos com list_orders. Sem arquivos de etiqueta aqui: use get_label por pedido, e get_balance para seu saldo atual.

{"batch_id": 91544}

list_connected_platforms

Somente leitura

Lista as plataformas de vendas conectadas à sua conta, com o status de cada conexão e o último horário de sincronização. Ele lê o que o Ship.com armazenou e não contata as plataformas.

Sem parâmetros.

Retorna: platforms e count. Cada plataforma tem name, status, error e last_sync. Apenas plataformas conectadas aparecem, nesta ordem e escritas exatamente: PayPal, Bomb Party, Shopify, Etsy, Ebay, SquareSpace, Wix, TikTok, WooCommerce, Maverick, Walmart. status geralmente é Active, Issues ou Disconnected, ou uma string vazia se nunca foi definido. error é uma mensagem de erro de conexão, atualmente relatada apenas para Walmart e caso contrário null. last_sync é UTC, ISO-8601 sem offset, ou null se a loja nunca sincronizou; WooCommerce mostra 0001-01-01T00:00:00 em vez de null. Com nada conectado: platforms: [], count: 0. Good to know: Uma entrada por plataforma, mesmo que você tenha conectado várias lojas nela. Importações do Square, Jotform e de planilhas ou e-mails não são listadas. Uma loja Shopify que revogou o acesso do Ship.com ainda pode aparecer, como Disconnected; reconecte-a em Configurações → Integrações antes de sincronizar. Leia last_sync junto com status: em uma entrada Shopify Disconnected, pode ser o momento em que o problema foi encontrado, em vez de uma sincronização bem-sucedida.

sync_platform_orders

Altera dados

Inicia uma importação em segundo plano de pedidos recentes da sua loja Shopify ou Etsy conectada e retorna imediatamente com um job_id. Um worker de sincronização pega o job, geralmente em segundos; acompanhe com get_sync_status. A importação apenas adiciona pedidos que o Ship.com ainda não possui, então executá-la novamente é seguro.

Parâmetro	Tipo	Obrigatório	Descrição
platform	string	Sim	shopify ou etsy. Não diferencia maiúsculas de minúsculas; espaços ao redor são ignorados. Qualquer outro valor, ou nenhum, retorna um erro "Unknown platform".

Retorna: job_id, platform (minúsculas), status e um note informando se um novo job foi enfileirado ou se um existente foi retornado. status é sempre queued, mesmo quando o job retornado já está em execução.

Good to know: A plataforma já deve estar conectada em Configurações → Integrações; para Shopify, a conexão também deve estar ativa, não desinstalada ou revogada. Se uma sincronização para essa plataforma já estiver enfileirada ou em execução, incluindo uma iniciada fora do MCP, como a importação que roda quando você conecta uma loja pela primeira vez, esse job é retornado em vez de um segundo. O Shopify importa pedidos criados nos últimos 7 dias (30 dias se a loja nunca concluiu uma sincronização), além de novos clientes da mesma janela. O Etsy importa pedidos dos últimos 7 dias. Pedidos existentes no Ship.com não são alterados e nada é gravado de volta na loja. Pedidos recém-importados podem acionar suas próprias regras de automação para pedidos importados e ganhar pontos de recompensa, como qualquer outra importação. Se a loja revogou o acesso do Ship.com, a conexão Shopify é marcada como desconectada ou a conexão Etsy é removida, e você precisará reconectá-la. Nenhum dinheiro é movimentado e nenhum e-mail é enviado. No caso raro de o job não poder ser enfileirado, você recebe "Could not queue the sync job"; tente novamente em instantes.

{"platform": "shopify"}

get_sync_status

Somente leitura

Verifica seus jobs de importação de pedidos em segundo plano. Passe um job_id de sync_platform_orders para ver esse job específico, ou omita-o para listar seus 10 jobs mais recentes, do mais novo para o mais antigo.

Parâmetro	Tipo	Obrigatório	Descrição
job_id	inteiro	Não	O job a ser consultado. Omita para listar jobs recentes. Envie um número inteiro; um valor que não possa ser lido como número retorna "job_id must be an integer."; um ID que não existe ou pertence a outra conta retorna um erro de não encontrado.

Retorna: Com job_id, os campos desse job diretamente (sem wrapper): job_id, service, platform, status (queued, running, completed ou error), queued, started, completed, error e last_sync. Sem ele, jobs (até 10 desses objetos) e count. Os horários estão em UTC, ISO-8601 sem offset; started e completed são null até serem alcançados. error é o detalhe de falha em texto livre, ou null. Para jobs do Shopify e Etsy, platform é shopify ou etsy e last_sync é o último horário de sincronização atual da conexão, o mesmo em cada linha para aquela plataforma, em vez de por job. Para outros jobs, platform repete o valor de service e last_sync é null.

Good to know: A lista cobre todo o trabalho de importação em segundo plano da sua conta, não apenas Shopify e Etsy: uploads de planilhas, pedidos encaminhados por e-mail, outras plataformas e atualizações de rastreamento também aparecem. completed significa que o job foi executado, não que pedidos chegaram; uma importação que encontrou um problema ainda pode terminar como completed sem erro. Para confirmar que os pedidos chegaram, verifique se last_sync avançou e se a conexão ainda está Active em list_connected_platforms, ou liste seus pedidos. Um job do Shopify ou Etsy ainda em execução cerca de 10 minutos após o início, ou um que encontre uma falha temporária, é encerrado com erro e tentado novamente como um novo job, até 5 vezes para travamentos. O texto do erro nomeia o ID do novo job, então uma linha error pode ter um acompanhamento mais recente acima dela. Um job é marcado como completed cerca de 10 segundos após o término da importação.

{"job_id": 73120458}

Clientes e e-mail

Estas ferramentas trabalham com seu catálogo de endereços de clientes e permitem que você alcance clientes por e-mail. Um fluxo típico: encontre alguém com list_customers, leia os detalhes e o histórico de pedidos com get_customer, corrija os dados de contato ou endereço com create_or_update_customer e então escreva para eles com send_customer_email. Para campanhas de recuperação, list_lapsed_customers encontra clientes que não pediram recentemente e send_mass_marketing_email envia e-mail para um segmento inteiro de uma vez.

Enviar e-mail é um fluxo de duas etapas. Chame uma ferramenta de envio sem confirm para pré-visualizar (nada é enviado) e depois chame novamente com "confirm": true para enviar. E-mails contam contra a cota de e-mails de marketing do seu plano, e cada ferramenta aqui só vê seus próprios clientes. Consulte Marketing-email allowance e Merge placeholders.

list_customers

Somente leitura

Lista os clientes no seu catálogo de endereços do Ship.com, excluindo os deletados. Filtre por nome ou e-mail e ordene alfabeticamente ou pelo pedido mais recente. As linhas são compactas; chame get_customer para detalhes completos e histórico de pedidos. Diferente das ferramentas de segmento de e-mail, esta lista inclui clientes que não têm endereço de e-mail.

Parâmetro	Tipo	Obrigatório	Descrição
query	string	Não	Filtro que não diferencia maiúsculas de minúsculas. Corresponde a clientes cujo primeiro ou último nome começa com o texto, ou cujo e-mail o contém. Apenas um termo: "jane doe" não é dividido em primeiro e último nome. Telefone, cidade e empresa não são pesquisados.
sort	string	Não	name (padrão): por último nome e depois primeiro nome; clientes sem último nome vêm por último. recent: clientes com os pedidos mais recentes primeiro, ignorando pedidos cancelados e mesclados; clientes sem pedidos vêm por último. Qualquer outro valor ordena por nome.
page	inteiro	Não	Número da página, começando em 1. Padrão 1.
page_size	inteiro	Não	Linhas por página, de 1 a 50. Padrão 25. Valores fora desse intervalo são limitados a ele.

Retorna: customers, cada um com customer_id, name, email, phone, city e state (null quando não registrado); além de page e page_size conforme aplicados, total (correspondências em todas as páginas) e sort (a ordenação realmente usada).

Good to know: Uma página além do final retorna uma lista customers vazia com o total real. Clientes que empatam na ordem de classificação não têm ordem garantida entre si.

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

get_customer

Somente leitura

Retorna o registro completo de um cliente: nome, empresa, dados de contato, aniversário, endereço para correspondência, contagem de pedidos e gasto total ao longo da vida, e seus pedidos mais recentes.

Parâmetro	Tipo	Obrigatório	Descrição
customer_id	inteiro	Sim	O ID do cliente, de list_customers.

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

Good to know: O Ship.com armazena aniversários apenas com mês e dia, então birthday retorna com o ano 1900 (por exemplo "1900-04-12T00:00:00"); ignore o ano. recent_orders lista até 20 pedidos, do mais novo para o mais antigo. order_count, total_spent e recent_orders excluem pedidos cancelados e mesclados, mas incluem pedidos que ainda não foram enviados; a contagem e o total cobrem todos esses pedidos, não apenas os 20 listados. order_number é null quando um pedido não tem número, e country é "US" quando nenhum está armazenado. Um ID de cliente que não está na sua conta retorna um erro como Customer 482913 was not found in this account.

{ "customer_id": 482913 }

create_or_update_customer

Altera dados

Adiciona um cliente ao seu catálogo de endereços ou atualiza um que você já possui. Omita customer_id (ou passe 0) para criar um cliente; passe o ID de um cliente existente para atualizá-lo. As alterações são aplicadas imediatamente, sem etapa de confirmação.

Parâmetro	Tipo	Obrigatório	Descrição
customer_id	inteiro	Não	O cliente a ser atualizado. Omita ou passe 0 para criar um novo cliente. Clientes deletados não podem ser editados.
first_name	string	Sim	Primeiro nome. Não pode estar em branco.
last_name	string	Sim	Último nome. Não pode estar em branco.
email	string	Não	Endereço de e-mail. O formato não é verificado.
phone	string	Não	Número de telefone, armazenado como fornecido.
birthday	string	Não	Mês e dia, mês primeiro, como "04/12" ou "4/12". Nenhum ano é armazenado. Como o mês vem primeiro, "12/04" é 4 de dezembro. Um valor com ano, uma data com dia primeiro como "25/12", 29 de fevereiro ou uma string vazia causa erro e nada é salvo.
street1	string	Não	Linha 1 do endereço. Se estiver em branco e street2 estiver definido, street2 sobe para a linha 1.
street2	string	Não	Linha 2 do endereço, como apartamento ou sala.
street3	string	Não	Linha 3 do endereço.
city	string	Não	Cidade.
state	string	Não	Código do estado ou província, como "TX". Verificado contra a lista de códigos do país. Um valor que não seja um código válido (por exemplo "Texas") é descartado sem erro, então verifique address.state no resultado.
zip	string	Não	CEP ou código postal. Envie como string para que os zeros à esquerda sejam mantidos.
country	string	Não	Código de país de duas letras, como US ou CA. Padrão US.
company	string	Não	Nome da empresa.

Retorna: customer_id (novo ou existente), created (true quando um cliente foi adicionado), name, email, phone, company, birthday, address, orders_updated e note. Os valores são retornados como armazenados, após a verificação do estado, a promoção da linha 2 e o padrão de país. orders_updated conta os pedidos alterados para corresponder (sempre 0 na criação), e note os resume ou é null. Bom saber: Uma atualização substitui o registro inteiro. Qualquer campo opcional que você omitir é limpo, e country volta para US. Para alterar um campo, leia o cliente com get_customer primeiro, depois envie todos os campos de volta com a sua alteração aplicada.

Toda atualização, mesmo uma que não altere o nome, também atualiza os pedidos do cliente que ainda não têm etiqueta e que ainda carregam o nome que o cliente tinha antes da atualização. Esses pedidos recebem o novo nome, empresa, e-mail, telefone e endereço do cliente, para que a próxima etiqueta imprima os dados corrigidos. Campos que você omitiu também são limpos nesses pedidos, então uma atualização parcial pode apagar o endereço de entrega deles. Pedidos com etiqueta comprada, impressa ou enviada nunca são alterados, e pedidos com um nome de destinatário diferente são deixados como estão.

Criar um cliente não verifica duplicatas; criar alguém que já está no seu catálogo de endereços adiciona um segundo registro. Nomes ausentes retornam first_name and last_name are required., e um customer_id que não está na sua conta retorna o erro de não encontrado descrito em 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

Envia e-mailPreview, depois confirmRequer: E-mail de marketing

Envia um e-mail de marketing para um dos seus clientes, em seu nome. Identifique o destinatário com customer_id ou order_id; o endereço de e-mail vem desse cliente ou pedido. O assunto e a mensagem podem usar placeholders de mesclagem como {First Name}, preenchidos para o destinatário.

Parâmetro	Tipo	Obrigatório	Descrição
customer_id	inteiro	Um destes dois	O ID do cliente destinatário. Envie este ou order_id, não ambos.
order_id	inteiro	Um destes dois	Um pedido na sua conta, em qualquer status. O e-mail vai para o endereço do pedido; pedidos salvos sem um endereço usam o endereço do cliente vinculado. Usar um pedido também preenche placeholders de pedido como {Invoice Number}, {Tracking Link} e {Order Total}, e usa {First Name} e {Last Name} do nome de destinatário do pedido.
subject	string	Sim	Linha de assunto. Suporta placeholders de mesclagem.
message	string	Sim	Corpo do e-mail. HTML é permitido. Suporta placeholders de mesclagem.
confirm	booleano	Não	Omita ou use false para visualizar; nada é enfileirado. true envia o e-mail.

Retorna: Uma visualização retorna preview (true), recipient_name, recipient_email, subject, limit_check e um note. Um envio confirmado retorna queued (true), recipient (name, email), subject e um note. O assunto é ecoado como você o escreveu, com placeholders ainda não preenchidos. limit_check tem allowed, reason, limit, used e message; os últimos quatro são nulos quando o envio é permitido (veja Permissão de e-mail de marketing).

Bom saber: A visualização verifica o destinatário e sua permissão; ela não renderiza o e-mail. Com "confirm": true, as mesmas verificações são feitas novamente, depois o e-mail é enfileirado e enviado cerca de um minuto depois. Os placeholders são preenchidos quando o e-mail é enfileirado. Não há opção de agendamento nesta ferramenta; use send_mass_marketing_email com scheduled_at para envios programados.

Uma visualização não é necessária antes de "confirm": true, e não há proteção contra duplicatas: confirmar duas vezes envia dois e-mails. Nenhuma ferramenta cancela um e-mail enfileirado. Todo e-mail inclui um link de cancelamento de inscrição, e endereços que cancelaram a inscrição nos e-mails de marketing do Ship.com são ignorados. Se suas configurações de e-mail copiarem você nos e-mails que envia, isso também se aplica aqui.

Erros incluem Provide exactly one of customer_id or order_id to identify the recipient., subject and message are required., um erro de não encontrado para um cliente ou pedido que não está na sua conta, e That recipient has no email address on file.. Se esse último aparecer para um pedido cujo cliente tem um e-mail, envie por customer_id em vez disso. Quando sua permissão é esgotada, a chamada de confirmação é recusada com a mensagem de permissão.

{
  "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

Envia e-mailPreview, depois confirmRequer: E-mail de marketing

Envia uma campanha de e-mail de marketing para um segmento dos seus clientes, ou para toda a sua lista com e-mail. Filtros reduzem o público por histórico de compras. Isso envia e-mails reais e não pode ser desfeito depois que o envio começa, então sempre visualize primeiro e verifique a contagem de destinatários.

Parâmetro	Tipo	Obrigatório	Descrição
filters	array de strings	Não	Filtros de segmento, aplicados em ordem; cada um reduz a lista. Valores permitidos: "has purchased anything", "has not purchased anything", "has purchased product", "has not purchased product". Omita para enviar e-mail a todo cliente com endereço de e-mail.
days	array de inteiros	Não	A janela de retrospectiva em dias para cada filtro, combinada por posição: days[0] vai com filters[0]. Dê um número positivo para cada filtro. Uma entrada ausente conta como 0, o que faz "has purchased anything" não corresponder a ninguém e "has not purchased anything" corresponder a todos.
products	array de strings	Não	O produto para cada filtro "...product", combinado por posição. Correspondência parcial sem diferenciar maiúsculas nos nomes dos itens pedidos, como "lavender". Ignorado para os filtros "...anything". Uma entrada ausente ou vazia corresponde a qualquer item.
subject	string	Sim	Linha de assunto. Suporta placeholders de mesclagem.
message	string	Sim	Corpo do e-mail. HTML é permitido. Suporta placeholders de cliente; placeholders de pedido não se aplicam a campanhas.
scheduled_at	string	Não	Quando enviar, em ISO 8601, como "2026-10-06T15:00:00Z". Um horário sem offset é lido como UTC. Padrão: agora. Um valor que não pode ser lido também significa agora, então verifique scheduled_for no resultado.
confirm	booleano	Não	Omita ou use false para visualizar; nada é salvo. true cria a campanha.

Retorna: Uma visualização retorna preview (true), recipient_count, sample (até 10 destinatários, cada um com name, email e last_purchase), subject, limit_check e um note. Um envio confirmado retorna queued (true), recipient_count, marketing_email_id (o ID da campanha), scheduled_for (UTC) e um note.

Bom saber: O público são os clientes no seu catálogo de endereços que têm um endereço de e-mail, um por endereço. Quando vários clientes compartilham um endereço idêntico, o mais recentemente adicionado é mantido; endereços com capitalização diferente contam como diferentes. Clientes sem e-mail nunca são incluídos. Qualquer pedido conta como compra para os filtros, incluindo cancelados.

Sempre passe filters, days e products como arrays JSON, mesmo para um único filtro. Um valor que não é um array é ignorado, e uma string de filtro não reconhecida também é ignorada. Filtros ignorados não reduzem nada, então a campanha pode ir para toda a sua lista. Verifique recipient_count na visualização antes de confirmar.

Na confirmação, o segmento é recalculado, então a contagem pode diferir da visualização. A campanha é recusada se ninguém corresponder ou se exceder sua permissão de e-mail de marketing restante; não há envios parciais. A lista de destinatários é fixada quando você confirma. Cada e-mail vai para o endereço do cliente como está no momento do envio, clientes excluídos são ignorados, e cada cliente recebe no máximo um e-mail por campanha. recipient_count pode incluir endereços que cancelaram a inscrição; eles são ignorados no envio.

Uma visualização não é necessária antes de "confirm": true, e não há proteção contra duplicatas: confirmar duas vezes cria duas campanhas. Nenhuma ferramenta cancela uma campanha. As campanhas aparecem com suas outras campanhas de e-mail no aplicativo web do Ship.com. Se suas configurações de e-mail copiarem você nos e-mails que envia, você recebe uma cópia de cada e-mail da campanha.

{
  "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

Somente leitura

Encontra candidatos a reconquista: clientes que não pediram nos últimos N dias (60 por padrão). Não envia nada e não usa sua permissão de e-mail de marketing. Combine com send_mass_marketing_email ou send_customer_email para alcançá-los.

Parâmetro	Tipo	Obrigatório	Descrição
days	inteiro	Não	Janela de retrospectiva em dias. Clientes sem pedido nessa janela são listados. Padrão 60. Use um número positivo.
product	string	Não	Lista clientes que não compraram este produto na janela em vez disso (correspondência parcial sem diferenciar maiúsculas nos nomes dos itens pedidos). Clientes que compraram outras coisas recentemente são incluídos, então isso não é mais uma lista puramente de inativos.
page	inteiro	Não	Número da página, começando em 1. Padrão 1.
page_size	inteiro	Não	Linhas por página, de 1 a 50. Padrão 20.

Retorna: customers, cada um com customer_id, name, email e last_purchase (a data do pedido mais recente de qualquer tipo, ou nulo); além de count (linhas nesta página), total (todas as correspondências), page, page_size e days.

Bom saber: Usa as mesmas regras de público que send_mass_marketing_email: apenas clientes com endereço de e-mail, um por endereço, clientes mais recentemente adicionados primeiro. Qualquer pedido conta como compra, incluindo cancelados. total corresponde ao recipient_count que uma visualização de campanha mostraria para o mesmo segmento: ["has not purchased anything"] com days [N], ou ["has not purchased product"] com os mesmos dias e produto. Para alcance por correio ou telefone, use list_customers, que inclui clientes sem endereço de e-mail.

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

Permissão de e-mail de marketing

Ambas as ferramentas de envio contam contra a permissão de e-mail de marketing do seu plano. O uso mensal é o número de e-mails de marketing que sua conta enviou no mês calendário atual (UTC). Um envio que excederia o limite é recusado como um todo; não há envios parciais.

Plano	E-mails de marketing
Starter, e planos antigos não mais vendidos	Não incluído
Growth	1.000 por mês
Executive	25.000 por mês
Ultra	Ilimitado
Teste gratuito	10 no total para todo o teste (o limite mensal do plano também se aplica)

A permissão nunca bloqueia uma visualização; a visualização relata o resultado em limit_check. Quando o envio é bloqueado, allowed é falso e reason e message dizem o porquê; a chamada de confirmação é então recusada com a mesma mensagem. Para trial_limit e tier_limit, limit e used mostram o limite e quanto dele é usado; para no_entitlement eles são nulos.

reason	Mensagem
trial_limit	Você atingiu o número máximo de e-mails de marketing permitidos durante seu período de teste.
tier_limit	Você atingiu o número máximo de e-mails de marketing permitidos com sua assinatura.
no_entitlement	Campanhas de e-mail de marketing não estão incluídas na sua assinatura atual.

Placeholders de mesclagem

Os placeholders funcionam tanto no assunto quanto na mensagem. Digite-os exatamente como mostrado, incluindo maiúsculas, espaços e chaves; qualquer coisa não reconhecida é deixada como digitada.

Placeholder	Preenche com
{First Name}	O primeiro nome do cliente, ou "there" quando não houver nenhum registrado. Ao enviar por order_id: o primeiro nome do destinatário do pedido, ou "Friend".
{Last Name}	O sobrenome do cliente (o sobrenome do destinatário ao enviar por order_id).
{Your Name}, {Business Name}, {Sign-Off}	Seu nome, o nome da sua empresa (ou seu nome se nenhum estiver definido) e sua assinatura de e-mail salva.
{Birthday}, {Birthday Short}, {Birthday Long}, {Birthday Month}	O aniversário do cliente como 04/12, 4/12, 12 de abril ou Abril. Vazio quando não há aniversário registrado.
{Reward Points Balance}, {Reward Points Remaining}, {Reward Points Required}, {Reward Text}, {Reward Icon}	Detalhes do seu programa de recompensas: o saldo de pontos do cliente, os pontos ainda necessários, os pontos exigidos para uma recompensa, a própria recompensa e o ícone das suas recompensas.
{Reward Message}	Um resumo curto das recompensas. Mostrado apenas nos planos Executive e Ultra com um programa de recompensas ativo, para clientes com histórico de pontos.
{Invoice Number}, {Tracking Link}, {Order Quantity}, {Order Total}, {Order Date Short}, {Order Date Long}, {Reward Points Earned}	Detalhes do pedido. Eles são preenchidos apenas com send_customer_email e order_id. Caso contrário, {Tracking Link} mostra "Unknown", {Order Total} "$0.00", {Order Quantity} "0 items", e o restante fica vazio.

Conta, créditos e relatórios

Estas ferramentas cobrem o lado financeiro e do plano da sua conta. Verifique seu saldo de postagem com get_balance e o que seu plano inclui com get_subscription_info. Veja quem você indicou com get_referral_info e mova o crédito de indicação para postagem com redeem_referral_credit. Depois, revise gastos, impostos sobre vendas e tendências de envio com get_shipping_report, get_tax_report e get_shipping_analytics.

As três ferramentas de relatório exigem um plano que inclua relatórios empresariais, como o Executive; Starter e Growth não o incluem. Elas sempre aparecem em tools/list, e o plano é verificado em cada chamada antes dos argumentos, então uma conta sem o recurso recebe este erro independentemente do que enviar: "Your current Ship.com plan does not include business reporting. Upgrade the subscription to use this tool." Verifique tier.features.business_reporting com get_subscription_info primeiro. Cada ferramenta aqui funciona apenas na sua própria conta. O dinheiro está em dólares americanos como números JSON simples, e os carimbos de data/hora estão em UTC sem sufixo de fuso horário.

get_balance

Somente leitura

Retorna seu saldo atual de postagem e sua configuração de recarga automática. Verifique antes de comprar etiquetas para explicar custos e ver se uma compra deixaria o saldo abaixo de zero. Com a recarga automática ativada, isso reabastece o saldo a partir do método de pagamento registrado.

Sem parâmetros.

Retorna: balance (saldo de postagem em USD; pode ser negativo), currency (USD), auto_recharge_amount (o mínimo adicionado cada vez que o saldo é reabastecido), auto_recharge_enabled (true quando auto_recharge_amount é maior que 0.01) e note, um resumo de uma linha sobre o que a configuração de recarga automática significa para compras de etiquetas.

Bom saber: Este é o mesmo saldo do qual as compras de etiquetas são retiradas, então ele corresponde ao que uma compra verá. Quando o valor é $0.01 (pague conforme usar), uma falta é cobrada por compra mais uma taxa de cartão de $0.30. Em $0, a recarga automática está desativada: a taxa de $0.30 ainda se aplica, e uma compra que seu saldo não cobre falha. auto_recharge_enabled é falso em ambos os casos.

get_subscription_info

Somente leitura

Retorna seu plano com preços, limites e sinalizadores de recursos, além dos seus pagamentos recentes de assinatura. Chame primeiro para verificar se uma ferramenta restrita por plano será executada: business_reporting cobre as ferramentas de relatório nesta seção, batch cobre compras em lote e carrier_pickup cobre agendamento de retiradas.

Sem parâmetros.

Retorna:

• subscription_level: o plano registrado, como starter, growth ou executive. Contas mais antigas podem mostrar um plano legado, e é null quando nenhum plano está registrado.
• is_annual: true para cobrança anual; null quando a conta não tem registro de cobrança de assinatura.
• tier: name, month_price, annual_price (preço anual completo), month_shipment_limit e month_email_limit (-1 significa ilimitado), platform_integration_limit, e features, um 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 e dedicated_support.
• note: presente apenas quando tier é null.
• recent_payments: até 12 pagamentos de assinatura, do mais recente para o mais antigo. Cada um tem date, reason, amount_due, amount_paid, refund (0 ou um valor negativo), charge_id (a referência de pagamento, ou unknown), reference_id, status (Succeeded ou Pending), failed_reason e note.

Bom saber: Planos legados e contas sem plano registrado retornam tier: null com uma nota de que recursos e limites por plano não estão disponíveis; ferramentas restritas por plano tratam essas contas como não autorizadas. subscription_level não reflete cancelamento, e não há campo de cancelamento. Apenas batch, business_reporting e carrier_pickup decidem se as ferramentas MCP são executadas; os outros sinalizadores descrevem o plano, e api_access e ai_features não restringem o acesso MCP. Cobranças com falha são omitidas, e vários registros de uma única cobrança são combinados em uma entrada, com quaisquer reembolsos totalizados em refund. Em registros mais antigos, status pode ser null, e entradas com charge_id unknown têm um reference_id vazio. Sem paginação.

get_referral_info

Somente leitura

Retorna seu saldo de crédito de indicação e todos que você indicou, incluindo detalhes de contato, plano e quanto cada indicação rendeu para você. Para gastar o saldo em postagem, use redeem_referral_credit.

Sem parâmetros.

Retorna: credit_balance (crédito de indicação em USD), currency (USD) e referrals, uma entrada por conta indicada com name, email (pode ser null), signup_date (quando eles fizeram upgrade, ou quando se inscreveram se não fizeram upgrade), subscription_level (o plano deles, como growth), canceled (true se a conta deles estiver cancelada), has_paid (se o bônus único de indicação para eles foi pago) e total_payments (crédito de indicação ganho deles; 0 se nenhum).

Bom saber: referrals lista todas as contas que você indicou, incluindo as canceladas, em nenhuma ordem específica, sem paginação; é uma lista vazia se você não indicou ninguém. name pode ser uma string vazia quando uma conta indicada está faltando parte do nome.

redeem_referral_credit

Altera dadosPré-visualizar, depois confirmar

Move todo o seu saldo de crédito de indicação para seu saldo de postagem para que você possa gastá-lo em etiquetas. Chame sem confirm para pré-visualizar os dois saldos, depois chame novamente com confirm: true para fazer a movimentação. Nunca cobra um cartão ou conta bancária.

Parâmetro	Tipo	Obrigatório	Descrição
confirm	boolean	Não	Omita ou envie false para pré-visualizar; nada é movido. Envie o booleano true para resgatar todo o saldo de indicação. Não há parâmetro de valor.

Retorna: Uma pré-visualização retorna preview: true, referral_credit_balance, shipping_balance (seu saldo de postagem) e um note. Uma chamada confirmada retorna redeemed (o valor movido), referral_balance_after (normalmente 0), shipping_balance_after (seu novo saldo de postagem) e um note como "Moved $30.00 of referral credit into the postage balance."

Bom saber: Sempre resgata o saldo inteiro; resgate parcial não é suportado. A pré-visualização e a confirmação não são vinculadas, então o valor movido é o saldo no momento em que você confirma, que pode diferir da pré-visualização. Uma pré-visualização com saldo de $0 retorna um erro de que não há nada para resgatar. Raramente, $0 significa que o saldo não pôde ser lido, então tente novamente mais tarde se você esperava crédito. Confirmar com $0 é bem-sucedido com redeemed: 0 e não move nada. A movimentação não pode ser desfeita via MCP, e aparece como crédito de indicação em get_shipping_report. Se uma confirmação relatar que o saldo de postagem não aumentou, verifique ambos os saldos com get_balance e get_referral_info antes de tentar novamente, e envie uma confirmação por vez.

{"confirm": true}

get_shipping_report

Somente leituraRequer: Relatórios empresariais

Retorna seus gastos com envio para um ano calendário, divididos por mês, além de um total anual. É construído a partir da atividade do seu saldo de postagem (cobranças de etiquetas, créditos e recargas), não de pedidos.

Parâmetro	Tipo	Obrigatório	Descrição
year	integer	Sim	Ano calendário para relatar, como 2026. Meses e o limite do ano estão em UTC.

Retorna: year, months (uma entrada por mês com atividade, em ordem calendária) e total (o ano inteiro). Cada entrada tem estes campos:

Campo	Tipo	Significado
date	string	Uma data naquele mês, MM/dd/yyyy; nem sempre o dia 1. null no total.
month	string	Nome do mês, como January. TOTAL no total.
shipments	integer	Pedidos com pelo menos uma entrada de saldo no período que não esteja marcada como cancelada, cada um contado uma vez.
postage	number	Postagem de etiquetas, incluindo quaisquer taxas de cartão de pagamento conforme usar, líquida de créditos para etiquetas canceladas.
returnPostage	number	Postagem de etiquetas de devolução.
surcharge	number	Sobretaxa de First Class.
upsAdjustments	number	Ajustes líquidos de cobrança da UPS.
payments	number	Recargas automáticas adicionadas ao seu saldo.
refunds	number	Créditos para etiquetas canceladas.
pending	number	Cobranças de etiquetas cujo cancelamento ainda aguarda reembolso.
referral	number ou null	Crédito de indicação movido para postagem; null quando nenhum.
promotional	number ou null	Créditos promocionais; null quando nenhum.
total	number	Gasto líquido: todas as cobranças menos todos os créditos, sem contar recargas automáticas.

Bom saber: Duas chaves estão em camelCase, returnPostage e upsAdjustments, ao contrário do snake_case usado por outras ferramentas. postage já tem refunds removido, e as cobranças em pending já estão contadas nos campos de cobrança, então não aplique nenhum deles novamente. Outra atividade de saldo também pode afetar total, então pode não ser igual à soma dos campos nomeados. O shipments do ano conta cada pedido uma vez, então pode ser menor que a soma dos meses. Um ano sem atividade retorna uma lista months vazia e um total de zeros, com referral e promotional null. Sem year, a ferramenta retorna "year is required."

{"year": 2026}

get_tax_report

Somente leituraRequer: Relatórios empresariais Retorna o imposto sobre vendas que você coletou por meio de faturas pagas do Ship.com, totalizado por trimestre e por mês, em todos os anos com faturas pagas. Útil ao declarar imposto sobre vendas.

Sem parâmetros.

Retorna: taxes, um objeto cujas chaves são rótulos de períodos e cujos valores são o imposto sobre vendas coletado em USD. Chaves de trimestre têm o formato Q3 2026 e chaves de mês, o formato September 2026. As chaves são ordenadas do ano mais recente para o mais antigo; dentro de um ano, vão de dezembro de volta a janeiro, com cada trimestre logo antes do seu último mês (Q4 2025, December 2025, November 2025, October 2025, Q3 2025,...). Apenas períodos com faturas pagas aparecem, e taxes é {} quando não há nenhum.

Bom saber: O imposto é contabilizado no mês e no trimestre em que a fatura foi paga (UTC). Apenas pedidos com fatura paga do Ship.com são incluídos, portanto pedidos de plataformas de vendas que não foram faturados pelo Ship.com não entram. Uma fatura paga ainda conta se o pedido foi cancelado posteriormente. Quando o mês atual tem faturas pagas, sua chave e todas as chaves de trimestre do ano atual terminam em To Date (por exemplo, October 2026 To Date e Q2 2026 To Date); quando ainda não há nenhuma, nenhuma chave termina assim. Leia o período a partir do início da chave e trate To Date como um rótulo. Não há filtros de data.

get_shipping_analytics

Somente leituraRequer: Relatórios de negócios

Retorna análises de envio para um intervalo de datas em uma única chamada: totais, volume diário de pedidos, status de pedidos, mix de transportadoras, principais destinos e canais de vendas. Os pedidos são agrupados pelo dia em que foram criados (UTC). Sem datas, cobre os últimos 90 dias até hoje.

Parâmetro	Tipo	Obrigatório	Descrição
start_date	string	Não	Primeiro dia do intervalo, YYYY-MM-DD, inclusivo. Padrão: 90 dias antes de end_date.
end_date	string	Não	Último dia do intervalo, YYYY-MM-DD, inclusivo; o dia inteiro é contado. Padrão: hoje (UTC). Deve ser em ou após start_date, e no máximo 366 dias depois dele.

Retorna:

• start_date, end_date: o intervalo usado, YYYY-MM-DD.
• totals: orders (todo pedido criado no intervalo, qualquer status), shipped (pedidos que atualmente têm uma etiqueta comprada) e postage_spent (os preços das etiquetas nesses pedidos enviados).
• daily_volume: {date, orders} por dia, do mais antigo ao mais recente. Dias sem pedidos são omitidos.
• status_distribution: {status, count}, usando os nomes de status da tabela de status de pedidos (como ChooseShipping ou Deleted), não os rótulos de exibição.
• carrier_mix: {carrier, count}. carrier é USPS, MoveMethod (etiquetas USPS compradas por uma segunda rota de compra do Ship.com; conte-as como USPS), UPS, unshipped ou other (etiquetas que não correspondem a nenhuma dessas, como as muito antigas).
• top_destinations: até 10 entradas de {state, country, count} para o estado e país de destino mais comuns. state fica vazio quando ausente, e um país em branco é lido como US.
• sales_channels: {channel, count}, onde channel é a origem do pedido conforme registrada, como Shopify, Etsy, Square ou Jotform. Pedidos criados pela API REST do Ship.com mostram um valor começando com API-, pedidos sem origem registrada mostram manual, e alguns podem mostrar None.
• truncated e note: presentes apenas quando o intervalo teve mais de 100.000 pedidos. Apenas os 100.000 mais recentes foram contados; reduza o intervalo para números exatos.

Status, transportadoras e canais são ordenados por contagem, do maior para o menor, com empates em ordem de nome; destinos desempatam por estado.

Bom saber: Nenhum filtro de status é aplicado, então pedidos cancelados e mesclados contam para todos os totais e detalhamentos. list_orders, por outro lado, filtra por status. "Enviado" significa que o pedido tem uma etiqueta no momento: anular uma etiqueta move o pedido de volta para não enviado. Destinos incluem pedidos não enviados, porque usam o endereço de entrega de cada pedido. O limite de 366 dias permite até 367 dias corridos, contando ambas as extremidades, e o intervalo padrão abrange 91 dias. Erros: "end_date must be an ISO date (YYYY-MM-DD).", o mesmo para start_date, "end_date must be on or after start_date." e "The date range is too large — keep it to 366 days or fewer." Um start_date futuro sem end_date falha na verificação de em ou após.

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

Alterações e suporte

Versionamento e alterações

• O servidor negocia a versão 2025-11-25 ou 2025-06-18 do protocolo MCP durante initialize. Se você solicitar qualquer outra versão, ele responde com 2025-11-25.
• O Ship.com pode adicionar ferramentas, adicionar argumentos opcionais e campos de resultado, e melhorar descrições de ferramentas e mensagens. Crie clientes que ignorem campos que não reconhecem.
• tools/list é a fonte da verdade para as ferramentas e esquemas de argumentos disponíveis para sua conexão. O servidor não envia notificações de mudança de lista, então leia tools/list a cada conexão em vez de codificar o catálogo.
• Esta página descreve o servidor de produção em https://app.ship.com/mcp. Onde ele e tools/list discordarem, tools/list vence.

Seus dados

• Uma conexão pode ver e alterar apenas a conta do Ship.com à qual seu token pertence.
• O Ship.com registra o nome, a hora e a duração de cada chamada de ferramenta, e se ela falhou. Apenas para chamadas com falha, ele também mantém o erro e os argumentos enviados, para ajudar na solução de problemas. Esses registros são excluídos após cerca de 90 dias. Argumentos e resultados de chamadas bem-sucedidas não são armazenados neste registro.
• Tokens de acesso OAuth, tokens de atualização e códigos de autorização são armazenados apenas em formato hash.
• Pedidos, etiquetas, coletas e e-mails criados via MCP são atividade comum da conta e aparecem no aplicativo web do Ship.com como qualquer outra alteração.

Obtendo ajuda

Envie um e-mail para help@ship.com. Para nos ajudar a encontrar o problema rapidamente, inclua o nome da ferramenta, aproximadamente quando ocorreu (com fuso horário), se você conecta com um token de acesso ou login OAuth, e a mensagem de erro exata. Nunca envie seu token.

Conectar Claude	www.ship.com/api/claude
API REST	www.ship.com/api/overview
Política de privacidade	app.ship.com/privacy
Termos de serviço	app.ship.com/terms