Grid Control

============================================================================= search_warranties_templates - Lista templates de garantia com filtros e paginação ============================================================================= Templates de garantia definem os termos de garantia aplicados a manutenções ou equipamentos: duração da cobertura, valor, extensão e empresas/tipos de manutenção vinculados. ── FILTROS ($where: WarrantiesTemplatesWhereInput) ────────────────────────── nameContains: String → busca parcial no nome nameEq: String → busca exata no nome descriptionContains: String → busca na descrição coverageDurationDaysEq: Int → duração exata em dias coverageDurationDaysGte: Int → duração mínima em dias coverageDurationDaysLte: Int → duração máxima em dias hasExtendedCoverage: Boolean → tem cobertura estendida doesNotHaveExtendedCoverage: Boolean → não tem cobertura estendida maintenanceTypeIds: [ID] → filtrar por tipo de manutenção companyIds: [ID!] → filtrar por empresa type: String → "maintenances" ou "equipments" archived: Boolean → true=arquivados, false=ativos EXEMPLO DE USO: "Quais templates de garantia existem?" → sem where (retorna todos ativos) "Garantias para equipamentos com cobertura > 90 dias" → where: { type: "equipments", coverageDurationDaysGte: 90 } "Garantias do fornecedor X" → where: { companyIds: ["id-da-empresa"] } COMBINA BEM COM: search_equipments (equipamentos com garantia), search_maintenances (filtrar por warrantyStatusIn) =============================================================================

search_warranties_templates

============================================================================= search_deadline_violation_reasons - Lista motivos de violação de SLA cadastrados ============================================================================= Motivos de violação categorizam por que um prazo de contrato de SLA foi descumprido (ex: "Aguardando peça", "Acesso negado", "Equipe indisponível"). Use para entender as razões disponíveis e correlacionar com violações reais. ── FILTROS ($where: DeadlineViolationReasonWhereInput) ─────────────────────── nameContains: String → busca parcial no nome descriptionContains: String → busca na descrição deadlineContractIds: [ID!] → motivos vinculados a contratos de SLA específicos archived: Boolean → true=arquivados, false=ativos EXEMPLO DE USO: "Quais motivos de violação de SLA temos cadastrados?" → where: { archived: false } (sem where retorna todos, inclusive arquivados) "Motivos do contrato de SLA X" → where: { deadlineContractIds: ["id-do-contrato"], archived: false } COMBINA BEM COM: dashboard (includeSlaSummary) (% de cumprimento), dashboard (includeSlaEvolution) (violações por dia) =============================================================================

search_deadline_violation_reasons

============================================================================= search_occurrences - Lista ocorrências de recorrências com filtros e paginação ============================================================================= Ocorrências são as execuções individuais geradas por uma recorrência. Cada ocorrência tem uma data programada e pode ou não ter gerado uma manutenção. Use após search_recurrences para ver o histórico de execuções. ── FILTROS ($where: OccurrenceWhereInput!) ────────────────────────────────── recurrenceId_in: [ID!] → filtrar por recorrência (RECOMENDADO) ⚠️ IMPORTANTE: Sempre filtre por recurrenceId_in para evitar retornar ocorrências de todas as recorrências da conta. EXEMPLO DE USO: "Quais ocorrências da recorrência abc123?" → where: { recurrenceId_in: ["abc123"] } COMBINA BEM COM: search_recurrences (listar recorrências e obter IDs), get_maintenance_details (ver detalhes da OS gerada por uma ocorrência) =============================================================================

search_occurrences

============================================================================= search_maintenances - Lista manutenções com filtros e paginação ============================================================================= Retorna registros individuais. Para números agregados — volume por status, totais do período, quebra por tipo ou segmento, backlog, SLA — a tool `dashboard` responde em uma chamada só, ligando os toggles correspondentes (includeMaintenancesSummary, includeVolumeSummary, includeMaintenancesByType, includeSlaSummary). Retorna lista paginada de manutenções (OS de fornecedores). ── PAGINAÇÃO ────────────────────────────────────────────────────────────────── $limit (Int, default 10): Registros por página $offset (Int, default 0): Offset ── FILTROS ($where: MaintenanceWhereInput) ──────────────────────────────────── numberContains: String → busca parcial no número da OS statusIn: [MaintenanceStatus] → new | pending | scheduled | inProgress | done | canceled | reported | requested | onNegotiation "OS ativa"/"não concluída" = todos os status exceto done e canceled. Esse status É a definição de "equipamento/peça indisponível" e "disponibilidade do parque" - um ativo está indisponível se tiver QUALQUER OS vinculada fora de done/canceled, de QUALQUER tipo. Não use maintenanceTypeIdIn (corretiva/isRepair) pra responder sobre disponibilidade - isso restringe pra um subconjunto e diverge do que os cards de insight do Parque de Ativos calculam. Só filtre por tipo se o usuário pedir corretiva/preventiva explicitamente. maintenanceTypeIdIn: [ID] → filtra por tipo de manutenção. Pra saber se um tipo é corretivo, confira isRepair em search_maintenance_types companyId_in: [ID] → filtra por empresa fornecedora archived: Boolean → true=arquivadas, false=ativas openedAt: DateRangeInput → { from, to } — intervalo de abertura (ISO 8601 com horário: "2026-04-17T00:00:00.000Z" / "2026-04-17T23:59:59.999Z") scheduledAt: DateRangeInput → intervalo de agendamento (ISO 8601 com horário: "2026-04-17T00:00:00.000Z" / "2026-04-17T23:59:59.999Z") closedAt: DateRangeInput → intervalo de encerramento (ISO 8601 com horário: "2026-04-17T00:00:00.000Z" / "2026-04-17T23:59:59.999Z") ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeFormAnswers (Boolean, default false): Inclui respostas de formulários. Use quando o usuário perguntar sobre checklists, formulários ou respostas preenchidas. $includeContract (Boolean, default false): Inclui contrato vinculado a cada OS. Use quando o usuário perguntar sobre contratos das OS ou cobertura contratual da lista. $includeDeadlineContract (Boolean, default false): Inclui SLA aplicado a cada OS. Use quando o usuário perguntar sobre SLAs, prazos ou risco de violação na listagem. $includeEquipments (Boolean, default false): Inclui os equipamentos vinculados a cada OS, com o campo real de criticidade (low | medium | high | critical) - "ativo crítico" refere-se a esse campo, não a atraso de SLA nem a idade da OS. Use quando o usuário perguntar quais equipamentos estão em manutenção, ou quiser destacar ativos com criticidade alta/crítica e OS ativa. $includeSectorsAndEnvironments (Boolean, default false): Inclui os setores e ambientes vinculados a cada OS. Use quando o usuário quiser agrupar ou filtrar por setor/ambiente na listagem. A maioria das OS não tem essa marcação preenchida - liste como vazio, não invente valor. ── DURAÇÃO ──────────────────────────────────────────────────────────────────── durationInMinutes: tempo REALIZADO, do início da primeira visita até o encerramento da OS. Vem null enquanto a OS não fechou ou não teve visita iniciada, e a soma da lista cobre só as OS com os dois marcos. É duração executada, não planejada: duração prevista não existe por OS - o padrão fica no tipo de manutenção. =============================================================================

