Suporte Técnico Webmania®

Oi, estamos aqui para te ajudar 😄

A Webmania® conta com um time de Weblovers completo, com especialistas no emissor de Nota Fiscal, contabilidade, código de programação, módulos de loja virtual e principalmente no encantamento das nossas soluções.


Está com dúvidas?
Confira nossa Central de Ajuda

Ainda com dúvidas? Estamos aqui! 😊️

  • Envie um E-mail com todos os detalhes (abrir ticket)
  • Ou acesse o Painel Webmania® e converse via Chat (iniciar chat)

Horário de atendimento:
E-mail 24 horas por dia. Chat de Segunda a Sexta-feira das 9h às 18h, exceto feriados.

Webmania
  • Para sua empresa
  • Para desenvolvedores
  • Sobre nós
  • Contato
  • Área do cliente
  • Para sua empresa

    Emissor de Nota Fiscal
    Consulta de Nota Fiscal
    Consulta de CEP e IBGE
  • Para desenvolvedores

    Documentação
    Comece a integrar com as APIs da Webmania

    Guias

    Nota Fiscal de Produto Nota Fiscal de Serviço Manifesto Eletrônico Consulta Nota Fiscal Consulta CEP

    Comece já

    Teste 30 dias grátis Módulos & Exemplos Guia Loja Virtual Testar sem código
  • Sobre nós

    Notícias
    Quem somos
    Clientes
  • Contato

    WhatsApp
    Fale Conosco
  • Área do cliente

    Entrar
    Acessar painel
    Acesso rápido
    2º via Boleto Central de ajuda Financeiro
    Suporte técnico
    Abrir chamado
    Comercial
    Fale conosco
Entrar
  • REST API Consulta
  • Guia Rápido
  • Autenticação
  • Consulta por QR Code
    • Requisição
    • Notificações
    • Consultar UUID
  • Consulta por Chave
    • Requisição
    • Condições
      Download XML
  • Consultar Requisições
  • Infraestrutura
  • Limite de requisições
⚡ Acompanhe em tempo real: Status Webmania® | Monitor Sefaz | Telegram | Twitter
Versão: 2.2.1

REST API de Consulta de Nota Fiscal

Utilize a REST API da Webmania® de alta disponibilidade, segura e atualizada em tempo real para consultar a Chave da nota fiscal e QR Code de NFC-e diretamente na Sefaz de cada estado.

Integração REST API
Compatível com todas as linguagens de programação, através da comunicação via JSON. Garantia de baixa latência com mais de 200 pontos de presença na rede Amazon Web Services.
Disponibilidade e Segurança
Alta disponibilidade, escalonável e servidores redundantes no mais alto nível de segurança PCI DSS na líder global de cloud computing Amazon Web Services.
Consulta Nacional
Cobertura de 100% do território nacional nas consultas de Notas Fiscais nos modelos NF-e e NFC-e. Saiba mais
Auditoria
Faça o download do XML das Notas Fiscais emitidas e obtenha o status em tempo real da Nota Fiscal para tomada de decisão.

Guia Rápido

Todas as solicitações na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://webmaniabr.com/api/. O prefixo /1/ indica que atualmente nós estamos utilizando a versão 1.0 da API.

URL HTTP Verb Função
/1/nfe/consulta/qr-code/ POST Consulta por QR Code
/1/nfe/consulta/ POST Consulta por Chave
/1/nfe/consulta/requests/ POST Consultar Requisições e Limites
/1/nfe/consulta/qr-code/ GET Consultar UUID da requisição

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-Consumer-Key, X-Consumer-Secret e X-Token.

Mantenha as credenciais de acesso em segurança. Nunca publique as credenciais de acesso no código fonte do site, aplicativo ou software onde o usuário possa ter fácil acesso.

Para aplicativos mobile iOS e Android recomendamos que o processo de consulta seja realizado no servidor (back-end). No código fonte do aplicativo deve possuir somente a solicitação de consulta, enquanto o processo deve ser realizado em seu servidor.

Consulta por QR Code

Atenção: A partir do dia 01/04/2023, o modo assíncrono será padrão para todas as requisições.

A Consulta por QR Code realiza a validação, leitura e retorno do dados da NFC-e de todos os estados brasileiros. Através dessa solução é possível oferecer:

  • Promoções: Validação de NFC-e para campanhas promocionais, de pontos e cashback.
  • Gestão de reembolso: Validação de NFC-e para reembolso de despesas.

