API de integração do PMOC Fácil

A integração é push: o seu sistema envia os dados por HTTPS e recebe de volta os identificadores criados, as contagens por bloco e o percentual de preenchimento do PMOC, com a lista do que ainda falta para o documento ficar completo.

• Base: https://pmocfacil.com
• Formato: JSON (UTF-8), Content-Type: application/json
• Versão do contrato: 1 (campo opcional versao no payload)
• Um envio = um cliente/edificação, com seus locais, equipamentos e plano
• Nenhum envio gera PMOC assinado automaticamente

O que normalmente não existe no sistema de origem e precisa ser completado no painel: área (m²), população fixa/flutuante e atividade por ambiente climatizado, e os dados do responsável técnico (formação, conselho, registro, ART e validade).

Cada conta assinante gera seus próprios tokens. O token define a conta de destino: tudo que entra fica isolado nela. Envie em um dos dois cabeçalhos:

Authorization: Bearer SEU_TOKEN
# ou
x-api-key: SEU_TOKEN

• O token é exibido uma única vez na criação — guarde em cofre de segredos.
• Só o prefixo fica visível no painel; o valor é armazenado como hash.
• Revogar uma chave invalida imediatamente todos os envios que a usam.
• Tokens de contas sem plano mensal ativo são recusados com 401.
• Use uma chave por ambiente (produção/homologação) para revogar sem parar o resto.

Quatro blocos, sendo apenas cliente obrigatório:

{
  "versao": "1",
  "cliente":  { ... },          // obrigatório
  "locais":   [ ... ],          // opcional (até 2000)
  "equipamentos": [ ... ],      // opcional (até 5000)
  "plano_manutencao": {         // opcional
    "nome": "...",
    "mes_inicio": 1,
    "itens": [ ... ]            // até 2000
  }
}

Campos desconhecidos são ignorados. Números aceitam string ("24000" ou "42,5") e são normalizados. Strings são aparadas e truncadas no limite do campo. null equivale a ausente.

5.1 cliente

5.2 locais[]

A hierarquia é montada por referencia_pai, com profundidade livre (prédio → pavimento → área → sala). Envie o pai antes ou depois — a ordem não importa.

5.3 equipamentos[]

5.4 plano_manutencao

5.5 plano_manutencao.itens[]

Informe tipo_equipamento para aplicar a atividade a todos os ativos daquele tipo, ou tag para um ativo específico.

Toda entidade carrega referencia_externa. A chave de unicidade é conta + referencia_externa, então:

• Reenviar o mesmo cliente atualiza o cadastro (nunca duplica).
• Locais e equipamentos seguem a mesma regra, individualmente.
• Contas diferentes podem usar as mesmas referências sem colisão.
• A resposta traz criado e contagens de criados/atualizados por bloco.
• Reenvio é seguro para retentativa após timeout ou erro de rede.

Envios não fazem exclusão: remover um equipamento no sistema de origem não o apaga no PMOC Fácil. Ajustes de baixa são feitos no painel.

7.1 Envio (POST)

