API de emissão de NFS-e: a nota inteira com 4 campos

Quem integra emissão de NFS-e costuma descobrir o tamanho do problema depois de começar: o leiaute da DPS tem dezenas de campos, e cada município tem as suas exigências sobre quais deles vão, quais não podem ir e com que valor. Na API de emissão da Sudrel, a chamada para uma nota com tomador CNPJ leva quatro campos. Este post mostra quais são e o que acontece com o resto.

Os quatro campos

• empresa_id: qual das empresas da sua conta emite. O certificado, o regime e o município vêm dela.
• tomador.documento: o CNPJ do cliente. Razão social e endereço saem da consulta cadastral do CNPJ.
• valor: em texto, com ponto decimal ("1500.00"). Texto, e não número, para nenhuma nota depender de arredondamento de ponto flutuante.
• servico.descricao: o que foi prestado, como vai aparecer na nota.

Recomendamos mandar também a referencia, o identificador do pedido ou da venda no seu sistema. Ela não é obrigatória, mas é o que permite repetir a chamada com segurança e encontrar a nota depois pelo número que você já conhece.

De onde vem o resto

Código de serviço, competência e regime tributário vêm da configuração fiscal da empresa emissora, feita uma vez no painel. Quando o município exige a alíquota do ISS e nem a chamada nem a empresa trazem uma, a Sudrel usa a alíquota oficial que o próprio município cadastrou no Sistema Nacional para aquele serviço. Tudo pode ser informado na chamada quando você quiser decidir: o que vem na nota vence o padrão da empresa.

O mesmo JSON em qualquer cidade

Município que não aceita inscrição municipal do prestador, que exige alíquota em certo regime, que recusa um campo de endereço: essas diferenças moram no motor de regras, e não no seu código. Algumas rejeições conhecidas são corrigidas e reenviadas sozinhas, e a correção aparece em ajustes. O seu sistema manda sempre a mesma estrutura, e a nota sai pelo Emissor Nacional ou pelo sistema próprio da prefeitura, conforme a cidade.

Antes de emitir, dá para perguntar

A rota de validação recebe a mesma nota e devolve os erros e os ajustes sem criar nada. E a prontidão da empresa responde, item por item, se o certificado, a configuração fiscal e o plano estão em dia. As duas existem para o erro aparecer na tela de quem integra, e não depois, numa nota rejeitada.

Perguntas frequentes

E se o tomador for pessoa física?

Para CPF não existe consulta cadastral pública, então entram na chamada o nome, o CEP e o número do endereço. Rua, bairro e cidade vêm do CEP, e o resto continua vindo da empresa e do município.

A nota emitida pela API aparece no painel?

Aparece, junto com as emitidas por planilha e pela tela, marcada com a origem API. É o mesmo motor, a mesma fila e a mesma franquia do plano.

Onde está a referência completa dos campos?

Na documentação da API, que tem também o guia da primeira nota em 5 minutos.

A página da emissão de NFS-e por API resume o que a integração entrega, do sandbox aos webhooks.