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
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."
}
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.
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 Fiscalaprovado |
motivo | string | Motivo do statusEx.: 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 Fiscalnfse |
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 |
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
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 | |
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 |
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 | |
servico | objeto | --- | Informações do Serviço | |
tomador | objeto | --- | Informações do Tomador | |
construcao_civil | objeto | --- | Informações Construção Civil |
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 | |
outras_retencoes | string | 15v2 | Valor das outras retenções | |
codigo_cnae | string | 7 | Código CNAE | |
codigo_servico | string | 5 | Código de serviço00.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 | |
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 |
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 WebmaniaBRREF00000000 | |
iss | string | 3v2 | Alíquota do ISS0.00 | |
pis | string | 3v2 | Alíquota do PIS0.00 | |
cofins | string | 3v2 | Alíquota do COFINS0.00 | |
inss | string | 3v2 | Alíquota do INSS0.00 | |
ir | string | 3v2 | Alíquota do IR0.00 | |
csll | string | 3v2 | Alíquota do CSLL0.00 |
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 CPF000.000.000-00 | |
nome_completo Pessoa Física | string | 2-150 | Nome completo | |
cnpj Pessoa Jurídica | string | 14 | Número do CNPJ00.000.000/0000-00 | |
razao_social Pessoa Jurídica | string | 2-150 | Razão social | |
im | string | 1-15 | Inscrição municipal |
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 CPF000.000.000-00 | |
nome_completo Pessoa Física | string | 2-150 | Nome completo | |
cnpj Pessoa Jurídica | string | 14 | Número do CNPJ00.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 |
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 |
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
}
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 |
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
}
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 | |
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 | |
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
}
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
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:
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:
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.