REST API de Nota Fiscal de Serviç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 nós 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 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.

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.

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:

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.

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.

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.

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.

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.

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.

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.

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.

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