⚡ Acompanhe em tempo real: Status | Monitor Sefaz | Monitor Prefeituras | Monitor Consultas

Versão: 1.0.0

REST API Validação de Documentos Fiscais com Inteligência Artificial

Validação inteligente de documentos fiscais com Inteligência Artificial avançada, dispensando OCR tradicional, detectando fraudes automaticamente e resposta em JSON estruturado.

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 em menos de 30 segundos com consulta direta na SEFAZ e integração nativa com Serpro.

1. Envie o Documento

Imagem, PDF ou XML

2. Análise com IA

IA proprietária

3. Validação

SEFAZ e Antifraude

4. Resultado

JSON estruturado

Inteligência Artificial Avançada
IA proprietária combinando as últimas tecnologias de LLM para validação de documentos fiscais. Dispensa OCR tradicional com resposta em JSON estruturado.

Sistema Antifraude e Segurança
Detecção automática de manipulações e adulterações em documentos fiscais. Garanta a autenticidade dos documentos fiscais através da imagem, PDF ou XML.

Validação Inteligente
Processamento de NF-e, NFC-e e NFS-e com validação SEFAZ em tempo real e integração nativa com Serpro. Acompanhe a mudança de status do documento fiscal.

Casos de Uso Versáteis
Ideal para programas de pontos/cashback, bancos, fintechs, compliance fiscal, liberação de pagamentos e análise de risco empresarial.

Casos de uso

Programas de Prêmios, Pontos e Cashback

Ideal para sistemas de fidelização e cashback que precisam validar cupons fiscais de forma rápida e segura:

Validação instantânea de cupons fiscais - Processe documentos em menos de 30 segundos.
Prevenção de uso múltiplo - Sistema antifraude detecta documentos já utilizados.
Extração automática de valores - IA extrai todos os dados relevantes do documento.
Liberação de benefícios automática - Integração direta com seu sistema de pontos.

Bancos e Financeiras

Solução completa para instituições financeiras que precisam validar documentos fiscais para análise de crédito:

Validação para aprovação de crédito - Confirme a veracidade dos documentos apresentados.
Antecipação de recebíveis - Valide notas fiscais para operações de antecipação.
Análise de faturamento real - Verifique o faturamento real das empresas.
Detecção de fraudes e duplicatas - IA identifica documentos manipulados ou duplicados.

Compliance e Análise

Mantenha sua empresa em conformidade fiscal com validação contínua de documentos:

Análise de status na SEFAZ - Consulta em tempo real do status dos documentos.
Detecção de cancelamentos - Monitore mudanças de status automaticamente.
Relatórios de conformidade - Dashboards completos para auditoria.
Monitoramento contínuo - Acompanhe todos os documentos processados.

Liberação de Pagamentos

Automatize a conferência de documentos fiscais para liberação segura de pagamentos:

Conferência de valores - Valide automaticamente valores e impostos.
Verificação de emitente - Confirme dados do fornecedor com a SEFAZ.
Integração com ERP - API REST compatível com qualquer sistema.
Conciliação automática - Match automático entre pedido e nota fiscal.

Segurança e Privacidade dos Dados

Segurança Antifraude

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.

Privacidade dos Dados

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.

Guia Rápido

🚀 Fluxo básico de integração em 4 passos:

Obtenha as suas credenciais com os especialistas da Webmania®.
Informe a imagem, PDF ou XML do documento fiscal.
Em apenas 30 segundos valide com a Inteligência Artificial da Webmania®.
Obtenha em JSON estruturado a validação e as informações do documento fiscal.

Todas as solicitações devem ser realizadas em ambiente criptografado HTTPS através da URL https://api.webmania.com.br/. O prefixo /2/valida/ identifica a versão 2.0 da API com recursos de validação por Inteligência Artificial.

A tabela abaixo lista todos os endpoints disponíveis na API:

