Suporte Técnico Webmania®

Oi, estamos aqui para te ajudar 😄

A Webmania® conta com um time de Weblovers completo, com especialistas no emissor de Nota Fiscal, contabilidade, código de programação, módulos de loja virtual e principalmente no encantamento das nossas soluções.


Está com dúvidas?
Confira nossa Central de Ajuda

Ainda com dúvidas? Estamos aqui! 😊️

  • Envie um E-mail com todos os detalhes (abrir ticket)
  • Ou acesse o Painel Webmania® e converse via Chat (iniciar chat)

Horário de atendimento:
E-mail 24 horas por dia. Chat de Segunda a Sexta-feira das 9h às 18h, exceto feriados.

Webmania
  • Para sua empresa
  • Para desenvolvedores
  • Sobre nós
  • Contato
  • Área do cliente
  • Para sua empresa

    Emissor de Nota Fiscal
    Consulta de Nota Fiscal
    Consulta de CEP e IBGE
  • Para desenvolvedores

    Documentação
    Comece a integrar com as APIs da Webmania

    Guias

    Emitir Nota Fiscal Nota Fiscal de Serviço Consulta Nota Fiscal Consulta CEP

    Comece já

    Exemplos de códigos Biblioteca e SDKs Plugins Testar sem código
  • Sobre nós

    Notícias
    Quem somos
    Clientes
  • Contato

    WhatsApp
    Fale Conosco
  • Área do cliente

    Entrar
    Acessar painel
    Acesso rápido
    2º via Boleto Central de ajuda Financeiro
    Suporte técnico
    Abrir chamado
    Comercial
    Fale conosco
Entrar
  • REST API NFS-e
  • Guia Rápido
  • Autenticação
  • Notificações
  • Emissão de Nota Fiscal
    • Informações Gerais
    • Recibo Provisório de Serviço
      • Informações do RPS
      • Serviço
        • Informações
        • Impostos
        • Intermediário
      • Tomador
      • Construção Civil
  • Funções
    • Consultar Nota Fiscal
    • Cancelar Nota Fiscal
    • Substituir Nota Fiscal
  • Informações
    • Notas em Processamento
    • Infraestrutura
    • Limite de requisições
⚡ Acompanhe em tempo real: Status Webmania® | Monitor Sefaz | Telegram | Twitter
Versão: 3.7.2.1

REST API de Nota Fiscal de Serviço

Documentação para emissão de Nota Fiscal de Serviço (NFS-e)

Utilize a REST API de Nota Fiscal da Webmania®
A partir de R$32,90/mês: Experimente por 30 dias grátis

Utilize a REST API da Webmania®, para emissão de Nota Fiscal de Serviço disponível em 464 municípios. Deseja emitir outros modelos? Ver documentação

Disponibilidade e Segurança
Alta disponibilidade, escalonável e servidores redundantes no mais alto nível de segurança PCI DSS na líder global de cloud computing Amazon Web Services.
Armazenamento
Arquivamento seguro, criptografado e ilimitado das Notas Fiscais na tecnologia Amazon S3, que garante 99,999999999% de durabilidade dos arquivos XML.
Integração REST API
Compatível com todas as linguagens de programação, através da comunicação via JSON. Garantia de baixa latência com mais de 200 pontos de presença na rede Amazon Web Services.
Numeração automática
Emita Notas Fiscais ao mesmo tempo via API, Ponto de Venda, Loja Virtual e painel Webmania®, onde todas as numerações são gerenciadas e auditadas automaticamente.
DANFE e Envio por e-mail
Geração de DANFE automático e compatível com todas as impressoras comuns e térmicas, com envio seguro da Nota Fiscal por e-mail.
Suporte Especializado
Atendimento 100% online e humano pelos nossos Weblovers, especialistas na área contábil e programação para te ajudar. #weblovers #webmaniabr

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 nós estamos utilizando a versão 2.0 da API.

