Pular para o conteúdo principal
Recursos para IAAbra o contexto completo da documentação em Markdown para ChatGPT, Claude, Cursor, Copilot e outros agentes.
Abrir contexto completo para LLMs

SDK para Python

Comece a usar rapidamente a ACBr API com o nosso SDK para Python! O SDK é uma biblioteca open source cujo código-fonte completo está disponível no GitHub:

Requisitos​

Python 2.7 e 3.4+.

As dependências (urllib3, six e python-dateutil) são instaladas automaticamente.

Instalação​

Escolha uma das formas abaixo para adicionar o SDK ao seu projeto.

Via pip direto do GitHub (recomendado)​

Instala o pacote diretamente do repositório. Execute dentro do ambiente virtual (venv) do seu projeto:

pip install "git+https://github.com/projeto-acbr-oficial/acbrapi-sdk-python.git"

Fixando a branch main (ou troque por uma tag/commit quando disponível):

pip install "git+https://github.com/projeto-acbr-oficial/acbrapi-sdk-python.git@main"

No requirements.txt do seu projeto:

acbrapi-sdk @ git+https://github.com/projeto-acbr-oficial/acbrapi-sdk-python.git@main

Em alguns ambientes o pip precisa de permissão de root: use sudo pip install ....

A partir do código-fonte​

Clone o repositório e instale via Setuptools:

python setup.py install --user

(ou sudo python setup.py install para instalar para todos os usuários)

Utilização​

Depois de instalar por qualquer um dos métodos acima, importe o pacote:

import acbrapi_sdk

Obtendo o token de acesso​

O processo de autenticação da ACBr API envolve dois passos:

O primeiro passo deve ser feito no console da ACBr API, enquanto o segundo você deve fazer manualmente. A geração do token não é definida pela ACBr API, mas sim pelo padrão OAuth2. A seguir uma sugestão básica de implementação, usando a biblioteca requests:

import os
import requests

def get_access_token(scope):
    response = requests.post(
        'https://auth.acbr.api.br/realms/ACBrAPI/protocol/openid-connect/token',
        data={
            'grant_type': 'client_credentials',
            'client_id': os.environ['ACBRAPI_CLIENTID'],
            'client_secret': os.environ['ACBRAPI_CLIENTSECRET'],
            'scope': scope,  # defina o scope a ser usado
        },
    )
    response.raise_for_status()
    return response.json()['access_token']

Criando o client​

Com um token de acesso em mãos, crie a Configuration e o ApiClient:

import acbrapi_sdk

# O host é opcional; o padrão é o ambiente de produção https://prod.acbr.api.br
configuration = acbrapi_sdk.Configuration(
    host='https://prod.acbr.api.br'
)
configuration.access_token = get_access_token('cep cnpj')

O prefixo Bearer é adicionado automaticamente pelo SDK — informe apenas o token em access_token.

Para usar o ambiente de homologação, informe host='https://hom.acbr.api.br'. Consulte o configuration.py para a lista completa de parâmetros de configuração suportados (proxy, timeout, verificação de SSL, entre outros).

Executando os métodos​

Todos os endpoints da API estão disponíveis nas classes de API, agrupados de acordo com o serviço: CepApi, CnpjApi, EmpresaApi, NfeApi, NfceApi, NfseApi, CteApi, CteOsApi, MdfeApi, NfcomApi, DceApi, DistribuioNFEApi, EmailApi, ContaApi e DebugApi.

Use o ApiClient como context manager para garantir que as conexões sejam liberadas ao final:

with acbrapi_sdk.ApiClient(configuration) as api_client:
    api_instance = acbrapi_sdk.CepApi(api_client)
    endereco = api_instance.consultar_cep('80030030')
    print(endereco.logradouro, endereco.municipio, endereco.uf)

Guia rápido​

from __future__ import print_function

import acbrapi_sdk
from acbrapi_sdk.rest import ApiException
from pprint import pprint

# Define o host; o padrão é https://prod.acbr.api.br
# Veja configuration.py para a lista de parâmetros de configuração suportados.
configuration = acbrapi_sdk.Configuration(
    host='https://prod.acbr.api.br'
)

# Configura o token de acesso OAuth2 para autorização: oauth2
configuration.access_token = 'YOUR_ACCESS_TOKEN'

# Abre um contexto com uma instância do cliente da API
with acbrapi_sdk.ApiClient(configuration) as api_client:
    # Cria uma instância da classe da API
    api_instance = acbrapi_sdk.CepApi(api_client)
    cep = '80030030'  # str | CEP sem máscara.

    try:
        # Consultar endereço através do CEP
        api_response = api_instance.consultar_cep(cep)
        pprint(api_response)
    except ApiException as e:
        print("Exceção ao chamar CepApi->consultar_cep: %s\n" % e)

Exemplo com tratamento de erros​

import acbrapi_sdk
from acbrapi_sdk.rest import ApiException

configuration = acbrapi_sdk.Configuration()
configuration.access_token = get_access_token('cep cnpj')

with acbrapi_sdk.ApiClient(configuration) as api_client:
    # Consulta de CEP
    cep_api = acbrapi_sdk.CepApi(api_client)
    endereco = cep_api.consultar_cep('80030030')
    print(endereco)

    # Consulta de CNPJ
    cnpj_api = acbrapi_sdk.CnpjApi(api_client)
    try:
        empresa = cnpj_api.consultar_cnpj('08421842000190')
        print(empresa.razao_social)
        print(empresa.endereco.municipio, empresa.endereco.uf)
    except ApiException as e:
        print('Erro ao consultar o CNPJ. Status:', e.status)
        print(e.body)

Referência completa​

O repositório do GitHub contém a lista de todos os endpoints e métodos correspondentes, classes de modelo, parâmetros, e mais — na pasta docs há uma página de documentação para cada API e cada modelo. Visite o repositório para uma referência completa do SDK para Python: