IValida Conecta — integração direta com o seu ERP

Autenticação

Toda chamada leva a chave no cabeçalho Authorization. A chave começa com iv_, é criada por um usuário logado na página Conta e API e aparece uma única vez: guardamos só um resumo criptográfico (hash) dela e os 9 primeiros caracteres (prefixo), para você reconhecê-la. Use uma chave por sistema, guarde-a no cofre de segredos do sistema (nunca no código-fonte) e troque ou revogue na mesma página, com efeito imediato.

Authorization: Bearer iv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A chave herda o aceite dos Termos de Uso e do Acordo de Tratamento de Dados feito por quem a criou. Quando publicarmos nova versão desses documentos (com aviso prévio), a chave responde 428 até alguém da conta aceitar a nova versão em Conta e API. Use sempre HTTPS: a API não aceita o login do navegador, só a chave.

Conferir uma nota antes de transmitir

POST https://app.ivalida.com.br/api/v1/pre-emissao com um XML no corpo (Content-Type: application/xml) ou um arquivo no campo arquivos de um multipart/form-data. Aceita NF-e (55), NFC-e (65), CT-e (57/67) e DPS/NFS-e do padrão nacional; um XML por chamada, assinado ou não.

curl -sS https://app.ivalida.com.br/api/v1/pre-emissao \
  -H "Authorization: Bearer $IVALIDA_CHAVE" \
  -H "Content-Type: application/xml" \
  --data-binary @nota.xml

Resposta (resumida):

{
  "veredito": "REJEITARIA",
  "pode_emitir": false,
  "resumo": "A SEFAZ deve rejeitar esta nota. Corrija antes de transmitir.",
  "documento": {"tipo": "NFE", "numero": "1001", "serie": "1", "emissao": "2026-09-15T10:00:00-03:00", "itens": 1},
  "rejeicoes_previstas": [
    {"regra": "R044", "severidade": "ERRO", "titulo": "vCBS difere do calculado", "item": 1,
     "campo": "gCBS/vCBS", "informado": "5.00", "esperado": "0.90", "cstat": ["1069"],
     "mensagem": "...", "como_corrigir": "..."}
  ],
  "riscos": [],
  "erros": [],
  "nao_verificado": ["..."],
  "sha256": "...",
  "base": {"motor": "0.3.0", "versao": "...", "conferido_em": "...", "nt": "...", "tabela": "..."}
}

Conferir um lote de notas

POST https://app.ivalida.com.br/api/v1/validar com multipart/form-data: um ou mais XMLs ou .zip no campo arquivos. Campos opcionais: perfil, mascarar (padrão 1: chave de acesso e nome do arquivo mascarados), identificar, carteira (CNPJs separados por vírgula) e formato (json, csv ou html). A resposta é o relatório completo do lote, o mesmo da tela do validador.

curl -sS https://app.ivalida.com.br/api/v1/validar \
  -H "Authorization: Bearer $IVALIDA_CHAVE" \
  -F "arquivos=@notas-outubro.zip"

Para enviar automaticamente as notas que chegam numa pasta, há um script em Python, só com a biblioteca padrão, que respeita os limites abaixo (scripts/enviar_pasta.py, enviado a pedido).

Erros

Erros vêm em JSON: {"erro": "mensagem em português"}.

Limites

• Por chave: chamadas por minuto e tamanho máximo por chamada definidos pelo plano da conta (mostrados em Conta e API; hoje de 30 a 240 chamadas por minuto e de 10 a 30 MB), e até 2 chamadas simultâneas. As respostas às chamadas com chave válida que passam pelo limite de taxa (inclusive a 429) trazem X-RateLimit-Limit e X-RateLimit-Remaining; as recusadas antes dele (401, 403, 413, 428) não trazem.
• Por conta: documentos por mês definidos pelo plano (navegador e API somados).
• Por XML: até 5 MB, 10.000 itens; por lote: até 500 arquivos, 5.000 documentos e 120 segundos de processamento.

Versões

O caminho /api/v1/ é estável: campos novos podem ser acrescentados às respostas, e o seu sistema deve ignorar campos que não conhece. Remover ou mudar o sentido de um campo só acontece numa nova versão (/api/v2/), avisada com antecedência, com a v1 mantida por um período de transição. As regras de IBS/CBS mudam com as Notas Técnicas: cada resposta traz em base a versão do motor e a data da base de regras, e as mudanças ficam no histórico de regras.

Privacidade

• Os XMLs são processados em memória, no Brasil (Google Cloud, São Paulo), e não são guardados; a resposta também não.
• Da conta de API guardamos só o e-mail de quem a usa, o nome e o resumo criptográfico de cada chave, as versões aceitas dos documentos legais e contadores de uso por mês. Detalhes, prazos e exclusão: Política de Privacidade.
• Cada chamada gera um registro técnico (data, conta, prefixo da chave, caminho, código de resposta, quantidade de documentos e duração), sem conteúdo das notas.
• Nos dados pessoais das notas, a sua empresa é a controladora e o IValida é operador (Acordo de Tratamento de Dados).

O que a API não cobre

A conferência é automatizada e baseada na documentação oficial (cada achado cita a fonte). Ela não assegura que a SEFAZ vá autorizar a nota, não cobre outras rejeições (cadastro, duplicidade, certificado, ICMS) e não é parecer fiscal. "Rejeitaria" é uma previsão a partir das regras publicadas, que podem mudar a cada versão da Nota Técnica. Não há acordo de nível de serviço enquanto não houver contratação paga (Termos de Uso).