Endpoint	Método	Descrição
`/2/valida/dfe/imagem`	POST	Validação de documentos fiscais a partir de imagem ou PDF
`/2/valida/dfe/xml`	POST	Validação de documentos fiscais a partir do XML
`/2/valida/conexoes/serpro`	POST	Cadastrar conexão com a SERPRO
`/2/valida/logs/{uuid}`	GET	Consulta da validação pelo UUID retornado
`/2/valida/conexoes/serpro`	GET	Listar conexão com a SERPRO
`/2/valida/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.

Autenticação

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.

Formato de resposta

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	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 IA

Esta 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:

Por imagem: NF-e, NFC-e e NFS-e.
Por XML: NF-e, NFC-e, NFS-e, CT-e e MDF-e.

Inteligência Artificial
Validação por Imagem

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:

Formatos aceitos: JPG, PNG e PDF
Tamanho máximo: 10MB por imagem
Processamento múltiplo: Para mais de uma imagem, o processo é sempre assíncrono.
Limite por requisição: Até 10 imagens por chamada

Inteligência Artificial • Validação por Imagem
URL pública

Envie URLs públicas de imagens do documento fiscal para validação. Ideal para documento já hospedado em servidores ou sistemas externos.

Parâmetro	Tipo	Descrição
`imagens`	array	URL das imagens de um único documento fiscal `Exemplo: ["https://exemplo.com/nfe1.jpg", "https://exemplo.com/nfe2.png"]`
`modelo`	string	Modelo do documento `nfe nfce nfse`
`formato`	string	Formato do retorno `json (padrão) texto`
`assincrono`	boolean	Processamento assíncrono `Para 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)

Segue abaixo exemplo do envio de uma única imagem:

curl -X POST https://api.webmaniabr.com/2/valida/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.webmaniabr.com/2/valida/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 do envio de múltiplas imagens do mesmo documento fiscal:

Atenção: O envio de múltiplas imagens deve sempre se referir ao mesmo documento fiscal, sendo recomendado apenas quando não for possível enviar a imagem completa de uma única vez — por exemplo, em casos de NFC-e com muitos itens.

curl -X POST https://api.webmaniabr.com/2/valida/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
  }'

Inteligência Artificial • Validação por Imagem
Upload

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	Tipo	Descrição
`imagens[]`	file[]	Caminho das imagens de um único documento fiscal `Formatos: JPG, PNG ou PDF Tamanho máximo: 10MB por arquivo`
`modelo`	string	Modelo do documento `nfe nfce nfse`
`formato`	string	Formato do retorno `json (padrão) texto`
`assincrono`	boolean	Processamento assíncrono `Para 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)

Segue abaixo exemplo do envio de uma única imagem:

curl -X POST https://api.webmaniabr.com/2/valida/dfe/imagem \
  -H "X-Token: SEU_ACCESS_TOKEN" \
  -F "imagens[]=@/caminho/para/documento.jpg" \
  -F "modelo=nfe"

Segue abaixo exemplo do envio de múltiplas imagens do mesmo documento fiscal:

curl -X POST https://api.webmaniabr.com/2/valida/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"

Inteligência Artificial
Validação por XML

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	Tipo	Descrição
`xml`	base64	Conteúdo do XML codificado em base64
`formato`	string	Formato do retorno `json (padrão) texto`
`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.webmaniabr.com/2/valida/dfe/xml \
  -H "X-Token: SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "xml": "PG5mZVByb2MgdmVyc2FvPSI0LjAwIiB4bWxucz0iaHR0cDovL3d3dy4..."
  }'

Inteligência Artificial
Processamento Assíncrono

Quando 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, que possui tempo médio de 30 segundos. 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"
}

Inteligência Artificial
Formato de Retorno

A API suporta dois formatos de retorno para atender diferentes necessidades de integração:

JSON: Retorna todos os dados validados do documento fiscal de forma estruturada, sendo compatível com qualquer linguagem de programação. Ideal para integrações completas e sistemas que precisam manipular dados detalhados.
Texto: Retorna as informações de forma simplificada e legível, ideal para chatbots, WhatsApp e outros canais de comunicação, onde uma resposta direta e amigável é necessária.

Inteligência Artificial • Formato de Retorno
JSON

