API: Módulo Envios (shipping)

O módulo shipping leva a parte de Envios para a API: as faixas de CEP (entrega própria, motoboy, valor fixo por cidade ou região) e as medidas de frete de cada produto (largura, altura, comprimento e frágil). É ótimo para ERPs, hubs logísticos e para quem cuida de muitas regiões de entrega e prefere atualizar tudo de uma vez, sem cadastrar faixa por faixa no painel.

⚠️ A API precisa estar habilitada para utilizá-la. Veja o passo a passo em API - Como habilitar.

Endpoint: https://app.interago.com.br/App/Api/index.php

Todas as chamadas são POST com:

• Cabeçalho Authorization: Bearer SEU_TOKEN
• websiteId no corpo
• module=shipping e method com o nome do método

Limite: 60 requisições autenticadas por minuto por website, além da cota do mês explicada em API - Como habilitar. Trate o token como senha.

Antes de começar

• A extensão Envios precisa estar instalada no site. Sem ela, a API responde 403 SHIPPING_EXTENSION_REQUIRED.

• No painel, abra API Interago e clique no chip Envios / Logística. Ali ficam o testador e a descrição dos 10 métodos do módulo. O chip fica disponível quando a extensão Envios está instalada.

• Leituras funcionam em qualquer plano. Gravações (métodos apply e delete) ficam bloqueadas para loja do plano grátis, com 403 FREE_TIER_DENIED.

Os 10 métodos

Faixas de CEP

As faixas vão no parâmetro cepRanges, um array JSON. Cada faixa tem:

• cepFrom e cepTo: CEP inicial e final, com 8 dígitos. Para um único CEP, repita o mesmo valor. O inicial precisa ser menor ou igual ao final.
• price: preço do frete na faixa. Prefira número (por exemplo 15.5), sem máscara de R$. 0 deixa o frete grátis na faixa.
• minCart: valor mínimo do carrinho para a faixa valer (0 vale para qualquer valor).
• deliveryTime: prazo em dias, de 0 a 365.
• name: o nome que o cliente lê no checkout, por exemplo Entrega própria. Obrigatório.

O caminho mais tranquilo tem dois passos:

1. Chame proposeCepRanges com as faixas e o mode que pretende usar. Nada é gravado: a resposta mostra a lista final em cepRanges e diz se está tudo certo em compatible. Se não estiver, os detalhes vêm em errors (por exemplo, Faixa #2: cepFrom e cepTo precisam ter 8 dígitos).

2. Com compatible: true, envie o mesmo conteúdo para applyCepRanges. Se alguma faixa estiver errada, a API recusa o envio inteiro com 422 CEP_RANGES_INVALID e não grava nada.

Sobre o mode:

• replace (padrão): a lista enviada substitui todas as faixas da loja. Enviar [] com replace apaga todas as faixas.
• append: as faixas enviadas entram no final da lista atual.
• Limite de 500 faixas por requisição e de 500 no total depois de um append.

A ordem importa. Na cotação vale a primeira faixa que coincidir com o CEP e com o mínimo do carrinho. Com append, a faixa nova fica depois das que já existem; se ela precisa ganhar de uma faixa mais ampla, monte a lista completa na ordem certa e use replace.

As faixas gravadas valem já na próxima cotação de frete, sem precisar republicar o catálogo.

Ler as faixas atuais:

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=shipping' \ -d 'method=listCepRanges'

Validar uma lista completa (nada é gravado):

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=shipping' \ -d 'method=proposeCepRanges' \ -d 'mode=replace' \ --data-urlencode 'cepRanges=[{"cepFrom":"15000000","cepTo":"15099999","price":15.5,"minCart":0,"deliveryTime":2,"name":"Entrega própria"},{"cepFrom":"15100000","cepTo":"15199999","price":0,"minCart":200,"deliveryTime":3,"name":"Frete grátis região"}]'

Acrescentar uma faixa no final da lista:

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=shipping' \ -d 'method=applyCepRanges' \ -d 'mode=append' \ --data-urlencode 'cepRanges=[{"cepFrom":"15130000","cepTo":"15139999","price":12,"minCart":0,"deliveryTime":1,"name":"Motoboy Mirassol"}]'

Depois de mexer nas faixas pela API

Peça para quem cuida da loja conferir no painel: em Menu → Extensões → Envios, a aba Regras de faixas de CEP mostra a lista exatamente como ficou gravada, na ordem de avaliação. Uma cotação de teste com um CEP de cada faixa confirma preço, prazo e o nome que aparece no checkout.

O passo a passo da tela está em Envios e frete: regras de faixas de CEP, e o teste de cotação em Como testar o frete por CEP antes de publicar.

Medidas de frete dos produtos

As medidas de frete (largura, altura e comprimento, em centímetros, mais a marcação de frágil) são as que a cotação usa para montar o pacote. O peso continua no cadastro do produto e é gravado pelo módulo Catálogo, com applyProduct (veja API: Módulo Catálogo (catalog)).

• width, height e length são obrigatórios em proposeProductMeasures e applyProductMeasures. Aceitam decimal (uma casa) e não podem ser negativos.
• fragile: 1 para frágil e 0 (padrão) para normal.
• Produto sem medidas próprias usa, na cotação, as medidas padrão de Envios → Configurações. O getShippingDefaults mostra esses valores e o CEP de origem.
• deleteProductMeasures apaga as medidas próprias e o produto volta aos padrões da loja.

Em lote: applyProductMeasuresBatch

• Até 100 itens por chamada, no array JSON items.
• identifyBy=productId (padrão) usa o productId de cada item; identifyBy=sku usa o sku.
• Sucesso parcial: a resposta separa applied e failed (com appliedCount e failedCount). Um item com problema não derruba os outros.
• SKU que pertence a mais de um produto da loja é recusado com SKU_AMBIGUOUS, para não gravar medida no produto errado. Nesse caso, envie aquele item com identifyBy=productId.
• SKU que não existe na loja volta em failed com PRODUCT_NOT_FOUND.

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=shipping' \ -d 'method=applyProductMeasuresBatch' \ -d 'identifyBy=sku' \ --data-urlencode 'items=[{"sku":"CAM-001","width":20,"height":4,"length":30,"fragile":0},{"sku":"CANECA-01","width":12,"height":12,"length":12,"fragile":1}]'

Paginação em listProductMeasures

• page começa em 1; pageSize tem padrão 50 e máximo 100. A lista vem em ordem alfabética de nome.
• A resposta traz hasMore: enquanto vier true, peça a próxima página.
• onlyWithMeasures=1 lista só os produtos que já têm medidas próprias; search filtra por nome ou SKU.

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID' -d 'module=shipping' \ -d 'method=listProductMeasures' \ -d 'onlyWithMeasures=1' \ -d 'page=1' \ -d 'pageSize=100'

Erros comuns

Veja também

• API - Como habilitar

• API do Interago: o que é e para que serve

• API: Módulo Catálogo (catalog)

• Envios e frete: regras de faixas de CEP

• Como testar o frete por CEP antes de publicar