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 Almztech 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 Almztech 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 Almztech 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 Almztech 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 Almztech 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 Almztech 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 anterior, que é arquivado.
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 é arquivado, não fica mais em uso) — não é necessário excluir antes de trocar um certificado vencido ou renovado.
O certificado é recusado quando está vencido (ou ainda não começou a valer) e quando o titular não é o emitente: o CPF/CNPJ é lido do certificado ICP-Brasil (e-CNPJ ou e-CPF) e comparado com o documento do emitente. Um e-CNPJ de outro estabelecimento da mesma empresa (mesma raiz de 8 dígitos — ex.: o certificado da matriz num emitente filial) é aceito, mas a resposta traz um aviso: cada prefeitura decide se aceita o certificado da matriz na nota da filial.
| 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) |
| aviso | string or null Preenchido quando o certificado é de outro estabelecimento da mesma empresa (mesma raiz de CNPJ). O vínculo é feito, mas a emissão pode ser rejeitada pela prefeitura se ela não aceitar o certificado da matriz. Nulo quando o titular é o próprio emitente |
{- "cnpjEmissor": "12345678000199",
- "base64": "string",
- "senha": "string"
}{- "chaveCertificado": "string",
- "vencimento": "2019-08-24T14:15:22Z",
- "aviso": "string"
}Cadastro de URLs, por emitente, que a Almztech 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 Almztech 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 Almztech 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.almztech.com.br/nfse/xml/99999",
"pdf": "https://api.almztech.com.br/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 Almztech 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 Almztech 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 Almztech 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 Almztech 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 Almztech 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 Almztech 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 Almztech 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": { }
}| arquivoBase64 | string or null |
| identificacaoEmitente | string or null |
| enviarParaProducao | boolean |
| urlWebhook | string or null |
{- "arquivoBase64": "string",
- "identificacaoEmitente": "string",
- "enviarParaProducao": true,
- "urlWebhook": "string"
}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 os dados da nota fiscal eletrônica a partir do número da nota, incluindo links para o XML e PDF.
| numeroNota required | string Número 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 |
| numeroNota required | string Número da nota fiscal emitida pela prefeitura, usado para consultar em GET /NFSe/Consultar/Numero/{numeroNota} |
| 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,
- "numeroNota": "string",
- "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 |
| numeroNota required | string Número da nota fiscal emitida pela prefeitura, usado para consultar em GET /NFSe/Consultar/Numero/{numeroNota} |
| 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,
- "numeroNota": "string",
- "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,
- "numeroNota": "string",
- "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": { }
}Consulta novamente, junto à prefeitura/governo, o estado atual de uma nota fiscal já existente na plataforma, usando a chave/RPS/número já salvos na nota — e atualiza a nota local com o resultado (nunca cria uma nota nova).
Útil como reconciliação manual quando o status local pode estar desatualizado: reprocessa o XML/código de verificação retornados e, para notas emitidas pelo padrão Nacional (Sefin Nacional/ADN), também verifica se a nota foi cancelada nos eventos da ADN — se detectado, o status local é atualizado para CANCELADA e o PDF é regerado automaticamente.
Para notas do padrão Nacional que ainda não têm a chave de acesso salva localmente, use POST /NFSe/Reconsultar/ChaveAcesso/{chaveAcesso} em vez deste endpoint.
| codigoNota required | integer Código interno da nota fiscal a ser reconsultada |
| 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": 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"
}Variante de POST /NFSe/Reconsultar/{codigoNota} para notas do padrão Nacional (Sefin Nacional/ADN) que ainda não possuem a chave de acesso salva localmente — por exemplo, quando a nota foi emitida por fora do fluxo normal ou a chave nunca chegou a ser persistida.
O CNPJ do emitente é extraído da própria chave de acesso (posição fixa, 14 dígitos) para localizar o emitente e, em seguida, a prefeitura/governo é consultada. A nota local correspondente é localizada por emitente + número da nota retornado na consulta (mesmo critério de desambiguação usado em GET /NFSe/Consultar/Numero/{numeroNota}, pegando a mais recente em caso de mais de um resultado) — e então tem sua chave de acesso preenchida com o valor informado na rota.
Como ainda não há nota local identificada no momento da chamada, o ambiente (produção real vs. restrita) não pode ser inferido automaticamente e precisa ser informado no corpo da requisição via enviarParaProducao.
| chaveAcesso required | string Chave de acesso (50 dígitos) da NFSe Nacional a ser reconsultada |
| enviarParaProducao | boolean Default: false Define se a consulta deve ser feita no ambiente de produção real (true) ou de produção restrita/testes (false) do governo. Sem nota local ainda identificada, não há como inferir esse valor automaticamente |
| 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} |
{- "enviarParaProducao": false
}{- "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"
}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 catálogo de planos disponíveis, do consumo de notas do ciclo vigente e controle do excedente de emissão, quando o limite do plano é atingido.
Toda conta nasce no plano gratuito de entrada (menor ordem do catálogo). A troca de plano (PUT /Plano/Alterar) nunca é aplicada na hora: gera uma cobrança de mensalidade (Boleto Pix) e o novo plano só passa a valer quando essa cobrança é paga — enquanto isso, o plano retornado por GET /Plano/Atual continua sendo o atual. Depois de contratar qualquer plano pago, a conta não pode mais voltar ao plano de entrada.
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 — use GET /Plano/Disponiveis para listar as opções e PUT /Plano/Alterar para contratar uma delas.
fimPeriodoGratuito só é preenchido quando a licença vigente é do tipo trial (período grátis inicial) — é null para licenças já faturadas, mesmo que o plano contratado seja o gratuito de entrada.
| 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 — ver GET /Plano/Disponiveis) |
| licencaValida required | boolean Se a licença vigente da conta ainda está dentro do prazo (trial ou faturada). Se false, a emissão de notas está bloqueada até renovação/pagamento |
| fimPeriodoGratuito | string or null <date> Data de fim do período grátis (trial), preenchida apenas quando a licença vigente é do tipo trial. null para licenças já faturadas |
{- "nome": "string",
- "valorMensal": 0.1,
- "limiteNotas": 0,
- "valorUnitarioExcedente": 0.1,
- "permiteExcedente": true,
- "dataRenovacao": "2019-08-24",
- "possivelUpgrade": true,
- "licencaValida": true,
- "fimPeriodoGratuito": "2019-08-24"
}Lista os planos ativos que a conta pode contratar via PUT /Plano/Alterar, ordenados por ordem (do menor para o maior tier).
O plano gratuito de entrada (menor ordem) só aparece nesta lista se a conta ainda não tiver contratado nenhum plano pago até hoje — depois da primeira licença faturada, a conta não pode mais voltar para o plano de entrada, então ele é omitido do catálogo retornado.
| codigo required | integer Código interno do plano, usado em PUT /Plano/Alterar (campo codigoPlano) |
| nome required | string Nome do tier de plano (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 |
| ordem required | integer Posição do plano no catálogo, do menor tier (plano gratuito de entrada) para o maior |
[- {
- "codigo": 0,
- "nome": "string",
- "valorMensal": 0.1,
- "limiteNotas": 0,
- "valorUnitarioExcedente": 0.1,
- "ordem": 0
}
]Inicia a troca para o plano informado (codigoPlano, ver GET /Plano/Disponiveis). A troca nunca é aplicada na hora: este endpoint apenas gera a cobrança recorrente da mensalidade (Boleto Pix) e a primeira ocorrência dela — o plano só passa a valer de fato quando essa cobrança é confirmada como paga (GET /Plano/Atual continua retornando o plano vigente até lá).
Se ainda houver dias de período grátis (trial) restantes, a data de início do novo plano é agendada para o fim do trial (dataInicioLicencaPrevista na resposta) — o período grátis em curso não é interrompido. Sem trial vigente, o novo plano começa a valer assim que a cobrança é paga.
Qualquer troca de plano anterior ainda não paga da mesma conta é cancelada automaticamente antes de criar a nova (inclusive o boleto correspondente no Banco Inter, best-effort), evitando cobrança duplicada quando o integrador tenta a troca mais de uma vez.
Não exige [ValidarLicenca] de propósito — é o próprio meio de uma conta com trial expirado se desbloquear contratando um plano pago.
| codigoPlano | integer <int32> Código do plano a ser contratado (ver codigo em GET /Plano/Disponiveis) |
object (DtoCobrancaRecorrente) Template de cobrança recorrente (mensalidade do plano ou Boleto Pix recorrente avulso) gerado pela troca de plano | |
object (DtoHistoricoCobranca) Uma ocorrência de cobrança (mensalidade, excedente ou avulsa) no histórico de faturamento da conta | |
| dataInicioLicencaPrevista | string or null <date> Data em que o novo plano passa a valer, quando há trial vigente sendo preservado (o plano é agendado para o fim do período grátis). null quando não há trial em curso — nesse caso o plano passa a valer assim que a cobrança gerada é paga |
{- "codigoPlano": 0
}{- "recorrente": {
- "identificadorExterno": "a53b9cc2-614e-47ab-adbe-9a74b9a6f39e",
- "descricao": "string",
- "nomeSacado": "string",
- "cpfCnpjSacado": "string",
- "emailSacado": "string",
- "enderecoSacado": "string",
- "cidadeSacado": "string",
- "ufSacado": "string",
- "cepSacado": "string",
- "valorNominal": 0.1,
- "diaVencimento": 0,
- "periodicidadeEmMeses": 0,
- "dataInicio": "2019-08-24",
- "dataFim": "2019-08-24",
- "diasAntecedenciaEmissao": 0,
- "descontoCodigo": "string",
- "descontoValor": 0.1,
- "multaCodigo": "string",
- "multaValor": 0.1,
- "moraCodigo": "string",
- "moraValor": 0.1,
- "statusDescricao": "string",
- "criadoEm": "2019-08-24T14:15:22Z",
- "atualizadoEm": "2019-08-24T14:15:22Z"
}, - "cobranca": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tipo": "plano",
- "descricao": "Mensalidade do plano",
- "valor": 0.1,
- "dataEmissao": "2019-08-24",
- "dataVencimento": "2019-08-24",
- "dataPagamento": "2019-08-24",
- "status": "pago",
- "comprovanteDisponivel": true,
- "linhaDigitavel": "string"
}, - "dataInicioLicencaPrevista": "2019-08-24"
}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
}