Usar os atributos no ERP (Bling, Tiny)
O Bling, o Tiny e a maioria dos ERPs brasileiros tratam o nome do frete como chave. Na primeira vez que chega “SEDEX”, o ERP cria a forma de envio “SEDEX”. Da segunda vez, reconhece e associa ao mesmo cadastro. É assim que ele sabe qual transportadora emitir e como mapear a etiqueta ou a NF-e.
Esse mecanismo funciona enquanto o nome do frete for fixo. Esta página explica o que quebra quando não é, o que no Cota Frete pode mudar o nome e como usar os atributos do pedido no seu ERP.
Três jeitos de bagunçar o cadastro de formas de envio#
Data no nome. “SEDEX - chega 22/07” converte bem no checkout. Mas se a data está no nome do serviço, cada dia gera um nome novo. Em um mês são 30 formas de envio “SEDEX” diferentes no ERP.
Campanha no nome. “Frete Grátis Black Friday” no lugar do nome do serviço. O ERP recebe uma forma de envio com esse nome e não sabe se é Correios ou Jadlog.
Grupo no nome. Com agrupamento, o cliente escolhe “Econômico”. Hoje o mais barato é Jadlog, amanhã é Correios. O ERP vê sempre “Econômico” e a transportadora real some.
O sintoma é o mesmo nos três casos: o cadastro do ERP vira uma lista sem fim, o mapeamento para etiqueta e nota quebra e alguém da operação corrige pedido a pedido.
O que pode mudar o nome do frete no Cota Frete#
Por padrão, o nome do frete é o nome do serviço da transportadora (“SEDEX”, “Jadlog .Package”) e não muda de uma cotação para outra. Data prevista, dias úteis e título da campanha vão para a descrição, embaixo do nome, e nunca para o nome. O cliente vê “Frete Grátis Inverno · Estimativa de entrega 22/07”; o ERP recebe “SEDEX”. Veja Prazo no checkout e data prevista.
Só três coisas mudam o nome, e todas são escolha sua:
| O que muda o nome | Efeito no ERP |
|---|---|
| Uma regra de renomear | O nome passa a ser o que você digitou. Continua fixo: o ERP ganha uma forma de envio nova, uma vez |
| Uma regra de agrupar com nome digitado (“Econômico”) | O nome é fixo, mas a transportadora por trás muda a cada pedido. Quem diz a transportadora é cotafrete_transportadora |
| O complemento no nome do serviço, em TransportadorasGeralPrazo no checkout | O nome muda a cada cotação. O próprio app avisa na tela: cada pedido chega ao ERP com um nome diferente. Deixe em Nome do Serviço se você usa ERP |
Nas regras de renomear e de agrupar existe a opção Usar o nome do serviço escolhido. Com ela ligada, o frete mantém o nome do próprio serviço com a conexão no fim: “SEDEX - Correios”, “Correios SEDEX - Frenet”. O nome continua fixo para cada serviço, e o ERP passa a distinguir o mesmo serviço vindo de contas diferentes. É a saída para o grupo “Econômico” que muda de transportadora todo dia.
Mapeie pelo código do serviço#
No ERP, a regra é mapear por cotafrete_codigo_servico, não pelo nome.
O código é gerado pelo app e nunca varia para um mesmo serviço. Os nomes são textos visíveis: mudam se a transportadora renomear o serviço ou se você criar uma regra de renomear. Um mapeamento feito pelo código continua valendo depois dessas mudanças.
Quando a loja usa mais de um gateway, combine o código com cotafrete_gateway: ele diz por qual conta a etiqueta precisa ser comprada.
O cadastro de formas de envio do ERP não se limpa sozinho. Depois que o nome do frete estabilizar com o Cota Frete, vale arquivar as variações antigas (“SEDEX - 21/07”, “Frete Grátis Natal”) para o cadastro voltar a ter só os serviços reais.
Onde os atributos chegam na API#
Os atributos vão junto com o pedido em qualquer leitura. Isso serve para integração própria, planilha, ferramentas de automação (Make, n8n, Zapier) ou para alimentar o sistema de expedição.
| Onde | Campo |
|---|---|
| API Admin GraphQL | customAttributes do objeto Order (pares key e value) |
| API REST | array note_attributes do pedido |
Webhooks de pedido (orders/updated, orders/paid e os demais) | note_attributes no payload |
Um trecho do payload REST de um pedido com frete do Cota Frete fica assim:
"note_attributes": [
{ "name": "cotafrete_transportadora", "value": "Correios" },
{ "name": "cotafrete_servico", "value": "SEDEX" },
{ "name": "cotafrete_codigo_servico", "value": "correios_03220" },
{ "name": "cotafrete_previsao_entrega", "value": "27/08/2026" }
]
O app grava os atributos alguns segundos depois de o pedido ser criado, a partir do próprio aviso de pedido criado da Shopify. Por isso o payload do orders/create chega sem eles. Se a sua integração reage a pedido novo, leia o pedido de novo um pouco depois, ou reaja ao orders/updated ou ao orders/paid.