REST API de Nota Fiscal de Comunicação

Guia Rápido

Todas as solicitações na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://api.webmaniabr.com. O prefixo /2/ indica que atualmente estamos utilizando a versão 2.0 da API.

Todas as respostas são no formato objeto JSON.

Uma requisição bem-sucedida é indicada através do status HTTP, o status 2xx indica sucesso. Quando ocorrer uma falha na requisição, o corpo da resposta [body] continua no formato JSON, mas sempre contém o campo error. Por exemplo, caso a sua autenticação não seja bem-sucedida, será retornada a seguinte mensagem:

{
  "error": "Acesso restrito."
}

Módulos & Exemplos

Realize a emissão com apenas um clique na sua plataforma através dos módulos da Webmania® ou realize a integração para os diversos tipos de linguagens de programação.

• Ferramentas
  • Vídeo: Testar REST API sem linha de código

Autenticação

Para as solicitações, o corpo da requisição [body] deve ser enviado no formato JSON com os headers Content-Type e Accept definidos para application/json.

A autenticação é realizada através do cabeçalho HTTP (HTTP headers). É necessário o envio do header Authorization Bearer Token com o Access-Token da API 2.0, que é encontrado no painel Webmania®.

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 emissão seja realizado no servidor (back-end). No código fonte do aplicativo deve possuir somente a solicitação de emissão, enquanto o processo deve ser realizado em seu servidor.

Notificações

Para que a sua plataforma se mantenha sempre atualizada, a Webmania disponibiliza as notificações automáticas para todos os status da NFCom.

Cada NFCom possui um identificador único chamado de UUID. Este identificador deve ser utilizado para recepcionar e identificar a NFCom para atualizar as informações no seu banco de dados.

No momento em que for realizada a emissão da NFCom, 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 uuid, chave, serie, numero, status, motivo, xml, danfecom e log.

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

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

Segue exemplo do retorno via POST:

{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "chave": "35240712345678901234620010000001191234567890",
    "serie": 1,
    "numero": 119,
    "status": "aprovado",
    "motivo": "Autorizado o uso da NFCom",
    "xml": "https://api.webmaniabr.com/xmlnfcom/[uuid]",
    "xml_cancelamento": "https://api.webmaniabr.com/xmlnfcom/[uuid]/cancelamento",
    "danfecom": "https://api.webmaniabr.com/danfecom/[uuid]",
    "log": { ... }
}

Emissão de NFCom

Para emitir uma Nota Fiscal de Comunicação, envie a requisição no método POST para a URL /2/nfcom/emissao contendo no corpo da requisição os objetos no formato JSON.

curl -X POST \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ambiente": 2,
    "natureza_operacao": "Prestação de Serviços de Telecomunicação",
    "tipo_operacao": 1,
    ...
  }' \
  https://api.webmaniabr.com/2/nfcom/emissao

Segue abaixo exemplo de como emitir NFCom:

{
    "ambiente": 2,
    "natureza_operacao": "Prestação de Serviços de Telecomunicação",
    "tipo_operacao": 1,
    "municipio_fato_gerador": "3550308",
    "finalidade": 1,
    "consumidor_final": 1,
    "presenca_comprador": 2,
    "processo_emissao": 0,
    "assinante": {
        "codigo": "ASS123456",
        "tipo": 3,
        "tipo_servico": 2
    },
    "cliente": {
        "cpf": "12345678901",
        "razao_social": "João da Silva",
        "indicador_ie": 9,
        "endereco": {
            "logradouro": "Rua das Flores",
            "numero": "123",
            "bairro": "Centro",
            "codigo_municipio": "3550308",
            "municipio": "São Paulo",
            "uf": "SP",
            "cep": "01310100"
        }
    },
    "itens": [{
        "codigo": "SERV001",
        "codigo_classificacao": "1234567",
        "descricao": "Internet Banda Larga 100MB",
        "unidade": "MES",
        "quantidade": 1,
        "valor_unitario": 99.90,
        "valor_total": 99.90,
        "indicador_total": 1,
        "impostos": {
            "icms": {
                "origem": 0,
                "cst": "00",
                "modalidade_bc": 3,
                "valor_bc": 99.90,
                "aliquota": 25.00,
                "valor": 24.98,
                "codigo_cfop": "5307",
            },
            "pis": {
                "cst": "01",
                "valor_bc": 99.90,
                "aliquota": 0.65,
                "valor": 0.65
            },
            "cofins": {
                "cst": "01",
                "valor_bc": 99.90,
                "aliquota": 3.00,
                "valor": 3.00
            }
        }
    }]
}

