VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Fiscal (NF-e e NFC-e)

Estabelecimentos emissores

Cadastra, consulta, altera e exclui os CNPJs que emitem as notas fiscais da loja.

Um estabelecimento é um CNPJ autorizado a emitir nota: a matriz, uma filial ou uma loja. Ele guarda a inscrição estadual, o endereço fiscal e as séries da NF-e e da NFC-e. O primeiro cadastrado vira o estabelecimento padrão da loja, e só pode haver um padrão. Depois de cadastrar, provisione o estabelecimento no provedor de emissão.

Todas as rotas exigem o módulo focusnfe e o privilégio manage_nfe ou manage_settings.

Tokens e certificado não passam por aqui

Os tokens do provedor são gravados pela plataforma no provisionamento e nunca são devolvidos nem aceitos nestas rotas. O certificado digital é enviado direto ao provedor.

Listar estabelecimentos

Devolve os estabelecimentos não excluídos, o padrão primeiro e depois por nome.

GET/api/v1/admin/fiscal/establishmentsAdmin

Lista os estabelecimentos emissores

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/fiscal/establishments" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estabelecimentos devolvidos
json
{
  "items": [
    {
      "id": "c04d4d27-b16d-4dcb-836a-7c9eb0a40c3b",
      "name": "Loja Modelo Comércio Ltda",
      "kind": "matriz",
      "cnpj": "11222333000181",
      "inscricao_estadual": "110042490114",
      "ie_isento": false,
      "uf": "SP",
      "city": "São Paulo",
      "cep": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 12",
      "neighborhood": "Bela Vista",
      "serie_nfe": "1",
      "serie_nfce": "1",
      "focusnfe_empresa_ref": "",
      "warehouse_id": "8e0f3b6a-52a1-4c7d-9d34-1f7a6b2c8e55",
      "is_default": true,
      "status": "active",
      "created_at": "2026-07-14T06:21:59Z",
      "updated_at": "2026-07-14T06:21:59Z"
    }
  ]
}

Campos da resposta

iduuid
Id do estabelecimento.
namestring
Razão social ou nome fantasia.
kindstring
matrizfilialloja
Tipo do estabelecimento.
cnpjstring
CNPJ, exatamente como foi cadastrado.
inscricao_estadualstring
Inscrição estadual (IE). Vazia quando isento.
ie_isentoboolean
true quando o estabelecimento é isento de IE.
ufstring
UF com 2 letras, em maiúsculas.
citystring
Cidade.
cepstring
CEP do endereço fiscal.
streetstring
Logradouro.
numberstring
Número.
complementstring
Complemento.
neighborhoodstring
Bairro.
serie_nfestring
Série da NF-e deste emissor.
serie_nfcestring
Série da NFC-e deste emissor.
focusnfe_empresa_refstring
Referência da empresa no provedor. Vazia até o provisionamento.
warehouse_iduuid
Depósito ligado ao emissor. Notas de pedidos despachados desse depósito usam este estabelecimento. Ausente quando não há.
is_defaultboolean
Se é o emissor padrão da loja.
statusstring
activeinactive
Situação.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo
500Falha de consulta{"error":"failed to list establishments","detail":"..."}
401 / 403Sem token, sem privilégio, módulo desligado{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}

Cadastrar um estabelecimento

Valida o CNPJ pelos dígitos verificadores (aceita o CNPJ alfanumérico novo) e exige a UF com 2 letras. Se for o primeiro da loja, é marcado como padrão automaticamente. Publica o evento fiscal.establishment.created.

POST/api/v1/admin/fiscal/establishmentsAdmin

Cadastra um estabelecimento emissor

Corpo da requisição

namestringobrigatório
Razão social ou nome fantasia.
cnpjstringobrigatório
CNPJ válido. Prefira só os dígitos (11222333000181): o valor é gravado como veio e deve ser único.
ufstringobrigatório
UF com 2 letras. Minúsculas viram maiúsculas.
kindstringpadrão: matriz
matrizfilialloja
Tipo.
inscricao_estadualstring
IE. Deixe vazio se ie_isento for true.
ie_isentobooleanpadrão: false
Isento de IE.
citystring
Cidade.
cepstring
CEP.
streetstring
Logradouro.
numberstring
Número.
complementstring
Complemento.
neighborhoodstring
Bairro.
serie_nfestringpadrão: 1
Série da NF-e.
serie_nfcestringpadrão: 1
Série da NFC-e.
focusnfe_empresa_refstring
Referência da empresa no provedor, se ela já existir lá. Normalmente fica vazia: o provisionamento preenche.
warehouse_iduuid
Depósito ligado a este emissor. Um depósito só pode estar em um estabelecimento.
is_defaultboolean
Pedido de padrão. O primeiro estabelecimento da loja é sempre o padrão. Enviar true quando a loja já tem um padrão falha com 422; para promover outro, use o PUT.
statusstringpadrão: active
activeinactive
Situação inicial.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/fiscal/establishments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Modelo Comércio Ltda",
    "kind": "matriz",
    "cnpj": "11222333000181",
    "inscricao_estadual": "110042490114",
    "uf": "SP",
    "city": "São Paulo",
    "cep": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "serie_nfe": "1",
    "serie_nfce": "1"
  }'

Resposta