{
    "uuid": "f9123xyz-1a2b-3c4d-5e6f-7890abcdef12",
    "status": "aprovado",
    "chave": "12345678901234000190550010000000991122334455",
    "protocolo": "991122334455667",
    "data_emissao": "2025-08-20T10:45:00-03:00",
    "numero": "27",
    "serie": "2",
    "data_saida": "2025-08-20T10:45:00-03:00",
    "total": "512.80",
    "emitente": {
        "cnpj": "12345678000199",
        "razao_social": "ALFA SOLUCOES TECNOLOGICAS LTDA",
        "nome_fantasia": "ALFA TECH",
        "endereco": "RUA DAS FLORES",
        "numero": "300",
        "bairro": "JARDIM NOVO HORIZONTE",
        "cep": "01001000",
        "cidade": "SAO PAULO",
        "uf": "SP",
        "telefone": "11987654321",
        "ie": "1234567890"
    },
    "consumidor": {
        "cnpj": "12.345.678/0001-55",
        "nome": "BETA COMERCIO DE PRODUTOS LTDA",
        "endereco": "AV CENTRAL",
        "numero": "450",
        "bairro": "CENTRO",
        "cep": "22000000",
        "cidade": "RIO DE JANEIRO",
        "uf": "RJ",
        "telefone": "2123456789",
        "email": "contato@betacomerciosimulado.com"
    },
    "produtos": [
        {
            "codigo": "100.200.300",
            "nome": "CAFE PREMIUM 500G",
            "ncm": "09012100",
            "cfop": "5405",
            "ean": "SEM GTIN",
            "quantidade": "3",
            "unidade": "UN",
            "total": "150.00",
            "subtotal": "150.00",
            "icms": {
                "cst": "0060"
            },
            "item": "1"
        },
        {
            "codigo": "100.200.301",
            "nome": "CHA VERDE 200G",
            "ncm": "09021000",
            "cfop": "5405",
            "ean": "SEM GTIN",
            "quantidade": "2",
            "unidade": "UN",
            "total": "80.00",
            "subtotal": "80.00",
            "icms": {
                "cst": "0060"
            },
            "item": "2"
        },
        {
            "codigo": "100.200.302",
            "nome": "MEL ORGANICO 1KG",
            "ncm": "04090000",
            "cfop": "5405",
            "ean": "SEM GTIN",
            "quantidade": "1",
            "unidade": "UN",
            "total": "282.80",
            "subtotal": "282.80",
            "icms": {
                "cst": "0051",
                "base_calculo": "282.80",
                "valor": "32.50"
            },
            "item": "3"
        }
    ],
    "totais": {
        "bc_icms": "282.80",
        "valor_icms": "32.50",
        "bc_icms_st": "0.00",
        "valor_icms_substituto": "0.00",
        "valor_produtos": "512.80",
        "valor_frete": "0.00",
        "valor_seguro": "0.00",
        "valor_descontos": "0.00",
        "valor_ipi": "0.00",
        "valor_pis": "9.80",
        "valor_cofins": "42.30",
        "outras_despesas_acessorias": "0.00",
        "valor_total": "512.80",
        "valor_aproximado_tributos": "0.00"
    },
    "transporte": {
        "modalidade_frete": 0,
        "peso_liquido": "45.000",
        "peso_bruto": "48.500"
    },
    "informacoes_adicionais": "Referente aos Pedidos:45 Operação simulada para testes internos.",
    "natureza_operacao": "Venda de mercadoria adquirida ou recebida de terceiros",
    "operacao": 1,
    "modelo": "nfe"
}

