Empresas e certificado#

Cada CNPJ que vai emitir é uma empresa da sua conta. Você cadastra, atualiza, envia o certificado digital e liga a produção pela API, sem depender de ninguém.

O {cnpj} da URL aceita só os dígitos (ou o formato alfanumérico); pontos, barra e traço são ignorados. O CNPJ de outra conta e um CNPJ que não existe recebem a mesma resposta 404 empresa_nao_encontrada: a API nunca revela quem é cliente da plataforma.

Cadastrar uma empresa#

POST /empresas

{
  "cnpj": "11.222.333/0001-81",
  "razao_social": "LOJA EXEMPLO LTDA",
  "nome_fantasia": "Loja Exemplo",
  "ie": "111.111.111.111",
  "regime": "simples",
  "uf": "SP",
  "municipio": "Sao Paulo",
  "logradouro": "Rua das Flores",
  "numero": "100",
  "bairro": "Centro",
  "cep": "01001-000",
  "email": "fiscal@loja.exemplo.com.br",
  "telefone": "(11) 99999-8888"
}

Resposta 201:

{
  "id": "d6a1174d-11f5-487e-9583-d846f870c54d",
  "razao_social": "LOJA EXEMPLO LTDA",
  "nome_fantasia": "Loja Exemplo",
  "cnpj": "11222333000181",
  "ie": "111111111111",
  "im": null,
  "cnae": null,
  "regime": "simples",
  "industrial": false,
  "p_cred_sn": null,
  "endereco": {
    "uf": "SP", "codigo_municipio": "3550308", "municipio": "Sao Paulo", "logradouro": "Rua das Flores",
    "numero": "100", "complemento": null, "bairro": "Centro", "cep": "01001000"
  },
  "telefone": "11999998888",
  "email": "fiscal@loja.exemplo.com.br",
  "ambiente": "homologacao",
  "certificado": { "instalado": false, "valido_ate": null, "dias_restantes": null, "vencido": false },
  "bloqueios_producao": [
    "Envie um certificado A1 válido (e-CNPJ).",
    "As tabelas fiscais ainda não foram validadas por um contador (FISCAL_RATES_VERIFIED)."
  ],
  "ativo": true,
  "criado_em": "2026-10-04T15:50:05+00:00"
}

Campos do cadastro#

Campo desconhecido é recusado. Obrigatórios no POST: cnpj, razao_social, regime, uf, municipio, logradouro, numero, bairro, cep, email.

Limite de empresas: cada conta tem um máximo de empresas (padrão 50, ajustável). Passou dele: 422 limite_de_empresas. Criar empresa e enviar certificado são operações sensíveis: no máximo 10 chamadas por minuto por chave.

CNPJ já cadastrado na plataforma devolve 422 com erro no campo cnpj (a mesma mensagem, seja o CNPJ da sua conta ou de outra).

Atualizar uma empresa#

PATCH /empresas/{cnpj}: atualização parcial. O que você não enviar fica como está, e o resultado inteiro é validado. O CNPJ não muda (o certificado e as notas estão presos a ele).

{ "nome_fantasia": "Loja Exemplo Centro", "regime": "presumido" }

Se você trocar o cep sem informar o município, o código IBGE antigo deixa de valer e a API o descobre de novo. Mande "ativo": false para desativar a emissão da empresa (as notas e o cadastro continuam); "ativo": true reativa.

Certificado digital A1#

Para emitir, a SEFAZ exige o certificado A1 (arquivo .pfx ou .p12) e-CNPJ ICP-Brasil da empresa, dentro da validade. Certificado de pessoa física (e-CPF), A3 (token ou cartão) e autoassinado não servem.

PUT /empresas/{cnpj}/certificado aceita dois formatos.

JSON, com o arquivo em base64:

curl -s -X PUT "$API/empresas/11222333000181/certificado" -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d "{\"arquivo_certificado_base64\": \"$(base64 -w0 certificado.pfx)\", \"senha_certificado\": \"SENHA\"}"

Multipart, com o arquivo:

