Orquestrador Mobility ⟷ Omie

Toda rota da Mobility exige o header X-Api-Key.

• A chave é gerada pela IAXYS e fica na variável MOBILITY_API_KEY.
• Chave ausente ou diferente devolve 401. Servidor sem chave configurada devolve 503.
• A comparação é feita em tempo constante para não vazar informação por tempo de resposta.

Cada reserva é identificada por empresa, filial, File e CodigoWooMobil.

• Chave: {empresa}-{filial}-{file}-{CodigoWooMobil da reserva}. Exemplo: 29-26-00341130-341131.
• A Mobility envia um payload por reserva. Reservas diferentes do mesmo File são aceitas e ficam agrupadas.
• Reenviar a mesma reserva devolve 409 com o estado atual, a menos que ela esteja em ERRO. Nesse caso o novo payload substitui o anterior e o processamento recomeça.
• Na Omie, cada registro leva um código de integração único. Se a Omie responder que o registro já existe, o orquestrador consulta e reaproveita, sem duplicar.

O payload é validado campo a campo antes de ser aceito.

• Obrigatórios: file, empresa, filial, cliente, dataCriacao e ao menos uma reserva em movimentos.
• Cada reserva exige codigoWooMobil, localizadorFrontOffice, dataRetirada, dataEntrega e valores.tarifa.
• Cada recebimento exige codigoWooMobil, valor e formaRecebimento. Cada pagamento exige codigoWooMobil e valor.
• Números em texto são convertidos. Campos extras são aceitos e guardados para auditoria.

Número de cartão, validade e documentos nunca são gravados completos.

• Número do cartão vira **** **** **** 1234 antes de qualquer gravação. A validade é descartada.
• Documento do condutor é reduzido aos 3 últimos dígitos.
• Na Omie, os dados do cartão entram apenas na observação do título: bandeira, 4 últimos dígitos, NSU, autorização e operadora.

O cliente é localizado na Omie pelo código MOB-{id do cliente na Mobility}.

• O orquestrador consulta geral/clientes pelo codigo_cliente_integracao MOB-{cliente}.
• Se não existir e o payload trouxer clienteDados, o cliente é cadastrado com UpsertCliente.
• Se não existir e não houver clienteDados, a reserva vai para ERRO. A carga inicial de clientes resolve esse caso.

Cada reserva gera uma OS na Omie com um item de serviço por locação.

• cCodIntOS = MOB-{chave da reserva}. Etapa inicial configurável (OMIE_ETAPA_OS, padrão 10).
• Item: serviço OMIE_COD_SERVICO_LOCACAO, quantidade 1, valor da tarifa, descrição com locadora, localizador, rota, classe e período.
• Os dados adicionais da nota levam o File, os localizadores e a reserva de origem, quando houver.
• Pode ser desligada com OMIE_CRIAR_OS=false. Nesse caso só os títulos financeiros são criados.

Cada recebimento vira um título por parcela, com vencimento pela forma de recebimento.

• Código: MOB-{file}-CRE-{CodigoWooMobil}-R{nº do recebimento}-P{nº da parcela}. Dois recebimentos da mesma reserva geram títulos distintos.
• Parcelas: o valor é dividido igualmente e a diferença de centavos fica na última parcela.
• Vencimento: dataVencimento do payload, se vier. Senão, a data de confirmação somada ao prazo da forma de recebimento. Cada parcela seguinte soma 30 dias.
• Os prazos por forma ficam na base Formas de recebimento e pagamento do Notion. Valores iniciais: FATURADO e CC 30 dias, CARTAO_CORPORATIVO e FATURADO + CARTAO 30 dias, BOLETO 7 dias, demais formas no mesmo dia. O intervalo entre parcelas vem de INTERVALO_PARCELAS_DIAS.
• Categoria OMIE_CATEG_RECEITA e conta corrente OMIE_CONTA_CORRENTE. A observação traz forma de recebimento, localizadores, crédito de reemissão e reembolso.

Cada pagamento vira um título, classificado como comissão, reembolso ou despesa.

• Código: MOB-{file}-CPA-{CodigoWooMobil}-{nº do pagamento}.
• Favorecido: a pessoa do pagamento (MOB-{pessoa}). Se for o próprio cliente, ou não vier, usa o cliente da venda.
• Categoria: OMIE_CATEG_COMISSAO quando pagamentoDeComissao é verdadeiro, OMIE_CATEG_REEMBOLSO quando é reembolso (RN09) e OMIE_CATEG_DESPESA nos demais casos.
• Vencimento: dataVencimento do payload ou a data de confirmação somada ao prazo da forma de pagamento (base Formas de recebimento e pagamento, padrão PRAZO_PAGAMENTO_DIAS).
• Comissão repassada no pagamento e comissão da reserva são tratadas como informações independentes, como orientou a Mobility.

Pagamento ao próprio cliente numa venda com ValorReembolso vira devolução.

• Um pagamento é reembolso quando não é comissão, o favorecido é o cliente e algum recebimento da reserva tem valorReembolso maior que zero.
• O título a pagar recebe a categoria de reembolso e a observação Reembolso ao cliente.
• Cancelamento continua fora do fluxo: a Mobility usa CancelarVenda e a regra (contas a pagar em categoria de abatimento) aguarda a especificação técnica.

