Emitentes
Cadastro, certificado A1, CSC, séries e perfil fiscal do emitente.
O emitente é o CNPJ (ou CPF) que emite as notas. Todo o onboarding é feito pela API: cadastro, certificado,
CSC e séries. As rotas de /emitentes não usam X-Emitente-Id e só enxergam os emitentes da sua conta.
Cadastro
POST /emitentes responde 201 + Location. Campos principais:
| Campo | Observação |
|---|---|
cnpjCpf | Com ou sem máscara; dígito verificador conferido. Não muda depois do cadastro (422 cnpj-imutavel). |
razaoSocial, nomeFantasia | |
inscricaoEstadual | Obrigatória para NF-e e NFC-e. |
inscricaoMunicipal | Usada na NFS-e. |
endereco | logradouro, numero, complemento, bairro, codigoMunicipio (IBGE), uf, cep |
ambiente | Obrigatório, sem padrão: HOMOLOGACAO ou PRODUCAO (veja Ambientes). |
regimeTributario | SIMPLES_NACIONAL, SIMPLES_NACIONAL_EXCESSO_SUBLIMITE, REGIME_NORMAL ou MEI |
regimeEspecialTributacao | Padrão NENHUM |
ativo | Padrão true. Emitente inativo responde 404 nas rotas de nota. |
PUT /emitentes/{id} substitui o cadastro. CNPJ já cadastrado na conta: 409 emitente-duplicado.
Para preencher o cadastro, GET /emitentes/inscricao-estadual?cnpj=&uf= busca a inscrição estadual na SEFAZ (ou
numa consulta pública, quando a UF não oferece a oficial). Nada é gravado; lista vazia pode ser contribuinte isento.
Certificado A1
curl -s -X PUT https://api.u2dnotafiscal.com.br/api/v1/emitentes/$EMITENTE_ID/certificado \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F arquivo=@certificado.pfx -F senha="$SENHA_DO_CERTIFICADO"- O titular do certificado precisa ter a mesma raiz de CNPJ do emitente (o A1 da matriz serve à filial).
- A resposta traz só metadados:
titular,titularNome,validoDe,validoAte,fingerprintSha256,enviadoEm. O arquivo e a senha ficam cifrados e nunca voltam. - Erros:
422 certificado-invalido(arquivo ou senha),certificado-vencido,certificado-outro-titular. POST /emitentes/certificado/inspecaolê o A1 antes do cadastro, para preencher o CNPJ e o nome, sem gravar nada.
Sem certificado válido, a emissão responde 422 certificado-indisponivel. Acompanhe o validoAte e envie o novo
certificado antes do vencimento.
CSC (NFC-e)
O CSC (Código de Segurança do Contribuinte) é gerado no portal da SEFAZ da UF, um por ambiente:
PUT /emitentes/{id}/csc
{ "ambiente": "HOMOLOGACAO", "idToken": "000001", "csc": "<código gerado na SEFAZ>" }Responde 204. GET /emitentes/{id}/csc lista ambiente e idToken dos CSC cadastrados; o código nunca volta.
Séries e numeração
PUT /emitentes/{id}/series
{ "tipo": "NFE", "ambiente": "HOMOLOGACAO", "serie": "1", "proximoNumero": 1, "padrao": true }tipo:NFE,NFCEouNFSE. Uma série por tipo e ambiente pode ser apadrao, usada quando a emissão não informaserie.proximoNumerosó avança: valor menor que o atual responde422 numeracao-retroativa.- A numeração é feita pelo servidor; o seu sistema nunca escolhe o número da nota.
- Emissão sem série configurada:
422 serie-nao-configurada.
Perfil fiscal (NFC-e)
O perfil fiscal é a tributação padrão aplicada ao item de NFC-e enviado sem icms e que não está no catálogo com
tributação:
PUT /emitentes/{id}/perfil-fiscal/NFCE
{
"cfop": "5102",
"tributacao": { "icms": { "origem": 0, "csosn": "102" }, "pis": { "cst": "49" }, "cofins": { "cst": "49" } }
}cfopde saída interna (5xxx);cstno regime normal,csosnno Simples/MEI.- Sem perfil, emitente do Simples usa CSOSN 102 e CFOP 5102 (
padrao: truenoGET). No regime normal sem perfil, oGETresponde404 perfil-fiscal-nao-configuradoe a emissão de item sem tributação,422 perfil-fiscal-ausente.