curl -s -X PUT "$API/empresas/11222333000181/certificado" -H "Authorization: Bearer $CHAVE" \
  -F "certificado=@certificado.pfx" -F "senha_certificado=SENHA"

A API confere que o arquivo abre com a senha, que não está vencido e que o CNPJ do certificado é o da empresa (mesma raiz de 8 dígitos: matriz e filiais compartilham o certificado do grupo). Resposta 200:

{ "empresa": "LOJA EXEMPLO LTDA:11222333000181", "cnpj": "11222333000181", "valido_ate": "2027-10-04", "dias_restantes": 364 }

• Arquivo de até 200 KB.
• A mensagem de erro para arquivo inválido e senha errada é a mesma de propósito (não ajudar quem está sondando): confira o arquivo e a senha.
• O arquivo e a senha ficam criptografados e nunca voltam em nenhuma resposta nem entram no log.
• GET /empresas/{cnpj}/certificado devolve só a situação: { "instalado": true, "valido_ate": "2027-10-04", "dias_restantes": 364, "vencido": false }. Monitore dias_restantes: certificado vencido bloqueia toda a emissão da empresa.
• DELETE /empresas/{cnpj}/certificado remove o certificado; sem ele não há emissão e a empresa volta para homologação.

Cadastrar já com o certificado (tudo ou nada)#

O POST /empresas aceita arquivo_certificado_base64 e senha_certificado junto dos dados: se o certificado for recusado, a empresa também não é criada. É o jeito mais simples de fazer o onboarding de um cliente em uma só chamada.

Trocar de ambiente#

PUT /empresas/{cnpj}/ambiente com { "ambiente": "producao" } ou { "ambiente": "homologacao" }.

Produção só libera quando nada impede. O que falta vem em erros.ambiente (e, a qualquer momento, em bloqueios_producao da empresa):

{ "codigo": "requisicao_invalida", "mensagem": "As tabelas fiscais ainda não foram validadas por um contador (FISCAL_RATES_VERIFIED).",
  "erros": { "ambiente": ["As tabelas fiscais ainda não foram validadas por um contador (FISCAL_RATES_VERIFIED)."] } }

Os bloqueios possíveis são: certificado A1 válido ausente ou vencido, inscrição estadual não informada e as tabelas fiscais da plataforma ainda não validadas. Antes de trocar, siga o checklist de produção.

Numeração da NF-e (séries e próximo número)#

Cada empresa numera as notas em sequência, por série e por ambiente (homologação e produção têm sequências próprias). Sem configurar nada, a nota sai na série 1 a partir do número 1.

Quem já emitia por outro sistema (Bling, Tiny...) precisa continuar de onde parou: a SEFAZ recusa número repetido na mesma série. Antes da primeira nota em produção, informe o próximo número:

curl -s -X PUT "$API/empresas/11222333000181/series/1" -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{ "proximo_numero": 1500 }'

Resposta 200:

{ "cnpj": "11222333000181", "ambiente": "producao", "serie": 1, "ultimo_numero": 1499, "proximo_numero": 1500 }

• A série vai de 0 a 889 (890 em diante são do fisco e da contingência). Série que não existe é criada na hora.
• A numeração só anda para a frente: número menor ou igual ao maior já usado na série responde 422 numero_retroativo, com o minimo aceito. Número já usado nunca é reaproveitado.
• O ajuste vale para o ambiente atual da empresa. Configure a numeração de produção depois de trocar de ambiente.
• Pular números sem nota (por exemplo, ir de 10 para 1500 sem ter emitido 11 a 1499 em outro sistema) obriga a inutilizar a faixa pulada.

GET /empresas/{cnpj}/series lista as séries do ambiente atual com ultimo_numero e proximo_numero (sem nenhuma nota, a série 1 aparece com próximo número 1). Para emitir em outra série, mande serie no corpo da nota (Emitir NF-e).

Resposta da empresa#

Campos que você vai usar mais: ambiente (homologacao ou producao), certificado.dias_restantes e certificado.vencido, bloqueios_producao (lista do que impede a produção; vazia quando pode ligar) e ativo.