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.

Consultar Nota Fiscal

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:

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"
}

Download XML da Nota Fiscal

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:

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
    }
  ],
}

Download XML
Emissor WebmaniaBR®

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.

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
    }
  ],
}

Download XML
Outros emissores

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.

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
    }
  ],
}

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": "2021-06-30 23:59:59", // Data de expiração
  "plan": "paid" // Plano atual
}

Infraestrutura

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:

• 13.248.145.90
• 76.223.17.240

Limite de requisições

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.

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