Migrando da Nuvem Fiscal para a ACBr API

Boa notícia: a migração é simples. A ACBr API é compatível com a API da Nuvem Fiscal em endpoints, escopos, payloads e retornos.

Na prática, você precisa fazer dois ajustes principais na sua aplicação:

1. Ajustar a autenticação, gerando novas credenciais da ACBr API.
2. Alterar a URL base das chamadas.

Também manteremos mudanças de endpoints da ACBr API em versões diferentes, para preservar a compatibilidade das aplicações existentes.

Ainda não usa a ACBr API?

Você pode começar criando uma conta para testes.

Quanto custa a ACBr API ?

Após o processo de cadastro, você receberá um e-mail, com as Condições Comercial da ACBr.API

SDKs

Os SDKs da ACBr API já foram ajustados com as URLs e a autenticação atuais. Você pode baixá-los no GitHub oficial do Projeto ACBr.

Empresas cadastradas

Lembre-se apesar da compatibilidade entre as APIs, Nuvem Fiscal e ACBr API são serviços diferentes. Por isso, as empresas existentes na sua conta da Nuvem Fiscal precisam ser recadastradas na ACBr API.

Os ID gerados na Nuvem Fiscal não são válido para utilização na ACBrAPI, portanto, cancelamento, eventos, download, impressão, retornará que o documento não foi encontrado.

Resumo da migração

Item	Nuvem Fiscal	ACBr API
API de produção	https://api.nuvemfiscal.com.br	https://prod.acbr.api.br
API de sandbox/homologação	https://api.sandbox.nuvemfiscal.com.br	https://hom.acbr.api.br
Autenticação OAuth 2	https://auth.nuvemfiscal.com.br/oauth/token	https://auth.acbr.api.br/realms/ACBrAPI/protocol/openid-connect/token
Credenciais	Console da Nuvem Fiscal	https://console.acbr.api.br
Fluxo OAuth 2	client_credentials	client_credentials
Header autenticado	Authorization: Bearer <token>	Authorization: Bearer <token>

info

As credenciais da Nuvem Fiscal não são reutilizadas na ACBr API. Gere um novo Client ID e um novo Client Secret no Console da ACBr API antes de atualizar a sua aplicação.

Antes de migrar

1. Acesse o Console da ACBr API.
2. Crie uma nova credencial para o ambiente que deseja utilizar.
3. Recadastre na ACBr API as empresas que já existem na sua conta da Nuvem Fiscal.
4. Guarde o Client ID e o Client Secret em local seguro.
5. Atualize a URL de autenticação da sua aplicação.
6. Atualize a URL base usada nas chamadas da API.
7. Gere um novo token e valide uma chamada simples, como consulta de CEP.

caution

O Client Secret deve ser tratado como segredo de produção. Não inclua esse valor em código-fonte, repositórios, aplicativos desktop, aplicativos mobile ou frontends públicos.

URLs base da ACBr API

Use a URL conforme o ambiente da credencial:

Produção

https://prod.acbr.api.br

Homologação

https://hom.acbr.api.br

Autenticação OAuth 2

https://auth.acbr.api.br/realms/ACBrAPI/protocol/openid-connect/token

Gerando o token

A autenticação continua usando OAuth 2 com o fluxo client_credentials. Faça uma requisição POST para o endpoint de autenticação da ACBr API com o header Content-Type: application/x-www-form-urlencoded.

Exemplo:

curl --request POST "https://auth.acbr.api.br/realms/ACBrAPI/protocol/openid-connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=SEU_CLIENT_ID" \
  --data-urlencode "client_secret=SEU_CLIENT_SECRET" \
  --data-urlencode "scope=cep cnpj nfse"

Campos do payload:

• grant_type: sempre client_credentials
• client_id: o Client ID gerado no Console da ACBr API
• client_secret: o Client Secret gerado no Console da ACBr API
• scope: escopos que o token deve possuir, separados por espaço, como cep cnpj nfse

Resposta esperada:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiIw...",
  "token_type": "bearer",
  "scope": "cep cnpj nfse",
  "expires_in": 2592000
}

Use o valor de access_token no header Authorization das próximas chamadas.

Chamando a API

Depois de gerar o token, mantenha a mesma URI do endpoint que você já utiliza e altere apenas a URL base.

Exemplo de consulta de CEP em produção:

GET https://prod.acbr.api.br/cep/01311200 HTTP/1.1
Host: prod.acbr.api.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiIw...
Accept: */*

Exemplo da mesma chamada em homologação:

GET https://hom.acbr.api.br/cep/01311200 HTTP/1.1
Host: hom.acbr.api.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiIw...
Accept: */*

Checklist de adaptação

• Trocar https://api.nuvemfiscal.com.br por https://prod.acbr.api.br
• Trocar https://api.sandbox.nuvemfiscal.com.br por https://hom.acbr.api.br
• Trocar o endpoint de token para https://auth.acbr.api.br/realms/ACBrAPI/protocol/openid-connect/token
• Gerar novas credenciais no Console da ACBr API
• Recadastrar na ACBr API as empresas usadas pela integração
• Atualizar client_id e client_secret na aplicação
• Manter os mesmos escopos usados pela integração
• Manter as mesmas URIs, payloads e leitura dos retornos dos endpoints
• Renovar o token próximo da expiração informada em expires_in

Próximos passos

• Para ver o fluxo completo de autenticação da ACBr API, consulte Autenticação
• Para testar a integração visualmente, consulte Usando Postman
• Para conferir os endpoints disponíveis, consulte a referência da API