API de Integração Confisped v1

Retorna informações da chave atual — útil pra testar autenticação e ver cota disponível.

Resposta 200

{
  "meta": { ... },
  "data": {
    "chave": "ck_a1b2c3…ef8d",
    "nome": "Integração ERP Cliente X",
    "tenant": { "id": "cl...", "nome": "Empresa Y", "plano": "PRO" },
    "cota": { "mensal": 50000, "usado_mes_atual": 137, "mes_referencia": "2026-05" },
    "escopo": "irrestrito",
    "criada_em": "2026-05-22T13:00:00Z",
    "expira_em": null
  }
}

Retorna a tributação completa do NCM informado — tributos atuais (ICMS, PIS, COFINS, IPI) e tributos da Reforma 2026 (CBS, IBS-UF, IBS-Mun, IS).

Path params

Query params (opcionais)

💡 Perfil emissor (Indústria/Atacado/Varejo/CD) e regime fiscal (Simples/Real/Presumido) não são parâmetros — saem automaticamente do cadastro do tenant dono da chave. Veja Perfis.

Exemplo de chamada

curl -H "Authorization: Bearer ck_SUA_CHAVE" \
  "https://srv1634928.hstgr.cloud/api/v1/produtos/ncm/3306.10.00?uf=MS"

const r = await fetch('https://srv1634928.hstgr.cloud/api/v1/produtos/ncm/3306.10.00?uf=MS', {
  headers: { 'Authorization': 'Bearer ' + process.env.CONFISPED_TOKEN }
});
const json = await r.json();
console.log(json.data.tributacao);

import requests, os
r = requests.get(
  'https://srv1634928.hstgr.cloud/api/v1/produtos/ncm/3306.10.00',
  headers={'Authorization': f'Bearer {os.getenv("CONFISPED_TOKEN")}'},
  params={'uf': 'MS'}
)
print(r.json()['data']['tributacao'])

<?php
$ch = curl_init('https://srv1634928.hstgr.cloud/api/v1/produtos/ncm/3306.10.00?uf=MS');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . getenv('CONFISPED_TOKEN')]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = json_decode(curl_exec($ch), true);
print_r($json['data']['tributacao']);

Resposta 200 (resumida — exemplo Atacado/Simples)

{
  "meta": { "version": "1.0.0", "duration_ms": 28, ... },
  "data": {
    "ncm": "33061000",
    "descricao": "Cremes dentais",
    "cest": "20.058.00",
    "setor": "Higiene",
    "uf_referencia": "MS",
    "emissor": {
      "perfil": "ATACADO",
      "regime": "SIMPLES",
      "uf": "MS",
      "matriz_filial": "MATRIZ"
    },
    "tributacao": {
      "atual": {
        "ipi":    { "aliquota": 0, "cobra": false, "observacao": "IPI só é recolhido pela indústria — perfil ATACADO não cobra" },
        "pis":    { "aliquota": 1.65, "cst": "01" },
        "cofins": { "aliquota": 7.60, "cst": "01" },
        "icms": {
          "regime": "SIMPLES",
          "perfil_tratamento": "ICMS_ST_RECEBIDO",
          "csosn": "500",
          "aliquota_st_recebida": 17,
          "mva_original": 35.42,
          "mva_ajustado": 41.18,
          "observacao": "ICMS já foi retido pela indústria — revendedor lança CSOSN 500"
        },
        "fcp_aliquota": 0,
        "tem_substituicao_tributaria": true
      },
      "reforma": {
        "vigencia_2026": "2026 — fase informativa...",
        "cbs": {
          "ativo": true,
          "aliquota_referencia": 8.5,
          "aliquota_2026": 0.9,
          "cst": "000",
          "cclass_trib": "000001",
          "norma_legal": "LC 214/2025 art 7º"
        },
        "ibs": {
          "uf":  { "ativo": true, "aliquota": 17.5, "cst": "000" },
          "municipio": { "ativo": true, "aliquota": 0, "codigo_ibge_municipio": "5003702" }
        },
        "is": { "aplicavel": false },
        "classificacao": { "categoria": "Padrão", "dispositivo": "Art 7º LC 214/2025" }
      }
    },
    "operacoes_sugeridas": {
      "venda_interna": "5405",
      "venda_interestadual": "6404",
      "venda_consumidor_final_interestadual": "6108",
      "observacao": "Atacado revende — CFOP indica revenda"
    }
  }
}

Busca produto e tributação por código de barras (EAN/GTIN). Útil pra integração com PDV, leitor de balança, app mobile. A busca prioriza a base global Confisped e depois os produtos do seu tenant — o campo escopo indica a origem. Se o EAN não existir, solicite o cadastro via POST /produtos/ean/{ean}/solicitar-cadastro.

Path params

💡 Não há query params — UF, perfil emissor e regime saem do cadastro do tenant dono da chave. Só produtos aprovados (status ATIVO) são retornados; produto em auditoria/quarentena responde 202 em_analise.

Exemplo de chamada

curl -H "Authorization: Bearer ck_SUA_CHAVE" \
  "https://srv1634928.hstgr.cloud/api/v1/produtos/ean/7894900664003"

Resposta 200 (resumida)

{
  "meta": { ... },
  "data": {
    "ean": "7894900664003",
    "descricao": "Refresco lata 350ml — marca X",
    "ncm": "22021000",
    "cest": "03.007.00",
    "status": "ATIVO",
    "escopo": "global",   /* "global" (base Confisped) ou "cliente" (produto do seu tenant) */
    "confianca": "ALTA",
    "fonte": "ROBO_CAD",
    "atualizado_em": "2026-07-01T12:00:00.000Z",
    "tributacao": {
      "atual":   { /* ICMS, PIS, COFINS, IPI — mesmo formato do /produtos/ncm */ },
      "reforma": { /* CBS, IBS-UF, IBS-Mun, IS */ }
    }
  }
}

O bloco tributacao vem preenchido quando o produto tem NCM com cadastro Mercantil ativo; caso contrário retorna null.

Resposta 202 (EAN em análise)

{
  "meta": { ... },
  "ean": "7894900664003",
  "status": "em_analise",
  "mensagem": "EAN 7894900664003 está em análise/classificação na Confisped — ainda não liberado para consulta. Tente novamente em breve."
}

Resposta 404 (EAN sem cadastro)

{
  "meta": { "request_id": "req_..." },
  "erro": {
    "codigo": "not_found",
    "mensagem": "EAN 7894900664003 não está cadastrado na base Confisped",
    "dica": "Solicite cadastro via POST /api/v1/produtos/ean/7894900664003/solicitar-cadastro"
  }
}

Erros específicos

Solicita o cadastro tributário de um EAN que ainda não existe na base Confisped. A solicitação entra na fila do Robo_Cad (classificação automática + revisão da equipe). Retorna um protocolo — depois consulte GET /produtos/ean/{ean} pra checar (202 enquanto em análise, 200 quando aprovado).

Path params

Body (JSON)

Exemplo de chamada

curl -X POST -H "Authorization: Bearer ck_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"descricao":"Refresco lata 350ml sabor guaraná","codigo_interno":"A2","ncm_sugerido":"22021000"}' \
  "https://srv1634928.hstgr.cloud/api/v1/produtos/ean/7894900664003/solicitar-cadastro"

Resposta 201 (solicitação criada)

{
  "meta": { ... },
  "data": {
    "protocolo": "cl9x7...",
    "status": "AGUARDANDO",
    "ean": "7894900664003",
    "descricao": "Refresco lata 350ml sabor guaraná",
    "criado_em": "2026-07-09T14:30:00.000Z",
    "mensagem": "Solicitação enviada ao Robo_Cad. Consulte GET /api/v1/produtos/ean/7894900664003 depois pra checar."
  }
}

Resposta 409 (duplicidade)

{
  "meta": { ... },
  "erro": {
    "codigo": "solicitacao_ativa",   /* ou "ja_existe_global" / "ja_cadastrado" */
    "mensagem": "Já existe solicitação em andamento para este EAN",
    "produto_id": null,
    "solicitacao_id": "cl8w2..."
  }
}

Erros específicos

Revisão fiscal em lote (até 300 itens). Cliente envia lista da própria base; sistema devolve tributação + flag divergencia: true se algum tributo enviado (ICMS, PIS, COFINS, NCM) diferir do cadastro Confisped.

Body (JSON array)

⚠ Limites: 300 itens por request · 1 request a cada 30 segundos.

Exemplo de chamada

curl -X POST -H "Authorization: Bearer ck_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '[
    {"codinterno":"A1","ean":"7891000100103","descricao":"Leite Condensado","ncm":"04029900","icms":0,"pis":0,"cofins":0},
    {"codinterno":"A2","ean":"7891000051405","descricao":"Biscoito recheado","ncm":"19053100","icms":17,"pis":1.65,"cofins":7.6}
  ]' \
  "https://srv1634928.hstgr.cloud/api/v1/produtos/revisao"

Resposta 200 (resumida)

{
  "meta": { ... },
  "data": {
    "total_itens": 2,
    "com_divergencia": 1,
    "itens": [
      {
        "codinterno": "A2",
        "ncm": "19053100",
        "divergencia": true,
        "divergencias_detectadas": ["ncm", "pis"],
        "tributacao": { /* tributação oficial Confisped */ }
      }
    ]
  }
}