201Estabelecimento criado
json
{
  "id": "c04d4d27-b16d-4dcb-836a-7c9eb0a40c3b",
  "name": "Loja Modelo Comércio Ltda",
  "kind": "matriz",
  "cnpj": "11222333000181",
  "inscricao_estadual": "110042490114",
  "ie_isento": false,
  "uf": "SP",
  "city": "São Paulo",
  "cep": "01310100",
  "street": "Avenida Paulista",
  "number": "1000",
  "complement": "",
  "neighborhood": "Bela Vista",
  "serie_nfe": "1",
  "serie_nfce": "1",
  "focusnfe_empresa_ref": "",
  "is_default": true,
  "status": "active",
  "created_at": "2026-10-11T22:30:00Z",
  "updated_at": "2026-10-11T22:30:00Z"
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid body","detail":"..."}
422CNPJ com dígito verificador errado{"error":"failed to create establishment","detail":"fiscal: invalid CNPJ"}
422UF sem 2 letras{"error":"failed to create establishment","detail":"fiscal: UF must be 2 letters"}
422CNPJ ou depósito já usado, kind fora da lista{"error":"failed to create establishment","detail":"..."}

Consultar um estabelecimento

GET/api/v1/admin/fiscal/establishments/{id}Admin

Consulta um estabelecimento emissor

Parâmetros de caminho

iduuidobrigatório
Id do estabelecimento.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/fiscal/establishments/c04d4d27-b16d-4dcb-836a-7c9eb0a40c3b" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estabelecimento devolvido
json
{
  "id": "c04d4d27-b16d-4dcb-836a-7c9eb0a40c3b",
  "name": "Loja Modelo Comércio Ltda",
  "kind": "matriz",
  "cnpj": "11222333000181",
  "uf": "SP",
  "serie_nfe": "1",
  "serie_nfce": "1",
  "is_default": true,
  "status": "active"
}

Exemplo abreviado; a resposta traz todos os campos da listagem.

Erros

StatusQuandoCorpo
404Não existe, foi excluído ou o id não é UUID{"error":"establishment not found"}

Alterar um estabelecimento

O PUT regrava os campos de endereço

name, kind, cnpj, uf, serie_nfe e serie_nfce só mudam quando você envia um valor não vazio. Todos os outros (inscricao_estadual, ie_isento, city, cep, street, number, complement, neighborhood, warehouse_id) são regravados com o que vier no corpo: se você omitir, ficam vazios. Reenvie o objeto completo, lido do GET. Este PUT também não altera status nem focusnfe_empresa_ref.

Enviar is_default: true promove este estabelecimento a padrão e tira a marca do anterior, antes de gravar o resto. Publica o evento fiscal.establishment.updated.

PUT/api/v1/admin/fiscal/establishments/{id}Admin

Altera um estabelecimento emissor

Parâmetros de caminho

iduuidobrigatório
Id do estabelecimento.

Corpo da requisição

namestring
Novo nome. Vazio mantém o atual.
kindstring
matrizfilialloja
Novo tipo. Vazio mantém o atual.
cnpjstring
Novo CNPJ, validado. Vazio mantém o atual.
ufstring
Nova UF. Vazio mantém a atual.
inscricao_estadualstring
IE. Vazio apaga.
ie_isentoboolean
Isento de IE. Omitir grava false.
citystring
Cidade. Vazio apaga.
cepstring
CEP. Vazio apaga.
streetstring
Logradouro. Vazio apaga.
numberstring
Número. Vazio apaga.
complementstring
Complemento. Vazio apaga.
neighborhoodstring
Bairro. Vazio apaga.
serie_nfestring
Série da NF-e. Vazio mantém a atual.
serie_nfcestring
Série da NFC-e. Vazio mantém a atual.
warehouse_iduuid
Depósito ligado. Vazio desliga.
is_defaultboolean
true promove a padrão. false ou omitido não retira a marca de padrão.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/fiscal/establishments/c04d4d27-b16d-4dcb-836a-7c9eb0a40c3b" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Modelo Comércio Ltda",
    "cnpj": "11222333000181",
    "uf": "SP",
    "inscricao_estadual": "110042490114",
    "city": "São Paulo",
    "cep": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "serie_nfe": "2"
  }'

Resposta

200Estabelecimento atualizado
json
{
  "id": "c04d4d27-b16d-4dcb-836a-7c9eb0a40c3b",
  "name": "Loja Modelo Comércio Ltda",
  "kind": "matriz",
  "cnpj": "11222333000181",
  "uf": "SP",
  "serie_nfe": "2",
  "serie_nfce": "1",
  "is_default": true,
  "status": "active"
}

Exemplo abreviado; a resposta traz todos os campos da listagem.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid body","detail":"..."}
409Falha ao promover a padrão{"error":"cannot set default","detail":"..."}
422CNPJ inválido, CNPJ ou depósito já usados, kind fora da lista{"error":"failed to update","detail":"fiscal: invalid CNPJ"}

Excluir um estabelecimento

Exclusão lógica: o estabelecimento some das listagens e fica inactive. Notas já emitidas por ele continuam consultáveis. Não é possível excluir o padrão.

DELETE/api/v1/admin/fiscal/establishments/{id}Admin

Exclui um estabelecimento emissor

Parâmetros de caminho

iduuidobrigatório
Id do estabelecimento.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/fiscal/establishments/c04d4d27-b16d-4dcb-836a-7c9eb0a40c3b" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Estabelecimento excluído
text
(sem corpo)

Erros

StatusQuandoCorpo
409É o estabelecimento padrão{"error":"promote another default first","detail":"..."}
500Não existe, já foi excluído ou id inválido{"error":"failed to delete","detail":"..."}
Excluir não desfaz o provisionamento

A empresa continua cadastrada no provedor. Antes de excluir, confirme que nenhum item aberto da fila aponta para este emissor.

Veja também

  • Provisionamento
  • Fila de emissão
  • Configuração de emissão
Anterior
Configuração de emissão
Próxima
Provisionamento no provedor
Nesta página
  • Listar estabelecimentos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Cadastrar um estabelecimento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um estabelecimento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar um estabelecimento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir um estabelecimento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também