A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos uuid, chave, serie, numero, status, motivo, modelo, xml, danfecom e log:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000", // Número único de identificação
  "chave": "35240712345678901234620010000001191234567890", // Chave de identificação na Sefaz
  "modelo": "62", // Modelo do documento
  "serie": 1, // Série da NFCom
  "numero": 119, // Número da NFCom
  "protocolo": "135240000123456", // Protocolo de autorização
  "status": "aprovado", // aprovado, reprovado, cancelado ou processando
  "motivo": "Autorizado o uso da NFCom", // Motivo do status
  "xml": "https://api.webmaniabr.com/xmlnfcom/550e8400-e29b-41d4-a716-446655440000",
  "danfecom": "https://api.webmaniabr.com/danfecom/550e8400-e29b-41d4-a716-446655440000",
  "log": "{...}" // Log de retorno da Sefaz
}

No momento em que for realizada a emissão da Nota Fiscal de Comunicação, caso tenha informado o parâmetro url_notificacao, será enviado o retorno no formato POST para a URL especificada. Saiba mais

Emissão de NFCom
Informações Gerais

A Nota Fiscal de Comunicação (NFCom) é um documento fiscal eletrônico, modelo 62, utilizado para documentar as prestações de serviços de telecomunicação.

A NFCom deve ser emitida por prestadores de serviços de telecomunicação, tais como:

Preencha os campos conforme finalidade da sua emissão. A tabela abaixo possui os campos necessários para a emissão de uma NFCom.

Emissão de NFCom
Comportamentos Especiais

A NFCom suporta indicadores específicos do setor de telecomunicações:

Emissão de NFCom
Assinante

As informações sobre o assinante do serviço são enviadas através do objeto assinante.

Emissão de NFCom -> Assinante
Contrato

Quando tipo_faturamento é 0 (Normal) ou 1 (Centralizado), é obrigatório informar os dados do contrato dentro do objeto assinante.contrato:

Segue abaixo exemplo de como informar o assinante com contrato:

{
    ...
    "tipo_faturamento": 0,
    "assinante": {
        "codigo": "ASS123456",
        "tipo": 3,
        "tipo_servico": 4,
        "contrato": {
            "numero": "12345/2025",
            "data_inicio": "2025-01-01",
            "data_fim": "2025-12-31"
        }
    },
    ...
}

Emissão de NFCom
Cliente

Os dados do tomador do serviço (cliente) são informados no objeto cliente, seguindo as regras abaixo.

Endereço do Cliente

Segue abaixo exemplo de como informar o cliente:

{
    ...
    "cliente": {
        "cpf": "12345678901",
        "razao_social": "João da Silva",
        "indicador_ie": 9,
        "email": ["joao@email.com", "joao.silva@email.com"],
        "endereco": {
            "logradouro": "Avenida Paulista",
            "numero": "1000",
            "complemento": "Apto 501",
            "bairro": "Bela Vista",
            "codigo_municipio": "3550308",
            "municipio": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "telefone": "1133334444"
        }
    },
    ...
}

Emissão de NFCom
Itens

Os serviços prestados e os bens/produtos relacionados são informados no array itens, onde cada elemento corresponde a um serviço ou produto.

Segue abaixo exemplo de como informar um item/serviço:

{
    ...
    "itens": [
        {
            "codigo": "SERV001",
            "descricao": "Internet Banda Larga 100MB",
            "unidade": "MES",
            "quantidade": 1,
            "valor_unitario": 99.90,
            "valor_total": 99.90,
            "indicador_total": 1,
            "impostos": {
                "codigo_classificacao": "0107",
                "icms": {
                    "origem": 0,
                    "cst": "00",
                    "codigo_cfop": "5307",
                    "modalidade_bc": 3,
                    "valor_bc": 99.90,
                    "aliquota": 25.00,
                    "valor": 24.98
                },
                "pis": {
                    "cst": "01",
                    "valor_bc": 99.90,
                    "aliquota": 0.65,
                    "valor": 0.65
                },
                "cofins": {
                    "cst": "01",
                    "valor_bc": 99.90,
                    "aliquota": 3.00,
                    "valor": 3.00
                }
            }
        }
    ],
    ...
}

Emissão de NFCom
Classe de Imposto

Existem duas formas de definir impostos para emissão da Nota Fiscal, através da Classe de Imposto ou diretamente na API.

