Documentação da API VigiaXML

# 1. Exporte a api-key copiada após confirmar o email
export VIGIA_API_KEY="vxml_..."

# 2. Consulte uma chave (a API detecta o modelo pelas posições 21-22)
curl -X POST https://api.vigiaxml.com/v1/consulta \
  -H "X-Api-Key: $VIGIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chaveAcesso": "35240300000000000000550010000001231123456785" }'

# 3. Coloque a mesma chave em monitoramento contínuo (30 dias)
curl -X POST https://api.vigiaxml.com/v1/monitoramento \
  -H "X-Api-Key: $VIGIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chaveAcesso": "35240300000000000000550010000001231123456785",
    "callbackUrl": "https://erp.example.com/webhooks/vigia"
  }'

# Lote misto (NF-e + CT-e + MDF-e) — modelo detectado pelas posições 21-22.
curl -X POST https://api.vigiaxml.com/v1/importar \
  -H "X-Api-Key: $VIGIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chaves": [
      "35240300000000000000550010000001231123456785",
      "35240300000000000000570010000001231123456786",
      "35240300000000000000580010000001231123456787"
    ],
    "modo": "monitoramento",
    "webhookUrl": "https://erp.example.com/webhooks/vigia",
    "pularConsultaInline": false
  }'

{
  "modo": "monitoramento",
  "total": 3,
  "duration_ms": 2918,
  "adicionadas": 3,
  "duplicadas": 0,
  "breakdown": { "nfe": 1, "cte": 1, "mdfe": 1 },
  "rejeitadas": [],
  "valor_estimado_brl": 1.05,
  "results": [
    { "chave": "35...", "modelo": 55, "tipo": "NF-e", "uf": "SP",
      "cStat": "100", "status": "autorizada", "xMotivo": "Autorizado o uso da NF-e", "durationMs": 980 }
  ]
}

// Botão "monitorar" no ERP — usuário aguardando na tela.
// A resposta 201 já traz o status consultado na SEFAZ; não faça um GET depois.
async function monitorar(chaveAcesso: string) {
  const ctrl = new AbortController();
  // 30s: p95 real é ~500ms, mas UF lenta pode cair na contingência.
  const t = setTimeout(() => ctrl.abort(), 30_000);

  try {
    const res = await fetch("https://api.vigiaxml.com/v1/monitoramento", {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.VIGIA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chaveAcesso,
        callbackUrl: "https://erp.suaempresa.com.br/webhooks/vigiaxml",
      }),
      signal: ctrl.signal,
    });

    // 409 = já estava monitorada. Não é erro e NÃO cobra de novo.
    if (res.status === 409) return { ok: true, aviso: "Nota já monitorada." };

    if (res.status === 402) return { ok: false, erro: "Limite do plano atingido." };
    if (res.status === 400) return { ok: false, erro: "Chave inválida." };
    if (!res.ok) return { ok: false, erro: "Indisponível — tente novamente." };

    const data = await res.json();
    // status_atual: autorizada | cancelada | denegada | inexistente | null
    // null = SEFAZ não respondeu em 12s. A nota ESTÁ monitorada; o status
    // atualiza no ciclo seguinte (~5 min) — confirme com GET /v1/monitoramento.
    // Mostre "aguardando SEFAZ", não erro.
    return { ok: true, status: data.status_atual, expiraEm: data.expira_em };
  } catch (e) {
    if ((e as Error).name === "AbortError") {
      // O monitoramento pode ter sido criado mesmo com timeout no cliente:
      // confirme com GET /v1/monitoramento/:chave antes de reenviar.
      return { ok: false, erro: "Tempo esgotado — verifique antes de repetir." };
    }
    return { ok: false, erro: "Falha de rede." };
  } finally {
    clearTimeout(t);
  }
}

# Uma nota, com link já na resposta
curl -X POST https://api.vigiaxml.com/v1/monitoramento \
  -H "X-Api-Key: $VIGIAXML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chaveAcesso": "'$CHAVE'", "linkRastreio": true, "linkDias": 15 }'

# 201 Created
# {
#   "success": true,
#   "link_rastreio": "https://vigiaxml.com/rastreio/a1b2...c3d4",
#   "link_expira_em": "2026-08-19T18:00:00+00:00",
#   "status_atual": "autorizada",
#   ...
# }

# Em lote: cada item de "results" volta com o seu link.
curl -X POST https://api.vigiaxml.com/v1/importar \
  -H "X-Api-Key: $VIGIAXML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chaves": ["...", "..."], "modo": "monitoramento", "linkRastreio": true }'

