Acesso Externo via API (Web Service)
Guia prático para emitir, consultar e cancelar notas fiscais a partir do seu sistema.
Índice
- Comece aqui (resumo)
- Obter acesso: Ambiente de Teste e Produção
- Chave de API e conexão
- Pré-requisitos do prestador
- Emitir nota fiscal (passo a passo)
- IBS e CBS (Reforma Tributária)
- Situações especiais
- Consultar notas fiscais
- Cancelar nota fiscal
- Guias de pagamento
- Erros comuns
- Referência de campos
1. Comece aqui (resumo)
A API usa o protocolo XML-RPC,
suportado por praticamente todas as linguagens. Todas as operações são feitas em
duas URLs: /xmlrpc/2/common (autenticação) e /xmlrpc/2/object
(operações). Você faz as mesmas ações que faria no navegador, só que pelo seu sistema.
O fluxo completo de uma emissão é:
- Obter um usuário no ambiente (no Ambiente de Teste, isso é feito pelo suporte, veja a seção 2).
- Gerar uma Chave de API no seu perfil e autenticar.
- Buscar (ou cadastrar) o tomador pelo CPF/CNPJ.
- Criar a nota em RASCUNHO com itens, serviço, serviço NBS e descrição, em uma única chamada.
- Conferir os valores calculados pelo sistema (ISS, IBS, CBS etc.).
- Emitir (
action_emitir). - Ler o número, o PDF e o XML da nota emitida.
2. Obter acesso: Ambiente de Teste e Produção
Existem dois ambientes independentes (usuários, senhas, chaves de API e notas de um não existem no outro):
| Ambiente | Para que serve | Como obter usuário |
|---|---|---|
| Teste | Desenvolver e testar a integração. Notas emitidas aqui não têm validade fiscal. | Somente pelo suporte. Veja abaixo. |
| Produção | Emissão real de notas fiscais. | Cadastro normal no site da prefeitura e aguardar a aprovação do cadastro. |
Ambiente de Teste: abra um chamado antes de começar
O Ambiente de Teste não envia e-mails. Por isso, o autocadastro não funciona: o e-mail para definir a senha nunca chega. O nome do banco de dados do Ambiente de Teste também é informado pelo suporte. Não tente se cadastrar no Ambiente de Teste.
Abra um chamado pela página de contato informando:
- que deseja acesso ao Ambiente de Teste da API deste município;
- CPF/CNPJ e razão social do prestador que vai emitir as notas;
- nome e e-mail do responsável técnico pela integração;
O suporte vai devolver:
- a URL e o nome do banco de dados do Ambiente de Teste;
- o usuário (login) e uma senha inicial;
- o prestador já cadastrado com serviço e serviço NBS, pronto para emitir.
Nunca envie a sua chave de API ou senha em chamados.
Ambiente de Produção: faça o cadastro pelo site. Depois de aprovado, acesse o sistema com o seu login (CPF ou CNPJ) e gere a chave de API conforme a seção 3. Conclua e valide toda a integração no Ambiente de Teste antes de enviar dados para produção.
3. Chave de API e conexão
A autenticação usa o seu login (o mesmo usado no navegador: CPF ou CNPJ, com pontuação) e uma Chave de API no lugar da senha. Para criar a chave, entre no sistema pelo navegador e acesse o menu Perfil > Preferências:
Abra a aba Segurança da Conta:
Clique em Nova Chave de API e copie a chave gerada (ela só é exibida uma vez):
Você pode criar várias chaves e revogá-las a qualquer momento, sem expor a sua senha. A chave tem as mesmas permissões do seu usuário.
Cliente da API (copie e use em todos os exemplos)
Escolha a linguagem. O código abaixo autentica e cria uma função call, usada em todos os
exemplos desta página. Os parâmetros já estão preenchidos com os dados deste site:
A biblioteca xmlrpc já vem com o Python; não é preciso instalar nada.
import xmlrpc.client
URL = 'https://aguabranca.joinfiscal.com.br'
BANCO = 'branca'
USUARIO = '00.000.000/0001-00' # seu login: CPF ou CNPJ, com pontuação
CHAVE = 'cole aqui a sua chave de API'
common = xmlrpc.client.ServerProxy(f'{URL}/xmlrpc/2/common')
models = xmlrpc.client.ServerProxy(f'{URL}/xmlrpc/2/object', allow_none=True)
uid = common.authenticate(BANCO, USUARIO, CHAVE, {})
if not uid:
raise Exception('Falha na autenticação: confira URL, BANCO, USUARIO e CHAVE.')
def call(model, method, *args, **kwargs):
"""Executa um método no servidor. Ex.: call('prefeitura.nota_fiscal', 'search_read', [], fields=['name'])"""
try:
return models.execute_kw(BANCO, uid, CHAVE, model, method, list(args), kwargs)
except xmlrpc.client.Fault as e:
# A última linha da mensagem contém o motivo do erro (ex.: validação da nota).
motivo = e.faultString.strip().splitlines()[-1]
raise Exception(f'Erro do servidor: {motivo}') from None
# Teste de conexão: deve imprimir o seu nome.
print(call('res.users', 'read', [uid], fields=['name', 'partner_id']))
Requer Java 9 ou superior e a biblioteca Apache XML-RPC (Maven:
org.apache.xmlrpc:xmlrpc-client:3.1.3).
import org.apache.xmlrpc.XmlRpcException;
import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
import java.net.URL;
import java.util.List;
import java.util.Map;
public class JoinFiscalApi {
static final String URL_BASE = "https://aguabranca.joinfiscal.com.br";
static final String BANCO = "branca";
static final String USUARIO = "00.000.000/0001-00"; // seu login: CPF ou CNPJ, com pontuação
static final String CHAVE = "cole aqui a sua chave de API";
final int uid;
private final XmlRpcClient models = new XmlRpcClient();
public JoinFiscalApi() throws Exception {
XmlRpcClientConfigImpl commonConfig = new XmlRpcClientConfigImpl();
commonConfig.setServerURL(new URL(URL_BASE + "/xmlrpc/2/common"));
XmlRpcClient common = new XmlRpcClient();
common.setConfig(commonConfig);
Object resultado = common.execute("authenticate", List.of(BANCO, USUARIO, CHAVE, Map.of()));
if (!(resultado instanceof Integer)) {
throw new Exception("Falha na autenticação: confira URL, BANCO, USUARIO e CHAVE.");
}
uid = (Integer) resultado;
XmlRpcClientConfigImpl objectConfig = new XmlRpcClientConfigImpl();
objectConfig.setServerURL(new URL(URL_BASE + "/xmlrpc/2/object"));
models.setConfig(objectConfig);
}
/** Executa um método no servidor. Ex.: call("prefeitura.nota_fiscal", "search_read", List.of(List.of()), Map.of("fields", List.of("name"))) */
public Object call(String model, String method, List> args, Map kwargs) throws Exception {
try {
return models.execute("execute_kw", List.of(BANCO, uid, CHAVE, model, method, args, kwargs));
} catch (XmlRpcException e) {
// A última linha da mensagem contém o motivo do erro (ex.: validação da nota).
String[] linhas = e.getMessage().trim().split("\n");
throw new Exception("Erro do servidor: " + linhas[linhas.length - 1], e);
}
}
public Object call(String model, String method, List> args) throws Exception {
return call(model, method, args, Map.of());
}
public static void main(String[] argumentos) throws Exception {
JoinFiscalApi api = new JoinFiscalApi();
// Teste de conexão: deve imprimir o seu nome.
Object[] usuarios = (Object[]) api.call("res.users", "read",
List.of(List.of(api.uid)), Map.of("fields", List.of("name", "partner_id")));
System.out.println(usuarios[0]);
}
}
Requer a biblioteca phpxmlrpc (Composer: composer require phpxmlrpc/phpxmlrpc:^4.10).
send(new Request('authenticate', [
new Value(BANCO), new Value(USUARIO), new Value(CHAVE), new Value([], 'struct'),
]));
$uid = $resposta->faultCode() ? false : (new Encoder())->decode($resposta->value());
if (!$uid) {
throw new Exception('Falha na autenticação: confira URL, BANCO, USUARIO e CHAVE.');
}
/**
* Executa um método no servidor. Ex.: call('prefeitura.nota_fiscal', 'search_read', [[]], ['fields' => ['name']])
*/
function call(string $model, string $method, array $args, array $kwargs = [])
{
global $uid;
$encoder = new Encoder();
$models = new Client(URL . '/xmlrpc/2/object');
$resposta = $models->send(new Request('execute_kw', [
new Value(BANCO), new Value($uid, 'int'), new Value(CHAVE),
new Value($model), new Value($method),
$encoder->encode($args),
$kwargs ? $encoder->encode($kwargs) : new Value([], 'struct'),
]));
if ($resposta->faultCode()) {
// A última linha da mensagem contém o motivo do erro (ex.: validação da nota).
$linhas = explode("\n", trim($resposta->faultString()));
throw new Exception('Erro do servidor: ' . end($linhas));
}
return $encoder->decode($resposta->value());
}
// Teste de conexão: deve imprimir o seu nome.
print_r(call('res.users', 'read', [[$uid]], ['fields' => ['name', 'partner_id']]));
Se authenticate retornar False, um dos quatro parâmetros está errado.
Os mais comuns: banco de dados com nome errado, login sem a pontuação do CPF/CNPJ, ou uso da
chave de um ambiente no outro. Qualquer outra linguagem com uma biblioteca XML-RPC também funciona,
seguindo o mesmo modelo.
Como ler os exemplos
Os exemplos das próximas seções estão em Python, mas as chamadas são as mesmas em qualquer linguagem: mudam apenas a sintaxe das listas e dos dicionários. Em Python, os argumentos vão em sequência e as opções como parâmetros nomeados. Em Java e PHP, os argumentos vão em uma lista e as opções em um mapa:
| Python | Java | PHP | |
|---|---|---|---|
| Lista | [1, 2] ou (1, 2) |
List.of(1, 2) |
[1, 2] |
| Dicionário | {'name': 'X'} |
Map.of("name", "X") |
['name' => 'X'] |
| Verdadeiro / falso | True / False |
true / false |
true / false |
| Chamada | call('res.users', 'read', [uid], fields=['name']) |
api.call("res.users", "read", List.of(List.of(uid)), Map.of("fields", List.of("name"))) |
call('res.users', 'read', [[$uid]], ['fields' => ['name']]) |
Valores nulos não são aceitos: em vez de enviar None/null, não envie o campo.
Na leitura, campos vazios retornam False.
search_read: busca e lê registros. Recebe um filtro, que é uma lista de condições[campo, operador, valor](ex.:[['state', '=', 'CONCLUIDO']]).read: lê registros pelos seusid.create: cria um registro e retorna oid.write: altera registros.- Campos de relação (
..._id) recebem oiddo registro relacionado e, na leitura, retornam[id, 'nome'].
4. Pré-requisitos do prestador
A maior parte dos erros de emissão vem do cadastro do prestador, e não da integração. Confira antes de emitir:
- Cadastro do prestador aprovado pela prefeitura e localizado neste município.
- Endereço completo (rua, número, bairro, CEP e cidade).
- Pelo menos um serviço (código de tributação nacional) e um serviço NBS cadastrados. A nota só aceita serviços que estejam no cadastro do prestador.
- O prestador não pode ser MEI. O MEI emite pelo Emissor Nacional (www.nfse.gov.br).
- Desde 1º de novembro de 2026, optantes pelo Simples Nacional (ME e EPP) emitem somente pelo Emissor Nacional (Resolução CGSN nº 189/2026).
Leia o cadastro do prestador para descobrir os id dos serviços que vai usar na nota:
usuario = call('res.users', 'read', [uid], fields=['partner_id'])[0]
prestador_id = usuario['partner_id'][0]
prestador = call('res.partner', 'read', [prestador_id], fields=[
'name', 'l10n_br_cnpj_cpf', 'foi_aprovado', 'e_simples',
'servico_ids', 'servico_nbs_ids', 'cnae_ids',
])[0]
servicos = call('prefeitura.servico', 'read', prestador['servico_ids'],
fields=['name', 'codigo_issqn', 'local_incidencia_iss'])
servicos_nbs = call('prefeitura.servico', 'read', prestador['servico_nbs_ids'],
fields=['name', 'codigo_nbs'])
print(prestador)
print('Serviços:', servicos)
print('Serviços NBS:', servicos_nbs)
Exemplo de resultado:
{'id': 378, 'name': 'EMPRESA EXEMPLO LTDA', 'l10n_br_cnpj_cpf': '12.345.678/0001-90',
'foi_aprovado': True, 'e_simples': False, 'servico_ids': [55], 'servico_nbs_ids': [912], 'cnae_ids': [301]}
Serviços: [{'id': 55, 'name': 'Desenvolvimento de programas de computador sob encomenda',
'codigo_issqn': '010201', 'local_incidencia_iss': 'PRESTADOR'}]
Serviços NBS: [{'id': 912, 'name': 'Serviços de desenvolvimento de software', 'codigo_nbs': '1.1502.10.00'}]
Usuário que representa mais de um prestador (ex.: contador ou pessoa física sócia de empresa):
o sistema escolhe um prestador padrão. Para escolher qual prestador emite a nota, envie
prestador_id ao criar a nota. Para descobrir o id, busque pelo CNPJ:
call('res.partner', 'search', [['l10n_br_cnpj_cpf', '=', '12.345.678/0001-90']]).
5. Emitir nota fiscal (passo a passo)
A emissão acontece em duas etapas: você cria a nota (ela fica em RASCUNHO
e pode ser alterada) e depois emite. As validações completas só rodam na emissão, então
um rascunho incompleto é aceito na criação e recusado na emissão.
5.1. Tomador
O tomador é um cadastro seu (cada usuário tem a sua lista de tomadores). Busque pelo CPF/CNPJ com pontuação e, se não existir, cadastre. O endereço do tomador precisa estar completo para a nota ser emitida.
cpf_cnpj_tomador = '98.765.432/0001-10' # sempre com pontuação
tomador_ids = call('prefeitura.tomador', 'search', [['cpf_cnpj', '=', cpf_cnpj_tomador]], limit=1)
if tomador_ids:
tomador_id = tomador_ids[0]
else:
cidade_tomador_id = call('res.city', 'search', [['l10n_br_ibge_code', '=', '2211001']], limit=1)[0]
tomador_id = call('prefeitura.tomador', 'create', {
'name': 'CLIENTE EXEMPLO LTDA',
'cpf_cnpj': cpf_cnpj_tomador,
'email': 'financeiro@cliente.com.br',
'cep': '64000-000', # com hífen
'rua': 'Rua Exemplo',
'numero': '100',
'bairro': 'Centro',
'cidade_id': cidade_tomador_id,
})
5.2. Local da prestação do serviço
O campo city_id é o id da cidade onde o serviço foi prestado. Se não for
informado, o sistema usa a cidade da prefeitura. Busque a cidade pelo código IBGE (7 dígitos),
que é mais seguro do que buscar pelo nome:
city_id = call('res.city', 'search', [['l10n_br_ibge_code', '=', '2211001']], limit=1)[0] # Teresina - PI
5.3. Criar a nota (rascunho)
Envie tudo em uma única chamada. Os itens são criados junto com a nota usando o formato
(0, 0, {...}), e o serviço usa (6, 0, [id]) (veja o
formato das relações).
from datetime import date
nota_id = call('prefeitura.nota_fiscal', 'create', {
'tomador_id': tomador_id,
'city_id': city_id,
'competencia': date.today().isoformat(), # 'AAAA-MM-DD'
'servico_ids': [(6, 0, [55])], # exatamente 1 serviço do cadastro do prestador
'servico_nbs_id': 912, # serviço NBS do cadastro do prestador (IBS/CBS)
'description': 'Desenvolvimento do módulo financeiro, conforme contrato 12/2026.',
'item_ids': [
(0, 0, {'name': 'Desenvolvimento de software', 'quantity': 1, 'price': 5000.00}),
(0, 0, {'name': 'Consultoria técnica (horas)', 'quantity': 10, 'price': 150.00}),
],
# Opcional: alíquotas (%) de IBS e CBS. Se omitidas, o sistema usa as alíquotas padrão.
# 'aliquota_cbs': 0.9,
# 'aliquota_ibs': 0.05, # IBS municipal
# 'aliquota_ibs_estadual': 0.05, # IBS estadual
})
print(nota_id) # ex.: 11790
Campos usados na emissão:
| Campo | Obrigatório | O que enviar |
|---|---|---|
tomador_id |
Sim | id do tomador (5.1). Endereço do tomador precisa estar completo. |
competencia |
Sim | Data 'AAAA-MM-DD'. Mês corrente, ou até 30 dias retroativos. Não pode ser futura. |
servico_ids |
Sim | [(6, 0, [id])] com exatamente 1 serviço do cadastro do prestador. Se o prestador tiver um só serviço, ele já vem preenchido. |
servico_nbs_id |
Sim | id de um serviço NBS do cadastro do prestador. É a partir dele que o IBS e a CBS são identificados (seção 6). |
description |
Sim | Descrição dos serviços prestados. Máximo de 2000 caracteres. Não pode ficar vazia. |
item_ids |
Sim | Pelo menos 1 item, cada um com name (descrição), quantity e price (valor unitário). A soma dos itens é a base de cálculo. |
aliquota_cbs, aliquota_ibs, aliquota_ibs_estadual |
Padrão | Alíquotas (%) da CBS, do IBS municipal e do IBS estadual. Se não forem enviadas, o sistema usa as alíquotas padrão. Os valores são calculados a partir delas (seção 6). |
city_id |
Padrão | id da cidade da prestação. Padrão: cidade da prefeitura. |
prestador_id |
Padrão | Preenchido a partir do usuário. Só envie se o usuário representar mais de um prestador. |
cnae_ids |
Padrão | Preenchido a partir do cadastro do prestador. |
tipo_recolhimento |
Calculado | Não envie. Calculado pelo sistema (ISS_A_RECOLHER, ISS_RETIDO ou SEM_INCIDENCIA). Em alguns serviços o prestador pode escolher; nesses casos, envie um desses valores. |
| Campos de obra, Simples Nacional e deduções | Depende | Veja situações especiais. |
Formato das relações. Campos que são listas de registros (item_ids,
servico_ids) recebem uma lista de comandos:
| Comando | Efeito |
|---|---|
(0, 0, {valores}) | Cria um novo registro (ex.: um item da nota). |
(1, id, {valores}) | Altera o registro id (ex.: corrigir o preço de um item). |
(2, id, 0) | Remove e apaga o registro id (ex.: excluir um item). |
(6, 0, [ids]) | Substitui a lista inteira pelos ids informados (ex.: escolher o serviço). |
Enquanto estiver em RASCUNHO, a nota pode ser corrigida com write:
call('prefeitura.nota_fiscal', 'write', [nota_id], {
'description': 'Texto corrigido.',
'item_ids': [(0, 0, {'name': 'Item adicional', 'quantity': 1, 'price': 200.00})],
})
5.4. Conferir os valores calculados
Antes de emitir, leia a nota para conferir os valores que o sistema calculou:
nota = call('prefeitura.nota_fiscal', 'read', [nota_id], fields=[
'state', 'item_total', 'base_calculo', 'tipo_recolhimento', 'local_incidencia_iss',
'aliquota_iss', 'valor_iss',
'aliquota_cbs', 'valor_cbs',
'aliquota_ibs', 'valor_ibs', 'aliquota_ibs_estadual', 'valor_ibs_estadual', 'valor_ibs_total',
'valor_com_deducoes',
])[0]
print(nota)
{'id': 11790, 'state': 'RASCUNHO', 'item_total': 6500.0, 'base_calculo': 6500.0,
'tipo_recolhimento': 'ISS_A_RECOLHER', 'local_incidencia_iss': 'PRESTADOR',
'aliquota_iss': 5.0, 'valor_iss': 325.0,
'aliquota_cbs': 0.9, 'valor_cbs': 55.58,
'aliquota_ibs': 0.05, 'valor_ibs': 3.09, 'aliquota_ibs_estadual': 0.05, 'valor_ibs_estadual': 3.09,
'valor_ibs_total': 6.18, 'valor_com_deducoes': 6500.0}
5.5. Emitir
call('prefeitura.nota_fiscal', 'action_emitir', [nota_id])
nota = call('prefeitura.nota_fiscal', 'read', [nota_id], fields=[
'name', 'state', 'emissao', 'valor_iss', 'boleto_id', 'nfse_chave_acesso',
])[0]
print(nota)
{'id': 11790, 'name': 'NF-2026-378-00012', 'state': 'TARIFACAO', 'emissao': '2026-11-09 14:03:11',
'valor_iss': 325.0, 'boleto_id': [1532, 'Guia 1532'], 'nfse_chave_acesso': False}
Se alguma validação falhar, a chamada retorna um erro com o motivo (veja erros comuns)
e a nota continua em RASCUNHO: corrija e emita de novo. Depois da emissão, a nota
pode estar em um destes estados:
Estado (state) |
Significado |
|---|---|
RASCUNHO | Criada, ainda não emitida. Pode ser alterada. |
APROVACAO | A nota tem deduções declaradas e aguarda aprovação da prefeitura antes de ser emitida. |
TARIFACAO | Emitida, aguardando o pagamento da guia de ISS (boleto_id). Exibido como "Pagamento". |
CONCLUIDO | Emitida e concluída (guia paga ou sem ISS a pagar). Exibido como "Emitida". |
CANCELADA | Cancelada. |
5.6. Obter o PDF e o XML
O PDF e o XML da nota são campos da própria nota, retornados em Base64. Leia-os pela API e salve em arquivo:
import base64
nota = call('prefeitura.nota_fiscal', 'read', [nota_id], fields=[
'nome_arquivo_pdf', 'arquivo_pdf', 'nome_arquivo_xml', 'arquivo_xml',
])[0]
if nota['arquivo_pdf']:
with open(nota['nome_arquivo_pdf'], 'wb') as f:
f.write(base64.b64decode(nota['arquivo_pdf']))
if nota['arquivo_xml']:
with open(nota['nome_arquivo_xml'], 'wb') as f:
f.write(base64.b64decode(nota['arquivo_xml']))
Enquanto a guia de ISS não for paga (estado TARIFACAO), o PDF pode ser gerado como
rascunho; leia o arquivo novamente depois do pagamento. Os métodos action_baixar_*
retornam um link para download no navegador e exigem login pelo navegador, por isso não são
indicados para integração.
6. IBS e CBS (Reforma Tributária)
servico_nbs_id (obrigatório). As alíquotas e os valores de IBS e
CBS são preenchidos automaticamente, mas você pode informar alíquotas próprias. Os valores são
sempre calculados a partir das alíquotas.
Campos que você pode enviar:
| Campo | Obrigatório | Descrição |
|---|---|---|
servico_nbs_id |
Sim | id de um serviço com código NBS (Nomenclatura Brasileira de Serviços) que esteja no
cadastro do prestador (servico_nbs_ids, veja a seção 4).
Se o código NBS não estiver no cadastro, o prestador deve incluí-lo antes de emitir. |
aliquota_cbs |
Não | Alíquota da CBS (federal), em %. Padrão: alíquota vigente. |
aliquota_ibs |
Não | Alíquota do IBS municipal, em %. Padrão: alíquota vigente. |
aliquota_ibs_estadual |
Não | Alíquota do IBS estadual, em %. Padrão: alíquota vigente. |
As alíquotas podem ser enviadas na criação da nota ou alteradas com write enquanto ela
estiver em RASCUNHO. Depois da emissão, não podem mais ser alteradas. A alíquota não pode ser
negativa. Quando a alíquota enviada é diferente da padrão, o campo de log correspondente passa a indicar
"Usuário definiu alíquota manualmente".
call('prefeitura.nota_fiscal', 'write', [nota_id], {
'aliquota_cbs': 0.8,
'aliquota_ibs': 0.05,
'aliquota_ibs_estadual': 0.05,
})
nota = call('prefeitura.nota_fiscal', 'read', [nota_id], fields=[
'aliquota_cbs', 'valor_cbs', 'cbs_log',
'aliquota_ibs', 'valor_ibs', 'aliquota_ibs_estadual', 'valor_ibs_estadual', 'valor_ibs_total',
])[0]
print(nota)
{'id': 11790, 'aliquota_cbs': 0.8, 'valor_cbs': 49.4, 'cbs_log': 'Usuário definiu alíquota manualmente.',
'aliquota_ibs': 0.05, 'valor_ibs': 3.09, 'aliquota_ibs_estadual': 0.05, 'valor_ibs_estadual': 3.09,
'valor_ibs_total': 6.18}
Campos calculados (somente leitura):
| Campo | Descrição |
|---|---|
valor_cbs | Valor da CBS: base de cálculo do IBS/CBS × aliquota_cbs. |
valor_ibs | Valor do IBS municipal: base × aliquota_ibs. |
valor_ibs_estadual | Valor do IBS estadual: base × aliquota_ibs_estadual. |
aliquota_ibs_total / valor_ibs_total | Soma do IBS municipal e estadual. |
cbs_log, ibs_log, ibs_estadual_log | Texto explicando como a alíquota foi definida. |
Para alterar um valor de IBS ou CBS, altere a alíquota correspondente. Os campos valor_*
não aceitam valor informado diretamente.
Regras de cálculo em 2026 (ano de transição):
- Alíquotas padrão: CBS 0,9%, IBS municipal 0,05% e IBS estadual 0,05%.
- Base de cálculo do IBS/CBS: base de cálculo da nota menos PIS, COFINS e ISS. Para optantes pelo Simples Nacional, é a própria base de cálculo da nota.
- Em 2026, os valores de IBS e CBS são destacados na nota, mas não entram na guia de pagamento (a guia continua cobrando o ISS).
As alíquotas padrão mudam ao longo da transição. Se você não informa alíquotas próprias, não grave esses números no seu sistema: leia os valores da nota (exemplo na seção 5.4).
7. Situações especiais
Alguns campos só são exigidos em situações específicas. Para saber se a nota exige esses campos,
leia os indicadores no rascunho (e_obra, regime_apuracao_simples_e_requerido,
permite_deducao).
Serviços de obra (construção civil)
Quando o serviço é de obra, e_obra retorna True e a obra precisa ser identificada:
tipo_identificacao_obra |
Campos obrigatórios |
|---|---|
CNO ou CEI | codigo_identificacao_obra |
CIB | codigo_identificacao_obra (8 caracteres) |
ENDERECO_NACIONAL | logradouro_obra, numero_obra, bairro_obra, cep_obra |
call('prefeitura.nota_fiscal', 'write', [nota_id], {
'tipo_identificacao_obra': 'CNO',
'codigo_identificacao_obra': '900012345678',
})
Regime de apuração do Simples Nacional
Para prestadores ME/EPP do Simples Nacional, quando regime_apuracao_simples_e_requerido for
True, envie regime_apuracao_simples com um dos valores:
FEDERAL_SN_MUNICIPAL_SN, FEDERAL_SN_MUNICIPAL_NF ou
FEDERAL_NF_MUNICIPAL_NF. Lembre-se de que, desde 1º de novembro de 2026, esses prestadores
emitem pelo Emissor Nacional (veja a seção 4).
Deduções da base de cálculo
Alguns serviços permitem deduções (permite_deducao = True). Uma nota com
deduções declaradas para serviço prestado no município vai para o estado APROVACAO e
só é emitida depois que a prefeitura aprova as deduções. Se a sua integração precisar de deduções,
abra um chamado para receber orientação específica.
Tomador órgão público
Quando o tomador é órgão público deste município, o sistema define o recolhimento como
ISS_RETIDO automaticamente. Não é preciso enviar nada diferente.
8. Consultar notas fiscais
Use search_read com um filtro, os campos que deseja e, opcionalmente, ordenação e paginação
(order, limit, offset). A consulta retorna apenas as notas que
o seu usuário pode ver.
# Notas emitidas em novembro de 2026, mais recentes primeiro, 50 por página
notas = call('prefeitura.nota_fiscal', 'search_read',
[
['state', 'in', ['TARIFACAO', 'CONCLUIDO']],
['emissao', '>=', '2026-11-01 00:00:00'],
['emissao', '<', '2026-12-01 00:00:00'],
],
fields=['name', 'state', 'emissao', 'tomador_id', 'base_calculo', 'valor_iss', 'valor_cbs', 'valor_ibs_total'],
order='emissao DESC',
limit=50,
offset=0, # próxima página: offset=50, depois 100...
)
for nota in notas:
print(nota)
{'id': 11790, 'name': 'NF-2026-378-00012', 'state': 'TARIFACAO', 'emissao': '2026-11-09 14:03:11',
'tomador_id': [2011, 'CLIENTE EXEMPLO LTDA'], 'base_calculo': 6500.0, 'valor_iss': 325.0,
'valor_cbs': 55.58, 'valor_ibs_total': 6.18}
...
Outros filtros úteis:
| Filtro | Encontra |
|---|---|
[['name', '=', 'NF-2026-378-00012']] | Nota pelo número. |
[['tomador_id.cpf_cnpj', '=', '98.765.432/0001-10']] | Notas de um tomador. |
[['state', '=', 'CANCELADA']] | Notas canceladas (use o campo data_hora_cancelamento). |
[['nfse_chave_acesso', '=', '...']] | Nota pela chave de acesso da NFS-e nacional. |
[['competencia', '>=', '2026-11-01'], ['competencia', '<=', '2026-11-30']] | Notas por competência. |
Para apenas contar os registros, use search_count:
call('prefeitura.nota_fiscal', 'search_count', [['state', '=', 'CANCELADA']]).
Para listar todos os campos de um model com tipo e descrição, use
call('prefeitura.nota_fiscal', 'fields_get', attributes=['string', 'type', 'help']).
9. Cancelar nota fiscal
Regras:
- A nota deve estar em
TARIFACAOouCONCLUIDO. - O motivo do cancelamento é obrigatório.
- O prestador pode cancelar até 30 dias após a competência. Depois disso, o cancelamento deve ser solicitado à prefeitura por protocolo.
- A guia de ISS em aberto da nota é cancelada junto.
- Uma nota em
RASCUNHOnão precisa ser cancelada: basta não emiti-la.
O cancelamento é feito em duas chamadas: cria-se o pedido de cancelamento com o motivo e depois ele é confirmado.
dialogo_id = call('prefeitura.nota_fiscal_dialogo', 'create', {
'nota_fiscal_id': nota_id,
'motivo_cancelamento': 'Valor do serviço informado incorretamente.',
})
call('prefeitura.nota_fiscal_dialogo', 'confirmar_cancelamento', [dialogo_id])
nota = call('prefeitura.nota_fiscal', 'read', [nota_id], fields=['state', 'data_hora_cancelamento'])[0]
print(nota) # {'id': 11790, 'state': 'CANCELADA', 'data_hora_cancelamento': '2026-11-09 15:20:44'}
10. Guias de pagamento
Quando a nota gera ISS a pagar, a emissão cria uma guia. Ela pode ser lida pela própria nota:
import base64
nota = call('prefeitura.nota_fiscal', 'read', [nota_id],
fields=['boleto_id', 'boleto_state', 'boleto_total', 'boleto_nome_pdf', 'boleto_conteudo_pdf'])[0]
if nota['boleto_conteudo_pdf']:
with open(nota['boleto_nome_pdf'], 'wb') as f:
f.write(base64.b64decode(nota['boleto_conteudo_pdf']))
boleto_state pode ser RASCUNHO, ABERTO (emitida),
VENCIDO, PAGO ou CANCELADO.
Uma guia para várias faturas
Também é possível juntar várias faturas em aberto do mesmo contribuinte em uma única guia. Primeiro, liste as faturas em aberto:
faturas = call('account.move', 'search_read',
[['state', '=', 'posted'], ['payment_state', '=', 'not_paid']],
fields=['name', 'partner_id', 'amount_total', 'invoice_date_due'],
)
Crie a guia com as faturas escolhidas, emita e leia o PDF:
import base64
boleto_id = call('prefeitura.boleto', 'create', {
'contribuinte_id': 378, # partner_id das faturas (todas devem ser do mesmo contribuinte)
'move_ids': [(6, 0, [356, 341, 134])], # ids das faturas
})
call('prefeitura.boleto', 'action_emitir', [boleto_id])
boleto = call('prefeitura.boleto', 'read', [boleto_id], fields=['state', 'nome_pdf', 'conteudo_pdf'])[0]
with open(boleto['nome_pdf'], 'wb') as f:
f.write(base64.b64decode(boleto['conteudo_pdf']))
11. Erros comuns
Os erros de validação chegam como uma falha XML-RPC (em Python, xmlrpc.client.Fault). O motivo fica na
última linha da mensagem de erro (o cliente da seção 3 já faz isso).
| Mensagem (resumida) | O que fazer |
|---|---|
authenticate retorna False |
Confira URL, banco de dados, login (com pontuação) e chave. A chave de um ambiente não funciona no outro. |
| Para emitir nota é obrigatório selecionar um serviço do IBS. | Envie servico_nbs_id (seção 6). |
| Serviço NBS (...) não está definido no seu cadastro do prestador. | Use um dos servico_nbs_ids do prestador, ou peça a inclusão do código NBS no cadastro do prestador. |
| Alíquota do CBS / IBS / IBS Estadual não pode ser negativa! | Envie alíquotas maiores ou iguais a zero, em % (ex.: 0.9 para 0,9%). |
| Selecione apenas um serviço. | Envie exatamente 1 serviço em servico_ids: [(6, 0, [id])]. |
| Prestador não possui serviços associados. | O cadastro do prestador não tem serviços. Atualize o cadastro. |
| É obrigatório informar os itens antes de emitir... | Envie ao menos 1 item em item_ids. |
| Texto da Descrição está vazio. | Envie description (máximo de 2000 caracteres). |
| ... com data não permitida. | competencia deve estar no mês corrente ou até 30 dias retroativos. |
| Data de Competência não pode ser posterior a Data de Emissão. | Não use competência futura. |
| Endereço do Prestador está incompleto! / Endereço do Tomador está incompleto! | Complete rua, número, bairro, CEP e cidade do cadastro indicado. |
| Prestador ainda não aprovado... | Aguarde a aprovação do cadastro pela prefeitura. |
| Prestador não pode emitir nota fiscal, pois está enquadrado como MEI. | O MEI emite pelo Emissor Nacional (www.nfse.gov.br). |
| Prestadores optantes do Simples Nacional devem fazer emissão... | Desde 01/11/2026, ME/EPP do Simples Nacional emitem pelo Emissor Nacional. |
| CPF/CNPJ inválido (tomador) | Envie o CPF/CNPJ com pontuação: 000.000.000-00 ou 00.000.000/0000-00. |
| A nota fiscal não pode ser alterada após emissão. | Notas emitidas não podem ser alteradas. Cancele e emita outra, se ainda estiver no prazo. |
| Não é possível cancelar notas após 30 dias da emissão. | Solicite o cancelamento à prefeitura por protocolo. |
| Access Denied / AccessError | Seu usuário não tem permissão para a operação ou para o registro. Confira se está usando o usuário do prestador correto. |
Para um erro que não esteja nesta tabela, abra um chamado pela página de contato
informando o ambiente (Teste ou Produção), o login utilizado, o id ou número da nota, a
chamada feita (model, método e valores enviados) e a mensagem de erro completa.
12. Referência de campos
Nota fiscal (prefeitura.nota_fiscal): campos de leitura
| Campo | Descrição |
|---|---|
name | Número da nota (preenchido na emissão). |
state | Estado (tabela na seção 5.5). |
emissao | Data e hora da emissão (UTC), 'AAAA-MM-DD HH:MM:SS'. |
item_total | Soma dos itens. |
base_calculo | Base de cálculo dos impostos. |
valor_com_deducoes | Valor líquido. |
tipo_recolhimento | ISS_A_RECOLHER, ISS_RETIDO ou SEM_INCIDENCIA. |
local_incidencia_iss | PRESTADOR, TOMADOR ou SERVICO. |
aliquota_iss, valor_iss | ISS. |
aliquota_cbs, valor_cbs | CBS (seção 6). |
aliquota_ibs, valor_ibs | IBS municipal. |
aliquota_ibs_estadual, valor_ibs_estadual | IBS estadual. |
aliquota_ibs_total, valor_ibs_total | IBS total. |
valor_inss, valor_ir, valor_pis, valor_cofins, valor_csll | Retenções federais, quando houver. |
arquivo_pdf, nome_arquivo_pdf | PDF da nota (Base64) e nome do arquivo. |
arquivo_xml, nome_arquivo_xml | XML da nota (Base64) e nome do arquivo. |
boleto_id, boleto_state, boleto_total, boleto_conteudo_pdf | Guia de ISS da nota. |
nfse_chave_acesso | Chave de acesso da NFS-e no Sistema Nacional, quando houver. |
motivo_cancelamento, data_hora_cancelamento | Dados do cancelamento. |
Item da nota (prefeitura.item_nota_fiscal)
| Campo | Descrição |
|---|---|
name | Descrição do item. |
quantity | Quantidade (padrão: 1). |
price | Valor unitário. |
total | Calculado: quantidade × valor unitário. |
Tomador (prefeitura.tomador)
| Campo | Descrição |
|---|---|
name | Nome ou razão social. |
cpf_cnpj | CPF ou CNPJ com pontuação. Obrigatório. |
email, phone | Contato. |
cep, rua, numero, bairro, complemento, cidade_id | Endereço. Exceto o complemento, todos são exigidos para emitir. |
inscricao_municipal | Inscrição municipal, se houver. |
- PREFEITURA MUNICIPAL DE ÁGUA BRANCA - PI
- Av. João Ferreira, nº 555
- Água Branca - PI 64460-000
- (86) 9 9806-7507
- suporte@jointecdesenvolvimento.com.br
- Ver localização no Google Maps