Erros específicos

Cálculo de DIFAL (Diferencial de Alíquota do ICMS) em operações interestaduais — LC 190/2022 + EC 87/2015. Uma operação por request (body é um objeto único, não array). Retorna base de cálculo, ICMS interestadual/interno, DIFAL, FCP, responsavel pelo recolhimento e memorial com a memória de cálculo passo a passo.

Body (JSON — objeto único)

Exemplo de chamada

curl -X POST -H "Authorization: Bearer ck_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"uf_origem":"SP","uf_destino":"MS","tipo_operacao":"B2C_FINAL_PF","valor_operacao":1000,"aliquota_interestadual":7,"aliquota_interna":17,"fcp_aliquota":2}' \
  "https://srv1634928.hstgr.cloud/api/v1/difal/calcular"

Resposta 200 (objeto único)

{
  "meta": { ... },
  "data": {
    "calculo_id": null,   /* preenchido quando persistir=true */
    "uf_origem": "SP",
    "uf_destino": "MS",
    "tipo_operacao": "B2C_FINAL_PF",
    "responsavel": "REMETENTE",   /* REMETENTE | DESTINATARIO | NAO_APLICAVEL */
    "ncm": null,
    "base_calculo": 1000.00,
    "icms_interestadual": 70.00,
    "icms_interno": 170.00,
    "difal_calculado": 100.00,
    "fcp_calculado": 20.00,
    "total_devido": 120.00,
    "aliquotas": {
      "interestadual": 7,
      "interna": 17,
      "fcp": 2,
      "difal": 10
    },
    "memorial": "Operação: B2C — consumidor final pessoa física\nUF origem → UF destino: SP → MS\n..."
  }
}

Erros específicos

Lista mudanças incrementais pra sincronização do seu ERP — registros da base Mercantil (tributação por NCM/UF) ou produtos (global + seu tenant) alterados desde a data informada. Rodar 1x por dia no início ou fim do dia.

Query params (opcionais)

Exemplo de chamada

curl -H "Authorization: Bearer ck_SUA_CHAVE" \
  "https://srv1634928.hstgr.cloud/api/v1/atualizacoes?since=2026-07-08&tipo=mercantil&take=500"

Resposta 200 (tipo=mercantil)

{
  "meta": {
    "since": "2026-07-08T00:00:00.000Z",
    "tipo": "mercantil",
    "total": 42,
    "truncado": false,   /* true = tem mais páginas; avance o since pro último atualizado_em */
    ...
  },
  "data": [
    {
      "tipo": "mercantil",
      "id": "cl7k1...",
      "ncm": "22021000",
      "ncm_ex": null,
      "uf": "MS",
      "descricao": "Refrescos e refrigerantes",
      "cest": "03.007.00",
      "status": "ATIVO",
      "reforma": { "cbs": 8.5, "ibs_uf": 17.5, "ibs_municipio": 0 },
      "atualizado_em": "2026-07-08T18:22:41.000Z"
    }
  ]
}

Com tipo=produto, cada item traz ean, descricao, ncm, cest, status, escopo (global|cliente), confianca e atualizado_em. Só produtos aprovados (ATIVO) entram na lista.

Erros específicos

Lista divergências fiscais detectadas no Monitoramento de XMLs (upload manual, Cofre ou webhook /monitoramento/xml). Cada resultado é um XML importado com pelo menos 1 divergência, incluindo os itens divergentes com o comparativo cliente × Confisped (NCM, CEST, CFOP, alíquota ICMS).

Query params (opcionais)

🔒 O escopo é sempre o tenant da chave — o filtro cnpj não vaza dados de outros tenants.

Exemplo de chamada

curl -H "Authorization: Bearer ck_SUA_CHAVE" \
  "https://srv1634928.hstgr.cloud/api/v1/divergencias?since=2026-07-01&take=100"

Resposta 200 (resumida)

{
  "meta": { "since": "2026-07-01T00:00:00.000Z", "cnpj_filtro": null, "total": 3, "truncado": false, ... },
  "data": [
    {
      "xml_id": "cl9z4...",
      "tipo": "NFE",
      "chave_acesso": "50260731920542000106550010000012341000012349",
      "numero": "1234",
      "serie": "1",
      "emissor": { "cnpj": "31920542000106", "razao_social": "Distribuidora X LTDA" },
      "destinatario": { "cnpj": "11222333000144", "razao_social": "Mercado Y LTDA" },
      "data_emissao": "2026-07-05T10:12:00.000Z",
      "valor_total": 4520.80,
      "total_divergencias": 2,
      "importado_em": "2026-07-05T10:15:33.000Z",
      "itens_com_divergencia": [
        {
          "ean": "7894900664003",
          "codigo_produto": "A2",
          "descricao": "Refresco lata 350ml",
          "divergencias_detectadas": ["ncm", "aliq_icms"],
          "cliente":   { "ncm": "22021000", "cest": "03.007.00", "cfop": "5405", "aliq_icms": 12 },
          "confisped": { "ncm": "22021000", "cest": "03.007.00", "cfop": "5405", "aliq_icms": 17 },
          "recorrente": true,
          "resolvido": false
        }
      ]
    }
  ]
}