URL HTTP Verb Função
/2/nfse/emissao POST Emissão de Nota Fiscal
/2/nfse/cancelar PUT Cancelar Nota Fiscal
/2/nfse/substituir POST Substituição de Nota Fiscal
/2/nfse/consultar GET Consulta de Nota Fiscal

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 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 sua autenticação não seja bem sucedida irá retornar a seguinte mensagem:

{
  "msg": "Acesso restrito."
}

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 definido 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 Nota Fiscal.

Cada Nota Fiscal possui um número único de identificação chamado de UUID, este número deve ser utilizado para recepcionar e identificar a Nota Fiscal para atualizar as informações no seu banco de dados.

No momento que realizado a emissão da Nota Fiscal, 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, status, motivo, numero, codigo_verificacao, serie_rps, numero_rps, xml e data.

Parâmetro Tipo Descrição
uuid string Número único de identificação da Nota FiscalDeve ser utilizado a UUID para recepcionar o retorno da notificação.
status string Status da Nota Fiscal
aprovado
reprovado
cancelado
processamento
contingencia
motivo string Motivo do status
Ex.: Autorizado o uso da NFS-e
numero número Número da Nota Fiscal
Gerenciado automaticamente pela prefeitura do município.
codigo_verificacao string Código de verificação da Nota Fiscal
serie_rps número Série do RPS da Nota Fiscal
numero_rps número Número do RPS da Nota Fiscal
modelo string Modelo da Nota Fiscal
nfse
lote_rps
xml string URL do XML da Nota Fiscal
log array Log de retorno da prefeitura.
data array Informações enviadas para emissão da Nota Fiscal

Emissão de Nota Fiscal

Para emitir uma Nota Fiscal de Serviço, envie a requisição no método POST para a URL /2/nfse/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": 1,
    "rps": [...]
  }' \
  https://api.webmaniabr.com/2/nfse/emissao

Segue abaixo exemplo de como Emitir Nota Fiscal de Serviço:

{
  "ambiente": 2,
  "rps": [
    {
      "natureza_operacao": 3,
      "servico": {
        "valor_servicos": "15.00",
        "codigo_cnae": "00000000",
        "codigo_servico": "00.00",
        "discriminacao": "Prestação de Serviço referente ao mês X",
        "impostos": {
          "iss": "2.00",
          "pis": "0.00",
          "cofins": "0.00",
          "csll": "0.00",
          "ir": "0.00",
          "inss": "0.00"
        }
      },
      "tomador": {
        "cnpj": "00.000.000/0000-00",
        "razao_social": "Empresa 1",
        "endereco": "Av. Brg. Faria Lima",
        "complemento": "Escritório",
        "numero": 1000,
        "bairro": "Itaim Bibi",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "00000-000",
        "telefone": "(00) 0000-0000",
        "email": "nome@email.com"
      }
    }
  ]
}

A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos uuid,status, motivo, numero, codigo_verificacao, serie_rps, numero_rps, xml e log:

{
  "uuid": "43eace5c-8008-4f6c-b830-b6d52d7ff90c", // Número único de identificação
  "status": "aprovado", // aprovado, reprovado, cancelado, processamento ou contingencia
  "motivo": "Autorizado o uso da NFS-e", // Motivo do status
  "numero": "25000", // Número da NF-e
  "codigo_verificacao": "SFH-046", // Número de série
  "modelo": "nfse", // Modelo da Nota Fiscal (nfse, lote_rps)
  "serie_rps": "A1", // Série do RPS
  "numero_rps": "2000", // Número do RPS
  "xml": "http://api.webmaniabr.com/xmlnfse/uuid/",
  "log": "{...}" // Log de retorno da prefeitura
}

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

Emissão de Nota Fiscal
Informações Gerais

A tabela abaixo possui os campos necessários para a emissão de uma Nota Fiscal de Serviço.

Preencha os campos conforme finalidade da sua emissão, alguns parâmetros possuem informações adicionais que podem ser acessadas ao clicar em cima.

Parâmetro NFS-e Tipo Tam. Descrição
ambiente
número 1 Ambiente de emissão da Nota Fiscal. Alguns municípios NÃO possuem ambiente de homologação.
1 - Produção
2 - Homologação
rps
array (objetos) 1-50 RPS que serão enviados para emissão.

