Atendimento

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:

CampoObservação
cnpjCpfCom ou sem máscara; dígito verificador conferido. Não muda depois do cadastro (422 cnpj-imutavel).
razaoSocial, nomeFantasia
inscricaoEstadualObrigatória para NF-e e NFC-e.
inscricaoMunicipalUsada na NFS-e.
enderecologradouro, numero, complemento, bairro, codigoMunicipio (IBGE), uf, cep
ambienteObrigatório, sem padrão: HOMOLOGACAO ou PRODUCAO (veja Ambientes).
regimeTributarioSIMPLES_NACIONAL, SIMPLES_NACIONAL_EXCESSO_SUBLIMITE, REGIME_NORMAL ou MEI
regimeEspecialTributacaoPadrão NENHUM
ativoPadrã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/inspecao lê 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, NFCE ou NFSE. Uma série por tipo e ambiente pode ser a padrao, usada quando a emissão não informa serie.
  • proximoNumero só avança: valor menor que o atual responde 422 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" } }
}
  • cfop de saída interna (5xxx); cst no regime normal, csosn no Simples/MEI.
  • Sem perfil, emitente do Simples usa CSOSN 102 e CFOP 5102 (padrao: true no GET). No regime normal sem perfil, o GET responde 404 perfil-fiscal-nao-configurado e a emissão de item sem tributação, 422 perfil-fiscal-ausente.

Nesta página