# 🔗 INTEGRAÇÃO OMIE - LAUDO CONTROL ## 📋 VISÃO GERAL O sistema Laudo Control integra com o **Omie ERP** para enviar faturas automaticamente como: - **Contas a Pagar** (Faturas de Médicos/Digitadores) - **Contas a Receber** (Faturas de Unidades) --- ## 🔑 CREDENCIAIS ```php OMIE_APP_KEY = '3927131072865' OMIE_APP_SECRET = 'f1d03644500f2ee22bb9e3fce8b83660' ``` ⚠️ **Importante**: Estas credenciais devem ser mantidas em segurança! --- ## 📊 ENDPOINTS UTILIZADOS ### 1. **Listar Clientes** ``` POST https://app.omie.com.br/api/v1/geral/clientes/ Call: ListarClientes ``` ### 2. **Contas a Pagar** (Médicos/Digitadores) ``` POST https://app.omie.com.br/api/v1/financas/contapagar/ Call: IncluirContaPagar ``` ### 3. **Contas a Receber** (Unidades) ``` POST https://app.omie.com.br/api/v1/financas/contareceber/ Call: IncluirContaReceber ``` --- ## 🏗️ ESTRUTURA DE ARQUIVOS ``` integracaoOmie/ ├── EnviarOmie.php # Envia faturas médico/digitador (Contas a Pagar) ├── enviarOmieMedimg.php # Envia faturas MedImagem específicas ├── EnviarFaturaUnidadeOmie.php # ✅ NOVO - Envia faturas unidade (Contas a Receber) └── ConciliarDepartamentosUnid.php # Concilia departamentos ``` --- ## 💳 INTEGRAÇÃO DE FATURAS DE UNIDADE ### **Arquivo**: `EnviarFaturaUnidadeOmie.php` ### **Fluxo de Envio:** ``` 1. Buscar fatura de unidade no banco ↓ 2. Validar CNPJ da unidade ↓ 3. Buscar unidade no Omie (ListarClientes) ↓ 4. Preparar JSON de Conta a Receber ↓ 5. Enviar para Omie (IncluirContaReceber) ↓ 6. Atualizar status da fatura para 'Enviada' ↓ 7. Salvar código Omie (fat_lanc_omie) ``` ### **JSON Enviado:** ```json { "call": "IncluirContaReceber", "app_key": "3927131072865", "app_secret": "f1d03644500f2ee22bb9e3fce8b83660", "param": [{ "codigo_lancamento_integracao": "FAT-UNI-123", "codigo_cliente_fornecedor": 4214850, "data_vencimento": "26/12/2025", "valor_documento": 16577.50, "codigo_categoria": "1.01.02", "data_previsao": "26/12/2025", "numero_documento": "FAT-UNI-123", "observacao": "Fatura de Unidade #123 - MEDIMAGEM - Ref: Novembro/2025", "data_emissao": "02/12/2025", "importado_api": "S" }] } ``` ### **Resposta do Omie:** ```json { "codigo_lancamento_omie": 987654321, "codigo_lancamento_integracao": "FAT-UNI-123", "codigo_status": "0", "descricao_status": "Conta a receber incluída com sucesso!" } ``` --- ## 🗄️ BANCO DE DADOS ### **Tabela: faturas_unidade** ```sql ALTER TABLE faturas_unidade ADD COLUMN fat_lanc_omie INTEGER; ALTER TABLE faturas_unidade DROP CONSTRAINT IF EXISTS faturas_unidade_fat_status_check; ALTER TABLE faturas_unidade ADD CONSTRAINT faturas_unidade_fat_status_check CHECK (fat_status IN ('Gerada', 'Enviada', 'Paga', 'Cancelada')); ``` ### **Tabela: response_omie** ```sql ALTER TABLE response_omie ADD COLUMN res_tipo VARCHAR(20) DEFAULT 'medico'; -- res_tipo pode ser: 'medico', 'digitador', 'unidade' ``` ### **Executar SQL:** ```bash psql -U postgres -d laudocontrol -f sql/adicionar_coluna_omie_faturas_unidade.sql ``` --- ## 🎯 COMO USAR ### **1. Via Interface Web:** 1. Acesse **Faturas > Faturas Unidades** 2. Localize a fatura com status **"Gerada"** 3. Clique no botão laranja **"Enviar para Omie"** (ícone 📤) 4. Aguarde o processamento 5. Verifique o status: **"Enviada"** 6. O código Omie será salvo automaticamente ### **2. Via URL Direta:** ``` http://seu-servidor.com/integracaoOmie/EnviarFaturaUnidadeOmie.php?fat_id=123 ``` ### **3. Programaticamente (PHP):** ```php // Redirecionar para envio header('Location: integracaoOmie/EnviarFaturaUnidadeOmie.php?fat_id=' . $fat_id); ``` --- ## 🔄 DIFERENÇAS ENTRE INTEGRAÇÕES | Aspecto | Faturas Médico/Digitador | Faturas Unidade | |---------|--------------------------|-----------------| | **Tipo Omie** | Conta a Pagar | Conta a Receber | | **Cliente** | Médico/Digitador (CPF/CNPJ) | Unidade (CNPJ) | | **Código Integração** | `fat_id` | `FAT-UNI-{fat_id}` | | **Rateio** | ✅ Sim (por departamento) | ❌ Não | | **Categoria** | Variável | 1.01.02 (fixo) | | **Arquivo** | `EnviarOmie.php` | `EnviarFaturaUnidadeOmie.php` | --- ## 📝 CAMPOS OBRIGATÓRIOS (OMIE) ### **Conta a Receber:** ```php [ 'codigo_lancamento_integracao' => 'FAT-UNI-123', // ✅ Obrigatório 'codigo_cliente_fornecedor' => 4214850, // ✅ Obrigatório 'data_vencimento' => '26/12/2025', // ✅ Obrigatório 'valor_documento' => 16577.50, // ✅ Obrigatório 'codigo_categoria' => '1.01.02', // ✅ Obrigatório 'data_previsao' => '26/12/2025', // ⚠️ Recomendado 'numero_documento' => 'FAT-UNI-123', // ⚠️ Recomendado 'observacao' => 'Descrição...', // ⚪ Opcional 'data_emissao' => '02/12/2025' // ⚪ Opcional ] ``` --- ## ⚙️ CONFIGURAÇÕES ### **Categoria Padrão:** ```php 'codigo_categoria' => '1.01.02' ``` **Para alterar**: Edite linha 163 em `EnviarFaturaUnidadeOmie.php` ### **Conta Corrente:** Se quiser especificar conta corrente: ```php 'id_conta_corrente' => 4243124 ``` Adicione na linha 164 do arquivo. --- ## 🐛 TRATAMENTO DE ERROS ### **Erros Comuns:** | Erro | Causa | Solução | |------|-------|---------| | Cliente não encontrado | CNPJ não cadastrado no Omie | Cadastrar unidade no Omie primeiro | | HTTP 401 | Credenciais inválidas | Verificar APP_KEY e APP_SECRET | | HTTP 500 | Erro no servidor Omie | Tentar novamente mais tarde | | Categoria inválida | Código não existe no Omie | Usar categoria válida (1.01.01, 1.01.02, etc) | | Valor zerado | Documento com valor 0 | Verificar cálculo da fatura | ### **Log de Erros:** Todas as respostas da API são salvas em `response_omie`: ```sql SELECT res_fat_cod, res_http_code, res_status, res_resposta, res_data, res_tipo FROM response_omie WHERE res_tipo = 'unidade' ORDER BY res_data DESC; ``` --- ## 🎨 INTERFACE VISUAL ### **Botão na Tabela:** ```html send ``` **Aparece apenas se**: `fat_status === 'Gerada'` ### **Página de Envio:** - ✅ Informações da fatura - ✅ Dados da unidade - ✅ JSON enviado (debug) - ✅ Mensagens de sucesso/erro - ✅ Botão voltar --- ## 🧪 TESTE DE INTEGRAÇÃO ### **Passo a Passo:** 1. **Criar fatura de unidade no sistema** ``` CadastrarFaturaUnidade.php → Nova Fatura ``` 2. **Verificar se unidade existe no Omie** ```sql SELECT uni_nome, uni_cnpj, uni_omie FROM unidades WHERE uni_cod = 1; ``` 3. **Enviar para Omie** ``` Clicar botão "Enviar para Omie" ``` 4. **Verificar no Omie** ``` Omie → Financeiro → Contas a Receber → Buscar por "FAT-UNI-123" ``` 5. **Verificar status no sistema** ```sql SELECT fat_id, fat_status, fat_lanc_omie FROM faturas_unidade WHERE fat_id = 123; ``` --- ## 📈 PRÓXIMAS MELHORIAS (OPCIONAL) ### **1. Webhook de Pagamento:** Receber notificação quando título for pago no Omie ### **2. Sincronização de Status:** Buscar status atualizado das faturas periodicamente ### **3. Envio em Lote:** Usar `IncluirContaReceberPorLote` para múltiplas faturas ### **4. Geração de Boleto:** Adicionar informações de boleto bancário ### **5. Distribuição por Departamento:** Implementar rateio também em faturas de unidade --- ## 📞 SUPORTE OMIE - **Portal do Desenvolvedor**: https://developer.omie.com.br/ - **Documentação API**: https://app.omie.com.br/api/v1/financas/contareceber/ - **Suporte**: suporte@omie.com.br --- ## ✅ CHECKLIST DE IMPLEMENTAÇÃO - [x] Criar arquivo `EnviarFaturaUnidadeOmie.php` - [x] Adicionar coluna `fat_lanc_omie` em `faturas_unidade` - [x] Adicionar status `'Enviada'` em `faturas_unidade` - [x] Adicionar botão na interface `CadastrarFaturaUnidade.php` - [x] Implementar tooltips nos botões - [x] Salvar respostas da API em `response_omie` - [x] Criar documentação completa - [ ] Executar SQL `adicionar_coluna_omie_faturas_unidade.sql` - [ ] Testar envio de fatura - [ ] Validar no Omie - [ ] Configurar categoria correta se necessário --- ## 🎉 STATUS **✅ Implementação Completa** **⏳ Aguardando Execução do SQL e Testes** --- **Versão**: 1.0 **Data**: Dezembro 2024 **Autor**: Sistema Laudo Control