search_maintenances

============================================================================= search_quotations - Lista orçamentos com filtros e paginação ============================================================================= Retorna orçamentos individuais. Para números agregados — contagem e valor por status, taxa e tempo de aprovação, maiores aprovadas — a tool `dashboard` responde em uma chamada só, ligando includeQuotationsByStatus, includeQuotationsSummary e includeQuotationsApprovedTotalByUser. Orçamentos são propostas de serviço enviadas por fornecedores para manutenções. ── FILTROS ($where: QuotationWhereInput) ───────────────────────────────────── status_in: [QuotationStatus] → pending | approved | refused | expired | canceled companyId_in: [ID] → filtra por empresa maintenanceId_in: [ID] → filtra por manutenção identifier_contains: String → busca no identificador archived: Boolean ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeDiscount (Boolean, default false): Inclui resumo do desconto aplicado. Use quando o usuário perguntar sobre descontos na listagem. $includeLabels (Boolean, default false): Inclui labels/tags de cada orçamento. Use quando o usuário perguntar sobre categorização ou filtros por label. =============================================================================

search_quotations

============================================================================= search_payments - Lista pagamentos com filtros e paginação ============================================================================= Retorna pagamentos individuais. Para visão financeira agregada, a tool `dashboard` com includeQuotationsSummary traz os valores em R$. Pagamentos agrupam manutenções ou orçamentos para faturamento ao fornecedor. ── FILTROS ($where: PaymentWhereInput) ─────────────────────────────────────── statusIn: [PaymentStatusEnum] → pending | approved | rejected | paid companyIdIn: [ID] → filtra por empresa numberContains: String → busca no número archived: Boolean ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeTreatment (Boolean, default false): Inclui dados de tratamento (quem tratou e quando). Use quando o usuário perguntar sobre processamento/aprovação dos pagamentos na lista. =============================================================================

search_payments

============================================================================= search_pendencies - Lista pendências com filtros e paginação por cursor ============================================================================= Pendências são itens de acompanhamento vinculados a manutenções. ── PAGINAÇÃO (cursor-based) ────────────────────────────────────────────────── $take (Int, default 10): Registros por página $after (String): Cursor para próxima página ── FILTROS ($where: PendenciesWhereInput) ──────────────────────────────────── statusIn: [PendencyStatus] → done | opened titleOrDescriptionContains: String → busca por texto companyIds: [ID] → filtra por empresa maintenanceIds: [ID] → filtra por manutenção ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeUpdatedBy (Boolean, default false): Inclui quem atualizou + data de conclusão. Use quando o usuário perguntar sobre auditoria, conclusão ou última modificação na lista. =============================================================================

search_pendencies

============================================================================= search_parts - Lista peças com filtros e paginação ============================================================================= Peças são itens que podem estar instalados em equipamentos (ex.: filtro de ar, correia). Diferente de equipamento, uma peça não se vincula direto a uma OS - a contagem de manutenções abaixo já soma todas as unidades da peça instaladas em qualquer equipamento. ── FILTROS ($where: PartWhereInput) ────────────────────────────────────────── nameContains: String → busca por nome codeContains: String → busca por código partTypeId: ID → filtra por tipo de peça equipmentTypeIds: [ID!] → filtra por tipos de equipamento compatíveis criticalityIn: [CriticalityLevel!] → filtra por criticidade (low | medium | high | critical) archived: Boolean → true=arquivadas, false=ativas ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeCriticality (Boolean, default false): Inclui a criticidade da peça e sua justificativa. Use quando o usuário perguntar se a peça é crítica, ou quiser priorizar por criticidade. $includeUnitsCount (Boolean, default false): Inclui a quantidade de unidades da peça. Use quando o usuário perguntar quantas unidades existem dessa peça. $includeMaintenancesCount (Boolean, default false): Inclui contagem de manutenções abertas e concluídas somando todas as unidades instaladas da peça. Use quando o usuário perguntar sobre OS, manutenção ativa ou histórico de serviço da peça. =============================================================================

search_parts

============================================================================= search_recurrences - Lista recorrências (manutenções programadas) com filtros ============================================================================= Recorrências são manutenções agendadas com periodicidade (diária, semanal, mensal). Cada recorrência gera ocorrências automaticamente. Use para saber quais manutenções estão programadas para se repetir. ── FILTROS ($where: RecurrenceWhereInput) ─────────────────────────────────── archived: Boolean → true=arquivadas, false=ativas segmentId_in: [ID!] → filtrar por segmento locationId_in: [ID!] → filtrar por local companyId_in: [ID] → filtrar por empresa fornecedora equipmentId_in: [ID!] → filtrar por equipamento maintenanceTypeId_in: [ID!] → filtrar por tipo de manutenção interval_in: [IntervalInput!] → filtrar por periodicidade (daily | weekly | monthly) message_contains: String → busca na descrição da recorrência EXEMPLO DE USO: "Quais recorrências estão ativas?" → where: { archived: false } "Recorrências semanais do local X" → where: { locationId_in: ["id-do-local"], interval_in: [weekly] } "Manutenções recorrentes do fornecedor Y" → where: { companyId_in: ["id-da-empresa"] } COMBINA BEM COM: search_occurrences (ver execuções de uma recorrência), search_maintenances (manutenções geradas por recorrência) ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeOccurrences (Boolean, default false): Inclui as próximas ocorrências geradas (com manutenção). Use quando o usuário perguntar sobre próximas execuções, agendas futuras ou histórico de gerações. $includeContext (Boolean, default false): Inclui equipamentos, setores e ambientes vinculados. Use quando o usuário perguntar sobre escopo da recorrência (onde/quais ativos atende). $includeLogs (Boolean, default false): Inclui auditoria completa de alterações na recorrência (quem alterou, quando, IP, origem e o snapshot do estado a cada mudança). Use quando o usuário perguntar sobre histórico de mudanças, quem alterou, o que mudou ou auditoria da recorrência. =============================================================================

