Integração de Transportadora (Carrier Integration)

Configuração que liga uma filial a uma transportadora para criar e gerenciar envios

Integração de transportadora é a configuração que liga uma filial a uma transportadora em uma modalidade específica para criar e gerenciar envios. No código e na API aparece como CarrierIntegration.

O que compõe uma integração de transportadora

Identificação e vínculo

Campo	Descrição
`id`	Identificador interno
`type`	Nome/tipo da transportadora
`seller_id` / `seller`	Para qual filial essa integração vale
`active`	Se está ativa ou não
`operation_type`	Entrega (DELIVERY) ou Reversa (RETURN)
`carrier_method_group`	Modalidade (ex.: CARRO, MOTO, CONVENCIONAL, PAC)

Credenciais e configuração operacional

data — contém as credenciais (API key, token etc.) e também configurações operacionais da transportadora (ex.: se comprovante de entrega é obrigatório, formato de etiqueta etc.). O conteúdo varia de transportadora para transportadora

Regras de negócio

Horário de corte — horário limite do dia para considerar que a solicitação de coleta será feita "hoje". Pedidos após esse horário começam a contar prazo no próximo dia útil. Veja mais em Tabela de Frete — Horário de corte
Tabela de frete — cada integração pode ter uma tabela de frete associada, do tipo CEP ou raio
Cobertura restrita — quando ativada, pedidos cujo destino não está coberto pela tabela de frete falham automaticamente. Veja mais em Tabela de Frete — Cobertura restrita
GRIS, ad valorem, fator de cubagem, isenção de cubagem

Para que serve

Definir quais transportadoras (e modalidades) cada filial pode usar
Ao fazer a solicitação de coleta de um pedido, o sistema usa a integração para criar o envio na transportadora — utilizando as credenciais e configurações operacionais para fazer a solicitação de coleta via integração tecnológica
Permitir trabalhar com várias transportadoras simultaneamente, comparar preços e definir regras automáticas

Onde aparece

Cada filial pode ter múltiplas integrações de transportadora, mas apenas uma por combinação de modalidade e operação — por exemplo: uma integração para Uber/Carro/Entrega e outra para Uber/Carro/Reversa, mas nunca duas iguais
Todo envio referencia a integração de transportadora que o atendeu
Relatórios de Integrações de Transportadoras exportam essas configurações por filial

Relação com os outros conceitos

A integração de transportadora é o motor de solicitação de coleta. Quando um pedido precisa ser enviado, o sistema seleciona a integração adequada da filial — manualmente ou via automação de envio — e cria um envio na transportadora.

Tabela de frete e contrato

A tabela de frete vinculada à integração representa os valores negociados em contrato entre a sua marca e a transportadora. Quando você negocia preços, prazos ou faixas de cobertura com a transportadora, esses valores são registrados na tabela de frete.

Cada integração pode ter uma tabela associada:

Tipo de tabela	Como funciona
Tabela de CEP	Preços por faixa de CEP de destino, peso e prazo
Tabela de Raio	Preços por faixa de distância (km), peso e prazo

A tabela pertence a uma modalidade, e várias integrações podem compartilhar a mesma tabela. Ao criar ou editar uma integração, você escolhe o tipo de tabela e seleciona qual tabela vincular.

Tabela reflete o contrato

Se as condições comerciais com a transportadora mudam (novos preços, novos prazos, novas faixas de CEP ou km), atualize a tabela de frete para que o sistema use os valores corretos na cotação e no envio. Lembre-se de revisar as automações de envio que usam prazo específico — prazos removidos da tabela podem invalidar essas automações.