Acesso Externo via API (Web Service)

Guia prático para emitir, consultar e cancelar notas fiscais a partir do seu sistema.

Índice

  1. Comece aqui (resumo)
  2. Obter acesso: Ambiente de Teste e Produção
  3. Chave de API e conexão
  4. Pré-requisitos do prestador
  5. Emitir nota fiscal (passo a passo)
  6. IBS e CBS (Reforma Tributária)
  7. Situações especiais
  8. Consultar notas fiscais
  9. Cancelar nota fiscal
  10. Guias de pagamento
  11. Erros comuns
  12. 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 é:

  1. Obter um usuário no ambiente (no Ambiente de Teste, isso é feito pelo suporte, veja a seção 2).
  2. Gerar uma Chave de API no seu perfil e autenticar.
  3. Buscar (ou cadastrar) o tomador pelo CPF/CNPJ.
  4. Criar a nota em RASCUNHO com itens, serviço, serviço NBS e descrição, em uma única chamada.
  5. Conferir os valores calculados pelo sistema (ISS, IBS, CBS etc.).
  6. Emitir (action_emitir).
  7. 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 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:

Menu Perfil, Preferências

Abra a aba Segurança da Conta:

Aba Segurança da Conta

Clique em Nova Chave de API e copie a chave gerada (ela só é exibida uma vez):

Botão Nova Chave de API

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.

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
RASCUNHOCriada, ainda não emitida. Pode ser alterada.
APROVACAOA nota tem deduções declaradas e aguarda aprovação da prefeitura antes de ser emitida.
TARIFACAOEmitida, aguardando o pagamento da guia de ISS (boleto_id). Exibido como "Pagamento".
CONCLUIDOEmitida e concluída (guia paga ou sem ISS a pagar). Exibido como "Emitida".
CANCELADACancelada.

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)

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_cbsValor da CBS: base de cálculo do IBS/CBS × aliquota_cbs.
valor_ibsValor do IBS municipal: base × aliquota_ibs.
valor_ibs_estadualValor do IBS estadual: base × aliquota_ibs_estadual.
aliquota_ibs_total / valor_ibs_totalSoma do IBS municipal e estadual.
cbs_log, ibs_log, ibs_estadual_logTexto 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 CEIcodigo_identificacao_obra
CIBcodigo_identificacao_obra (8 caracteres)
ENDERECO_NACIONALlogradouro_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 TARIFACAO ou CONCLUIDO.
  • 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 RASCUNHO nã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
nameNúmero da nota (preenchido na emissão).
stateEstado (tabela na seção 5.5).
emissaoData e hora da emissão (UTC), 'AAAA-MM-DD HH:MM:SS'.
item_totalSoma dos itens.
base_calculoBase de cálculo dos impostos.
valor_com_deducoesValor líquido.
tipo_recolhimentoISS_A_RECOLHER, ISS_RETIDO ou SEM_INCIDENCIA.
local_incidencia_issPRESTADOR, TOMADOR ou SERVICO.
aliquota_iss, valor_issISS.
aliquota_cbs, valor_cbsCBS (seção 6).
aliquota_ibs, valor_ibsIBS municipal.
aliquota_ibs_estadual, valor_ibs_estadualIBS estadual.
aliquota_ibs_total, valor_ibs_totalIBS total.
valor_inss, valor_ir, valor_pis, valor_cofins, valor_csllRetenções federais, quando houver.
arquivo_pdf, nome_arquivo_pdfPDF da nota (Base64) e nome do arquivo.
arquivo_xml, nome_arquivo_xmlXML da nota (Base64) e nome do arquivo.
boleto_id, boleto_state, boleto_total, boleto_conteudo_pdfGuia de ISS da nota.
nfse_chave_acessoChave de acesso da NFS-e no Sistema Nacional, quando houver.
motivo_cancelamento, data_hora_cancelamentoDados do cancelamento.

Item da nota (prefeitura.item_nota_fiscal)

CampoDescrição
nameDescrição do item.
quantityQuantidade (padrão: 1).
priceValor unitário.
totalCalculado: quantidade × valor unitário.

Tomador (prefeitura.tomador)

CampoDescrição
nameNome ou razão social.
cpf_cnpjCPF ou CNPJ com pontuação. Obrigatório.
email, phoneContato.
cep, rua, numero, bairro, complemento, cidade_idEndereço. Exceto o complemento, todos são exigidos para emitir.
inscricao_municipalInscriçã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