Para realizar a Consulta por QR Code de uma nota fiscal do modelo NFC-e, envie a requisição no método POST para a URL /1/nfe/consulta/qr-code/ com as credenciais da sua aplicação e contendo no corpo os parâmetros qrcode, estado, assincrono e url_notificacao.

Parâmetro Tipo Descrição
qrcode string URL do QR Code
estado string Estado do QR Code
XX
url_notificacao string URL de notificação para todas as atualizações d do QR Code
assincrono boolean Envio assíncrono da consulta com retorno via url_notifcacao

Verifique a lista dos estados disponíveis para consulta e as informações de retorno:

  • Completo: Validação e retorno completo da NFC-e com a listagem dos produtos.
  • Parcial: Validação completa da NFC-e, porém com leitura parcial (sem produtos).
  • Em breve: Em fase de homologação.
Resultado (completo) Resultado (parcial) Em breve
AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA (Parcial), PB, PR, PE, PI, RJ, RN, RO, RS, RR, SE, SC, SP (NFC-e), SP (CF-e SAT) e TO PA CE (CF-e SAT)

A captação do QR Code da NFC-e pode ser realizado através da tecnologia OCR (Optical Character Recognition) como Amazon Textract, Google Cloud Vision ou Microsoft Pesquisa Visual. Saiba mais

Segue abaixo exemplo para consultar QR Code:

curl -X POST \
-H "X-Consumer-Key: SEU_CONSUMER_KEY" \
-H "X-Consumer-Secret: SEU_CONSUMER_SECRET" \
-H "X-Token: SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "qrcode": "http://www.sefaz.to.gov.br/nfce/qrcode?p=00000000000000000000000000000000000000000000"
  "estado": "TO",
  "url_notificacao": "http://meudominio.com/retorno.php",
  "assincrono": true
}' \
https://webmaniabr.com/api/1/nfe/consulta/qr-code/

A resposta do corpo da mensagem será no formato objeto JSON, contendo os seguintes campos:

Parâmetro Tipo Descrição
uuid string Número único de identificação da consulta
status string Status da consulta
processando (Em processamento de leitura)
concluido (Leitura completa da NFC-e)
parcial (Leitura parcial da NFC-e)
cancelado (NFC-e se encontra cancelada)
invalido (QR Code inválido)
chave string Chave de identificação da Nota Fiscal no Sefaz
motivo número Número da série da nota fiscal

Segue exemplo no formato JSON, de um retorno bem sucedido, onde deve ser aguardado atualização do status na url_notificacao e armazenado o número UUID para consulta posterior:

{
  "uuid": "00000000-0000-0000-0000-000000000000", // UUID   
  "chave": "00000000000000000000000000000000000000000000", // Chave
  "status": "processando", // Status da consulta 
  "motivo": "Consulta do QR Code em processamento", // Motivo
}

Somente a 1ª requisição é contabilizada no plano, por esse motivo, caso sejam realizadas novas consultas da mesma URL do QR Code não será contabilizado. Segue exemplo, no formato JSON, quando realizado uma nova consulta e o status for concluido:

{
  "uuid": "00000000-0000-0000-0000-000000000000", // UUID   
  "status": "concluido", // concluido, parcial, cancelado, invalido    
  "chave": "00000000000000000000000000000000000000000000", // Chave
  "protocolo": "00000000000", // Protocolo de aprovação
  "data_emissao": "01/04/2023 18:50:30", // Data de emissão
  "numero": 10, // Número
  "serie": 1, // Série
  "total": "55.60", // Valor da nota
  "emitente": [
    "cnpj" : "00.000.000/0000-00", 
    "razao_social" : "Nome do emitente", 
    "endereco" : "Av. Brg. Faria Lima", 
    "numero" : 1000, 
    "complemento" : "Escritório",
    "bairro" : "Itaim Bibi",
    "cidade" : "São Paulo",
    "uf" : "SP"
  ],
  "produtos": [
    {
      "nome": "NOME DO PRODUTO",
      "item": "0001",
      "quantidade": "2",
      "unidade": "UN",
      "subtotal": "27.80",
      "total": "55.60"
    }
  ],
  "consumidor": [
    "cpf": "000.000.000-00"
  ] 
}