Obs.: Alguns municípios não permitem o envio de Lote de RPS, sendo possível emitir somente uma NFS-e a cada requisição.
url_notificacao
string --- URL de notificação para todas as atualizações de status da Nota Fiscal

Emissão de Nota Fiscal
Recibo Provisório de Serviço

O RPS (Recibo Provisório de Serviço) é um documento que contém todas as informações de uma prestação de serviços, possui validade temporária e deve ser convertido em Nota Fiscal de Serviço dentro do prazo definido pela prefeitura.

A API da WebmaniaBR gera o RPS para cada elemento informado no array rps, em seguida são enviados para a prefeitura realizar a validação. Caso seja aprovado, o RPS é convertido em Nota Fiscal de Serviço.

Abaixo estão os parâmetros que podem ser informados para cada RPS:

Parâmetro NFS-e Tipo Tam. Descrição
natureza_operacao
número 1 Código de natureza da operação
1 - Tributação no município
2 - Tributação fora do município
3 - Isenção
4 - Imune
5 - Exigibilidade suspensa por decisão judicial
6 - Exigibilidade suspensa por procedimento administrativo
servico
objeto --- Informações do Serviço
tomador
objeto --- Informações do Tomador
construcao_civil
objeto --- Informações Construção Civil

Emissão de Nota Fiscal > RPS
Informações do Serviço

As informações do serviço são montados dentro do objeto servico conforme mostrado na tabela Informações do RPS.

Parâmetro NFS-e Tipo Tam. Descrição
valor_servico
string 15v2 Valor total dos serviços prestados
deducoes
string 15v2 Valor da dedução da Base de Cálculo
desconto_condicionado
string 15v2 Valor do desconto condicionado
desconto_incondicionado
string 15v2 Valor do desconto incondicionado
impostos
objeto --- Impostos da Nota Fiscal de Serviço
responsavel_retencao_iss
número 15v2 Responsável pela retenção do ISS
1 - Tomador
2 - Intermediário
outras_retencoes
string 15v2 Valor das outras retenções
codigo_cnae
string 7 Código CNAE
codigo_servico
string 5 Código de serviço
00.00
codigo_tributacao_municipio
string 1-20 Código de Tributação no município
discriminacao
string 1-2000 Discriminação do serviço
exigibilidade_iss
número 1 Exigibilidade do ISS
1 - Exigível
2 - Não incidência
3 - Isenção
4 - Exportação
5 - Imunidade
6 - Exigibilidade suspensa por decisão judicial
7 - Exigibilidade suspensa por processo administrativo
numero_processo
string 1-30 Número do processo judicial ou administrativo de suspensão da exigibilidade do ISS
codigo_nbs
string 1-9 Código da Nomenclatura Brasileira de Serviços
intermediario
objeto --- Informações do Intermediário do Serviço

Emissão de Nota Fiscal > RPS > Serviço
Impostos

As informações dos impostos são montados dentro do objeto impostos conforme mostrado na tabela Informações do Serviço.

Os impostos também podem ser informados através da classe de imposto no painel WebmaniaBR. Nesse caso, deverá ser informado apenas o parâmetro classe_imposto com a referência (REF) da classe de imposto configurada.

Parâmetro NFS-e Tipo Tam. Descrição
classe_imposto
string --- Referência para a Classe de imposto configurada no painel WebmaniaBR
REF00000000
iss
string 3v2 Alíquota do ISS
0.00
pis
string 3v2 Alíquota do PIS
0.00
cofins
string 3v2 Alíquota do COFINS
0.00
inss
string 3v2 Alíquota do INSS
0.00
ir
string 3v2 Alíquota do IR
0.00
csll
string 3v2 Alíquota do CSLL
0.00

Emissão de Nota Fiscal > RPS > Serviço
Intermediário

As informações do intermediário do serviço são montados dentro do objeto intermediario conforme mostrado na tabela Informações do Serviço.