A classe de imposto reúne informações fiscais do CÓDIGO DE CLASSIFICAÇÃO, ICMS, PIS, FUST e FUNTTEL para que seja realizado o cálculo automático dos impostos. É um procedimento simples, configurado uma única vez, que facilita emissões das notas fiscais de comunicação com maior agilidade.

Para utilizar a classe de imposto, basta informar o código de referência para emitir a nota fiscal conforme o exemplo abaixo:

{
    "itens": [
        {
            "descricao": "Plano Internet Fibra 200MB",
            "unidade": "GB",
            "quantidade": 1,
            "valor_unitario": 99.90,
            "valor_total": 99.90,
            "indicador_total": 1,
            "classe_imposto": "REF000000000"
        },
        {
            "descricao": "Modem hwauei fibra",
            "unidade": "un",
            "quantidade": 1,
            "valor_unitario": 280.50,
            "valor_total": 280.50,
            "indicador_total": 1,
            "classe_imposto": "REF000000000"
        }
    ]
}

Para efetuar o cadastro de uma classe de imposto de comunicação basta acessar este link: Cadastrar Classe de Imposto de comunicação. Após o cadastro, o código de referência da classe de imposto pode ser obtido no painel Webmania® clicando no botão Impostos.

Emissão de NFCom
Impostos

As informações tributárias são informadas dentro do objeto impostos de cada item. A NFCom suporta os seguintes impostos:

Segue abaixo exemplo completo de impostos de um item:

{
    ...
    "impostos": {
        "codigo_classificacao": "0107",
        "icms": {
            "origem": 0,
            "cst": "00",
            "codigo_cfop": "5307",
            "modalidade_bc": 3,
            "valor_bc": 99.90,
            "aliquota": 25.00,
            "valor": 24.98
        },
        "pis": {
            "cst": "01",
            "valor_bc": 99.90,
            "aliquota": 0.65,
            "valor": 0.65
        },
        "cofins": {
            "cst": "01",
            "valor_bc": 99.90,
            "aliquota": 3.00,
            "valor": 3.00
        },
        "fust": {
            "valor_bc": 99.90,
            "aliquota": 1.0,
            "valor": 1.00
        },
        "funttel": {
            "valor_bc": 99.90,
            "aliquota": 0.5,
            "valor": 0.50
        }
    },
    ...
}

Emissão de NFCom
Faturamento

As informações de faturamento e cobrança são opcionais e podem ser informadas no objeto fatura.

Períodos da Fatura

Segue abaixo exemplo de faturamento:

{
    ...
    "fatura": {
        "numero": "2024001234",
        "vencimento": "2024-08-10",
        "valor_original": 99.90,
        "valor_desconto": 0.00,
        "valor_liquido": 99.90,
        "codigo_barras": "00190000090194926000000099900000000000012345678",
        "periodos": [
            {
                "referencia": "2024-07",
                "vencimento": "2024-08-10",
                "valor": 99.90
            }
        ]
    },
    ...
}

Emissão de NFCom
Informações Opcionais

Autorizados para Download do XML

É possível autorizar CPFs ou CNPJs específicos para realizar o download do XML da NFCom diretamente na SEFAZ. Útil para contadores, parceiros comerciais ou sistemas integrados.

Exemplo de uso:

{
    ...
    "autorizar_download": [
        "12345678901",      // CPF
        "12345678901234",   // CNPJ
        "98765432100"       // CPF
    ],
    ...
}

Indicadores Especiais

A NFCom permite informar indicadores específicos do setor de telecomunicações que afetam a tributação e características do serviço.

Exemplo de uso com indicadores:

{
    ...
    "indicador_prepago": true,
    "indicador_cessao_meios": false,
    "indicador_servico_parcial": false,
    ...
}

Substituição Tributária

Informações relativas à substituição tributária. Grupo opcional utilizado quando há substituição tributária na operação.

Exemplo de uso:

{
    ...
    "substituicao": {
        "valor_bc_retido": 150.00,
        "valor_retido": 27.00,
        "codigo_cfop": "5949"
    },
    ...
}

Cofaturamento

Informações do cofaturamento. Utilizado quando a cobrança é realizada por outra operadora em regime de cofaturamento.

Exemplo de uso:

{
    ...
    "cofaturamento": {
        "cnpj": "12345678901234",
        "numero_nfcom": "123456"
    },
    ...
}

Nota de Entrada

Referência a uma nota fiscal de entrada de produto. Utilizado para relacionar a NFCom com uma nota fiscal de entrada quando aplicável.