{
    "uuid": "b8912def-34ab-5678-90cd-ef1234567890",
    "status": "aprovado",
    "chave": "98765432109876000190550010000000771122334455",
    "protocolo": 991122334455667,
    "protocolo_detalhado": {
        "numero": "991122334455667",
        "digest_value": "abCDeFgHiJKlMnOpQrStUvWxYz0=",
        "data_recebimento": "20/08/2025 10:45:25",
        "id": "ID991122334455667",
        "motivo": "Autorizado o uso da NF-e",
        "codigo_status": 100
    },
    "data_emissao": "2025-08-20T10:45:00-03:00",
    "numero": "27",
    "serie": "2",
    "total": "512.80",
    "data_saida": "2025-08-20T10:45:00-03:00",
    "natureza_operacao": "Venda de mercadoria adquirida ou recebida de terceiros",
    "finalidade": 1,
    "emitente": {
        "cnpj": "12345678000199",
        "razao_social": "ALFA SOLUCOES TECNOLOGICAS LTDA",
        "nome_fantasia": "ALFA TECH",
        "endereco": "RUA DAS FLORES",
        "numero": "300",
        "bairro": "JARDIM NOVO HORIZONTE",
        "cep": "01001000",
        "cidade": "SAO PAULO",
        "uf": "SP",
        "telefone": "11987654321",
        "ie": "1234567890"
    },
    "consumidor": {
        "cnpj": "12.345.678/0001-55",
        "nome": "BETA COMERCIO DE PRODUTOS LTDA",
        "endereco": "AV CENTRAL",
        "numero": "450",
        "bairro": "CENTRO",
        "cep": "22000000",
        "cidade": "RIO DE JANEIRO",
        "uf": "RJ",
        "telefone": "2123456789",
        "email": "contato@betacomerciosimulado.com"
    },
    "produtos": [
        {
            "codigo": "100.200.300",
            "nome": "CAFE PREMIUM 500G",
            "ncm": "09012100",
            "cfop": "5405",
            "ean": "SEM GTIN",
            "quantidade": "3",
            "unidade": "UN",
            "total": "150.00",
            "subtotal": "150.00",
            "icms": {
                "cst": "0060"
            },
            "item": "1"
        },
        {
            "codigo": "100.200.301",
            "nome": "CHA VERDE 200G",
            "ncm": "09021000",
            "cfop": "5405",
            "ean": "SEM GTIN",
            "quantidade": "2",
            "unidade": "UN",
            "total": "80.00",
            "subtotal": "80.00",
            "icms": {
                "cst": "0060"
            },
            "item": "2"
        },
        {
            "codigo": "100.200.302",
            "nome": "MEL ORGANICO 1KG",
            "ncm": "04090000",
            "cfop": "5405",
            "ean": "SEM GTIN",
            "quantidade": "1",
            "unidade": "UN",
            "total": "282.80",
            "subtotal": "282.80",
            "icms": {
                "cst": "0051",
                "base_calculo": "282.80",
                "valor": "32.50"
            },
            "item": "3"
        }
    ],
    "totais": {
        "bc_icms": "282.80",
        "valor_icms": "32.50",
        "bc_icms_st": "0.00",
        "valor_icms_substituto": "0.00",
        "valor_produtos": "512.80",
        "valor_frete": "0.00",
        "valor_seguro": "0.00",
        "valor_descontos": "0.00",
        "valor_ipi": "0.00",
        "valor_pis": "9.80",
        "valor_cofins": "42.30",
        "outras_despesas_acessorias": "0.00",
        "valor_total": "512.80",
        "valor_aproximado_tributos": "0.00"
    },
    "transporte": {
        "modalidade_frete": 0,
        "peso_liquido": "45.000",
        "peso_bruto": "48.500"
    },
    "cobranca": {
        "fatura": {
            "numero": "27",
            "valor": "512.80"
        },
        "duplicatas": [
            {
                "numero": "001",
                "data_vencimento": "27/08/2025",
                "valor": "512.80"
            }
        ]
    },
    "pagamento": [
        {
            "forma_pagamento": "15",
            "valor_pagamento": "512.80"
        }
    ],
    "informacoes_complementares": "Referente aos Pedidos:45 Operação simulada para testes internos.",
    "reservado_fisco": "ICMS SIMULADO PARA TESTE DE SISTEMA",
    "informacoes_adicionais": "Referente aos Pedidos:45 Operação simulada para testes internos.",
    "operacao": 1,
    "eventos": [
        {
            "orgao": 35,
            "data_evento": "21/08/2025 11:00:37",
            "tipo_evento": 110110,
            "descricao": "Carta de Correcao",
            "protocolo_evento": "772233445566778",
            "data_registro": "21/08/2025 11:00:38"
        },
        {
            "orgao": 88,
            "data_evento": "22/08/2025 17:20:36",
            "tipo_evento": 210210,
            "descricao": "Ciencia da Operacao",
            "protocolo_evento": "882233445566778",
            "data_registro": "22/08/2025 17:20:39"
        },
        {
            "orgao": 88,
            "data_evento": "23/08/2025 13:15:15",
            "tipo_evento": 210200,
            "descricao": "Confirmacao da Operacao",
            "protocolo_evento": "992233445566778",
            "data_registro": "23/08/2025 13:15:15"
        }
    ],
    "modelo": "nfe"
}

