REST API de Gestão de Documentos Fiscais

Guia Rápido

Principais funcionalidades:

• Download automático de documentos fiscais recebidos pelo CNPJ/CPF
• Gestão de múltiplas empresas em uma única conta
• Acesso a XML e PDF dos documentos
• Manifestação do destinatário para NF-e
• Exportação em lote (XML, Excel, CSV)
• Filtros avançados por data, status, valor, entre outros.

Todas as requisições na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://api.webmaniabr.com/. O prefixo /2/gestao-documentos-fiscais deve ser adicionado na URL em todas as requisições.

A tabela abaixo lista todos os endpoints disponíveis na API:

Autenticação

Para acessar os recursos da API, é necessário autenticar as requisições por meio do cabeçalho HTTP (HTTP headers). A autenticação deve ser feita utilizando o cabeçalho Authorization, no seguinte formato:

Authorization: Bearer {Access-Token}

O Access-Token pode ser obtido no painel da Webmania® e deve ser incluído em todas as requisições.

Mantenha suas credenciais em segurança. Nunca publique o Access Token no código-fonte do site, aplicativo ou sistema onde ele possa ser facilmente acessado por terceiros.

Para aplicativos móveis (iOS e Android), recomendamos que a consulta à API seja realizada no servidor (back-end). O código-fonte do aplicativo deve apenas enviar a requisição enquanto o processamento da consulta deve ocorrer no seu servidor.

Formato de resposta

Todas as respostas da API seguem um padrão e estão no formato JSON, garantindo clareza e facilidade de interpretação.

A tabela abaixo apresenta os códigos de status HTTP que a API pode retornar com suas respectivas descrições. Esses códigos indicam o resultado da operação solicitada e ajudam a entender se a requisição foi bem-sucedida ou se ocorreu alguma falha.

Exemplo de resposta para uma requisição com erro:

{
  "error": "Parâmetro inválido: cnpj. O valor ABCD não é um CNPJ válido."
}

Notificações

Para que a sua plataforma se mantenha sempre atualizada, a Webmania disponibiliza as notificações automáticas sempre que novos documentos fiscais forem identificados e respectivos eventos forem registrados.

Cada documento fiscal e evento possui um número único de identificação chamado de UUID. Este número deve ser utilizado para recepcionar e identificar as requisições para atualizar as informações no seu banco de dados.

No momento que realizado o cadastro ou atualizado a empresa, caso tenha informado o parâmetro url_notificacao, será enviado o retorno no formato POST para a URL especificada contendo no corpo os parâmetros tipo_notificacao, data e documento.

A requisição via POST é realizada no formato application/json:

-X POST \
-header "Content-type: application/json" \

Segue exemplo do retorno via JSON:

{
  "tipo_notificacao": 2,
  "data": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "documento_uuid": "00000000-0000-0000-0000-000000000000",
    "protocolo": "0000000000000000",
    "registrado_em": "2025-06-02 13:17:00",
    "tipo_evento": 110112,
    "descricao_evento": "Encerramento",
    "cnpj_autor": "00000000000000",
    "cpf_autor": "00000000000",
    "resumo": false,
    "data_encerramento": "2025-06-02 13:15:00",
    "cidade_encerramento": "XXXXXXXX",
    "uf_encerramento": "XX",
    "log": {}
  },
  "documento": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "empresa_uuid": "00000000-0000-0000-0000-000000000000",
    "modelo": "mdfe",
    "status": "encerrado",
    "categoria": "citadas",
    "data_emissao": "2025-02-03 08:43:00",
    "numero": 500,
    ...
  }
}

Empresas

A API de Gestão de Documentos Fiscais funciona por meio do monitoramento automático dos documentos recebidos pelo CNPJ ou CPF das empresas cadastradas. Sem o cadastro dessas empresas, não é possível acessar os documentos fiscais.

Para cadastrar uma empresa, são necessários os seguintes dados:

• CNPJ ou CPF da empresa
• Certificado Digital A1 no formato Base64
• Senha do Certificado Digital

Esta seção explica como gerenciar empresas na API, incluindo o cadastro, a listagem, a consulta e a atualização. O gerenciamento de empresas é essencial para o correto funcionamento da API.

Municípios Disponíveis

