REST API de Consulta QR Code e Chave

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.

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

A Consulta por QR Code realiza a validação, leitura e retorno 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 e url_notificacao.

O parâmetro qrcode permite a utilização da URL do QRCode ou Chave da nota fiscal. Verifique abaixo o preenchimento permitido para cada tipo de documento fiscal:

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

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"
}' \
https://webmaniabr.com/api/1/nfe/consulta/qr-code/

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

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 
  "nota_valida": true, // Nota válida
  "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
  "nota_valida": true, // Nota válida
  "protocolo": "00000000000", // Protocolo de aprovação
  "data_emissao": "01/11/2024 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 dos dados do QR Code são realizados 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.

A requisição via POST é realizada no formato x-www-form-urlencoded ou application/json, dependendo do valor do parâmetro formato_notificacao.

Segue exemplo do retorno no formato x-www-form-urlencoded:

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

["uuid"] = "00000000-0000-0000-0000-000000000000"
["status"] = "concluido"
["chave"] = "00000000000000000000000000000000000000000000"
["nota_valida"] = true
["serie"] = 1
["numero"] = 10
["protocolo"] = "00000000000"
["data_emissao"] = "01/11/2024 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:

Segue exemplo no formato JSON:

{
  "uuid": "00000000-0000-0000-0000-000000000000", // UUID   
  "status": "concluido", // Status da consulta    
  "chave": "00000000000000000000000000000000000000000000", // Chave
  "nota_valida": true, // Nota válida
  "protocolo": "00000000000", // Protocolo de aprovação
  "data_emissao": "01/11/2024 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:

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:

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:

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:

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 balance, total, expires_in e plan:

{
  "balance": 252, 
  "total": 1000, 
  "expires_in": "2025-11-21 23:59:59",
  "plan": "paid"
}

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.

• 13.248.145.90
• 76.223.17.240

• 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.