Conectando a Omie (ERP) - BulkRoute Central de Ajuda

A Omie é um ERP completo para PMEs. A integração usa autenticação por App Key + App Secret — sem OAuth.

Conectando

1. Obter credenciais

Faça login na Omie
Vá em Configurações > API
Gere um par App Key + App Secret
Copie ambos os valores

2. Conectar no BulkRoute

Acesse Integrações > Omie > Conectar
Preencha App Key e App Secret
Clique em Conectar

O BulkRoute envia app_key e app_secret no corpo de cada requisição à API da Omie. Para desconectar, use Desconectar.

3. Mapear carriers

A Omie identifica transportadoras por transporte.transportadora.codigo. Mapeie cada uma em Integrações > Omie > Mapeamentos:

Carrier na Omie (código)	Carrier no BulkRoute
Código da Braspress	`BRASPRESS`
Código dos Correios	`CORREIOS`
Código da Jadlog	`JADLOG`
(outro)	`OMIE` (fallback automático)

Se não houver mapeamento, o BulkRoute faz fallback por nome: se o nome da transportadora contiver “CORREIOS”, “JADLOG” ou “BRASPRESS”, usa o carrier correspondente; caso contrário, usa OMIE.

4. Disparar sincronização

A sincronização é manual — não há cron automático. Para importar pedidos:

Em Integrações > Omie, clique em Sincronizar Agora
Escolha o tipo de sync:
- orders — importa pedidos da Omie
- tracking — envia tracking codes de volta à Omie
- full — executa ambos
O job entra na fila BullMQ e processa em background (concurrency 2)
Acompanhe o progresso em Sync History

A importação da Omie busca todas as páginas de pedidos até a última retornar menos de 100 registros (não filtra por data como o Tiny).

O que é importado

Campo da Omie	Campo no BulkRoute
`order.codigo_pedido` / `codigo_lancamento`	`external_order_id`
`order.transporte.transportadora.codigo`	`carrier_code` (via mapeamento)
`order.transporte.cep` / `contato.cep`	`destination_zip`
`contato.nome` / `transporte.nome`	`recipient.name`
`contato.telefone` / `transporte.telefone`	`recipient.phone`
`produto.codigo` / `cod_produto`	`items[].sku`
`produto.descricao` / `desc_prod`	`items[].description`
`item.quantidade` / `qtd`	`items[].quantity`
`produto.peso`	`items[].weight`
`produto.altura` / `largura` / `comprimento`	`items[].height/width/length`
`item.valor` / `produto.valor_unitario`	`items[].value`

Metadados adicionais: omieOrderId, omieCarrierName, omieCarrierId. Status inicial: PENDING.

Sincronização de tracking

O BulkRoute envia o tracking code de volta à Omie via POST /geral/rastreio/ com a call EnviarRastreio:

{
  "call": "EnviarRastreio",
  "app_key": "...",
  "app_secret": "...",
  "param": [{
    "codigo_pedido": 12345,
    "codigo_rastreio": "BR123456789BR",
    "transportadora": "Braspress"
  }]
}

O sync tracking busca shipments com tracking_code e metadata.omieOrderId (limite 200 por execução).

Endpoints da API BulkRoute

Método	Endpoint	Descrição
`POST`	`/integrations/omie/connect`	Conectar com App Key + Secret
`POST`	`/integrations/omie/disconnect`	Desconectar
`POST`	`/integrations/omie/sync`	Disparar sincronização
`GET`	`/integrations/omie/sync-history`	Histórico de sincronizações
`GET`	`/integrations/omie/sync-history/:id`	Detalhe de um sync
`POST`	`/integrations/omie/sync-history/:id/retry`	Reprocessar sync falho
`GET`	`/integrations/omie/mappings`	Listar mapeamentos
`POST`	`/integrations/omie/mappings`	Criar mapeamento
`PUT`	`/integrations/omie/mappings/:id`	Atualizar mapeamento
`DELETE`	`/integrations/omie/mappings/:id`	Remover mapeamento
`GET`	`/integrations/omie/status`	Status da conexão

Rate limit e retry

A API da Omie tem rate limit. Em 429, o BulkRoute respeita Retry-After (default 2s) e tenta novamente (até 3 vezes)
Fila BullMQ: 3 tentativas, backoff exponencial de 10s
Concorrência do worker: 2

Troubleshooting

Problema	Causa	Solução
App Key/Secret inválidos	Credenciais erradas ou revogadas	Gerar novo par na Omie e reconectar
Pedidos não importam	Sync não disparado	Disparar manualmente em Integrações > Omie
Pedido sem CEP	Cliente sem endereço completo	Preencher CEP na Omie
Carrier não mapeado	Carrier da Omie sem mapeamento	Adicionar mapeamento

​Conectando

​1. Obter credenciais

​2. Conectar no BulkRoute

​3. Mapear carriers

​4. Disparar sincronização

​O que é importado

​Sincronização de tracking

​Endpoints da API BulkRoute

​Rate limit e retry

​Troubleshooting

Conectando

1. Obter credenciais

2. Conectar no BulkRoute

3. Mapear carriers

4. Disparar sincronização

O que é importado

Sincronização de tracking

Endpoints da API BulkRoute

Rate limit e retry

Troubleshooting