{
    "uuid": "d7f50f50-9999-4abc-8d88-11aa3b456789",
    "status": "valido",
    "modelo": "nfse",
    "serie_nfse": "2",
    "numero_rps": "5678",
    "serie_rps": "2",
    "data_emissao": "10/10/2025 14:30:10",
    "hora_emissao": "14:30:10",
    "data_rps": "10/10/2025",
    "prestador": {
        "cnpj_cpf": "99887766000155",
        "cnpj": "99887766000155",
        "codigo_municipio": "9999",
        "municipio": "9999"
    },
    "tomador": {
        "cnpj_cpf": "55443322000111",
        "cnpj": "55443322000111",
        "tipo": "juridica",
        "razao_social": "OMEGA SOLUCOES DIGITAIS LTDA",
        "endereco": "AV PRINCIPAL",
        "logradouro": "AV PRINCIPAL",
        "numero": "999",
        "bairro": "CENTRO NOVO",
        "codigo_municipio": "8888",
        "municipio": "8888",
        "cep": "11020330",
        "email": "contato@omegasimulada.com"
    },
    "servico": {
        "codigo_local_prestacao": "9999",
        "codigo_local_prestacao_servico": "9999",
        "itens": [
            {
                "codigo_servico": "0207",
                "discriminacao": "SERVIÇOS REFERENTE À FATURA NÚMERO 888888. \\n\\n 1. Desenvolvimento de Software - Pacote mensal: 500 horas \\n \\n\\n Conf. Lei 12.741/2012 a carga tributária dessa NF é de aprox. 15,00% - Fonte Simulada",
                "descricao": "SERVIÇOS REFERENTE À FATURA NÚMERO 888888. \\n\\n 1. Desenvolvimento de Software - Pacote mensal: 500 horas \\n \\n\\n Conf. Lei 12.741/2012 a carga tributária dessa NF é de aprox. 15,00% - Fonte Simulada",
                "aliquota": "3.5000",
                "aliquota_item_lista_servico": "3.5000",
                "situacao_tributaria": "0",
                "valor_tributavel": "850.00",
                "valor_total": "850.00",
                "tributa_municipio_prestador": "1"
            }
        ],
        "informacoes_adicionais": "SERVIÇOS REFERENTE À FATURA NÚMERO 888888. \\n\\n 1. Desenvolvimento de Software - Pacote mensal: 500 horas \\n \\n\\n Conf. Lei 12.741/2012 a carga tributária dessa NF é de aprox. 15,00% - Fonte Simulada",
        "discriminacao_servico": "SERVIÇOS REFERENTE À FATURA NÚMERO 888888. \\n\\n 1. Desenvolvimento de Software - Pacote mensal: 500 horas \\n \\n\\n Conf. Lei 12.741/2012 a carga tributária dessa NF é de aprox. 15,00% - Fonte Simulada"
    },
    "valores": {
        "valor_total_nfse": "850.00",
        "valor_servicos": "850.00",
        "valor_total_servico": "850.00"
    },
    "total": "850.00"
}

{
    "uuid": "a8b7c9d0-1234-5678-9abc-def012345678",
    "chave": "35250998765432000999550020000999991122334455",
    "sefaz_status": "aprovado",
    "protocolo": "135999888777666",
    "data_emissao": "10/10/2025 11:30:45",
    "modelo": "cte",
    "modal": "01",
    "serie": "2",
    "numero": "30015",
    "valor_servico": "55.90",
    "valor_receber": "55.90",
    "tomador": 0,
    "emitente": {
        "cnpj": "11223344000155",
        "ie": "998877665544",
        "razao_social": "ALFA LOGISTICA LTDA.",
        "endereco": "AV DAS NAÇÕES UNIDAS",
        "numero": "5000",
        "complemento": "GALPÃO 2",
        "bairro": "CENTRO INDUSTRIAL",
        "codigo_municipio": "3550308",
        "cidade": "SÃO PAULO",
        "cep": "05000000",
        "uf": "SP",
        "telefone": "11988887777"
    },
    "remetente": {
        "cnpj": "55443322000111",
        "ie": "554433221100",
        "razao_social": "OMEGA INDUSTRIA DE EQUIPAMENTOS LTDA",
        "endereco": "RUA NOVA ESPERANÇA",
        "numero": "450",
        "bairro": "JARDIM INDUSTRIAL",
        "codigo_municipio": "3304557",
        "cidade": "RIO DE JANEIRO",
        "cep": "21000000",
        "uf": "RJ"
    },
    "destinatario": {
        "cpf": "98765432100",
        "razao_social": "MARIA DA SILVA",
        "endereco": "AVENIDA DAS AMÉRICAS, 1500, BLOCO 3",
        "numero": "1500",
        "bairro": "BARRA DA TIJUCA",
        "codigo_municipio": "3304557",
        "cidade": "Rio de Janeiro",
        "cep": "22640002",
        "uf": "RJ"
    },
    "carga": {
        "valor_carga": "950.00",
        "produto_predominante": "ELETRODOMÉSTICO PORTÁTIL - SIMULADO",
        "quantidades": [
            {
                "unidade": "03",
                "tipo_medida": "CAIXAS",
                "quantidade": "5.0000"
            },
            {
                "unidade": "01",
                "tipo_medida": "PESO BRUTO",
                "quantidade": "2.3000"
            }
        ]
    },
    "modal_rodo": {
        "rntrc": "11223344"
    },
    "documentos": [
        {
            "chave": "35250998765432000999550020000999991122334455"
        }
    ]
}