Quando uma requisição ocorre falha o corpo da resposta [body] continua no formato JSON, mas sempre contém o campo error. Por exemplo, caso o QR Code seja inválido será retornado a seguinte mensagem:

{
  "chave": "00000000000000000000000000000000000000000000", 
  "error": "URL do QR Code inválido. Não é possível consultar a Sefaz.",
  "status": "invalido"
}

Consultar por QR Code
Notificações

Todo o processamento, leitura e retorno do dados do QR Code é realizado de forma automática pela Webmania, para melhorar a experiência do usuário na sua aplicação.

Cada consulta por QR Code possui um número único de identificação chamado de UUID, este número deve ser utilizado para recepcionar e identificar o QR Code para atualizar as informações no seu banco de dados.

No momento que realizado a consulta, será enviado o retorno no formato POST para a URL especificada contendo no corpo os parâmetros uuid, status, chave, serie, numero, protocolo, data_emissao, total, emitente, produtos e consumidor.

Parâmetro Tipo Descrição
uuid string Número único de identificação da consulta
status string Status da consulta
concluido (Leitura completa da NFC-e)
parcial (Leitura parcial da NFC-e)
cancelado (NFC-e se encontra cancelada)
invalido (QR Code inválido)
chave string Chave de identificação da Nota Fiscal no Sefaz
serie número Número da série da nota fiscal
numero número Número da nota fiscal
protocolo string Protocolo de aprovação da nota fiscal
data_emissao string Data em que a nota fiscal foi emitida
total string Valor total da nota fiscal
emitente json Informações sobre o emitente da nota fiscal
produtos json Informações sobre os produtos da nota fiscal
consumidor json Informações sobre o consumidor da nota fiscal

A requisição via POST é realizada no formato x-www-form-urlencoded:

-X POST \
-header "Content-type: x-www-form-urlencoded" \

Segue exemplo do retorno via POST:

["uuid"] = "00000000-0000-0000-0000-000000000000"
["status"] = "concluido"
["chave"] = "00000000000000000000000000000000000000000000"
["serie"] = 1
["numero"] = 10
["protocolo"] = "00000000000"
["data_emissao"] = "01/04/2023 18:50:30"
["total"] = "55.60"
["emitente"] = {
    "cnpj" : "00.000.000/0000-00", 
    "razao_social" : "Nome do emitente", 
    "endereco" : "Av. Brg. Faria Lima", 
    "numero" : 1000, 
    "complemento" : "Escritório",
    "bairro" : "Itaim Bibi",
    "cidade" : "São Paulo",
    "uf" : "SP"
}
["produtos"] = [
    {
      "nome": "NOME DO PRODUTO",
      "item": "0001",
      "quantidade": "2",
      "unidade": "UN",
      "subtotal": "27.80",
      "total": "55.60"
    }
]
["consumidor"] = {
    "cpf": "000.000.000-00"
}

Consultar por QR Code
Consultar UUID da requisição

Para realizar a consulta da UUID da requisição, envie a requisição no método GET para a URL /1/nfe/consulta/qr-code/ com as credenciais da sua aplicação e contendo no corpo o parâmetro uuid. Segue abaixo exemplo da consulta UUID da requisição:

curl -X GET \
-H "X-Consumer-Key: SEU_CONSUMER_KEY" \
-H "X-Consumer-Secret: SEU_CONSUMER_SECRET" \
-H "X-Token: SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "uuid":"00000000-0000-0000-0000-000000000000"
}' \
https://webmaniabr.com/api/1/nfe/consulta/qr-code/

A resposta do corpo da mensagem será no formato objeto JSON, contendo os seguintes campos:

Parâmetro Tipo Descrição
uuid string Número único de identificação da consulta
status string Status da consulta
processando (Em processamento de leitura)
concluido (Leitura completa da NFC-e)
parcial (Leitura parcial da NFC-e)
cancelado (NFC-e se encontra cancelada)
invalido (QR Code inválido)
chave string Chave de identificação da Nota Fiscal no Sefaz
serie número Número da série da nota fiscal
numero número Número da nota fiscal
protocolo string Protocolo de aprovação da nota fiscal
data_emissao string Data em que a nota fiscal foi emitida
total string Valor total da nota fiscal
emitente array Informações sobre o emitente da nota fiscal
produtos array Informações sobre os produtos da nota fiscal
consumidor array Informações sobre o consumidor da nota fiscal

Segue exemplo no formato JSON:

