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.
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/ | POST | Consulta por Chave |
/1/nfe/consulta/qr-code/ | POST | Consulta por QR Code |
/1/nfe/consulta/requests/ | POST | Consultar Requisições e Limites |
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-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.
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:
NF-e | NFC-e | CT-e | NFS-e |
---|---|---|---|
Disponível | Disponível | Em breve | Em breve |
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 Fiscalaprovado |
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 Fiscalnfe |
serie | número | Série da Nota Fiscal |
nfe | número | Número da Nota Fiscal |
emissao | número | Tipo de emissão1 - Normal |
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"
}
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:
Nível 2 | Nível 1 (retorno parcial) |
---|---|
AC, AL, AM, BA, ES, GO, MT, MS, MG, PR, PE, PI, RJ, RS, RR, SC, SP e TO | AP, CE, DF, MA, PA, PB, RN, RO, SE e SP (CF-e-SAT) |
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:
Parâmetro | Tipo | Descrição |
---|---|---|
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:
{
"chave": "00000000000000000000000000000000000000000000", // Chave
"protocolo": "00000000000", // Protocolo de aprovação
"data_emissao": "01/08/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"
}
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:
Tipo | Descrição | |
---|---|---|
Emitente | ✅ | Disponibilizado para emitente o XML completo da Nota Fiscal.xml_completo |
Destinatário | ✅ | Disponibilizado para destinatário o XML completo da Nota Fiscal.xml_completo |
Transportador | ✅ | Disponibilizado para transportador o XML completo da Nota Fiscal.xml_completo |
Terceiros | ✅ | Disponibilizado para terceiros o XML completo da Nota Fiscal.xml_completo |
Regras para download de XML de outros emissores:
Tipo | Descrição | |
---|---|---|
Emitente | ❌ | Não é relizado 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 maisxml_resumo |
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 XMLxml_resumo |
versao | string | Versão do XML retornadoExemplo: |
xml | string | Arquivo XMLXML 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
}
],
}
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-08-31 23:59:59", // Data de expiração
"plan": "paid" // Plano atual
}
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:
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://webmaniabr.com/api/
retorne 403 Erro Forbidden entre em contato para liberarmos o IP do seu servidor.