Parâmetro NFS-e Tipo Tam. Descrição
cpf
Pessoa Física
string 11 Número do CPF
000.000.000-00
nome_completo
Pessoa Física
string 2-150 Nome completo
cnpj
Pessoa Jurídica
string 14 Número do CNPJ
00.000.000/0000-00
razao_social
Pessoa Jurídica
string 2-150 Razão social
im
string 1-15 Inscrição municipal

Emissão de Nota Fiscal > RPS
Tomador

As informações do tomador do serviço são montados dentro do objeto tomador conforme mostrado na tabela Informações do RPS.

Parâmetro NFS-e Tipo Tam. Descrição
cpf
Pessoa Física
string 11 Número do CPF
000.000.000-00
nome_completo
Pessoa Física
string 2-150 Nome completo
cnpj
Pessoa Jurídica
string 14 Número do CNPJ
00.000.000/0000-00
razao_social
Pessoa Jurídica
string 2-150 Razão social
im
string 1-15 Inscrição municipal
nif
string 1-40 Número de Identificação Fiscal
endereco
string 1-40 Endereço do tomador
numero
string 1-40 Número do endereço do tomador
complemento
string 1-40 Complemento do endereço do tomador
bairro
string 1-40 Bairro do endereço do tomador
cidade
string 1-40 Cidade do endereço do tomador
uf
string 1-40 Estado do endereço do tomador
cep
string 1-40 CEP do endereço do tomador
email
string 1-40 E-mail do tomador para envio da NFS-e
telefone
string 1-40 Telefone do tomador

Emissão de Nota Fiscal > RPS
Construção Civil

As informações de construção civil devem ser informadas caso o serviço prestado esteja relacionado à obras de construção civil. As informações são montadas dentro do objeto construcao_civil conforme mostrado na tabela Informações do RPS.

Parâmetro NFS-e Tipo Tam. Descrição
codigo_obra
string 1-15 Código da obra
art
string 1-15 Código da Anotação de Responsabilidade Técnica

Funções
Consultar Nota Fiscal

Para consultar o status de emissão da Nota Fiscal de Serviço, envie a requisição no método GET para URL /2/nfse/consulta/ contendo na requisição o parâmetro uuid ou numero da Nota Fiscal.

Parâmetro NFS-e Tipo Tam. Descrição
uuid
string 36 UUID da NFS-e

Segue abaixo exemplo da consulta de uma Nota Fiscal:

curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "uuid": "43eace5c-8008-4f6c-b830-b6d52d7ff90c"
}' \
https://api.webmaniabr.com/2/nfse/consulta

A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos uuid, status, motivo, numero, codigo_verificacao, serie_rps, numero_rps, xml e log:

{
  "uuid": "43eace5c-8008-4f6c-b830-b6d52d7ff90c", // Número único de identificação
  "status": "aprovado", // aprovado, reprovado, cancelado, processamento ou contingencia,
  "motivo": "Autorizado o uso da NFS-e", // Motivo do status
  "numero": "25000", // Número da NFS-e
  "codigo_verificacao": "UIO-345", // Código de verificação
  "serie_rps": "A1", // Série do RPS
  "numero_rps": "2000", // Número do RPS
  "modelo": "nfe", // Modelo da Nota Fiscal (nfse, lote_rps)
  "xml": "http://api.webmaniabr.com/xmlnfse/uuid/",
  "log": "{...}" // Log de retorno da prefeitura
}

Funções
Cancelar Nota Fiscal

Para cancelar uma Nota Fiscal de Serviço, envie a requisição no método PUT para URL /2/nfse/cancelar/ contendo na requisição os parâmetros uuid e motivo da Nota Fiscal.

Parâmetro NFS-e Tipo Tam. Descrição
uuid
string 36 UUID da NFS-e
motivo
número 1 Motivo do cancelamento
1 - Erro na emissão
2 - Serviço não prestado
4 - Duplicidade da nota

Segue abaixo exemplo de cancelamento da Nota Fiscal:

curl -X PUT \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
   "uuid": "43eace5c-8008-4f6c-b830-b6d52d7ff90c",
   "motivo": 1
}' \
https://api.webmaniabr.com/2/nfse/cancelar/

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

