Comece agora
Teste Grátis!
Conheça as soluções Webmania® para o seu negócio. Teste grátis as nossas soluções.
Conversar no WhatsApp*Teste grátis para novos clientes.
Consulte condições e serviços disponíveis.
Conheça as soluções Webmania® para o seu negócio. Teste grátis as nossas soluções.
Conversar no WhatsApp*Teste grátis para novos clientes.
Consulte condições e serviços disponíveis.
Utilize a REST API da Webmania® para consultar, armazenar e baixar os documentos fiscais recebidos contra o CNPJ da sua empresa ou autorizados através da tag autXML.
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:
| Endpoint | HTTP Verb | Função |
|---|---|---|
/empresas | POST | Cadastrar uma nova empresa |
/documentos | POST | Listar ou exportar documentos fiscais |
/documentos/{uuid}/eventos | POST | Registrar evento para um documento |
/empresas/{empresa_uuid}/municipios-nfse | POST | Cadastrar monitoramento para município (NFS-e) |
/documentos/{uuid} | GET | Buscar documento pelo UUID |
/documentos/importacoes | POST | Importar documentos |
/empresas | GET | Listar todas as empresas cadastradas |
/empresas/{uuid} | GET | Buscar empresa pelo UUID |
/municipios-nfse | GET | Listar municípios disponíveis para NFS-e |
/empresas/{empresa_uuid}/municipios-nfse | GET | Listar municípios monitorados da empresa |
/empresas/{uuid} | PUT | Atualizar dados de uma empresa |
/empresas/{empresa_uuid}/municipios-nfse/{uuid} | PUT | Atualizar credenciais do município monitorado (NFS-e) |
/empresas/{empresa_uuid}/municipios-nfse/{uuid} | DELETE | Remover monitoramento do município (NFS-e) |
Sempre envie o corpo da requisição no formato JSON, e o cabeçalho Content-Type deve estar definido como application/json.
A resposta da API estará sempre no formato JSON, o padrão da estrutura da resposta está disponível nesta seção da documentaçã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.
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.
| Código | Significado | Sucesso | Descrição |
|---|---|---|---|
200 | OK | Operações bem-sucedidas (GET|PUT|DELETE). | |
201 | Created | Criação de recursos (POST). | |
400 | Bad Request | A requisição está incorreta ou possui parâmetros inválidos no corpo (body) da requisição. | |
401 | Unauthorized | Falha na autenticação. Verifique o token de acesso enviado. | |
403 | Forbidden | Acesso negado. Não possui permissão para realizar a operação. |
Exemplo de resposta para uma requisição com erro:
{
"error": "Parâmetro inválido: cnpj. O valor ABCD não é um CNPJ válido."
}
Atualmente a API de Gestão de Documentos Fiscais realiza a consulta, download e armazenamento dos seguintes documentos fiscais:
| Modelo | Código | Abrangência | Tomadas | Emitidas | Descrição |
|---|---|---|---|---|---|
| NF-e | nfe | Nacional | Nota Fiscal Eletrônica | ||
| NFS-e | nfse | Consulte | Nota Fiscal de Serviço Eletrônica | ||
| CT-e | cte | Nacional | Conhecimento de Transporte Eletrônico | ||
| MDF-e | mdfe | Nacional | Manifesto Eletrônico de Documentos Fiscais |
O processo de consulta ocorre de forma automática e periódica com intervalo mínimo de uma hora, garantindo que as informações estejam sempre atualizadas e disponíveis. As consultas são realizadas das notas fiscais tomadas (recebidas contra o CNPJ/CPF da empresa e CNPJ/CPF citadas na tag autXML) ou emitidas (conforme regras de cada município).
As tabelas abaixo listam as condições de participação da empresa no documento fiscal:
| Tipo | Descrição | |
|---|---|---|
Emitidas | ❌ | O sistema não realiza o download do documento fiscal quando a empresa é a própria emitente. A legislação determina que o emitente deve armazenar por 5 anos o XML do documento emitido. |
Tomador | ✅ | O sistema realiza o download da versão completa do XML do documento quando a empresa manifesta o recebimento. A Webmania realiza automaticamente a manifestação como "Ciência da Operação" se o documento estiver dentro do prazo de 10 dias após a emissão. Caso contrário, será necessário realizar a manifestação manualmente. |
Transportador | ✅ | O sistema realiza o download da versão completa do XML quando a empresa está informada como transportador no documento fiscal, indicado no grupo X03 do XML. |
Terceiros | ✅ | O sistema realiza o download da versão completa do XML quando o CNPJ/CPF da empresa está indicado na tag autXML do documento fiscal. |
| Tipo | Descrição | |
|---|---|---|
Emitente | ✅ | Realiza o download da versão completa do XML do documento, conforme disponibilizado pelo município. |
Tomador | ✅ | Realiza o download da versão completa do XML do documento caso a empresa esteja informada como tomador dos serviços. |
| Tipo | Descrição | |
|---|---|---|
Emitente | ❌ | O sistema não realiza o download do documento fiscal quando a empresa é a própria emitente. A legislação determina que o emitente deve armazenar por 5 anos o XML do documento emitido. |
Remetente | ✅ | Realiza o download da versão completa do XML quando a empresa esteja informada como remetente no documento fiscal. |
Destinatário | ✅ | Realiza o download da versão completa do XML quando a empresa esteja informada como destinatário no documento fiscal. |
Recebedor | ✅ | Realiza o download da versão completa do XML quando a empresa esteja informada como recebedor no documento fiscal. |
Expedidor | ✅ | Realiza o download da versão completa do XML quando a empresa esteja informada como expedidor no documento fiscal. |
Tomador | ✅ | Realiza o download da versão completa do XML quando a empresa esteja informada como tomador no documento fiscal. |
Terceiros | ✅ | O sistema realiza o download da versão completa do XML quando o CNPJ/CPF da empresa está indicado na tag autXML do documento fiscal. |
| Tipo | Descrição | |
|---|---|---|
Emitente | ❌ | O sistema não realiza o download do documento fiscal quando a empresa é a própria emitente. A legislação determina que o emitente deve armazenar por 5 anos o XML do documento emitido. |
Contratante do serviço | ✅ | Realiza o download da versão completa do XML caso a empresa seja a responsável pela contratação do serviço de transporte no modelo rodoviário. |
Proprietário do veículo | ✅ | Realiza o download da versão completa do XML caso a empresa seja proprietária do veículo de transporte no modelo rodoviário. |
Terceiros | ✅ | O sistema realiza o download da versão completa do XML quando o CNPJ/CPF da empresa está indicado na tag autXML do documento fiscal. |
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.
| Parâmetro | Tipo | Descrição |
|---|---|---|
tipo_notificacao | número | Tipo da notificação1 - Documentos fiscais |
data | objeto | Informações do documento fiscal, evento ou empresaTipo 1: dados do documento fiscal |
documento | objeto | Documento relacionado ao evento geradoObjeto do documento de acordo com o modelo |
Observação: As notificações de vencimento do Certificado Digital (tipo_notificacao = 3) começam a ser enviadas quando restam 15 dias para a data de vencimento e seguem diariamente até a inclusão de um novo certificado.
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,
...
}
}Importante: Configuração obrigatória para gerenciar os documentos fiscais.
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.
Esta seção explica como gerenciar empresas na API, incluindo o cadastro, a listagem, a consulta e a atualização. O gerenciamento adequado das empresas é fundamental para garantir o funcionamento correto da API.
Ao cadastrar uma empresa, o sistema inicia automaticamente a consulta e armazenamento dos documentos fiscais recebidos no modelo NF-e (Nota Fiscal Eletrônica) para o CNPJ ou CPF informado. Para habilitar a consulta de outros modelos, é necessário especificá-los no parâmetro modelos_download.
modelos_download a qualquer momento.modelos_download, o processo de monitoramento ocorre automaticamente.modelos_download, é necessário configurar o monitoramento: Para cadastrar uma empresa, envie a requisição no método POST para a URL /empresas incluindo no corpo da requisição os seguintes parâmetros:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
cnpjPessoa Jurídica | string | CNPJ da empresa00.000.000/0000-00 | |
razao_socialPessoa Jurídica | string | Razão Social da empresa | |
cpfPessoa Física | string | CPF da empresa000.000.000-00 | |
nome_completoPessoa Física | string | Nome da empresa | |
im | string | Inscrição MunicipalConsulte o município para verificar a obrigatoriedade. Saiba mais | |
cep | string | CEP do endereço da empresa | |
certificado_base64 | Base64 Encode | Certificado Digital A1 Saiba mais | |
certificado_senha | string | Senha do Certificado Digital A1 | |
url_notificacao | string | URL do webhook para envio das notificações Notificação de novos documentos fiscais recebidos, atualização de status e outros eventos relacionados aos documentos fiscais monitorados. | |
modelos_download | array | Modelos de documentos fiscais monitorados nfe (padrão) | |
ambiente_download | número | Ambiente de monitoramento dos documentos fiscais 1 - Produção (padrão) Observação: É monitorado os documentos fiscais apenas no ambiente selecionado, alterne entre os ambientes a qualquer momento. | |
dfe_retroativas | boolean | Ativar download de documentos fiscais retroativos (com data de emissão anterior ao cadastro da empresa na API de gestão).Padrão: falseAtenção: Uma vez que essa opção é ativada, não é possível desativá-la novamente para a respectiva empresa. |
Segue abaixo exemplo de como cadastrar uma empresa:
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"cnpj": "00.000.000/0000-00",
"razao_social": "Nome da empresa LTDA",
"cep": "00000-000",
"certificado_base64": "...",
"certificado_senha": "abc12345",
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/empresasA resposta do corpo da mensagem será no formato objeto JSON, contendo as informações da empresa cadastrada:
| Parâmetro | Tipo | Descrição |
|---|---|---|
uuid | string | UUID da empresa cadastrada |
cnpj|cpf | string | CNPJ ou CNPJ da empresa |
razao_social|nome_completo | string | Razão social ou Nome completo da empresa |
im | string | Inscrição municipal |
endereco.cep | string | CEP do endereço |
endereco.municipio | string | Município |
endereco.codigo_municipio | integer | Código IBGE do município |
endereco.estado | string | Sigla da UF |
modelos_download | array | Modelos de documentos fiscais monitorados |
ambiente_download | boolean | Indica qual ambiente de download habilitado |
certificado_vencimento | string | Data de vencimento do Certificado Digital A1 Importante: acompanhe o vencimento do Certificado Digital A1 para um completo funcionamento da API. |
url_notificacao | boolean | URL que será encaminhado as notificações |
dfe_retroativas | boolean | Download de documentos fiscais retroativos. |
dfe_retroativas_total | número | Quantidade de documentos fiscais retroativos encontrados. Observação: Este parâmetro é retornado apenas se a opção dfe_retroativas estiver desativada. Ative a opção para ter acesso aos documentos fiscais retroativos. |
{
"uuid": "00000000-0000-0000-0000-000000000000",
"cnpj": "00.000.000/0000-00",
"razao_social": "Nome da empresa LTDA",
"endereco": {
"cep": "00000-000",
"municipio": "São Paulo",
"codigo_municipio": 3550308,
"estado": "SP"
},
"certificado_vencimento": "2025-08-28 19:49:22",
"modelos_download": ["nfe", "nfse", "mdfe", "cte"]
}
Para atualizar uma empresa, envie a requisição no método PUT para a URL /empresas/{uuid}, incluindo no corpo da requisição (body) apenas os parâmetros que deseja atualizar.
curl -X PUT \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"certificado_base64": "...",
"certificado_senha": "abc12345",
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/empresas/00000000-0000-0000-0000-000000000000A resposta do corpo da mensagem será no formato objeto JSON, contendo as informações da empresa atualizada:
| Parâmetro | Tipo | Descrição |
|---|---|---|
uuid | string | UUID da empresa cadastrada |
cnpj|cpf | string | CNPJ ou CNPJ da empresa |
razao_social|nome_completo | string | Razão social ou Nome completo da empresa |
im | string | Inscrição municipal |
endereco.cep | string | CEP do endereço |
endereco.municipio | string | Município |
endereco.codigo_municipio | integer | Código IBGE do município |
endereco.estado | string | Sigla da UF |
modelos_download | array | Modelos de documentos fiscais monitorados |
ambiente_download | boolean | Indica qual ambiente de download habilitado |
certificado_vencimento | string | Data de vencimento do Certificado Digital A1 Importante: acompanhe o vencimento do Certificado Digital A1 para um completo funcionamento da API. |
url_notificacao | boolean | URL que será encaminhado as notificações |
dfe_retroativas | boolean | Download de documentos fiscais retroativos. |
dfe_retroativas_total | número | Quantidade de documentos fiscais retroativos encontrados. Observação: Este parâmetro é retornado apenas se a opção dfe_retroativas estiver desativada. Ative a opção para ter acesso aos documentos fiscais retroativos. |
{
"uuid": "00000000-0000-0000-0000-000000000000",
"cnpj": "00.000.000/0000-00",
"razao_social": "Nome da empresa LTDA",
"endereco": {
"cep": "00000-000",
"municipio": "São Paulo",
"codigo_municipio": 3550308,
"estado": "SP"
},
"certificado_vencimento": "2025-08-28 19:49:22",
"modelos_download": ["nfe", "nfse", "mdfe", "cte"]
}
Para realizar a consulta da UUID de uma empresa, envie a requisição no método GET para a URL /empresas/{uuid}. Segue abaixo exemplo da consulta UUID:
curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/empresas/00000000-0000-0000-0000-000000000000A resposta do corpo da mensagem será no formato objeto JSON, contendo as informações da empresa consultada:
| Parâmetro | Tipo | Descrição |
|---|---|---|
uuid | string | UUID da empresa cadastrada |
cnpj|cpf | string | CNPJ ou CNPJ da empresa |
razao_social|nome_completo | string | Razão social ou Nome completo da empresa |
im | string | Inscrição municipal |
endereco.cep | string | CEP do endereço |
endereco.municipio | string | Município |
endereco.codigo_municipio | integer | Código IBGE do município |
endereco.estado | string | Sigla da UF |
modelos_download | array | Modelos de documentos fiscais monitorados |
ambiente_download | boolean | Indica qual ambiente de download habilitado |
certificado_vencimento | string | Data de vencimento do Certificado Digital A1 Importante: acompanhe o vencimento do Certificado Digital A1 para um completo funcionamento da API. |
url_notificacao | boolean | URL que será encaminhado as notificações |
dfe_retroativas | boolean | Download de documentos fiscais retroativos. |
dfe_retroativas_total | número | Quantidade de documentos fiscais retroativos encontrados. Observação: Este parâmetro é retornado apenas se a opção dfe_retroativas estiver desativada. Ative a opção para ter acesso aos documentos fiscais retroativos. |
{
"uuid": "00000000-0000-0000-0000-000000000000",
"cnpj": "00.000.000/0000-00",
"razao_social": "Nome da empresa LTDA",
"endereco": {
"cep": "00000-000",
"municipio": "São Paulo",
"codigo_municipio": 3550308,
"estado": "SP"
},
"certificado_vencimento": "2025-08-28 19:49:22",
"modelos_download": ["nfe", "nfse", "mdfe", "cte"]
}
Para listar as empresas cadastradas, envie a requisição no método GET para a URL /empresas incluindo na URL a query string page (número da página que deseja acessar) e per_page (quantidade de registros retornados por página). Segue exemplo:
curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/empresas?page=1&per_page=50A resposta da requisição será um objeto JSON contendo o parâmetro data, com a array das empresas localizadas no formato objeto, e meta com os metadados da paginação. Segue abaixo:
{
"data": [
{
"uuid": "00000000-0000-0000-0000-000000000000",
"cnpj": "00.000.000/0000-00",
"razao_social": "Nome da empresa LTDA",
"endereco": {
"cep": "00000-000",
"municipio": "São Paulo",
"codigo_municipio": 3550308,
"estado": "SP"
},
"certificado_vencimento": "2025-08-28 19:49:22",
"modelos_download": ["nfe", "nfse", "mdfe", "cte"]
},
{
"uuid": "00000000-0000-0000-0000-000000000000",
"cnpj": "00.000.000/0000-00",
"razao_social": "Nome da empresa LTDA",
"endereco": {
"cep": "00000-000",
"municipio": "São Paulo",
"codigo_municipio": 3550308,
"estado": "SP"
},
"certificado_vencimento": "2025-08-28 19:49:22",
"modelos_download": ["nfe", "nfse", "mdfe", "cte"]
}
],
"meta": {
"current_page": 1,
"last_page": 1,
"per_page": 50,
"total": 2
}
}
Após cadastrar uma empresa, é possível configurar o monitoramento de NFS-e para os municípios que exigem credenciais adicionais. Consulte todos os municípios disponíveis.
Por que essa configuração é necessária?
Monitoramento automático usando apenas o Certificado Digital A1 da empresa.
Exemplos: São Paulo, Fortaleza
Requerem login e senha do portal da prefeitura para download.
Exemplos: Osasco, Porto Alegre
Como funciona?
/municipios-nfseImportante: Consulte a lista de municípios disponíveis ou o código IBGE, antes de cadastrar as credenciais do município. Deseja visualizar em planilha? Clique aqui
Para listar os municípios disponíveis envie uma requisição no método GET para a URL /municipios-nfse. Segue abaixo exemplo:
curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/municipios-nfsePara pesquisar um único município, informe o parâmetro codigo_ibge na URL como parâmetro de consulta (query string). Segue abaixo exemplo com o Código IBGE:
curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/municipios-nfse?codigo_ibge=0000000A resposta da requisição será um objeto JSON contendo o parâmetro data, com a array dos municípios disponíveis no formato objeto. Segue abaixo:
| Parâmetro | Tipo | Descrição |
|---|---|---|
municipio | string | Nome do município |
uf | string | Sigla do estado |
codigo_ibge | string | Código IBGE do município |
nativo | boolean | Indica se o município é nativotrue = Nativo |
download_emitidas | boolean | Indica se o município permite o download de documentos emitidos |
download_recebidas | boolean | Indica se o município permite o download de documentos recebidos |
im | boolean | Indica a obrigatoriedade da Inscrição Municipal |
certificado | boolean | Indica se requer Certificado Digital A1 |
login_senha | boolean | Indica se requer login e senha para acessoObrigatório caso o parâmetro certificado seja true |
cadastro_prefeitura | boolean | Indica se requer cadastro na prefeitura |
guia_cadastro_prefeitura | string | Retorna a URL do guia na Central de Ajuda da Webmania |
domicilio_fiscal_municipio | boolean | Indica se requer domicílio fiscal no municípioÉ o endereço cadastrado junto ao Fisco, que obrigatoriamente precisa ser o mesmo do município. |
multiplos_servicos | boolean | Indica se suporta múltiplos serviços por notaÉ quando uma única nota fiscal de serviço (NFS-e) reúne dois ou mais serviços diferentes prestados ao mesmo cliente, detalhados separadamente, mas cobrados juntos em um único documento fiscal. |
{
"data": [
{
"municipio": "São Paulo",
"uf": "SP",
"codigo_ibge": "3550308",
"nativo": true,
"download_emitidas": true,
"download_recebidas": 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,
"download_emitidas": false,
"download_recebidas": true,
"certificado": false,
"login_senha": true,
"cadastro_prefeitura": false,
"domicilio_fiscal_municipio": false,
"multiplos_servicos": false
}
]
}Para listar os municípios monitorados, envie a requisição no método GET para a URL /empresas/{uuid}/municipios-nfse informando o UUID da empresa e, na URL, a query string page (número da página que deseja acessar) e per_page (quantidade de registros retornados por página). Segue exemplo:
curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/empresas/00000000-0000-0000-0000-000000000000/municipios-nfse?page=1&per_page=50A resposta da requisição será um objeto JSON contendo o parâmetro data, com a array dos municípios monitorados no formato objeto, e meta com os metadados da paginação. Segue abaixo:
| Parâmetro | Tipo | Descrição |
|---|---|---|
uuid | string | UUID do monitoramento |
municipio | string | Nome do município monitorado |
uf | string | Sigla da UF |
tipo_download | número | Tipo de download1 - Documentos recebidos |
codigo_ibge | string | Código IBGE do município monitorado |
login | string | Login de acesso ao portal da prefeitura |
im | string | Inscrição Municipal do município monitorado |
{
"data": [
{
"uuid": "00000000-0000-0000-0000-000000000000",
"municipio": "Osasco",
"uf": "SP",
"codigo_ibge": "0000000",
"login": "usuario123",
"im": "00000000"
},
{
"uuid": "00000000-0000-0000-0000-000000000000",
"municipio": "São Paulo",
"uf": "SP",
"codigo_ibge": "0000000",
"login": "usuario123",
"im": "00000000"
}
],
"meta": {
"current_page": 1,
"last_page": 1,
"per_page": 50,
"total": 2
}
}Para cadastrar um município, envie a requisição no método POST para a URL /empresas incluindo no corpo da requisição os seguintes parâmetros:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
codigo_ibge | string | Código IBGE do municípioEx: 3534401 | |
login | string | Login de acesso ao portal da prefeituraObrigatório se o município exige autenticação. | |
senha | string | Senha de acesso ao portal da prefeituraObrigatório caso informado o parâmetro login. | |
im | string | Inscrição Municipal do municípioObrigatório se o município exige inscrição municipal. | |
tipo_download | número | Tipo de download1 - Documentos recebidos |
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"codigo_ibge": "0000000",
"login": "usuario123",
"senha": "senha123"
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/empresas/00000000-0000-0000-0000-000000000000/municipios-nfsePara atualizar um município, envie a requisição no método PUT para a URL /empresas/{empresa_uuid}/municipios-nfse/{uuid}, incluindo no corpo da requisição (body) apenas os parâmetros que deseja atualizar.
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
login | string | Login de acesso ao portal da prefeitura | |
senha | string | Senha de acesso ao portal da prefeitura | |
im | string | Inscrição Municipal do município |
curl -X PUT \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"login": "login123",
"senha": "senha123"
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/empresas/00000000-0000-0000-0000-000000000000/municipios-nfse/00000000-0000-0000-0000-000000000000A resposta do corpo da mensagem será no formato objeto JSON, contendo as informações do município atualizado:
{
"uuid": "00000000-0000-0000-0000-000000000000",
"municipio": "Osasco",
"uf": "SP",
"codigo_ibge": "0000000",
"login": "usuario123",
"im": "00000000"
}Importante: Ao remover um município o monitoramento é paralisado, mas não é removido os documentos fiscais já localizados anteriormente.
Para excluir um município, envie a requisição no método DELETE para a URL /empresas/{empresa_uuid}/municipios-nfse/{uuid}.
curl -X DELETE \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/empresas/00000000-0000-0000-0000-000000000000/municipios-nfse/00000000-0000-0000-0000-000000000000A resposta do corpo da mensagem será no formato objeto JSON, contendo a mensagem de sucesso:
{
"msg": "O download de notas para o município Osasco - SP foi interrompido com sucesso."
}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.
Para listar os documentos fiscais, envie a requisição no método POST para a URL /documentos. No corpo da requisição, inclua o parâmetro modelo e, se desejar, os parâmetros filtros, filtros_modelo e pesquisa — esses parâmetros podem ser usados juntos ou separadamente para refinar a pesquisa.
Além disso, adicione à URL as query strings page (número da página que deseja acessar) e per_page (quantidade de registros que serão retornados por página). Segue abaixo exemplo:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
modelo | string | Modelo do Documento Fiscal nfe | |
novos_documentos | boolean | Retorna somente os novos documentos.Verificado se existem documentos novos desde a última consulta. | |
filtros | objeto | Filtros geraisVisualize todos os filtros - Saiba mais | |
filtros_modelo | objeto | Filtros por modelo de documento fiscalVisualize todos os filtros - Saiba mais | |
pesquisa | string | Pesquisa textual das informações.Pesquise informações do XML do documento fiscal. Saiba mais |
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"modelo" : "nfe"
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos?page=1&per_page=50A resposta da requisição será um objeto JSON contendo o parâmetro data, com a array dos documentos fiscais no formato objeto, e meta com os metadados da paginação. Cada modelo de documento fiscal possui um retorno diferente, verifique os detalhes específicos selecionando o modelo desejado abaixo:
💡 Dica interativa: Passe o mouse sobre os campos do JSON para ver a descrição detalhada de cada parâmetro, tipo de dado e valores possíveis.
{
"data": [
{
"uuid": "00000000-0000-0000-0000-000000000000",
"empresa_uuid": "00000000-0000-0000-0000-000000000000",
"modelo": "nfe",
"status": "aprovado",
"categoria": "recebidas",
"data_emissao": "2025-02-27 13:17:00",
"numero": 200,
"serie": 1,
"chave": "00000000000000000000000000000000000000000000",
"valor": 6200,
"operacao": 0,
"finalidade": 1,
"cfop": ["2909"],
"natureza_operacao": "Compra para industrialização",
"emitente": {
"cnpj": "00000000000000",
"razao_social": "EMPRESA FORNECEDORA LTDA",
"ie": "000000000000",
"uf": "SP",
"endereco": "Rua das Indústrias",
"numero": "1500",
"complemento": "Galpão 2",
"bairro": "Distrito Industrial",
"cep": "12345-678",
"cidade": "São Paulo",
"telefone": "11999999999",
"email": "fiscal@fornecedor.com"
},
"destinatario": {
"cnpj": "11111111000111",
"razao_social": "EMPRESA COMPRADORA S/A",
"ie": "111111111111",
"uf": "SP",
"endereco": "Av. Principal",
"numero": "1000",
"bairro": "Centro",
"cep": "98765-432",
"cidade": "São Paulo",
"telefone": "11888888888",
"email": "compras@empresa.com"
},
"pedido": {
"numero_pedido": "PED-2025-001234",
"numero_compra": "OC-2025-005678"
},
"produtos": [
{
"codigo": "MP001",
"descricao": "MATÉRIA PRIMA ESPECIAL TIPO A",
"ncm": "39269090",
"cfop": "2909",
"unidade": "KG",
"quantidade": 1000,
"valor_unitario": 6.2,
"valor_total": 6200,
"impostos": {
"icms": {
"situacao_tributaria": "00",
"origem": 0,
"base_calculo": 6200,
"aliquota": 18,
"valor": 1116
},
"ipi": {
"situacao_tributaria": "50",
"base_calculo": 6200,
"aliquota": 5,
"valor": 310
},
"pis": {
"situacao_tributaria": "01",
"base_calculo": 6200,
"aliquota": 1.65,
"valor": 102.3
},
"cofins": {
"situacao_tributaria": "01",
"base_calculo": 6200,
"aliquota": 7.6,
"valor": 471.2
}
}
}
],
"transporte": {
"modalidade_frete": 1,
"transportadora": {
"cnpj": "22222222000222",
"razao_social": "TRANSPORTADORA RÁPIDA LTDA",
"ie": "222222222222",
"endereco": "Rod. BR-101",
"numero": "KM 50",
"cidade": "São Paulo",
"uf": "SP"
},
"volumes": [
{
"quantidade": 10,
"especie": "CAIXA",
"marca": "FORNECEDOR",
"numeracao": "1-10",
"peso_liquido": 1000,
"peso_bruto": 1050
}
],
"veiculo": {
"placa": "ABC1234",
"uf": "SP"
}
},
"totais": {
"icms_bc": 6200,
"icms_valor": 1116,
"icms_valor_desonerado": 0,
"icms_st_bc": 0,
"icms_st_valor": 0,
"fcp_valor": 0,
"fcp_st_valor": 0,
"fcp_st_retido_valor": 0,
"ipi_valor": 310,
"ipi_devolvido_valor": 0,
"pis_valor": 102.3,
"cofins_valor": 471.2,
"ii_valor": 0,
"valor_produtos": 6200,
"valor_seguro": 0,
"valor_outras_despesas": 0,
"valor_desconto": 0,
"valor_frete": 0,
"valor_total_nfe": 7826
},
"totais_issqn": {
"valor_servicos": 0,
"iss_bc": 0,
"iss_valor": 0,
"pis_valor": 0,
"cofins_valor": 0,
"data_competencia": "2025-02-27",
"deducao": 0,
"outras_retencoes": 0,
"desconto_incondicionado": 0,
"desconto_condicionado": 0,
"iss_retido_valor": 0,
"regime_especial_tributacao": "1"
},
"fatura": {
"numero": "2025/0200",
"valor_original": 6200,
"valor_desconto": 0,
"valor_liquido": 6200
},
"parcelas": [
{
"numero": "001",
"vencimento": "2025-03-27",
"valor": 3100
},
{
"numero": "002",
"vencimento": "2025-04-27",
"valor": 3100
}
],
"responsavel_tecnico": {
"cnpj": "33333333000333",
"contato": "João Silva",
"email": "suporte@sistema.com",
"telefone": "11777777777"
},
"protocolo": "135250000123456"
}
],
"meta": {
"current_page": 1,
"last_page": 1,
"per_page": 50,
"total": 1
}
}Utilize os filtros para aprimorar a pesquisa dos documentos fiscais, os filtros devem ser montados no parâmetro filtros ao enviar a requisição no método POST para a URL /documentos — esses parâmetros podem ser usados juntos ou separadamente para refinar a pesquisa.
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
ambiente | string | Ambiente do documento fiscal 1 - Produção | |
empresa_uuid | string | UUID da empresa associada ao documento fiscal | |
categoria | string | Categoria do documento fiscal emitidas | |
data_inicial | string | Data inicial para filtragem dos documentos fiscais YYYY-MM-DD | |
data_final | string | Data final para filtragem dos documentos fiscais YYYY-MM-DD | |
serie | string | Série do documento fiscal ou série RPS | |
numero | string | Nº do documento fiscal ou nº RPS | |
valor | string | Valor do documento fiscal 0.00 |
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"modelo" : "nfe",
"filtros": {
"ambiente": 1,
"empresa_uuid": "00000000-0000-0000-0000-000000000000",
"categoria": "emitidas",
"data_inicial": "2025-08-28",
"data_final": "2025-08-28",
"serie": "1",
"numero": "12345",
"valor": "100.00"
}
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos?page=1&per_page=50Utilize os filtros para aprimorar a pesquisa dos documentos fiscais, os filtros devem ser montados no parâmetro filtros_modelo ao enviar a requisição no método POST para a URL /documentos — esses parâmetros podem ser usados juntos ou separadamente para refinar a pesquisa.
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
status | string | Status do documento fiscal aprovado | |
chave | string | Chave de acesso do documento fiscal | |
finalidade | string | Finalidade do documento fiscal 1 - Normal | |
operacao | string | Operação do documento fiscal 1 - Entrada | |
ncm | string | Código NCM do produto | |
cfop | string | Código CFOP do produto |
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"modelo" : "nfe",
"filtros": {
"categoria": "recebidas"
},
"filtros_modelo": {
"chave": "00000000000000000000000000000000000000000000"
}
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos?page=1&per_page=50| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
status | string | Status do documento fiscal aprovado | |
codigo_verificacao | string | Código de verificação do documento fiscal | |
codigo_cnae | string | Código CNAE do serviço prestado | |
codigo_servico | string | Código do serviço prestado |
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"modelo" : "nfse",
"filtros": {
"categoria": "recebidas"
},
"filtros_modelo": {
"codigo_cnae": "00000000"
}
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos?page=1&per_page=50| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
status | string | Status do documento fiscal aprovado | |
chave | string | Chave de acesso do documento fiscal | |
modalidade | string | Modalidade do documento fiscal1 - Rodoviário | |
uf_inicio_prestacao | string | Unidade Federativa de Início da PrestaçãoExemplo: SP | |
uf_termino_prestacao | string | Unidade Federativa de Término da PrestaçãoExemplo: SP |
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"modelo" : "cte",
"filtros": {
"categoria": "recebidas"
},
"filtros_modelo": {
"modalidade": 1
}
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos?page=1&per_page=50| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
status | string | Status do documento fiscal aprovado | |
chave | string | Chave de acesso do documento fiscal | |
modalidade | string | Modalidade do documento fiscal1 - Rodoviário | |
uf_carregamento | string | Unidade Federativa de CarregamentoExemplo: SP | |
uf_descarregamento | string | Unidade Federativa de DescarregamentoExemplo: SP | |
placa_veiculo | string | Placa do veículoExemplo: ABC1234 |
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"modelo" : "mdfe",
"filtros": {
"categoria": "recebidas"
},
"filtros_modelo": {
"uf_carregamento": "PR"
}
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos?page=1&per_page=50Utilize a pesquisa textual para aprimorar a pesquisa dos documentos fiscais, deve ser enviado o parâmetro pesquisa com a informação que deseja pesquisar ao enviar a requisição no método POST para a URL /documentos — outros parâmetros podem ser usados juntos ou separadamente para refinar a pesquisa.
Através da pesquisa textual, você pode buscar documentos fiscais utilizando os seguintes critérios:
Exemplo de requisição para buscar documentos através da pesquisa textual:
Limites: O parâmetro pesquisa possui um limite de 80 caracteres.
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"modelo" : "nfe",
"filtros": {
"categoria": "recebidas"
},
"pesquisa": "EMPRESA LTDA"
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos?page=1&per_page=50Para listar todos os eventos vinculados a um documento fiscal, envie uma requisição GET para o endpoint /documentos/{uuid}/eventos, contendo o UUID do respectivo documento fiscal. Segue abaixo exemplo:
curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/00000000-0000-0000-0000-000000000000/eventosA resposta da requisição será um objeto JSON contendo o parâmetro data, com a array dos eventos do documento fiscal no formato objeto.
📄 Exemplos JSON de Retorno: Cada evento retorna uma estrutura específica. Para visualizar cada variação, clique nos links Exemplo JSON nas tabelas abaixo.
| Evento | Tipo | Retorno | Objetivo |
|---|---|---|---|
| Carta de correção | 110110 | Exemplo JSON | Corrigir erros no documento fiscal sem a necessidade de cancelar e reemitir o documento |
| Cancelamento | 110111 | Exemplo JSON | Anular o documento fiscal autorizado quando a operação não se concretizar |
| Confirmação da operação | 210200 | Exemplo JSON | Destinatário do documento fiscal confirmar que a operação ocorreu conforme descrito no documento |
| Ciência da operação | 210210 | Exemplo JSON | Destinatário apenas declarar ter conhecimento da emissão do documento fiscal |
| Desconhecimento da operação | 210220 | Exemplo JSON | Destinatário informar que não reconhece a operação descrita no documento fiscal |
| Operação não realizada | 210240 | Exemplo JSON | Destinatário informar que a operação não foi realizada |
| Registro de autorização de CT-e | 610600 | Exemplo JSON | Indicar que houve aprovação de um CT-e em que a NF-e está referenciada |
| Registro de cancelamento de CT-e | 610601 | Exemplo JSON | Indicar que houve cancelamento de um CT-e em que a NF-e está referenciada |
| Comprovante de entrega de CT-e | 610130 | Exemplo JSON | Comprovar a entrega das mercadorias transportadas por um CT-e em que a NF-e está referenciada |
| Registro de autorização de MDF-e | 610614 | Exemplo JSON | Indicar que houve aprovação de um MDF-e em que a NF-e está referenciada |
| Registro de cancelamento de MDF-e | 610615 | Exemplo JSON | Indicar que houve cancelamento de um MDF-e em que a NF-e está referenciada |
| Registro de passagem automático | 510630 | Exemplo JSON | Registrar automaticamente a passagem de um veículo em pedágios transportando mercadorias documentadas em um MDF-e em que a NF-e está referenciada |
| Registro de passagem em posto fiscal | 610500 | Exemplo JSON | Registrar a passagem das mercadorias transportadas em um posto fiscal |
| Registro de passagem propagado | 610514 | Exemplo JSON | Registrar passagem em postos fiscais das mercadorias transportadas documentadas em um MDF-e, que possui um CT-e referenciando a NF-e |
| Evento | Tipo | Retorno | Objetivo |
|---|---|---|---|
| Cancelamento | 101101 | Exemplo JSON | Anular o documento fiscal autorizado quando a operação não se concretizar |
| Substituição | 105102 | Exemplo JSON | Substituir o documento fiscal por um novo, corrigindo informações incorretas ou incompletas do documento original |
| Evento | Tipo | Retorno | Objetivo |
|---|---|---|---|
| Carta de correção | 110110 | Exemplo JSON | Corrigir erros no documento fiscal sem a necessidade de cancelar e reemitir o documento |
| Cancelamento | 110111 | Exemplo JSON | Anular o documento fiscal autorizado quando a operação não se concretizar |
| Comprovante de entrega | 110180 | Exemplo JSON | Comprovar a entrega das mercadorias transportadas |
| Registro de autorização de MDF-e | 310610 | Exemplo JSON | Indicar que houve aprovação de um MDF-e em que o CT-e está referenciado |
| Registro de cancelamento de MDF-e | 310611 | Exemplo JSON | Indicar que houve cancelamento de um MDF-e em que o CT-e está referenciado |
| Prestação de serviço em desacordo | 610110 | Exemplo JSON | Tomador do serviço manifestar discordância em relação a um CT-e emitido, informando que existem erros ou divergências no documento |
| Evento | Tipo | Retorno | Objetivo |
|---|---|---|---|
| Cancelamento | 110111 | Exemplo JSON | Anular o documento fiscal autorizado quando a operação não se concretizar. |
| Encerramento | 110112 | Exemplo JSON | Indicar que o transporte foi concluído e que a mercadoria foi entregue no destino final. |
| Inclusão de condutor | 110114 | Exemplo JSON | Adicionar novos condutores ao longo da viagem, caso haja troca ou necessidade de registrar um novo condutor além dos que já foram informados. |
Para realizar a consulta de um documento fiscal, envie a requisição no método GET para a URL /documentos/{uuid}. Segue abaixo exemplo da consulta UUID:
curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/00000000-0000-0000-0000-000000000000A resposta retornará as informações completas do documento solicitado no parâmetro data. Cada modelo de documento fiscal possui um retorno diferente, selecione o modelo desejado abaixo para visualizar o exemplo de resposta:
💡 Dica interativa: Passe o mouse sobre os campos do JSON para ver a descrição detalhada de cada parâmetro, tipo de dado e valores possíveis.
{
"data": {
"uuid": "00000000-0000-0000-0000-000000000000",
"empresa_uuid": "00000000-0000-0000-0000-000000000000",
"modelo": "nfe",
"status": "aprovado",
"categoria": "recebidas",
"data_emissao": "2025-02-27 13:28:00",
"numero": 100,
"serie": 1,
"chave": "00000000000000000000000000000000000000000000",
"valor": 6700,
"operacao": 0,
"finalidade": 1,
"cfop": [
"2909"
],
"natureza_operacao": "Retorno de bem por conta de contrato de comodato ou locacao.",
"emitente": {
"cnpj": "00000000000000",
"cpf": "00000000000",
"razao_social": "XXXXXX XXXXXX XXX",
"nome_completo": "XXXXXX XXXXXX XXX",
"nome_fantasia": "XXXXXXX XXXXXXXXXX",
"ie": "00000000",
"endereco": "XXXX XXXX",
"numero": "XXX",
"complemento": "XXXX XXXXXX",
"bairro": "XXXXXXX XXXX",
"cep": "00000000",
"cidade": "Sao Paulo",
"uf": "SP",
"telefone": "00000000000",
"email": "abcd@efgh.com"
},
"pedido": {
"ID": "000000000",
"presenca": "0",
"modalidade_frete": "0",
"frete": 5,
"intermediador": "0",
"cnpj_intermediador": "00000000000000",
"id_intermediador": "XXXXXXXXX",
"pagamento": [
"0"
],
"forma_pagamento": [
"99"
],
"desc_pagamento": [
"Pagamento Digital"
],
"valor_pagamento": [
6700
],
"tipo_integracao": [
"1"
],
"cnpj_credenciadora": [
"00000000000000"
],
"bandeira": [
"01"
],
"autorizacao": [
"12345"
],
"desconto": 0,
"informacoes_fisco": "XXXXX XXXXXXXXXXX",
"informacoes_complementares": "XXXXXXX XXXXXXXX XXXXXXXXX XXXX"
},
"produtos": [
{
"nome": "HD SSD 512GB NVME",
"item": "1",
"codigo": ".560",
"ncm": "85219000",
"cest": "0000000",
"quantidade": 1,
"quantidade_tributavel": 1,
"unidade": "UN",
"unidade_tributavel": "UN",
"origem": "0",
"subtotal": 1000,
"subtotal_tributavel": 1000,
"total": 1000,
"desconto": 0,
"frete": 0,
"seguro": 0,
"outras_despesas": 0,
"gtin": "SEM GTIN",
"gtin_tributavel": "SEM GTIN",
"impostos": {
"icms": {
"codigo_cfop": "2909",
"situacao_tributaria": "41",
"icms_bc":0,
"icms_modalidade_bc":0,
"icms_aliquota":0,
"icms_valor":0,
"icms_aliquota_reducao":0,
"icms_valor_desonerado":0,
"icms_motivo_desoneracao":0,
"icms_valor_operacao":0,
"icms_aliquota_diferimento":0,
"icms_valor_diferimento":0,
"icms_aliquota_reducao_efetiva":0,
"icms_bc_efetiva":0,
"icms_aliquota_efetiva":0,
"icms_valor_efetivo":0,
"icms_bc_operacao_propria":0,
"icms_substituto_valor":0,
"icms_aliquota_credito":0,
"icms_valor_credito":0,
"icms_bc_uf_destino":0,
"icms_aliquota_uf_destino":0,
"icms_aliquota_interestadual":0,
"icms_aliquota_partilha_interestadual":0,
"icms_valor_uf_destino":0,
"icms_valor_uf_remetente":0,
"icms_st_bc":0,
"icms_st_modalidade_bc":0,
"icms_st_aliquota":0,
"icms_st_valor":0,
"icms_st_aliquota_mva":0,
"icms_st_aliquota_reducao":0,
"icms_st_uf":0,
"icms_st_bc_dest":0,
"icms_st_valor_dest":0,
"icms_st_retido_bc":0,
"icms_st_retido_valor":0,
"fcp_bc":0,
"fcp_aliquota":0,
"fcp_valor":0,
"fcp_bc_uf_destino":0,
"fcp_aliquota_uf_destino":0,
"fcp_valor_uf_destino":0,
"fcp_st_bc":0,
"fcp_st_aliquota":0,
"fcp_st_valor":0,
"fcp_st_retido_bc":0,
"fcp_st_retido_aliquota":0,
"fcp_st_retido_valor":0
},
"ipi": {
"situacao_tributaria": "99",
"codigo_enquadramento": "999",
"ipi_bc": 0,
"ipi_aliquota": 0,
"ipi_valor": 0,
"codigo_selo": "XXXX",
"qtd_selo": 1
},
"ipi_devolvido": {
"percentual_devolvido": 0,
"ipi_devolvido_valor": 0
},
"pis": {
"situacao_tributaria": "98",
"pis_bc": 0,
"pis_quantidade_bc": 0,
"pis_aliquota": 0,
"pis_aliquota_valor": 0,
"pis_valor": 0
},
"cofins": {
"situacao_tributaria": "98",
"cofins_bc": 0,
"cofins_quantidade_bc": 0,
"cofins_aliquota": 0,
"cofins_aliquota_valor": 0,
"cofins_valor": 0
},
"issqn": {
"iss_bc": 0,
"iss_aliquota": 0,
"iss_valor": 0,
"municipio_fato_gerador": "00000000",
"item_servico": "0000",
"deducao": 0,
"retencoes": 0,
"desconto_incondicionado": 0,
"desconto_condicionado": 0,
"iss_retido_valor": 0,
"exigibilidade": "1",
"codigo_servico": "0000",
"municipio_incidencia": "00000000",
"pais": "1058",
"processo": "12345",
"incentivo_fiscal": "2"
},
"imposto_importacao": {
"ii_bc": 0,
"despesas_aduaneiras": 0,
"ii_valor": 0,
"iof_valor": 0
}
}
}
],
"transporte": {
"volume": "0",
"especie": "PECAS",
"marca": "XXXX",
"numeracao": "0000",
"peso_liquido": 0,
"peso_bruto": 0,
"transportadora": {
"cnpj": "00000000000000",
"cpf": "00000000000",
"razao_social": "XXXXXX XXXXXX XXX",
"nome_completo": "XXXXXX XXXXXX XXX",
"nome_fantasia": "XXXXXXX XXXXXXXXXX",
"ie": "00000000",
"endereco": "XXXX XXXX",
"numero": "XXX",
"complemento": "XXXX XXXXXX",
"bairro": "XXXXXXX XXXX",
"cep": "00000000",
"cidade": "Sao Paulo",
"uf": "SP",
"telefone": "00000000000",
"email": "abcd@efgh.com"
},
"entrega": {
"cnpj": "00000000000000",
"cpf": "00000000000",
"razao_social": "XXXXXX XXXXXX XXX",
"nome_completo": "XXXXXX XXXXXX XXX",
"nome_fantasia": "XXXXXXX XXXXXXXXXX",
"ie": "00000000",
"endereco": "XXXX XXXX",
"numero": "XXX",
"complemento": "XXXX XXXXXX",
"bairro": "XXXXXXX XXXX",
"cep": "00000000",
"cidade": "Sao Paulo",
"uf": "SP",
"telefone": "00000000000",
"email": "abcd@efgh.com"
},
"retirada": {
"cnpj": "00000000000000",
"cpf": "00000000000",
"razao_social": "XXXXXX XXXXXX XXX",
"nome_completo": "XXXXXX XXXXXX XXX",
"nome_fantasia": "XXXXXXX XXXXXXXXXX",
"ie": "00000000",
"endereco": "XXXX XXXX",
"numero": "XXX",
"complemento": "XXXX XXXXXX",
"bairro": "XXXXXXX XXXX",
"cep": "00000000",
"cidade": "Sao Paulo",
"uf": "SP",
"telefone": "00000000000",
"email": "abcd@efgh.com"
}
},
"totais": {
"icms_bc": 0,
"icms_valor": 0,
"icms_valor_desonerado": 0,
"icms_st_bc": 0,
"icms_st_valor": 0,
"fcp_valor": 0,
"fcp_st_valor": 0,
"fcp_st_retido_valor": 0,
"ipi_valor": 0,
"ipi_devolvido_valor": 0,
"pis_valor": 0,
"cofins_valor": 0,
"ii_valor": 0,
"valor_produtos": 6700,
"valor_seguro": 0,
"valor_outras_despesas": 0,
"valor_desconto": 0,
"valor_frete": 0
},
"totais_issqn": {
"valor_servicos": 0,
"iss_bc": 0,
"iss_valor": 0,
"pis_valor": 0,
"cofins_valor": 0,
"data_competencia": "2025-02-27",
"deducao": 0,
"outras_retencoes": 0,
"desconto_incondicionado": 0,
"desconto_condicionado": 0,
"iss_retido_valor": 0,
"regime_especial_tributacao": "1"
},
"fatura": {
"numero": "000000000",
"valor": 6700,
"desconto": 0,
"valor_liquido": 6700
},
"parcelas": [
{
"numero": 1,
"valor": 6700,
"vencimento": "2025-03-27"
}
],
"responsavel_tecnico": {
"cnpj": "00000000000000",
"razao_social": "XXXXXX XXXXXX XXX",
"telefone": "00000000000",
"email": "abcd@efgh.com"
},
"protocolo": {
"motivo": "Autorizado o uso da NF-e",
"status": "100",
"data_recebimento": "2025-02-27T13:28:33-03:00",
"numero_protocolo": "000000000000000"
},
"docs": {
"xml": "<nfeProc versao=\"4.00\" xmlns=\"http://www.portalfiscal.inf.br/nfe\">...</nfeProc>",
"pdf": "H4sIAAAAAAAAA+3BMQEAAADCoPVEAAA..."
}
}
}Ao consultar um documento específico pelo UUID, a resposta incluirá o objeto docs contendo os arquivos XML e PDF do documento fiscal:
ℹ️ Importante: Os campos docs.xml e docs.pdf estão disponíveis em todas as respostas de consulta individual de documento, independentemente do modelo (NF-e, NFS-e, CT-e, MDF-e).
| Campo | Formato | Descrição |
|---|---|---|
docs.xml | String (texto puro) | Conteúdo completo do XML do documento fiscal, já com caracteres HTML escapados. Pronto para ser salvo diretamente em arquivo ou processado. |
docs.pdf | String (Base64 + Gzip) | PDF do documento fiscal comprimido em Gzip e depois codificado em Base64. Requer decodificação e descompactação. |
{
"docs": {
"xml": "<nfeProc versao=\"4.00\" xmlns=\"http://www.portalfiscal.inf.br/nfe\">...</nfeProc>",
"pdf": "H4sIAAAAAAAAA+3BMQEAAADCoPVEAAA..."
}
}O campo docs.pdf está comprimido e codificado para otimizar o tamanho da resposta. Para acessar o arquivo PDF original, siga estes passos:
<?php
// Supondo que $response contém a resposta da API
$pdfBase64 = $response['data']['docs']['pdf'];
$xmlContent = $response['data']['docs']['xml'];
// Processar XML (já está pronto para uso)
file_put_contents('documento.xml', html_entity_decode($xmlContent));
// Processar PDF
$pdfCompressed = base64_decode($pdfBase64);
$pdfContent = gzdecode($pdfCompressed);
file_put_contents('documento.pdf', $pdfContent);
echo "Arquivos salvos com sucesso!";
?>⚠️ Atenção: Certifique-se de tratar adequadamente os caracteres especiais no XML. O conteúdo vem com entidades HTML escapadas (ex: < ao invés de <) e precisa ser decodificado antes de ser salvo ou processado.
Para importar um documento fiscal usando sua chave de acesso, envie uma requisição POST para o endpoint /documentos/importacoes com os parâmetros necessários:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
empresa_uuid | string | UUID da empresa Observação: A empresa selecionada deve atender às condições de participação no documento fiscal. Saiba mais | |
chave | string | Chave de acesso do documento fiscal |
⚠️ Importante: A importação por chave de acesso está disponível apenas para o modelo NF-e.
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
"https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/importacoes" \
-d '{
"empresa_uuid": "00000000-0000-0000-0000-000000000000",
"chave": "00000000000000000000000000000000000000000000"
}'A resposta da requisição é um objeto JSON contendo as informações do documento fiscal importado. Para visualizar exemplos de resposta, consulte a seção Consultar Documento.
Além da importação por chave de acesso, você também pode importar documentos fiscais pelo XML. Isso pode ser feito de duas formas:
ℹ️ XML (base64): enviando o conteúdo do XML codificado em base64. A importação ocorre de forma síncrona, retornando o resultado imediatamente.
ℹ️ Arquivo ZIP: enviando a URL de um arquivo ZIP, com o tamanho máximo de 50MB e possuindo até 5000 arquivos XML. O processamento é realizado de forma assíncrona, e o resultado deve ser acompanhado através da URL de notificação configurada para a empresa.
Em ambos os casos, utilize o endpoint /2/gestao-documentos-fiscais/documentos/importacoes. A tabela abaixo descreve os parâmetros que devem ser enviados no corpo da requisição:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
empresa_uuid | string | UUID da empresa Observação: A empresa selecionada deve ter participação no documento fiscal como um dos atores, ou ter o CNPJ/CPF citado como autorizado a acessar o XML. | |
xml | string | Conteúdo do arquivo XML codificado em base64. | |
url_arquivo_zip | string | URL de um arquivo .zip contendo múltiplos XMLs. |
Importante: utilize apenas um dos campos xml ou url_arquivo_zip por requisição.
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
"https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/importacoes" \
-d '{
"empresa_uuid": "00000000-0000-0000-0000-000000000000",
"xml": "H4sIAAAAAAAAA+3BMQEAAADCoPVEAAA..."
}'A resposta da requisição é um objeto JSON contendo as informações do documento fiscal importado. Para visualizar exemplos de resposta, consulte a seção Consultar Documento.
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
"https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/importacoes" \
-d '{
"empresa_uuid": "00000000-0000-0000-0000-000000000000",
"url_arquivo_zip": "https://exemplo.com/arquivo.zip"
}'A resposta da requisição é um objeto JSON contendo as informações do progresso da importação e dos documentos fiscais que foram importados e descartados. A tabela abaixo descreve os campos retornados:
| Parâmetro | Tipo | Descrição |
|---|---|---|
uuid | string | UUID identificando individualmente o lote de importação./td> |
empresa_uuid | string | UUID da empresa. |
status | string | Status da importação.processando |
processado | número | Número de XMLs processados até o momento. |
total | número | Total de XMLs encontrados no arquivo ZIP. |
importados | array | Lista de documentos importados com sucesso, contendo o nome do arquivo XML no ZIP enviado e o UUID do documento fiscal. |
descartados | array | Lista de documentos descartados, contendo o nome do arquivo XML no ZIP enviado e o motivo do XML não ter sido aceito. |
Ao executar a mesma requisição na API o parâmetro processado é alterado para que seja acompanhado o progresso da importação, recomendamos que as requisições sejam realizadas em um intervalo de no mínimo 5 segundos. Caso tenha informado o parâmetro url_notificacao nas configurações da empresa, ao concluir a importação, será enviado o retorno no formato POST para a URL configurada.
Ao concluir a importação, o parâmetro status é alterado para concluido, e você pode verificar quais documentos foram importados com sucesso e quais foram descartados através dos parâmetros importados e descartados. Segue abaixo o exemplo de retorno no formato JSON:
{
"uuid": "00000000-0000-0000-0000-000000000000",
"status": "concluido",
"empresa_uuid": "00000000-0000-0000-0000-000000000000",
"importados": [
{
"nome": "arquivo1.xml",
"uuid": "00000000-0000-0000-0000-000000000000"
},
{
"nome": "arquivo2.xml",
"uuid": "00000000-0000-0000-0000-000000000000"
}
],
"descartados": [
{
"nome": "arquivo3.xml",
"motivo": "A chave do documento fiscal não possui protocolo de aprovação na SEFAZ."
}
],
"processado": 3,
"total": 3
}Para realizar a manifestação, envie a requisição no método POST para a URL /documentos/{uuid}/eventos, onde deve substituir pelo UUID (identificador único) do documento fiscal que será manifestado.
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
evento | número | Tipo de evento 1 - Manifestação do destinatário | |
manifestacao | número | Tipo de manifestação 1 - Confirmação da operação | |
justificativa | string | Justificativa do evento Obrigatório para o tipo de manifestação 3. Opcional para os demais tipos. |
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"evento": 1,
"manifestacao": 1
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/00000000-0000-0000-0000-000000000000/eventosA resposta do corpo da mensagem será no formato objeto JSON, contendo as seguintes informações do evento gerado:
{
"uuid": "00000000-0000-0000-0000-000000000000",
"documento_uuid": "00000000-0000-0000-0000-000000000000",
"registrado_em": "2024-12-15 12:56:40",
"tipo_evento": 210200,
"log": {}
}Os relatórios podem ser exportados nos formatos CSV, XML e Excel. Para exportar um relatório, envie a requisição no método POST para a URL /documentos, utilizando os filtros necessários e informando os parâmetros relatorio e url_notificacao.
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
relatorio | string | Relatório a ser exportado xml | |
url_notificacao | string | URL para envio da notificação após a exportação ser concluída |
curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"modelo" : "nfe",
"filtros": {
"ambiente": 1,
"empresa_uuid": "00000000-0000-0000-0000-000000000000",
"categoria": "emitidas",
"data_inicial": "2025-07-11",
"data_final": "2025-07-11",
"serie": "1",
"numero": "12345",
"valor": "100.00"
},
"relatorio": "xml",
"url_notificacao": "https://seusite.com.br/api/relatorio-concluido"
}' \
https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/00000000-0000-0000-0000-000000000000/eventosA resposta do corpo da mensagem será no formato objeto JSON, contendo as seguintes informações do relatório gerado:
{
"uuid": "00000000-0000-0000-0000-000000000000",
"relatorio": "xml",
"modelo": "nfe",
"status": "processando",
"processado": 0,
"total": 120
}
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. Caso tenha informado o parâmetro url_notificacao, ao concluir a exportação, será enviado o retorno no formato POST para a URL especificada.
Ao concluir a exportação, o parâmetro status é alterado para concluido junto com o parâmetro url para download do relatório. Segue abaixo o retorno no formato JSON:
{
"uuid": "00000000-0000-0000-0000-000000000000",
"relatorio": "xml",
"modelo": "nfe",
"status": "concluido",
"processado": 120,
"total": 120,
"url": "https://api.webmaniabr.com/2/gestao-documentos-fiscais/documentos/relatorios/00000000-0000-0000-0000-000000000000",
"expira_em": "2024-12-31 15:20:10",
}
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.
IPs estáticos de entrada: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.
https://webmaniabr.com/api/ retorne 403 Erro Forbidden entre em contato para liberarmos o IP do seu servidor.