# 13.2 Usar os atributos no ERP (Bling, Tiny)

> Por que o nome do frete não serve de chave no ERP, o que no Cota Frete pode mudar esse nome, como mapear pelo código do serviço e onde os atributos chegam na API e nos webhooks.

Fonte: https://www.cotafrete.app/manual/pedidos/atributos-no-erp/
Planos: Basic, Business · no checkout, requer o Carrier Calculated Shipping (CCS) da Shopify
Atualizado em 25/10/2026

---

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](https://www.cotafrete.app/manual/checkout/prazo-no-checkout/).

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](https://www.cotafrete.app/manual/regras-de-frete/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](https://www.cotafrete.app/manual/regras-de-frete/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 **Transportadoras → Geral → Prazo 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.


> **Migrando de outro app de cotação?:** 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:

```json
"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`.