Exemplo de uso:

{
    ...
    "nota_entrada": {
        "chave_acesso": "35240712345678901234550010000001191234567890",
        "tipo_nota_entrada": 1
    },
    ...
}

Funções
Download XML e PDF da NFCom

Na Webmania, a segurança da informação é nossa prioridade máxima. Por esse motivo, aplicamos restrições de acesso aos arquivos XML e PDF para garantir a segurança dos documentos fiscais.

O documento fiscal é criptografado com senha, e só pode ser visualizado após a confirmação do CPF/CNPJ do tomador da nota fiscal ou conforme formas de autenticação através do IP emissor, Credenciais de acesso, Token ou Conectado no painel Webmania®.

Segue abaixo as condições de acesso disponibilizados, após as restrições serem aplicadas:

Funções > Download XML e PDF da NFCom
Credenciais de acesso

Ao enviar as credenciais de acesso da empresa na HEADER da requisição, podem ser acessados todos os documentos fiscais emitidos pela empresa. Segue abaixo exemplo de como visualizar o PDF, utilizando as credenciais de acesso:

curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/danfecom/00000000-0000-0000-0000-000000000000/

A resposta do corpo da mensagem será no formato application/pdf ou text/xml, contendo no corpo da requisição o arquivo.

Funções > Download XML e PDF da NFCom
Token

Para disponibilizar o link do PDF e XML com segurança e eliminar a exigência da senha, é necessário a geração do token de forma criptografada utilizando a camada de segurança AES-256-CBC. Após gerar o token, deve ser enviado na URL do arquivo. Segue abaixo exemplo:

https://api.webmaniabr.com/danfecom/00000000-0000-0000-0000-000000000000/?token=[TOKEN]

Pare gerar o token criptografado, verifique o passo a passo disponibilizado no Github da Webmania juntamente com as funções nas linguagens em PHP, Python, Java, C# e Ruby: https://github.com/webmaniabr/DFeToken.

Funções
Consultar NFCom

Para consultar o status de emissão da NFCom, envie a requisição no método GET para URL /2/nfcom/consulta/ contendo na URL da requisição o UUID ou Chave de Acesso da NFCom.

Segue abaixo exemplo da consulta de uma NFCom:

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

A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos uuid, chave, status, motivo, serie, numero, xml, danfecom, log:

{
  "uuid": "00000000-0000-0000-0000-000000000000", // Número único de identificação
  "chave": "00000000000000000000000000000000000000000000", // Chave de identificação na Sefaz
  "status": "aprovado", // aprovado, reprovado, cancelado, processando ou contingencia
  "motivo": "Autorizado o uso da NFCom", // Motivo do status
  "serie": 1, // Série da NFCom
  "numero": 123, // Número da NFCom
  "xml": "https://api.webmaniabr.com/xmlnfcom/[chave]",
  "xml_cancelamento": "https://api.webmaniabr.com/xmlnfcom/[chave]/cancelamento",
  "danfecom": "https://api.webmaniabr.com/danfecom/[chave]",
  "log": "{...}" // Log de retorno da Sefaz
}

Funções
Cancelar NFCom

Para cancelar uma NFCom, envie a requisição no método PUT para URL /2/nfcom/cancelar/ contendo na requisição os parâmetros uuid ou chave da NFCom e justificativa do cancelamento.

Segue abaixo exemplo de cancelamento da NFCom:

curl -X PUT \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
   "chave": "00000000000000000000000000000000000000000000",
   "justificativa": "Cancelado por motivos administrativos."
}' \
https://api.webmaniabr.com/2/nfcom/cancelar/

A resposta do corpo da mensagem será no formato objeto JSON:

{
  "uuid": "00000000-0000-0000-0000-000000000000", // Número único de identificação
  "chave": "00000000000000000000000000000000000000000000", // Chave de identificação na Sefaz
  "status": "cancelado",
  "motivo": "Cancelado por motivos administrativos.", // Motivo do status
  "serie": 1, // Série da NFCom
  "numero": 123, // Número da NFCom
  "xml": "https://api.webmaniabr.com/xmlnfcom/[chave]",
  "xml_cancelamento": "https://api.webmaniabr.com/xmlnfcom/[chave]/cancelamento",
  "danfecom": "https://api.webmaniabr.com/danfecom/[chave]",
  "log": "{...}" // Log de retorno da Sefaz
}

Status do Serviço

