Cálculo de frete e etiquetas

O caminho de um envio pela API tem quatro chamadas:

1. Cotar o frete: POST /api/v0/calculator
2. Criar a etiqueta com o serviço escolhido: POST /api/v0/cart
3. Pagar a etiqueta com o saldo da carteira: POST /api/v0/checkout
4. Imprimir a etiqueta em PDF: POST /api/v0/tag/print

Para conhecer os limites técnicos de cada serviço dos Correios (peso, dimensões e seguro), use GET /api/v0/services/info.

Serviços disponíveis

Código	Serviço	Transportadora
1	PAC	Correios
2	SEDEX	Correios
17	Mini Envios	Correios
3	Jadlog	Jadlog
31	Loggi	Loggi
33	J&T	J&T Express

Na cotação, envie os códigos separados por vírgula no campo services, por exemplo "1,2,17". Na criação da etiqueta, envie um único código no campo service.

Cotar: caixa pronta ou lista de produtos

Você descreve o que vai ser enviado de um destes dois jeitos:

• package: quando você já sabe as dimensões da caixa. Informe weight (kg), height, width e length (cm).
• products: quando você tem só os produtos. Informe quantity, weight (kg), height, width e length (cm) de cada um, e a API calcula a caixa ideal para acomodar todos.

Se você enviar os dois, package tem prioridade.

Os opcionais vão em options: own_hand (Mão Própria), receipt (Aviso de Recebimento), insurance_value (valor declarado para o seguro) e use_insurance_value (envie true para incluir o seguro no cálculo).

Use a caixa que a cotação devolveu

Quando você cota por products, a resposta traz a caixa ideal calculada pela API. Ao criar a etiqueta, envie essa caixa em volumes, e não as dimensões dos produtos individuais. Assim o envio sai com as mesmas medidas que foram cotadas e você evita divergências com a transportadora.

Exemplo: dois produtos de 2 kg, com 2 × 16 × 20 cm cada. A cotação devolve uma caixa de 4 kg com 6 cm de altura, 16 cm de largura e 24 cm de comprimento. São esses os valores que vão em volumes na criação da etiqueta.

Criar a etiqueta

Com o serviço escolhido, envie remetente (from), destinatário (to), service, volumes e o nome da sua plataforma em platform. A etiqueta nasce com status pending (aguardando pagamento).

Alguns cuidados que evitam erros de validação:

• Nome do remetente com nome e sobrenome, até 50 caracteres. Se for uma loja com nome de uma palavra só, adicione "Loja" antes: Loja SuperFrete.
• state_abbr com as duas letras em caixa alta: SP, não sp.
• postal_code com 8 dígitos.
• district é obrigatório. Se o endereço não tiver bairro, envie "NA".
• number é opcional. Sem número, envie uma string vazia.
• CPF ou CNPJ do destinatário (to.document) é obrigatório para Jadlog, Loggi e J&T, e para os Correios sempre que houver declaração de conteúdo.
• Telefone do destinatário (to.phone), quando enviado, precisa ter 10 ou 11 dígitos, sem formatação. Na J&T, se ele não vier, usamos o telefone do remetente.
• Na Loggi, o remetente precisa de e-mail: envie from.email ou cadastre um e-mail na conta.

Declaração de conteúdo ou nota fiscal

• Para usar declaração de conteúdo, envie a lista de products (name, quantity, unitary_value). Sempre que products vem na requisição, a etiqueta sai com declaração de conteúdo.
• Para usar nota fiscal, não envie products e informe options.invoice.number com a chave de 44 dígitos. Você ainda precisa imprimir a nota e colocar no pacote.
• O campo options.non_commercial é ignorado e pode ser omitido.

Pagar a etiqueta

Você pode pagar de dois jeitos:

• Pelo painel, em Minhas etiquetas, com cartão de crédito ou saldo.
• Pela API, com o saldo da carteira: envie o id da etiqueta para POST /api/v0/checkout. Com saldo suficiente, a etiqueta passa para released e está pronta para postagem.

Para recarregar a carteira de produção, acesse o painel, vá em Perfil > Carteira, clique em Recarregue com Pix, escolha o valor e pague o Pix pelo seu banco. No sandbox o pagamento é simulado: veja Adicione saldo no sandbox.

Status da etiqueta

Status	Significado
pending	Aguardando pagamento
released	Paga, aguardando postagem. O código de rastreio já está disponível
posted	Postada
delivered	Entregue
canceled	Cancelada

O código de rastreio aparece no campo tracking de Consultar pedido a partir do status released. Para não precisar consultar, assine os webhooks.

Só é possível cancelar etiquetas que ainda não foram postadas. O valor volta para a carteira da conta.

Imprimir

POST /api/v0/tag/print devolve a URL do PDF das etiquetas informadas. Para receber no formato A6 (Zebra), ative a opção na sua conta: menu Etiquetas > Configurações > A6 (Zebra). A partir daí, todas as etiquetas saem nesse formato.

Regras por transportadora

Jadlog, Loggi e J&T só aparecem na cotação quando existe um ponto de postagem da transportadora perto do CEP de origem.

Loggi

A Loggi só é cotada quando as duas condições valem: o código 31 está em services e a Loggi está ativada nas configurações do token usado na requisição. Para conferir a configuração:

1. Acesse web.superfrete.com/#/integrations.
2. Clique em Configurações do token (o ícone de engrenagem).
3. Ative ou desative a Loggi.
4. Clique em Salvar.

• Cada lado com no máximo 100 cm, e a soma dos lados até 200 cm.
• Peso máximo: 30 kg com Loggi Pontos, 11 kg sem.
• Seguro máximo: R$ 3.000,00.

Jadlog

Ponto de postagem	Medidas máximas	Peso máximo
Franquias (unidades oficiais da Jadlog)	80 × 80 × 80 cm	120 kg
Lojas parceiras (comércios que recebem pacotes da Jadlog)	60 × 60 × 60 cm	30 kg

Seguro máximo: R$ 1.500,00. Nota fiscal (NF-e) não é aceita para Jadlog e Loggi: use declaração de conteúdo.

J&T

• Cada lado com no máximo 100 cm, e a soma de largura, comprimento e altura até 200 cm.
• Peso máximo: 11 kg.
• Telefone do destinatário obrigatório.

Correios

Os limites de PAC, SEDEX e Mini Envios (peso, dimensões, soma dos lados e faixa de seguro) são devolvidos por GET /api/v0/services/info. Consulte esse endpoint em vez de fixar os valores no seu código, porque eles podem mudar.

Quer ver tudo funcionando de ponta a ponta? Siga Sua primeira etiqueta. Se uma chamada falhar, as mensagens mais comuns estão em Erros e limites.

Ficou com alguma dúvida? Escreva para integracao@superfrete.com ou fale com a gente pelo chat.