Cada XML retorna no máximo 50 itens divergentes. XMLs sem divergência não aparecem na lista.

Lista produtos (do seu tenant + base global) que precisam de revisão fiscal — status REVISAR ou PENDENTE. Cada item traz o motivo_revisao (aguardando classificação, confiança baixa, sem NCM etc.).

Query params (opcionais)

Exemplo de chamada

curl -H "Authorization: Bearer ck_SUA_CHAVE" \
  "https://srv1634928.hstgr.cloud/api/v1/revisoes?status=PENDENTE&take=100&skip=0"

Resposta 200 (resumida)

{
  "meta": {
    "total": 248,        /* total geral pro filtro (independente da página) */
    "take": 100,
    "skip": 0,
    "truncado": true,    /* true = tem mais páginas; incremente o skip */
    ...
  },
  "data": [
    {
      "id": "cl8p3...",
      "ean": "7894900664003",
      "codigo_interno": "A2",
      "descricao": "Refresco lata 350ml",
      "ncm": null,
      "cest": null,
      "status": "PENDENTE",
      "confianca": null,
      "escopo": "cliente",
      "motivo_revisao": "Aguardando classificação inicial",
      "criado_em": "2026-07-08T09:00:00.000Z",
      "atualizado_em": "2026-07-08T09:00:00.000Z"
    }
  ]
}

Webhook de NF-e em tempo real — seu ERP/retaguarda empurra o XML da nota assim que emite/recebe, e o Monitoramento Confisped processa na mesma engine do upload manual e do Cofre, detectando divergências fiscais item a item. Idempotente: a chave de acesso da NF-e é única — reenviar o mesmo XML retorna 200 duplicado sem reprocessar.

Body — dois formatos aceitos

⚠ Limite: 10 MB por request · 1 XML por chamada.

Exemplo de chamada

# XML direto no body
curl -X POST -H "Authorization: Bearer ck_SUA_CHAVE" \
  -H "Content-Type: text/xml" \
  --data-binary @nota-fiscal.xml \
  "https://srv1634928.hstgr.cloud/api/v1/monitoramento/xml"

# ou wrapper JSON
curl -X POST -H "Authorization: Bearer ck_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"xml":"<nfeProc>...</nfeProc>"}' \
  "https://srv1634928.hstgr.cloud/api/v1/monitoramento/xml"

Resposta 201 (XML processado)

{
  "meta": { ... },
  "data": {
    "ok": true,
    "xml_id": "cl9z4...",
    "chave_acesso": "50260731920542000106550010000012341000012349",
    "numero_documento": "1234",
    "tipo": "NFE",
    "total_itens": 18,
    "total_divergencias": 2,
    "mensagem": "XML processado com 2 divergência(s) fiscal(is) detectada(s)."
  }
}

Resposta 200 (duplicado — idempotência)

{
  "meta": { ... },
  "data": {
    "ok": true,
    "duplicado": true,
    "xml_id": "cl9z4...",
    "chave_acesso": "50260731920542000106550010000012341000012349",
    "mensagem": "XML já foi importado anteriormente (idempotência por chave de acesso)."
  }
}

Erros específicos

Consulta apuração CBS oficial (Receita Federal) do CNPJ informado, competência informada. Disponível só pra CNPJs com procuração e-CAC ativa outorgada à Confisped. Vigência prática: a partir de jul/2026 quando a Plataforma RTC entrar em produção.

Query params

Exemplo de chamada

curl -H "Authorization: Bearer ck_SUA_CHAVE" \
  "https://srv1634928.hstgr.cloud/api/v1/apuracao/cbs?cnpj=31920542000106&competencia=2026-08"

Resposta 200 (resumida)

{
  "meta": { ... },
  "data": {
    "cnpj": "31920542000106",
    "competencia": "2026-08",
    "status": "APURADO",
    "debito_total": 12340.55,
    "credito_total": 8210.30,
    "saldo_devedor": 4130.25,
    "fonte": "Receita Federal RTC",
    "consultado_em": "2026-09-15T10:00:00Z",
    "itens": [ /* detalhamento por operação */ ]
  }
}

Erros específicos