{
  "uuid": "00000000-0000-0000-0000-000000000000", // UUID   
  "status": "concluido", // Status da consulta    
  "chave": "00000000000000000000000000000000000000000000", // Chave
  "protocolo": "00000000000", // Protocolo de aprovação
  "data_emissao": "01/04/2023 18:50:30", // Data de emissão
  "numero": 10, // Número
  "serie": 1, // Série
  "total": "55.60", // Valor da nota
  "emitente": [
    "cnpj" : "00.000.000/0000-00", 
    "razao_social" : "Nome do emitente", 
    "endereco" : "Av. Brg. Faria Lima", 
    "numero" : 1000, 
    "complemento" : "Escritório",
    "bairro" : "Itaim Bibi",
    "cidade" : "São Paulo",
    "uf" : "SP"
  ],
  "produtos": [
    {
      "nome": "NOME DO PRODUTO",
      "item": "0001",
      "quantidade": "2",
      "unidade": "UN",
      "subtotal": "27.80",
      "total": "55.60"
    }
  ],
  "consumidor": [
    "cpf": "000.000.000-00"
  ] 
}

Quando uma requisição ocorre falha o corpo da resposta [body] continua no formato JSON, mas sempre contém o campo error e status. Por exemplo, caso a URL do QR Code seja inválida será retornado a seguinte mensagem:

{
  "chave": "00000000000000000000000000000000000000000000",
  "error": "URL do QR Code inválido. Não é possível consultar a Sefaz.",
  "status": "invalido"
}

Consulta por Chave

A Consulta por Chave realiza a validação, leitura e retorno dos documentos fiscais. Segue abaixo aplicações que utilizam a nossa solução:

  • Contadores: Download do XML com validade fiscal para declarações.
  • Transportadoras: Download do XML para rápido preenchimento da CT-e.
  • Bancos/Financeiras: Validação do XML para antecipação de recebíveis.
  • Promoções: Validação do XML do modelo NF-e (55).
  • Auditoria: Validação e download do XML para fins de auditoria.

Para realizar a Consulta por Chave de nota fiscal, envie a requisição no método POST para a URL /1/nfe/consulta/ com as credenciais da sua aplicação e contendo no corpo o parâmetro chave. Segue modelos aceitos para consulta por chave:

NF-e NFC-e CT-e
Disponível Disponível Em breve
A consulta por chave exige Certificado Digital A1 configurado no painel Webmania®

Segue abaixo exemplo da consulta por chave:

curl -X POST \
-H "X-Consumer-Key: SEU_CONSUMER_KEY" \
-H "X-Consumer-Secret: SEU_CONSUMER_SECRET" \
-H "X-Token: SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "chave":"00000000000000000000000000000000000000000000"
}' \
https://webmaniabr.com/api/1/nfe/consulta/

A resposta do corpo da mensagem será no formato objeto JSON, contendo os seguintes campos:

Parâmetro Tipo Descrição
chave número Chave de identificação da Nota Fiscal no Sefaz
status string Status da Nota Fiscal
aprovado
cancelado
processamento
invalido
motivo número Motivo retornado pela Sefaz
emitente número CNPJ do emitente
uf número Estado do emitente
ano número Ano de emissão
mes número Mês de emissão
modelo string Modelo da Nota Fiscal
nfe
nfce
serie número Série da Nota Fiscal
nfe número Número da Nota Fiscal
emissao número Tipo de emissão
1 - Normal
6 - Contingência SVC-AN
7 - Contingência SVC-RS
9 - Contingência off-line da NFC-e
docs array Download do XML da Nota Fiscal
Saiba mais
log array Log de retorno do Sefaz

Segue exemplo no formato JSON:

{
  "chave": "00000000000000000000000000000000000000000000",
  "status": "aprovado", // aprovado, cancelado, processamento, invalido
  "motivo": "Autorizado o uso da NF-e", // Motivo da Sefaz
  "emitente": "00000000000000", // CNPJ do emitente
  "uf": "SP", // UF do emitente
  "ano": "00", // Ano da emissão
  "mes": "00", // Mês da emissão
  "modelo": "nfe", // Modelo
  "serie": "000", // Série
  "nfe": "000000000", // Número
  "emissao": "1", // Tipo de emissão
  "docs": "[{...}]", // Download XML
  "log": "{...}" // Log de retorno da SEFAZ
}