search_recurrences

============================================================================= search_segments - Lista segmentos de negócio com filtros e paginação ============================================================================= Segmentos agrupam tipos de manutenção e definem fluxos de trabalho. ── FILTROS ($where: SegmentWhereInput) ─────────────────────────────────────── name_contains: String → busca por nome archived: Boolean ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeForms (Boolean, default false): Inclui formulários vinculados ao segmento por tipo de manutenção. Use quando o usuário perguntar sobre formulários obrigatórios, checklists por segmento ou vistorias. =============================================================================

search_segments

============================================================================= search_services - Lista serviços/mão de obra com filtros e paginação ============================================================================= Serviços são tipos de trabalho que podem ser cobrados em orçamentos. ── FILTROS ($where: ServiceWhereInput) ─────────────────────────────────────── nameContains: String → busca por nome companyIdIn: [ID] → filtra por empresa archived: Boolean ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeCompanies (Boolean, default false): Inclui fornecedores que oferecem o serviço (com preço acordado). Use quando o usuário perguntar sobre quais empresas prestam o serviço ou comparar preços. $includePricing (Boolean, default false): Inclui preço base e unidade de medida. Use quando o usuário perguntar sobre valor, preço ou unidade do serviço. =============================================================================

search_services

============================================================================= search_requesters - Lista solicitantes com filtros e paginação ============================================================================= Solicitantes são os usuários que abrem ordens de serviço (OS). Diferente de search_users (que lista todos os usuários do sistema), esta query retorna apenas os solicitantes. Use para identificar quem abre OS e associar a manutenções. ── FILTROS ($where: UserWhereInput) ───────────────────────────────────────── name_contains: String → busca parcial no nome email_contains: String → busca parcial no email name_or_email_contains: String → busca no nome ou email archived: Boolean → true=arquivados, false=ativos EXEMPLO DE USO: "Quais são os solicitantes?" → sem where (retorna todos ativos) "Solicitante com nome 'João'" → where: { name_contains: "João" } COMBINA BEM COM: search_maintenances (filtrar por requesterId_in), get_maintenance_details (ver o solicitante de uma OS) ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeGuest (Boolean, default false): Inclui os dados de convidado do solicitante (documento e telefone). Use quando o usuário perguntar o CPF/CNPJ ou telefone do solicitante. =============================================================================

search_requesters

============================================================================= search_expenses - Lista tipos de despesa com filtros e paginação ============================================================================= Despesas são categorias de custo associadas a manutenções (ex: mão de obra, material, deslocamento). Definem se exigem comprovante e um valor máximo. Use para entender a estrutura de custos configurada. ── FILTROS ($where: ExpenseWhereInput) ────────────────────────────────────── nameContains: String → busca parcial no nome nameEquals: String → busca exata no nome descriptionContains: String → busca na descrição archived: Boolean → true=arquivadas, false=ativas EXEMPLO DE USO: "Quais tipos de despesa existem?" → sem where (retorna todos ativos) "Despesas que exigem comprovante" → sem filtro direto, verificar o campo receiptRequired nos resultados COMBINA BEM COM: get_maintenance_details (ver despesas de uma OS), dashboard (includeQuotationsSummary) (visão financeira) =============================================================================

search_expenses

============================================================================= search_equipment_types - Lista tipos de equipamento com filtros e paginação ============================================================================= Tipos de equipamento categorizam os ativos físicos (ex: ar-condicionado, elevador, gerador). Cada tipo pertence a um segmento. Use esta query para descobrir IDs de tipos e usá-los como filtro em search_equipments (equipmentTypeId_in). ── FILTROS ($where: EquipmentTypeWhereInput) ──────────────────────────────── name_contains: String → busca parcial no nome segmentId_in: [ID!] → filtrar por segmento archived: Boolean → true=arquivados, false=ativos EXEMPLO DE USO: "Quais tipos de equipamento existem?" → sem where (retorna todos ativos) "Tipos de equipamento do segmento X" → where: { segmentId_in: ["id-do-segmento"] } COMBINA BEM COM: search_equipments (filtrar equipamentos por tipo), dashboard (includeEquipmentsSummary) (estatísticas por equipamento) ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeForms (Boolean, default false): Inclui formulários vinculados ao tipo de equipamento. Use quando o usuário perguntar sobre formulários, checklists ou vistorias exigidas para o ativo. $includeCustomFields (Boolean, default false): Inclui campos customizados do tipo. Use quando o usuário perguntar sobre atributos extras ou metadados configurados para o tipo. =============================================================================

search_equipment_types

============================================================================= search_maintenance_types - Lista tipos de manutenção ============================================================================= Tipos de manutenção categorizam as OS (ex: corretiva, preventiva, preditiva). Use esta query para obter IDs de tipos e usá-los como filtro em outras queries (typeId_in em maintenances, dashboard, etc.). ── FILTROS ($where: MaintenanceTypeWhereInput) ──────────────────────────────── name_contains: String → busca por nome type_in: [MaintenanceTypeEnum]→ preventiveMaintenance | correctiveMaintenance | customMaintenance isRepair: Boolean → true = é corretiva de verdade. Independente de type_in/nome - um customMaintenance pode ter isRepair: true (e vice-versa). Use este campo pra saber se um tipo é corretivo, não o nome nem o type_in. archived: Boolean → true=arquivados, false=ativos EXEMPLO DE USO: "Quais tipos de manutenção existem?" → sem where (retorna todos ativos) "Tipos corretivos" / "essa OS é corretiva?" → where: { isRepair: true } COMBINA BEM COM: dashboard (includeMaintenancesByType) (volume por tipo), search_maintenances (filtrar por maintenanceTypeIdIn) ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeForms (Boolean, default false): Inclui formulários do tipo (rating, ticket e por segmento). Use quando o usuário perguntar sobre formulários, checklists ou vistorias por segmento. $includeAppSettings (Boolean, default false): Inclui configurações mobile/app (validação de raio, assinatura, etc.). Use quando o usuário perguntar sobre app, validação de localização, assinatura ou disponibilidade mobile. =============================================================================