Reservas com o mesmo File formam uma venda. A reserva vinculada aponta para a origem.

• Cada reserva gera sua própria OS e seus títulos. A consulta por File junta todas.
• O campo reservaVinculada guarda o localizador da reserva de origem e aparece na OS e nas consultas.
• O crédito de reemissão da reserva de origem é registrado na observação do título. O abatimento automático aguarda definição da Mobility.

Datas vão para a Omie em dd/mm/aaaa e valores com duas casas.

• Datas ISO do payload são convertidas para dd/mm/aaaa, formato exigido pela Omie.
• A Omie trabalha só em reais. Reservas em moeda estrangeira já chegam com a tarifa convertida pela Mobility, e o câmbio aplicado fica registrado.

Rentabilidade = total a receber menos total a pagar do File.

• Situação do item: Real quando o título está baixado na Omie (recebido, pago ou liquidado), Previsto nos demais casos.
• percentualRentabilidade = rentabilidade dividida pelo total a receber, vezes 100.
• Se a Omie falhar para algum título, o valor do orquestrador é usado e a falha aparece em avisos.

Cotação de venda do boletim de fechamento do Banco Central.

• Dias sem cotação (fins de semana e feriados) são pulados. A busca volta até 12 dias além do pedido.
• Cada cotação obtida fica gravada e é reaproveitada nas próximas consultas.
• O parâmetro tipo é mantido por compatibilidade com o WOOFFICE. A fonte é a mesma para todos os tipos.

Bloqueio por consumo da Omie coloca a reserva em RETRY, reprocessada a cada 10 minutos.

• Mensagens como MISUSE_API_PROCESS e falhas de rede são tratadas como temporárias.
• Cada chamada tenta uma segunda vez após 2,5 segundos. Persistindo, a reserva vai para RETRY com nova tentativa em 10 minutos.
• A espera (RETRY_MINUTOS) e o limite de tentativas (MAX_TENTATIVAS, padrão 12) ficam na base Configurações. Esgotado o limite, a reserva vai para ERRO e precisa de reprocessamento manual.
• Erros de dados (cadastro ausente, categoria inválida) vão direto para ERRO.

RECEBIDO → ENVIANDO → INTEGRADO, RETRY ou ERRO.

• RECEBIDO: payload aceito e gravado.
• ENVIANDO: chamadas à Omie em andamento.
• INTEGRADO: cliente, OS e todos os títulos criados.
• RETRY: bloqueio temporário da Omie, nova tentativa agendada.
• ERRO: problema de dados ou tentativas esgotadas. O campo erros explica cada etapa.

Eventos são validados, gravados e ligados ao File da Mobility.

• A Omie não oferece token no webhook. A URL é cadastrada sem parâmetros e a autenticidade vem do appKey enviado no corpo de cada evento.
• appKey igual ao OMIE_APP_KEY: evento aceito. appKey diferente: 403. Sem appKey (notificação de teste): 200 e ignorado.
• O appKey não é gravado no histórico do evento.
• A resposta sai antes de 7 segundos, limite da Omie. O repasse para a Mobility acontece em segundo plano.
• O File é descoberto pelos códigos de integração MOB- presentes no evento.

Callback assinado com HMAC-SHA256, com nova tentativa a cada 10 minutos.

• Tipos: venda.status (fim do processamento de uma reserva) e omie.evento (evento repassado da Omie).
• Headers: X-Iaxys-Event, X-Iaxys-Delivery e X-Iaxys-Signature com o HMAC-SHA256 do corpo usando MOBILITY_WEBHOOK_SECRET.
• Respostas fora de 2xx são reenviadas pelo cron, até 30 tentativas.
• A URL de destino fica na base Configurações do Notion (MOBILITY_WEBHOOK_URL). Sem ela, os eventos ficam disponíveis na rota de polling. O segredo do HMAC fica no .env.

Categorias, conta corrente, serviço, prazos e URL de callback ficam na base Configurações.

• Prioridade de cada chave: linha ativa com valor na base Configurações do Notion, depois a variável de ambiente de mesmo nome, depois o padrão do código.
• O .env guarda só segredos e infraestrutura: OMIE_APP_KEY, OMIE_APP_SECRET, MOBILITY_API_KEY, MOBILITY_WEBHOOK_SECRET, CRON_SECRET, NOTION_TOKEN, SESSION_SECRET e, se usado, DATABASE_URL.
• O orquestrador relê o Notion a cada 60 segundos. Alterações feitas pelo painel valem na hora.
• Se o Notion ficar indisponível, o último valor lido continua valendo.

Vendas, eventos, log e cotações são gravados em bases da página Mobility.

• Bases: Vendas recebidas, Eventos Omie, Log de integração, Cotações, Configurações, Formas de recebimento e pagamento e Usuários.
• Payload e resultado de cada reserva ficam em JSON na própria linha, para auditoria e reprocessamento.
• A API do Notion aceita cerca de 3 requisições por segundo. Para volume de produção alto, basta configurar DATABASE_URL e PERSISTENCIA=postgres, sem mudar o contrato.