Para integrações via API (servidor a servidor), o fluxo recomendado é:
POST /Usuario/Autenticar (login e senha).GET /Usuario/ApiKey para gerar uma chave de API não expirável.x-api-key em todas as chamadas seguintes aos demais endpoints — não é necessário reautenticar a cada requisição.POST /Usuario/Autenticar também define um cookie HttpOnly de sessão, mas esse mecanismo é voltado para uso do portal web (navegador) e não deve ser usado por integrações automatizadas.
Todos os endpoints são protegidos e exigem o header x-api-key, exceto POST /Usuario/Autenticar e GET /Usuario/ValidarToken (marcados como públicos/anônimos nesta documentação). Use o botão Authorize desta página para informar sua chave uma única vez e testar os demais endpoints diretamente por aqui.
Para emitir a primeira nota fiscal, siga esta ordem:
x-api-key (seção acima).POST /Emitente/Cadastrar.POST /Emitente/UploadCertificado, informando o CNPJ já cadastrado no passo anterior — é ele quem assina as notas junto à prefeitura.POST /Emitente/Webhook) para ser notificado automaticamente sobre o resultado do processamento, em vez de fazer polling do protocolo.POST /NFSe/Emitir e acompanhe o resultado por GET /NFSe/Consultar/Protocolo/{protocolo} ou pelo webhook configurado.Autenticação e geração da chave de API (x-api-key) usada nos demais endpoints. Veja a seção "Autenticação" acima para o fluxo recomendado em integrações servidor-a-servidor.
Realiza a autenticação do usuário com login e senha.
Em caso de sucesso, um cookie HttpOnly de sessão é definido e os dados do usuário são retornados.
Para integrações automatizadas, prefira gerar uma chave de API não expirável em GET /Usuario/ApiKey logo após este login e utilizá-la via header x-api-key — veja a seção "Autenticação" na introdução desta documentação.
| login required | string E-mail ou login do usuário |
| senha required | string Senha do usuário |
| codigo | integer or null Identificador interno do usuário, gerado automaticamente pela plataforma |
| nome required | string Nome do usuário/empresa cadastrado na conta |
| login required | string E-mail usado para autenticação (login) |
| ativo required | boolean Indica se a conta está ativa. Contas inativas não conseguem se autenticar |
{- "login": "string",
- "senha": "string"
}{- "codigo": 0,
- "nome": "string",
- "login": "string",
- "ativo": true
}Verifica se um token JWT informado como parâmetro de consulta é válido. Útil para validação externa de tokens sem necessidade de cookie.
| token required | string Token JWT a ser validado (pode vir URL-encoded) |
| mensagem | string |
{- "mensagem": "Token válido"
}Renova o token do usuário atualmente autenticado na sessão (identificado pelo cookie de sessão ou pelo header enviado na própria requisição). Um novo cookie HttpOnly de sessão é emitido e os dados do usuário são retornados.
| codigo | integer or null Identificador interno do usuário, gerado automaticamente pela plataforma |
| nome required | string Nome do usuário/empresa cadastrado na conta |
| login required | string E-mail usado para autenticação (login) |
| ativo required | boolean Indica se a conta está ativa. Contas inativas não conseguem se autenticar |
{- "codigo": 0,
- "nome": "string",
- "login": "string",
- "ativo": true
}Gera um token não expirável para ser utilizado como chave de API em integrações automatizadas.
Requer autenticação prévia (via POST /Usuario/Autenticar). Após obter a chave, envie-a no header x-api-key nas demais chamadas — não é necessário reautenticar ou renovar esta chave periodicamente.
| apiKey | string Chave de API não expirável. Envie este valor no header 'x-api-key' em todas as chamadas subsequentes aos demais endpoints |
{- "apiKey": "string"
}Cadastro dos emitentes (prestadores de serviço) vinculados à sua conta. Um emitente precisa estar cadastrado aqui antes de vincular um certificado digital (grupo Certificado), configurar webhooks (grupo Webhook) ou emitir notas em seu nome (grupo NFSe).
Retorna todos os emitentes cadastrados na plataforma associados ao usuário autenticado. Cada emitente inclui dados cadastrais básicos e seu respectivo endereço.
| codigo | integer or null Código interno do emitente, gerado pela plataforma no cadastro. Não deve ser informado ao cadastrar; é obrigatório ao atualizar |
| razaoSocial required | string Razão social da empresa emitente (ou nome completo, se pessoa física) |
| nomeFantasia | string Nome fantasia da empresa emitente |
| cpfCnpj required | string CNPJ (14 dígitos) ou CPF (11 dígitos) do emitente, apenas números. É o identificador único do emitente na plataforma |
| inscricaoEstadual | string or null Inscrição estadual do emitente, quando aplicável |
| inscricaoMunicipal | string or null Inscrição municipal do emitente. Costuma ser exigida pela maioria das prefeituras para emissão de NFSe |
| telefone | string Telefone de contato do emitente, apenas números, com DDD |
string or null E-mail de contato do emitente | |
| usuarioPrefeitura | string or null Usuário de acesso ao portal da prefeitura, exigido apenas por municípios cuja integração depende de login/senha (além do certificado digital) |
| senhaPrefeitura | string or null Senha de acesso ao portal da prefeitura, correspondente a usuarioPrefeitura, quando exigida pelo município |
| codigoCnae | string Código CNAE principal da atividade do emitente, sem pontuação (ex.: '6201501') |
| incentivadorCultural | boolean Indica se o emitente é incentivador cultural (isenção/benefício previsto em lei municipal de incentivo à cultura), refletido nas notas emitidas |
| incentivoFiscal | string Descrição do incentivo fiscal aplicável ao emitente, quando houver. Pode ser deixado em branco |
| optanteSimples | boolean Indica se o emitente é optante pelo Simples Nacional, o que afeta o cálculo de alguns tributos na nota |
| regimeTributacao | integer Regime de tributação do emitente: 0 = MEI, 1 = Simples Nacional, 2 = Lucro Real, 3 = Lucro Presumido |
| chaveCertificado | string or null Chave interna que identifica o certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| senhaCertificado | string or null Senha do certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| vencimentoCertificado | string or null <date-time> Data de validade do certificado digital vinculado ao emitente. Recomenda-se monitorar este campo para renovar o certificado antes do vencimento |
| controleAutomaticoRPS | boolean Quando true, a IntegroBR controla automaticamente a numeração do RPS a partir de sequenciaRPS, dispensando o preenchimento de rps.numeroRPS pelo integrador no envio da nota |
| sequenciaRPS | integer or null Próximo número de RPS a ser utilizado, quando controleAutomaticoRPS estiver ativo |
| ativo | boolean Indica se o emitente está ativo. Emitentes inativos não conseguem emitir novas notas |
object (EnderecoEmitente) Endereço cadastrado do emitente |
[- {
- "codigo": 0,
- "razaoSocial": "string",
- "nomeFantasia": "string",
- "cpfCnpj": "12345678000199",
- "inscricaoEstadual": "string",
- "inscricaoMunicipal": "string",
- "telefone": "string",
- "email": "string",
- "usuarioPrefeitura": "string",
- "senhaPrefeitura": "string",
- "codigoCnae": "string",
- "incentivadorCultural": true,
- "incentivoFiscal": "string",
- "optanteSimples": true,
- "regimeTributacao": 0,
- "chaveCertificado": "string",
- "senhaCertificado": "string",
- "vencimentoCertificado": "2019-08-24T14:15:22Z",
- "controleAutomaticoRPS": true,
- "sequenciaRPS": 0,
- "ativo": true,
- "endereco": {
- "codigo": 0,
- "codigoEmitente": 0,
- "logradouro": "string",
- "bairro": "string",
- "numero": "string",
- "cep": "string",
- "complemento": "string",
- "codigoIBGEMunicipio": 0,
- "codigoIBGEUF": 0
}
}
]Retorna os dados do emitente com o código informado, caso esteja cadastrado na base de dados do usuário autenticado.
| codigo required | integer Código interno do emitente |
| codigo | integer or null Código interno do emitente, gerado pela plataforma no cadastro. Não deve ser informado ao cadastrar; é obrigatório ao atualizar |
| razaoSocial required | string Razão social da empresa emitente (ou nome completo, se pessoa física) |
| nomeFantasia | string Nome fantasia da empresa emitente |
| cpfCnpj required | string CNPJ (14 dígitos) ou CPF (11 dígitos) do emitente, apenas números. É o identificador único do emitente na plataforma |
| inscricaoEstadual | string or null Inscrição estadual do emitente, quando aplicável |
| inscricaoMunicipal | string or null Inscrição municipal do emitente. Costuma ser exigida pela maioria das prefeituras para emissão de NFSe |
| telefone | string Telefone de contato do emitente, apenas números, com DDD |
string or null E-mail de contato do emitente | |
| usuarioPrefeitura | string or null Usuário de acesso ao portal da prefeitura, exigido apenas por municípios cuja integração depende de login/senha (além do certificado digital) |
| senhaPrefeitura | string or null Senha de acesso ao portal da prefeitura, correspondente a usuarioPrefeitura, quando exigida pelo município |
| codigoCnae | string Código CNAE principal da atividade do emitente, sem pontuação (ex.: '6201501') |
| incentivadorCultural | boolean Indica se o emitente é incentivador cultural (isenção/benefício previsto em lei municipal de incentivo à cultura), refletido nas notas emitidas |
| incentivoFiscal | string Descrição do incentivo fiscal aplicável ao emitente, quando houver. Pode ser deixado em branco |
| optanteSimples | boolean Indica se o emitente é optante pelo Simples Nacional, o que afeta o cálculo de alguns tributos na nota |
| regimeTributacao | integer Regime de tributação do emitente: 0 = MEI, 1 = Simples Nacional, 2 = Lucro Real, 3 = Lucro Presumido |
| chaveCertificado | string or null Chave interna que identifica o certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| senhaCertificado | string or null Senha do certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| vencimentoCertificado | string or null <date-time> Data de validade do certificado digital vinculado ao emitente. Recomenda-se monitorar este campo para renovar o certificado antes do vencimento |
| controleAutomaticoRPS | boolean Quando true, a IntegroBR controla automaticamente a numeração do RPS a partir de sequenciaRPS, dispensando o preenchimento de rps.numeroRPS pelo integrador no envio da nota |
| sequenciaRPS | integer or null Próximo número de RPS a ser utilizado, quando controleAutomaticoRPS estiver ativo |
| ativo | boolean Indica se o emitente está ativo. Emitentes inativos não conseguem emitir novas notas |
object (EnderecoEmitente) Endereço cadastrado do emitente |
{- "codigo": 0,
- "razaoSocial": "string",
- "nomeFantasia": "string",
- "cpfCnpj": "12345678000199",
- "inscricaoEstadual": "string",
- "inscricaoMunicipal": "string",
- "telefone": "string",
- "email": "string",
- "usuarioPrefeitura": "string",
- "senhaPrefeitura": "string",
- "codigoCnae": "string",
- "incentivadorCultural": true,
- "incentivoFiscal": "string",
- "optanteSimples": true,
- "regimeTributacao": 0,
- "chaveCertificado": "string",
- "senhaCertificado": "string",
- "vencimentoCertificado": "2019-08-24T14:15:22Z",
- "controleAutomaticoRPS": true,
- "sequenciaRPS": 0,
- "ativo": true,
- "endereco": {
- "codigo": 0,
- "codigoEmitente": 0,
- "logradouro": "string",
- "bairro": "string",
- "numero": "string",
- "cep": "string",
- "complemento": "string",
- "codigoIBGEMunicipio": 0,
- "codigoIBGEUF": 0
}
}Retorna os dados do emitente associado ao CPF ou CNPJ informado, se houver.
| cpfCnpj required | string^[0-9]{11}|[0-9]{14}$ Example: 12345678000199 CPF ou CNPJ do emitente (somente números) |
| codigo | integer or null Código interno do emitente, gerado pela plataforma no cadastro. Não deve ser informado ao cadastrar; é obrigatório ao atualizar |
| razaoSocial required | string Razão social da empresa emitente (ou nome completo, se pessoa física) |
| nomeFantasia | string Nome fantasia da empresa emitente |
| cpfCnpj required | string CNPJ (14 dígitos) ou CPF (11 dígitos) do emitente, apenas números. É o identificador único do emitente na plataforma |
| inscricaoEstadual | string or null Inscrição estadual do emitente, quando aplicável |
| inscricaoMunicipal | string or null Inscrição municipal do emitente. Costuma ser exigida pela maioria das prefeituras para emissão de NFSe |
| telefone | string Telefone de contato do emitente, apenas números, com DDD |
string or null E-mail de contato do emitente | |
| usuarioPrefeitura | string or null Usuário de acesso ao portal da prefeitura, exigido apenas por municípios cuja integração depende de login/senha (além do certificado digital) |
| senhaPrefeitura | string or null Senha de acesso ao portal da prefeitura, correspondente a usuarioPrefeitura, quando exigida pelo município |
| codigoCnae | string Código CNAE principal da atividade do emitente, sem pontuação (ex.: '6201501') |
| incentivadorCultural | boolean Indica se o emitente é incentivador cultural (isenção/benefício previsto em lei municipal de incentivo à cultura), refletido nas notas emitidas |
| incentivoFiscal | string Descrição do incentivo fiscal aplicável ao emitente, quando houver. Pode ser deixado em branco |
| optanteSimples | boolean Indica se o emitente é optante pelo Simples Nacional, o que afeta o cálculo de alguns tributos na nota |
| regimeTributacao | integer Regime de tributação do emitente: 0 = MEI, 1 = Simples Nacional, 2 = Lucro Real, 3 = Lucro Presumido |
| chaveCertificado | string or null Chave interna que identifica o certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| senhaCertificado | string or null Senha do certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| vencimentoCertificado | string or null <date-time> Data de validade do certificado digital vinculado ao emitente. Recomenda-se monitorar este campo para renovar o certificado antes do vencimento |
| controleAutomaticoRPS | boolean Quando true, a IntegroBR controla automaticamente a numeração do RPS a partir de sequenciaRPS, dispensando o preenchimento de rps.numeroRPS pelo integrador no envio da nota |
| sequenciaRPS | integer or null Próximo número de RPS a ser utilizado, quando controleAutomaticoRPS estiver ativo |
| ativo | boolean Indica se o emitente está ativo. Emitentes inativos não conseguem emitir novas notas |
object (EnderecoEmitente) Endereço cadastrado do emitente |
{- "codigo": 0,
- "razaoSocial": "string",
- "nomeFantasia": "string",
- "cpfCnpj": "12345678000199",
- "inscricaoEstadual": "string",
- "inscricaoMunicipal": "string",
- "telefone": "string",
- "email": "string",
- "usuarioPrefeitura": "string",
- "senhaPrefeitura": "string",
- "codigoCnae": "string",
- "incentivadorCultural": true,
- "incentivoFiscal": "string",
- "optanteSimples": true,
- "regimeTributacao": 0,
- "chaveCertificado": "string",
- "senhaCertificado": "string",
- "vencimentoCertificado": "2019-08-24T14:15:22Z",
- "controleAutomaticoRPS": true,
- "sequenciaRPS": 0,
- "ativo": true,
- "endereco": {
- "codigo": 0,
- "codigoEmitente": 0,
- "logradouro": "string",
- "bairro": "string",
- "numero": "string",
- "cep": "string",
- "complemento": "string",
- "codigoIBGEMunicipio": 0,
- "codigoIBGEUF": 0
}
}Lista até 50 emitentes do usuário filtrados por CNPJ/CPF, razão social ou nome fantasia.
| termo required | string Termo de busca (não vazio) |
| codigo | integer or null Código interno do emitente, gerado pela plataforma no cadastro. Não deve ser informado ao cadastrar; é obrigatório ao atualizar |
| razaoSocial required | string Razão social da empresa emitente (ou nome completo, se pessoa física) |
| nomeFantasia | string Nome fantasia da empresa emitente |
| cpfCnpj required | string CNPJ (14 dígitos) ou CPF (11 dígitos) do emitente, apenas números. É o identificador único do emitente na plataforma |
| inscricaoEstadual | string or null Inscrição estadual do emitente, quando aplicável |
| inscricaoMunicipal | string or null Inscrição municipal do emitente. Costuma ser exigida pela maioria das prefeituras para emissão de NFSe |
| telefone | string Telefone de contato do emitente, apenas números, com DDD |
string or null E-mail de contato do emitente | |
| usuarioPrefeitura | string or null Usuário de acesso ao portal da prefeitura, exigido apenas por municípios cuja integração depende de login/senha (além do certificado digital) |
| senhaPrefeitura | string or null Senha de acesso ao portal da prefeitura, correspondente a usuarioPrefeitura, quando exigida pelo município |
| codigoCnae | string Código CNAE principal da atividade do emitente, sem pontuação (ex.: '6201501') |
| incentivadorCultural | boolean Indica se o emitente é incentivador cultural (isenção/benefício previsto em lei municipal de incentivo à cultura), refletido nas notas emitidas |
| incentivoFiscal | string Descrição do incentivo fiscal aplicável ao emitente, quando houver. Pode ser deixado em branco |
| optanteSimples | boolean Indica se o emitente é optante pelo Simples Nacional, o que afeta o cálculo de alguns tributos na nota |
| regimeTributacao | integer Regime de tributação do emitente: 0 = MEI, 1 = Simples Nacional, 2 = Lucro Real, 3 = Lucro Presumido |
| chaveCertificado | string or null Chave interna que identifica o certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| senhaCertificado | string or null Senha do certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| vencimentoCertificado | string or null <date-time> Data de validade do certificado digital vinculado ao emitente. Recomenda-se monitorar este campo para renovar o certificado antes do vencimento |
| controleAutomaticoRPS | boolean Quando true, a IntegroBR controla automaticamente a numeração do RPS a partir de sequenciaRPS, dispensando o preenchimento de rps.numeroRPS pelo integrador no envio da nota |
| sequenciaRPS | integer or null Próximo número de RPS a ser utilizado, quando controleAutomaticoRPS estiver ativo |
| ativo | boolean Indica se o emitente está ativo. Emitentes inativos não conseguem emitir novas notas |
object (EnderecoEmitente) Endereço cadastrado do emitente |
[- {
- "codigo": 0,
- "razaoSocial": "string",
- "nomeFantasia": "string",
- "cpfCnpj": "12345678000199",
- "inscricaoEstadual": "string",
- "inscricaoMunicipal": "string",
- "telefone": "string",
- "email": "string",
- "usuarioPrefeitura": "string",
- "senhaPrefeitura": "string",
- "codigoCnae": "string",
- "incentivadorCultural": true,
- "incentivoFiscal": "string",
- "optanteSimples": true,
- "regimeTributacao": 0,
- "chaveCertificado": "string",
- "senhaCertificado": "string",
- "vencimentoCertificado": "2019-08-24T14:15:22Z",
- "controleAutomaticoRPS": true,
- "sequenciaRPS": 0,
- "ativo": true,
- "endereco": {
- "codigo": 0,
- "codigoEmitente": 0,
- "logradouro": "string",
- "bairro": "string",
- "numero": "string",
- "cep": "string",
- "complemento": "string",
- "codigoIBGEMunicipio": 0,
- "codigoIBGEUF": 0
}
}
]Registra um novo emitente no sistema, vinculando-o ao usuário da sessão.
Próximos passos após o cadastro: envie o certificado digital do emitente em POST /Emitente/UploadCertificado e, opcionalmente, configure notificações em POST /Emitente/Webhook — ambos exigem que o emitente já esteja cadastrado.
| codigo | integer or null Código interno do emitente, gerado pela plataforma no cadastro. Não deve ser informado ao cadastrar; é obrigatório ao atualizar |
| razaoSocial required | string Razão social da empresa emitente (ou nome completo, se pessoa física) |
| nomeFantasia | string Nome fantasia da empresa emitente |
| cpfCnpj required | string CNPJ (14 dígitos) ou CPF (11 dígitos) do emitente, apenas números. É o identificador único do emitente na plataforma |
| inscricaoEstadual | string or null Inscrição estadual do emitente, quando aplicável |
| inscricaoMunicipal | string or null Inscrição municipal do emitente. Costuma ser exigida pela maioria das prefeituras para emissão de NFSe |
| telefone | string Telefone de contato do emitente, apenas números, com DDD |
string or null E-mail de contato do emitente | |
| usuarioPrefeitura | string or null Usuário de acesso ao portal da prefeitura, exigido apenas por municípios cuja integração depende de login/senha (além do certificado digital) |
| senhaPrefeitura | string or null Senha de acesso ao portal da prefeitura, correspondente a usuarioPrefeitura, quando exigida pelo município |
| codigoCnae | string Código CNAE principal da atividade do emitente, sem pontuação (ex.: '6201501') |
| incentivadorCultural | boolean Indica se o emitente é incentivador cultural (isenção/benefício previsto em lei municipal de incentivo à cultura), refletido nas notas emitidas |
| incentivoFiscal | string Descrição do incentivo fiscal aplicável ao emitente, quando houver. Pode ser deixado em branco |
| optanteSimples | boolean Indica se o emitente é optante pelo Simples Nacional, o que afeta o cálculo de alguns tributos na nota |
| regimeTributacao | integer Regime de tributação do emitente: 0 = MEI, 1 = Simples Nacional, 2 = Lucro Real, 3 = Lucro Presumido |
| chaveCertificado | string or null Chave interna que identifica o certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| senhaCertificado | string or null Senha do certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| vencimentoCertificado | string or null <date-time> Data de validade do certificado digital vinculado ao emitente. Recomenda-se monitorar este campo para renovar o certificado antes do vencimento |
| controleAutomaticoRPS | boolean Quando true, a IntegroBR controla automaticamente a numeração do RPS a partir de sequenciaRPS, dispensando o preenchimento de rps.numeroRPS pelo integrador no envio da nota |
| sequenciaRPS | integer or null Próximo número de RPS a ser utilizado, quando controleAutomaticoRPS estiver ativo |
| ativo | boolean Indica se o emitente está ativo. Emitentes inativos não conseguem emitir novas notas |
object (EnderecoEmitente) Endereço cadastrado do emitente |
| mensagem | string |
| cpfCnpj | string |
| codigo | integer |
{- "codigo": 0,
- "razaoSocial": "string",
- "nomeFantasia": "string",
- "cpfCnpj": "12345678000199",
- "inscricaoEstadual": "string",
- "inscricaoMunicipal": "string",
- "telefone": "string",
- "email": "string",
- "usuarioPrefeitura": "string",
- "senhaPrefeitura": "string",
- "codigoCnae": "string",
- "incentivadorCultural": true,
- "incentivoFiscal": "string",
- "optanteSimples": true,
- "regimeTributacao": 0,
- "chaveCertificado": "string",
- "senhaCertificado": "string",
- "vencimentoCertificado": "2019-08-24T14:15:22Z",
- "controleAutomaticoRPS": true,
- "sequenciaRPS": 0,
- "ativo": true,
- "endereco": {
- "codigo": 0,
- "codigoEmitente": 0,
- "logradouro": "string",
- "bairro": "string",
- "numero": "string",
- "cep": "string",
- "complemento": "string",
- "codigoIBGEMunicipio": 0,
- "codigoIBGEUF": 0
}
}{- "mensagem": "Emitente cadastrado com sucesso.",
- "cpfCnpj": "12345678000199",
- "codigo": 101
}Atualiza as informações de um emitente já existente com base no seu código.
| codigo | integer or null Código interno do emitente, gerado pela plataforma no cadastro. Não deve ser informado ao cadastrar; é obrigatório ao atualizar |
| razaoSocial required | string Razão social da empresa emitente (ou nome completo, se pessoa física) |
| nomeFantasia | string Nome fantasia da empresa emitente |
| cpfCnpj required | string CNPJ (14 dígitos) ou CPF (11 dígitos) do emitente, apenas números. É o identificador único do emitente na plataforma |
| inscricaoEstadual | string or null Inscrição estadual do emitente, quando aplicável |
| inscricaoMunicipal | string or null Inscrição municipal do emitente. Costuma ser exigida pela maioria das prefeituras para emissão de NFSe |
| telefone | string Telefone de contato do emitente, apenas números, com DDD |
string or null E-mail de contato do emitente | |
| usuarioPrefeitura | string or null Usuário de acesso ao portal da prefeitura, exigido apenas por municípios cuja integração depende de login/senha (além do certificado digital) |
| senhaPrefeitura | string or null Senha de acesso ao portal da prefeitura, correspondente a usuarioPrefeitura, quando exigida pelo município |
| codigoCnae | string Código CNAE principal da atividade do emitente, sem pontuação (ex.: '6201501') |
| incentivadorCultural | boolean Indica se o emitente é incentivador cultural (isenção/benefício previsto em lei municipal de incentivo à cultura), refletido nas notas emitidas |
| incentivoFiscal | string Descrição do incentivo fiscal aplicável ao emitente, quando houver. Pode ser deixado em branco |
| optanteSimples | boolean Indica se o emitente é optante pelo Simples Nacional, o que afeta o cálculo de alguns tributos na nota |
| regimeTributacao | integer Regime de tributação do emitente: 0 = MEI, 1 = Simples Nacional, 2 = Lucro Real, 3 = Lucro Presumido |
| chaveCertificado | string or null Chave interna que identifica o certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| senhaCertificado | string or null Senha do certificado digital vinculado ao emitente. É preenchida automaticamente por POST /Emitente/uploadCertificado; é ignorada no cadastro (POST /Emitente/Cadastrar) e normalmente não deve ser enviada manualmente |
| vencimentoCertificado | string or null <date-time> Data de validade do certificado digital vinculado ao emitente. Recomenda-se monitorar este campo para renovar o certificado antes do vencimento |
| controleAutomaticoRPS | boolean Quando true, a IntegroBR controla automaticamente a numeração do RPS a partir de sequenciaRPS, dispensando o preenchimento de rps.numeroRPS pelo integrador no envio da nota |
| sequenciaRPS | integer or null Próximo número de RPS a ser utilizado, quando controleAutomaticoRPS estiver ativo |
| ativo | boolean Indica se o emitente está ativo. Emitentes inativos não conseguem emitir novas notas |
object (EnderecoEmitente) Endereço cadastrado do emitente |
| mensagem | string |
| cpfCnpj | string |
| codigo | integer |
{- "codigo": 0,
- "razaoSocial": "string",
- "nomeFantasia": "string",
- "cpfCnpj": "12345678000199",
- "inscricaoEstadual": "string",
- "inscricaoMunicipal": "string",
- "telefone": "string",
- "email": "string",
- "usuarioPrefeitura": "string",
- "senhaPrefeitura": "string",
- "codigoCnae": "string",
- "incentivadorCultural": true,
- "incentivoFiscal": "string",
- "optanteSimples": true,
- "regimeTributacao": 0,
- "chaveCertificado": "string",
- "senhaCertificado": "string",
- "vencimentoCertificado": "2019-08-24T14:15:22Z",
- "controleAutomaticoRPS": true,
- "sequenciaRPS": 0,
- "ativo": true,
- "endereco": {
- "codigo": 0,
- "codigoEmitente": 0,
- "logradouro": "string",
- "bairro": "string",
- "numero": "string",
- "cep": "string",
- "complemento": "string",
- "codigoIBGEMunicipio": 0,
- "codigoIBGEUF": 0
}
}{- "mensagem": "Emitente atualizado com sucesso.",
- "cpfCnpj": "12345678000199",
- "codigo": 101
}Remove logicamente (ou fisicamente, dependendo da implementação) um emitente a partir do seu código.
| codigo required | integer Example: 101 Código do emitente a ser excluído |
| mensagem | string |
{- "mensagem": "Emitente excluido com sucesso."
}Upload do certificado digital A1 (arquivo .pfx em Base64) usado para assinar as notas fiscais de um emitente já cadastrado. Cada emitente possui no máximo um certificado ativo por vez — um novo upload substitui o certificado (e o arquivo) anterior.
Realiza o upload de um certificado digital no formato Base64, valida a senha e armazena o certificado com uma chave única gerada pelo sistema.
O emitente informado em cnpjEmissor já deve estar cadastrado (POST /Emitente/Cadastrar). Um novo upload para o mesmo emitente substitui o certificado anterior (o arquivo antigo é descartado) — não é necessário excluir antes de trocar um certificado vencido ou renovado.
| cnpjEmissor required | string CNPJ do emitente já cadastrado na plataforma (somente números) ao qual o certificado será vinculado |
| base64 required | string Conteúdo binário do arquivo do certificado A1 (.pfx) codificado em Base64 |
| senha required | string Senha de exportação do certificado (a mesma usada para abrir o arquivo .pfx). É armazenada de forma segura e usada apenas para assinar as notas deste emitente |
| chaveCertificado | string Identificador único gerado para o certificado armazenado |
| vencimento | string <date-time> Data de validade do certificado (NotAfter) |
{- "cnpjEmissor": "12345678000199",
- "base64": "string",
- "senha": "string"
}{- "chaveCertificado": "string",
- "vencimento": "2019-08-24T14:15:22Z"
}Cadastro de URLs, por emitente, que a IntegroBR chamará via HTTP POST quando o evento configurado ocorrer (ex.: conclusão da emissão ou do cancelamento de uma nota). Alternativa ao polling manual de GET /NFSe/Consultar/Protocolo/{protocolo} — um emitente pode ter múltiplos webhooks, um para cada evento de interesse.
codigoEmitente do emitente (retornado no cadastro POST /Emitente/Cadastrar ou em GET /Emitente/Consultar).POST /Emitente/Webhook informando codigoEmitente, a url HTTPS que deve receber as notificações, o evento desejado (enum WebhookEvento: 0 = Emissão, 1 = Cancelamento, 2 = Rejeição) e ativo: true.evento que quiser acompanhar (Emissão, Cancelamento e/ou Rejeição).PUT /Emitente/Webhook com ativo: false. Para remover definitivamente, use DELETE /Emitente/Webhook/{codigo}.POST /Emitente/Webhook/Teste para confirmar que sua URL está acessível e responde corretamente, sem precisar emitir ou cancelar uma nota de verdade.Exemplo de corpo de POST /Emitente/Webhook:
{
"codigoEmitente": 101,
"evento": 0,
"ativo": true,
"url": "https://www.suaempresa.com.br/webhook/nfse"
}
Se, além do webhook cadastrado no emitente, o campo urlWebhook também for informado diretamente em POST /NFSe/Emitir ou POST /NFSe/Cancelar/{codigoNota}, a URL do request tem prioridade sobre a cadastrada aqui — apenas para aquele envio específico.
Quando o evento ocorre, a IntegroBR faz um POST (Content-Type: application/json) para a url cadastrada, no formato do schema ProtocoloResponse — o mesmo schema devolvido por GET /NFSe/Consultar/Protocolo/{protocolo}. Apenas o status HTTP da sua resposta é considerado: somente 200 (OK) confirma o recebimento; qualquer outro status — ou timeout, o limite de espera pela resposta é de 10 segundos — é tratado como falha e faz a IntegroBR tentar novamente, em mais 2 reenvios (até 3 tentativas no total), com 30 minutos de intervalo entre elas.
Sua aplicação deve responder imediatamente com status 200 (OK) ao receber a notificação, e só então processar o payload — não espere o processamento terminar para responder. Como o limite de espera é de apenas 10 segundos, qualquer demora em responder é tratada como falha e gera uma nova tentativa, o que pode causar notificações duplicadas para o mesmo evento.
Evento de Emissão (evento: 0) — disparado quando o lote termina de ser processado com sucesso (nota autorizada pela prefeitura e PDF já gerado):
{
"protocolo": "PRD-145405dcfc0a48c4a23054c9584507a8",
"status": "PROCESSADO_COM_SUCESSO",
"notas": [
{
"codigoNota": 99999,
"tipoNota": "1",
"numero": "1",
"rps": "99",
"serie": "1",
"dataEmissao": "2026-01-01",
"situacao": "EMITIDA",
"codigoVerificacao": "ABCDEFGH",
"xml": "https://api.integrobr.com/nfse/xml/99999",
"pdf": "https://api.integrobr.com/nfse/pdf/99999",
"protocolo": "PRD-145405dcfc0a48c4a23054c9584507a8"
}
]
}
Evento de Cancelamento (evento: 1) — disparado quando o cancelamento de uma nota é concluído:
{
"protocolo": "PRD-9a1c2b3d4e5f60718293a4b5c6d7e8f9",
"status": "PROCESSADO_COM_SUCESSO",
"dadosCancelamento": {
"codigoNota": 99999,
"numeroNota": "1"
}
}
Repare que o campo status também retorna "PROCESSADO_COM_SUCESSO" neste caso — o mesmo valor do evento de Emissão. Para diferenciar os dois eventos programaticamente, não confie no status: verifique qual dos dois campos veio preenchido, notas (Emissão) ou dadosCancelamento (Cancelamento).
Evento de Rejeição (evento: 2) — disparado quando um protocolo (de emissão ou de cancelamento) é rejeitado pela prefeitura, ou falha antes de chegar lá (ex.: erro de validação):
{
"protocolo": "PRD-3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
"status": "REJEITADO",
"mensagem": "CPF/CNPJ do tomador inválido."
}
Como as notas de um protocolo rejeitado são descartadas no processamento, este payload nunca traz notas/dadosCancelamento — apenas mensagem, com o motivo da rejeição.
Retorna os detalhes de um webhook associado ao emitente do usuário da sessão.
| codigo required | string <uuid> Identificador único (GUID) do webhook |
| codigo | string or null <uuid> Identificador (GUID) do webhook. Obrigatório em PUT/DELETE; deve ser omitido no POST de um novo registro, pois é gerado pela plataforma |
| evento | integer <int32> (WebhookEvento) Enum: 0 1 2 |
| ativo | boolean Indica se o webhook está ativo. Quando false, a IntegroBR não realiza chamadas para este webhook |
| url | string or null URL HTTPS que receberá a chamada POST quando o evento configurado ocorrer |
| codigoEmitente | integer <int32> Código interno do emitente ao qual este webhook está vinculado |
{- "codigo": "81e48cac-c3e8-4135-aad1-32f73b3b54da",
- "evento": 0,
- "ativo": true,
- "url": "string",
- "codigoEmitente": 0
}Remove permanentemente um webhook associado ao emitente do usuário da sessão.
| codigo required | string <uuid> Example: 6f9619ff-8b86-d011-b42d-00cf4fc964ff Identificador único (GUID) do webhook a ser excluído |
| mensagem | string |
{- "mensagem": "Webhook excluído com sucesso."
}Retorna todos os webhooks vinculados ao emitente informado (do usuário autenticado).
| codigoEmitente required | integer Example: 101 Código interno do emitente (retornado no cadastro/consulta de emitente) |
| codigo | string or null <uuid> Identificador (GUID) do webhook. Obrigatório em PUT/DELETE; deve ser omitido no POST de um novo registro, pois é gerado pela plataforma |
| evento | integer <int32> (WebhookEvento) Enum: 0 1 2 |
| ativo | boolean Indica se o webhook está ativo. Quando false, a IntegroBR não realiza chamadas para este webhook |
| url | string or null URL HTTPS que receberá a chamada POST quando o evento configurado ocorrer |
| codigoEmitente | integer <int32> Código interno do emitente ao qual este webhook está vinculado |
[- {
- "codigo": "81e48cac-c3e8-4135-aad1-32f73b3b54da",
- "evento": 0,
- "ativo": true,
- "url": "string",
- "codigoEmitente": 0
}
]Cria um novo webhook para o emitente informado no corpo da requisição (codigoEmitente).
Um mesmo emitente pode ter múltiplos webhooks cadastrados — cadastre um por evento de interesse (ver a tabela de eventos no schema DtoWebhook). Não é uma configuração global da conta: cada emitente tem seu próprio conjunto de webhooks.
| codigo | string or null <uuid> Identificador (GUID) do webhook. Obrigatório em PUT/DELETE; deve ser omitido no POST de um novo registro, pois é gerado pela plataforma |
| evento | integer <int32> (WebhookEvento) Enum: 0 1 2 |
| ativo | boolean Indica se o webhook está ativo. Quando false, a IntegroBR não realiza chamadas para este webhook |
| url | string or null URL HTTPS que receberá a chamada POST quando o evento configurado ocorrer |
| codigoEmitente | integer <int32> Código interno do emitente ao qual este webhook está vinculado |
| codigo | string or null <uuid> Identificador (GUID) do webhook. Obrigatório em PUT/DELETE; deve ser omitido no POST de um novo registro, pois é gerado pela plataforma |
| evento | integer <int32> (WebhookEvento) Enum: 0 1 2 |
| ativo | boolean Indica se o webhook está ativo. Quando false, a IntegroBR não realiza chamadas para este webhook |
| url | string or null URL HTTPS que receberá a chamada POST quando o evento configurado ocorrer |
| codigoEmitente | integer <int32> Código interno do emitente ao qual este webhook está vinculado |
{- "codigo": "81e48cac-c3e8-4135-aad1-32f73b3b54da",
- "evento": 0,
- "ativo": true,
- "url": "string",
- "codigoEmitente": 0
}{- "codigo": "81e48cac-c3e8-4135-aad1-32f73b3b54da",
- "evento": 0,
- "ativo": true,
- "url": "string",
- "codigoEmitente": 0
}Atualiza os dados de um webhook existente vinculado ao emitente do usuário da sessão.
| codigo | string or null <uuid> Identificador (GUID) do webhook. Obrigatório em PUT/DELETE; deve ser omitido no POST de um novo registro, pois é gerado pela plataforma |
| evento | integer <int32> (WebhookEvento) Enum: 0 1 2 |
| ativo | boolean Indica se o webhook está ativo. Quando false, a IntegroBR não realiza chamadas para este webhook |
| url | string or null URL HTTPS que receberá a chamada POST quando o evento configurado ocorrer |
| codigoEmitente | integer <int32> Código interno do emitente ao qual este webhook está vinculado |
| codigo | string or null <uuid> Identificador (GUID) do webhook. Obrigatório em PUT/DELETE; deve ser omitido no POST de um novo registro, pois é gerado pela plataforma |
| evento | integer <int32> (WebhookEvento) Enum: 0 1 2 |
| ativo | boolean Indica se o webhook está ativo. Quando false, a IntegroBR não realiza chamadas para este webhook |
| url | string or null URL HTTPS que receberá a chamada POST quando o evento configurado ocorrer |
| codigoEmitente | integer <int32> Código interno do emitente ao qual este webhook está vinculado |
{- "codigo": "81e48cac-c3e8-4135-aad1-32f73b3b54da",
- "evento": 0,
- "ativo": true,
- "url": "string",
- "codigoEmitente": 0
}{- "codigo": "81e48cac-c3e8-4135-aad1-32f73b3b54da",
- "evento": 0,
- "ativo": true,
- "url": "string",
- "codigoEmitente": 0
}Envia um payload mockado (no mesmo formato do payload real, ver seção "Payload enviado pela IntegroBR ao seu webhook" na descrição do grupo Webhook) para a url informada, permitindo validar a integração antes de emitir/cancelar uma nota de verdade.
Não depende de um webhook já cadastrado (WebhookEntity) — url e evento são informados diretamente no corpo da requisição. Reaproveita o mesmo cliente HTTP e timeout de 10 segundos usados nas notificações reais: qualquer resposta que não seja 200 (OK) dentro desse prazo é tratada como falha.
| url | string or null URL HTTPS que receberá o payload de teste |
| evento | integer <int32> (WebhookEvento) Enum: 0 1 2 |
| mensagem | string |
{- "url": "string",
- "evento": 0
}{- "mensagem": "Webhook obteve resposta de sucesso!"
}Emissão, consulta, cancelamento e download (XML/PDF) de notas fiscais de serviço eletrônicas. O envio e o cancelamento são assíncronos — use o protocolo retornado para acompanhar o resultado (ver "Fluxo de Integração" acima).
Recebe um lote com uma ou mais notas fiscais de serviço para emissão.
O processamento é assíncrono: a resposta deste endpoint apenas confirma o recebimento do lote e devolve um protocolo, que deve ser usado posteriormente em GET /NFSe/Consultar/Protocolo/{protocolo} (ou recebido via webhook, se configurado) para acompanhar o resultado do processamento junto à prefeitura.
Pontos importantes:
enviarParaProducao define se a nota será enviada para o ambiente de produção da prefeitura (true) ou para homologação/teste (false). O protocolo gerado recebe um prefixo diferente para cada ambiente (ex.: HML-/PRD-), o que permite filtrar as consultas por ambiente.urlWebhook para ser notificado assim que o processamento for concluído, evitando a necessidade de polling na consulta de protocolo.| identificacaoEmitente | string or null CPF ou CNPJ (apenas números) do emitente já cadastrado na plataforma, que será o prestador de todas as notas deste lote. Obrigatório |
Array of objects or null (NotaFiscalResumida) Lista de notas fiscais que compõem o lote (podem ser enviadas várias notas de uma vez). Obrigatório, deve conter ao menos uma nota | |
| enviarParaProducao | boolean Define se o lote será enviado para o ambiente de produção da prefeitura (true) ou para homologação/teste (false). Obrigatório — afeta o prefixo do protocolo retornado |
| urlWebhook | string or null URL que receberá uma notificação HTTP POST assim que o processamento do lote for concluído. Campo opcional — se não informada, o resultado só fica disponível via consulta de protocolo |
| protocolo required | string Identificador único do protocolo, usado para consultar o andamento em GET /NFSe/Consultar/Protocolo/{protocolo} |
| status required | string Status atual do protocolo. Valores possíveis: 'EM_FILA' (aguardando processamento), 'EM_PROCESSAMENTO' (em andamento), 'PENDENTE_PREFEITURA' (aguardando retorno da prefeitura), 'PROCESSADO_COM_SUCESSO' (concluído), 'REJEITADO' (rejeitado pela prefeitura, ver mensagem), 'CANCELADO' e 'ERRO_INTERNO' |
| mensagem | string or null Mensagem detalhando o resultado do processamento, especialmente útil quando status for 'REJEITADO' ou 'ERRO_INTERNO' |
Array of objects or null (ProtocoloNotaResponse) Notas fiscais processadas neste protocolo, com o resultado individual de cada uma | |
| dadosCancelamento | object or null Presente apenas quando o protocolo se refere a um cancelamento de nota, com o código e o número da nota cancelada |
{- "identificacaoEmitente": "string",
- "notas": [
- {
- "rps": {
- "numeroRPS": "string",
- "numeroNota": "string",
- "serie": "string",
- "tipo": "string",
- "status": 0,
- "dataEmissao": "2019-08-24T14:15:22Z",
- "dataCompetencia": "2019-08-24T14:15:22Z",
- "codigoVerificacao": "string",
- "chaveNota": "string"
}, - "destinatario": {
- "razaoSocial": "string",
- "nomeFantasia": "string",
- "cpfCnpj": "string",
- "inscricaoEstadual": "string",
- "inscricaoMunicipal": "string",
- "telefone": "string",
- "endereco": {
- "logradouro": "string",
- "numero": "string",
- "bairro": "string",
- "cep": "string",
- "complemento": "string",
- "codigoPais": 0,
- "codigoIBGEUF": 0,
- "codigoIBGEMunicipio": 0,
- "descricaoUF": "string",
- "descricaoMunicipio": "string",
- "siglaUF": "string"
}
}, - "servicos": [
- {
- "codigo": "string",
- "descricao": "string",
- "codigoTributacao": "string",
- "localPrestacao": "string",
- "responsavelPelaRetencao": 0,
- "exigibilidadeISS": 0,
- "tipoTributacao": 0,
- "municipioIncidencia": 0,
- "aliquotaISS": 0.1,
- "retemISS": 0,
- "quantidade": 0.1,
- "valorUnitario": 0.1,
- "valorDesconto": 0.1,
- "valorAcrescimo": 0.1,
- "codigoCnae": "string",
- "numeroProcesso": "string",
- "nbs": "string",
- "ibsCbs": {
- "codigoOperacao": "string",
- "operacaoTrabalhista": "string",
- "categoriaOperacao": "string",
- "categoriaEntePublico": "string",
- "descricaoCategoriaEntePublico": "string",
- "regime": {
- "cst": "string",
- "cct": "string"
}
}, - "pisCofins": {
- "modalidadeRetencao": "string",
- "baseDeCalculo": 0.1,
- "cst": "string",
- "pis": {
- "percentual": 0.1,
- "valor": 0.1
}, - "cofins": {
- "percentual": 0.1,
- "valor": 0.1
}
}, - "totaisDosTributos": {
- "percentualDosTributosFederais": 0.1,
- "percentualDosTributosEstaduais": 0.1,
- "percentualDosTributosMunicipais": 0.1,
- "percentualDosTributosDoSimplesNacional": 0.1
}
}
], - "condicoesPagamentos": [
- {
- "condicao": "string",
- "pagamentos": [
- {
- "parcela": 0,
- "dataPagamento": "2019-08-24T14:15:22Z",
- "valor": 0.1
}
]
}
], - "observacao": "string",
- "subtituicaoRps": {
- "numeroRPS": "string",
- "numeroNota": "string",
- "serie": "string",
- "tipo": "string"
}
}
], - "enviarParaProducao": true,
- "urlWebhook": "string"
}{- "protocolo": "string",
- "status": "string",
- "mensagem": "string",
- "notas": [
- {
- "codigoNota": 0,
- "tipoNota": "string",
- "numero": "string",
- "rps": "string",
- "serie": "string",
- "situacao": "string",
- "dataEmissao": "2019-08-24",
- "codigoVerificacao": "string",
- "dataHoraCancelamento": "2019-08-24T14:15:22Z",
- "protocolo": "string"
}
], - "dadosCancelamento": { }
}Retorna os dados da nota fiscal eletrônica, incluindo links para o XML e PDF.
| codigoNota required | integer Código identificador da nota fiscal. |
| codigoNota required | integer Código interno da nota fiscal na plataforma, usado para consultar/cancelar/baixar XML e PDF |
| tipoNota | string or null Tipo do RPS que originou a nota (mesma tabela de rps.tipo: '1' = RPS comum, '2' = RPS Misto, '3' = Cupom) |
| numero | string or null Número definitivo da nota fiscal, atribuído pela prefeitura. Só é preenchido após a autorização |
| rps required | string Número do RPS (Recibo Provisório de Serviços) que originou esta nota |
| serie required | string Série do RPS/nota fiscal |
| situacao required | string Situação atual da nota. Valores possíveis: 'EM_PROCESSAMENTO', 'EMITIDA', 'CANCELADA', 'DENEGADA', 'REJEITADA', 'PENDENTE_PREFEITURA' |
| dataEmissao required | string <date> Data de emissão da nota |
| codigoVerificacao | string or null Código de verificação/autenticidade da nota, retornado pela prefeitura (quando aplicável ao município) |
| xml | string or null <uri> URL para download do XML autorizado da nota fiscal (disponível apenas quando a nota já foi emitida com sucesso) |
string or null <uri> URL para download do PDF (DANFSE) da nota fiscal (disponível apenas quando a nota já foi emitida com sucesso) | |
| dataHoraCancelamento | string or null <date-time> Data e hora em que a nota foi cancelada. Ausente/nulo quando a nota não foi cancelada |
| protocolo | string or null Identificador do protocolo de processamento ao qual esta nota pertence, útil para consultar o lote completo em GET /NFSe/Consultar/Protocolo/{protocolo} |
{- "codigoNota": 99999,
- "tipoNota": "1",
- "numero": "1",
- "rps": "99",
- "serie": "1",
- "situacao": "Autorizada",
- "dataEmissao": "2025-01-01",
- "codigoVerificacao": "ABCDEFGH",
- "dataHoraCancelamento": "2025-01-01T20:11:44.0000000-03:00",
- "protocolo": "HML-145405dcfc0a48c4a23054c9584507a8"
}Retorna até 50 notas do usuário cujo identificador de protocolo (ambiente) começa com o prefixo informado (ex.: homologação vs produção, conforme prefixo gravado no protocolo).
| ambiente required | string Example: PRD Prefixo do protocolo usado para filtrar o ambiente das notas (ex.: 'HML' para homologação, 'PRD' para produção) |
| codigoNota required | integer Código interno da nota fiscal na plataforma, usado para consultar/cancelar/baixar XML e PDF |
| codigoEmitente required | integer Código interno do emitente (prestador) responsável pela nota |
| cpfCnpjEmitente required | string CPF ou CNPJ do emitente responsável pela nota |
| nomeEmitente required | string Razão social do emitente responsável pela nota |
| numeroRPS required | string Número do RPS que originou a nota |
| serieRPS required | string Série do RPS que originou a nota |
| loteRPS required | integer Código interno do lote ao qual esta nota pertence |
| valorTotal required | number Valor total dos serviços prestados na nota |
| status required | string Status atual da nota. Valores possíveis: 'EM_PROCESSAMENTO', 'EMITIDA', 'CANCELADA', 'DENEGADA', 'REJEITADA', 'PENDENTE_PREFEITURA' |
| dataAutorizacao | string or null <date> Data de emissão/autorização da nota |
| tempoDeProcessamento | string or null Tempo total decorrido entre o início e o fim do processamento da nota, já formatado para exibição (ex.: '350ms', '4s', '2m 10s', '1h 5m 30s'). Nulo enquanto a nota ainda está em processamento |
| protocolo | string or null Identificador do protocolo ao qual esta nota pertence, útil para consultar o lote completo em GET /NFSe/Consultar/Protocolo/{protocolo} |
[- {
- "codigoNota": 0,
- "codigoEmitente": 0,
- "cpfCnpjEmitente": "string",
- "nomeEmitente": "string",
- "numeroRPS": "string",
- "serieRPS": "string",
- "loteRPS": 0,
- "valorTotal": 0,
- "status": "string",
- "dataAutorizacao": "2019-08-24",
- "tempoDeProcessamento": "string",
- "protocolo": "string"
}
]Até 50 notas filtradas por ambiente (prefixo do protocolo) e termo (código da nota, CNPJ, número, razão/nome fantasia ou identificador do protocolo).
| ambiente required | string Example: PRD Prefixo do protocolo usado para filtrar o ambiente das notas (ex.: 'HML' para homologação, 'PRD' para produção) |
| termo required | string Termo de busca livre: casa com código da nota, CNPJ do emitente, número da nota, razão social/nome fantasia do emitente ou identificador do protocolo |
| codigoNota required | integer Código interno da nota fiscal na plataforma, usado para consultar/cancelar/baixar XML e PDF |
| codigoEmitente required | integer Código interno do emitente (prestador) responsável pela nota |
| cpfCnpjEmitente required | string CPF ou CNPJ do emitente responsável pela nota |
| nomeEmitente required | string Razão social do emitente responsável pela nota |
| numeroRPS required | string Número do RPS que originou a nota |
| serieRPS required | string Série do RPS que originou a nota |
| loteRPS required | integer Código interno do lote ao qual esta nota pertence |
| valorTotal required | number Valor total dos serviços prestados na nota |
| status required | string Status atual da nota. Valores possíveis: 'EM_PROCESSAMENTO', 'EMITIDA', 'CANCELADA', 'DENEGADA', 'REJEITADA', 'PENDENTE_PREFEITURA' |
| dataAutorizacao | string or null <date> Data de emissão/autorização da nota |
| tempoDeProcessamento | string or null Tempo total decorrido entre o início e o fim do processamento da nota, já formatado para exibição (ex.: '350ms', '4s', '2m 10s', '1h 5m 30s'). Nulo enquanto a nota ainda está em processamento |
| protocolo | string or null Identificador do protocolo ao qual esta nota pertence, útil para consultar o lote completo em GET /NFSe/Consultar/Protocolo/{protocolo} |
[- {
- "codigoNota": 0,
- "codigoEmitente": 0,
- "cpfCnpjEmitente": "string",
- "nomeEmitente": "string",
- "numeroRPS": "string",
- "serieRPS": "string",
- "loteRPS": 0,
- "valorTotal": 0,
- "status": "string",
- "dataAutorizacao": "2019-08-24",
- "tempoDeProcessamento": "string",
- "protocolo": "string"
}
]Retorna notas fiscais do usuário autenticado com suporte a paginação, filtro rápido (texto livre) e filtros estruturados por campo/operador/valor. Útil para telas de consulta com grade e busca avançada.
| ambiente | string or null Prefixo do protocolo (ex.: 'HML' para homologação, 'PRD' para produção) usado para restringir a consulta a um ambiente |
| filtroRapido | string or null Termo de busca rápida (texto livre), casa com código da nota, CNPJ do emitente, número da nota, RPS, razão social/nome fantasia do emitente ou identificador do protocolo. Pode ser combinado com 'filtros' |
Array of objects or null (DtoFiltro) Filtros estruturados adicionais, combinados entre si com E lógico (todos precisam ser atendidos) e com o filtroRapido, quando ambos forem informados | |
| pagina | integer <int32> Número da página a ser retornada, começando em 1 |
| limiteDaPagina | integer <int32> Quantidade máxima de notas por página (máximo 100) |
required | Array of objects (DtoNotaFiscalResumo) Notas fiscais da página atual (quantidade limitada por limiteDaPagina) |
| paginaAtual required | integer Número da página retornada (o mesmo valor informado em pagina, ou 1 se não informado/inválido) |
| totalDeRegistros required | integer Total de notas que atendem ao(s) filtro(s), em todas as páginas |
| totalEmProcessamento required | integer Total de notas com status 'EM_PROCESSAMENTO' dentre as que atendem ao(s) filtro(s) |
| totalEmitidas required | integer Total de notas com status 'EMITIDA' dentre as que atendem ao(s) filtro(s) |
| totalCanceladas required | integer Total de notas com status 'CANCELADA' dentre as que atendem ao(s) filtro(s) |
| totalDenegadas required | integer Total de notas com status 'DENEGADA' dentre as que atendem ao(s) filtro(s) |
| totalRejeitadas required | integer Total de notas com status 'REJEITADA' dentre as que atendem ao(s) filtro(s) |
| totalPendentes required | integer Total de notas com status 'PENDENTE_PREFEITURA' dentre as que atendem ao(s) filtro(s) |
{- "ambiente": "string",
- "filtroRapido": "string",
- "filtros": [
- {
- "campo": "string",
- "operador": 0,
- "valor": "string",
- "valorFinal": "string"
}
], - "pagina": 0,
- "limiteDaPagina": 0
}{- "notas": [
- {
- "codigoNota": 0,
- "codigoEmitente": 0,
- "cpfCnpjEmitente": "string",
- "nomeEmitente": "string",
- "numeroRPS": "string",
- "serieRPS": "string",
- "loteRPS": 0,
- "valorTotal": 0,
- "status": "string",
- "dataAutorizacao": "2019-08-24",
- "tempoDeProcessamento": "string",
- "protocolo": "string"
}
], - "paginaAtual": 0,
- "totalDeRegistros": 0,
- "totalEmProcessamento": 0,
- "totalEmitidas": 0,
- "totalCanceladas": 0,
- "totalDenegadas": 0,
- "totalRejeitadas": 0,
- "totalPendentes": 0
}Permite consultar as notas fiscais de serviço associadas a um determinado protocolo de envio. O protocolo é informado como parâmetro de rota.
| protocolo required | string Identificador externo do protocolo (GUID/string retornado no envio) |
| protocolo required | string Identificador único do protocolo, usado para consultar o andamento em GET /NFSe/Consultar/Protocolo/{protocolo} |
| status required | string Status atual do protocolo. Valores possíveis: 'EM_FILA' (aguardando processamento), 'EM_PROCESSAMENTO' (em andamento), 'PENDENTE_PREFEITURA' (aguardando retorno da prefeitura), 'PROCESSADO_COM_SUCESSO' (concluído), 'REJEITADO' (rejeitado pela prefeitura, ver mensagem), 'CANCELADO' e 'ERRO_INTERNO' |
| mensagem | string or null Mensagem detalhando o resultado do processamento, especialmente útil quando status for 'REJEITADO' ou 'ERRO_INTERNO' |
Array of objects or null (ProtocoloNotaResponse) Notas fiscais processadas neste protocolo, com o resultado individual de cada uma | |
| dadosCancelamento | object or null Presente apenas quando o protocolo se refere a um cancelamento de nota, com o código e o número da nota cancelada |
{- "protocolo": "string",
- "status": "string",
- "mensagem": "string",
- "notas": [
- {
- "codigoNota": 0,
- "tipoNota": "string",
- "numero": "string",
- "rps": "string",
- "serie": "string",
- "situacao": "string",
- "dataEmissao": "2019-08-24",
- "codigoVerificacao": "string",
- "dataHoraCancelamento": "2019-08-24T14:15:22Z",
- "protocolo": "string"
}
], - "dadosCancelamento": { }
}Permite cancelar uma nota fiscal de serviço previamente emitida. O cancelamento é realizado com base no código da nota fiscal. É possível informar opcionalmente uma URL de webhook para ser notificado com o resultado do processamento.
| codigoNota required | integer Código da nota fiscal a ser cancelada |
| urlWebhook | string <uri> URL para notificação via webhook (opcional) |
| protocolo required | string Identificador único do protocolo, usado para consultar o andamento em GET /NFSe/Consultar/Protocolo/{protocolo} |
| status required | string Status atual do protocolo. Valores possíveis: 'EM_FILA' (aguardando processamento), 'EM_PROCESSAMENTO' (em andamento), 'PENDENTE_PREFEITURA' (aguardando retorno da prefeitura), 'PROCESSADO_COM_SUCESSO' (concluído), 'REJEITADO' (rejeitado pela prefeitura, ver mensagem), 'CANCELADO' e 'ERRO_INTERNO' |
| mensagem | string or null Mensagem detalhando o resultado do processamento, especialmente útil quando status for 'REJEITADO' ou 'ERRO_INTERNO' |
Array of objects or null (ProtocoloNotaResponse) Notas fiscais processadas neste protocolo, com o resultado individual de cada uma | |
| dadosCancelamento | object or null Presente apenas quando o protocolo se refere a um cancelamento de nota, com o código e o número da nota cancelada |
{
}{- "protocolo": "string",
- "status": "string",
- "mensagem": "string",
- "notas": [
- {
- "codigoNota": 0,
- "tipoNota": "string",
- "numero": "string",
- "rps": "string",
- "serie": "string",
- "situacao": "string",
- "dataEmissao": "2019-08-24",
- "codigoVerificacao": "string",
- "dataHoraCancelamento": "2019-08-24T14:15:22Z",
- "protocolo": "string"
}
], - "dadosCancelamento": { }
}Retorna o arquivo XML referente à nota fiscal identificada pelo codigoNota.
| codigoNota required | integer Código da nota fiscal. |
{- "mensagem": "string"
}Retorna o arquivo PDF referente à nota fiscal identificada pelo codigoNota.
| codigoNota required | integer Código da nota fiscal. |
{- "mensagem": "string"
}Consulta do plano contratado, do consumo de notas do ciclo vigente e controle do excedente de emissão, quando o limite do plano é atingido.
Retorna os dados do plano atualmente contratado pela conta autenticada: mensalidade, limite de notas do ciclo, valor cobrado por nota excedente e a data de renovação do ciclo vigente.
"Renovação" aqui é o fim do ciclo de consumo atual (calculado a partir do vencimento da cobrança recorrente da mensalidade — ver GET /Plano/Consumo), não uma ação manual do integrador.
possivelUpgrade indica apenas se existe algum outro plano ativo de ordem superior no catálogo — este endpoint não expõe uma tela/fluxo de troca de plano.
| nome required | string Nome do tier de plano contratado (ex.: 'Básico', 'Profissional') |
| valorMensal required | number <double> Valor da mensalidade do plano |
| limiteNotas required | integer Quantidade de notas (status EMITIDA) incluída na mensalidade, por ciclo |
| valorUnitarioExcedente required | number <double> Valor cobrado por cada nota emitida além do limite do plano, quando o excedente estiver habilitado |
| permiteExcedente required | boolean Se a conta pode ultrapassar o limite de notas do plano (toggle da Licença, não do plano em si — ver PUT /Plano/Excedente) |
| dataRenovacao required | string <date> Data de fim do ciclo de consumo vigente |
| possivelUpgrade required | boolean Indica se existe, no catálogo, outro plano ativo de ordem superior ao atual (não expõe qual nem oferece um fluxo de troca) |
{- "nome": "string",
- "valorMensal": 0.1,
- "limiteNotas": 0,
- "valorUnitarioExcedente": 0.1,
- "permiteExcedente": true,
- "dataRenovacao": "2019-08-24",
- "possivelUpgrade": true
}Retorna quantas notas fiscais já foram emitidas (status EMITIDA) no ciclo de consumo vigente, o limite do plano contratado e quantos dias restam até o fim do ciclo.
O consumo nunca é persistido — é sempre recalculado on-the-fly somando as notas emitidas de todos os emitentes vinculados ao responsável pela conta (mesmo critério usado para bloquear a emissão em POST /NFSe/Emitir).
| notasEmitidas required | integer Quantidade de notas com status EMITIDA no ciclo vigente, somando todos os emitentes do responsável pela conta |
| limiteNotas required | integer Limite de notas do plano contratado para o ciclo |
| diasRestantes required | integer Dias restantes até o fim do ciclo vigente (nunca negativo) |
| inicioPeriodo required | string <date> |
| fimPeriodo required | string <date> |
{- "notasEmitidas": 0,
- "limiteNotas": 0,
- "diasRestantes": 0,
- "inicioPeriodo": "2019-08-24",
- "fimPeriodo": "2019-08-24"
}Retorna quantas notas foram emitidas acima do limite do plano no ciclo vigente e o valor total que seria cobrado por esse excedente (notasExcedentes × valorUnitarioExcedente do plano).
Esta consulta sempre retorna o valor projetado, independentemente de permiteExcedente estar habilitado — a cobrança de fato só é gerada automaticamente ao fechar o ciclo (na emissão da próxima mensalidade) se o toggle estiver ligado, ver PUT /Plano/Excedente.
| notasExcedentes required | integer Quantidade de notas emitidas além do limite do plano no ciclo vigente (0 se dentro do limite) |
| valorTotalExcedente required | number <double> notasExcedentes × valorUnitarioExcedente do plano contratado. É apenas uma projeção — só é efetivamente cobrada se permiteExcedente estiver habilitado, no fechamento do ciclo |
| apenasPeriodoAtual required | boolean Sempre true nesta versão da API — o valor retornado sempre se refere apenas ao ciclo vigente, nunca a um acumulado histórico |
{- "notasExcedentes": 0,
- "valorTotalExcedente": 0.1,
- "apenasPeriodoAtual": true
}Define se a conta pode ultrapassar o limite de notas do plano contratado.
Quando habilitado (permitir: true), a emissão de notas continua funcionando normalmente mesmo após o limite ser atingido, e o excedente do ciclo é cobrado automaticamente (Pix avulsa, motivoCobranca: Excedente) no fechamento do ciclo, junto com a geração da próxima mensalidade.
Quando desabilitado e o limite é atingido, POST /NFSe/Emitir passa a rejeitar novas notas até o início do próximo ciclo ou até um upgrade de plano.
Requer licença ativa.
| permitir | boolean true para permitir ultrapassar o limite do plano (com cobrança automática do excedente); false para bloquear novas emissões ao atingir o limite |
| permiteExcedente | boolean |
{- "permitir": true
}{- "permiteExcedente": true
}