search_maintenance_types

============================================================================= search_pendency_types - Lista tipos de pendência com filtros e paginação ============================================================================= Tipos de pendência categorizam as pendências registradas em manutenções (ex: documentação faltante, peça em espera, aprovação pendente). Use para descobrir IDs de tipos e dar contexto às pendências listadas via search_pendencies. ── FILTROS ($where: PendencyTypeWhereInput) ───────────────────────────────── nameContains: String → busca parcial no nome nameEq: String → busca exata no nome descriptionContains: String → busca na descrição archived: Boolean → true=arquivados, false=ativos EXEMPLO DE USO: "Quais tipos de pendência existem?" → sem where (retorna todos ativos) "Tipos de pendência com 'aprovação'" → where: { nameContains: "aprovação" } COMBINA BEM COM: search_pendencies (listar pendências por tipo), get_maintenance_details (ver pendências de uma OS) =============================================================================

search_pendency_types

============================================================================= search_problems - Lista tipos de problema com filtros e paginação ============================================================================= Problemas categorizam o motivo das manutenções. ── FILTROS ($where: ProblemWhereInput) ─────────────────────────────────────── name_contains: String → busca por nome segmentId_in: [ID] → filtra por segmento maintenanceTypeId_in: [ID]→ filtra por tipo de manutenção archived: Boolean =============================================================================

search_problems

============================================================================= search_product_types - Lista tipos de produto com filtros e paginação ============================================================================= Tipos de produto categorizam os produtos cadastrados no sistema (ex: peças, materiais elétricos, materiais hidráulicos). Use esta query para descobrir IDs de tipos e usá-los como contexto em perguntas sobre produtos. ── FILTROS ($where: ProductTypeWhereInput) ────────────────────────────────── nameContains: String → busca parcial no nome do tipo nameEq: String → busca exata no nome archived: Boolean → true=arquivados, false=ativos EXEMPLO DE USO: "Quais tipos de produto existem?" → sem where (retorna todos ativos) "Tipos de produto com nome 'elétrico'" → where: { nameContains: "elétrico" } COMBINA BEM COM: dashboard (includeQuotationsTopProductsServices) (produtos mais cotados), dashboard (includeQuotationsSummary) (produto vs serviço) =============================================================================

search_product_types

============================================================================= search_users - Lista usuários do sistema com filtros e paginação ============================================================================= ── FILTROS ($where: UserWhereInput) ────────────────────────────────────────── name_contains: String → busca por nome email_contains: String → busca por email role_in: [UserRole] → default | admin | owner archived: Boolean ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeGroups (Boolean, default false): Inclui os grupos de cada usuário. Use quando o usuário perguntar a quais grupos um usuário pertence. =============================================================================

search_users

============================================================================= create_import — Cria um novo registro de importação a partir de um arquivo já enviado ao S3 ============================================================================= 🎯 SEGUNDA ETAPA do fluxo de importação. Registra a importação no sistema após o arquivo ter sido enviado com sucesso ao S3. Requer permissão: imports-create QUANDO USAR: após fazer upload do arquivo com generate_upload_credential, chame esta mutation para criar o registro de importação. Em seguida, use start_import_validation para validar a planilha antes de importar. ── PARÂMETRO $input: CreateImportInput! ───────────────────────────────────── type: ImportType! — tipo da importação (ex: equipments, maintenances, etc.) fileKey: String! — chave do arquivo no S3 (retornada por generate_upload_credential) bucketName: String! — nome do bucket S3 (retornado por generate_upload_credential) O QUE RETORNA: objeto Import com status inicial e metadados do arquivo. Após criar, inicie a validação com start_import_validation. FLUXO TÍPICO: 1. generate_upload_credential → upload → obtém fileKey e bucketName 2. create_import com fileKey e bucketName → obtém id e updatedAt 3. start_import_validation com o id retornado =============================================================================

create_import

============================================================================= get_company_details - Retorna uma empresa fornecedora pelo ID com detalhes completos ============================================================================= ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeFieldAccount (Boolean, default false): Inclui dados da conta Field vinculada (telefone, timezone, tipo de conta e gestor responsável). Use quando o usuário perguntar sobre a conta Field/integração ou o gestor. =============================================================================

get_company_details