curl -X POST https://pmocfacil.com/api/public/integracoes/confirm8/clientes \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "versao": "1",
  "cliente": {
    "referencia_externa": "CLI-1042",
    "razao_social": "Hospital Santa Clara Ltda",
    "nome_fantasia": "Santa Clara",
    "cnpj": "12.345.678/0001-90",
    "endereco": "Av. Paulista, 1000",
    "cidade": "São Paulo",
    "uf": "SP",
    "telefone": "11988887777",
    "email": "manutencao@santaclara.com.br",
    "tipo_edificacao": "Hospital / clínica",
    "responsavel_local": "Eng. Ana Souza"
  },
  "locais": [
    {
      "referencia_externa": "L-1",
      "referencia_pai": null,
      "nome": "Prédio Central",
      "tipo": "predio",
      "climatizado": false,
      "area_m2": null,
      "populacao_fixa": null,
      "populacao_flutuante": null,
      "tipo_atividade": null
    },
    {
      "referencia_externa": "L-1-2",
      "referencia_pai": "L-1",
      "nome": "2º pavimento",
      "tipo": "pavimento",
      "climatizado": false,
      "area_m2": null,
      "populacao_fixa": null,
      "populacao_flutuante": null,
      "tipo_atividade": null
    },
    {
      "referencia_externa": "L-1-2-201",
      "referencia_pai": "L-1-2",
      "nome": "Centro cirúrgico 201",
      "tipo": "sala",
      "climatizado": true,
      "area_m2": 42.5,
      "populacao_fixa": 6,
      "populacao_flutuante": 12,
      "tipo_atividade": "Cirurgia"
    }
  ],
  "equipamentos": [
    {
      "referencia_externa": "EQ-9001",
      "local": "L-1-2-201",
      "tag": "AC-201",
      "tipo_equipamento": "fancoil",
      "marca": "Carrier",
      "modelo": "42BQA024",
      "serie": "SN789012",
      "tensao": "220V",
      "capacidade_btu_h": 24000,
      "ano_fabricacao": 2019,
      "quantidade": 1,
      "observacao": "Atende sala limpa"
    }
  ],
  "plano_manutencao": {
    "nome": "Plano preventivo Confirm8",
    "mes_inicio": 1,
    "itens": [
      {
        "tipo_equipamento": "fancoil",
        "tag": null,
        "componente": "Filtros de ar",
        "atividade": "Verificar, limpar e substituir quando saturado",
        "periodicidade": "Mensal",
        "referencia": "Portaria 3.523/98 · NBR 13971"
      },
      {
        "tipo_equipamento": "fancoil",
        "tag": null,
        "componente": "Bandeja de condensado",
        "atividade": "Limpeza, remoção de biofilme e teste de escoamento",
        "periodicidade": "Mensal",
        "referencia": "RE-09/2003"
      }
    ]
  }
}'

7.2 Resposta do envio

{
  "ok": true,
  "edificacao_id": "8f2c…",
  "referencia_externa": "CLI-1042",
  "criado": true,
  "locais": { "criados": 3, "atualizados": 0 },
  "equipamentos": { "criados": 1, "atualizados": 0 },
  "atividades": 2,
  "completude": {
    "percentual": 76,
    "pendencias": [
      "Responsável técnico: conselho e registro",
      "ART e validade"
    ]
  },
  "revisar_em": "https://pmocfacil.com/painel"
}

7.3 Consulta (GET)

curl https://pmocfacil.com/api/public/integracoes/confirm8/clientes/CLI-1042 \
  -H "Authorization: Bearer SEU_TOKEN"

7.4 Resposta da consulta

{
  "ok": true,
  "referencia_externa": "CLI-1042",
  "edificacao_id": "8f2c…",
  "razao_social": "Hospital Santa Clara Ltda",
  "locais": 3,
  "equipamentos": 1,
  "pmocs_gerados": 0,
  "completude": { "percentual": 76, "pendencias": ["..."] }
}

Erros de validação (422) listam até 50 campos, cada um com o caminho exato (equipamentos.3.tag) e a mensagem. Nesse caso nada é gravado.

• Um cliente por requisição; até 2000 locais, 5000 equipamentos e 2000 atividades.
• Envie o inventário completo do cliente em um único POST — é mais rápido e consistente que fatiar.
• Retentativa recomendada: 3 tentativas com espera exponencial (2s, 8s, 30s) para 5xx e timeout.
• Não retente 401 nem 422 — corrija token ou payload.
• Cada envio fica registrado no painel da conta (data, cliente, itens, resultado e erro).
• Use HTTPS sempre; nunca coloque o token em URL, log ou código-fonte do cliente.
• Trate o percentual de preenchimento retornado como um checklist para o usuário final.

• Chave gerada para o ambiente correto e guardada em cofre de segredos.
• Mapeamento de referencia_externa definido e estável para cliente, local e equipamento.
• Tipos de equipamento e periodicidades mapeados para os valores aceitos.
• Reenvio testado: segundo POST atualiza sem duplicar.
• Tratamento de 401, 422 e 5xx implementado com log.
• Consulta GET exibindo pendências para o usuário do seu sistema.
• Responsável técnico cadastrado no painel para permitir a assinatura do documento.

Dúvidas de integração: contato@pmocfacil.com.