Para verificar o status do serviço da SEFAZ:

          curl -X PUT \
          -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
          GET /2/nfcom/status
          
        

Resposta:

{
    "status": "online",
    "ambiente": 1,
    "tempo_medio": 850,
    "data_hora": "2024-07-01 10:00:00",
    "mensagem": "Serviço em operação"
}

Sistema de Contingência

A NFCom possui um sistema de contingência automático que garante a continuidade das emissões mesmo quando a SEFAZ está indisponível. O sistema é ativado automaticamente quando detecta falhas de comunicação com a SEFAZ.

Características do Sistema

• Ativação Automática: Quando a comunicação com a SEFAZ falha, o sistema automaticamente muda para modo de contingência
• Tipo de Emissão: NFCom utiliza tpEmis=2 (Contingência por ausência de comunicação)
• Armazenamento Local: As notas são armazenadas localmente e enviadas automaticamente quando a comunicação é restabelecida
• Job de Reprocessamento: Um job automático tenta reenviar as notas a cada 15 minutos
• Limite de Tentativas: Máximo de 21 tentativas (aproximadamente 5 horas)

Erros que Ativam Contingência

Os seguintes erros de comunicação ativam automaticamente o modo de contingência:

Processo de Contingência

1. Detecção: Sistema detecta falha na comunicação com a SEFAZ
2. Ativação: Modo de contingência é ativado automaticamente
3. Armazenamento: NFCom é armazenada localmente com status "contingência"
4. Notificação: Cliente recebe notificação via webhook (se configurado)
5. Reprocessamento: Job automático tenta reenviar a cada 15 minutos
6. Finalização: Quando enviada com sucesso, status é atualizado e nova notificação é enviada

Resposta em Contingência

Quando uma NFCom é emitida em contingência, a resposta inclui:

{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "contingencia",
    "motivo": "NFCom em contingência - será processada automaticamente",
    "contingencia": true,
    "tipo_emissao": 2,
    "danfecom": "https://api.webmaniabr.com/danfecom/550e8400-e29b-41d4-a716-446655440000",
    "xml": "https://api.webmaniabr.com/xmlnfcom/550e8400-e29b-41d4-a716-446655440000"
}

Códigos de Classificação

A tabela de classificação de produtos utilizada para validar o valor do campo cClass nos itens da NFCom determina diversas validações que são aplicadas na autorização da NFCom, além de determinar a natureza do valor do item na totalização da nota, uma vez que alguns tipos de produtos podem entrar deduzindo do valor total. Códigos que iniciarem pelo dígito 5 devem deduzir do valor total da nota, enquanto os demais códigos, iniciados por zero, serão itens somados no total da nota.

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

O retorno via POST na url_notificacao é enviado diretamente dos servidores da Webmania, através dos IPs estáticos de saída. Com a verificação do IP, é possível garantir que o retorno para sua aplicação está sendo realizada através de nossos servidores.

Todos os arquivos são armazenados na Amazon S3 que garante 99,999999999% de durabilidade dos arquivos e criptografia de ponta a ponta, seguindo critérios rígidos de segurança e controle interno.

Limite de requisições

API da Webmania® é protegida por um firewall que identifica de forma automática os acessos indevidos, suspeitos, credenciais incorretas e a localização da requisição, onde também pode limitar solicitações por segundo e o total de requisições para evitar o mal uso da API e a sobrecarga dos servidores. O uso indevido da API pode gerar mensagens de erro 503 ou 403 no retorno do cabeçalho da requisição. Segue abaixo especificações para uma correta integração:

• Localização do servidor: O firewall bloqueia por padrão o IP de servidores suspeitos ou de baixa reputação. Caso a sua comunicação via GET no endpoint https://webmaniabr.com/api/ ou https://api.webmaniabr.com retorne 403 Erro Forbidden por engano, por favor, entre em contato para liberarmos o IP do seu servidor.
• Limite de requisições:
  - GET: 4.500 requisições a cada 5 minutos (15/reqs/s).
  - POST/PUT/DELETE: 10.000 requisições a cada 5 minutos (30/reqs/s).
  Precisa de um volume maior de requisições? Por favor, entre em contato para liberação.
• Credenciais de acesso: Os endpoints exigem as credenciais de acesso válida e correta na HEADER da requisição, o envio incorreto é atribuído como uso indevido da API.
• URL de notificação: Realize a integração para obter todos os retornos da API via URL de notificação, dessa forma todos os processos podem ser realizados ao receber o retorno, como atualizar o banco de dados e o download do Danfe e XML.