{
    "uuid": "f868be0a-3671-4b40-a48f-0e1115117eb8",
    "chave": "35250912306124000189550010000012151650062780",
    "sefaz_status": "aprovado",
    "protocolo": "135252759951427",
    "data_emissao": "19/09/2025 09:25:48",
    "modelo": "mdfe",
    "serie": "1",
    "numero": "304",
    "modal": "1",
    "uf_inicio": "SP",
    "uf_fim": "DF",
    "emitente": {
        "cnpj": "07194821000155",
        "ie": "675338315116",
        "razao_social": "BR EX TRANSPORTE DE CARGAS LTDA",
        "nome_fantasia": "MXLOG",
        "endereco": "RUA FRANCISCA RONCADA PAROLISE",
        "numero": "14",
        "bairro": "JARDIM WANDA",
        "codigo_municipio": "3552809",
        "cidade": "TABOAO DA SERRA",
        "cep": "06765470",
        "uf": "SP",
        "telefone": "1142405336",
        "email": "adm@mxlog.com.br"
    },
    "modal_rodo": {
        "rntrc": "51498111",
        "placa": "GCA0G53"
    },
    "totais": {
        "quantidade_nfe": "1",
        "valor_carga": "0.00",
        "quantidade_carga": "100.0000"
    },
    "documentos": [
        {
            "chave": "35250912306124000189550010000012151650062780"
        }
    ]
}

Inteligência Artificial • Formato de Retorno
Texto

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: 135240001234567

Inteligência Artificial
Consultar UUID

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.webmaniabr.com/2/valida/logs/550e8400-e29b-41d4-a716-446655440000

Conexões

Aprimore as validações de documentos fiscais com conexões que fornecem dados adicionais e que aumentam a conectividade da validação com a Webmania®.

Conexões
Serpro

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.

Validação Oficial

Consulta direta na base da SEFAZ através do Serpro, incluindo documentos com mais de 180 dias de emissão.

Histórico Completo

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

Conexões • Serpro
Cadastrar Credenciais

⚠️ 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.webmaniabr.com/2/valida/conexoes/serpro

Exemplo de resposta do cadastro das credenciais:

{
  "status": "cadastrado",
  "provedor": "serpro",
  "credencial": {
    "consumer_key": "SUA_CONSUMER_KEY",
    "consumer_secret": "***************"
  }
}

Conexões • Serpro
Consultar Credenciais

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.webmaniabr.com/2/valida/conexoes/serpro

Exemplo de resposta da consulta das credenciais:

{
  "provedor": "serpro",
  "credencial": {
    "consumer_key": "SUA_CONSUMER_KEY",
    "consumer_secret": "***************"
  }
}

Conexões • Serpro
Remover Credenciais

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.webmaniabr.com/2/valida/conexoes/serpro

Exemplo de resposta da remoção das credenciais:

{
  "status": "removido"
}

Boas Práticas

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.

Qualidade das Imagens

Resolução mínima de 150 DPI para melhor precisão
Evite o envio de fotos com sombras ou reflexos

Processamento Assíncrono

Use para lotes grandes de documentos
Implemente webhook para notificações

Conexão Serpro

Use apenas quando necessário (custo adicional)
Ideal para validações críticas ou compliance

Tratamento de Erros

Implemente retry com backoff exponencial
Valide parâmetros antes de enviar
Monitore códigos de status HTTP

Infraestrutura

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:

13.248.145.90
76.223.17.240

IPs estáticos de saída (notificações):

34.196.69.38
44.219.142.86

Limite de requisições

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.

Localização do servidor: O firewall bloqueia por padrão o IP de servidores em regiões com alto índice de ataques. Caso a sua comunicação via GET no endpoint https://webmaniabr.com/api/ retorne 403 Erro Forbidden entre em contato para liberarmos o IP do seu servidor.
Credenciais de acesso: Os endpoints exigem as credenciais de acesso válida e correta na URI da requisição, o envio incorreto é atribuído como uso indevido da API.

Comece agora Teste Grátis!