Utilize a REST API da WebmaniaBR® de alta disponibilidade, segura e atualizada em tempo real para consultar as chaves das Notas Fiscais 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 modelo NF-e e NFC-e |
/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 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" \
-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"
}
Através da Consulta da Nota Fiscal é possível realizar o download do XML de Notas Fiscais emitidas na WebmaniaBR® e em outros emissores.
Consulte todas as condições em que o XML é disponibilizado. De acordo com as diretrizes da Sefaz alguns pré-requisitos são necessários para download do XML, nós simplificamos todas as condições quando emitida na WebmaniaBR® e em 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:
Parâmetro | Tipo | Descrição |
---|---|---|
modelo | string | Modelo do XMLxml_resumo |
versao | string | Versão do XML retornadoExemplo: |
xml | string | Arquivo XMLXML retornado pela WebmaniaBR® 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
}
],
}
O download do XML das Notas Fiscais emitidas no emissor da WebmaniaBR® abrange os modelos NF-e e NFC-e, onde sempre é retornado o XML completo na consulta.
A consulta pode ser realizada pelo emitente, destinatário, transportador e terceiros. Por exemplo, a matriz pode ter o controle de todas as Notas Fiscais emitidas pelas filiais que também emitem na WebmaniaBR®, realizando a auditoria contábil necessária.
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 |
Segue exemplo no formato JSON:
{
...
"docs": [
{
"modelo": "xml_completo", // Modelo do XML
"versao": "4.00|WEBMANIABR", // Versão do XML da WebmaniaBR®
"xml": "<\xml>...<\xml>" // Arquivo XML
}
],
}
As condições para download do XML de outros emissores está disponível somente no modelo NF-e, onde possui condições de acordo com o CNPJ/CPF que está realizando a requisição seja emitente, destinatário, transportador ou terceiro.
Veja todas as condições de acordo com o tipo de requisição.
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 manifestar como "Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação".xml_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 |
Segue exemplo no formato JSON:
{
...
"docs": [
{
"modelo": "xml_completo", // Modelo do XML
"versao": "4.00|SEFAZ", // Versão do XML da Sefaz
"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": "2021-01-31 23:59:59", // Data de expiração
"plan": "paid" // Plano atual
}
O servidores da WebmaniaBR 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 WebmaniaBR 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 WebmaniaBR® 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.