============================================================================= get_maintenance_details - Retorna uma manutenção pelo ID com detalhes completos ============================================================================= ── DURAÇÃO ──────────────────────────────────────────────────────────────────── durationInMinutes: tempo REALIZADO, do início da primeira visita até o encerramento da OS. Vem null enquanto a OS não fechou ou não teve visita iniciada. É duração executada, não planejada: prevista não existe por OS - o padrão fica no tipo de manutenção. ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeFormAnswers (Boolean, default false): Inclui respostas de formulários. Use quando o usuário perguntar sobre checklists, formulários ou respostas preenchidas. $includeContract (Boolean, default false): Inclui contrato vinculado à OS. Use quando o usuário perguntar sobre contrato, acordo ou cobertura contratual da manutenção. $includeDeadlineContract (Boolean, default false): Inclui SLA aplicado (prazos de resposta/solução). Use quando o usuário perguntar sobre SLA, prazos, deadlines ou risco de violação. $includeAttachments (Boolean, default false): Inclui anexos da manutenção. Use quando o usuário perguntar sobre fotos, documentos, evidências ou anexos da OS. $includeQuotations (Boolean, default false): Inclui orçamentos vinculados. Use quando o usuário perguntar sobre orçamentos, propostas ou valores cotados na OS. $includeProductsServices (Boolean, default false): Inclui produtos e serviços lançados. Use quando o usuário perguntar sobre peças, serviços executados ou composição do custo. $includeWarranties (Boolean, default false): Inclui garantias da manutenção. Use quando o usuário perguntar sobre garantia, cobertura ou prazo de garantia. $includeLogs (Boolean, default false): Inclui auditoria completa da OS — o snapshot do estado a cada mudança (status, responsável, empresa, prazo, etc.) com quem alterou, quando, IP e origem. Use quando o usuário perguntar sobre histórico, quem alterou, o que mudou ou auditoria da OS. $includeTicket (Boolean, default false): Inclui ticket de origem. Use quando o usuário perguntar sobre origem, solicitação inicial ou ticket que gerou a OS. $includeTasks (Boolean, default false): Inclui as visitas/atendimentos de campo da OS. Cada visita traz o técnico (employee), status, agenda, a timeline real de campo (recebeu → saiu pra rota → chegou → iniciou → concluiu), GPS (latitude/longitude) e avaliação. Use quando o usuário perguntar qual técnico foi atender, quantas visitas, horários de chegada/conclusão, deslocamento, localização do atendimento ou avaliação da visita. $includeEquipmentCustomFields (Boolean, default false): Inclui os campos customizados preenchidos de cada equipamento da OS (definidos no tipo de equipamento). Cada campo traz name/value/type. Use quando os critérios mencionarem atributos/campos do equipamento (ex.: "o campo X do equipamento está preenchido?"). Atenção: value é o estado ATUAL do equipamento, não um congelado da OS. $includePendencyEvents (Boolean, default false): Inclui as RESPOSTAS registradas nas pendências da OS (apenas eventos do tipo reply — log e note são descartados), com autor, data e o metadado dos anexos (title/type, sem URL). Use quando os critérios mencionarem pendência, tratativa, retorno, correção ou o que foi respondido. Atenção: é o que o técnico DECLARA ter feito, não prova do estado da OS. $includeEquipmentTypeForms (Boolean, default false): Inclui os formulários vinculados ao tipo de cada equipamento da OS (via equipmentTypeForms). Cada vínculo traz o form (id/name) e os flags requiredComplete/requiredReport, além do maintenanceType quando o formulário for específico de um tipo de manutenção. Use quando o usuário perguntar quais formulários/checklists devem ser preenchidos para os equipamentos da OS. Atenção: são os formulários ESPERADOS pelo tipo de equipamento, não as respostas preenchidas (para respostas use $includeFormAnswers). $includeLocationContext (Boolean, default false): Inclui setores e ambientes da localização da OS. Use quando o usuário perguntar sobre onde exatamente é o atendimento (setor/ambiente). =============================================================================

get_maintenance_details

============================================================================= get_pendency_details - Retorna uma pendência pelo ID com detalhes completos ============================================================================= ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeEventContent (Boolean, default false): Expande o conteúdo dos eventos (notas, respostas com anexos, e logs de auditoria com o de/para de cada campo alterado — coluna, oldValue e newValue). Os eventos básicos sempre são retornados; este toggle adiciona o campo `content` aninhado. Use quando o usuário perguntar sobre histórico detalhado, conversa, anexos em respostas ou auditoria com diffs. $includeReaders (Boolean, default false): Inclui leitores/seguidores da pendência. Use quando o usuário perguntar quem acompanha ou tem acesso à pendência. $includeUpdatedBy (Boolean, default false): Inclui quem fez a última atualização. Use quando o usuário perguntar sobre auditoria, "quem alterou" ou "última modificação". =============================================================================

get_pendency_details

============================================================================= get_ticket_details - Retorna um ticket pelo ID com detalhes completos ============================================================================= ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeFormAnswers (Boolean, default false): Inclui respostas de formulários. Use quando o usuário perguntar sobre checklists, vistorias ou formulários do ticket. $includeLocationContext (Boolean, default false): Inclui setores e ambientes da localização. Use quando o usuário perguntar sobre onde exatamente é o problema (setor/ambiente). =============================================================================

get_ticket_details

============================================================================= get_contract_details - Retorna um contrato pelo ID com detalhes completos ============================================================================= ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeDashboard (Boolean, default false): Inclui KPIs do contrato (progresso, deadlines, top violações). Use quando o usuário perguntar sobre saúde do contrato, cumprimento de SLA, progresso ou métricas. $includeAudit (Boolean, default false): Inclui auditoria (createdBy, updatedBy) e configuração. Use quando o usuário perguntar sobre quem criou/alterou o contrato ou suas configurações. $includeItemDeadlines (Boolean, default false): Inclui o contrato de prazo/SLA vinculado a cada item. Use quando o usuário perguntar sobre o SLA aplicado a cada item do contrato. =============================================================================

get_contract_details

============================================================================= get_equipment_details - Retorna um equipamento pelo ID com detalhes completos ============================================================================= ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeWarranties (Boolean, default false): Inclui garantias e resumo de garantia do equipamento. Use quando o usuário perguntar sobre garantia, cobertura, vencimento ou status de garantia. $includeMaintenances (Boolean, default false): Inclui histórico de manutenções do equipamento. Use quando o usuário perguntar sobre OS, histórico de manutenção ou serviços feitos no ativo. $includeLogs (Boolean, default false): Inclui auditoria completa de alterações no equipamento (quem alterou, quando, IP, origem e o snapshot do estado a cada mudança). Use quando o usuário perguntar sobre histórico de mudanças, quem alterou, o que mudou ou auditoria do ativo. $includeCriticality (Boolean, default false): Inclui a criticidade do equipamento e sua justificativa. Use quando o usuário perguntar se o ativo é crítico, ou quiser priorizar por criticidade. =============================================================================

get_equipment_details

============================================================================= get_deadline_violation_reason_details - Retorna um motivo de violação de SLA pelo ID ============================================================================= Detalhe completo de um motivo de violação, incluindo a quais contratos de SLA ele está vinculado. =============================================================================

get_deadline_violation_reason_details

============================================================================= get_quotation_details - Retorna um orçamento pelo ID com detalhes completos ============================================================================= ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeDiscount (Boolean, default false): Inclui detalhes do desconto aplicado. Use quando o usuário perguntar sobre desconto, abatimento ou valor antes/depois do desconto. $includeExpenses (Boolean, default false): Inclui despesas adicionais (frete, mão de obra extra, etc.). Use quando o usuário perguntar sobre despesas extras, taxas ou composição do total. $includeLabels (Boolean, default false): Inclui labels/tags do orçamento. Use quando o usuário perguntar sobre categorização, tags ou filtros por label. $includeApprovalDetails (Boolean, default false): Inclui quem aprovou/recusou e observações. Use quando o usuário perguntar sobre aprovação, recusa, justificativa ou observações do orçamento. =============================================================================

get_quotation_details