Antes de configurar o monitoramento, verifique quais municípios estão disponíveis e se precisam de credenciais adicionais.

GET /municipios-nfse

Exemplo de requisição:

curl -X GET \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://api.webmaniabr.com/2/gestao-documentos-fiscais/municipios-nfse

Caso queira consultar a disponibilidade de apenas um município específico, pode ser enviado o parâmetro codigo_ibge na URL como parâmetro de consulta (query string).

Resposta:

A resposta da requisição terá o parâmetro data que será um array de objetos, onde cada objeto corresponderá a um município que está integrado e disponível para realizar download de NFS-e.

{
  "data": [
    {
      "municipio": "São Paulo",
      "uf": "SP",
      "codigo_ibge": "3550308",
      "nativo": true,
      "certificado": true,
      "login_senha": false,
      "cadastro_prefeitura": false,
      "domicilio_fiscal_municipio": false,
      "multiplos_servicos": false
    },
    {
      "municipio": "Osasco",
      "uf": "SP",
      "codigo_ibge": "3534401",
      "nativo": false,
      "certificado": false,
      "login_senha": true,
      "cadastro_prefeitura": false,
      "domicilio_fiscal_municipio": false,
      "multiplos_servicos": false
    }
  ]
}

Documentos

Esta seção abrange todas as operações relacionadas aos documentos fiscais na API. Aqui você encontrará informações sobre os modelos disponíveis, categorias, como listar e buscar documentos específicos.

A API suporta os seguintes modelos de documentos fiscais:

• NF-e - Nota Fiscal Eletrônica
• NFS-e - Nota Fiscal de Serviço Eletrônica
• MDF-e - Manifesto Eletrônico de Documentos Fiscais
• CT-e - Conhecimento de Transporte Eletrônico

Documentos Fiscais
Filtros

Os filtros permitem personalizar as consultas de documentos fiscais, garantindo que você obtenha exatamente os registros desejados de maneira eficiente.

Os parâmetros responsáveis por filtrar os registros devem ser enviados no corpo (body) da requisição, e variam conforme o modelo de documento que está sendo consultado.

A tabela abaixo lista todos os parâmetros disponíveis para cada modelo:

Exemplo de utilização dos filtros:

{
  "modelo": "nfe",
  "data_inicial": "2024-12-01",
  "data_final": "2024-12-31",
  "status": "aprovado",
  "pesquisa": "Venda"
}

Documentos Fiscais > Relatórios
Exportar

Os relatórios permitem exportar o XML, ou visualizar as informações em planilha Excel ou CSV dos registros, facilitando a análise, gerenciamento e o controle dos documentos fiscais.

Para realizar a exportação, envie a requisição no método POST para a URL /documentos.

A tabela abaixo lista os parâmetros que devem ser enviados no corpo (body) da requisição:

Os filtros também podem ser utilizados na exportação de relatórios para selecionar os registros desejados, a lista com todos os filtros disponíveis pode ser encontrada aqui.

Exemplo de requisição para solicitar a exportação de um relatório:

curl -X POST \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelo": "nfe",
    "relatorio": "xml",
    "url_notificacao": "http://meudominio.com/retorno.php",
    "data_inicial": "2024-12-01",
    "data_final": "2024-12-31",
    "finalidade": 4, // Notas de devolução
  }' \
  https://api.webmaniabr.com/2/gestao-documentos-fiscais/consulta

A resposta da requisição terá o parâmetro data, que será um objeto contendo as informações do relatório gerado, exemplo:

{
  "message": "Relatório criado com sucesso. A exportação está sendo executada em segundo plano.",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "relatorio": "xml",
    "modelo": "nfe",
    "status": "processando",
    "processado": 0, // Progresso da exportação
    "total": 120 // Total de registros encontrados
  }
}

Documentos Fiscais > Relatórios
Acompanhar progresso

A exportação dos relatórios é executada em segundo plano e o tempo para finalizar a exportação pode variar dependendo do volume de dados e dos filtros aplicados.

Ao executar a mesma requisição na API, o parâmetro processado é alterado para que seja acompanhado o progresso da exportação, recomendamos que as requisições sejam realizadas em um intervalo de no mínimo 5 segundos.

