SDK para Node.js

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

• SDK da ACBr API para Node.js: https://github.com/projeto-acbr-oficial/acbrapi-sdk-node

Requisitos

• Node.js 18 ou posterior (o SDK utiliza a fetch API nativa do runtime)
• TypeScript é opcional: o pacote é distribuído com os tipos (.d.ts) e pode ser consumido tanto em projetos TypeScript quanto JavaScript (CommonJS ou ESM)

Instalação

O SDK é instalado diretamente a partir do GitHub. Execute o comando na pasta do seu projeto (onde fica o package.json). O pacote é compilado automaticamente no momento da instalação (script prepare), então não é preciso rodar o build manualmente:

npm install git+https://github.com/projeto-acbr-oficial/acbrapi-sdk-node.git --save

ou na forma curta:

npm install projeto-acbr-oficial/acbrapi-sdk-node --save

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

npm install "git+https://github.com/projeto-acbr-oficial/acbrapi-sdk-node.git#main" --save

No package.json do seu projeto isso equivale a:

{
  "dependencies": {
    "acbrapi-sdk": "git+https://github.com/projeto-acbr-oficial/acbrapi-sdk-node.git#main"
  }
}

Utilização

Depois de instalar, importe as classes de configuração e as APIs que você vai utilizar:

import { Configuration, CepApi, CnpjApi, EmpresaApi } from 'acbrapi-sdk';

Em projetos JavaScript com CommonJS:

const { Configuration, CepApi } = require('acbrapi-sdk');

Obtendo o token de acesso

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

• Obtenção das credenciais (Client ID e Client Secret)
• Geração do token de acesso usando as credenciais obtidas.

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:

async function getAccessToken(scope: string): Promise<string> {
  const response = await fetch(
    'https://auth.acbr.api.br/realms/ACBrAPI/protocol/openid-connect/token',
    {
      method: 'POST',
      headers: {'Content-Type': 'application/x-www-form-urlencoded'},
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: process.env.ACBRAPI_CLIENTID!,
        client_secret: process.env.ACBRAPI_CLIENTSECRET!,
        scope, // defina o scope a ser usado
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Falha ao obter o token: ${response.status}`);
  }

  const data = await response.json();
  return data.access_token;
}

Criando o client

Com um token de acesso em mãos, crie a Configuration e instancie as classes de API:

const config = new Configuration({
  accessToken: `Bearer ${await getAccessToken('cep cnpj')}`,
});

const cepApi = new CepApi(config);

Atenção

O valor de accessToken é enviado exatamente como recebido no header Authorization. Por isso, é necessário incluir o prefixo Bearer , como no exemplo acima.

A Configuration também aceita, entre outras opções:

• basePath: para apontar para o ambiente de homologação (https://hom.acbr.api.br). O padrão é o ambiente de produção (https://prod.acbr.api.br).
• accessToken como função (sincrona ou async): útil para renovar o token automaticamente quando ele expira.
• fetchApi: para usar uma implementação de fetch customizada.
• middleware: para interceptar as requisições e respostas (log, retentativas etc.).

const config = new Configuration({
  basePath: 'https://hom.acbr.api.br',
  accessToken: async () => `Bearer ${await getAccessToken('cep cnpj')}`,
});

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.

Os métodos recebem os parâmetros em um único objeto de requisição e retornam uma Promise com o objeto de resposta já tipado:

const endereco = await cepApi.consultarCep({cep: '80030030'});
console.log(endereco.logradouro, endereco.municipio, endereco.uf);

Cada método também possui a variante ...Raw, que retorna a resposta HTTP completa, caso você precise inspecionar status e headers:

const response = await cepApi.consultarCepRaw({cep: '80030030'});
console.log(response.raw.status);
const endereco = await response.value();

Exemplo completo

import { Configuration, CepApi, CnpjApi, ResponseError } from 'acbrapi-sdk';

async function main() {
  const config = new Configuration({
    accessToken: `Bearer ${await getAccessToken('cep cnpj')}`,
  });

  // Consulta de CEP
  const cepApi = new CepApi(config);
  const endereco = await cepApi.consultarCep({cep: '80030030'});
  console.log(endereco);

  // Consulta de CNPJ
  const cnpjApi = new CnpjApi(config);
  try {
    const empresa = await cnpjApi.consultarCnpj({cnpj: '08421842000190'});
    console.log(empresa.razao_social, empresa.endereco?.municipio);
  } catch (error) {
    if (error instanceof ResponseError) {
      console.error('Erro ao consultar o CNPJ:', error.response.status);
      console.error(await error.response.text());
    } else {
      throw error;
    }
  }
}

main();

Desenvolvimento (build a partir do código-fonte)

Caso queira compilar os fontes TypeScript para JavaScript:

npm install
npm run build

Referência completa

O repositório do GitHub contém a lista de todos os endpoints e métodos correspondentes, tipos e modelos, parâmetros, e mais. Visite o repositório para uma referência completa do SDK para Node.js:

• SDK da ACBr API para Node.js: https://github.com/projeto-acbr-oficial/acbrapi-sdk-node