============================================================================= get_payment_details - Retorna um pagamento pelo ID com detalhes completos ============================================================================= ── CAMPOS OPCIONAIS ────────────────────────────────────────────────────────── $includeMaintenances (Boolean, default false): Inclui as manutenções agrupadas no pagamento. Use quando o usuário perguntar quais OS estão neste pagamento ou drill-down nas OS pagas. $includeQuotations (Boolean, default false): Inclui os orçamentos agrupados no pagamento. Use quando o usuário perguntar quais orçamentos compõem o pagamento. $includeTreatment (Boolean, default false): Inclui dados de tratamento (quem aprovou/pagou e quando). Use quando o usuário perguntar sobre aprovação, processamento ou auditoria do pagamento. =============================================================================

get_payment_details

============================================================================= get_import — Retorna os detalhes e status atual de uma importação pelo ID ============================================================================= 🎯 USE para acompanhar o progresso de uma importação em andamento (polling) ou para consultar o resultado final de uma importação concluída. Requer permissão: imports-list QUANDO USAR: - Polling durante validação: chame a cada 2-3s enquanto o status for validation_pending | validation_queued | validation_in_progress - Polling durante importação: chame a cada 3-5s enquanto o status for import_queued | import_in_progress - Verificar resultado: após importação concluída para apresentar resumo ao usuário ── STATUS POSSÍVEIS (enum ImportStatus) ────────────────────────────────────── validation_pending — criado, aguardando início da validação validation_queued — validação enfileirada validation_in_progress — validação em andamento (polling) validation_success — validação OK → pronto para start_import validation_error — planilha/linhas com erros → verificar notes.errors import_queued — importação enfileirada import_in_progress — importação em andamento (polling) import_success — importação concluída com sucesso import_partial_success — importação concluída parcialmente → verificar notes.errors import_error — importação falhou → verificar notes.errors ── PARÂMETRO ──────────────────────────────────────────────────────────────── $id: ID! — ID da importação retornado por create_import O QUE RETORNA: objeto Import completo com: - status e contadores de progresso (processedRowsCount / totalRowsCount) - notas de erros e avisos (notes.errors, notes.warnings) - link para download do relatório de erros (download.signedUrl) - createdBy: usuário que criou a importação =============================================================================

get_import

============================================================================= start_import — Inicia a importação definitiva dos dados da planilha ============================================================================= 🎯 ETAPA FINAL do fluxo de importação. Persiste os dados no banco. Execute SOMENTE quando o status for validation_success E após confirmação explícita do usuário para prosseguir. Requer permissão: imports-create QUANDO USAR: o usuário revisou o resumo da validação (validRowsCount, warnings) e confirmou que deseja importar. Nunca inicie sem confirmação explícita. Esta mutation define o status como import_queued; o processamento é assíncrono (import_in_progress) e termina em import_success, import_partial_success ou import_error. Use get_import para acompanhar o progresso. ── PARÂMETRO $input: StartImportInput! ────────────────────────────────────── id: ID! — ID da importação validada updatedAt: Datetime! — timestamp de atualização atual (controle de concorrência) language: String — idioma para mensagens, ex: "pt-BR" (opcional) O QUE RETORNA: objeto Import com status atualizado para import_queued. Use get_import periodicamente para verificar quando a importação concluir. Ao concluir (import_success ou import_partial_success), apresente o resumo: createRowsCount, updateRowsCount, deleteRowsCount e eventuais warnings/errors. FLUXO TÍPICO: 1. start_import_validation → validation_success → apresentar resumo ao usuário 2. Usuário confirma importação → start_import com id e updatedAt → import_queued 3. Polling com get_import enquanto status for import_queued | import_in_progress 4. Apresentar resultado final (import_success | import_partial_success | import_error): criados, atualizados, deletados, erros ⚠️ ATENÇÃO: esta operação é irreversível. Confirme sempre com o usuário antes de executar. =============================================================================

start_import

============================================================================= generate_upload_credential — Gera credenciais pré-assinadas para upload de arquivo no S3 ============================================================================= 🎯 MUTATION OBRIGATÓRIA para iniciar qualquer importação via planilha. Deve ser chamada ANTES de criar a importação. Retorna uma URL pré-assinada e campos de formulário para envio direto ao S3 (upload sem passar pelo servidor). QUANDO USAR: sempre que o usuário enviar uma planilha para importar dados. Chame esta mutation para obter as credenciais de upload, depois suba o arquivo diretamente para o S3 usando os campos retornados, e só então crie a importação. ── PARÂMETRO $input: UploadCredentialInput! ───────────────────────────────── size: Int! — tamanho do arquivo em bytes (obrigatório) extension: String! — extensão do arquivo, ex: "xlsx" (sem ponto) entity: UploadCredentialEntityEnum! — tipo de entidade; use "imports" para planilhas sessionId: ID — ID de sessão opcional (não obrigatório) Valores válidos para entity: imports, products, services, equipments, pendencies, maintenances, warranties, coursesImage, coursesContentMainFile, coursesContentExtraFile, payments, contracts, chat Para importação de planilhas use sempre entity: imports (xlsx, máx 10MB). O QUE RETORNA: - baseUrl: URL base do bucket S3 - link: URL completa do arquivo após upload - fields: campos de formulário (JSON) para incluir no POST multipart ao S3 - bucketName: nome do bucket (necessário para criar a importação) - fileKey: chave do arquivo no S3 (necessário para criar a importação) FLUXO TÍPICO: 1. generate_upload_credential → obtém baseUrl, fields, bucketName, fileKey 2. Upload do arquivo via POST multipart para baseUrl com os fields 3. create_import com fileKey e bucketName obtidos aqui =============================================================================

generate_upload_credential

============================================================================= list_imports — Lista as importações mais recentes (opcionalmente por tipo) ============================================================================= 🎯 USE para RETOMAR uma importação iniciada em um turno anterior: em vez de criar outra, localize a importação recente compatível e continue a partir do seu id/status. Requer permissão: imports-list QUANDO USAR: - O usuário pede para continuar/acompanhar uma importação sem informar o id - Antes de criar uma nova importação, para evitar duplicar uma já em andamento ── PARÂMETROS ─────────────────────────────────────────────────────────────── $where: ImportWhereInput — filtro (ex.: { type_in: [equipment] }) $orderBy: ImportOrderByInput — ordenação (use createdAt_desc para as mais recentes) $limit: Int / $offset: Int — paginação O QUE RETORNA: total + itens (id, type, status, datas) para o agente escolher qual importação retomar. =============================================================================