Ao concluir a exportação, o parâmetro status é alterado para concluido e serão adicionados os parâmetros url com o link para download do relatório e o parâmetro expira_em com a data de expiração do relatório.

Exemplo de retorno após a exportação ser concluída:

{
  "message": "Relatório exportado com sucesso.",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "relatorio": "xml",
    "modelo": "nfe",
    "status": "concluido",
    "processado": 120,
    "total": 120,
    "url": "https://api.webmaniabr.com/2/gestao-documentos-fiscais/relatorios/00000000-0000-0000-0000-000000000000",
    "expira_em": "2024-12-31 15:20:10",
  }
}

Caso tenha informado o parâmetro url_notificacao, o retorno também será enviado no formato POST para a URL especificada.

Documentos Fiscais
Manifestação do Destinatário

A Manifestação do Destinatário é um conjunto de eventos que permitem que o destinatário da NF-e possa apontar a sua participação comercial descrita no documento fiscal, confirmando e controlando as operações e informações prestadas pelo seu fornecedor, que é o emissor do documento.

Para realizar a manifestação, envie a requisição no método POST para a URL /documentos/{id}/eventos, onde {id} corresponde ao identificador único (UUID) do documento fiscal que será manifestado.

A tabela abaixo lista os parâmetros que devem ser enviados no corpo (body) da requisição:

Exemplo de requisição para realizar a manifestação:

curl -X POST \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "evento": 1,
    "manifestacao": 1 // Confirmação da operação
  }' \
  https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/00000000-0000-0000-0000-000000000000/eventos

A resposta da requisição terá o parâmetro data, que será um objeto contendo as seguintes informações do evento gerado:

Exemplo de retorno:

{
  "message": "Evento registrado com sucesso.",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "documento_id": "00000000-0000-0000-0000-000000000000",
    "registrado_em": "2024-12-15 12:56:40",
    "evento": 1,
    "manifestacao": 1,
    "log": {}
  }
}

Documentos Fiscais
Listar Eventos

Para listar todos os eventos vinculados a um documento fiscal, envie uma requisição GET para o endpoint /documentos/{uuid}/eventos.

GET /documentos/{uuid}/eventos

curl -X GET \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/00000000-0000-0000-0000-000000000000/eventos

A resposta da requisição terá o parâmetro data que será um array de objetos, onde cada objeto corresponderá a um evento do documento fiscal.

Tipos de Eventos por Modelo

Filtros Avançados

A API oferece filtros avançados para refinamento das consultas de documentos.

{
  "data_inicio": "2025-01-01",
  "data_fim": "2025-01-31"
}

{
  "data_inicio": "2025-01-08",
  "data_fim": "2025-01-15"
}

{
  "modelos": ["nfe"],
  "categorias": ["emitidas"],
  "status": ["aprovado"],
  "data_inicio": "2025-01-01",
  "data_fim": "2025-01-31"
}

{
  "modelos": ["nfe", "nfce", "cte", "mdfe"],
  "status": ["cancelado"],
  "data_inicio": "2025-01-01",
  "data_fim": "2025-01-31"
}

{
  "cnpj_cpf": "00000000000000",
  "categorias": ["emitidas", "recebidas"]
}

Filtros Avançados
Exemplos Visuais de Filtros

Filtros de Modelo

Selecione um ou mais modelos de documentos para filtrar

Filtros de Categoria

Filtre por documentos emitidos, recebidos ou citados

Filtros de Status

Consulte documentos por seu status atual

Filtros de Data

Defina períodos específicos para suas consultas

Documentos Fiscais
Exportar Documentos

Para realizar a exportação de relatórios dos documentos fiscais, envie uma requisição POST para o endpoint /documentos.

{
  "modelos": ["nfe"],
  "data_inicio": "2025-01-01",
  "data_fim": "2025-01-31",
  "formato": "csv"
}

{
  "download_url": "https://api.webmaniabr.com/downloads/documentos_2025_01.csv",
  "expires_at": "2025-01-16T00:00:00.000000Z"
}

{
  "modelos": ["nfe", "nfce", "cte", "mdfe"],
  "data_inicio": "2025-01-01",
  "data_fim": "2025-12-31",
  "formato": "zip",
  "incluir_xml": true,
  "incluir_pdf": true
}

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.