Quando uma requisição ocorre falha o corpo da resposta [body] continua no formato JSON, mas sempre contém o campo error e status. Por exemplo, caso a chave seja inválida será retornado a seguinte mensagem:

{
  "chave": "00000000000000000000000000000000000000000000",
  "error": "Chave de acesso inválida. Não é possível consultar a Sefaz.",
  "status": "invalido"
}

Condições para Download do XML

Através da Consulta por Chave da nota fiscal é possível realizar o download do XML de notas emitidas na Webmania® e em outros emissores. Consulte todas as condições em que o XML é disponibilizado:

Tipo Descrição
Emitente ❌ Não é realizado o download do XML caso a solicitação seja realizada pelo próprio emitente. A legislação determina que o emitente precisa armazenar por 5 anos o XML da Nota Fiscal emitida.
Destinatário ✅ Disponibilizado para destinatário a versão resumo e completa do XML da Nota Fiscal. Somente é disponibilizado a versão completa, caso o destinatário manifeste como "Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação". Saiba mais
xml_resumo
xml_completo
Transportador ✅ Disponibilizado para transportador o XML completo da Nota Fiscal, quando identificado na Nota Fiscal no grupo X03 do XML.
xml_completo
Terceiros ✅ Disponibilizado para terceiros o XML completo da Nota Fiscal, quando informado o CNPJ/CPF na tag autXML da Nota Fiscal.
xml_completo

O documento XML quando disponível se encontra no parâmetro docs da requisição com os parâmetros status, modelo, versao e xml dentro da array. Segue abaixo:

Parâmetro Tipo Descrição
modelo string Modelo do XML
xml_resumo
xml_completo
evento_resumo
evento_completo
versao string Versão do XML retornado
Exemplo:
4.00|WEBMANIABR
4.00|SEFAZ
xml string Arquivo XML
XML retornado pela Webmania® ou Sefaz

Segue exemplo no formato JSON:

{
  ...
  "docs": [
    {
      "modelo": "xml_completo", // Modelo do XML
      "versao": "4.00|[WEBMANIABR|SEFAZ]", // Versão do XML
      "xml": "<\xml>...<\xml>" // Arquivo XML
    }
  ],
}

Consultar Requisições e Limites

Para consultar o uso das requisções e os limites da API, envie a requisição no método POST para a URL /1/nfe/consulta/requests/ com as credenciais da sua aplicação. Segue abaixo exemplo:

curl -X POST \
-H "X-Consumer-Key: SEU_CONSUMER_KEY" \
-H "X-Consumer-Secret: SEU_CONSUMER_SECRET" \
-H "X-Token: SEU_TOKEN" \
-H "Content-Type: application/json" \
https://webmaniabr.com/api/1/nfe/consulta/requests/

A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos total, limit, expires_in e plan:

{
  "total": 0, // Requisições
  "limit": 100, // Limite de requisições
  "expires_in": "2023-04-30 23:59:59", // Data de expiração
  "plan": "paid" // Plano atual
}

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 IP's estáticos, caso necessite autorize no firewall a comunicação com os seguintes IP's:

  • 13.248.145.90
  • 76.223.17.240

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.

Soluções

Emissor de Nota Fiscal Consulta de Nota Fiscal Consulta de CEP e IBGE Nota Fiscal WooCommerce

Documentação

API Nota Fiscal de Produto API Nota Fiscal de Serviço API Manifesto Eletrônico API Consulta de Nota Fiscal API CEP e IBGE API Gerencial B2B

Webmania

Blog Clientes Sobre nós

Cases

Nordweg Podi App

Transparência

Política de Cookies Política de Privacidade Política Fiscal Contratos

Acesso rápido

Fale conosco Painel do Cliente Central de Ajuda 2ª via de Boleto Status Webmania® Monitor Sefaz
Facebook Webmania Instagram Webmania Linkedin Webmania Twitter Webmania
GitHub Webmania Telegram Webmania Youtube Webmania
Webmania

Copyright © 2009-2023 Webmania®.
Webmania® é uma marca registrada e de uso exclusivo da WebmaniaBR Serviços Empresariais LTDA
CNPJ: 11.290.027/0001-82 e WebmaniaBR Desenvolvimento de Software LTDA - CNPJ: 30.902.296/0001-05
sediadas na Av. Anita Garibaldi, 850, Salas 109C e 809A - Curitiba, PR - CEP 80540-400

Grupo WMBR
Voltar para o topo