list_imports

============================================================================= dashboard — Painel operacional consolidado (V2) ============================================================================= 🎯 QUERY ÚNICA de dashboard. Uma só chamada cobre SLA, volume, manutenções, orçamentos, equipamentos e avaliações. Você liga APENAS os blocos que precisa via toggles `include*` (todos default false) — cada bloco ligado dispara um agregado no banco, então peça só o que vai usar. QUANDO USAR: qualquer pergunta agregada/resumo executivo — "como está o SLA", "% no prazo", "fora do prazo", "volume do mês", "backlog", "ranking de fornecedor", "orçamentos aprovados", "avaliações", "MTBF/MTTR". Para listar OS individuais ou detalhar UMA OS, use search_maintenances / get_maintenance_details — não este dashboard. ── PARÂMETRO $where: DashboardV2WhereInput! ────────────────────────────────── referenceDate_gte / referenceDate_lte: Datetime! (OBRIGATÓRIOS) — recorte do período. Formato "YYYY-MM-DD" ou ISO completo. Intervalo máx: 1 ano. timeZone: String — ex: "America/Sao_Paulo" (recomendado p/ cortes diários). Dimensões (opcionais, todas [ID!]): maintenanceTypeId_in, companyId_in, segmentId_in, locationId_in, locationGroupId_in, assigneeId_in, equipmentId_in, productId_in, serviceId_in. ── SEMÂNTICA DE PRAZO (LEIA ANTES DE INTERPRETAR SLA) ──────────────────────── Toda OS do período recebe UM veredito, mutuamente exclusivo. Os contadores de `sla.summary` somam esses vereditos e fecham em `totalCount`: without_sla ......................... sem contrato de prazo → withoutSlaCount on_schedule / at_risk / violated ..... em aberto → sla.openPortfolio (onScheduleCount / atRiskCount / violatedCount); as duas últimas também aparecem no summary como openAtRiskCount / openViolatedCount completed_on_time / completed_with_violation ... concluídas; a soma das duas é completedWithSlaCount, e completedOnTimeCount é a primeira delas Consequências ao explicar números: • `compliancePercentage` considera SOMENTE as concluídas com SLA (completedOnTimeCount ÷ completedWithSlaCount). OS em aberto — mesmo as violadas — NÃO entram no percentual; não as some ao denominador. • `openViolatedCount` usa o tempo atual como referência: CRESCE com o passar dos dias enquanto a OS não é atendida. Um valor de ontem não bate com o de hoje — isso é esperado, não é inconsistência. • `withoutSlaCount` não é violação: são OS sem contrato de prazo vinculado. Fica fora do numerador e do denominador de qualquer taxa de cumprimento. • Uma listagem de "em aberto e vencido" (search_maintenances com solutionDeadlineStatus = violated) corresponde a openViolatedCount, não ao total de violações do período — as já concluídas com violação estão em completedWithSlaCount − completedOnTimeCount. ── TOGGLES (todos Boolean, default false) ──────────────────────────────────── SLA / prazos: $includeSlaSummary ............. vereditos consolidados + % de cumprimento $includeSlaOpenPortfolio ....... carteira em aberto (no prazo / risco / violada) $includeSlaClassicPanel ........ painel clássico: resposta e solução separadas $includeSlaByStatusPanel ....... quebra por status da OS $includeSlaViolationReasons .... motivos de violação ($slaViolationReasonsLimit) $includeSlaByCompany ........... ranking por fornecedor ($slaRankingLimit) $includeSlaByType .............. ranking por tipo de OS ($slaRankingLimit) $includeSlaByLocationGroup ..... ranking por grupo de locais ($slaRankingLimit) $includeSlaEvolution ........... série temporal ($slaEvolutionGranularity: WEEK|MONTH) Volume / backlog: $includeVolumeSummary, $includeVolumeAgeBuckets, $includeVolumeTopOpenMaintenances (limit $volumeTopOpenLimit), $includeVolumeByMonth, $includeVolumeHeatmap Manutenções: $includeMaintenancesSummary, $includeMaintenancesByType, $includeMaintenancesVolumeByWeek, $includeMaintenancesRecent (paginado: $maintenancesRecentLimit/Offset) Orçamentos: $includeQuotationsSummary, $includeQuotationsByStatus, $includeQuotationsApprovedValuesByMonth, $includeQuotationsApprovedTotalByUser (paginado), $includeQuotationsTopProductsServices (paginado) Avaliações: $includeRatingsSummary, $includeRatingsAverageTimeline, $includeRatingsTop Equipamentos: $includeEquipmentsSummary (MTBF/MTTR/disponibilidade), $includeEquipmentsTopEquipments, $includeEquipmentsTraceability (paginado), $includeEquipmentsFailureHistory ── EXEMPLOS ────────────────────────────────────────────────────────────────── "Como está o cumprimento de SLA em junho, e quem são os piores fornecedores?" → where: { referenceDate_gte: "2026-06-01", referenceDate_lte: "2026-06-30", timeZone: "America/Sao_Paulo" } includeSlaSummary: true, includeSlaByCompany: true "Evolução do SLA por mês no ano" → where: { referenceDate_gte: "2026-01-01", referenceDate_lte: "2026-12-31" } includeSlaEvolution: true, slaEvolutionGranularity: MONTH OBS: formulários (dashboard_forms_answers*) e estoque (dashboard_products_by_storage, dashboard_storage_movements_by_day*) seguem em queries próprias — não estão aqui. =============================================================================

dashboard

============================================================================= dashboard_forms_answers_detail — Detalhamento de respostas de um formulário ============================================================================= QUANDO USAR: usuário quer ver "respostas detalhadas do formulário X", "estatísticas de cada pergunta", análise de um checklist específico. Use APÓS dashboard_forms_answers para obter o formId. O QUE RETORNA: lista de perguntas do formulário com estatísticas de respostas. Cada item: { title, type, position, answers }. answers é um union type: - OpenQuestionAnswerStatistics: { value } (respostas abertas) - ClosedQuestionAnswerStatistics: { value, count } (múltipla escolha) - MultipleQuestionAnswerStatistics: { values } (checkbox) ── PARÂMETRO $where: DashboardFormsAnswersDetailWhereInput! ────────────────── OBRIGATÓRIO: formId_eq: ID! — ID do formulário (obter via dashboard_forms_answers) Datas (opcionais): createdAt_gte/lte: Datetime — filtrar por período de resposta Formato Datetime: "YYYY-MM-DD" (ex: "2026-01-01") ou "YYYY-MM-DDTHH:mm:ssZ" Dimensões (opcionais): locationId_in: [ID], segmentId_in: [ID], companyId_in: [ID], locationGroupId_in: [ID], maintenanceTypeId_in: [ID], formAnswer_contains: String EXEMPLO DE USO: "Detalhes do formulário abc123 no mês" → where: { formId_eq: "abc123", createdAt_gte: "2026-04-01", createdAt_lte: "2026-04-11" } COMBINA BEM COM: dashboard_forms_answers (lista de formulários com contagem) =============================================================================

