REST API de Consulta de Nota Fiscal

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 Chave

Para realizar a consulta 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"
}

Consulta por QR Code

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

Para realizar a consulta de uma nota fiscal por meio do QR Code, 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 e estado.

Verifique a lista dos estados disponíveis para consulta:

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"
}' \
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:

{
  "chave": "00000000000000000000000000000000000000000000", // Chave
  "protocolo": "00000000000", // Protocolo de aprovação
  "data_emissao": "01/05/2022 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 a url seja inválida será retornado a seguinte mensagem:

{
  "error": "NFC-e inexistente ou não se encontra aprovada na Sefaz.",
  "status": "invalido"
}

Recomendamos que seja criado uma rotina caso a Sefaz esteja offline, onde deve ser realizado a consulta do QR Code da NFC-e posteriormente. Segue abaixo exemplo:

{
  "error": "NFC-e indisponível para consulta - Sefaz PR offline.",
  "status": "offline"
}

Download XML

Através da Consulta da Nota Fiscal é possível realizar o download do XML de Notas Fiscais emitidas na Webmania® e em outros emissores. Consulte todas as condições em que o XML é disponibilizado.

Regras para download de XML da Webmania:

Regras para download de XML de outros emissores:

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

{
  "total": 0, // Requisições
  "limit": 100, // Limite de requisições
  "expires_in": "2022-05-31 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, como na Europa e na Ásia oriental. 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.