Comece agora
com a Webmania®
Conheça as soluções Webmania® para o seu negócio e escolha a ideal para sua operação.
Conversar no WhatsAppConsulte condições e serviços disponíveis.
Conheça as soluções Webmania® para o seu negócio e escolha a ideal para sua operação.
Conversar no WhatsAppConsulte condições e serviços disponíveis.
Nossa IA proprietária combina tecnologias da OpenAI, Anthropic e Google Gemini para processar NF-e, NFC-e e NFS-e, detectando manipulações e fraudes automaticamente. Resposta em JSON estruturado com tempo médio de processamento entre ~25s e ~2min (conforme modalidade), com consulta direta na SEFAZ e integração nativa com Serpro.
Imagem, PDF ou XML
IA proprietária
SEFAZ e Antifraude
JSON estruturado
Ideal para sistemas de fidelização e cashback que precisam validar cupons fiscais de forma rápida e segura:
Solução completa para instituições financeiras que precisam validar documentos fiscais para análise de crédito:
Mantenha sua empresa em conformidade fiscal com validação contínua de documentos:
Automatize a conferência de documentos fiscais para liberação segura de pagamentos:
Nossa tecnologia proprietária de Inteligência Artificial realiza análises avançadas para identificar indícios de manipulação ou adulteração em documentos fiscais já emitidos.
O sistema avalia aspectos visuais e estruturais do documento, identificando automaticamente sinais de fraude e garantindo uma validação confiável para empresas e operações fiscais. Além da análise técnica do documento, nossa solução realiza checagens diretas junto a fontes oficiais para confirmar sua autenticidade e validade.
Essa estrutura multicamadas proporciona uma taxa excepcional de acerto na detecção de irregularidades acima de 99%, protegendo as empresas contra fraudes e assegurando total conformidade fiscal.
Adotamos uma política rigorosa de privacidade e proteção de dados.
Seus documentos fiscais não são utilizados para treinar nossos modelos de IA, garantindo total confidencialidade das informações processadas. Implementamos uma política de Zero Retenção de Dados (ZDR), onde todos os dados são processados em memória volátil e descartados imediatamente após a conclusão da validação.
Os resultados das validações ficam disponíveis em cache por um período máximo de 72 horas apenas para consulta via UUID, sendo automaticamente eliminados após esse prazo.
Todas as solicitações devem ser realizadas em ambiente criptografado HTTPS através da URL https://api.webmania.com.br/. O prefixo /2/validador/ identifica os endpoints de validação por Inteligência Artificial (v2.0). Para consultas de créditos, utilize /2/creditos.
A tabela abaixo lista todos os endpoints disponíveis na API:
| Endpoint | Método | Descrição |
|---|---|---|
/2/validador/dfe/imagem | POST | Validação de documentos fiscais a partir de imagem ou PDF |
/2/validador/dfe/xml | POST | Validação de documentos fiscais a partir do XML |
/2/validador/conexoes/serpro | POST | Cadastrar conexão com a SERPRO |
/2/validador/logs/{uuid} | GET | Consulta da validação pelo UUID retornado |
/2/creditos | GET | Consulta saldo de créditos e logs de consumo |
/2/creditos/recargas | GET | Lista recargas realizadas |
/2/validador/conexoes/serpro | GET | Listar conexão com a SERPRO |
/2/validador/conexoes/serpro | DELETE | Remover conexão com a SERPRO |
Sempre envie o corpo da requisição no formato JSON, e o cabeçalho Content-Type deve estar definido como application/json.
Todas as respostas são no formato objeto JSON.
Para as solicitações o corpo da requisição [body] deve ser enviado no formato JSON com o header Content-Type definido para application/json.
A autenticação é realizada através do cabeçalho HTTP (HTTP headers). É necessário o envio do X-Token, que deve ser obtido com os especialistas da Webmania® e incluído em todas as requisições.
Mantenha suas credenciais em segurança. Nunca publique o X-Token no código-fonte do site, aplicativo ou sistema onde ele possa ser facilmente acessado por terceiros.
Para aplicativos móveis (iOS e Android), recomendamos que a consulta à API seja realizada no servidor (back-end). O código-fonte do aplicativo deve apenas enviar a requisição enquanto o processamento da consulta deve ocorrer no seu servidor.
Todas as respostas da API são entregues em JSON, mantendo padronização e clareza.
A tabela abaixo resume os códigos HTTP possíveis, indicando o resultado do processamento da solicitação.
| Código | Significado | Sucesso | Descrição |
|---|---|---|---|
200 | OK | Consulta concluída com êxito. | |
400 | Bad Request | Parâmetros sintaticamente inválidos. | |
401 | Unauthorized | Falha de autenticação, verifique o token enviado no cabeçalho. | |
404 | Not Found | Empresa não localizada para o cliente autenticado. | |
422 | Unprocessable Entity | Payload válido sintaticamente, mas com dados inviáveis (ex.: certificado expirado ou payload sem campos obrigatórios). |
Exemplo de resposta para uma requisição com erro:
{
"error": "bad_request",
"message": "Parâmetro 'chave' deve conter 44 dígitos."
}
Validações de Documentos Fiscais com IAEsta seção abrange todas as operações relacionadas à validação de documentos fiscais através de Inteligência Artificial. Nossa API utiliza tecnologia proprietária de IA para extrair e validar informações de documentos fiscais a partir de imagens, PDFs ou XMLs, oferecendo diferentes métodos de validação e formatos de retorno.
ℹ️ Documentos suportados:
⏱️ Tempos médios e créditos: Os valores abaixo são médias e podem variar conforme qualidade da imagem, quantidade de páginas/itens e carga do processamento. A tabela considera validação por imagem/PDF.
| Modalidade | Parâmetros | Tempo médio | Créditos |
|---|---|---|---|
| Pré-validação (triagem) | pre_validacao: true | ~25s | 0.25 (fixo) |
| OCR Inteligente (sem antifraude) | antifraude: false | ~60s | 1.00 (média) |
| OCR + Antifraude (validação completa) | antifraude: true (padrão) | ~2min | ≥ 2.50 (média) |
A pré-validação é utilizada para identificar se a imagem é um documento fiscal, o modelo do documento fiscal e a chave (quando aplicável aos modelos NF-e, NFC-e e NF3-e).
Principais benefícios:
Para realizar a pré-validação, envie a requisição no método POST para a URL /valida/dfe/imagem com o parâmetro pre_validacao definido como true:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
pre_validacao | boolean | Define se a requisição é uma pré-validaçãotrue | |
imagens | array | URL das imagens do documento fiscalExemplo: ["https://exemplo.com/documento.jpg"] | |
url_notificacao | string | URL do webhook para envio das notificações |
Segue abaixo exemplo de requisição de pré-validação:
curl --location 'https://prod-yoda.api.webmania.cloud/2/validador/dfe/imagem?bypass_cache=1&debug=0' \
--header 'X-Token: SEU_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"pre_validacao": true,
"imagens": [
"https://exemplo.com/documento-fiscal.jpg"
],
"url_notificacao": "https://exemplo.com/webhook"
}'Exemplo de resposta da pré-validação para uma NFC-e:
| Campo | Tipo | Descrição |
|---|---|---|
uuid | string | Identificador único da requisição |
modelo | string | Modelo do documento fiscal identificadoNF-e, NFC-e, NFS-e ou NF3-e |
documento_fiscal | boolean | Indica se a imagem contém um documento fiscal válidotrue/false |
chave | string | Chave de acesso do documentoQuando aplicável aos modelos NF-e, NFC-e e NF3-e |
score_ocr | float | Pontuação de confiança do OCR0 (pouco confiável) a 1 (muito confiável) |
creditos | float | Quantidade de créditos utilizados na operação |
{
"uuid": "a97117dd-f8c4-49a6-9fac-df6de3832972",
"modelo": "nfce",
"documento_fiscal": true,
"chave": "41250878116670003180650210000481251007540526",
"score_ocr": 0.52,
"creditos": 0.25
}A validação por imagem permite enviar documentos fiscais em formato de imagem para análise através de nossa Inteligência Artificial. Você pode enviar as imagens através de URLs públicas ou fazer upload direto dos arquivos.
⚠️ Especificações importantes:
Envie URLs públicas de imagens do documento fiscal para validação. Ideal para documento já hospedado em servidores ou sistemas externos.
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
imagens | array | URL das imagens de um único documento fiscalExemplo: ["https://exemplo.com/nfe1.jpg", "https://exemplo.com/nfe2.png"] | |
modelo | string | Modelo do documentonfe | |
formato | string | Formato do retornojson (padrão) | |
assincrono | boolean | Processamento assíncronoPara mais de uma imagem o processo é sempre assíncrono. | |
url_notificacao | string | URL do webhook para envio das notificações | |
serpro | boolean | Ativa validação adicional via Serpro (requer credenciais cadastradas) | |
antifraude | boolean | Ativa/desativa as análises antifraudetrue (padrão) |
Segue abaixo exemplo do envio de uma única imagem:
curl -X POST https://api.webmania.com.br/2/validador/dfe/imagem \
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"imagens": ["https://exemplo.com/documento-fiscal.jpg"],
"modelo": "nfe"
}'Segue abaixo exemplo com validação Serpro ativada:
curl -X POST https://api.webmania.com.br/2/validador/dfe/imagem \
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"imagens": ["https://exemplo.com/documento-fiscal.jpg"],
"modelo": "nfe",
"serpro": true
}'Segue abaixo exemplo com OCR Inteligente (antifraude desativado):
curl -X POST https://api.webmania.com.br/2/validador/dfe/imagem \
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"imagens": ["https://exemplo.com/documento-fiscal.jpg"],
"modelo": "nfe",
"antifraude": false
}'Segue abaixo exemplo do envio de múltiplas imagens do mesmo documento fiscal:
curl -X POST https://api.webmania.com.br/2/validador/dfe/imagem \
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"imagens": [
"https://exemplo.com/nfe-001-pagina1.jpg",
"https://exemplo.com/nfe-001-pagina2.jpg",
"https://exemplo.com/nfe-002.pdf"
],
"modelo": "nfe",
"assincrono": true
}'Envie o conteúdo da imagem/PDF em base64 no padrão Data URI. Este método é útil quando você não possui uma URL pública para o arquivo.
ℹ️ Dica: Para arquivos grandes, prefira Upload (multipart) ou URL pública, pois o payload base64 pode aumentar significativamente o tamanho da requisição.
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
imagens | array | Lista de Data URIs base64 do documento fiscalEx.: ["data:image/jpeg;base64,/9j/4AAQSkZJRg...=="] | |
modelo | string | Modelo do documentonfe | |
formato | string | Formato do retornojson (padrão) | |
assincrono | boolean | Processamento assíncronoPara mais de uma imagem o processo é sempre assíncrono. | |
url_notificacao | string | URL do webhook para envio das notificações | |
serpro | boolean | Ativa validação adicional via Serpro (requer credenciais cadastradas) | |
antifraude | boolean | Ativa/desativa as análises antifraudetrue (padrão) |
Segue abaixo exemplo de requisição via base64:
curl -X POST https://api.webmania.com.br/2/validador/dfe/imagem \
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"imagens": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...=="],
"modelo": "nfce"
}'Para utilizar OCR Inteligente via base64 (sem antifraude), inclua o parâmetro antifraude:
curl -X POST https://api.webmania.com.br/2/validador/dfe/imagem \
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"imagens": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...=="],
"modelo": "nfce",
"antifraude": false
}'Faça upload direto de arquivos de imagem para validação. Suporta envio único ou múltiplo através de multipart/form-data.
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
imagens[] | file[] | Caminho das imagens de um único documento fiscalFormatos: JPG, PNG ou PDF | |
modelo | string | Modelo do documentonfe | |
formato | string | Formato do retornojson (padrão) | |
assincrono | boolean | Processamento assíncronoPara mais de uma imagem o processo é sempre assíncrono. | |
url_notificacao | string | URL do webhook para envio das notificações | |
serpro | boolean | Ativa validação adicional via Serpro (requer credenciais cadastradas) | |
antifraude | boolean | Ativa/desativa as análises antifraudetrue (padrão) |
Segue abaixo exemplo do envio de uma única imagem:
curl -X POST https://api.webmania.com.br/2/validador/dfe/imagem \
-H "X-Token: SEU_ACCESS_TOKEN" \
-F "imagens[]=@/caminho/para/documento.jpg" \
-F "modelo=nfe"Para utilizar OCR Inteligente via upload (sem antifraude), inclua o parâmetro antifraude:
curl -X POST https://api.webmania.com.br/2/validador/dfe/imagem \
-H "X-Token: SEU_ACCESS_TOKEN" \
-F "imagens[]=@/caminho/para/documento.jpg" \
-F "modelo=nfe" \
-F "antifraude=false"Segue abaixo exemplo do envio de múltiplas imagens do mesmo documento fiscal:
curl -X POST https://api.webmania.com.br/2/validador/dfe/imagem \
-H "X-Token: SEU_ACCESS_TOKEN" \
-F "imagens[]=@/caminho/para/nfe-001.jpg" \
-F "imagens[]=@/caminho/para/nfe-002.png" \
-F "imagens[]=@/caminho/para/nfe-003.pdf" \
-F "modelo=nfe"Valide a autenticidade dos documentos fiscais enviando o XML completo dos modelos NF-e, NFS-e, CT-e e MDF-e. A inteligência artificial verifica a integridade do XML, garantindo que não haja modificações ou adulterações.
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
xml | base64 | Conteúdo do XML codificado em base64 | |
formato | string | Formato do retornojson (padrão) | |
assincrono | boolean | Processamento assíncrono | |
url_notificacao | string | URL do webhook para envio das notificações | |
serpro | boolean | Ativa validação adicional via Serpro (requer credenciais cadastradas) |
Segue abaixo exemplo de requisição para validação do XML:
curl -X POST https://api.webmania.com.br/2/validador/dfe/xml \
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"xml": "PG5mZVByb2MgdmVyc2FvPSI0LjAwIiB4bWxucz0iaHR0cDovL3d3dy4..."
}'A API suporta dois formatos de retorno para atender diferentes necessidades de integração:
{
"uuid": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
"status": "aprovado",
"chave": "35250812345678000190550010001234560123456789",
"protocolo": "235251498765432",
"data_emissao": "15/10/2025 14:30:22",
"numero": "123456",
"serie": 1,
"total": "342.87",
"emitente": {
"cnpj": "12.345.678/0001-90",
"razao_social": "SUPERMERCADO BOM PREÇO LTDA",
"endereco": "RUA DAS FLORES",
"numero": "1500",
"bairro": "CENTRO",
"cidade": "SÃO PAULO",
"uf": "SP"
},
"consumidor": {
"cpf": "XXX.XXX.123-45"
},
"produtos": [
{
"nome": "SUCO DE LARANJA INTEGRAL",
"item": "1",
"ean": "07891234567890",
"quantidade": "2",
"unidade": "UN",
"valor_unitario": "18,50",
"subtotal": "37.00",
"total": "37.00"
},
{
"nome": "FILE DE FRANGO",
"item": "2",
"quantidade": "1.500",
"unidade": "KG",
"valor_unitario": "24,90",
"subtotal": "37.35",
"total": "37.35"
},
{
"nome": "PEITO DE FRANGO",
"item": "3",
"quantidade": "0.950",
"unidade": "KG",
"valor_unitario": "19,90",
"subtotal": "18.91",
"total": "18.91"
},
{
"nome": "SORVETE CHOCOLATE 2L",
"item": "4",
"ean": "07899876543210",
"quantidade": "1",
"unidade": "UN",
"valor_unitario": "39,90",
"subtotal": "39.90",
"total": "39.90"
},
{
"nome": "PICANHA GRELHADA",
"item": "5",
"quantidade": "0.380",
"unidade": "KG",
"valor_unitario": "89,90",
"subtotal": "34.16",
"total": "34.16"
},
{
"nome": "PICANHA GRELHADA",
"item": "6",
"quantidade": "0.420",
"unidade": "KG",
"valor_unitario": "89,90",
"subtotal": "37.76",
"total": "37.76"
},
{
"nome": "ALCATRA ASSADA",
"item": "7",
"quantidade": "0.315",
"unidade": "KG",
"valor_unitario": "69,90",
"subtotal": "22.02",
"total": "22.02"
},
{
"nome": "LASANHA QUATRO QUEIJOS",
"item": "8",
"quantidade": "0.580",
"unidade": "KG",
"valor_unitario": "59,90",
"subtotal": "34.74",
"total": "34.74"
},
{
"nome": "BOLO DE CHOCOLATE PREMIUM",
"item": "9",
"ean": "07891122334455",
"quantidade": "1",
"unidade": "UN",
"valor_unitario": "42,90",
"subtotal": "42.90",
"total": "42.90"
},
{
"nome": "REFRIGERANTE COLA 2L",
"item": "10",
"ean": "07895544332211",
"quantidade": "3",
"unidade": "UN",
"valor_unitario": "12,71",
"subtotal": "38.13",
"total": "38.13"
}
],
"pagamento": [
{
"forma_pagamento": "Cartao de Debito",
"valor_pagamento": "342.87"
}
],
"informacoes_complementares": "Tributos Incid. Lei Federal 12.741/12 R$ 89,45 N:02345 O:056789 E:098765-000123 Trib Municipais aprox Trib Federais aprox: 45.23 (13,19%) Trib Estaduais 44,22 (12,89%) Operador CAIXA 05 Programa de Fidelidade Voce ganhou 34 pontos. 15/10/2025 LJ:00001 PDV:005 C00:098765",
"analise_fraude": {
"score_fraude": 0.15,
"score_ocr": 0.62,
"analises": [
{
"codigo": "qr_partial_occlusion",
"gravidade": "medio",
"evidencia": "O QR Code está parcialmente coberto por um carimbo, mas a URL de consulta 'http://www.fazenda.pr.gov.br/nfce/consulta' está legível."
},
{
"codigo": "blurry_image",
"gravidade": "baixo",
"evidencia": "Desfoque perceptível."
}
]
},
"creditos": 2.50
}{
"uuid": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
"modelo": "nfe",
"status": "aprovado",
"chave": "35250887654321000145550010001111120987654321",
"protocolo": "335250498765432",
"data_emissao": "05/10/2025 14:25:15",
"numero": "111112",
"serie": 1,
"data_saida": "05/10/2025 14:25:14",
"emitente": {
"cnpj": "87654321000145",
"razao_social": "PAPELARIA MODERNA LTDA",
"nome_fantasia": "MODERNA OFFICE",
"endereco": "Rua das Palmeiras",
"numero": "456",
"complemento": "Loja A",
"bairro": "Centro",
"cep": "12345-678",
"cidade": "Santos",
"uf": "SP",
"ie": "123456789",
"telefone": "1334567890"
},
"consumidor": {
"cpf": "111.222.333-44",
"nome": "Maria Oliveira Costa",
"endereco": "Avenida Brasil",
"numero": "2580",
"complemento": "Bloco 3 Apto 205",
"bairro": "Jardim Paulista",
"cep": "13400-123",
"cidade": "Piracicaba",
"uf": "SP",
"ie": "98765432109",
"email": "exemplo@email.com"
},
"produtos": [
{
"nome": "Organizador de Escritório Premium",
"codigo": "1",
"ncm": "48219000",
"cfop": "5102",
"quantidade": "2",
"unidade": "UN",
"subtotal": "223.44",
"total": "223.44",
"desconto": "6.28",
"icms": {
"cst": "0102",
"base_calculo": "0.00",
"aliquota": "0.00",
"valor": "0.00"
},
"ipi": {
"aliquota": "0.00",
"valor": "0.00"
},
"item": "1",
"informacoes_adicionais": "LABELS: 1-ORGANIZADOR-MESA-PREMIUM"
}
],
"totais": {
"bc_icms": "0.00",
"valor_icms": "0.00",
"bc_icms_st": "0.00",
"valor_icms_substituto": "0.00",
"valor_produtos": "236.00",
"valor_frete": "15.24",
"valor_seguro": "0.00",
"valor_descontos": "12.56",
"valor_ipi": "0.00",
"valor_pis": "0.00",
"valor_cofins": "0.00",
"outras_despesas_acessorias": "0.00",
"valor_total": "238.68",
"valor_aproximado_tributos": "79.84",
"detalhamento_tributos_aproximados": {
"valor_federal": "32.10",
"percentual_federal": "13.45",
"valor_estadual": "47.74",
"percentual_estadual": "20.00",
"fonte": "IBPT"
}
},
"transporte": {
"modalidade_frete": 0,
"peso_liquido": "1.040",
"peso_bruto": "1.040"
},
"informacoes_adicionais": "Inf. Contribuinte: Conf. Lei 12.741/2012 Tributação aprox. R$32.10 (13.45%) Federal e R$47.74 (20.00%) Estadual - Fonte IBPT / Não recolhimento do diferencial por força da ADI 5464 / NÚMERO DO PEDIDO: 7654321 / / Email do Destinatário: mariaoliveira@email.com",
"natureza_operacao": "Venda de mercadoria adquirida de terceiros",
"operacao": 1,
"numero_pedido": "7654321",
"analise_fraude": {
"score_fraude": 0,
"score_ocr": 0.7,
"analises": []
},
"total": "238.68",
"creditos": 2.50
}Formato simplificado e legível, ideal para aplicações de mensageria, chatbots e integração com WhatsApp.
Para utilizar este formato de retorno, é obrigatório informar o parâmetro url_notificacao na requisição, pois o resultado será enviado via webhook para a URL especificada em formato JSON, contendo o UUID da requisição e todos os parâmetros originais, incluindo o campo texto com o conteúdo formatado e pronto para ser enviado diretamente ao usuário final, sem necessidade de formatação adicional.
Segue abaixo exemplo de retorno da validação de uma NF-e:
📄 **DOCUMENTO FISCAL VALIDADO**
✅ Status: APROVADO
📋 Tipo: Nota Fiscal Eletrônica (NF-e)
🏢 **EMITENTE**
• Razão Social: Empresa Exemplo LTDA
• CNPJ: 12.345.678/0001-95
• Nome Fantasia: Exemplo Store
• UF: SP
👤 **DESTINATÁRIO**
• Nome: João da Silva
• CPF: 123.456.789-09
• Cidade: São Paulo - SP
📊 **DADOS DA NOTA**
• Número: 12345 - Série: 1
• Data Emissão: 15/03/2024 14:30:00
• Valor Total: R$ 1.500,00
🛍️ **PRODUTOS**
1. Notebook Pro 15 (1 UN) - R$ 1.500,00
💳 **PAGAMENTO**
• Cartão de Crédito: R$ 1.500,00
🔐 **VALIDAÇÃO**
• Chave de Acesso: 3524 0312 3456 7800 0195 5500 1000 0123 4512 3456 7890
• Protocolo: 135240001234567Quando o parâmetro assincrono é definido como true, a API retorna imediatamente um UUID para acompanhamento do processamento, que após a execução é enviado na url_notificacao. O modo assíncrono é indicado para alto volume de requisições, quando o tempo de resposta não é fator crítico.
Para ações que exigem processamento em tempo real, utilize o modo síncrono, com tempo médio de processamento variável conforme a modalidade: pré-validação (~25s), OCR Inteligente (~60s) e OCR + antifraude (~2min). Por padrão, o parâmetro assincrono é false em todas as requisições, exceto quando é enviado mais de uma imagem do documento fiscal (neste caso, o processamento é sempre assíncrono).
Segue exemplo de resposta de requisição assíncrona:
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"status": "processando"
}Consulte o status e resultado de uma requisição através do UUID retornado em processamentos assíncronos. Este endpoint permite acompanhar o progresso da validação e recuperar os dados processados quando concluído.
⚠️ Importante: A Webmania® não armazena os dados em banco de dados persistente. O UUID é mantido em memória volátil (cache) por até 72 horas, podendo ser removido antes desse prazo em caso de reinicialização do sistema ou expiração do cache.
Para realizar a consulta de um UUID, envie a requisição no método GET para a URL /valida/logs/{uuid}. Segue abaixo exemplo da consulta UUID:
curl -X GET \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmania.com.br/2/validador/logs/550e8400-e29b-41d4-a716-446655440000Aprimore as validações de documentos fiscais com conexões que fornecem dados adicionais e que aumentam a conectividade da validação com a Webmania®.
A integração com Serpro permite validação adicional de NF-e diretamente na SEFAZ, fornecendo informações atualizadas sobre situação e eventos do documento. Esta integração proporciona uma camada extra de segurança e confiabilidade nas validações.
Consulta direta na base da SEFAZ através do Serpro, incluindo documentos com mais de 180 dias de emissão.
Acesso a todos os eventos registrados do documento, incluindo cancelamentos e cartas de correção.
Segue abaixo as informações adicionais retornadas pela conexão com o Serpro:
| Informação | Descrição Detalhada |
|---|---|
| Código EAN | EAN de todos os produtos listados no documento, com ou sem GTIN cadastrado |
| Protocolo de Autorização | Número único do protocolo emitido pela SEFAZ no momento da autorização |
| Data/Hora de Autorização | Momento exato em que o documento foi autorizado pela SEFAZ |
| Situação Atual | Status em tempo real do documento na SEFAZ (Autorizada, Cancelada, Denegada, etc.) |
| Eventos Registrados | Histórico completo de todos os eventos: cancelamentos, cartas de correção, manifestações |
| Digest Value | Hash criptográfico único do documento para verificação de integridade e autenticidade |
| Validações Complementares | Verificação automática de CNPJs, cálculo de valores e conformidade fiscal completa |
⚠️ Pré-requisito: Você precisa ter credenciais válidas do Serpro (consumer_key e consumer_secret) para utilizar esta integração. Entre em contato com o Serpro para obter suas credenciais.
Configure suas credenciais Serpro para habilitar validação adicional do modelo NF-e (único modelo suportado). As credenciais são armazenadas de forma segura e criptografada.
Para cadastrar as credenciais da Serpro, envie a requisição no método POST para a URL /valida/conexoes/serpro. Segue abaixo exemplo de cadastro das credenciais:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
consumer_key | string | Chave de acesso fornecida pelo Serpro | |
consumer_secret | string | Chave secreta fornecida pelo Serpro |
curl -X POST
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"consumer_key": "SUA_CONSUMER_KEY",
"consumer_secret": "SUA_CONSUMER_SECRET"
}' \
https://api.webmania.com.br/2/validador/conexoes/serproExemplo de resposta do cadastro das credenciais:
{
"status": "cadastrado",
"provedor": "serpro",
"credencial": {
"consumer_key": "SUA_CONSUMER_KEY",
"consumer_secret": "***************"
}
}Para consultar as credenciais da Serpro, envie a requisição no método GET para a URL /valida/conexoes/serpro. Segue abaixo exemplo de consulta das credenciais:
curl -X GET /
-H "X-Token: SEU_ACCESS_TOKEN" /
https://api.webmania.com.br/2/validador/conexoes/serproExemplo de resposta da consulta das credenciais:
{
"provedor": "serpro",
"credencial": {
"consumer_key": "SUA_CONSUMER_KEY",
"consumer_secret": "***************"
}
}Para remover as credenciais da Serpro, envie a requisição no método DELETE para a URL /valida/conexoes/serpro. Segue abaixo exemplo da remoção das credenciais:
curl -X DELETE
-H "X-Token: SEU_ACCESS_TOKEN" /
https://api.webmania.com.br/2/validador/conexoes/serproExemplo de resposta da remoção das credenciais:
{
"status": "removido"
}Para consultar o saldo de créditos e informações do seu plano, envie a requisição no método GET para a URL /2/creditos.
curl -X GET \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmania.com.br/2/creditosA resposta do corpo da mensagem será um objeto JSON contendo o saldo de créditos, dados do plano e um resumo dos logs de consumo:
| Campo | Tipo | Descrição |
|---|---|---|
saldo | float | Créditos disponíveis |
total | float | Total de créditos da recarga/assinatura ativa |
tipo | string | Tipo do planoEx.: pre_pago |
status | string | Status do planoEx.: ativo |
expira_em | string | Data/hora de expiração dos créditos (ISO 8601) |
logs | object | Resumo dos logs de consumo (últimas requisições) |
Exemplo de resposta:
{
"saldo": 123.45,
"total": 1000,
"tipo": "pre_pago",
"status": "ativo",
"expira_em": "2030-12-31T23:59:59-03:00",
"logs": {
"data": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"endpoint": "/2/validador/dfe/imagem",
"metodo": "POST",
"http_code": 200,
"creditos": 2.50,
"data": "2026-01-29T17:30:24-03:00"
}
],
"paginacao": {
"pagina": 1,
"resultados": 50,
"total": 1234,
"total_paginas": 25,
"continua": true
}
}
}Para consultar o histórico de recargas, envie a requisição no método GET para a URL /2/creditos/recargas.
curl -X GET \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmania.com.br/2/creditos/recargasExemplo de resposta:
{
"recargas": [
{
"id": 1,
"tipo": "pre_pago",
"creditos_totais": 1000,
"creditos_utilizados": 200,
"creditos_disponiveis": 800,
"creditos_expirados": 0,
"status": "ativo",
"data": "2024-01-01T00:00:00-03:00",
"expira_em": "2025-01-01T23:59:59-03:00"
}
]
}Otimize o uso da API de Validação de Documentos seguindo estas recomendações essenciais para garantir melhor desempenho e confiabilidade.
💡 Dica de Performance: Para melhor desempenho, processe múltiplos documentos em paralelo usando processamento assíncrono e implemente um sistema de filas para gerenciar grandes volumes de validações.
Número oficial do WhatsApp
📱 (41) 96347-0817
Toda comunicação com o bot de validação deve ser feita exclusivamente neste número. Não há outro canal oficial.
Receba validações de documentos fiscais diretamente por mensagens do WhatsApp. Seus usuários vinculam a conta ao número oficial da Webmania®, enviam a foto, o PDF ou o XML do documento, e o resultado da validação é entregue em tempo real na própria conversa — e, opcionalmente, replicado em um webhook configurável para o seu sistema.
ℹ️ Documentos suportados no WhatsApp:
GET /2/validador/conexoes/whatsapp) e envia pelo WhatsApp para concluir o pareamento.antifraud (padrão) ou ocr_only — ajustável via API.| Etapa | Descrição |
|---|---|
| 1 | Cliente obtém um token de vinculação via API (GET /2/validador/conexoes/whatsapp). |
| 2 | Usuário envia o token pelo WhatsApp para o número oficial da Webmania®. O token tem TTL padrão de 15 minutos. |
| 3 | Após o pareamento, o usuário envia fotos, PDFs ou XMLs fiscais diretamente na conversa. |
| 4 | A Webmania® processa cada arquivo pelo pipeline de validação com IA e responde o resultado no mesmo chat. |
| 5 | Se houver webhook configurado, o mesmo payload é replicado via HTTPS POST no endpoint configurado (ver configuração). |
As próximas subseções detalham cada endpoint de gerenciamento do canal WhatsApp: vinculação, gestão de usuários, webhook de saída, fluxo de mensagens, formato do payload, mensagens de erro e dicas para os usuários finais.
Gere um token de uso único para que o seu usuário final vincule o número de WhatsApp dele à sua conta Webmania®. O usuário envia o token pelo WhatsApp para o número oficial da Webmania® e, após o pareamento, passa a enviar documentos fiscais diretamente no chat.
Número oficial do WhatsApp
📱 (41) 96347-0817
Toda comunicação com o bot de validação deve ser feita exclusivamente neste número. Não há outro canal oficial.
⚠️ Atenção: o token é de uso único e expira em 15 minutos (padrão). Gere um novo token a cada novo vínculo.
Para gerar o token, envie a requisição no método GET para /2/validador/conexoes/whatsapp:
curl -X GET \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/2/validador/conexoes/whatsappExemplo de resposta:
| Campo | Tipo | Descrição |
|---|---|---|
token | string | Token de vinculação de uso único. Deve ser enviado pelo usuário via WhatsApp para o número oficial da Webmania®. |
expira_em | string | Tempo de expiração do tokenEx.: "15 minutos" |
instrucoes | string | Instrução textual para entregar ao usuário final. |
{
"token": "WMB-92F4A1",
"expira_em": "15 minutos",
"instrucoes": "Envie este token via WhatsApp para o numero da Webmania para vincular sua conta."
}💡 Boa prática: personalize a mensagem que o usuário final recebe no seu app/e-mail, incluindo o token e o número oficial da Webmania® no WhatsApp. Isso aumenta a taxa de conclusão do pareamento.
Gerencie os usuários de WhatsApp vinculados à sua conta: liste, bloqueie ou desbloqueie temporariamente, altere o modo de validação (antifraude vs. OCR) ou remova o vínculo definitivamente.
Retorna todos os usuários vinculados à sua conta com o respectivo status e modo de validação. Envie a requisição no método GET para /2/validador/conexoes/whatsapp/usuarios:
curl -X GET \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/2/validador/conexoes/whatsapp/usuariosCampos retornados por usuário:
| Campo | Tipo | Descrição |
|---|---|---|
user_id | string | Identificador interno (Meta Business-Scoped User ID). Use este valor nas rotas subsequentes. |
wa_id | string | Número do WhatsApp no padrão E.164 (ex.: +5511999990000). |
username | string | Nome de exibição do usuário no WhatsApp (pode ser nulo). |
bloqueado | boolean | Indica se o usuário está temporariamente bloqueado de enviar mensagens. |
vinculado_em | string | Data/hora do pareamento (ISO 8601). |
modo | string | Modo de validação ativo para este númeroantifraud (padrão) ou ocr_only |
{
"usuarios": [
{
"user_id": "1234567890",
"wa_id": "+5511999990000",
"username": "Maria Silva",
"bloqueado": false,
"vinculado_em": "2026-04-01T14:05:12-03:00",
"modo": "antifraud"
}
]
}Bloqueia temporariamente um usuário vinculado. Usuários bloqueados continuam na base (o vínculo não é removido), mas as mensagens enviadas por eles não são processadas. Utilize quando quiser suspender o acesso sem perder o histórico do vínculo.
Para bloquear, envie a requisição no método PUT para /2/validador/conexoes/whatsapp/usuarios/{user_id}/bloquear:
curl -X PUT \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/2/validador/conexoes/whatsapp/usuarios/1234567890/bloquearExemplo de resposta:
{
"ok": true,
"status": "bloqueado"
}Para desbloquear, envie a requisição no método PUT para /2/validador/conexoes/whatsapp/usuarios/{user_id}/desbloquear:
curl -X PUT \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/2/validador/conexoes/whatsapp/usuarios/1234567890/desbloquearExemplo de resposta:
{
"ok": true,
"status": "desbloqueado"
}Remove definitivamente o vínculo do usuário com a sua conta. Diferente do bloqueio, a remoção apaga a linha de vínculo — após remover, o usuário precisa gerar um novo token e refazer o pareamento para voltar a enviar documentos.
Envie a requisição no método DELETE para /2/validador/conexoes/whatsapp/usuarios/{user_id}:
curl -X DELETE \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/2/validador/conexoes/whatsapp/usuarios/1234567890Exemplo de resposta:
{
"ok": true
}antifraud vs. ocr_only)Cada usuário vinculado opera em um dos dois modos. O modo controla qual pipeline de IA é executado em cada imagem recebida pelo WhatsApp:
| Modo | Pipeline | Tempo médio | Créditos | Quando usar |
|---|---|---|---|---|
antifraud(padrão) | OCR + Antifraude | ~2min | ≥ 2.50 | Validação completa com análise de fraude, cross-checks fiscais e fingerprint da imagem. Recomendado para compliance, financeiro, premiação e cashback. |
ocr_only | OCR Inteligente | ~60s | 1.00 (média) | Apenas extração dos dados fiscais via OCR, sem análise antifraude. Ideal para bancos com antifraude próprio, alto volume ou cenários onde a velocidade e o custo são prioritários. |
💡 Observação: o modo é por usuário vinculado, não por requisição. Mudanças valem para as próximas mensagens enviadas por aquele número. Para alternância por requisição no canal HTTP, use o parâmetro antifraude: false no corpo da chamada POST /2/valida/dfe/imagem.
Envie a requisição no método GET para /2/validador/conexoes/whatsapp/usuarios/{user_id}/modo:
curl -X GET \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/2/validador/conexoes/whatsapp/usuarios/1234567890/modoExemplo de resposta:
{
"modo": "antifraud"
}Envie a requisição no método PUT para /2/validador/conexoes/whatsapp/usuarios/{user_id}/modo com o novo modo no corpo:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
modo | string | Novo modo de validaçãoantifraud ou ocr_only |
curl -X PUT \
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"modo": "ocr_only"
}' \
https://api.webmaniabr.com/2/validador/conexoes/whatsapp/usuarios/1234567890/modoExemplo de resposta:
{
"ok": true,
"modo": "ocr_only"
}⚠️ Fail-safe: se o modo salvo for inválido ou o campo estiver ausente (por exemplo, durante uma migração), a Webmania® utiliza automaticamente o modo antifraud (padrão). Nenhuma validação é silenciosamente degradada.
Configure uma URL HTTPS para receber, via POST, o mesmo payload que o usuário recebe no WhatsApp a cada documento validado. Use o webhook para persistir os resultados no seu sistema, disparar automações internas ou encadear a validação em fluxos de BPM/ERP.
ℹ️ Paridade com a API: o payload enviado no webhook é idêntico ao retornado pela API HTTP (POST /2/valida/dfe/imagem) para o mesmo documento, após as regras de sanitização pública. Veja a seção Formato do Payload do Webhook para o detalhamento.
| Requisito | Descrição |
|---|---|
| Protocolo | HTTPS obrigatório (certificado SSL válido). Endereços internos (localhost, 127.0.0.1, ranges privados) são rejeitados. |
| Método HTTP | POST |
| Timeout | 10 segundos para a resposta do seu endpoint. |
| Código de Resposta | 200–299 para confirmar o recebimento. |
| Disponibilidade | Acessível publicamente na internet. |
Envie a requisição no método GET para /2/validador/conexoes/whatsapp/webhook:
curl -X GET \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/2/validador/conexoes/whatsapp/webhookExemplo de resposta:
{
"url": "https://seu-sistema.com/webhooks/whatsapp"
}Quando não há webhook configurado, o campo url retorna null.
Envie a requisição no método POST para /2/validador/conexoes/whatsapp/webhook com a nova URL:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
url | string | URL HTTPS pública do endpoint que receberá os webhooks de WhatsApp. |
curl -X POST \
-H "X-Token: SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://seu-sistema.com/webhooks/whatsapp"
}' \
https://api.webmaniabr.com/2/validador/conexoes/whatsapp/webhookExemplo de resposta:
{
"url": "https://seu-sistema.com/webhooks/whatsapp"
}⚠️ URL inválida: URLs que apontam para localhost, 127.0.0.1, 10.0.0.0/8, 172.16.0.0/12 ou 192.168.0.0/16 retornam HTTP 422 com {"error": "invalid_url"}.
Envie a requisição no método DELETE para /2/validador/conexoes/whatsapp/webhook:
curl -X DELETE \
-H "X-Token: SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/2/validador/conexoes/whatsapp/webhookExemplo de resposta:
{
"mensagem": "Webhook removido com sucesso."
}Quando um usuário vinculado envia uma mensagem, a Webmania® processa o conteúdo de acordo com o tipo do anexo. Em todos os casos, o resultado é respondido no próprio chat e, se houver webhook configurado, replicado por HTTPS POST.
| Entrada | Comportamento |
|---|---|
| Foto (JPG/PNG) | Processada pelo pipeline de validação com IA (OCR + antifraude ou OCR apenas, conforme modo do usuário). Aceita NF-e, NFC-e e NFS-e. |
| Processado pelo mesmo pipeline de imagem. Aceita NF-e, NFC-e e NFS-e. | |
| XML | Processado pelo pipeline de XML. Aceita NF-e, NFC-e, NFS-e, CT-e e MDF-e. |
Texto de saudação (oi, ola, ajuda, menu, start, etc.) | O bot responde com a mensagem de boas-vindas listando os documentos aceitos e as dicas de foto (ver dicas). |
Consulta de saldo (ex.: qual meu saldo?) | O bot responde com o saldo de créditos atual da conta do cliente. |
| Outros textos | O bot utiliza IA para interpretar a mensagem e orientar o usuário a enviar um documento fiscal. |
O payload enviado ao endpoint configurado (Webhook de Saída) corresponde ao mesmo objeto JSON retornado pela API HTTP (POST /2/valida/dfe/imagem) para o mesmo documento, após aplicadas as regras de sanitização pública.
✅ Paridade com a API HTTP: não há diferença estrutural entre o payload do webhook e a resposta inline da API. Qualquer sanitização aplicada à resposta pública da API é aplicada ao webhook antes da entrega.
{
"uuid": "d35d0717-d4f1-4d23-897e-c354c5cf991a",
"status": "aprovado",
"modelo": "nfce",
"documento_fiscal": true,
"chave": "41250878116670003180650210000481251007540526",
"protocolo": "141251395911082",
"data_emissao": "31/08/2025 12:25:47",
"numero": "48125",
"serie": "021",
"valor_total": "267.63",
"emitente": {
"cnpj": "78.116.670/0031-80",
"razao_social": "FESTIVAL SUPERMERCADOS LTDA"
},
"produtos": [
{
"nome": "SUCO DE UVA 1L",
"quantidade": "1",
"total": "29.90"
}
],
"creditos": 2.50,
"origem": "whatsapp"
}{
"uuid": "af11c6b2-7c9a-4d2e-b8a1-4b51f7c49a11",
"status": "reprovado",
"documento_fiscal": false,
"error": {
"code": "not_a_fiscal_document",
"message": "A imagem não é um documento fiscal. Envie foto/PDF de NF-e, NFC-e, NFS-e ou XML de NF-e/NFC-e/NFS-e/CT-e/MDF-e."
},
"creditos": 0.25,
"origem": "whatsapp"
}Quando a validação não consegue extrair um documento fiscal utilizável, o bot responde no WhatsApp com uma mensagem formatada (com emojis e quebras de linha) orientando o usuário sobre o que fazer. As mensagens abaixo são determinísticas: não passam por IA, não variam entre execuções.
ℹ️ Códigos de erro: o campo error.code no payload do webhook traz o código técnico correspondente. Use-o para roteamento/automação interna; use a mensagem no WhatsApp (tabela abaixo) para copy de produto.
| Código | Mensagem no WhatsApp |
|---|---|
critical_info_missingInformação crítica ausente | |
illegibleImagem ilegível | |
not_a_fiscal_documentNão é um documento fiscal | |
incomplete_access_keyChave de acesso incompleta | |
low_quality_imageImagem em baixa qualidade | |
generic (fallback)Erro não mapeado | |
⚠️ Outros códigos: códigos como older_than_180_days e resultados com possível fraude (possible_fraud) são considerados resultados válidos da validação, não erros — a formatação da mensagem é feita pela IA conforme o conteúdo retornado.
Estas são as dicas canônicas que o bot envia aos usuários finais na mensagem de boas-vindas. Utilize a mesma orientação na experiência do seu produto (in-app, e-mail, onboarding) para reduzir erros de captura.
O servidores da Webmania estão localizados na Amazon AWS, líder global em cloud computing, na região us-east-1 (Leste dos EUA) com ponto de presença em sa-east-1 (São Paulo). Manter a sua estrutura perto de algumas das duas localidades, garante um menor tempo de resposta nas requisições na API.
Utilizamos uma infraestrutura na Amazon AWS anycast de alta disponibilidade, o que significa que ao se comunicar com API da Webmania a requisição será redirecionada para o servidor mais próximo da sua localidade. As requisições dos endpoints são gerenciados através de IPs estáticos, caso necessite autorize no firewall a comunicação com os IPs abaixo.
IPs estáticos de entrada:A Webmania® aplica um limite de solicitações por segundo e total requisições por mês de acordo com o plano escolhido, calculado com a soma das solicitações do lado do cliente e do lado do servidor. Se o aplicativo exceder o limite inicial, apresentará falhas.
https://webmania.com.br/api/ retorne 403 Erro Forbidden entre em contato para liberarmos o IP do seu servidor.