# { "results": [ { "chave": "...", "status": "autorizada",
#                  "link_rastreio": "https://vigiaxml.com/rastreio/..." } ] }

# Gera um link de rastreio válido por 15 dias
curl -X POST "https://api.vigiaxml.com/v1/rastreio/$CHAVE/link?dias=15" \
  -H "X-Api-Key: $VIGIAXML_API_KEY"

# 200 OK
# {
#   "url": "https://vigiaxml.com/rastreio/a1b2...c3d4",
#   "chave": "35260344340879000196550010001073051136511817",
#   "expira_em": "2026-08-19T18:00:00+00:00"
# }
#
# Mande essa url pro cliente final. Ela abre sozinha, sem login.

# Histórico paginado de consultas (mais recentes primeiro).
# Filtros: chave, since (ISO 8601), limit (max 200), offset.
# Pra espelhar no seu banco, use o modo feed (de/ate/cursor) — ver Sincronização.
curl "https://api.vigiaxml.com/v1/consultas?since=2026-05-01T00:00:00Z&limit=50" \
  -H "X-Api-Key: $VIGIA_API_KEY"

# Primeira chamada: cursor vazio = começar do início.
curl "https://api.vigiaxml.com/v1/consultas?cursor=&limit=500" \
  -H "X-Api-Key: $VIGIA_API_KEY"

# Chamadas seguintes: só o next_cursor da resposta anterior.
curl "https://api.vigiaxml.com/v1/consultas?cursor=eyJmIjoiY29uc3VsdGFzIiwidCI6Ii4uLiJ9" \
  -H "X-Api-Key: $VIGIA_API_KEY"

# Ou por janela de data (de inclusivo, ate exclusivo; sem hora = meia-noite BRT).
curl "https://api.vigiaxml.com/v1/consultas?de=2026-09-08&ate=2026-09-09" \
  -H "X-Api-Key: $VIGIA_API_KEY"

# Eventos: mesmo contrato, cursor próprio.
curl "https://api.vigiaxml.com/v1/eventos?cursor=&limit=500" \
  -H "X-Api-Key: $VIGIA_API_KEY"

# Conferência: total por status na janela (máx. 7 dias).
curl "https://api.vigiaxml.com/v1/consultas/resumo?de=2026-09-08&ate=2026-09-09" \
  -H "X-Api-Key: $VIGIA_API_KEY"

{
  "items": [
    {
      "id": "b7e3a9f0-4c21-4f8a-9d3e-1a2b3c4d5e6f",
      "chave_acesso": "35260912345678000190550010000123451000123450",
      "modelo": 55,
      "uf": "SP",
      "status": "cancelada",
      "c_stat": "101",
      "x_motivo": "Cancelamento de NF-e homologado",
      "protocolo_sefaz": "135260001240001",
      "data_status_sefaz": "2026-09-08T18:47:33+00:00",
      "queried_at": "2026-09-08T19:00:07+00:00",
      "origem": "Monitoramento",
      "alerta_manifestacao": false,
      "tem_cce": false
    }
  ],
  "next_cursor": "eyJmIjoiY29uc3VsdGFzIiwidCI6IjIwMjYtMDktMDhUMTk6MDA6MDcrMDA6MDAiLCJpIjoiYjdlMy4uLiJ9",
  "has_more": false
}

# roda num cron a cada 5 minutos
def sincronizar(feed):                      # "consultas" ou "eventos"
    cursor = db.get_cursor(feed) or ""      # "" na primeira vez
    while True:
        r = http.get(f"https://api.vigiaxml.com/v1/{feed}",
                     params={"cursor": cursor, "limit": 500},
                     headers={"X-Api-Key": API_KEY}).json()
        for item in r["items"]:
            db.upsert(feed, item)           # chave do upsert: item["id"]
        cursor = r["next_cursor"]
        db.save_cursor(feed, cursor)        # só DEPOIS do upsert commitar
        if not r["has_more"]:
            break

sincronizar("consultas")
sincronizar("eventos")

# Árvore de documentos vinculados (NF-e ↔ CT-e ↔ MDF-e) com timeline.
# Use pra reconstruir a história completa de uma operação fiscal.
curl https://api.vigiaxml.com/v1/rastreio/35240300000000000000550010000001231123456785 \
  -H "X-Api-Key: $VIGIA_API_KEY"

{
  "error": "chave_acesso deve ter 44 dígitos"
}