Antes da primeira nota pela API: como saber se a empresa já pode emitir

A primeira nota de uma empresa pela API costuma falhar por um motivo que não tem nada a ver com a nota: falta o certificado, o regime tributário não foi configurado, o plano de emissão não está ativo. A Sudrel faz essa checagem antes de criar qualquer nota e expõe ela numa rota própria, a prontidão, para o seu sistema perguntar antes de emitir e mostrar ao usuário o que falta.

Uma pergunta, uma lista de itens

GET /v1/companies/{id}/prontidao

A resposta traz cada requisito como um item, com uma situação, uma mensagem e a correção em português. A situação da resposta inteira é a pior entre os itens:

• ok: requisito atendido. Pode emitir.
• aviso: emite, mas vale olhar. Por exemplo, o certificado nos últimos 30 dias de validade, ou um parâmetro do município que ainda não se conhece.
• bloqueio: a emissão é recusada com HTTP 412, código empresa_nao_pronta, e nada é criado. Tentar de novo não adianta: é preciso corrigir o item antes.

O que bloqueia e o que só avisa

Quatro itens podem impedir a emissão:

• certificado: o certificado A1 da empresa ausente ou vencido. Nos últimos 30 dias de validade ele vira aviso.
• regime_tributario: o regime tributário da empresa não configurado.
• plano_emissao: sem plano de emissão ativo. Só vale em produção; no ambiente de teste é sempre ok.
• sandbox_municipio_proprio: só com a chave de teste, quando a empresa emite pelo sistema da prefeitura, que não tem ambiente de teste.

Os outros itens nunca bloqueiam, mas dizem o que a Sudrel sabe e o que vai preencher: o regime de apuração no Simples, o município de emissão, se o município usa o Sistema Nacional e como, a série da DPS, os padrões da empresa (como o código de serviço), as alíquotas oficiais do município, o NBS para o IBS e a CBS e a redução de IBS e CBS prevista para o serviço.

Três jeitos de usar

• No cadastro da empresa, no seu sistema: depois de enviar o certificado, consulte a prontidão e mostre ao usuário a mensagem e a correção de cada item que não está ok.
• Antes de um lote grande: um bloqueio recusaria o lote inteiro com 412. Melhor saber antes de montar o arquivo.
• Para ser avisado: o webhook EMPRESA_PRONTIDAO_ALTERADA chega quando um item muda de situação, por exemplo quando o certificado entra nos últimos 30 dias de validade. A conferência roda a cada 6 horas, em produção.

A validação de uma nota sem emitir (POST /v1/nfse/validacoes) também devolve a prontidão, junto do resultado da nota. No SDK oficial, é empresas.prontidao(id); no servidor MCP, um assistente de IA responde "essa empresa já pode emitir?" com a mesma checagem.

Perguntas frequentes

O que significa o erro 412 empresa_nao_pronta?

Que a empresa tem pelo menos um item da prontidão em bloqueio, como certificado ausente ou vencido, regime tributário não configurado ou plano de emissão inativo. Nada foi criado; corrija o item e emita de novo.

Preciso consultar a prontidão antes de toda nota?

Não. A emissão já faz a mesma checagem. Consultar antes serve para mostrar o que falta ao usuário no cadastro e antes de um lote grande; para acompanhar mudanças, use o webhook EMPRESA_PRONTIDAO_ALTERADA.

Certificado vencendo bloqueia a emissão?

Não. Nos últimos 30 dias de validade o item certificado vem como aviso e a emissão continua. Só bloqueia quando o certificado está ausente ou já venceu.

Referência completa na documentação da API.