{
  "uuid": "43eace5c-8008-4f6c-b830-b6d52d7ff90c", // Número único de identificação
  "status": "cancelado",
  "xml": "https://api.webmaniabr.com/xmlnfse/uuid",
  "log": "{...}" // Log de retorno da prefeitura
}

Funções
Substituir Nota Fiscal

Para substituir uma Nota Fiscal de Serviço, envie a requisição no método POST para URL /2/nfse/substituir/ contendo na requisição os parâmetros uuid e motivo da Nota Fiscal.

Parâmetro NFS-e Tipo Tam. Descrição
ambiente
número 1 Ambiente de emissão da substituição. 1 - Produção
2 - Homologação
codigo_verificacao
string --- Código de verificação da Nota Fiscal a ser substituída
motivo
número 1 Motivo da substituição
1 - Erro na emissão
2 - Serviço não prestado
4 - Duplicidade da nota
rps
objeto 1 RPS que será convertido em Nota Fiscal de Serviço e irá substituir a nota informada.

Segue abaixo exemplo de substituição de uma Nota Fiscal:

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
   "ambiente": 1,
   "codigo_verificacao": "XXX-XXX",
   "motivo": 1,
   "rps": {
     ...
   }
}' \
https://api.webmaniabr.com/2/nfse/substituir/

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

{
  "uuid": "43eace5c-8008-4f6c-b830-b6d52d7ff90c", // Número único de identificação
  "status": "aprovado",
  "numero": "340",
  "codigo_verificacao": "XXX-XXX",
  "serie_rps": "A2",
  "numero_rps": "99",
  "nfse_substituida": {
    "uuid": "8f54e040-4344-4169-a9e7-daacd35bcfb1",
    "numero": "95",
    "codigo_verificacao": "XXX-XXX",
  },
  "xml": "https://api.webmaniabr.com/xmlnfse/uuid",
  "log": "{...}" // Log de retorno da prefeitura
}

Notas Fiscais em Processamento

A Nota Fiscal de Serviço (NFS-e) pode ser emitida de forma síncrona ou assíncrona, dependendo da disponibilidade de cada município, exceto quando é feito um envio de vários RPS, nesse caso a emissão sempre será assíncrona podendo variar de segundos a minutos, e nestes casos o status da Nota Fiscal é definida inicialmente como processando. É necessário aguardar o retorno da prefeitura antes de solicitar a emissão de uma nova Nota Fiscal.

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

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 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 API de Nota Fiscal da Webmania® não possui limite de requisições, porém existem regras automáticas realizadas pelo Firewall para evitar o mal uso da API e a sobrecarga nos servidores. O uso incorreto da API pode gerar o erro 503 ou 403 no retorno do cabeçalho da requisição. Segue abaixo as 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.
  • 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.
  • Requisições GET: O método GET deve ser utilizado de forma sistemática, o recomendado são 2 solicitações por segundo. Um alto índice de requisições via GET é atribuído como uso indevido da API.

Soluções

Emissor de Nota Fiscal Consulta de Nota Fiscal Consulta de CEP e IBGE Nota Fiscal WooCommerce

Documentação

API Nota Fiscal API Nota Fiscal de Serviço API Consulta de Nota Fiscal API CEP e IBGE API Gerencial B2B

Webmania

Blog Clientes Sobre nós Política de Cookies Política de Privacidade Contratos

Acesso rápido

Fale conosco Painel do Cliente Central de Ajuda 2ª via de Boleto Status Webmania® Monitor Sefaz
Facebook Webmania Instagram Webmania Linkedin Webmania Twitter Webmania GitHub Webmania Telegram Webmania Youtube Webmania
Webmania

Copyright © 2009-2022 Webmania®.
Webmania® é uma marca registrada e de uso exclusivo da WebmaniaBR Serviços Empresariais LTDA
CNPJ: 11.290.027/0001-82 e WebmaniaBR Desenvolvimento de Software LTDA - CNPJ: 30.902.296/0001-05
sediadas na Av. Anita Garibaldi, 850, Sala 809 Royal - Curitiba, PR - CEP 80540-180

Grupo WMBR
Voltar para o topo