# Abbiamo Docs (/docs)
# Abbiamo [#abbiamo]
A **Abbiamo** é uma plataforma de gestão logística que conecta **embarcadores** (quem envia) a **transportadoras** (quem entrega) — num único painel, do pedido à entrega confirmada.
***
## O que você consegue fazer com a Abbiamo [#o-que-você-consegue-fazer-com-a-abbiamo]
### Para embarcadores — LOG [#para-embarcadores--log]
Você recebe pedidos do seu e-commerce ou ERP, cota o frete em tempo real entre múltiplas transportadoras, aciona a coleta automaticamente, rastreia cada envio e audita cobranças — tudo sem precisar acessar o sistema de cada transportadora separadamente.
| Capacidade | O que resolve |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| **Receber pedidos** | Integre VTEX, Shopify, Shopee, Linx e outros — os pedidos chegam automaticamente |
| **Cotar frete** | Compara transportadoras em tempo real com base em CEP, peso, prazo e regras customizadas |
| **Despachar automaticamente** | Automações de envio escolhem e acionam a transportadora certa sem intervenção manual |
| **Rastrear envios** | Acompanha status de cada envio com sub-status e histórico de eventos |
| **Gerenciar falhas** | Automações de reenvio e inatividade lidam com entregas com falha ou paradas automaticamente |
| **Faturar** | Gera faturas com base nos preços cotados e auditados por período |
| **Medir desempenho** | Relatórios e CSAT para acompanhar SLA, volume e satisfação do cliente |
### Para transportadoras / frota própria — GO [#para-transportadoras--frota-própria--go]
Você recebe as solicitações de coleta, cria rotas, escala motoristas e monitora cada entrega em tempo real — com o motorista operando pelo app mobile da Abbiamo.
| Capacidade | O que resolve |
| --------------------------- | --------------------------------------------------------------------------------- |
| **Criar rotas** | Agrupa entregas por motorista e organiza a sequência de paradas |
| **Escalar motoristas** | Cadastro, marcadores, grupos e distribuição automática de ofertas |
| **Automatizar ofertas** | Define quais motoristas recebem entregas por filial, tipo de operação e condições |
| **Rastrear em tempo real** | Acompanha motoristas no mapa e atualiza status de cada entrega |
| **Relatórios operacionais** | Volume por rota, motorista e período |
***
## Por onde começar [#por-onde-começar]
### Sou embarcador (LOG) [#sou-embarcador-log]
1. Leia o [**Guia de Onboarding LOG**](/docs/log/onboarding/) — conceitos, fluxo e primeiros passos.
2. Configure [**Filiais**](/docs/log/settings/filiais/) e [**Integrações de Transportadora**](/docs/log/settings/integracoes-de-transportador/).
3. Conecte seu sistema via [**Integrações de Pedido**](/docs/log/settings/integracoes-de-pedidos/).
4. Crie [**Automações de Envio**](/docs/log/products/regras-de-envio/) para despachar automaticamente.
5. Acompanhe [**Envios**](/docs/log/products/envios/) e [**Relatórios**](/docs/log/products/relatorios/).
### Sou transportadora / frota própria (GO) [#sou-transportadora--frota-própria-go]
1. Cadastre seus [**Motoristas**](/docs/go/products/motoristas/).
2. Configure [**Automações de Ofertas**](/docs/go/products/automacoes-de-ofertas/) para distribuir entregas.
3. Acompanhe as [**Rotas**](/docs/go/products/rotas/) em tempo real.
### Sou desenvolvedor / integrador [#sou-desenvolvedor--integrador]
* [**API pública (Transportadora)**](/docs/transportadora/) — integração técnica para transportadoras.
* [**Quick Guide — Código de Coleta**](/docs/transportadora/quick-guide-codigo-coleta/) — quando usar `collect_verification_code`.
* [**Integração VTEX**](/docs/log/integrations/pedido/vtex/) — guia da integração de pedidos com VTEX.
* [**Troubleshooting Uber**](/docs/log/integrations/transportadora/uber/) — erros comuns na integração Uber.
***
## Visão geral dos contextos [#visão-geral-dos-contextos]
| | **LOG** | **GO** |
| ----------------------- | ------------------------------------------------- | ------------------------------------------- |
| **Quem usa** | Embarcadores, varejistas, e-commerces | Transportadoras, operações de frota própria |
| **Foco principal** | Pedidos, cotação de frete, despacho, rastreamento | Rotas, motoristas, entregas last-mile |
| **Automações** | Envio, reenvio, inatividade, marcadores | Ofertas, marcadores |
| **Configurações chave** | Filiais, integrações de TRP, tabelas de frete | Operação, marcadores de motorista |
***
## Changelog [#changelog]
Acompanhe as últimas atualizações da documentação em [**Changelog**](/docs/changelog/).
---
# Lista de Produtos Disponíveis (/docs/produtos-disponiveis)
# Lista de Produtos Disponíveis [#lista-de-produtos-disponíveis]
Esta página consolida todos os produtos disponíveis na plataforma Abbiamo, com base no que é documentado e visível no painel. Os produtos são diferenciados por contexto: **LOG** (embarcadores), **GO** (transportadoras no painel GO) e **Transportadora** (integração via API pública).
***
## LOG (embarcadores) [#log-embarcadores]
Clientes que direcionam pedidos para transportadoras.
### Produtos documentados [#produtos-documentados]
| Produto | Descrição | Documentação |
| --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
| **Relatórios** | Página de relatórios | [Visão Geral](/docs/log/products/relatorios/) |
| **Pedidos** | Tela de Pedidos (filtros, tabela, ações, KPIs) | [Visão Geral](/docs/log/products/pedidos/) |
| **Automações de Envio** | Página de Envio (interface e funcionalidades) | [Visão Geral](/docs/log/products/regras-de-envio/) |
| **Tabelas de Frete** | Criação e gestão de tabelas de preço por CEP ou raio | [Visão Geral](/docs/log/products/tabelas-de-frete/) |
| **Integrações de Transportadora** | Configuração de transportadoras por filial | [Visão Geral](/docs/log/products/integracoes-de-transportadora/) |
### Páginas com documentação em breve (LOG) [#páginas-com-documentação-em-breve-log]
| Produto/Página | Rota |
| ------------------------------ | --------------------- |
| Dashboard (Analytics) | `/analytics` |
| Envios | `/deliveries` |
| Pesquisas de satisfação (CSAT) | `/csat` |
| Automações de reenvio | `/resend-rules` |
| Automações por inatividade | `/inactivity-rules` |
| Automações de marcadores | `/tags-rules` |
| Integrações de pedidos | `/order-integrations` |
| Regras de frete | `/quotation-rules` |
| Filiais | `/sellers` |
***
## GO (transportadoras) [#go-transportadoras]
Transportadoras que criam rotas e direcionam entregas para motoristas.
### Produtos documentados [#produtos-documentados-1]
* Apenas **Visão Geral** (link para página inicial). No momento, não há documentação específica de produtos GO.
### Páginas com documentação em breve (GO) [#páginas-com-documentação-em-breve-go]
| Produto/Página | Rota |
| ---------------- | ----------- |
| **Rotas** | `/routes` |
| **Embarcadores** | `/shippers` |
| **Motoristas** | `/drivers` |
***
## Transportadora (API pública) [#transportadora-api-pública]
Transportadoras que integram diretamente com os endpoints públicos da Abbiamo.
### Produtos documentados [#produtos-documentados-2]
| Produto/Página | Descrição | Documentação |
| ---------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Visão Geral** | Contexto da integração, responsabilidades e links oficiais | [Visão Geral](/docs/transportadora/) |
| **Quick Guide - Código de Coleta** | Regras e exemplos de quando informar `collect_verification_code` | [Quick Guide - Código de Coleta](/docs/transportadora/quick-guide-codigo-coleta/) |
### Páginas com documentação em breve (Transportadora) [#páginas-com-documentação-em-breve-transportadora]
| Produto/Página | Rota |
| ----------------------------- | --------------------------------- |
| Troubleshooting de integração | `/transportadora/troubleshooting` |
| Guia de homologação | `/transportadora/homologacao` |
***
## Compartilhados (LOG e GO) — documentação em breve [#compartilhados-log-e-go--documentação-em-breve]
| Produto/Página | Rota |
| --------------------------------------------------- | ------------- |
| Configurações (Preferências, Usuários, Temas, etc.) | `/settings/*` |
---
# Como medimos o status (/docs/status)
{/* imprime a janela móvel lida dos SLOs do Datadog
(threshold `timeframe`). Não chumbe "7 dias"/"30 dias" na prosa: mudou lá,
muda aqui sozinho. Fallback em `lib/status.ts` (FALLBACK_TIMEFRAME). */}
A [página de Status](/status) mostra a saúde dos sistemas da Abbiamo em tempo real. Esta página explica **como cada número é calculado** — o que ele representa, sobre qual período e quando consideramos um componente saudável.
## O número principal (Saúde) [#o-número-principal-saúde]
O percentual grande de cada componente é um **SLI** (*Service Level Indicator*): a fração de eventos "bons" sobre o total, medida numa **janela móvel de **.
```
Saúde = eventos bons na janela ÷ total de eventos na janela
```
A cada novo evento a janela "anda" — então o número reflete sempre os **últimos corridos**, não o mês-calendário nem o dia de hoje isolado.
Cada componente tem uma **meta** dentro dessa janela — o nosso *SLO* (*Service Level Objective*). A **API Pública** mira **99,9%** (os 0,1% restantes são o **orçamento de erro**: o tempo de indisponibilidade tolerável na janela antes de a meta ser furada). A **Cotação** tem meta de **99,0%**.
## O que cada componente mede [#o-que-cada-componente-mede]
O que conta como "evento bom" depende do componente:
| Componente | O que medimos | "Evento bom" |
| --------------- | ------------------------------------- | ----------------------------------------------------- |
| **API Pública** | Disponibilidade das requisições à API | Resposta **sem erro de servidor** (HTTP 5xx) |
| **Cotação** | **Performance** da cotação | Resposta dentro do limite de latência (p95 \< 500 ms) |
{/* Plataforma e Tracking saíram da página de status temporariamente
(comentados em `lib/status.ts`). Descomentar lá e devolver estas linhas
à tabela acima:
| **Plataforma** | Disponibilidade da plataforma web | Resposta **sem erro de servidor** (HTTP 5xx) |
| **Tracking** | Disponibilidade da página pública de tracking | Resposta **sem erro de servidor** (HTTP 5xx) |
*/}
Repare que **Cotação** mede **velocidade**, não disponibilidade: ela responde "a cotação está rápida?". Falhas de cotação (erros) entram no indicador da **API Pública** — por isso os dois andam juntos.
## Os estados [#os-estados]
O badge de cada componente combina a Saúde atual com a meta e o orçamento de erro:
| Estado | Significado |
| ------------------ | -------------------------------------------------------------- |
| 🟢 **Operacional** | Dentro da meta — tudo normal. |
| 🟡 **Degradado** | Consumindo o orçamento de erro rápido / perto de furar a meta. |
| 🔴 **Instável** | Meta furada na janela de . |
| ⚪ **Indisponível** | Não foi possível medir agora (o número aparece como `—`). |
{/* Seção Transportadoras — fora do ar junto com a seção correspondente
em `app/(home)/status/page.tsx`. Descomentar os dois de volta juntos.
## Transportadoras
A seção **Transportadoras** acompanha a performance dos parceiros de entrega. São dois indicadores por transportadora, sobre ****:
| Indicador | O que medimos | "Evento bom" |
| --- | --- | --- |
| **SLA das requisições** | Respostas da transportadora às chamadas que fazemos a ela | Resposta **sem erro de servidor** (HTTP 5xx) |
| **Erros nos últimos ** | Eventos de status dos pedidos despachados para a transportadora | Evento que **não** é uma falha [`ORDER_FAILED / CARRIER_ERROR`](/docs/api/conceitos/tables/status-and-substatus) |
Instabilidade de uma transportadora é da transportadora — **não** pinta a Abbiamo como instável. Por isso esses indicadores ficam numa seção à parte e não entram no estado geral da plataforma.
*/}
## Detalhes de exibição [#detalhes-de-exibição]
* **Atualização:** a página re-consulta os números **a cada 60 segundos**.
* **Arredondamento:** truncamos em 2 casas (não arredondamos pra cima) — um `99,89%` nunca vira `99,90%`. Preferimos errar pra baixo a dar uma impressão melhor que a real.
* **`—`:** aparece quando um indicador não pôde ser medido no momento (sem dado suficiente ou falha temporária na consulta).
---
# Bem-vindo 👋🏼 (/docs/api)
Aqui você encontra exemplos prontos pra copiar e colar, schemas completos e um playground interativo pra testar os endpoints sem sair da página. Escolha por onde começar conforme o seu papel na operação.
## Embarcador (LOG) [#embarcador-log]
Loja, e-commerce ou varejo integrando pedidos e envios.
Crie um pedido na Abbiamo (e, opcionalmente, dispare a coleta).
Solicite uma entrega numa modalidade específica.
Receba eventos do pedido em tempo real (status, recebedor, CSAT...).
## Transportadora (TRP) [#transportadora-trp]
Parceira de entrega integrando a sua operação à Abbiamo.
Visão geral da integração e primeiros passos.
Processo de certificação pra entrar em produção.
---
# GO — Visão Geral (/docs/go)
O **GO** é o contexto da plataforma Abbiamo para **transportadoras e operações de frota própria**. Você recebe as solicitações de coleta, cria rotas, escala motoristas e acompanha cada entrega em tempo real — com o motorista operando pelo app mobile da Abbiamo.
***
## O que você consegue fazer [#o-que-você-consegue-fazer]
| Capacidade | Como funciona |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Receber entregas** | Solicitações chegam via integração com embarcadores (LOG) ou diretamente pela API |
| **Criar rotas** | Agrupa entregas, define sequência de paradas e atribui ao motorista certo |
| **Distribuir com automações** | Automações de Ofertas enviam entregas automaticamente para motoristas conforme filial, tipo e condições |
| **Gerenciar motoristas** | Cadastro completo com marcadores, grupos e vínculo por filial |
| **Rastrear em tempo real** | Acompanha posição do motorista e status de cada entrega |
| **Relatórios** | Volume por rota, motorista, filial e período |
***
## Fluxo típico de operação [#fluxo-típico-de-operação]
```
Entrega chega → Automação de Oferta dispara → Motorista aceita → Rota criada → Entrega executada → Status atualizado
```
1. Um pedido chega ao GO (via LOG ou API).
2. A **Automação de Ofertas** determina quais motoristas recebem a oferta com base em filial, tipo de operação e condições.
3. O motorista aceita no **app mobile** e inicia a entrega.
4. A **Rota** é criada e acompanhada em tempo real no painel.
5. Ao finalizar, o status é atualizado e o comprovante é coletado.
***
## Produtos [#produtos]
| Produto | O que faz | Documentação |
| ---------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Rotas** | Cria e acompanha rotas de entrega | [Visão Geral](/docs/go/products/rotas/) · [Como Usar](/docs/go/products/rotas/como-usar/) |
| **Motoristas** | Cadastra e gerencia a frota de entregadores | [Visão Geral](/docs/go/products/motoristas/) · [Como Usar](/docs/go/products/motoristas/como-usar/) |
| **Relatórios** | Dados operacionais por período, filial e motorista | [Visão Geral](/docs/go/products/relatorios/) · [Como Usar](/docs/go/products/relatorios/como-usar/) |
| **Embarcadores** | Clientes parceiros que direcionam pedidos para sua operação | [Visão Geral](/docs/go/products/embarcadores/) |
| **Automações de Marcadores** | Aplica tags automaticamente a pedidos conforme condições | [Visão Geral](/docs/go/products/automacoes-de-marcadores/) · [Como Usar](/docs/go/products/automacoes-de-marcadores/como-usar/) |
| **Automações de Ofertas** | Define quais motoristas recebem ofertas de entrega | [Visão Geral](/docs/go/products/automacoes-de-ofertas/) · [Como Usar](/docs/go/products/automacoes-de-ofertas/como-usar/) |
| **Tabela de Ofertas** | Precificação por rota: paga o motorista pelo trajeto (km, paradas e coletas) | [Visão Geral](/docs/go/products/tabela-de-ofertas/) · [Como Usar](/docs/go/products/tabela-de-ofertas/como-usar/) |
***
## Configurações [#configurações]
| Página | O que configura |
| --------------------------------------------------- | ----------------------------------------------------------- |
| [**Visão Geral**](/docs/go/settings/) | Mapa completo das configurações |
| [**Filiais**](/docs/go/settings/filiais/) | Unidades operacionais, endereço e horários |
| [**Marcadores**](/docs/go/settings/marcadores/) | Tags para pedidos e motoristas |
| [**Operação**](/docs/go/settings/operacao/) | Comprovante de entrega, motivos de falha, limite de paradas |
| [**Usuários**](/docs/go/settings/usuarios/) | Membros da equipe e níveis de acesso |
| [**Temas**](/docs/go/settings/temas/) | Identidade visual por filial |
| [**Notificações**](/docs/go/settings/notificacoes/) | Alertas ao cliente final via e-mail, SMS e WhatsApp |
| [**API**](/docs/go/settings/api/) | Chave de API para integrações externas |
| [**Webhooks**](/docs/go/settings/webhooks/) | Eventos em tempo real para o seu sistema |
***
## Diferença entre GO e LOG [#diferença-entre-go-e-log]
| | **GO** | **LOG** |
| --------------------- | ------------------------------------------ | --------------------------------------- |
| **Quem usa** | Transportadoras / frota própria | Embarcadores / varejistas |
| **Foco** | Criar rotas, motoristas, executar entregas | Pedidos, cotação de frete, acionar TRPs |
| **Motoristas** | Gerenciados no GO | Visíveis nos envios |
| **Rotas** | Frota própria | Via transportadora externa |
| **Config. exclusiva** | Operação (comprovante, falhas, paradas) | Tabelas de frete, regras de cotação |
---
# Acompanhe seus motoristas em tempo real no mapa (/docs/changelog/2026-04-16-mapa-motoristas)
✅ Disponível agora em /driver-location para perfis do tipo Transportadora.
## O que é [#o-que-é]
Um mapa interativo com a última localização registrada de cada motorista da sua operação. Com ele, o operador consegue visualizar em segundos quantos motoristas estão dentro de um raio, quais estão com localização atualizada e quais somem do radar — sem precisar ligar pra ninguém ou cruzar dados.
## Status dos motoristas [#status-dos-motoristas]
Cada marcador no mapa tem uma cor que indica a situação da localização:
●
Verde
Localização atualizada nas últimas 2 horas. Motorista ativo e rastreável.
●
Amarelo
Última atualização há mais de 2 horas. Localização pode estar desatualizada.
●
Preto
Motorista fora do raio de pesquisa definido no filtro.
## Filtros disponíveis [#filtros-disponíveis]
* **Raio de quilometragem** — define a área de busca a partir de uma filial
* **Filial** — filtra os motoristas em cada ponto da sua operação
* **Marcadores de motoristas** — controle de visualização no mapa
## Por que isso importa [#por-que-isso-importa]
Antes
Decisão no escuro
O operador enviava ofertas para um raio sem saber quantos motoristas estavam de fato disponíveis naquela região.
Agora
Decisão com contexto
Antes de enviar qualquer oferta, o operador visualiza exatamente quantos motoristas estão no raio — e com localização atualizada.
---
# Só os motoristas mais próximos recebem a oferta — filtro de raio em km reto (/docs/changelog/2026-04-20-automacao-ofertas-km-reto)
✅ Disponível agora nas Automações de ofertas — em Configurações → Automações de ofertas, ao criar ou editar qualquer regra.
## O que mudou [#o-que-mudou]
Ao criar ou editar uma automação de oferta, agora há um toggle para **limitar quais motoristas recebem a oferta pelo raio em km reto a partir da filial**. Quando ativado, só motoristas dentro do raio definido são elegíveis — os demais não veem a oferta.
Antes
Todos recebiam, poucos aceitavam
A oferta ia para toda a frota. Motoristas do outro lado da cidade recebiam notificações que não faziam sentido — e ignoravam.
Agora
Só quem está perto recebe
Você define o raio em metros a partir da filial. Quem está fora não recebe — menos ruído para o motorista, mais taxa de aceitação para você.
## Como ativar [#como-ativar]
Dentro do formulário de criação ou edição de uma automação, ative o toggle **"Limitar oferta por distância entre filial até a localização do motorista"** e defina o raio máximo em metros.
*Com o toggle ativo, o campo de raio aparece logo abaixo. O valor é em metros — ex: 5000 = 5 km em linha reta a partir da filial.*
*O cálculo é feito em km reto (linha reta), não por rota — o que garante que só quem está geograficamente próximo da filial receba a oferta.*
## Importante: o cálculo é feito no momento do pedido [#importante-o-cálculo-é-feito-no-momento-do-pedido]
A automação dispara assim que o pedido é criado. É nesse instante que o sistema verifica quais motoristas estão dentro do raio e envia a oferta. **Se um motorista entrar na área depois que o pedido foi criado, ele não receberá a oferta** — o cálculo não é contínuo.
## O que não mudou [#o-que-não-mudou]
Todas as outras condições da automação (distância de entrega, peso, valor, CEP, etc.) continuam funcionando normalmente — o filtro de raio é um complemento, não um substituto.
***
---
# Chega de abrir chamado pra checar webhook — Logs no dashboard (/docs/changelog/2026-04-24-logs-webhooks)
✅ Disponível agora em /settings/logs/webhooks — acessível pelo novo item Logs no sidebar, em Desenvolvedor.
## O que mudou [#o-que-mudou]
Antes
Dependência do suporte
Quando um cliente relatava que não havia recebido um evento, a investigação dependia da engenharia acessar os logs internos — o cliente não tinha visibilidade nenhuma.
Agora
Autonomia total
O cliente filtra pelo número do pedido, vê o disparo, confere o payload enviado e o status HTTP retornado — sem abrir chamado.
## O que você encontra na tela de Logs [#o-que-você-encontra-na-tela-de-logs]
*Histórico de disparos com evento, URL, status HTTP, número do pedido e sub-status — tudo paginado e filtrável.*
A tabela exibe todos os webhooks disparados pela sua conta, com as informações mais úteis na frente:
* **Tipo de evento** — `ORDER_STATUS_CHANGE`, `ROUTE_STATUS_CHANGE`, `ORDER_RECEIVER_UPDATE`, `ORDER_CSAT_ANSWER`
* **URL** de destino do disparo
* **Status HTTP** retornado pelo servidor do cliente (200, 429, 500...)
* **Número do pedido**, data, status e sub-status do evento
* **Ações** — visualizar detalhes ou copiar o JSON do log
> Os logs ficam disponíveis por **10 dias**. Após esse período são removidos automaticamente.
## Filtros disponíveis [#filtros-disponíveis]
🔢
Nº do pedido
Busque direto pelo número do pedido para ver todos os webhooks disparados para ele.
🌐
Status HTTP
Filtre por faixa: Sucesso (200+), Redirecionamento (300+), Erros do cliente (400+) ou Erros do servidor (500+).
📡
Tipo de evento
Veja só os eventos que importam — filtre por
ORDER_STATUS_CHANGE
,
ROUTE_STATUS_CHANGE
e outros.
🎛️
Filtros avançados
Refine ainda mais por Webhook URL, data de criação, status e sub-status do pedido.
## Detalhes do log: o payload completo [#detalhes-do-log-o-payload-completo]
Clique no ícone de visualização em qualquer linha para abrir os detalhes do log.
*Status HTTP, timestamps de envio, tipo de execução e o JSON exato enviado para o endpoint — tudo em um só lugar.*
Você vê:
* **Metadados** — Webhook URL, HTTP Status, tipo de execução (automático ou manual), timestamps de evento e de envio, IDs do log e do webhook
* **Request** — payload completo em JSON, com syntax highlight, copiável ou baixável
Se o servidor do cliente retornou erro, a seção de erros detalha exatamente o que voltou na resposta:
*Erros retornados pelo endpoint do cliente ficam visíveis aqui — sem precisar pedir os logs pro time de engenharia.*
## Casos de uso práticos [#casos-de-uso-práticos]
**"O cliente diz que não recebeu o webhook de entregue"**
→ Filtre pelo número do pedido, encontre o evento `SUCCESSFUL` e mostre o HTTP 200 retornado. Se retornou 200, o problema está no lado do servidor do cliente.
**"Estamos recebendo erros 5xx nos webhooks"**
→ Filtre por "Erros do servidor (500+)" e veja quais URLs estão rejeitando. É o ponto de partida para o time técnico do cliente investigar.
**"Preciso do payload exato de um evento para depurar a integração"**
→ Abra o detalhe do log e copie o JSON. Sem precisar recriar o evento manualmente.
***
---
# Crie e personalize temas em segundos — sem abrir ticket (/docs/changelog/2026-04-27-gestao-temas)
✅ Disponível agora em /settings/themes para usuários do tipo Proprietário.
## O que mudou [#o-que-mudou]
⚡
Em segundos
Digite o domínio da marca e a gente puxa logo, cores e favicon automaticamente.
👀
Veja antes de salvar
Preview ao vivo da página de rastreio nos 4 status de entrega — sem precisar publicar pra testar.
✏️
Ajuste quando quiser
Trocar logo, cores ou favicon não depende mais do CS. Você edita direto no dashboard.
Antes
\~24 horas
Abrir ticket no CS → esperar o gerente de contas configurar pelo back-office → qualquer ajuste virava novo chamado.
Agora
\~30 segundos
Você digita o domínio, vê o preview, salva. Pronto.
*Todos os temas da sua conta, com logo, status (ativo/inativo) e quantidade de filiais usando cada um.*
## ⚡ Auto-preenchimento por domínio [#-auto-preenchimento-por-domínio]
Clique em **Criar tema** e digite só o domínio da marca (ex: `lojaxyz.com.br`).
*Sem upload, sem color picker pra acertar no olho — só o domínio.*
A gente preenche automaticamente:
* **Nome de exibição** da marca
* **Cor primária**
* **Logomarca** em alta resolução
* **Favicon**
* **Paleta de cores complementares**, sugeridas no color picker
* **Cor de fundo da logo**, calculada pra garantir bom contraste e legibilidade
Tudo editável depois — você pode trocar qualquer campo, fazer upload manual de logo/favicon (ou colar uma URL) e ajustar as cores como preferir.
## 👀 Preview da página de rastreio em tempo real [#-preview-da-página-de-rastreio-em-tempo-real]
Ao lado do formulário, um mockup ao vivo de como o seu cliente final vai ver a página de rastreio — com o tema já aplicado, incluindo favicon na aba e título do navegador.
*Buscamos `marvel.com.br` (só de exemplo). Em segundos, formulário preenchido e preview renderizando com a identidade da marca.*
Dá pra alternar entre **4 status de entrega** e ver na hora como cada um fica:
Criado
— "Aguardando previsão"
Despachado
— "Você é o próximo!"
Saiu para entrega
— com mapa ao vivo
Entregue
— com confirmação "Você recebeu seu pedido?"
Acabou aquele ciclo de "criei → abri o link → ficou estranho → volto pra editar".
## ✏️ Edite quando quiser [#️-edite-quando-quiser]
Abre o mesmo dialog do criar, já preenchido com o tema atual. Troca o que quiser, mantém o resto — se você não subir uma imagem nova, fica a antiga.
*Editando o tema "Marvel" criado antes, com logo e cores já preenchidas.*
## 🎛️ Menu de ações [#️-menu-de-ações]
O menu `⋯` no card de cada tema reúne todas as ações disponíveis:
*Ver detalhes, editar, definir como padrão, aplicar em filiais, desativar, excluir — tudo a um clique.*
## 🗑️ Excluir, com proteções [#️-excluir-com-proteções]
Apagar é 1 clique no menu + confirmação. Mas a gente bloqueia a exclusão em 2 casos pra você não tomar susto:
* O tema é o **padrão da conta** → defina outro como padrão antes
* O tema está sendo **usado por filiais** → mostramos quantas ainda usam e pedimos pra reatribuir antes
***
O "Quando despachar?" das automações de envio chegou em reenvio e inatividade.
🎯
Aguarde alguns minutos
Some minutos ao disparo pra dar margem antes do despacho.
📍
Fora da Área de Cobertura
Novo gatilho na automação de reenvio: quando o pedido cai fora da abrangência da tabela de frete, a regra reenvia automaticamente.
Antes
Só nas automações de envio
Em reenvio e inatividade, o pedido sempre saía na hora — mesmo que a regra acionasse fora do horário de operação. Aí o despacho ia parar com a loja fechada ou sem motorista trabalhando pra fazer a coleta.
Agora
Em reenvio e inatividade também
Imediato ou agendado pra próxima janela de operação. Com ajuste fino de minutos pra cair exatamente onde faz sentido — em qualquer um dos três tipos de automação.
## ⏱️ A seção "Quando despachar?" agora aparece em reenvio e inatividade [#️-a-seção-quando-despachar-agora-aparece-em-reenvio-e-inatividade]
Ao criar ou editar uma regra de **reenvio** ou **inatividade**, dentro do accordion **Ação** aparece a seção **Quando despachar?** — a mesma que já estava em automações de envio. Com duas opções:
* **Despachar imediatamente** — o pedido é despachado para o método selecionado assim que a automação for acionada.
* **Próximo horário de operação disponível ou próximo dia útil de operação** — se estiver dentro do horário de operação, despacha na hora; senão, agenda pra próxima abertura.
*A seção fica inline no accordion de Ação, junto do método e da condição de disparo.*
## 🎯 Aguardar alguns minutos antes do despacho [#-aguardar-alguns-minutos-antes-do-despacho]
Em qualquer uma das duas opções, você pode somar minutos ao disparo com o campo **Aguardar**.
Exemplo: a regra agendaria o envio pra próximo horário de operação às 07:30. Com aguardo de 15 minutos, o pedido será agendado pra 07:45.
Útil pra dar tempo do pedido ser conferido, gerar etiqueta ou esperar uma janela específica antes de sair.
## 📍 Novo gatilho: Fora da Área de Cobertura [#-novo-gatilho-fora-da-área-de-cobertura]
Na automação de reenvio, dentro do gatilho **Falha na solicitação**, agora tem mais uma opção: **Fora da Área de Cobertura**.
*Junto de "Erro na transportadora", "Transportadora não respondeu a tempo" e "Transportadora cancelou".*
Quando uma tabela de frete tem **"Restringir à abrangência da tabela"** ligado, o sistema bloqueia o despacho de pedidos cujo CEP (ou localização, no caso de tabela por raio) cai fora da abrangência configurada — e a falha entra como Fora da Área de Cobertura. Antes esse cenário ficava parado esperando alguém intervir; agora a regra de reenvio reage automaticamente, mandando pra outro método ou seguindo a sequência configurada.
## O que não mudou [#o-que-não-mudou]
* O resto do fluxo da automação (condições, sequência de ações, validade) continua igual.
* Regras existentes seguem despachando imediatamente — só passam a usar a nova opção quando você editar e escolher.
***
---
# Chegou o PIN de coleta no sentido motorista → loja (/docs/changelog/2026-05-13-pin-coleta)
✅ No ar pra quem operar nesse novo modelo. Pra quem segue no fluxo de sempre (loja → motorista), nada muda — continua igualzinho. A escolha do modelo a gente combina com você.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Antes, a coleta com PIN só rolava num sentido: **a loja recebia um código e passava pro motorista**, que confirmava no app dele. Funcionava, mas dependia da transportadora pra tudo.
Agora tem um segundo modelo, no sentido **motorista → loja**: a **Abbiamo gera o código** quando o pedido é despachado, e quando o entregador chega na loja ele **fala o código pro operador**, que digita no dashboard. A gente confirma na hora e o motorista só sai com o pacote quando bate.
> 📖 Quer ver o passo a passo ponta a ponta (inclusive como a transportadora recebe o código)? O guia completo está na documentação: [Pincode de coleta — fluxo motorista para loja](/docs/api/guias/pickup-pincode-driver-to-seller).
## O que mudou [#o-que-mudou]
🔐
O código agora pode ser nosso
Quando você opera nesse modelo, a Abbiamo gera um código único por entrega na hora do despacho. A transportadora recebe e mostra pro motorista no app dela.
⌨️
Operador digita, a gente confere
Bloco novo no drawer do pedido com 4 caixinhas. Conforme digita já aparece um joinha (ou um xis) — sem deixar apertar botão com código errado.
🔄
Pedido vai pra coletado sozinho
Bateu o código? A gente avisa a transportadora destravar o motorista no app dele, espera a confirmação dela e marca o pedido como coletado — quem atualiza o status nesse modelo é a Abbiamo, não a transportadora.
## Por que fizemos assim [#por-que-fizemos-assim]
Quando a Abbiamo gera e confere o código, ele fica **mais perto da loja** — que é quem é dona do pedido e quem precisa garantir que a mercadoria certa saiu pra coleta certa. Sobra um arranjo mais simétrico: a transportadora não carrega regras que não são dela, a loja enxerga tudo, e a gente faz o meio de campo.
Na prática:
* **A loja enxerga e controla.** O operador digita no dashboard e o histórico das tentativas fica no pedido.
* **Dá pra destravar caso esquisito sem ligar pra transportadora.** Motorista perdeu o código, fila grande no balcão, app travou — alguém da operação da loja resolve direto pelo dashboard.
* **A transportadora respira mais.** A gente só pede pra ela destravar o motorista quando o código bateu e o pedido ainda não foi coletado. Erro de digitação não vira chamada pra ela — o operador vê o aviso na hora.
## ⌨️ O bloco novo no drawer do pedido [#️-o-bloco-novo-no-drawer-do-pedido]
Abriu um pedido que tá nesse modelo? Aparece o bloco "Validar PIN de coleta" dentro de **Dados de Entrega**. Quando a gente tem essa info, mostramos também os **dados do motorista esperado** (nome, documento, telefone, veículo + placa) — pra o operador bater olho antes de digitar.
*Quatro caixinhas com auto-focus pra próxima. Pode colar o código todo de uma vez, Backspace volta, setas navegam.*
### Feedback ao vivo [#feedback-ao-vivo]
Mal o operador termina de digitar, a gente já devolve o resultado — sem precisar clicar em nada.
*Errou? Vermelho na hora. Confirma com o motorista, corrige e tenta de novo.*
*Acertou? Verde, e o botão "Liberar coleta" acende. Com código errado o botão simplesmente não responde — sem liberar por descuido.*
## 🔄 Liberação na hora [#-liberação-na-hora]
Quando o operador clica em "Liberar coleta", três coisas acontecem em sequência (e em segundos):
1. A gente **avisa a transportadora destravar o motorista** no app dele — ela precisa confirmar do lado dela antes da gente seguir.
2. Com o motorista destravado, **a Abbiamo marca o pedido como coletado** — quem atualiza o status nesse modelo é a gente, não a transportadora.
3. O operador vê o card verde de confirmação na hora e o histórico do pedido já mostra o evento de coleta.
*Tudo no mesmo lugar: motorista esperado, código conferido, pedido coletado.*
Se a transportadora não responder no tempo certo, o operador vê um aviso claro, o pedido **não** vai pra coletado e o pacote **não** sai. Sem zona cinza.
## E pra quem é embarcador? [#e-pra-quem-é-embarcador]
Hoje a validação acontece pelo **dashboard da Abbiamo**. Se a sua operação prefere disparar a conferência direto do seu próprio sistema (sem passar pelo nosso painel), ainda não tem endpoint público pra isso — mas tá na lista. Quando sair, a gente avisa por aqui.
## O que **não** mudou [#o-que-não-mudou]
* **Fluxo loja → motorista continua igualzinho.** Quem opera no modelo de sempre (a transportadora dá o código) segue exatamente como tá. Ninguém precisa migrar.
* **Devolução de pacote** (motorista trazendo de volta depois de uma falha de entrega) segue usando o fluxo atual — ainda sem PIN. Tem novidade nessa frente vindo aí, mas é outro post.
***
---
# DC-e nos envios sem NF-e: mais controle na criação de pedidos (/docs/changelog/2026-05-14-dc-e-envios-sem-nf-e)
✅ Disponível agora para operações que precisam informar dados da DC-e em pedidos sem NF-e. Quem não informa DC-e manualmente segue criando pedidos pelo fluxo normal.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Antes, informar a declaração dependia do canal de criação ou da etapa posterior com a transportadora. Agora, quando sua operação já emite a **Declaração de Conteúdo Eletrônica (DC-e)**, os dados entram no pedido desde a criação: chave, série e número do documento.
## O que mudou [#o-que-mudou]
📄
DC-e junto do pedido
Quando sua operação já emite a DC-e, dá para informar os dados do documento no mesmo fluxo em que o pedido é criado.
✅
Menos retrabalho depois
Se um campo for preenchido, os três precisam estar corretos. A gente valida chave, série e número antes do pedido avançar.
🔌
Canais cobertos
O suporte vale para formulário manual, CSV/XLSX, XML, API pública e integrações de pedido.
↩️
Fluxo atual preservado
Se a DC-e não for informada, o pedido continua seguindo pelo fluxo que sua operação já usa hoje.
Antes
Documento espalhado
Quando o pedido não tinha NF-e, os dados da declaração podiam depender do canal usado para criar o pedido ou da etapa posterior com a transportadora.
Agora
DC-e no lugar certo
O pedido já nasce com os dados da DC-e quando eles existem, e o sistema segura preenchimentos parciais ou inconsistentes antes de seguir.
## Onde informar a DC-e [#onde-informar-a-dc-e]
A DC-e pode entrar pelos principais caminhos de criação de pedido:
* **Formulário manual** — o operador pode marcar a opção para informar os dados da DC-e e preencher chave, série e número.
* **CSV/XLSX** — as colunas de DC-e são opcionais. Se uma linha vier com erro, a falha fica restrita àquela linha, sem bloquear o arquivo inteiro.
* **XML** — quando o arquivo trouxer os dados da DC-e, eles são mapeados automaticamente para o pedido.
* **API pública e integrações** — sistemas integrados podem enviar os dados de DC-e no payload de criação de pedido.
*A opção aparece dentro do fluxo de criação do pedido. Se a operação não informar DC-e manualmente, o pedido segue pelo caminho normal.*
*Ao informar uma chave válida, série e número podem ser preenchidos automaticamente para reduzir erro de digitação.*
## Como a gente evita preenchimento errado [#como-a-gente-evita-preenchimento-errado]
Ao informar DC-e, o sistema valida os dados antes de criar ou importar o pedido:
* **Chave** com 44 dígitos numéricos.
* **Série** com 3 dígitos.
* **Número** com 9 dígitos.
* Se um dos três campos for informado, os outros dois também precisam ser preenchidos.
* Série e número precisam bater com os valores presentes na chave.
* A chave precisa ser de uma DC-e. Chaves de NF-e ou CT-e são recusadas nesse campo.
No formulário manual, ao preencher uma chave válida, a série e o número podem ser preenchidos automaticamente a partir da própria chave. O operador ainda consegue revisar e ajustar os campos, mas o sistema valida a consistência antes de seguir.
*Se a série ou o número não baterem com a chave, o sistema mostra o erro antes do pedido avançar.*
## O que não mudou [#o-que-não-mudou]
* Criar pedido sem informar DC-e continua permitido.
* Quando o pedido tem NF-e, ela continua sendo o documento fiscal principal.
* Transportadoras que geram DC-e automaticamente seguem usando o fluxo normal da integração.
* Regras específicas de transportadora, como campos adicionais ou limites de valor, continuam sendo tratadas na etapa de integração.
***
---
# Crie rotas via API a partir de pedidos que já existem (/docs/changelog/2026-05-18-criar-rota-via-api)
✅ No ar em produção. Disponível pra qualquer seller group.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Antes, pra criar uma rota via API você usava `POST /v2/orders/route`, que **criava os pedidos e a rota no mesmo request**. Funciona, mas se você já tinha cadastrado os pedidos via outro caminho (webhook, integração, dashboard), precisava reenviar tudo.
Agora tem `POST /v2/routes`: você manda **só os `order_ids` que já existem** + os dados da rota, e a gente monta a rota apontando pra eles.
> 📖 Referência completa com schema, exemplos e códigos de erro: [Create Route from Orders](/docs/api/routes/create-route-from-orders).
## Quando usar [#quando-usar]
* **Pedido já está na Abbiamo.** Se o pedido já entrou pelo seu fluxo normal (integração, webhook, dashboard, outro endpoint), use o endpoint novo. Mais simples, menos payload.
* **Pedido ainda não existe.** Se quer criar pedido + rota no mesmo request, continue usando `POST /v2/orders/route`. Nada muda nele.
## Payload [#payload]
```http
POST /v2/routes
x-abbiamo-seller-group-key:
Content-Type: application/json
```
```json
{
"order_ids": [
"22222222-2222-2222-2222-222222222222",
"33333333-3333-3333-3333-333333333333"
],
"route": {
"driver_document": "12345678909",
"cost": 1000,
"start": {
"type": "WAREHOUSE_SELLER_IDENTIFIER",
"value": "minha-loja-01"
},
"end": {
"type": "WAREHOUSE_SELLER_IDENTIFIER",
"value": "minha-loja-01"
},
"orders_sequenced": false
}
}
```
### Campos da rota [#campos-da-rota]
* **`start`** *(obrigatório)* — local de partida. `type` é sempre `WAREHOUSE_SELLER_IDENTIFIER` e `value` é o `identifier` do seller cujo local será usado.
* **`end`** *(opcional)* — local de chegada (se a rota terminar em outro lugar).
* **`driver_document`** *(opcional)* — CPF do motorista. Quando informado, tem que pertencer a algum seller do seu seller group. Veja a seção abaixo pra entender o papel desse campo.
* **`cost`** *(opcional)* — custo da rota, em centavos.
* **`expected_duration` / `expected_distance`** *(opcionais)* — duração estimada em minutos e distância em metros.
* **`orders_sequenced`** *(opcional, default `false`)* — se `true`, a ordem do array `order_ids` define a sequência da rota.
* **`external_name`** *(opcional)* — nome externo pra identificar a rota nos seus sistemas.
### O papel do `driver_document` [#o-papel-do-driver_document]
`driver_document` é **opcional de propósito** — e isso muda como você pode operar a rota:
* **Passou o `driver_document`** → a rota já nasce com motorista atribuído, pronta pra ser despachada com a sua frota.
* **Não passou** → a rota fica **criada e "parada"** (sem motorista). Aí você decide depois, pelo dashboard, o que fazer com ela:
* Atribuir um motorista próprio e despachar normalmente, **ou**
* Despachar pra uma **transportadora (TRP) que suporte esse tipo de operação**, e quem faz a entrega é a TRP.
Ou seja, dá pra usar o endpoint só pra **agrupar pedidos numa rota** e deixar a decisão de quem entrega pra um segundo momento, sem precisar ter um motorista na mão na hora de criar.
## Validações [#validações]
Antes de criar a rota, a gente valida — e devolve erro claro se algo não bater:
* Cada `order_id` **existe e pertence ao seu seller group** → senão, `INVOICE_NOT_FOUND_OR_NOT_IN_SELLER_GROUP` (404).
* Cada pedido está **roteirizável** → senão, `INVOICE_NOT_ROUTEABLE` (400). Detalhe abaixo.
* O `seller_identifier` do `start`/`end` tem um local ativo associado → senão, `WAREHOUSE_NOT_FOUND` (404).
* O motorista (quando informado) **pertence a algum seller do seller group** → senão, `DRIVER_NOT_FOUND` (404).
### O erro `INVOICE_NOT_ROUTEABLE` em detalhe [#o-erro-invoice_not_routeable-em-detalhe]
Esse é o erro que mais aparece na prática. Um pedido **deixa de ser roteirizável** quando ele **já foi despachado em outro lugar** — ou seja:
* Já foi **incluído em outra rota** (mesmo que ainda não tenha saído pra entrega), **ou**
* Já foi **despachado como envio individual pra uma transportadora (TRP)**.
O motivo é simples: cada pedido só pode estar em **um** despacho ativo. Se ele já tá em rota A, não dá pra colocar em rota B sem antes cancelar a A.
A resposta vem assim:
```json
{
"status_code": 400,
"timestamp": "2026-05-18T19:20:35.397Z",
"message": "Orders are not routeable: b235ada8-54ca-454e-8800-e64ecefa28a2",
"code": "INVOICE_NOT_ROUTEABLE",
"error_id": "f6c4b159-e94e-41b6-92c4-da29d3cc0580",
"params": {
"order_ids": [
"b235ada8-54ca-454e-8800-e64ecefa28a2"
]
}
}
```
**Como tratar:** olhe a lista `params.order_ids` — esses são os culpados. Você pode:
1. Remover os ids problemáticos da chamada e refazer com o restante, **ou**
2. Cancelar o despacho anterior do pedido (rota antiga ou envio pra transportadora) e tentar de novo, **ou**
3. Conferir no dashboard onde aquele pedido foi parar — geralmente o histórico do pedido mostra a rota/envio que travou.
***
---
# iFood agora é transportadora na Abbiamo (/docs/changelog/2026-05-18-integracao-ifood)
✅ Disponível agora para clientes com contrato ativo de Shipping iFood. Entre em contato com o CS para habilitar.
## O que é [#o-que-é]
O iFood não é só um marketplace de delivery — ele também tem uma rede própria de motoboys disponível para lojas e restaurantes parceiros. Com a nova integração: o pedido sai do sistema do cliente, a Abbiamo aciona o iFood, o iFood aloca um motoboy, e tudo volta pro dashboard da Abbiamo em tempo real.
O cliente não precisa instalar nada, configurar nenhuma API ou criar conta de desenvolvedor no iFood. A Abbiamo cuida de toda a parte técnica.
🛵
Frota do iFood
Acesse a rede de motoboys do iFood como mais uma opção de transportadora — sem montar frota própria.
📍
Rastreamento completo
Do "buscando entregador" até "entregue" (ou "retornou"), cada status aparece no dashboard automaticamente.
⚙️
Zero configuração técnica
O cliente só precisa do
merchant_id
da loja no iFood. O resto é com a gente.
## Como funciona na prática [#como-funciona-na-prática]
O fluxo completo, do ponto de vista do cliente:
1. **Pedido criado** — a loja despacha uma entrega normalmente pelo sistema integrado à Abbiamo.
2. **iFood recebe** — a Abbiamo envia o pedido para a API do iFood, que faz uma cotação e reserva um motoboy.
3. **Status em tempo real** — conforme o motoboy se move, os eventos chegam automaticamente: buscando motoboy → coletando → saiu para entrega → entregue.
4. **Tudo no dashboard** — o operador acompanha cada etapa sem precisar abrir nenhuma outra plataforma.
Antes
Gestão fragmentada
Quem usava a frota do iFood gerenciava as entregas fora da Abbiamo — sem visibilidade centralizada, sem rastreamento unificado.
Agora
Tudo em um lugar
A frota do iFood entra como mais uma transportadora no Abbiamo. Despacha, rastreia e cancela — tudo pelo dashboard.
## O que o cliente precisa ter [#o-que-o-cliente-precisa-ter]
Para ativar a integração, o cliente precisa de três coisas:
1. **Conta ativa no Portal do Parceiro iFood** com o módulo de Shipping habilitado para a loja.
2. **Contrato Abbiamo** com integração de transportadora habilitada para o iFood.
3. **O `merchant_id` da loja** — o identificador único da loja no iFood, que o cliente repassa para o nosso time de CS.
O resto — credenciais, webhook, autenticação — a Abbiamo configura e mantém de forma centralizada para todos os clientes.
*Cadastro da integração por filial: selecione a filial, escolha IFOOD como transportadora e informe o ID do cliente (merchant\_id). O campo "ID experiment iFood" é opcional e fornecido pelo iFood ao integrar uma nova marca.*
> Se a marca tiver múltiplas filiais no iFood, cada uma tem seu próprio `merchant_id` e é cadastrada separadamente na Abbiamo.
***
## O que mudou [#o-que-mudou]
Ao montar a condição de uma regra, o campo **Número do pedido** entra na lista junto de CEP, peso, valor e os outros. Como ele é um campo de texto, vem com a régua completa de operadores:
* **Igualdade:** `=`, `!=`, `in`, `notIn`
* **Texto parcial:** `contém`, `começa com`, `termina com` (e os respectivos negados)
* **Vazio/preenchido:** `é nulo`, `não é nulo`
## Pra que serve [#pra-que-serve]
O caso clássico é **rotear por prefixo de número**. Se o ERP gera pedidos com prefixos diferentes por canal de venda (ex.: `PRC-SHO...` pra um canal, `VIP-...` pra clientes premium, `B2B-...` pra atacado), agora dá pra criar regras que olham só pra esse pedaço do número:
> "Pedidos cujo número **começa com `PRC-SHO`** → despachar imediatamente no método `LALAMOVE/CAR/EXP30`."
*Condição configurada com `Número do pedido` + `começa com` + `PRC-SHO`, ação enviar pra método específico.*
Outros usos que apareceram em conversas com sellers:
* **Contém `VIP`** → sobe pra uma TRP mais rápida.
* **Termina com `-DEV`** → separa pedidos de teste pra um método sandbox.
* **Não começa com o prefixo da loja principal** → reenvio mais agressivo pra pedidos de canais secundários.
## Onde aparece [#onde-aparece]
A condição está em todos os quatro tipos de automação que usam o mesmo motor de regras:
* **Automações de envio** — escolhe o método com base no número.
* **Automações de reenvio** — só reenvia pedidos com determinado prefixo (ou exclui um prefixo).
* **Automações de inatividade** — atua só num subconjunto de pedidos.
* **Oferta automática** — filtra quais pedidos entram na esteira de oferta.
## O que não mudou [#o-que-não-mudou]
* Regras existentes continuam idênticas — o campo novo só aparece quando você adiciona uma condição.
* O número considerado é o **número do pedido na Abbiamo** (o mesmo que aparece na listagem e no detalhe do pedido).
***
---
# Reenvio em cascata: cada nível reenvia para uma transportadora diferente (/docs/changelog/2026-05-28-reenvio-cascade)
✅ Disponível agora em Automações de reenvio. Não precisa mexer em nada nas regras existentes — vale automaticamente pra qualquer cascata com mais de uma ação Mais barato ou Mais rápido.
## O que mudou [#o-que-mudou]
Em automações de reenvio que encadeiam múltiplas ações **Mais barato** (ou **Mais rápido**), cada nível agora considera só as combinações de **transportadora/modalidade/prazo** que ainda **não foram tentadas** no pedido. A escolha continua sendo pelo preço (ou pelo tempo), só que dentro do conjunto restante.
Antes
A cascata empacava na mesma combinação
Cada nível pedia "a opção mais barata" do zero. Como a cotação devolvia sempre o top 1, os três níveis caíam na mesma transportadora/modalidade/prazo — o pedido tentava três vezes a mesma opção que já tinha falhado, até esgotar a rede de segurança interna.
Agora
Cada nível pula o que já tentou
O segundo nível pega a segunda mais barata. O terceiro, a terceira mais barata. E assim por diante — sem repetir a transportadora e a modalidade que já falharam no mesmo pedido.
## Pra que serve [#pra-que-serve]
O caso clássico é uma cascata de fallback estilo:
> "Falhou a primeira → tenta o **mais barato**. Falhou de novo → tenta o **mais barato**. Falhou de novo → tenta o **mais barato**."
Antes, se a primeira opção da cotação fosse, por exemplo, Uber/CARRO/EXP120, os três níveis tentavam Uber/CARRO/EXP120 e o pedido nunca saía. Agora a sequência fica natural — Uber/CARRO/EXP120 → próxima opção do ranking → terceira opção do ranking — até alguma dar certo ou as opções acabarem.
*A mesma regra que antes ficava presa numa transportadora agora percorre o ranking de cotação de cima pra baixo, pulando o que já falhou.*
## Se esgotar todas as opções, a regra para na hora [#se-esgotar-todas-as-opções-a-regra-para-na-hora]
Quando todas as transportadoras compatíveis com o pedido já foram tentadas, o reenvio falha imediatamente em vez de continuar batendo numa porta fechada. O pedido vai pra atenção manual mais rápido e a sua fila de retentativas não fica entupida com tentativas inviáveis.
*Quando a cascata pede a próxima opção e não sobra ninguém, a regra encerra com motivo "todas as opções já tentadas".*
## Vale também pra "Mais rápido" [#vale-também-pra-mais-rápido]
A mesma lógica se aplica quando a ação é **Mais rápido**: o segundo nível escolhe a segunda modalidade mais rápida que ainda não foi tentada, e assim por diante. Cascatas mistas (ex: mais barato → mais rápido → mais barato) também respeitam o histórico.
## O que não mudou [#o-que-não-mudou]
* Cascatas com ações **Modalidade específica** continuam idênticas — quem está marcado pra ir numa modalidade fixa vai na modalidade fixa, mesmo se já tiver sido tentada.
* A ordenação do ranking (preço pra "Mais barato", tempo pra "Mais rápido") é a mesma de antes — a mudança é só **quem entra no ranking**.
* A regra ainda pode tentar a mesma transportadora em **modalidades diferentes** (ex: Uber/CARRO/EXP30 depois de Uber/CARRO/EXP120 falhar) — a exclusão é pelo par transportadora + modalidade, não só pela transportadora.
***
---
# Marcadores de filial (/docs/changelog/2026-05-29-marcador-filiais)
✅ Disponível agora em Configurações → Marcadores. Crie um marcador, escolha a cor e comece a aplicar nas filiais.
## O que mudou [#o-que-mudou]
Chegou uma forma de **agrupar e etiquetar filiais** do jeito que faz sentido pra sua operação. Crie marcadores com **nome e cor** — *Premium*, *Centro de distribuição*, *Franquia*, *Loja própria*, o que você quiser — e aplique nas filiais. Depois é só usar pra **filtrar, organizar e recortar** o que você vê.
Antes
Filial era só um nome numa lista
Não dava pra agrupar filiais por característica. Pra trabalhar com "só as franquias" ou "só os CDs" você precisava saber de cabeça quais eram e selecionar uma por uma.
Agora
Etiquetas coloridas e filtráveis
Cada filial pode ter um ou mais marcadores. Eles aparecem como bolinhas coloridas, viram filtro com um clique e dão pra selecionar grupos inteiros de uma vez.
## Crie seus marcadores [#crie-seus-marcadores]
Em **Configurações → Marcadores**, monte os marcadores do seu grupo com nome e cor. A cor é o que deixa a leitura rápida lá na lista — bate o olho e já sabe o tipo da filial.
*Cadastro de marcadores com nome e cor, no padrão dos marcadores de pedido e de motorista.*
## Aplique em uma filial ou em massa [#aplique-em-uma-filial-ou-em-massa]
Tem dois caminhos pra aplicar:
* **Em uma filial:** pelo menu de ações da filial na lista, em **Aplicar marcadores**.
* **Em massa:** marque várias filiais na lista de **Filiais** e use a ação em massa **Aplicar marcadores** — ideal pra etiquetar dezenas de filiais de uma vez.
*O mesmo modal funciona pra uma filial só ou pra uma seleção inteira.*
## Veja e filtre na lista de filiais [#veja-e-filtre-na-lista-de-filiais]
Na página de **Filiais**, os marcadores aparecem como **bolinhas coloridas** (igualzinho aos marcadores de pedido e de motorista). E eles são **clicáveis**: um clique na bolinha já filtra a lista por aquele marcador. No topo da página também tem um **seletor de marcadores** pra combinar mais de um.
As bolinhas de marcador também aparecem (e são clicáveis pra filtrar) nas listas de **Pedidos** e **Motoristas**, mantendo a mesma linguagem visual em todo o dashboard.
## Use como filtro no seletor de filiais [#use-como-filtro-no-seletor-de-filiais]
Os marcadores conversam direto com o [novo seletor de filiais](/docs/changelog/2026-05-29-seletor-filiais): digite `marcador:premium` na busca do seletor e trabalhe só com aquele grupo de filiais — sem precisar lembrar quais são.
## O que não mudou [#o-que-não-mudou]
* Filiais sem marcador continuam funcionando normalmente — marcador é opcional.
* Marcador é só uma etiqueta organizacional: ele **não altera** roteirização, cotação ou qualquer regra de operação por conta própria.
***
---
# Novo seletor de filiais (/docs/changelog/2026-05-29-seletor-filiais)
✅ Disponível agora — é o seletor "Você está visualizando" no rodapé da barra lateral. Abra clicando nele ou apertando Ctrl/⌘ + B de qualquer tela.
## O que mudou [#o-que-mudou]
O seletor de filiais foi reconstruído do zero pensando em quem opera com **dezenas ou centenas de filiais**. Em vez de rolar uma lista gigante procurando no olho, agora você **busca, cola ou filtra** — e marca tudo em segundos.
Antes
Rolar a lista no braço
Uma lista longa de filiais pra rolar e marcar uma por uma. Achar a filial certa em grupos grandes era lento, e não dava pra filtrar por cidade, estado ou marcador.
Agora
Buscar, colar e filtrar
Busca por qualquer campo da filial, colar uma lista pronta de identificadores/CNPJs, filtros por estado/cidade/marcador na própria busca e navegação 100% por teclado.
## Abra de qualquer lugar com um atalho [#abra-de-qualquer-lugar-com-um-atalho]
Ctrl/⌘ + B
*O seletor abre focado no campo de busca — é só começar a digitar.*
## Busca inteligente (e sem acento) [#busca-inteligente-e-sem-acento]
Digite qualquer coisa e a busca casa contra **nome da filial, identificador, CNPJ, cidade, estado, bairro e marcadores**. E o melhor: **acento não importa** — `guaruja` encontra **Guarujá**, `sao paulo` encontra **São Paulo**.
Cada filial aparece com **cidade/UF e seus marcadores**, então dá pra confirmar de bate-pronto que é a filial certa.
## Cole uma lista inteira de uma vez [#cole-uma-lista-inteira-de-uma-vez]
O caso clássico de quem recebe uma planilha: **cole uma lista de identificadores ou CNPJs** separados por vírgula, espaço ou quebra de linha, e o seletor marca todos de uma vez. O que ele não reconhecer é sinalizado, pra você conferir.
> Cole `00.776.574/0001-01, LOJA-SP-01, LOJA-RJ-02` e pronto — as três filiais já vêm marcadas.
## Filtros direto na busca: `estado:` `cidade:` `marcador:` [#filtros-direto-na-busca-estado-cidade-marcador]
Pra recortes maiores, a busca entende uma sintaxe de filtros que se combinam (E lógico):
* `estado:SP` — só filiais de São Paulo
* `cidade:"Belo Horizonte"` — use aspas quando o nome tem espaço
* `marcador:premium` — só filiais com o marcador *premium*
Conforme você digita o nome do filtro, aparece um **chip rápido** (Estado / Cidade / Marcador) pra completar com um toque — e em seguida o autocomplete sugere os **valores reais do seu grupo**, já com a contagem de filiais de cada um.
*Comece a escrever `cidade:` e escolha entre os valores existentes — sem decorar nada.*
## Tudo pelo teclado [#tudo-pelo-teclado]
Pensado pra não tirar a mão do teclado:
* **↑ / ↓** navegam tanto a lista de filiais quanto as sugestões do autocomplete.
* **Enter** marca/desmarca a filial em foco (ou aplica a sugestão do autocomplete).
* **Tab** completa o filtro sugerido.
* **Esc** fecha o autocomplete (e, de novo, fecha o seletor).
* Ctrl/⌘ + Shift + A marca/desmarca todas as filiais visíveis no filtro atual.
## Detalhes que deixam a experiência redonda [#detalhes-que-deixam-a-experiência-redonda]
* A lista **não fica pulando** enquanto você seleciona — as marcadas continuam no lugar, com destaque, e só reagrupam no topo quando você faz uma nova busca.
* **Skeleton** de carregamento na primeira abertura, pra ficar claro que os dados estão chegando.
* Fechar sem salvar (no X, clicando fora ou no Esc) **descarta as alterações** e volta pra seleção anterior.
* Por baixo, o seletor passou a usar um endpoint enxuto, então ele **abre mais rápido** mesmo em grupos com muitas filiais.
***
---
# Editar endereço do pedido dinâmicamente (/docs/changelog/2026-05-30-editar-endereco-pedido)
✅ Disponível agora em Pedidos → abre o sidepanel de qualquer pedido e clica no lápis do lado do endereço do cliente. Disponível para usuários com permissão de editar endereço de destino.
## O que mudou [#o-que-mudou]
O dialog de **Editar endereço** no sidepanel do pedido foi refeito do zero pra seguir o mesmo padrão da edição de endereço de filial. O fluxo agora é coerente entre as duas telas, e ganhou três melhorias práticas:
📮
CEP no topo, autofill na hora
Digita o CEP, clica em buscar (ou aperta Enter) e UF, cidade, bairro e rua já vêm preenchidos. O foco pula automaticamente pro próximo campo que ainda está vazio.
📍
Geolocalização recalcula sozinha
Mudou o número, a rua ou o bairro? Ao sair do campo (blur), a geo é recalculada automaticamente — sem precisar lembrar de clicar em "calcular". E o botão manual continua disponível pra quem quiser forçar.
🔔
Toasts mais claros
Salvar, recalcular e buscar CEP agora mostram um toast unificado com loading → sucesso ou erro. Sem aquele empilhamento de mensagens conflitantes que aparecia antes.
## O passo a passo no novo dialog [#o-passo-a-passo-no-novo-dialog]
*O CEP virou o ponto de partida do formulário. Botão "Buscar" do lado, e Enter também dispara.*
*Mudou número/rua/bairro → blur → toast de "recalculando geolocalização" → sucesso. Sem ação manual.*
## O que saiu [#o-que-saiu]
Antes haviam avisos no formulário tipo "a geolocalização pode estar desatualizada" — mas sem botão claro pra agir, e sem recalcular sozinho. Esses avisos confundiam mais do que ajudavam e foram substituídos pelo comportamento proativo: se algo mudou, recalcula; se você quiser forçar, tem o botão.
## O que continua igual [#o-que-continua-igual]
* O **ícone de lápis** do lado do endereço no sidepanel é o mesmo — abre o novo dialog no clique.
* A **permissão** pra editar endereço continua igual, só vale pra pedidos roteirizáveis.
* O **mapa interativo** dentro do dialog continua funcionando — você pode arrastar o pin pra ajustar lat/lng manualmente quando a geo não acerta de primeira.
***
---
# Mapa do trajeto agora aparece direto no painel do pedido (/docs/changelog/2026-05-30-mapa-trajeto-pedido)
✅ Disponível agora em Pedidos. Vale automaticamente para qualquer pedido com endereço de origem e destino geolocalizados — não precisa configurar nada.
## O que mudou [#o-que-mudou]
No sidepanel de pedido (aquele painel lateral que abre quando você clica num pedido da listagem), agora aparece um mapa logo abaixo do endereço do cliente. O mapa mostra:
* **Pino de partida** — endereço de coleta / filial de origem
* **Pino de destino** — endereço do cliente
* **Linha do trajeto** — rota estimada entre os dois pontos
* **Badge de Distância dirigida estimada** — em km, calculada pela rota real (não em km reto)
*O mapa entra inline no painel. Os mesmos dados que já existiam na visão completa, agora à mão.*
## Pra que serve [#pra-que-serve]
Antes, pra ter contexto geográfico do pedido (a quantos km está, em que região, se faz sentido o motorista X cobrir), você precisava conferir endereço por endereço. Agora, ao clicar num pedido na lista e abrir o sidepanel, o mapa já está lá — útil pra:
* **Triagem rápida** de pedidos que estão na fila de oferta ou em retentativa.
* **Decidir manualmente** se vale despachar agora ou esperar agrupar.
* **Conferência visual** de pedidos com endereço duvidoso (cliente em região de risco, fora da abrangência, etc.) sem sair do fluxo.
## Quando o mapa não aparece [#quando-o-mapa-não-aparece]
* **Pedidos do tipo retira (TAKEOUT)** — não tem trajeto, então o mapa fica oculto.
* **Pedidos sem coordenadas no endereço de destino** — geralmente endereços antigos ou que falharam na geocodificação. Editando o endereço (e recalculando a geo — veja o changelog de 28/05) o mapa volta a aparecer.
* **Pedidos antigos sem rota gravada** — o mapa renderiza só os dois pinos, sem a linha do trajeto. A distância em linha reta continua disponível no badge.
## O que não mudou [#o-que-não-mudou]
* Permissões: quem já via o pedido continua vendo o mapa, sem nada novo pra configurar.
***
---
# Cancele entregas agendadas pela API (/docs/changelog/2026-06-02-cancelar-entrega-agendada)
✅ Disponível no endpoint Cancelar entrega. Mesma chamada de sempre — nada muda na integração.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Antes, o cancelamento de entrega só funcionava para entregas já despachadas para a transportadora. Se o pedido tinha uma **entrega agendada** (programada para um horário futuro e ainda não enviada à transportadora), a chamada falhava.
Agora o mesmo endpoint — `PUT /seller-group/v1/orders/{order_id}/cancel-delivery` — cancela também as entregas agendadas.
## Quando usar [#quando-usar]
* **Entrega agendada (ainda não despachada).** A chamada cancela o agendamento na hora, sem esperar a data do despacho e sem acionar a transportadora.
* **Entrega em andamento.** Continua igual: o cancelamento vale enquanto a transportadora ainda não coletou o pacote.
Você não precisa saber em qual estágio o pedido está — é a **mesma chamada** para os dois casos.
## O que não mudou [#o-que-não-mudou]
* O contrato do endpoint é o mesmo (rota, header `x-abbiamo-seller-group-key` e payload).
* Entregas já coletadas pela transportadora continuam não podendo ser canceladas.
***
---
# Clique e Retire agora tem doc: QR e instruções de retirada por filial via API (/docs/changelog/2026-06-03-clique-e-retire)
✅ No ar na documentação pública. Os endpoints já existiam — o que mudou é que agora estão documentados, com guia e playground, pra você gerar o material de retirada sem depender de ninguém.
## A novidade em uma frase [#a-novidade-em-uma-frase]
O material de **Clique e Retire** de cada filial — o **QR Code do cartaz** e o **PDF de instruções** — agora pode ser gerado direto pela API, e a gente documentou tudo: passo a passo no guia operacional e as duas rotas no API Reference.
> 📖 Guia ponta a ponta: [Clique e Retire — material de retirada por filial](/docs/api/guias/retira-clique-e-retire).
## O que documentamos [#o-que-documentamos]
🔳
QR Code estático por filial
Endpoint que devolve o PNG do QR de retirada da filial — o mesmo que vai no cartaz do balcão. É fixo por loja: gere uma vez e reutilize em todos os materiais daquela unidade.
Ver endpoint
.
📄
Instruções em PDF
Endpoint que devolve o PDF com o passo a passo de retirada, pronto pra imprimir e expor junto do QR no ponto de venda.
Ver endpoint
.
🧭
Guia operacional novo
Um guia só de Clique e Retire: como montar o material da filial e como funciona a jornada do pedido (de
TAKEOUT
até retirado).
Ler o guia
.
▶️
Playground pra testar
As duas rotas aparecem no API Reference com o playground inline — coloca a chave, passa o identificador da filial e baixa o material na hora.
## Como usar [#como-usar]
A filial é identificada pelo `identifier` (o mesmo `seller_identifier` que você já usa na criação de pedidos), e a chamada vai autenticada pela sua chave de seller group.
```bash
# QR Code do cartaz (PNG)
curl -X GET \
"https://api.abbiamo.io/v1/takeout/seller/{identifier}/static-qrcode" \
-H "x-abbiamo-seller-group-key: SUA_CHAVE" \
--output retirada-qrcode.png
# Instruções de retirada (PDF)
curl -X GET \
"https://api.abbiamo.io/v1/takeout/seller/{identifier}/instructions" \
-H "x-abbiamo-seller-group-key: SUA_CHAVE" \
--output retirada-instrucoes.pdf
```
Tem mais de uma filial ou bandeira? Repita pra cada `identifier` — cada loja tem seu próprio QR e PDF.
## Onde fica na doc [#onde-fica-na-doc]
* **Guia:** [Clique e Retire — material de retirada por filial](/docs/api/guias/retira-clique-e-retire)
* **API Reference:** [Retirada (Clique e Retire)](/docs/api/retira) → [QR Code estático](/docs/api/retira/static-qrcode) e [Instruções (PDF)](/docs/api/retira/instructions)
* **Jornada do pedido:** [Obter token de retirada](/docs/api/orders/get-takeout-token) e [Marcar pedido como retirado](/docs/api/orders/set-order-as-withdrawn)
***
Dúvida pra habilitar Clique e Retire na sua operação?
Fala com a gente
.
---
# Chegou o Abbiamo Doc: a documentação oficial da plataforma (/docs/changelog/2026-06-04-abbiamo-doc)
✅ No ar — e você já está navegando nele. Esta página de changelog faz parte do Abbiamo Doc, ao lado dos guias, da API Reference e do status.
## O que é o Abbiamo Doc [#o-que-é-o-abbiamo-doc]
Por muito tempo a nossa documentação era basicamente uma **referência de API**: uma lista de endpoints pra quem ia integrar. Boa pra consultar um parâmetro, mas não respondia "como eu **faço** isso na prática?" — nem servia pra quem usa a plataforma pela tela, sem tocar em código.
O **Abbiamo Doc** é a evolução disso — e é onde você está agora: uma central de documentação que junta o **guia operacional** (como a plataforma funciona, papel por papel) com a **referência técnica** (a API, endpoint por endpoint) — interligados, buscáveis e sempre atualizados.
## O que tem aqui dentro [#o-que-tem-aqui-dentro]
🧭
Guias por papel
Trilhas dedicadas pra Embarcador, Frota Própria e Transportadora — cada um encontra o caminho da sua operação, da criação do pedido à entrega.
⚡
API Reference com playground
58 endpoints e 20 webhooks documentados, com playground pra testar a chamada na hora — sem sair da página.
🔎
Busca unificada
Uma busca só que atravessa guias e API. Procure por um conceito, um endpoint ou um campo e caia direto no lugar certo.
📊
Status ao vivo
A saúde da plataforma em tempo real, com indicadores por componente — na home e na página de status.
🆕
Changelog
Todo lançamento, melhoria e correção registrado aqui — exatamente onde você está lendo agora.
🔗
Guia ↔ API interligados
Cada conceito do guia aponta pro endpoint que o executa, e cada endpoint volta pro contexto de negócio. Sem ficar perdido entre as duas pontas.
## O que muda em relação à referência antiga [#o-que-muda-em-relação-à-referência-antiga]
Antes
Só a API
Uma lista de endpoints isolada. Ótima pra conferir um parâmetro, mas sem o "como fazer", sem busca decente e sem nada pra quem opera pela tela.
Agora
Documentação completa
Guia + API + status + changelog, interligados e buscáveis. Pra quem integra e pra quem usa a plataforma — num endereço único e oficial.
## As novidades agora aparecem no seu dashboard [#as-novidades-agora-aparecem-no-seu-dashboard]
Você não precisa nem abrir a doc pra ficar por dentro: as **últimas mudanças** do changelog agora aparecem direto na **barra lateral do dashboard**, ali no rodapé. Um resumo das entradas mais recentes, com um aviso discreto quando tem novidade que você ainda não viu — e o link "Changelog →" pra ver o resto.
*O bloco "Mudanças recentes" no rodapé da barra lateral, logo acima de "Você está visualizando".*
Quer focar? É só **minimizar** o bloco: ele vira uma barrinha "Novidades" e só acende um pontinho quando sai algo novo.
É público e está sempre atualizado — salve nos favoritos.
---
# Detalhe do pedido agora abre lado a lado com a lista (/docs/changelog/2026-06-04-painel-pedido-lado-a-lado)
✅ Disponível agora em Pedidos — clique em qualquer linha pra abrir o painel do pedido ao lado da lista.
## O que mudou [#o-que-mudou]
Antes, abrir um pedido cobria a tabela com um painel por cima — pra ver outro pedido você tinha que fechar e procurar de novo. Agora o painel **divide o espaço** com a lista: a tabela continua à vista e você navega de pedido em pedido com um clique, sem perder o contexto.
*A lista continua visível enquanto o painel abre ao lado — clique em outra linha pra trocar de pedido.*
↔️
Painel lado a lado
O detalhe do pedido abre ao lado da tabela em vez de cobrir tudo. A lista fica sempre visível.
👆
Troca com um clique
Clicou na linha, o painel já mostra aquele pedido. Pra ver outro, é só clicar na próxima linha — sem fechar nada.
🖱️
Botão direito = Ações
Clique com o botão direito em qualquer linha pra abrir o mesmo menu de ações dos três pontinhos, ali no cursor.
⚡
Tabela mais leve
A lista de pedidos rola mais suave, mesmo com muitos pedidos carregados na página.
⏱️
Prazos e linha do tempo
No topo do painel você vê o prazo prometido ao cliente e uma linha do tempo de Preparo → Entrega.
## Prazos e linha do tempo no topo [#prazos-e-linha-do-tempo-no-topo]
Logo no topo do painel você vê o **prazo prometido ao cliente** e uma **linha do tempo** com o tempo de Preparo e de Entrega — dá pra avaliar o pedido sem rolar a tela.
*Prazo prometido + linha do tempo (Preparo → Entrega) logo no topo do painel.*
## A linha selecionada fica destacada [#a-linha-selecionada-fica-destacada]
Quando um pedido está aberto, a linha dele na tabela fica **destacada** — fica fácil saber qual você está olhando enquanto navega pela lista.
## Exportar virou atalho pro relatório [#exportar-virou-atalho-pro-relatório]
O botão **Exportar** na tela de Pedidos agora abre direto a criação de relatório, já com a seção **Pedidos** selecionada — é só ajustar o período e os filtros e gerar.
## Botão direito abre o menu de ações [#botão-direito-abre-o-menu-de-ações]
Não precisa mais mirar nos **três pontinhos**: clique com o **botão direito** em qualquer linha da tabela e o mesmo menu de ações abre ali no cursor — rastreio, etiqueta, DANFE, duplicar pedido, editar marcadores e o resto.
*Botão direito em qualquer linha abre o menu de ações no cursor — os mesmos atalhos dos três pontinhos.*
## Detalhe do pedido continua completo [#detalhe-do-pedido-continua-completo]
Tudo que já estava no painel segue lá: dados do pedido e do cliente, endereço com mapa, produtos e volumes, histórico de status e o menu de **Ações** (com rastreio, etiqueta, DANFE, reenvio, marcadores e mais). O menu de **três pontinhos** na linha da tabela também continua, pros atalhos rápidos sem abrir o painel.
---
# Exportar pedidos: tela atual na hora ou relatório completo com seus filtros (/docs/changelog/2026-06-09-exportar-pedidos)
✅ Disponível agora em Pedidos → botão Exportar, no topo da lista.
## A novidade em uma frase [#a-novidade-em-uma-frase]
O **Exportar** da tela de Pedidos deixou de ser um botão único e virou um **menu com duas opções**: baixar na hora o que está na tela, ou gerar o relatório completo já com os filtros que você aplicou.
## O que mudou [#o-que-mudou]
⬇️
Exportar tela atual
Baixa na hora um CSV com os pedidos que estão na tela. Antes de baixar, você escolhe o idioma dos cabeçalhos (Português ou Inglês) — e as colunas saem com os
mesmos nomes do relatório
, pra bater com o que você já usa.
📊
Gerar relatório completo
Abre a página de Relatórios com o formulário de novo relatório já aberto e
pré-preenchido com os filtros da tela
: período, filiais, status e transportadoras. É só conferir e gerar.
🎯
Seus filtros vão junto
Filtrou Pedidos por status "Criado" e pela transportadora X? Ao gerar o relatório completo, esses filtros já chegam aplicados. Pra mudar, é só ajustar os filtros na tela de Pedidos.
🚚
Status e transportadoras no relatório
O formulário de relatório de
Pedidos
agora tem filtro de
status
e de
transportadoras
direto ali, além de período e filiais.
## Como funciona [#como-funciona]
1. Na tela de **Pedidos**, ajuste os filtros como quiser (período, filiais, status, transportadoras).
2. Clique em **Exportar** e escolha uma das opções:
*O botão **Exportar** abre um menu com as duas opções.*
### Exportar tela atual [#exportar-tela-atual]
Abre um diálogo rápido que mostra **quantos pedidos serão exportados** e um resumo dos **filtros aplicados** (somente leitura — pra mudar, ajuste os filtros na própria tela). Você escolhe o **idioma dos cabeçalhos** e baixa o CSV na hora.
*Mostra quantos pedidos saem (página atual e total com os filtros), os filtros aplicados e o idioma dos cabeçalhos.*
### Gerar relatório completo [#gerar-relatório-completo]
Leva você para **Relatórios** com o formulário de novo relatório já aberto, tipo **Pedidos** selecionado e os filtros da tela (período, filiais, status, transportadoras) preenchidos. Confira e clique em **Gerar relatório**.
*O relatório completo já abre com os filtros da tela de Pedidos aplicados — incluindo os filtros de status e transportadoras direto no formulário.*
## Onde ver na doc [#onde-ver-na-doc]
* [**Relatórios — Como usar**](/docs/log/products/relatorios/como-usar/): o passo a passo completo, incluindo o novo fluxo de exportação a partir da tela de Pedidos.
***
---
# Chegou o Care: o pós-venda da sua operação num lugar só (/docs/changelog/2026-06-10-care-lancamento)
✅ Disponível agora para todas as contas, em /care/disputes. Configure o e-mail de contato em Care → Configurações e comece.
## O que é [#o-que-é]
O **Care** é o módulo de pós-venda da Abbiamo. Quando algo dá errado com um pedido — não chegou, chegou com itens faltando ou danificados, veio o produto errado — o caso vira uma **disputa**: um registro único, com histórico próprio, onde você conversa com o cliente, aciona a transportadora e fecha registrando o que aconteceu.
Sem caixa de e-mail bagunçada, sem planilha paralela, sem "quem é que estava cuidando disso mesmo?".
## O que dá pra fazer [#o-que-dá-pra-fazer]
Conversar com o cliente
Um chat direto na página de rastreio. O cliente vê o nome da sua loja; seu time vê qual agente respondeu.
Acionar a transportadora
Acione pela sua via habitual com ela e mantenha o andamento atualizado no Care.
Organizar o time
Notas internas que o cliente nunca vê, e um responsável por disputa.
Registrar o desfecho
Entregue, retornado, perdido… e a compensação: reembolso, voucher ou reenvio.
## Abrir uma disputa, do jeito que fizer sentido [#abrir-uma-disputa-do-jeito-que-fizer-sentido]
* O **cliente abre** pela página de rastreio, escolhendo o motivo e os itens afetados.
* Ou **você abre** — pela lista de disputas, ou direto do menu de ações de um pedido entregue.
E na própria tela de **Pedidos** dá pra ver, num ícone, quais pedidos têm disputa, e filtrar por **disputa aberta**, **fechada** ou **sem disputa**.
## Feito pra rodar do seu jeito [#feito-pra-rodar-do-seu-jeito]
O Care se adapta à sua operação nas **Configurações**:
* **Agentes**: escolha quem do time aparece como responsável.
* **SLA**: ligue se você trabalha com prazo; desligue se não.
* **Chat**: deixe o cliente conversar pelo rastreio, ou registre o caso sem abrir chat.
* **Transportadoras**: e-mail de cada uma e acionamento automático.
* **Moderação de imagens**, **auto-fechamento** e **notificações**.
## Feito pra dar conta de volume [#feito-pra-dar-conta-de-volume]
A lista de disputas foi pensada pra escala: **filtros server-side** (status, desfecho, compensação, transportadora, responsável, período), **ações em massa** (atribuir, desatribuir, resolver, reabrir) por checkbox, **clique-direito** e uma **coluna de 3 pontos** — sempre contextuais, mostrando só o que faz sentido. E o botão **Exportar** leva direto pro relatório de Disputas.
## Integre com o seu sistema [#integre-com-o-seu-sistema]
* **Zendesk**: espelhe cada disputa como um ticket — com dossiê traduzido e links —, e o ticket fecha quando você resolve a disputa. Veja o [guia de integração](/docs/log/care/zendesk).
* **Relatórios**: exporte as disputas, ou veja a coluna de disputa direto no relatório de pedidos. Veja [Relatórios](/docs/log/care/relatorios).
* **Webhook**: assine o **`DISPUTE_STATUS_CHANGE`** e receba cada mudança de status em tempo real. Veja a [documentação do webhook](/docs/log/care/webhook).
***
Quer ir a fundo? A documentação completa do Care está em **[Embarcador → Care](/docs/log/care)**.
---
# Login Unificado: um acesso só para LOG e GO (/docs/changelog/2026-06-16-login-unificado-lancamento)
✅ Disponível agora para todas as contas, em portal.abbiamolog.com. Quem já usa os logins com +log, +go ou +hml continua acessando normalmente — a recomendação é migrar pro email único quando der.
## O que é [#o-que-é]
O **Login Unificado** é a nova porta de entrada da Abbiamo. Em vez de manter cadastros separados — um pra LOG, outro pra GO, outro pra homologação — você passa a ter **um único email** e escolhe a operação que quer abrir.
Tudo começa em **portal.abbiamolog.com**. Você entra uma vez, e o portal te leva pra onde precisa ir: LOG, GO, ou os ambientes de homologação, se a sua conta usar.
## O que muda pra você [#o-que-muda-pra-você]
Um email só
Acabou ter que lembrar qual login era pra qual operação. Mesma pessoa, mesmo acesso, mesma senha.
Escolha a operação na hora
Se você usa mais de uma, o portal mostra suas opções. Se usa só uma, vai direto pra dentro.
Troque sem deslogar
Dentro do dashboard, dá pra alternar entre LOG e GO num clique, sem refazer login.
Homologação na cara
Ambientes de homologação ficam claramente marcados — sem chance de confundir com produção.
## Um portal, vários caminhos [#um-portal-vários-caminhos]
Depois de entrar no portal, o que aparece pra você depende do seu acesso:
* **Tem só uma operação?** Você cai direto no dashboard certo.
* **Tem LOG e GO?** O portal mostra os cards das suas operações pra você escolher.
* **Tem ambiente de homologação?** Ele aparece junto dos de produção, marcado pra não confundir.
A escolha fica clara antes de entrar — você decide onde quer trabalhar e segue.
## Trocar de operação sem sair [#trocar-de-operação-sem-sair]
Lá dentro do dashboard, o **switcher no sidebar** faz a troca entre LOG e GO direto. Você não precisa fechar nada, refazer login, nem voltar pro portal. Clica, escolhe, e o dashboard recarrega já no contexto da outra operação.
E como cada operação tem seus próprios dados, o switch deixa tudo limpo — sem risco de uma informação de LOG vazar pra GO, ou vice-versa.
## Gestão de usuários, agora com identidade única [#gestão-de-usuários-agora-com-identidade-única]
Como cada pessoa agora tem um cadastro só, a gestão de quem acessa o quê ficou mais simples:
* **Convide com o email real** da pessoa, sem precisar inventar sufixo.
* **Defina o acesso por operação** — a mesma pessoa pode ser admin numa e usuário comum na outra.
* **Remova quando precisar** sem perder o histórico do que aquela pessoa fez.
E pro time interno da Abbiamo, ficou mais fácil organizar quais operações pertencem à mesma marca, mantendo tudo agrupado no lugar certo.
## E os logins antigos? [#e-os-logins-antigos]
Continuam funcionando. Os emails com `+log`, `+go` e `+hml` seguem ativos — ninguém precisa fazer nada agora pra continuar acessando. A diferença é que, daqui pra frente, **a recomendação é usar o email único pelo portal**: é menos coisa pra lembrar, e é por onde vão chegar todas as melhorias futuras.
Quando der, faça a migração na sua rotina. Em algum momento à frente os logins antigos serão aposentados, mas com aviso e prazo — sem corte de surpresa.
---
# Cancele pedidos em rota sem travar o motorista (/docs/changelog/2026-06-22-cancelamento-pedidos-em-rota)
✅ Disponível agora no fluxo legado de frota própria (LOG + GO): cancelamento pelo dashboard, com reflexo no app do motorista em até \~30 segundos. Vale antes da coleta — depois que o pacote foi coletado, as regras de cancelamento da transportadora continuam valendo.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Antes, cancelar um pedido que já estava na rota do motorista podia **deixar a entrega presa na tela do app** — o motorista via o pedido como se ainda precisasse ser feito e não conseguia seguir o fluxo normalmente.
Agora o cancelamento feito no dashboard **propaga pro app**: o pedido aparece como **cancelado** (visível, mas não acionável) e, quando não sobra nenhum pedido ativo na rota, ela **encerra sozinha** e o motorista volta a ficar disponível.
🛑
Cancelamento no dashboard, de novo
Você cancela o pedido do mesmo jeito de sempre, pelo painel de Pedidos — não precisa de fluxo novo.
📱
App reflete o cancelamento
No app do motorista, o pedido cancelado continua na lista da rota, mas marcado como
cancelado
— não dá pra iniciar coleta nem entrega nele.
🔄
Rota esvazia sozinha
Se todos os pedidos ativos da rota foram cancelados, a rota encerra automaticamente. O motorista não fica numa rota fantasma.
⏱️
Atualização em ~30s
O app sincroniza o estado da rota periodicamente — em geral você vê a mudança em até meio minuto, sem o motorista precisar fazer nada.
## Como funciona — passo a passo [#como-funciona--passo-a-passo]
### 1. Pedido em rota, motorista já atribuído [#1-pedido-em-rota-motorista-já-atribuído]
O pedido já está despachado e o histórico mostra **Entregador Atribuído** — ou seja, o motorista já tem a rota no app, mas ainda **não coletou** o pacote. É nesse cenário que o cancelamento passa a refletir corretamente no app.
*Antes do cancelamento: motorista atribuído, rota ativa no app.*
### 2. Cancele pelo menu de Ações [#2-cancele-pelo-menu-de-ações]
O fluxo é o de sempre: abra **Ações → Cancelar entrega**. Nada muda na operação do dashboard — a diferença é o que acontece depois, quando o pedido já estava na rota.
*Mesma ação de cancelamento que você já usa — agora também funciona com pedido em rota (antes da coleta).*
### 3. Histórico registra o cancelamento [#3-histórico-registra-o-cancelamento]
Depois de confirmar, o histórico do pedido mostra **Marca Cancelou** — com quem solicitou e quem cancelou, como em qualquer outro cancelamento.
*Depois do cancelamento: status e histórico atualizados no dashboard.*
### 4. App do motorista reflete na lista da rota [#4-app-do-motorista-reflete-na-lista-da-rota]
Em **Rota Atual**, o pedido cancelado **permanece visível** (não some). Aparece com texto riscado, indicação **(Cancelado)** e borda vermelha. Os demais pedidos ativos seguem normalmente — o motorista continua a coleta nos que ainda valem.
*Na lista da rota: o cancelado fica marcado; os ativos continuam clicáveis.*
### 5. No mapa, paradas canceladas também aparecem [#5-no-mapa-paradas-canceladas-também-aparecem]
Na visão com mapa, as paradas canceladas aparecem com status **CANCELADO**, nome riscado e ícone de proibido — o motorista enxerga de relance o que ainda precisa fazer e o que já caiu fora.
*No mapa: paradas canceladas diferenciadas das ativas.*
## O que não mudou [#o-que-não-mudou]
* **Como cancelar no dashboard** — mesma tela, mesmas ações; a diferença é o reflexo no app quando o pedido já estava na rota.
* **Recusar oferta** (motorista recusa antes de aceitar a rota) — continua sendo outro fluxo.
* **Cancelar a rota inteira** pelo app do motorista — continua disponível como antes.
## Pra quem importa [#pra-quem-importa]
| Papel | O que ganha |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| **Operador no dashboard** | Pode cancelar pedido em rota sem gerar chamado pro motorista "destravar" manualmente |
| **Motorista no app** | Vê claramente o que foi cancelado e não fica preso numa rota que não tem mais entrega ativa |
| **Operação** | Menos rota travada, menos intervenção manual, histórico da rota preservado |
***
---
# Busca de pedidos: pesquise vários de uma vez e selecione em lote (/docs/changelog/2026-06-25-busca-multipla-pedidos)
✅ Disponível agora em Pedidos → campo Pesquisar pedido, no topo da lista.
## A novidade em uma frase [#a-novidade-em-uma-frase]
A busca de Pedidos deixou de ser **um pedido por vez**: agora você pesquisa **vários de uma vez**, vê todos juntos na tabela e age em lote — e ainda copia os dados dos pedidos (até no formato do relatório) pra reusar onde quiser.
## O que mudou [#o-que-mudou]
🔎
Pesquisar vários pedidos
Cole vários números de pedido separados por
|
ou
,
. Aparece no topo da busca a opção
"Visualizar todos os N pedidos"
— que filtra a tabela por todos eles de uma vez.
📋
Colar do Excel
Copiou uma coluna de números no Excel/Sheets? Cole direto no campo de busca: a quebra de linha vira separador automaticamente. Sem precisar formatar nada.
📦
Abrir um pedido específico
Escolher um pedido na busca além de filtrar já
abre o painel de detalhes
dele, lado a lado com a lista.
⧉
Copiar dados
Na seleção
ou no botão direito
da linha, o menu
"Copiar dados"
copia
número, ID, ID externo ou NF
— um por linha, pronto pra colar numa coluna do Excel ou de volta na busca. E
"Linha (planilha)"
copia tudo no formato do relatório (em português ou inglês) pra colar como tabela.
⇧
Selecionar em intervalo
Marque um checkbox e, segurando
Shift
, marque outro: todas as linhas entre os dois são selecionadas de uma vez.
## Como funciona [#como-funciona]
### Pesquisar vários pedidos de uma vez [#pesquisar-vários-pedidos-de-uma-vez]
1. Na tela de **Pedidos**, no campo **Pesquisar pedido**, cole os valores separados por **|** ou **,** — por exemplo: `PEDIDO-1 | PEDIDO-2 | PEDIDO-3`. Pode colar número do pedido, ID, ID externo ou NF — a busca resolve cada um pro pedido certo.
2. No topo da lista aparece **"Visualizar todos os N pedidos"**. Clique (ou aperte **Enter**).
3. A tabela passa a mostrar **todos os pedidos encontrados**, e o período se ajusta automaticamente pra que eles apareçam.
### Abrir um pedido específico [#abrir-um-pedido-específico]
Se você escolher **um** pedido na busca (em vez de "Visualizar todos"), além de filtrar a tabela o **painel de detalhes** daquele pedido já abre lado a lado. No menu **Ações** do painel, o **"Copiar dados"** também exporta o pedido em **JSON** — no formato de criar pedido pela API ou no formato completo (pedido + eventos) — pra reaproveitar numa integração.
### Selecionar e copiar em lote [#selecionar-e-copiar-em-lote]
* **Shift+clique** nos checkboxes seleciona um **intervalo** de linhas: marque a primeira, segure **Shift** e marque a última.
* Com pedidos selecionados — ou no **botão direito** numa linha — use **"Copiar dados"**:
* **Número, ID, ID externo ou NF**: copia um por linha — cola direto numa coluna do Excel, e a busca também aceita essa lista de volta.
* **Linha (planilha)**: copia as linhas no **mesmo formato do relatório** (as mesmas colunas e cabeçalhos do "Exportar tela atual"), em **português ou inglês** — cola como tabela no Excel/Sheets.
* Se algum pedido selecionado não tiver NF ou ID externo, a opção mostra um aviso; se nenhum tiver aquele dado, ela fica desabilitada.
***
---
# Solicitar coleta em massa: selecione vários pedidos e peça a coleta de uma vez (/docs/changelog/2026-06-25-solicitar-coleta-em-massa)
✅ Disponível agora em Pedidos → selecione pedidos e clique em Solicitar coleta na barra de seleção.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Antes você pedia coleta de **um pedido por vez**. Agora dá pra **selecionar vários pedidos e solicitar a coleta de todos de uma vez** — cotando as transportadoras na hora e escolhendo uma **transportadora em comum** pra todos.
## O que mudou [#o-que-mudou]
🚚
Coleta em massa
Marque os pedidos na tabela e clique em
"Solicitar coleta"
na barra de seleção. Abre um modal com todos eles prontos pra coleta — sem precisar abrir um por um.
🏷️
Uma transportadora pra todos
Em
Ações Rápidas
, escolha uma transportadora e ela é aplicada a
todos os pedidos de uma vez
. Dá pra ajustar o frete de um pedido específico depois, se precisar.
🏬
Agrupado por filial
Selecionou pedidos de filiais diferentes? Eles são agrupados por filial — uma cotação e uma coleta por filial. O modal mostra
"Filial X de N"
e avança pra próxima sozinho a cada coleta solicitada.
💰
Cotação na hora
As transportadoras disponíveis aparecem já com o
preço do frete
de cada uma, somando os pedidos da filial — você compara e escolhe antes de solicitar.
## Como funciona [#como-funciona]
1. Na tela de **Pedidos**, marque os checkboxes dos pedidos que quer coletar.
2. Na barra de seleção que aparece embaixo, clique em **Solicitar coleta**.
*Marque os pedidos e use **Solicitar coleta** na barra de seleção em massa.*
3. No modal, escolha a transportadora. Em **Ações Rápidas** → "Selecione todos os pedidos para", a transportadora escolhida é aplicada a todos de uma vez.
*As transportadoras disponíveis aparecem com o preço — escolha uma pra aplicar a todos os pedidos da filial.*
4. Confira e clique em **Solicitar coleta** no rodapé do modal. Pronto — a coleta é solicitada pra todos os pedidos daquela filial de uma vez.
## Onde ver na doc [#onde-ver-na-doc]
* [**Pedidos — Como usar**](/docs/log/products/pedidos/como-usar/): o passo a passo da tela de Pedidos, incluindo a solicitação de coleta a partir da seleção.
***
---
# Associe marcadores ao criar um pedido via API (/docs/changelog/2026-07-02-marcadores-criacao-pedido-api)
✅ No ar em produção.
## O que mudou [#o-que-mudou]
Antes, se você queria aplicar um marcador a um pedido criado via integração, precisava fazer isso depois — em um passo separado, manual ou via outra chamada.
Agora dá pra passar os marcadores diretamente na criação do pedido. O pedido já chega no dashboard com os marcadores aplicados, sem nenhuma etapa a mais.
## Quando faz diferença [#quando-faz-diferença]
Se a sua integração já sabe, no momento do envio, como aquele pedido deve ser classificado — por tipo de produto, canal de venda, prioridade, origem — você pode mandar essa informação junto. O marcador aparece no dashboard na hora, sem depender de ninguém aplicar depois.
## Como funciona [#como-funciona]
No payload de criação do pedido, inclua o campo `tag_ids` com os IDs dos marcadores que devem ser aplicados:
```json
{
"seller_identifier": "minha-loja-01",
"orders": [
{
"external_id": "PED-9999",
"tag_ids": [
"a1b2c3d4-0000-0000-0000-111111111111"
]
}
]
}
```
Para saber os IDs dos marcadores cadastrados na sua marca, use o endpoint de listagem antes de integrar. O campo `tag_ids` é opcional — pedidos sem marcador continuam funcionando normalmente.
> 📖 Veja os detalhes técnicos, exemplos e campos disponíveis na documentação: [Criar pedido](/docs/api/orders/create-order-v2) e [Listar marcadores](/docs/api/tags/list-tags).
***
---
# Escolha as colunas do seu relatório (/docs/changelog/2026-07-06-colunas-do-relatorio)
✅ Disponível em Relatórios → Novo relatório. Não muda nada do que já funciona: sem tocar no seletor, o relatório continua vindo com todas as colunas.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Agora **você decide quais colunas** o relatório vai conter. No modal de **Novo relatório**, o novo campo **Colunas** deixa montar um export enxuto — só com os campos que interessam — em vez de receber sempre as dezenas de colunas padrão.
## Como funciona [#como-funciona]
✅
Só o que você precisa
Marque as colunas que quer no relatório. Os atalhos
Todos
e
Limpar
ajudam a partir de tudo ou do zero. Deixou tudo marcado? O relatório sai igualzinho a antes.
🔎
Busca rápida
Os relatórios de pedidos têm dezenas de colunas. Digite pra achar na hora — pelo nome técnico (o que sai no cabeçalho do arquivo) ou pela descrição do campo.
🌐
No idioma do relatório
Escolha o idioma primeiro: as colunas já aparecem com as chaves e descrições em português ou inglês — exatamente como vão sair no arquivo.
💾
Lembra a sua seleção
A última escolha fica guardada por tipo de relatório e idioma. Na próxima vez, o seletor já abre do jeitinho que você deixou.
## Ache qualquer campo pela busca [#ache-qualquer-campo-pela-busca]
Não precisa rolar uma lista enorme atrás de uma coluna. Abra o seletor, digite parte do nome — como `tracking`, `nota` ou `transportadora` — e marque só o que interessa. Cada item mostra o **nome técnico** que vai no cabeçalho do arquivo e uma **descrição** do que aquele campo significa.
## Por que isso importa [#por-que-isso-importa]
* **Arquivos mais leves**: menos colunas, CSV/JSON menor e mais rápido de abrir no Excel ou de processar numa integração.
* **Foco no que interessa**: monte um relatório de conferência com 5 colunas ou um completo com todas — do seu jeito, sem campos sobrando.
* **Consistente com o resto**: o seletor usa os mesmos componentes do novo visual de Relatórios — busca, atalhos **Todos** / **Limpar** e o **"Apenas"** no hover que você já conhece de Pedidos.
Dica: quer conferir o que cada coluna significa antes de montar o export? O Dicionário (botão no topo da tela de Relatórios) lista todas as colunas de cada tipo de relatório, com a descrição de cada campo.
---
# Relatórios de cara nova — a renovação de design da Abbiamo avança (/docs/changelog/2026-07-06-relatorios-novo-visual)
✅ Disponível agora em Relatórios. Tudo funciona como antes — o que mudou é a experiência.
## A novidade em uma frase [#a-novidade-em-uma-frase]
A tela de **Relatórios** é a primeira do dia a dia da operação a ganhar o **novo design da Abbiamo** — a linguagem visual que estreou no Care: mais limpa, mais rápida de ler e de filtrar. E vem mais: essa renovação vai se estender ao restante do dashboard nas próximas semanas.
## O que mudou [#o-que-mudou]
🎨
Visual novo, do nosso jeito
Tipografia nova, bordas finas, cores com significado: cada
tipo
e
status
de relatório tem seu badge — verde pra completo, âmbar na fila, vermelho quando falha. Bater o olho já diz o que está acontecendo.
⚡
Filtros mais rápidos
Tipo, formato e status agora são seletores múltiplos compactos, com busca e os atalhos
Limpar
/
Todos
— e o "Apenas" no hover que você já conhece da tela de Pedidos.
📖
Dicionário reorganizado
O dicionário de dados dos relatórios ganhou
abas laterais
— escolha o relatório à esquerda e veja as colunas à direita, com o nome técnico de cada campo destacado. Rolagem leve mesmo nos relatórios com dezenas de colunas.
🗓️
Novo relatório com layout repensado
O modal de gerar relatório ficou mais direto: calendário novo, filtros de transportadora e status mais claros, e avisos de fuso horário que não passam despercebidos. O período dinâmico funciona exatamente como antes.
## Filtros mais diretos [#filtros-mais-diretos]
Tipo, formato e status viraram seletores múltiplos compactos, com badges coloridos nas opções e os atalhos **Limpar** / **Todos** no rodapé. Os padrões que você já usa em Pedidos — como o **"Apenas"** no hover — continuam funcionando do mesmo jeito aqui.
## Gerar relatório, sem fricção [#gerar-relatório-sem-fricção]
O formulário de novo relatório mantém tudo que você já usa — tipo, formato, período, filiais, transportadoras, status e idioma — num layout mais respirado. O período dinâmico, lançado em junho, continua funcionando do mesmo jeito (um relatório de "últimos 7 dias" sempre pega os últimos 7 dias); o que mudou é a apresentação — e a data absoluta agora abre num calendário novo de dois meses.
## Dicionário de dados em abas [#dicionário-de-dados-em-abas]
Precisa saber exatamente o que significa cada coluna do CSV? O **Dicionário** (botão no topo da tela) agora lista os relatórios em abas verticais e mostra as colunas do relatório selecionado ao lado — nome técnico à esquerda, descrição à direita.
## Por que isso importa (e o que vem por aí) [#por-que-isso-importa-e-o-que-vem-por-aí]
Esse redesign não é um retoque isolado: estamos construindo um **design system próprio da Abbiamo** — componentes, cores e tipografia unificados. Ele estreou no **Care** e agora chega à primeira tela do dia a dia da operação, usada de ponta a ponta. Na prática, isso significa:
* **Consistência**: os mesmos botões, filtros, tabelas e modais em todas as telas, se comportando sempre do mesmo jeito.
* **Velocidade**: componentes mais leves e telas que respondem mais rápido.
* **Evolução contínua**: com a base pronta, novas telas e melhorias chegam com muito mais frequência.
As demais telas do dashboard vão sendo renovadas gradualmente — sem mudar onde as coisas ficam nem como funcionam, só deixando tudo mais claro e agradável de usar. Feedback é muito bem-vindo: se algo parecer estranho na nova tela, fale com a gente pelo suporte — ou pelo feedback aqui do Abbiamo Docs.
---
# Código de rastreio dos Correios na página de acompanhamento do cliente (/docs/changelog/2026-07-14-codigo-rastreio-correios)
✅ Disponível agora na página de rastreio — a que o seu cliente abre. Vale para todas as contas, sem nada pra ativar ou configurar.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Envio feito pelos **Correios** agora mostra o **código do objeto** na própria página de acompanhamento — o destinatário não precisa mais pedir esse código pra você.
## O que mudou [#o-que-mudou]
Antes
O código existia, mas não chegava
O código do objeto já era gerado na pré-postagem e ficava guardado do nosso lado. Pro cliente que quisesse conferir no site dos Correios, sobrava perguntar pro seu atendimento.
Agora
Aparece pra quem está esperando
O código vai junto com o status, na própria página de rastreio. Quem quiser acompanhar também pelos Correios já tem o que precisa na tela.
## Onde aparece [#onde-aparece]
📮
Ao lado do status
Uma
pílula cinza
na mesma linha do selo de status (
Saiu para entrega
, por exemplo), logo acima da barra de progresso.
↔️
Na entrega e na reversa
Vale nos dois fluxos da página: no acompanhamento da
entrega
e no da
logística reversa
. Retirada (Clique e Retire) não tem código de objeto e segue sem a pílula.
🔓
Sem ativar nada
Não é opcional nem depende de configuração por marca: todo envio Correios com código passou a exibi-lo automaticamente, em todas as contas.
📦
O mesmo código dos Correios
É o código do objeto gerado na
pré-postagem
— o mesmo que se cola no site dos Correios pra ver a movimentação por lá.
*a pílula fica à direita, na mesma linha do selo de status — logo acima da barra de progresso. (código ilustrativo)*
Na prática, praticamente todo envio pelos Correios já nascia com esse código gravado: o dado existia, só não chegava a quem estava esperando o pacote.
## Por enquanto, só Correios [#por-enquanto-só-correios]
Outras transportadoras também registram um código próprio, mas a página exibe **apenas o dos Correios** — que é o único com um site público de consulta onde o código, sozinho, serve pra alguma coisa. Se isso mudar pra outras transportadoras, a pílula acompanha.
## O que não mudou [#o-que-não-mudou]
O resto da página de rastreio segue idêntico: mesmos status, mesma linha do tempo, mesma barra de progresso, mesma personalização de marca. O código é **informação a mais** ao lado do status — nada foi removido nem reorganizado. O link de rastreio que você envia pro cliente também continua o mesmo.
## Onde ver na doc [#onde-ver-na-doc]
* [**Rastreamento**](/docs/tracking/): a página de acompanhamento que o destinatário vê.
***
---
# Seus chamados de suporte, agora dentro do dashboard (/docs/changelog/2026-07-14-tickets-suporte)
✅ Disponível agora para todas as marcas — a tela de Tickets de Suporte já está no ar, na seção Suporte do menu.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Todo chamado que a sua marca abre com a Abbiamo — seja por e-mail pro suporte, seja pela plataforma — agora fica reunido numa **tela de acompanhamento** dentro do próprio dashboard, com a conversa completa a um clique.
## O que mudou [#o-que-mudou]
📥
Tudo num lugar só
Chamados abertos por
e-mail
ou pela
plataforma
aparecem na mesma lista. Não precisa mais caçar no e-mail o que foi que você pediu — está tudo aqui, com o número, o assunto e o status atual.
🔎
Fácil de encontrar
Busca por texto, filtro por
categoria
e por
quem abriu
o chamado, além de ordenar por qualquer coluna. As abas separam
todos os chamados da marca
dos
seus
.
💬
A conversa inteira
Clique num chamado e veja a
troca de mensagens
com o suporte, com formatação,
imagens com zoom
, vídeos e
arquivos pra baixar
— exatamente como no e-mail, só que mais organizado.
✏️
Abra um chamado dali mesmo
O botão
Novo ticket
abre um formulário rápido pra descrever o problema, escolher a categoria e anexar o que precisar — sem trocar de aba nem abrir o e-mail.
## Acompanhe cada chamado [#acompanhe-cada-chamado]
A lista mostra, de bate-pronto, o **número**, o **assunto** (com a categoria logo abaixo), **quem abriu**, o **status** traduzido e as datas de abertura e última atualização. Por padrão os mais recentes vêm primeiro, mas você pode ordenar por qualquer coluna — é só clicar no cabeçalho.
Os status são os mesmos que o time usa internamente, traduzidos pra ficar claro de relance: **Na fila**, **Em andamento**, **Resolvido**.
## A conversa, a um clique [#a-conversa-a-um-clique]
Clicar num chamado abre a **conversa com o suporte** — a mesma troca que acontece por e-mail, aqui apresentada em balões, com a formatação preservada. Imagens abrem em tela cheia com um clique, vídeos tocam ali mesmo e arquivos (planilhas, PDFs) ficam prontos pra baixar.
## Precisa abrir um novo? É dali mesmo [#precisa-abrir-um-novo-é-dali-mesmo]
O botão **Novo ticket** abre um formulário direto: descreva o que aconteceu, escolha a categoria e, se ajudar, anexe imagens ou arquivos. O chamado entra na fila do suporte e passa a aparecer na sua lista.
## Por que isso importa [#por-que-isso-importa]
Acompanhar um chamado por e-mail é fácil de perder o fio: a thread some no meio da caixa de entrada, e saber "em que pé está" vira uma garimpagem. Trazer isso pro dashboard significa **visibilidade** — você vê, a qualquer momento, tudo que abriu com a gente e o status de cada coisa — no **mesmo design** que já está chegando às outras telas (como você viu em Relatórios).
A tela **já está disponível para todas as marcas** — é só abrir a seção **Suporte** no menu e começar a usar. Feedback é muito bem-vindo pelo próprio suporte ou aqui pelo Abbiamo Docs.
---
# Cancelar envio em massa: selecione vários pedidos e cancele de uma vez (/docs/changelog/2026-07-20-cancelar-envio-em-massa)
✅ Disponível agora em Pedidos → selecione pedidos e clique em Cancelar envio na barra de seleção.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Antes você cancelava **um pedido por vez** pelo painel lateral. Agora dá pra **selecionar vários pedidos e cancelar o envio de todos de uma vez** — e antes de confirmar você vê **exatamente o que vai ser cancelado** e **o que fica de fora**.
## O que mudou [#o-que-mudou]
🗂️
Cancelamento em massa
Marque os pedidos na tabela e clique em
"Cancelar envio"
na barra de seleção. Um só clique para todos — sem abrir pedido por pedido no painel lateral.
🔎
Você vê antes de confirmar
O resumo mostra
exatamente o que será cancelado
, agrupado por tipo — cancelar envio, cancelar agendamento e cancelar oferta. Nada é cancelado sem você conferir.
⚠️
Filtra e avisa
Selecionou algum pedido que não dá pra cancelar? Ele fica
de fora automaticamente
, com o
motivo
ao lado (já finalizado, entrega encerrada, status não permite…). Você não precisa separar na mão.
⏳
Acompanha um a um
Ao confirmar, cada cancelamento roda em paralelo com uma
barra de progresso
e o status de cada pedido — e no fim um aviso do que deu certo e do que falhou.
## Como funciona [#como-funciona]
1. Na tela de **Pedidos**, marque os checkboxes dos pedidos que quer cancelar.
2. Na barra de seleção que aparece embaixo, clique em **Cancelar envio**.
*Marque os pedidos e use **Cancelar envio** na barra de seleção em massa.*
3. No resumo, confira **o que será cancelado** (agrupado por tipo) e **o que fica de fora**. Clique em **Cancelar envio** para confirmar.
*O resumo mostra a quebra por tipo e, quando houver, os pedidos que ficam de fora com o motivo.*
4. Pronto — cada pedido é cancelado e a barra mostra o andamento. No fim, um aviso confirma quantos foram cancelados e se algum falhou.
## Onde ver na doc [#onde-ver-na-doc]
* [**Pedidos — Como usar**](/docs/log/products/pedidos/como-usar/): o passo a passo da tela de Pedidos, incluindo o cancelamento a partir da seleção.
***
## A novidade em uma frase [#a-novidade-em-uma-frase]
Antes, a automação de inatividade cancelava o pedido depois de **um tempo único**, valendo pra qualquer status. Agora dá pra definir **um tempo diferente para cada status** — e o pedido é cancelado e reenviado assim que estoura o tempo daquele status.
## O que mudou [#o-que-mudou]
⏱️
Tempo por status
Em vez de um prazo só pra tudo, você define quanto tempo o pedido pode ficar parado em
cada
status antes de agir.
🔗
Etapas encadeadas
As esperas são avaliadas em ordem. Se o pedido anda de um status para o outro, a contagem
recomeça
no status novo.
🔄
Cancela e reenvia
Estourou o tempo daquele status? O pedido é
cancelado
na transportadora e
reenviado
para o método que você escolher.
Antes
Um tempo só pra tudo
Um único tempo de inatividade valia para todos os status. Um pedido "Pendente" e um pedido "Despachado" esperavam exatamente o mesmo tanto.
Agora
Um tempo pra cada status
Cada status tem o seu prazo. "Pendente" pode esperar 1 hora, "Despachado" 30 minutos — do jeito que faz sentido pra sua operação.
## Escolhendo a modalidade [#escolhendo-a-modalidade]
Ao criar ou editar a automação, você escolhe entre duas modalidades de espera:
* **Tempo único de inatividade** — *Cancela o pedido quando ele ficar parado pelo tempo definido em qualquer um dos status selecionados.* É o comportamento de sempre.
* **Espera por status (encadeada)** — *Defina um tempo de espera diferente para cada status. Se o pedido ficar parado no status pelo tempo definido, ele é cancelado e reenviado.*
*Escolha entre um tempo único para todos os status ou um tempo diferente por status.*
## Montando as etapas [#montando-as-etapas]
Na modalidade **Espera por status**, você monta as **Etapas de espera** — uma por status. Para cada etapa, se o pedido permanecer naquele status pelo tempo definido, a ação é executada.
Um exemplo prático:
1. **Despachado · Buscando motorista** — espera **10 min**. Se não achar entregador nesse tempo, cancela e reenvia.
2. **Em trânsito · Coletando** — espera **15 min**.
3. **Em trânsito · No local de coleta** — espera **5 min**.
Cada status tem o seu tempo, **independente dos outros** — não precisa ser crescente nem seguir a ordem da viagem. Use **Adicionar etapa** para incluir quantos status precisar.
*Cada etapa é um status com o seu próprio tempo de espera.*
## Duplicar uma automação [#duplicar-uma-automação]
Para reaproveitar uma regra bem ajustada em outra filial, agora tem **Duplicar automação** no menu de cada regra. Ele abre uma cópia já preenchida — é só ajustar o que mudar e salvar.
## O que não mudou [#o-que-não-mudou]
Quem já usa o **tempo único de inatividade** continua exatamente igual — nada muda nas regras existentes. A espera por status é uma opção a mais, para quando você quer tratar cada status com um prazo próprio.
***
---
# Origem do envio: veja qual automação criou cada entrega (/docs/changelog/2026-07-22-origem-do-envio)
✅ Disponível agora em Pedidos → clique num pedido para abrir o painel lateral → seção Histórico.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Quando uma entrega nasce de uma **automação**, o painel lateral do pedido agora diz **qual automação foi** — e o nome da regra vira um **link direto** pra ela.
## O que mudou [#o-que-mudou]
⚡
De onde veio esse envio
Cada entrega no histórico do pedido ganha a marca
Origem do envio
:
Automação de envio
,
Automação de reenvio
ou
Automação de inatividade
.
🏷️
Com o nome da regra
Não é só o tipo: aparece
o nome da automação
que disparou. Em conta com dezenas de regras, é a diferença entre "foi um reenvio" e "foi
aquela
regra".
🔗
Um clique abre a regra
Clicar leva direto pra tela da automação correspondente,
já filtrada naquela regra
— sem procurar na lista.
🔍
Entender o reenvio ficou direto
Pedido que falhou e foi reenviado sozinho agora conta a própria história: qual regra pegou, e qual automação gerou cada tentativa.
## Como funciona [#como-funciona]
1. Na tela de **Pedidos**, clique num pedido para abrir o **painel lateral**.
2. Vá até a seção **Histórico** e expanda a entrega que você quer investigar.
3. No topo do bloco da entrega aparece a marca de **Origem do envio** com o tipo da automação e o nome da regra.
*A marca aparece no bloco da entrega, logo abaixo do status — com o tipo da automação e o nome da regra.*
4. Clique nela: a tela da automação abre **já filtrada naquela regra**.
*O clique leva direto pra automação correspondente, sem procurar na lista.*
## O que não mudou [#o-que-não-mudou]
O histórico do pedido continua igual no resto: mesmos eventos, mesma ordem, mesmas ações. A origem é **informação a mais** em cada entrega — nada foi removido nem reorganizado. As automações também continuam funcionando exatamente como antes; a mudança é só passar a **mostrar** o que já acontecia nos bastidores.
## Onde ver na doc [#onde-ver-na-doc]
* [**Pedidos — Como usar**](/docs/log/products/pedidos/como-usar/): o painel lateral do pedido e a seção de histórico.
* [**Regras de envio**](/docs/log/products/regras-de-envio/), [**Regras de reenvio**](/docs/log/products/regras-de-reenvio/) e [**Regras de inatividade**](/docs/log/products/regras-de-inatividade/): as automações que podem originar um envio.
***
---
# Veja onde cada atualização do pedido aconteceu, no mapa e no histórico (/docs/changelog/2026-07-23-coordenadas-eventos-pedido)
✅ Disponível agora em Pedidos. Vale automaticamente para qualquer evento de entrega que tenha coordenada — não precisa configurar nada.
## A novidade em uma frase [#a-novidade-em-uma-frase]
O mapa do trajeto que já vive no painel do pedido agora mostra **onde cada atualização de status aconteceu** — e o histórico ganhou o **Local** com a coordenada de cada evento.
*Cada ponto é um evento de entrega, na cor do seu status, com o número e o rótulo do status sempre à vista. A legenda embaixo do mapa mostra o que cada cor significa.*
## O que mudou [#o-que-mudou]
📍
Pontos no mapa
Todo evento com localização vira um
ponto numerado
no mapa, na cor do seu status. O número é o mesmo que aparece no histórico — dá pra cruzar os dois de relance.
🗒️
"Local" no histórico
Na linha do tempo do pedido, cada evento agora mostra a
coordenada
onde foi registrado, logo abaixo do status. Clique pra
copiar
, abrir no
Google Maps
ou pular direto pro ponto no mapa.
👆
Status sempre à vista
Cada ponto já mostra o
status
ao lado do número, sem precisar clicar. Passar o mouse num ponto (ou numa linha do histórico)
destaca
o par correspondente no outro lugar.
🎯
Pontos no mesmo lugar se agrupam
Quando vários eventos acontecem no mesmo ponto (várias tentativas no mesmo endereço, por exemplo), eles viram um
+N
com a contagem. Um clique
expande
e mostra todos empilhados, ali no ponto.
## Como usar [#como-usar]
No **sidepanel do pedido** (o painel lateral que abre ao clicar num pedido), role até o **mapa do trajeto** e o **histórico**:
* **No mapa**, cada ponto já traz o **status** ao lado do número. Pontos no mesmo lugar viram um **+N** — clique pra expandir e ver todos empilhados. A **legenda** logo abaixo do mapa lista as cores dos status presentes.
* **No histórico**, o **Local** de cada evento traz a coordenada (logo abaixo do status). Clique nele pra **copiar**, abrir no **Google Maps** ou usar **Ver no mapa** — que leva a visão direto pro ponto, útil quando o pedido tem muitos eventos.
* Passar o mouse numa linha do histórico **destaca** o ponto correspondente no mapa, e vice-versa.
* Precisa de mais espaço? O mapa agora tem um botão de **tela cheia** (no canto superior direito) pra abrir o trajeto em tela inteira.
*Vários eventos no mesmo lugar viram um +N; o clique expande e mostra todos empilhados ali.*
*Clicar no Local de um evento abre a coordenada com **Ver no mapa**, **Copiar** e **Google Maps**.*
## Pra que serve [#pra-que-serve]
Saber **onde** cada etapa aconteceu ajuda a entender o pedido sem sair do painel:
* **Conferir uma entrega** — o mapa mostra a **distância** entre o ponto de "Entregue" e o endereço do cliente (ex.: *"Entregue a 53 m do endereço do cliente"*).
* **Investigar uma falha** — onde o motorista registrou a tentativa que não deu certo?
* **Apurar uma disputa** — a localização de cada evento vira evidência concreta, a um clique.
## Quando um evento não aparece no mapa [#quando-um-evento-não-aparece-no-mapa]
* **Eventos sem coordenada** — atualizações antigas ou de integrações que não enviam localização não têm ponto no mapa (nem o Local no histórico). O restante do histórico continua igual.
* **Pedidos sem o mapa** — como o mapa depende de origem e destino geolocalizados (e não vale pra retiradas), pedidos nessas condições não mostram os pontos. O **Local** no histórico, esse aparece de qualquer forma.
## O que não mudou [#o-que-não-mudou]
* Permissões: quem já via o pedido e o mapa continua vendo tudo, sem nada novo pra configurar.
* O mapa, a rota estimada e a distância dirigida seguem exatamente como antes — os pontos dos eventos são um acréscimo por cima deles.
***
## A novidade em uma frase [#a-novidade-em-uma-frase]
Os Pedidos agora mostram uma coluna **Situação de entrega** pelo prazo do cliente — e você pode configurar **marcadores de risco** que a própria plataforma aplica quando um pedido está perto de atrasar, sem você ficar de olho.
## O que mudou [#o-que-mudou]
🚦
Coluna Situação de entrega
Cada pedido mostra se está
No prazo
,
Atrasado
ou
Sem info
, medido pelo prazo prometido ao cliente. Passe o mouse para ver o prazo e quanto falta.
🏷️
Marcadores de risco
Você cria estados de risco próprios — um
nome
e uma
cor
, tipo "Risco de Entrega Grave". Eles aparecem na coluna, no lugar do "No prazo".
⚙️
Regras automáticas
Diga
quando
cada marcador acende: para pedidos com um marcador específico, a quantos minutos do prazo. A plataforma marca sozinha.
## A coluna Situação de entrega [#a-coluna-situação-de-entrega]
Na lista de **Pedidos**, a coluna **Situação de entrega** classifica cada pedido pelo **prazo prometido ao cliente**:
* **No prazo** — ainda dentro do prazo (ou entregue dentro dele).
* **Atrasado** — o prazo do cliente já passou (ou foi entregue depois dele).
* **Sem info** — sem prazo de cliente, retirada em loja, ou cancelado.
Passando o mouse sobre a situação, você vê **quando o cliente espera receber** e **quanto falta** (ou há quanto tempo estourou) — o mesmo texto do painel lateral do pedido.
*A coluna mostra a situação de cada pedido — e o marcador de risco quando ele acende.*
## Marcadores de risco de entrega [#marcadores-de-risco-de-entrega]
Em **Configuração → Marcadores de risco de entrega**, você cria os estados de risco da sua operação. Cada marcador é só um **nome** e uma **cor** — por exemplo, um "Risco de Entrega Grave" em vermelho. Eles são reutilizáveis: o mesmo marcador serve para várias regras.
*Cada marcador é um nome e uma cor, reutilizável por várias regras.*
## Regras: quando o marcador acende [#regras-quando-o-marcador-acende]
Depois de criar o marcador, você monta as **regras** que decidem quando ele é aplicado. Cada regra liga três coisas:
1. **Marcador do pedido** — a quais pedidos a regra vale (ex.: os com o marcador `turbo60`).
2. **Antecedência** — a quantos minutos do prazo do cliente o pedido entra em risco.
3. **Marcador de risco** — qual estado acende (ex.: "Risco de Entrega Grave").
Um exemplo prático, com o mesmo marcador de risco em duas regras:
1. Pedidos **turbo60** — quando faltar **30 min** para o prazo → **Risco de Entrega Grave**.
2. Pedidos **turbo120** — quando faltar **60 min** para o prazo → **Risco de Entrega Grave**.
Quando um pedido em trânsito cruza esse limite e ainda não foi entregue, a plataforma **aplica o marcador sozinha** — e ele aparece na coluna Situação de entrega e no painel do pedido, na cor que você escolheu.
*A regra se lê como uma frase: para este marcador do pedido, a esta antecedência, acende este marcador de risco.*
## No painel do pedido [#no-painel-do-pedido]
Ao abrir um pedido em risco, o painel lateral também reflete o estado: em vez de "dentro do prazo", ele mostra o **marcador de risco** com o nome e a cor que você configurou, junto do prazo do cliente.
*O painel do pedido mostra o mesmo estado de risco, com o prazo do cliente e quanto falta.*
## Filtrar por situação [#filtrar-por-situação]
No **Mais filtros → Situação de entrega**, além de Atrasado / No prazo / Sem info, entram também os seus marcadores de risco — dá para listar só os pedidos que estão num estado de risco específico.
***
---
# O rastreio do pedido agora abre dentro do painel, numa aba (/docs/changelog/2026-07-24-rastreio-no-painel-do-pedido)
✅ Disponível agora em Pedidos → clique num pedido para abrir o painel lateral → aba Rastreio.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Pra ver o que o seu cliente está vendo sobre a entrega, você não precisa mais abrir outra aba do navegador: o **rastreio do destinatário** agora vive dentro do próprio painel do pedido.
## O que mudou [#o-que-mudou]
📑
Duas abas no painel
O painel do pedido agora tem
Detalhes
e
Rastreio
. A aba Detalhes é tudo o que já existia — mesmas seções, mesma ordem, nada saiu do lugar.
🛰️
A página do cliente, embutida
A aba Rastreio carrega
a mesma página pública
que o destinatário acompanha — não é uma versão resumida nem um espelho: é ela mesma, dentro do painel.
🔗
O link pronto pra enviar
No topo da aba fica o endereço do rastreio, com um botão de
copiar
ao lado — pra colar direto na conversa com o cliente. Clicando nele, a página abre em tela cheia.
↔️
Sem perder o contexto
Como o painel abre
ao lado da lista
, dá pra conferir o rastreio de um pedido e pular pro próximo sem fechar nada.
## Como funciona [#como-funciona]
1. Na tela de **Pedidos**, clique num pedido para abrir o **painel lateral**.
2. No topo do painel, ao lado do botão **Ações**, aparecem as duas abas.
*As abas ficam na mesma linha das ações do pedido — a de Detalhes é a que abre por padrão.*
3. Clique em **Rastreio**: a página de acompanhamento do cliente carrega ali dentro, com o link copiável logo acima.
*O que aparece aqui é exatamente o que o destinatário vê ao abrir o link de rastreio.*
## O que não mudou [#o-que-não-mudou]
O link de rastreio é **o mesmo de sempre** — a mesma URL que a ação *Rastreio* do pedido já entregava, e a mesma que o seu cliente recebe nas notificações. A aba não cria um link novo nem um segundo endereço: só traz pra dentro do painel o que antes obrigava a sair dele. A aba **Detalhes** também segue idêntica — nenhuma seção foi removida ou reordenada.
## Onde ver na doc [#onde-ver-na-doc]
* [**Pedidos — Como usar**](/docs/log/products/pedidos/como-usar/): o painel lateral do pedido e suas seções.
* [**Rastreamento**](/docs/tracking/): a página de acompanhamento que o destinatário vê.
***
## A novidade em uma frase [#a-novidade-em-uma-frase]
Quando um pedido atrasa, a Abbiamo agora faz um `POST` no seu endpoint — vale para **qualquer pedido com prazo de cliente**, sem configuração nenhuma.
## O que mudou [#o-que-mudou]
Antes
Só dava pra ver na tela
O atraso aparecia na coluna
Situação de entrega
. Para reagir no seu sistema, era preciso alguém olhando a lista de Pedidos — ou uma varredura periódica na API atrás de pedidos perto do prazo.
Agora
Chega no seu servidor
O evento
ORDER_DELAY
bate no seu endpoint no minuto exato. Seu sistema abre o alerta, o ticket ou a mensagem no canal do time — sem polling.
## Dois gatilhos, um evento [#dois-gatilhos-um-evento]
O campo `trigger` diz por que o evento chegou:
🔴
DELAYED
O prazo prometido ao cliente
estourou
e o pedido não foi concluído. Vale para todo pedido com prazo —
não precisa configurar nada
.
🟡
RISK_MARKER
Uma
regra de risco
sua acendeu um marcador
antes
do prazo. Vem com o nome e a cor do marcador que você configurou.
Um mesmo pedido pode gerar os dois: primeiro o aviso preventivo, depois o atraso consumado.
## O payload [#o-payload]
```json
{
"event_type": "ORDER_DELAY",
"trigger": "DELAYED",
"order_id": "3f9a1c22-0000-0000-0000-000000000000",
"order_number": "1042",
"external_order_id": "PED-98213",
"tracking": "AB12CD34EF",
"status": "START_DELIVERY",
"promised_delivery_date": "2026-07-27T21:00:00.000Z",
"threshold_minutes": 0,
"minutes_to_deadline": 0,
"overdue": true,
"risk_marker": null,
"rule_id": null,
"event_at": "2026-07-27T21:00:03.482Z"
}
```
No caso `RISK_MARKER`, o `risk_marker` vem preenchido com `id`, `name` e `color`. O corpo completo, campo a campo, está na [referência do evento `ORDER_DELAY`](/docs/api/webhook/order-delay).
## Nada chega para pedido já resolvido [#nada-chega-para-pedido-já-resolvido]
O disparo é agendado quando o pedido nasce — a partir do prazo informado na criação —, mas no instante em que vence o pedido é **revalidado**. Se ele já foi **entregue**, **cancelado**, **baixado manualmente** ou **devolvido**, o evento simplesmente não sai.
## Para ligar [#para-ligar]
1. Em **Configurações → Webhooks**, cadastre a URL do seu endpoint com o evento `ORDER_DELAY`.
2. Opcional: em **Configuração → Marcadores de risco de entrega**, crie regras para receber também os avisos preventivos (`trigger: "RISK_MARKER"`).
3. Os disparos ficam auditáveis em **Configurações → Logs → Webhooks**, com o payload exato e o status HTTP retornado.
***
---
# Neomode: nova integração de pedido (/docs/changelog/2026-07-28-integracao-neomode)
✅ Disponível agora para lojas cadastradas na Neomode. Fale com o suporte Abbiamo para habilitar sua filial.
## O que é [#o-que-é]
A **Neomode** é uma plataforma de gestão de pedidos omnichannel usada por redes de lojas e franquias para centralizar vendas de canais físicos e digitais. Com a nova integração, pedidos faturados na Neomode caem automaticamente no dashboard da Abbiamo — sem precisar de cadastro manual.
📦
Importação automática
Pedidos faturados na Neomode chegam direto na Abbiamo, prontos para despacho.
🔄
Status de volta em tempo real
Despachado, em rota e entregue são refletidos automaticamente na Neomode.
⚙️
Zero configuração técnica
Sem credenciais para gerar ou webhooks para configurar — a Abbiamo cuida da parte técnica.
## Como funciona na prática [#como-funciona-na-prática]
1. **Pedido é faturado na Neomode** — a loja processa a venda normalmente.
2. **Abbiamo importa o pedido** — o pedido aparece no dashboard, já vinculado à filial correta.
3. **Despacho normal** — a filial despacha pela transportadora que já usa hoje.
4. **Neomode é atualizada** — conforme o pedido avança (despachado, em rota, entregue), a Neomode reflete o status automaticamente.
## O que a loja precisa ter [#o-que-a-loja-precisa-ter]
Para habilitar a integração, a loja precisa apenas:
1. **Estar cadastrada na Neomode** com pedidos sendo faturados normalmente.
2. **Repassar o identificador da loja na Neomode** para o suporte Abbiamo vincular à filial correspondente.
O resto — autenticação, importação e atualização de status — a Abbiamo configura e mantém centralizado.
Veja o guia completo em [Integração de Pedido — Neomode](/docs/log/integrations/pedido/neomode/).
***
## A novidade em uma frase [#a-novidade-em-uma-frase]
Agora você pode remunerar o motorista pela **rota inteira** que ele monta a partir das ofertas — com base na **distância**, no **número de paradas** e nas **coletas** — em vez do frete de cada pedido isolado.
## O que mudou [#o-que-mudou]
🧮
Preço pela rota
O valor é
Tarifa por km
× distância +
Bônus por parada
× paradas extras +
Preço por coleta
× filiais coletadas.
🏷️
Por marcador e filial
Cada tabela vale para os motoristas com um
marcador
escolhido (ex.: Moto) e para as
filiais
que você definir.
📱
Transparente no app
O motorista vê
"Você recebe R$ X"
com o total da rota
antes de aceitar
— não o frete pedido a pedido.
## Como configurar [#como-configurar]
Em **Tabelas de frete → Tabela de Ofertas**, crie uma tabela com quatro valores:
* **Tarifa por km** — o valor por quilômetro rodado na rota.
* **Bônus por parada** — um extra por cada parada além da primeira.
* **Preço por coleta** — a base que o motorista já ganha por filial coletada.
* **Marcadores e Filiais** — para quais motoristas (pelo marcador) e em quais filiais a tabela vale.
Assim dá para segmentar a frota: uma tabela para **motos**, outra para **carros**, cada uma com sua tarifa.
## Como o motorista vê [#como-o-motorista-vê]
Quando as ofertas usam precificação por rota, o app do motorista deixa de mostrar o frete por pedido e passa a exibir o **total da rota**. Ao selecionar os pedidos, ele vê **"Você recebe R$ X"** antes de aceitar — sabe exatamente quanto vai ganhar pelo trajeto completo.
***
---
# Aba Logs: as chamadas de integração do pedido, com quem fez cada uma (/docs/changelog/2026-07-29-aba-logs-do-pedido)
✅ Disponível agora em Pedidos → clique num pedido para abrir o painel lateral → aba Logs.
🔒 Quem vê: a aba Logs aparece para o perfil proprietário (master) da conta — o mesmo critério da página Chave de API e das configurações. Para os demais usuários o painel do pedido segue igual, com as abas Detalhes e Rastreio.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Quando um pedido é cancelado, despachado ou tem o status mudado **pela API de embarcadores**, agora dá pra ver **quem fez** — e, do outro lado, **o que a Abbiamo solicitou à transportadora** (entrega, cancelamento, código de coleta) — tudo na mesma tabela, em ordem de acontecimento.
## O que mudou [#o-que-mudou]
🧾
Uma aba só pra integrações
O painel do pedido agora tem
Detalhes
,
Rastreio
e
Logs
. Nada saiu do lugar: a aba nova é onde vivem as
chamadas de integração
do pedido.
🔑
Quem fez pela API
Ação feita na
API de embarcadores
mostra o
nome da chave
que fez. Antes, um cancelamento via integração aparecia sem autor — agora tem nome e hora.
↔️
A direção da chamada
Cada linha diz
quem chamou quem
: a sua integração chamando a Abbiamo, ou a Abbiamo chamando a transportadora. Some a dúvida de "quem pediu isso?".
📍
Status continua no Detalhes
As
atualizações de status da transportadora
(saiu para entrega, entregue…)
não
entram aqui — elas seguem no histórico do pedido, na aba Detalhes.
🔎
Request e resposta completos
Em
Ver detalhes
, o log inteiro: endereço chamado, cabeçalhos, código de retorno e o corpo da resposta — com as chaves secretas já ocultadas.
## Por que isso importa [#por-que-isso-importa]
Quando um pedido some da operação ou aparece cancelado sem ninguém saber por quê, a primeira pergunta é sempre a mesma: **"quem fez isso?"**. Se a ação veio de uma integração — o seu ERP, o seu marketplace, um robô interno —, até agora o painel não sabia responder: o cancelamento aparecia no histórico como qualquer outro, sem dono.
A aba Logs fecha essa lacuna dos dois lados:
* **De fora pra dentro** — o que a sua integração pediu pra Abbiamo pela **API de embarcadores** (cancelar pedido, cancelar envio, solicitar entrega, reenviar, atualizar status, baixa manual, retirada), com o nome da chave de API que assinou a chamada.
* **De dentro pra fora** — o que a **Abbiamo solicitou à transportadora**: solicitação de entrega, solicitação de cancelamento e validação do código de coleta — com a resposta que ela devolveu.
Como as duas coisas ficam na **mesma tabela e na mesma linha do tempo**, dá pra ler a história do pedido na ordem em que ela aconteceu — em vez de cruzar telas.
### O que entra nesta aba (e o que não entra) [#o-que-entra-nesta-aba-e-o-que-não-entra]
ℹ️ A aba Logs é sobre solicitações, não sobre status. Ela registra as chamadas de integração: as que a sua API de embarcadores faz na Abbiamo, e as que a Abbiamo faz na transportadora (entrega, cancelamento, código de coleta).
**Não entram aqui** as **atualizações de status enviadas pela transportadora** — "saiu para entrega", "entregue", "falha na entrega" e afins. Esses eventos continuam onde sempre estiveram: no **histórico do pedido**, na aba **Detalhes** (e no mapa do trajeto). A aba Logs não duplica esse histórico; ela mostra o outro lado, o das solicitações.
## Detalhe importante [#detalhe-importante]
ℹ️ Falhas também entram. Uma tentativa que deu erro aparece marcada como Falha, com o código de retorno e a mensagem — justamente o caso em que você mais precisa entender o que aconteceu.
Nas ações feitas por chave de API, os cabeçalhos sensíveis (a própria chave, autorização, cookies) aparecem como `[REDACTED]`: o log mostra o que foi chamado, sem expor o segredo. Códigos de verificação de coleta e dados pessoais do destinatário também são mascarados antes de o log ser gravado.
É por carregar esse nível de detalhe — a troca HTTP como ela saiu — que a aba fica restrita ao perfil proprietário.
## Onde encontrar [#onde-encontrar]
1. Abra **Pedidos** e clique no pedido — o painel abre ao lado.
2. Vá na aba **Logs** (visível para o perfil **proprietário**; se você não a vê, peça a quem administra a conta).
3. Clique em **Ver detalhes** em qualquer linha pra abrir o request e a resposta.
---
# Foto de comprovação também na falha de entrega (/docs/changelog/2026-07-29-foto-na-falha)
## A novidade em uma frase [#a-novidade-em-uma-frase]
Agora você pode **exigir uma foto do motorista quando a entrega não dá certo** — a mesma prova de entrega (POD) que já existia na entrega concluída, agora também na falha.
## O que mudou [#o-que-mudou]
📸
Foto na falha
Ao marcar uma entrega como sem sucesso, o motorista anexa uma foto como comprovação — pela
câmera
ou pela
galeria
— junto do motivo do insucesso.
⚙️
Você decide
Um novo controle em
Comprovantes
liga ou desliga a exigência da foto na falha — do mesmo jeito que já funcionava para a entrega concluída.
📱
Cobrança no app
Com a exigência ligada, o app do motorista só conclui a falha
depois
que a foto é anexada.
## Como ativar [#como-ativar]
Em **Configurações → Operação**, no bloco **Comprovantes**, marque **Foto (POD)** na linha **FALHA** e salve. Pronto: a partir daí, toda entrega marcada como sem sucesso passa a pedir a foto no aplicativo do motorista.
Sem a opção marcada, nada muda: o registro de falha continua exatamente como antes, apenas com o motivo e a observação.
## Onde você vê a foto [#onde-você-vê-a-foto]
A foto fica **no mesmo lugar do comprovante da entrega concluída**: no **painel do pedido**, na aba **Detalhes**, o **histórico de entrega** mostra o evento de **Falha na Entrega** com a foto anexada — junto do motivo e da localização do registro.
---
# Automação de prazo prometido: a plataforma preenche o prazo do cliente (/docs/changelog/2026-07-30-automacao-prazo-prometido)
🔒 Quem vê: a tela aparece para o perfil proprietário da conta — o mesmo critério das outras telas de configuração.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Quando um pedido chega **sem prazo prometido ao cliente**, a plataforma não tinha contra o que medir atraso: ele ficava como **Sem info** na Situação de entrega, fora dos marcadores de risco e fora do webhook de atraso. Agora você define uma automação que **preenche esse prazo a partir da criação do pedido** — e ele passa a valer para tudo o mais.
## O que mudou [#o-que-mudou]
⏱️
Prazo a partir da criação
Você diz
quantas horas
depois da criação do pedido é o prazo. Pedido criado 14:00 com automação de 24h ganha prazo para as
14:00 do dia seguinte
.
🏷️
Condições, inclusive por marcador
A automação pode valer para todos os pedidos sem prazo, ou só para os que casam com condições —
marcador
, filial, tipo da entrega, valor, cidade, campos adicionais.
🔢
A ordem decide
Um pedido tem
um
prazo, então vence a
primeira automação que casar
. Clique no número da ordem para reordenar todas de uma vez.
⚡
Dá para ver de onde veio
Prazo preenchido por automação aparece no pedido com uma
marca clicável
, que leva direto para a automação que preencheu.
Antes
Sem prazo, sem régua
Pedido que chegava sem prazo prometido ficava
Sem info
na Situação de entrega. Não entrava nos marcadores de risco de entrega nem no webhook de atraso — e não havia como cobrar prazo de uma operação que não manda a data na integração.
Agora
O prazo é definido na criação
A automação preenche o prazo assim que o pedido entra. Ele passa a valer na
Situação de entrega
, nos
marcadores de risco
e no
webhook de atraso
, como qualquer pedido que já vinha com data.
## 🎯 Pra quem isso resolve [#-pra-quem-isso-resolve]
O prazo prometido só chega na Abbiamo se quem cria o pedido mandar. Na prática, um monte de operação não manda — e aí o pedido nasce sem prazo e fica fora de tudo que mede atraso.
Alguns casos onde isso pesa:
* **Integração de pedido que não envia prazo.** ERP, marketplace ou plataforma que simplesmente não tem esse campo no payload. Com a automação, o prazo passa a existir **sem depender de mudança do outro lado**.
* **Pedido criado por formulário ou planilha** no painel, onde ninguém para pra digitar uma data a cada pedido.
* **Integração via API já pronta e funcionando.** Se você já subiu a sua integração, não precisa mexer nela — nem entrar na fila de desenvolvimento do time — só pra passar um campo a mais.
E, mesmo para quem já manda o prazo em parte dos pedidos, o ganho é **controle e padronização**: o prazo deixa de depender de quem criou o pedido e passa a ser uma **regra da sua operação**, igual para todos, com quem definiu registrado no pedido.
## ⏱️ Como a automação calcula [#️-como-a-automação-calcula]
Cada automação tem um nome e um número: **quantas horas depois da criação do pedido** é o prazo prometido ao cliente.
A contagem começa na **criação do pedido**, não no momento em que a automação roda. Isso importa em dia de volume: se o processamento atrasa alguns minutos, o prazo não escorrega junto — ele continua ancorado em quando o pedido de fato entrou.
Um exemplo: automação de **24 horas**, pedido criado às **14:00 de segunda** → prazo prometido para **14:00 de terça**.
*Cada linha é uma automação: a ordem em que ela é avaliada, as condições, e o prazo que ela define.*
## 🏷️ Quando a automação vale [#️-quando-a-automação-vale]
Sem condição nenhuma, a automação vale para **todo pedido do grupo que chegar sem prazo**. Com condições, ela só age em quem casa — e aí você pode ter automações diferentes para operações diferentes.
As condições são as mesmas que você já usa nas outras automações (filial, tipo da entrega, valor total, cidade, CEP, campos adicionais), mais uma que é a mais útil aqui: **Marcador**.
A automação de prazo prometido roda **depois da automação de marcador**. Ou seja: um marcador que a plataforma acabou de aplicar no pedido já pode ser usado como condição do prazo. Isso permite montar réguas assim:
* pedidos com marcador **expresso** → prazo de **6 horas**
* pedidos da filial **Loja Centro** → prazo de **12 horas**
* pedidos com marcador **padrão** → prazo de **24 horas**
No campo Marcador as opções são **tem algum de** e **não tem nenhum de** — um pedido pode ter vários marcadores ao mesmo tempo, então a comparação é sempre contra a lista dele.
*O formulário se lê como uma frase: este nome, tantas horas depois da criação, quando o pedido casar com estas condições.*
## 🔢 A ordem decide qual vale [#-a-ordem-decide-qual-vale]
Aqui está a diferença mais importante em relação à automação de marcador: um pedido pode receber **vários marcadores**, mas tem **um único prazo**. Então as automações não se acumulam — vence a **primeira, de cima para baixo, que casar** com o pedido.
Por isso a coluna **Ordem** abre a tabela. Clique em qualquer número dela (ou no botão **Ordenar**) para abrir a reordenação: mova as automações com as setas ou digitando a posição, veja o resultado antes de aplicar, e salve tudo de uma vez.
*Reordene tudo e confira antes de salvar — nada é aplicado enquanto você mexe.*
O exemplo da seção anterior só funciona nessa ordem: a regra genérica de 24h tem que ficar **por último**, senão ela casaria primeiro e as específicas nunca rodariam.
## ⚡ De onde veio esse prazo [#-de-onde-veio-esse-prazo]
Prazo que a plataforma preencheu não se explica sozinho — e a pergunta que aparece é sempre "de onde saiu essa data?".
*A marca ao lado da data abre a automação que preencheu — e o balão já diz qual foi e quantas horas ela somou.*
Pedido cujo prazo veio na integração ou foi editado à mão continua exibindo o campo exatamente como antes, sem marca nenhuma.
## 🧾 Na aba Logs do pedido [#-na-aba-logs-do-pedido]
As ações das automações também passaram a aparecer na [aba **Logs**](/docs/changelog/2026-07-29-aba-logs-do-pedido) do painel do pedido, com um selo próprio de **Automação** — distinto do que veio pela API de embarcadores e do que a Abbiamo solicitou à transportadora.
Isso vale para **duas** automações:
* **prazo prometido** — qual automação definiu o prazo, e o cálculo que ela fez;
* **marcador** — qual automação aplicou cada marcador no pedido.
A segunda responde uma dúvida antiga: quando um marcador aparece num pedido sem ninguém ter colocado à mão, agora dá para ver qual automação o colocou.
## O que não mudou [#o-que-não-mudou]
* **Pedido que já chega com prazo é intocado.** A automação só preenche o que está vazio; ela nunca sobrescreve um prazo que veio na criação nem um que você editou. Esse prazo é o que foi combinado com o consumidor final, e ele tem preferência sobre qualquer regra nossa.
* **Retirada em loja** continua sem prazo de entrega ao cliente — não faz sentido medir atraso de entrega em pedido que o cliente busca na loja.
* **A automação de marcador segue igual.** Ela continua acumulando marcadores como sempre; a única novidade é que agora deixa registro de qual automação aplicou cada um.
* **Os marcadores de risco de entrega** continuam funcionando do mesmo jeito. A diferença é que passam a alcançar também os pedidos cujo prazo veio de automação — antes eles ficavam de fora por não ter prazo.
***
---
# Saúde de Localização: descubra as filiais cadastradas fora do lugar (/docs/changelog/2026-07-30-saude-de-localizacao)
🔬 Sob consulta — a análise já está rodando e vai ser liberada para todo mundo em breve. Se quiser usar antes, fale com a gente que habilitamos na sua conta. Quando ativa, aparece em Filiais → coluna Localização Inteligente e botão Revisar localizações.
🔒 Quem vê: a Saúde de Localização aparece para o perfil proprietário da conta — o mesmo critério da aba Logs do pedido e da página Chave de API. Aceitar uma correção reescreve a coordenada da filial e muda para onde o motorista é enviado em toda a operação daquela loja, então a revisão fica com quem responde pela conta. Para os demais usuários a tela de Filiais segue igual.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Se o endereço cadastrado de uma filial aponta pro lugar errado, o motorista descobre isso todo dia — **agora o sistema também descobre**, comparando o cadastro com o GPS real de onde as coletas acontecem.
## O que mudou [#o-que-mudou]
📍
O cadastro contra a realidade
A Abbiamo calcula o
ponto mediano das coletas
dos últimos 90 dias de cada filial e compara com a coordenada cadastrada. Divergiu de forma consistente? A filial é sinalizada.
🗺️
A prova no mapa
Cada coleta vira um
ponto no mapa
. Dá pra ver a nuvem inteira e quantas delas caem mais perto do ponto sugerido do que do cadastrado.
👁️
Street View dos dois pontos
Alterne entre
cadastro
e
coleta
e veja o que existe de fato em cada lugar. É o que resolve a dúvida em cinco segundos.
🧾
Os pedidos que comprovam
Clique em qualquer coleta da amostra e veja
a rota daquele pedido
— partida, coleta e destino — sem sair da revisão.
✍️
Você decide, sempre
Nada é corrigido sozinho. Você
aceita
,
ajusta a coordenada à mão
ou
mantém o cadastro
— e toda alteração fica registrada.
## Por que isso importa [#por-que-isso-importa]
Uma coordenada errada no cadastro não aparece em relatório nenhum. Ela aparece como **motorista rodando atrás do endereço**, coleta que atrasa, entregador que liga pra loja perguntando onde é a entrada — todo dia, na mesma filial, sem que ninguém ligue os pontos.
O sinal pra corrigir isso sempre existiu: **o GPS de quem coleta**. Se dezenas de motoristas param sistematicamente no mesmo lugar, e esse lugar fica a 600 metros do que está cadastrado, quem está errado é o cadastro. Era só ninguém estar olhando.
Agora a conta é feita sozinha, todo dia, pra todas as filiais.
## Como a análise é feita [#como-a-análise-é-feita]
ℹ️ Só entram filiais com no mínimo 20 coletas nos últimos 90 dias. Abaixo disso não há amostra suficiente pra afirmar nada, e a filial simplesmente não é avaliada.
Para cada filial, a Abbiamo pega o **ponto mediano** das coletas com GPS válido (a mediana ignora o motorista que marcou a coleta do estacionamento do outro lado da avenida) e mede a distância até a coordenada cadastrada. Junto vai a **dispersão** — o quanto essas coletas estão espalhadas entre si.
Dessa dispersão sai o **nível de confiança**:
| Nível | Critério | O que significa |
| --------- | -------------------------------------- | ------------------------------------------------------------- |
| **Alta** | coletas agrupadas em até 150 m | O ponto sugerido é preciso — a conferência tende a ser rápida |
| **Média** | coletas espalhadas entre 150 m e 400 m | O ponto é provável, mas o GPS variou. Confira no mapa |
| **Baixa** | coletas espalhadas por mais de 400 m | O GPS não converge. Inspecione os pedidos antes de decidir |
ℹ️ Confiança alta não quer dizer "pode aceitar sem olhar". Ela mede o quanto as coletas concordam entre si, não se a correção está certa. Por isso não existe correção automática: toda alteração passa por uma pessoa.
## Filiais em shopping merecem outra leitura [#filiais-em-shopping-merecem-outra-leitura]
🏬 Em shopping, o desvio é esperado. A loja fica dentro do prédio, mas a coleta acontece na doca ou entrada de serviço — naturalmente algumas centenas de metros dali.
Medimos isso: em filiais de shopping o desvio mediano é de **132 metros**, contra **20 metros** nas filiais de rua. Não é cadastro errado, é a geometria do lugar.
Por isso, quando a filial é de shopping, a tela avisa e muda a pergunta: não é *"o cadastro está errado?"*, e sim ***"o pino está na doca?"***. Corrigir continua valendo — apontar pra doca leva o motorista direto pro lugar de carregar —, mas se a sugestão cair no meio do estacionamento, o melhor é **ajustar a coordenada à mão**.
## Revisando na prática [#revisando-na-prática]
A revisão abre com o **panorama da conta**: quantas filiais estão sinalizadas, quantas divergem, o desvio mediano e o pior caso. Dali você escolhe por onde começar — por nível de confiança, pelos piores desvios, ou vendo tudo.
Na revisão você tem, lado a lado:
* **o mapa** com o cadastro (âmbar), o ponto sugerido (verde) e a nuvem de coletas reais;
* **o Street View** dos dois pontos, alternável;
* **as métricas** — nº de coletas, dispersão, distância e confiança;
* **os pedidos da amostra**, cada um abrindo a própria rota;
* **o campo de coordenada**, se você quiser apontar um ponto exato (com *restaurar sugerida* sempre à mão).
E três saídas: **aceitar**, **aceitar em lote** (marcando várias na lista) ou **manter o cadastro** — nesse caso a tela pergunta o porquê, porque é isso que nos deixa afinar o critério com o tempo.
## Também no painel do pedido [#também-no-painel-do-pedido]
Quando você abre um pedido cuja filial está com a localização divergente, um **aviso aparece no topo do painel**, com o tamanho do desvio e um atalho pro cadastro. Assim o problema chega até você mesmo sem ninguém ter entrado na revisão — também no perfil **proprietário**.
## Onde encontrar [#onde-encontrar]
Com a análise ativa na sua conta, e no perfil **proprietário**:
1. Abra **Filiais**.
2. Olhe a coluna **Localização Inteligente** — ela marca as filiais sinalizadas.
3. Clique em **Revisar localizações** pra abrir a revisão da conta inteira. Pra olhar uma filial só, clique no marcador dela na coluna (ou use **⋯ → Corrigir localização**).
## Como pedir acesso [#como-pedir-acesso]
🔬 Este recurso está disponível apenas para alguns clientes, sob consulta. Ele não vem ativo por padrão: estamos liberando conta a conta enquanto acompanhamos os resultados de perto.
Se fizer sentido para a sua operação, é só pedir — por qualquer um destes caminhos:
* o botão de **feedback** ou de **ajuda** aqui na documentação;
* o botão de **ajuda** dentro da plataforma;
* ou o seu **contato de Customer Success** na Abbiamo.
A gente avalia junto com você se a sua base já tem coletas suficientes para a análise fazer sentido e, se tiver, habilita na sua conta.
---
# A nova tela de Pedidos: filtros com "ou", visualizações do time e três níveis de granularidade (/docs/changelog/2026-07-31-filtros-e-visualizacoes-pedidos)
🔬 Sob consulta — a tela nova já está pronta e vai ser liberada para todo mundo em breve. Se quiser usar antes, fale com a gente que habilitamos na sua conta.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Agora dá para pedir **"isto ou aquilo"** num filtro só, guardar esse recorte como uma aba que o time inteiro enxerga — e descer até o detalhe que resolve: a modalidade de quem entregou e o motivo exato da falha.
## O problema era o "ou" [#o-problema-era-o-ou]
Os filtros antigos empilhavam condições com **e**: status *e* período *e* filial. Ótimo para estreitar, inútil para juntar.
Só que a pergunta que a operação faz de manhã quase nunca é de estreitar. É:
> *quais pedidos precisam de mim agora?*
E isso é uma soma de coisas diferentes: **atrasados** (de qualquer status) **ou** **devolvidos** **ou** **com falha na solicitação**. Três recortes que não têm nada em comum, exceto exigirem alguém.
Na tela antiga isso não tinha resposta: era filtrar três vezes, em três abas, e somar de cabeça.
Antes
Uma pergunta, três buscas
Filtra por atrasado. Anota. Troca para devolvido. Anota. Troca para falha na solicitação. Anota. Junta na cabeça — e repete amanhã.
Agora
Uma pergunta, um filtro
Monta o "ou" uma vez, salva como visualização, dá um nome. Amanhã é um clique na aba — e o time todo tem a mesma.
## Como monta [#como-monta]
O construtor trabalha com **condições** e **grupos**. Condição é uma linha (`Status é um de: Devolvido`). Grupo é uma caixa que junta linhas com **e** ou com **ou** — e grupos entram dentro de grupos, então dá para escrever coisas como *"criados nos últimos 7 dias **e** (atrasados **ou** devolvidos)"*.
Dá para arrastar as condições entre os grupos: se você montou no lugar errado, é puxar e soltar, não refazer.
## O recorte vira uma aba [#o-recorte-vira-uma-aba]
Salvou, virou aba no topo da lista. A aba guarda o filtro, **a ordenação e quais colunas estão visíveis** — reabrir devolve a tela exatamente como você deixou.
Cada visualização tem nome, ícone e cor, e pode ser:
👥
Compartilhada
Aparece para todo o time do grupo, e qualquer um pode aplicar. É o jeito de todo mundo olhar o mesmo recorte — sem combinar por mensagem.
🔒
Privada
Só você vê. Boa para o recorte que é do seu dia, não do processo.
Mexeu no filtro com uma visualização aberta? A aba marca que há alterações não salvas e te dá as duas saídas: **salvar nela** ou **descartar** e voltar ao que estava guardado. Explorar não estraga o que o time combinou.
## "Entregue por" agora tem três níveis [#entregue-por-agora-tem-três-níveis]
Antes, filtrar por quem entregou era escolher a transportadora e parar por aí. Só que **transportadora não é uma coisa só**: a mesma Uber entrega de carro e entrega de moto, com prazos diferentes — e esses casos não têm nada a ver um com o outro, nem no custo, nem no prazo, nem em quem reclama quando atrasa.
Agora o filtro é uma árvore de **transportadora › modalidade › prazo**, e você escolhe em que altura quer parar:
🚚
UBER
Tudo que a Uber entregou, sem distinção.
🚗
UBER › CARRO
Só a modalidade de carro dela — de qualquer prazo.
⏱️
UBER › CARRO › D1
O recorte exato: carro com prazo de um dia.
A **modalidade** é o grupo de método que está cadastrado na integração daquela transportadora — o mesmo nome que você vê nas configurações. Aparece exatamente como foi cadastrado (`CARRO`, `MOTO`, `CONVENCIONAL`…), sem tradução: quem deu o nome foi você, e renomear na tela só criaria uma segunda verdade.
Os códigos de prazo também aparecem como são (`EXP30`, `EXP120`, `D0`, `D1`) — quem opera a tela conhece esses nomes, e traduzir afastaria em vez de ajudar. E cada nível traz a contagem de pedidos ao lado, então dá para ver o volume antes de marcar.
Transportadora que não registrou modalidade aparece sem galho, como folha do primeiro nível — é o caso de quem ainda não foi atribuído.
## O Status desce até o motivo da falha [#o-status-desce-até-o-motivo-da-falha]
Mesma ideia, no filtro mais usado da tela. **Falha** era um item só: endereço errado e destinatário ausente caíam na mesma linha, sendo que um é problema de cadastro e o outro de tentativa — e a ação de cada um é diferente.
O Status também é uma árvore, de **status › sub-status › motivo da falha**, e você para na altura que quiser:
⚠️
Falha
Tudo que falhou, de coleta a devolução.
📦
Falha › Falha na Entrega
Só a falha na entrega — por qualquer motivo.
🏠
Falha › Falha na Entrega › Endereço Incorreto
O recorte exato, o que dá para resolver com o cliente.
O terceiro nível aparece só onde existe: nas três falhas que o entregador registra com motivo — **falha na entrega, falha na coleta e falha na devolução**. Nos outros status a árvore acaba no sub-status, porque não há motivo para descer. Ao lado de cada motivo vem o código que o app do entregador gravou, para bater com o que sua integração recebe.
Marcar um nível marca tudo abaixo dele, e desmarcar um filho deixa o pai meio-marcado — então "toda falha na entrega, menos endereço incorreto" é questão de desmarcar uma linha, não de montar condição. Os dois primeiros níveis mostram a contagem do recorte, e o que está zerado fica escondido por padrão (tem um **Mostrar todos os status** para ver o catálogo inteiro).
E como é o mesmo construtor, isso combina com o "ou": *falha na entrega por endereço incorreto* **ou** *devolvido* **ou** *atrasado* é um filtro só — e cabe numa aba salva.
## Duas coisas menores que mudam o dia [#duas-coisas-menores-que-mudam-o-dia]
🔎
Buscar não esbarra mais na data
Procurar um pedido de dois meses atrás com o filtro em "últimos 7 dias" achava — e a lista escondia. Agora, enquanto a busca manda, o filtro de data fica suspenso (e volta sozinho quando você limpa a busca).
🔗
A aba mora no link
A visualização aberta entra no endereço. Recarregar a página volta nela — e mandar o link para alguém abre o mesmo recorte do outro lado.
## Para pedir [#para-pedir]
A tela convive com a atual: enquanto não for liberada para todos, ela é habilitada por conta. Fale com o seu contato na Abbiamo ou com o suporte que a gente liga para você — e a tela antiga continua ali, do jeito que está hoje, até a virada.
---
# Aviso de nova oferta: som exclusivo e alerta flutuante de ofertas (/docs/changelog/2026-08-10-aviso-de-nova-oferta)
✅ Disponível para o Abbiamo GO — no Android.
## A novidade em uma frase [#a-novidade-em-uma-frase]
O motorista **para de perder oferta**: toca um **som exclusivo** quando uma corrida chega e um **alerta flutuante** mostra quantas ofertas estão esperando — mesmo com o app minimizado.
## O que mudou [#o-que-mudou]
🔊
Som exclusivo
Quando chega uma nova oferta, o app toca um
som próprio da Abbiamo
, diferente das outras notificações — o motorista reconhece na hora.
🫧
Alerta flutuante
Um alerta flutuante com a
contagem de ofertas
aparece
por cima de qualquer app
que ele estiver usando. Um toque abre a lista de ofertas.
🔔
Não perde corrida
Mesmo com o app
minimizado ou em segundo plano
, o motorista vê e ouve a oferta no momento em que ela chega.
## O som da oferta [#o-som-da-oferta]
Toda nova oferta agora chega com um **som próprio**, que se destaca das demais notificações do celular. Vale para **todos os motoristas** — sem configuração.
## O alerta flutuante de ofertas [#o-alerta-flutuante-de-ofertas]
O alerta flutua **por cima de qualquer aplicativo** — o motorista continua vendo quando está no mapa, no navegador ou em outro app. Ele mostra **quantas ofertas** estão esperando; um toque **abre direto a lista** dentro do Abbiamo GO.
## Como o motorista ativa [#como-o-motorista-ativa]
Na primeira vez, o app mostra um convite explicando o alerta e pede, **em passos**, as duas permissões que ele precisa: **exibir sobre outros apps** e **notificações** (é por elas que a oferta chega e toca o som). Se ele adiar, o app lembra de novo mais pra frente — sem insistir a cada abertura.
---
# Ações no rastreio: escolha quais botões o seu cliente pode usar (/docs/changelog/2026-08-14-acoes-no-rastreio)
✅ Disponível para contas com Care — configure em Care → Configurações, no card Ações no rastreio.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Você passa a **escolher quais botões de ação** o cliente vê na página de rastreio: marque os que fazem sentido para a sua operação e o restante simplesmente **não aparece** para ele.
## O que dá pra fazer [#o-que-dá-pra-fazer]
🎛️
Você no controle
Um card com todas as ações disponíveis. Marque para mostrar, desmarque para esconder — sem depender de ninguém.
🧭
Certo em cada fase
Cada ação aparece só quando faz sentido: mudar o endereço enquanto o pedido está a caminho, devolver depois de entregue, e assim por diante.
🔄
Também em retirada e devolução
As ações não estão mais só na entrega: valem também para retirada na loja e para a logística reversa.
## As ações que você pode oferecer [#as-ações-que-você-pode-oferecer]
Organizadas pelo momento do pedido:
| Fase | Ações |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| Pedido a caminho | Mudar o endereço · Reagendar a entrega · Não vou estar em casa · Cancelar a entrega · Cadê meu pedido? |
| Pedido entregue | Não recebi · Veio o produto errado · Faltando itens · Chegou danificado · Quero devolver · Quero trocar |
| Falha na entrega | Tentar entregar de novo · Corrigir o endereço · Cancelar e ser reembolsado |
Começa com tudo ligado. Por padrão, todas as ações vêm marcadas — a página do cliente já funciona completa. Vá desmarcando o que a sua operação prefere não oferecer.
## Como configurar [#como-configurar]
Acesse
Care → Configurações
.
No card
Ações no rastreio
, marque ou desmarque cada ação.
Salve. As mudanças passam a valer nas próximas aberturas da página de rastreio.
## O que acontece quando o cliente usa [#o-que-acontece-quando-o-cliente-usa]
Cada ação abre um caso no **Care** — o mesmo lugar onde seu time acompanha e resolve. O cliente relata pela página de rastreio, e vocês conduzem pelo painel, com histórico próprio. É a ponte entre o que o cliente quer e a sua operação.
Em breve: Care AI. Você reparou nos selos "IA resolve sozinho" ao lado de cada ação? É pra onde estamos indo: uma IA que atende dentro das políticas da sua marca e resolve os casos automaticamente — já em testes resolvendo cerca de 80% sozinha, escalando pra sua equipe só quando precisa.
Essas ações moram na nova página de rastreio. Para o cliente ver os botões, a nova página precisa estar ativa na sua conta — as duas coisas chegam juntas.
---
# A nova página de rastreio: mapa em destaque, uma informação por vez e suporte integrado (/docs/changelog/2026-08-14-nova-pagina-rastreio)
✅ Chegando gradualmente às contas — a nova página de rastreio está sendo liberada aos poucos. Quer adiantar a ativação na sua conta? Fale com o suporte.
## A novidade em uma frase [#a-novidade-em-uma-frase]
A página de rastreio que seu cliente abre para acompanhar o pedido foi **redesenhada de ponta a ponta** — mais clara, com o **mapa ao vivo em destaque**, uma **informação por vez** e o **suporte integrado** — acompanhando a entrega do começo ao fim.
## O que mudou [#o-que-mudou]
🗺️
Mapa no centro
O rastreamento ao vivo passou a ser o destaque da tela — com o entregador e a distância até o cliente, quando disponíveis. É o motivo de reabrir a página.
✨
Uma informação por vez
Cada etapa mostra o essencial: a data de entrega em destaque, "chegou às 14h", "entrega agendada para…". Sem ruído.
💬
Suporte a um toque
Uma aba de Suporte acompanha o pedido em qualquer fase — atraso, endereço errado, um problema com a entrega. Aparece só quando o Care está ativo na sua conta.
✅
Confirme o recebimento
Quando o pedido é entregue, o cliente confirma que recebeu com um toque — ou abre um problema ali mesmo. A confirmação fecha o ciclo e aparece pra sua equipe.
## Mais estável, atualizando ao vivo [#mais-estável-atualizando-ao-vivo]
A página se atualiza sozinha enquanto o cliente acompanha. Antes, cada atualização redesenhava o mapa inteiro — piscava e perdia o zoom. Agora **só o entregador se move**: o mapa fica parado, a rota permanece, e a posição avança suavemente.
## O que o cliente vê em cada momento [#o-que-o-cliente-vê-em-cada-momento]
| Momento | O que aparece em destaque |
| ---------------- | -------------------------------------------------------------------- |
| A caminho | Mapa ao vivo + previsão de entrega |
| Agendado | A data agendada, como fato principal |
| Entregue | Confirmação de recebimento e, na sequência, a pesquisa de satisfação |
| Falha na entrega | Um caminho para resolver, não um beco sem saída |
## Suporte a um toque, em qualquer fase [#suporte-a-um-toque-em-qualquer-fase]
Uma aba de **Suporte** acompanha o pedido do começo ao fim — e mostra só as ações que fazem sentido no momento. Aparece quando o Care está ativo na sua conta.
A caminho
— ajustar a entrega
Entregue
— relatar um problema, devolver ou trocar
Falha
— reagendar, corrigir o endereço ou reembolso
## Quando a entrega falha, um caminho para resolver [#quando-a-entrega-falha-um-caminho-para-resolver]
Se a entrega não é concluída, a página não vira um beco sem saída: diz com clareza o que aconteceu e leva direto às opções de resolver.
Com clareza
— o que aconteceu, sem susto
Vamos resolver isso
— reagendar, corrigir ou reembolsar
Nada muda na sua operação. É a mesma página, no mesmo link — apenas mais bonita e mais clara para quem recebe. Você não precisa fazer nada para o seu cliente aproveitar.
## E o que vem junto [#e-o-que-vem-junto]
A nova página também é a base para dois recursos que o cliente encontra ali mesmo: as **[ações no rastreio](/docs/changelog/2026-08-14-acoes-no-rastreio)** (os botões de suporte que você escolhe) e os espaços de comunicação e ofertas da sua marca. Fale com o suporte para habilitar na sua conta.
---
# Verificação em duas etapas (2FA) para proteger sua conta (/docs/changelog/2026-08-14-verificacao-em-duas-etapas)
✅ Disponível para todas as contas Abbiamo — no LOG e no GO.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Sua conta ganhou **verificação em duas etapas (2FA)**: além da senha, você informa um **código do seu aplicativo autenticador** ao entrar — uma camada extra de proteção que você mesmo ativa em segundos.
## O que mudou [#o-que-mudou]
🛡️
Mais segurança
Mesmo que alguém descubra sua senha, não entra sem o código do seu aplicativo autenticador.
⚡
Você ativa sozinho
Sem depender de ninguém: ative ou desative pelo menu da sua conta, na página
Segurança
.
📱
Com o app que você já usa
Funciona com Google Authenticator, Authy, 1Password e outros aplicativos autenticadores.
## Onde encontrar [#onde-encontrar]
Clique no seu usuário, no canto inferior do menu, e abra **Segurança**.
## Como ativar [#como-ativar]
Na página **Segurança**, clique em **Ativar**. Você vai:
1. **Escanear o QR Code** com o seu aplicativo autenticador — ou copiar a chave, se preferir digitar.
2. **Digitar o código de 6 dígitos** que o app gera e clicar em **Ativar**.
Pronto. A partir daí, sempre que você entrar na Abbiamo, vamos pedir o código do app.
## Contas que já exigem 2FA [#contas-que-já-exigem-2fa]
Algumas contas com acesso a informações mais sensíveis já têm a verificação em duas etapas **obrigatória**. Nesses casos, na primeira vez que você entrar, vamos pedir para configurá-la ali mesmo na tela de login — é o mesmo passo a passo, com o QR Code e o código.
## Perdeu o acesso ao aplicativo? [#perdeu-o-acesso-ao-aplicativo]
Se você trocar de celular ou perder o acesso ao aplicativo autenticador, fale com o suporte para reativar sua conta com segurança.
---
# Marcadores de rota: identifique e filtre suas rotas por cor (/docs/changelog/2026-08-17-marcadores-de-rota)
✅ Disponível — crie seus marcadores em Configurações → Marcadores, na aba Rotas, e aplique nas rotas onde você trabalha.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Assim como já existia para pedidos e filiais, agora as **rotas** também têm marcadores: você cria etiquetas coloridas com o nome que quiser e aplica nas rotas para **identificá-las e filtrá-las** — na montagem, na lista de Rotas e no acompanhamento ao vivo.
## O que dá pra fazer [#o-que-dá-pra-fazer]
🏷️
Um ou vários por rota
Aplique quantos marcadores fizerem sentido em cada rota — por região, tipo de operação, prioridade, o que a sua rotina pedir.
🗺️
Onde você trabalha
Os marcadores aparecem na lista de Rotas, na tela de montagem e no acompanhamento ao vivo das entregas — sempre visíveis ao lado da rota.
🔎
Filtro num clique
Mostre só as rotas de um marcador, combine mais de um, ou esconda o que não interessa no momento.
## Como criar seus marcadores [#como-criar-seus-marcadores]
Acesse
Configurações → Marcadores
.
Abra a aba
Rotas
(ao lado de Pedidos, Motoristas e Filiais).
Clique no
+
, dê um
nome
ao marcador e escolha uma
cor
. Salve.
O menu
⋯
de cada linha permite
editar
depois, e a coluna
Em uso
mostra em quantas rotas cada marcador está aplicado.
Cada tipo de marcador é independente: os de Rotas não se misturam com os de Pedidos, Motoristas ou Filiais.
## Onde os marcadores aparecem [#onde-os-marcadores-aparecem]
Na **lista de Rotas**, cada rota mostra seus marcadores numa coluna própria — e o filtro no topo deixa você recortar por marcador na hora.
## Como aplicar em uma rota [#como-aplicar-em-uma-rota]
Abra a rota (na lista de Rotas, na montagem ou no acompanhamento).
Em
Marcadores
, clique em
Adicionar
/
Editar marcadores
.
Selecione
um ou mais
marcadores e salve. Pronto — eles ficam visíveis na rota.
Já sai marcada da montagem. Se você aplicar os marcadores enquanto monta a rota, ela nasce com eles — sem precisar marcar de novo depois de criar.
## Filtrar por marcador [#filtrar-por-marcador]
No acompanhamento, os marcadores viram atalhos de filtro: clique em um para ver só as rotas daquele marcador, ou use a legenda no mapa para mostrar/ocultar cada um.
Os marcadores de rota são criados uma vez em Configurações → Marcadores → Rotas e ficam disponíveis para toda a sua operação de rotas.
---
# Atribua o motorista direto no acompanhamento das rotas (/docs/changelog/2026-08-18-motorista-no-acompanhamento)
✅ Disponível no acompanhamento de rotas — abra uma rota de frota própria e atribua o motorista pelo card de detalhe.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Atribuir o motorista antes só dava na tela de Rotas; agora você faz isso **direto no acompanhamento ao vivo** — a mesma ação, no lugar onde você já está olhando a operação acontecer.
## O que muda [#o-que-muda]
🧑✈️
Atribuir sem trocar de tela
No card de detalhe da rota, um botão
Atribuir motorista
abre a lista e resolve na hora — sem voltar pra tela de Rotas.
🟢
Quem está disponível
A lista mostra cada motorista com um indicador de
disponível
ou
ocupado
, e tem busca por nome. Você escolhe com contexto.
🧹
Card mais limpo
Rota sem motorista não mostra mais Telefone e Última posição vazios: aparece direto a opção de atribuir, e na lista fica marcada como
"Sem motorista"
.
## Como atribuir [#como-atribuir]
No
acompanhamento
, abra a rota (card de detalhe à direita).
Em
Motorista
, clique em
Atribuir motorista
.
Escolha o motorista na lista — o indicador mostra quem está livre — e clique em
Salvar
.
Um retorno confirma a atribuição, e o card passa a mostrar o motorista, o telefone e a última posição.
Rotas de transportadora seguem sem essa etapa — a atribuição de motorista vale para as rotas de frota própria.
---
# Webhook de rota: agora com o nome que você deu na criação (/docs/changelog/2026-08-20-nome-da-rota-no-webhook)
✅ Disponível agora — sem nenhuma configuração adicional. Contrato completo na referência do evento.
## A novidade em uma frase [#a-novidade-em-uma-frase]
O evento `ROUTE_STATUS_CHANGE` agora inclui `external_name` — o nome ou referência que você informa ao criar a rota — além do `route_id` interno da Abbiamo.
## O que mudou [#o-que-mudou]
Antes
Só o ID interno
O payload trazia apenas o
route_id
gerado pela Abbiamo. Para casar o evento com a rota que você criou, era preciso guardar esse ID de volta no seu sistema no momento da criação.
Agora
Também o seu nome de rota
Se você informou um nome ou referência ao criar a rota, ele chega em
external_name
— dá para identificar a rota pelo dado que já faz sentido pro seu sistema, sem precisar mapear o ID interno.
---
# Repasses e Auditoria de frete, direto no painel (/docs/changelog/2026-08-20-repasses-e-auditoria)
✅ Disponível para operações habilitadas. Repasses aparece no contexto GO (entregadores) e Auditoria no contexto LOG (transportadoras) — direto no menu lateral.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Tudo o que antes exigia um sistema à parte agora está **dentro do painel**: você aprova o repasse de um entregador, reprocessa uma transferência que falhou e audita a cobrança de uma transportadora contra o contrato — no mesmo lugar onde já acompanha a operação.
## Repasses — pague seus entregadores sem sair do painel [#repasses--pague-seus-entregadores-sem-sair-do-painel]
📊
Visão geral
Um painel com os valores
pendente, aprovado, pago e negado
e as entregas agrupadas por status — cada aba com seu marcador colorido, pra bater o olho e agir.
🧑🚀
Entregadores
A lista de entregadores com status (em dia, pendente, atenção, inativo) e, no detalhe, as
últimas entregas
, o resumo dos valores e os
dados bancários
completos.
✅
Ações na hora
Aprovar
,
pausar
ou
negar
pagamentos — uma entrega por vez ou várias de uma vez com a seleção múltipla. A lista atualiza no mesmo instante.
🔁
Transferências
Todos os repasses enviados, com o motivo de quem falhou e um botão de
Tentar de novo
. Os IDs do provedor viram
campo copiável
pra conciliação.
## Auditoria — audite o frete das suas transportadoras [#auditoria--audite-o-frete-das-suas-transportadoras]
🚚
Transportadoras
As transportadoras (3PLs) são
detectadas automaticamente
a partir dos pedidos finalizados. Veja volume, valor faturado e
custo médio do frete
por parceira, no período que escolher.
🔎
Conformidade
No detalhe de cada transportadora, a auditoria do mês: quanto foi
conforme
, quanto veio
acima
do contrato e a evolução nas últimas semanas.
🧾
Faturas
Agrupe entregas de uma transportadora por período em uma
fatura fechada
, com total conferido para o financeiro.
📄
Contratos com IA
Anexe o contrato e a
IA extrai
vigência, cláusulas e tabelas de frete — a base que sustenta toda a reconciliação de cobrança.
Cada transportadora sem contrato aparece marcada como Atenção — é só anexar um contrato ali mesmo pra começar a auditar a cobrança dela.
## Como acessar [#como-acessar]
No seletor de contexto (canto superior do menu), escolha
GO
para
Repasses
ou
LOG
para
Auditoria
.
O submenu correspondente aparece no menu lateral.
Em
Repasses
: comece pela
Visão geral
, depois
Entregadores
e
Transferências
.
Em
Auditoria
: comece por
Transportadoras
, depois
Contratos
e
Faturas
. O
Glossário de status
explica cada resultado da auditoria.
O acesso é por operador: só quem está habilitado vê os menus. Se você não enxerga Repasses ou Auditoria e acha que deveria, fale com o seu contato na Abbiamo pra liberar.
---
# Acompanhe as rotas de várias filiais na mesma tela (/docs/changelog/2026-08-21-acompanhamento-multiplas-filiais)
✅ Disponível no acompanhamento de rotas — o seletor Filiais fica logo abaixo da busca.
## A novidade em uma frase [#a-novidade-em-uma-frase]
O acompanhamento abria filtrado em **uma filial só**. Agora você escolhe **quantas filiais quiser** e vê a operação inteira num quadro só — sem ficar trocando de filial pra saber o que está acontecendo.
Antes
Uma filial por vez
Quem opera com muitas filiais via só um pedaço do dia. Se a operação está espalhada — várias filiais com uma ou duas rotas cada —, era trocar de filial dezenas de vezes pra ter a visão do dia.
Agora
Quantas filiais você quiser
Escolha as filiais que interessam (ou todas) e acompanhe tudo junto: a mesma lista, o mesmo mapa, com cada rota identificada pela filial de origem.
## O que muda [#o-que-muda]
🏬
Seletor de filiais
Busque pelo nome, marque as que quiser e aplique. Abre sempre na
filial atual
, e um atalho traz de volta só as filiais que
têm rota no dia
.
🎨
Cada rota diz de onde é
Com mais de uma filial no quadro, cada rota ganha o
selo da filial
na lista e no detalhe — e o
CD de cada filial
aparece no mapa na mesma cor.
⚡
Abre bem mais rápido
Mudamos a forma como a tela carrega as rotas do dia. O tempo de abertura caiu de
alguns segundos para quase imediato
, mesmo com muitas filiais selecionadas.
## Como escolher as filiais [#como-escolher-as-filiais]
No
acompanhamento
, clique em
Filiais
, abaixo da busca.
Marque as filiais que quer acompanhar — use a busca por nome se a lista for longa, ou
todas
de uma vez.
Clique em
Aplicar
. A lista, os contadores e o mapa passam a considerar todas elas.
Para voltar ao de antes, use
só a filial atual
.
O link guarda a seleção. As filiais escolhidas ficam no endereço da página: dá pra favoritar a sua visão, recarregar sem perder nada e mandar o link para outra pessoa da equipe — inclusive quando a escolha é todas. Marcar filiais uma a uma tem teto de 150; daí pra cima o caminho é todas. Ao trocar a filial no topo da tela, a seleção volta para essa filial.
## Busca e filtros valem para tudo que está selecionado [#busca-e-filtros-valem-para-tudo-que-está-selecionado]
A busca por rota, motorista ou pedido, os filtros de **frota, transportadora e ofertas**, e os **marcadores** passaram a valer sobre o conjunto inteiro de filiais selecionadas — e não só sobre o que já estava carregado na tela.
As abas **Ativas** e **Criadas** continuam mostrando o dia inteiro de uma vez, para que as rotas que precisam de atenção apareçam sempre no topo. A aba **Finalizadas**, que é onde o volume se acumula ao longo do dia, ganhou **paginação**.
O trajeto de uma rota continua sendo desenhado quando você abre a rota — clicando no card ou no ponto do motorista no mapa. O que muda é que ele agora sai sempre do CD da filial daquela rota.
Dois detalhes de quem marca muitas filiais. Com mais de uma filial no quadro, a posição do motorista passa a vir da própria rota — o telefone dele aparece no detalhe quando você acompanha uma filial só. E, se a seleção for muito grande, o mapa prioriza os CDs das filiais que têm rota no dia, para não cobrir tudo de losangos.
---
# Webhook só quando importa: filtre por condições do pedido (/docs/changelog/2026-08-26-condicoes-no-webhook)
✅ Disponível agora — em Configurações › Webhooks, ao criar ou editar um webhook.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Cada webhook pode ter um filtro próprio: em vez de receber todas as atualizações do evento e descartar do seu lado, você diz **quando** quer ser chamado.
## O que mudou [#o-que-mudou]
Antes
Tudo ou nada
O webhook era enviado em toda atualização do evento assinado. Se você só se importava com as entregas que falharam, recebia também todas as que deram certo — e precisava filtrar no seu sistema, gastando processamento com o que ia descartar.
Agora
Você escolhe o gatilho
Monta o filtro na tela, do mesmo jeito que já filtra a lista de Pedidos, e só recebe o que casa. O que não bate na condição simplesmente não é enviado.
## Por onde filtrar [#por-onde-filtrar]
* **Status** — em cascata, igual à tela de Pedidos: escolha o status, desça pro sub-status e, nas falhas, até o motivo (por exemplo: `Falha na entrega → Destinatário indisponível`).
* **Pedido** — o número no seu sistema. Útil pra separar por prefixo, quando o número já carrega uma convenção sua.
* **Origem do pedido** — por onde ele entrou: integração, painel, API.
* **Informação adicional** — qualquer chave que a sua integração grava no pedido. Você digita o nome do campo e filtra por ele.
O seletor de status é o mesmo da lista de Pedidos: escolha o status e desça pelos níveis quando precisar de mais detalhe.
Dá pra combinar quantas condições quiser, com **E** e **OU**, e agrupar — a mesma montagem de filtro da lista de Pedidos.
## Sem condição, nada muda [#sem-condição-nada-muda]
Webhook sem filtro continua recebendo todas as atualizações do evento, exatamente como antes. Os webhooks que você já tem hoje **não foram alterados**.
## Como configurar [#como-configurar]
1. Vá em **Configurações › Webhooks**.
2. Crie um webhook novo ou edite um existente.
3. Na seção **Condições**, desmarque *"Enviar todas as atualizações desse evento"*.
4. Monte o filtro e salve.
A listagem de webhooks passa a mostrar uma coluna **Condições**, com o resumo do filtro de cada um — dá pra ver de relance quem está filtrando o quê.
***
---
# Botão para solicitar coleta no Abbiamo GO permite seleção de regras de automação de oferta (/docs/changelog/2026-08-28-automacao-de-oferta-no-reenvio-manual)
✅ Disponível agora no modal Enviar oferta, ao reenviar manualmente uma oferta do Abbiamo GO.
## O que mudou [#o-que-mudou]
Quando uma oferta é cancelada e você precisa reenviá-la na mão, o modal **Enviar oferta** agora resolve sozinho qual **automação de oferta** da filial vale para aquele pedido — e mostra os critérios dela antes de você confirmar o envio.
Antes
Reenvio ignorava a automação
Reenviar manualmente pedia para configurar tudo de novo do zero — quem recebe, distância máxima — sem nenhuma ligação com as automações de oferta já cadastradas para a filial.
Agora
A automação certa já vem selecionada
O modal identifica a automação que se aplica ao pedido e mostra, de cara, quem recebe a oferta, a distância máxima da filial e quantos motoristas atendem esse critério agora.
## Os critérios ficam visíveis antes de enviar [#os-critérios-ficam-visíveis-antes-de-enviar]
Com a automação escolhida, três informações aparecem lado a lado:
* **Quem recebe** — todos os motoristas da filial, um grupo específico ou uma lista de motoristas, conforme a automação.
* **Distância máxima da filial** — o raio configurado na automação, ou "sem limite" quando não há um.
* **Disponíveis agora** — quantos motoristas atendem esse critério neste momento. Quando ninguém atende, um aviso deixa isso claro antes do envio.
Se a filial tiver mais de uma automação cadastrada, dá para trocar para outra na mesma tela — e a configuração manual (escolher motoristas e distância na mão) continua disponível como alternativa.
## Como configurar as automações [#como-configurar-as-automações]
As automações de oferta continuam sendo criadas e editadas em Automações de ofertas, dentro de **Configurações → Automações de ofertas** — nada muda por lá. O que muda é que o reenvio manual agora as aplica também.
***
---
# Exporte a base completa dos seus motoristas (/docs/changelog/2026-09-01-relatorio-motoristas)
✅ Disponível em Relatórios → Novo relatório → tipo MOTORISTAS.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Agora dá pra **exportar a base inteira de motoristas** das suas filiais direto do painel — com documento, contato, etiquetas e cidade de cadastro — em vez de conferir motorista por motorista na tela.
## Como funciona [#como-funciona]
📋
Sem escolher período
Diferente dos relatórios de pedidos e envios, esse não pede data. É o retrato do seu cadastro no momento em que você gera — todo mundo que está vinculado às filiais escolhidas.
🏷️
Com as etiquetas
As etiquetas que você atribuiu a cada motorista vêm numa coluna só, separadas por vírgula.
🗂️
Escolha as colunas
Como nos outros relatórios, dá pra montar um export enxuto com o
seletor de Colunas
— só o documento e o contato, por exemplo.
## O que vem no arquivo [#o-que-vem-no-arquivo]
| Coluna | O que é |
| ------------------------------- | --------------------------------------------------- |
| `id_do_motorista` | Identificador único do motorista na base da Abbiamo |
| `nome_do_motorista` | Primeiro nome |
| `sobrenome_do_motorista` | Sobrenome |
| `documento_do_motorista` | CPF |
| `email_do_motorista` | E-mail |
| `telefone_do_motorista` | Telefone |
| `data_de_cadastro_do_motorista` | Quando o motorista entrou na base |
| `data_da_ultima_atividade` | Última atividade registrada no aplicativo |
| `etiquetas_do_motorista` | Etiquetas atribuídas, separadas por vírgula |
| `ultima_latitude` | Latitude da última localização conhecida |
| `ultima_longitude` | Longitude da última localização conhecida |
| `data_da_ultima_localizacao` | Quando a localização foi atualizada pela última vez |
| `cidade_do_motorista` | Cidade do endereço de cadastro |
| `uf_do_motorista` | UF do endereço de cadastro |
Gerando em inglês, os cabeçalhos saem com os nomes equivalentes (`driver_first_name`, `driver_document_number`, e assim por diante).
## Por que isso importa [#por-que-isso-importa]
* **Conferência de cadastro**: bater a base do painel com a sua planilha interna, achar motorista sem e-mail ou sem telefone, revisar quem está sem etiqueta.
* **Recorte por região**: com cidade e UF do cadastro, dá pra dimensionar quantos entregadores você tem por praça.
* **Quem está ativo**: a data da última atividade mostra quem anda usando o aplicativo e quem sumiu — útil antes de uma campanha ou de uma limpeza de base.
Atenção com o CPF: o arquivo traz o documento como está no cadastro. Se ele vier só com dígitos, o Excel e o Google Sheets tendem a tratar a coluna como número na importação automática e cortar o zero à esquerda. Ao abrir, marque a coluna do documento como Texto antes de confirmar.
Dica: quer saber o que cada coluna significa antes de montar o export? O Dicionário (botão no topo da tela de Relatórios) lista todas as colunas de cada tipo de relatório, com a descrição de cada campo.
---
# Corrigir endereço sem sair do Roteirizador (/docs/changelog/2026-09-02-endereco-no-roteirizador)
✅ Disponível agora para as contas que já usam o Roteirizador → selecione um pedido e clique no lápis ao lado do endereço de entrega.
## A novidade em uma frase [#a-novidade-em-uma-frase]
Quando o endereço de um pedido chega errado, dá para consertar direto na tela de roteirização — agora com **complemento**, **busca por CEP** e o **mapa acompanhando** o que você digita.
## O que mudou [#o-que-mudou]
🏢
Campo de complemento
Apto, bloco, portaria dos fundos. A informação que decide se o motorista acha o destino ou fica rodando no quarteirão agora tem onde ser escrita.
📮
Busca automática por CEP
Digite os oito dígitos e rua, bairro, cidade e UF vêm preenchidos. Sem botão para clicar: assim que o CEP fica completo, a busca dispara sozinha.
📍
O mapa segue o endereço
Preencheu pelo CEP e o pino vai junto para o local novo. Antes ele ficava parado no endereço antigo, e você não tinha como conferir se o resultado fazia sentido.
## Como usar [#como-usar]
1. **Abra a edição.** Selecione o pedido e clique no lápis ao lado do endereço de entrega.
2. **Digite o CEP.** Ao completar os oito dígitos, rua, bairro, cidade e UF são preenchidos e o pino do mapa se move para lá.
3. **Ajuste o pino, se precisar.** Arraste o marcador quando o ponto não cair na entrada certa. O que você posicionar à mão é o que vale.
## Detalhes que valem saber [#detalhes-que-valem-saber]
* **CEP de cidade inteira não apaga o que você escreveu.** Alguns CEPs cobrem um município todo e não trazem rua nem bairro. Nesse caso, os campos que você já tinha preenchido continuam como estão.
* **CEP inexistente não quebra o formulário.** Se a busca não encontrar nada, nada é alterado e você segue preenchendo à mão.
* **Corrigir só o complemento não mexe no pino.** Como complemento não muda a coordenada, ajustar "apto 42" preserva uma localização que já tinha sido acertada.
* **Quem agiu por último manda.** Se você arrastar o pino depois de mexer no endereço, vale o pino. Se mexer no endereço depois de arrastar o pino, o endereço é reprocessado.
O endereço corrigido segue para a entrega, então a rota e o aplicativo do motorista passam a usar a localização nova.
## Também nesta atualização [#também-nesta-atualização]
**"Terminar no depósito" agora nasce desmarcada.** A opção vinha ligada por padrão no painel de paradas selecionadas, e quando ninguém lembrava de desmarcar o motorista era acionado com um retorno ao CD que a operação não precisava.
Agora o retorno é uma escolha explícita, feita rota a rota. A opção continua no mesmo lugar: se a sua operação precisa que o veículo volte ao depósito, é só ligar antes de criar a rota.
A escolha não é lembrada entre sessões, de propósito. Guardar a última seleção traria de volta o mesmo esquecimento, agora herdado do dia anterior — e invisível.
---
# Changelog (/docs/changelog)
Cada vez que lançamos algo novo, melhoramos um fluxo ou consertamos algo importante, registramos por aqui.
---
# Log (/docs/log)
---
# TMS — Visão Geral (/docs/tms)
# TMS [#tms]
Esta seção é voltada para sistemas de gestão de transporte (TMS) que integram com a Abbiamo para enviar rotas fechadas ao aplicativo do motorista (**Abbiamo Go**).
O fluxo garante que a inteligência de roteirização do TMS seja refletida fielmente no app: o TMS define a rota e escala o motorista; a Abbiamo recebe os dados e os exibe no aplicativo; o motorista executa a entrega; e a Abbiamo notifica o TMS sobre cada mudança de status.
***
## Autenticação [#autenticação]
Todas as requisições devem conter o header de autenticação do seller group:
| Header | Descrição |
| ---------------------------- | ------------------------------------------------------------------------- |
| `x-abbiamo-seller-group-key` | Chave fornecida pela Abbiamo para identificar e autorizar o seller group. |
* **Base URL:** `https://api.abbiamo.io`
* **Rate limit:** 1500 requisições a cada 5 minutos.
***
## Fluxo de integração [#fluxo-de-integração]
```
TMS → Abbiamo API → Abbiamo Go App
Define rota Cria pedidos Motorista visualiza
e motorista e vincula à e executa a rota
rota no app
← Webhooks
Notifica o TMS sobre
mudanças de status
```
***
## Criar rota com pedidos [#criar-rota-com-pedidos]
**`POST /v2/orders/route`**
Cria os pedidos e a rota de uma só vez, já vinculando o motorista. Limite de **50 pedidos por rota**.
Referência oficial: [Create route for new orders](/docs/api/routes/create-route-for-new-orders)
### Campos do objeto `orders[]` [#campos-do-objeto-orders]
| Campo | Tipo | Obrigatório | Descrição |
| ----------------------------------- | ------ | ----------- | ------------------------------------------------------------- |
| `order_number` | string | Sim | Identificador do pedido no TMS. |
| `seller_identifier` | string | Sim | CNPJ ou identificador da filial (seller) de origem do pedido. |
| `customer.name` | string | Sim | Nome do destinatário. |
| `destination_address.zip_code` | string | Sim | CEP do endereço de entrega (apenas números). |
| `destination_address.state` | string | Sim | UF do estado de entrega (ex: `SP`). |
| `destination_address.city` | string | Sim | Cidade de entrega. |
| `destination_address.street` | string | Sim | Logradouro de entrega. |
| `destination_address.street_number` | string | Sim | Número do endereço de entrega. |
### Campos do objeto `route` [#campos-do-objeto-route]
| Campo | Tipo | Obrigatório | Descrição |
| ------------------ | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `driver_document` | string | Não | CPF do motorista responsável pela rota. Se não informado, a rota é criada sem motorista e pode ser atribuída depois pelo dashboard. |
| `external_name` | string | Não | Nome externo da rota (identificador do TMS). |
| `orders_sequenced` | boolean | Não | Se `true`, a Abbiamo respeita a ordem exata do array `orders`. Use quando o TMS já definiu a sequência otimizada. |
| `start.type` | string | Não | Tipo do ponto de partida. Use `WAREHOUSE_SELLER_IDENTIFIER` para partir de uma filial. |
| `start.value` | string | Não | Identificador da filial de partida (CNPJ ou seller identifier). |
| `end.type` | string | Não | Tipo do ponto de chegada. Use `WAREHOUSE_SELLER_IDENTIFIER` para retornar a uma filial. |
| `end.value` | string | Não | Identificador da filial de chegada (CNPJ ou seller identifier). |
### Exemplo de requisição [#exemplo-de-requisição]
```json
{
"orders": [
{
"order_number": "PEDIDO-001",
"seller_identifier": "12345678000190",
"customer": { "name": "Cliente Exemplo" },
"destination_address": {
"zip_code": "01412100",
"state": "SP",
"city": "São Paulo",
"street": "Rua Exemplo",
"street_number": "100"
}
}
],
"route": {
"driver_document": "12345678909",
"external_name": "ROTA_SUL_0502",
"orders_sequenced": true,
"start": {
"type": "WAREHOUSE_SELLER_IDENTIFIER",
"value": "12345678000190"
},
"end": {
"type": "WAREHOUSE_SELLER_IDENTIFIER",
"value": "12345678000190"
}
}
}
```
### Exemplo de resposta [#exemplo-de-resposta]
```json
{
"status": "success",
"route": {
"id": "1d1dfa9c-4fe2-4315-9d65-ec0e8f95d239",
"cost": 1200
},
"orders": [
{
"id": "30c24480-8e45-4afa-af35-0231b460e9ed",
"order_number": "PEDIDO-001",
"tracking": "abc123#",
"already_exists": false,
"mail_label_link": "https://mail-label-api.abbiamo.io/mail-label/v1?trackings=abc123#",
"tracking_link": "http://meupedido.abbiamolog.com/abc123#"
}
]
}
```
O campo `already_exists` indica se o pedido já existia no sistema e foi apenas vinculado à rota (sem ser recriado).
***
## Trocar motorista da rota [#trocar-motorista-da-rota]
**`PATCH /v1/routes/{route_id}/change-driver`**
Atribui um novo motorista a uma rota já criada. A rota deve estar com status `CREATED`.
```json
{
"document_number": "12345678909"
}
```
Para mais detalhes, consulte a [referência completa de Rotas](/docs/tms/rotas).
***
## Cancelar rota [#cancelar-rota]
**`PUT /v1/routes/{route_id}`**
Cancela a rota. Os pedidos vinculados retornam ao estado pendente. A rota deve estar com status `CREATED`.
Para mais detalhes, consulte a [referência completa de Rotas](/docs/tms/rotas).
***
## Gestão de motoristas [#gestão-de-motoristas]
Motoristas são vinculados a uma ou mais filiais (sellers). Para que um motorista visualize rotas no app, ele precisa estar associado ao `seller_identifier` correto.
Os endpoints disponíveis são:
| Endpoint | Descrição |
| ----------------------------------- | -------------------------------------------- |
| `POST /v1/drivers` | Cria ou atualiza um motorista. |
| `GET /v1/drivers` | Lista motoristas do seller group (paginado). |
| `GET /v1/drivers/{document_number}` | Retorna os dados de um motorista específico. |
Para mais detalhes, consulte a [referência completa de Motoristas](/docs/tms/motoristas).
***
## Webhooks de status [#webhooks-de-status]
A cada mudança no status de um pedido, a Abbiamo envia um `POST` para a URL configurada no TMS.
| Status | Descrição |
| ---------------- | ------------------------------------------------ |
| `CREATED` | Pedido recebido no sistema. |
| `DISPATCHED` | Rota planejada e enviada ao app do motorista. |
| `START_DELIVERY` | Motorista iniciou o deslocamento para o cliente. |
| `SUCCESSFUL` | Entrega realizada com sucesso. |
| `FAILED` | Falha na entrega. |
***
## Regras de negócio [#regras-de-negócio]
* **Idempotência de pedidos:** se o `order_number` já existir e não estiver finalizado, a Abbiamo apenas vincula o pedido à nova rota, sem recriar.
* **Sequenciamento:** se o TMS já define a ordem otimizada, sempre envie `"orders_sequenced": true`.
* **Limite de rota:** rotas com mais de 50 pedidos não são aceitas.
* **Filiais (Sellers):** certifique-se de que as filiais foram criadas antes de criar rotas — o `seller_identifier` deve existir no seller group autenticado.
---
# API de Motoristas (/docs/tms/motoristas)
Todos os endpoints requerem o seguinte header:
| Header | Descrição |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| `x-abbiamo-seller-group-key` | Chave de autenticação usada para identificar e autorizar o seller group que está fazendo a requisição. |
***
## 1. Listar Motoristas [#1-listar-motoristas]
**`GET /v1/drivers`**
Retorna uma lista paginada de motoristas associados ao seller group autenticado. Os resultados são ordenados por data de criação, do mais recente para o mais antigo.
### Query Params [#query-params]
| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| ----------- | ------ | ----------- | ------ | -------------------------------------------------------------------- |
| `page` | string | Não | `1` | Número da página a ser retornada. |
| `page_size` | string | Não | `10` | Quantidade de motoristas por página. Valor máximo permitido é `100`. |
### Resposta — 200 OK [#resposta--200-ok]
```json
{
"page": 1,
"page_size": 10,
"total_pages": 3,
"has_next_page": true,
"total_results": 25,
"results": [
{
"id": "b3d2f1a0-4c5e-4f6d-8e9b-1a2b3c4d5e6f",
"name": "João Silva Santos",
"document_number": "12345678901",
"phone": "5511999999999",
"active": true,
"seller_identifiers": ["seller-sp-01", "seller-sp-02"]
}
]
}
```
### Erros [#erros]
| Status | Código | Descrição |
| ------ | ------------------ | --------------------------------------------- |
| 400 | `INVALID_PARAMS` | `page_size` excede o valor máximo de 100. |
| 404 | `SELLER_NOT_FOUND` | Nenhum seller encontrado para o seller group. |
***
## 2. Buscar Motorista por Documento [#2-buscar-motorista-por-documento]
**`GET /v1/drivers/:document_number`**
Retorna os dados de um único motorista. O motorista deve estar associado ao seller group autenticado.
### Path Params [#path-params]
| Parâmetro | Tipo | Obrigatório | Descrição |
| ----------------- | ------ | ----------- | ------------------------------------------- |
| `document_number` | string | Sim | Número do documento do motorista (ex: CPF). |
### Resposta — 200 OK [#resposta--200-ok-1]
```json
{
"id": "b3d2f1a0-4c5e-4f6d-8e9b-1a2b3c4d5e6f",
"name": "João Silva Santos",
"document_number": "12345678901",
"phone": "5511999999999",
"active": true,
"created_at": "2026-03-19T10:00:00.000Z",
"updated_at": "2026-03-19T10:00:00.000Z",
"seller_identifiers": ["seller-sp-01"]
}
```
### Erros [#erros-1]
| Status | Código | Descrição |
| ------ | ------------------ | --------------------------------------------------------- |
| 404 | `DRIVER_NOT_FOUND` | Motorista não encontrado. |
| 400 | `DRIVER_NOT_FOUND` | Motorista não possui sellers associados. |
| 400 | `DRIVER_NOT_FOUND` | Motorista não está associado ao seller group autenticado. |
***
## 3. Criar ou Atualizar Motorista [#3-criar-ou-atualizar-motorista]
**`POST /v1/drivers`**
Cria um novo motorista ou atualiza um existente dentro do seller group autenticado. O `document_number` é usado para determinar se é uma criação ou atualização. Os campos `name`, `phone` e `seller_identifiers` são obrigatórios. Na atualização, apenas motoristas já pertencentes ao seller group podem ser modificados.
### Body [#body]
| Campo | Tipo | Obrigatório | Descrição |
| -------------------- | --------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document_number` | string | Sim | Número do documento do motorista (apenas: CPF). Usado para identificar se é criação ou atualização. |
| `name` | string | Sim | Nome completo do motorista obrigatório. |
| `phone` | string | Sim | Número de telefone do motorista obrigatório. |
| `seller_identifiers` | string\[] | Apenas na criação | Lista de identificadores de sellers para associar ao motorista. Obrigatório na criação. Na atualização, adiciona os sellers informados às associações existentes do motorista dentro do seller group. Todos os identificadores devem pertencer ao seller group autenticado. |
| `password` | string | Não | Senha do motorista no aplicativo. Na criação é obrigatório para definir a senha inicial. Na atualização, substitui a senha atual mas não é obrigatório. |
### Resposta — 201 Created [#resposta--201-created]
```json
{
"id": "b3d2f1a0-4c5e-4f6d-8e9b-1a2b3c4d5e6f",
"name": "João Silva Santos",
"document_number": "12345678901",
"phone": "5511999999999",
"seller_identifiers": ["seller-sp-01", "seller-sp-02"],
"created_at": "2026-03-19T10:00:00.000Z",
"password": "senha123"
}
```
### Erros [#erros-2]
| Status | Código | Descrição |
| ------ | ------------------ | -------------------------------------------------------------- |
| 400 | `INVALID_PARAMS` | `name` ou `phone` não informados na criação. |
| 400 | `SELLER_NOT_FOUND` | `seller_identifiers` não informado na criação. |
| 400 | `SELLER_NOT_FOUND` | Um ou mais seller identifiers não encontrados no seller group. |
| 404 | `DRIVER_NOT_FOUND` | Motorista existe mas pertence a outro seller group. |
---
# API de Rotas (/docs/tms/rotas)
Todos os endpoints requerem o seguinte header:
| Header | Descrição |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| `x-abbiamo-seller-group-key` | Chave de autenticação usada para identificar e autorizar o seller group que está fazendo a requisição. |
***
## 1. Alterar Motorista da Rota [#1-alterar-motorista-da-rota]
**`PATCH /v1/routes/:route_id/change-driver`**
Atribui um motorista a uma rota existente dentro do seller group autenticado. A rota deve ter status `CREATED` e o motorista deve estar associado ao seller group.
### Path Params [#path-params]
| Parâmetro | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | ---------------------------- |
| `route_id` | string | Sim | Identificador único da rota. |
### Body [#body]
| Campo | Tipo | Obrigatório | Descrição |
| ----------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `document_number` | string | Sim | Número do documento do motorista a ser atribuído à rota. O motorista deve pertencer ao seller group autenticado. |
### Resposta — 200 OK [#resposta--200-ok]
```json
{
"driver_id": "b3d2f1a0-4c5e-4f6d-8e9b-1a2b3c4d5e6f",
"document_number": "12345678901",
"name": "João Silva Santos",
"route_id": "c4e5f6a7-8b9c-4d5e-6f7a-8b9c0d1e2f3a"
}
```
### Erros [#erros]
| Status | Código | Descrição |
| ------ | -------------------------- | ---------------------------------------------------------- |
| 400 | `INVALID_PARAMS` | `document_number` não informado. |
| 400 | `ROUTE_CANNOT_BE_MODIFIED` | Status da rota é diferente de `CREATED`. |
| 404 | `ROUTE_NOT_FOUND` | Rota não encontrada ou pertence a outro seller group. |
| 404 | `DRIVER_NOT_FOUND` | Motorista não encontrado ou pertence a outro seller group. |
***
## 2. Cancelar Rota [#2-cancelar-rota]
**`PUT /v1/routes/:route_id`**
Cancela uma rota existente dentro do seller group autenticado. A rota deve ter status `CREATED` para ser elegível ao cancelamento.
### Path Params [#path-params-1]
| Parâmetro | Tipo | Obrigatório | Descrição |
| ---------- | ------ | ----------- | -------------------------------------------- |
| `route_id` | string | Sim | Identificador único da rota a ser cancelada. |
### Resposta — 200 OK [#resposta--200-ok-1]
```json
{
"route_id": "c4e5f6a7-8b9c-4d5e-6f7a-8b9c0d1e2f3a",
"cancelled_at": "2026-03-19T10:00:00.000Z"
}
```
### Erros [#erros-1]
| Status | Código | Descrição |
| ------ | -------------------------- | ----------------------------------------------------- |
| 400 | `ROUTE_CANNOT_BE_MODIFIED` | Status da rota é diferente de `CREATED`. |
| 404 | `ROUTE_NOT_FOUND` | Rota não encontrada ou pertence a outro seller group. |
---
# Homologação (/docs/transportadora/homologacao)
A **homologação** é a etapa final de validação da sua integração com a Abbiamo antes de entrar em produção. Consiste em uma reunião guiada onde os **5 fluxos operacionais** da integração são simulados em ambiente de testes para garantir que tudo está funcionando corretamente.
***
## Pré-requisitos (antes da reunião) [#pré-requisitos-antes-da-reunião]
Dois pontos são **obrigatórios** antes de agendar a reunião de homologação. Se algum deles não estiver cumprido, a reunião será reagendada.
### 1. Webhooks cadastrados [#1-webhooks-cadastrados]
Você deve ter cadastrado os dois webhooks abaixo via API antes da reunião. Sem eles, não é possível receber pedidos nem cancelamentos.
| Webhook | Descrição | Documentação |
| ---------------------- | ---------------------------------------------------------- | --------------------------------------------------------- |
| `delivery_request` | Recebe o pedido quando a Abbiamo solicita a coleta | [ver payload](/docs/api/carrier-integration/deliveries) |
| `cancellation_request` | Recebe o cancelamento quando o embarcador cancela o pedido | [ver payload](/docs/api/carrier-integration/cancellation) |
→ [Como cadastrar webhooks](/docs/api/carrier-integration/list-webhooks)
### 2. Evidência de teste realizado no dia [#2-evidência-de-teste-realizado-no-dia]
Você deve enviar ao menos **uma evidência de que testou sua integração no dia da reunião** — print, log, registro de chamada de endpoint ou similar.
***
## Preparação do ambiente de testes [#preparação-do-ambiente-de-testes]
Com os pré-requisitos confirmados, verifique se seu ambiente de testes está operacional e com pedidos disponíveis para simular os fluxos. Serão usados **5 pedidos** — um por fluxo.
***
## Os 5 fluxos validados [#os-5-fluxos-validados]
A referência oficial dos fluxos está em: [Carrier Homologation](/docs/api/carrier-integration/homologation)
***
### Fluxo 1 — Padrão (Standard) [#fluxo-1--padrão-standard]
O fluxo esperado na grande maioria das entregas. Um pedido é enviado e percorre todos os status obrigatórios.
**Status obrigatórios (na ordem operacional):**
| Status | Endpoint |
| ------------------------ | ----------------- |
| Transportadora confirmou | `/confirmed` |
| Em rota | `/start-delivery` |
| Sucesso na entrega | `/successful` |
| Falha na entrega | `/failed` |
| Falha na solicitação | `/order-failed` |
| Devolvido | `/returned` |
***
### Fluxo 2 — Nova Requisição (New Request) [#fluxo-2--nova-requisição-new-request]
Utilizado quando a Abbiamo precisa cancelar a entrega e fazer uma **nova solicitação para o mesmo pedido**.
**Quem cancela:** a Abbiamo, pelo dashboard.
Sua integração deve ser capaz de receber o cancelamento e aceitar um novo `delivery_request` para o mesmo pedido **sem erros**.
***
### Fluxo 3 — Cancelamento (Cancellation) [#fluxo-3--cancelamento-cancellation]
Utilizado quando a **transportadora** perde ou extravia o pedido.
**Quem cancela:** a própria transportadora.
A sequência obrigatória é:
```
/failed → /canceled
```
***
### Fluxo 4 — Devolução (Return) [#fluxo-4--devolução-return]
Fluxo de retorno do item ao remetente após falha na entrega.
```
/failed → /returning-delivery → /returned
```
***
### Fluxo 5 — Segunda Tentativa (Second Attempt) [#fluxo-5--segunda-tentativa-second-attempt]
Nova tentativa de entrega após falha na primeira.
```
/failed → /start-delivery → /successful
```
***
## Validações técnicas [#validações-técnicas]
Durante a execução dos fluxos, os seguintes pontos são verificados:
### 1. Campo `event_at` com precisão de milissegundos [#1-campo-event_at-com-precisão-de-milissegundos]
Todas as atualizações de status devem incluir `event_at` com **hora, minuto, segundo e milissegundos**.
| ✅ Correto | ❌ Incorreto |
| -------------------------- | ---------------------- |
| `2024-01-15T14:30:45.123Z` | `2024-01-15T14:30:45Z` |
Se dois eventos chegarem dentro do mesmo segundo sem precisão de milissegundos, a ordenação fica ambígua e ocorre erro.
### 2. Cada endpoint chamado apenas uma vez por evento [#2-cada-endpoint-chamado-apenas-uma-vez-por-evento]
Cada endpoint de atualização de status deve ser chamado **uma única vez** por evento. Chamadas duplicadas (2× ou mais no mesmo endpoint para o mesmo pedido) indicam problema de retry sem idempotência na implementação.
### 3. Fluxo de status em ordem operacional [#3-fluxo-de-status-em-ordem-operacional]
Os status devem ser enviados na sequência lógica da operação. Enviar `/successful` antes de `/start-delivery`, por exemplo, gera inconsistência no rastreio do cliente final.
***
## Checklist [#checklist]
### Antes da reunião [#antes-da-reunião]
* [ ] Webhook `delivery_request` cadastrado e testado
* [ ] Webhook `cancellation_request` cadastrado e testado
* [ ] Evidência de teste realizado **no dia** enviada para a Abbiamo
* [ ] Ambiente de testes com pedidos disponíveis
### Durante a reunião [#durante-a-reunião]
* [ ] **Fluxo 1 (Padrão):** `/confirmed` chamado dentro de 30 min após envio
* [ ] **Fluxo 1 (Padrão):** todos os status obrigatórios atualizados na ordem correta
* [ ] **Fluxo 2 (Nova Requisição):** Abbiamo cancelou pelo dashboard; novo `delivery_request` aceito sem erros
* [ ] **Fluxo 3 (Cancelamento):** transportadora enviou `/failed` + `/canceled`
* [ ] **Fluxo 4 (Devolução):** sequência `/failed → /returning-delivery → /returned` validada
* [ ] **Fluxo 5 (Segunda Tentativa):** sequência `/failed → /start-delivery → /successful` validada
* [ ] `event_at` com milissegundos em todas as atualizações
* [ ] Nenhum endpoint chamado mais de uma vez por evento
***
## Referências [#referências]
* [Carrier Homologation — API Reference](/docs/api/carrier-integration/homologation)
* [Delivery Request — payload completo](/docs/api/carrier-integration/deliveries)
* [Cancellation Request — payload completo](/docs/api/carrier-integration/cancellation)
* [Gerenciar webhooks](/docs/api/carrier-integration/list-webhooks)
---
# Transportadora — Visão Geral (/docs/transportadora)
# Transportadora [#transportadora]
Esta seção é voltada para transportadoras que usam a API pública da Abbiamo para receber solicitações de entrega, receber solicitações de cancelamento e atualizar status operacionais.
Considere a documentação oficial como fonte de verdade para contratos e campos: [Welcome Carrier](/docs/api/carrier-integration/welcome-carrier).
## Responsabilidades da transportadora [#responsabilidades-da-transportadora]
* Consumir o webhook `DELIVERY_REQUEST` e processar o payload recebido, conforme a documentação oficial: [Delivery request](/docs/api/carrier-integration/deliveries).
* Consumir o webhook `CANCELLATION_REQUEST` e interromper a operação quando aplicável, conforme a documentação oficial: [Cancellation request](/docs/api/carrier-integration/cancellation).
* Respeitar as configurações operacionais enviadas no `logistic_data`, inclusive o desejo do cliente de usar pincode de coleta; veja o [Quick Guide - Código de Coleta](/docs/transportadora/quick-guide-codigo-coleta/).
* Reportar status no endpoint correto e na ordem operacional adequada.
* Garantir consistência temporal dos eventos (`event_at` sem repetição para eventos sequenciais).
***
## Referências oficiais [#referências-oficiais]
* [Welcome Carrier](/docs/api/carrier-integration/welcome-carrier)
* [Delivery request (webhook)](/docs/api/carrier-integration/deliveries)
* [Cancellation request (webhook)](/docs/api/carrier-integration/cancellation)
---
# Transportadora — Quick Guide - Código de Coleta (/docs/transportadora/quick-guide-codigo-coleta)
# Quick Guide - Código de Coleta [#quick-guide---código-de-coleta]
Este guia explica especificamente **quando informar** `collect_verification_code` nos endpoints de status da API de transportadoras.
## Quando informar o `collect_verification_code` [#quando-informar-o-collect_verification_code]
Você **pode** enviar `collect_verification_code` nos endpoints de status:
* [At Pickup Point](/docs/api/carrier-integration/at-pickup-point)
* [Collecting Delivery](/docs/api/carrier-integration/carrier-collecting-delivery)
* [Confirm Delivery](/docs/api/carrier-integration/carrier-confirm-delivery)
* [Failed to Collect](/docs/api/carrier-integration/carrier-failed-to-collect)
* [Searching Driver](/docs/api/carrier-integration/carrier-searching-driver)
Mas esse campo só deve ser enviado quando o webhook de entrega indicar que verificação por código está habilitada, isto é:
* `logistic_data.pickup_verification.pincode = true`
### Regra prática [#regra-prática]
1. Receba o webhook [Delivery request](/docs/api/carrier-integration/deliveries).
2. Leia `logistic_data.pickup_verification.pincode`.
3. Se for `true`, inclua `collect_verification_code` nas chamadas de status permitidas.
4. Se for `false` (ou ausente), **não envie** `collect_verification_code`.
### Exemplo mínimo do webhook (campo relevante) [#exemplo-mínimo-do-webhook-campo-relevante]
Este payload é uma **simplificação** apenas para destacar os campos necessários nesta regra. O payload completo possui mais campos na documentação oficial.
```jsonc
{
"event_type": "DELIVERY_REQUEST",
// ... outros campos
"seller": {
// ... outros campos
},
"carrier": {
// ... outros campos
},
"deliveries": [
{
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"content_declaration": {
"key": "35200000000000000000000000000000000000000000",
"serie": "001",
"number": "000000780"
}
// ... outros campos da entrega
}
],
"logistic_data": {
// ... outros campos de logística
"pickup_verification": {
"pincode": true
}
}
}
```
### Exemplo de status com código (quando `pincode = true`) [#exemplo-de-status-com-código-quando-pincode--true]
```json
{
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"event_at": "2026-03-13T15:10:00.000Z",
"collect_verification_code": "123456"
}
```
### Exemplo de status sem código (quando `pincode = false`) [#exemplo-de-status-sem-código-quando-pincode--false]
```json
{
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"event_at": "2026-03-13T15:10:00.000Z"
}
```
***
## Referências oficiais [#referências-oficiais]
* [Delivery request (webhook)](/docs/api/carrier-integration/deliveries)
* [At Pickup Point](/docs/api/carrier-integration/at-pickup-point)
* [Collecting Delivery](/docs/api/carrier-integration/carrier-collecting-delivery)
* [Confirm Delivery](/docs/api/carrier-integration/carrier-confirm-delivery)
* [Failed to Collect](/docs/api/carrier-integration/carrier-failed-to-collect)
* [Searching Driver](/docs/api/carrier-integration/carrier-searching-driver)
---
# Pesquisa de Satisfação (/docs/tracking/csat)
A página de rastreamento inclui uma **pesquisa de satisfação (CSAT/NPS)** integrada ao final do fluxo de cada tipo de pedido.
## Quando a pesquisa aparece [#quando-a-pesquisa-aparece]
| Tipo de pedido | Momento | Pré-condição |
| ------------------ | --------------------------------------------- | ----------------------------- |
| **Entrega** | Após o cliente confirmar que recebeu o pedido | Pesquisa ainda não respondida |
| **Retirada** | Imediatamente quando o status é "Retirado" | Pesquisa ainda não respondida |
| **Coleta reversa** | Imediatamente quando o status é "Devolvido" | Sempre exibida |
## Confirmação de entrega (somente entregas) [#confirmação-de-entrega-somente-entregas]
Antes da pesquisa, o cliente vê uma pergunta de confirmação:
* **"Sim, recebi"** — marca o recebimento e exibe a pesquisa de satisfação
* **"Não recebi"** — abre um campo de texto para relatar o problema. Após o envio, exibe "Recebemos seu relato"
## Escala de avaliação [#escala-de-avaliação]
A pesquisa utiliza uma escala **NPS de 0 a 10**:
| Faixa | Classificação | Cor |
| ----- | ------------- | ---------------- |
| 0–6 | Detrator | Vermelho → âmbar |
| 7–8 | Neutro | Âmbar |
| 9–10 | Promotor | Verde |
## Comentário opcional [#comentário-opcional]
Após selecionar a nota, o cliente pode adicionar um **comentário em texto livre** para detalhar sua experiência.
## Após o envio [#após-o-envio]
A pesquisa exibe uma mensagem de confirmação: **"Obrigado pela sua avaliação!"**
A pesquisa é exibida uma única vez por pedido. Após o envio, não aparece novamente.
---
# Relatar Problema (/docs/tracking/disputas)
A página de rastreamento permite que o consumidor **relate problemas** relacionados à entrega diretamente pela interface, sem precisar entrar em contato por outros canais.
## Como funciona [#como-funciona]
Quando o consumidor identifica um problema com a entrega, ele pode reportar diretamente pela página de rastreamento informando:
| Campo | Descrição | Obrigatório |
| ------------ | ----------------------------------------------------------- | ----------- |
| **Motivo** | Categoria do problema (ex.: não recebi, produto danificado) | Não |
| **Detalhes** | Descrição adicional em texto livre | Não |
Após o envio, o relato é encaminhado automaticamente para a equipe de suporte do embarcador.
## Exemplos de problemas [#exemplos-de-problemas]
* Pacote não recebido
* Produto danificado
* Produto incorreto
* Entrega atrasada
* Entrega em endereço errado
---
# Tracking (/docs/tracking)
A **página de rastreamento** é a interface que o consumidor final utiliza para acompanhar pedidos em tempo real. Ela é acessada por meio de um link único (token) enviado pelo embarcador ou pela transportadora.
## Tipos de pedido [#tipos-de-pedido]
A página se adapta automaticamente ao tipo de pedido:
| Tipo | Descrição | Fluxo |
| ---------------------------- | ------------------------------------------------------------ | ---------------------- |
| **Entrega** (Delivery) | Entrega padrão no endereço do cliente | Loja → Cliente |
| **Retirada** (Takeout) | Cliente retira na loja ou ponto de coleta | Cliente vai até a loja |
| **Coleta reversa** (Reverse) | Logística reversa — item coletado do cliente de volta à loja | Cliente → Loja |
## Funcionalidades principais [#funcionalidades-principais]
Mapa interativo com posição do motorista, rota estimada e progresso da entrega.
Previsão de entrega atualizada em tempo real. Indica atrasos quando a previsão é ultrapassada.
Cores, logo e identidade visual do embarcador aplicados automaticamente na página.
Pesquisa NPS integrada ao final do fluxo de entrega, retirada ou coleta.
Lista de itens do pedido exibida na página para o consumidor saber o que está sendo entregue.
Canal direto para o consumidor reportar problemas de entrega pela página de tracking.
## Como funciona [#como-funciona]
```
Link de rastreamento
→ Identificação do tipo de pedido
→ Exibição do status atual e etapas
→ Mapa com localização em tempo real
→ Código de verificação (quando aplicável)
→ Confirmação de entrega + pesquisa de satisfação
```
A página é atualizada automaticamente a cada 60 segundos, sem necessidade de recarregar manualmente.
## Acesso [#acesso]
O consumidor acessa a página de rastreamento por um link no formato:
```
https://rastreios.net/track/{token}
```
O token é único por pedido e é gerado automaticamente pela plataforma.
## Comparativo entre tipos [#comparativo-entre-tipos]
| Aspecto | Entrega | Retirada | Coleta reversa |
| -------------------------- | ---------------------------- | ----------------------------- | -------------------------- |
| **Mapa** | Origem → Motorista → Destino | Localização da loja | Cliente → Motorista → Loja |
| **Etapas** | 5 ou 6 etapas | Baseado em status (3 estados) | 5 etapas |
| **Código de verificação** | Pincode no mapa | QR code para retirada | — |
| **Fila de entrega** | Sim | — | Sim |
| **Comprovante de entrega** | Sim | Sim | — |
| **Pesquisa de satisfação** | Após confirmar recebimento | Após retirar | Após devolução |
| **Produtos do pedido** | Sim | Sim | Sim |
| **Relatar problema** | Sim | Sim | Sim |
## Próximos passos [#próximos-passos]
* [Status e etapas](/docs/tracking/status-e-etapas/) — entenda cada status e o pipeline de etapas
* [Mapa e ETA](/docs/tracking/mapa-e-eta/) — como funciona o mapa e a previsão de entrega
* [Personalização](/docs/tracking/personalizacao/) — como a marca do embarcador é aplicada
* [Verificação e comprovante](/docs/tracking/verificacao/) — códigos de verificação e comprovante de entrega
* [Pesquisa de satisfação](/docs/tracking/csat/) — pesquisa NPS integrada
* [Produtos do pedido](/docs/tracking/produtos/) — lista de itens do pedido na página
* [Relatar problema](/docs/tracking/disputas/) — canal direto para reportar problemas
---
# Mapa e ETA (/docs/tracking/mapa-e-eta)
## Mapa de rastreamento [#mapa-de-rastreamento]
A página exibe um mapa interativo que mostra a posição do motorista e o progresso da entrega em tempo real.
### Marcadores no mapa [#marcadores-no-mapa]
| Marcador | Cor | Descrição |
| ------------- | ----- | --------------------------------------------------- |
| **Origem** | Azul | Localização do armazém ou loja |
| **Motorista** | Âmbar | Posição atual do entregador (com animação de pulso) |
| **Destino** | Verde | Endereço de entrega do cliente |
### Rota [#rota]
O mapa traça a rota entre origem e destino. Quando disponível, a rota segue as vias reais. Caso contrário, exibe uma linha reta como fallback.
* **Trecho percorrido**: linha sólida azul (verde quando entregue)
* **Trecho restante**: linha tracejada cinza
### Barra de progresso [#barra-de-progresso]
Abaixo do mapa, uma barra de progresso mostra visualmente o quanto da rota já foi percorrido, com base na distância entre o motorista e os pontos de origem e destino.
### Indicador "Ao vivo" [#indicador-ao-vivo]
| Condição | Indicador |
| ---------------------------------------------- | ----------------------------------- |
| Atualização do motorista há menos de 2 minutos | Ponto verde animado + "Ao vivo" |
| Atualização há mais de 2 minutos | Ponto cinza + "Atualizado há X min" |
| Pedido entregue | Oculto |
### Comportamento por tipo de pedido [#comportamento-por-tipo-de-pedido]
| Recurso | Entrega | Retirada | Coleta reversa |
| ------------------------- | -------------------------- | ------------- | -------------------------- |
| Marcador de origem | Loja/armazém | Loja | Endereço do cliente |
| Marcador do motorista | Sim | — | Sim |
| Marcador de destino | Endereço do cliente | — | Loja |
| Rota rodoviária | Sim | — | Sim |
| Geolocalização do usuário | — | Sim | — |
| Estado padrão | Aberto (fecha ao entregar) | Sempre aberto | Aberto (fecha ao devolver) |
***
## Previsão de entrega (ETA) [#previsão-de-entrega-eta]
A página exibe a previsão de entrega com base no status atual do pedido.
### Antes de sair para entrega [#antes-de-sair-para-entrega]
A previsão é baseada na data prometida pelo embarcador ou transportadora. Quando nenhuma previsão está disponível, exibe "Aguardando previsão".
### Após sair para entrega [#após-sair-para-entrega]
A previsão é calculada em tempo real pela engine de rotas, com base na posição do motorista.
### Formatação [#formatação]
| Situação | Exibição |
| ----------------------- | ------------------------------ |
| Entregue | "Entregue em 1 de abr · 14:30" |
| Em trânsito, ETA hoje | "Hoje · até 18:00" |
| Em trânsito, ETA futuro | "5 de abr · até 14:00" |
| Sem previsão | "Aguardando previsão" |
### Atraso [#atraso]
Quando a previsão de entrega é ultrapassada em mais de 1 hora:
* O rótulo muda para **"Entrega atrasada"** em vermelho
* A previsão original é exibida abaixo
* Se já entregue com atraso, mostra "Previsão original: ..." abaixo da data de entrega
***
## Fila de entrega [#fila-de-entrega]
Quando o motorista tem múltiplas entregas, a página exibe a posição na fila:
| Posição | Mensagem |
| ------- | ------------------------- |
| 1 | "Você é o próximo!" |
| 2 | "Quase lá!" |
| 3 | "Aguenta firme!" |
| 4+ | "X entregas antes da sua" |
---
# Personalização (/docs/tracking/personalizacao)
A página de rastreamento aplica automaticamente a identidade visual configurada na plataforma Abbiamo. Isso inclui cores, logo e links de suporte.
## Elementos personalizáveis [#elementos-personalizáveis]
| Elemento | Descrição |
| ------------------------ | ---------------------------------------------------------- |
| **Cor primária** | Botões, barra de progresso, ícones e indicadores de status |
| **Cor secundária** | Fundo de cards e detalhes visuais |
| **Logo** | Exibido no topo da página |
| **Cor de fundo do logo** | Fundo atrás da imagem do logo |
| **Favicon** | Ícone da aba do navegador |
| **Link de ajuda** | URL de suporte exibido como "Ajuda" na página |
## Como funciona [#como-funciona]
1. A plataforma envia as configurações de tema junto com os dados do pedido
2. A página aplica as cores como variáveis CSS
3. O logo é exibido no cabeçalho com o fundo configurado
4. Opcionalmente, cores complementares são extraídas do logo para enriquecer a paleta
## Cor primária [#cor-primária]
A cor primária é usada em:
* Botões e elementos interativos
* Barra de progresso das etapas
* Ícones de status e marcadores no mapa
* Faixa superior do card principal
## Transportadora com frota própria [#transportadora-com-frota-própria]
Quando o pedido é entregue por frota própria, a página exibe o nome e o logo configurados no tema do embarcador, em vez das informações da transportadora.
## Paleta do logo [#paleta-do-logo]
A página pode extrair cores adicionais do logo para complementar a identidade visual:
* **Cor de destaque**: extraída para variações mais claras
* **Cor secundária**: extraída quando não configurada manualmente
Isso acontece de forma transparente e automática.
---
# Produtos do Pedido (/docs/tracking/produtos)
A página de rastreamento exibe a **lista de produtos** do pedido, permitindo que o consumidor saiba exatamente o que está sendo entregue, retirado ou devolvido.
## O que é exibido [#o-que-é-exibido]
Cada produto mostra:
| Elemento | Descrição |
| ------------------- | ------------------------------------------------------------------ |
| **Foto do produto** | Miniatura da imagem cadastrada (fallback: ícone genérico de caixa) |
| **Nome do produto** | Nome completo do item |
| **Variante** | Detalhes como tamanho, cor ou modelo (ex.: "Tamanho M · Azul") |
| **Quantidade** | Badge com a quantidade do item no pedido |
## Comportamento [#comportamento]
* A seção mostra um badge com a quantidade total de itens (ex.: "3 itens")
* Se o pedido não tiver produtos cadastrados, a seção não é exibida
* As imagens são otimizadas automaticamente para carregamento rápido em dispositivos móveis
## Disponibilidade [#disponibilidade]
| Tipo de pedido | Produtos exibidos |
| -------------- | ----------------- |
| Entrega | Sim |
| Retirada | Sim |
| Coleta reversa | Sim |
---
# Status e Etapas (/docs/tracking/status-e-etapas)
## Entrega [#entrega]
### Status [#status]
| Status | Descrição | Cor |
| --------------------- | -------------------------------------------- | -------- |
| **Pedido criado** | O pedido foi registrado e está em preparação | Cinza |
| **Despachado** | A transportadora confirmou o recebimento | Azul |
| **Em trânsito** | O pacote está em deslocamento | Âmbar |
| **Saiu para entrega** | O entregador está a caminho do destino | Violeta |
| **Entregue** | Pedido entregue com sucesso | Verde |
| **Falha na entrega** | Não foi possível concluir a entrega | Vermelho |
### Pipeline de etapas [#pipeline-de-etapas]
A página detecta automaticamente o tipo de entrega e exibe o pipeline adequado:
**Entrega last-mile** (5 etapas) — frota própria, entregas urbanas:
1. Pedido criado
2. Despachado
3. Coletado
4. Saiu para entrega
5. Entregue
**Entrega nacional** (6 etapas) — transportadoras com transferência entre bases:
1. Pedido criado
2. Despachado
3. Coletado
4. Em trânsito
5. Saiu para entrega
6. Entregue
### Falha na entrega [#falha-na-entrega]
Quando ocorre falha, a última etapa exibe:
* O rótulo **"Falha na entrega"** em vermelho
* A observação da transportadora sobre o motivo (quando disponível)
* A barra de progresso fica vermelha na etapa final
***
## Retirada (Takeout) [#retirada-takeout]
A retirada não usa pipeline de etapas — exibe status com ícones animados:
| Status | Descrição | Ícone |
| ------------------------- | -------------------------------- | ------------ |
| **Preparando seu pedido** | O pedido está sendo preparado | Sol âmbar |
| **Pronto para retirada** | Disponível para retirada na loja | Sacola verde |
| **Retirado** | O cliente já retirou o pedido | Check verde |
***
## Coleta reversa (Reverse) [#coleta-reversa-reverse]
### Status [#status-1]
| Status | Descrição |
| ---------------------- | ------------------------------------- |
| **Coleta criada** | Aguardando processamento |
| **Despachado** | Motorista designado |
| **A caminho** | Motorista indo ao endereço do cliente |
| **No local de coleta** | Motorista chegou ao endereço |
| **Coletado** | Item coletado com sucesso |
| **Devolvido** | Entregue ao remetente |
| **Falha na coleta** | Não foi possível concluir a coleta |
### Pipeline de etapas (5 etapas) [#pipeline-de-etapas-5-etapas]
1. Coleta criada
2. Despachado
3. A caminho
4. Coletado
5. Devolvido
***
## Linha do tempo [#linha-do-tempo]
Todos os tipos de pedido exibem uma **linha do tempo** (tracking history) com o histórico completo de eventos. Cada evento mostra:
* O status e a descrição
* Data e hora do evento
* Observações da transportadora (quando disponíveis)
---
# Verificação e Comprovante (/docs/tracking/verificacao)
A página de rastreamento oferece mecanismos de verificação para garantir a segurança da entrega e o acesso ao comprovante.
## Código de verificação (Entrega) [#código-de-verificação-entrega]
Para entregas que exigem confirmação, a página exibe um **código de verificação** (pincode) como uma pílula flutuante sobre o mapa.
* O código é alfanumérico (ex.: `A3X7K2`)
* O cliente deve apresentar este código ao entregador para concluir a entrega
* É possível copiar o código com um clique
* O código fica oculto após a entrega ser concluída
## QR Code (Retirada) [#qr-code-retirada]
Para pedidos de retirada, a página exibe um **QR code** que o cliente apresenta na loja:
* Acessível por um botão na tela de rastreamento
* Pode ser reenviado ao cliente (com intervalo mínimo de 60 segundos entre reenvios)
* Usado para validar a retirada no ponto de coleta
***
## Comprovante de entrega (POD) [#comprovante-de-entrega-pod]
Após a entrega ou retirada, o cliente pode acessar o **comprovante de entrega** (Proof of Delivery) diretamente na página de rastreamento.
### Verificação de identidade [#verificação-de-identidade]
Para proteger os dados do comprovante, o acesso exige verificação de identidade:
| Método | Como funciona |
| ------------ | ------------------------------------------------ |
| **CPF** | Cliente informa os primeiros 5 dígitos do CPF |
| **Telefone** | Cliente informa os últimos 4 dígitos do telefone |
### Dados do comprovante [#dados-do-comprovante]
Após a verificação, o comprovante exibe:
* **Nome do recebedor** — quem recebeu o pacote
* **Documento do recebedor** — CPF
* **Observação** — notas da transportadora (ex.: "Entregue na portaria")
* **Fotos e assinatura** — imagens de comprovação (clique para ampliar)
### Disponibilidade por tipo de pedido [#disponibilidade-por-tipo-de-pedido]
| Tipo | Comprovante disponível |
| -------------- | ---------------------- |
| Entrega | Sim — após a entrega |
| Retirada | Sim — após a retirada |
| Coleta reversa | Não disponível |
---
# Criar/atualizar motoristas (/docs/api/drivers/create-drivers)
{/* concept-backlink */}
Gestão de motoristas: [Motoristas (Frota Própria)](/docs/go/products/motoristas).
---
# Consultar motorista (/docs/api/drivers/get-driver)
{/* concept-backlink */}
Gestão de motoristas: [Motoristas (Frota Própria)](/docs/go/products/motoristas).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
---
# Listar motoristas (/docs/api/drivers/get-drivers)
{/* concept-backlink */}
Gestão de motoristas: [Motoristas (Frota Própria)](/docs/go/products/motoristas).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
---
# Motoristas (Drivers) (/docs/api/drivers)
---
# Autenticação (/docs/api/conceitos/authentication)
Todos os endpoints desta documentação exigem o header `x-abbiamo-seller-group-key` para serem chamados. Essa API Key é criada junto com a sua conta na Abbiamo — se você ainda não tem conta, fala com a gente em [contato@abbiamolog.com](mailto:contato@abbiamolog.com).
Depois que a conta estiver criada, o administrador da conta consegue copiar a chave em [dashboard.abbiamolog.com/settings/tokens](https://dashboard.abbiamolog.com/settings/tokens).
Toda página de endpoint mostra um alerta laranja lembrando do header obrigatório:
**Header obrigatório.** O header `x-abbiamo-seller-group-key` é obrigatório em todas as chamadas. Preencha-o no canto superior direito da página de cada endpoint para testar no playground.
**Essa API Key é só para integração de sistemas.** Se você está procurando como entrar no painel Abbiamo (login de usuário), veja [Login Unificado](/docs/log/conceitos/login/) — o acesso ao painel é feito por email e senha, não pela API Key.
---
# Países (/docs/api/conceitos/country-attributes)
A Abbiamo opera nos seguintes países. Use o **código Alpha-3** quando algum endpoint pedir referência de país, e atente-se ao **timezone** ao interpretar `created_at`, `delivered_at` e demais campos de data.
| País | Código Alpha-3 | Timezone |
| -------------- | -------------- | -------------------------------- |
| 🇦🇷 Argentina | `ARG` | `America/Argentina/Buenos_Aires` |
| 🇧🇷 Brasil | `BRA` | `America/Sao_Paulo` |
| 🇨🇱 Chile | `CHL` | `America/Santiago` |
| 🇨🇴 Colômbia | `COL` | `America/Bogota` |
| 🇲🇽 México | `MEX` | `America/Mexico_City` |
| 🇵🇪 Peru | `PER` | `America/Lima` |
---
# Conceitos (/docs/api/conceitos)
---
# Limite de Requisições (/docs/api/conceitos/rate-limit)
Todos os endpoints compartilham o mesmo rate limit por API Key (`x-abbiamo-seller-group-key`). O limite é de **300 requisições por minuto**.
Se você passar desse limite, a API responde com **HTTP 429 (Too Many Requests)**. Pra evitar isso, considere adicionar delays/retries com backoff no seu cliente, principalmente em scripts que fazem muitas chamadas em rajada.
Todas as páginas de endpoint mostram esse limite no topo como lembrete.
---
# Primeiros passos (/docs/api/guias/getting-started)
Estas páginas cobrem **fluxos operacionais de ponta a ponta** para integração com a Abbiamo. Para os contratos brutos da API (endpoints, payloads, eventos de status), acesse diretamente a [API Reference](/docs/api/carrier-integration/welcome-carrier).
## Por onde começar [#por-onde-começar]
* **Embarcadores** — comece pela [API Reference de Pedidos](/docs/api/orders/create-order-v2) para aprender a criar entregas pela Abbiamo.
* **Transportadoras** — comece por [Boas-vindas à transportadora](/docs/api/carrier-integration/welcome-carrier) para o fluxo de onboarding da integração (registro de webhooks, atualizações de status, homologação).
## Guias operacionais [#guias-operacionais]
* [Clique e Retire — material de retirada por filial](/docs/api/guias/retira-clique-e-retire) — como gerar o QR Code estático e o PDF de instruções de retirada de cada filial, além da jornada de autoatendimento de retirada de ponta a ponta.
* [Pickup pincode — fluxo filial para motorista](/docs/api/guias/pickup-pincode-seller-to-driver) — o modelo tradicional em que a transportadora é dona do PIN e o operador da loja repassa ao motorista no momento da coleta. Já em produção.
* [Pickup pincode — fluxo motorista para filial](/docs/api/guias/pickup-pincode-driver-to-seller) — o modelo mais recente em que a Abbiamo é dona do PIN, o motorista o exibe ao operador, e a Abbiamo valida a coleta. Opt-in por integração embarcador × transportadora.
* [Mensageria via webhook — notificando o cliente](/docs/api/guias/mensageria-via-webhook) — como usar os eventos `ORDER_STATUS_CHANGE` e `TOKEN_GENERATED` para disparar mensagens ao cliente em cada etapa do pedido (entrega e retirada).
Para a referência conceitual do lado da transportadora e os contratos de cada modelo, consulte [Pickup pincode](/docs/api/carrier-integration/pickup-pincode) na API Reference.
---
# Guias operacionais (/docs/api/guias)
---
# Mensageria via webhook — notificando o cliente (/docs/api/guias/mensageria-via-webhook)
A Abbiamo entrega atualizações em tempo real de cada pedido via webhook. Este guia mostra como usar esses eventos para disparar mensagens ao cliente — por WhatsApp, SMS, e-mail ou qualquer canal — em cada etapa do ciclo de vida do pedido.
Para o contrato completo de cada evento (campos, payloads, exemplos por status), consulte a referência dos webhooks: [ORDER\_STATUS\_CHANGE](/docs/api/webhook/order-status-change) e [TOKEN\_GENERATED](/docs/api/webhook/token-generated).
## Quem faz o quê [#quem-faz-o-quê]
| Ator | Responsabilidade |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| **Abbiamo** | Dispara os eventos de webhook a cada mudança de status do pedido e a cada geração de token de retirada. |
| **Embarcador** | Recebe os eventos, extrai os dados relevantes (tracking, token) e aciona o canal de mensageria escolhido. |
| **Cliente** | Recebe as mensagens e acompanha o pedido via link de rastreio ou usa o código de retirada na loja. |
## Link de rastreio [#link-de-rastreio]
O link de rastreio tem uma parte fixa e uma parte variável — o código de rastreio (`tracking`) enviado em todos os eventos `ORDER_STATUS_CHANGE`:
```
https://rastreios.net/track/{tracking}
```
Para pedidos de **entrega**, o link exibe posição do motorista, ETA e histórico de status.
Para pedidos de **retirada**, o link exibe localização da loja, endereço completo e distância estimada até a filial.
***
## Pedidos de entrega (`order_type: DELIVERY`) [#pedidos-de-entrega-order_type-delivery]
Os três gatilhos mais usados para mensageria em entregas:
| Status no webhook | Momento |
| ----------------- | ---------------------------------- |
| `CREATED` | Pedido criado com sucesso |
| `START_DELIVERY` | Motorista saiu para a última milha |
| `SUCCESSFUL` | Entrega concluída |
### Templates de exemplo [#templates-de-exemplo]
**1 — Pedido criado**
```
Olá [customer_name],
Seu pedido foi criado com sucesso! Acompanhe todas as atualizações em tempo real:
https://rastreios.net/track/[tracking]
```
**2 — Pedido em rota**
```
Olá [customer_name],
Seu pedido saiu para entrega. Acompanhe o trajeto e o status em tempo real:
https://rastreios.net/track/[tracking]
```
**3 — Pedido entregue**
```
Olá [customer_name],
Sua entrega foi realizada com sucesso!
Confirme o recebimento e deixe sua avaliação:
https://rastreios.net/track/[tracking]
```
Os campos `customer_name` e `tracking` estão disponíveis em todos os eventos `ORDER_STATUS_CHANGE`. Consulte a [referência do evento](/docs/api/webhook/order-status-change) para o payload completo.
***
## Pedidos de retirada (`order_type: TAKEOUT`) [#pedidos-de-retirada-order_type-takeout]
Para retiradas, há **dois webhooks** envolvidos:
* **`ORDER_STATUS_CHANGE`** — para os gatilhos de status do pedido.
* **`TOKEN_GENERATED`** — para obter o código de retirada (token) que o cliente usa na loja.
### Gatilhos de status [#gatilhos-de-status]
| Status no webhook | Substatus | Momento |
| ----------------- | ----------- | ---------------------------- |
| `PENDING` | — | Pedido criado ou adiado |
| `SUCCESSFUL` | `WITHDRAWN` | Pedido retirado pelo cliente |
O primeiro `PENDING` representa a criação do pedido — **exceto** quando ele foi criado diretamente em `READY_FOR_TAKEOUT`, caso em que o primeiro `PENDING` já indica adiamento. A partir do segundo `PENDING`, independentemente da origem, o evento sempre significa que o pedido foi adiado para uma nova data.
### Código de retirada [#código-de-retirada]
O token de retirada chega pelo webhook `TOKEN_GENERATED`, no campo `token`. Um evento é disparado:
* Quando o pedido fica pronto para retirada (primeira emissão do token).
* Quando o cliente solicita **reenvio do código** — a Abbiamo gera um novo token e dispara o mesmo evento novamente.
Basta escutar o `TOKEN_GENERATED` e, a cada evento recebido, enviar (ou reenviar) o código ao cliente — sempre usando o mesmo template.
Sempre use o `token` do evento mais recente. Cada reenvio gera um novo código — o anterior é invalidado.
### Templates de exemplo [#templates-de-exemplo-1]
**1 — Pronto para retirada** *(disparado a cada TOKEN\_GENERATED — primeiro envio e reenvios)*
```
Olá [customer_name],
Seu pedido nº [order_number] está disponível para retirada.
Código de rastreio: [tracking]
Código de confirmação: [token]
Endereço e mapa da loja:
https://rastreios.net/track/[tracking]
```
**2 — Pedido retirado**
```
Olá [customer_name],
Seu pedido foi retirado com sucesso! Deixe sua avaliação:
https://rastreios.net/track/[tracking]
```
***
## Referências relacionadas [#referências-relacionadas]
* [Webhook ORDER\_STATUS\_CHANGE](/docs/api/webhook/order-status-change) — todos os status e substatuses, payload completo
* [Webhook TOKEN\_GENERATED](/docs/api/webhook/token-generated) — evento de código de retirada
* [Status & Substatus](/docs/api/conceitos/tables/status-and-substatus) — tabela completa de transições
---
# Pickup pincode — fluxo motorista para filial (/docs/api/guias/pickup-pincode-driver-to-seller)
Este é o fluxo de pickup pincode **motorista para filial**, controlado por `pickup_verification.pincode_owner = "abbiamo"` no webhook de [Requisição de entrega](/docs/api/carrier-integration/deliveries). A Abbiamo gera o PIN na criação do pedido e o valida localmente quando o operador o digita no dashboard. É exigido por embarcadores que precisam ser a fonte da verdade do PIN — tipicamente por razões de auditoria, prevenção de fraude ou regulatórias.
Este modelo é **opt-in por integração embarcador × transportadora** — ambos os lados precisam suportá-lo. Para o fluxo padrão em que a transportadora gera o PIN, consulte [Pickup pincode — fluxo filial para motorista](/docs/api/guias/pickup-pincode-seller-to-driver).
## Quem valida o quê [#quem-valida-o-quê]
| Ator | Responsabilidade |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Abbiamo** | Gera o PIN na criação do pedido. Envia o PIN pré-gerado à transportadora. Valida o PIN digitado pelo operador localmente. Solicita à transportadora (de forma síncrona) que libere o motorista após o PIN ser validado. |
| **Transportadora** | Recebe o PIN pré-gerado na [Requisição de entrega](/docs/api/carrier-integration/deliveries) e o exibe ao motorista em seu próprio aplicativo. Expõe o webhook de [Validação do pin de coleta](/docs/api/carrier-integration/pickup-pin-validation) para liberar o motorista quando a Abbiamo chamar. |
| **Motorista** | Recebe o PIN pelo aplicativo da transportadora e o informa verbalmente ao operador da loja no balcão. |
| **Operador da loja** | Recebe o PIN verbalmente do motorista e o digita no dashboard da Abbiamo. |
## Passo a passo [#passo-a-passo]
1. **Criação do pedido.** O embarcador cria uma entrega pela Orders API. A integração embarcador × transportadora está configurada pela Abbiamo com `pickup_verification.pincode = true` e `pickup_verification.pincode_owner = "abbiamo"`. A Abbiamo gera um PIN de 4 dígitos e o persiste na entrega.
2. **Despacho.** A Abbiamo envia o webhook de [Requisição de entrega](/docs/api/carrier-integration/deliveries) à transportadora. O bloco `logistic_data.pickup_verification` contém `pincode: true`, `pincode_owner: "abbiamo"` e `pincode_value` com o código de 4 dígitos.
3. **Transportadora exibe o PIN ao motorista.** O aplicativo do motorista mostra o código recebido em `pincode_value` junto com as demais informações de coleta.
4. **Motorista chega à loja.** Informa verbalmente o PIN ao operador no balcão.
5. **Operador digita o PIN no dashboard.** A Abbiamo valida o código localmente contra a cópia armazenada na criação do pedido.
6. **Abbiamo solicita à transportadora que libere o motorista.** Se o PIN coincidir, a Abbiamo dispara o webhook de [Validação do pin de coleta](/docs/api/carrier-integration/pickup-pin-validation) à transportadora. Esta chamada é **síncrona** — a Abbiamo aguarda a resposta da transportadora na mesma requisição HTTP, com timeout de 5 segundos.
7. **Transportadora libera o motorista e responde.** Na mesma resposta HTTP, a transportadora retorna `200 / driver_unlocked` (ou `200 / already_unlocked` para uma nova tentativa idempotente). O aplicativo do motorista para de bloquear a coleta.
8. **Coleta confirmada.** A Abbiamo transita a entrega para `COLLECTED`, retorna sucesso ao dashboard e o operador libera fisicamente o pacote ao motorista.
Se o PIN não coincidir, o operador vê um erro no dashboard. A transportadora **não** é chamada, o motorista permanece bloqueado e o status da entrega não muda. Se a transportadora responder com 4xx/5xx ou expirar o timeout, o dashboard exibe um erro de "transportadora indisponível" e o operador pode tentar novamente ou recorrer a um canal manual.
## Exemplos de payload [#exemplos-de-payload]
**Requisição de entrega da Abbiamo para a transportadora (bloco relevante apenas):**
```json
{
"event_type": "DELIVERY_REQUEST",
"logistic_data": {
"pickup_verification": {
"pincode": true,
"pincode_owner": "abbiamo",
"pincode_value": "8745"
}
}
}
```
**Webhook síncrono da Abbiamo para a transportadora quando o operador envia o PIN:**
```json
{
"event_type": "PICKUP_PIN_VALIDATION_REQUEST",
"event_at": "2026-05-12T14:34:17.890Z",
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059"
}
```
**Resposta esperada da transportadora na mesma requisição HTTP:**
```json
{
"code": "driver_unlocked",
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"unlocked_at": "2026-05-12T14:34:18.014Z",
"driver": {
"id": "MOTO-5544",
"name": "Carlos Silva",
"document_number": "12345678900"
}
}
```
Quando a Abbiamo chama a transportadora no passo 6, o PIN já foi validado localmente. A transportadora recebe apenas o `delivery_id` e deve liberar o motorista com base nisso. Reenviar o PIN nesta chamada duplicaria a fonte da verdade.
## Habilitando este fluxo [#habilitando-este-fluxo]
A escolha do modelo faz parte do acordo comercial entre embarcador e transportadora, e é configurada pelo lado da Abbiamo — o embarcador não escolhe o modelo por pedido. Para habilitar o fluxo motorista para filial em um par embarcador × transportadora:
1. A transportadora deve suportar a leitura de `pickup_verification.pincode_value` no webhook de [Requisição de entrega](/docs/api/carrier-integration/deliveries) e exibi-lo ao motorista.
2. A transportadora deve expor o handler do webhook de [Validação do pin de coleta](/docs/api/carrier-integration/pickup-pin-validation), respeitando os requisitos de idempotência e timeout de 5 segundos documentados ali.
3. Ambos os lados entram em contato com [carrier@abbiamolog.com](mailto:carrier@abbiamolog.com) para migrar a integração para `pincode_owner = "abbiamo"`.
Enquanto ambos os lados não estiverem prontos, a integração permanece no fluxo padrão `pincode_owner = "carrier"` — sem quebra de contrato.
## Armadilhas comuns [#armadilhas-comuns]
* **Transportadora ignora `pincode_value` e gera seu próprio PIN.** Neste modelo, a transportadora **deve** exibir o `pincode_value` recebido — o operador digitará esse código, não o que a transportadora gerou. PINs divergentes aparecem como erros `INVALID_PIN` no dashboard.
* **Handler da transportadora muito lento no webhook síncrono.** O timeout padrão da Abbiamo é de 5 segundos. Se a lógica de liberação da transportadora for mais pesada, ela deve responder `200 / driver_unlocked` assim que o desbloqueio for confirmado em seu banco de dados e concluir o restante do trabalho de forma assíncrona.
* **Handler da transportadora não é idempotente.** A Abbiamo realiza uma nova tentativa em caso de `5xx` / timeout. O handler deve retornar `200 / already_unlocked` (sem reexecutar os efeitos colaterais) ao receber uma segunda chamada para o mesmo `delivery_id`.
## Validação via API (sem o dashboard) [#validação-via-api-sem-o-dashboard]
Operações que usam ferramenta própria (em vez do dashboard da Abbiamo) executam os passos 5–6 via API pública:
* [Verificações do pedido (coleta e retorno)](/docs/api/orders/get-order-verification) — informa se o pedido exige o PIN de coleta (e o código de retorno, quando houver).
* [Confirmar pincode de coleta](/docs/api/orders/confirm-pickup-pincode) — valida o PIN digitado, libera o motorista na transportadora e transita a entrega para `COLLECTED`.
## Referências relacionadas [#referências-relacionadas]
* [Pickup pincode (visão geral dos dois modelos)](/docs/api/carrier-integration/pickup-pincode)
* [Webhook de requisição de entrega](/docs/api/carrier-integration/deliveries)
* [Webhook de validação do pin de coleta](/docs/api/carrier-integration/pickup-pin-validation)
---
# Pickup pincode — fluxo filial para motorista (/docs/api/guias/pickup-pincode-seller-to-driver)
Este é o fluxo de pickup pincode **tradicional**, controlado por `pickup_verification.pincode_owner = "carrier"` no webhook de [Requisição de entrega](/docs/api/carrier-integration/deliveries). A transportadora gera o PIN como parte de sua própria operação de coleta; o dashboard da filial apenas exibe o código para que o operador da loja possa repassá-lo ao motorista.
Este é o padrão para toda integração de transportadora que suporta pickup pincode hoje — nenhum opt-in é necessário. Para o modelo alternativo em que a Abbiamo é dona do PIN, consulte [Pickup pincode — fluxo motorista para filial](/docs/api/guias/pickup-pincode-driver-to-seller).
## Quem valida o quê [#quem-valida-o-quê]
| Ator | Responsabilidade |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Transportadora** | Gera o PIN. Repassa-o à Abbiamo no primeiro evento de status. Valida o PIN digitado pelo motorista dentro do seu próprio aplicativo. |
| **Abbiamo** | Recebe o PIN da transportadora e exibe na visualização do pedido da filial. **Não** valida o PIN neste modelo. |
| **Operador da loja** | Lê o PIN no dashboard e repassa ao motorista (normalmente de forma verbal no balcão). |
| **Motorista** | Recebe o PIN do operador e digita no aplicativo da transportadora. |
## Passo a passo [#passo-a-passo]
1. **Criação do pedido.** O embarcador cria uma entrega pela Orders API. A integração embarcador × transportadora já está configurada pela Abbiamo com `pickup_verification.pincode = true` e `pickup_verification.pincode_owner = "carrier"`.
2. **Despacho.** A Abbiamo envia o webhook de [Requisição de entrega](/docs/api/carrier-integration/deliveries) à transportadora. O bloco `logistic_data.pickup_verification` contém `pincode: true` e `pincode_owner: "carrier"`. Nenhum `pincode_value` é enviado — a transportadora é quem o gera.
3. **Transportadora gera o PIN.** Internamente, em seus próprios sistemas.
4. **Transportadora repassa o PIN.** No próximo evento de status após o motorista se dirigir ao ponto de coleta — tipicamente [At pickup point](/docs/api/carrier-integration/at-pickup-point) ou [Collecting delivery](/docs/api/carrier-integration/carrier-collecting-delivery) — a transportadora inclui `collect_verification_code` no payload. Eventos de status que aceitam esse campo:
* [At pickup point](/docs/api/carrier-integration/at-pickup-point)
* [Collecting delivery](/docs/api/carrier-integration/carrier-collecting-delivery)
* [Confirm delivery](/docs/api/carrier-integration/carrier-confirm-delivery)
* [Failed to collect](/docs/api/carrier-integration/carrier-failed-to-collect)
* [Searching driver](/docs/api/carrier-integration/carrier-searching-driver)
5. **Dashboard exibe o PIN.** A Abbiamo persiste o código e o exibe no sidepanel do pedido no dashboard da filial.
6. **Entrega na loja.** O motorista chega. O operador da loja lê o PIN no dashboard e o repassa ao motorista (verbalmente no balcão é o padrão mais comum).
7. **Motorista digita no aplicativo da transportadora.** A validação ocorre **dentro do sistema da transportadora** — a Abbiamo não participa neste ponto.
8. **Coleta confirmada.** Quando a transportadora aceita o código, ela envia um evento de status `collected` à Abbiamo, e a entrega transita para `COLLECTED`.
## Exemplos de payload [#exemplos-de-payload]
**Requisição de entrega da Abbiamo para a transportadora (bloco relevante apenas):**
```json
{
"event_type": "DELIVERY_REQUEST",
"logistic_data": {
"pickup_verification": {
"pincode": true,
"pincode_owner": "carrier"
}
}
}
```
**Atualização de status da transportadora repassando o PIN à Abbiamo (exemplo com `at-pickup-point`):**
```json
{
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"event_at": "2026-05-12T15:10:00.000Z",
"collect_verification_code": "123456"
}
```
Quando `pickup_verification.pincode = false` (ou o bloco estiver ausente), a transportadora **não deve** enviar `collect_verification_code` nos eventos de status — o campo é ignorado de qualquer forma e gera ruído de auditoria.
As transportadoras devem persistir a decisão "enviar código sim/não" por `delivery_id` no momento em que recebem o webhook de [Requisição de entrega](/docs/api/carrier-integration/deliveries). Isso evita omitir o código acidentalmente em um evento posterior ou enviá-lo em uma entrega que não habilitou o pickup pincode.
## Armadilhas comuns [#armadilhas-comuns]
* **Enviar `collect_verification_code` em toda entrega.** Envie apenas quando a [Requisição de entrega](/docs/api/carrier-integration/deliveries) sinalizou `pickup_verification.pincode = true`. Caso contrário, o campo é ignorado.
* **Validação apenas na transportadora — a Abbiamo não pode ajudar se o operador repassar o código errado.** Se o operador ler o código incorretamente e o motorista digitá-lo errado, o aplicativo da transportadora rejeita a entrada. A Abbiamo só fica sabendo indiretamente (nenhum evento `collecting-delivery` chega).
* **Repassar o PIN somente no `collected`.** Repasse o PIN em `at-pickup-point` ou `collecting-delivery` — quanto antes, melhor. Quando o `collected` chega, o código no dashboard já não é mais útil para o operador.
## Referências relacionadas [#referências-relacionadas]
* [Webhook de requisição de entrega](/docs/api/carrier-integration/deliveries)
* [At pickup point](/docs/api/carrier-integration/at-pickup-point)
* [Collecting delivery](/docs/api/carrier-integration/carrier-collecting-delivery)
* [Pickup pincode (visão geral dos dois modelos)](/docs/api/carrier-integration/pickup-pincode)
---
# Clique e Retire — material de retirada por filial (/docs/api/guias/retira-clique-e-retire)
O **Clique e Retire** é a modalidade em que o cliente retira o pedido na loja por autoatendimento, sem depender do balcão para localizar o pacote. Cada filial expõe um **cartaz com um QR Code estático**; o cliente escaneia, informa o código de rastreio do pedido e confirma a retirada presencialmente.
Este guia cobre as duas pontas:
* **Montar o material da filial** — o QR Code estático e o PDF de instruções que vão no ponto de venda (um QR por filial, fixo).
* **A jornada do pedido** — como o pedido nasce como retirada, gera o token de retirada e é fechado como retirado.
Para o contrato cru de cada endpoint (parâmetros, respostas, playground), vá direto à seção [Retirada (Clique e Retire)](/docs/api/retira) na API Reference.
## Quem faz o quê [#quem-faz-o-quê]
| Ator | Responsabilidade |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Embarcador** | Gera o material de cada filial (QR + instruções) uma vez e o imprime/expõe no ponto de venda. Cria os pedidos do tipo `TAKEOUT`. |
| **Abbiamo** | Entrega o QR estático e o PDF de instruções por filial; gera o token de retirada por pedido; registra a confirmação da retirada. |
| **Operador da loja** | Mantém o cartaz visível no balcão e dá suporte ao cliente no autoatendimento. |
| **Cliente** | Escaneia o QR exposto na loja, informa o código de rastreio, preenche o código de confirmação e conclui a retirada. |
## Parte 1 — Montar o material da filial [#parte-1--montar-o-material-da-filial]
O material é **fixo por filial**: gere uma vez por loja e reutilize em todos os cartazes e adesivos daquela unidade. A filial é identificada pelo `identifier` (o mesmo `seller_identifier` usado na criação de pedidos) e precisa pertencer ao seller group autenticado.
### Passo a passo [#passo-a-passo]
1. **Pegue o QR Code estático da filial.** Chame o endpoint [QR Code estático de retirada](/docs/api/retira/static-qrcode). A resposta é uma imagem **PNG** — salve direto como `.png`.
```bash
curl -X GET \
"https://api.abbiamo.io/v1/takeout/seller/{identifier}/static-qrcode" \
-H "x-abbiamo-seller-group-key: SUA_CHAVE" \
--output retirada-qrcode.png
```
2. **Pegue o PDF de instruções da filial.** Chame o endpoint [Instruções de retirada (PDF)](/docs/api/retira/instructions). A resposta é um **PDF** — salve direto como `.pdf`.
```bash
curl -X GET \
"https://api.abbiamo.io/v1/takeout/seller/{identifier}/instructions" \
-H "x-abbiamo-seller-group-key: SUA_CHAVE" \
--output retirada-instrucoes.pdf
```
3. **Monte o cartaz e exponha no balcão.** Junte o QR e as instruções no seu material de ponto de venda e deixe visível na loja.
Os dois endpoints retornam **conteúdo binário** (`image/png` e `application/pdf`). Salve o corpo da resposta direto em arquivo — não tente fazer parse como JSON.
Tem mais de uma filial/bandeira? Repita os dois passos para cada `identifier`. Cada filial tem seu próprio QR e PDF.
**A busca de retirada é escopada pela filial.** O QR de uma filial só encontra pedidos de retirada (`TAKEOUT`) **daquela filial**, criados nos últimos 3 meses. Um QR único para a bandeira inteira só acharia os pedidos de uma única filial — para bandeiras com mais de uma filial, gere **um QR por filial** (um `identifier` por loja).
## Parte 2 — A jornada do pedido [#parte-2--a-jornada-do-pedido]
1. **Pedido de retirada.** Crie o pedido como `TAKEOUT` (campo `type` na [criação de pedido](/docs/api/orders/create-order-v2)). É o que sinaliza que o cliente vai retirar na loja em vez de receber em casa.
2. **Pedido fica pronto para retirada.** Quando o pacote está disponível na loja, o pedido entra em `DISPATCHED` (pronto para retirada). O cliente é avisado por e-mail e SMS com o código de rastreio.
3. **Cliente escaneia o QR na loja.** Pelo QR estático do cartaz, o cliente abre a jornada de retirada e informa o código de rastreio para localizar o pedido. A busca é feita **dentro daquela filial** — apenas pedidos `TAKEOUT` da filial do QR, criados nos últimos 3 meses.
4. **Token de retirada.** O pedido tem um token único de retirada — disponível via [Obter token de retirada](/docs/api/orders/get-takeout-token). O cliente apresenta/confirma esse código para validar que é o dono do pedido.
5. **Retirada confirmada.** Com a retirada validada, o pedido é movido para `SUCCESSFUL.WITHDRAWN` — manualmente via [Marcar pedido como retirado](/docs/api/orders/set-order-as-withdrawn) ou pelo próprio fluxo de autoatendimento. Esse é o fim do ciclo de vida do pedido.
Os endpoints da jornada do pedido falham se o pedido não for do tipo `TAKEOUT` ou ainda não estiver pronto para retirada (`DISPATCHED`).
## Erros comuns [#erros-comuns]
* **Tratar a resposta binária como JSON.** Os endpoints de QR e instruções devolvem PNG/PDF. Use `--output arquivo` (curl) ou salve o buffer da resposta; não dê parse em JSON.
* **Gerar o QR por pedido.** O QR de Clique e Retire é **por filial**, não por pedido — é o mesmo cartaz para todos os pedidos daquela loja. Quem é único por pedido é o **token de retirada**.
* **Um QR único para uma bandeira com várias filiais.** A busca é escopada por filial: o QR de uma filial não encontra pedidos de outra. Se a bandeira tem mais de uma loja, gere **um QR por filial**.
* **`403` ao buscar o material.** O `identifier` da filial precisa pertencer ao seller group da chave usada. Filial de outro grupo retorna `403`; `identifier` inexistente retorna `404`.
* **Pedido criado sem `type: "TAKEOUT"`.** Sem isso o pedido segue como entrega normal e a jornada de retirada não se aplica.
## Referências relacionadas [#referências-relacionadas]
* [QR Code estático de retirada](/docs/api/retira/static-qrcode)
* [Instruções de retirada (PDF)](/docs/api/retira/instructions)
* [Obter token de retirada](/docs/api/orders/get-takeout-token)
* [Marcar pedido como retirado](/docs/api/orders/set-order-as-withdrawn)
* [Criar pedido (v2)](/docs/api/orders/create-order-v2)
---
# Cotações (Quotations) (/docs/api/quotations)
---
# Cotar pedidos (v2) (/docs/api/quotations/quote-orders-v2)
{/* concept-backlink */}
Entenda o fluxo no guia: [Conceito: Cotação de frete](/docs/log/conceitos/cotacao-frete) · [Como cotar frete](/docs/log/acoes/cotacao-frete).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint serve para simular o frete dos seus pedidos. Foi desenvolvido para simular entregas com ponto de coleta em uma das suas filiais e múltiplos pontos de entrega. Assim, antes de criar os pedidos, você pode cotar quanto eles custariam e quanto tempo levariam para chegar ao destino final.
A resposta é dividida em duas seções:
* `optimized_global_quotation`: refere-se às melhores combinações de frete de acordo com a data de envio (mais rápido) e de acordo com o valor do frete (mais barato), somando todos os métodos disponíveis.
Para que um método seja selecionado como o mais barato ou o mais rápido na resposta dentro do objeto `optimized_global_quotation`, ele precisa ter tanto `method_expected_delivery_date` quanto `method_shipping_price`.
* `orders`: cada item do array corresponde a um pedido cotado com todas as cotações possíveis para os métodos disponíveis.
Para que um método apareça na resposta dentro de `quotations` no array `orders`, ele precisa ter `method_expected_delivery_date`.
## Quando não há cotação disponível [#quando-não-há-cotação-disponível]
Se nenhuma transportadora conseguir cotar um pedido, a resposta continua **200** e o pedido aparece em `orders` com `quotations: []` — não é mais necessário tratar 204 como "sem cotação". Nesse caso, o pedido também traz:
* `reason`: veredito consolidado do motivo. `code` é `NO_QUOTATION_AVAILABLE` quando é falta de cobertura ou de configuração da transportadora para aquele destino, ou `QUOTATION_SERVICE_UNAVAILABLE` quando foi uma falha temporária — nesse segundo caso vale a pena repetir a chamada antes de investigar mais a fundo.
* `unavailable_reasons`: detalhe do motivo por transportadora que tentou cotar o pedido e não conseguiu, com `error_id` para referenciar caso precise abrir chamado com o suporte.
---
# Cotar pedidos (v1) (/docs/api/quotations/quote-orders)
{/* concept-backlink */}
Entenda o fluxo no guia: [Conceito: Cotação de frete](/docs/log/conceitos/cotacao-frete) · [Como cotar frete](/docs/log/acoes/cotacao-frete).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint serve para simular o frete dos seus pedidos. Foi desenvolvido para simular entregas com ponto de coleta em uma das suas filiais e múltiplos pontos de entrega. Assim, antes de criar os pedidos, você pode cotar quanto eles custariam e quanto tempo levariam para chegar ao destino final.
A resposta é dividida em duas seções:
* `optimized_global_quotation`: refere-se às melhores combinações de frete de acordo com a data de envio (mais rápido) e de acordo com o valor do frete (mais barato), somando todos os métodos disponíveis.
Para que um método seja selecionado como o mais barato ou o mais rápido na resposta dentro do objeto `optimized_global_quotation`, ele precisa ter tanto `method_expected_delivery_date` quanto `method_shipping_price`.
* `orders`: cada item do array corresponde a um pedido cotado com todas as cotações possíveis para os métodos disponíveis.
Para que um método apareça na resposta dentro de `quotations` no array `orders`, ele precisa ter `method_expected_delivery_date`.
Quando um pedido fica sem cotação (`quotations: []`) ou o CEP informado é inválido, a resposta segue o mesmo formato do endpoint v2 — veja [Quando não há cotação disponível](/docs/api/quotations/quote-orders-v2#quando-não-há-cotação-disponível) na página da v2.
---
# Motorista no ponto de coleta (/docs/api/carrier-integration/at-pickup-point)
{/* concept-backlink */}
Fluxo completo: [Guia rápido: código de coleta](/docs/transportadora/quick-guide-codigo-coleta).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
In Transit
com sub_status At Pickup Point
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Solicitação de cancelamento (/docs/api/carrier-integration/cancellation)
{/* concept-backlink */}
Contexto operacional: [Transportadora](/docs/transportadora) · [Homologação](/docs/transportadora/homologacao).
Essa ação pode ser realizada via endpoint, diretamente na plataforma pela filial ou automaticamente pelo sistema caso o pedido precise ser cancelado por qualquer motivo. **Em ambos os casos, esta ação é restrita a situações em que o pedido ainda não foi coletado — seja antes da coleta ou quando o motorista não conseguiu realizar a coleta.**
Sempre que essa ação é executada, um evento é disparado e uma requisição POST é enviada à URL que você forneceu para cancelamento.
O payload é similar ao mostrado abaixo:
```json SELLER_CANCELED
{
"event_type": "CANCELLATION_REQUEST",
"delivery_id": "4278444b-d4e5-4890-8d12-ad3cacd7aaaa",
"order_number": "example_carrier_payload_1",
"tracking": "8oRjvvv",
"seller_id": "5b2d4006-f0af-47d3-943e-e8352aaaaaa",
"seller_name": "Go Go Fruits",
"seller_document_number": "12345678000190",
"seller_group_id": "b7d56bca-606e-405e-bf4d-9b0a3291b61d",
"status": "ORDER_FAILED",
"sub_status": "SELLER_CANCELED",
"timestamp": 1671134757870,
"event_at": "2022-12-15T20:05:56Z",
"support_id": "xxx-yyy-zzz"
}
```
```json CARRIER_TIMEOUT
{
"event_type": "CANCELLATION_REQUEST",
"delivery_id": "4278444b-d4e5-4890-8d12-ad3cacd7aaaa",
"order_number": "example_carrier_payload_1",
"tracking": "8oRjvvv",
"seller_id": "5b2d4006-f0af-47d3-943e-e8352aaaaaa",
"seller_name": "Go Go Fruits",
"seller_document_number": "12345678000190",
"seller_group_id": "b7d56bca-606e-405e-bf4d-9b0a3291b61d",
"status": "ORDER_FAILED",
"sub_status": "CARRIER_TIMEOUT",
"timestamp": 1671134757870,
"event_at": "2022-12-15T20:05:56Z",
"support_id": null
}
```
---
# Cancelar entrega (transportadora) (/docs/api/carrier-integration/carrier-cancel-delivery)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Order Failed
com sub_status Carrier Canceled
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Entrega coletada (/docs/api/carrier-integration/carrier-collected-delivery)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Collected
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Coletando entrega (/docs/api/carrier-integration/carrier-collecting-delivery)
{/* concept-backlink */}
Fluxo completo: [Guia rápido: código de coleta](/docs/transportadora/quick-guide-codigo-coleta).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
In Transit
com sub_status Collecting
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Confirmar entrega (/docs/api/carrier-integration/carrier-confirm-delivery)
{/* concept-backlink */}
Fluxo completo: [Guia rápido: código de coleta](/docs/transportadora/quick-guide-codigo-coleta).
Se ainda não leu, dá uma olhada no nosso [sistema de timeout](/docs/api/carrier-integration/receive-events#sistema-de-timeout) — é peça importante da integração.
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Dispatched
com sub_status Carrier Confirmed
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Motorista atribuído (/docs/api/carrier-integration/carrier-driver-assigned)
Se ainda não leu, dá uma olhada no nosso [sistema de timeout](/docs/api/carrier-integration/receive-events#sistema-de-timeout) — é peça importante da integração.
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Dispatched
com sub_status Driver Assgined
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Motorista recusou (/docs/api/carrier-integration/carrier-driver-rejected)
Se ainda não leu, dá uma olhada no nosso [sistema de timeout](/docs/api/carrier-integration/receive-events#sistema-de-timeout) — é peça importante da integração.
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Dispatched
com sub_status Driver Reject e apague o último motorista atribuído
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Falha na coleta (/docs/api/carrier-integration/carrier-failed-to-collect)
{/* concept-backlink */}
Fluxo completo: [Guia rápido: código de coleta](/docs/transportadora/quick-guide-codigo-coleta).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Failed
com sub_status Failed to Colect
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Falha na entrega (/docs/api/carrier-integration/carrier-failed-to-deliver)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
Lembre-se: o campo **`failure_code`** precisa ser um dos códigos da [tabela de códigos de falha](/docs/api/conceitos/tables/failure-codes).
Se o motivo da falha não está nesta tabela, envie `failure_code` **17** (outro) e coloque a descrição no campo `observation`.
{`
Atualize o pedido para
Failed
com sub_status Failed to Deliver
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Falha no retorno (/docs/api/carrier-integration/carrier-failed-to-return)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Failed
com sub_status Failed to Return
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Manuseando entrega (/docs/api/carrier-integration/carrier-handling-delivery)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Handling
com o sub_status especificado
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Erros comuns nos endpoints (/docs/api/carrier-integration/carrier-homologation-copy)
### EVENT\_AT\_BEFORE\_ORDER\_CREATED\_AT [#event_at_before_order_created_at]
O evento que você está enviando tem `event_at` anterior à criação do pedido na Abbiamo — não é possível processar.
### EVENT\_AT\_BEFORE\_DELIVERY\_CREATED\_AT [#event_at_before_delivery_created_at]
O evento que você está enviando tem `event_at` anterior à `DELIVERY_REQUEST` enviada ao seu servidor — não é possível processar.
### EVENT\_NOT\_IN\_UPDATE\_TIME\_WINDOW [#event_not_in_update_time_window]
Há uma janela de 24 horas para atualizações atrasadas em entregas após o status terminal. Eventos não-terminais que aconteceram antes do terminal são processados se enviados dentro dessa janela; fora dela, este erro é retornado.
### EVENT\_CANNOT\_BE\_TERMINAL\_AGAIN [#event_cannot_be_terminal_again]
Depois de enviar um status terminal (endpoints `/confirmed`, `/returned` ou `/canceled`), você não pode enviar outro status terminal — caso contrário este erro é retornado.
### EVENT\_CANNOT\_BE\_AFTER\_TERMINAL\_STATUS [#event_cannot_be_after_terminal_status]
Depois de enviar um status terminal (endpoints `/confirmed`, `/returned` ou `/canceled`), eventos não-terminais devem ter acontecido antes do terminal — caso contrário este erro é retornado.
---
# Entrega devolvida (/docs/api/carrier-integration/carrier-returned-delivery)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Returned
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Devolvendo entrega (/docs/api/carrier-integration/carrier-returning-delivery)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Returning
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Procurando motorista (/docs/api/carrier-integration/carrier-searching-driver)
{/* concept-backlink */}
Fluxo completo: [Guia rápido: código de coleta](/docs/transportadora/quick-guide-codigo-coleta).
Se ainda não leu, dá uma olhada no nosso [sistema de timeout](/docs/api/carrier-integration/receive-events#sistema-de-timeout) — é peça importante da integração.
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Dispatched
com sub_status searching driver
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Iniciar entrega (/docs/api/carrier-integration/carrier-start-delivery)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
On Route
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Entrega bem-sucedida (/docs/api/carrier-integration/carrier-successful-delivery)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o pedido para
Successful
`}
* Eventos sequenciais não podem ter o mesmo `event_at`. Se você enviar um payload com o mesmo `event_at` de um evento anterior, ele não será processado.
---
# Criar pedido (transportadora) (/docs/api/carrier-integration/create-an-order)
## Login [#login]
Acesse o [Dashboard](https://dashboard.abbiamolog.com) com as credenciais fornecidas para fazer login.
## Criar pedido [#criar-pedido]
Clique no botão "Criar pedido" no canto superior direito do dashboard.
Em seguida, você encontrará o formulário para preencher os campos com informações de teste.
Clique no botão "**Create Order**".
Por fim, você deve ver o pedido criado conforme a imagem a seguir.
Após criar o pedido com sucesso, veja na próxima seção [como enviar o pedido para o seu sistema](/docs/api/carrier-integration/send-order-to-carrier).
---
# Criar webhook (/docs/api/carrier-integration/create-webhook)
Cada chamada registra **uma URL por `event_type`**. Os tipos disponíveis são:
| `event_type` | Quando é disparado |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `DELIVERY_REQUEST` | Uma nova solicitação de entrega foi despachada para a transportadora. |
| `CANCELLATION_REQUEST` | O cliente solicitou o cancelamento de uma entrega. |
| `PICKUP_PIN_VALIDATION_REQUEST` | Webhook **síncrono** de [validação do pincode de coleta](/docs/api/carrier-integration/pickup-pin-validation) no modelo motorista → loja. |
Registre o `PICKUP_PIN_VALIDATION_REQUEST` apenas se a sua integração suporta o modelo motorista → loja (`pincode_owner = "abbiamo"`). Veja [Pincode de coleta](/docs/api/carrier-integration/pickup-pincode) para entender os dois modelos e [Validação do pincode de coleta](/docs/api/carrier-integration/pickup-pin-validation) para os requisitos do handler (resposta síncrona, idempotência e timeout). Transportadoras que ainda não suportam esse modelo podem deixar de registrar essa URL — nesse caso a Abbiamo não despacha entregas com `pincode_owner = "abbiamo"` para a integração.
---
# Deletar webhook (/docs/api/carrier-integration/delete-webhook)
---
# Solicitação de entrega (webhook) (/docs/api/carrier-integration/deliveries)
Este payload espelha as informações do pedido fornecidas pela filial. Por isso, alguns campos podem não aparecer ou ser nulos quando a informação não foi fornecida, já que alguns campos são opcionais na API de pedidos.
Leia a [documentação de pedidos](/docs/api/orders/create-order-v2) para entender os campos obrigatórios.
* **amount**: cents
* **weight**: grams
* **height**: cm
* **width**: cm
* **length**: cm
* **cubic\_volume**: cm3
* **keep\_prescription**: indica se o entregador deve recolher a receita com o paciente no momento da entrega (mais comum no setor farmacêutico)
* **thermolabile**: indica se os itens do pedido são termolábeis e requerem tratamento especial
* **pos\_terminal\_required**: indica se o entregador deve levar a maquininha de cartão
* **return\_to\_origin**: indica se o entregador designado para este pedido deve retornar à origem
* **observation**: campo de texto para comentários ou observações sobre a entrega
Bloco opcional enviado apenas quando a integração filial × transportadora tem o pincode de coleta habilitado. A transportadora deve inspecionar `pincode_owner` para decidir qual fluxo executar.
* **pincode**: `true` quando o pincode de coleta é obrigatório para esta entrega.
* **pincode\_owner**: `"carrier"` — modelo tradicional: a transportadora gera o PIN e o devolve via eventos `at-pickup-point` / `collecting-delivery` usando `collect_verification_code`. `"abbiamo"` — modelo de pincode do motorista para a filial: a Abbiamo é a proprietária do PIN e o envia pré-gerado em `pincode_value`. A transportadora deve exibi-lo ao motorista no seu próprio aplicativo e aguardar um webhook `PICKUP_PIN_VALIDATION_REQUEST` para liberar a coleta (veja [Validação de pincode de coleta](/docs/api/carrier-integration/pickup-pin-validation)).
* **pincode\_value**: string de 4 dígitos. Presente **apenas** quando `pincode_owner = "abbiamo"`. Deve ser exibido ao motorista no aplicativo da transportadora exatamente como recebido.
Sempre que uma filial solicita uma entrega a uma transportadora, este evento é disparado. Um payload com os detalhes do pedido e as informações do método de entrega é apresentado abaixo:
```json SPOT payload
{
"event_type": "DELIVERY_REQUEST",
"seller": {
"seller_name": "Go Go Fruits",
"seller_id": "eb064ede-08f3-470e-a37c-5b796a17cca8",
"seller_document_number": "12345678000190",
"seller_group_id": "b7d56bca-606e-405e-bf4d-9b0a3291b61d",
"seller_contacts": [ // optinal array. It depends wheter the seller has it configured or not
{
"name": "Eduardo Silveira",
"phone": "21999999999",
"phone_country_code": "55",
"email": "contato@exemplo.com.br"
}
],
},
"carrier": {
"name": "CARRIER_BRAND_NAME",
"max_dispatched_time": "14:00:00-03",
"expected_delivery_date": "2022-12-22T23:59:00.000-03:00",
"total_expected_delivery_price": 1200,
"method": {
"external_id": "name/id",
"id": "e84b2788-5b78-40dd-95cf-75807f70aaaa",
"name": "CARRIER_BRAND_NAME_D0",
"type": "D0"
}
},
"logistic_data": {
"headers": {
"Authorization": "Bearer xxx"
},
"pickup_verification": { // optional · see callout above
"pincode": true,
"pincode_owner": "abbiamo", // "carrier" | "abbiamo"
"pincode_value": "8745" // present only when pincode_owner = "abbiamo"
}
},
"source_address": {
"zip_code": "04029904",
"country": "BRA",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Indianópolis",
"street": "Avenida Ibirapuera",
"street_number": "3407",
"complement": null,
"reference": null,
"latitude": -23.52045997445427,
"longitude": -46.438805678513575
},
"make_route": false,
"courier_must_return": true,
"route_id": null, // exists when make_route is true
"route_name": null, // exists when make_route is true
"deliveries": [
{
"invoice_number": "example_invoice_number_1",
"invoice_access_key": "35200000000000000000000000000000000000000000",
"invoice_created_at": "2023-06-22T18:59:37.024Z",
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"order_number": "example_carrier_payload_1",
"tracking": "a-vBGOS",
"amount": 6909,
"expected_delivery_price": 1000,
"carrier_additional_information": {
"keep_prescription": true,
"thermolabile": true,
"pos_terminal_required": true,
"return_to_origin": true,
"observation": "pegar maquina com Walmir no caixa"
},
"volumes": [
{
"id": "4754cd99-3378-4e6c-bdaf-53db23ac5a4f",
"weight": 0,
"height": null,
"width": null,
"length": null,
"cubic_volume": 0
}
],
"customer": {
"name": "Machado de Assis",
"phone": "911111111",
"phone_country_code": "55",
"document_number": "12345678909"
},
"destination_address": {
"zip_code": "08050360",
"country": "BRA",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim das Camélias",
"street": "Rua Doutor Alfredo Sales",
"street_number": "931",
"complement": "sala 2",
"reference": null,
"latitude": -23.834499518193947,
"longitude": -45.37406370734008
}
}
]
}
```
```json ROUTE Payload
{
"event_type": "DELIVERY_REQUEST",
"seller": {
"seller_name": "Go Go Fruits",
"seller_id": "eb064ede-08f3-470e-a37c-5b796a17cca8",
"seller_document_number": "12345678000190",
"seller_group_id": "b7d56bca-606e-405e-bf4d-9b0a3291b61d",
"seller_contacts": [
{
"name": "Eduardo Silveira",
"phone": "21999999999",
"phone_country_code": "55",
"email": "contato@exemplo.com.br"
}
],
},
"carrier": {
"name": "CARRIER_BRAND_NAME",
"max_dispatched_time": "14:00:00-03",
"expected_delivery_date": "2022-12-22T23:59:00.000-03:00",
"total_expected_delivery_price": 1200,
"method": {
"id": "e84b2788-5b78-40dd-95cf-75807f70aaaa",
"name": "CARRIER_BRAND_NAME_D0",
"type": "D0"
}
},
"logistic_data": {
"headers": {
"Authorization": "Bearer xxx"
},
"pickup_verification": { // optional · see callout above
"pincode": true,
"pincode_owner": "abbiamo", // "carrier" | "abbiamo"
"pincode_value": "8745" // present only when pincode_owner = "abbiamo"
}
},
"source_address": {
"zip_code": "04029904",
"country": "BRA",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Indianópolis",
"street": "Avenida Ibirapuera",
"street_number": "3407",
"complement": null,
"reference": null,
"latitude": -23.52045997445427,
"longitude": -46.438805678513575
},
"make_route": true,
"courier_must_return": false,
"route_id": "7ed34417-b51f-4d98-bec8-3ccb41290575", // exists when make_route is true
"route_name": "GPT-2LkRo", // exists when make_route is true
"deliveries": [
{
"invoice_number": "example_invoice_number_1",
"invoice_access_key": "35200000000000000000000000000000000000000000",
"invoice_created_at": "2023-06-22T18:59:37.024Z",
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"order_number": "example_carrier_payload_1",
"tracking": "a-vBGOS",
"amount": 6909,
"expected_delivery_price": 1000,
"carrier_additional_information": {
"keep_prescription": true,
"thermolabile": true,
"pos_terminal_required": true,
"return_to_origin": true,
"observation": "pegar maquina com Walmir no caixa"
},
"volumes": [
{
"id": "4754cd99-3378-4e6c-bdaf-53db23ac5a4f",
"weight": 0,
"height": null,
"width": null,
"length": null,
"cubic_volume": 0
}
],
"customer": {
"name": "Machado de Assis",
"phone": "911111111",
"phone_country_code": "55",
"document_number": "12345678909"
},
"destination_address": {
"zip_code": "08050360",
"country": "BRA",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim das Camélias",
"street": "Rua Doutor Alfredo Sales",
"street_number": "931",
"complement": "sala 2",
"reference": null,
"latitude": -23.834499518193947,
"longitude": -45.37406370734008
}
}
]
}
```
---
# Consultar entrega (/docs/api/carrier-integration/get-delivery)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
Este endpoint retorna os dados da entrega. Inclui nota fiscal, cliente, endereços, eventos, recebedor e anexos.
---
# Homologação (/docs/api/carrier-integration/homologation)
* Enviar os dados do destinatário e a prova de entrega não é obrigatório, mas quase todas as transportadoras disponíveis na plataforma garantem comprovante de entrega. Por isso, espera-se que a sua integração também forneça essa informação.
* Poucas transportadoras enviam a localização do motorista em tempo real. Essa é uma funcionalidade de extrema importância para a experiência do cliente final. Se você tem a tecnologia para isso, é uma vantagem significativa em relação aos concorrentes.
### Checklist para entender quais dados estão sendo enviados [#checklist-para-entender-quais-dados-estão-sendo-enviados]
1. Você envia os dados do motorista, como nome e documento? Esses dados devem chegar preferencialmente no endpoint /driver-assigned ou /collecting.
2. Você envia o motivo da falha corretamente? Recomenda-se que o motivo seja enviado no campo "failure\_driver\_message" ou "observation" como uma string completa, dependendo do que o aplicativo da transportadora suporta.
3. Você envia o ETA (Tempo Estimado de Chegada)?
4. Você envia os dados do destinatário e/ou a foto comprobatória? Eles podem chegar junto com o evento de sucesso no endpoint /successful ou posteriormente no endpoint /receiver.
### Fluxos a serem validados durante a homologação [#fluxos-a-serem-validados-durante-a-homologação]
Todos os fluxos foram desenhados para validar a integração tanto tecnicamente quanto operacionalmente. Se um fluxo não se aplicar ao seu caso, os times revisam juntos como isso afeta a experiência do cliente final.
> A documentação dos fluxos de homologação foi atualizada e movida. Consulte o guia completo aqui: **[Guia de Homologação](/docs/transportadora/homologacao)**.
---
# Integração de Transportadoras (/docs/api/carrier-integration)
---
# Listar webhooks (/docs/api/carrier-integration/list-webhooks)
{/* concept-backlink */}
Passo a passo: [Homologação](/docs/transportadora/homologacao).
---
# Validação do pincode de coleta (/docs/api/carrier-integration/pickup-pin-validation)
Este webhook é enviado **somente quando a entrega foi despachada com `logistic_data.pickup_verification.pincode_owner = "abbiamo"`** no payload da [Solicitação de entrega](/docs/api/carrier-integration/deliveries) — modelo motorista → loja (veja [Pincode de coleta](/docs/api/carrier-integration/pickup-pincode)).
A Abbiamo já validou o PIN digitado pelo operador da loja contra a própria cópia do código. Esta chamada pede que a transportadora destrave o motorista no app dela para que a coleta física possa continuar.
A Abbiamo aguarda a resposta da transportadora na **mesma requisição HTTP** — **não há callback**. O HTTP status code e o campo `code` retornados pela transportadora decidem diretamente se a coleta é liberada para o operador da loja.
* **Timeout padrão: 5 segundos.** Se o seu handler precisar de mais tempo, responda `200 / driver_unlocked` assim que o destravamento for persistido no seu banco e finalize o resto de forma assíncrona do seu lado.
* **Retries:** a Abbiamo refaz a chamada **uma vez** em `5xx` / timeout. **Não há retry** em respostas `4xx`.
Sempre que o operador da loja envia o pincode no dashboard da Abbiamo e a Abbiamo confirma localmente, este evento é disparado para a URL de webhook da transportadora. A transportadora precisa destravar o motorista no próprio app e responder de forma síncrona.
O payload espelha os mesmos blocos identificadores já enviados na [Solicitação de entrega](/docs/api/carrier-integration/deliveries) original (`seller`, `carrier`, identificadores da entrega, `logistic_data`), para que a transportadora consiga localizar a entrega nos próprios sistemas e reutilizar qualquer contexto que chegou no momento do despacho (por exemplo, um token específico do seller dentro de `logistic_data.headers`):
```json PICKUP_PIN_VALIDATION_REQUEST
{
"event_type": "PICKUP_PIN_VALIDATION_REQUEST",
"event_at": "2026-05-12T14:34:17.890Z",
"seller": {
"seller_name": "Go Go Fruits",
"seller_id": "eb064ede-08f3-470e-a37c-5b796a17cca8",
"seller_document_number": "12345678000190",
"seller_group_id": "b7d56bca-606e-405e-bf4d-9b0a3291b61d",
"seller_contacts": [
{
"name": "Eduardo Silveira",
"phone": "21999999999",
"phone_country_code": "55",
"email": "contato@exemplo.com.br"
}
]
},
"carrier": {
"name": "CARRIER_BRAND_NAME",
"max_dispatched_time": "14:00:00-03",
"expected_delivery_date": "2022-12-22T23:59:00.000-03:00",
"total_expected_delivery_price": 1200,
"method": {
"external_id": "name/id",
"id": "e84b2788-5b78-40dd-95cf-75807f70aaaa",
"name": "CARRIER_BRAND_NAME_D0",
"type": "D0"
}
},
"invoice_number": "example_invoice_number_1",
"invoice_access_key": "35200000000000000000000000000000000000000000",
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"order_number": "example_carrier_payload_1",
"logistic_data": {
"headers": {
"Authorization": "Bearer xxx"
},
"pickup_verification": {
"pincode": true,
"pincode_owner": "abbiamo",
"pincode_value": "8745"
}
}
}
```
A Abbiamo é a fonte da verdade do PIN no modelo motorista → loja e **já validou** localmente antes de disparar este webhook. A transportadora **não deve re-validar** o `pincode_value` que vem dentro de `logistic_data.pickup_verification` — o único propósito deste endpoint é destravar o motorista no app da transportadora.
O `pincode_value` aparece aqui apenas porque o bloco `logistic_data` inteiro é reenviado por conveniência (assim a transportadora pode reutilizar qualquer contexto usado no momento do despacho — geralmente um token específico do seller dentro de `logistic_data.headers`). Se a transportadora não precisa desse contexto, pode ignorar tudo menos o `delivery_id`.
## Respostas esperadas [#respostas-esperadas]
A transportadora precisa responder na mesma chamada HTTP. A Abbiamo usa a resposta para decidir se transita a entrega para `COLLECTED` e libera a coleta no lado da loja.
| HTTP | `code` | Significado |
| ------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200 | `driver_unlocked` | Motorista destravado no app da transportadora. A Abbiamo transita a entrega para `COLLECTED` e retorna sucesso ao operador da loja. |
| 200 | `already_unlocked` | Motorista já estava destravado (retry idempotente do mesmo `delivery_id`). Mesmo efeito de `driver_unlocked`. |
| 404 | `DELIVERY_NOT_FOUND` | A transportadora não reconhece este `delivery_id`. A Abbiamo mostra o erro ao operador. Sem retry. |
| 409 | `INVALID_DRIVER_STATUS` | O motorista não está mais em estado válido pra coletar (desistiu, já saiu do ponto de coleta, etc.). A Abbiamo bloqueia a coleta. Sem retry. |
| 5xx / timeout | — | A Abbiamo refaz a chamada uma vez imediatamente. Se ainda falhar, o operador vê um erro "transportadora indisponível" no dashboard e a entrega não avança. |
Exemplo de resposta para `200 / driver_unlocked`:
```json 200 driver_unlocked
{
"code": "driver_unlocked",
"delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
"unlocked_at": "2026-05-12T14:34:18.014Z",
"driver": {
"name": "Carlos Silva",
"document_number": "12345678900"
},
"location": {
"latitude": -10.9731,
"longitude": -37.0568
}
}
```
Campos da resposta de sucesso (`driver_unlocked` / `already_unlocked`):
| Campo | Obrigatório | Descrição |
| ------------------------ | ----------- | ----------------------------------------------------------------------- |
| `code` | Sim | `driver_unlocked` ou `already_unlocked`. |
| `delivery_id` | Não | Eco do `delivery_id` recebido. |
| `unlocked_at` | Não | Momento do destravamento (ISO 8601). |
| `driver.name` | Não | Nome do motorista que fará a coleta — gravado no evento de `COLLECTED`. |
| `driver.document_number` | Não | Documento do motorista. |
| `location.latitude` | Não | Latitude real da coleta (posição do motorista no destravamento). |
| `location.longitude` | Não | Longitude real da coleta. |
Se a transportadora enviar `location` com um par `latitude`/`longitude` válido, a Abbiamo grava **essa coordenada** no evento de `COLLECTED` (é o local real da coleta). O campo é opcional: quando `location` vem ausente ou incompleta, o evento de `COLLECTED` simplesmente fica sem coordenada. O par precisa vir completo (latitude **e** longitude) para ser considerado.
O endpoint da transportadora **precisa** aceitar uma segunda chamada com o mesmo `delivery_id` sem efeitos colaterais e responder `200 / already_unlocked`. A Abbiamo trata `driver_unlocked` e `already_unlocked` como equivalentes (sucesso), o que mantém o comportamento de retry seguro.
## Onde registrar a URL [#onde-registrar-a-url]
Registre a URL deste handler com o `event_type` **`PICKUP_PIN_VALIDATION_REQUEST`** em [Criar webhook](/docs/api/carrier-integration/create-webhook). Pode ser a mesma URL que a transportadora já usa para `DELIVERY_REQUEST` e `CANCELLATION_REQUEST` — ou uma URL separada, se preferir. Veja [Receber eventos](/docs/api/carrier-integration/receive-events) para o passo de registro. Transportadoras que ainda não suportam o modelo motorista → loja podem pular o registro dessa URL — nesse caso, a Abbiamo simplesmente não despacha entregas com `pincode_owner = "abbiamo"` para a sua integração.
---
# Pincode de coleta (/docs/api/carrier-integration/pickup-pincode)
**Pincode de coleta** é um código numérico curto (4 dígitos) validado no momento em que o motorista chega à origem (a loja) para confirmar que o motorista certo está pegando o pedido certo. É usado por embarcadores que precisam de uma camada extra de verificação anti-fraude / compliance no handover entre a loja e o motorista.
A Abbiamo suporta **dois modelos coexistentes** de pincode de coleta. A escolha é parte do acordo comercial entre embarcador e transportadora, e é configurada por integração. As transportadoras só precisam saber que **o mesmo campo** no payload da [Solicitação de entrega](/docs/api/carrier-integration/deliveries) (`logistic_data.pickup_verification.pincode_owner`) indica qual fluxo se aplica a cada entrega.
## Modelo tradicional — `pincode_owner = "carrier"` [#modelo-tradicional--pincode_owner--carrier]
A transportadora gera o PIN como parte do próprio fluxo de coleta.
1. A Abbiamo despacha a entrega para a transportadora com `pickup_verification.pincode = true` e `pincode_owner = "carrier"`. Nenhum valor de PIN é enviado.
2. A transportadora gera o PIN internamente e o devolve para a Abbiamo no primeiro evento de status enviado após o motorista sair em direção ao ponto de coleta — geralmente `at-pickup-point` ou `collecting-delivery` — no campo `collect_verification_code`.
3. A Abbiamo exibe o código para o operador da loja no dashboard. O operador entrega o código ao motorista (geralmente verbalmente no balcão).
4. O motorista digita o código no app da própria transportadora. **A validação acontece dentro do sistema da transportadora.**
5. A transportadora envia o evento de status `collected` quando a coleta é finalizada.
Este é o modelo já em produção hoje para transportadoras que suportam pincode de coleta.
## Modelo motorista → loja — `pincode_owner = "abbiamo"` [#modelo-motorista--loja--pincode_owner--abbiamo]
A Abbiamo é dona do PIN e valida localmente.
1. No momento em que a Abbiamo despacha uma entrega para a transportadora, ela gera um PIN de 4 dígitos **único por entrega** (um pedido pode ter múltiplos envios, cada um com seu próprio PIN) e persiste. A entrega é então despachada com `pickup_verification.pincode = true`, `pincode_owner = "abbiamo"` e `pincode_value` contendo o código de 4 dígitos.
2. A transportadora exibe o `pincode_value` para o motorista no app dela — o motorista leva o código consigo até o ponto de coleta.
3. Na loja, o motorista informa o código para o operador. O operador digita o código no dashboard da Abbiamo.
4. A Abbiamo valida o código localmente contra a própria cópia.
5. Se o código bater, a Abbiamo dispara o webhook [Validação do pincode de coleta](/docs/api/carrier-integration/pickup-pin-validation) **sincronicamente** para a transportadora. A transportadora destrava o motorista no app dela e responde `200 / driver_unlocked` na mesma resposta HTTP.
6. A Abbiamo transita a entrega para `COLLECTED` e libera a coleta no lado da loja.
Este modelo é exigido por embarcadores que precisam ser a fonte da verdade do PIN — geralmente por motivos de auditoria, prevenção de fraude ou regulatórios.
## Comparação lado a lado [#comparação-lado-a-lado]
| Aspecto | `pincode_owner = "carrier"` | `pincode_owner = "abbiamo"` |
| ---------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Quem gera o PIN | Transportadora | Abbiamo (ou o embarcador, repassado via Abbiamo) |
| Como o PIN chega na Abbiamo | Eventos de status com `collect_verification_code` | Gerado dentro da Abbiamo no momento do despacho (um PIN por entrega) |
| Como o PIN chega na transportadora | A transportadora já tem (gerou internamente) | `pickup_verification.pincode_value` na [Solicitação de entrega](/docs/api/carrier-integration/deliveries) |
| Quem mostra o PIN para quem | Dashboard mostra ao operador → operador fala ao motorista | App da transportadora mostra ao motorista → motorista fala ao operador |
| Onde acontece a validação | Dentro do app da transportadora (motorista digita lá) | Dentro da Abbiamo (operador digita no dashboard) |
| Novo webhook da Abbiamo | Nenhum (eventos de status já existentes bastam) | [`PICKUP_PIN_VALIDATION_REQUEST`](/docs/api/carrier-integration/pickup-pin-validation) — síncrono, a resposta decide o resultado |
| Status na transportadora | Igual às integrações de pickup pincode atuais | Exige ler `pincode_value` e expor o novo handler de webhook síncrono |
## Como configurar [#como-configurar]
O modelo usado em cada entrega é decidido pela configuração da integração filial × transportadora do lado da Abbiamo — a transportadora não precisa fazer nada por pedido para escolher entre os dois. Para habilitar o modelo motorista → loja para um embarcador específico, a transportadora precisa:
1. Implementar a leitura de `pickup_verification.pincode_value` na [Solicitação de entrega](/docs/api/carrier-integration/deliveries) e exibi-lo ao motorista no app.
2. Implementar o handler [Validação do pincode de coleta](/docs/api/carrier-integration/pickup-pin-validation) atendendo aos requisitos de idempotência e timeout documentados lá.
3. Falar com [carrier@abbiamolog.com](mailto:carrier@abbiamolog.com) para virar a chave da integração para `pincode_owner = "abbiamo"` no embarcador específico.
Transportadoras que ainda não implementaram o modelo motorista → loja continuam recebendo `pincode_owner = "carrier"` (ou nenhum bloco `pickup_verification` quando pickup pincode não é usado) para todos os seus embarcadores — sem breaking change.
---
# Receber eventos (/docs/api/carrier-integration/receive-events)
**Registro de webhook obrigatório.** Para receber webhooks você precisa ter pelo menos 2 URLs registradas — podem ser a mesma URL repetida ou URLs diferentes: uma para o webhook de **Delivery request** e outra para os eventos de status. Veja [Criar webhook](/docs/api/carrier-integration/create-webhook).
Nestes webhooks (eventos) é possível enviar um header **`Authorization`** para proteger seu endpoint. Avise qual token devemos usar em cada evento.
Se a sua integração suporta o modelo motorista → loja de pincode de coleta (`pincode_owner = "abbiamo"`), registre também uma URL para o `event_type` **`PICKUP_PIN_VALIDATION_REQUEST`** — o webhook **síncrono** de [validação do pincode de coleta](/docs/api/carrier-integration/pickup-pin-validation).
Eventualmente o cliente precisa cancelar uma solicitação. Garanta que seu sistema escuta de forma confiável os eventos de cancelamento — evita problemas de alocação de motorista e outros transtornos.
Em caso de dúvidas, fala com a gente que ajudamos.
Leia com atenção sobre o nosso sistema de timeout abaixo.
## Sistema de Timeout [#sistema-de-timeout]
Para garantir a melhor experiência possível aos nossos clientes, temos um **Sistema de Timeout** que cancela automaticamente a solicitação de entrega após um tempo padrão de **30 minutos** caso ela não seja **CONFIRMADA** pelo sistema da transportadora.
Para evitar esse cenário, você deve processar e **confirmar a entrega o mais rápido possível**, usando [Confirmar Entrega](/docs/api/carrier-integration/carrier-confirm-delivery). Lembre-se de que você será notificado via **WEBHOOK** caso a solicitação de entrega expire, e que esse tempo padrão de 30 minutos é configurável.
Se o evento DELIVERY\_REQUEST não for processado com sucesso, você deve retornar uma resposta com o erro como valor string dentro de um objeto com a chave `abbiamo_error`, para que possamos espelhá-lo no nosso dashboard e alertar a filial sobre o problema. Exemplo:
```
{
"abbiamo_error": "customer phone must be valid"
}
```
---
# Enviar pedido à transportadora (/docs/api/carrier-integration/send-order-to-carrier)
## Enviando o pedido para o seu sistema [#enviando-o-pedido-para-o-seu-sistema]
Para enviar o pedido do dashboard para o seu sistema com sucesso, é preciso preencher as seguintes informações:
* Um endereço de coleta suportado pela sua operação (lojas e armazéns)
* URL que receberá as requisições POST do nosso sistema
No dashboard, acesse a barra de navegação vertical à direita e clique no ícone de caminhão. Depois, clique em "**Request Pickup**" conforme indicado abaixo.
Ao clicar, abre um painel lateral à direita. Selecione a filial, a transportadora (seu logo e nome devem aparecer), o warehouse/loja (`pickup_address`) e os pedidos que serão enviados ao seu sistema.
Após preencher todos os campos e clicar no botão "**REQUEST COLLECTION**", você deve receber uma requisição POST na URL que forneceu ao time da Abbiamo, conforme descrito [aqui](/docs/api/carrier-integration/deliveries).
---
# Testando a integração (/docs/api/carrier-integration/testing-integration)
Suas **principais responsabilidades** como transportadora são:
* **1:** Receber uma requisição POST (webhook) do nosso sistema com a solicitação de entrega em formato JSON em uma URL que você fornecerá;
* **2:** Atualizar os status de entrega sempre que houver mudanças no seu sistema; e
* **3:** Escutar o webhook de cancelamento (quando aplicável).
Para testar cada um dos pontos listados acima, crie um pedido no nosso ([dashboard](https://dashboard.abbiamolog.com)) e envie ao seu sistema. Você vai receber o webhook listado no **passo 1** e a partir daí pode seguir com os testes.
*Com as credenciais e o acesso ao nosso sistema, você deverá seguir os seguintes passos:*
Temos páginas de documentação para cada um desses passos:
* [Criar pedido](/docs/api/carrier-integration/create-an-order)
* [Enviar pedido à transportadora](/docs/api/carrier-integration/send-order-to-carrier)
* [Atualizar status do pedido](/docs/api/carrier-integration/update-delivery-status)
---
# Atualizar detalhes da entrega (/docs/api/carrier-integration/update-deliveries-details)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
Este endpoint serve para atualizar informações de entrega em lote (coordenadas, ETA, etc.). **Você pode enviar uma ou várias atualizações na mesma requisição.**
* `latitude` e `longitude` precisam ser enviados juntos — caso contrário nada é atualizado.
---
# Atualizar CT-e da entrega (/docs/api/carrier-integration/update-delivery-cte)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
Este endpoint permite atualizar o XML do CT-e (Conhecimento de Transporte Eletrônico) de uma entrega específica.
## Validação do XML [#validação-do-xml]
Os seguintes campos dentro de `xml_cte_string` são validados:
* `ide.cUF`: Código da Unidade Federativa (estado) onde o CT-e está sendo emitido.
* `ide.nCT`: Número sequencial do CT-e.
* `ide.dhEmi`: Data e hora de emissão do CT-e.
* `emit.CNPJ`: CNPJ do emitente.
* `vPrest.vTPrest`: Valor total do serviço (frete).
* `dest.CNPJ` / `dest.CPF`: CNPJ ou CPF do destinatário.
* `infCte`: Informações gerais do CT-e.
Garanta que os campos estão preenchidos corretamente e batem com os dados da entrega na Abbiamo. Informações incorretas ou faltantes resultam em erro de validação. A string precisa estar com escape (`"\"`) por causa de aspas duplas repetidas.
**Example**: "\...
---
# Atualizar etiqueta da entrega (/docs/api/carrier-integration/update-delivery-mail-label)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-carrier-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
Use este endpoint para enviar à Abbiamo o PDF da etiqueta de envio de uma entrega específica. Você informa o `delivery_id` da entrega e o conteúdo da etiqueta (`base64`); opcionalmente, envie um `external_id` para referência cruzada com o seu sistema.
## Como enviar a etiqueta [#como-enviar-a-etiqueta]
* O campo `base64` deve conter o PDF da etiqueta codificado em base64. O prefixo data URI (`data:application/pdf;base64,`) é opcional.
* O arquivo é validado: precisa ser um PDF íntegro, com header `%PDF` e trailer `%%EOF`. Conteúdo que não for um PDF válido é recusado.
* A entrega precisa pertencer à sua transportadora e não pode estar cancelada ou já finalizada com falha.
Reenviar a etiqueta para a mesma entrega substitui o PDF anterior. Sempre envie a versão mais atual.
---
# Atualizar NF-e da entrega (/docs/api/carrier-integration/update-delivery-nfe)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
Este endpoint permite atualizar o XML da NF-e (Nota Fiscal Eletrônica) de uma entrega específica.
## Validação do XML [#validação-do-xml]
Os seguintes campos dentro de `xml_nfe_string` são validados:
* `InfNfse`: Informações gerais da NF-e.
* `Numero`: Número sequencial da NF-e.
* `DataEmissao`: Data e hora de emissão da NF-e.
* `PrestadorServico.IdentificacaoPrestador.Cnpj`: CNPJ do emitente.
* `TomadorServico.IdentificacaoTomador.CpfCnpj.Cnpj` / `TomadorServico.IdentificacaoTomador.CpfCnpj.Cnpj`: CNPJ ou CPF do destinatário.
* `Servico.Valores.ValorServicos`: Valor total do serviço (frete).
Garanta que os campos estão preenchidos corretamente e batem com os dados da entrega na Abbiamo. Informações incorretas ou faltantes resultam em erro de validação. A string precisa estar com escape (`"\"`) por causa de aspas duplas repetidas.
**Example**: "\...
---
# Atualizar destinatário da entrega (/docs/api/carrier-integration/update-delivery-receiver)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
{`
Atualize o destinatário de um pedido com status
Successful
`}
---
# Atualizar status da entrega (/docs/api/carrier-integration/update-delivery-status)
Nesta seção você entenderá como o fluxo de uma entrega deve ser tratado na Abbiamo.
Após enviar o pedido ao seu sistema, ele fica em status `PENDING` na Abbiamo. A primeira ação é **confirmá-lo** usando o endpoint documentado nesta página.
Se ainda não leu, dá uma olhada no nosso [sistema de timeout](/docs/api/carrier-integration/receive-events#sistema-de-timeout) — é peça importante da integração.
Para alterar o status do pedido, é preciso ter o token de transportadora que fornecemos e usá-lo para autenticar as chamadas aos nossos endpoints.
## Status na Abbiamo [#status-na-abbiamo]
Sabemos que imprevistos acontecem — por isso documentamos tanto o fluxo ideal de status quanto os endpoints alternativos que você deve usar em cenários de exceção.
---
# Atualizar webhook (/docs/api/carrier-integration/update-webhook)
Você precisa enviar o resultado desejado completo no payload do corpo, porque este endpoint edita o registro inteiro do webhook. Por exemplo:
* para atualizar apenas um header, envie a URL e o novo objeto `headers`.
* Para atualizar a URL, envie a nova URL e repita os headers — caso contrário os headers são apagados (vão para `null`).
---
# Configurar webhooks (/docs/api/carrier-integration/webhooks)
---
# Boas-vindas — Transportadora (/docs/api/carrier-integration/welcome-carrier)
{/* concept-backlink */}
Visão geral da operação: [Guia da Transportadora](/docs/transportadora).
Para conhecer melhor a Abbiamo, assista ao vídeo abaixo (PT-BR):
Para iniciar o processo de integração corretamente, você precisa das seguintes informações:
* Suas credenciais de login no nosso [Dashboard](https://dashboard.abbiamolog.com)
* Sua chave de API da transportadora guardada em segurança
**Se ainda não fez, fale com nosso time em [carrier@abbiamolog.com](mailto:carrier@abbiamolog.com) pra configurar suas credenciais. Você precisa nos fornecer as seguintes informações (você é registrado tanto como transportadora quanto como seller):**
* Endereço de coleta (onde a loja vai ficar);
* Número do documento (CNPJ/CPF);
* E-mail dos usuários que devem ter acesso ao dashboard.
### Integração para entregas [#integração-para-entregas]
O fluxo básico para entender a integração está ilustrado abaixo:
Você precisa expor um endpoint para receber as solicitações de entrega. Veja [como receber eventos](/docs/api/carrier-integration/receive-events).
O payload do `DELIVERY_REQUEST` pode ser consultado [aqui](/docs/api/carrier-integration/deliveries). É importante verificar ambos os payloads — completo e mínimo — para garantir que você atende aos requisitos dos campos específicos.
Para atualizar o status, optamos por endpoints separados para cada um — assim temos mais controle sobre o payload e os campos obrigatórios. Na maioria dos endpoints basta preencher `delivery_id` e `event_at`, mas recomendamos enviar o máximo de informação possível (os varejistas frequentemente pedem).
### Integração para cancelamentos [#integração-para-cancelamentos]
O payload do `CANCELLATION_REQUEST` pode ser consultado [aqui](/docs/api/carrier-integration/cancellation). Ele pode ser disparado em duas situações:
* A entrega não foi confirmada nos últimos 30 minutos (janela de tempo para receber a primeira atualização).
* A filial acionou o cancelamento. Essa ação é personalizada para a transportadora em status específicos.
---
# Cancelar envio (/docs/api/orders/cancel-delivery)
{/* concept-backlink */}
Entenda o conceito no guia: [Envio (Delivery)](/docs/log/conceitos/envio).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
## Entregas em andamento e agendadas [#entregas-em-andamento-e-agendadas]
Esta mesma chamada cobre os dois cenários — você não precisa saber em qual estágio o pedido está:
* **Entrega agendada (ainda não despachada).** Quando o pedido tem uma entrega agendada para um horário futuro e que ainda não foi enviada à transportadora, a chamada cancela o agendamento na hora. Não é preciso esperar a data do despacho.
* **Entrega em andamento.** Quando o pedido já foi despachado, o cancelamento vale enquanto a transportadora ainda **não coletou** o pacote. Depois da coleta, o cancelamento não é mais aceito.
---
# Tratar pedido manualmente (/docs/api/orders/cancel-order)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
{`
Este endpoint atualiza o status do pedido para
MANUAL_HANDLE.
Só pode ser usado em pedidos com status roteirizáveis, ou seja:
CREATED
FAILED(no caso de um evento PRIVATE-FLEET do tipo de transportadora)
ORDER_FAILED
RETURNED
`}
---
# Cancelar pedido (/docs/api/orders/cancel)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
## O que acontece ao cancelar [#o-que-acontece-ao-cancelar]
Use este endpoint quando o cliente quiser cancelar o pedido por qualquer motivo. Numa única chamada, o cancelamento:
1. **Cancela o agendamento e a entrega.** A mesma operação cobre os dois cenários: se a entrega está apenas **agendada** (ainda não despachada), o agendamento é cancelado na hora; se já foi despachada à transportadora, a entrega é cancelada enquanto o pacote ainda **não foi coletado**.
2. **Cancela o próprio pedido.** Só depois que a entrega é cancelada (ou quando não há entrega a cancelar) é que o pedido é marcado como cancelado.
**O cancelamento da entrega é a etapa de bloqueio.** Se a entrega **não puder ser cancelada** — por exemplo, quando o pedido já está em uma rota (trip) / em trânsito —, a chamada retorna **HTTP 400** com o código `ORDER_DELIVERY_NOT_CANCELABLE` e **o pedido não é cancelado**. Pedidos sem nenhuma entrega são cancelados normalmente.
---
# Confirmar pincode de coleta (/docs/api/orders/confirm-pickup-pincode)
{/* concept-backlink */}
Fluxo completo do PIN reverso: [Pickup pincode — fluxo motorista para filial](/docs/api/guias/pickup-pincode-driver-to-seller).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Equivalente via API ao passo em que o operador digita o PIN no dashboard ([passo 5 do guia](/docs/api/guias/pickup-pincode-driver-to-seller#passo-a-passo)). Em uma única chamada, a Abbiamo:
1. **Valida o PIN localmente** contra o código gerado na criação do pedido.
2. **Solicita à transportadora que libere o motorista** — chamada síncrona do webhook de [Validação do pin de coleta](/docs/api/carrier-integration/pickup-pin-validation), com timeout de 5 segundos.
3. **Transita a entrega para `COLLECTED`** e retorna sucesso.
Antes de chamar, use [Verificações do pedido](/docs/api/orders/get-order-verification) para saber se o pedido exige o PIN.
* **PIN incorreto** retorna **HTTP 400** `INVALID_PICKUP_PIN` — a transportadora **não** é chamada e o status não muda.
* **Transportadora indisponível** (4xx/5xx ou timeout no webhook) retorna erro — o operador pode tentar novamente (a chamada é idempotente: confirmar um pedido já coletado retorna `COLLECTED`).
* Só se aplica ao fluxo **PIN reverso** (`pincode_owner = abbiamo`); em entregas fora desse modelo retorna `PICKUP_PINCODE_NOT_OWNED_BY_ABBIAMO`.
---
# Criar pedido (v2) (/docs/api/orders/create-order-v2)
{/* concept-backlink */}
Entenda o fluxo no guia: [Conceito: Pedido](/docs/log/conceitos/pedido) · [Como criar um pedido](/docs/log/acoes/criacao-pedido).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`. Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Validação de duplicidade.** Para garantir integridade operacional e evitar despacho de múltiplos motoristas pro mesmo pacote, a Abbiamo bloqueia a criação de pedidos duplicados.
### Como funciona a validação? [#como-funciona-a-validação]
O sistema não olha só o número do pedido. Pra um pedido ser considerado **duplicado**, ele precisa ter paridade simultânea em todos estes critérios:
* **Número do pedido (`number`):** identificador único da carga.
* **ID da filial (`seller_id`):** origem da venda.
* **Tipo do pedido (`type`):** categoria da entrega.
* **Documento do cliente (`document_number`):** CPF ou CNPJ do destinatário.
* **Número da nota (`invoice_number`):** se presente nos dois registros.
* **Janela de tempo:** a verificação cobre pedidos criados nos últimos **3 meses**.
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**. Veja [Limite de Requisições](/docs/api/conceitos/rate-limit).
**Objeto `delivery`.** Esse objeto automatiza o despacho do pedido pra transportadora já no momento da criação. Você pode usar desde a forma mais simples (só uma `preference_rule` tipo `cheapest`/`fastest`) até a mais específica (escolher transportadora, método e prazo). Veja a página [Objeto `delivery`](/docs/api/orders/delivery-object) pra entender as 4 formas de montar esse objeto e qual usar em cada caso.
**Marca, categoria e fabricante do item.** Cada item aceita os campos opcionais `brand` (marca do produto — ex.: "Natura", "Neo Química"), `category` (categoria do produto — ex.: "shampoo", "medicamentos") e `manufacturer` (fabricante — empresa dona da marca; ex.: marca "Lacta" → fabricante "Mondelez"), todos texto livre com até 255 caracteres. Eles alimentam recursos de segmentação e análise por catálogo (campanhas e relatórios por marca/categoria/fabricante). Recomendamos enviar o valor real do catálogo do seu ERP/e-commerce, junto com um `name` descritivo.
Os objetos `destination_address` (e `source_address`, quando `type = RETURN`) aceitam os campos opcionais `latitude` e `longitude`. Se os dois vierem preenchidos, a Abbiamo **não roda o geocoding automático** para esse endereço — usa a coordenada enviada e grava `geolocation_provider = SELLER`.
Isso é útil como fallback pra endereços que o geocoder automático não resolve bem (condomínios, vias privadas, loteamentos fechados): basta informar a coordenada correta na criação do pedido. O mesmo campo existe na planilha (CSV/XLSX) de criação de pedidos — veja [Criação de Pedido](/docs/log/acoes/criacao-pedido).
Os dois campos precisam vir juntos — só `latitude` ou só `longitude` preenchido é rejeitado na validação.
Este endpoint cria pedidos individuais para a filial identificada pelo `seller_identifier`.
---
# Objeto `delivery` (/docs/api/orders/delivery-object)
Como mencionado em [Criar pedido (v2)](/docs/api/orders/create-order-v2), o objeto `delivery` é uma ferramenta poderosa que automatiza o despacho do pedido pra transportadora já no momento da criação.
Existem quatro formas de montar o objeto `delivery`. Abaixo elas aparecem da mais simples (menos específica) pra mais específica.
## 1 - Preference Rule (objeto mínimo) [#1---preference-rule-objeto-mínimo]
A forma mais simples de montar o `delivery` object é especificando apenas `preference_rule`. A regra escolhida determina qual `delivery_method`, entre as opções cadastradas, é usado no despacho. Existem duas `preference_rules`: `cheapest` e `fastest`.
```json minimal object
{
"preference_rule": "fastest"
}
```
Você pode usar esta forma do `delivery` object mesmo sem utilizar o [endpoint de cotação](/docs/api/quotations/quote-orders) ou as [opções de entrega](/docs/api/orders/delivery-options).
***
## 2 - Por nome da transportadora [#2---por-nome-da-transportadora]
Outra forma menos específica é informar o nome da transportadora escolhida. Como o nome da transportadora não basta para definir o método exato, este formato permite incluir o nome junto com um `preference_rule` opcional. Sem `preference_rule`, o valor padrão é `cheapest`. Para listar os nomes das transportadoras disponíveis para um pedido, use o endpoint [Opções de entrega](/docs/api/orders/delivery-options).
```json Carrier name Object
{
"carrier_name": "TRANSPORTADORA-B",
"schedule_at": "2025-03-28T15:08:00.000Z",
"preference_rule": "fastest" //opcional
}
```
***
## 3 - Por nome da transportadora + tipo de método [#3---por-nome-da-transportadora--tipo-de-método]
Este formato é um pouco mais específico do que apenas `carrier_name` porque também leva em conta o `method_type` da transportadora. Para listar os nomes das transportadoras e métodos disponíveis, use o endpoint [Opções de entrega](/docs/api/orders/delivery-options).
```json Carrier + Method Type
{
"carrier_name": "TRANSPORTADORA-B",
"method_type": "CONVENCIONAL",
"schedule_at": "2025-03-28T15:08:00.000Z"
}
```
***
## 4 - Por `logistic_id` [#4---por-logistic_id]
Esta é a forma mais precisa e específica de solicitar uma coleta usando o objeto `delivery`. Existem duas formas de compor este objeto e ambas exigem o uso do [endpoint de cotação](/docs/api/quotations/quote-orders).
Tanto o `logistic_id` quanto o `method_id` são retornados pelo endpoint de cotação. O `logistic_id` representa a transportadora e o `method_type`, enquanto o `method_id` reflete o prazo de entrega.
Existem dois tipos de `method_id`:
* O primeiro é `D(n)`, normalmente usado pra métodos convencionais, onde *n* é o número de dias *(ex.: uma transportadora com método convencional pode ter `method_id` `D3`, ou seja, entrega convencional em 3 dias)*.
* O segundo é `EXP(n)`, usado pra métodos expressos, onde *n* é o tempo em minutos *(ex.: uma transportadora com método Express pode ter `method_id` `EXP120`, ou seja, entrega expressa em 120 minutos)*.
### Montando o objeto Logistics [#montando-o-objeto-logistics]
Como este é o formato mais específico, é necessário informar o `logistic_id` junto com o `method_id` (prazo).
Alternativamente, você pode enviar apenas o `logistic_id` — o comportamento é equivalente ao formato 3 (Carrier Name + Method Type), com o desempate definido pelo `preference_rule`.
Em casos raros, o endpoint de cotação pode retornar o `method_id` como UUID. Esses métodos estão sendo descontinuados, mas continuam funcionando normalmente — você pode usá-los sem problema.
```json Logistic_id
{
"logistic_id": "9edc4f36-0444-47a7-a8e1-3ba0ba9deb45",
"method_id": "D1",
"schedule_at": "2025-03-28T15:08:00.000Z"
}
```
```json Alternative object
{
"logistic_id": "9edc4f36-0444-47a7-a8e1-3ba0ba9deb45",
"schedule_at": "2025-03-28T15:08:00.000Z",
"preference_rule": "cheapest" //ou "fastest"
}
```
---
# Opções de envio (/docs/api/orders/delivery-options)
{/* concept-backlink */}
Entenda o conceito no guia: [Envio (Delivery)](/docs/log/conceitos/envio).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint retorna as opções de entrega ativas de uma filial. Útil pra escolher uma transportadora no momento de despachar via [Criar pedido (v2)](/docs/api/orders/create-order-v2).
If 200 status code, you will get the carrier\_name, method\_type and available methods according to the expected shipping date.
---
# Eventos do pedido por chave de acesso (/docs/api/orders/get-events-by-access-key)
---
# Eventos do pedido por external_id (/docs/api/orders/get-events-by-external-id)
---
# Eventos do pedido por order_id (/docs/api/orders/get-events-by-order-id)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint retorna os detalhes do pedido (a maior parte deles é o que você enviou na criação) e os eventos que aconteceram ao longo do ciclo de vida. Use pra reconstruir a timeline do pedido — equivale a um histórico do webhook `ORDER_STATUS_CHANGE`.
---
# Eventos do pedido por order_number (/docs/api/orders/get-events-by-order-number)
---
# Consultar pedido por chave de acesso (/docs/api/orders/get-order-by-access-key)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint retorna os detalhes do pedido (a maior parte deles é o que você enviou na criação).
---
# Consultar pedido por external_id (/docs/api/orders/get-order-by-external-id)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint retorna os detalhes do pedido (a maior parte deles é o que você enviou na criação).
---
# Consultar pedido por order_id (/docs/api/orders/get-order-by-order-id)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint retorna os detalhes do pedido (a maior parte deles é o que você enviou na criação).
---
# Consultar pedido por order_number (/docs/api/orders/get-order-by-order-number)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint retorna os detalhes do pedido (a maior parte deles é o que você enviou na criação).
---
# Verificações do pedido (coleta e retorno) (/docs/api/orders/get-order-verification)
{/* concept-backlink */}
Os dois modelos de pincode de coleta: [visão geral](/docs/api/carrier-integration/pickup-pincode) · [motorista para filial (PIN reverso)](/docs/api/guias/pickup-pincode-driver-to-seller) · [filial para motorista](/docs/api/guias/pickup-pincode-seller-to-driver).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Use este endpoint para a operação da loja saber, a partir do `order_id`, **quais verificações se aplicam ao pedido**. O campo `pickup.pincode_owner` diz qual modelo está em uso:
| `pincode_owner` | Modelo | O que a operação faz |
| --------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `abbiamo` | **PIN reverso** (motorista → filial) | O motorista informa o PIN de 4 dígitos no balcão e o operador o valida via [Confirmar pincode de coleta](/docs/api/orders/confirm-pickup-pincode). O valor do PIN **não** é retornado aqui. |
| `carrier` | **Nativo da transportadora** (filial → motorista — Uber, Bee...) | O código vem em `pickup.pincode`: o operador o **exibe/informa ao motorista**, que o digita no aplicativo da transportadora (a validação acontece do lado dela). Pode ser `null` até a transportadora informá-lo. |
* **Entrega (`delivery`)** — quando `verification_required: true`, há pincode na entrega ao destinatário. **Apenas o flag é retornado**: o código pertence ao **destinatário** (é ele quem o informa ao motorista, como prova de entrega) — expô-lo à operação da loja quebraria essa prova.
* **Retorno (`return`)** — quando `verification_required: true`, o `verification_code` é retornado: o operador o informa ao motorista na devolução do pacote, e o motorista o digita **no aplicativo da transportadora**.
* `pickup.pending` indica que a entrega ainda não foi coletada.
**No PIN reverso (`pincode_owner = abbiamo`) o valor do PIN nunca é retornado.** Ele chega pelo motorista e é validado no endpoint de confirmação — retorná-lo quebraria a segurança do modelo em que a Abbiamo é a fonte da verdade do PIN.
---
# Obter token de retirada (/docs/api/orders/get-takeout-token)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint retorna o token de retirada ativo de um pedido. Em resposta `200`, devolve o `takeout_token`, o `order_number` e o `tracking`.
A requisição falha se o pedido não for do tipo `TAKEOUT` ou ainda não estiver pronto pra retirada (status `DISPATCHED`).
---
# Pedidos (Orders) (/docs/api/orders)
---
# Solicitar envio (modalidade específica) (/docs/api/orders/request-delivery)
{/* concept-backlink */}
Entenda o conceito no guia: [Envio (Delivery)](/docs/log/conceitos/envio).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
A lógica para montar o body segue de perto a estrutura do objeto de entrega usado no processo create-order-v2.
Existem quatro formas diferentes de compor o objeto de entrega, e vamos explorá-las da abordagem mais simples e menos detalhada até a opção mais específica disponível.
## 1 - Preference Rule (minimal Object) [#1---preference-rule-minimal-object]
A forma mais simples de montar o `delivery` object é especificando apenas `preference_rule`. A regra escolhida determina qual `delivery_method`, entre as opções cadastradas, é usado no despacho. Existem duas `preference_rules`: `cheapest` e `fastest`.
```json minimal object
{
"preference_rule": "fastest"
}
```
Você pode usar esta forma do `delivery` object mesmo sem utilizar o [endpoint de cotação](/docs/api/quotations/quote-orders) ou as [opções de entrega](/docs/api/orders/delivery-options).
***
## 2 - By Carrier Name [#2---by-carrier-name]
Outra forma menos específica é informar o nome da transportadora escolhida. Como o nome da transportadora não basta para definir o método exato, este formato permite incluir o nome junto com um `preference_rule` opcional. Sem `preference_rule`, o valor padrão é `cheapest`. Para listar os nomes das transportadoras disponíveis para um pedido, use o endpoint [Opções de entrega](/docs/api/orders/delivery-options).
```json Carrier name Object
{
"carrier_name": "TRANSPORTADORA-B",
"preference_rule": "fastest" //optional
}
```
***
## 3 - By Carrier Name + Carrier Method Type [#3---by-carrier-name--carrier-method-type]
Este formato é um pouco mais específico do que apenas `carrier_name` porque também leva em conta o `method_type` da transportadora. Para listar os nomes das transportadoras e métodos disponíveis, use o endpoint [Opções de entrega](/docs/api/orders/delivery-options).
```json Carrier + Method Type
{
"carrier_name": "TRANSPORTADORA-B",
"method_type": "CONVENCIONAL"
}
```
***
## 4 - By Logistic\_id [#4---by-logistic_id]
Esta é a forma mais precisa e específica de solicitar uma coleta usando o objeto de entrega. Há duas formas de compor esse objeto, ambas requerendo o uso do [endpoint de cotação](/docs/api/quotations/quote-orders).
Tanto o `logistic_id` quanto o `method_id` podem ser obtidos no endpoint de cotação. O `logistic_id` representa a transportadora e o `method_type`, enquanto o `method_id` indica o prazo da entrega.
Existem dois tipos de `method_id`:
* O primeiro tipo é D(*n*), comumente usado para métodos convencionais, onde *n* representa o número de dias *(ex.: uma transportadora com `method_type` convencional pode ter `method_id` D3, o que significa entrega convencional em 3 dias)*.
* O segundo tipo é EXP(*n*), usado para métodos expressos, onde *n* representa o tempo em minutos *(ex.: uma transportadora com `method_type` expresso pode ter `method_id` EXP120, o que significa entrega expressa em 120 minutos)*.
### Montando o objeto logístico [#montando-o-objeto-logístico]
Por ser o objeto de entrega mais específico possível, é necessário fornecer o `logistic_id` junto com o `method_id` (prazo).
Alternativamente, você pode enviar apenas o `logistic_id` — o comportamento é equivalente ao formato 3 (Carrier Name + Method Type), com o desempate definido pelo `preference_rule`.
Aviso: em casos raros, o endpoint de cotação pode retornar o `method_id` como um UUID. Não se preocupe — esses métodos estão sendo descontinuados, mas continuarão funcionando por enquanto. Você pode usá-los normalmente.
```json Logistic_id
{
"logistic_id": "9edc4f36-0444-47a7-a8e1-3ba0ba9deb45",
"method_id": "D1"
}
```
```json Alternative object
{
"logistic_id": "9edc4f36-0444-47a7-a8e1-3ba0ba9deb45",
"preference_rule"?: "cheapest" //fastest
}
```
---
# Reenviar envio (/docs/api/orders/resend-delivery)
{/* concept-backlink */}
Entenda o conceito no guia: [Envio (Delivery)](/docs/log/conceitos/envio).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint refaz o despacho usando a mesma modalidade da última tentativa. Se não houver tentativa anterior registrada, retorna erro — por isso só use em pedidos com status `ORDER_FAILED` ou `RETURNED`.
---
# Marcar pedido como retirado (/docs/api/orders/set-order-as-withdrawn)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint move o pedido para `SUCCESSFUL` com `sub_status` `WITHDRAWN`. É o fim do ciclo de vida do pedido — nenhuma outra atualização pode ser feita depois disso.
A requisição falha se o pedido não for do tipo `TAKEOUT` ou ainda não estiver pronto pra retirada (status `DISPATCHED`).
---
# Atualizar status manualmente (/docs/api/orders/update-order-status)
{/* concept-backlink */}
Entenda o conceito no guia: [Envio (Delivery)](/docs/log/conceitos/envio).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
## Quando usar [#quando-usar]
Use esta chamada para registrar manualmente um evento que aconteceu **fora do fluxo automático** da transportadora — por exemplo, uma entrega confirmada presencialmente ou uma falha registrada por um operador.
* A alteração é processada de forma **assíncrona**: a resposta `200` confirma que o evento foi aceito.
* No sistema, o status aparece como **atualizado manualmente**, identificando o token de API que originou a mudança.
## `event_at` [#event_at]
**Regras do `event_at`:**
* Deve estar no formato **RFC 3339** (ISO 8601 com timezone). Ex.: `2026-06-16T18:37:12.000Z` ou `2026-06-16T15:37:12.000-03:00`
* **Não pode ser anterior** à data de criação da entrega (erro `EVENT_AT_BEFORE_DELIVERY_CREATED_AT`)
* **Não pode ser igual** ao `event_at` de um evento anterior da mesma entrega — eventos sequenciais precisam de timestamps distintos
* Deve refletir **quando o evento realmente ocorreu**, não o momento da chamada
## Entrega existente vs. criar entrega [#entrega-existente-vs-criar-entrega]
A chamada cobre os dois cenários automaticamente:
* **Pedido com entrega ativa** — o status da entrega atual é atualizado. `carrier` deve ser igual ao da entrega existente; caso contrário a API responde **HTTP 400** (`CARRIER_MISMATCH`).
* **Pedido sem entrega** — uma entrega é **criada** já com o status informado usando o `carrier` enviado.
### Exemplo — sucesso direto em frota própria [#exemplo--sucesso-direto-em-frota-própria]
Pedido que ainda não foi despachado: envie `status=SUCCESSFUL` + `carrier=PRIVATE-FLEET` e a entrega nasce concluída.
```http
PUT /seller-group/v1/orders/{order_id}/status
x-abbiamo-seller-group-key:
Content-Type: application/json
{
"status": "SUCCESSFUL",
"sub_status": "DELIVERED",
"carrier": "PRIVATE-FLEET",
"event_at": "2026-06-16T18:37:12.000Z",
"observation": "Entrega confirmada pelo operador"
}
```
Resposta de sucesso:
```json
{ "success": true }
```
O pedido passa para `status_name: SUCCESSFUL`, `last_delivery_type: PRIVATE-FLEET`.
## Valores válidos [#valores-válidos]
### `status` / `sub_status` [#status--sub_status]
Por enquanto este endpoint aceita **apenas** `status: "SUCCESSFUL"` com `sub_status: "DELIVERED"`.
| `status` | `sub_status` | Descrição |
| ------------ | ------------ | ----------------------------- |
| `SUCCESSFUL` | `DELIVERED` | Entrega realizada com sucesso |
### `carrier` [#carrier]
| Valor | Descrição |
| --------------- | ------------- |
| `PRIVATE-FLEET` | Frota própria |
---
# Atualizar dados do pedido (/docs/api/orders/update-order)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint atualiza dados gerais de um pedido existente. Informe **ao menos um** dos campos abaixo:
* `invoice_number` — número da nota fiscal do pedido.
* `access_key` — chave de acesso da nota fiscal (44 dígitos).
Campos que não forem enviados permanecem inalterados.
A requisição falha com **HTTP 404** se o pedido não existir ou não pertencer à sua conta.
---
# Retirada (Clique e Retire) (/docs/api/retira)
O **Clique e Retire** é a jornada de autoatendimento de retirada na loja: o cliente escaneia o QR Code exposto no balcão, informa o código de rastreio do pedido e confirma a retirada presencialmente.
Estes endpoints entregam, por filial, os dois materiais que vão no ponto de venda — o **QR Code estático** e o **PDF de instruções**. São fixos por filial: gere uma vez e reutilize em todos os cartazes e adesivos daquela loja.
Procurando o passo a passo ponta a ponta da operação? Veja o guia [Clique e Retire — material de retirada por filial](/docs/api/guias/retira-clique-e-retire).
## Endpoints relacionados [#endpoints-relacionados]
A jornada de retirada também usa endpoints no escopo do pedido:
* [Obter token de retirada](/docs/api/orders/get-takeout-token) — gera o token único que o cliente apresenta na loja (modalidade Pick\&Go).
* [Marcar pedido como retirado](/docs/api/orders/set-order-as-withdrawn) — fecha o ciclo movendo o pedido para `SUCCESSFUL.WITHDRAWN`.
---
# Instruções de retirada (PDF) (/docs/api/retira/instructions)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint devolve um **PDF** com as instruções de retirada de uma filial — o material de apoio que acompanha o [QR Code estático](/docs/api/retira/static-qrcode) no ponto de venda. Traz o passo a passo que o cliente segue para retirar o pedido:
1. Escanear o QR Code de retirada.
2. Informar o código de rastreio recebido por e-mail e SMS para buscar o pedido.
3. Preencher os dados e o código de confirmação para validar a retirada na loja.
4. Conferir que a retirada foi confirmada com sucesso.
A filial é identificada pelo `identifier` na URL (o mesmo `seller_identifier` usado na criação de pedidos) e precisa pertencer ao seller group autenticado.
## Exemplo do material [#exemplo-do-material]
O PDF vem pronto para impressão, com a marca, o QR Code da filial e o passo a passo da retirada:
A resposta é binária (`application/pdf`). Salve o corpo da resposta direto como arquivo `.pdf` para imprimir ou exibir no ponto de venda.
A requisição falha com **403** se a filial informada não pertencer ao seller group autenticado, e com **404** se nenhuma filial for encontrada para o `identifier`.
---
# QR Code estático de retirada (/docs/api/retira/static-qrcode)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint devolve a imagem **PNG** do QR Code estático de retirada de uma filial. É o QR que vai nos materiais de **Clique e Retire** expostos no ponto de venda — o cliente escaneia no balcão para iniciar a jornada de autoatendimento de retirada.
O QR é **fixo por filial**: gere uma vez e reutilize em todos os cartazes e adesivos daquela loja. A filial é identificada pelo `identifier` na URL (o mesmo `seller_identifier` usado na criação de pedidos) e precisa pertencer ao seller group autenticado.
**O QR escopa a busca pela filial.** Quando o cliente escaneia este QR e informa o código de rastreio, a jornada de retirada só encontra pedidos de retirada (`TAKEOUT`) **daquela filial**, criados nos últimos 3 meses. Por isso o material é por filial: se a sua bandeira tem mais de uma filial, gere **um QR por filial** — um QR único da bandeira só acharia os pedidos de uma única filial.
A resposta é binária (`image/png`). Salve o corpo da resposta direto como arquivo `.png`, ou embuta a imagem no seu material de impressão.
A requisição falha com **403** se a filial informada não pertencer ao seller group autenticado, e com **404** se nenhuma filial for encontrada para o `identifier`.
---
# Cancelar rota (/docs/api/routes/cancel-route)
{/* concept-backlink */}
Entenda o conceito no guia: [Rota](/docs/log/conceitos/rota).
---
# Trocar motorista da rota (/docs/api/routes/change-driver-of-route)
{/* concept-backlink */}
Entenda o conceito no guia: [Rota](/docs/log/conceitos/rota).
---
# Criar rota (com pedidos novos ou existentes) (/docs/api/routes/create-route-for-new-orders)
{/* concept-backlink */}
Uso no produto: [TMS — app em rota](/docs/tms).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
**Só pedidos existentes? Use [`POST /v2/routes`](/docs/api/routes/create-route-from-orders).** Esse outro endpoint é purpose-built pra roteirizar pedidos que já estão na Abbiamo: payload enxuto (`order_ids` + warehouse de partida), sem precisar reenviar endereço, cliente ou nota fiscal.
Este aqui (`/v2/orders/route`) faz sentido quando você **cria os pedidos junto com a rota** na mesma chamada — ou quando mistura pedidos novos e existentes no mesmo array. O campo `already_exists` na resposta indica, pra cada pedido, se ele já existia ou foi criado agora.
Este endpoint cria uma rota agrupando múltiplos pedidos. Uma rota é um conjunto de pedidos atribuídos a um motorista, com ordem de paradas definida.
O campo `driver_document` é opcional — quando a rota é enviada sem `driver_document`, o sistema cria uma rota **ociosa**, sem transportadora nem motorista atribuídos, que pode ser atribuída depois pelo dashboard.
**Pedidos de devolução (`type: RETURN`).** Para pedidos do tipo `RETURN`, informe `source_address` (o endereço do cliente onde o motorista vai coletar o pacote) no lugar de `destination_address`. Internamente o sistema usa esse endereço como destino do pedido.
O campo `type` assume `DELIVERY` por padrão quando não informado.
## Como pedidos existentes são tratados [#como-pedidos-existentes-são-tratados]
* O campo `already_exists` na resposta indica, pra cada pedido, se ele já existia no sistema no momento da requisição.
* Se um ou mais pedidos já existem no sistema, há dois desfechos possíveis:
* São **roteirizáveis** (status em `CREATED`, `FAILED`, `RETURNED`, etc.) — entram na rota junto com os novos.
* **Não são roteirizáveis** (já estão em rota, já foram entregues, etc.) — a requisição retorna erro.
⛔ **Este endpoint não edita pedidos.** Se um ou mais pedidos já existem no sistema com endereço diferente do enviado na requisição, o pedido antigo (com o endereço antigo) é agrupado na rota — o endereço novo é ignorado.
## Outras observações [#outras-observações]
* `driver_document`, quando informado, precisa ser de um motorista atribuído a pelo menos uma das filiais dos pedidos da rota.
---
# Criar rota a partir de pedidos existentes (/docs/api/routes/create-route-from-orders)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Use este endpoint quando você **já tem os pedidos criados** na Abbiamo (via [Criar pedido (v2)](/docs/api/orders/create-order-v2), pelo dashboard ou por integração) e quer agrupá-los em uma nova rota da frota própria.
Diferente de [Criar rota com pedidos novos ou existentes](/docs/api/routes/create-route-for-new-orders), aqui o payload é enxuto: você manda apenas os `order_ids` e configura a rota (warehouse de partida, motorista, custo). Nada de endereços de destino, número do pedido ou nota fiscal — esses dados já estão nos pedidos.
## Quando usar este endpoint vs. os outros [#quando-usar-este-endpoint-vs-os-outros]
| Cenário | Endpoint |
| ---------------------------------------------------------- | ----------------------------------------------------------------------- |
| Já tenho os pedidos criados e só quero agrupar em rota | **`POST /v2/routes`** (esta página) |
| Vou criar os pedidos e a rota juntos, em uma única chamada | [`POST /v2/orders/route`](/docs/api/routes/create-route-for-new-orders) |
| Vou criar um pedido individual (sem rota) | [`POST /v2/order`](/docs/api/orders/create-order-v2) |
## Pré-requisitos [#pré-requisitos]
* Todos os `order_ids` precisam **pertencer ao seller group** autenticado.
* Todos precisam estar **roteirizáveis** — um pedido deixa de ser roteirizável quando já foi incluído em outra rota ou despachado individualmente pra uma transportadora (TRP). Status como `CREATED`, `FAILED` e `RETURNED` são roteirizáveis; veja [Status & Substatus](/docs/api/conceitos/tables/status-and-substatus) pra detalhes.
* `route.start` é obrigatório — atualmente só aceita `type: "WAREHOUSE_SELLER_IDENTIFIER"`, ou seja, o warehouse da filial identificada pelo `value`.
* `driver_document`, quando informado, precisa ser de um motorista já vinculado ao seller group.
## Sequência das paradas [#sequência-das-paradas]
Por padrão, a Abbiamo otimiza a sequência das paradas. Pra forçar a ordem exata do array `order_ids`, envie `route.orders_sequenced: true`.
## Erros comuns [#erros-comuns]
* **`INVOICE_NOT_ROUTEABLE`** (400) — um ou mais pedidos não são mais roteirizáveis (já estão em rota ou foram despachados). O campo `params.order_ids` lista exatamente quais — remova-os do payload ou desfaça o despacho anterior antes de tentar de novo.
* **`INVOICE_NOT_FOUND_OR_NOT_IN_SELLER_GROUP`** (404) — algum `order_id` não existe ou pertence a outro seller group.
* **`WAREHOUSE_NOT_FOUND`** (404) — o `seller_identifier` do `route.start` (ou `route.end`) não tem warehouse cadastrado pra frota própria.
* **`DRIVER_NOT_FOUND`** (404) — o `driver_document` informado não está vinculado ao seller group.
---
# Rotas (Routes) (/docs/api/routes)
> Pra roteirizar pedidos que já estão na Abbiamo, use **[`POST /v2/routes`](/docs/api/routes/create-route-from-orders)** — payload enxuto, só com os `order_ids`. Use **[`POST /v2/orders/route`](/docs/api/routes/create-route-for-new-orders)** quando precisar criar pedidos novos junto da rota (ou misturar novos + existentes na mesma chamada).
---
# Marcadores (/docs/api/tags)
---
# Listar marcadores (/docs/api/tags/list-tags)
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
Use os `id`s retornados para preencher o campo `tag_ids` ao criar pedidos via [`POST /v2/order`](/docs/api/orders/create-order-v2).
---
# Criar filial (/docs/api/sellers/create-seller)
{/* concept-backlink */}
Entenda o conceito no guia: [Filial (Seller)](/docs/log/conceitos/filial).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint cria uma nova filial na sua conta, identificada pelo `seller_identifier` informado.
---
# Listar filiais (/docs/api/sellers/get-sellers)
{/* concept-backlink */}
Entenda o conceito no guia: [Filial (Seller)](/docs/log/conceitos/filial).
**Header obrigatório.** Toda chamada exige o header `x-abbiamo-seller-group-key`.
Preencha-o no canto superior direito desta página ou veja [como obter a sua chave](/docs/api/conceitos/authentication).
**Rate limit:** 300 requisições por minuto por chave. Acima disso a API retorna **HTTP 429**.
Este endpoint retorna suas filiais paginadas, com `page_size` padrão de 10 resultados por página.
É fácil paginar os resultados usando o campo `has_next_page`. Considerando todos os campos presentes na resposta, recomendamos uma das duas abordagens:
* se page \< total\_pages
* se has\_next\_page
```json
{
"page": 1,
"page_size": 10,
"total_pages": 9,
"has_next_page": true,
"total_results": 86,
"results": [...]
}
```
---
# Filiais (Sellers) (/docs/api/sellers)
---
# Evento `DISPUTE_STATUS_CHANGE` (/docs/api/webhook/dispute-status-change)
Evento enviado ao seller sempre que uma **disputa de pós-venda (Care)** muda de estado — abertura, mudança de status/sub-status, acionamento ou resposta da transportadora, e resolução. Use-o para refletir o pós-venda no seu próprio sistema (ERP, CRM, planilha).
Para assinar, crie um webhook em **Configurações → Webhooks** apontando para o seu endpoint e selecione o evento `DISPUTE_STATUS_CHANGE`.
## Estrutura base [#estrutura-base]
A cada disparo, a Abbiamo faz um `POST` no seu endpoint com este corpo:
```json
{
"event_type": "DISPUTE_STATUS_CHANGE",
"dispute_public_id": "A7ELSB88",
"invoice_id": "a1b2c3d4-0000-0000-0000-000000000000",
"status": "pending",
"sub_status": "with_carrier",
"carrier_type": "CORREIOS",
"carrier_status": "pending",
"carrier_sub_status": "awaiting_response",
"outcome": null,
"resolution": null,
"compensation_amount": null,
"compensation_currency": null,
"rejection_reason_code": null,
"closure_reason": null,
"event_at": "2026-06-08T18:32:10.494Z"
}
```
## Glossário de campos [#glossário-de-campos]
| Campo | Tipo | Notas |
| ----------------------- | --------------------------------- | -------------------------------------------------------------------------------------------- |
| `event_type` | string | sempre `"DISPUTE_STATUS_CHANGE"` |
| `dispute_public_id` | string | ID curto da disputa, igual ao exibido no painel |
| `invoice_id` | string (uuid) | pedido a que a disputa pertence |
| `status` | `"pending" \| "resolved"` | situação geral |
| `sub_status` | string \| null | de quem é a vez (`with_brand`, `with_carrier`, `with_customer`…); `null` quando resolvida |
| `carrier_type` | string \| null | slug da transportadora responsável, ou `null` se não atribuída |
| `carrier_status` | `"pending" \| "resolved" \| null` | situação da trilha com a transportadora |
| `carrier_sub_status` | string \| null | `not_engaged`, `awaiting_response`, `paid`, `denied`… |
| `outcome` | string \| null | desfecho: `delivered`, `returned`, `lost`, `false_claim`, `undecided` — só quando `resolved` |
| `resolution` | string \| null | compensação: `none`, `refund`, `voucher`, `replacement`, `denied` |
| `compensation_amount` | string \| null | valor decimal (ex.: `"49.90"`) |
| `compensation_currency` | string \| null | ex.: `"BRL"` |
| `rejection_reason_code` | string \| null | código do motivo da recusa (quando `resolution = "denied"`) |
| `closure_reason` | string \| null | `cancelled_by_customer`, `cancelled_by_brand`, `auto_closed` |
| `event_at` | ISO datetime | data/hora do evento |
Os campos de **desfecho** (`outcome`, `resolution`, `compensation_*`) só vêm preenchidos quando a disputa é **resolvida** (`status = "resolved"`). Enquanto `pending`, eles ficam `null`.
## Exemplos [#exemplos]
```json
{
"status": "pending",
"sub_status": "with_brand",
"carrier_type": null,
"carrier_status": null,
"outcome": null,
"resolution": null
}
```
```json
{
"status": "pending",
"sub_status": "with_carrier",
"carrier_type": "CORREIOS",
"carrier_status": "pending",
"carrier_sub_status": "awaiting_response"
}
```
```json
{
"status": "resolved",
"sub_status": null,
"outcome": "lost",
"resolution": "refund",
"compensation_amount": "49.90",
"compensation_currency": "BRL"
}
```
```json
{
"status": "resolved",
"sub_status": null,
"outcome": "false_claim",
"resolution": "denied",
"rejection_reason_code": "no_evidence"
}
```
---
# Webhooks (/docs/api/webhook)
---
# Evento `ORDER_CSAT_ANSWER` (/docs/api/webhook/order-csat-answer)
| Campo | Tipo | Descrição |
| :------------------------------------- | :---------------------------- | :----------------------------------------------------------------------------- |
| order\_id | string | UUID gerado pela Abbiamo na criação do pedido |
| order\_number | string | Mesmo valor do campo `order_number` enviado no endpoint Criar pedido (v2) |
| order\_type | string | Mesmo valor do campo `type` enviado no endpoint Criar pedido (v2) |
| invoice\_number | string | Mesmo valor do campo `invoice_number` enviado no endpoint Criar pedido (v2) |
| access\_key | string | |
| invoice\_created\_timestamp | string | |
| seller\_identifier | string | Mesmo valor do campo `seller_identifier` enviado no endpoint Criar pedido (v2) |
| seller\_document\_number | string | CPF/CNPJ cadastrado da filial |
| seller\_trading\_name | string | Nome fantasia cadastrado da filial |
| external\_order\_id | string | Mesmo valor do campo `external_id` enviado no endpoint Criar pedido (v2) |
| event\_type | string("ORDER\_CSAT\_ANSWER") | |
| tracking | string(length: 7) | Código de rastreio gerado pela Abbiamo |
| timestamp | integer | Timestamp do momento em que a Abbiamo disparou o evento |
| event\_at | ISOString | Timestamp (ISOString) do momento em que o evento aconteceu |
| customer\_name | string | Mesmo valor do campo `customer.name` enviado no endpoint Criar pedido (v2) |
| customer\_phone | string | Mesmo valor do campo `customer.phone` enviado no endpoint Criar pedido (v2) |
| customer\_email | string | Mesmo valor do campo `customer.email` enviado no endpoint Criar pedido (v2) |
| customer\_delivery\_experience\_rating | integer | |
| customer\_feedback\_comment | string | |
```json Example
{
"customer_delivery_experience_rating": 10,
"customer_feedback_comment": "Testeeeeeee",
"order_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
"order_number": "123456789",
"order_type": "DELIVERY",
"invoice_number": "xxxxxxxxxx",
"access_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"invoice_created_timestamp": "2023-01-09T13:43:21.000Z",
"seller_identifier": "1234569191",
"seller_document_number": "1234569191",
"seller_trading_name": "Go Go Salads",
"external_order_id":"1892831",
"event_type":"ORDER_CSAT_ANSWER",
"tracking": "a7g92yd",
"timestamp": 1661280476296,
"event_at": "2023-01-10T10:18:44.000Z",
"customer_name": "John Doe",
"customer_phone": "21999999999",
"customer_email": "john@email.com"
}
```
---
# Evento `ORDER_DELAY` (/docs/api/webhook/order-delay)
Evento enviado ao seller quando um pedido **fura o prazo prometido ao cliente** — ou quando **entra em risco** de furar, se você configurou marcadores de risco. Vale para **qualquer pedido** que tenha prazo de cliente, com ou sem marcador.
O disparo é **agendado no momento em que o pedido nasce**, a partir do prazo informado na criação, e acontece no instante exato desse prazo (ou da antecedência da regra de risco). Nesse instante a Abbiamo **revalida o pedido**: se ele já foi entregue, cancelado, baixado manualmente ou devolvido, nada é enviado.
Para assinar, crie um webhook em **Configurações → Webhooks** apontando para o seu endpoint e selecione o evento `ORDER_DELAY`.
## Os dois gatilhos [#os-dois-gatilhos]
O campo **`trigger`** diz por que o evento chegou. Ele é a primeira coisa que o seu consumidor deve olhar.
| `trigger` | Quando dispara | O que vem no payload |
| ------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `DELAYED` | O prazo prometido ao cliente **estourou** e o pedido não foi concluído | `overdue: true`, `risk_marker: null`, `rule_id: null` |
| `RISK_MARKER` | Uma **regra de risco** que você configurou acendeu um marcador **antes** do prazo | `risk_marker` preenchido, `rule_id` preenchido, `overdue` normalmente `false` |
`DELAYED` é automático e vale para todo pedido com prazo de cliente — não precisa configurar nada. `RISK_MARKER` só existe se você criou regras em *Configuração → Marcadores de risco de entrega*.
Um mesmo pedido pode gerar **os dois**: primeiro o `RISK_MARKER` (faltando 30 min), depois o `DELAYED` (quando o prazo estourou de fato).
Este evento **não é uma mudança de status**. O pedido continua no status em que estava — o campo `status` vem só como contexto do momento do disparo. Se você já trata `ORDER_STATUS_CHANGE`, trate este num caminho separado.
**Duas datas diferentes, não confunda.** Este evento usa o `promised_delivery_date` — o prazo que **você** prometeu ao cliente final e nos enviou em `POST /v2/order`. Não é o `expected_delivery_date` do `ORDER_STATUS_CHANGE`, que é o prazo combinado com a **transportadora**. O `ORDER_DELAY` mede o compromisso com o cliente, não com o parceiro logístico.
## Estrutura base [#estrutura-base]
A cada disparo, a Abbiamo faz um `POST` no seu endpoint com este corpo:
```json
{
"event_type": "ORDER_DELAY",
"trigger": "DELAYED",
"order_id": "3f9a1c22-0000-0000-0000-000000000000",
"order_number": "1042",
"invoice_number": "000123456",
"external_order_id": "PED-98213",
"tracking": "AB12CD34EF",
"seller_id": "8c1e4b70-0000-0000-0000-000000000000",
"seller_group_id": "b7d2f011-0000-0000-0000-000000000000",
"seller_identifier": "loja-centro",
"order_type": "DELIVERY",
"status": "START_DELIVERY",
"sub_status": null,
"delivery_type": "BEE",
"promised_delivery_date": "2026-07-27T21:00:00.000Z",
"threshold_minutes": 0,
"minutes_to_deadline": 0,
"overdue": true,
"risk_marker": null,
"rule_id": null,
"event_at": "2026-07-27T21:00:03.482Z",
"timestamp": 1785186003482
}
```
## Glossário de campos [#glossário-de-campos]
| Campo | Tipo | Notas |
| ------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `event_type` | string | sempre `"ORDER_DELAY"` |
| `trigger` | `"DELAYED" \| "RISK_MARKER"` | **por que o evento chegou** — veja a tabela acima |
| `order_id` | string (uuid) | identificador do pedido na Abbiamo |
| `order_number` | string | número do pedido no painel |
| `invoice_number` | string \| null | número da nota fiscal |
| `external_order_id` | string \| null | seu identificador, enviado na criação |
| `tracking` | string | código de rastreio público |
| `seller_id` | string (uuid) | filial dona do pedido |
| `seller_group_id` | string (uuid) | marca (seller group) |
| `seller_identifier` | string \| null | identificador externo da filial |
| `order_type` | string | `DELIVERY`, `TAKEOUT`, `RETURN`… |
| `status` | string | status do pedido **no momento do disparo** (contexto, não mudança) |
| `sub_status` | string \| null | sub-status correspondente |
| `delivery_type` | string \| null | transportadora atribuída, ou `null` se ainda não despachado. Mesmo vocabulário do `delivery_type` do `ORDER_STATUS_CHANGE` |
| `promised_delivery_date` | ISO datetime | prazo prometido ao cliente que serviu de âncora — o mesmo valor que você enviou em `POST /v2/order` |
| `threshold_minutes` | number | antecedência da regra; **sempre `0`** quando `trigger = "DELAYED"` |
| `minutes_to_deadline` | number | minutos restantes até o prazo; **negativo** se já estourou |
| `overdue` | boolean | `true` quando o prazo já passou no momento do disparo |
| `risk_marker` | objeto \| null | `null` quando `trigger = "DELAYED"` |
| `risk_marker.id` | string (uuid) | marcador de risco aplicado |
| `risk_marker.name` | string | nome que você deu ao marcador (ex.: `"Risco de Entrega Grave"`) |
| `risk_marker.color` | string | cor em hexadecimal, a mesma exibida no painel |
| `rule_id` | string (uuid) \| null | regra de risco que originou o disparo; `null` quando `trigger = "DELAYED"` |
| `event_at` | ISO datetime | data/hora do disparo |
| `timestamp` | number | mesmo instante em epoch (ms) |
## Garantias de entrega [#garantias-de-entrega]
Leia esta seção antes de escrever o consumidor — as garantias aqui são diferentes das do `ORDER_STATUS_CHANGE`.
* **Entrega é *at-least-once*: deduplique do seu lado.** O normal é chegar um evento por gatilho, mas uma repetição é possível. Trate `order_id` + `trigger` (+ `risk_marker.id`, quando houver) como chave e ignore o que já processou — é a única garantia da qual vale depender.
* **Um `RISK_MARKER` por par (pedido, marcador).** Se duas regras acendem o **mesmo** marcador no mesmo pedido, chega **um** evento — o da primeira que vencer. Regras que acendem marcadores **diferentes** geram eventos distintos.
* **Nada é enviado para pedido já concluído.** No instante do disparo o pedido é revalidado: `SUCCESSFUL`, `CANCELED`, `MANUAL_HANDLE` (baixa manual) e `RETURNED` cancelam o envio silenciosamente.
* **Prazo em branco não dispara.** Pedido sem `promised_delivery_date` nunca gera `ORDER_DELAY`. O prazo é lido **na criação do pedido** — é ali que o disparo é agendado.
* **Retirada em loja fica de fora.** Pedidos `TAKEOUT` não têm prazo de entrega ao cliente — é o mesmo recorte da coluna *Situação de entrega*, que mostra "Sem info" para eles.
* **Não há evento de "saiu do atraso".** O disparo é de mão única; a conclusão você recebe pelo `ORDER_STATUS_CHANGE` com `status: "SUCCESSFUL"`.
* **Retentativas:** até 3 tentativas com timeout de 20s por chamada, igual aos demais webhooks. Todos os disparos ficam auditáveis em **Configurações → Logs → Webhooks**.
## Exemplos [#exemplos]
```json
{
"event_type": "ORDER_DELAY",
"trigger": "DELAYED",
"status": "START_DELIVERY",
"promised_delivery_date": "2026-07-27T21:00:00.000Z",
"threshold_minutes": 0,
"minutes_to_deadline": 0,
"overdue": true,
"risk_marker": null,
"rule_id": null
}
```
```json
{
"event_type": "ORDER_DELAY",
"trigger": "RISK_MARKER",
"status": "START_DELIVERY",
"promised_delivery_date": "2026-07-27T21:00:00.000Z",
"threshold_minutes": 30,
"minutes_to_deadline": 30,
"overdue": false,
"risk_marker": {
"id": "d81f9a3c-0000-0000-0000-000000000000",
"name": "Risco de Entrega Grave",
"color": "#D92D20"
},
"rule_id": "0a55c7e2-0000-0000-0000-000000000000"
}
```
```json
{
"event_type": "ORDER_DELAY",
"trigger": "DELAYED",
"status": "PENDING",
"promised_delivery_date": "2026-07-27T18:00:00.000Z",
"threshold_minutes": 0,
"minutes_to_deadline": -45,
"overdue": true,
"risk_marker": null,
"rule_id": null
}
```
## Como consumir [#como-consumir]
O caso de uso mais direto é **abrir um alerta interno** (ticket, mensagem no canal do time, linha num painel) sem depender de alguém olhando a lista de Pedidos.
```js
app.post('/abbiamo/webhook', (req, res) => {
const e = req.body
if (e.event_type !== 'ORDER_DELAY') return res.sendStatus(200)
if (e.trigger === 'DELAYED') {
abrirOcorrencia(e.order_id, `Pedido ${e.order_number} atrasou`)
} else {
avisarTime(e.order_id, `${e.order_number}: ${e.risk_marker.name}`)
}
res.sendStatus(200)
})
```
Sugestões práticas:
* **Ramifique sempre pelo `trigger`.** Um `RISK_MARKER` é um aviso preventivo; um `DELAYED` é um fato consumado. Tratar os dois igual gera ruído no time.
* **Deduplique por `order_id` + `trigger`** (+ `risk_marker.id`, quando houver). O mesmo pedido gera um `RISK_MARKER` e depois um `DELAYED` — são eventos distintos —, e a entrega é at-least-once.
* `minutes_to_deadline` já vem calculado a partir do `promised_delivery_date` — não recalcule se o seu servidor estiver em outro fuso.
* Combine com o `ORDER_STATUS_CHANGE`: ao receber `SUCCESSFUL` para um pedido que atrasou, feche o alerta.
---
# Evento `ORDER_RECEIVER_UPDATE` (/docs/api/webhook/order-receiver-update)
Evento que carrega os **dados do recebedor** de uma entrega — nome, documento, descrição (ex.: "Vizinho") — e/ou o **comprovante de entrega (POD)**: fotos e assinatura.
Ele é disparado **sempre que um evento de entrega traz recebedor e/ou anexos** — tipicamente junto da confirmação de entrega (`SUCCESSFUL`).
## Por que um evento separado [#por-que-um-evento-separado]
Quando a transportadora captura o recebedor/POD **no mesmo momento da entrega**, esses dados já acompanham o próprio `ORDER_STATUS_CHANGE` de `SUCCESSFUL` (nos campos `receiver_name`, `receiver_description` e `attachments`) — e o `ORDER_RECEIVER_UPDATE` chega junto, com a mesma informação.
O valor deste evento está no caso em que esses dados são reportados **separadamente**: a transportadora confirma a entrega primeiro e só registra o recebedor/comprovante **depois** (minutos ou horas mais tarde). Nesse cenário o `SUCCESSFUL` já foi enviado **sem** esses campos, e é o `ORDER_RECEIVER_UPDATE` que entrega o recebedor/POD posteriormente.
Para receber o recebedor/comprovante de forma confiável — independente de a transportadora reportar junto ou depois da entrega — **ouça o `ORDER_RECEIVER_UPDATE`**. Confiar só no `ORDER_STATUS_CHANGE` faz você perder os casos em que o recebedor/POD chega após a confirmação.
O evento depende de a transportadora **enviar** recebedor e/ou anexos — entregas confirmadas sem esses dados não o geram. Por vir em webhook próprio, ele pode chegar **junto** ou **após** o `SUCCESSFUL` do mesmo pedido; correlacione pelo `order_id`/`tracking`.
## Glossário de campos [#glossário-de-campos]
| Campo | Tipo | Descrição |
| -------------------------- | ------------------------------ | ---------------------------------------------------------- |
| `event_type` | `"ORDER_RECEIVER_UPDATE"` | identificador do evento |
| `order_id` | uuid | UUID do pedido na Abbiamo |
| `order_number` | string | mesmo valor do `number` enviado no `create-order` |
| `order_type` | string | `DELIVERY`, `TAKEOUT`, `RETURN`, etc. |
| `invoice_number` | string | número da nota fiscal |
| `external_order_id` | string \| null | ID externo do pedido (se informado na criação) |
| `seller_identifier` | string | identificador da filial |
| `seller_id` | uuid | ID interno da filial |
| `seller_group_id` | uuid | ID interno da conta |
| `creation_origin` | string | origem do pedido (`API-V2`, `VTEX`, etc.) |
| `tracking` | string(7) | código de rastreio gerado pela Abbiamo |
| `timestamp` | integer | timestamp em ms de quando o evento foi disparado |
| `event_at` | ISO datetime | quando o evento aconteceu |
| `receiver_name` | string \| null | nome de quem recebeu o pedido |
| `receiver_document_number` | string \| null | documento de quem recebeu |
| `receiver_description` | string \| null | descrição livre (ex.: "Porteiro", "Vizinho") |
| `attachments` | `Array<{ url, type }>` \| null | anexos do POD (Proof of Delivery) |
| `attachments[].url` | URL | URL pública do anexo |
| `attachments[].type` | `"image"` \| `"signature"` | tipo do anexo — foto da entrega ou assinatura do recebedor |
`attachments` pode trazer **múltiplos itens** — tipicamente uma `image` (foto da entrega) e uma `signature` (assinatura do recebedor). Pode vir vazio/ausente quando não houve captura.
## Exemplo [#exemplo]
```json
{
"order_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
"order_number": "123456789",
"order_type": "DELIVERY",
"invoice_number": "xxxxxxxxxx",
"external_order_id": "1892831",
"seller_identifier": "1234569191",
"seller_id": "f3b3a3a3-aaaa-bbbb-cccc-ddddddddddd",
"seller_group_id": "c2c2c2c2-aaaa-bbbb-cccc-ddddddddddd",
"creation_origin": "API-V2",
"event_type": "ORDER_RECEIVER_UPDATE",
"tracking": "a7g92yd",
"timestamp": 1661280476296,
"event_at": "2026-05-26T13:50:07.709Z",
"receiver_name": "João",
"receiver_document_number": "12345678909",
"receiver_description": "Vizinho",
"attachments": [
{
"url": "https://attachments.abbiamolog.com/11111111-1111-1111-1111-111111111111.jpeg",
"type": "image"
},
{
"url": "https://attachments.abbiamolog.com/22222222-2222-2222-2222-222222222222.jpeg",
"type": "signature"
}
]
}
```
---
# Evento `ORDER_STATUS_CHANGE` (/docs/api/webhook/order-status-change)
Evento enviado ao seller a cada mudança de status do pedido. A página de [Status & Substatus](/docs/api/conceitos/tables/status-and-substatus) descreve cada estado e suas transições.
## Estrutura base [#estrutura-base]
Todo evento `ORDER_STATUS_CHANGE` chega com este **envelope base**. Os cards mais abaixo (CREATED, DISPATCHED, IN\_TRANSIT…) mostram só o **delta** — o que muda ou aparece a mais em cada status.
```json
{
"order_id": "33595136-bf9d-4a07-89ff-8fca22166a0d",
"order_number": "26007537",
"order_type": "DELIVERY",
"external_order_id": "26025007537_25044",
"invoice_number": "46631",
"access_key": "35200000000000000000000000000000000000000000",
"invoice_created_timestamp": "2026-05-28T13:53:29.000Z",
"tracking": "W9GR58BEU10A",
"seller_identifier": "12345678000190",
"seller_document_number": "12345678000190",
"seller_trading_name": "Loja XYZ",
"seller_id": "d40466d4-8cbf-431a-ae71-a11913965d80",
"seller_group_id": "1d967918-f877-49a3-95a0-673cdcab0ab8",
"customer_name": "João Silva",
"customer_phone": "21999999999",
"customer_email": "joao@email.com",
"customer_document_number": "00000000000",
"event_type": "ORDER_STATUS_CHANGE",
"event_at": "2026-05-28T21:14:10.494Z",
"timestamp": 1780002850946,
"event_observation": null,
"delivery_type": "CARRIER",
"status": "CREATED",
"sub_status": null,
"expected_delivery_price": null,
"expected_delivery_date": null,
"final_delivery_price": null,
"delivery_eta": null
}
```
**`order_type`** define o caminho: `DELIVERY` (entrega ao cliente), `TAKEOUT` (retirada na loja) ou `RETURN` (logística reversa).
**`delivery_type`** identifica quem está executando a entrega: `CARRIER`, `PRIVATE-FLEET`, `TAKEOUT`, ou o slug da transportadora (`TRANSPORTADORA-C`, `UBER`, `99-ENTREGAS`, etc.).
## Glossário de campos [#glossário-de-campos]
| Campo | Tipo | Notas |
| ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------- |
| `status` | string (enum) | sempre presente — ver [Status & Substatus](/docs/api/conceitos/tables/status-and-substatus) |
| `sub_status` | string \| null | varia conforme o `status` |
| `delivery_type` | string | sempre — `CARRIER`, `PRIVATE-FLEET`, `TAKEOUT`, ou o slug da transportadora |
| `event_observation` | string \| null | observação textual associada ao evento (motivo de falha, cancelamento, etc.) |
| `driver_name` | string \| null | nome do motorista após atribuição (`DISPATCHED` em diante, quando há motorista) |
| `carrier_name` | string \| null | nome da transportadora quando aplicável (`CARRIER` ou nome do parceiro) |
| `expected_delivery_price` | integer (centavos) \| null | preço estimado pela transportadora — populado a partir de `PENDING`/`DISPATCHED` |
| `expected_delivery_date` | ISO datetime \| null | prazo combinado com a transportadora |
| `delivery_eta` | ISO datetime \| null | ETA dinâmica enviada por carriers que suportam (Uber, 99, etc.) |
| `final_delivery_price` | integer (centavos) \| null | preço efetivo da entrega — **só populado em `SUCCESSFUL`** |
| `failure_code` | integer | só em `FAILED` — ver [Códigos de falha](/docs/api/conceitos/tables/failure-codes) |
| `failure_message` | string | só em `FAILED` |
| `failure_driver_message` | string | só em `FAILED` — relato do motorista |
| `receiver_name` | string | só em `SUCCESSFUL` — nome de quem recebeu a entrega |
| `attachments` | `Array<{ url, type? }>` | só em `SUCCESSFUL.DELIVERED` quando há POD. `type`: `"image"` ou `"signature"` |
## Exemplos por status [#exemplos-por-status]
Cada card mostra **apenas o delta** sobre o envelope base. Os campos que aparecem aqui são os que mudam ou se somam ao envelope.
```json
{
"status": "CREATED",
"sub_status": null
}
```
```json
{
"status": "PENDING",
"sub_status": "WAITING_FOR_CARRIER",
"carrier_name": "TRANSPORTADORA-C",
"expected_delivery_price": 2500,
"expected_delivery_date": "2026-03-01T02:59:00.000Z",
"delivery_eta": "2026-03-02T14:59:00.000Z"
}
```
```json
{
"status": "DISPATCHED",
"sub_status": "ROUTE_PLANNED",
"driver_name": "João",
"carrier_name": "TRANSPORTADORA-C"
}
```
```json
{
"status": "IN_TRANSIT",
"sub_status": "COLLECTING",
"driver_name": "João",
"carrier_name": "TRANSPORTADORA-C"
}
```
```json
{
"status": "COLLECTED",
"sub_status": null,
"driver_name": "João",
"carrier_name": "TRANSPORTADORA-C"
}
```
```json
{
"status": "START_DELIVERY",
"sub_status": null,
"driver_name": "João",
"carrier_name": "TRANSPORTADORA-C",
"delivery_eta": "2026-05-28T23:59:00.000Z"
}
```
```json
{
"status": "HANDLING",
"sub_status": "TRANSFER_COMPLETED",
"carrier_name": "TRANSPORTADORA-C"
}
```
```json
{
"status": "SUCCESSFUL",
"sub_status": "DELIVERED",
"driver_name": "João",
"carrier_name": "TRANSPORTADORA-C",
"receiver_name": "Maria Silva",
"final_delivery_price": 952,
"expected_delivery_price": 1200,
"delivery_eta": "2026-05-28T23:59:00.000Z",
"attachments": [
{ "url": "https://attachments.abbiamolog.com/...jpeg", "type": "image" },
{ "url": "https://attachments.abbiamolog.com/...jpeg", "type": "signature" }
]
}
```
```json
{
"status": "FAILED",
"sub_status": "COLLECT_FAILED",
"driver_name": "João",
"carrier_name": "TRANSPORTADORA-C",
"failure_code": 17,
"failure_message": "Outro",
"failure_driver_message": "Loja fechada quando cheguei"
}
```
```json
{
"status": "ORDER_FAILED",
"sub_status": "CARRIER_TIMEOUT"
}
```
```json
{
"status": "CANCELED",
"sub_status": "RETURNED_TO_SELLER",
"event_observation": "Cliente solicitou cancelamento após coleta"
}
```
```json
{
"status": "RETURNING",
"sub_status": null,
"driver_name": "João",
"carrier_name": "TRANSPORTADORA-C"
}
```
```json
{
"status": "RETURNED",
"sub_status": null,
"carrier_name": "TRANSPORTADORA-C"
}
```
```json
{
"status": "MANUAL_HANDLE",
"sub_status": null
}
```
---
# Evento `ROUTE_STATUS_CHANGE` (/docs/api/webhook/route-status-change)
## Glossário de campos [#glossário-de-campos]
| Campo | Tipo | Notas |
| ------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `external_name` | string \| null | referência de rota que você mesmo informou na criação — `null` quando nenhuma foi informada |
| `route_cost` | integer (centavos) | custo inicial cotado no momento da criação da rota — snapshot, presente desde `CREATED` |
| `final_route_cost` | integer (centavos) \| null | custo final efetivamente cobrado — preenchido apenas no status `FINISHED`; `null` para rotas legadas ou ainda não finalizadas |
```json CREATED
{
"route_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
"external_name": "08 - MANHÃ",
"status": "CREATED",
"event_type": "ROUTE_STATUS_CHANGE",
"event_at": "2023-01-10T10:18:44.000Z",
"timestamp": 1673363868000,
"route_cost": 1200,
"driver": {
"name": "Joao Felix",
"document": "12312312312"
},
"orders": [
{
"id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
"tracking": "XPT-OqpTlSfxB",
"number": "123123",
"external_id": "xxx"
},
{
"id": "yyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyy",
"tracking": "XBC-ObgTlSfxB",
"number": "345345",
"external_id": "yyy"
},
{
"id": "zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzz",
"tracking": "YPZ-OrwTlSfxB",
"number": "678678",
"external_id": "zzz"
}
]
}
```
```json FINISHED
{
"route_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
"external_name": "08 - MANHÃ",
"status": "FINISHED",
"event_type": "ROUTE_STATUS_CHANGE",
"event_at": "2023-01-10T10:18:44.000Z",
"timestamp": 1673363868000,
"route_cost": 1200,
"final_route_cost": 1500,
"driver": {
"name": "Joao Felix",
"document": "12312312312"
},
"orders": [
{
"id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
"tracking": "XPT-OqpTlSfxB",
"number": "123123",
"external_id": "xxx"
},
{
"id": "yyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyy",
"tracking": "XBC-ObgTlSfxB",
"number": "345345",
"external_id": "yyy"
},
{
"id": "zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzz",
"tracking": "YPZ-OrwTlSfxB",
"number": "678678",
"external_id": "zzz"
}
]
}
```
---
# Evento `TOKEN_GENERATED` (/docs/api/webhook/token-generated)
| Campo | Tipo | Descrição |
| :-------------------------- | :------------------------- | :----------------------------------------------------------------------------- |
| order\_id | string | UUID gerado pela Abbiamo na criação do pedido |
| order\_number | string | Mesmo valor do campo `order_number` enviado no endpoint Criar pedido (v2) |
| order\_type | string | Mesmo valor do campo `type` enviado no endpoint Criar pedido (v2) |
| invoice\_number | string | Mesmo valor do campo `invoice_number` enviado no endpoint Criar pedido (v2) |
| access\_key | string | |
| invoice\_created\_timestamp | string | Timestamp de criação da nota, em milissegundos |
| seller\_identifier | string | Mesmo valor do campo `seller_identifier` enviado no endpoint Criar pedido (v2) |
| seller\_document\_number | string | CPF/CNPJ cadastrado da filial |
| seller\_trading\_name | string | Nome fantasia cadastrado da filial |
| external\_order\_id | string | Mesmo valor do campo `external_id` enviado no endpoint Criar pedido (v2) |
| event\_type | string("TOKEN\_GENERATED") | Identifica o tipo de evento que ocorreu |
| tracking | string(length: 7) | Código de rastreio gerado pela Abbiamo |
| timestamp | integer | Timestamp do momento em que a Abbiamo disparou o evento |
| event\_at | ISOString | Timestamp (ISOString) do momento em que o evento aconteceu |
| customer\_name | string | Mesmo valor do campo `customer.name` enviado no endpoint Criar pedido (v2) |
| customer\_phone | string | Mesmo valor do campo `customer.phone` enviado no endpoint Criar pedido (v2) |
| customer\_email | string | Mesmo valor do campo `customer.email` enviado no endpoint Criar pedido (v2) |
| token | integer | Token gerado por este evento |
| seller\_id | string | Identificador único da filial |
| seller\_group\_id | string | Identificador único do grupo ou marca da filial |
```json Example
{
"token": "798793",
"order_id": "e4b99026-4985-48f2-8e04-6c2e49045d76",
"order_number": "example order",
"order_type": "TAKEOUT",
"invoice_number": null,
"access_key": null,
"invoice_created_timestamp": "2025-10-24T04:14:54.583Z",
"seller_identifier": "12345678000190",
"seller_document_number": "12345678000190",
"seller_trading_name": "Go Go Salads",
"external_order_id": null,
"event_type": "TOKEN_GENERATED",
"tracking": "LZ3IL66BIG2L",
"timestamp": 1761279322758,
"customer_name": "example@user",
"customer_phone": null,
"customer_email": "example@gmail.com",
"event_at": "2025-10-24T04:15:22.758Z",
"seller_id": "258aa03c-355f-4a68-ba22-d6f5edc1d484",
"seller_group_id": "d6e6d1be-144c-4341-b92d-697c7eaa70d4"
}
```
---
# Introdução a webhooks (/docs/api/webhook/webhook-101)
Uma aplicação web que implementa webhooks envia uma requisição HTTP para uma URL sempre que determinados eventos ocorrem. É tão simples quanto fornecer sua URL e aguardar nossas notificações sobre mudanças de status dos pedidos.
## Introdução [#introdução]
Webhooks são uma das formas como aplicações web se comunicam entre si — permitem enviar dados em tempo real de uma aplicação para outra sempre que um evento acontece.
Por exemplo, imagine que você criou um pedido usando a API da Abbiamo. O ideal é poder saber quando o status do pedido mudou de criado para despachado, ou de despachado para em entrega. Isso permite que sua equipe monitore e receba atualizações em tempo real sobre o status dos pedidos.
## Como funciona tecnicamente [#como-funciona-tecnicamente]
Os webhooks são às vezes chamados de “APIs reversas”, pois fornecem o equivalente a uma especificação de API, e você precisa criar um endpoint para que o webhook utilize. O webhook fará uma requisição HTTP (POST) para a sua aplicação, e caberá a você interpretá-la.
Portanto, em vez de tentar verificar periodicamente mudanças de estado nos pedidos, você aguardará que os dados do webhook cheguem ao seu endpoint registrado com o schema descrito na [referência da API de webhooks](/docs/api/webhook/webhook-events).
## API vs Webhooks [#api-vs-webhooks]
Embora os dois funcionem de formas muito distintas, é comum haver confusão entre eles. Em termos simples, uma API é uma interface comum entre duas aplicações diferentes — um intermediário que permite que dois sistemas se comuniquem. Já os webhooks são tipicamente usados para integrar dois sistemas de forma reativa. Uma chamada de API pode ser usada para solicitar dados, enquanto um webhook recebe dados. Em outras palavras, a diferença fundamental entre webhooks e chamadas de API é que o primeiro é baseado em eventos, enquanto o segundo é baseado em requisições.
---
# Eventos de webhook (/docs/api/webhook/webhook-events)
{`
Sempre que uma ação importante ocorre no ecossistema Abbiamo,
um evento é disparado e uma notificação é enviada para os seus servidores.
Abaixo você pode ler mais sobre esses tipos de eventos:
`}
| event\_type | Descrição |
| :---------------------- | :----------------------------------------------------------------------------------- |
| ORDER\_STATUS\_CHANGE | Disparado quando o status de um pedido é alterado |
| ORDER\_DELAY | Disparado quando um pedido atrasa — ou entra em risco de atrasar |
| ORDER\_RECEIVER\_UPDATE | Disparado quando o destinatário do pedido é atualizado |
| ORDER\_CSAT\_ANSWER | Disparado quando o CSAT é respondido por um cliente |
| TOKEN\_GENERATED | Disparado quando o token de retirada é gerado |
| ROUTE\_STATUS\_CHANGE | Disparado quando o status de uma rota é alterado |
| DISPUTE\_STATUS\_CHANGE | Disparado quando uma disputa de pós-venda (Care) abre, muda de status ou é resolvida |
---
# Conceito: Embarcador (/docs/go/conceitos/embarcador)
No contexto **GO**, um **Embarcador** é qualquer cliente para o qual a operação de frota própria executa entregas. Ele é a origem dos pedidos — quem encomenda o serviço de entrega.
***
## Dois tipos de embarcador [#dois-tipos-de-embarcador]
### Embarcador Abbiamo [#embarcador-abbiamo]
Uma empresa que usa o **Abbiamo LOG** como plataforma de gestão logística. Ela cria pedidos no LOG e, ao configurar uma **Integração de Transportadora** apontando para a sua operação GO, passa a direcionar pedidos automaticamente para o seu painel.
**Características:**
* Vínculo criado automaticamente quando a integração é configurada no LOG.
* Pedidos chegam em tempo real sem intervenção manual.
* Dados do embarcador (nome, filiais, configurações) são gerenciados pelo próprio cliente no LOG.
* Identificado como tipo **Abbiamo** na tela de Embarcadores.
### Embarcador Externo [#embarcador-externo]
Uma empresa que **não usa a plataforma Abbiamo**. O agente GO cadastra esse cliente manualmente, configurando nome, identificador, filiais e parâmetros operacionais. Os pedidos entram via API ou importação.
**Características:**
* Criado manualmente pelo agente GO.
* Sem dependência de conta Abbiamo por parte do cliente.
* Dados gerenciados inteiramente pelo agente GO.
* Identificado como tipo **Externo** na tela de Embarcadores.
***
## Comparativo [#comparativo]
| | **Embarcador Abbiamo** | **Embarcador Externo** |
| ---------------------- | -------------------------------- | ----------------------- |
| **Criação** | Automática (via integração LOG) | Manual (pelo agente GO) |
| **Conta Abbiamo** | Necessária (lado LOG) | Não necessária |
| **Entrada de pedidos** | Automática em tempo real | Via API ou importação |
| **Gestão de dados** | Pelo próprio cliente (LOG) | Pelo agente GO |
| **Desvinculação** | Automática ao remover integração | Manual |
***
## O que um embarcador tem no GO [#o-que-um-embarcador-tem-no-go]
Independente do tipo, cada embarcador pode ter:
* **Filiais** — unidades operacionais (pontos de coleta/origem dos pedidos).
* **Pedidos** — entregas a serem executadas pela frota.
* **Automações de Ofertas** — regras que definem quais motoristas recebem as entregas desse embarcador.
***
## Onde aparece na plataforma [#onde-aparece-na-plataforma]
| Tela | Como aparece |
| --------------------------------------------------------------------- | --------------------------------------------------- |
| [**Embarcadores**](/docs/go/products/embarcadores/) | Lista todos os embarcadores (Abbiamo e externos) |
| [**Automações de Ofertas**](/docs/go/products/automacoes-de-ofertas/) | Usado como critério de filial/embarcador nas regras |
| [**Rotas**](/docs/go/products/rotas/) | Pedidos do embarcador são agrupados em rotas |
| [**Relatórios**](/docs/go/products/relatorios/) | Volume e desempenho por embarcador |
---
# Filial (Carrier) (/docs/go/conceitos/filial)
No contexto **GO**, a **Filial** é a unidade operacional da transportadora: cada base, centro de distribuição ou ponto a partir do qual a frota opera. No código e na API aparece como **seller** (a mesma entidade do LOG, porém no perfil de transportadora).
***
## O que compõe uma filial [#o-que-compõe-uma-filial]
### Identificação [#identificação]
| Campo | Descrição |
| ----------------- | --------------------------------- |
| **Nome fantasia** | Nome exibido na plataforma |
| **Razão social** | Razão social da unidade |
| **Identificador** | Identificador externo/customizado |
### Documento [#documento]
* Tipo e número do documento (CNPJ, CPF etc.)
* Inscrição estadual
### Contato e endereço [#contato-e-endereço]
* E-mail e telefone
* Endereço completo da filial (usado como ponto de origem das rotas)
### Configuração [#configuração]
* Fuso horário
* País
* Horários de operação
***
## O que a filial controla no GO [#o-que-a-filial-controla-no-go]
| Contexto | Relação |
| ---------------- | ---------------------------------------------------------------------------------- |
| **Pedidos** | Todo [pedido](/docs/go/conceitos/pedido/) pertence a uma filial |
| **Rotas** | [Rotas](/docs/go/products/rotas/) partem do endereço da filial (armazém de origem) |
| **Motoristas** | [Motoristas](/docs/go/products/motoristas/) são vinculados a filiais |
| **Embarcadores** | [Embarcadores](/docs/go/conceitos/embarcador/) podem ser segmentados por filial |
| **Relatórios** | Filtros de relatório permitem selecionar filiais específicas |
***
## Onde configurar [#onde-configurar]
→ [Configurações > Filiais](/docs/go/settings/filiais/)
---
# Conceitos (/docs/go/conceitos)
---
# Marcador (/docs/go/conceitos/marcador)
Um **marcador** é uma tag colorida que você cria para categorizar pedidos ou motoristas. No GO, marcadores têm dois usos distintos conforme o tipo.
***
## Tipos de marcador [#tipos-de-marcador]
| Tipo | Aplicado em | Onde criar |
| ------------------------- | ----------- | ------------------------------------------------------------------------------ |
| **Marcador de pedido** | Pedidos | [Configurações > Marcadores](/docs/go/settings/marcadores/) |
| **Marcador de motorista** | Motoristas | [Configurações > Marcadores](/docs/go/settings/marcadores/) (seção Motoristas) |
***
## Campos de um marcador [#campos-de-um-marcador]
| Campo | Obrigatório | Descrição |
| ------------- | ----------- | ------------------------------------------------------------------ |
| **Nome** | ✓ | Ex.: "Frágil", "Moto", "Zona Norte" |
| **Descrição** | | Texto explicativo para a equipe |
| **Cor** | ✓ | Valor hexadecimal (ex.: `#EF4444`) — exibido como bolinha colorida |
***
## Marcadores de pedido [#marcadores-de-pedido]
Usados para categorizar e filtrar pedidos na operação.
### Como aplicar [#como-aplicar]
1. **Manualmente** — na tela de [Pedidos](/docs/go/products/pedidos/), selecione um ou mais pedidos e use a ação "Editar marcadores".
2. **Por automação** — via [Automação de Marcadores](/docs/go/products/automacoes-de-marcadores/), que aplica o marcador automaticamente quando as condições configuradas são atendidas.
### Como são usados [#como-são-usados]
* **Em filtros** — na tela de Pedidos, filtre por marcador para segmentar a operação.
* **Em automações de marcadores** — use marcadores como condição ou ação em [Automações de Marcadores](/docs/go/products/automacoes-de-marcadores/).
* **Em relatórios** — [Relatórios](/docs/go/products/relatorios/) incluem a coluna de marcadores para segmentação e análise.
* **Em automações de oferta** — o marcador de pedido pode ser usado como condição para decidir para quais motoristas a oferta é enviada. Ex.: "se o pedido tiver o marcador 'Frágil', envie a oferta apenas para o grupo de motoristas habilitados".
***
## Marcadores de motorista e automações de oferta [#marcadores-de-motorista-e-automações-de-oferta]
Marcadores de motorista servem para **segmentar sua frota** — você pode marcar motoristas com tags como "Zona Norte", "Van", "Moto" ou "Prioritário" e usar isso para direcionar ofertas.
Nas [**Automações de Ofertas**](/docs/go/products/automacoes-de-ofertas/), ao definir quem recebe uma oferta de entrega, você pode combinar condições de pedido com ações segmentadas por grupo de motoristas — onde os grupos podem ser organizados com base nos marcadores cadastrados em cada motorista.
→ [Ver Automações de Ofertas](/docs/go/products/automacoes-de-ofertas/)
***
***
## Onde aparece [#onde-aparece]
* [**Configurações > Marcadores**](/docs/go/settings/marcadores/) — criação e gestão de marcadores de pedido e motorista.
* [**Tela de Pedidos**](/docs/go/products/pedidos/) — filtro e aplicação.
* [**Tela de Motoristas**](/docs/go/products/motoristas/) — aplicação de marcadores de motorista.
* [**Automações de Marcadores**](/docs/go/products/automacoes-de-marcadores/) — aplicação automática em pedidos com base em condições.
* [**Automações de Ofertas**](/docs/go/products/automacoes-de-ofertas/) — uso de marcadores de pedido como condição e de grupos de motoristas (organizados por marcador) como ação.
---
# Oferta de Motorista (/docs/go/conceitos/oferta-motorista)
**Oferta de motorista** é o mecanismo pelo qual o GO distribui um pedido para um ou mais entregadores da frota própria. Quando um pedido chega ao GO e precisa ser despachado, o sistema — seguindo as [Automações de Ofertas](/docs/go/products/automacoes-de-ofertas/) configuradas — envia uma notificação no app do motorista. O primeiro que aceitar assume a entrega.
***
## Quem pode receber a oferta [#quem-pode-receber-a-oferta]
Só entram no pool de ofertas de um pedido os motoristas **vinculados à [filial](/docs/go/conceitos/filial/) do pedido**. Esse vínculo é definido no cadastro do motorista, no campo **Filiais** (obrigatório) — veja [Motoristas](/docs/go/products/motoristas/).
Na prática, isso significa que:
* Um motorista **sem filial**, ou vinculado a **outra** filial, **não recebe** a oferta daquele pedido.
* Um motorista pode ser vinculado a **mais de uma filial** e, nesse caso, é elegível às ofertas de todas elas.
***
## Por que a oferta vive no GO, não no Portal/LOG [#por-que-a-oferta-vive-no-go-não-no-portallog]
O GO e o LOG tratam o mesmo pedido de perspectivas diferentes:
| | **LOG (Portal)** | **GO** |
| ------------------------ | ----------------------------- | --------------------------------------- |
| **Perspectiva** | Embarcador que envia | Transportadora que executa |
| **Relação com o pedido** | Pedido → Transportadora (TRP) | Pedido → Motorista |
| **Foco operacional** | Cotação, envio, rastreio | Rota, oferta, entrega na "última milha" |
Quando um embarcador usa o LOG e configura a Abbiamo GO como transportadora, o GO atua como uma TRP (Transportadora) do ponto de vista do LOG. A partir do momento em que o pedido chega ao GO, **quem gerencia a oferta e a interação com o motorista é o próprio GO** — o LOG não tem acesso nem visibilidade sobre esse nível de detalhe.
***
## Como acompanhar as ofertas [#como-acompanhar-as-ofertas]
Para visualizar quais motoristas foram ofertados em um pedido, acesse o GO:
1. Abra a tela de [**Pedidos**](/docs/go/products/pedidos/) no GO.
2. Localize o pedido pelo número, NF ou `external_id`.
3. Clique no pedido para abrir o painel lateral de detalhes — o histórico de ofertas e o motorista que aceitou aparecem nesse painel.
Para configurar *quem* recebe as ofertas, use as [**Automações de Ofertas**](/docs/go/products/automacoes-de-ofertas/).
***
## Conceitos relacionados [#conceitos-relacionados]
* [**Automações de Ofertas**](/docs/go/products/automacoes-de-ofertas/) — regras que definem quais motoristas recebem a oferta e em qual ordem.
* [**Motoristas**](/docs/go/products/motoristas/) — cadastro e gestão da frota.
* [**Embarcador**](/docs/go/conceitos/embarcador/) — cliente que origina os pedidos (incluindo os que vêm do LOG).
* [**Rota**](/docs/go/conceitos/rota/) — agrupamento de pedidos atribuídos a um motorista para execução.
---
# Pedido (Order / Invoice) (/docs/go/conceitos/pedido)
**Pedido** é a entidade central que representa uma solicitação de entrega (ou coleta/retorno) recebida de um [embarcador](/docs/go/conceitos/embarcador/) e vinculada a uma [filial](/docs/go/conceitos/filial/). No sistema, a mesma entidade é chamada de **order** na API e, em parte do contexto de negócio, de **invoice** quando se fala da nota fiscal ou do documento do pedido.
***
## O que compõe um pedido [#o-que-compõe-um-pedido]
### Identificação [#identificação]
* `id` — identificador interno Abbiamo
* `number` — número do pedido
* `external_id` — ID do embarcador
* `tracking` — código de rastreio
### Nota fiscal / Invoice [#nota-fiscal--invoice]
* `invoice_number` — número da NF
* `access_keys` — chave de acesso da NF
* `content_declaration` — dados da DC-e quando o pedido foi criado com declaração de conteúdo informada pelo embarcador (`key`, `serie`, `number`)
* Dados de emissão
### Valores [#valores]
* `amount` — valor total do pedido
* **Preço e prazo prometido ao cliente** — valor do frete e data de entrega prometidos
### Status [#status]
* `status` / `sub_status` — refletem o estado atual do pedido. Para a lista completa de códigos e traduções, veja [Status de pedido](/docs/go/conceitos/status-de-pedido/).
### Tipo [#tipo]
* `type` — Entrega (DELIVERY), Retirada em loja (TAKEOUT) ou Reversa (RETURN)
### Relacionamentos [#relacionamentos]
| Relação | Descrição |
| ------------------- | --------------------------------------------------------------------------------- |
| **Filial** | A qual [filial](/docs/go/conceitos/filial/) o pedido pertence |
| **Embarcador** | O [embarcador](/docs/go/conceitos/embarcador/) que originou o pedido |
| **Cliente** | Destinatário e dados de contato |
| **Endereços** | Origem (endereço da filial) e destino |
| **Volumes e itens** | Volumes e itens associados |
| **Envios** | Um pedido pode ter um ou mais envios (ex.: reenvio) |
| **Rota** | A [rota](/docs/go/conceitos/rota/) à qual o pedido está associado (quando houver) |
### Outros dados [#outros-dados]
* **Entrega:** dados da última entrega — motorista, data de entrega, janela de entrega etc.
* **Marcadores:** tags/labels associadas ao pedido
* **Datas:** criação, atualização de status, data prevista de entrega
***
## Como um pedido chega ao GO [#como-um-pedido-chega-ao-go]
* **Do embarcador Abbiamo (LOG)** — pedidos chegam automaticamente via integração quando o embarcador usa o [LOG](/docs/log/onboarding/) e configura uma integração de transportadora apontando para a sua operação GO.
* **De embarcador externo** — pedidos entram via API ou importação manual para embarcadores cadastrados diretamente no GO.
* **Criação manual** — pelo formulário na tela de [Pedidos](/docs/go/products/pedidos/).
***
## Pedido vs. Invoice [#pedido-vs-invoice]
---
# Rota (/docs/go/conceitos/rota)
Uma **rota** é um agrupamento de pedidos organizados em uma sequência de paradas otimizada para entrega. A Abbiamo calcula o trajeto ideal e permite acompanhar a execução em tempo real.
***
## Tipos de rota [#tipos-de-rota]
| Tipo | Quem executa |
| ------------------ | --------------------------------------------------------------------------------- |
| **Frota Própria** | Motorista cadastrado na plataforma — veículo e motorista são da empresa |
| **Transportadora** | Transportadora externa — a rota é convertida em uma solicitação de coleta em lote |
***
## Status de rota [#status-de-rota]
| Status | Significado |
| ------------------------ | --------------------------------------------------- |
| `CREATED` | Rota criada, ainda não iniciada |
| `START_DELIVERY` | Entregas em andamento |
| `CANCELED` | Rota cancelada manualmente |
| `ALL_WAYPOINTS_FINISHED` | Todas as paradas concluídas, aguardando finalização |
| `FINISHED` | Rota finalizada com sucesso |
***
## Estrutura de uma rota [#estrutura-de-uma-rota]
### Informações principais [#informações-principais]
| Campo | Descrição |
| ------------------ | ------------------------------------------------------------------------------- |
| **Nome** | Identificador amigável da rota |
| **Tipo** | Frota Própria ou Transportadora |
| **Armazém** | Local de partida dos pedidos (endereço da [filial](/docs/go/conceitos/filial/)) |
| **Motorista** | Responsável pela execução (apenas Frota Própria) |
| **Transportadora** | Parceiro externo (apenas modo Transportadora) |
### Waypoints (paradas) [#waypoints-paradas]
Cada pedido na rota é uma **parada** (*waypoint*) com:
* Endereço de entrega
* Janela de horário (quando configurada)
* Status individual da parada (ex.: entregue, falhou, pendente)
* Comprovante de entrega (foto, assinatura, código)
***
## Fluxo de criação [#fluxo-de-criação]
1. **Selecionar pedidos** — escolher quais pedidos entrarão na rota.
2. **Configurar** — definir armazém de origem e responsável (motorista ou transportadora).
3. **Sugerir rota** — a plataforma otimiza a sequência de paradas.
4. **Visualizar prévia** — revisar o trajeto no mapa antes de confirmar.
5. **Confirmar** — rota criada e (se Frota Própria) motorista notificado.
***
## Ciclo de vida [#ciclo-de-vida]
```
CREATED → START_DELIVERY → ALL_WAYPOINTS_FINISHED → FINISHED
↘ CANCELED
```
Uma rota pode ser cancelada manualmente enquanto estiver em `CREATED` ou `START_DELIVERY`.
***
## Ações disponíveis por status [#ações-disponíveis-por-status]
| Ação | CREATED | START\_DELIVERY | ALL\_WAYPOINTS\_FINISHED |
| ---------------------- | ------- | --------------- | ------------------------ |
| Atribuir motorista | ✓ | — | — |
| Solicitar coleta (TRP) | ✓ | — | — |
| Duplicar | ✓ | ✓ | ✓ |
| Cancelar | ✓ | ✓ | — |
***
## Onde aparece [#onde-aparece]
* [**Tela de Rotas (GO)**](/docs/go/products/rotas/) — criação e acompanhamento de rotas.
* [**Pedidos**](/docs/go/products/pedidos/) — cada pedido exibe a rota à qual está associado (quando houver).
---
# Status de pedido (/docs/go/conceitos/status-de-pedido)
Referência de todos os **status** (status principal do pedido) e **sub\_status** usados na plataforma, com tradução em **Português (PT-BR)**. Os status são compartilhados entre LOG e GO — a mesma entidade de pedido segue o mesmo ciclo de vida independente do contexto.
***
## Status principal (status\_name) [#status-principal-status_name]
| Código | PT-BR |
| ---------------- | -------------------- |
| `SUCCESSFUL` | Sucesso |
| `CREATED` | Criado |
| `DISPATCHED` | Despachado |
| `START_DELIVERY` | Em Rota |
| `CANCELED` | Cancelado |
| `FAILED` | Falha |
| `TREATED` | Tratado |
| `VISIT_LATER` | Visitar mais tarde |
| `PENDING` | Pendente |
| `COLLECTED` | Coletado |
| `ORDER_FAILED` | Falha na Solicitação |
| `MANUAL_HANDLE` | Baixa manual |
| `HANDLING` | Em manuseio |
| `RETURNING` | Em Devolução |
| `RETURNED` | Devolvido |
| `IN_TRANSIT` | Em trânsito |
| `ON_TIME` | No Prazo |
| `DELAYED` | Atrasado |
| `ON_HOLD` | Em espera |
| `SCHEDULED` | Agendado |
***
## Sub-status por status (status → sub\_status) [#sub-status-por-status-status--sub_status]
Cada bloco lista os **sub\_status** que podem ocorrer para aquele **status** principal.
### CREATED (Criado) [#created-criado]
| Código sub\_status | PT-BR |
| --------------------- | ----------------------- |
| `LAST_ROUTE_CANCELED` | Rota Anterior Cancelada |
***
### PENDING (Pendente) [#pending-pendente]
| Código sub\_status | PT-BR |
| ------------------------------ | ------------------------------------ |
| `WAITING_FOR_CARRIER` | Aguardando Transportadora |
| `WAITING_CARRIER_ACTION` | Aguardando Ação com a Transportadora |
| `WAITING_FOR_DRIVER` | Aguardando Entregador |
| `WAITING_TAKEOUT_CONFIRMATION` | Aguardando Confirmação de Retirada |
***
### DISPATCHED (Despachado) [#dispatched-despachado]
| Código sub\_status | PT-BR |
| ------------------- | ------------------------ |
| `ROUTE_PLANNED` | Rota Planejada |
| `CARRIER_CONFIRMED` | Transportadora Confirmou |
| `SEARCHING_DRIVER` | Buscando Entregador |
| `DRIVER_ASSIGNED` | Entregador Atribuído |
| `DRIVER_REJECTED` | Entregador Recusou |
| `READY_FOR_TAKEOUT` | Pronto para Retirada |
| `DRIVER_CONFIRMED` | Entregador Confirmou |
***
### IN\_TRANSIT (Em trânsito) [#in_transit-em-trânsito]
| Código sub\_status | PT-BR |
| ------------------ | ------------------ |
| `COLLECTING` | Coletando |
| `AT_PICKUP_POINT` | No Local de Coleta |
***
### HANDLING (Em manuseio) [#handling-em-manuseio]
| Código sub\_status | PT-BR |
| -------------------- | ---------------------------------- |
| `LOGISTICS_STARTED` | Logística Iniciada na Base |
| `READY_FOR_TRANSFER` | Preparado para transferência |
| `PACKAGE_RECEIVED` | Objeto Recebido na Base |
| `IN_TRANSFER` | Em Transferência entre Bases |
| `TRANSFER_COMPLETED` | Transferência entre Bases Completa |
| `SCHEDULED_DELIVERY` | Entrega Agendada |
| `REDISPATCHED` | Re-solicitação de coleta feita |
| `PROCESSED_DELIVERY` | Processado para entrega |
***
### SUCCESSFUL (Sucesso) [#successful-sucesso]
| Código sub\_status | PT-BR |
| ------------------ | --------- |
| `DELIVERED` | Entregue |
| `WITHDRAWN` | Retirado |
| `RETURNED` | Retornado |
***
### FAILED (Falha) [#failed-falha]
| Código sub\_status | PT-BR |
| ------------------ | ------------------ |
| `DELIVERY_FAILED` | Falha na Entrega |
| `COLLECT_FAILED` | Falha na Coleta |
| `RETURN_FAILED` | Falha na Devolução |
***
### ORDER\_FAILED (Falha na Solicitação) [#order_failed-falha-na-solicitação]
| Código sub\_status | PT-BR |
| -------------------------------- | ------------------------------------ |
| `CARRIER_CANCELED` | Transportadora Cancelou |
| `CARRIER_REFUSED` | Transportadora Recusou |
| `CARRIER_ERROR` | Erro da Transportadora |
| `CARRIER_TIMEOUT` | Transportadora Não Respondeu a Tempo |
| `PACKAGE_NOT_COLLECTED` | Pacote Não Coletado |
| `SELLER_CANCELED` | Marca Cancelou |
| `OUT_OF_COVERAGE` | Fora da Área de Cobertura |
| `INACTIVITY_TIMEOUT` | Tempo de Inatividade Excedido |
| `SCHEDULE_FAILED` | Falha no Agendamento |
| `SCHEDULE_CANCELED` | Agendamento Cancelado |
| `LAST_SEARCHING_DRIVER_CANCELED` | Busca de Entregador Cancelada |
| `SEARCHING_DRIVER_CANCELED` | Busca de Entregador Cancelada |
| `NO_DRIVER_AVAILABLE` | Nenhum Entregador Disponível |
***
### CANCELED (Cancelado) [#canceled-cancelado]
| Código sub\_status | PT-BR |
| ------------------ | ---------------------- |
| `INTERNAL` | Interno |
| `SELLER_CANCELED` | Marca Cancelou |
| `CANCELED_BY_USER` | Cancelado pelo Usuário |
***
### Status sem sub\_status no mapeamento [#status-sem-sub_status-no-mapeamento]
Os status abaixo **não** possuem sub\_status no mapeamento: **COLLECTED**, **RETURNED**, **START\_DELIVERY**, **SCHEDULED**, **MANUAL\_HANDLE**, **ON\_HOLD**, **TREATED**, **VISIT\_LATER**, **RETURNING**, **ON\_TIME**, **DELAYED**. Podem aparecer com `sub_status` vazio ou valores vindos do backend em contextos específicos.
---
# Produtos (/docs/go/products)
---
# API (/docs/go/settings/api)
**URL:** `https://dashboard.abbiamolog.com/settings/tokens`
Aqui você encontra a **Chave de API** do seu seller group — necessária para autenticar requisições às APIs da Abbiamo a partir de sistemas externos.
***
## Chave de API [#chave-de-api]
A chave é exibida de forma mascarada (••••••••). Use os botões ao lado para:
| Botão | Função |
| ---------------- | ----------------------------------------------- |
| **Copiar** (📋) | Copia a chave para a área de transferência |
| **Revelar** (👁) | Exibe o valor completo da chave temporariamente |
***
## Como usar a Chave de API [#como-usar-a-chave-de-api]
A chave deve ser enviada no **header** de cada requisição à API:
```http
x-abbiamo-seller-group-key: SUA_CHAVE_AQUI
```
### Exemplo de requisição [#exemplo-de-requisição]
```bash
curl -X GET "https://api.abbiamo.io/v1/drivers" \
-H "x-abbiamo-seller-group-key: SUA_CHAVE_AQUI"
```
***
## Documentação completa da API [#documentação-completa-da-api]
A referência oficial de todos os endpoints está disponível em:
**[Documentação da API](/docs/api)**
Lá você encontra:
* Endpoints de pedidos, rotas, motoristas e webhooks
* Exemplos de requisição e resposta
* Schemas de payload
* Guias de autenticação e integração
---
# Filiais (/docs/go/settings/filiais)
A tela de **Filiais** centraliza o gerenciamento de todas as lojas/unidades da sua conta. Cada filial possui dados cadastrais, endereço e horários de operação — usados pela plataforma para cotação de frete, automações e relatórios.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/sellers](https://dashboard.abbiamolog.com/sellers)
* **Menu:** seção **Configurações** > **Filiais**
***
## Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------------------ | -------------------------------------------- |
| **Título** | "Filiais" |
| **Menu de ações** (Beta) | Abre paleta de comandos rápidos (`Ctrl + K`) |
| **Nova filial** | Abre o modal de criação de filial |
***
## Barra de filtros [#barra-de-filtros]
| Filtro | Descrição |
| --------------------------- | ---------------------------------------------------- |
| **Pesquisar** | Busca por nome, documento ou identificador da filial |
| **Atualizar** | Recarrega a lista |
| **Filtros** | Painel de filtros avançados |
| **Visibilidade de colunas** | Mostrar/ocultar colunas da tabela |
***
## Tabela de filiais [#tabela-de-filiais]
| Coluna | O que mostra |
| ---------------------- | ------------------------------------------------------------ |
| **ID** | Identificador único da filial (truncado, com botão de cópia) |
| **Filial** | Nome exibido como badge colorido |
| **Documento** | CNPJ ou outro documento de registro |
| **Identificador** | Código interno (geralmente igual ao documento) |
| **Inscrição Estadual** | IE da filial |
| **Endereço** | Endereço completo (rua, número, bairro, cidade, estado, CEP) |
| **Hora** | Horários de operação configurados (ex.: SEG 08:00–17:00) |
| **Ícone de usuário** | Acesso rápido aos usuários vinculados à filial |
| **Ícone de relógio** | Acesso rápido aos horários de operação |
| **Menu (⋯)** | Ações adicionais por filial |
***
## Criar filial [#criar-filial]
Clique em **Nova filial** para abrir o modal de criação. O modal tem duas abas:
### Aba: Informações gerais [#aba-informações-gerais]
| Campo | Obrigatório | Descrição |
| ----------------------- | ----------- | ------------------------------------------------------------------ |
| **Nome da filial** | ✓ | Nome de exibição da loja (ex.: "Loja Centro SP") |
| **Documento** | ✓ | Tipo (CNPJ/CPF) + número |
| **Email da filial** | | Email de contato da loja |
| **Identificador** | ✓ | Código interno — pode ser igual ao documento (checkbox "Replicar") |
| **Telefone da filial** | | Telefone de contato |
| **Inscrição Estadual** | | Número da IE |
| **País / Fuso horário** | ✓ | País (padrão: BRA) e fuso (padrão: America/Sao\_Paulo) |
| **CEP** | ✓ | Preenchimento automático do endereço ao digitar |
| **Rua** | ✓ | Nome da rua |
| **Número** | ✓ | Número do endereço |
| **Complemento** | | Apto, sala, etc. |
| **Bairro** | ✓ | Bairro |
| **Cidade** | ✓ | Cidade |
| **Estado** | ✓ | UF |
| **Referência** | | Instruções para facilitar o entregador achar o local de coleta |
### Aba: Horários de operação [#aba-horários-de-operação]
Configure os horários de funcionamento por dia da semana. Esses horários são usados por automações de envio, automações de ofertas e pela plataforma para agendamento de rotas e coletas.
| Campo | Descrição |
| ----------------- | ---------------------------------- |
| **Dia da semana** | SEG, TER, QUA, QUI, SEX, SAB, DOM |
| **Hora início** | Horário de abertura (ex.: 08:00) |
| **Hora fim** | Horário de fechamento (ex.: 18:00) |
***
## Paginação [#paginação]
* **Padrão:** 50 filiais por página
* **Opções:** 50, 100, 150, 200
---
# Configurações — Visão Geral (/docs/go/settings)
As **Configurações** do dashboard centralizam os ajustes da conta, da equipe, da identidade visual, das integrações técnicas e das regras operacionais.
* **URL:** `https://dashboard.abbiamolog.com/settings`
* **Acesso:** ícone de engrenagem ⚙ no canto inferior esquerdo do menu lateral
***
## Estrutura das configurações [#estrutura-das-configurações]
### Gerais [#gerais]
| Página | O que configura |
| --------------------------------------------------- | ----------------------------------------------------------------- |
| [**Preferências**](/docs/go/settings/preferencias/) | Aparência (claro/escuro) e idioma da interface |
| [**Usuários**](/docs/go/settings/usuarios/) | Criação, edição e controle de acesso de usuários da conta |
| [**Temas**](/docs/go/settings/temas/) | Identidade visual (logo, cor e link da marca) por filial |
| [**Notificações**](/docs/go/settings/notificacoes/) | Envio de notificações ao cliente final via e-mail, SMS e WhatsApp |
### Desenvolvedor [#desenvolvedor]
| Página | O que configura |
| ------------------------------------------- | ------------------------------------------------------- |
| [**API**](/docs/go/settings/api/) | Chave de API do seller group para integração externa |
| [**Webhooks**](/docs/go/settings/webhooks/) | Endpoints para receber eventos em tempo real do sistema |
### Outros [#outros]
| Página | O que configura |
| ----------------------------------------------- | --------------------------------------------------------------------- |
| [**Marcadores**](/docs/go/settings/marcadores/) | Tags personalizadas para pedidos e motoristas |
| [**Filiais**](/docs/go/settings/filiais/) | Cadastro e gestão de filiais: dados, endereço e horários de operação |
| [**Operação**](/docs/go/settings/operacao/) | Comprovante de entrega, motivos de falha e limite de paradas por rota |
***
---
# Marcadores (/docs/go/settings/marcadores)
**URL:** `https://dashboard.abbiamolog.com/settings/tags`
Marcadores são **tags coloridas** que você cria para categorizar pedidos e motoristas, facilitando filtros e organização na operação.
***
## Seções da tela [#seções-da-tela]
A página é dividida em duas seções independentes:
| Seção | Onde é usado |
| -------------- | ---------------------------------------------------------- |
| **Pedidos** | Marcadores aplicáveis a pedidos na tela de Pedidos |
| **Motoristas** | Marcadores aplicáveis a motoristas (exibe contador de uso) |
***
## Pedidos [#pedidos]
### Colunas da tabela [#colunas-da-tabela]
| Coluna | Descrição |
| ------------- | ----------------------------------------------------- |
| **Nome** | Nome do marcador com prévia da cor (bolinha colorida) |
| **Descrição** | Descrição opcional do marcador |
| **Criado em** | Data e hora de criação |
### Criar marcador de pedido [#criar-marcador-de-pedido]
1. Clique no **+** no canto superior direito da seção **Pedidos**.
2. Informe o **Nome** (obrigatório).
3. Adicione uma **Descrição** opcional.
4. Selecione a **Cor** em hexadecimal (padrão: `#3B82F6` — azul).
5. Clique em **Criar marcador**.
***
## Motoristas [#motoristas]
### Colunas da tabela [#colunas-da-tabela-1]
| Coluna | Descrição |
| ------------- | ------------------------------------------------- |
| **Nome** | Nome do marcador com prévia da cor |
| **Descrição** | Descrição opcional |
| **Em uso** | Número de motoristas atualmente com este marcador |
| **Criado em** | Data e hora de criação |
### Criar marcador de motorista [#criar-marcador-de-motorista]
1. Clique no **+** no canto superior direito da seção **Motoristas**.
2. Informe o **Nome**, **Descrição** (opcional) e **Cor**.
3. Clique em **Criar marcador**.
***
## Editar um marcador [#editar-um-marcador]
No menu ⋯ de qualquer marcador, clique em **Editar marcador**. Os campos disponíveis são os mesmos da criação (Nome, Descrição, Cor).
---
# Notificações (/docs/go/settings/notificacoes)
**URL:** `https://dashboard.abbiamolog.com/settings/notifications`
Controle quais notificações são enviadas ao **cliente final** a cada evento de pedido, e por qual canal.
***
## Canais disponíveis [#canais-disponíveis]
| Canal | Descrição | Provedor |
| ------------ | ----------------------------------------------------------- | ---------------------------- |
| **E-mail** | Notificação por e-mail para o endereço cadastrado no pedido | Abbiamo |
| **SMS** | Mensagem de texto para o celular do destinatário | Abbiamo |
| **WhatsApp** | Mensagem via WhatsApp para o celular do destinatário | Botmaker, Twilio ou Polichat |
***
## Gatilhos disponíveis [#gatilhos-disponíveis]
### Entrega [#entrega]
| Gatilho | Quando dispara |
| ------------------------------- | ---------------------------------------------------------------------------------- |
| **Pedido criado** | Quando um novo pedido é registrado no sistema |
| **Pedido em rota** | Quando o motorista inicia a rota com o pedido |
| **Pedido entregue + Avaliação** | Quando a entrega é confirmada com sucesso; inclui link para pesquisa de satisfação |
### Retirada em loja [#retirada-em-loja]
| Gatilho | Quando dispara |
| ------------------------ | ---------------------------------------------------------- |
| **Pronto para retirada** | Quando o pedido está disponível para retirada pelo cliente |
| **Adiar retirada** | Quando a data de retirada do pedido é adiada |
***
## Como editar as notificações [#como-editar-as-notificações]
1. Clique em **Editar** no canto inferior direito da tela.
2. Marque ou desmarque os checkboxes para cada combinação de **gatilho × canal**.
3. Salve as alterações.
---
# Operação (/docs/go/settings/operacao)
**URL:** `https://dashboard.abbiamolog.com/settings/operation`
Defina as regras operacionais da sua conta: o que o motorista precisa registrar ao entregar um pedido, quais são os motivos de falha disponíveis e quantos pedidos cabem em uma rota.
***
## Entregas [#entregas]
### Comprovante de Entrega [#comprovante-de-entrega]
Configure quais informações o motorista deve registrar no aplicativo **Abbiamo Go** ao confirmar uma entrega.
| Campo | Descrição |
| -------------------------- | ------------------------------------------- |
| **Entrega realizada** | Confirmação básica de que a entrega ocorreu |
| **Nome do recebedor** | Nome de quem recebeu o pedido |
| **Documento do recebedor** | CPF ou documento de quem recebeu |
| **Número do pedido** | Confirmação do número do pedido entregue |
| **Foto** | Foto do comprovante ou da entrega no local |
| **Assinatura** | Assinatura digital do recebedor |
Cada campo pode ser configurado como obrigatório ou opcional.
***
### Motivos de Falha na Entrega [#motivos-de-falha-na-entrega]
Configure a lista de motivos disponíveis para o motorista registrar quando uma entrega não é concluída.
Clique em **Editar** para adicionar, renomear ou remover motivos da lista.
Exemplos comuns de motivos de falha:
* Destinatário ausente
* Endereço não encontrado
* Pedido recusado
* Acesso bloqueado
***
## Rotas [#rotas]
### Limite de Paradas por Rota [#limite-de-paradas-por-rota]
Define o número máximo de pedidos que podem ser incluídos em uma única rota.
| Configuração | Valor |
| --------------------------- | ----------- |
| **Limite padrão** | 50 paradas |
| **Limite máximo permitido** | 200 paradas |
Use os botões **−** e **+** para ajustar o valor, depois clique em **Editar** para salvar.
---
# Preferências (/docs/go/settings/preferencias)
**URL:** `https://dashboard.abbiamolog.com/settings`
Ajustes pessoais do usuário logado — não afetam outros membros da equipe.
***
## Aparência [#aparência]
Escolha entre dois temas visuais para o dashboard:
| Opção | Descrição |
| ---------- | ----------------------------------- |
| **Claro** | Interface com fundo branco (padrão) |
| **Escuro** | Interface com fundo escuro |
A escolha é salva automaticamente e persiste entre sessões.
***
## Língua e região [#língua-e-região]
Selecione o idioma da interface no menu suspenso.
| Opção disponível |
| ---------------- |
| Português |
A configuração de idioma afeta rótulos, datas e mensagens exibidas na interface.
---
# Temas (/docs/go/settings/temas)
**URL:** `https://dashboard.abbiamolog.com/settings/themes`
Configure a identidade visual exibida ao seu cliente final na página de rastreio e nas comunicações enviadas pela Abbiamo.
***
## O que você vê na tela [#o-que-você-vê-na-tela]
Os temas são exibidos como **cartões visuais** com preview da logomarca. Cada cartão mostra:
| Elemento | Descrição |
| ----------- | ------------------------------------------------------------------------------ |
| **Preview** | Miniatura com a logo e cor de fundo do tema |
| **Nome** | Nome interno do tema |
| **Padrão** | Badge "Padrão" indica o tema aplicado por padrão a filiais sem tema específico |
| **Filiais** | Número de filiais usando este tema |
| **Menu ⋯** | Ações disponíveis para o tema |
***
## Ações do tema (menu ⋯) [#ações-do-tema-menu-]
| Ação | Descrição |
| ---------------------------- | -------------------------------------------------- |
| **Ver detalhes** | Abre o modal de edição do tema |
| **Definir como tema padrão** | Define este tema como padrão da conta |
| **Aplicar tema em filiais** | Associa o tema a uma ou mais filiais |
| **Desativar tema** | Desativa o tema (não pode ser o tema padrão ativo) |
***
## Campos do tema [#campos-do-tema]
Acessíveis em **Ver detalhes**:
| Campo | Obrigatório | Descrição |
| ----------------------------- | ----------- | ---------------------------------------------------------- |
| **Nome** | Sim | Nome interno para identificação no dashboard |
| **Nome de exibição** | Não | Nome exibido ao cliente final |
| **Link da sua marca** | Não | URL para o site da marca (ex: `https://suamarca.com.br`) |
| **Cor primária** | Sim | Cor principal da marca em hexadecimal (ex: `#FF5733`) |
| **Cor de fundo da logomarca** | Não | Cor de fundo usada atrás da logo em hexadecimal |
| **Logomarca** | Não | Upload da imagem da logo (recomendado: fundo transparente) |
| **Ícone** | Não | Upload do ícone da marca (favicon/ícone compacto) |
***
## Como aplicar um tema a filiais [#como-aplicar-um-tema-a-filiais]
1. No menu ⋯ do tema, clique em **Aplicar tema em filiais**.
2. Selecione as filiais desejadas.
3. Confirme.
As filiais sem tema específico utilizam automaticamente o **tema padrão** da conta.
---
# Usuários (/docs/go/settings/usuarios)
**URL:** `https://dashboard.abbiamolog.com/settings/users`
Gerencie quem tem acesso ao dashboard e quais permissões cada pessoa possui.
***
## O que você vê na tela [#o-que-você-vê-na-tela]
### Barra superior [#barra-superior]
| Elemento | Função |
| ---------------- | --------------------------------------- |
| **Pesquisar** | Busca por e-mail |
| **Filtros** | Filtra por tipo, status ativo e filiais |
| **Novo usuário** | Abre o modal de criação |
### Tabela de usuários [#tabela-de-usuários]
| Coluna | Descrição |
| ----------------- | -------------------------------------------------------- |
| **Email** | Endereço de e-mail do usuário |
| **Tipo** | Nível de acesso: `PROPRIETÁRIO` ou `ADMINISTRADOR` |
| **Usuário ativo** | Indicador verde (ativo) ou apagado (inativo) |
| **Permissões** | Permissões específicas concedidas (quando aplicável) |
| **Filiais** | Filiais às quais o usuário tem acesso (`TODOS` ou lista) |
| **Ações** | Ícone de edição (✏) e menu ⋯ |
***
## Tipos de usuário [#tipos-de-usuário]
| Tipo | Descrição |
| ----------------- | ------------------------------------------------------------------------------------ |
| **Proprietário** | Acesso total a todas as filiais e configurações. Não pode ser restringido por filial |
| **Administrador** | Acesso configurável — pode ser limitado a filiais específicas |
***
## Criar um usuário [#criar-um-usuário]
1. Clique em **Novo usuário** no canto superior direito.
2. Informe o **e-mail** do novo usuário.
3. Selecione o **tipo** (Administrador é o padrão para novos usuários).
4. Associe as **filiais** que este usuário poderá acessar.
5. Clique em **Salvar**.
O usuário receberá um e-mail com uma **senha temporária** — não um link de definição de senha. Ao entrar pela primeira vez com ela pelo portal, é pedido que defina sua senha definitiva antes de acessar o dashboard.
***
## Editar um usuário [#editar-um-usuário]
1. Clique no ícone de edição (✏) na linha do usuário desejado.
2. Ajuste o **tipo**, as **filiais** ou o status **Ativo**.
3. Clique em **Salvar**.
### Campos editáveis [#campos-editáveis]
| Campo | Descrição |
| ----------- | ------------------------------------- |
| **Email** | Exibido, não editável |
| **Ativo** | Toggle para ativar/desativar o acesso |
| **Tipo** | Proprietário ou Administrador |
| **Filiais** | Filiais associadas ao usuário |
***
## Desativar um usuário [#desativar-um-usuário]
No modal de edição, desative o toggle **Ativo** e clique em **Salvar**. O usuário perde acesso imediatamente mas permanece na lista (para reativação futura).
---
# Webhooks (/docs/go/settings/webhooks)
**URL:** `https://dashboard.abbiamolog.com/settings/webhooks`
Configure URLs que receberão chamadas **HTTP POST** automáticas sempre que um evento ocorrer no sistema — útil para sincronizar seu sistema com a Abbiamo em tempo real.
***
## O que você vê na tela [#o-que-você-vê-na-tela]
### Tabela de webhooks [#tabela-de-webhooks]
| Coluna | Descrição |
| ------------- | ----------------------------------------------------------- |
| **ID** | Identificador único do webhook (truncado, com botão copiar) |
| **Evento** | Tipo de evento que dispara o webhook (badge colorido) |
| **Ativo** | Indicador verde (ativo) ou vermelho (inativo) |
| **URL** | Endpoint que receberá as notificações |
| **Headers** | Headers customizados configurados (quando houver) |
| **Ações (⋯)** | Editar webhook ou ativar/desativar |
***
## Eventos disponíveis [#eventos-disponíveis]
| Evento | Quando dispara |
| --------------------- | --------------------------------------------------------- |
| `ORDER_STATUS_CHANGE` | A cada mudança de status de um pedido |
| `ROUTE_STATUS_CHANGE` | A cada mudança de status de uma rota |
| `TOKEN_GENERATED` | Quando um novo token de API é gerado |
| `ORDER_CSAT_ANSWER` | Quando o cliente responde à pesquisa de satisfação (CSAT) |
***
## Criar um webhook [#criar-um-webhook]
1. Clique em **Novo webhook** no canto superior direito.
2. Selecione o **Evento** no menu suspenso.
3. Informe a **Webhook URL** — o endpoint do seu sistema que receberá as chamadas.
4. Opcionalmente, clique em **+ Adicionar header** para incluir headers de autenticação ou identificação.
5. Ative o toggle **Ativar webhook?** se quiser ativá-lo imediatamente.
6. Clique em **Criar webhook**.
### Campos do formulário [#campos-do-formulário]
| Campo | Obrigatório | Descrição |
| ------------------- | ----------- | --------------------------------------------------------------------------------- |
| **Evento** | Sim | Tipo de evento que dispara o webhook |
| **Webhook URL** | Sim | URL do seu endpoint (deve aceitar POST) |
| **Headers** | Não | Pares chave-valor enviados em cada requisição (ex: `Authorization: Bearer token`) |
| **Ativar webhook?** | — | Toggle para ativar imediatamente |
***
## Editar ou desativar um webhook [#editar-ou-desativar-um-webhook]
No menu ⋯ de qualquer webhook:
| Ação | Descrição |
| ---------------------- | ----------------------------------- |
| **Editar webhook** | Altera evento, URL ou headers |
| **Ativar / Desativar** | Pausa ou retoma o envio sem excluir |
***
## Formato do payload [#formato-do-payload]
A Abbiamo envia um `POST` com o corpo em JSON para a URL configurada. Para detalhes completos do payload de cada evento, consulte a documentação oficial:
**[Documentação da API — Webhooks](/docs/api/webhook)**
---
# Cotação de Frete (/docs/log/acoes/cotacao-frete)
A **cotação de frete** é a ação de calcular o valor e o prazo de entrega antes de o [envio](/docs/log/conceitos/envio/) ser criado. O sistema consulta as [tabelas de frete](/docs/log/conceitos/tabela-frete/) e retorna as opções disponíveis.
***
## Onde a cotação acontece [#onde-a-cotação-acontece]
* **Via API** — endpoint [Quote orders V2](/docs/api/quotations/quote-orders-v2) para simular frete antes de criar o pedido.
* **Na solicitação de coleta** — na página de [Pedidos](/docs/log/products/pedidos/), ao clicar em "Solicitar coleta", o sidepanel exibe as cotações; o operador escolhe uma opção e o envio é criado.
* **Em algumas integrações de pedido** — integrações específicas (ex.: VTEX) podem disparar a cotação no fluxo de criação ou exibição de opções de frete.
* **Automaticamente** — quando uma [automação de envio](/docs/log/conceitos/regra-envio/) com ação **mais barato** ou **mais rápido** é acionada.
***
## Conceito completo [#conceito-completo]
Para entender como o cálculo funciona (tabelas de CEP e raio, lat/lng, data de entrega esperada), veja o [conceito de Cotação de Frete](/docs/log/conceitos/cotacao-frete/).
---
# Criação de Pedido (/docs/log/acoes/criacao-pedido)
A **criação de pedido** é a ação de registrar um novo [pedido](/docs/log/conceitos/pedido/) no sistema. Existem três formas principais: pelo dashboard (formulário, CSV ou XLSX), via API pública ou por [integração de pedido](/docs/log/conceitos/integracao-pedido/).
***
## Pelo dashboard [#pelo-dashboard]
Na página de [Pedidos](/docs/log/products/pedidos/), o botão **Criar pedido** permite criar pedidos de três formas:
| Forma | Descrição |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| **Formulário** | Preenchimento manual dos dados do pedido (cliente, endereço, volumes, NF etc.) em um formulário na interface. |
| **CSV** | Upload de arquivo CSV com os dados dos pedidos. Útil para criar vários pedidos de uma vez. |
| **XLSX** | Upload de planilha Excel (.xlsx) com os dados dos pedidos. Também permite criação em lote. |
### Latitude e longitude na planilha (pula o geocoding automático) [#latitude-e-longitude-na-planilha-pula-o-geocoding-automático]
A planilha (CSV ou XLSX) aceita colunas de **latitude** e **longitude** para o endereço do pedido. Se as duas vierem preenchidas na linha, a Abbiamo **não roda o geocoding automático** para aquele endereço — usa direto a coordenada informada e marca o pedido com `geolocation_provider = SELLER`.
O mesmo comportamento vale para pedidos criados via API pública (campos `latitude`/`longitude` dentro de `destination_address` ou `source_address` — veja [Criar pedido (v2)](/docs/api/orders/create-order-v2)) e para pedidos recebidos por integração de pedido que já chegam com coordenada na origem.
### Janela de entrega em horas e tipo de moradia na planilha [#janela-de-entrega-em-horas-e-tipo-de-moradia-na-planilha]
A planilha (CSV ou XLSX) também aceita os campos `delivery_start_window_hour`, `delivery_end_window_hour` (formato `HH:mm`, ex.: `09:00`) e `residence_type` (`commercial` ou `residential`). São os mesmos campos aceitos pela API pública — veja a descrição completa em [Pedido (conceito)](/docs/log/conceitos/pedido/#janela-de-entrega-e-tempo-de-servico).
***
## Via API pública [#via-api-pública]
A API da Abbiamo permite criar pedidos programaticamente. O endpoint [Create order V2](/docs/api/orders/create-order-v2) (`POST https://api.abbiamo.io/v2/order`) cria pedidos individuais.
O objeto **delivery** na requisição pode automatizar a [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) para transportadoras — desde configurações simples até regras de preferência e condições especiais. Consulte a documentação do [Delivery Object](/docs/api/orders/create-order-v2) para montar o objeto conforme sua necessidade.
O corpo da requisição também aceita `delivery_start_window_hour`/`delivery_end_window_hour` (janela de entrega em horário, formato `HH:mm`, sem data associada) e `residence_type` (`commercial` ou `residential`) — veja a descrição completa em [Pedido (conceito)](/docs/log/conceitos/pedido/#janela-de-entrega-e-tempo-de-servico).
***
## Via integração de pedido [#via-integração-de-pedido]
Quando a [integração de pedido](/docs/log/conceitos/integracao-pedido/) está configurada (ex.: [VTEX](/docs/log/integrations/pedido/vtex)), os pedidos são criados automaticamente no sistema a partir dos canais conectados — marketplace, e-commerce, ERP etc.
***
## Links relacionados [#links-relacionados]
* [Pedido (conceito)](/docs/log/conceitos/pedido/) — o que compõe um pedido
* [Integração de Pedido](/docs/log/conceitos/integracao-pedido/) — conceito das integrações
* [Tela de Pedidos](/docs/log/products/pedidos/) — onde criar e acompanhar novos pedidos
* [Create order V2](/docs/api/orders/create-order-v2) — endpoint da API
---
# Ações (/docs/log/acoes)
---
# Solicitação de Coleta (/docs/log/acoes/solicitacao-coleta)
A **solicitação de coleta** é o fluxo em que o operador solicita a coleta de um [pedido](/docs/log/conceitos/pedido/) para uma transportadora a partir da página de [Pedidos](/docs/log/products/pedidos/). O sistema exibe as opções de frete (cotações), o operador escolhe uma e o [envio](/docs/log/conceitos/envio/) é criado.
***
## Onde acessar [#onde-acessar]
* **Página de Pedidos** — botão **Solicitar coleta** no cabeçalho (para pedidos selecionados) ou ação no sidepanel de um pedido.
* O mesmo fluxo serve para **solicitar reversa** (coleta de devolução).
***
## Como funciona [#como-funciona]
1. O operador seleciona um ou mais pedidos na lista e clica em **Solicitar coleta** (ou abre o sidepanel do pedido e aciona a solicitação).
2. O sistema realiza uma [cotação de frete](/docs/log/acoes/cotacao-frete/) consultando as [tabelas de frete](/docs/log/conceitos/tabela-frete/) das [integrações de transportadora](/docs/log/conceitos/integracao-transportadora/) ativas da filial.
3. As opções aparecem no painel — transportadora, modalidade, prazo, preço e data de entrega esperada.
4. O operador escolhe uma opção (ex.: Uber/Carro/EXP60 por R$ 15,00).
5. O sistema cria o envio na transportadora selecionada.
***
## Agendamento [#agendamento]
Além de solicitar imediatamente, é possível **agendar** a solicitação para:
* Próximo horário de operação da loja
* Início da janela de entrega do pedido (quando configurada)
* Data e horário customizados
***
## Links relacionados [#links-relacionados]
* [Cotação de Frete](/docs/log/acoes/cotacao-frete/) — como as opções são calculadas
* [Conceito de Cotação](/docs/log/conceitos/cotacao-frete/) — detalhes do cálculo
* [Tela de Pedidos](/docs/log/products/pedidos/) — onde a solicitação é feita
* [Envio](/docs/log/conceitos/envio/) — o que é criado após a escolha
---
# Abrir uma disputa (/docs/log/care/abrir-disputa)
Existem duas formas de uma disputa nascer.
## 1. O cliente abre pelo rastreio [#1-o-cliente-abre-pelo-rastreio]
Na página de rastreio do pedido, o cliente encontra a opção de relatar um problema. Ele escolhe o **motivo** (não recebeu, faltou item, item danificado, pedido errado) e, dependendo do motivo, indica **quais itens** e a **quantidade**. Pode anexar fotos como evidência.
Assim que ele envia, a disputa aparece no seu painel em **Care → Disputas**, e — se o chat estiver ligado — a conversa com o cliente já fica disponível ali mesmo.
Se você preferir não oferecer o chat ao cliente, é possível desligá-lo nas Configurações. Nesse caso o cliente vê apenas um aviso de que o caso foi recebido, e o atendimento segue por fora.
## 2. Você abre manualmente [#2-você-abre-manualmente]
Você pode abrir uma disputa direto do pedido, sem esperar o cliente. Isso é útil quando a sua equipe identifica o problema primeiro (um cliente que ligou, um e-mail, um chargeback).
Há dois caminhos:
### A partir da lista de disputas [#a-partir-da-lista-de-disputas]
Em **Care → Disputas**, clique em **Nova disputa**. O fluxo pede, em ordem:
1. **Pedido** — busque pelo número do pedido.
2. **Motivo** — o que aconteceu. Alguns motivos (itens faltando, itens danificados) pedem que você marque **quais itens**; outros (não recebido, pedido errado) tratam o pedido inteiro.
3. **Itens** — só aparece quando o motivo pede; marque o que entrou na disputa e a quantidade.
4. **Detalhes** — um texto livre de contexto (opcional).
Você também decide se quer **notificar o cliente** (a disputa aparece na página de rastreio dele) ou registrar de forma silenciosa.
### A partir do pedido [#a-partir-do-pedido]
Abra o pedido (na tela de **Pedidos**), e no menu de **Ações** do pedido use **Criar disputa Care**. O pedido já vem pré-selecionado.
Hoje a criação de disputa a partir do pedido está disponível apenas para pedidos entregues. Para outros status, a opção fica desabilitada.
## Um pedido, uma disputa [#um-pedido-uma-disputa]
Cada pedido pode ter **no máximo uma disputa** — aberta ou já resolvida. Se você tentar abrir uma segunda, o sistema avisa que o pedido já tem disputa e te leva à existente. Na tela de Pedidos, um ícone indica quais pedidos têm disputa, e há um filtro para ver pedidos **com disputa aberta**, **com disputa fechada** ou **sem disputa**.
---
# Atender uma disputa (/docs/log/care/atender-disputa)
Cada disputa abre num painel lateral com duas colunas: à esquerda, a **conversa com o cliente**; à direita, abas com **notas internas**, **dados do cliente**, do **pedido**, da **loja** e as **evidências**.
## Conversa com o cliente [#conversa-com-o-cliente]
É um chat, igual ao que você já conhece de qualquer mensageiro. Você escreve, anexa fotos e envia. O cliente recebe e responde pela página de rastreio.
Para o cliente, as mensagens aparecem como vindas da sua loja (o nome configurado em Configurações). Internamente, no painel, sua equipe vê qual agente escreveu cada mensagem — assim o time sabe quem falou o quê, sem expor isso ao cliente.
### Reenvio do pedido [#reenvio-do-pedido]
Quando você marca que **reenviou** o pedido como resolução, o sistema envia ao cliente a mensagem correspondente automaticamente — você pode editar o texto antes de enviar.
## Notas internas [#notas-internas]
A aba **Notas** é um chat privado do seu time. Tudo que é escrito ali **o cliente nunca vê**. Use para alinhar o caso, registrar uma ligação, combinar quem faz o quê.
* Escreva texto, anexe arquivos, ou ambos.
* Cada nota mostra **quem escreveu** e quando.
* A nota aparece na hora para todo o time (e some na hora se você apagar, com uma confirmação rápida).
* Você só apaga as **suas** notas.
## Responsável [#responsável]
No topo da disputa você define um **responsável** — a pessoa do time encarregada daquele caso. O seletor é pesquisável, e você pode "pegar pra mim" com um clique. Trocar o responsável reflete na hora, e há um filtro na lista de disputas para ver, por exemplo, **as suas**.
Você pode definir, nas Configurações, quem da equipe fica disponível como agente. Assim o seletor mostra só essas pessoas, em vez de toda a base de usuários.
### Quem pode responder [#quem-pode-responder]
Se a sua marca configurou uma lista de agentes, quem **não** está nela não responde o chat — mas pode **entrar como agente** com um clique, ali mesmo no painel.
## Evidências, cliente, pedido e loja [#evidências-cliente-pedido-e-loja]
As abas restantes reúnem o contexto do caso:
* **Cliente** — histórico de disputas do mesmo cliente, dados de contato.
* **Pedido** — itens, valores, status.
* **Loja** — dados da sua operação exibidos ao cliente.
* **Evidências** — todas as fotos e anexos da disputa, em galeria.
## Moderação de imagens [#moderação-de-imagens]
Fotos enviadas pelo cliente passam por uma checagem automática de conteúdo impróprio. Você escolhe, nas Configurações, o que fazer com fotos sinalizadas: **borrar** (com um botão "ver mesmo assim"), **bloquear** (o cliente precisa enviar outra), ou **aceitar todas**.
---
# Configurações do Care (/docs/log/care/configuracoes)
Tudo do Care é configurado em **Care → Configurações**. As mudanças valem para novas disputas.
## Contato da marca [#contato-da-marca]
* **Nome exibido nos chats** — como a sua loja aparece para o cliente nas mensagens. Em branco, usa o nome cadastrado na Abbiamo.
* **E-mail principal** — recebe as notificações de novas disputas e mensagens.
* **Cópias** — até 5 e-mails adicionais.
## Moderação de imagens [#moderação-de-imagens]
Como tratar fotos consideradas impróprias pelo modelo de moderação:
Borrar
Recomendado. A foto fica borrada com um botão "ver mesmo assim".
Bloquear
O cliente recebe erro no upload e precisa enviar outra foto.
Aceitar todas
Sem moderação. Não recomendado.
## Regras automáticas [#regras-automáticas]
* **Auto-fechar disputa em (dias)** — sem movimentação por X dias, a disputa é marcada como auto-resolvida. `0` desliga o timer.
* **Notificar a cada nova mensagem** — e-mail para o contato principal sempre que uma resposta nova entra.
## SLA [#sla]
O **SLA** é opcional (vem desligado por padrão). Quando ligado, a lista de disputas ganha uma coluna e uma legenda de SLA, o painel da disputa mostra um contador, e a ordenação padrão prioriza as disputas mais urgentes. Desligado, a lista ordena por data de abertura.
## Agentes do Care [#agentes-do-care]
Defina **quem da equipe** pode ser responsável por uma disputa. Com a lista preenchida, o seletor de responsável mostra só essas pessoas (útil quando a sua conta tem muitos usuários). Deixe vazio para liberar todos.
## Chat com o cliente [#chat-com-o-cliente]
Liga ou desliga a conversa com o cliente na página de rastreio.
Ligado (padrão): o cliente conversa com você pelo rastreio. Desligado: a ocorrência é registrada normalmente, mas o cliente vê só um aviso de que o caso foi recebido — sem chat. O atendimento segue por fora (e-mail, telefone).
---
# Care — pós-venda e disputas (/docs/log/care)
O **Care** é o módulo de pós-venda da Abbiamo. Ele transforma o que normalmente vira uma troca caótica de e-mails e mensagens em um fluxo único e rastreável: o cliente relata um problema com o pedido, vocês conversam pela própria página de rastreio, e a sua equipe acompanha, aciona a transportadora quando preciso e fecha o caso registrando o desfecho.
O Care está disponível para todas as contas. Para começar, configure o e-mail de contato da marca em Care → Configurações.
## Para que serve [#para-que-serve]
* **Centralizar o pós-venda**: toda ocorrência de um pedido (não recebido, item faltando, item danificado, pedido errado) vira uma **disputa** com histórico próprio.
* **Conversar com o cliente** sem sair da plataforma — o cliente responde pela página de rastreio, você responde pelo painel.
* **Acionar a transportadora** pelo seu canal habitual com ela e manter o andamento atualizado no Care.
* **Registrar o desfecho** (entregue, retornado, perdido, reclamação sem procedência) e a compensação (reembolso, voucher, reenvio).
* **Manter o time alinhado** com notas internas (que o cliente nunca vê) e um responsável por disputa.
* **Trabalhar em escala** com filtros, ações em massa e exportação — e **integrar com o Zendesk** pra espelhar cada disputa como ticket.
## Como funciona, em resumo [#como-funciona-em-resumo]
1\. Abre
O cliente abre uma disputa pela página de rastreio, ou você abre manualmente a partir de um pedido entregue.
2\. Atende
Você conversa com o cliente, anexa evidências, deixa notas internas pro time e define um responsável.
3\. Aciona a TRP
Quando o caso depende da transportadora, você a aciona pelo seu canal habitual com ela e atualiza o andamento no Care.
4\. Resolve
Você registra o desfecho e a compensação. A disputa é encerrada e o cliente é avisado.
## Conceitos [#conceitos]
* **Disputa** — o registro de uma ocorrência de um pedido. Cada pedido pode ter **no máximo uma** disputa.
* **Motivo (tipo de ocorrência)** — não recebido, itens faltando, itens danificados, pedido errado, ou outro.
* **Desfecho** — o que de fato aconteceu (entregue, retornado, perdido, reclamação sem procedência, sem evidência).
* **Compensação** — o que foi oferecido ao cliente (nenhuma, reembolso, voucher, reenvio).
* **Responsável** — a pessoa do seu time encarregada daquela disputa.
* **Nota interna** — anotação visível só para o seu time; o cliente nunca vê.
## Trabalhando em escala [#trabalhando-em-escala]
A lista de **Disputas** foi feita pra dar conta de volume:
* **Filtros** por status, desfecho, compensação, transportadora, responsável e período — todos do lado do servidor (filtram a base inteira, não só a página).
* **Ações em massa**: selecione várias disputas (checkbox) e atribua, desatribua, resolva ou reabra de uma vez. As mesmas ações estão no **clique-direito** da linha e na **coluna de 3 pontos** à direita — e o menu é contextual (só mostra o que faz sentido pras disputas selecionadas).
* **Exportar** abre o relatório de Disputas pronto pra gerar (veja [Relatórios](/docs/log/care/relatorios)).
## Por onde começar [#por-onde-começar]
1. **[Abrir uma disputa](/docs/log/care/abrir-disputa)** — pelo cliente (tracking) ou manualmente.
2. **[Atender uma disputa](/docs/log/care/atender-disputa)** — chat, notas, responsável e evidências.
3. **[Resolver uma disputa](/docs/log/care/resolver-disputa)** — desfecho e compensação.
4. **[Configurações](/docs/log/care/configuracoes)** — e-mails de contato, SLA, agentes e chat.
5. **[Integração com o Zendesk](/docs/log/care/zendesk)** — espelhe cada disputa como um ticket.
6. **[Relatórios e exportação](/docs/log/care/relatorios)** — exporte disputas e veja a disputa no relatório de pedidos.
7. **[Webhook de disputa](/docs/log/care/webhook)** — receba as mudanças de status no seu sistema.
---
# Relatórios e exportação (/docs/log/care/relatorios)
O Care se conecta ao módulo de **Relatórios** da Abbiamo de duas formas: um relatório dedicado de **Disputas** e a informação de disputa **dentro do relatório de Pedidos**.
## Exportar disputas [#exportar-disputas]
Na tela de **Disputas**, o botão **Exportar** abre a página de Relatórios já com o relatório de **Disputas** selecionado — é só escolher período e gerar.
O relatório de Disputas traz, por disputa: número, pedido, nota fiscal, filial, transportadora, status e substatus, status da transportadora (TRP), desfecho, compensação (e valor/moeda), motivo de encerramento, responsável, dados do cliente e as datas de abertura e resolução. Os campos de status/desfecho/compensação vêm **traduzidos**.
O botão Exportar leva pra página de Relatórios (abre o modal de "novo relatório" com o tipo Disputas pré-selecionado). Você ajusta o período e os filtros lá.
## Disputa no relatório de Pedidos [#disputa-no-relatório-de-pedidos]
O relatório de **Pedidos** também ganhou colunas de disputa — a mesma informação que aparece na página de pedidos:
* **Tem disputa** — Sim/Não.
* **Número da disputa** — o identificador público, quando houver.
* **Status da disputa** — Em aberto / Resolvida.
* **Desfecho** e **Compensação** — preenchidos quando a disputa está resolvida.
Assim dá pra cruzar pedidos e pós-venda num relatório só, sem precisar casar duas exportações.
Veja a descrição de cada coluna em Relatórios → Detalhamento dos relatórios (abas Pedidos e Disputas).
---
# Resolver uma disputa (/docs/log/care/resolver-disputa)
Toda disputa caminha para um encerramento. Resolver é registrar duas coisas: o **desfecho** (o que aconteceu) e a **compensação** (o que o cliente recebeu).
## Quando depende da transportadora (TRP) [#quando-depende-da-transportadora-trp]
Quando o caso depende da transportadora — um pedido que sumiu no trajeto, por exemplo — você aciona a transportadora **pelo seu canal habitual com ela** (e-mail, portal ou telefone) e mantém a disputa atualizada no Care.
Enquanto está com a transportadora, a disputa fica como **aguardando TRP**. Conforme ela responde, você registra o andamento — por exemplo, se a transportadora **pagou** ou **negou** a ocorrência — e segue para o desfecho.
## Desfecho × compensação [#desfecho--compensação]
Os dois eixos são independentes — o desfecho descreve o fato, a compensação descreve o que você fez por isso.
Desfecho (o fato)
Entregue · Retornado · Perdido · Reclamação sem procedência · Sem evidência
Compensação (o que ofereceu)
Nenhuma · Reembolso · Voucher · Reenvio
Por exemplo: um pedido **perdido** pode ser compensado com **reenvio** ou **reembolso**; uma **reclamação sem procedência** normalmente fecha **sem compensação**.
## Auto-fechamento [#auto-fechamento]
Disputas que ficam **sem movimentação** por um número de dias configurável são **fechadas automaticamente** como auto-resolvidas — evitando casos esquecidos em aberto. Você define o prazo (ou desliga o timer) nas Configurações.
## Reabrir [#reabrir]
Uma disputa resolvida pode ser **reaberta** caso o cliente volte com o assunto ou surja informação nova.
---
# Webhook de disputa (/docs/log/care/webhook)
Se você quer refletir o pós-venda no seu próprio sistema (ERP, CRM, planilha), assine o webhook **`DISPUTE_STATUS_CHANGE`**. A cada mudança relevante de uma disputa, a Abbiamo faz um `POST` no endereço que você configurar.
## Como assinar [#como-assinar]
Em **Configurações → Webhooks**, crie um webhook, informe a **URL** do seu endpoint e escolha o evento **`DISPUTE_STATUS_CHANGE`**. Pronto — a partir daí, toda mudança de status de disputa dispara uma chamada.
O mesmo painel de webhooks permite acompanhar os logs de cada disparo (status da resposta, payload enviado), úteis para depurar a integração.
## Quando dispara [#quando-dispara]
O evento é disparado quando uma disputa:
* **abre** (pelo cliente ou manualmente);
* muda de **status** ou **sub-status** (ex.: passa a aguardar a transportadora);
* muda o **status com a transportadora (TRP)**;
* é **resolvida** ou **rejeitada**.
## Payload [#payload]
```json
{
"event_type": "DISPUTE_STATUS_CHANGE",
"dispute_public_id": "AB12CD",
"invoice_id": "a1b2c3d4-0000-0000-0000-000000000000",
"status": "pending",
"sub_status": "with_carrier",
"carrier_type": "CORREIOS",
"carrier_status": "pending",
"carrier_sub_status": "awaiting_response",
"outcome": null,
"resolution": null,
"compensation_amount": null,
"compensation_currency": null,
"rejection_reason_code": null,
"closure_reason": null,
"event_at": "2026-06-08T12:34:56.000Z"
}
```
A referência completa do evento (com glossário e exemplos por estado) está na [documentação de webhooks da API](/docs/api/webhook/dispute-status-change).
### Campos [#campos]
| Campo | Descrição |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `dispute_public_id` | Identificador curto da disputa (o mesmo exibido no painel). |
| `invoice_id` | Identificador do pedido ao qual a disputa pertence. |
| `status` | `pending` (em aberto) ou `resolved` (encerrada). |
| `sub_status` | Detalhe da situação enquanto em aberto (ex.: aguardando a marca, a transportadora, o cliente). `null` quando resolvida. |
| `carrier_type` | A transportadora envolvida, se houver. |
| `carrier_status` / `carrier_sub_status` | A situação do trilho com a transportadora. |
| `outcome` | O desfecho registrado ao resolver (entregue, retornado, perdido…). |
| `resolution` | A compensação (reembolso, voucher, reenvio…). |
| `compensation_amount` / `compensation_currency` | Valor da compensação, quando aplicável. |
| `rejection_reason_code` | Motivo, quando a disputa é rejeitada. |
| `closure_reason` | Motivo do encerramento. |
| `event_at` | Quando a mudança aconteceu (ISO 8601). |
Os webhooks são entregues na ordem de cada disputa. Se o seu endpoint responder com erro, a Abbiamo tenta novamente algumas vezes antes de desistir — então trate o recebimento de forma idempotente (use dispute\_public\_id + event\_at).
---
# Integração com o Zendesk (/docs/log/care/zendesk)
A integração com o **Zendesk** espelha cada disputa do Care como um ticket no seu Zendesk. É um caminho de mão única, pensado pra quem já centraliza o atendimento no Zendesk e quer que o pós-venda apareça por lá também — sem digitar nada duas vezes.
A integração é por marca e fica em Care → Configurações → Zendesk. Você liga, testa a conexão e pronto — as próximas disputas já sincronizam.
## O que ela faz [#o-que-ela-faz]
* **Abriu disputa → cria ticket.** Quando uma disputa é aberta, o Care cria um ticket no Zendesk com um **dossiê traduzido** (pedido, cliente, motivo, status, transportadora) e **links** pra disputa no painel e pro pedido.
* **Resolveu disputa → fecha o ticket.** Quando você resolve a disputa, o ticket correspondente é marcado como **solved**, com uma nota interna contendo o desfecho e a compensação.
* **Idempotente.** Cada disputa tem no máximo um ticket. Reabrir/reprocessar não duplica.
## O que você vê no ticket [#o-que-você-vê-no-ticket]
O corpo do ticket criado fica assim:
```
Assunto: Disputa Care #A1B2C3D4 — pedido 200050
Uma disputa de pedido não entregue foi aberta no Care.
• Pedido: 200050
• Cliente: Maria Souza
• Motivo: Não recebido
• Status: Em aberto (aguardando a marca)
• Transportadora: CORREIOS
Ver disputa: https://dashboard.abbiamolog.com/care/disputes?disputeId=A1B2C3D4
Ver pedido: https://dashboard.abbiamolog.com/orders?order_id=...
```
Na resolução, o ticket recebe uma nota interna com **Desfecho** e **Compensação** traduzidos e vira `solved`.
## Configuração, passo a passo [#configuração-passo-a-passo]
### 1. Pegue as credenciais no Zendesk [#1-pegue-as-credenciais-no-zendesk]
Você precisa de três coisas:
| Campo | Onde achar |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subdomínio** | É o começo da URL do seu Zendesk: em `https://suaempresa.zendesk.com`, o subdomínio é `suaempresa`. |
| **E-mail do agente** | O e-mail de um usuário **agente/admin** do seu Zendesk (ex.: `suporte@suaempresa.com`). |
| **API token** | Em **Admin Center → Apps and integrations → APIs → Zendesk API → Settings**, ative **Token access** e clique em **Add API token**. Copie o token gerado (ele só aparece uma vez). |
O Token access precisa estar ativado em Admin Center → APIs → Zendesk API → Settings. Se estiver desligado, a conexão falha com "Credenciais inválidas" mesmo com o token certo.
### 2. Preencha no Care [#2-preencha-no-care]
Em **Care → Configurações → Zendesk**, preencha **subdomínio**, **e-mail do agente** e **API token**.
### 3. Teste a conexão [#3-teste-a-conexão]
Clique em **Testar conexão**. O Care valida as credenciais direto no Zendesk e mostra o nome do agente autenticado. Erros comuns:
* **Credenciais inválidas** — e-mail ou token errados, ou Token access desligado (veja o aviso acima).
* **Subdomínio não encontrado** — confira o subdomínio (sem `https://` e sem `.zendesk.com`).
### 4. Ative e salve [#4-ative-e-salve]
Ligue o toggle **Ativar integração** e salve. A partir daí, **novas disputas** sincronizam automaticamente.
Disputas já existentes antes de ligar a integração não geram ticket retroativo — só as criadas depois.
## Boas práticas [#boas-práticas]
* Use um **e-mail de agente dedicado** (ex.: `integracao@suaempresa.com`) pra ficar fácil identificar os tickets criados pela Abbiamo.
* O token é sensível: o Care nunca devolve o token salvo na tela (só indica que existe um). Pra trocar, basta colar um novo.
* O ticket é enriquecido no idioma do painel; os campos de status/desfecho/compensação vêm **traduzidos**.
## Limitações [#limitações]
* Sincronização é **one-way** (Care → Zendesk). Responder no ticket do Zendesk não volta pro chat do Care.
* Um ticket por disputa.
---
# Integrações (/docs/log/integrations)
---
# Guia de Onboarding — LOG (/docs/log/onboarding)
O **LOG** é o contexto da plataforma Abbiamo para **embarcadores**: varejistas, e-commerces, distribuidores ou qualquer empresa que precise enviar pedidos para clientes usando transportadoras externas.
Com o LOG você centraliza toda a operação logística — da chegada do pedido até a confirmação da entrega — sem precisar acessar o sistema de cada transportadora separadamente.
***
## O que você consegue fazer [#o-que-você-consegue-fazer]
```
Pedido chega → Frete cotado → Transportadora acionada → Envio rastreado → Entrega confirmada
```
| Etapa | Como a Abbiamo resolve |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Receber pedidos** | Integração com VTEX, Shopify, Shopee, Linx, Intelipost e outros. Pedidos chegam automaticamente. |
| **Cotar frete** | Compara transportadoras em tempo real com base em CEP, peso, dimensões e prazo. Regras de frete permitem ajustar preços e ocultar opções. |
| **Despachar** | Automações de envio escolhem e acionam a transportadora certa sem intervenção manual. |
| **Acompanhar** | Tela de Envios mostra status em tempo real de cada entrega: despachado, em rota, sucesso, falha. |
| **Tratar falhas** | Automações de reenvio cuidam de envios com falha. Automações de inatividade detectam envios parados. |
| **Auditar e faturar** | Compara preço cotado vs. praticado. Faturas geradas por período. |
| **Medir** | Relatórios de volume, SLA e desempenho por transportadora e filial. |
***
## Hierarquia da conta [#hierarquia-da-conta]
```
Conta (Seller Group)
└── Filial (Seller)
├── Usuários
├── Integrações de Pedido
├── Integrações de Transportadora
└── Pedidos / Envios / Rotas
```
Toda a operação acontece dentro de uma **Filial**. Uma conta pode ter múltiplas filiais — por loja, região ou CNPJ.
***
## Conceitos essenciais [#conceitos-essenciais]
### 1. Conta e Filial [#1-conta-e-filial]
* **[Conta (Seller Group)](/docs/log/conceitos/seller-group/)** — nível mais alto: agrupa filiais, define permissões globais e consolida relatórios.
* **[Filial (Seller)](/docs/log/conceitos/filial/)** — unidade operacional. Cada filial tem seu endereço, CNPJ, horários de operação e configurações próprias de transportadora.
### 2. Pedido e Envio [#2-pedido-e-envio]
* **[Pedido](/docs/log/conceitos/pedido/)** — a solicitação de entrega. Contém NF, dados do destinatário, itens e status geral.
* **[Envio (Delivery)](/docs/log/conceitos/envio/)** — a execução logística de um pedido. Um pedido pode ter múltiplos envios (tentativa inicial + reenvios).
* **[Status de Pedido](/docs/log/conceitos/status-de-pedido/)** — ciclo de vida do pedido: Pendente → Despachado → Em Rota → Sucesso / Falha.
### 3. Transportadora e Frete [#3-transportadora-e-frete]
* **[Transportadora](/docs/log/conceitos/transportadora/)** — empresa que executa a entrega. Ativada via Integração de Transportadora.
* **[Integração de Transportadora](/docs/log/conceitos/integracao-transportadora/)** — configuração que liga uma filial a uma transportadora. Define credenciais, modalidade e regras de despacho.
* **[Tabela de Frete](/docs/log/conceitos/tabela-frete/)** — define preço e prazo por CEP ou raio. Usada na cotação.
* **[Modalidade](/docs/log/conceitos/modalidade/)** — tipo de serviço da transportadora (ex.: Expresso, Econômico, Moto).
### 4. Automações [#4-automações]
* **[Automação de Envio](/docs/log/conceitos/regra-envio/)** — escolhe automaticamente qual transportadora/modalidade usar para despachar um pedido.
* **[Automação de Reenvio](/docs/log/conceitos/regra-reenvio/)** — redespacha automaticamente quando um envio falha.
* **[Automação de Inatividade](/docs/log/conceitos/regra-inatividade/)** — age quando um envio fica sem atualização de status por muito tempo.
* **[Marcador](/docs/log/conceitos/marcador/)** — tag colorida aplicada a pedidos e motoristas para segmentação e filtros.
### 5. Financeiro [#5-financeiro]
* **[Fatura](/docs/log/conceitos/fatura/)** — gerada sob demanda, consolida o custo dos envios do período comparando preço cotado e auditado.
***
## Primeiros passos [#primeiros-passos]
### Passo 1 — Configure as filiais [#passo-1--configure-as-filiais]
Cadastre cada unidade operacional com nome, CNPJ, endereço e horários de operação.
→ [Ver documentação de Filiais](/docs/log/settings/filiais/)
### Passo 2 — Conecte suas transportadoras [#passo-2--conecte-suas-transportadoras]
Configure as credenciais de cada transportadora por filial em **Configurações > Integrações de Transportadora**.
→ [Ver Integrações de Transportadora](/docs/log/settings/integracoes-de-transportador/)
### Passo 3 — Configure tabelas de frete (se necessário) [#passo-3--configure-tabelas-de-frete-se-necessário]
Se a transportadora não tiver cotação dinâmica, suba uma **Tabela de Frete** com preço e prazo por CEP.
→ [Ver Tabelas de Frete](/docs/log/products/tabelas-de-frete/)
### Passo 4 — Integre a origem dos pedidos [#passo-4--integre-a-origem-dos-pedidos]
Configure a integração com seu e-commerce ou ERP em **Configurações > Integrações de Pedido**.
→ [Ver Integrações de Pedido](/docs/log/settings/integracoes-de-pedidos/)
### Passo 5 — Crie automações de envio [#passo-5--crie-automações-de-envio]
Defina as regras para despacho automático: qual transportadora usar para cada tipo de pedido, região ou horário.
→ [Ver Automações de Envio](/docs/log/products/regras-de-envio/)
### Passo 6 — Configure tratamento de falhas [#passo-6--configure-tratamento-de-falhas]
Crie automações de reenvio e inatividade para que a operação continue sem intervenção manual mesmo em cenários de falha.
→ [Automações de Reenvio](/docs/log/products/regras-de-reenvio/) · [Automações de Inatividade](/docs/log/products/regras-de-inatividade/)
### Passo 7 — Ative webhooks (opcional) [#passo-7--ative-webhooks-opcional]
Configure webhooks para receber atualizações de status de entrega em tempo real no seu sistema.
→ [Ver Webhooks](/docs/log/settings/webhooks/)
***
## Operação com frota própria — LOG + GO [#operação-com-frota-própria--log--go]
Se além de transportadoras externas você também opera com **frota própria** (veículos e motoristas da sua empresa), é possível solicitar uma **conta GO** vinculada à sua conta LOG.
Com o acoplamento LOG + GO, a sua conta GO aparece como uma **transportadora dentro do LOG** — da mesma forma que qualquer transportadora externa. Isso permite:
| Cenário | Como funciona |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **GO como transportador principal** | Configure sua transportadora GO com prioridade nas automações de envio. Pedidos são direcionados primeiro para a sua frota. |
| **GO como escoador** | Use a frota própria para absorver pedidos que as transportadoras externas não conseguem atender (overflow). |
| **Transportadora externa como principal, GO como complemento** | Mantenha transportadoras externas no fluxo principal e acione a frota GO em regiões ou horários específicos. |
Para solicitar a ativação de uma conta GO vinculada, entre em contato com o suporte ou com o seu gerente de conta.
→ [Ver documentação do GO](/docs/go/)
***
## Mapa da documentação LOG [#mapa-da-documentação-log]
| Área | Páginas disponíveis |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pedidos** | [Visão Geral](/docs/log/products/pedidos/) · [Como Usar](/docs/log/products/pedidos/como-usar/) |
| **Envios** | [Visão Geral](/docs/log/products/envios/) · [Como Usar](/docs/log/products/envios/como-usar/) |
| **Rotas** | [Visão Geral](/docs/log/products/rotas/) · [Como Usar](/docs/log/products/rotas/como-usar/) |
| **Relatórios** | [Visão Geral](/docs/log/products/relatorios/) · [Como Usar](/docs/log/products/relatorios/como-usar/) |
| **Faturas** | [Visão Geral](/docs/log/products/faturas/) |
| **CSAT** | [Visão Geral](/docs/log/products/pesquisa-satisfacao/) |
| **Automações de Envio** | [Visão Geral](/docs/log/products/regras-de-envio/) · [Como Usar](/docs/log/products/regras-de-envio/como-usar/) |
| **Automações de Reenvio** | [Visão Geral](/docs/log/products/regras-de-reenvio/) · [Como Usar](/docs/log/products/regras-de-reenvio/como-usar/) |
| **Automações de Inatividade** | [Visão Geral](/docs/log/products/regras-de-inatividade/) · [Como Usar](/docs/log/products/regras-de-inatividade/como-usar/) |
| **Automações de Marcadores** | [Visão Geral](/docs/log/products/automacoes-de-marcadores/) · [Como Usar](/docs/log/products/automacoes-de-marcadores/como-usar/) |
| **Tabelas de Frete** | [Visão Geral](/docs/log/products/tabelas-de-frete/) · [Como Usar](/docs/log/products/tabelas-de-frete/como-usar/) |
| **Regras de Frete** | [Visão Geral](/docs/log/products/regras-de-frete/) · [Como Usar](/docs/log/products/regras-de-frete/como-usar/) |
| **Configurações** | [Filiais](/docs/log/settings/filiais/) · [Marcadores](/docs/log/settings/marcadores/) · [Usuários](/docs/log/settings/usuarios/) · [API](/docs/log/settings/api/) · [Webhooks](/docs/log/settings/webhooks/) · [Integrações de Pedido](/docs/log/settings/integracoes-de-pedidos/) · [Integrações de Transportadora](/docs/log/settings/integracoes-de-transportador/) |
---
# Produtos (/docs/log/products)
---
# API (/docs/log/settings/api)
**URL:** `https://dashboard.abbiamolog.com/settings/tokens`
Aqui você encontra a **Chave de API** do seu seller group — necessária para autenticar requisições às APIs da Abbiamo a partir de sistemas externos.
***
## Chave de API [#chave-de-api]
A chave é exibida de forma mascarada (••••••••). Use os botões ao lado para:
| Botão | Função |
| ---------------- | ----------------------------------------------- |
| **Copiar** (📋) | Copia a chave para a área de transferência |
| **Revelar** (👁) | Exibe o valor completo da chave temporariamente |
***
## Como usar a Chave de API [#como-usar-a-chave-de-api]
A chave deve ser enviada no **header** de cada requisição à API:
```http
x-abbiamo-seller-group-key: SUA_CHAVE_AQUI
```
### Exemplo de requisição [#exemplo-de-requisição]
```bash
curl -X GET "https://api.abbiamo.io/v1/drivers" \
-H "x-abbiamo-seller-group-key: SUA_CHAVE_AQUI"
```
***
## Documentação completa da API [#documentação-completa-da-api]
A referência oficial de todos os endpoints está disponível em:
**[Documentação da API](/docs/api)**
Lá você encontra:
* Endpoints de pedidos, rotas, motoristas e webhooks
* Exemplos de requisição e resposta
* Schemas de payload
* Guias de autenticação e integração
---
# Filiais (/docs/log/settings/filiais)
A tela de **Filiais** centraliza o gerenciamento de todas as lojas/unidades da sua conta. Cada filial possui dados cadastrais, endereço e horários de operação — usados pela plataforma para cotação de frete, automações e relatórios.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/sellers](https://dashboard.abbiamolog.com/sellers)
* **Menu:** seção **Configurações** > **Filiais**
***
## Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------------------ | -------------------------------------------- |
| **Título** | "Filiais" |
| **Menu de ações** (Beta) | Abre paleta de comandos rápidos (`Ctrl + K`) |
| **Nova filial** | Abre o modal de criação de filial |
***
## Barra de filtros [#barra-de-filtros]
| Filtro | Descrição |
| --------------------------- | ---------------------------------------------------- |
| **Pesquisar** | Busca por nome, documento ou identificador da filial |
| **Atualizar** | Recarrega a lista |
| **Filtros** | Painel de filtros avançados |
| **Visibilidade de colunas** | Mostrar/ocultar colunas da tabela |
***
## Tabela de filiais [#tabela-de-filiais]
| Coluna | O que mostra |
| ---------------------- | ------------------------------------------------------------ |
| **ID** | Identificador único da filial (truncado, com botão de cópia) |
| **Filial** | Nome exibido como badge colorido |
| **Documento** | CNPJ ou outro documento de registro |
| **Identificador** | Código interno (geralmente igual ao documento) |
| **Inscrição Estadual** | IE da filial |
| **Endereço** | Endereço completo (rua, número, bairro, cidade, estado, CEP) |
| **Hora** | Horários de operação configurados (ex.: SEG 08:00–17:00) |
| **Ícone de usuário** | Acesso rápido aos usuários vinculados à filial |
| **Ícone de relógio** | Acesso rápido aos horários de operação |
| **Menu (⋯)** | Ações adicionais por filial |
***
## Criar filial [#criar-filial]
Clique em **Nova filial** para abrir o modal de criação. O modal tem duas abas:
### Aba: Informações gerais [#aba-informações-gerais]
| Campo | Obrigatório | Descrição |
| ----------------------- | ----------- | ------------------------------------------------------------------ |
| **Nome da filial** | ✓ | Nome de exibição da loja (ex.: "Loja Centro SP") |
| **Documento** | ✓ | Tipo (CNPJ/CPF) + número |
| **Email da filial** | | Email de contato da loja |
| **Identificador** | ✓ | Código interno — pode ser igual ao documento (checkbox "Replicar") |
| **Telefone da filial** | | Telefone de contato |
| **Inscrição Estadual** | | Número da IE |
| **País / Fuso horário** | ✓ | País (padrão: BRA) e fuso (padrão: America/Sao\_Paulo) |
| **CEP** | ✓ | Preenchimento automático do endereço ao digitar |
| **Rua** | ✓ | Nome da rua |
| **Número** | ✓ | Número do endereço |
| **Complemento** | | Apto, sala, etc. |
| **Bairro** | ✓ | Bairro |
| **Cidade** | ✓ | Cidade |
| **Estado** | ✓ | UF |
| **Referência** | | Instruções para facilitar o entregador achar o local de coleta |
### Aba: Horários de operação [#aba-horários-de-operação]
Configure os horários de funcionamento por dia da semana. Esses horários são usados por automações de envio e pela plataforma para agendamento de coletas.
| Campo | Descrição |
| ----------------- | ---------------------------------- |
| **Dia da semana** | SEG, TER, QUA, QUI, SEX, SAB, DOM |
| **Hora início** | Horário de abertura (ex.: 08:00) |
| **Hora fim** | Horário de fechamento (ex.: 18:00) |
***
## Paginação [#paginação]
* **Padrão:** 50 filiais por página
* **Opções:** 50, 100, 150, 200
---
# Configurações — Visão Geral (/docs/log/settings)
As **Configurações** do dashboard centralizam os ajustes da conta, da equipe, da identidade visual e das integrações técnicas.
* **URL:** `https://dashboard.abbiamolog.com/settings`
* **Acesso:** ícone de engrenagem ⚙ no canto inferior esquerdo do menu lateral
***
## Estrutura das configurações [#estrutura-das-configurações]
### Gerais [#gerais]
| Página | O que configura |
| ---------------------------------------------------- | ----------------------------------------------------------------- |
| [**Preferências**](/docs/log/settings/preferencias/) | Aparência (claro/escuro) e idioma da interface |
| [**Usuários**](/docs/log/settings/usuarios/) | Criação, edição e controle de acesso de usuários da conta |
| [**Temas**](/docs/log/settings/temas/) | Identidade visual (logo, cor e link da marca) por filial |
| [**Notificações**](/docs/log/settings/notificacoes/) | Envio de notificações ao cliente final via e-mail, SMS e WhatsApp |
### Desenvolvedor [#desenvolvedor]
| Página | O que configura |
| -------------------------------------------- | ------------------------------------------------------- |
| [**API**](/docs/log/settings/api/) | Chave de API do seller group para integração externa |
| [**Webhooks**](/docs/log/settings/webhooks/) | Endpoints para receber eventos em tempo real do sistema |
### Outros [#outros]
| Página | O que configura |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [**Marcadores**](/docs/log/settings/marcadores/) | Tags personalizadas para pedidos e motoristas |
| [**Filiais**](/docs/log/settings/filiais/) | Cadastro e gestão de filiais: dados, endereço e horários de operação |
| [**Integrações de Pedido**](/docs/log/settings/integracoes-de-pedidos/) | Conexões com plataformas de e-commerce (VTEX, Shopify, Shopee etc.) para importar pedidos automaticamente |
| [**Integrações de Transportadora**](/docs/log/settings/integracoes-de-transportador/) | Conexões com transportadoras externas para cotação e despacho automático |
***
---
# Integrações de Pedido — Visão Geral (/docs/log/settings/integracoes-de-pedidos)
A página de **Integrações de Pedido** centraliza a configuração e o monitoramento das conexões entre a plataforma Abbiamo e sistemas externos de e-commerce ou ERPs, permitindo a importação automática de pedidos.
***
## Onde acessar [#onde-acessar]
* **URL:** `https://dashboard.abbiamolog.com/order-integrations`
* **Menu:** seção **Configurações** > **Integrações de Pedido**
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------------- | ------------------------------------------ |
| **Título** | "Integrações de pedido" |
| **Nova integração** | Abre o modal de criação de nova integração |
### Barra de filtros [#barra-de-filtros]
* **Campo de busca** — Pesquisa por nome da integração ou filial.
* **Botão atualizar** — Recarrega a lista manualmente.
* **Filtros avançados** — Nome, Filial, Situação (Ativa/Desativada).
* **Visibilidade de colunas** — Mostrar/ocultar colunas da tabela.
### Tabela de integrações [#tabela-de-integrações]
| Coluna | O que mostra |
| ----------------- | -------------------------------------------------------------------- |
| **Nome** | Nome dado à integração |
| **Filial** | Filial vinculada à integração |
| **Provedor** | Plataforma conectada (VTEX, Shopify, Shopee, Linx, Intelipost, etc.) |
| **Situação** | Badge Ativa ou Desativada |
| **Criado em** | Data e hora de criação |
| **Atualizado em** | Data e hora da última atualização |
| **Ações** | Menu (⋮) com Ver, Editar, Ativar/Desativar e Excluir |
### Menu de ações por integração (⋮) [#menu-de-ações-por-integração-]
| Ação | Descrição |
| ---------------------- | ----------------------------------------------------- |
| **Ver integração** | Abre modal somente leitura com os dados da integração |
| **Editar integração** | Abre modal de edição |
| **Ativar / Desativar** | Alterna a situação da integração |
| **Excluir integração** | Remove a integração após confirmação |
***
## Provedores disponíveis [#provedores-disponíveis]
| Provedor | Descrição |
| -------------- | ----------------------------------- |
| **VTEX** | Plataforma de e-commerce enterprise |
| **Shopify** | Plataforma de e-commerce para PMEs |
| **Shopee** | Marketplace |
| **Linx** | ERP/OMS para varejo |
| **Intelipost** | TMS e gestão logística |
***
## Modal de criação e edição [#modal-de-criação-e-edição]
O modal varia conforme o provedor selecionado, mas geralmente solicita:
| Campo | Descrição |
| --------------- | -------------------------------------------------------------- |
| **Nome** | Identificador interno da integração |
| **Filial** | Filial que receberá os pedidos importados |
| **Provedor** | Plataforma a conectar |
| **Credenciais** | Chaves de API, tokens ou configurações específicas do provedor |
***
## Estado vazio [#estado-vazio]
Quando não há integrações configuradas:
> *"Nenhuma integração de pedido encontrada"*
***
## Comportamentos automáticos [#comportamentos-automáticos]
* Pedidos criados na plataforma integrada são importados automaticamente para a filial configurada.
* A integração pode ser desativada temporariamente sem perda de configuração.
---
# Integrações de Transportadora — Visão Geral (/docs/log/settings/integracoes-de-transportador)
A página de **Integrações de Transportadora** centraliza a configuração das conexões entre a plataforma Abbiamo e transportadoras externas, habilitando cotação de frete, despacho automático e rastreamento em tempo real.
***
## Onde acessar [#onde-acessar]
* **URL:** `https://dashboard.abbiamolog.com/carrier-integrations`
* **Menu:** seção **Configurações** > **Integrações de Transportadora**
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------------- | ------------------------------------------ |
| **Título** | "Integrações de transportadora" |
| **Nova integração** | Abre o modal de criação de nova integração |
### Barra de filtros [#barra-de-filtros]
* **Campo de busca** — Pesquisa por nome da integração ou transportadora.
* **Botão atualizar** — Recarrega a lista manualmente.
* **Filtros avançados** — Nome, Transportadora, Filial, Situação.
* **Visibilidade de colunas** — Mostrar/ocultar colunas da tabela.
### Tabela de integrações [#tabela-de-integrações]
| Coluna | O que mostra |
| ------------------ | ---------------------------------------------------- |
| **Nome** | Nome dado à integração |
| **Transportadora** | Nome da transportadora integrada |
| **Filial** | Filial vinculada |
| **Situação** | Badge Ativa ou Desativada |
| **Criado em** | Data e hora de criação |
| **Atualizado em** | Data e hora da última atualização |
| **Ações** | Menu (⋮) com Ver, Editar, Ativar/Desativar e Excluir |
### Menu de ações por integração (⋮) [#menu-de-ações-por-integração-]
| Ação | Descrição |
| ---------------------- | ----------------------------------------------------- |
| **Ver integração** | Abre modal somente leitura com os dados da integração |
| **Editar integração** | Abre modal de edição |
| **Ativar / Desativar** | Alterna a situação da integração |
| **Excluir integração** | Remove a integração após confirmação |
***
## Modal de criação e edição [#modal-de-criação-e-edição]
O modal varia conforme a transportadora selecionada, mas geralmente solicita:
| Campo | Descrição |
| ---------------------------- | ------------------------------------------------------------------------------- |
| **Nome** | Identificador interno da integração |
| **Transportadora** | Carrier a conectar |
| **Filial** | Filial de origem dos despachos |
| **Credenciais** | Chaves de API ou tokens da transportadora |
| **Configurações adicionais** | Parâmetros específicos da transportadora (ex.: conta, contrato, CNPJ remetente) |
***
## Relação com outras funcionalidades [#relação-com-outras-funcionalidades]
| Funcionalidade | Como usa a integração |
| -------------------------------------------------------------- | -------------------------------------------------------------- |
| [**Cotação de Frete**](/docs/log/acoes/cotacao-frete/) | Consulta a API da transportadora para retornar preços e prazos |
| [**Automações de Envio**](/docs/log/products/regras-de-envio/) | Despacha para a transportadora configurada na automação |
| [**Tabelas de Frete**](/docs/log/products/tabelas-de-frete/) | Complementa ou substitui a cotação via API com preços manuais |
***
## Estado vazio [#estado-vazio]
Quando não há integrações configuradas:
> *"Nenhuma integração de transportadora encontrada"*
***
## Comportamentos automáticos [#comportamentos-automáticos]
* Uma integração desativada impede cotação e despacho para aquela transportadora.
* Automações de Envio que referenciam uma integração desativada exibem um badge de alerta.
---
# Marcadores (/docs/log/settings/marcadores)
**URL:** `https://dashboard.abbiamolog.com/settings/tags`
Marcadores são **tags coloridas** que você cria para categorizar pedidos, facilitando filtros e organização na operação.
***
## Colunas da tabela [#colunas-da-tabela]
| Coluna | Descrição |
| ------------- | ----------------------------------------------------- |
| **Nome** | Nome do marcador com prévia da cor (bolinha colorida) |
| **Descrição** | Descrição opcional do marcador |
| **Criado em** | Data e hora de criação |
***
## Criar marcador [#criar-marcador]
1. Clique no **+** no canto superior direito.
2. Informe o **Nome** (obrigatório).
3. Adicione uma **Descrição** opcional.
4. Selecione a **Cor** em hexadecimal (padrão: `#3B82F6` — azul).
5. Clique em **Criar marcador**.
***
## Editar um marcador [#editar-um-marcador]
No menu ⋯ do marcador, clique em **Editar marcador**. Os campos disponíveis são os mesmos da criação (Nome, Descrição, Cor).
---
# Notificações (/docs/log/settings/notificacoes)
**URL:** `https://dashboard.abbiamolog.com/settings/notifications`
Controle quais notificações são enviadas ao **cliente final** a cada evento de pedido, e por qual canal.
***
## Canais disponíveis [#canais-disponíveis]
| Canal | Descrição | Provedor |
| ------------ | ----------------------------------------------------------- | ---------------------------- |
| **E-mail** | Notificação por e-mail para o endereço cadastrado no pedido | Abbiamo |
| **SMS** | Mensagem de texto para o celular do destinatário | Abbiamo |
| **WhatsApp** | Mensagem via WhatsApp para o celular do destinatário | Botmaker, Twilio ou Polichat |
***
## Gatilhos disponíveis [#gatilhos-disponíveis]
### Entrega [#entrega]
| Gatilho | Quando dispara |
| ------------------------------- | ---------------------------------------------------------------------------------- |
| **Pedido criado** | Quando um novo pedido é registrado no sistema |
| **Pedido em rota** | Quando o motorista inicia a rota com o pedido |
| **Pedido entregue + Avaliação** | Quando a entrega é confirmada com sucesso; inclui link para pesquisa de satisfação |
### Retirada em loja [#retirada-em-loja]
| Gatilho | Quando dispara |
| ------------------------ | ---------------------------------------------------------- |
| **Pronto para retirada** | Quando o pedido está disponível para retirada pelo cliente |
| **Adiar retirada** | Quando a data de retirada do pedido é adiada |
***
## Como editar as notificações [#como-editar-as-notificações]
1. Clique em **Editar** no canto inferior direito da tela.
2. Marque ou desmarque os checkboxes para cada combinação de **gatilho × canal**.
3. Salve as alterações.
---
# Preferências (/docs/log/settings/preferencias)
**URL:** `https://dashboard.abbiamolog.com/settings`
Ajustes pessoais do usuário logado — não afetam outros membros da equipe.
***
## Aparência [#aparência]
Escolha entre dois temas visuais para o dashboard:
| Opção | Descrição |
| ---------- | ----------------------------------- |
| **Claro** | Interface com fundo branco (padrão) |
| **Escuro** | Interface com fundo escuro |
A escolha é salva automaticamente e persiste entre sessões.
***
## Língua e região [#língua-e-região]
Selecione o idioma da interface no menu suspenso.
| Opção disponível |
| ---------------- |
| Português |
A configuração de idioma afeta rótulos, datas e mensagens exibidas na interface.
---
# Temas (/docs/log/settings/temas)
**URL:** `https://dashboard.abbiamolog.com/settings/themes`
Configure a identidade visual exibida ao seu cliente final na página de rastreio e nas comunicações enviadas pela Abbiamo.
***
## O que você vê na tela [#o-que-você-vê-na-tela]
Os temas são exibidos como **cartões visuais** com preview da logomarca. Cada cartão mostra:
| Elemento | Descrição |
| ----------- | ------------------------------------------------------------------------------ |
| **Preview** | Miniatura com a logo e cor de fundo do tema |
| **Nome** | Nome interno do tema |
| **Padrão** | Badge "Padrão" indica o tema aplicado por padrão a filiais sem tema específico |
| **Filiais** | Número de filiais usando este tema |
| **Menu ⋯** | Ações disponíveis para o tema |
***
## Ações do tema (menu ⋯) [#ações-do-tema-menu-]
| Ação | Descrição |
| ---------------------------- | -------------------------------------------------- |
| **Ver detalhes** | Abre o modal de edição do tema |
| **Definir como tema padrão** | Define este tema como padrão da conta |
| **Aplicar tema em filiais** | Associa o tema a uma ou mais filiais |
| **Desativar tema** | Desativa o tema (não pode ser o tema padrão ativo) |
***
## Campos do tema [#campos-do-tema]
Acessíveis em **Ver detalhes**:
| Campo | Obrigatório | Descrição |
| ----------------------------- | ----------- | ---------------------------------------------------------- |
| **Nome** | Sim | Nome interno para identificação no dashboard |
| **Nome de exibição** | Não | Nome exibido ao cliente final |
| **Link da sua marca** | Não | URL para o site da marca (ex: `https://suamarca.com.br`) |
| **Cor primária** | Sim | Cor principal da marca em hexadecimal (ex: `#FF5733`) |
| **Cor de fundo da logomarca** | Não | Cor de fundo usada atrás da logo em hexadecimal |
| **Logomarca** | Não | Upload da imagem da logo (recomendado: fundo transparente) |
| **Ícone** | Não | Upload do ícone da marca (favicon/ícone compacto) |
***
## Como aplicar um tema a filiais [#como-aplicar-um-tema-a-filiais]
1. No menu ⋯ do tema, clique em **Aplicar tema em filiais**.
2. Selecione as filiais desejadas.
3. Confirme.
As filiais sem tema específico utilizam automaticamente o **tema padrão** da conta.
---
# Usuários (/docs/log/settings/usuarios)
**URL:** `https://dashboard.abbiamolog.com/settings/users`
Gerencie quem tem acesso ao dashboard e quais permissões cada pessoa possui.
***
## O que você vê na tela [#o-que-você-vê-na-tela]
### Barra superior [#barra-superior]
| Elemento | Função |
| ---------------- | --------------------------------------- |
| **Pesquisar** | Busca por e-mail |
| **Filtros** | Filtra por tipo, status ativo e filiais |
| **Novo usuário** | Abre o modal de criação |
### Tabela de usuários [#tabela-de-usuários]
| Coluna | Descrição |
| ----------------- | -------------------------------------------------------- |
| **Email** | Endereço de e-mail do usuário |
| **Tipo** | Nível de acesso: `PROPRIETÁRIO` ou `ADMINISTRADOR` |
| **Usuário ativo** | Indicador verde (ativo) ou apagado (inativo) |
| **Permissões** | Permissões específicas concedidas (quando aplicável) |
| **Filiais** | Filiais às quais o usuário tem acesso (`TODOS` ou lista) |
| **Ações** | Ícone de edição (✏) e menu ⋯ |
***
## Tipos de usuário [#tipos-de-usuário]
| Tipo | Descrição |
| ----------------- | ------------------------------------------------------------------------------------ |
| **Proprietário** | Acesso total a todas as filiais e configurações. Não pode ser restringido por filial |
| **Administrador** | Acesso configurável — pode ser limitado a filiais específicas |
***
## Criar um usuário [#criar-um-usuário]
1. Clique em **Novo usuário** no canto superior direito.
2. Informe o **e-mail** do novo usuário.
3. Selecione o **tipo** (Administrador é o padrão para novos usuários).
4. Associe as **filiais** que este usuário poderá acessar.
5. Clique em **Salvar**.
O usuário receberá um e-mail com uma **senha temporária** — não um link de definição de senha. Ao entrar pela primeira vez com ela pelo portal, é pedido que defina sua senha definitiva antes de acessar o dashboard.
***
## Editar um usuário [#editar-um-usuário]
1. Clique no ícone de edição (✏) na linha do usuário desejado.
2. Ajuste o **tipo**, as **filiais** ou o status **Ativo**.
3. Clique em **Salvar**.
### Campos editáveis [#campos-editáveis]
| Campo | Descrição |
| ----------- | ------------------------------------- |
| **Email** | Exibido, não editável |
| **Ativo** | Toggle para ativar/desativar o acesso |
| **Tipo** | Proprietário ou Administrador |
| **Filiais** | Filiais associadas ao usuário |
***
## Desativar um usuário [#desativar-um-usuário]
No modal de edição, desative o toggle **Ativo** e clique em **Salvar**. O usuário perde acesso imediatamente mas permanece na lista (para reativação futura).
---
# Webhooks (/docs/log/settings/webhooks)
**URL:** `https://dashboard.abbiamolog.com/settings/webhooks`
Configure URLs que receberão chamadas **HTTP POST** automáticas sempre que um evento ocorrer no sistema — útil para sincronizar seu sistema com a Abbiamo em tempo real.
***
## O que você vê na tela [#o-que-você-vê-na-tela]
### Tabela de webhooks [#tabela-de-webhooks]
| Coluna | Descrição |
| ------------- | ----------------------------------------------------------- |
| **ID** | Identificador único do webhook (truncado, com botão copiar) |
| **Evento** | Tipo de evento que dispara o webhook (badge colorido) |
| **Ativo** | Indicador verde (ativo) ou vermelho (inativo) |
| **URL** | Endpoint que receberá as notificações |
| **Headers** | Headers customizados configurados (quando houver) |
| **Ações (⋯)** | Editar webhook ou ativar/desativar |
***
## Eventos disponíveis [#eventos-disponíveis]
| Evento | Quando dispara |
| --------------------- | --------------------------------------------------------- |
| `ORDER_STATUS_CHANGE` | A cada mudança de status de um pedido |
| `ROUTE_STATUS_CHANGE` | A cada mudança de status de uma rota |
| `TOKEN_GENERATED` | Quando um novo token de API é gerado |
| `ORDER_CSAT_ANSWER` | Quando o cliente responde à pesquisa de satisfação (CSAT) |
***
## Criar um webhook [#criar-um-webhook]
1. Clique em **Novo webhook** no canto superior direito.
2. Selecione o **Evento** no menu suspenso.
3. Informe a **Webhook URL** — o endpoint do seu sistema que receberá as chamadas.
4. Opcionalmente, clique em **+ Adicionar header** para incluir headers de autenticação ou identificação.
5. Ative o toggle **Ativar webhook?** se quiser ativá-lo imediatamente.
6. Clique em **Criar webhook**.
### Campos do formulário [#campos-do-formulário]
| Campo | Obrigatório | Descrição |
| ------------------- | ----------- | --------------------------------------------------------------------------------- |
| **Evento** | Sim | Tipo de evento que dispara o webhook |
| **Webhook URL** | Sim | URL do seu endpoint (deve aceitar POST) |
| **Headers** | Não | Pares chave-valor enviados em cada requisição (ex: `Authorization: Bearer token`) |
| **Ativar webhook?** | — | Toggle para ativar imediatamente |
***
## Editar ou desativar um webhook [#editar-ou-desativar-um-webhook]
No menu ⋯ de qualquer webhook:
| Ação | Descrição |
| ---------------------- | ----------------------------------- |
| **Editar webhook** | Altera evento, URL ou headers |
| **Ativar / Desativar** | Pausa ou retoma o envio sem excluir |
***
## Formato do payload [#formato-do-payload]
A Abbiamo envia um `POST` com o corpo em JSON para a URL configurada. Para detalhes completos do payload de cada evento, consulte a documentação oficial:
**[Documentação da API — Webhooks](/docs/api/webhook)**
---
# Automação de Marcador (/docs/log/conceitos/automacao-marcador)
Uma **Automação de Marcador** é uma regra que aplica um [Marcador](/docs/log/conceitos/marcador/) automaticamente a um pedido quando determinadas condições são atendidas. Ela elimina a marcação manual e garante consistência na classificação dos pedidos.
***
## Como funciona [#como-funciona]
Quando um pedido entra ou é atualizado na plataforma, todas as automações de marcadores **ativas** são avaliadas em ordem de **sequência**. Para cada automação:
1. As condições configuradas são verificadas contra os dados do pedido.
2. Se todas as condições forem atendidas (ou não houver condições), o marcador é aplicado.
3. A avaliação continua nas próximas automações — **um pedido pode receber múltiplos marcadores**.
```
Pedido chega
→ Automação 1 (seq. 1): condições atendidas? → aplica marcador A
→ Automação 2 (seq. 2): condições atendidas? → aplica marcador B
→ Automação 3 (seq. 3): condições não atendidas → não aplica
```
***
## Componentes de uma automação [#componentes-de-uma-automação]
| Campo | Descrição |
| ------------- | -------------------------------------------------------------------------------- |
| **Título** | Nome descritivo da regra |
| **Sequência** | Ordem de avaliação (1 = primeiro). Controla a prioridade quando a ordem importa. |
| **Condições** | Filtros que o pedido deve atender. Sem condições = aplica em todos os pedidos. |
| **Marcador** | O marcador que será aplicado quando as condições forem satisfeitas. |
| **Situação** | Ativa ou Desativada. Automações desativadas não são avaliadas. |
***
## Condições [#condições]
As condições são construídas como filtros: um **campo** (ex.: Filial, CEP, SKU), um **operador** (é / não é / contém) e um **valor**. Múltiplas condições numa mesma automação são avaliadas em conjunto — o pedido precisa satisfazer **todas** (lógica AND).
***
## Diferença para marcação manual [#diferença-para-marcação-manual]
| | Automação | Manual |
| ------------------ | ------------------------------------------ | ---------------------------------- |
| **Aplicação** | Automática ao receber/atualizar o pedido | Usuário aplica na tela de Pedidos |
| **Escala** | Funciona para qualquer volume | Limitado pela capacidade da equipe |
| **Consistência** | Sempre aplica a mesma regra | Sujeito a esquecimento ou variação |
| **Retroatividade** | Não reaplica em pedidos antigos por padrão | Pode ser feita a qualquer momento |
***
## Relação com outras entidades [#relação-com-outras-entidades]
| Entidade | Relação |
| ---------------------------------------------------------- | ------------------------------------------------------------------------ |
| [**Marcador**](/docs/log/conceitos/marcador/) | O que é aplicado pela automação. Precisa existir antes de criar a regra. |
| [**Pedido**](/docs/log/conceitos/pedido/) | Entidade que recebe o marcador quando as condições são atendidas. |
| [**Automação de Envio**](/docs/log/conceitos/regra-envio/) | Pode usar marcadores como condição de despacho. |
| [**Filtros de Pedidos**](/docs/log/products/pedidos/) | Marcadores aplicados pelas automações ficam disponíveis como filtros. |
***
## Onde configurar [#onde-configurar]
* **Tela:** [Automações de Marcadores](/docs/log/products/automacoes-de-marcadores/)
* **URL:** `https://dashboard.abbiamolog.com/tags-rules`
---
# Automação de Oferta (/docs/log/conceitos/automacao-oferta)
Uma **automação de oferta** é uma regra que define automaticamente **para quais motoristas** (ou grupos de motoristas) uma entrega deve ser ofertada quando um pedido precisa ser despachado.
***
## O que é uma oferta de entrega [#o-que-é-uma-oferta-de-entrega]
Quando um pedido está pronto para ser despachado, a plataforma precisa saber **quem pode atender** aquela entrega. Em vez de atribuir um motorista fixo, a oferta é enviada para um conjunto de motoristas — e o primeiro a aceitar fica responsável pela entrega.
***
## Como funciona o fluxo [#como-funciona-o-fluxo]
1. **Pedido entra no sistema** e atinge o estado de pronto para despacho.
2. A plataforma percorre as **automações de oferta** da filial em **ordem de sequência**.
3. A primeira automação cujas **condições** são atendidas define o **conjunto de motoristas** que receberão a oferta.
4. O motorista recebe a notificação pelo app e pode **aceitar** ou **recusar**.
5. O primeiro a aceitar tem a entrega atribuída.
***
## Componentes de uma automação de oferta [#componentes-de-uma-automação-de-oferta]
| Campo | Descrição |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Filial** | Filial à qual a automação se aplica |
| **Tipo de operação** | ENTREGA (padrão) ou REVERSA |
| **Título** | Nome descritivo |
| **Condições** | Critérios que o pedido deve atender para acionar esta automação (ex.: CEP começa com "01", marcador = "Zona Sul") |
| **Ação** | Quem recebe a oferta |
### Opções de Ação [#opções-de-ação]
| Ação | Comportamento |
| ------------------------------ | ----------------------------------------------------------------- |
| **Todos os motoristas** | A oferta é enviada para todos os motoristas disponíveis da filial |
| **Motorista(s) específico(s)** | Apenas os motoristas selecionados recebem |
| **Grupo(s) de motoristas** | Apenas motoristas do(s) grupo(s) selecionado(s) recebem |
***
## Sequência e prioridade [#sequência-e-prioridade]
As automações são avaliadas em **ordem crescente de sequência**. A primeira cujas condições forem atendidas é executada — as demais são ignoradas para aquele pedido.
***
## Automação sem condições [#automação-sem-condições]
Uma automação sem condições age como **fallback universal** — todos os pedidos que não foram capturados por automações anteriores são direcionados para a ação definida nela.
***
## Diferença de Automação de Envio [#diferença-de-automação-de-envio]
| | Automação de Oferta | Automação de Envio |
| ------------- | -------------------------------------- | ------------------------------------------------- |
| **Contexto** | GO (frota própria) | LOG e GO (transportadoras externas) |
| **O que faz** | Define quem recebe a oferta de entrega | Define qual transportadora/prazo solicitar coleta |
| **Executa** | Motorista próprio via app | Transportadora externa via API |
***
## Onde aparece [#onde-aparece]
* [**Automações de Ofertas (GO)**](/docs/go/products/automacoes-de-ofertas/) — criação e gestão das automações.
* [**Tela de Motoristas**](/docs/tms/motoristas/) — motoristas que compõem os grupos e recebem ofertas.
---
# Conciliação de Frete (/docs/log/conceitos/conciliacao-frete)
Processo de validar:
* Valor cotado
* Valor cobrado
* Divergências de peso ou reclassificação
Ajuda no controle financeiro e margem.
---
# Cotação de Frete (/docs/log/conceitos/cotacao-frete)
A **Cotação de Frete** é o cálculo do valor e prazo de entrega antes de o envio ser criado. O sistema consulta as [tabelas de frete](/docs/log/conceitos/tabela-frete/) das [integrações de transportadora](/docs/log/conceitos/integracao-transportadora/) ativas da [filial](/docs/log/conceitos/filial/) e retorna as opções de envio disponíveis.
***
## Quando acontece [#quando-acontece]
A cotação pode ser realizada em diferentes momentos:
* **Via API** — para simular frete antes de criar o pedido. O endpoint [Quote orders V2](/docs/api/quotations/quote-orders-v2) permite cotar com ponto de coleta em uma loja e um ponto de entrega.
* **Na solicitação de coleta** — na página de [Pedidos](/docs/log/products/pedidos/), ao clicar em "Solicitar coleta". O sidepanel exibe as cotações, o operador escolhe uma opção e o [envio](/docs/log/conceitos/envio/) é criado. Veja [Solicitação de Coleta](/docs/log/acoes/solicitacao-coleta/).
* **Em algumas integrações de pedido** — integrações específicas (ex.: [VTEX](/docs/log/integrations/pedido/vtex)) podem disparar a cotação no fluxo de criação ou exibição de opções de frete.
* **Automaticamente** — quando uma [automação de envio](/docs/log/conceitos/regra-envio/) com ação **mais barato** ou **mais rápido** é acionada.
***
## Como funciona [#como-funciona]
1. O sistema identifica todas as integrações de transportadora **ativas** da filial.
2. Para cada integração, consulta a [tabela de frete](/docs/log/conceitos/tabela-frete/) vinculada — que pode ser do tipo **CEP** ou do tipo **raio**.
3. Se os dados de **latitude/longitude** e **distância dirigida** ainda não existirem (por exemplo, quando vêm da API), o sistema calcula novamente a partir do endereço.
4. Para cada **prazo** da tabela (ex.: D1, D3, EXP60):
* Verifica se o destino está **coberto** pela tabela.
* Calcula o **preço** com base na faixa de destino (CEP ou km) e na faixa de peso do pedido.
5. Calcula a **data de entrega esperada** para cada prazo, considerando:
* O número de dias ou minutos do prazo (D1 = 1 dia útil, EXP60 = 60 minutos)
* O [horário de corte](/docs/log/conceitos/tabela-frete/#horário-de-corte) da integração
6. Aplica as **regras de cotação** configuradas, que podem ajustar preço ou prazo.
7. Retorna todas as opções disponíveis com: transportadora, modalidade, prazo, preço e data de entrega esperada.
***
## Diferença entre tabela de CEP e tabela de raio na cotação [#diferença-entre-tabela-de-cep-e-tabela-de-raio-na-cotação]
| | Tabela de CEP | Tabela de Raio |
| ----------------------------- | ----------------------------------------------- | -------------------------------------------------------------- |
| **Dado usado** | CEP de destino do pedido | Distância entre origem e destino |
| **Como encontra o preço** | Busca em qual faixa de CEP o destino se encaixa | Calcula a distância (via geolocalização) e busca a faixa de km |
| **Faixas de preço** | Por faixa de peso, dentro de cada faixa de CEP | Por faixa de peso, dentro de cada faixa de km |
| **Dado adicional necessário** | Apenas o CEP de destino | Endereço completo (para calcular coordenadas e distância) |
***
## Como o prazo gera a data de entrega esperada [#como-o-prazo-gera-a-data-de-entrega-esperada]
O prazo da tabela de frete (ex.: D1, D3, EXP120) é transformado em uma **data de entrega esperada** no momento da cotação:
* **Prazos em dias úteis** (D0, D1, D3, D7...): o sistema conta os dias úteis a partir da data do pedido, considerando o horário de corte.
* **Prazos expressos** (EXP60, EXP120...): o sistema soma os minutos ao horário atual, respeitando a janela de operação.
***
## Regras de cotação [#regras-de-cotação]
Após o cálculo base (preço + prazo), o sistema pode aplicar **regras de cotação** que alteram o resultado:
* **Alterar o preço** — definir um preço fixo ou adicionar/subtrair do preço calculado.
* **Alterar a data de entrega** — definir uma data fixa ou adicionar tempo à data calculada.
* **Excluir opções** — remover prazos ou transportadoras específicas do resultado.
As regras de cotação são configuradas separadamente e permitem ajustar o resultado sem alterar a tabela de frete em si.
***
## O que a cotação retorna [#o-que-a-cotação-retorna]
Para cada opção disponível, a cotação retorna:
| Informação | Descrição |
| ---------------------------- | ---------------------------------------- |
| **Transportadora** | Nome da transportadora |
| **Modalidade** | Modalidade (ex.: CARRO, MOTO, PAC) |
| **Prazo** | Código do prazo (ex.: D1, D3, EXP60) |
| **Preço** | Valor do frete calculado |
| **Data de entrega esperada** | Data estimada de entrega ao destinatário |
***
## Links relacionados [#links-relacionados]
* [Cotação de Frete (ação)](/docs/log/acoes/cotacao-frete/) — onde e quando a cotação acontece
* [Solicitação de Coleta](/docs/log/acoes/solicitacao-coleta/) — fluxo no sidepanel de pedidos
* [Tabela de Frete](/docs/log/conceitos/tabela-frete/) — onde os preços e prazos são definidos
* [Quote orders V2](/docs/api/quotations/quote-orders-v2) — endpoint da API para cotação
* [Prazos de Entrega](/docs/log/conceitos/prazos/) — códigos de prazo e como interpretá-los
* [Integração de Transportadora](/docs/log/conceitos/integracao-transportadora/) — integrações consultadas na cotação
* [Automação de Envio](/docs/log/conceitos/regra-envio/) — automações que usam a cotação para escolher a melhor opção
---
# Emissão de Etiqueta (/docs/log/conceitos/emissao-etiqueta)
Após a confirmação do envio:
* A etiqueta é gerada automaticamente
* Inclui código de barras ou QR Code
* Segue padrão da transportadora
A Abbiamo centraliza e padroniza a geração.
---
# Envio (Delivery) (/docs/log/conceitos/envio)
**Envio** é a unidade de trabalho da transportadora: a "viagem" ou a execução logística de um [pedido](/docs/log/conceitos/pedido/) (ou parte dele). Um mesmo pedido pode ter vários envios ao longo do tempo (ex.: primeiro envio falhou, reenvio). No sistema aparece como **delivery**.
***
## O que compõe um envio [#o-que-compõe-um-envio]
### Identificação [#identificação]
| Campo | Descrição |
| ------------- | ------------------------------- |
| `id` | Identificador interno Abbiamo |
| `external_id` | ID na transportadora |
| `support_id` | ID de suporte na transportadora |
### Status [#status]
* `status` / `sub_status` — estado do envio (ex.: criado, em coleta, em rota, entregue, cancelado). A referência de códigos e traduções está em [Status de pedido](/docs/log/conceitos/status-de-pedido/).
### Transportadora [#transportadora]
O envio está sempre associado a uma [integração de transportadora](/docs/log/conceitos/integracao-transportadora/) que o atendeu.
### Modalidade e prazo [#modalidade-e-prazo]
O envio está sempre associado a uma **modalidade** e um **prazo**. A combinação identifica o tipo de serviço — por exemplo: `UBER/CARRO/EXP60`.
Para entender os códigos de prazo (EXP60, EXP120, D0, D1 etc.), veja [Prazos de Entrega](/docs/log/conceitos/prazos/).
### Motorista [#motorista]
* Nome, documento, telefone
* Veículo: tipo, cor, placa
* Imagem do motorista e do veículo
### Eventos [#eventos]
Lista de [eventos de entrega](/docs/log/conceitos/eventos-entrega/) — cada mudança de status ou ocorrência (ex.: saída para entrega, entrega realizada).
### Datas e valores [#datas-e-valores]
* Criação, ETA, data prevista de entrega
* **Expectativa de prazo e preço** — vêm da [tabela de frete](/docs/log/conceitos/tabela-frete/) no momento da [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) (ou da cotação, quando o envio é criado por automação). São o preço e a data de entrega esperada calculados com base na tabela.
* Valor previsto/auditado da transportadora
* Códigos de verificação (coleta, entrega, retorno)
### Criação [#criação]
* `manual_action` — indica se foi criado manualmente ou pelo sistema
* Usuário que solicitou envio/cancelamento, quando aplicável
***
## Relação com pedido e filial [#relação-com-pedido-e-filial]
| Relação | Descrição |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Envio → Pedido** | Todo envio pertence a um [pedido](/docs/log/conceitos/pedido/) |
| **Envio → Filial** | Indiretamente, via pedido — o envio "herda" a [filial](/docs/log/conceitos/filial/) do pedido |
| **Envio → Integração de transportadora** | O envio é criado/gerenciado por uma [integração de transportadora](/docs/log/conceitos/integracao-transportadora/) |
***
## Onde aparece [#onde-aparece]
* Na página de **Envios** do painel: lista de envios com filtros por filial, status, transportadora etc.
* No **sidepanel de um pedido**: ao abrir um pedido, os envios associados aparecem no painel lateral com seus eventos e status.
***
## Ciclo de vida de um envio [#ciclo-de-vida-de-um-envio]
---
# Eventos de Entrega (Delivery Events) (/docs/log/conceitos/eventos-entrega)
Os **eventos de entrega** (delivery events) são os registros de cada mudança de status ou ocorrência durante o ciclo de vida de um [envio](/docs/log/conceitos/envio/) — por exemplo: saída para entrega, tentativa de entrega, entrega realizada, falha, retorno.
Cada [envio](/docs/log/conceitos/envio/) possui sua própria lista de eventos, formando o histórico completo daquela tentativa de entrega. Para o significado dos códigos de status e sub\_status exibidos nos eventos, consulte [Status de pedido](/docs/log/conceitos/status-de-pedido/).
---
# Fatura (/docs/log/conceitos/fatura)
Uma **fatura** é o resultado do cálculo consolidado dos valores a pagar às transportadoras por todos os envios realizados em um determinado período. Ela representa o "fechamento" financeiro da operação logística.
***
## Relação com Envios e Auditoria [#relação-com-envios-e-auditoria]
O ciclo financeiro da operação envolve três etapas:
| Etapa | Onde | O que acontece |
| ------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **1. Despacho** | Tela de Pedidos | Pedido é despachado para a transportadora; preço cotado é registrado |
| **2. Auditoria** | [Tela de Envios](/docs/log/products/envios/) | Preço real cobrado pela transportadora é registrado via "Adicionar preço auditado" ou importação de planilha |
| **3. Faturamento** | [Tela de Faturas](/docs/log/products/faturas/) | Cálculo consolidado de todos os envios do período com os preços auditados |
***
## Como é gerada [#como-é-gerada]
A fatura não é criada automaticamente — ela é gerada **sob demanda**:
1. Selecione o **período** desejado na tela de Faturas.
2. Clique em **Gerar fatura**.
3. A plataforma consolida todos os envios do período e calcula o total.
***
## Onde aparece [#onde-aparece]
* [**Tela de Faturas**](/docs/log/products/faturas/) — geração e consulta de faturas por período.
* [**Tela de Envios**](/docs/log/products/envios/) — registro de preços auditados que alimentam o cálculo da fatura.
* [**Relatórios**](/docs/log/products/relatorios/) — exportação de envios com valores para análise externa.
---
# Filial (Seller) (/docs/log/conceitos/filial)
**Filial** é a unidade de negócio do embarcador: cada loja, restaurante ou ponto que emite pedidos e usa o sistema. No código e na API aparece como **seller**.
***
## O que compõe uma filial [#o-que-compõe-uma-filial]
### Identificação [#identificação]
| Campo | Descrição |
| -------------- | --------------------------------- |
| `id` | Identificador interno |
| `identifier` | Identificador externo/customizado |
| `trading_name` | Nome fantasia |
| `company_name` | Razão social |
### Documento [#documento]
* `document_type` / `document_number` — tipo e número do documento (CNPJ, CPF etc.)
* `state_registration` — inscrição estadual
### Contato e endereço [#contato-e-endereço]
* `email` / `phone`
* `address` — dados completos do endereço da filial
### Configuração [#configuração]
* `timezone` — fuso horário da filial
* `country` — país
* `active` — se está ativa
* `operation_hours` — horários de funcionamento
### Conta (Seller Group) [#conta-seller-group]
* `seller_group_id` — a [conta](/docs/log/conceitos/seller-group/) à qual a filial pertence. Toda filial está vinculada a uma única conta
### White label [#white-label]
* Aparência/identidade (logo, cores) quando o painel é white label
***
## Onde a filial aparece [#onde-a-filial-aparece]
| Contexto | Relação |
| -------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Pedido** | Todo [pedido](/docs/log/conceitos/pedido/) pertence a uma filial (`order.seller`) |
| **Envio** | Todo [envio](/docs/log/conceitos/envio/) está ligado a um pedido e, portanto, à filial desse pedido |
| **Integração de transportadora** | Configurada por filial (`seller_id`) — [saiba mais](/docs/log/conceitos/integracao-transportadora/) |
| **Integração de pedido** | Configurada por filial (`seller_id`) — [saiba mais](/docs/log/conceitos/integracao-pedido/) |
| **Relatórios** | É comum selecionar quais filiais entram no escopo (ex.: relatório de pedidos por filial) |
---
# Forma de Pagamento do Frete (/docs/log/conceitos/forma-pagamento-frete)
O frete pode ser:
* **CIF** — remetente paga
* **FOB** — destinatário paga
* Faturado
* Pré-pago
---
# Conceitos (/docs/log/conceitos)
---
# Integração de Pedido (Order Integration) (/docs/log/conceitos/integracao-pedido)
**Integração de pedido** é a configuração que liga uma [filial](/docs/log/conceitos/filial/) a um **provedor externo de pedidos** (marketplace, ERP, e-commerce) para receber pedidos automaticamente. No código e na API aparece como **OrderIntegration**.
***
## O que compõe uma integração de pedido [#o-que-compõe-uma-integração-de-pedido]
| Campo | Descrição |
| --------------------------- | ---------------------------------------------------------------------- |
| `id` | Identificador interno |
| `type` | Tipo do provedor (ex.: VTEX, INTELIPOST, LINX, OMNIK, LINX\_ECOMMERCE) |
| `seller_id` / `seller` | De qual [filial](/docs/log/conceitos/filial/) vêm os pedidos |
| `active` | Se está ativa ou não |
| `data` | Credenciais e metadados (tokens, URLs etc.) para a API do provedor |
| `external_identification` | Identificador próprio do provedor, quando aplicável |
| `created_at` / `updated_at` | Datas de criação e última atualização |
Cada tipo de provedor tem um schema de dados (`order_integration_data_schema`) que define quais campos configurar.
***
## Para que serve [#para-que-serve]
* **Receber pedidos** automaticamente do provedor (VTEX, Intelipost etc.) e criar os [pedidos](/docs/log/conceitos/pedido/) no sistema Abbiamo
* **Atualizar o provedor** quando o pedido muda de status na Abbiamo (ex.: com solicitação de coleta feita, em rota, entregue) — quando a integração suporta
* Eliminar operação manual de cadastro de pedidos
* Reduzir erros de digitação e atrasos
* Escalar facilmente a operação
***
## Fluxo [#fluxo]
1. O provedor externo gera um pedido (ex.: cliente faz uma compra na VTEX)
2. A integração de pedido **recebe** esse pedido via API/webhook
3. O sistema **cria o pedido** na Abbiamo, vinculado à filial correspondente
4. O pedido segue para [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) — manualmente ou via [automação de envio](/docs/log/conceitos/regra-envio/)
5. Quando o pedido é atualizado na Abbiamo (com solicitação de coleta feita, em rota, entregue), a integração **atualiza o provedor** de volta, quando possível
***
## Integrações disponíveis [#integrações-disponíveis]
| Provedor | Documentação |
| ----------- | -------------------------------------------------- |
| **VTEX** | [Ver guia](/docs/log/integrations/pedido/vtex/) |
| **Neomode** | [Ver guia](/docs/log/integrations/pedido/neomode/) |
***
## Onde aparece [#onde-aparece]
* Cada **filial** pode ter uma ou mais integrações de pedido configuradas
* Relatórios de **Integrações de Pedidos** exportam essas configurações por filial
---
# Integração de Transportadora (Carrier Integration) (/docs/log/conceitos/integracao-transportadora)
**Integração de transportadora** é a configuração que liga uma [filial](/docs/log/conceitos/filial/) a uma [transportadora](/docs/log/conceitos/transportadora/) em uma [modalidade](/docs/log/conceitos/modalidade/) específica para criar e gerenciar [envios](/docs/log/conceitos/envio/). No código e na API aparece como **CarrierIntegration**.
***
## O que compõe uma integração de transportadora [#o-que-compõe-uma-integração-de-transportadora]
### Identificação e vínculo [#identificação-e-vínculo]
| Campo | Descrição |
| ---------------------- | ----------------------------------------------------------------------------------- |
| `id` | Identificador interno |
| `type` | Nome/tipo da transportadora |
| `seller_id` / `seller` | Para qual [filial](/docs/log/conceitos/filial/) essa integração vale |
| `active` | Se está ativa ou não |
| `operation_type` | Entrega (DELIVERY) ou Reversa (RETURN) |
| `carrier_method_group` | [Modalidade](/docs/log/conceitos/modalidade/) (ex.: CARRO, MOTO, CONVENCIONAL, PAC) |
### Credenciais e configuração operacional [#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 [#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](/docs/log/conceitos/tabela-frete/#horário-de-corte)
* **Tabela de frete** — cada integração pode ter uma [tabela de frete](/docs/log/conceitos/tabela-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](/docs/log/conceitos/tabela-frete/#cobertura-restrita)
* GRIS, ad valorem, fator de cubagem, isenção de cubagem
***
## Para que serve [#para-que-serve]
* Definir **quais transportadoras** (e modalidades) cada filial pode usar
* Ao fazer a [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) de um [pedido](/docs/log/conceitos/pedido/), o sistema usa a integração para criar o [envio](/docs/log/conceitos/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 [#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
***
## Tabela de frete e contrato [#tabela-de-frete-e-contrato]
A [tabela de frete](/docs/log/conceitos/tabela-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.
---
# Login Unificado (/docs/log/conceitos/login)
O **Login Unificado** é a porta de entrada do painel Abbiamo em [**portal.abbiamolog.com**](https://portal.abbiamolog.com). Em vez de manter um cadastro por operação, cada pessoa tem **um único email e senha**, e escolhe no portal qual operação quer abrir.
***
## Como acessar o portal [#como-acessar-o-portal]
1. Acesse [**portal.abbiamolog.com**](https://portal.abbiamolog.com).
2. Informe seu **email** e **senha**.
3. Se você tem acesso a mais de uma operação (LOG, GO, ou ambiente de homologação), o portal mostra um card para cada uma — escolha em qual quer entrar.
4. Se você tem acesso a apenas uma operação, o portal te leva direto para o dashboard correspondente.
Ambientes de homologação aparecem marcados de forma clara ao lado dos de produção, para não gerar confusão.
***
## Redefinir senha [#redefinir-senha]
1. Na tela de login, clique em **Esqueci minha senha**.
2. Informe o email da sua conta.
3. Você recebe um email com um código para definir uma nova senha.
4. Informe o código e a nova senha na tela de redefinição.
No primeiro acesso via convite, o email traz uma **senha temporária** pronta para uso — não um link de definição de senha. Faça login normalmente pelo portal com essa senha; em seguida, o portal pede que você defina sua senha definitiva antes de continuar.
***
## Trocar de operação sem sair [#trocar-de-operação-sem-sair]
Se sua conta tem acesso a **LOG e GO**, o dashboard mostra um **switcher no menu lateral** com a operação ativa em destaque. Basta clicar e escolher a outra operação — o dashboard recarrega já no novo contexto, sem precisar refazer login.
Cada operação tem seus próprios dados: trocar de contexto não mistura informações de uma operação com a outra.
***
## Sair da conta [#sair-da-conta]
Clique em **Sair** no menu do painel para encerrar sua sessão. Isso desconecta você de todas as operações abertas com aquele login — para entrar em outra operação depois, basta fazer login novamente pelo portal.
***
## Gerenciar quem tem acesso [#gerenciar-quem-tem-acesso]
Quem administra a conta convida pessoas pelo email real (sem precisar de sufixos) e define o tipo de acesso — **Proprietário** ou **Administrador** — e as filiais que cada pessoa pode ver.
→ Veja [Usuário](/docs/log/conceitos/usuario/) para os tipos de acesso e [Configurações › Usuários](/docs/log/settings/usuarios/) para o passo a passo de convite e edição.
***
## E os logins antigos? [#e-os-logins-antigos]
Emails com sufixo `+log`, `+go` ou `+hml` continuam funcionando normalmente. Não é obrigatório migrar agora — a recomendação é passar a usar o email único pelo portal quando for conveniente, já que é por onde chegam as melhorias futuras. Os logins antigos serão desativados no futuro, mas com aviso e prazo comunicados antes — sem corte de surpresa.
***
## Como se relaciona com as outras entidades [#como-se-relaciona-com-as-outras-entidades]
| Entidade | Relação com o login |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **[Conta (Seller Group)](/docs/log/conceitos/seller-group/)** | Cada pessoa pode ter acesso a uma ou mais contas/operações com o mesmo login |
| **[Usuário](/docs/log/conceitos/usuario/)** | O login dá acesso a um usuário por operação, com sua própria role e filiais |
| **[Filial](/docs/log/conceitos/filial/)** | Definida por usuário, dentro de cada operação escolhida no login |
---
# Logística Reversa (/docs/log/conceitos/logistica-reversa)
Fluxo de devolução de mercadorias.
Inclui:
* Geração de etiqueta reversa
* Coleta no cliente final
* Retorno ao CD
---
# Marcador (/docs/log/conceitos/marcador)
Um **marcador** é uma tag colorida que você cria para categorizar pedidos. Marcadores facilitam filtros, organização da operação e são usados como condição em automações.
***
## Campos de um marcador [#campos-de-um-marcador]
| Campo | Obrigatório | Descrição |
| ------------- | ----------- | ------------------------------------------------------------------ |
| **Nome** | ✓ | Ex.: "Frágil", "Prioridade Alta", "Zona Leste" |
| **Descrição** | | Texto explicativo para a equipe |
| **Cor** | ✓ | Valor hexadecimal (ex.: `#EF4444`) — exibido como bolinha colorida |
***
## Como marcadores são aplicados a pedidos [#como-marcadores-são-aplicados-a-pedidos]
Existem três formas:
1. **Manualmente** — na tela de Pedidos, selecione um ou mais pedidos e use a ação em lote "Aplicar marcador".
2. **Por automação** — via [Automação de Marcadores](/docs/log/products/automacoes-de-marcadores/), que aplica o marcador automaticamente quando as condições configuradas são atendidas.
***
## Como marcadores são usados [#como-marcadores-são-usados]
### Em filtros [#em-filtros]
Na tela de **Pedidos**, **Envios** e outras, o campo **Marcadores** filtra registros que possuem a tag selecionada.
### Em condições de automações [#em-condições-de-automações]
[Automações de Envio](/docs/log/conceitos/regra-envio/) e [Automações de Marcadores](/docs/log/products/automacoes-de-marcadores/) podem usar marcadores como condição de avaliação — ex.: "se o pedido tiver o marcador X, aplique a regra Y".
### Em relatórios [#em-relatórios]
Relatórios do tipo **PEDIDOS** e **ENVIOS** incluem a coluna de marcadores para segmentação e análise.
***
## Propagação [#propagação]
Quando um marcador é aplicado a um pedido, ele aparece associado ao pedido em todas as telas que exibem aquele registro — incluindo a tela de Envios e o painel lateral do pedido.
***
## Onde aparece [#onde-aparece]
* [**Configurações > Marcadores**](/docs/log/settings/marcadores/) — criação e gestão de marcadores.
* [**Tela de Pedidos**](/docs/log/products/pedidos/) — filtro e aplicação em lote.
* [**Tela de Envios**](/docs/log/products/envios/) — coluna e filtro de marcadores.
* [**Automações de Marcadores**](/docs/log/products/automacoes-de-marcadores/) — aplicação automática com base em condições.
---
# Modalidade (/docs/log/conceitos/modalidade)
A **modalidade** é o tipo de serviço ou veículo que a [transportadora](/docs/log/conceitos/transportadora/) oferece. Uma mesma transportadora pode ter várias modalidades — por exemplo, Uber tem **CARRO** e **MOTO**; Correios tem **PAC**, **SEDEX** e **CONVENCIONAL**.
No código e na API aparece como `carrier_method_group`.
***
## Exemplos de modalidades [#exemplos-de-modalidades]
| Modalidade | Descrição típica |
| ---------------- | ---------------------------------------------- |
| **CARRO** | Entrega em veículo de quatro rodas |
| **MOTO** | Entrega em moto (mais ágil em centros urbanos) |
| **BICICLETA** | Entrega em bicicleta |
| **PAC** | Serviço econômico dos Correios |
| **SEDEX** | Serviço expresso dos Correios |
| **CONVENCIONAL** | Entrega rodoviária padrão |
| **EXPRESSO** | Entrega rápida |
***
## Como a modalidade aparece no sistema [#como-a-modalidade-aparece-no-sistema]
A modalidade faz parte da [integração de transportadora](/docs/log/conceitos/integracao-transportadora/): cada integração é **uma transportadora em uma modalidade** para uma [filial](/docs/log/conceitos/filial/). A [tabela de frete](/docs/log/conceitos/tabela-frete/) vinculada à integração pertence a essa modalidade.
***
## Composição: transportadora / modalidade / prazo [#composição-transportadora--modalidade--prazo]
A identificação completa de um serviço de envio é:
**Transportadora** + **Modalidade** + **Prazo**
Exemplos: `UBER/CARRO/EXP60`, `CORREIOS/PAC/D3`, `LOGGI/MOTO/EXP120`.
***
## Links relacionados [#links-relacionados]
* [Transportadora](/docs/log/conceitos/transportadora/) — empresa que realiza a entrega
* [Prazos de Entrega](/docs/log/conceitos/prazos/) — códigos de prazo (D1, EXP60, etc.)
* [Integração de Transportadora](/docs/log/conceitos/integracao-transportadora/) — onde a modalidade é configurada
* [Tabela de Frete](/docs/log/conceitos/tabela-frete/) — preços por modalidade e prazo
---
# Orquestração Logística (/docs/log/conceitos/orquestracao-logistica)
A Abbiamo atua como um **orquestrador logístico**.
Ela conecta:
* Seu sistema
* Transportadoras
* Tabelas de frete
* Regras de decisão
* Monitoramento de SLA
Tudo de forma integrada e automatizada.
---
# Pedido (Order / Invoice) (/docs/log/conceitos/pedido)
**Pedido** é a entidade central que representa uma solicitação de entrega (ou coleta/retorno) vinculada a um cliente e a uma [filial](/docs/log/conceitos/filial/). No sistema, a mesma entidade é chamada de **order** na API e, em parte do contexto de negócio, de **invoice** quando se fala da nota fiscal ou do documento do pedido.
***
## O que compõe um pedido [#o-que-compõe-um-pedido]
### Identificação [#identificação]
* `id` — identificador interno Abbiamo
* `number` — número do pedido
* `external_id` — ID do embarcador
* `tracking` — código de rastreio
### Nota fiscal / Invoice [#nota-fiscal--invoice]
* `invoice_number` — número da NF
* `access_keys` — chave de acesso da NF
* `content_declaration` — dados da DC-e quando o pedido foi criado com declaração de conteúdo informada pelo embarcador (`key`, `serie`, `number`)
* Dados de emissão
### Valores [#valores]
* `amount` — valor total do pedido
* **Preço e prazo prometido ao cliente** — valor do frete e data de entrega que foram prometidos ao cliente final (ex.: no checkout ou na criação do pedido). Podem vir da [cotação de frete](/docs/log/conceitos/cotacao-frete/) ou da [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/).
### Status [#status]
* `status` / `sub_status` — refletem o estado atual do pedido (ex.: criado, com solicitação de coleta feita, em rota, entregue). Para a lista completa de códigos e traduções, veja [Status de pedido](/docs/log/conceitos/status-de-pedido/).
### Tipo [#tipo]
* `type` — Entrega (DELIVERY), Retirada em loja (TAKEOUT) ou Reversa (RETURN)
### Relacionamentos [#relacionamentos]
| Relação | Descrição |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Filial** (`seller`) | A qual [filial](/docs/log/conceitos/filial/) o pedido pertence |
| **Cliente** (`customer`) | Destinatário e dados de contato |
| **Endereços** | Origem (`source_address`, endereço da [filial](/docs/log/conceitos/filial/) associada) e destino (`destination_address`) |
| **Volumes e itens** | `volumes` e itens associados |
| **Envios** (`deliveries`) | Um pedido pode ter um ou mais [envios](/docs/log/conceitos/envio/) (ex.: reenvio) |
### Janela de entrega e tempo de serviço [#janela-de-entrega-e-tempo-de-serviço]
Existem duas formas de informar uma janela de entrega, que não se combinam entre si — use uma ou outra conforme o caso:
| Campo | Tipo | Descrição |
| ---------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `delivery_window_start` | string (ISO 8601) | Início da janela de entrega — **data e hora completas**, para um dia específico |
| `delivery_window_end` | string (ISO 8601) | Fim da janela de entrega — data e hora completas |
| `delivery_start_window_hour` | string (`HH:mm`) | Início da janela de entrega — **apenas o horário**, sem data associada (ex.: sempre entre 9h e 12h, em qualquer dia) |
| `delivery_end_window_hour` | string (`HH:mm`) | Fim da janela de entrega — apenas o horário. Precisa ser depois de `delivery_start_window_hour` |
| `delivery_service_time` | integer (minutos) | Tempo de permanência estimado no destino durante a entrega |
Todos os campos são opcionais e independentes entre si. Quando presentes, podem ser usados por [automações de envio](/docs/log/conceitos/regra-envio/) para agendar a [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) próxima ao início da janela — evitando que o pedido seja coletado e despachado muito antes da janela abrir.
### Tipo de moradia do destinatário [#tipo-de-moradia-do-destinatário]
| Campo | Tipo | Descrição |
| ---------------- | -------------------------------------- | ------------------------------------------------------ |
| `residence_type` | string (`commercial` ou `residential`) | Tipo do endereço de entrega — comercial ou residencial |
Campo opcional. Não afeta cotação, seleção de transportadora ou despacho — é armazenado no pedido e repassado a integrações e transportadoras que usam essa informação a jusante (ex.: para orientar o entregador sobre o tipo de local).
### Outros dados [#outros-dados]
* **Entrega:** dados da última entrega — transportadora, motorista, data de entrega, janela de entrega etc.
* **Marcadores:** `invoice_tags` — tags/labels associadas ao pedido
* **Datas:** criação, atualização de status, data prevista de entrega, data de processamento pelo embarcador
***
## Como um pedido é criado [#como-um-pedido-é-criado]
* **Pelo dashboard** — formulário, upload de CSV ou XLSX na página de [Pedidos](/docs/log/products/pedidos/). Veja [Criação de Pedido](/docs/log/acoes/criacao-pedido/).
* **Via API pública** — endpoint [Create order V2](/docs/api/orders/create-order-v2)
* **Via integração de pedido** — [VTEX](/docs/log/integrations/pedido/vtex) e outras integrações conectadas
Após a criação, a [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) é feita para uma [integração de transportadora](/docs/log/conceitos/integracao-transportadora/) — manualmente pelo operador ou via [automação de envio](/docs/log/conceitos/regra-envio/) —, que gera um ou mais [envios](/docs/log/conceitos/envio/).
***
## Pedido vs. Invoice [#pedido-vs-invoice]
---
# Peso Real, Cubagem e Peso Taxado (/docs/log/conceitos/peso-cubagem-taxado)
Transportadoras consideram:
| Termo | Significado |
| --------------- | ------------------------- |
| **Peso real** | Peso físico do pacote |
| **Peso cubado** | Volume convertido em peso |
| **Peso taxado** | Maior entre real e cubado |
---
# Prazos de Entrega (/docs/log/conceitos/prazos)
O **prazo de entrega** é o código que indica em quanto tempo um [envio](/docs/log/conceitos/envio/) deve ser concluído. Ele vem da [tabela de frete](/docs/log/conceitos/tabela-frete/) (por CEP ou por raio) e é associado ao envio no momento da sua criação. A identificação completa do serviço é **transportadora** + **modalidade** + **prazo** — veja [Transportadora](/docs/log/conceitos/transportadora/) e [Modalidade](/docs/log/conceitos/modalidade/).
***
## Códigos de prazo [#códigos-de-prazo]
### Prazos expressos (em minutos) [#prazos-expressos-em-minutos]
Usados para entregas rápidas (same-day, last-mile):
| Código | Significado |
| ---------- | ---------------------------------------- |
| **EXP60** | Entrega em até **60 minutos** |
| **EXP120** | Entrega em até **120 minutos** (2 horas) |
| **EXP180** | Entrega em até **180 minutos** (3 horas) |
### Prazos em dias úteis [#prazos-em-dias-úteis]
Usados para entregas convencionais/rodoviárias:
| Código | Significado |
| ------- | -------------------------------------- |
| **D0** | Entrega no **mesmo dia** (same-day) |
| **D1** | Entrega no **dia seguinte** (next-day) |
| **D2** | Entrega em até **2 dias úteis** |
| **D3** | Entrega em até **3 dias úteis** |
| **D+N** | Entrega em até **N dias úteis** |
***
## Como aparece no sistema [#como-aparece-no-sistema]
O prazo faz parte da identificação do serviço de entrega. Por exemplo:
| Exemplo | Transportadora | Modalidade | Prazo |
| ------------------- | -------------- | ---------- | ------------ |
| `UBER/CARRO/EXP60` | Uber | Carro | 60 minutos |
| `LOGGI/MOTO/EXP120` | Loggi | Moto | 120 minutos |
| `CORREIOS/PAC/D3` | Correios | PAC | 3 dias úteis |
***
## Onde o prazo aparece [#onde-o-prazo-aparece]
* No [envio](/docs/log/conceitos/envio/): cada envio tem a modalidade e prazo associados
* Na [tabela de frete](/docs/log/conceitos/tabela-frete/): o prazo é definido por faixa de CEP ou raio e vinculado a uma modalidade
* Na cotação de frete: o prazo é um dos critérios para escolha da transportadora
---
# Automação de Envio (/docs/log/conceitos/regra-envio)
Uma automação de envio define **como e quando** a [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) será feita automaticamente para uma transportadora, com base em condições que você configura.
***
## O que é uma automação de envio [#o-que-é-uma-automação-de-envio]
Uma automação de envio:
1. **Avalia condições** — Ex.: CEP, cidade, valor do pedido, tipo de entrega, peso, etc.
2. **Define a ação** — Qual ação usar: prazo específico (transportadora + modalidade + prazo), mais barato ou mais rápido.
3. **Controla o momento da solicitação de coleta** — Imediato, próximo horário de operação, agendamento customizado, etc.
Quando um pedido é criado e fica pronto para envio, o sistema percorre as automações da filial em **ordem de sequência** até encontrar a primeira cujas condições são atendidas. A automação então dispara o envio para a transportadora escolhida.
***
## Quando a automação é acionada [#quando-a-automação-é-acionada]
A automação pode ser configurada para ser avaliada em diferentes momentos:
* **A qualquer momento** — Sem restrição de horário.
* **Durante horário de operação** — Somente quando a filial está em horário de operação.
* **Fora do horário de operação** — Somente fora do horário.
* **Dias e horários customizados** — Definir dias da semana e horários específicos (ex.: SEG 08:00–18:00).
***
## Quando a solicitação de coleta é feita [#quando-a-solicitação-de-coleta-é-feita]
Depois que a automação é acionada, você pode definir quando o envio será efetivamente feito:
* **Despachar imediatamente** — Assim que a automação for acionada.
* **Próximo horário de operação disponível** — Aguardar o próximo slot ou próximo dia útil.
* **Agendar para a próxima abertura da loja** — Sempre agendar para o próximo dia de operação.
* **Agendamento customizado** — Definir dias e horários específicos.
* **Agendar para início da janela de entrega** — Usar a janela de entrega definida no pedido (quando habilitado).
É possível adicionar um **delay** em minutos para aguardar ou adiantar a solicitação de coleta em relação ao horário base.
***
## Tipos de ação [#tipos-de-ação]
| Ação | Descrição |
| -------------------------------- | -------------------------------------------------------------------- |
| **Enviar para prazo específico** | Escolher transportadora, modalidade e prazo (ex.: UBER/CARRO/EXP60). |
| **Enviar para mais barato** | O sistema cotará e escolherá automaticamente a opção mais barata. |
| **Enviar para mais rápido** | O sistema cotará e escolherá automaticamente a opção mais rápida. |
***
## Condições disponíveis [#condições-disponíveis]
As condições podem usar campos do pedido e do endereço, como:
* **Endereço:** CEP, bairro, cidade, estado
* **Valores e datas:** Valor total, data de criação, data da NF
* **Distância:** Distância de entrega
* **Origem:** De onde o pedido veio (integração, formulário, etc.)
* **Dimensões:** Peso, cubagem, comprimento, largura, altura
* **Outros:** Tipo de entrega, tipo de operação (entrega/reversa), marcadores
Você pode criar automações **sem condições** — nesse caso, todos os pedidos da filial serão automatizados por aquela automação (útil como automação padrão no final da sequência).
***
## Dependência com a tabela de frete [#dependência-com-a-tabela-de-frete]
A automação de envio depende da [tabela de frete](/docs/log/conceitos/tabela-frete/) da [integração de transportadora](/docs/log/conceitos/integracao-transportadora/) de formas diferentes, conforme o tipo de ação:
* **Prazo específico:** a automação aponta para uma integração + prazo (ex.: Correios/PAC/D3). O prazo **precisa existir** na tabela de frete da integração. Se alguém editar a tabela e remover esse prazo, o envio vai falhar com erro de "prazo não encontrado".
* **Mais barato / mais rápido:** o sistema realiza uma [cotação](/docs/log/conceitos/cotacao-frete/) usando as tabelas de frete de todas as integrações ativas. A automação **se adapta automaticamente** a mudanças na tabela — se um prazo for removido ou adicionado, a cotação reflete isso.
***
## Relação com outras telas [#relação-com-outras-telas]
As automações de envio são configuradas na tela **Automações de Envio**. Elas também podem ser referenciadas em:
* **Tabela de CEP** — Automações associadas a faixas de CEP.
* **Tabela de Raio** — Automações associadas a áreas por raio.
Ao editar uma tabela de frete, é possível visualizar e atualizar as automações vinculadas às integrações daquela tabela.
O resultado da solicitação de coleta aparece na [Tela de Pedidos](/docs/log/products/pedidos/), onde o status do pedido é atualizado.
***
## Links relacionados [#links-relacionados]
* [Tela de Automações de Envio](/docs/log/products/regras-de-envio/) — onde criar e gerenciar as automações.
* [Tela de Pedidos](/docs/log/products/pedidos/) — onde o pedido é exibido e o resultado da solicitação de coleta é refletido.
* [Integração de Transportadora](/docs/log/conceitos/integracao-transportadora/) — conceito das integrações que recebem os envios.
* [Tabela de Frete](/docs/log/conceitos/tabela-frete/) — tabelas de preços e prazos vinculadas às integrações.
* [Cotação de Frete](/docs/log/conceitos/cotacao-frete/) — como o sistema calcula preço e prazo.
* [Automação de Reenvio](/docs/log/conceitos/regra-reenvio/) — fallback quando o envio falha.
* [Automação de Inatividade](/docs/log/conceitos/regra-inatividade/) — ação quando o envio fica sem atualização.
---
# Automação de Inatividade (/docs/log/conceitos/regra-inatividade)
A **Automação de Inatividade** define o que acontece automaticamente quando um [envio](/docs/log/conceitos/envio/) fica sem atualização de status por um período prolongado — por exemplo, cancelar o envio parado e reenviar com outra transportadora.
***
## O que é [#o-que-é]
Quando um envio é criado mas a transportadora não atualiza o status por muito tempo (não coleta, não movimenta, não entrega), isso pode indicar um problema. A automação de inatividade permite que o sistema tome uma ação automática depois de um tempo configurado, sem precisar de intervenção manual.
***
## Quando é acionada [#quando-é-acionada]
A automação de inatividade é avaliada periodicamente pelo sistema. Ela é acionada quando um envio atende a **todas** as condições:
1. O envio está em um dos **status monitorados** configurados na automação.
2. O tempo desde a última atualização de status ultrapassou o **tempo de tolerância** definido.
***
## Tempo de tolerância [#tempo-de-tolerância]
O tempo de tolerância define **quantos segundos** o envio pode ficar sem atualização antes de a automação ser acionada. Esse valor é configurado em cada automação.
***
## Como funciona [#como-funciona]
1. O sistema verifica periodicamente os envios em status monitorados.
2. Para cada envio que ultrapassou o tempo de tolerância, o sistema avalia as automações de inatividade da filial em **ordem de sequência**.
3. A primeira automação cujas condições forem atendidas é executada.
4. O envio atual é **cancelado**.
5. Um **novo envio** é criado com a ação definida na automação.
***
## Tipos de ação [#tipos-de-ação]
| Ação | Descrição |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| **Prazo específico** | Cancela o envio parado e reenvia para uma integração e prazo definidos. |
| **Mais barato** | Cancela e realiza uma [cotação](/docs/log/conceitos/cotacao-frete/) para escolher a opção mais barata. |
| **Mais rápido** | Cancela e realiza uma cotação para escolher a opção mais rápida. |
***
## Filtro por modalidade [#filtro-por-modalidade]
A automação de inatividade pode ser configurada para monitorar envios de uma **modalidade** específica (ex.: apenas envios de MOTO, ou apenas envios CONVENCIONAL). Isso permite ter regras de inatividade diferentes para cada tipo de envio.
***
## Relação com a tabela de frete [#relação-com-a-tabela-de-frete]
Assim como nas [automações de envio](/docs/log/conceitos/regra-envio/) e [reenvio](/docs/log/conceitos/regra-reenvio/):
* **Prazo específico**: o prazo referenciado precisa existir na [tabela de frete](/docs/log/conceitos/tabela-frete/) da integração. Se o prazo foi removido, o novo envio vai falhar.
* **Mais barato / mais rápido**: o sistema consulta as tabelas de frete via cotação e se adapta automaticamente a mudanças na tabela.
***
## Links relacionados [#links-relacionados]
* [Automação de Envio](/docs/log/conceitos/regra-envio/) — automação do envio original
* [Automação de Reenvio](/docs/log/conceitos/regra-reenvio/) — ação quando o envio falha
* [Tabela de Frete](/docs/log/conceitos/tabela-frete/) — tabelas consultadas na cotação
* [Integração de Transportadora](/docs/log/conceitos/integracao-transportadora/) — integrações disponíveis para reenvio
---
# Automação de Reenvio (/docs/log/conceitos/regra-reenvio)
A **Automação de Reenvio** define o que acontece automaticamente quando um [envio](/docs/log/conceitos/envio/) falha — por exemplo, tentar novamente com a mesma transportadora ou redirecionar para outra.
***
## O que é [#o-que-é]
Uma automação de reenvio funciona como um plano B (e C, D...) para quando o envio original não deu certo. Em vez de o operador precisar intervir manualmente a cada falha, o sistema tenta automaticamente reenviar o pedido seguindo as regras configuradas.
***
## Quando é acionada [#quando-é-acionada]
A automação de reenvio é avaliada quando um envio muda para o status **falho** ou **cancelado**. Você pode configurar **quais status de falha** disparam o reenvio — por exemplo:
* Erro da transportadora (timeout, rejeição, instabilidade)
* Cancelamento do envio
* Outros motivos de falha
Se o status da falha corresponde ao que está configurado na automação, ela é acionada.
***
## Como funciona [#como-funciona]
1. O envio falha com um dos status configurados na automação.
2. O sistema percorre as automações de reenvio da filial em **ordem de sequência**.
3. Para cada automação, verifica se as **condições** são atendidas (se houver).
4. A primeira automação cujas condições forem atendidas é executada.
5. O sistema cria um **novo envio** com a ação definida na automação.
***
## Tipos de ação [#tipos-de-ação]
| Ação | Descrição |
| -------------------- | ---------------------------------------------------------------------------------------- |
| **Prazo específico** | Envia para uma integração e prazo definidos (ex.: Loggi/MOTO/EXP120). |
| **Mais barato** | Realiza uma [cotação](/docs/log/conceitos/cotacao-frete/) e escolhe a opção mais barata. |
| **Mais rápido** | Realiza uma cotação e escolhe a opção mais rápida. |
| **Último prazo** | Tenta novamente com a mesma transportadora e prazo do envio que falhou. |
***
## Condições [#condições]
Assim como as [automações de envio](/docs/log/conceitos/regra-envio/), as automações de reenvio podem ter **condições** que filtram quando devem ser aplicadas — como CEP, cidade, peso, valor do pedido, entre outros.
Se nenhuma condição for definida, a automação vale para todos os pedidos da filial.
***
## Encadeamento (cascata) [#encadeamento-cascata]
Uma automação de reenvio pode ser **encadeada**: se o reenvio também falhar, o sistema pode acionar **outra automação de reenvio** vinculada à primeira — criando uma cascata de tentativas.
Por exemplo:
1. Envio original com Uber falha → reenvio para Loggi (automação 1)
2. Loggi também falha → reenvio para Correios (automação 2, encadeada à automação 1)
Isso permite criar planos de contingência com múltiplos níveis.
***
## Relação com a tabela de frete [#relação-com-a-tabela-de-frete]
As automações de reenvio se relacionam com a [tabela de frete](/docs/log/conceitos/tabela-frete/) da mesma forma que as automações de envio:
* **Prazo específico** e **último prazo**: o prazo referenciado precisa existir na tabela de frete da integração. Se o prazo foi removido da tabela, o reenvio vai falhar.
* **Mais barato / mais rápido**: o sistema consulta as tabelas de frete via cotação e se adapta automaticamente.
***
## Links relacionados [#links-relacionados]
* [Automação de Envio](/docs/log/conceitos/regra-envio/) — automação do envio original
* [Automação de Inatividade](/docs/log/conceitos/regra-inatividade/) — ação quando o envio fica sem atualização
* [Tabela de Frete](/docs/log/conceitos/tabela-frete/) — tabelas consultadas na cotação
* [Integração de Transportadora](/docs/log/conceitos/integracao-transportadora/) — integrações disponíveis para reenvio
---
# Regras de Orquestração (/docs/log/conceitos/regras-orquestracao)
A orquestração define qual transportadora ou modalidade será utilizada.
## Exemplos de regras [#exemplos-de-regras]
* Se peso > 30kg → usar Transportadora X
* Se destino interior → priorizar Transportadora Y
* Se urgente → usar modalidade Expresso
* Se transportadora falhar → aplicar fallback
---
# Rota (/docs/log/conceitos/rota)
Uma **rota** é um agrupamento de pedidos organizados em uma sequência de paradas otimizada para entrega. A Abbiamo calcula o trajeto ideal (via Mapbox) e permite acompanhar a execução em tempo real.
***
## Tipos de rota [#tipos-de-rota]
| Tipo | Valor interno | Quem executa |
| ------------------------ | --------------- | --------------------------------------------------------------------------------- |
| **Frota Própria** | `PRIVATE_FLEET` | Motorista cadastrado na plataforma — veículo e motorista são da empresa |
| **Transportadora (TRP)** | `CARRIER` | Transportadora externa — a rota é convertida em uma solicitação de coleta em lote |
***
## Status de rota [#status-de-rota]
| Status | Significado |
| ------------------------ | --------------------------------------------------- |
| `CREATED` | Rota criada, ainda não iniciada |
| `START_DELIVERY` | Entregas em andamento |
| `CANCELED` | Rota cancelada manualmente |
| `ALL_WAYPOINTS_FINISHED` | Todas as paradas concluídas, aguardando finalização |
| `FINISHED` | Rota finalizada com sucesso |
***
## Estrutura de uma rota [#estrutura-de-uma-rota]
### Informações principais [#informações-principais]
| Campo | Descrição |
| ------------------ | ------------------------------------------------------- |
| **Nome** | Identificador amigável da rota (atribuído pelo criador) |
| **Tipo** | PRIVATE\_FLEET ou CARRIER |
| **Armazém** | Local de partida dos pedidos (ponto de origem) |
| **Motorista** | Responsável pela execução (apenas Frota Própria) |
| **Transportadora** | Carrier externo (apenas modo Transportadora) |
### Waypoints (paradas) [#waypoints-paradas]
Cada pedido na rota é uma **parada** (*waypoint*) com:
* Endereço de entrega
* Janela de horário (quando configurada)
* Status individual da parada (ex.: entregue, falhou, pendente)
* Comprovante de entrega (foto, assinatura, código)
***
## Fluxo de criação [#fluxo-de-criação]
1. **Selecionar pedidos** — escolher quais pedidos entrarão na rota.
2. **Configurar** — definir armazém de origem e responsável (motorista ou transportadora).
3. **Sugerir rota** — a plataforma otimiza a sequência de paradas via Mapbox.
4. **Visualizar prévia** — revisar o trajeto no mapa antes de confirmar.
5. **Confirmar** — rota criada e (se Frota Própria) motorista notificado.
***
## Ciclo de vida [#ciclo-de-vida]
```
CREATED → START_DELIVERY → ALL_WAYPOINTS_FINISHED → FINISHED
↘ CANCELED
```
Uma rota pode ser cancelada manualmente enquanto ainda estiver em `CREATED` ou `START_DELIVERY`.
***
## Ações disponíveis por status [#ações-disponíveis-por-status]
| Ação | CREATED | START\_DELIVERY | ALL\_WAYPOINTS\_FINISHED |
| ---------------------- | ------- | --------------- | ------------------------ |
| Atribuir motorista | ✓ | — | — |
| Solicitar coleta (TRP) | ✓ | — | — |
| Duplicar | ✓ | ✓ | ✓ |
| Cancelar | ✓ | ✓ | — |
***
## Onde aparece [#onde-aparece]
* [**Tela de Rotas (GO)**](/docs/go/products/rotas/) — criação e acompanhamento no contexto de frota própria e transportadora.
* [**Tela de Rotas (LOG)**](/docs/log/products/rotas/) — acompanhamento de rotas no modo transportadora.
* **Pedidos** — cada pedido exibe a rota à qual está associado (quando houver).
---
# Conta (Seller Group) (/docs/log/conceitos/seller-group)
**Seller Group** (grupo de embarcadores) é a entidade de mais alto nível no painel — representa a **conta** de um cliente Abbiamo. Uma conta pode ter várias [filiais](/docs/log/conceitos/filial/) e vários [usuários](/docs/log/conceitos/usuario/) atuando sobre essas filiais.
No código e na API aparece como **SellerGroup** ou `seller_group`.
***
## O que compõe uma conta [#o-que-compõe-uma-conta]
### Identificação [#identificação]
| Campo | Descrição |
| ------------- | --------------------- |
| `id` | Identificador interno |
| `name` | Nome da conta |
| `description` | Descrição (opcional) |
### Configurações globais [#configurações-globais]
* `default_theme_id` — tema padrão (logo, cores) aplicado quando não há configuração específica por filial
* `default_notification_preferences_id` — preferências de notificação padrão
***
## Usuários e permissões [#usuários-e-permissões]
* Cada [usuário](/docs/log/conceitos/usuario/) pertence a uma conta e tem uma **role** (papel) com permissões granulares
* O usuário pode ser **admin**, **master** ou **read-only** — algumas páginas e ações só ficam disponíveis para admin ou master
***
## Filiais e contexto de uso [#filiais-e-contexto-de-uso]
* O usuário "enxerga" apenas as [filiais](/docs/log/conceitos/filial/) da sua conta
* No painel, o usuário pode selecionar **todas as filiais** ou **algumas filiais**. Essa escolha define o escopo dos dados em várias páginas (pedidos, envios, relatórios, integrações)
* O **tema** (logo, cores) exibido no painel pode vir da primeira filial selecionada (white label), quando aplicável
***
## Como se relaciona com as outras entidades [#como-se-relaciona-com-as-outras-entidades]
| Entidade | Relação com a conta |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **[Filial](/docs/log/conceitos/filial/)** | Pertence a uma conta; é a unidade operacional |
| **[Usuário](/docs/log/conceitos/usuario/)** | Pertence a uma conta; tem role, permissões e lista de filiais acessíveis |
| **[Pedido](/docs/log/conceitos/pedido/)** | Pertence a uma filial, que pertence à conta |
| **[Envio](/docs/log/conceitos/envio/)** | Pertence a um pedido → filial → conta |
| **[Integrações](/docs/log/conceitos/integracao-transportadora/)** | Configuradas por filial dentro da conta |
---
# SLA (Prazo de Entrega) (/docs/log/conceitos/sla)
O **SLA** define o prazo acordado para entrega.
## Pode variar por [#pode-variar-por]
* Região
* Modalidade
* Transportadora
* Tipo de produto
## O que a plataforma permite [#o-que-a-plataforma-permite]
* Monitoramento de atrasos
* Comparação de performance
* Controle de nível de serviço
---
# Status de pedido (/docs/log/conceitos/status-de-pedido)
Referência de todos os **status** (status principal do pedido) e **sub\_status** usados na plataforma, com tradução em **Português (PT-BR)**. A relação **qual sub\_status pertence a qual status** segue o mapeamento do código.
***
## Status principal (status\_name) [#status-principal-status_name]
| Código | PT-BR |
| ---------------- | -------------------- |
| `SUCCESSFUL` | Sucesso |
| `CREATED` | Criado |
| `DISPATCHED` | Despachado |
| `START_DELIVERY` | Em Rota |
| `CANCELED` | Cancelado |
| `FAILED` | Falha |
| `TREATED` | Tratado |
| `VISIT_LATER` | Visitar mais tarde |
| `PENDING` | Pendente |
| `COLLECTED` | Coletado |
| `ORDER_FAILED` | Falha na Solicitação |
| `MANUAL_HANDLE` | Baixa manual |
| `HANDLING` | Em manuseio |
| `RETURNING` | Em Devolução |
| `RETURNED` | Devolvido |
| `IN_TRANSIT` | Em trânsito |
| `ON_TIME` | No Prazo |
| `DELAYED` | Atrasado |
| `ON_HOLD` | Em espera |
| `SCHEDULED` | Agendado |
***
## Sub-status por status (status → sub\_status) [#sub-status-por-status-status--sub_status]
Cada bloco lista os **sub\_status** que podem ocorrer para aquele **status** principal.
### CREATED (Criado) [#created-criado]
| Código sub\_status | PT-BR |
| --------------------- | ----------------------- |
| `LAST_ROUTE_CANCELED` | Rota Anterior Cancelada |
***
### PENDING (Pendente) [#pending-pendente]
| Código sub\_status | PT-BR |
| ------------------------------ | ------------------------------------ |
| `WAITING_FOR_CARRIER` | Aguardando Transportadora |
| `WAITING_CARRIER_ACTION` | Aguardando Ação com a Transportadora |
| `WAITING_FOR_DRIVER` | Aguardando Entregador |
| `WAITING_TAKEOUT_CONFIRMATION` | Aguardando Confirmação de Retirada |
***
### DISPATCHED (Despachado) [#dispatched-despachado]
| Código sub\_status | PT-BR |
| ------------------- | ------------------------ |
| `ROUTE_PLANNED` | Rota Planejada |
| `CARRIER_CONFIRMED` | Transportadora Confirmou |
| `SEARCHING_DRIVER` | Buscando Entregador |
| `DRIVER_ASSIGNED` | Entregador Atribuído |
| `DRIVER_REJECTED` | Entregador Recusou |
| `READY_FOR_TAKEOUT` | Pronto para Retirada |
| `DRIVER_CONFIRMED` | Entregador Confirmou |
***
### IN\_TRANSIT (Em trânsito) [#in_transit-em-trânsito]
| Código sub\_status | PT-BR |
| ------------------ | ------------------ |
| `COLLECTING` | Coletando |
| `AT_PICKUP_POINT` | No Local de Coleta |
***
### HANDLING (Em manuseio) [#handling-em-manuseio]
| Código sub\_status | PT-BR |
| -------------------- | ---------------------------------- |
| `LOGISTICS_STARTED` | Logística Iniciada na Base |
| `READY_FOR_TRANSFER` | Preparado para transferência |
| `PACKAGE_RECEIVED` | Objeto Recebido na Base |
| `IN_TRANSFER` | Em Transferência entre Bases |
| `TRANSFER_COMPLETED` | Transferência entre Bases Completa |
| `SCHEDULED_DELIVERY` | Entrega Agendada |
| `REDISPATCHED` | Re-solicitação de coleta feita |
| `PROCESSED_DELIVERY` | Processado para entrega |
***
### SUCCESSFUL (Sucesso) [#successful-sucesso]
| Código sub\_status | PT-BR |
| ------------------ | --------- |
| `DELIVERED` | Entregue |
| `WITHDRAWN` | Retirado |
| `RETURNED` | Retornado |
***
### FAILED (Falha) [#failed-falha]
| Código sub\_status | PT-BR |
| ------------------ | ------------------ |
| `DELIVERY_FAILED` | Falha na Entrega |
| `COLLECT_FAILED` | Falha na Coleta |
| `RETURN_FAILED` | Falha na Devolução |
***
### ORDER\_FAILED (Falha na Solicitação) [#order_failed-falha-na-solicitação]
| Código sub\_status | PT-BR |
| -------------------------------- | ------------------------------------ |
| `CARRIER_CANCELED` | Transportadora Cancelou |
| `CARRIER_REFUSED` | Transportadora Recusou |
| `CARRIER_ERROR` | Erro da Transportadora |
| `CARRIER_TIMEOUT` | Transportadora Não Respondeu a Tempo |
| `PACKAGE_NOT_COLLECTED` | Pacote Não Coletado |
| `SELLER_CANCELED` | Marca Cancelou |
| `OUT_OF_COVERAGE` | Fora da Área de Cobertura |
| `INACTIVITY_TIMEOUT` | Tempo de Inatividade Excedido |
| `SCHEDULE_FAILED` | Falha no Agendamento |
| `SCHEDULE_CANCELED` | Agendamento Cancelado |
| `LAST_SEARCHING_DRIVER_CANCELED` | Busca de Entregador Cancelada |
| `SEARCHING_DRIVER_CANCELED` | Busca de Entregador Cancelada |
| `NO_DRIVER_AVAILABLE` | Nenhum Entregador Disponível |
***
### CANCELED (Cancelado) [#canceled-cancelado]
| Código sub\_status | PT-BR |
| ------------------ | ---------------------- |
| `INTERNAL` | Interno |
| `SELLER_CANCELED` | Marca Cancelou |
| `CANCELED_BY_USER` | Cancelado pelo Usuário |
***
### Status sem sub\_status no mapeamento [#status-sem-sub_status-no-mapeamento]
Os status abaixo **não** possuem sub\_status no mapeamento do front (`substatusesByStatus`): **COLLECTED**, **RETURNED**, **START\_DELIVERY**, **SCHEDULED**, **MANUAL\_HANDLE**, **ON\_HOLD**, **TREATED**, **VISIT\_LATER**, **RETURNING**, **ON\_TIME**, **DELAYED**. Podem aparecer com `sub_status` vazio ou valores vindos do backend em contextos específicos.
---
# Status e Rastreamento (/docs/log/conceitos/status-rastreamento)
Durante o transporte, o pedido recebe atualizações como:
* Criado
* Coletado
* Em trânsito
* Saiu para entrega
* Entregue
* Falha na entrega
* Devolvido
## Como as atualizações ocorrem [#como-as-atualizações-ocorrem]
* Webhook
* Consulta automática
* Atualização manual
---
# Tabela de Frete (/docs/log/conceitos/tabela-frete)
A **Tabela de Frete** registra os valores negociados em contrato entre a sua marca e a transportadora. É nela que você cadastra quanto custa cada faixa de peso, para cada faixa de destino (CEP ou quilometragem), separado por [prazo de entrega](/docs/log/conceitos/prazos/).
Ela está vinculada a uma [integração de transportadora](/docs/log/conceitos/integracao-transportadora/) e é usada para:
* Calcular o **valor do frete** e a **data de entrega esperada** na [cotação](/docs/log/conceitos/cotacao-frete/)
* Validar o prazo de envio na **solicitação de coleta**
* Fornecer as opções de frete para as [automações de envio](/docs/log/conceitos/regra-envio/)
***
## Tipos de tabela [#tipos-de-tabela]
| Tipo | Como funciona |
| ------------------ | ----------------------------------------------------------------------------- |
| **Tabela de CEP** | Define preço por **faixa de CEP de destino** e **peso**, para cada prazo |
| **Tabela de Raio** | Define preço por **faixa de distância (km)** e **peso**, para cada prazo |
***
## Como a tabela é organizada [#como-a-tabela-é-organizada]
Toda tabela de frete segue a mesma hierarquia:
1. **Tabela** — contém um ou mais **prazos**
2. **Prazo** (ex.: D1, D3, D7, EXP60, EXP120) — dentro de cada prazo, há uma ou mais **faixas de destino**
3. **Faixa de destino** — uma faixa de CEP (na tabela de CEP) ou uma faixa de quilometragem (na tabela de raio), com **preços por faixa de peso**
### Tabela de CEP [#tabela-de-cep]
Cada prazo contém faixas de CEP de destino (ex.: 01000-000 a 01999-999). Para cada faixa, você define preços por faixa de peso — por exemplo, até 1 kg, até 5 kg, até 10 kg — e opcionalmente um valor por kg adicional.
**Como criar:** via upload de arquivo CSV. O arquivo contém as colunas de CEP inicial, CEP final, as faixas de peso com seus preços, valor por kg adicional e o prazo.
### Tabela de Raio [#tabela-de-raio]
Cada prazo contém faixas de distância em quilômetros (ex.: 0–5 km, 5–10 km, 10–20 km). Para cada faixa de km, você define preços por faixa de peso e opcionalmente um valor por km adicional acima da quilometragem máxima.
**Como criar:** via upload de planilha Excel. Cada aba da planilha representa um prazo (ex.: aba "D1", aba "D3", aba "EXP60"). Dentro de cada aba, as linhas são as faixas de km e as colunas são as faixas de peso.
***
## Vínculo com integração de transportadora [#vínculo-com-integração-de-transportadora]
A tabela de frete é vinculada a uma [integração de transportadora](/docs/log/conceitos/integracao-transportadora/). Cada integração pode ter **uma** tabela associada — do tipo CEP ou do tipo raio.
* A tabela pertence a uma **modalidade** (ex.: CARRO, MOTO, CONVENCIONAL, PAC).
* **Várias integrações** podem compartilhar a mesma tabela de frete.
* O tipo de tabela (CEP ou raio) é definido na integração.
***
## Horário de corte [#horário-de-corte]
O **horário de corte** é configurado na [integração de transportadora](/docs/log/conceitos/integracao-transportadora/) e impacta diretamente como a data de entrega esperada é calculada a partir dos prazos da tabela.
* Define o **horário limite do dia** para que a solicitação de coleta seja considerada "hoje".
* Se o pedido entra **antes** do horário de corte: a contagem do prazo começa no mesmo dia.
* Se o pedido entra **depois** do horário de corte: a contagem do prazo começa no **próximo dia útil de operação**.
***
## Cobertura restrita [#cobertura-restrita]
A **cobertura restrita** é uma opção configurada na [integração de transportadora](/docs/log/conceitos/integracao-transportadora/). Quando ativada:
* Se o destino do pedido **não está coberto** por nenhuma faixa da tabela de frete (o CEP não cai em nenhuma faixa de CEP, ou a distância não cai em nenhuma faixa de km), o envio **falha automaticamente** como "fora de cobertura".
* O pedido aparece como **falho** na tela de pedidos.
Quando **desativada** (padrão), o envio é tentado normalmente mesmo que o destino não esteja mapeado na tabela.
***
## Onde a tabela é usada [#onde-a-tabela-é-usada]
### Na cotação [#na-cotação]
Quando o sistema calcula opções de frete (no checkout, na criação do pedido ou automaticamente), ele consulta as tabelas de frete das integrações ativas da [filial](/docs/log/conceitos/filial/):
* Para cada **prazo** da tabela, verifica se o destino está coberto e calcula o preço pela faixa de peso.
* Calcula a **data de entrega esperada** usando o prazo, o horário de corte, os dias de operação e feriados.
* Retorna as opções disponíveis com preço, prazo e transportadora.
### Na solicitação de coleta [#na-solicitação-de-coleta]
Quando um envio é criado (manual ou via automação), o sistema valida que o **prazo escolhido existe na tabela de frete** da integração. Se o prazo não for encontrado, o envio falha.
### Nas automações [#nas-automações]
As [automações de envio](/docs/log/conceitos/regra-envio/), [reenvio](/docs/log/conceitos/regra-reenvio/) e [inatividade](/docs/log/conceitos/regra-inatividade/) podem usar a tabela de frete de duas formas:
* **Prazo específico:** a automação aponta diretamente para uma integração + prazo (ex.: Correios/PAC/D3). O prazo **precisa existir** na tabela.
* **Mais barato ou mais rápido:** o sistema realiza uma cotação automática usando as tabelas de frete de todas as integrações ativas e escolhe a melhor opção. Nesse caso, a automação se adapta automaticamente a mudanças na tabela.
***
## Erros comuns [#erros-comuns]
### Prazo não encontrado [#prazo-não-encontrado]
**O que acontece:** a automação de envio tenta fazer a solicitação de coleta do pedido com um prazo específico (ex.: D1), mas esse prazo não existe mais na tabela de frete da integração. O pedido vai para **falho**.
**Causa mais comum:** a tabela de frete foi editada (um prazo foi removido ou renomeado) sem atualizar as automações de envio que referenciavam aquele prazo.
**Como resolver:** atualize a automação para usar o novo prazo disponível na tabela, ou mude a ação da automação para **mais barato** ou **mais rápido** — assim ela se adapta automaticamente às opções da tabela.
### Fora de cobertura [#fora-de-cobertura]
**O que acontece:** o destino do pedido não cai em nenhuma faixa da tabela de frete (o CEP ou a distância não está mapeado), e a integração está com **cobertura restrita** ativada. O pedido vai para **falho** como "fora de cobertura".
**Como resolver:** adicione a faixa de CEP ou km na tabela de frete, ou desative a cobertura restrita na integração se quiser que o envio seja tentado mesmo para destinos não mapeados.
### Nenhuma opção na cotação [#nenhuma-opção-na-cotação]
**O que acontece:** a automação com ação **mais barato** ou **mais rápido** não encontra nenhuma opção de frete. Nenhuma integração da filial cobre aquele destino, ou a tabela não tem faixas para aquele CEP/km/peso.
**Como resolver:** verifique se as integrações da filial estão ativas e se as tabelas de frete cobrem o destino do pedido.
***
## Links relacionados [#links-relacionados]
* [Prazos de Entrega](/docs/log/conceitos/prazos/) — códigos de prazo usados nas tabelas (D0, D1, EXP60, etc.)
* [Integração de Transportadora](/docs/log/conceitos/integracao-transportadora/) — onde a tabela é vinculada
* [Cotação de Frete](/docs/log/conceitos/cotacao-frete/) — como a tabela é usada para calcular preço e prazo
* [Automação de Envio](/docs/log/conceitos/regra-envio/) — automações que dependem dos prazos da tabela
* [Automação de Reenvio](/docs/log/conceitos/regra-reenvio/) — fallback quando o envio falha
* [Automação de Inatividade](/docs/log/conceitos/regra-inatividade/) — ação quando o envio fica parado
---
# Transportadora (/docs/log/conceitos/transportadora)
A **transportadora** é a empresa que realiza a coleta e a entrega dos [envios](/docs/log/conceitos/envio/). No sistema, cada transportadora pode oferecer uma ou mais [modalidades](/docs/log/conceitos/modalidade/) de serviço — por exemplo, a mesma empresa pode ter entrega de **carro** e de **moto**.
***
## Exemplos de transportadoras [#exemplos-de-transportadoras]
| Transportadora | Exemplos de modalidades |
| -------------- | ------------------------ |
| **Uber** | CARRO, MOTO |
| **Loggi** | CARRO, MOTO, BICICLETA |
| **Correios** | PAC, SEDEX, CONVENCIONAL |
| **Jadlog** | CONVENCIONAL, EXPRESSO |
***
## Como a transportadora aparece no sistema [#como-a-transportadora-aparece-no-sistema]
A transportadora não é configurada sozinha — ela entra no sistema por meio da [integração de transportadora](/docs/log/conceitos/integracao-transportadora/), que liga uma [filial](/docs/log/conceitos/filial/) a uma combinação **transportadora + modalidade**. Por exemplo:
* Uma integração para **Uber / Carro**
* Outra para **Uber / Moto**
* Outra para **Correios / PAC**
Cada integração tem credenciais, [tabela de frete](/docs/log/conceitos/tabela-frete/) e configurações próprias.
***
## Composição: transportadora / modalidade / prazo [#composição-transportadora--modalidade--prazo]
Quando você escolhe um envio (manual ou via [automação](/docs/log/conceitos/regra-envio/)), a identificação completa é:
**Transportadora** + **Modalidade** + **Prazo**
Exemplos: `UBER/CARRO/EXP60`, `CORREIOS/PAC/D3`, `LOGGI/MOTO/EXP120`.
***
## Links relacionados [#links-relacionados]
* [Modalidade](/docs/log/conceitos/modalidade/) — tipo de serviço da transportadora (CARRO, MOTO, PAC)
* [Prazos de Entrega](/docs/log/conceitos/prazos/) — códigos de prazo (D1, EXP60, etc.)
* [Integração de Transportadora](/docs/log/conceitos/integracao-transportadora/) — configuração que conecta a filial à transportadora
* [Tabela de Frete](/docs/log/conceitos/tabela-frete/) — preços e prazos negociados com a transportadora
---
# Usuário (/docs/log/conceitos/usuario)
O **Usuário** é quem acessa o painel da Abbiamo. Desde o [Login Unificado](/docs/log/conceitos/login/), cada pessoa tem **um único email e senha**, e pode ter um usuário em uma ou mais contas (LOG, GO, ou ambas) — cada um com sua própria role e filiais.
Cada usuário pertence a uma [conta (seller group)](/docs/log/conceitos/seller-group/) e tem acesso a uma ou mais [filiais](/docs/log/conceitos/filial/) dessa conta, conforme suas permissões.
***
## Tipos de usuário (roles) [#tipos-de-usuário-roles]
| Tipo | Descrição |
| ----------------- | --------------------------------------------------------------------------------------------- |
| **Proprietário** | Acesso total a todas as filiais e configurações da conta. Não pode ser restringido por filial |
| **Administrador** | Acesso configurável — pode ser limitado a filiais específicas |
***
## Onde gerenciar [#onde-gerenciar]
A criação, edição e desativação de usuários acontece em **Configurações › Usuários** dentro de cada operação.
→ Veja [Configurações › Usuários](/docs/log/settings/usuarios/) para o passo a passo completo.
---
# Códigos de Falha (/docs/api/conceitos/tables/failure-codes)
Quando um pedido entra em `FAILED` (`COLLECT_FAILED`, `DELIVERY_FAILED` ou `RETURN_FAILED`), a Abbiamo registra o motivo via `failure_code`. Use a tabela abaixo para interpretar o evento:
| `failure_code` | `failure_message` |
| :------------: | :------------------------------------------------- |
| `17` | Outro |
| `18` | Endereço incorreto |
| `19` | Área inacessível ou de risco |
| `20` | Destinatário indisponível |
| `21` | Chegada no cliente fora da janela de atendimento |
| `22` | Estabelecimento fechado |
| `23` | Tempo insuficiente para entrega |
| `24` | Tempo excessivo de espera |
| `25` | Compra não reconhecida — pacote recusado |
| `26` | Pacote avariado — pacote recusado |
| `27` | Pacote perdido |
| `28` | Pacote não carregado no veículo |
| `29` | Erro na emissão da nota fiscal |
| `30` | Etiqueta avariada |
| `31` | Erro de carregamento |
| `32` | Sistema fora do ar |
| `33` | Dado incorreto no sistema |
| `34` | Capacidade do veículo atingida |
| `35` | Problema mecânico no veículo |
| `36` | Sinistro/Emergência |
| `37` | Acidente de trânsito |
| `38` | Local com estacionamento proibido (risco de multa) |
| `39` | Compra cancelada |
---
# Tabelas de referência (/docs/api/conceitos/tables)
Os status possíveis de um pedido ao longo do ciclo de vida e o significado de cada substatus.
Códigos numéricos retornados quando uma coleta, entrega ou devolução falha.
---
# Status de um pedido (/docs/api/conceitos/tables/status-and-substatus)
O ciclo de vida completo de um pedido — do `CREATED` ao `SUCCESSFUL` ou `RETURNED`. Cada estado mostra quem dispara a transição, qual webhook sai e o que você pode fazer a partir dali.
Um pedido passa por uma sequência previsível de **status**. Cada transição é registrada como um **evento** e dispara o webhook `ORDER_STATUS_CHANGE` pra integrações que estão escutando.
Esta página cobre **todos os status possíveis**, organizados em três grupos: caminho feliz (Criado → Entregue), estados de espera (Pendente, Handling) e caminho infeliz (Falha, Devolução, Cancelamento). Os status são `enum`s que aparecem no campo `status` da resposta; substatus aparecem em `sub_status`.
A coluna **Roteirizável**, quando indicada em frota própria (`PRIVATE_FLEET`), significa que um pedido nesse estado pode ser incluído em uma nova rota.
***
O pedido **acabou de ser criado** na Abbiamo. Ainda não foi despachado para nenhuma transportadora. Em uma operação de **frota própria**, este pedido já é elegível pra ser incluído em uma rota.
POST /v2/order
— criação manual ou via integração
DISPATCHED
— quando a entrega é solicitada à transportadora
PENDING
— quando ainda falta uma ação pra despachar
A entrega foi **solicitada à transportadora** (ou planejada numa rota da frota própria). A partir daqui o pedido sai do controle direto da loja — quem dirige o próximo passo é a operação logística.
Confirmação da transportadora via webhook
carrier-confirm-delivery
O motorista está **a caminho da filial** pra pegar o pacote. Esta é a primeira "perna" da entrega — o veículo se moveu mas ainda não tem o pacote.
Webhook da transportadora:
carrier-collecting-delivery
Motorista da frota própria iniciando a etapa de coleta no TMS
COLLECTED
— motorista chegou e pegou o pacote
FAILED
com
COLLECT_FAILED
— falha na coleta (loja fechada, pacote indisponível, etc.)
O pacote já está **com o motorista**. Em fluxos com **pincode**, este é o estado que confirma a coleta válida; em fluxos sem pincode, é o checkpoint que a transportadora envia ao sair da filial.
Validação de pincode bem-sucedida (modelo motorista → loja, dono Abbiamo)
Confirmação no TMS pela operação de frota própria
START_DELIVERY
— motorista saiu da filial em direção ao destinatário
HANDLING
— pacote entrou no hub interno da transportadora
O motorista **saiu da filial com o pacote** e está a caminho do endereço do destinatário. Esta é a "última milha" — o estado em que o cliente final começa a ver atualizações na página de tracking.
Webhook
carrier-start-delivery
Frota própria: motorista marca "iniciar entrega" no TMS
SUCCESSFUL
com
DELIVERED
— entregue ao destinatário
SUCCESSFUL
com
WITHDRAWN
— retirado pelo cliente (Pick&Go)
FAILED
com
DELIVERY_FAILED
— falha na entrega
RETURNING
— entrega não rolou, pacote voltando pra filial
Fim feliz. O pacote chegou ao destinatário (`DELIVERED`) ou foi retirado pelo cliente final na loja (`WITHDRAWN`). Nenhuma outra transição sai daqui — é estado terminal de sucesso.
Webhook
carrier-successful-delivery
Motorista da frota marca como entregue no TMS (POD opcional)
PUT /v1/orders/{`{id}`}/withdrawn
— retirada presencial
Webhook
ORDER_STATUS_CHANGE
com status final
Webhook
ORDER_CSAT_ANSWER
quando o cliente responde a pesquisa de satisfação
***
O pedido está esperando algo acontecer antes de seguir. Pode ser uma confirmação da transportadora, uma ação manual da loja ou uma janela operacional aguardando abrir.
Pacote em **operação interna da transportadora** — transferências entre filiais, processamento em hubs, agendamento. O pacote não está com um motorista de entrega final ainda; pode passar dias aqui em transportadoras maiores.
***
Algo deu errado em uma das três etapas: coleta, entrega ou retorno. Em **frota própria**, um pedido em `FAILED` ainda é *roteirizável* — você pode incluí-lo em uma nova rota pra tentar de novo. Veja a [tabela de códigos de falha](/docs/api/conceitos/tables/failure-codes) pra interpretar cada `failure_code`.
O motorista está **a caminho da filial de origem com o pacote**. Sempre vem depois de uma `DELIVERY_FAILED` — alguém precisa receber o pacote de volta.
O pacote **voltou pra filial de origem**. Estado terminal — mas em frota própria, ainda é *roteirizável*: você pode tentar uma nova entrega pelo mesmo ou outro destinatário.
Estado terminal usado quando o pedido foi **cancelado depois de ter sido coletado** e o pacote **voltou pra filial**. Vem com `sub_status: RETURNED_TO_SELLER`.
Diferente de `ORDER_FAILED` (cancelamento antes/durante despacho), aqui já houve coleta e o pacote precisou retornar.
O pedido foi **cancelado antes ou durante o despacho**. Diferente de `FAILED` (falha na operação), aqui o motivo é decisão da loja ou da transportadora.
***
O pedido foi **finalizado manualmente** fora do fluxo padrão — geralmente via dashboard quando uma operação precisa intervir (ex.: pacote perdido conciliado offline). Disparado pelo endpoint `cancel-order` (que na verdade marca como manual handle, não cancela).
---
# Automações de Marcadores — Como Usar (/docs/go/products/automacoes-de-marcadores/como-usar)
***
## Criar uma automação de marcador [#criar-uma-automação-de-marcador]
1. Acesse **Configurações > Automações de marcadores**.
2. Clique em **Criar automação**.
3. Preencha o formulário:
### 1. Título [#1-título]
Dê um nome descritivo à automação (ex.: "Produto frágil — filial SP").
### 2. Ativar automação [#2-ativar-automação]
Marque o toggle se quiser que a automação já fique ativa ao salvar.
### 3. Condições [#3-condições]
Defina **quais pedidos** receberão o marcador. Sem condições, todos os pedidos serão automatizados.
Para adicionar uma condição:
1. Clique em **"Quais condições devem ser atendidas?"**.
2. Selecione o **campo** a avaliar (ex.: Filial, CEP, SKU).
3. Escolha o **operador** (ex.: é, não é, contém).
4. Informe o **valor**.
5. Adicione mais condições se necessário (AND).
### 4. Marcador a atribuir [#4-marcador-a-atribuir]
No campo **"Qual marcador atribuir ao pedido?"**, selecione o marcador na lista.
4. Clique em **Criar automação**.
***
## Editar, ativar/desativar ou excluir [#editar-ativardesativar-ou-excluir]
Clique no **menu ⋯** da automação desejada:
| Ação | Descrição |
| ---------------------- | --------------------------------------------- |
| **Editar** | Abre o modal de edição |
| **Ativar / Desativar** | Alterna a situação (🟢 ativa / 🔴 desativada) |
| **Excluir** | Remove permanentemente |
***
## Entender a sequência [#entender-a-sequência]
A coluna **Sequência** define a prioridade de avaliação. Se um pedido atende às condições de mais de uma automação, o marcador da **primeira na sequência** é aplicado.
---
# Automações de Marcadores — Visão Geral (/docs/go/products/automacoes-de-marcadores)
A tela de **Automações de Marcadores** permite criar regras que aplicam [marcadores](/docs/go/settings/marcadores/) automaticamente a pedidos quando determinadas condições são atendidas — eliminando a necessidade de marcação manual.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/tags-rules](https://dashboard.abbiamolog.com/tags-rules)
* **Menu:** seção **Configurações** > **Automações de marcadores**
***
## Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------------- | ----------------------------------------- |
| **Título** | "Automação de marcadores de pedidos" |
| **Criar automação** | Abre o modal de criação de nova automação |
***
## Barra de filtros [#barra-de-filtros]
| Filtro | Descrição |
| ------------- | --------------------------- |
| **Nome** | Busca por nome da automação |
| **Atualizar** | Recarrega a lista |
| **Filtros** | Painel de filtros avançados |
***
## Tabela de automações [#tabela-de-automações]
| Coluna | O que mostra |
| --------------------- | ----------------------------------------------------------------------- |
| **Sequência** | Ordem de avaliação das automações (1 = maior prioridade) |
| **Nome** | Nome descritivo da automação |
| **Condições** | Resumo das condições configuradas (ex.: "Filial") ou "Todos os pedidos" |
| **Marcador aplicado** | Badge colorido com o nome do marcador que será atribuído |
| **Situação** | 🟢 Ativa / 🔴 Desativada |
| **Criado em** | Data e hora de criação |
| **Atualizada em** | Data e hora da última modificação |
| **Menu (⋯)** | Ações por automação |
***
## Modal de criação / edição [#modal-de-criação--edição]
Clique em **Criar automação** (ou **Editar** no menu ⋯) para abrir o formulário:
| Campo | Descrição |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Título** | Nome da automação (ex.: "Fragilidade por filial") |
| **Ativar automação** | Toggle para ativar/desativar imediatamente após criar |
| **Condições** | Regras que um pedido deve atender para receber o marcador. Sem condições = "Todos os pedidos serão automatizados" |
| **Marcador a atribuir** | Selecione o marcador (criado em [Configurações > Marcadores](/docs/go/settings/marcadores/)) |
### Como funcionam as condições [#como-funcionam-as-condições]
As condições são construídas como filtros: selecione um **campo** (ex.: Filial, CEP, SKU), um **operador** (é / não é / contém) e um **valor**. Múltiplas condições são avaliadas em conjunto (AND).
***
## Ações por automação (menu ⋯) [#ações-por-automação-menu-]
| Ação | Descrição |
| ---------------------- | ---------------------------------- |
| **Editar** | Abre o modal de edição |
| **Ativar / Desativar** | Alterna a situação da automação |
| **Excluir** | Remove permanentemente a automação |
***
## Próximos passos [#próximos-passos]
* [**Como Usar**](/docs/go/products/automacoes-de-marcadores/como-usar/) — passo a passo para criar e gerenciar automações de marcadores.
---
# Automações de Ofertas — Como Usar (/docs/go/products/automacoes-de-ofertas/como-usar)
***
## Criar uma automação de oferta [#criar-uma-automação-de-oferta]
1. Acesse **Configurações > Automações de ofertas**.
2. Selecione a **filial** no seletor da barra de filtros.
3. Clique em **Criar automação**.
4. Preencha o formulário:
### 1. Selecionar Filial [#1-selecionar-filial]
Confirme ou altere a filial para a qual a automação se aplica.
### 2. Tipo de operação [#2-tipo-de-operação]
Escolha **ENTREGA** (padrão) ou **REVERSA** (logística reversa).
### 3. Título [#3-título]
Dê um nome descritivo (ex.: "CEP ZL → Grupo Zona Leste").
### 4. Condições [#4-condições]
Defina os critérios que um pedido deve atender. Sem condições, a automação se aplica a todos os pedidos da filial.
Para adicionar uma condição:
1. Clique em **"Quais condições devem ser atendidas?"**.
2. Selecione o **campo** (ex.: CEP, Filial, Marcador).
3. Escolha o **operador** (ex.: começa com, é, contém).
4. Informe o **valor**.
### 5. Ação [#5-ação]
Defina quem recebe a oferta:
| Opção | Quando usar |
| ------------------------------ | ------------------------------------------------------------- |
| **Todos os motoristas** | Sem restrição — qualquer motorista disponível recebe a oferta |
| **Motorista(s) específico(s)** | Apenas os motoristas selecionados recebem |
| **Grupo(s) de motoristas** | Apenas motoristas do(s) grupo(s) selecionado(s) recebem |
5. Clique em **Criar automação**.
***
## Editar sequência (prioridade) [#editar-sequência-prioridade]
A **sequência** define qual automação é avaliada primeiro. Para reordenar:
1. Clique em **Editar Sequência** na barra de controles.
2. Arraste as automações para a ordem desejada.
3. Salve.
***
## Ativar, editar ou excluir [#ativar-editar-ou-excluir]
Clique no **menu ⋯** da automação:
| Ação | Descrição |
| ---------------------- | ---------------------------- |
| **Editar** | Abre o formulário de edição |
| **Ativar / Desativar** | Alterna a situação (🟢 / 🔴) |
| **Excluir** | Remove permanentemente |
***
## Verificar se o serviço está online [#verificar-se-o-serviço-está-online]
O indicador **Online** na barra de controles mostra se o serviço de automação de ofertas está ativo. Se aparecer como offline, as automações não serão avaliadas — contate o suporte.
---
# Automações de Ofertas — Visão Geral (/docs/go/products/automacoes-de-ofertas)
A tela de **Automações de Ofertas** permite configurar regras que definem automaticamente **para quais motoristas** (ou grupos) uma oferta de entrega é enviada quando um pedido precisa ser despachado — com base em condições como CEP, filial ou características do pedido.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/offer-automation-rules](https://dashboard.abbiamolog.com/offer-automation-rules)
* **Menu:** seção **Configurações** > **Automações de ofertas**
***
## Cabeçalho e controles [#cabeçalho-e-controles]
| Elemento | Descrição |
| --------------------- | ------------------------------------------------- |
| **Título** | "Automações de ofertas" |
| **Criar automação** | Abre o modal de criação |
| **Seletor de filial** | Filtra as automações pela filial selecionada |
| **Nome** | Busca por nome da automação |
| **Editar Sequência** | Reordena a prioridade de avaliação das automações |
| **Indicador Online** | Mostra se o serviço de ofertas está ativo |
***
## Tabela de automações [#tabela-de-automações]
| Coluna | O que mostra |
| -------------------- | ------------------------------------------------------------------------- |
| **Sequência** | Ordem de avaliação (1 = maior prioridade) |
| **Nome** | Nome descritivo da automação |
| **Condições** | Resumo das condições (ex.: "CEP", "Todos os pedidos") |
| **Ação** | Destinatário da oferta (ex.: "Todos os motoristas", motorista específico) |
| **Tipo de Operação** | ENTREGA ou REVERSA |
| **Situação** | 🟢 Ativa / 🔴 Desativada |
| **Criada em** | Data e hora de criação |
| **Atualizada em** | Data e hora da última modificação |
| **Menu (⋯)** | Ações por automação |
***
## Modal de criação / edição [#modal-de-criação--edição]
| Campo | Descrição |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Selecionar Filial** | Filial à qual a automação se aplica |
| **Tipo de operação** | ENTREGA (padrão) ou REVERSA |
| **Título** | Nome descritivo da automação |
| **Condições** | Regras que um pedido deve atender para que a automação seja acionada. Sem condições = "Todos os pedidos" |
| **Ação** | Quem recebe a oferta: **Todos os motoristas**, **Motorista(s) específico(s)** ou **Grupo(s) de motoristas** |
### Opções de Ação [#opções-de-ação]
| Ação | Comportamento |
| ------------------------------ | ------------------------------------------------------- |
| **Todos os motoristas** | A oferta é enviada para todos os motoristas disponíveis |
| **Motorista(s) específico(s)** | Selecione um ou mais motoristas pelo nome |
| **Grupo(s) de motoristas** | Selecione um ou mais grupos de motoristas cadastrados |
***
## Sequência e prioridade [#sequência-e-prioridade]
As automações são avaliadas em ordem crescente de **Sequência**. O primeiro conjunto de condições que corresponder ao pedido determina qual ação é executada.
Use o botão **Editar Sequência** para reordenar as automações via drag-and-drop.
***
## Ações por automação (menu ⋯) [#ações-por-automação-menu-]
| Ação | Descrição |
| ---------------------- | ---------------------- |
| **Editar** | Abre o modal de edição |
| **Ativar / Desativar** | Alterna a situação |
| **Excluir** | Remove permanentemente |
***
## Próximos passos [#próximos-passos]
* [**Como Usar**](/docs/go/products/automacoes-de-ofertas/como-usar/) — passo a passo para criar e gerenciar automações de ofertas.
***
## Conceitos relacionados [#conceitos-relacionados]
* [**Marcador**](/docs/go/conceitos/marcador/) — como marcadores de pedido e de motorista se integram às automações de oferta para segmentar a frota.
---
# Motoristas — Como Usar (/docs/go/products/motoristas/como-usar)
Guia prático para gerenciar a frota de motoristas no dia a dia.
***
## Fluxo típico [#fluxo-típico]
1. Acesse **Operação > Motoristas** (`/drivers`).
2. Use o campo de busca ou filtros para localizar um motorista existente.
3. Clique em **Novo motorista** para cadastrar um novo entregador.
4. Use o menu (⋮) para editar dados ou aplicar marcadores.
***
## Cadastrar um novo motorista [#cadastrar-um-novo-motorista]
1. Clique em **Novo motorista** no cabeçalho.
2. Preencha os campos obrigatórios: **Nome**, **Documento**, **Telefone** e **Filial(is)**.
3. Opcionalmente, adicione **Marcadores** para segmentar o motorista (ex.: "Moto", "Zona Sul").
4. Clique em **Salvar**.
***
## Editar um motorista [#editar-um-motorista]
1. Localize o motorista na tabela.
2. Clique no menu (⋮) > **Editar motorista**.
3. Atualize os campos necessários.
4. Clique em **Salvar**.
***
## Aplicar marcadores [#aplicar-marcadores]
Marcadores facilitam a segmentação para [Automações de Ofertas](/docs/go/products/automacoes-de-ofertas/):
1. Acesse **Configurações > Marcadores** para criar os marcadores de motorista desejados (ex.: "Van", "Moto", "Zona Norte").
2. No modal de edição do motorista, selecione os marcadores aplicáveis.
3. Nas Automações de Ofertas, use esses marcadores como critério de direcionamento.
***
## Vincular motorista a múltiplas filiais [#vincular-motorista-a-múltiplas-filiais]
Um motorista pode atender mais de uma filial. No campo **Filiais** do modal de edição, selecione todas as filiais às quais ele deve ter acesso.
***
## Excluir um motorista [#excluir-um-motorista]
1. No menu (⋮) > **Excluir motorista**.
2. Confirme a exclusão no modal.
***
## Boas práticas [#boas-práticas]
* Use nomes completos para evitar confusão entre motoristas.
* Aplique marcadores de zona geográfica para facilitar o direcionamento de automações.
* Mantenha o telefone atualizado — é pelo telefone que o motorista acessa o app.
* Revise periodicamente motoristas inativos e remova-os da lista para manter a base limpa.
---
# Motoristas — Visão Geral (/docs/go/products/motoristas)
A tela de **Motoristas** permite cadastrar, visualizar e gerenciar os entregadores que compõem a frota própria da transportadora.
***
## Onde acessar [#onde-acessar]
* **URL:** `https://dashboard.abbiamolog.com/drivers`
* **Menu:** seção **Operação** > **Motoristas**
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------------ | ------------------------------------------ |
| **Título** | "Motoristas" |
| **Novo motorista** | Abre o modal de cadastro de novo motorista |
### Barra de filtros [#barra-de-filtros]
* **Campo de busca** — Pesquisa por nome, documento ou telefone do motorista.
* **Botão atualizar** — Recarrega a lista manualmente.
* **Filtros avançados** — Nome, Documento, Filial, Marcadores, Situação.
* **Visibilidade de colunas** — Mostrar/ocultar colunas.
### Tabela de motoristas [#tabela-de-motoristas]
| Coluna | O que mostra |
| -------------- | ------------------------------------------- |
| **Nome** | Nome completo do motorista |
| **Documento** | CPF ou outro documento de identificação |
| **Telefone** | Contato principal |
| **Filiais** | Filiais às quais o motorista está vinculado |
| **Marcadores** | Tags coloridas aplicadas ao motorista |
| **Situação** | Ativo ou Inativo |
| **Criado em** | Data e hora de cadastro |
| **Ações** | Menu (⋮) com Ver, Editar e Excluir |
### Menu de ações por motorista (⋮) [#menu-de-ações-por-motorista-]
| Ação | Descrição |
| --------------------- | -------------------------- |
| **Ver motorista** | Abre modal somente leitura |
| **Editar motorista** | Abre modal de edição |
| **Excluir motorista** | Remove após confirmação |
***
## Modal de criação e edição [#modal-de-criação-e-edição]
### Campos [#campos]
| Campo | Obrigatório | Descrição |
| -------------- | ----------- | --------------------------------------------------------------------- |
| **Nome** | ✓ | Nome completo do motorista |
| **Documento** | ✓ | CPF ou outro documento |
| **Telefone** | ✓ | Número de contato (usado para acesso ao app) |
| **Filiais** | ✓ | Uma ou mais filiais às quais o motorista pertence |
| **Marcadores** | | Tags de motorista para segmentação (ex.: "Moto", "Van", "Zona Norte") |
***
## Grupos de motoristas [#grupos-de-motoristas]
Motoristas podem ser organizados em **grupos** para facilitar o direcionamento de ofertas de entrega. Os grupos são usados nas [Automações de Ofertas](/docs/go/products/automacoes-de-ofertas/).
Para criar grupos, acesse **Configurações > Marcadores** (seção Motoristas).
***
## Marcadores de motorista [#marcadores-de-motorista]
Marcadores são tags coloridas para segmentar motoristas por tipo de veículo, zona de atendimento ou qualquer critério relevante para a operação.
* Criados em [Configurações > Marcadores](/docs/go/settings/marcadores/)
* Aplicados no modal de edição do motorista
* Usados como condição nas [Automações de Ofertas](/docs/go/products/automacoes-de-ofertas/)
***
## Estado vazio [#estado-vazio]
Quando não há motoristas cadastrados:
> *"Nenhum motorista encontrado"*
***
## Próximos passos [#próximos-passos]
* [**Como usar**](/docs/go/products/motoristas/como-usar/) — cadastrar, editar e organizar motoristas no dia a dia.
* [**Automações de Ofertas**](/docs/go/products/automacoes-de-ofertas/) — definir quais motoristas recebem ofertas de entrega.
---
# Embarcadores — Como Usar (/docs/go/products/embarcadores/como-usar)
***
## Cadastrar um embarcador externo (manualmente) [#cadastrar-um-embarcador-externo-manualmente]
Use este fluxo quando o cliente **não usa o Abbiamo LOG** e você precisa registrá-lo manualmente.
1. Acesse **Produtos > Embarcadores**.
2. Clique em **Novo embarcador**.
3. Preencha os campos do formulário:
* **Nome** — nome do cliente ou empresa.
* **Identificador** — código interno para identificar o embarcador nas automações e relatórios.
* **Filiais** — adicione as filiais (pontos de coleta/origem) que essa conta vai usar.
4. Confirme e salve.
O embarcador aparece na lista com tipo **Externo** e já pode ter pedidos associados via API ou importação.
***
## Gerenciar um embarcador Abbiamo (vínculo automático) [#gerenciar-um-embarcador-abbiamo-vínculo-automático]
Quando o cliente usa o LOG e configura a integração com a sua operação, o vínculo aparece automaticamente. Não é necessário criá-lo.
O que você pode fazer:
* **Visualizar** os detalhes do embarcador e suas filiais.
* **Editar** configurações operacionais se necessário.
* **Associar Automações de Ofertas** específicas para as entregas desse embarcador.
***
## Configurar Automações de Ofertas por embarcador [#configurar-automações-de-ofertas-por-embarcador]
Para definir quais motoristas recebem as entregas de um embarcador específico:
1. Acesse **Produtos > Automações de Ofertas**.
2. Crie uma nova automação com:
* **Filial** do embarcador como condição.
* **Tipo de operação** correspondente.
* **Ação** (todos os motoristas, motoristas específicos ou grupo).
3. Ative a automação.
→ [Ver documentação de Automações de Ofertas](/docs/go/products/automacoes-de-ofertas/)
***
## Filtrar e buscar embarcadores [#filtrar-e-buscar-embarcadores]
* Use o **campo de busca** para localizar por nome ou identificador.
* Clique no embarcador para ver detalhes e as filiais vinculadas.
---
# Embarcadores (/docs/go/products/embarcadores)
A tela de **Embarcadores** lista os clientes para os quais a sua operação executa entregas. Um embarcador pode ser uma conta parceira que usa o **Abbiamo LOG** — onde o vínculo é criado automaticamente — ou um **cliente externo** cadastrado manualmente pelo agente GO, sem necessidade de conta na plataforma.
***
## Onde acessar [#onde-acessar]
* **URL:** `https://dashboard.abbiamolog.com/shippers`
* **Menu:** seção **Produtos** > **Embarcadores**
***
## O que você vê ao entrar [#o-que-você-vê-ao-entrar]
### Barra de filtros [#barra-de-filtros]
| Elemento | Descrição |
| ------------------- | ---------------------------------------------------------- |
| **Campo de busca** | Pesquisa por nome ou identificador do embarcador |
| **Novo embarcador** | Abre o formulário para cadastrar um embarcador manualmente |
| **Botão atualizar** | Recarrega a lista manualmente |
### Tabela de embarcadores [#tabela-de-embarcadores]
| Coluna | O que mostra |
| ----------------- | --------------------------------------------------------------- |
| **Nome** | Nome do embarcador |
| **Identificador** | Código único na plataforma |
| **Filiais** | Quantidade de filiais vinculadas à sua operação |
| **Tipo** | Abbiamo (integrado via LOG) ou Externo (cadastrado manualmente) |
| **Criado em** | Data de criação ou vínculo |
| **Ações** | Menu (⋮) com Ver, Editar e opções de gerenciamento |
***
## Tipos de embarcador [#tipos-de-embarcador]
### Embarcador Abbiamo (integração automática) [#embarcador-abbiamo-integração-automática]
O embarcador usa o **Abbiamo LOG**. Quando ele configura uma Integração de Transportadora apontando para a sua operação GO, o vínculo é criado automaticamente e os pedidos chegam direto ao painel.
```
Embarcador (LOG)
→ Configura integração de TRP apontando para seu GO
→ Aparece automaticamente em Embarcadores (GO)
→ Pedidos chegam em tempo real
```
### Embarcador Externo (cadastro manual) [#embarcador-externo-cadastro-manual]
O cliente **não usa a plataforma Abbiamo**. O agente GO cria o embarcador manualmente, configurando nome, identificador, filiais e as regras de operação. Os pedidos entram via API ou importação manual.
```
Agente GO
→ Cria embarcador manualmente
→ Configura filiais e parâmetros
→ Pedidos entram via API ou importação
```
***
## Relação com outras telas [#relação-com-outras-telas]
| Tela | Relação |
| --------------------------------------------------------------------- | --------------------------------------------------------------- |
| [**Rotas**](/docs/go/products/rotas/) | Entregas do embarcador são agrupadas em rotas |
| [**Motoristas**](/docs/go/products/motoristas/) | Recebem as entregas via oferta ou atribuição direta |
| [**Automações de Ofertas**](/docs/go/products/automacoes-de-ofertas/) | Define quais motoristas recebem ofertas por embarcador e filial |
→ Para entender o conceito de Embarcador no contexto GO, veja [**Conceito: Embarcador**](/docs/go/conceitos/embarcador/).
---
# Tela de Pedidos — Visão Geral (GO) (/docs/go/products/pedidos)
A tela de **Pedidos** no GO concentra a operação diária da transportadora: consulta, filtragem, acompanhamento de status e ações individuais por pedido — com foco nos pedidos recebidos dos seus [embarcadores](/docs/go/conceitos/embarcador/).
***
## Onde acessar [#onde-acessar]
* **URL principal:** [https://dashboard.abbiamolog.com/orders](https://dashboard.abbiamolog.com/orders)
* **Menu:** seção **Operação** > **Pedidos**
***
## O que você vê ao entrar [#o-que-você-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ---------------- | ------------------------------- |
| **Menu lateral** | Abre/fecha a sidebar |
| **Título** | "Pedidos" |
| **Criar pedido** | Abre fluxo de criação de pedido |
### Cards de status (topo) [#cards-de-status-topo]
No topo da tela, cards colapsáveis exibem a contagem de pedidos por status (Criado, Pendente, Despachado, Em Trânsito, etc.), permitindo uma visão rápida do estado geral da operação.
### Barra de filtros e controles [#barra-de-filtros-e-controles]
* **Busca de pedido** por NF, número do pedido e `external_id`
* **Atualizar lista** manualmente (botão de refresh)
* **Status** (multisseleção)
* **Entregue por** (transportadora/responsável da última entrega)
* **Período** (date range, até 93 dias)
* **Marcadores** (incluindo opção "Sem marcadores")
* **Grupo de embarcadores** — filtra por grupo de embarcadores
* **Embarcador** — filtra por embarcador específico
* **Filtros avançados** (filtro por campo)
* **Visibilidade de colunas** (mostrar/ocultar)
* **Exportar** (CSV da tabela atual)
### Tabela de pedidos [#tabela-de-pedidos]
Colunas principais disponíveis:
| Coluna | O que mostra |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| **Pedido** | Número do pedido |
| **ID Externo** | ID externo do pedido |
| **NF** | Número da nota fiscal |
| **Embarcador** | Nome do embarcador que originou o pedido, com indicação do grupo |
| **Tipo da entrega** | Entrega / Retirada / Reversa |
| **Criado em** | Data/hora de criação |
| **Atualizado em** | Tempo relativo desde última atualização |
| **Envios** | Quantidade de envios |
| **Status / Sub Status** | Situação atual do pedido (veja [Status de pedido](/docs/go/conceitos/status-de-pedido/)) |
| **Entregue por** | Responsável da última entrega |
| **Cliente** | Nome do cliente |
| **Chegada** | Data/hora de chegada |
| **Prazo prometido** | Data/hora prometida (quando aplicável) |
| **Frete pago** | Valor de frete |
| **Rastreio** | Código de rastreio |
| **Marcadores** | Tags aplicadas |
| **Indicadores** | Avaliação e comprovante |
| **Ações** | Menu de ações por pedido (⋮) |
### Interações de linha [#interações-de-linha]
* **Clique simples:** abre detalhes do pedido em side panel
* **Seleção múltipla:** habilita barra de ações em lote
### Paginação [#paginação]
* Tamanhos de página: **50, 100, 150, 200**
### Estado vazio [#estado-vazio]
Quando não há resultados:
> *"Nenhum pedido encontrado. Crie um novo agora mesmo"*
***
## Filtros avançados disponíveis [#filtros-avançados-disponíveis]
No menu de filtros avançados, os campos incluem:
* Pedido (`invoice.number`)
* NF (`invoice.invoice_number`)
* Nome do cliente (`customer.name`)
* Documento do cliente (`customer.document_number`)
* Tipo da entrega (`invoice.type`)
* Origem do pedido (`invoice.creation_origin`)
* Filial (`invoice.seller_id`)
* Tipo da operação (`invoice.operation`)
***
## Ações por pedido (menu ⋮) [#ações-por-pedido-menu-]
As opções variam por status e tipo do pedido.
### Ações comuns [#ações-comuns]
* **Ver rastreio**
* **Ver etiqueta**
* **Ver DANFE** (desabilita se o pedido não tiver NF/chave)
* **Duplicar pedido**
* **Anexar comprovantes** (somente quando status = `SUCCESSFUL`)
* **Editar marcadores**
* **Editar embarcador** — associar ou alterar o embarcador do pedido
### Ações condicionais [#ações-condicionais]
* **Finalizar retirada** (pedido TAKEOUT em `DISPATCHED` + substatus `READY_FOR_TAKEOUT`)
* **Solicitar coleta/reversa** (tipos DELIVERY/RETURN)
* **Reenviar pedido** (status elegíveis + tipo de entrega elegível)
* **Cancelar agendamento** (somente quando status = `SCHEDULED`)
***
## Status e substatus [#status-e-substatus]
Os status são os mesmos da plataforma Abbiamo, compartilhados entre LOG e GO. Consulte a referência completa em [Status de pedido](/docs/go/conceitos/status-de-pedido/).
***
## Comportamentos automáticos importantes [#comportamentos-automáticos-importantes]
* **Reset de paginação:** alterações de filtros voltam para a primeira página
* **Preservação de seleção:** seleção é reconciliada quando os dados mudam
* **Side panel por URL:** `order_id` em query string abre detalhes do pedido
* **Exportação local:** exporta CSV da visão atual da tabela (respeitando visibilidade de colunas)
---
# Pesquisa de Satisfação (CSAT) — Visão Geral (GO) (/docs/go/products/pesquisa-satisfacao)
A tela de **Pesquisas de Satisfação** exibe as avaliações enviadas pelos clientes após a entrega dos seus pedidos. As pesquisas são disparadas automaticamente pelo sistema e os resultados ficam disponíveis para consulta e análise.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/csat](https://dashboard.abbiamolog.com/csat)
* **Menu:** seção **Operação** > **Pesquisas de satisfação**
***
## Barra de filtros [#barra-de-filtros]
| Filtro | Descrição |
| ----------------------- | --------------------------------------------------------------------- |
| **Pesquisar avaliação** | Busca por pedido, cliente ou ID da avaliação |
| **Entregue por** | Filtra por transportadora que realizou a entrega |
| **Avaliação** | Filtra pela nota dada pelo cliente (ex.: todas, positivas, negativas) |
| **Período** | Intervalo de datas das avaliações |
***
## Configuração do disparo [#configuração-do-disparo]
As pesquisas de satisfação são configuradas na tela de [Notificações](/docs/go/settings/notificacoes/). O gatilho **"Pedido entregue + avaliação"** define quando o cliente recebe o link para avaliar a entrega.
***
## Estado vazio [#estado-vazio]
Quando não há avaliações no período selecionado:
> *"Nenhuma pesquisa de satisfação encontrada"*
***
## Paginação [#paginação]
* **Padrão:** 50 avaliações por página
* **Opções:** 50, 100, 150, 200
---
# Relatórios — Como Usar (/docs/go/products/relatorios/como-usar)
Guia prático de todas as ações disponíveis na página de Relatórios.
***
## Fluxo típico [#fluxo-típico]
1. Acessar **Relatórios** pelo menu lateral (`/reports`).
2. *(Opcional)* Consultar o **Dicionário** para entender o significado das colunas.
3. Clicar em **Novo relatório** → preencher tipo, formato, período, filiais e filtros → **Gerar relatório**.
4. Aguardar (a lista atualiza sozinha enquanto o status for "Na fila" ou "Processando").
5. Quando o status mudar para **Completo**, abrir o menu ⋮ → **Baixar relatório**.
6. Se precisar do mesmo relatório: ⋮ → **Gerar relatório novamente** (ajustar se necessário).
7. Para remover: ⋮ → **Excluir relatório** → confirmar no modal.
***
## Criar um novo relatório [#criar-um-novo-relatório]
Clique em **Novo relatório** no cabeçalho da página. O modal que abre tem os seguintes campos:
### Campos do formulário [#campos-do-formulário]
| Campo | Descrição |
| --------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Tipo do relatório** | Pedidos, Eventos, Envios, Integrações de Pedidos, Integrações de Transportadoras, Filiais ou CSAT |
| **Formato** | CSV ou JSON |
| **Período** | Data absoluta ou período dinâmico — máximo de **31 dias** (disponível para Pedidos, Eventos, Envios e CSAT) |
| **Filiais** | Seletor de filiais — mínimo 1 obrigatória |
Após preencher, clique em **Gerar relatório**. Um toast confirma o envio e a lista é atualizada automaticamente.
***
## Consultar o dicionário de colunas [#consultar-o-dicionário-de-colunas]
No cabeçalho, clique no ícone de **Dicionário** (ℹ). Escolha o idioma (**Português** ou **Inglês**) e o modal exibirá a descrição de todas as colunas de cada tipo de relatório.
Isso é útil para entender exatamente o que cada campo significa no arquivo exportado.
***
## Filtrar e buscar relatórios [#filtrar-e-buscar-relatórios]
### Busca rápida [#busca-rápida]
Use o campo de busca (placeholder "Nome do relatório") para filtrar a lista pelo nome.
### Filtros avançados [#filtros-avançados]
Clique no botão de filtros para abrir o painel e selecione:
* **Nome** — texto livre
* **Tipo do relatório** — Pedidos, Eventos, Envios, etc.
* **Formato** — CSV, JSON
* **Status** — Na fila, Processando, Completo, Falha, Expirado
### Controle de colunas [#controle-de-colunas]
Ao lado dos filtros, há o botão de **visibilidade de colunas**: permite mostrar ou ocultar colunas da tabela conforme sua necessidade.
***
## Ações na linha do relatório (menu ⋮) [#ações-na-linha-do-relatório-menu-]
Cada relatório na tabela possui um menu de ações à direita:
### Baixar relatório [#baixar-relatório]
| Situação | Comportamento |
| ------------------------------------- | ------------------------------------------------------- |
| Status **Na fila** ou **Processando** | Ícone de loading — aguarde a conclusão |
| Status **Completo** | Solicita a URL de download e abre o arquivo em nova aba |
| Status **Falha** ou **Expirado** | O download não estará disponível — gere novamente |
Um toast de carregamento/sucesso/erro aparece durante o processo.
### Gerar relatório novamente [#gerar-relatório-novamente]
Abre o mesmo modal de criação, já preenchido com o tipo, formato, filiais e período daquele relatório. Você pode ajustar os campos e clicar em **Gerar relatório** para criar um novo.
### Excluir relatório [#excluir-relatório]
Abre o modal de confirmação:
> *"Tem certeza que deseja excluir o relatório "Nome do relatório"?"*
* **Excluir**: remove o relatório da lista (soft delete) e atualiza a tabela.
* **Cancelar**: fecha o modal sem ação.
---
# Relatórios — Visão Geral (/docs/go/products/relatorios)
A página de **Relatórios** permite extrair, filtrar e baixar dados da sua operação logística em diversos formatos. É o ponto central para análise de pedidos, envios, eventos, integrações, filiais e pesquisa de satisfação.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/reports](https://dashboard.abbiamolog.com/reports)
* **Menu:** Na barra lateral (sidebar) do painel, o item **"Relatórios"** aparece com ícone de documento.
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ---------------------- | ------------------------------------------------------------------------------ |
| **Menu lateral duplo** | Botão para abrir/fechar a sidebar |
| **Título** | "Relatórios" |
| **Dicionário** | Abre o dicionário de colunas (PT ou EN), explicando cada coluna dos relatórios |
| **Novo relatório** | Abre o modal de criação de novo relatório |
### Área de filtros e busca [#área-de-filtros-e-busca]
* **Campo de busca:** filtra pelo nome do relatório.
* **Botão atualizar:** recarrega a lista manualmente.
* **Filtros avançados:**
* Nome
* Tipo do relatório
* Formato (CSV, JSON)
* Status (Na fila, Processando, Completo, Falha, Expirado)
* **Controle de colunas:** permite mostrar/ocultar colunas da tabela.
### Tabela de relatórios [#tabela-de-relatórios]
| Coluna | O que mostra |
| ------------- | ----------------------------------------------------- |
| **Nome** | Nome dado ao relatório |
| **Tipo** | Badge indicando a categoria (Pedidos, Eventos, etc.) |
| **Formato** | Ícone de CSV ou JSON |
| **Status** | Badge com o estado atual do relatório |
| **Filiais** | Chips das filiais incluídas ou "Todos" |
| **Criado em** | Data e hora de criação |
| **Ações** | Menu (⋮) com opções: baixar, gerar novamente, excluir |
### Paginação [#paginação]
No rodapé da tabela: tamanhos de página (50, 100, 150, 200) e navegação entre páginas.
### Estado vazio [#estado-vazio]
Se não houver relatórios ou nenhum resultado dos filtros, aparece a mensagem:
> *"Nenhum relatório encontrado, ainda... Crie um novo agora mesmo!"*
***
## Tipos de relatório [#tipos-de-relatório]
| Tipo | Descrição |
| ---------------------------------- | --------------------------------------------------------------------------------------- |
| **Pedidos (ORDERS)** | Dados completos dos pedidos — com filtros de período, filiais, transportadoras e status |
| **Eventos (EVENTS)** | Registros de eventos logísticos |
| **Envios (DELIVERIES)** | Dados dos envios realizados |
| **Integrações de Pedidos** | Informações das integrações de pedidos com sistemas externos |
| **Integrações de Transportadoras** | Dados das integrações com transportadoras |
| **Filiais (SELLERS)** | Dados cadastrais das filiais |
| **Pesquisa de Satisfação (CSAT)** | Respostas da pesquisa de satisfação — com filtro de período |
***
## Status do relatório [#status-do-relatório]
| Status | Significado |
| ---------------------------- | ------------------------------------------------------- |
| **Na fila (QUEUED)** | Aguardando processamento |
| **Processando (PROCESSING)** | O arquivo está sendo gerado com os filtros aplicados |
| **Completo (DONE)** | Pronto para download |
| **Falha (FAILED)** | Houve um erro na geração |
| **Expirado (EXPIRED)** | Não está mais disponível — gere novamente se necessário |
***
## Formatos disponíveis [#formatos-disponíveis]
| Formato | Observação |
| -------- | -------------------------------------------------------- |
| **CSV** | Formato padrão, compatível com Excel, Google Sheets etc. |
| **JSON** | Ideal para integrações e consumo programático |
***
## Comportamentos automáticos [#comportamentos-automáticos]
* **Polling de status:** relatórios recentes com status pendente são atualizados a cada 5 segundos (até 2 horas).
* **Filtros persistentes:** as condições de filtro são salvas no navegador por grupo de filiais e por página (`reports`). Ao retornar, os filtros permanecem como estavam.
* **Reset de paginação:** ao alterar texto de busca ou condições de filtro, a tabela volta para a primeira página.
***
## Próximos passos [#próximos-passos]
* [**Como usar**](/docs/go/products/relatorios/como-usar/) — passo a passo para criar, baixar, filtrar e excluir relatórios.
* [**Troubleshooting**](/docs/go/products/relatorios/troubleshooting/) — resolver divergências de datas, timezone e problemas de status.
---
# Relatórios — Troubleshooting (/docs/go/products/relatorios/troubleshooting)
Este guia auxilia na resolução de dúvidas sobre os dados extraídos nos relatórios de **Pedidos**, **Eventos**, **Envios**, **Filiais**, **Integrações** e **CSAT**.
## 1. Comportamento global de datas (timezone) [#1-comportamento-global-de-datas-timezone]
Uma dúvida comum é a diferença de horários entre o painel web e o arquivo exportado. Esta funcionalidade é nativa da plataforma para garantir a precisão logística local.
### No painel (web) [#no-painel-web]
Os dados são exibidos no padrão **UTC**, identificado pelo `"Z"` no final da string (ex.: `2026-02-13T16:18:19.000Z`).
### No relatório (CSV/JSON) [#no-relatório-csvjson]
O sistema detecta o **fuso horário da sua máquina** (ex.: `America/Sao_Paulo` -03:00) e converte automaticamente todas as datas para este fuso no momento da exportação.
**Exemplo:** Um pedido criado às 16:00 no painel (UTC) aparecerá como **13:00** no seu relatório (horário de Brasília).
## 2. Colunas afetadas por tipo de relatório [#2-colunas-afetadas-por-tipo-de-relatório]
Abaixo estão os principais campos de data que sofrem essa conversão automática em cada categoria:
| Tipo de relatório | Colunas de data convertidas (exemplos) |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Pedidos (ORDERS)** | `data_de_entrega`, `data_de_atualizacao`, `data_de_criacao_do_pedido`, `data_de_emissao_da_nf`, `data_de_processamento_do_embarcador` |
| **Eventos (EVENTS)** | `data_de_criacao_do_evento`, `data_em_que_o_evento_ocorreu`, `data_prevista_de_finalizacao_do_envio` |
| **Envios (DELIVERIES)** | `delivery_created_at`, `delivered_delivery_date`, `delivery_expected_delivery_date`, `delivery_eta_updated_at` |
| **CSAT** | `answered_at` (data de resposta), `invoice_issued_at` (emissão de NF) |
| **Integrações** | `carrier_integration_created_at`, `order_integration_updated_at` |
## 3. Checklist de verificação [#3-checklist-de-verificação]
Se os horários não estiverem batendo conforme o esperado, siga estes passos:
### Verifique a mensagem de aviso [#verifique-a-mensagem-de-aviso]
Ao gerar um **Novo Relatório**, a plataforma exibe um alerta:
> *"Identificamos que você está no fuso horário \[Seu Fuso]. Todos os campos de data e hora serão exportados neste fuso."*
Confirme se o fuso detectado é o correto.
### Origem da extração [#origem-da-extração]
### Configuração da filial [#configuração-da-filial]
Alguns relatórios de **Filiais (SELLERS)** possuem campos específicos de `fuso_horario_da_filial` e `seller_timezone`. Certifique-se de que a configuração da filial no cadastro condiz com a região física dela.
## 4. Status do processamento [#4-status-do-processamento]
Caso o relatório não esteja disponível imediatamente, verifique a coluna **Status** na tela de relatórios:
| Status | Significado |
| ---------------------------- | -------------------------------------------------------------------------------- |
| **NA FILA (QUEUED)** | Aguardando processamento. |
| **PROCESSANDO (PROCESSING)** | O arquivo está sendo gerado com os filtros aplicados. |
| **COMPLETO (DONE)** | Pronto para download. |
| **EXPIRADO (EXPIRED)** | Relatórios antigos são removidos periodicamente; gere-o novamente se necessário. |
## 5. Formato XLSX não disponível [#5-formato-xlsx-não-disponível]
O formato **XLSX** não é suportado atualmente. Os formatos disponíveis para exportação são **CSV** e **JSON**.
Se você precisa de um arquivo `.xlsx`, exporte em **CSV** e abra no Excel ou Google Sheets — a conversão é automática ao abrir o arquivo.
---
# Tela de Rotas — Como Usar (/docs/go/products/rotas/como-usar)
Guia prático das principais ações para operar rotas de entrega no dia a dia.
***
## Fluxo típico [#fluxo-típico]
1. Acesse **Operação > Rotas** (`/routes`).
2. Defina período, status e tipo de transportadora para trazer a visão correta.
3. Use filtros avançados para localizar rotas por motorista, número de pedido ou status de entrega.
4. Clique em uma rota para abrir o painel lateral com detalhes, lista de entregas e mapa.
5. Use o menu ⋮ para executar ações individuais na rota.
6. Para criar uma nova rota, clique em **Nova rota** no cabeçalho.
***
## Filtrar e localizar rotas [#filtrar-e-localizar-rotas]
### Filtros principais [#filtros-principais]
* **Status** — filtre por CRIADA, EM EXECUÇÃO, CANCELADA, PEDIDOS CONCLUÍDOS ou FINALIZADA
* **Entregue por** — filtre por frota própria ou transportadoras integradas
* **Período** — janela de datas (padrão: últimos 7 dias)
* **Filtros avançados** — nome da rota, motorista, documento, pedido e status de entrega
***
## Acompanhar uma rota [#acompanhar-uma-rota]
Clique em qualquer linha da tabela para abrir o painel lateral com:
* Lista de entregas e status individual de cada uma
* Motorista responsável
* Visualização do trajeto no mapa
A URL é atualizada com `?route_id=` — você pode compartilhar ou copiar o link para abrir diretamente a rota em questão.
***
## Ações por rota [#ações-por-rota]
### Atribuir ou trocar motorista [#atribuir-ou-trocar-motorista]
Disponível quando a rota está nos status **CRIADA** ou **EM EXECUÇÃO**, desde que nenhuma entrega esteja com status de sucesso ou falha.
1. Abra o menu ⋮ da rota.
2. Clique em **Atribuir motorista** ou **Trocar motorista**.
3. Selecione o motorista desejado (deve pertencer ao seller group da rota).
4. Confirme.
### Solicitar coleta [#solicitar-coleta]
Disponível quando a rota ainda não tem motorista atribuído e todos os pedidos pertencem a uma única filial. Acionar essa opção encaminha a rota para uma transportadora integrada.
### Duplicar rota [#duplicar-rota]
Cria uma nova rota com os mesmos pedidos e configurações. Disponível para a maioria dos status, exceto **EM EXECUÇÃO** e **PEDIDOS CONCLUÍDOS**.
### Cancelar rota [#cancelar-rota]
***
## Criar uma rota [#criar-uma-rota]
### Como acessar [#como-acessar]
Clique em **Nova rota** no canto superior direito da tela de Rotas. A URL muda para `/routes/create`.
### Layout da tela [#layout-da-tela]
A tela de criação é dividida em **dois painéis simultâneos**:
| Painel | O que contém |
| ------------ | -------------------------------------------------------------------- |
| **Esquerdo** | Modo de criação, campos de configuração e mapa com prévia do trajeto |
| **Direito** | Tabela de pedidos disponíveis para seleção, com filtros |
### Modos de criação [#modos-de-criação]
| Modo | Quando usar |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Frota Própria** | A entrega será feita por motoristas próprios. Você configura motorista, armazém de início e, opcionalmente, armazém de fim. |
| **Transportadora** | A entrega será terceirizada via transportadora integrada. Você seleciona a filial, o método de entrega e se o veículo deve retornar ao depósito. |
***
### Campos — Frota Própria [#campos--frota-própria]
| Campo | Obrigatório | Observações |
| ---------------------------- | ----------- | ------------------------------------------------------------------------------------ |
| **Motorista** | Não | Se não informado na criação, pode ser atribuído depois pelo menu ⋮ na lista de rotas |
| **Início da Rota** (armazém) | Sim | Define o ponto de partida. Deve pertencer ao seller group |
| **Fim da Rota** (armazém) | Não | Define o ponto de retorno. Se omitido, a rota não terá destino final configurado |
### Campos — Transportadora [#campos--transportadora]
| Campo | Obrigatório | Observações |
| ----------------------- | ----------- | ---------------------------------------------------------------------------- |
| **Filial** | Sim | Filial de origem dos pedidos |
| **Método** | Sim | Modalidade ou serviço da transportadora integrada |
| **Retorno obrigatório** | Não | Toggle que exige o retorno do veículo ao depósito de origem após as entregas |
***
### Selecionar pedidos [#selecionar-pedidos]
No painel direito, use os filtros para localizar e selecionar os pedidos a incluir na rota:
* **Busca** por número do pedido, nome do cliente ou filial
* **Marcadores** — filtre por tags aplicadas aos pedidos
* **Filial** — filtre por filial de origem
* **Período** — ajuste o intervalo de datas
* **Filtros avançados** — opções adicionais de filtragem
***
### Sugerir rota e prévia [#sugerir-rota-e-prévia]
| Ação | O que faz |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sugerir rota** | Consulta o serviço de roteirização (Mapbox) para calcular a sequência otimizada de entregas. Requer armazém de início selecionado e ao menos um pedido escolhido. |
| **Prévia de rota** | Exibe o trajeto calculado no mapa à esquerda antes de confirmar a criação. |
### Confirmar criação [#confirmar-criação]
Após configurar a rota e selecionar os pedidos, clique em **Criar Rota** (botão no canto inferior direito). O sistema valida os dados e cria a rota. Você é redirecionado de volta para a tela de listagem.
***
### Validações e restrições [#validações-e-restrições]
### Erros durante a criação [#erros-durante-a-criação]
| Código | O que significa |
| ----------------------------------------------- | ------------------------------------------------------------------------------- |
| `ORDERS_NOT_ROUTEABLE` | Um ou mais pedidos selecionados não estão em status roteável |
| `DIFFERENT_SELLER_IDS` | Pedidos de seller groups diferentes foram incluídos na seleção |
| `COULD_NOT_SUGGEST_ROUTE_WITH_MUST_HAVE_ORDERS` | O otimizador não conseguiu incluir todos os pedidos obrigatórios na sugestão |
| `COULD_NOT_SUGGEST_ROUTE_WITH_CURRENT_CONFIG` | A configuração atual (armazéns, pedidos) não permite gerar uma sugestão de rota |
***
## Boas práticas operacionais [#boas-práticas-operacionais]
* Verifique o **status dos pedidos** antes de selecioná-los — apenas pedidos em status roteável podem ser incluídos.
* Defina o **armazém de início** antes de usar **Sugerir rota** — ele é o ponto de partida do cálculo.
* Use **Prévia de rota** para validar visualmente o trajeto antes de confirmar.
* Se o motorista não estiver disponível no momento da criação, deixe o campo em branco e atribua depois pelo menu ⋮ na listagem.
***
## Próximos passos [#próximos-passos]
* [**Troubleshooting**](/docs/go/products/rotas/troubleshooting/) — botão desabilitado, erros de criação e outros problemas comuns.
---
# Tela de Rotas — Visão Geral (/docs/go/products/rotas)
A tela de **Rotas** concentra a operação diária de entregas com frota própria ou transportadoras: visualização de status, atribuição de motoristas, criação e acompanhamento de todas as rotas ativas.
***
## Onde acessar [#onde-acessar]
* **URL principal:** [https://dashboard.abbiamolog.com/routes](https://dashboard.abbiamolog.com/routes)
* **Menu:** seção **Operação** > **Rotas**
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------- | ------------------------------------------------- |
| **Título** | "Rotas" |
| **Nova rota** | Abre a tela de Criação de Rota (`/routes/create`) |
### Barra de filtros [#barra-de-filtros]
* **Pesquisar** — busca por nome da rota ou número do pedido
* **Atualizar lista** — botão de refresh manual
* **Status** (multisseleção) — ver seção [Status de rota](#status-de-rota) para os valores disponíveis
* **Entregue por** (multisseleção) — frota própria e transportadoras integradas configuradas na conta
* **Período** (date range, padrão: últimos 7 dias, máximo 93 dias)
* **Filtros avançados** — ver seção dedicada abaixo
* **Visibilidade de colunas** — ícone de ajuste para mostrar/ocultar colunas
### Tabela de rotas [#tabela-de-rotas]
| Coluna | O que mostra |
| ------------------ | ------------------------------------------------------------------------------- |
| **ID** | Identificador único da rota (exibido com até 12 caracteres + botão de copiar) |
| **Nome da Rota** | Nome externo da rota (`external_name`), gerado automaticamente se não informado |
| **Status** | Badge colorido com o status atual da rota |
| **Entregas** | Contagem total + blocos visuais por status com os números dos pedidos |
| **Responsável** | Avatar e nome do motorista atribuído, ou "Não atribuído" |
| **Criado em** | Data e hora de criação (formato dd/MM/yy HH:mm) |
| **Custo** | Custo da rota em BRL (quando informado) |
| **Distância** | Distância esperada em km |
| **Tempo estimado** | Tempo esperado no formato HH:mm |
| **Ações** | Menu suspenso (⋮) com ações individuais por rota |
### Interações de linha [#interações-de-linha]
* **Clique simples:** abre o painel lateral da rota (adiciona `?route_id=` à URL)
### Paginação [#paginação]
* Tamanhos de página: **50** (padrão)
### Estado vazio [#estado-vazio]
Quando não há rotas para os filtros aplicados:
> *"Nenhuma rota encontrada. Crie uma rota agora mesmo"*
***
## Filtros avançados disponíveis [#filtros-avançados-disponíveis]
| Campo | Tipo |
| -------------------------- | ------------- |
| **Nome da rota** | Texto |
| **Nome do motorista** | Texto |
| **Sobrenome do motorista** | Texto |
| **Documento do motorista** | Texto |
| **Pedido de entrega** | Texto |
| **Status da entrega** | Multisseleção |
***
## Ações por rota (menu ⋮) [#ações-por-rota-menu-]
As opções variam conforme o status da rota.
| Ação | Disponibilidade |
| ------------------------------- | --------------------------------------------------------------------------------- |
| **Ver rota** | Sempre disponível |
| **Atribuir / Trocar motorista** | Status **CRIADA** ou **EM EXECUÇÃO**, sem entregas com status de sucesso ou falha |
| **Solicitar coleta** | Rota sem motorista atribuído e com pedidos de uma única filial |
| **Duplicar rota** | Indisponível para **EM EXECUÇÃO** e **PEDIDOS CONCLUÍDOS** |
| **Exportar CSV** | Disponível para contas habilitadas |
| **Cancelar rota** | Ação destrutiva e irreversível |
***
## Status de rota [#status-de-rota]
| Status | Descrição |
| ---------------------- | -------------------------------------------------------------- |
| **CRIADA** | Rota criada e aguardando início pelo motorista |
| **EM EXECUÇÃO** | Motorista iniciou o deslocamento e está realizando as entregas |
| **CANCELADA** | Rota cancelada — pedidos retornam ao estado pendente |
| **PEDIDOS CONCLUÍDOS** | Todos os waypoints da rota foram finalizados |
| **FINALIZADA** | Rota encerrada pelo sistema |
***
## Painel lateral da rota [#painel-lateral-da-rota]
Ao clicar em uma rota (ou usar "Ver rota" no menu ⋮), um painel lateral exibe:
* Lista de entregas com status individual
* Motorista responsável e dados do veículo
* Visualização do trajeto no mapa
A URL é atualizada com `?route_id=`, permitindo compartilhar ou favoritar o estado diretamente.
***
## Comportamentos automáticos importantes [#comportamentos-automáticos-importantes]
* **Reset de paginação:** alterações de filtro voltam para a primeira página
* **Side panel por URL:** `?route_id=` na query string abre automaticamente o painel lateral da rota correspondente
* **Exportação CSV:** respeita os filtros ativos no momento da exportação (disponível para contas habilitadas)
***
## Próximos passos [#próximos-passos]
* [**Como usar**](/docs/go/products/rotas/como-usar/) — passo a passo para criar, filtrar, acompanhar e gerenciar rotas.
---
# Tela de Rotas — Troubleshooting (/docs/go/products/rotas/troubleshooting)
Problemas mais comuns na tela de Rotas e como resolvê-los.
***
## Botão "Criar Rota" está desabilitado [#botão-criar-rota-está-desabilitado]
O botão fica bloqueado enquanto algum campo obrigatório não estiver preenchido. A tela exibe a razão no próprio botão ou próximo a ele.
### Frota Própria [#frota-própria]
| Mensagem exibida | Causa | O que fazer |
| --------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------- |
| *Nenhum pedido foi selecionado* | Nenhum pedido marcado no painel direito | Selecione ao menos 1 pedido na tabela |
| *Nenhum inicio de rota foi selecionada* | Campo **Início da Rota** vazio | Escolha um armazém de início |
| *Nenhum motorista foi selecionado* | Campo **Motorista** vazio | Selecione um motorista ou deixe para atribuir depois pelo menu ⋮ na listagem |
### Transportadora [#transportadora]
| Mensagem exibida | Causa | O que fazer |
| ---------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
| *Nenhum pedido foi selecionado* | Nenhum pedido marcado | Selecione ao menos 1 pedido na tabela |
| *Nenhuma filial foi selecionada* | Campo **Filial** vazio | Selecione a filial de origem |
| *Nenhum método foi selecionado* | Campo **Método** vazio | Escolha o método/modalidade da transportadora |
| *Carregando informações da filial...* | Dados do armazém ainda carregando | Aguarde alguns segundos e tente novamente |
| *Nenhum warehouse encontrado para esta filial* | A filial selecionada não tem armazém cadastrado | Verifique se a filial possui um armazém configurado em **Configurações > Filiais** |
***
## Erros ao clicar em "Criar Rota" [#erros-ao-clicar-em-criar-rota]
### Pedidos com problema [#pedidos-com-problema]
| Erro exibido | Causa | O que fazer |
| -------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| *Nenhum desses pedidos é roteirizável: \[números]* | Um ou mais pedidos selecionados estão em status que não permite roteamento | Volte ao painel de pedidos e remova os pedidos listados. Verifique o status de cada um — apenas pedidos em status roteável podem ser incluídos |
| *Nenhum desses pedidos foi encontrado: \[números]* | Os pedidos foram deletados ou alterados entre a seleção e o envio | Atualize a lista de pedidos e selecione novamente |
### Motorista com problema (Frota Própria) [#motorista-com-problema-frota-própria]
| Erro exibido | Causa | O que fazer |
| -------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| *Motorista (nome) não encontrado* | O motorista foi removido do sistema após ser selecionado | Selecione outro motorista ou cadastre o motorista novamente em **Motoristas** |
| *Motorista (nome) não associado a sua organização* | O motorista existe no sistema mas não pertence ao seu seller group | Verifique se o motorista está associado às filiais corretas. Consulte **Configurações > Motoristas** |
### Armazém com problema (Frota Própria) [#armazém-com-problema-frota-própria]
| Erro exibido | Causa | O que fazer |
| ----------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
| *Início da rota não encontrado* | O armazém de início foi removido após ser selecionado | Selecione outro armazém de início |
| *Fim da rota não encontrado* | O armazém de fim foi removido após ser selecionado | Selecione outro armazém de fim ou deixe em branco |
| *Armazém não associado a sua organização* | O armazém existe mas pertence a outro seller group | Verifique se o armazém está configurado corretamente para a sua conta |
### Erro genérico [#erro-genérico]
| Erro exibido | Causa provável | O que fazer |
| ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| *Erro ao criar rota, tente novamente mais tarde* | Falha no serviço de roteirização ou erro interno | Aguarde alguns minutos e tente novamente. Se o problema persistir, entre em contato com o suporte |
***
## "Sugerir rota" retorna erro ou não funciona [#sugerir-rota-retorna-erro-ou-não-funciona]
| Erro / Sintoma | Causa | O que fazer |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| *Botão desabilitado* | Nenhum pedido selecionado ou armazém de início não definido | Selecione ao menos 1 pedido e defina o **Início da Rota** antes de sugerir |
| Pedidos de filiais diferentes | Todos os pedidos de uma sugestão precisam pertencer à mesma filial | Filtre os pedidos por filial no painel direito antes de sugerir a rota |
| *Não foi possível sugerir uma rota com a configuração atual* | O serviço de roteirização não encontrou um trajeto válido com os parâmetros informados | Tente alterar o armazém de início, remover pedidos com endereço inválido ou reduzir a quantidade de pedidos |
| *Não foi possível incluir todos os pedidos obrigatórios* | A otimização não conseguiu encaixar todos os pedidos marcados como obrigatórios em nenhuma rota viável | Reduza o número de pedidos ou desmarque alguns como obrigatórios |
| Sugestão ignorada / rota criada sem sequência | O serviço de roteirização está indisponível | A rota é criada normalmente, mas sem sequência otimizada. Tente sugerir novamente em alguns minutos |
***
## Pedidos não aparecem na lista de seleção [#pedidos-não-aparecem-na-lista-de-seleção]
| Sintoma | Causa provável | O que fazer |
| ------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Pedido existe em **Pedidos** mas não aparece aqui | Pedido não está em status roteável | Verifique o status do pedido na tela de **Pedidos**. Pedidos em status `SUCCESSFUL`, `FAILED`, `CANCELED` ou similares não são roteáveis |
| Lista vazia mesmo com pedidos ativos | Período selecionado muito restrito | Amplie o intervalo de datas no filtro de período do painel de pedidos |
| Pedido de outra filial não aparece | Filial filtrada no painel direito | Remova o filtro de **Filial** ou selecione a filial correta |
***
## Rota criada não aparece na listagem [#rota-criada-não-aparece-na-listagem]
| Sintoma | Causa | O que fazer |
| ----------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------- |
| Rota recém-criada não está visível | O período padrão (últimos 7 dias) pode não incluir a rota | Verifique a data de criação e ajuste o período nos filtros |
| Filtro de status excluindo a rota | Status **CRIADA** foi desmarcado nos filtros | Marque o status **CRIADA** no filtro de **Status** |
| Rota visível para um usuário mas não para outro | Filtro de **Entregue por** aplicado diferente | Verifique se o filtro de **Entregue por** está configurado igual para ambos |
***
## Ação "Atribuir motorista" indisponível no menu ⋮ [#ação-atribuir-motorista-indisponível-no-menu-]
| Causa | O que fazer |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| Rota não está em status **CRIADA** ou **EM EXECUÇÃO** | Não é possível trocar motorista após a rota ser finalizada ou cancelada |
| Uma ou mais entregas já foram finalizadas (sucesso ou falha) | A rota já tem ocorrências registradas — não é possível trocar o motorista neste ponto |
| Usuário sem permissão para esta ação | Solicite acesso ao administrador da conta |
---
# Tabela de Ofertas — Como Usar (/docs/go/products/tabela-de-ofertas/como-usar)
***
## Antes de começar [#antes-de-começar]
Para uma Tabela de Ofertas realmente precificar as rotas, você vai precisar de:
1. **Marcadores de motorista** já criados — veja [Marcadores](/docs/go/settings/marcadores/).
2. Os motoristas certos **com esse marcador aplicado** no cadastro — veja [Motoristas](/docs/go/products/motoristas/).
3. As **filiais** que a tabela vai cobrir.
***
## Criar uma Tabela de Ofertas [#criar-uma-tabela-de-ofertas]
1. Acesse **Tabelas de frete** e abra a aba **Tabela de Ofertas**.
2. Clique em **Nova tabela** (botão no topo da tela).
3. Preencha o formulário:
### 1. Nome da tabela [#1-nome-da-tabela]
Um nome descritivo que ajude a identificar a tabela na lista (ex.: **"Ofertas Moto — CD Pinheiros"**).
### 2. Tarifa por km [#2-tarifa-por-km]
Valor pago por quilômetro rodado na rota.
### 3. Bônus por parada [#3-bônus-por-parada]
Valor adicional por cada parada **além da primeira**. Numa rota de 4 paradas, o bônus é aplicado 3 vezes.
### 4. Preço por coleta [#4-preço-por-coleta]
Base que o motorista recebe por **filial coletada** — ele já começa ganhando esse valor só por fazer a coleta. Em rotas de uma única filial, entra uma vez; coletando em várias filiais, multiplica pelo número de filiais.
### 5. Marcadores [#5-marcadores]
Selecione um ou mais **marcadores de motorista**. Só os motoristas que tiverem esse marcador serão precificados por esta tabela.
### 6. Filiais [#6-filiais]
Selecione **uma ou mais filiais** em que a oferta se aplica (mínimo 1). Uma mesma filial pode ter mais de uma tabela, desde que os marcadores sejam diferentes.
4. Clique em **salvar**.
***
## Editar uma tabela [#editar-uma-tabela]
No **menu ⋯** da tabela, clique em **Editar**. Os campos são os mesmos da criação (nome, valores, marcadores e filiais). As alterações valem para as **próximas** ofertas — rotas já criadas mantêm o valor com que foram fechadas.
***
## Duplicar uma tabela [#duplicar-uma-tabela]
No **menu ⋯**, use **Duplicar** para partir de uma tabela existente. O formulário abre já preenchido com os valores, marcadores e filiais da original, e é salvo como uma **nova** tabela. Útil para criar variações (ex.: mesma tarifa, outra filial).
***
## Excluir uma tabela [#excluir-uma-tabela]
No **menu ⋯**, clique em **Excluir**. A tabela e seus marcadores são removidos e ela deixa de precificar novas rotas.
***
## Conferir se está valendo [#conferir-se-está-valendo]
Depois de configurar, valide com um motorista de teste que tenha o marcador da tabela e esteja vinculado à filial:
1. Dispare ofertas para a filial coberta pela tabela.
2. No app do motorista, os cards de oferta **não** mostram preço de frete por pedido.
3. Ao selecionar os pedidos, o rodapé **"Você recebe R$ X"** exibe o total da rota.
Se o preço não aparecer, veja o [Troubleshooting](/docs/go/products/tabela-de-ofertas/troubleshooting/).
---
# Tabela de Ofertas — Visão Geral (/docs/go/products/tabela-de-ofertas)
A **Tabela de Ofertas** define a **precificação por rota** do GO: em vez de o motorista ganhar o valor de frete de cada pedido isolado, ele é remunerado pela **rota inteira** que monta a partir das ofertas — considerando a distância percorrida, o número de paradas e as coletas feitas.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/shipping-tables/offers](https://dashboard.abbiamolog.com/shipping-tables/offers)
* **Menu:** **Tabelas de frete** > aba **Tabela de Ofertas**
A tela fica ao lado das tabelas de frete por **Raio** e por **CEP** — a Tabela de Ofertas é a aba dedicada à precificação por rota.
***
## Como o valor é calculado [#como-o-valor-é-calculado]
O valor que o motorista recebe pela rota é a soma de três componentes, todos definidos na tabela:
| Componente | O que representa |
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Tarifa por km** | Valor por quilômetro rodado na rota |
| **Bônus por parada** | Valor adicional por cada parada **além da primeira** |
| **Preço por coleta** | Base que o motorista recebe por **filial coletada** — ele já começa ganhando esse valor só por fazer a coleta |
**Fórmula:**
```
Total da rota = Tarifa por km × distância da rota
+ Bônus por parada × (nº de paradas − 1)
+ Preço por coleta × nº de filiais coletadas
```
***
## Quem recebe o preço da tabela [#quem-recebe-o-preço-da-tabela]
Uma Tabela de Ofertas só se aplica quando **dois** critérios batem:
| Critério | Como se define |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Marcadores** | O motorista precisa ter um dos **marcadores de motorista** vinculados à tabela. É por aí que você segmenta a frota (ex.: uma tabela para motos, outra para carros). |
| **Filiais** | A tabela cobre uma ou mais **filiais**. A rota só é precificada se **todas** as suas filiais estiverem cobertas pela mesma tabela. |
Veja [Marcadores](/docs/go/settings/marcadores/) para criar e aplicar marcadores de motorista, e [Filiais](/docs/go/settings/filiais/) para as unidades operacionais.
***
## Colunas da lista [#colunas-da-lista]
| Coluna | O que mostra |
| ------------------ | --------------------------------------------------------------- |
| **Filiais** | Filiais cobertas pela tabela |
| **Tipo de tabela** | Sempre "Tabela de Ofertas" (diferencia das tabelas de Raio/CEP) |
| **Tarifa / km** | Valor por quilômetro |
| **Bônus / parada** | Valor por parada adicional |
| **Preço / coleta** | Valor base por filial coletada |
| **Criado em** | Data e hora de criação |
| **Atualizado em** | Data e hora da última alteração |
| **Menu (⋯)** | Ações da tabela (editar, duplicar, excluir) |
***
## Como o motorista vê no app [#como-o-motorista-vê-no-app]
Quando as ofertas de um pedido usam precificação por rota, o app do motorista muda o comportamento:
* **O preço de frete por pedido some** dos cards de oferta — o que passa a valer é o **total da rota**.
* Ao selecionar os pedidos, o motorista vê o rodapé **"Você recebe R$ X"** com o valor da rota calculado pela tabela, **antes de aceitar**.
* Pode haver um **número mínimo de pedidos por rota** (definido na configuração de [Operação](/docs/go/settings/operacao/) da conta). Abaixo do mínimo, o app avisa quantos pedidos ainda faltam.
* Não é possível **misturar** pedidos com preço de rota e pedidos avulsos na mesma rota — o app bloqueia e avisa, do mesmo jeito que impede misturar pedidos de filiais diferentes.
* Se a loja **cancelar um pedido antes da coleta**, o app **recalcula** o valor da rota com os pedidos que sobraram e mostra um aviso com o **novo valor** — o motorista pode **continuar a coleta** por esse valor ou **cancelar a rota**.
O rodapé
"Você recebe R$ X"
mostra o total da rota; abaixo do mínimo, o app avisa quantos pedidos ainda faltam.
Quando um pedido é
cancelado antes da coleta
, o app mostra o novo valor da rota e deixa o motorista continuar ou cancelar.
***
## Próximos passos [#próximos-passos]
* [**Como Usar**](/docs/go/products/tabela-de-ofertas/como-usar/) — passo a passo para criar, editar e duplicar uma Tabela de Ofertas.
* [**Troubleshooting**](/docs/go/products/tabela-de-ofertas/troubleshooting/) — por que o preço de rota não está aparecendo.
***
## Conceitos relacionados [#conceitos-relacionados]
* [**Oferta de Motorista**](/docs/go/conceitos/oferta-motorista/) — como o GO distribui pedidos para a frota via oferta.
* [**Marcador**](/docs/go/conceitos/marcador/) — tags de motorista que segmentam quem recebe cada tabela.
* [**Rota**](/docs/go/conceitos/rota/) — agrupamento de pedidos que o motorista executa e que é precificado pela tabela.
* [**Automações de Ofertas**](/docs/go/products/automacoes-de-ofertas/) — definem quais motoristas recebem as ofertas que depois viram rota.
---
# Tabela de Ofertas — Troubleshooting (/docs/go/products/tabela-de-ofertas/troubleshooting)
A oferta chegou no app do motorista, mas **sem preço de rota** (o card ainda mostra o frete por pedido, ou o rodapé "Você recebe" não aparece). Percorra a lista abaixo na ordem — as causas estão da mais comum para a menos comum.
***
## 1. O motorista não tem o marcador da tabela [#1-o-motorista-não-tem-o-marcador-da-tabela]
A tabela só precifica motoristas que carregam um dos **marcadores** vinculados a ela. Confirme, no cadastro do motorista ([Motoristas](/docs/go/products/motoristas/)), que ele tem exatamente o marcador que está na tabela.
***
## 2. A filial do pedido não está na tabela [#2-a-filial-do-pedido-não-está-na-tabela]
A tabela cobre um conjunto de **filiais**. Uma rota só é precificada se **todas** as filiais dela estiverem na mesma tabela.
* Confira se a filial do pedido está entre as **Filiais** da tabela.
* Em rotas que juntam pedidos de **várias** filiais, todas precisam estar cobertas pela mesma tabela — senão a rota cai no preço por pedido.
***
## 3. A tabela está inativa ou foi excluída [#3-a-tabela-está-inativa-ou-foi-excluída]
Só tabelas **ativas** precificam. Verifique na aba **Tabela de Ofertas** se a tabela existe e está ativa. Se foi excluída, recrie-a.
***
## 4. A oferta foi criada antes da configuração [#4-a-oferta-foi-criada-antes-da-configuração]
O valor da precificação é **calculado no momento em que a oferta é criada** e fica "congelado" naquela oferta. Se você marcou o motorista, criou a tabela ou ajustou a filial **depois** que a oferta já tinha sido disparada, aquela oferta antiga continua sem preço de rota.
**O que fazer:** dispare **novas** ofertas depois de terminar toda a configuração. As ofertas antigas não são reprecificadas.
***
## 5. Preço de rota não some / mínimo de pedidos [#5-preço-de-rota-não-some--mínimo-de-pedidos]
| Sintoma | Causa | O que fazer |
| -------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| App pede para **selecionar mais pedidos** | A conta define um **mínimo de pedidos por rota** | Selecione até atingir o mínimo indicado. Ajuste o mínimo em [Operação](/docs/go/settings/operacao/) |
| Não consigo **misturar** pedidos | Um pedido tem preço de rota e outro é avulso | Monte a rota só com pedidos de preço de rota **ou** só com avulsos — não misture |
| Card mostra **preço por pedido** ao invés do total | A oferta não é elegível a preço de rota (causas 1 a 4) | Reveja marcador, filial e tabela acima |
***
## 6. O app não atualizou [#6-o-app-não-atualizou]
Se toda a configuração está correta e a oferta é nova, mas o app ainda não mostra o preço de rota, o dispositivo pode estar com uma **versão desatualizada** do app. Feche e reabra o app para forçar a atualização; se persistir, confirme com o suporte se o app está na versão que suporta precificação por rota.
***
## Conceitos relacionados [#conceitos-relacionados]
* [**Tabela de Ofertas — Visão Geral**](/docs/go/products/tabela-de-ofertas/) — o que é e como o valor é calculado.
* [**Marcador**](/docs/go/conceitos/marcador/) — como os marcadores de motorista definem quem recebe cada tabela.
* [**Oferta de Motorista**](/docs/go/conceitos/oferta-motorista/) — o pré-requisito de vínculo com a filial, avaliado antes da precificação.
---
# Transportadora (/docs/log/integrations/transportadora)
---
# Uber Integration (/docs/log/integrations/transportadora/uber)
Ao utilizar a API da Abbiamo para solicitar coleta de pedidos via **Uber**, alguns erros de validação podem ocorrer no momento da criação do pedido. Abaixo, detalhamos o erro mais recorrente e como corrigi-lo.
## 1. Erro: `dropoff phone number is not valid` [#1-erro-dropoff-phone-number-is-not-valid]
Este é o erro principal retornado pela Uber quando os dados de contato do cliente (destinatário) não estão em conformidade com os padrões internacionais exigidos pela plataforma deles.
### Por que isso acontece? [#por-que-isso-acontece]
O motor de validação da Uber exige que o telefone seja composto pela combinação correta do **DDI (Código do País)** e o **Número com DDD**. O erro geralmente ocorre por dois motivos:
1. **DDD no campo errado**: O usuário preenche o `phone_country_code` com o DDD (ex: 11) em vez do código do país (Brasil = 55).
2. **Formato inconsistente**: O campo `phone` contém caracteres especiais ou o código do país duplicado.
### Como corrigir [#como-corrigir]
No objeto `customer` da sua chamada à API [Create Order V2](/docs/api/orders/create-order-v2), certifique-se de seguir este padrão:
* **`phone_country_code`**: Deve ser estritamente o código do país (ex: `"55"`).
* **`phone`**: Deve conter apenas números, iniciando pelo DDD (ex: `"11999999999"`).
#### Exemplo de payload incorreto [#exemplo-de-payload-incorreto]
```json
{
"customer": {
"name": "Maria Souza",
"phone": "11999999999",
"phone_country_code": "11"
}
}
```
#### Exemplo de payload correto [#exemplo-de-payload-correto]
```json
{
"customer": {
"name": "Maria Souza",
"phone": "11999999999",
"phone_country_code": "55"
}
}
```
### Tabela de validação rápida [#tabela-de-validação-rápida]
| Campo | Descrição | Exemplo correto |
| -------------------- | ------------------------------------- | --------------- |
| `phone_country_code` | Apenas o código internacional do país | `"55"` |
| `phone` | DDD + Número (apenas dígitos) | `"11999999999"` |
| `document_type` | Tipo de documento do cliente | `"CPF"` |
---
# Pedido (/docs/log/integrations/pedido)
---
# Neomode (/docs/log/integrations/pedido/neomode)
A **Neomode** é uma plataforma de gestão de pedidos omnichannel (OMS) usada por redes de lojas e franquias para centralizar vendas de canais físicos e digitais. A integração com a Abbiamo permite receber automaticamente os pedidos faturados na Neomode e atualizar o status de volta conforme a entrega avança.
Para entender o conceito geral, veja [Integração de Pedido](/docs/log/conceitos/integracao-pedido/).
***
## Como funciona [#como-funciona]
1. **Pedido é faturado na Neomode** — a loja processa a venda e o pedido chega ao status faturado.
2. **Abbiamo importa o pedido** — periodicamente, a Abbiamo busca na Neomode os pedidos faturados e cria o [pedido](/docs/log/conceitos/pedido/) na filial correspondente.
3. **Solicitação de coleta** — o pedido segue para [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) manual ou via [automação de envio](/docs/log/conceitos/regra-envio/).
4. **Atualização na Neomode** — conforme o pedido avança na Abbiamo (despachado, em rota, entregue), a Neomode é atualizada automaticamente.
***
## Configuração [#configuração]
Diferente de integrações self-service (como VTEX), a integração com a Neomode não tem um formulário de credenciais preenchido pelo cliente — a autenticação é centralizada e mantida pela Abbiamo.
Para habilitar a integração em uma filial, a Abbiamo precisa apenas do **identificador da loja na Neomode**. Fale com o seu contato comercial ou com o suporte Abbiamo para configurar.
***
## Como o dado vem na Abbiamo [#como-o-dado-vem-na-abbiamo]
Após o mapeamento, o pedido criado na Abbiamo contém as seguintes informações vindas da Neomode:
### Identificação [#identificação]
| Na Abbiamo | Origem na Neomode |
| --------------------- | ------------------------------------------------- |
| Número do pedido | Identificador externo do pedido na Neomode |
| Número da nota fiscal | Número da nota fiscal, quando disponível |
| Chave de acesso da NF | Chave de acesso da nota fiscal, quando disponível |
### Cliente [#cliente]
| Na Abbiamo | Origem na Neomode |
| ---------- | ----------------------------------------------------- |
| Nome | Nome completo do comprador |
| E-mail | E-mail do comprador |
| Telefone | Telefone do comprador |
| CPF/CNPJ | Documento do comprador (CPF ou CNPJ, conforme o tipo) |
### Endereço de entrega [#endereço-de-entrega]
| Na Abbiamo | Origem na Neomode |
| ----------- | ----------------------------- |
| CEP | CEP do endereço de entrega |
| Rua | Rua do endereço de entrega |
| Número | Número do endereço de entrega |
| Complemento | Complemento, quando informado |
| Bairro | Bairro do endereço de entrega |
| Cidade | Cidade do endereço de entrega |
| Estado | Estado do endereço de entrega |
### Itens e volumes [#itens-e-volumes]
* Cada item do pedido vira um item do volume na Abbiamo — itens marcados como brinde não são importados.
* Peso de cada item vem direto do cadastro do produto na Neomode.
* SKU, nome e quantidade são mapeados dos itens originais.
### Informações adicionais [#informações-adicionais]
| Na Abbiamo | Origem na Neomode |
| -------------- | --------------------------------------------------- |
| Transportadora | Nome da transportadora informado no frete do pedido |
***
## Atualização de status na Neomode [#atualização-de-status-na-neomode]
Quando o pedido muda de status na Abbiamo, a Neomode é atualizada automaticamente:
| Status na Abbiamo | O que é enviado para a Neomode |
| ---------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Despachado** | Código de rastreio, link de rastreio e transportadora — avança o pedido para o passo de pronto para transporte. |
| **Em Rota** | Pedido marcado como em transporte. |
| **Sucesso (Entregue)** | Pedido marcado como finalizado. |
***
## Troubleshooting [#troubleshooting]
### O pedido não apareceu na Abbiamo [#o-pedido-não-apareceu-na-abbiamo]
Checklist:
1. **Integração ativa?** Confirme com o suporte Abbiamo se a integração da loja está ativa.
2. **Pedido faturado?** Só pedidos com o pedido faturado na Neomode são importados — pedidos em processamento ainda não aparecem.
3. **Loja cadastrada corretamente?** O identificador da loja na Neomode precisa estar vinculado à filial certa na Abbiamo. Se o cadastro estiver incorreto ou ausente, o pedido não é criado.
### O status não atualizou na Neomode [#o-status-não-atualizou-na-neomode]
* Verifique se a **solicitação de coleta** foi feita na Abbiamo (não apenas o pedido criado).
* A atualização de status é assíncrona — pequenos atrasos de alguns minutos entre a mudança na Abbiamo e o reflexo na Neomode são esperados.
***
## Onde acessar [#onde-acessar]
* **Pedidos recebidos:** Operação > Pedidos — filtre pela filial e verifique a coluna de origem para identificar pedidos vindos da Neomode.
* **Configuração da integração:** feita pelo suporte Abbiamo — entre em contato para habilitar ou ajustar uma filial.
---
# Shopify (/docs/log/integrations/pedido/shopify)
A integração com a **Shopify** permite receber pedidos automaticamente assim que são pagos e devolver o rastreamento ao lojista conforme o pedido é despachado, sai para entrega e é entregue.
Para entender o conceito geral, veja [Integração de Pedido](/docs/log/conceitos/integracao-pedido/).
***
## Como funciona [#como-funciona]
1. **Cliente compra na Shopify** — o pedido é criado e **pago** na loja.
2. **Shopify envia o pedido** — o webhook `orders/paid` é disparado para a Abbiamo.
3. **Abbiamo enriquece e filtra** — o sistema consulta a API GraphQL da Shopify, identifica a **filial (location)** e aplica o **filtro de entrega** configurado.
4. **Abbiamo cria o pedido** — se passar no filtro, o [pedido](/docs/log/conceitos/pedido/) é criado na filial correspondente e o pedido na Shopify recebe a tag `AbbiamoInvoice:`.
5. **Atualização na Shopify** — quando o pedido muda de status na Abbiamo (despachado, em rota, entregue), a Abbiamo atualiza o **fulfillment** na Shopify com código e link de rastreamento.
***
## Passo 1 — Instalar o app da Abbiamo (OAuth 2.0) [#passo-1--instalar-o-app-da-abbiamo-oauth-20]
A conexão é feita por OAuth 2.0. A Abbiamo envia ao lojista um link de instalação já com os parâmetros prontos.
1. Abra o **link de instalação** fornecido pela Abbiamo.
2. **Autorize** a instalação do app na loja.
3. Ao final, será exibido o **Token de Acesso** da loja (`shpca_...`).
4. **Copie o token** — ele será usado no cadastro da integração.
Ao concluir o OAuth, a Abbiamo configura automaticamente o **webhook `orders/paid`** e o **carrier service "Cotação Abbiamo Dinamica"** (usado no modo de cotação dinâmica — ver Passo 3).
***
## Passo 2 — Descobrir o identificador do local (filial) [#passo-2--descobrir-o-identificador-do-local-filial]
Você precisa do **ID numérico** do local para vincular à filial na Abbiamo.
1. No painel Shopify, vá em **Configurações → Locais**.
2. Clique no local desejado.
3. O número no **final da URL** é o identificador. Ex.:
`https://admin.shopify.com/store/nomedaloja/settings/locations/72808693869` → `72808693869`.
***
## Passo 3 — Escolher o modo de entrega (filtro) [#passo-3--escolher-o-modo-de-entrega-filtro]
A integração só cria pedidos que batem com o **filtro de entrega** configurado. Há dois modos.
### Modo A — Taxa de frete fixa (`SHIPPING_LINE`) [#modo-a--taxa-de-frete-fixa-shipping_line]
Use quando o lojista já tem **taxas de frete cadastradas manualmente** na Shopify (ex.: "Entrega Padrão", "Local Delivery").
* A integração compara o **código (`code`) da taxa** escolhida no checkout com a lista de nomes cadastrados na Abbiamo.
* Só importa o pedido se a taxa bater com um dos nomes configurados.
Para descobrir os nomes: **Configurações → Frete e Entrega**, localize a zona de frete do local e anote **exatamente** os nomes das taxas.
### Modo B — Cotação dinâmica Abbiamo (`QUOTATION_ONLY`) [#modo-b--cotação-dinâmica-abbiamo-quotation_only]
Use quando o frete deve ser **cotado em tempo real** pela Abbiamo no checkout.
* No checkout, o carrier service **"Cotação Abbiamo Dinamica"** (criado na instalação) retorna as opções de frete da Abbiamo.
* Cada opção carrega um código no formato `ABB:logistic_id:method_id`.
* Ao pagar, a integração lê esse código e cria o pedido já com a **transportadora e o método** corretos.
Garanta que o carrier service da Abbiamo esteja **ativo nas zonas de frete** do local no checkout.
### Retirada (takeout) [#retirada-takeout]
Se a loja oferece **retirada na loja**, defina o comportamento:
| Opção | Comportamento |
| ---------------------------------------------------------------- | ------------------------------------------------------- |
| **Não criar** (`IGNORE`) | Pedidos de retirada não são importados |
| **Criar** (`CREATE`) | Pedidos de retirada são importados como pedidos normais |
| **Criar como pronto para retirada** (`CREATE_READY_FOR_TAKEOUT`) | Importa já marcado como "pronto para retirada" |
***
## Passo 4 — Cadastrar a integração na Abbiamo [#passo-4--cadastrar-a-integração-na-abbiamo]
Cadastre **uma integração de pedido por filial** em **Configurações → Integrações de Pedido**, escolhendo o provedor **Shopify**.
### Campos da integração (o que você preenche) [#campos-da-integração-o-que-você-preenche]
| Campo | Descrição | Exemplo |
| -------------------------- | --------------------------------------------------- | ---------------------------------- |
| **Endereço da loja** | Domínio `.myshopify.com` da loja | `minhaloja.myshopify.com` |
| **Token de acesso** | Token gerado no Passo 1 | `shpca_XXXXXXXX` |
| **Identificador do local** | ID numérico do local (Passo 2) | `72808693869` |
| **Modo de filtro** | `SHIPPING_LINE` ou `QUOTATION_ONLY` | `SHIPPING_LINE` |
| **Taxas de frete** | Nomes aceitos (modo A; e retirada no modo B) | `Entrega Padrão, Entrega Expressa` |
| **Retirada** | Não criar / Criar / Criar como pronto para retirada | `Criar como pronto para retirada` |
***
## Como o dado vem na Abbiamo [#como-o-dado-vem-na-abbiamo]
### Cliente [#cliente]
| Na Abbiamo | Origem na Shopify |
| ---------- | --------------------------------------------- |
| Nome | `customer.first_name` + `last_name` |
| E-mail | `customer.email` |
| Telefone | `customer.phone` (ou `default_address.phone`) |
### Endereço de entrega [#endereço-de-entrega]
| Na Abbiamo | Origem na Shopify |
| ----------- | --------------------------- |
| CEP | `shipping_address.zip` |
| Rua | `shipping_address.address1` |
| Complemento | `shipping_address.address2` |
| Cidade | `shipping_address.city` |
| Estado | `shipping_address.province` |
| País | `shipping_address.country` |
### Itens e valores [#itens-e-valores]
* Cada item do pedido vira um item nos volumes da Abbiamo (nome, SKU, quantidade, valor e peso em `grams`).
* O valor do pedido vem de `total_price`.
### Tipo de pedido [#tipo-de-pedido]
| Na Abbiamo | Condição na Shopify |
| ------------ | -------------------------- |
| **DELIVERY** | delivery method `SHIPPING` |
| **TAKEOUT** | delivery method `PICK_UP` |
***
## Atualização de status na Shopify [#atualização-de-status-na-shopify]
Quando o pedido muda de status na Abbiamo, a Shopify é atualizada automaticamente:
| Status na Abbiamo | O que é enviado para a Shopify |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| **Despachado** (entrega) | Cria o fulfillment com código de rastreamento, transportadora e link `meupedido.abbiamolog.com` |
| **Saiu para entrega** | Evento de fulfillment "Out for delivery" |
| **Entregue** | Evento de fulfillment "Delivered" |
| **Retirada — despachado** | Marca o fulfillment como "pronto para retirada" |
***
## Ver o nome do motorista no pedido [#ver-o-nome-do-motorista-no-pedido]
Conforme o pedido avança (saiu para entrega, foi entregue), a Abbiamo também envia o **nome do motorista** para o pedido na Shopify. Esse dado fica visível só para o time da loja no painel administrativo — o comprador final **nunca** vê essa informação, nem na página de rastreio nem em e-mails.
Por padrão a Shopify não mostra esse campo na tela do pedido. Para habilitar a exibição, é preciso criar uma **definição de metacampo** uma única vez por loja. É rápido e só precisa ser feito uma vez.
### Como habilitar (passo a passo) [#como-habilitar-passo-a-passo]
1. No admin da Shopify, clique em **Configurações**, no canto inferior esquerdo.
2. Na lista de configurações, clique em **Metacampos e metaobjetos**.
3. Clique em **Pedidos**.
4. Clique em **Adicionar definição**.
5. Você vai ver o formulário de criação, com o campo **Nome**, o **Tipo** e a opção **Acesso à API Storefront** (que vem **ligada** por padrão — atenção nesse ponto no passo 7).
6. No campo **Nome**, digite `Nome do motorista` (ou outro texto de sua preferência — é só o rótulo exibido na tela). Assim que você digita, a Shopify gera um identificador técnico logo abaixo, algo como `custom.nome_do_motorista`.
7. **Clique nesse identificador** para editá-lo, apague o conteúdo e digite **exatamente**:
```
abbiamo.driver_name
```
Em seguida, selecione **Texto de linha única** no campo **Tipo**, e **desligue** a opção **Acesso à API Storefront** (estava ligada por padrão no passo 5) — isso garante que o nome do motorista não fique acessível pelo site de compra do cliente final.
8. Clique em **Salvar**, no aviso que aparece no rodapé da tela.
### Onde aparece depois de configurado [#onde-aparece-depois-de-configurado]
Na página de qualquer pedido despachado pela Abbiamo, dentro da seção **Metacampos**, o campo com o nome escolhido no passo 3 mostra o motorista responsável pela entrega — atualizado automaticamente conforme o pedido avança.
***
## Critérios para importação de pedidos [#critérios-para-importação-de-pedidos]
Um pedido só é importado quando **todas** as condições abaixo são verdadeiras:
1. O pedido está **pago** (webhook `orders/paid`).
2. O pedido tem **linha(s) de frete** (`shipping_lines`).
3. Para entregas (não retirada), o pedido tem **endereço de entrega**.
4. A entrega **passa no filtro** configurado (`SHIPPING_LINE` ou `QUOTATION_ONLY`).
Pedidos que não atendem a esses critérios são **ignorados** pela integração.
***
## Onde acessar [#onde-acessar]
* **Configuração da integração:** Configurações > Integrações de pedido — o cliente cadastra a integração de pedido Shopify.
* **Pedidos recebidos:** Operação > Pedidos — filtre pela filial e verifique a origem para identificar pedidos vindos da Shopify.
---
# VTEX (/docs/log/integrations/pedido/vtex)
A integração com a **VTEX** permite receber pedidos automaticamente e atualizar o status de volta na plataforma quando a solicitação de coleta é feita, o pedido entra em rota ou é entregue.
Para entender o conceito geral, veja [Integração de Pedido](/docs/log/conceitos/integracao-pedido/).
***
## Como funciona [#como-funciona]
1. **Cliente compra na VTEX** — O pedido é criado na loja VTEX.
2. **VTEX envia o pedido** — Quando o pedido atinge o status configurado (pagamento aprovado ou faturado), a VTEX envia uma notificação para a Abbiamo.
3. **Abbiamo cria o pedido** — O sistema cria o [pedido](/docs/log/conceitos/pedido/) na filial correspondente, respeitando filtros de transportadora e mapeamento de vendedor.
4. **Solicitação de coleta** — O pedido segue para [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) manual ou via [automação de envio](/docs/log/conceitos/regra-envio/).
5. **Atualização na VTEX** — Quando o pedido muda de status na Abbiamo (com solicitação de coleta feita, em rota, entregue), a Abbiamo atualiza a VTEX automaticamente.
***
## Campos da integração (o que você preenche) [#campos-da-integração-o-que-você-preenche]
Ao criar uma integração de pedido VTEX no painel, você verá os campos abaixo. Esta seção explica o que é cada um e onde obter as informações na VTEX.
### Chave de API da VTEX (appKey) [#chave-de-api-da-vtex-appkey]
AppKey gerada na VTEX. Para obter: **Configurações da conta → Gerenciamento da conta → Chaves de aplicação → Gerenciar minhas chaves → Gerar chave**. Copie o valor em **Chave de aplicação**.
### Token de API da VTEX (appToken) [#token-de-api-da-vtex-apptoken]
AppToken gerado na VTEX. Mesmo fluxo da chave acima; copie o valor em **Token de aplicação**. São duas informações diferentes — não confunda uma com a outra.
### Tipo da integração (integration\_style) [#tipo-da-integração-integration_style]
Define como a filial será identificada na VTEX:
| Valor no formulário | Descrição |
| -------------------- | --------------------------------------------------------------------------- |
| **vtex\_seller\_id** | Cada filial corresponde a um seller (vendedor) específico na VTEX. |
| **dock\_id** | Cada filial corresponde a um armazém/centro de distribuição (dock) na VTEX. |
Escolha de acordo com o tipo de operação que você utiliza.
### ID do armazém (vtex\_id) [#id-do-armazém-vtex_id]
Preencha com o **seller\_id** ou o **dock\_id**, conforme o tipo da integração escolhido:
* Se **Tipo da integração** for **vtex\_seller\_id**: informe o ID do seller na VTEX (a Abbiamo pode ajudar a listar os sellers da sua conta).
* Se for **dock\_id**: informe o ID do dock que atende os pedidos dessa filial (configurado no fluxo de envio da VTEX ou informado pela transportadora).
### TLD (tld) [#tld-tld]
Domínio de topo da URL da sua loja: **.com** ou **.com.br**. Para lojas brasileiras costuma ser `.com.br`.
### Nome da conta VTEX (accountName) [#nome-da-conta-vtex-accountname]
Valor do campo accountName da sua loja VTEX — é o subdomínio. Ex.: se a URL é `minhaloja.vtex.com.br`, o Nome da conta VTEX é `minhaloja`.
### Ambiente VTEX (environment) [#ambiente-vtex-environment]
Ambiente configurado na VTEX: **myvtex** (homologação/testes) ou **vtexcommercestable** (produção).
### Status de importação do pedido (order\_creation\_status) [#status-de-importação-do-pedido-order_creation_status]
Em qual status da VTEX o pedido será criado na Abbiamo:
| Opção no formulário | Significado |
| ---------------------- | ------------------------------------------------------------------------ |
| **Faturado** | Pedido é importado quando estiver faturado na VTEX. |
| **Pagamento Aprovado** | Pedido é importado assim que o pagamento for aprovado (antes da fatura). |
### Políticas de envio (shipping\_policies) [#políticas-de-envio-shipping_policies]
Lista de políticas de envio VTEX que devem ser importadas para a Abbiamo. Se preenchido, **apenas** pedidos que usem uma dessas políticas serão importados. Os nomes devem ser exatamente iguais aos configurados na VTEX (maiúsculas, espaços e acentos importam).
### Gerar volume único (single\_volume) [#gerar-volume-único-single_volume]
Se **Sim**: os pedidos importados terão um único volume (todos os itens agrupados). Se **Não**: cada item do pedido representará um volume separado.
### Importar pedidos do tipo RETIRA (takeout) [#importar-pedidos-do-tipo-retira-takeout]
Define como tratar pedidos de **retirada em loja** (pickup-in-point) na VTEX:
| Opção no formulário | Comportamento |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| **Não criar** | Pedidos de retirada não são importados para a Abbiamo. |
| **Criar aguardando confirmação** | Pedidos de retirada são importados como pedidos normais. |
| **Criar como pronto para retirada** | Pedidos de retirada são importados já marcados como prontos para o cliente retirar. |
***
## Como o dado vem na Abbiamo [#como-o-dado-vem-na-abbiamo]
Após o mapeamento, o pedido criado na Abbiamo contém as seguintes informações vindas da VTEX:
### Identificação [#identificação]
| Na Abbiamo | Origem na VTEX |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Número do pedido | `orderId` |
| Número da nota fiscal | `invoiceNumber` (do pacote). Só é preenchido quando o fluxo é **Faturado**; no fluxo **Pagamento Aprovado** o pedido fica sem esse dado até ser faturado na VTEX. |
| Chave de acesso da NF | `invoiceKey` (quando disponível) |
### Cliente [#cliente]
| Na Abbiamo | Origem na VTEX |
| ---------- | ---------------------------------------------------------------------- |
| Nome | `clientProfileData.firstName` + `lastName` |
| E-mail | `clientProfileData.email` (ou `corporateName` em pedidos corporativos) |
| Telefone | `clientProfileData.phone` ou `corporatePhone` |
| CPF/CNPJ | `clientProfileData.document` ou `corporateDocument` |
### Endereço de entrega [#endereço-de-entrega]
| Na Abbiamo | Origem na VTEX |
| ----------- | ----------------------------------- |
| CEP | `shippingData.address.postalCode` |
| Rua | `shippingData.address.street` |
| Número | `shippingData.address.number` |
| Complemento | `shippingData.address.complement` |
| Bairro | `shippingData.address.neighborhood` |
| Cidade | `shippingData.address.city` |
| Estado | `shippingData.address.state` |
| País | `shippingData.address.country` |
### Itens e volumes [#itens-e-volumes]
* Cada item do pedido VTEX vira um item nos volumes da Abbiamo.
* Dimensões (peso, altura, largura, comprimento) vêm de `additionalInfo.dimension` de cada item.
* SKU, nome, imagem e preço são mapeados dos itens originais.
### Informações adicionais [#informações-adicionais]
| Na Abbiamo | Origem na VTEX |
| ------------------------ | ------------------------------------------ |
| Transportadora escolhida | `logisticsInfo.deliveryIds[0].courierName` |
| Prazo de entrega | `shippingEstimate` ou `deliveryWindow` |
| Valor do frete pago | Total "Shipping" em `totals` |
| Data de processamento | `authorizedDate` |
### Tipo de pedido [#tipo-de-pedido]
| Na Abbiamo | Condição na VTEX |
| ------------ | --------------------------------------- |
| **DELIVERY** | `deliveryChannel === 'delivery'` |
| **TAKEOUT** | `deliveryChannel === 'pickup-in-point'` |
***
## Atualização de status na VTEX [#atualização-de-status-na-vtex]
Quando o pedido muda de status na Abbiamo, a VTEX é atualizada automaticamente:
| Status na Abbiamo | O que é enviado para a VTEX |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Solicitação de coleta feita** | Nome da transportadora, data da solicitação de coleta, código de rastreio e URL de rastreio. |
| **Em rota** | Data da ocorrência e status "Em Rota". |
| **Entregue** | Data da entrega, status "Entregue" e indicação de que o pedido foi entregue (campo absoluto que altera a visualização do pedido no admin da VTEX). |
***
## Troubleshooting [#troubleshooting]
### O pedido não apareceu na Abbiamo [#o-pedido-não-apareceu-na-abbiamo]
Checklist:
1. **Integração ativa?** Verifique em Configurações > Integrações de pedido se a integração VTEX está ativa.
2. **Status de importação do pedido** — O pedido precisa ter atingido o status escolhido (Faturado ou Pagamento Aprovado). Pedidos ainda em processamento não são importados.
3. **Políticas de envio** — Se você preencheu Políticas de envio, confira se o nome da política/transportadora do pedido bate exatamente com o configurado.
4. **Tipo da integração e ID do armazém** — O pedido precisa pertencer ao seller ou dock informado na integração para a filial correta. Se a integração for por **vtex\_seller\_id**, o seller do pedido na VTEX precisa bater com o configurado; pedidos de outros sellers/docks são ignorados.
5. **Importar pedidos do tipo RETIRA** — Se estiver em "Não criar", pedidos de retirada em loja não serão importados.
### O status não atualizou na VTEX [#o-status-não-atualizou-na-vtex]
* Verifique se a **solicitação de coleta** foi feita na Abbiamo (não apenas criado).
* Pedidos de retirada (TAKEOUT) têm um fluxo específico — a atualização "Entregue" na Abbiamo envia "Retirado pelo Cliente" na VTEX.
### O pedido foi criado na filial errada [#o-pedido-foi-criado-na-filial-errada]
* A integração VTEX mapeia por **Tipo da integração** (vtex\_seller\_id ou dock\_id). Se você tem múltiplas filiais, confira se cada integração está com o seller ou dock correto para a filial desejada.
### Nome da transportadora não bate [#nome-da-transportadora-não-bate]
* O nome da transportadora na VTEX deve ser **idêntico** ao configurado (incluindo maiúsculas, espaços e acentos).
### Webhook ou credenciais com erro [#webhook-ou-credenciais-com-erro]
* A Abbiamo cadastra o webhook na VTEX no momento da criação da integração de pedido. Se o **Token de API da VTEX** estiver sem permissão de OMS nessa hora, o cadastro pode falhar e os pedidos não passarão a chegar.
* Verifique se a **Chave de API da VTEX** e o **Token de API da VTEX** estão corretos e se o perfil de acesso na VTEX tem permissão de OMS.
* Chave e token são dois valores diferentes — confira se foram copiados separadamente.
***
## Onde acessar [#onde-acessar]
* **Configuração da integração:** Configurações > Integrações de pedido — o próprio cliente cadastra a integração de pedido VTEX.
* **Pedidos recebidos:** Operação > Pedidos — filtre pela filial e verifique a coluna de origem para identificar pedidos vindos da VTEX.
---
# Dashboard (Analytics) — Visão Geral (/docs/log/products/dashboard)
O **Dashboard** exibe indicadores, métricas e análises da sua operação logística em tempo (quase) real.
---
# Automações de Marcadores — Como Usar (/docs/log/products/automacoes-de-marcadores/como-usar)
***
## Criar uma automação de marcador [#criar-uma-automação-de-marcador]
1. Acesse **Configurações > Automações de marcadores**.
2. Clique em **Criar automação**.
3. Preencha o formulário:
### 1. Título [#1-título]
Dê um nome descritivo à automação (ex.: "Produto frágil — filial SP").
### 2. Ativar automação [#2-ativar-automação]
Marque o toggle se quiser que a automação já fique ativa ao salvar. Deixe desmarcado para criar inativa e ativar depois.
### 3. Condições [#3-condições]
Defina **quais pedidos** receberão o marcador. Sem condições, todos os pedidos serão automatizados.
Para adicionar uma condição:
1. Clique em **"Quais condições devem ser atendidas?"**.
2. Selecione o **campo** a avaliar (ex.: Filial, CEP, SKU).
3. Escolha o **operador** (ex.: é, não é, contém).
4. Informe o **valor** (ex.: nome da filial ou faixa de CEP).
5. Adicione mais condições se necessário — todas devem ser atendidas simultaneamente (AND).
### 4. Marcador a atribuir [#4-marcador-a-atribuir]
No campo **"Qual marcador atribuir ao pedido?"**, selecione o marcador na lista.
4. Clique em **Criar automação**.
***
## Editar uma automação [#editar-uma-automação]
1. Localize a automação na tabela.
2. Clique no **menu ⋯** da linha.
3. Selecione **Editar**.
4. Modifique os campos desejados e salve.
***
## Ativar ou desativar uma automação [#ativar-ou-desativar-uma-automação]
1. Clique no **menu ⋯** da linha.
2. Selecione **Ativar** ou **Desativar**.
***
## Entender a sequência [#entender-a-sequência]
A coluna **Sequência** define a prioridade de avaliação. A automação de número 1 é avaliada primeiro. Se um pedido atende às condições de mais de uma automação, o marcador da **primeira na sequência** é aplicado.
***
## Excluir uma automação [#excluir-uma-automação]
1. Clique no **menu ⋯** da linha.
2. Selecione **Excluir**.
3. Confirme a exclusão.
---
# Automações de Marcadores — Visão Geral (/docs/log/products/automacoes-de-marcadores)
A tela de **Automações de Marcadores** permite criar regras que aplicam [marcadores](/docs/log/settings/marcadores/) automaticamente a pedidos quando determinadas condições são atendidas — eliminando a necessidade de marcação manual.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/tags-rules](https://dashboard.abbiamolog.com/tags-rules)
* **Menu:** seção **Configurações** > **Automações de marcadores**
***
## Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------------- | ----------------------------------------- |
| **Título** | "Automação de marcadores de pedidos" |
| **Criar automação** | Abre o modal de criação de nova automação |
***
## Barra de filtros [#barra-de-filtros]
| Filtro | Descrição |
| ------------- | --------------------------- |
| **Nome** | Busca por nome da automação |
| **Atualizar** | Recarrega a lista |
| **Filtros** | Painel de filtros avançados |
***
## Tabela de automações [#tabela-de-automações]
| Coluna | O que mostra |
| --------------------- | ----------------------------------------------------------------------- |
| **Sequência** | Ordem de avaliação das automações (1 = maior prioridade) |
| **Nome** | Nome descritivo da automação |
| **Condições** | Resumo das condições configuradas (ex.: "Filial") ou "Todos os pedidos" |
| **Marcador aplicado** | Badge colorido com o nome do marcador que será atribuído |
| **Situação** | 🟢 Ativa / 🔴 Desativada |
| **Criado em** | Data e hora de criação |
| **Atualizada em** | Data e hora da última modificação |
| **Menu (⋯)** | Ações por automação |
***
## Modal de criação / edição [#modal-de-criação--edição]
Clique em **Criar automação** (ou **Editar** no menu ⋯) para abrir o formulário:
| Campo | Descrição |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Título** | Nome da automação (ex.: "Fragilidade por filial") |
| **Ativar automação** | Toggle para ativar/desativar imediatamente após criar |
| **Condições** | Regras que um pedido deve atender para receber o marcador. Sem condições = "Todos os pedidos serão automatizados" |
| **Marcador a atribuir** | Selecione o marcador (criado em [Configurações > Marcadores](/docs/log/settings/marcadores/)) |
### Como funcionam as condições [#como-funcionam-as-condições]
As condições são construídas como filtros: selecione um **campo** (ex.: Filial, CEP, SKU), um **operador** (é / não é / contém) e um **valor**. Múltiplas condições são avaliadas em conjunto (AND).
***
## Ações por automação (menu ⋯) [#ações-por-automação-menu-]
| Ação | Descrição |
| ---------------------- | ---------------------------------- |
| **Editar** | Abre o modal de edição |
| **Ativar / Desativar** | Alterna a situação da automação |
| **Excluir** | Remove permanentemente a automação |
***
## Próximos passos [#próximos-passos]
* [**Como Usar**](/docs/log/products/automacoes-de-marcadores/como-usar/) — passo a passo para criar e gerenciar automações de marcadores.
---
# Envios — Como Usar (/docs/log/products/envios/como-usar)
***
## Monitorar envios do dia [#monitorar-envios-do-dia]
1. Acesse **Operação > Envios**.
2. O período padrão exibe os últimos 7 dias. Ajuste o seletor de **Período** se precisar de um intervalo diferente.
3. Use o filtro **Status** para focar em envios específicos (ex.: apenas "EM ROTA").
4. Use **Entregue por** para filtrar por uma transportadora específica.
***
## Localizar um envio específico [#localizar-um-envio-específico]
1. Use o campo **Pesquisar envio** para buscar por:
* ID Abbiamo do envio
* Código de rastreio da transportadora (ID Transportadora)
* Nome ou referência do pedido
2. O resultado filtra a tabela em tempo real.
***
## Entender o status de um envio [#entender-o-status-de-um-envio]
Cada envio passa por estágios:
| Sequência | Status | O que significa |
| --------- | -------------- | ------------------------------------------------------ |
| 1 | **PENDENTE** | Despacho solicitado, aguardando transportadora aceitar |
| 2 | **DESPACHADO** | Aceito — transportadora buscando entregador |
| 3 | **EM ROTA** | Entregador a caminho do destinatário |
| 4 | **SUCESSO** | Entregue com sucesso |
O **Sub status** complementa com mais detalhes: "Aguardando Transportadora", "Transportadora Confirmou", "Buscando Entregador", "Entregue".
***
## Adicionar preço auditado [#adicionar-preço-auditado]
Use esta ação quando o valor cobrado pela transportadora divergir do valor cotado:
1. Localize o envio na tabela.
2. Clique no **menu ⋯** da linha.
3. Selecione **Adicionar preço auditado**.
4. Informe o valor real cobrado.
5. Confirme.
***
## Auditar frete em lote (importação de planilha) [#auditar-frete-em-lote-importação-de-planilha]
Para auditar múltiplos envios de uma vez:
1. Clique no botão **Auditar** no canto superior direito.
2. Selecione **Importar planilhas com valores de frete**.
3. Baixe o modelo de planilha (se disponível) e preencha com os valores reais.
4. Faça o upload do arquivo.
5. A plataforma associa os valores importados aos envios correspondentes.
***
## Filtrar por marcadores [#filtrar-por-marcadores]
1. Clique no seletor **Marcadores** na barra de filtros.
2. Escolha um ou mais marcadores.
3. A tabela exibe apenas envios cujos pedidos possuem aqueles marcadores.
***
## Exportar / Relatórios [#exportar--relatórios]
Para análises mais completas, use a tela de [Relatórios](/docs/log/products/relatorios/) com o tipo **ENVIOS** — ela permite exportar os dados em CSV com filtros de período e filial.
---
# Envios — Visão Geral (/docs/log/products/envios)
A tela de **Envios** exibe todos os despachos realizados para transportadoras externas — cada linha representa um **envio** vinculado a um pedido, com rastreamento de status e sub-status em tempo quase real.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/deliveries](https://dashboard.abbiamolog.com/deliveries)
* **Menu:** seção **Operação** > **Envios**
***
## Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ----------- | --------------------------------------------------------------------------------------- |
| **Título** | "Envios" |
| **Auditar** | Dropdown com opção "Importar planilhas com valores de frete" para conciliação de custos |
***
## Barra de filtros [#barra-de-filtros]
| Filtro | O que faz |
| --------------------------- | -------------------------------------------------------------------------- |
| **Pesquisar envio** | Busca por ID Abbiamo, ID Transportadora ou nome do pedido |
| **Status** | Filtra por status do envio (Todos, PENDENTE, DESPACHADO, EM ROTA, SUCESSO) |
| **Entregue por** | Filtra pela transportadora responsável |
| **Período** | Intervalo de datas (padrão: últimos 7 dias) |
| **Marcadores** | Filtra por marcadores aplicados ao pedido |
| **Filtros** | Abre painel de filtros avançados |
| **Visibilidade de colunas** | Mostrar/ocultar colunas da tabela |
***
## Tabela de envios [#tabela-de-envios]
| Coluna | O que mostra |
| --------------------- | ---------------------------------------------------------------------------------- |
| **ID Abbiamo** | Identificador interno do envio na Abbiamo (truncado, com botão de cópia) |
| **ID Transportadora** | Código de rastreio gerado pela transportadora (pode estar vazio antes do despacho) |
| **Pedido** | Nome ou referência do pedido vinculado |
| **Filial** | Filial de origem do pedido |
| **Marcadores** | Marcadores aplicados ao pedido |
| **Status** | Status principal do envio |
| **Sub status** | Descrição mais detalhada da etapa atual |
| **Transportadora** | Logotipo e nome da transportadora responsável |
| **Menu (⋯)** | Ações disponíveis para o envio |
***
## Status de envio [#status-de-envio]
| Status | Significado |
| -------------- | ------------------------------------------------- |
| **PENDENTE** | Envio criado, aguardando aceite da transportadora |
| **DESPACHADO** | Transportadora aceitou; entregador sendo buscado |
| **EM ROTA** | Entregador a caminho do destino |
| **SUCESSO** | Pedido entregue com sucesso |
### Sub-status comuns [#sub-status-comuns]
| Sub-status | Quando aparece |
| ----------------------------- | --------------------------------------------------------- |
| **Aguardando Transportadora** | Logo após o despacho, antes da confirmação |
| **Buscando Entregador** | Transportadora confirmou, procurando motorista disponível |
| **Transportadora Confirmou** | Motorista atribuído pela transportadora |
| **Entregue** | Entrega confirmada |
***
## Ações por envio (menu ⋯) [#ações-por-envio-menu-]
| Ação | Descrição |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| **Adicionar preço auditado** | Registra manualmente o valor real cobrado pela transportadora para fins de conciliação |
***
## Auditoria de frete [#auditoria-de-frete]
O botão **Auditar** no cabeçalho permite importar planilhas de valores cobrados pelas transportadoras para cruzar com os preços cotados pela plataforma.
***
## Estado vazio [#estado-vazio]
Quando nenhum envio é encontrado no período ou filtros selecionados:
> *"Nenhum envio encontrado"*
***
## Paginação [#paginação]
* **Padrão:** 50 envios por página
* **Opções:** 50, 100, 150, 200
***
## Próximos passos [#próximos-passos]
* [**Como Usar**](/docs/log/products/envios/como-usar/) — passo a passo para monitorar envios e realizar a auditoria de frete.
---
# Faturas — Visão Geral (/docs/log/products/faturas)
A tela de **Faturas** permite gerar e consultar o cálculo de valores a pagar para transportadoras em um determinado período — consolidando os custos de frete de todos os envios realizados.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/payments](https://dashboard.abbiamolog.com/payments)
* **Menu:** seção **Auditoria** > **Faturas**
***
## Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ---------------- | ---------------------------------------------------------- |
| **Título** | "Fatura" |
| **Gerar fatura** | Dispara o cálculo de pagamentos para o período selecionado |
***
## Filtros [#filtros]
| Filtro | Descrição |
| ----------- | ------------------------------------------------------------------ |
| **Período** | Seletor de data (início e fim) para o qual gerar/consultar faturas |
| **Filtros** | Painel de filtros avançados |
***
## Como funciona [#como-funciona]
1. Selecione o **período** desejado usando o seletor de datas.
2. Clique em **Gerar fatura** para solicitar o cálculo.
3. A plataforma consolida os envios do período e calcula o valor total por transportadora.
4. Os resultados aparecem na tabela após o processamento.
***
## Estado vazio [#estado-vazio]
Quando não há fatura calculada para o período selecionado:
> *"Nenhum pagamento calculado para o período informado"*
> *"Ainda não foi gerado cálculo dos pagamentos para o período selecionado. Solicite agora para começar."*
***
## Paginação [#paginação]
* **Padrão:** 50 registros por página
---
# Integrações de Transportadora — Como Usar (/docs/log/products/integracoes-de-transportadora/como-usar)
Guia prático das principais ações para configurar e operar integrações de transportadora.
***
## Fluxo típico [#fluxo-típico]
1. Acesse **Operação > Integrações de transportadora** (`/carrier-integrations`).
2. Use os filtros de filial e transportador para encontrar integrações específicas.
3. Clique em **Nova integração de transportadora** para criar, ou use o menu (⋮) para editar, duplicar, ativar/desativar ou excluir.
4. Ao editar, revise as automações vinculadas nas abas laterais.
***
## Criar uma integração [#criar-uma-integração]
### Passo 1: Informações obrigatórias [#passo-1-informações-obrigatórias]
1. Clique em **Nova integração de transportadora**.
2. Selecione a **filial** que usará esta integração.
3. Escolha o **tipo de operação**: Entrega ou Reversa.
4. Selecione o **transportador** e a **modalidade** (ex.: Uber / Carro, Correios / PAC).
### Passo 2: Tabela de frete (opcional) [#passo-2-tabela-de-frete-opcional]
1. Selecione uma [tabela de frete](/docs/log/products/tabelas-de-frete/) — CEP ou Raio. As tabelas disponíveis são filtradas pela modalidade selecionada.
2. Se selecionou uma tabela, a opção **Cobertura restrita** aparece. Ative se quiser que pedidos com destino fora da cobertura da tabela falhem automaticamente.
### Passo 3: Horário de corte (opcional) [#passo-3-horário-de-corte-opcional]
Informe o **horário de corte** (formato HH:MM:SS). Pedidos criados depois desse horário começam a contar prazo no próximo dia útil.
### Passo 4: Informações adicionais (opcional) [#passo-4-informações-adicionais-opcional]
Expanda a seção de informações adicionais para configurar:
* **GRIS** — Percentual de gerenciamento de risco.
* **Advalorem** — Percentual ad valorem.
* **Fator de cubagem** — Fator para cálculo de peso cúbico (g/m³).
* **Isenção de cubagem** — Peso máximo isento de cálculo de cubagem (g).
### Passo 5: Configurações da transportadora [#passo-5-configurações-da-transportadora]
Dependendo da transportadora, campos adicionais específicos podem aparecer (credenciais, formato de etiqueta, etc.). Preencha conforme as instruções da transportadora.
### Passo 6: Salvar [#passo-6-salvar]
Clique em **Salvar** para criar a integração.
***
## Editar uma integração (com automações) [#editar-uma-integração-com-automações]
### Passo 1: Abrir o modal de edição [#passo-1-abrir-o-modal-de-edição]
No menu (⋮) da integração, clique em **Editar**.
### Passo 2: Editar dados da integração [#passo-2-editar-dados-da-integração]
Na aba **Integração da transportadora**:
* **Campos editáveis:** tabela de frete, cobertura restrita, horário de corte, GRIS, advalorem, fator de cubagem, isenção de cubagem e configurações da transportadora.
* **Campos somente leitura:** filial, transportador e tipo de operação.
### Passo 3: Revisar automações [#passo-3-revisar-automações]
Clique nas abas laterais para revisar as automações vinculadas a esta integração:
* **Automações de envio** — Lista as [automações de envio](/docs/log/conceitos/regra-envio/) com indicador de validação.
* **Automações de reenvio** — Lista as [automações de reenvio](/docs/log/conceitos/regra-reenvio/).
* **Automações de inatividade** — Lista as [automações de inatividade](/docs/log/conceitos/regra-inatividade/).
Cada aba exibe um badge com o número de automações válidas (ex.: "3/4"). Automações com prazo inválido ficam com indicador vermelho.
### Passo 4: Salvar [#passo-4-salvar]
Clique em **Salvar** para atualizar a integração e todas as automações de uma vez.
***
## Duplicar uma integração [#duplicar-uma-integração]
Útil para criar integrações semelhantes para diferentes filiais:
1. No menu (⋮), clique em **Duplicar**.
2. O modal abre com as configurações pré-preenchidas:
* **Fixos:** transportador, tipo de operação, tabela de frete.
* **Editáveis:** filial (selecione a nova filial), horário de corte, cobertura restrita, informações adicionais e configurações da transportadora.
3. Ajuste os campos necessários e salve.
***
## Ativar e desativar [#ativar-e-desativar]
* **Desativar** — A integração deixa de ser usada nas cotações e envios, mas permanece salva. Útil para pausar temporariamente.
* **Ativar** — A integração volta a ser usada.
Use o menu (⋮) > **Ativar** ou **Desativar**.
***
## Excluir uma integração [#excluir-uma-integração]
1. No menu (⋮), clique em **Excluir**.
2. Confirme no modal de confirmação.
A exclusão é permanente. Automações que referenciam esta integração precisarão ser ajustadas.
***
## Visualizar a tabela de frete vinculada [#visualizar-a-tabela-de-frete-vinculada]
Na coluna **Tabela de frete** da tabela de integrações, clique no nome da tabela para abrir um modal com a visualização completa da tabela — prazos, faixas e preços.
***
## Boas práticas [#boas-práticas]
* **Uma integração por modalidade e operação** — Cada filial pode ter apenas uma integração por combinação de transportadora + modalidade + tipo de operação.
* **Defina o horário de corte** — Alinhe com o horário limite de coleta da transportadora para que a data de entrega esperada seja realista.
* **Use cobertura restrita com cuidado** — Ative apenas se a tabela de frete cobre todas as regiões que a filial atende. Caso contrário, pedidos para destinos não mapeados falharão.
* **Revise automações ao mudar a tabela** — Ao trocar a tabela de frete de uma integração, confira se os prazos da nova tabela são compatíveis com as automações existentes.
* **Duplique para escalar** — Use a duplicação para replicar configurações entre filiais, ajustando apenas o que for diferente.
---
# Integrações de Transportadora — Visão Geral (/docs/log/products/integracoes-de-transportadora)
A tela de **Integrações de Transportadora** permite criar, editar e gerenciar as configurações que conectam cada [filial](/docs/log/conceitos/filial/) a uma transportadora para criar e gerenciar [envios](/docs/log/conceitos/envio/).
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/carrier-integrations](https://dashboard.abbiamolog.com/carrier-integrations)
* **Menu:** seção **Operação** > **Integrações de transportadora**
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------------------------------- | ------------------------------- |
| **Menu lateral duplo** | Abre/fecha a sidebar |
| **Título** | "Integrações de transportadora" |
| **Nova integração de transportadora** | Abre o modal de criação |
### Barra de filtros e controles [#barra-de-filtros-e-controles]
* **Filial** — Filtro multiselect para mostrar integrações de filiais específicas.
* **Transportador** — Filtro multiselect para mostrar integrações de transportadoras específicas.
* **Ativa** — Checkbox que filtra apenas integrações ativas (ativo por padrão).
* **Campo de busca** — Busca textual.
* **Botão atualizar** — Recarrega a lista.
* **Visibilidade de colunas** — Mostrar/ocultar colunas da tabela.
### Tabela de integrações [#tabela-de-integrações]
| Coluna | O que mostra |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **ID** | Identificador da integração |
| **Filial** | Nome da filial vinculada |
| **Transportador** | Nome da transportadora + modalidade (ex.: Uber / Carro) |
| **Metadados** | Botão "Ver" que abre as configurações específicas da transportadora |
| **Tabela de frete** | Tipo da tabela (CEP ou Raio) + nome. Exibe ícone de cadeado quando a [cobertura restrita](/docs/log/conceitos/tabela-frete/#cobertura-restrita) está ativada |
| **Horário de corte** | [Horário limite](/docs/log/conceitos/tabela-frete/#horário-de-corte) do dia para considerar o pedido como "do dia" |
| **Ativa** | Badge indicando se a integração está ativa ou inativa |
| **GRIS** | Percentual de GRIS configurado |
| **Advalorem** | Percentual de ad valorem configurado |
| **Fator de cubagem** | Valor do fator de cubagem (g/m³) |
| **Isenção de cubagem** | Peso máximo isento de cubagem (g) |
| **Tipo de operação** | Entrega ou Reversa |
| **Criada em** | Data/hora de criação |
| **Atualizada em** | Data/hora da última atualização |
| **Menu (⋮)** | Ações por integração |
### Menu de ações por integração (⋮) [#menu-de-ações-por-integração-]
| Ação | Descrição |
| ---------------------- | ---------------------------------------------- |
| **Editar** | Abre o modal de edição com abas de automações |
| **Duplicar** | Cria uma cópia da integração para outra filial |
| **Ativar / Desativar** | Alterna a situação da integração |
| **Excluir** | Remove a integração |
***
## Criar integração [#criar-integração]
Ao clicar em **Nova integração de transportadora**, o modal de criação é aberto:
### Campos obrigatórios [#campos-obrigatórios]
* **Filial** — Selecione a filial que usará esta integração.
* **Tipo de operação** — Entrega ou Reversa.
* **Transportador** — Selecione a transportadora e a modalidade (ex.: Uber / Carro, Correios / PAC).
### Campos opcionais [#campos-opcionais]
* **Tabela de frete** — Selecione uma [tabela de frete](/docs/log/products/tabelas-de-frete/) (CEP ou Raio) para vincular. As tabelas disponíveis são filtradas pela modalidade selecionada.
* **Cobertura restrita** — Aparece apenas quando uma tabela de frete é selecionada. Quando ativada, pedidos com destino fora da cobertura da tabela falham automaticamente.
* **Horário de corte** — Horário limite do dia (formato HH:MM:SS). Pedidos criados depois desse horário começam a contar prazo no próximo dia útil.
### Informações adicionais [#informações-adicionais]
Em uma seção expansível:
* **GRIS** — Percentual de gerenciamento de risco.
* **Advalorem** — Percentual ad valorem.
* **Fator de cubagem** — Fator para cálculo de peso cúbico (g/m³).
* **Isenção de cubagem** — Peso máximo isento de cálculo de cubagem (g).
### Configurações da transportadora [#configurações-da-transportadora]
Dependendo da transportadora selecionada, campos adicionais específicos podem aparecer — como credenciais de acesso, formato de etiqueta, comprovante obrigatório, entre outros. Esses campos variam de transportadora para transportadora.
***
## Editar integração (com automações) [#editar-integração-com-automações]
Ao clicar em **Editar**, um modal com abas laterais é aberto:
### Aba "Integração da transportadora" [#aba-integração-da-transportadora]
Exibe os dados da integração para edição:
* **Somente leitura:** Filial, Transportador, Tipo de operação
* **Editáveis:** Tabela de frete, Cobertura restrita, Horário de corte, GRIS, Advalorem, Fator de cubagem, Isenção de cubagem, Configurações específicas da transportadora
### Aba "Automações de envio" [#aba-automações-de-envio]
Lista as [automações de envio](/docs/log/conceitos/regra-envio/) vinculadas a esta integração. Cada automação mostra um indicador de validação:
* **Verde:** a automação está válida (o prazo referenciado existe na tabela de frete).
* **Vermelho:** a automação está inválida (o prazo foi removido ou não existe na tabela).
O badge no título da aba exibe o total de automações válidas (ex.: "3/4").
### Aba "Automações de reenvio" [#aba-automações-de-reenvio]
Lista as [automações de reenvio](/docs/log/conceitos/regra-reenvio/) vinculadas, com o mesmo indicador de validação.
### Aba "Automações de inatividade" [#aba-automações-de-inatividade]
Lista as [automações de inatividade](/docs/log/conceitos/regra-inatividade/) vinculadas, com o mesmo indicador de validação.
### Salvar [#salvar]
Ao clicar em salvar, a integração e todas as automações são atualizadas em conjunto. Não é possível salvar enquanto houver automações inválidas.
***
## Duplicar integração [#duplicar-integração]
Ao clicar em **Duplicar**, um modal é aberto com as configurações da integração original pré-preenchidas:
* **Fixos (não editáveis):** Transportador, Tipo de operação, Tabela de frete
* **Editáveis:** Filial (obrigatório — selecione a filial de destino), Horário de corte, Cobertura restrita, GRIS, Advalorem, Fator de cubagem, Isenção de cubagem, Configurações da transportadora
Isso facilita a criação de integrações semelhantes para diferentes filiais sem precisar preencher tudo do zero.
***
## Ativar / Desativar [#ativar--desativar]
Ao clicar em **Ativar** ou **Desativar**, um modal de confirmação é exibido. Integrações desativadas deixam de ser usadas nas cotações e nos envios.
***
## Excluir [#excluir]
Ao clicar em **Excluir**, um modal de confirmação é exibido. A integração é removida permanentemente.
***
## Visualizar tabela de frete [#visualizar-tabela-de-frete]
Na coluna **Tabela de frete**, ao clicar no nome da tabela, um modal é aberto com a visualização completa da [tabela de frete](/docs/log/products/tabelas-de-frete/) vinculada — os mesmos dados que aparecem na tela de Tabelas de Frete.
***
## Paginação [#paginação]
* Tamanhos de página: **50, 100, 150, 200**
***
## Próximos passos [#próximos-passos]
* [**Como usar**](/docs/log/products/integracoes-de-transportadora/como-usar/) — passo a passo para criar, editar e gerenciar integrações.
* [**Troubleshooting**](/docs/log/products/integracoes-de-transportadora/troubleshooting/) — dúvidas comuns e problemas frequentes.
***
## Links relacionados [#links-relacionados]
* [Conceito de Integração de Transportadora](/docs/log/conceitos/integracao-transportadora/) — o que é e para que serve
* [Tabelas de Frete](/docs/log/products/tabelas-de-frete/) — onde criar e gerenciar as tabelas vinculadas
* [Conceito de Tabela de Frete](/docs/log/conceitos/tabela-frete/) — estrutura, tipos e relação com contrato
* [Automações de Envio](/docs/log/products/regras-de-envio/) — automações que usam as integrações
* [Cotação de Frete](/docs/log/conceitos/cotacao-frete/) — como a integração e tabela são usadas na cotação
---
# Integrações de Transportadora — Troubleshooting (/docs/log/products/integracoes-de-transportadora/troubleshooting)
Este guia ajuda a resolver as dúvidas e problemas mais comuns ao configurar e usar integrações de transportadora.
***
## 1. "O pedido falhou com erro de prazo não encontrado" [#1-o-pedido-falhou-com-erro-de-prazo-não-encontrado]
O envio falha quando a automação tenta fazer a solicitação de coleta com um prazo que não existe na tabela de frete vinculada à integração.
**Causa mais comum:** a tabela de frete foi editada (prazo removido ou renomeado) sem atualizar as automações.
**O que fazer:**
1. Verifique qual prazo a automação está tentando usar (ex.: D1).
2. Acesse **Operação > Tabelas de frete** e verifique se o prazo existe na tabela vinculada à integração.
3. Se o prazo não existe: edite a automação para usar um prazo disponível, ou mude a ação para **mais barato** / **mais rápido**.
4. Se o prazo existe mas a tabela é outra: edite a integração e vincule a tabela correta.
***
## 2. "O pedido falhou como 'fora de cobertura'" [#2-o-pedido-falhou-como-fora-de-cobertura]
O envio falha quando o destino não está coberto pela tabela de frete e a **cobertura restrita** está ativada na integração.
**O que fazer:**
* **Ampliar a cobertura:** edite a [tabela de frete](/docs/log/products/tabelas-de-frete/) e adicione a faixa de CEP ou km que cobre o destino.
* **Desativar a restrição:** edite a integração e desmarque a opção de cobertura restrita.
***
## 3. "A integração está ativa mas os pedidos não estão sendo enviados por ela" [#3-a-integração-está-ativa-mas-os-pedidos-não-estão-sendo-enviados-por-ela]
Checklist rápido:
* **A integração está ativa?** Verifique a coluna "Ativa" na tabela.
* **A filial está correta?** Confirme que a integração pertence à filial do pedido.
* **O tipo de operação está correto?** Integrações de Entrega só atendem pedidos de entrega; Reversa só atende reversas.
* **Existe automação configurada?** Verifique se há uma [automação de envio](/docs/log/products/regras-de-envio/) que referencia esta integração ou que usa ação mais barato/mais rápido.
* **A tabela de frete cobre o destino?** Se a integração tem cobertura restrita ativada, o destino precisa estar mapeado na tabela.
* **O horário de corte foi ultrapassado?** Se o pedido chegou depois do horário de corte, a solicitação de coleta pode estar agendada para o próximo dia útil.
***
## 4. "A data de entrega esperada está errada" [#4-a-data-de-entrega-esperada-está-errada]
A data de entrega esperada depende de vários fatores configurados na integração:
* **Horário de corte** — Se o pedido foi criado depois do horário de corte, a contagem começa no próximo dia útil. Veja [Horário de corte](/docs/log/conceitos/tabela-frete/#horário-de-corte).
* **Dias de operação** — Dias em que a transportadora não opera são pulados.
* **Feriados** — Feriados cadastrados são pulados.
* **Prazo da tabela de frete** — Confira se o prazo (D1, D3, etc.) está correto na tabela.
**O que verificar:**
1. Confira o **horário de corte** na integração.
2. Verifique os **dias de operação** configurados.
3. Confirme o **prazo** na tabela de frete vinculada.
***
## 5. "Não consigo criar uma integração — erro de duplicidade" [#5-não-consigo-criar-uma-integração--erro-de-duplicidade]
Cada filial pode ter apenas **uma integração por combinação** de transportadora + modalidade + tipo de operação. Exemplo: não é possível ter duas integrações Uber / Carro / Entrega para a mesma filial.
**O que fazer:**
* Verifique se já existe uma integração com a mesma combinação. Use os filtros de filial e transportador para encontrar.
* Se a integração existente está desativada, ative-a em vez de criar uma nova.
* Se precisa de configurações diferentes para a mesma combinação, edite a integração existente.
***
## 6. "Alterei a tabela de frete e as automações ficaram inválidas" [#6-alterei-a-tabela-de-frete-e-as-automações-ficaram-inválidas]
Ao trocar a tabela de frete de uma integração, os prazos disponíveis mudam. Automações que usam **prazo específico** com prazos da tabela anterior ficam inválidas.
**O que fazer:**
1. No modal de edição da integração, clique nas abas de automações (envio, reenvio, inatividade).
2. Localize automações com indicador vermelho.
3. Ajuste o prazo para um que existe na nova tabela, ou mude a ação para **mais barato** / **mais rápido**.
4. Salve.
***
## 7. "A automação mostra alerta de 'integração desativada'" [#7-a-automação-mostra-alerta-de-integração-desativada]
Na tela de [Automações de Envio](/docs/log/products/regras-de-envio/), automações que referenciam uma integração desativada ou excluída mostram um badge de alerta.
**O que fazer:**
* **Se a integração foi desativada:** reative-a na tela de integrações.
* **Se a integração foi excluída:** edite a automação e selecione outra integração, ou desative a automação.
***
## 8. "Quero usar a mesma tabela de frete em várias filiais" [#8-quero-usar-a-mesma-tabela-de-frete-em-várias-filiais]
Uma tabela de frete pode ser compartilhada por várias integrações. Para isso:
1. Crie a tabela de frete uma única vez em **Operação > Tabelas de frete**.
2. Ao criar ou editar cada integração, selecione a mesma tabela de frete.
3. Ou use a opção de **duplicar** uma integração que já tem a tabela vinculada — a tabela é mantida na cópia.
***
## 9. "Não tenho acesso à tela de Integrações de Transportadora" [#9-não-tenho-acesso-à-tela-de-integrações-de-transportadora]
O acesso à tela depende das permissões configuradas na sua conta. Entre em contato com o administrador da conta ou com o suporte da Abbiamo para verificar se o módulo de integrações de transportadora está habilitado.
---
# Pesquisa de Satisfação (CSAT) — Visão Geral (/docs/log/products/pesquisa-satisfacao)
A tela de **Pesquisas de Satisfação** exibe as avaliações enviadas pelos clientes após a entrega dos seus pedidos. As pesquisas são disparadas automaticamente pelo sistema e os resultados ficam disponíveis para consulta e análise.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/csat](https://dashboard.abbiamolog.com/csat)
* **Menu:** seção **Operação** > **Pesquisas de satisfação**
***
## Barra de filtros [#barra-de-filtros]
| Filtro | Descrição |
| ----------------------- | --------------------------------------------------------------------- |
| **Pesquisar avaliação** | Busca por pedido, cliente ou ID da avaliação |
| **Entregue por** | Filtra por transportadora que realizou a entrega |
| **Avaliação** | Filtra pela nota dada pelo cliente (ex.: todas, positivas, negativas) |
| **Período** | Intervalo de datas das avaliações |
***
## Configuração do disparo [#configuração-do-disparo]
As pesquisas de satisfação são configuradas na tela de [Notificações](/docs/log/settings/notificacoes/). O gatilho **"Pedido entregue + avaliação"** define quando o cliente recebe o link para avaliar a entrega.
***
## Estado vazio [#estado-vazio]
Quando não há avaliações no período selecionado:
> *"Nenhuma pesquisa de satisfação encontrada"*
***
## Paginação [#paginação]
* **Padrão:** 50 avaliações por página
* **Opções:** 50, 100, 150, 200
---
# Tela de Pedidos — Como Usar (/docs/log/products/pedidos/como-usar)
Guia prático das principais ações para operar pedidos no dia a dia.
***
## Fluxo típico [#fluxo-típico]
1. Acesse **Operação > Pedidos** (`/orders`).
2. Defina período, status e demais filtros para trazer a visão correta.
3. Use a busca por pedido/NF para localizar itens específicos.
4. Clique no pedido para abrir detalhes no side panel.
5. Execute ações individuais (menu ⋮) ou selecione múltiplos pedidos para ações em lote.
6. Exporte CSV quando precisar compartilhar a visão atual da tabela.
***
## Filtrar e localizar pedidos [#filtrar-e-localizar-pedidos]
### Busca rápida [#busca-rápida]
No campo de busca, pesquise por **NF**, **número do pedido** ou `external_id`.
### Filtros principais [#filtros-principais]
* **Status** (multisseleção)
* **Entregue por**
* **Período** (até 93 dias)
* **Marcadores** (incluindo "Sem marcadores")
* **Filtros avançados** por campo (Pedido, NF, Nome do cliente, Documento do cliente, Tipo da entrega, Origem do pedido, Filial e Tipo da operação)
### Visibilidade de colunas [#visibilidade-de-colunas]
Use o botão de colunas para mostrar ou ocultar informações na tabela conforme a necessidade da operação.
***
## Interagir com pedidos na tabela [#interagir-com-pedidos-na-tabela]
### Ações de clique [#ações-de-clique]
* **Clique simples:** abre detalhes no side panel.
* **Seleção múltipla:** ativa barra de ações em lote.
### Ações em lote [#ações-em-lote]
Com múltiplas linhas selecionadas, podem aparecer opções como:
* **Solicitar coleta** (vários pedidos de uma vez — veja [Solicitar coleta em massa](#solicitar-coleta-em-massa))
* **Pronto pra retirada**
* **Etiquetas**
* **DANFE**
As opções exibidas dependem da elegibilidade dos pedidos selecionados.
### Ações por pedido (menu ⋮) [#ações-por-pedido-menu-]
Algumas das ações mais comuns:
* **Ver rastreio**
* **Ver etiqueta**
* **Ver DANFE**
* **Duplicar pedido**
* **Anexar comprovantes**
* **Editar marcadores**
***
## Simular frete [#simular-frete]
O botão **Simular frete** no cabeçalho da tela permite consultar as opções de frete disponíveis antes de enviar um pedido.
### Passo a passo [#passo-a-passo]
1. Clique em **Simular frete** no cabeçalho da tela de pedidos.
2. Selecione a **filial de origem**.
3. Informe o **CEP de destino** e o **peso total** (em gramas).
4. Clique em **Cotar**.
5. O sistema exibe as opções de frete disponíveis, cada uma com:
* **Transportadora** e **modalidade**
* **Preço** do frete
* **Data de entrega esperada**
* **Distância** (quando disponível)
***
## Solicitar coleta em massa [#solicitar-coleta-em-massa]
Selecione vários pedidos na tabela e solicite a coleta de todos de uma vez, escolhendo uma transportadora em comum e com a cotação na hora.
### Passo a passo [#passo-a-passo-1]
1. Na tabela, marque os checkboxes dos pedidos que quer coletar.
2. Na barra de ações em lote, clique em **Solicitar coleta**.
3. No modal, em **Ações Rápidas** → "Selecione todos os pedidos para", escolha a transportadora — ela é aplicada a **todos os pedidos de uma vez**. As opções aparecem com o **preço do frete** de cada uma. Se precisar, ajuste o frete de um pedido específico depois.
4. Confira e clique em **Solicitar coleta** no rodapé do modal.
***
## Exportar dados da tela [#exportar-dados-da-tela]
O botão **Exportar** gera um CSV com a visão atual da tabela, considerando:
* filtros aplicados
* colunas visíveis
* contexto atual da página
***
## Boas práticas operacionais [#boas-práticas-operacionais]
* Ajuste filtros antes de executar ações em lote.
* Verifique status/substatus antes de acionar fluxos como retirada e coleta.
* Revise filtros e seleção antes de confirmar ações em lote.
---
# Tela de Pedidos — Conhecimentos Internos (/docs/log/products/pedidos/conhecimentos-internos)
***
## Modo tempo real (detalhes técnicos) [#modo-tempo-real-detalhes-técnicos]
Quando habilitado no contexto elegível:
* atualização automática da lista a cada 30 segundos
* janela de dados recentes das últimas 8 horas
* bloqueio da alteração manual de período
* indicador visual "Em tempo real" no cabeçalho
* ocultação da paginação visual em algumas combinações de tela
Elegibilidade:
* condicionado por regra de seller group no estado atual da aplicação
***
## Feature flags — Tela de Pedidos e Side Panel [#feature-flags--tela-de-pedidos-e-side-panel]
Este documento lista **todas as feature flags** que impactam a tela de Pedidos e o side panel (detalhes do pedido), onde são usadas e como afetam a percepção da tela.
As flags são configuradas por **seller group** (em `user.seller_group.feature_config` ou, no caso de `simplified_danfe`, via variável de ambiente). Quando uma flag está desligada, o elemento associado não é exibido ou o comportamento padrão é usado.
### Resumo rápido [#resumo-rápido]
| Flag | Onde atua | Efeito principal na percepção |
| -------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------ |
| `simplified_danfe` | Tela + menu da linha + side panel | Define qual URL/backend abre ao clicar em "Ver DANFE" / "DANFE" |
| `mark_as_collected` | Tela de pedidos | Exibe "Marcar Coletado" na barra de seleção e atalho "Filtrar Pedidos Prontos Para Coleta" |
| `order_supply_enabled` | Tela + side panel | Exibe atalho "Filtrar Pedidos Abastecimento" e campo "Ordem de Operação" nas Informações |
| `order_external_id_search` | Tela de pedidos | Exibe coluna "ID Externo" e ID externo nos resultados da busca de pedido |
### 1. `simplified_danfe` [#1-simplified_danfe]
**O que controla:** Qual serviço de DANFE é usado ao abrir o comprovante fiscal (fluxo "Natura"/simplificado vs padrão).
**Onde é usada:**
* **Tela de pedidos — ação em lote:** ao clicar em **DANFE** na barra flutuante (pedidos selecionados), a URL aberta é:
* **Ligada:** `NX_MAIL_DANFE_URL_APP_RUNNER` + `/mail-danfe/v1/orders?trackings=...`
* **Desligada:** `NX_MAIL_DANFE_URL` + `/v1/orders?trackings=...`
* **Menu da linha (⋮):** opção **Ver DANFE** usa a mesma regra para abrir o link.
* **Side panel — dropdown Ações:** opção **Ver DANFE** usa a mesma regra.
**Como afeta a percepção:**
* O texto continua sendo **"Ver DANFE"** / **"DANFE"** em todos os lugares.
* A diferença é apenas o **destino** (domínio/backend) que abre na nova aba. Para o usuário a tela "parece" a mesma; apenas o conteúdo/URL do DANFE muda conforme a flag.
* A opção só é habilitada quando o pedido tem NF e chave de acesso; a flag não altera essa regra.
**Detalhe técnico:** além de `feature_config`, essa flag pode ser definida pela variável de ambiente `NX_DANFE_SELLER_GROUP_ID` (lista de IDs de seller group separados por vírgula). Se o `seller_group_id` do usuário estiver nessa lista, a flag é considerada ligada.
### 2. `mark_as_collected` [#2-mark_as_collected]
**O que controla:** Exibição da ação **Marcar Coletado** e do atalho de filtro para pedidos prontos para coleta.
**Onde é usada:**
* **Tela de pedidos — barra flutuante:** quando há linhas selecionadas, o botão **Marcar Coletado** só aparece se a flag estiver ligada. Ao clicar, navega para o fluxo `mark-collected` com os pedidos selecionados.
* **Tela de pedidos — dropdown Atalhos:** o botão **Atalhos** (ícone ListEnd) só é exibido se pelo menos uma das flags `mark_as_collected` ou `order_supply_enabled` estiver ligada. Com `mark_as_collected` ligada, dentro de Atalhos aparece o item **Filtrar Pedidos Prontos Para Coleta**, que aplica:
* filtro de origem de criação `HERMES-XML`
* filtro de status `CREATED`.
**Como afeta a percepção:**
* **Desligada:** não há botão "Marcar Coletado" na seleção múltipla e não há atalho para "prontos para coleta". Quem não tem a flag não vê esse fluxo de coleta nem o filtro rápido.
* **Ligada:** a tela ganha uma ação clara de "marcar como coletado" em lote e um atalho para focar nos pedidos prontos para coleta, mudando a percepção da tela para um fluxo mais orientado a coleta.
### 3. `order_supply_enabled` [#3-order_supply_enabled]
**O que controla:** Visibilidade de conceitos de **abastecimento** (operação SUPPLY) na lista e no detalhe do pedido.
**Onde é usada:**
* **Tela de pedidos — dropdown Atalhos:** (junto com `mark_as_collected`) define se o botão **Atalhos** aparece. Com `order_supply_enabled` ligada, dentro de Atalhos aparece o item **Filtrar Pedidos Abastecimento**, que aplica filtro por tipo de operação `SUPPLY`.
* **Side panel — seção Informações:** o campo **Ordem de Operação** (operation: SUPPLY / DELIVERY) só é exibido quando a flag está ligada. Caso contrário, o campo fica oculto na seção Informações.
**Como afeta a percepção:**
* **Desligada:** não há atalho para "abastecimento", e no painel de detalhes o usuário não vê se o pedido é de operação SUPPLY ou DELIVERY. A tela parece "só entrega".
* **Ligada:** a tela passa a expor atalho para filtrar pedidos de abastecimento e, no side panel, o campo de operação deixa explícito o tipo (abastecimento vs entrega), reforçando a percepção de que há dois fluxos (abastecimento e entrega).
**Nota:** A seção **Trecho de origem** (pedido anterior / abastecimento) no side panel depende de o pedido ter `previous_order` (dado), não desta flag. A flag só controla o campo "Ordem de Operação" e o atalho de filtro.
### 4. `order_external_id_search` [#4-order_external_id_search]
**O que controla:** Exposição do **ID externo** do pedido na busca e na tabela.
**Onde é usada:**
* **Tela de pedidos — busca assíncrona:** nas sugestões de pedido (combobox de busca), cada item pode exibir a linha **"ID Externo:"** seguido do valor de `order.external_id` quando a flag está ligada e o pedido tem `external_id`.
* **Tela de pedidos — colunas da tabela:** é adicionada a coluna **ID Externo** (`external_id`) após a coluna do número do pedido. O conteúdo é exibido (ou vazio) conforme o dado do pedido.
* **Lista de pedidos (versão v1):** na página legada de listagem, a coluna **external\_id** também é incluída quando a flag está ligada.
**Como afeta a percepção:**
* **Desligada:** a busca não mostra ID externo nas sugestões e a tabela não tem coluna "ID Externo". A tela parece centrada só em número de pedido, NF e rastreio.
* **Ligada:** o usuário passa a ver o identificador do sistema de origem (ERP, e-commerce etc.) na busca e na tabela, melhorando a percepção de rastreabilidade e integração com sistemas externos.
### Flags relacionadas a "pedido" mas fora da tela de listagem / side panel [#flags-relacionadas-a-pedido-mas-fora-da-tela-de-listagem--side-panel]
As flags abaixo não alteram diretamente a **tela de Pedidos** (lista) nem o **side panel** de detalhes; atuam em outros fluxos acessíveis a partir do contexto de pedidos:
| Flag | Onde atua | Efeito |
| --------------------------- | --------------------------------------------- | --------------------------------------------------------- |
| `supply_order_enabled` | Criação de pedido (Upload / criação em massa) | Habilita criação de pedidos de abastecimento nesse fluxo. |
| `supply_order_cd_seller_id` | Upload XML | Usada na lógica do componente de upload XML (CD/seller). |
Ou seja: quem só consulta a lista e o side panel não é afetado por essas duas; elas mudam a **criação** de pedidos (e, no caso do XML, o comportamento do upload).
### Onde as flags são definidas [#onde-as-flags-são-definidas]
* **Código:** `apps/seller-hermes/src/hooks/useSellerGroupFeatureFlag.ts` — tipo `FeatureFlag` e função `getSellerGroupFeatureFlag`.
* **Fonte do valor:** em geral `user.seller_group.feature_config[flag]`. A exceção é `simplified_danfe`, que também pode ser ligada quando `user.seller_group_id` está em `process.env['NX_DANFE_SELLER_GROUP_ID']` (lista separada por vírgula).
Documentar no código ou no backend quais seller groups têm cada flag evita dúvidas sobre por que um cliente vê ou deixa de ver cada comportamento descrito acima.
---
# Tela de Pedidos — Visão Geral (/docs/log/products/pedidos)
A tela de **Pedidos** concentra a operação diária: consulta, filtragem, acompanhamento de status, ações em lote e ações individuais por pedido.
***
## Onde acessar [#onde-acessar]
* **URL principal:** [https://dashboard.abbiamolog.com/orders](https://dashboard.abbiamolog.com/orders)
* **Menu:** seção **Operação** > **Pedidos**
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Menu lateral duplo** | Abre/fecha a sidebar |
| **Título** | "Pedidos" |
| **Simular frete** | Abre modal de [cotação de frete](/docs/log/conceitos/cotacao-frete/): selecione a filial de origem, informe CEP de destino e peso para ver opções de frete com preço e prazo. As opções vêm das [tabelas de frete](/docs/log/products/tabelas-de-frete/) configuradas nas [integrações de transportadora](/docs/log/products/integracoes-de-transportadora/) |
| **Solicitar coleta** | Permite solicitar coletas e reversas |
| **Criar pedido** | Abre fluxo de criação de pedido |
| **Barra lateral direita (Novo!)** | KPIs detalhados em painel lateral (quando exibido) |
### Barra de filtros e controles [#barra-de-filtros-e-controles]
* **Busca de pedido** por NF, número do pedido e `external_id`
* **Atualizar lista** manualmente (botão de refresh)
* **Status** (multisseleção)
* **Entregue por** (transportadora/responsável da última entrega)
* **Período** (date range, até 93 dias)
* **Marcadores** (incluindo opção "Sem marcadores")
* **Filtros avançados** (filtro por campo)
* **Visibilidade de colunas** (mostrar/ocultar)
* **Exportar** (CSV da tabela atual)
### Tabela de pedidos [#tabela-de-pedidos]
Colunas principais disponíveis:
| Coluna | O que mostra |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Pedido** | Número do pedido |
| **ID Externo** | ID externo do pedido |
| **NF** | Número da nota fiscal |
| **Filial** | Filial do pedido |
| **Tipo da entrega** | Entrega / Retirada / Reversa |
| **Criado em** | Data/hora de criação |
| **Atualizado em** | Tempo relativo desde última atualização |
| **Envios** | Quantidade de envios |
| **Status / Sub Status** | Situação atual do pedido (veja [Status de pedido](/docs/log/conceitos/status-de-pedido/) para a lista completa) |
| **Entregue por** | Responsável da última entrega |
| **Cliente** | Nome do cliente |
| **Chegada** | Data/hora de chegada |
| **Prazo prometido** | Data/hora prometida (quando aplicável) |
| **Frete pago** | Valor de frete |
| **Rastreio** | Código de rastreio |
| **Marcadores** | Tags aplicadas |
| **Indicadores** | Avaliação e comprovante |
| **Ações** | Menu de ações por pedido (⋮) |
### Interações de linha [#interações-de-linha]
* **Clique simples:** abre detalhes do pedido em side panel (`order_id` na URL)
* **Seleção múltipla:** habilita barra de ações em lote
### Paginação [#paginação]
* Tamanhos de página: **50, 100, 150, 200**
### Estado vazio [#estado-vazio]
Quando não há resultados:
> *"Nenhum pedido encontrado. Crie um novo agora mesmo"*
***
## Filtros avançados disponíveis [#filtros-avançados-disponíveis]
No menu de filtros avançados, os campos incluem:
* Pedido (`invoice.number`)
* NF (`invoice.invoice_number`)
* Nome do cliente (`customer.name`)
* Documento do cliente (`customer.document_number`)
* Tipo da entrega (`invoice.type`)
* Origem do pedido (`invoice.creation_origin`)
* Filial (`invoice.seller_id`)
* Tipo da operação (`invoice.operation`)
***
## Ações em lote (seleção de múltiplos pedidos) [#ações-em-lote-seleção-de-múltiplos-pedidos]
Ao selecionar linhas na tabela, a barra flutuante pode exibir:
* **Pronto pra retirada** (somente pedidos elegíveis de retirada)
* **Etiquetas** (gera labels para os rastreios selecionados)
* **DANFE** (habilitado somente quando todos os pedidos selecionados têm NF e chave de acesso)
***
## Ações por pedido (menu ⋮) [#ações-por-pedido-menu-]
As opções variam por status e tipo do pedido.
### Ações comuns [#ações-comuns]
* **Ver rastreio**
* **Ver etiqueta**
* **Ver DANFE** (desabilita se o pedido não tiver NF/chave)
* **Duplicar pedido**
* **Anexar comprovantes** (somente quando status = `SUCCESSFUL`)
* **Editar marcadores**
### Ações condicionais [#ações-condicionais]
* **Finalizar retirada** (pedido TAKEOUT em `DISPATCHED` + substatus `READY_FOR_TAKEOUT`)
* **Solicitar coleta/reversa** (tipos DELIVERY/RETURN)
* **Reenviar pedido** (status elegíveis + tipo de entrega elegível)
* **Cancelar agendamento** (somente quando status = `SCHEDULED`)
***
## Status e substatus [#status-e-substatus]
Status principais suportados na tela:
* `CREATED` (Criado)
* `PENDING` (Pendente)
* `DISPATCHED` (Despachado)
* `IN_TRANSIT` (Em trânsito)
* `START_DELIVERY` (Em rota)
* `SUCCESSFUL` (Sucesso)
* `FAILED` (Falha)
* `ORDER_FAILED` (Falha na solicitação)
* `RETURNED` (Devolvido)
* `SCHEDULED` (Agendado)
* `MANUAL_HANDLE` (Baixa manual)
* entre outros estados operacionais
Substatus também são exibidos na coluna dedicada (ex.: `WAITING_TAKEOUT_CONFIRMATION`, `READY_FOR_TAKEOUT`, `SEARCHING_DRIVER`).
***
## KPIs da tela [#kpis-da-tela]
### Painel lateral direito [#painel-lateral-direito]
* OTD (On Time Delivery)
* Pedidos por status
* Pedidos por tipo
* Taxa de comprovantes anexados
* Faturamento de frete em entregas
Possíveis bloqueios do painel:
* filtros de cliente ativos
* erro de consulta de KPI
* limite de filiais excedido
***
## Comportamentos automáticos importantes [#comportamentos-automáticos-importantes]
* **Reset de paginação:** alterações de filtros voltam para a primeira página
* **Preservação de seleção:** seleção é reconciliada quando os dados mudam
* **Side panel por URL:** `order_id` em query string abre detalhes do pedido
* **Exportação local:** exporta CSV da visão atual da tabela (respeitando visibilidade de colunas)
***
## Próximos passos [#próximos-passos]
* [**Como usar**](/docs/log/products/pedidos/como-usar/) — passo a passo da operação diária na tela.
* [**Troubleshooting**](/docs/log/products/pedidos/troubleshooting/) — dúvidas comuns, filtros e quando usar Relatórios.
---
# Tela de Pedidos — Troubleshooting (/docs/log/products/pedidos/troubleshooting)
Este guia ajuda a resolver as dúvidas mais comuns durante a operação na tela de **Pedidos**.
***
## 1. "Não encontro meu pedido" [#1-não-encontro-meu-pedido]
Checklist rápido:
* valide o **período** selecionado
* confira **status** e outros filtros ativos
* remova filtros de **marcadores** e filtros avançados temporariamente
* pesquise por **NF** e por **número do pedido**
Se mesmo assim não aparecer, teste o refresh da lista e confirme se o pedido está na filial/escopo correto do usuário.
***
## 2. "Botão ou ação não aparece" [#2-botão-ou-ação-não-aparece]
Na tela de Pedidos, ações são exibidas por combinação de:
* tipo do pedido (DELIVERY, TAKEOUT, RETURN)
* status e substatus atuais
* elegibilidade operacional do pedido
Exemplos comuns:
* **Finalizar retirada** depende de tipo, status e substatus
* **Solicitar coleta** depende do tipo de pedido e do fluxo disponível
***
## 3. "Exportei CSV, mas faltam dados" [#3-exportei-csv-mas-faltam-dados]
A exportação da tela é **local** e reflete apenas a visão atual da tabela.
Ela respeita:
* filtros aplicados
* colunas visíveis
* escopo atual de navegação
Se você precisa de dados mais amplos, históricos ou para análise detalhada, use
[Relatórios](/docs/log/products/relatorios/) para extrair datasets completos.
***
## 4. "Preciso de extração para BI, auditoria ou histórico longo" [#4-preciso-de-extração-para-bi-auditoria-ou-histórico-longo]
Nesses casos, a recomendação é usar o produto **Relatórios**, não a exportação rápida da tela de Pedidos.
---
# Regras de Frete — Como Usar (/docs/log/products/regras-de-frete/como-usar)
***
## Criar uma regra de frete [#criar-uma-regra-de-frete]
1. Acesse **Cotação de frete > Regras de frete**.
2. Clique em **Nova regra**.
3. Preencha o formulário:
* **Nome** — Identifique a regra (ex.: "Margem 10% — Sul").
* **Filial** — Selecione a filial onde a regra será aplicada.
* **Condições** — Defina os critérios (ex.: CEP de destino, transportadora, modalidade, peso).
* **Ação** — Escolha o tipo de ajuste:
* **Ajuste de preço** (valor fixo ou percentual)
* **Ajuste de prazo** (dias adicionais ou redução)
* **Excluir modalidade** (remove da cotação)
* **Priorizar opção** (destaque na cotação)
4. Clique em **Salvar**.
***
## Editar uma regra [#editar-uma-regra]
1. Na tabela, localize a regra desejada.
2. Clique no menu **⋮** e selecione **Editar regra**.
3. Faça as alterações e salve.
***
## Ativar ou desativar [#ativar-ou-desativar]
1. No menu **⋮**, selecione **Ativar** ou **Desativar**.
2. Regras desativadas não são aplicadas nas cotações.
***
## Excluir uma regra [#excluir-uma-regra]
1. No menu **⋮**, selecione **Excluir regra**.
2. Confirme a exclusão.
***
## Dicas de uso [#dicas-de-uso]
* **Ordene as regras**: a ordem determina qual regra é aplicada primeiro quando múltiplas condições se sobrepõem.
* **Separe por filial**: regras por filial evitam que ajustes destinados a uma região afetem outras.
* **Combine com Automações de Envio**: use regras de frete para filtrar opções e automações de envio para escolher qual será usada no despacho.
---
# Regras de Frete — Visão Geral (/docs/log/products/regras-de-frete)
As **Regras de Frete** permitem modificar os resultados da [cotação de frete](/docs/log/conceitos/cotacao-frete/) antes de apresentá-los ao cliente ou à automação de envio — ajustando preços, alterando prazos ou ocultando modalidades específicas.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/quotation-rules](https://dashboard.abbiamolog.com/quotation-rules)
* **Menu:** seção **Cotação de frete** > **Regras de frete**
***
## O que uma regra de frete pode fazer [#o-que-uma-regra-de-frete-pode-fazer]
| Tipo de ajuste | Exemplo |
| ---------------------- | ------------------------------------------------ |
| **Alterar preço** | Adicionar margem de 10% ao frete cotado |
| **Alterar prazo** | Adicionar 1 dia ao prazo de entrega |
| **Excluir modalidade** | Remover "Expresso" de determinada transportadora |
| **Priorizar opção** | Destacar a opção mais barata |
***
## Quando usar [#quando-usar]
Use regras de frete quando precisar padronizar ou ajustar as opções de frete para situações específicas — por exemplo, ocultar modalidades que não atendem a determinadas regiões, ou acrescentar custo operacional ao valor cotado.
---
# Automações de Envio — Como Usar (/docs/log/products/regras-de-envio/como-usar)
Guia prático das principais ações para configurar e operar automações de envio.
***
## Fluxo típico [#fluxo-típico]
1. Acesse **Operação > Automações de envio** (`/dispatch-rules`).
2. Selecione a **filial** cujas automações deseja gerenciar.
3. Use a busca por nome para localizar automações específicas.
4. Clique em **Criar automação** para nova automação ou use o menu (⋮) para editar, duplicar ou ativar/desativar.
5. Use **Editar Sequência** para reordenar as automações quando necessário.
***
## Criar uma nova automação [#criar-uma-nova-automação]
### Passo 1: Informações básicas [#passo-1-informações-básicas]
1. Clique em **Criar automação**.
2. Dê um **nome** claro para a automação (ex.: "SP Capital - UBER Carro EXP60").
3. Defina as **condições**:
* Adicione condições (CEP, cidade, valor, etc.) ou marque "Todos os pedidos serão automatizados".
* Use operadores como "é igual a", "contém", "está entre" conforme o campo.
4. Escolha a **ação**:
* **Método específico** — Selecione transportadora, modalidade e prazo.
* **Mais barato** ou **Mais rápido** — O sistema escolherá automaticamente após cotar.
5. Selecione o **tipo de operação** (ENTREGA ou REVERSA).
### Passo 2: Quando acionar [#passo-2-quando-acionar]
Defina em que momento a automação será avaliada:
* **A qualquer momento** — Para automações que devem rodar 24h.
* **Durante horário de operação** — Para respeitar o horário da filial.
* **Fora do horário** — Para pedidos criados fora do expediente.
* **Dias e horários customizados** — Para automações específicas (ex.: só em dias úteis).
### Passo 3: Quando solicitar coleta [#passo-3-quando-solicitar-coleta]
Defina quando o envio será efetivamente feito após a automação ser acionada:
* **Imediatamente** — Para solicitação de coleta instantânea.
* **Próximo horário de operação** — Para aguardar o próximo slot disponível.
* **Próxima abertura da loja** — Para sempre agendar para o próximo dia útil.
* **Agendamento customizado** — Para dias e horários fixos.
* **Janela de entrega** — Para usar a janela definida no pedido (quando habilitado).
### Passo 4: Configurações avançadas (opcional) [#passo-4-configurações-avançadas-opcional]
* **Data de Ativação** — Quando a automação passa a valer.
* **Validade** — Quando a automação expira.
* **Delay** — Minutos para aguardar ou adiantar (valores positivos = aguardar, negativos = adiantar).
***
## Ordenar automações [#ordenar-automações]
A ordem das automações define a prioridade. O sistema avalia da primeira para a última e aplica a **primeira** cujas condições forem atendidas.
1. Clique em **Editar Sequência**.
2. Arraste as automações para a ordem desejada.
3. Salve.
***
## Duplicar uma automação [#duplicar-uma-automação]
Útil para criar variações de uma automação existente:
1. No menu (⋮) da automação, clique em **Duplicar automação**.
2. Ajuste nome, condições ou ação conforme necessário.
3. Salve.
***
## Ativar e desativar [#ativar-e-desativar]
* **Desativar** — A automação deixa de ser avaliada, mas permanece salva. Útil para pausar temporariamente.
* **Ativar** — A automação volta a ser avaliada.
Use o menu (⋮) > **Ativar automação** ou **Desativar automação**.
***
## Alerta de integração desativada ou deletada [#alerta-de-integração-desativada-ou-deletada]
Quando uma automação está **ativa** mas a integração da transportadora está **desativada** ou **deletada**, um badge de alerta aparece na tabela.
Nesse caso, a automação não funcionará. Você pode:
* Reativar a integração em **Configurações > Integrações de transportador**, ou
* Editar a automação e escolher outra transportadora e prazo, ou
* Desativar a automação até resolver a integração.
***
## Boas práticas [#boas-práticas]
* Revise a sequência das automações periodicamente.
* Use nomes descritivos para facilitar a manutenção.
* Teste novas automações com poucos pedidos antes de ampliar.
* Configure **Data de Ativação** e **Validade** para automações sazonais ou promocionais.
---
# Automações de Envio — Visão Geral (/docs/log/products/regras-de-envio)
A tela de **Automações de Envio** permite criar, editar e gerenciar as automações que automatizam a [solicitação de coleta](/docs/log/acoes/solicitacao-coleta/) de pedidos para transportadoras.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/dispatch-rules](https://dashboard.abbiamolog.com/dispatch-rules)
* **Menu:** seção **Operação** > **Automações de envio**
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ---------------------- | ----------------------------------------- |
| **Menu lateral duplo** | Abre/fecha a sidebar |
| **Título** | "Automações de envio" |
| **Criar automação** | Abre o modal de criação de nova automação |
### Barra de filtros e controles [#barra-de-filtros-e-controles]
* **Seletor de filial** — Escolher a filial cujas automações serão exibidas.
* **Campo de busca** — Busca por nome da automação.
* **Botão atualizar** — Recarrega a lista de automações.
* **Editar Sequência** — Abre modal para reordenar todas as automações da filial.
* **Filtros avançados** — Campos: Nome, Situação (Ativa/Desativada), Data de Ativação, Validade.
* **Visibilidade de colunas** — Mostrar/ocultar colunas da tabela.
### Tabela de automações [#tabela-de-automações]
| Coluna | O que mostra |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Sequência** | Número da ordem (clicável para abrir modal de ordenação) |
| **Nome** | Nome da automação |
| **Condições** | Resumo das condições ("Condições atendidas", "Condição atendida" ou "Todos os pedidos") |
| **Acionada** | Quando a automação é acionada: "A qualquer momento", "Durante horário de operação", "Fora do horário" ou "Dias e horários customizados" |
| **Ação** | Tipo: prazo específico (com transportadora, modalidade e prazo), mais barato ou mais rápido |
| **Data de Ativação** | Quando a automação passa a valer |
| **Validade** | Quando a automação expira |
| **Tipo de Operação** | ENTREGA ou REVERSA |
| **Situação** | Ativa ou Desativada |
| **Alerta** | Badge quando a automação está ativa mas a integração está desativada ou deletada |
| **Criada em** | Data/hora de criação |
| **Atualizada em** | Data/hora da última atualização |
| **Menu (⋮)** | Ações por automação |
### Menu de ações por automação (⋮) [#menu-de-ações-por-automação-]
| Ação | Descrição |
| ------------------------------ | ------------------------------- |
| **Ver automação** | Abre modal somente leitura |
| **Editar automação** | Abre modal de edição |
| **Duplicar automação** | Cria cópia da automação |
| **Ativar/Desativar automação** | Alterna a situação da automação |
| **Excluir automação** | Remove a automação |
***
## Modal de criação e edição [#modal-de-criação-e-edição]
O modal permite configurar:
### Informações básicas [#informações-básicas]
* **Nome** — Título da automação.
* **Condições** — Construtor de condições (campo, operador, valor). Opção "Todos os pedidos serão automatizados" quando não há condições.
* **Ação** — Escolha do tipo:
* **Enviar para prazo específico** — Transportadora + modalidade + prazo (ex.: UBER/CARRO/EXP60).
* **Enviar para mais barato** — Cotação e escolha automática.
* **Enviar para mais rápido** — Cotação e escolha automática.
* **Tipo de operação** — ENTREGA ou REVERSA.
### Quando acionar [#quando-acionar]
* **A qualquer momento** — Sem restrição de horário.
* **Durante horário de operação** — Só quando a filial está em horário de operação.
* **Fora do horário de operação** — Só fora do horário.
* **Dias e horários customizados** — Definir dias da semana e horários (ex.: SEG 08:00–18:00).
### Quando solicitar coleta [#quando-solicitar-coleta]
* **Despachar imediatamente** — Assim que a automação for acionada.
* **Próximo horário de operação disponível** — Aguardar próximo slot ou próximo dia útil.
* **Agendar para a próxima abertura da loja** — Sempre agendar para o próximo dia de operação.
* **Agendamento customizado** — Definir dias e horários específicos.
* **Agendar para início da janela de entrega** — Usar a janela de entrega do pedido (quando habilitado).
### Configurações avançadas [#configurações-avançadas]
* **Data de Ativação** — Quando a automação passa a valer.
* **Validade** — Quando a automação expira.
* **Delay** — Minutos para aguardar ou adiantar a solicitação de coleta.
***
## Estado vazio [#estado-vazio]
Quando não há automações para a filial selecionada:
> *"Nenhuma automação de envio encontrada"*\
> *"Crie uma nova automação de envio para começar a automatizar o envio de pedidos"*
***
## Paginação [#paginação]
* Tamanhos de página: **50, 100, 150, 200**
***
## Próximos passos [#próximos-passos]
* [**Como usar**](/docs/log/products/regras-de-envio/como-usar/) — passo a passo para criar e gerenciar automações.
* [**Troubleshooting**](/docs/log/products/regras-de-envio/troubleshooting/) — dúvidas comuns e problemas frequentes.
---
# Automações de Envio — Troubleshooting (/docs/log/products/regras-de-envio/troubleshooting)
Este guia ajuda a resolver as dúvidas mais comuns ao configurar e usar automações de envio.
***
## 1. "A solicitação de coleta não foi feita automaticamente" [#1-a-solicitação-de-coleta-não-foi-feita-automaticamente]
Checklist rápido:
* **A automação está ativa?** Verifique a coluna Situação na tabela.
* **A integração está ativa?** Se aparecer badge de alerta (ação desativada/deletada), a integração da transportadora pode estar inativa ou deletada.
* **As condições foram atendidas?** Revise CEP, valor, tipo de entrega e demais condições da automação.
* **A automação está na sequência correta?** Outra automação pode estar sendo aplicada antes (a primeira que bater é a que vale).
* **O horário de acionamento está correto?** Se configurou "Durante horário de operação" ou "Dias customizados", confira se o pedido foi criado no momento esperado.
* **A automação está dentro da validade?** Verifique Data de Ativação e Validade.
***
## 2. "Aparece 'Ação desativada' ou 'Ação deletada' na tabela" [#2-aparece-ação-desativada-ou-ação-deletada-na-tabela]
Isso significa que a automação está ativa, mas a **integração da transportadora** configurada na automação está desativada ou foi removida.
**O que fazer:**
1. Acesse **Configurações > Integrações de transportador**.
2. Localize a integração usada na automação.
3. Reative a integração ou remova-a e cadastre novamente.
4. Se a integração foi deletada, edite a automação e escolha outra transportadora e prazo.
***
## 3. "Não encontro minha automação na lista" [#3-não-encontro-minha-automação-na-lista]
* Confirme que selecionou a **filial correta** no seletor.
* Use o campo de **busca por nome**.
* Remova filtros avançados temporariamente (Situação, Data de Ativação, Validade).
* Verifique se a automação não foi excluída (exclusões são permanentes).
***
## 4. "A automação está aplicando a transportadora errada" [#4-a-automação-está-aplicando-a-transportadora-errada]
A ordem das automações define a prioridade. O sistema avalia da **primeira** para a **última** e aplica a primeira cujas condições forem atendidas.
**O que fazer:**
1. Clique em **Editar Sequência**.
2. Mova a automação desejada para **acima** da que está sendo aplicada incorretamente.
3. Automações mais específicas devem ficar no topo; a automação padrão ("Todos os pedidos") deve ficar por último.
***
## 5. "O pedido ficou pendente e a solicitação de coleta não foi feita" [#5-o-pedido-ficou-pendente-e-a-solicitação-de-coleta-não-foi-feita]
Possíveis causas:
* **Nenhuma automação atendeu as condições** — O pedido pode ter CEP, valor ou outros atributos que não batem com nenhuma automação. Crie uma automação padrão "Todos os pedidos" no final da sequência.
* **Horário de acionamento** — Se a automação só roda "Durante horário de operação" ou em "Dias customizados", o pedido pode ter sido criado fora desse período. A solicitação de coleta será agendada para o próximo momento válido.
* **Agendamento** — Se configurou "Próximo horário de operação" ou "Agendamento customizado", o pedido pode estar aguardando o horário programado. Verifique na [Tela de Pedidos](/docs/log/products/pedidos/) o status e a data prevista.
***
## 6. "Quero que pedidos de um CEP específico usem outra transportadora" [#6-quero-que-pedidos-de-um-cep-específico-usem-outra-transportadora]
1. Crie uma **nova automação** com condição CEP (ou faixa de CEP, se disponível).
2. Configure a transportadora desejada.
3. Use **Editar Sequência** e coloque essa automação **acima** das automações mais genéricas.
4. Salve.
***
## 7. "A opção 'Agendar para janela de entrega' não aparece" [#7-a-opção-agendar-para-janela-de-entrega-não-aparece]
Essa opção depende de configuração na sua conta. Se não estiver disponível, use as outras opções de agendamento (próximo horário, customizado, etc.) ou entre em contato com o suporte para verificar a disponibilidade.
***
## 8. "Não tenho acesso à tela de Automações de Envio" [#8-não-tenho-acesso-à-tela-de-automações-de-envio]
O acesso à tela depende da configuração da sua conta. Entre em contato com o administrador da conta ou com o suporte da Abbiamo para verificar se o módulo de automações de envio está habilitado para sua filial ou conta.
---
# Automações de Inatividade — Como Usar (/docs/log/products/regras-de-inatividade/como-usar)
***
## Criar uma automação de inatividade [#criar-uma-automação-de-inatividade]
1. Acesse **Configurações > Automações por inatividade**.
2. Clique em **Criar automação**.
3. Preencha o formulário:
* **Nome** — Identifique a regra (ex.: "Cancelar após 48h sem atualização").
* **Filial** — Selecione a filial à qual a regra se aplica.
* **Tempo de inatividade** — Quantidade de horas sem atualização de status para acionar a regra.
* **Condições** — Filtros adicionais (ex.: transportadora, modalidade, status atual).
* **Ação** — O que fazer: cancelar, reenviar com outra transportadora, notificar, etc.
4. Clique em **Salvar**.
***
## Editar uma automação [#editar-uma-automação]
1. Na tabela, localize a automação desejada.
2. Clique no menu **⋮** e selecione **Editar automação**.
3. Altere os campos necessários e clique em **Salvar**.
***
## Ativar ou desativar [#ativar-ou-desativar]
1. No menu **⋮**, selecione **Ativar automação** ou **Desativar automação**.
2. Automações desativadas ficam suspensas sem ser excluídas.
***
## Excluir uma automação [#excluir-uma-automação]
1. No menu **⋮**, selecione **Excluir automação**.
2. Confirme a exclusão.
***
## Dicas de uso [#dicas-de-uso]
* **Calibre o tempo de inatividade** de acordo com o SLA da transportadora — evite acionar muito cedo para modais com rastreamento esparso (ex.: Correios).
* **Combine com Automações de Reenvio**: inatividade pode acionar um cancelamento, e a automação de reenvio cuida do redespacho.
* Use as [Notificações](/docs/log/settings/notificacoes/) para alertar a equipe quando um envio inativo for detectado, mesmo que a ação automática seja cancelamento.
---
# Automações de Inatividade — Visão Geral (/docs/log/products/regras-de-inatividade)
As **Automações de Inatividade** definem o que acontece quando um envio fica sem atualização de status por um período prolongado — por exemplo, cancelar e reenviar com outra transportadora, ou notificar a equipe.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/inactivity-rules](https://dashboard.abbiamolog.com/inactivity-rules)
* **Menu:** seção **Configurações** > **Automações por inatividade**
***
## Quando usar [#quando-usar]
Use automações de inatividade para monitorar envios "travados" — sem atualização de rastreamento por mais de X horas — e tomar ação automaticamente, como cancelar e redespachar, reduzindo a necessidade de monitoramento manual.
***
## Conceito [#conceito]
Você pode entender o conceito em [Automação de Inatividade](/docs/log/conceitos/regra-inatividade/).
---
# Automações de Reenvio — Como Usar (/docs/log/products/regras-de-reenvio/como-usar)
***
## Criar uma automação de reenvio [#criar-uma-automação-de-reenvio]
1. Acesse **Configurações > Automações de reenvio**.
2. Clique em **Criar automação**.
3. Preencha o formulário:
* **Nome** — Identifique a regra (ex.: "Reenvio por falha via Jadlog").
* **Filial** — Selecione a filial à qual a regra se aplica.
* **Condições** — Defina quando a automação deve ser acionada (ex.: status = FALHA, transportadora = X).
* **Ação** — Escolha a transportadora e modalidade para o reenvio.
4. Clique em **Salvar**.
***
## Editar uma automação [#editar-uma-automação]
1. Na tabela, localize a automação desejada.
2. Clique no menu **⋮** e selecione **Editar automação**.
3. Faça as alterações e clique em **Salvar**.
***
## Ativar ou desativar [#ativar-ou-desativar]
1. No menu **⋮** da automação, selecione **Ativar automação** ou **Desativar automação**.
2. Automações desativadas não são executadas — use para pausar sem excluir.
***
## Excluir uma automação [#excluir-uma-automação]
1. No menu **⋮**, selecione **Excluir automação**.
2. Confirme a exclusão na caixa de diálogo.
***
## Dicas de uso [#dicas-de-uso]
* **Ordene as regras** com cuidado: a primeira regra que satisfizer as condições do envio será acionada.
* **Teste em filial piloto** antes de aplicar a uma filial com alto volume.
* Combine com [Automações de Inatividade](/docs/log/products/regras-de-inatividade/) para cobrir cenários de envios parados e envios com falha explícita.
---
# Automações de Reenvio — Visão Geral (/docs/log/products/regras-de-reenvio)
As **Automações de Reenvio** definem o que acontece quando um envio falha — por exemplo, quando o entregador não conseguiu realizar a entrega. A plataforma pode, automaticamente, criar um novo envio com outra transportadora ou modalidade.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/resend-rules](https://dashboard.abbiamolog.com/resend-rules)
* **Menu:** seção **Configurações** > **Automações de reenvio**
***
## Quando usar [#quando-usar]
Use automações de reenvio para garantir que pedidos com falha de entrega sejam automaticamente redespachados — sem necessidade de intervenção manual — para outra transportadora ou modalidade previamente configurada.
***
## Conceito [#conceito]
Você pode entender o conceito em [Automação de Reenvio](/docs/log/conceitos/regra-reenvio/).
---
# Relatórios — Como Usar (/docs/log/products/relatorios/como-usar)
Guia prático de todas as ações disponíveis na página de Relatórios.
***
## Fluxo típico [#fluxo-típico]
1. Acessar **Relatórios** pelo menu lateral (`/reports`).
2. *(Opcional)* Consultar o **Dicionário** para entender o significado das colunas.
3. Clicar em **Novo relatório** → preencher tipo, formato, período, filiais e filtros → **Gerar relatório**.
4. Aguardar (a lista atualiza sozinha enquanto o status for "Na fila" ou "Processando").
5. Quando o status mudar para **Completo**, abrir o menu ⋮ → **Baixar relatório**.
6. Se precisar do mesmo relatório: ⋮ → **Gerar relatório novamente** (ajustar se necessário).
7. Para remover: ⋮ → **Excluir relatório** → confirmar no modal.
***
## Criar um novo relatório [#criar-um-novo-relatório]
Clique em **Novo relatório** no cabeçalho da página. O modal que abre tem os seguintes campos:
### Campos do formulário [#campos-do-formulário]
| Campo | Descrição |
| --------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Tipo do relatório** | Pedidos, Eventos, Envios, Integrações de Pedidos, Integrações de Transportadoras, Filiais ou CSAT |
| **Formato** | CSV ou JSON |
| **Período** | Data absoluta ou período dinâmico — máximo de **31 dias** (disponível para Pedidos, Eventos, Envios e CSAT) |
| **Filiais** | Seletor de filiais — mínimo 1 obrigatória |
| **Status** | *(Pedidos, Eventos, Envios e CSAT)* Filtra pelos status dos pedidos — por padrão, todos os status |
| **Transportadoras** | *(Pedidos)* Filtra por quem entrega (transportadoras) — por padrão, todas |
Após preencher, clique em **Gerar relatório**. Um toast confirma o envio e a lista é atualizada automaticamente.
***
## Exportar a partir da tela de Pedidos [#exportar-a-partir-da-tela-de-pedidos]
Você não precisa começar pela página de Relatórios: na tela de **Pedidos**, o botão **Exportar** (no topo da lista) abre um menu com duas opções.
### Exportar tela atual [#exportar-tela-atual]
Baixa **na hora** um arquivo CSV com os pedidos que estão na tela atual. Ao escolher essa opção, abre um diálogo que mostra:
* **Quantos pedidos serão exportados** (os que estão carregados na tela);
* Um **resumo dos filtros aplicados** (período, filiais, status e transportadoras) — somente leitura;
* O **idioma dos cabeçalhos** (Português ou Inglês).
As colunas do arquivo saem com os **mesmos nomes usados no relatório completo**, então os dois caminhos ficam consistentes.
### Gerar relatório completo [#gerar-relatório-completo]
Leva você para a página de **Relatórios** com o formulário de novo relatório **já aberto**, tipo **Pedidos** selecionado e os filtros da tela de Pedidos **pré-preenchidos** (período, filiais, status e transportadoras). Confira e clique em **Gerar relatório**.
***
## Consultar o dicionário de colunas [#consultar-o-dicionário-de-colunas]
No cabeçalho, clique no ícone de **Dicionário** (ℹ). Escolha o idioma (**Português** ou **Inglês**) e o modal exibirá a descrição de todas as colunas de cada tipo de relatório.
Isso é útil para entender exatamente o que cada campo significa no arquivo exportado. A mesma referência, com todas as colunas reunidas, está em [Dicionário de Colunas](/docs/log/products/relatorios/dicionario-de-colunas/).
***
## Filtrar e buscar relatórios [#filtrar-e-buscar-relatórios]
### Busca rápida [#busca-rápida]
Use o campo de busca (placeholder "Nome do relatório") para filtrar a lista pelo nome.
### Filtros avançados [#filtros-avançados]
Clique no botão de filtros para abrir o painel e selecione:
* **Nome** — texto livre
* **Tipo do relatório** — Pedidos, Eventos, Envios, etc.
* **Formato** — CSV, JSON
* **Status** — Na fila, Processando, Completo, Falha, Expirado
### Controle de colunas [#controle-de-colunas]
Ao lado dos filtros, há o botão de **visibilidade de colunas**: permite mostrar ou ocultar colunas da tabela conforme sua necessidade.
***
## Ações na linha do relatório (menu ⋮) [#ações-na-linha-do-relatório-menu-]
Cada relatório na tabela possui um menu de ações à direita:
### Baixar relatório [#baixar-relatório]
| Situação | Comportamento |
| ------------------------------------- | ------------------------------------------------------- |
| Status **Na fila** ou **Processando** | Ícone de loading — aguarde a conclusão |
| Status **Completo** | Solicita a URL de download e abre o arquivo em nova aba |
| Status **Falha** ou **Expirado** | O download não estará disponível — gere novamente |
Um toast de carregamento/sucesso/erro aparece durante o processo.
### Gerar relatório novamente [#gerar-relatório-novamente]
Abre o mesmo modal de criação, já preenchido com o tipo, formato, filiais, período e os filtros (status e transportadoras) daquele relatório. Você pode ajustar os campos e clicar em **Gerar relatório** para criar um novo.
### Excluir relatório [#excluir-relatório]
Abre o modal de confirmação:
> *"Tem certeza que deseja excluir o relatório "Nome do relatório"?"*
* **Excluir**: remove o relatório da lista (soft delete) e atualiza a tabela.
* **Cancelar**: fecha o modal sem ação.
---
# Relatórios — Dicionário de Colunas (/docs/log/products/relatorios/dicionario-de-colunas)
Esta é a referência completa das colunas de cada tipo de relatório exportável. É o mesmo conteúdo do botão **Dicionário** no cabeçalho da página de Relatórios — reunido aqui para consulta rápida.
***
## Colunas por tipo de relatório [#colunas-por-tipo-de-relatório]
### Pedidos (ORDERS) [#pedidos-orders]
| Coluna | Descrição |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Identificador único do pedido na base da Abbiamo |
| `numero_do_pedido` | Número do pedido |
| `id_externo_do_pedido` | Identificador externo do pedido (identificador do embarcador) |
| `codigo_de_rastreio` | Código de rastreio do pedido |
| `valor_do_pedido` | Valor total do pedido |
| `moeda` | Moeda referente ao valor do pedido |
| `data_de_entrega` | Data e hora de entrega prometida para o cliente |
| `valor_pago_pelo_envio` | Valor pago pelo cliente para o envio |
| `marcadores_de_pedido` | Nomes dos marcadores associados ao pedido |
| `tipo_de_pedido` | Tipo do pedido (DELIVERY, TAKEOUT, RETURN) |
| `status` | Status atual do pedido |
| `substatus` | Substatus atual do pedido |
| `data_de_atualizacao` | Data e hora da última atualização de um status ou substatus do pedido |
| `transportadora` | Nome da última transportadora responsável, se aplicável |
| `modalidade` | Nome da última modalidade de entrega (ex: CARRO, MOTO, CONVENCIONAL) |
| `ultimo_metodo_de_envio` | Tipo do último método de envio (ex: EXPRESS, STANDARD, SAME\_DAY) |
| `nome_do_motorista` | Nome do motorista responsável pelo último envio |
| `documento_do_motorista` | Número do documento do motorista responsável pelo último envio |
| `nome_da_rota` | Nome da rota do envio, se aplicável |
| `valor_da_rota` | Custo da rota do envio |
| `data_de_criacao_do_pedido` | Data e hora de criação do pedido |
| `data_prevista_de_entrega` | Data e hora prevista para finalização do envio |
| `data_de_finalizacao_da_entrega` | Data e hora em que o envio foi finalizado (caso tenha ocorrido) |
| `data_de_emissao_da_nf` | Data e hora de emissão da nota fiscal |
| `numero_da_nf` | Número da nota fiscal |
| `chave_de_acesso_da_nf` | Chave de acesso da nota fiscal |
| `distancia_estimada_caminho_dirigido` | Distância estimada do pedido considerando caminho dirigido |
| `distancia_estimada_linha_reta` | Distância estimada do pedido considerando caminho em linha reta |
| `distancia_total_da_rota` | Distância total do trajeto completo da rota (CD → todas as paradas → CD), a mesma exibida na tela de Rotas. Pode não estar preenchida para rotas antigas ou criadas fora da roteirização automática |
| `fim_da_janela_de_entrega` | Fim da janela de entrega do pedido |
| `inicio_da_janela_de_entrega` | Início da janela de entrega do pedido |
| `data_de_processamento_do_embarcador` | Data e hora em que o pedido foi processado no embarcador |
| `nome_do_destinatario` | Nome completo do destinatário |
| `telefone_do_destinatario` | Telefone de contato do destinatário |
| `email_do_destinatario` | Email do destinatário |
| `documento_do_destinatario` | Número do documento do destinatário (CPF/CNPJ) |
| `tipo_de_documento` | Tipo de documento do destinatário (CPF ou CNPJ) |
| `endereco_de_entrega` | Rua do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `numero` | Número do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `bairro` | Bairro do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `cep` | CEP do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `cidade` | Cidade do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `estado` | Estado do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `complemento` | Complemento do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `ponto_de_referencia` | Ponto de referência do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `pais` | País do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `latitude` | Latitude do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `longitude` | Longitude do endereço de entrega (tipo DELIVERY) ou coleta (tipo RETURN) |
| `nome_da_filial` | Nome da filial |
| `id_da_filial` | Identificador único da filial na base da Abbiamo |
| `seller_identifier` | Identificador da filial |
| `nome_de_quem_recebeu` | Nome da pessoa que recebeu o envio |
| `documento_de_quem_recebeu` | Documento da pessoa que recebeu o envio |
| `descricao_sobre_quem_recebeu` | Descrição fornecida sobre quem recebeu o envio |
| `nota_da_experiencia_de_entrega` | Nota atribuída na pesquisa de avaliação para a experiência de entrega |
| `comentario_do_cliente` | Comentário deixado pelo destinatário na pesquisa de avaliação (feedback) |
| `origem_de_criacao` | Origem da criação do pedido |
| `codigo_de_falha` | Código de falha da última tentativa de entrega com falha, se houver |
| `mensagem_de_falha` | Mensagem de falha da última tentativa de entrega com falha, se houver |
| `mensagem_de_falha_do_motorista` | Mensagem de falha específica para o motorista da última tentativa de entrega com falha, se houver |
| `tem_disputa` | Indica se o pedido tem disputa no Care (Sim/Não) |
| `numero_da_disputa` | Número público da disputa do pedido no Care |
| `status_da_disputa` | Status da disputa do pedido (Em aberto / Resolvida) |
| `desfecho_da_disputa` | Desfecho da disputa quando resolvida (entregue, retornada, perdida, etc.) |
| `compensacao_da_disputa` | Compensação dada ao cliente na disputa (reembolso, voucher, reenvio, etc.) |
*65 colunas.*
### Eventos (EVENTS) [#eventos-events]
| Coluna | Descrição |
| ----------------------------------------- | -------------------------------------------------------------------------- |
| `id_do_evento` | Identificador único do evento na base da Abbiamo |
| `status_do_evento` | Status do evento |
| `substatus_do_evento` | Substatus do evento |
| `observacoes_do_evento` | Observações adicionais sobre o evento |
| `id_do_envio` | Identificador único do envio na base da Abbiamo |
| `id_externo_do_envio` | Identificador externo do envio na base do transportador |
| `id_de_suporte_do_envio` | Identificador de suporte relacionado ao envio na base do transportador |
| `tipo_de_envio` | Tipo do envio |
| `status_do_envio` | Status atual do envio |
| `substatus_do_envio` | Substatus atual do envio |
| `envio_criado_manualmente` | Indica se o envio foi criado manualmente (TRUE) ou sistemicamente (FALSE) |
| `data_de_criacao_do_envio` | Data e hora de criação do envio |
| `id_do_pedido` | Identificador único do pedido na base da Abbiamo |
| `id_externo_do_pedido` | Identificador externo do pedido (identificador do embarcador) |
| `status_do_pedido` | Status atual do pedido |
| `substatus_do_pedido` | Substatus atual do pedido |
| `data_de_atualizacao_do_status_do_pedido` | Data e hora da última atualização de um status ou substatus do pedido |
| `marcadores_de_pedido` | Nomes dos marcadores associados ao pedido |
| `nome_da_filial` | Nome da filial |
| `id_da_filial` | Identificador único da filial na base da Abbiamo |
| `seller_identifier` | Identificador da filial |
| `nome_da_transportadora` | Nome da transportadora responsável pelo envio |
| `modalidade_de_entrega` | Nome da modalidade de entrega (ex: CARRO, MOTO, CONVENCIONAL) |
| `metodo_de_envio` | Tipo do método de envio (ex: EXPRESS, STANDARD, SAME\_DAY) |
| `data_de_criacao_do_evento` | Data e hora de criação do evento |
| `data_em_que_o_evento_ocorreu` | Data e hora em que o evento ocorreu |
| `latitude` | Latitude em que o evento foi apontado |
| `longitude` | Longitude em que o evento foi apontado |
| `evento_criado_manualmente` | Indica se o evento foi criado manualmente (TRUE) ou sistemicamente (FALSE) |
| `nome_do_motorista` | Nome do motorista responsável pelo envio |
| `documento_do_motorista` | Número do documento do motorista responsável pelo envio |
| `tipo_de_veiculo` | Tipo do veículo do motorista responsável pelo envio |
| `cor_do_veiculo` | Cor do veículo do motorista responsável pelo envio |
| `placa_do_veiculo` | Placa do veículo do motorista responsável pelo envio |
| `url_da_imagem_do_motorista` | URL da imagem do motorista responsável pelo envio |
| `codigo_de_falha` | Código de falha, se houver |
| `mensagem_de_falha` | Mensagem de falha, se houver |
| `mensagem_de_falha_do_motorista` | Mensagem de falha específica para o motorista, se houver |
| `data_prevista_de_finalizacao_do_envio` | Data e hora prevista para finalização do envio |
*39 colunas.*
### Envios (DELIVERIES) [#envios-deliveries]
| Coluna | Descrição |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id_do_envio` | Identificador único do envio na base da Abbiamo |
| `id_externo_do_envio` | Identificador externo do envio na base do transportador |
| `id_de_suporte_do_envio` | Identificador de suporte relacionado ao envio na base do transportador |
| `tipo_de_envio` | Tipo do envio (DELIVERY, TAKEOUT, RETURN) |
| `status_do_envio` | Status atual do envio |
| `substatus_do_envio` | Substatus atual do envio |
| `envio_criado_manualmente` | Indica se o envio foi criado manualmente (TRUE) ou sistemicamente (FALSE) |
| `data_de_criacao_do_envio` | Data e hora de criação do envio |
| `id_do_usuario_que_solicitou_o_envio` | Identificador do usuário que solicitou o envio |
| `email_do_usuario_que_solicitou_o_envio` | Email do usuário que solicitou o envio |
| `id_do_usuario_que_solicitou_o_cancelamento_do_envio` | Identificador do usuário que solicitou o cancelamento do envio |
| `email_do_usuario_que_solicitou_o_cancelamento_do_envio` | Email do usuário que solicitou o cancelamento do envio |
| `id_do_pedido` | Identificador único do pedido na base da Abbiamo |
| `numero_do_pedido` | Número do pedido |
| `id_externo_do_pedido` | Identificador externo do pedido (identificador do embarcador) |
| `status_do_pedido` | Status atual do pedido |
| `substatus_do_pedido` | Substatus atual do pedido |
| `data_de_atualizacao_do_status_do_pedido` | Data e hora da última atualização do status ou substatus do pedido |
| `distancia_estimada_caminho_dirigido` | Distância estimada do pedido considerando caminho dirigido |
| `distancia_estimada_linha_reta` | Distância estimada do pedido considerando linha reta |
| `distancia_total_da_rota` | Distância total do trajeto completo da rota (CD → todas as paradas → CD), a mesma exibida na tela de Rotas. Pode não estar preenchida para rotas antigas ou criadas fora da roteirização automática |
| `valor_pago_pelo_cliente_pelo_envio` | Valor pago pelo cliente pelo envio |
| `marcadores_de_pedido` | Nomes dos marcadores associados ao pedido |
| `nome_da_filial` | Nome da filial |
| `id_da_filial` | Identificador único da filial na base da Abbiamo |
| `seller_identifier` | Identificador da filial |
| `nome_da_transportadora` | Nome da transportadora responsável pelo envio |
| `modalidade_de_entrega` | Nome da modalidade de entrega (ex: CARRO, MOTO, CONVENCIONAL) |
| `tipo_de_metodo_de_envio` | Tipo do método de envio (ex: EXPRESS, STANDARD, SAME\_DAY) |
| `data_prevista_de_finalizacao_do_envio` | Data e hora prevista para finalização do envio |
| `data_de_entrega_do_envio` | Data e hora em que o envio foi finalizado |
| `valor_previsto_para_o_envio` | Valor previsto para o envio |
| `moeda_referente_ao_valor_previsto` | Moeda referente ao valor previsto para o envio |
| `valor_previo_do_envio` | Valor prévio do envio informado pela transportadora |
| `moeda_referente_ao_valor_previo_do_envio` | Moeda referente ao valor prévio informado pela transportadora |
| `valor_final_do_envio` | Valor final do envio informado pela transportadora |
| `moeda_referente_ao_valor_final_do_envio` | Moeda referente ao valor final do envio |
| `valor_auditado_do_envio` | Valor auditado do envio |
| `moeda_referente_ao_valor_auditado` | Moeda referente ao valor auditado do envio |
| `nome_do_motorista_responsavel` | Nome do motorista responsável pelo envio |
| `documento_do_motorista` | Documento do motorista responsável pelo envio |
| `telefone_do_motorista` | Telefone do motorista responsável pelo envio |
| `tipo_de_veiculo_do_motorista` | Tipo de veículo do motorista responsável pelo envio |
| `cor_do_veiculo` | Cor do veículo do motorista responsável pelo envio |
| `placa_do_veiculo` | Placa do veículo do motorista responsável pelo envio |
| `url_da_imagem_do_motorista` | URL da imagem do motorista responsável pelo envio |
| `codigo_de_verificacao_para_coleta` | Código de verificação para coleta |
| `codigo_de_verificacao_para_entrega` | Código de verificação para entrega |
| `codigo_de_verificacao_para_retorno` | Código de verificação para retorno |
| `tempo_estimado_para_coleta` | Tempo estimado para coleta |
| `tempo_estimado_para_entrega` | Tempo estimado para entrega |
| `tempo_estimado_para_retorno` | Tempo estimado para retorno |
| `data_de_atualizacao_do_tempo_estimado_de_entrega` | Data e hora da última atualização do tempo estimado de entrega |
| `nome_da_pessoa_que_recebeu_o_envio` | Nome da pessoa que recebeu o envio |
| `documento_da_pessoa_que_recebeu_o_envio` | Documento da pessoa que recebeu o envio |
| `descricao_sobre_quem_recebeu_o_envio` | Descrição sobre quem recebeu o envio |
*56 colunas.*
### Integrações de Pedidos (ORDER\_INTEGRATIONS) [#integrações-de-pedidos-order_integrations]
| Coluna | Descrição |
| ------------------------------------------- | --------------------------------------------------------------- |
| `id_da_integracao_de_pedidos` | Identificador único da integração de pedidos na base da Abbiamo |
| `nome_do_provedor_da_integracao_de_pedidos` | Nome do provedor da integração de pedidos |
| `integracao_ativa` | Indica se a integração está ativa |
| `metadados_da_integracao` | Metadados da integração (ex: API Key, Token, etc.) |
| `data_de_criacao_da_integracao` | Data e hora de criação da integração |
| `data_de_atualizacao_da_integracao` | Data e hora da última atualização da integração |
| `nome_da_filial` | Nome da filial |
| `id_da_filial` | Identificador único da filial na base da Abbiamo |
| `seller_identifier` | Identificador da filial |
*9 colunas.*
### Integrações de Transportadoras (CARRIER\_INTEGRATIONS) [#integrações-de-transportadoras-carrier_integrations]
| Coluna | Descrição |
| --------------------------------------- | ------------------------------------------------------------------------- |
| `id_da_integracao_com_a_transportadora` | Identificador único da integração com a transportadora na base da Abbiamo |
| `nome_da_transportadora` | Nome da transportadora |
| `nome_da_transportadora_virtual` | Nome da transportadora virtual |
| `modalidade_de_envio` | Nome da modalidade de envio (ex: CARRO, MOTO, CONVENCIONAL) |
| `tipo_de_operação` | Tipo da integração (DELIVERY, RETURN) |
| `integracao_ativa` | Indica se a integração está ativa |
| `metadados_da_integracao` | Metadados da integração (ex: API Key, Token, etc.) |
| `horario_maximo_de_despacho` | Horário máximo para despacho para ser considerado como SAME\_DAY |
| `gris` | GRIS (Gerenciamento de Risco) |
| `ad_valorem` | Ad Valorem |
| `fator_de_cubagem` | Fator de cubagem |
| `isencao_de_cubagem` | Isenção de cubagem |
| `data_de_criacao_da_integracao` | Data e hora de criação da integração |
| `data_de_atualizacao_da_integracao` | Data e hora da última atualização da integração |
| `nome_da_filial` | Nome da filial |
| `id_da_filial` | Identificador único da filial na base da Abbiamo |
| `seller_identifier` | Identificador da filial |
| `tabela_de_frete` | Nome da tabela de frete vinculada à integração |
| `tipo_tabela_de_frete` | Tipo da tabela de frete (Raio ou CEP) |
| `restringir_abrangencia_ativa` | Indica se a restrição de abrangência está ativa |
| `telefone_da_integracao` | Telefone de contato configurado na integração |
*21 colunas.*
### Filiais (SELLERS) [#filiais-sellers]
| Coluna | Descrição |
| --------------------------------------------- | -------------------------------------------------------------- |
| `id_da_filial` | Identificador único da filial na base da Abbiamo |
| `nome_da_filial` | Nome da filial |
| `seller_identifier` | Identificador da filial |
| `tipo_de_documento_da_filial` | Tipo do documento da filial |
| `numero_do_documento_da_filial` | Número do documento da filial |
| `identificador_da_filial` | Identificador da filial |
| `inscricao_estadual_da_filial` | Inscrição estadual da filial |
| `email_da_filial` | Email da filial |
| `telefone_da_filial` | Telefone da filial |
| `pais_da_filial` | País da filial |
| `fuso_horario_da_filial` | Fuso horário da filial |
| `possui_horario_de_funcionamento_configurado` | Indica se a filial possui horário de funcionamento configurado |
| `horario_de_abertura_no_domingo` | Horário de abertura no domingo |
| `horario_de_fechamento_no_domingo` | Horário de fechamento no domingo |
| `horario_de_abertura_na_segunda_feira` | Horário de abertura na segunda-feira |
| `horario_de_fechamento_na_segunda_feira` | Horário de fechamento na segunda-feira |
| `horario_de_abertura_na_terca_feira` | Horário de abertura na terça-feira |
| `horario_de_fechamento_na_terca_feira` | Horário de fechamento na terça-feira |
| `horario_de_abertura_na_quarta_feira` | Horário de abertura na quarta-feira |
| `horario_de_fechamento_na_quarta_feira` | Horário de fechamento na quarta-feira |
| `horario_de_abertura_na_quinta_feira` | Horário de abertura na quinta-feira |
| `horario_de_fechamento_na_quinta_feira` | Horário de fechamento na quinta-feira |
| `horario_de_abertura_na_sexta_feira` | Horário de abertura na sexta-feira |
| `horario_de_fechamento_na_sexta_feira` | Horário de fechamento na sexta-feira |
| `horario_de_abertura_no_sabado` | Horário de abertura no sábado |
| `horario_de_fechamento_no_sabado` | Horário de fechamento no sábado |
| `filial_ativa` | Indica se a filial está ativa |
| `status_da_filial` | Status da filial (Ativa ou Inativa) |
| `data_de_criacao_da_filial` | Data e hora de criação da filial |
| `data_de_atualizacao_da_filial` | Data e hora da última atualização da filial |
| `rua_do_endereco_da_filial` | Rua do endereço da filial |
| `numero_do_endereco_da_filial` | Número do endereço da filial |
| `complemento_do_endereco_da_filial` | Complemento do endereço da filial |
| `ponto_de_referencia_do_endereco_da_filial` | Ponto de referência do endereço da filial |
| `bairro_do_endereco_da_filial` | Bairro do endereço da filial |
| `cep_do_endereco_da_filial` | CEP do endereço da filial |
| `cidade_do_endereco_da_filial` | Cidade do endereço da filial |
| `estado_do_endereco_da_filial` | Estado do endereço da filial |
| `latitude_do_endereco_da_filial` | Latitude do endereço da filial |
| `longitude_do_endereco_da_filial` | Longitude do endereço da filial |
| `pais_do_endereco_da_filial` | País do endereço da filial |
| `endereco_completo_da_filial` | Endereço completo da filial |
*42 colunas.*
### Pesquisa de Satisfação (CSAT) [#pesquisa-de-satisfação-csat]
| Coluna | Descrição |
| -------------------------- | --------------------------------------------------------------------- |
| `id` | Identificador único do pedido na base da Abbiamo |
| `numero_do_pedido` | Número do pedido |
| `id_externo_do_pedido` | Identificador externo do pedido (identificador do embarcador) |
| `codigo_de_rastreio` | Código de rastreio do pedido |
| `tipo_de_pedido` | Tipo do pedido (DELIVERY, TAKEOUT, RETURN) |
| `nota_de_avaliacao` | Nota atribuída na pesquisa de avaliação para a experiência de entrega |
| `comentario_de_avaliacao` | Comentário deixado na pesquisa de avaliação (feedback) |
| `numero_da_nf` | Número da nota fiscal |
| `chave_de_acesso_da_nf` | Chave de acesso da nota fiscal |
| `data_de_emissao_da_nf` | Data e hora de emissão da nota fiscal |
| `id_da_filial` | Identificador único da filial na base da Abbiamo |
| `nome_da_filial` | Nome da filial |
| `seller_identifier` | Identificador da filial |
| `data_de_resposta` | Data e hora em que a pesquisa CSAT foi respondida |
| `origem_da_resposta` | Fonte da qual a pesquisa CSAT foi respondida (ex: SMS, EMAIL, APP) |
| `nome_do_destinatario` | Nome completo do destinatário |
| `telefone_do_destinatario` | Telefone de contato do destinatário |
| `email_do_destinatario` | Email do destinatário |
| `transportadora` | Nome da transportadora responsável pelo envio |
| `modalidade` | Nome da modalidade de entrega (ex: CARRO, MOTO, CONVENCIONAL) |
| `ultimo_metodo_de_envio` | Tipo do último método de envio (ex: EXPRESS, STANDARD, SAME\_DAY) |
| `nome_do_motorista` | Nome do motorista responsável pelo último envio |
| `documento_do_motorista` | Número do documento do motorista responsável pelo último envio |
*23 colunas.*
### Automações de Envio (DISPATCH\_RULES) [#automações-de-envio-dispatch_rules]
| Coluna | Descrição |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `nome_da_filial` | Nome da filial |
| `cnpj` | CNPJ da filial |
| `seller_id` | Identificador único da filial na base da Abbiamo |
| `id_da_automacao_de_envio` | Identificador único da automação de envio |
| `nome_da_automacao` | Nome da automação de envio |
| `tipo_acao` | Tipo da ação da automação (Método Específico, Método Mais Barato, Método Mais Rápido) |
| `transportadora` | Nome da transportadora associada à automação |
| `metodo` | Tipo do método de envio (ex: EXP60) |
| `status_automacao` | Indica se a automação está ativa ou desativada |
| `criada_em` | Data e hora de criação da automação |
| `atualizada_em` | Data e hora da última atualização da automação |
| `tipo_de_operacao` | Tipo de operação da automação (Entrega ou Reversa) |
| `ordem_da_regra` | Ordem de prioridade da regra de automação |
| `status_filial` | Indica se a filial está ativa ou inativa |
| `condicao_de_horario` | Condição de horário configurada para a automação |
*15 colunas.*
### Automações de Reenvio (RESEND\_RULES) [#automações-de-reenvio-resend_rules]
| Coluna | Descrição |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| `nome_da_filial` | Nome da filial |
| `cnpj` | CNPJ da filial |
| `seller_id` | Identificador único da filial na base da Abbiamo |
| `id_da_automacao_de_reenvio` | Identificador único da automação de reenvio |
| `nome_da_automacao` | Nome da automação de reenvio |
| `tipo_acao` | Tipo da ação da automação (Método Específico, Método Mais Barato, Método Mais Rápido) |
| `transportadora` | Nome da transportadora associada à automação |
| `metodo` | Tipo do método de envio |
| `tipo_de_operacao` | Tipo de operação da automação (Entrega ou Reversa) |
| `status_automacao` | Indica se a automação está ativa ou desativada |
| `criada_em` | Data e hora de criação da automação |
| `atualizada_em` | Data e hora da última atualização da automação |
| `status_filial` | Indica se a filial está ativa ou inativa |
| `ordem_da_acao` | Ordem de prioridade da regra de automação |
*14 colunas.*
### Disputas (DISPUTES) [#disputas-disputes]
| Coluna | Descrição |
| ------------------------ | ------------------------------------------------------------------------- |
| `numero_da_disputa` | Número público da disputa no Care |
| `numero_do_pedido` | Número do pedido associado à disputa |
| `numero_da_nf` | Número da nota fiscal do pedido |
| `filial` | Filial (seller) dona do pedido |
| `transportadora` | Transportadora associada à disputa, se aplicável |
| `status_da_disputa` | Status da disputa (Em aberto / Resolvida) |
| `substatus_da_disputa` | Substatus quando em aberto (aguardando marca, transportadora, cliente...) |
| `tags` | Tags da disputa (motivo do incidente, etc.) |
| `status_transportadora` | Status da trilha com a transportadora (acionada, pagou, negou...) |
| `desfecho` | Desfecho da disputa quando resolvida (entregue, retornada, perdida...) |
| `compensacao` | Compensação dada ao cliente (reembolso, voucher, reenvio...) |
| `valor_da_compensacao` | Valor da compensação, quando houver |
| `moeda` | Moeda da compensação |
| `motivo_de_encerramento` | Motivo de encerramento da disputa, se aplicável |
| `responsavel` | Agente responsável pela disputa |
| `nome_do_cliente` | Nome do cliente da disputa |
| `email_do_cliente` | E-mail do cliente da disputa |
| `telefone_do_cliente` | Telefone do cliente da disputa |
| `data_de_abertura` | Data e hora de abertura da disputa |
| `data_de_resolucao` | Data e hora de resolução da disputa, se resolvida |
*20 colunas.*
---
# Relatórios — Visão Geral (/docs/log/products/relatorios)
A página de **Relatórios** permite extrair, filtrar e baixar dados da sua operação logística em diversos formatos. É o ponto central para análise de pedidos, envios, eventos, integrações, filiais e pesquisa de satisfação.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/reports](https://dashboard.abbiamolog.com/reports)
* **Menu:** Na barra lateral (sidebar) do painel, o item **"Relatórios"** aparece com ícone de documento.
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Menu lateral duplo** | Botão para abrir/fechar a sidebar |
| **Título** | "Relatórios" |
| **Dicionário** | Abre o dicionário de colunas (PT ou EN), explicando cada coluna dos relatórios — veja a referência completa em [Dicionário de Colunas](/docs/log/products/relatorios/dicionario-de-colunas/) |
| **Novo relatório** | Abre o modal de criação de novo relatório |
### Área de filtros e busca [#área-de-filtros-e-busca]
* **Campo de busca:** filtra pelo nome do relatório.
* **Botão atualizar:** recarrega a lista manualmente.
* **Filtros avançados:**
* Nome
* Tipo do relatório
* Formato (CSV, JSON)
* Status (Na fila, Processando, Completo, Falha, Expirado)
* **Controle de colunas:** permite mostrar/ocultar colunas da tabela.
### Tabela de relatórios [#tabela-de-relatórios]
| Coluna | O que mostra |
| ------------- | ----------------------------------------------------- |
| **Nome** | Nome dado ao relatório |
| **Tipo** | Badge indicando a categoria (Pedidos, Eventos, etc.) |
| **Formato** | Ícone de CSV ou JSON |
| **Status** | Badge com o estado atual do relatório |
| **Filiais** | Chips das filiais incluídas ou "Todos" |
| **Criado em** | Data e hora de criação |
| **Ações** | Menu (⋮) com opções: baixar, gerar novamente, excluir |
### Paginação [#paginação]
No rodapé da tabela: tamanhos de página (50, 100, 150, 200) e navegação entre páginas.
### Estado vazio [#estado-vazio]
Se não houver relatórios ou nenhum resultado dos filtros, aparece a mensagem:
> *"Nenhum relatório encontrado, ainda... Crie um novo agora mesmo!"*
***
## Tipos de relatório [#tipos-de-relatório]
| Tipo | Descrição |
| ---------------------------------- | --------------------------------------------------------------------------------------- |
| **Pedidos (ORDERS)** | Dados completos dos pedidos — com filtros de período, filiais, transportadoras e status |
| **Eventos (EVENTS)** | Registros de eventos logísticos |
| **Envios (DELIVERIES)** | Dados dos envios realizados |
| **Integrações de Pedidos** | Informações das integrações de pedidos com sistemas externos |
| **Integrações de Transportadoras** | Dados das integrações com transportadoras |
| **Filiais (SELLERS)** | Dados cadastrais das filiais |
| **Pesquisa de Satisfação (CSAT)** | Respostas da pesquisa de satisfação — com filtro de período |
***
## Status do relatório [#status-do-relatório]
| Status | Significado |
| ---------------------------- | ------------------------------------------------------- |
| **Na fila (QUEUED)** | Aguardando processamento |
| **Processando (PROCESSING)** | O arquivo está sendo gerado com os filtros aplicados |
| **Completo (DONE)** | Pronto para download |
| **Falha (FAILED)** | Houve um erro na geração |
| **Expirado (EXPIRED)** | Não está mais disponível — gere novamente se necessário |
***
## Formatos disponíveis [#formatos-disponíveis]
| Formato | Observação |
| -------- | -------------------------------------------------------- |
| **CSV** | Formato padrão, compatível com Excel, Google Sheets etc. |
| **JSON** | Ideal para integrações e consumo programático |
***
## Comportamentos automáticos [#comportamentos-automáticos]
* **Polling de status:** relatórios recentes com status pendente são atualizados a cada 5 segundos (até 2 horas).
* **Filtros persistentes:** as condições de filtro são salvas no navegador por grupo de filiais e por página (`reports`). Ao retornar, os filtros permanecem como estavam.
* **Reset de paginação:** ao alterar texto de busca ou condições de filtro, a tabela volta para a primeira página.
***
## Próximos passos [#próximos-passos]
* [**Como usar**](/docs/log/products/relatorios/como-usar/) — passo a passo para criar, baixar, filtrar e excluir relatórios.
* [**Dicionário de Colunas**](/docs/log/products/relatorios/dicionario-de-colunas/) — referência completa de todas as colunas de cada tipo de relatório.
* [**Troubleshooting**](/docs/log/products/relatorios/troubleshooting/) — resolver divergências de datas, timezone e problemas de status.
---
# Relatórios — Troubleshooting (/docs/log/products/relatorios/troubleshooting)
Este guia auxilia na resolução de dúvidas sobre os dados extraídos nos relatórios de **Pedidos**, **Eventos**, **Envios**, **Filiais**, **Integrações** e **CSAT**.
## 1. Comportamento global de datas (timezone) [#1-comportamento-global-de-datas-timezone]
Uma dúvida comum é a diferença de horários entre o painel web e o arquivo exportado. Esta funcionalidade é nativa da plataforma para garantir a precisão logística local.
### No painel (web) [#no-painel-web]
Os dados são exibidos no padrão **UTC**, identificado pelo `"Z"` no final da string (ex.: `2026-02-13T16:18:19.000Z`).
### No relatório (CSV/JSON) [#no-relatório-csvjson]
O sistema detecta o **fuso horário da sua máquina** (ex.: `America/Sao_Paulo` -03:00) e converte automaticamente todas as datas para este fuso no momento da exportação.
**Exemplo:** Um pedido criado às 16:00 no painel (UTC) aparecerá como **13:00** no seu relatório (horário de Brasília).
## 2. Colunas afetadas por tipo de relatório [#2-colunas-afetadas-por-tipo-de-relatório]
Abaixo estão os principais campos de data que sofrem essa conversão automática em cada categoria:
| Tipo de relatório | Colunas de data convertidas (exemplos) |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Pedidos (ORDERS)** | `data_de_entrega`, `data_de_atualizacao`, `data_de_criacao_do_pedido`, `data_de_emissao_da_nf`, `data_de_processamento_do_embarcador` |
| **Eventos (EVENTS)** | `data_de_criacao_do_evento`, `data_em_que_o_evento_ocorreu`, `data_prevista_de_finalizacao_do_envio` |
| **Envios (DELIVERIES)** | `delivery_created_at`, `delivered_delivery_date`, `delivery_expected_delivery_date`, `delivery_eta_updated_at` |
| **CSAT** | `answered_at` (data de resposta), `invoice_issued_at` (emissão de NF) |
| **Integrações** | `carrier_integration_created_at`, `order_integration_updated_at` |
## 3. Checklist de verificação [#3-checklist-de-verificação]
Se os horários não estiverem batendo conforme o esperado, siga estes passos:
### Verifique a mensagem de aviso [#verifique-a-mensagem-de-aviso]
Ao gerar um **Novo Relatório**, a plataforma exibe um alerta:
> *"Identificamos que você está no fuso horário \[Seu Fuso]. Todos os campos de data e hora serão exportados neste fuso."*
Confirme se o fuso detectado é o correto.
### Origem da extração [#origem-da-extração]
### Configuração da filial [#configuração-da-filial]
Alguns relatórios de **Filiais (SELLERS)** possuem campos específicos de `fuso_horario_da_filial` e `seller_timezone`. Certifique-se de que a configuração da filial no cadastro condiz com a região física dela.
## 4. Status do processamento [#4-status-do-processamento]
Caso o relatório não esteja disponível imediatamente, verifique a coluna **Status** na tela de relatórios:
| Status | Significado |
| ---------------------------- | -------------------------------------------------------------------------------- |
| **NA FILA (QUEUED)** | Aguardando processamento. |
| **PROCESSANDO (PROCESSING)** | O arquivo está sendo gerado com os filtros aplicados. |
| **COMPLETO (DONE)** | Pronto para download. |
| **EXPIRADO (EXPIRED)** | Relatórios antigos são removidos periodicamente; gere-o novamente se necessário. |
## 5. Formato XLSX não disponível [#5-formato-xlsx-não-disponível]
O formato **XLSX** não é suportado atualmente. Os formatos disponíveis para exportação são **CSV** e **JSON**.
Se você precisa de um arquivo `.xlsx`, exporte em **CSV** e abra no Excel ou Google Sheets — a conversão é automática ao abrir o arquivo.
---
# Tela de Rotas — Como Usar (/docs/log/products/rotas/como-usar)
Guia prático para criar e gerenciar rotas de entrega via transportadora no dia a dia do contexto **LOG**.
***
## Fluxo típico [#fluxo-típico]
1. Acesse **Operação > Rotas** (`/routes`).
2. Defina período, status e transportadora nos filtros principais para trazer a visão correta.
3. Use filtros avançados para localizar rotas por pedido ou status de entrega.
4. Clique em uma rota para abrir o painel lateral com detalhes, lista de entregas e mapa.
5. Use o menu ⋮ para executar ações individuais na rota.
6. Para criar uma nova rota, clique em **Nova rota** no cabeçalho.
***
## Filtrar e localizar rotas [#filtrar-e-localizar-rotas]
### Filtros principais [#filtros-principais]
* **Status** — filtre por CRIADA, EM EXECUÇÃO, CANCELADA, PEDIDOS CONCLUÍDOS ou FINALIZADA
* **Entregue por** — filtre pela transportadora responsável
* **Período** — janela de datas (padrão: últimos 7 dias)
* **Filtros avançados** — nome da rota, motorista (quando disponível), número do pedido e status de entrega
***
## Acompanhar uma rota [#acompanhar-uma-rota]
Clique em qualquer linha da tabela para abrir o painel lateral com:
* Lista de entregas e status individual de cada uma
* Transportadora responsável
* Visualização do trajeto no mapa
A URL é atualizada com `?route_id=` — você pode copiar o link para compartilhar diretamente a rota em questão.
***
## Ações por rota [#ações-por-rota]
### Solicitar coleta [#solicitar-coleta]
Encaminha a rota para uma transportadora integrada. Disponível quando a rota ainda não tem responsável atribuído e todos os pedidos pertencem a uma única filial.
### Duplicar rota [#duplicar-rota]
Cria uma nova rota com os mesmos pedidos e configurações. Disponível para a maioria dos status, exceto **EM EXECUÇÃO** e **PEDIDOS CONCLUÍDOS**.
### Cancelar rota [#cancelar-rota]
***
## Criar uma rota via transportadora [#criar-uma-rota-via-transportadora]
### Como acessar [#como-acessar]
Clique em **Nova rota** no canto superior direito da tela de Rotas. A URL muda para `/routes/create`.
### Layout da tela [#layout-da-tela]
A tela de criação é dividida em **dois painéis simultâneos**:
| Painel | O que contém |
| ------------ | -------------------------------------------------------------------- |
| **Esquerdo** | Modo de criação, campos de configuração e mapa com prévia do trajeto |
| **Direito** | Tabela de pedidos disponíveis para seleção, com filtros |
### Campos — aba Transportadora [#campos--aba-transportadora]
| Campo | Obrigatório | Descrição |
| ----------------------- | ----------- | ------------------------------------------------------------------------------------------- |
| **Filial** | Sim | Filial de origem dos pedidos. Define a transportadora e as opções de método disponíveis |
| **Método** | Sim | Modalidade ou serviço da transportadora (ex.: Expresso, Econômico) |
| **Retorno obrigatório** | Não | Toggle — quando ativado, exige que o veículo retorne ao depósito de origem após as entregas |
### Selecionar pedidos [#selecionar-pedidos]
No painel direito, use os filtros para localizar e selecionar os pedidos a incluir na rota:
* **Busca** por número do pedido, nome do cliente ou filial
* **Marcadores** — filtre por tags aplicadas aos pedidos
* **Filial** — filtre por filial de origem
* **Período** — ajuste o intervalo de datas
* **Filtros avançados** — opções adicionais de filtragem
### Sugerir rota e prévia [#sugerir-rota-e-prévia]
| Ação | O que faz |
| ------------------ | --------------------------------------------------------------------------------- |
| **Sugerir rota** | Calcula a sequência otimizada de entregas. Requer ao menos um pedido selecionado. |
| **Prévia de rota** | Exibe o trajeto no mapa à esquerda antes de confirmar a criação. |
### Confirmar criação [#confirmar-criação]
Após configurar a rota e selecionar os pedidos, clique em **Criar Rota** (botão no canto inferior direito). O sistema valida os dados e cria a rota. Você é redirecionado de volta para a tela de listagem.
***
### Validações e restrições [#validações-e-restrições]
### Erros durante a criação [#erros-durante-a-criação]
| Código | O que significa |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| `ORDERS_NOT_ROUTEABLE` | Um ou mais pedidos selecionados não estão em status roteável |
| `DIFFERENT_SELLER_IDS` | Pedidos de seller groups diferentes foram incluídos na seleção |
| `COULD_NOT_SUGGEST_ROUTE_WITH_MUST_HAVE_ORDERS` | O otimizador não conseguiu incluir todos os pedidos obrigatórios na sugestão |
| `COULD_NOT_SUGGEST_ROUTE_WITH_CURRENT_CONFIG` | A configuração atual não permite gerar uma sugestão de rota |
***
## Boas práticas operacionais [#boas-práticas-operacionais]
* Verifique o **status dos pedidos** antes de selecioná-los — apenas pedidos em status roteável podem ser incluídos.
* Confirme que a **filial selecionada** possui integração ativa com a transportadora desejada.
* Use **Sugerir rota** para otimizar automaticamente a sequência de entregas quando a transportadora permite.
* Use **Prévia de rota** para validar visualmente o trajeto antes de confirmar.
***
## Próximos passos [#próximos-passos]
* [**Troubleshooting**](/docs/log/products/rotas/troubleshooting/) — botão desabilitado, erros de criação e outros problemas comuns.
---
# Tela de Rotas — Visão Geral (/docs/log/products/rotas)
A tela de **Rotas** permite visualizar, acompanhar e criar rotas de entrega. No contexto **LOG**, ela é usada para criar e gerenciar **rotas via transportadora (TRP)** — quando um lote de pedidos é enviado a uma transportadora integrada para execução das entregas.
***
## Onde acessar [#onde-acessar]
* **URL principal:** [https://dashboard.abbiamolog.com/routes](https://dashboard.abbiamolog.com/routes)
* **Menu:** seção **Operação** > **Rotas**
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------- | ------------------------------------------------- |
| **Título** | "Rotas" |
| **Nova rota** | Abre a tela de Criação de Rota (`/routes/create`) |
### Barra de filtros [#barra-de-filtros]
* **Pesquisar** — busca por nome da rota ou número do pedido
* **Atualizar lista** — botão de refresh manual
* **Status** (multisseleção) — ver seção [Status de rota](#status-de-rota)
* **Entregue por** (multisseleção) — filtre pelas transportadoras integradas configuradas na conta
* **Período** (date range, padrão: últimos 7 dias, máximo 93 dias)
* **Filtros avançados** — ver seção dedicada abaixo
* **Visibilidade de colunas** — ícone de ajuste para mostrar/ocultar colunas
### Tabela de rotas [#tabela-de-rotas]
| Coluna | O que mostra |
| ------------------ | ----------------------------------------------------------------------------- |
| **ID** | Identificador único da rota (exibido com até 12 caracteres + botão de copiar) |
| **Nome da Rota** | Nome externo da rota, gerado automaticamente se não informado |
| **Status** | Badge colorido com o status atual da rota |
| **Entregas** | Contagem total + blocos visuais por status com os números dos pedidos |
| **Responsável** | Transportadora responsável pelas entregas |
| **Criado em** | Data e hora de criação (formato dd/MM/yy HH:mm) |
| **Custo** | Custo da rota em BRL (quando informado) |
| **Distância** | Distância esperada em km |
| **Tempo estimado** | Tempo esperado no formato HH:mm |
| **Ações** | Menu suspenso (⋮) com ações individuais por rota |
### Interações de linha [#interações-de-linha]
* **Clique simples:** abre o painel lateral da rota (adiciona `?route_id=` à URL)
### Estado vazio [#estado-vazio]
Quando não há rotas para os filtros aplicados:
> *"Nenhuma rota encontrada. Crie uma rota agora mesmo"*
***
## Filtros avançados disponíveis [#filtros-avançados-disponíveis]
| Campo | Tipo |
| -------------------------- | ------------- |
| **Nome da rota** | Texto |
| **Nome do motorista** | Texto |
| **Sobrenome do motorista** | Texto |
| **Documento do motorista** | Texto |
| **Pedido de entrega** | Texto |
| **Status da entrega** | Multisseleção |
***
## Ações por rota (menu ⋮) [#ações-por-rota-menu-]
| Ação | Disponibilidade |
| -------------------- | ----------------------------------------------------------- |
| **Ver rota** | Sempre disponível |
| **Solicitar coleta** | Rota sem responsável atribuído, pedidos de uma única filial |
| **Duplicar rota** | Indisponível para **EM EXECUÇÃO** e **PEDIDOS CONCLUÍDOS** |
| **Exportar CSV** | Disponível para contas habilitadas |
| **Cancelar rota** | Ação destrutiva e irreversível |
***
## Status de rota [#status-de-rota]
| Status | Descrição |
| ---------------------- | ------------------------------------------------------------- |
| **CRIADA** | Rota criada e aguardando aceite ou início pela transportadora |
| **EM EXECUÇÃO** | A transportadora iniciou as entregas |
| **CANCELADA** | Rota cancelada — pedidos retornam ao estado pendente |
| **PEDIDOS CONCLUÍDOS** | Todos os waypoints da rota foram finalizados |
| **FINALIZADA** | Rota encerrada pelo sistema |
***
## Painel lateral da rota [#painel-lateral-da-rota]
Ao clicar em uma rota (ou usar "Ver rota" no menu ⋮), um painel lateral exibe:
* Lista de entregas com status individual
* Transportadora responsável
* Visualização do trajeto no mapa
A URL é atualizada com `?route_id=`, permitindo compartilhar ou favoritar o estado diretamente.
***
## Comportamentos automáticos importantes [#comportamentos-automáticos-importantes]
* **Reset de paginação:** alterações de filtro voltam para a primeira página
* **Side panel por URL:** `?route_id=` na query string abre automaticamente o painel lateral da rota correspondente
* **Exportação CSV:** respeita os filtros ativos no momento da exportação (disponível para contas habilitadas)
***
## Próximos passos [#próximos-passos]
* [**Como usar**](/docs/log/products/rotas/como-usar/) — passo a passo para criar rotas via transportadora, filtrar e acompanhar o status das entregas.
---
# Tela de Rotas — Troubleshooting (/docs/log/products/rotas/troubleshooting)
Problemas mais comuns na criação e gestão de rotas via transportadora e como resolvê-los.
***
## Botão "Criar Rota" está desabilitado [#botão-criar-rota-está-desabilitado]
O botão fica bloqueado enquanto algum campo obrigatório não estiver preenchido. A tela indica a razão diretamente.
| Mensagem exibida | Causa | O que fazer |
| ---------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
| *Nenhum pedido foi selecionado* | Nenhum pedido marcado no painel direito | Selecione ao menos 1 pedido na tabela |
| *Nenhuma filial foi selecionada* | Campo **Filial** vazio | Selecione a filial de origem dos pedidos |
| *Nenhum método foi selecionado* | Campo **Método** vazio | Escolha a modalidade/serviço da transportadora |
| *Carregando informações da filial...* | Dados do armazém ainda sendo carregados | Aguarde alguns segundos e tente novamente |
| *Nenhum warehouse encontrado para esta filial* | A filial não tem armazém cadastrado | Verifique se a filial possui um armazém configurado em **Configurações > Filiais** |
***
## Erros ao clicar em "Criar Rota" [#erros-ao-clicar-em-criar-rota]
### Pedidos com problema [#pedidos-com-problema]
| Erro exibido | Causa | O que fazer |
| -------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| *Nenhum desses pedidos é roteirizável: \[números]* | Um ou mais pedidos estão em status que não permite roteamento | Volte ao painel de pedidos, remova os pedidos listados e verifique o status de cada um em **Operação > Pedidos** |
| *Nenhum desses pedidos foi encontrado: \[números]* | Os pedidos foram alterados ou removidos entre a seleção e o envio | Atualize a lista e selecione os pedidos novamente |
### Transportadora / integração com problema [#transportadora--integração-com-problema]
| Erro exibido | Causa | O que fazer |
| --------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| *Integração de transportadora não encontrada* | A integração de transportadora selecionada foi desativada ou removida | Verifique se a integração está ativa em **Configurações > Integrações de transportadora** |
| *Armazém não associado a sua organização* | O armazém da filial pertence a outro seller group | Verifique a configuração da filial com o time de suporte |
### Erro genérico [#erro-genérico]
| Erro exibido | Causa provável | O que fazer |
| ------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------ |
| *Erro ao criar rota, tente novamente mais tarde* | Falha no serviço de roteirização ou instabilidade | Aguarde alguns minutos e tente novamente. Se o problema persistir, contate o suporte |
***
## "Sugerir rota" retorna erro ou não funciona [#sugerir-rota-retorna-erro-ou-não-funciona]
| Erro / Sintoma | Causa | O que fazer |
| ------------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| *Botão desabilitado* | Nenhum pedido selecionado | Selecione ao menos 1 pedido antes de sugerir a rota |
| Pedidos de filiais diferentes | A sugestão exige pedidos da mesma filial | Use o filtro de **Filial** no painel de pedidos para garantir que todos são da mesma origem |
| *Não foi possível sugerir uma rota com a configuração atual* | O serviço de roteirização não encontrou trajeto válido | Tente remover pedidos com endereço inválido ou reduzir a quantidade selecionada |
| *Não foi possível incluir todos os pedidos obrigatórios* | A otimização não conseguiu encaixar todos os pedidos obrigatórios | Reduza o número de pedidos ou desmarque alguns como obrigatórios |
***
## Pedidos não aparecem na lista de seleção [#pedidos-não-aparecem-na-lista-de-seleção]
| Sintoma | Causa provável | O que fazer |
| ------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Pedido existe em **Pedidos** mas não aparece aqui | Pedido não está em status roteável | Verifique o status na tela de **Pedidos**. Pedidos já finalizados, cancelados ou com falha não são roteáveis |
| Lista vazia mesmo com pedidos ativos | Período muito restrito no filtro de datas | Amplie o intervalo de datas no painel de pedidos |
| Pedido de outra filial não aparece | Filtro de **Filial** ativo no painel direito | Remova ou ajuste o filtro de **Filial** |
***
## Rota criada não aparece na listagem [#rota-criada-não-aparece-na-listagem]
| Sintoma | Causa | O que fazer |
| ----------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------- |
| Rota recém-criada não está visível | O período padrão (últimos 7 dias) não inclui a rota | Ajuste o período nos filtros da tela de Rotas |
| Filtro de status excluindo a rota | Status **CRIADA** desmarcado | Marque o status **CRIADA** no filtro de **Status** |
| Rota visível para um usuário mas não para outro | Filtro de **Entregue por** diferente entre usuários | Verifique se o filtro de transportadora está configurado da mesma forma |
***
## Ação "Solicitar coleta" indisponível no menu ⋮ [#ação-solicitar-coleta-indisponível-no-menu-]
| Causa | O que fazer |
| -------------------------------------- | ----------------------------------------------------------------------- |
| Rota já tem transportadora atribuída | Solicitar coleta só está disponível para rotas sem responsável definido |
| Pedidos pertencem a mais de uma filial | A solicitação de coleta exige pedidos de uma única filial na rota |
| Usuário sem permissão para esta ação | Solicite acesso ao administrador da conta |
---
# Tabelas de Frete — Como Usar (/docs/log/products/tabelas-de-frete/como-usar)
Guia prático das principais ações para configurar e operar tabelas de frete.
***
## Fluxo típico [#fluxo-típico]
1. Acesse **Operação > Tabelas de frete** (`/shipping-tables`).
2. Escolha a aba **Tabelas de Raio** ou **Tabelas de CEP**.
3. Clique em **Adicionar nova tabela** para criar, ou use o menu (⋮) para ver, editar, baixar ou excluir.
4. Ao editar, revise as automações vinculadas nas abas laterais.
***
## Criar uma tabela de CEP [#criar-uma-tabela-de-cep]
### Passo 1: Abrir o modal de criação [#passo-1-abrir-o-modal-de-criação]
1. Clique em **Adicionar nova tabela**.
2. Selecione o tipo **Tabela de CEP**.
### Passo 2: Preencher informações [#passo-2-preencher-informações]
1. Informe o **nome** da tabela (ex.: "Correios PAC - Nacional").
2. Selecione a **modalidade** (transportadora + modalidade, ex.: Correios / PAC).
### Passo 3: Upload do arquivo [#passo-3-upload-do-arquivo]
1. Clique em **Baixar modelo** para obter o template no formato correto.
2. Preencha o arquivo Excel com os dados do contrato. O arquivo tem uma única aba onde cada linha representa uma faixa de CEP:
* Colunas: CEP inicial, CEP final, faixas de peso com seus preços, valor por kg adicional e o [prazo](/docs/log/conceitos/prazos/) (ex.: "D1", "D3", "D7").
* O prazo é informado como uma coluna em cada linha — diferentes prazos ficam em linhas separadas, não em abas separadas.
3. Faça upload do arquivo preenchido.
### Passo 4: Revisar e salvar [#passo-4-revisar-e-salvar]
1. Confira a **prévia** dos dados importados.
2. Clique em **Salvar**.
***
## Criar uma tabela de Raio [#criar-uma-tabela-de-raio]
O fluxo é o mesmo da tabela de CEP, com uma diferença no formato do arquivo:
* O arquivo Excel tem **múltiplas abas** — cada aba representa um [prazo](/docs/log/conceitos/prazos/) (ex.: "D1", "EXP60").
* Dentro de cada aba: as linhas são as faixas de distância em km e as colunas são as faixas de peso com seus preços.
***
## Visualizar uma tabela [#visualizar-uma-tabela]
1. Na lista, clique no botão de **olho** ou no menu (⋮) > **Ver tabela**.
2. O modal exibe:
* Nome e modalidade da tabela.
* Abas por prazo — clique em cada aba para ver as faixas e preços.
* Para tabelas de CEP: use o **filtro por CEP** para buscar uma faixa específica.
3. Clique em **Baixar** para exportar os dados em formato planilha.
***
## Editar uma tabela [#editar-uma-tabela]
### Editar nome e dados [#editar-nome-e-dados]
1. No menu (⋮), clique em **Editar tabela**.
2. Na aba **Tabela**:
* Altere o **nome** diretamente.
* Para atualizar dados: faça upload de um novo arquivo. Prazos com o mesmo nome são sobrescritos; novos prazos são adicionados.
* Clique em **Baixar tabela** para exportar os dados atuais antes de editar.
### Revisar automações vinculadas [#revisar-automações-vinculadas]
Ao editar uma tabela, as abas laterais mostram as automações vinculadas:
1. Clique na aba **Automações de envio**, **Automações de reenvio** ou **Automações de inatividade**.
2. Cada automação mostra um indicador:
* **Verde** — o prazo referenciado existe na tabela.
* **Vermelho** — o prazo foi removido ou não existe.
3. Se houver automações inválidas, ajuste o prazo na automação antes de salvar.
### Salvar [#salvar]
Clique em **Salvar** para atualizar a tabela e todas as automações de uma vez.
***
## Baixar uma tabela [#baixar-uma-tabela]
No menu (⋮), clique em **Baixar tabela** para exportar os dados em formato planilha. Útil para:
* Conferir os dados atuais antes de editar.
* Compartilhar com a transportadora para validação.
* Ter um backup antes de alterações.
***
## Excluir uma tabela [#excluir-uma-tabela]
1. No menu (⋮), clique em **Excluir**.
2. Confirme no modal de confirmação.
***
## Boas práticas [#boas-práticas]
* **Nomeie com clareza** — Inclua transportadora, modalidade e região no nome (ex.: "Correios PAC - SP e RJ").
* **Atualize junto com o contrato** — Sempre que renegociar valores com a transportadora, atualize a tabela.
* **Revise automações ao editar** — Antes de remover prazos, confira as automações nas abas laterais do modal de edição.
* **Prefira ações automáticas** — Automações com ação **mais barato** ou **mais rápido** se adaptam automaticamente a mudanças na tabela, sem necessidade de ajuste manual.
* **Baixe antes de editar** — Exporte a tabela atual como backup antes de fazer upload de novos dados.
---
# Tabelas de Frete — Visão Geral (/docs/log/products/tabelas-de-frete)
A tela de **Tabelas de Frete** permite criar, visualizar, editar e excluir as tabelas que definem preços e prazos de envio por faixa de CEP ou raio de distância.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/shipping-tables](https://dashboard.abbiamolog.com/shipping-tables)
* **Menu:** seção **Operação** > **Tabelas de frete**
***
## O que o cliente vê ao entrar [#o-que-o-cliente-vê-ao-entrar]
### Cabeçalho [#cabeçalho]
| Elemento | Descrição |
| ------------------------- | -------------------------------------- |
| **Menu lateral duplo** | Abre/fecha a sidebar |
| **Título** | "Tabelas de frete" |
| **Adicionar nova tabela** | Abre o modal de criação de nova tabela |
### Abas [#abas]
A tela é dividida em duas abas:
| Aba | O que mostra |
| ------------------- | ------------------------------------------------------------ |
| **Tabelas de Raio** | Tabelas que definem preço por faixa de distância (km) e peso |
| **Tabelas de CEP** | Tabelas que definem preço por faixa de CEP de destino e peso |
Ao trocar de aba, a URL é atualizada (`/shipping-tables/radius` ou `/shipping-tables/cep`).
### Barra de filtros e controles [#barra-de-filtros-e-controles]
* **Campo de busca** — Busca por nome da tabela.
* **Botão atualizar** — Recarrega a lista de tabelas.
* **Filtro por transportador** — Filtra tabelas pela transportadora vinculada.
* **Visibilidade de colunas** — Mostrar/ocultar colunas da tabela.
### Tabela de frete [#tabela-de-frete]
| Coluna | O que mostra |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | Nome da tabela |
| **Modalidade** | Transportadora + modalidade (ex.: Correios / PAC) |
| **Tipo** | Badge indicando "Tabela de raio" ou "Tabela de CEP" |
| **Ver** | Botão para abrir a visualização da tabela |
| **Integrações** | Quantidade de [integrações de transportadora](/docs/log/products/integracoes-de-transportadora/) vinculadas a esta tabela |
| **Criada em** | Data/hora de criação |
| **Atualizada em** | Data/hora da última atualização |
| **Menu (⋮)** | Ações por tabela |
### Menu de ações por tabela (⋮) [#menu-de-ações-por-tabela-]
| Ação | Descrição |
| ----------------- | ----------------------------------------------------------- |
| **Ver tabela** | Abre a visualização completa da tabela |
| **Baixar tabela** | Faz download da tabela em formato planilha |
| **Editar tabela** | Abre o modal de edição (com automações) |
| **Excluir** | Remove a tabela (desabilitado se há integrações vinculadas) |
***
## Criar tabela [#criar-tabela]
Ao clicar em **Adicionar nova tabela**, o modal de criação é aberto:
### Passo a passo [#passo-a-passo]
1. **Escolher o tipo** — Selecione entre tabela de **Raio** ou tabela de **CEP**.
2. **Informar o nome** — Defina um nome para identificar a tabela.
3. **Selecionar a modalidade** — Escolha a transportadora + modalidade (ex.: Correios / PAC, Uber / Carro).
4. **Fazer upload do arquivo** — Envie o arquivo com os dados da tabela:
* **Tabela de CEP:** arquivo Excel (`.xlsx`) com uma única aba. Cada linha representa uma faixa de CEP, e o [prazo](/docs/log/conceitos/prazos/) (ex.: "D1", "D3", "EXP60") é informado como uma coluna em cada linha, junto com as faixas de peso e seus preços.
* **Tabela de Raio:** arquivo Excel (`.xlsx`) com múltiplas abas. Cada aba representa um prazo (ex.: "D1", "EXP60"). Dentro de cada aba, as linhas são as faixas de km e as colunas são as faixas de peso com seus preços.
5. **Revisar o preview** — Antes de salvar, o sistema exibe uma prévia dos dados importados para conferência.
6. **Salvar** — Confirma a criação da tabela.
***
## Visualizar tabela [#visualizar-tabela]
Ao clicar em **Ver tabela** (botão de olho ou menu ⋮), um modal exibe:
* **Nome** e **modalidade** da tabela
* **Abas por prazo** — Cada prazo (D1, D3, EXP60...) aparece em uma aba separada
* **Dados da tabela** — Faixas de destino (CEP ou km) com os preços por faixa de peso
* **Filtro por CEP** (apenas para tabelas de CEP) — Permite buscar uma faixa específica digitando um CEP
* **Botão de download** — Faz download da tabela em formato planilha
***
## Editar tabela [#editar-tabela]
Ao clicar em **Editar tabela**, um modal com abas laterais é aberto:
### Aba "Tabela" [#aba-tabela]
* **Editar nome** — Altere o nome da tabela diretamente.
* **Visualizar dados atuais** — Os prazos e faixas atuais são exibidos.
* **Baixar tabela** — Faz download dos dados atuais.
* **Upload de novos dados** — Envie um novo arquivo para adicionar ou sobrescrever prazos. Prazos com o mesmo nome são sobrescritos; novos prazos são adicionados.
### Aba "Automações de envio" [#aba-automações-de-envio]
Lista as [automações de envio](/docs/log/conceitos/regra-envio/) vinculadas às integrações que usam esta tabela. Exibe um indicador de validação:
* **Verde:** a automação está válida (o prazo referenciado existe na tabela).
* **Vermelho:** a automação está inválida (o prazo referenciado foi removido da tabela).
### Aba "Automações de reenvio" [#aba-automações-de-reenvio]
Lista as [automações de reenvio](/docs/log/conceitos/regra-reenvio/) vinculadas, com o mesmo indicador de validação.
### Aba "Automações de inatividade" [#aba-automações-de-inatividade]
Lista as [automações de inatividade](/docs/log/conceitos/regra-inatividade/) vinculadas, com o mesmo indicador de validação.
### Salvar [#salvar]
Ao clicar em salvar, a tabela e todas as automações são atualizadas em conjunto.
***
## Excluir tabela [#excluir-tabela]
Ao clicar em **Excluir**, um modal de confirmação é exibido. A exclusão só é possível quando a tabela **não possui integrações vinculadas**. Se houver integrações, o botão de excluir fica desabilitado com uma explicação.
***
## Estado vazio [#estado-vazio]
Quando não há tabelas cadastradas:
> *"Nenhuma tabela de frete encontrada"*
> *"Crie uma nova tabela de frete para começar"*
***
## Paginação [#paginação]
* Tamanhos de página: **50, 100, 150, 200**
***
## Próximos passos [#próximos-passos]
* [**Como usar**](/docs/log/products/tabelas-de-frete/como-usar/) — passo a passo para criar, editar e gerenciar tabelas de frete.
* [**Troubleshooting**](/docs/log/products/tabelas-de-frete/troubleshooting/) — dúvidas comuns e problemas frequentes.
***
## Links relacionados [#links-relacionados]
* [Conceito de Tabela de Frete](/docs/log/conceitos/tabela-frete/) — o que é, tipos, estrutura e relação com automações
* [Cotação de Frete](/docs/log/conceitos/cotacao-frete/) — como a tabela é usada para calcular preço e prazo
* [Integrações de Transportadora](/docs/log/products/integracoes-de-transportadora/) — onde a tabela é vinculada
* [Automações de Envio](/docs/log/products/regras-de-envio/) — automações que dependem dos prazos da tabela
---
# Tabelas de Frete — Troubleshooting (/docs/log/products/tabelas-de-frete/troubleshooting)
Este guia ajuda a resolver as dúvidas e problemas mais comuns ao configurar e usar tabelas de frete.
***
## 1. "O pedido falhou com erro de prazo não encontrado" [#1-o-pedido-falhou-com-erro-de-prazo-não-encontrado]
O envio falha quando a automação tenta fazer a solicitação de coleta com um prazo (ex.: D1) que não existe mais na tabela de frete da integração.
**Causa mais comum:** a tabela foi editada e o prazo foi removido ou renomeado, mas a automação de envio ainda referencia o prazo antigo.
**O que fazer:**
1. Acesse **Operação > Automações de envio** e localize a automação que falhou.
2. Edite a automação e altere o prazo para um que exista na tabela, ou mude a ação para **mais barato** / **mais rápido**.
3. Alternativamente, edite a tabela de frete e adicione novamente o prazo que a automação espera.
***
## 2. "O pedido falhou como 'fora de cobertura'" [#2-o-pedido-falhou-como-fora-de-cobertura]
O envio falha com status "fora de cobertura" quando o CEP ou distância do destino não está mapeado em nenhuma faixa da tabela de frete, e a integração tem a **cobertura restrita** ativada.
**O que fazer:**
* **Adicionar a faixa:** edite a tabela de frete e inclua o CEP ou faixa de km que cobre o destino do pedido.
* **Desativar a restrição:** se quiser que o envio seja tentado mesmo para destinos não mapeados, desative a cobertura restrita na [integração de transportadora](/docs/log/products/integracoes-de-transportadora/).
***
## 3. "Nenhuma opção aparece na cotação / simulação de frete" [#3-nenhuma-opção-aparece-na-cotação--simulação-de-frete]
Quando a cotação não retorna nenhuma opção, pode ser que:
* **Nenhuma integração cobre o destino** — Verifique se as integrações da filial estão ativas e se as tabelas de frete têm faixas para aquele CEP ou distância.
* **O peso está fora das faixas da tabela** — Confira se a tabela tem faixas de peso suficientes para o peso do pedido.
* **A integração não tem tabela vinculada** — Verifique na tela de [Integrações de Transportadora](/docs/log/products/integracoes-de-transportadora/) se a integração tem uma tabela de frete associada.
***
## 4. "Não consigo excluir a tabela" [#4-não-consigo-excluir-a-tabela]
Tabelas com integrações vinculadas não podem ser excluídas. O botão de excluir fica desabilitado com uma explicação.
**O que fazer:**
1. Acesse **Operação > Integrações de transportadora**.
2. Localize as integrações que usam esta tabela (veja a coluna "Tabela de frete").
3. Edite cada integração e altere a tabela de frete para outra, ou remova o vínculo.
4. Após desvincular todas as integrações, volte à tela de tabelas e exclua.
***
## 5. "O upload do arquivo deu erro" [#5-o-upload-do-arquivo-deu-erro]
Verifique se o arquivo está no formato correto:
* **Tabela de CEP:** arquivo Excel (`.xlsx`) com uma única aba. Cada linha contém CEP inicial, CEP final, faixas de peso com preços, valor por kg adicional e o prazo (ex.: "D1", "D3", "EXP60") como coluna.
* **Tabela de Raio:** arquivo Excel (`.xlsx`) com múltiplas abas. Cada aba deve ter o nome do prazo (ex.: "D1", "EXP60"). Os nomes de aba válidos seguem o padrão D seguido de número (D1, D2, D10) ou EXP seguido de número (EXP60, EXP120).
Erros comuns no arquivo:
* **Faixas de CEP sobrepostas** (CEP) — Duas faixas no mesmo prazo não podem cobrir os mesmos CEPs.
* **CEP início maior que CEP fim** (CEP) — O CEP inicial deve ser menor ou igual ao CEP final.
* **Nome da aba inválido** (Raio) — Use apenas "D1", "D2", "EXP60", etc. Sem espaços ou caracteres especiais.
* **Valores duplicados de km ou peso** (Raio) — Cada faixa de km ou peso deve ser única dentro do prazo.
***
## 6. "Editei a tabela e as automações ficaram inválidas" [#6-editei-a-tabela-e-as-automações-ficaram-inválidas]
Ao remover ou renomear prazos na tabela, automações que usam **prazo específico** com o prazo antigo ficam inválidas (indicador vermelho).
**O que fazer:**
1. No modal de edição da tabela, clique nas abas de automações (envio, reenvio, inatividade).
2. Localize as automações com indicador vermelho.
3. Ajuste o prazo de cada automação para um prazo que existe na tabela, ou mude a ação para **mais barato** / **mais rápido**.
4. Salve.
***
## 7. "A data de entrega esperada está errada na cotação" [#7-a-data-de-entrega-esperada-está-errada-na-cotação]
A data de entrega esperada depende de vários fatores além do prazo da tabela:
* **Horário de corte** — Se o pedido foi criado depois do horário de corte da integração, a contagem do prazo começa no próximo dia útil. Veja [Horário de corte](/docs/log/conceitos/tabela-frete/#horário-de-corte).
* **Dias de operação** — Dias em que a transportadora não opera são pulados na contagem.
* **Feriados** — Feriados cadastrados são pulados na contagem.
* **Regras de cotação** — Regras de cotação podem alterar a data de entrega calculada.
Verifique o horário de corte na [integração de transportadora](/docs/log/products/integracoes-de-transportadora/) e os dias de operação configurados.
***
## 8. "Não tenho acesso à tela de Tabelas de Frete" [#8-não-tenho-acesso-à-tela-de-tabelas-de-frete]
O acesso à tela depende das permissões configuradas na sua conta. Entre em contato com o administrador da conta ou com o suporte da Abbiamo para verificar se o módulo de tabelas de frete está habilitado.
---
# Criar pedido (v2) — deprecado (/docs/create-order-v2-deprecated)
---
# Criar pedido (v2) — cópia (/docs/create-order-v2-copy)
---
# Criar pedido (v2) (/docs/create-order-v2)
---
# Criar rota para novos pedidos (/docs/create-route-for-new-orders)
---
# Tratar pedido manualmente (/docs/cancel-order)
---
# Marcar pedido como retirado (/docs/set-order-as-withdrawn)
---
# Consultar pedido por order_id (/docs/get-order-by-order-id)
---
# Atualizar dados do pedido (/docs/update-order)
---
# Consultar pedido por order_number (/docs/get-order-by-order-number)
---
# Consultar pedido por external_id (/docs/get-order-by-external-id)
---
# Consultar pedido por chave de acesso (/docs/get-order-by-access-key)
---
# Eventos do pedido por order_id (/docs/get-events-by-order-id)
---
# Eventos do pedido por order_number (/docs/get-events-by-order-number)
---
# Eventos do pedido por external_id (/docs/get-events-by-external-id)
---
# Eventos do pedido por chave de acesso (/docs/get-events-by-access-key)
---
# Obter token de retirada (/docs/get-takeout-token)
---
# QR Code estático de retirada (/docs/get-takeout-static-qrcode)
---
# Instruções de retirada (PDF) (/docs/get-takeout-instructions)
---
# Pedido de abastecimento (v3) (/docs/create-supply-order-v3)
---
# Listar marcadores (/docs/listTags)
---
# Listar filiais (/docs/get-sellers)
---
# Criar filial (/docs/create-seller)
---
# Cotar pedidos (v1) (/docs/quote-orders)
---
# Cotar pedidos (v2) (/docs/quote-orders-v2)
---
# Opções de entrega (/docs/delivery-options)
---
# Solicitar entrega (modalidade específica) (/docs/request-delivery)
---
# Reenviar entrega (/docs/resend-delivery)
---
# Cancelar entrega (/docs/cancel-delivery)
---
# Cancelar pedido (/docs/order-cancel)
---
# Atualizar status manualmente (/docs/update-order-status-manually)
---
# Consultar motorista (/docs/get-driver)
---
# Listar motoristas (/docs/get-drivers)
---
# Criar/atualizar motoristas (/docs/create-drivers)
---
# Trocar motorista da rota (/docs/change-driver-of-route)
---
# Cancelar rota (/docs/cancel-route)
---
# Consultar warehouse (/docs/get-warehouse)
---
# Listar warehouses (/docs/get-warehouses)
---
# Criar rota a partir de pedidos (/docs/create-route-from-orders)
---
# Verificações do pedido (coleta e retorno) (/docs/order-verification)
---
# Confirmar pincode de coleta (/docs/order-verification-pickup-confirm)
---
# Cotar entrega por itens do pedido (/docs/quote-delivery-by-products)
---
# Cotar entrega por pontos de origem (/docs/quote-delivery-by-origins)
---
# Listar webhooks (/docs/list-webhooks)
---
# Criar webhook (/docs/create-webhook)
---
# Atualizar webhook (/docs/update-webhook)
---
# Deletar webhook (/docs/delete-webhook)
---
# Consultar entrega (/docs/get-delivery)
---
# Motorista no ponto de coleta (/docs/at-pickup-point)
---
# Cancelar entrega (transportadora) (/docs/carrier-cancel-delivery)
---
# Entrega coletada (/docs/carrier-collected-delivery)
---
# Coletando entrega (/docs/carrier-collecting-delivery)
---
# Confirmar entrega (/docs/carrier-confirm-delivery)
---
# Motorista atribuído (/docs/carrier-driver-assigned)
---
# Motorista recusou (/docs/carrier-driver-rejected)
---
# Falha na coleta (/docs/carrier-failed-to-collect)
---
# Falha na entrega (/docs/carrier-failed-to-deliver)
---
# Falha no retorno (/docs/carrier-failed-to-return)
---
# Manuseando entrega (/docs/carrier-handling-delivery)
---
# Entrega devolvida (/docs/carrier-returned-delivery)
---
# Devolvendo entrega (/docs/carrier-returning-delivery)
---
# Procurando motorista (/docs/carrier-searching-driver)
---
# Iniciar entrega (/docs/carrier-start-delivery)
---
# Entrega bem-sucedida (/docs/carrier-successful-delivery)
---
# Atualizar destinatário da entrega (/docs/update-delivery-receiver)
---
# Atualizar detalhes da entrega (/docs/update-deliveries-details)
---
# Atualizar CT-e da entrega (/docs/update-delivery-cte)
---
# Atualizar NF-e da entrega (/docs/update-delivery-nfe)
---
# Atualizar etiqueta da entrega (/docs/update-delivery-mail-label)
## Precisa abrir um novo? É dali mesmo [#precisa-abrir-um-novo-é-dali-mesmo]
O botão **Novo ticket** abre um formulário direto: descreva o que aconteceu, escolha a categoria e, se ajudar, anexe imagens ou arquivos. O chamado entra na fila do suporte e passa a aparecer na sua lista.
## Por que isso importa [#por-que-isso-importa]
Acompanhar um chamado por e-mail é fácil de perder o fio: a thread some no meio da caixa de entrada, e saber "em que pé está" vira uma garimpagem. Trazer isso pro dashboard significa **visibilidade** — você vê, a qualquer momento, tudo que abriu com a gente e o status de cada coisa — no **mesmo design** que já está chegando às outras telas (como você viu em Relatórios).
A tela **já está disponível para todas as marcas** — é só abrir a seção **Suporte** no menu e começar a usar. Feedback é muito bem-vindo pelo próprio suporte ou aqui pelo Abbiamo Docs.
*Vários eventos no mesmo lugar viram um +N; o clique expande e mostra todos empilhados ali.*
*Clicar no Local de um evento abre a coordenada com **Ver no mapa**, **Copiar** e **Google Maps**.*
## Pra que serve [#pra-que-serve]
Saber **onde** cada etapa aconteceu ajuda a entender o pedido sem sair do painel:
* **Conferir uma entrega** — o mapa mostra a **distância** entre o ponto de "Entregue" e o endereço do cliente (ex.: *"Entregue a 53 m do endereço do cliente"*).
* **Investigar uma falha** — onde o motorista registrou a tentativa que não deu certo?
* **Apurar uma disputa** — a localização de cada evento vira evidência concreta, a um clique.
## Quando um evento não aparece no mapa [#quando-um-evento-não-aparece-no-mapa]
* **Eventos sem coordenada** — atualizações antigas ou de integrações que não enviam localização não têm ponto no mapa (nem o Local no histórico). O restante do histórico continua igual.
* **Pedidos sem o mapa** — como o mapa depende de origem e destino geolocalizados (e não vale pra retiradas), pedidos nessas condições não mostram os pontos. O **Local** no histórico, esse aparece de qualquer forma.
## O que não mudou [#o-que-não-mudou]
* Permissões: quem já via o pedido e o mapa continua vendo tudo, sem nada novo pra configurar.
* O mapa, a rota estimada e a distância dirigida seguem exatamente como antes — os pontos dos eventos são um acréscimo por cima deles.
***
## Como o motorista vê [#como-o-motorista-vê]
Quando as ofertas usam precificação por rota, o app do motorista deixa de mostrar o frete por pedido e passa a exibir o **total da rota**. Ao selecionar os pedidos, ele vê **"Você recebe R$ X"** antes de aceitar — sabe exatamente quanto vai ganhar pelo trajeto completo.
***
---
# Automação de prazo prometido: a plataforma preenche o prazo do cliente (/docs/changelog/2026-07-30-automacao-prazo-prometido)
## Como o motorista ativa [#como-o-motorista-ativa]
Na primeira vez, o app mostra um convite explicando o alerta e pede, **em passos**, as duas permissões que ele precisa: **exibir sobre outros apps** e **notificações** (é por elas que a oferta chega e toca o som). Se ele adiar, o app lembra de novo mais pra frente — sem insistir a cada abertura.
---
# Ações no rastreio: escolha quais botões o seu cliente pode usar (/docs/changelog/2026-08-14-acoes-no-rastreio)
## O que dá pra fazer [#o-que-dá-pra-fazer]
## O que acontece quando o cliente usa [#o-que-acontece-quando-o-cliente-usa]
Cada ação abre um caso no **Care** — o mesmo lugar onde seu time acompanha e resolve. O cliente relata pela página de rastreio, e vocês conduzem pelo painel, com histórico próprio. É a ponte entre o que o cliente quer e a sua operação.
## O que mudou [#o-que-mudou]
## Como ativar [#como-ativar]
Na página **Segurança**, clique em **Ativar**. Você vai:
1. **Escanear o QR Code** com o seu aplicativo autenticador — ou copiar a chave, se preferir digitar.
2. **Digitar o código de 6 dígitos** que o app gera e clicar em **Ativar**.
Pronto. A partir daí, sempre que você entrar na Abbiamo, vamos pedir o código do app.
## Contas que já exigem 2FA [#contas-que-já-exigem-2fa]
Algumas contas com acesso a informações mais sensíveis já têm a verificação em duas etapas **obrigatória**. Nesses casos, na primeira vez que você entrar, vamos pedir para configurá-la ali mesmo na tela de login — é o mesmo passo a passo, com o QR Code e o código.
## Perdeu o acesso ao aplicativo? [#perdeu-o-acesso-ao-aplicativo]
Se você trocar de celular ou perder o acesso ao aplicativo autenticador, fale com o suporte para reativar sua conta com segurança.
---
# Marcadores de rota: identifique e filtre suas rotas por cor (/docs/changelog/2026-08-17-marcadores-de-rota)
## O que dá pra fazer [#o-que-dá-pra-fazer]
## Como aplicar em uma rota [#como-aplicar-em-uma-rota]
## O que muda [#o-que-muda]
## Repasses — pague seus entregadores sem sair do painel [#repasses--pague-seus-entregadores-sem-sair-do-painel]
## Auditoria — audite o frete das suas transportadoras [#auditoria--audite-o-frete-das-suas-transportadoras]
## O que mudou [#o-que-mudou]
Dá pra combinar quantas condições quiser, com **E** e **OU**, e agrupar — a mesma montagem de filtro da lista de Pedidos.
## Sem condição, nada muda [#sem-condição-nada-muda]
Webhook sem filtro continua recebendo todas as atualizações do evento, exatamente como antes. Os webhooks que você já tem hoje **não foram alterados**.
## Como configurar [#como-configurar]
1. Vá em **Configurações › Webhooks**.
2. Crie um webhook novo ou edite um existente.
3. Na seção **Condições**, desmarque *"Enviar todas as atualizações desse evento"*.
4. Monte o filtro e salve.
A listagem de webhooks passa a mostrar uma coluna **Condições**, com o resumo do filtro de cada um — dá pra ver de relance quem está filtrando o quê.
***
## Os critérios ficam visíveis antes de enviar [#os-critérios-ficam-visíveis-antes-de-enviar]
Com a automação escolhida, três informações aparecem lado a lado:
* **Quem recebe** — todos os motoristas da filial, um grupo específico ou uma lista de motoristas, conforme a automação.
* **Distância máxima da filial** — o raio configurado na automação, ou "sem limite" quando não há um.
* **Disponíveis agora** — quantos motoristas atendem esse critério neste momento. Quando ninguém atende, um aviso deixa isso claro antes do envio.
Se a filial tiver mais de uma automação cadastrada, dá para trocar para outra na mesma tela — e a configuração manual (escolher motoristas e distância na mão) continua disponível como alternativa.
## Como configurar as automações [#como-configurar-as-automações]
As automações de oferta continuam sendo criadas e editadas em Automações de ofertas, dentro de **Configurações → Automações de ofertas** — nada muda por lá. O que muda é que o reenvio manual agora as aplica também.
***
Se o preço não aparecer, veja o [Troubleshooting](/docs/go/products/tabela-de-ofertas/troubleshooting/).
---
# Tabela de Ofertas — Visão Geral (/docs/go/products/tabela-de-ofertas)
A **Tabela de Ofertas** define a **precificação por rota** do GO: em vez de o motorista ganhar o valor de frete de cada pedido isolado, ele é remunerado pela **rota inteira** que monta a partir das ofertas — considerando a distância percorrida, o número de paradas e as coletas feitas.
***
## Onde acessar [#onde-acessar]
* **URL:** [https://dashboard.abbiamolog.com/shipping-tables/offers](https://dashboard.abbiamolog.com/shipping-tables/offers)
* **Menu:** **Tabelas de frete** > aba **Tabela de Ofertas**
A tela fica ao lado das tabelas de frete por **Raio** e por **CEP** — a Tabela de Ofertas é a aba dedicada à precificação por rota.