dashboard_forms_answers_detail

============================================================================= dashboard_storage_movements_by_day — Movimentações de estoque por dia ============================================================================= QUANDO USAR: usuário pergunta "movimentação diária de estoque", "entradas e saídas por dia", gráfico de evolução do estoque. O QUE RETORNA: série temporal diária de movimentações de estoque. Cada item: { date, entryCount, removeCount, transferCount, finalCount, productId, storageId, productName, storageName }. ── FILTROS ($where: DashboardStorageWhereInput!) ───────────────────────────── OBRIGATÓRIO: from + to (período de análise) OPCIONAIS: productId (filtrar produto específico), storageId_in (filtrar almoxarifados) EXEMPLO DE USO: "Movimentação diária de estoque em março" → where: { from: "2026-03-01", to: "2026-03-31" } COMBINA BEM COM: dashboard_storage_movements_by_type (totais por tipo), dashboard_products_by_storage (visão geral de estoque) =============================================================================

dashboard_storage_movements_by_day

============================================================================= dashboard_storage_movements_by_type — Movimentações de estoque por tipo ============================================================================= QUANDO USAR: usuário pergunta "total de entradas vs saídas?", "quantas transferências?", resumo de tipos de movimentação de estoque. O QUE RETORNA: contagem total de movimentações por tipo: { entryCount, removeCount, transferCount }. ── FILTROS ($where: DashboardStorageWhereInput!) ───────────────────────────── OBRIGATÓRIO: from + to (período de análise) OPCIONAIS: productId (filtrar produto específico), storageId_in (filtrar almoxarifados) EXEMPLO DE USO: "Resumo de movimentações de estoque no mês" → where: { from: "2026-03-01", to: "2026-03-31" } COMBINA BEM COM: dashboard_storage_movements_by_day (evolução diária), dashboard_products_by_storage (visão geral de estoque) =============================================================================

dashboard_storage_movements_by_type

============================================================================= dashboard_products_by_storage — Produtos por almoxarifado/estoque ============================================================================= QUANDO USAR: usuário pergunta "quais produtos têm em estoque?", "estoque por almoxarifado", "distribuição de produtos nos estoques". O QUE RETORNA: contagem de produtos por almoxarifado/estoque. Cada item tem { key: "storageName/productName", value: quantidade }. ── FILTROS ($where: DashboardStorageWhereInput!) ───────────────────────────── OBRIGATÓRIO: from + to (período de análise) OPCIONAIS: productId (filtrar produto específico), storageId_in (filtrar almoxarifados) EXEMPLO DE USO: "Produtos em estoque no mês atual" → where: { from: "2026-03-01", to: "2026-03-31" } COMBINA BEM COM: dashboard_storage_movements_by_day (movimentação diária), dashboard_storage_movements_by_type (por tipo de movimentação) =============================================================================

dashboard_products_by_storage

============================================================================= dashboard_forms_answers — Resumo de respostas de formulários ============================================================================= QUANDO USAR: usuário pergunta "quais formulários foram respondidos?", "quantas respostas por formulário?", visão geral de checklists/formulários. O QUE RETORNA: lista paginada de formulários com contagem de respostas. Cada item: { formId, formName, formAnswerCount }. ── PARÂMETRO $where: DashboardFormsAnswersWhereInput! ──────────────────────── Datas (opcionais): createdAt_gte: Datetime — início do período de resposta createdAt_lte: Datetime — fim do período Formato Datetime: "YYYY-MM-DD" (ex: "2026-01-01") ou "YYYY-MM-DDTHH:mm:ssZ" Dimensões (opcionais): locationId_in: [ID], segmentId_in: [ID], companyId_in: [ID], locationGroupId_in: [ID], maintenanceTypeId_in: [ID], formAnswer_contains: String — busca textual nas respostas ── PAGINAÇÃO ────────────────────────────────────────────────────────────────── $limit (Int!): registros por página $offset (Int!): offset EXEMPLO DE USO: "Quais formulários foram mais respondidos no mês?" → where: { createdAt_gte: "2026-04-01", createdAt_lte: "2026-04-11" }, limit: 20, offset: 0 COMBINA BEM COM: dashboard_forms_answers_detail (detalhamento de um formulário) =============================================================================

dashboard_forms_answers

============================================================================= update_import_file — Substitui o arquivo de uma importação existente por um novo ============================================================================= 🎯 USE quando o usuário precisar corrigir e reenviar a planilha de uma importação já validada. Aceita SOMENTE imports em status validation_error ou validation_success, e reseta o status para validation_pending (zera contadores e notes). Requer permissão: imports-create QUANDO USAR: o usuário corrigiu a planilha e quer substituir o arquivo antes de iniciar novamente a validação. Primeiro faça um novo upload com generate_upload_credential, depois chame esta mutation com o novo fileKey. ── PARÂMETRO $input: UpdateImportFileInput! ───────────────────────────────── id: ID! — ID da importação a ser atualizada (obtido em create_import ou get_import) fileKey: String! — nova chave do arquivo no S3 (do novo upload) bucketName: String! — nome do bucket S3 (do novo upload) updatedAt: Datetime! — timestamp de atualização atual da importação (controle de concorrência) O QUE RETORNA: objeto Import atualizado com o novo fileKey e status validation_pending. Após atualizar, inicie uma nova validação com start_import_validation. FLUXO TÍPICO: 1. Usuário corrige a planilha 2. generate_upload_credential → upload → novo fileKey e bucketName 3. update_import_file com id (importação existente) + novos fileKey/bucketName + updatedAt 4. start_import_validation para revalidar =============================================================================

update_import_file