Notavia Documentação da API Central de Ajuda →

Emissão e eventos assíncronos

Emissão, cancelamento, carta de correção e inutilização são assíncronos: o POST devolve 202 Accepted com um jobId e o processamento (cálculo de impostos, assinatura, transmissão à SEFAZ) acontece em segundos, em segundo plano.

📦 DC-e (modelo 99). A Declaração de Conteúdo eletrônica usa este mesmo modelo: POST /dce → 202 { jobId } → polling/webhook → GET /dce/{jobId}; cancelamento em POST /dce/cancelamentos (pela chave de acesso, com justificativa ≥ 15 caracteres). O corpo é mais simples que o da NF-e (sem impostos: remetente, destinatário, itens, transporte) e o remetente deve ser não contribuinte de ICMS (contribuinte emite NF-e — rejeição 812). O resultado do job traz xmlUrl/daceUrl já no scheme da API (/api/integracao/dce/{chave}/xml|dace, header X-Api-Key), e o webhook job.concluido inclui o dceId. Cota própria por plano (Free 5/dia → 402; pagos = franquia da NF-e + 15%).

POST /api/integracao/dce
{
  "referenciaExterna": "envio-1001",
  "cnpjEmitente": "43636483000128",
  "tpEmit": 1,
  "remetente": { "nome": "Vendedor Exemplo", "cpf": "52998224725",
    "endereco": { "logradouro": "Rua A", "numero": "1", "bairro": "Centro",
      "codigoMunicipio": "3550308", "municipio": "São Paulo", "uf": "SP", "cep": "01000000" } },
  "destinatario": { "nome": "Comprador Exemplo", "cpf": "11144477735",
    "endereco": { "logradouro": "Av. B", "numero": "2", "bairro": "Centro",
      "codigoMunicipio": "3550308", "municipio": "São Paulo", "uf": "SP", "cep": "01000000" } },
  "itens": [{ "descricao": "Livro usado", "ncm": "49019900", "quantidade": 1, "valorUnitario": 45.9 }],
  "transporte": { "modalidade": 1 }
}

tpEmit: 1 = Marketplace (a plataforma assina; identificação preenchida automaticamente) ou 2 = Emissor próprio (remetente = o próprio emitente); Transportadora/ECT não estão disponíveis. O GET /dce/{jobId} devolve dceId, chaveAcesso, protocolo, cStat, xmlUrl e daceUrl.

Por que assíncrono?

A SEFAZ pode demorar ou oscilar. O modelo de jobs desacopla seu sistema dessa latência: você nunca fica preso num request de 30 s, e a idempotência por referenciaExterna elimina o risco clássico de "timeout → reenvio → nota duplicada".

Idempotência

Envie sempre referenciaExterna (ex.: número do pedido). Ela é única por empresa: um segundo POST com a mesma referência retorna 202 com o job original — nunca cria outra nota.

Emissão

POST /api/integracao/emissoes
{
  "referenciaExterna": "pedido-1001",
  "cnpjEmitente": "43636483000128",
  "serie": 2,
  "cpfCnpjCliente": "12345678000190",
  "codigoOperacao": "VENDA",
  "itens": [
    { "codigoProduto": "CANETA-AZ", "quantidade": 100, "valorUnitario": 2.50, "desconto": 10.00 }
  ],
  "frete": 25.00,
  "seguro": null,
  "outrasDespesas": null,
  "pagamentos": [ { "forma": "17", "valor": 265.00, "aVista": true } ],
  "transporte": {
    "modFrete": 1,
    "transportadora": { "cnpjCpf": "11222333000144", "nome": "Transportadora X",
                        "inscricaoEstadual": null, "endereco": null, "municipio": null, "uf": null },
    "volumes": [ { "quantidade": 2, "especie": "CAIXA", "marca": null, "numeracao": null,
                   "pesoLiquido": 10.5, "pesoBruto": 11.0 } ]
  },
  "cobranca": {
    "duplicatas": [ { "numero": "001", "vencimento": "2026-07-10", "valor": 265.00 } ]
  },
  "observacoes": "Pedido nº 1001. Mercadoria sai do depósito 2.",
  "troco": 0,
  "chavesReferenciadas": ["35260612345678000190550010000000011234567890"],
  "autorizadosDownloadXml": ["12345678000190"],
  "localEntrega": {
    "cpfCnpj": "12345678000190",
    "endereco": { "logradouro": "Av. Entrega", "numero": "50", "bairro": "Centro",
      "municipio": "São Paulo", "codigoMunicipioIbge": "3550308", "uf": "SP", "cep": "01000-000" }
  }
}

Campos avançados (opcionais)

Eventos

POST /api/integracao/cancelamentos
{ "referenciaExterna": "canc-1001", "chaveAcesso": "35260...", "justificativa": "Pedido cancelado pelo cliente" }

POST /api/integracao/cartas-correcao
{ "referenciaExterna": "cce-1001", "chaveAcesso": "35260...", "correcao": "Endereço de entrega: bloco B, não bloco A" }

POST /api/integracao/inutilizacoes
{ "referenciaExterna": "inut-2026-01", "cnpjEmitente": "43636483000128",
  "serie": 1, "numeroInicial": 15, "numeroFinal": 15, "justificativa": "Falha de transmissão queimou o numero" }

Justificativa/correção: mínimo 15 caracteres (regra SEFAZ). Cancelamento em regra só nas primeiras 24 h.

Consultando o job

GET /api/integracao/emissoes/{jobId}   (emissão)
GET /api/integracao/eventos/{jobId}    (cancelamento, CC-e, inutilização)

{
  "jobId": "...",
  "tipo": "Emissao",
  "status": "Concluido",
  "referenciaExterna": "pedido-1001",
  "erro": null,
  "resultado": { "chaveAcesso": "35260...", "numero": 1, "serie": 1, "protocolo": "1352600..." },
  "criadoEmUtc": "2026-06-12T14:00:00Z",
  "processadoEmUtc": "2026-06-12T14:00:03Z"
}
status Significado
Pendente Na fila
Processando Transmitindo à SEFAZ
Concluido Sucesso — resultado preenchido
Falha erro traz o motivo (validação, rejeição SEFAZ com código, comunicação)

Falha é terminal — o job não é retentado automaticamente (a decisão de negócio é sua). Corrija a causa e envie um novo POST com outra referenciaExterna.

Nota rejeitada pela SEFAZ

Quando a SEFAZ recebe e recusa a nota, o job fica Concluido e o resultado traz a nota com status Rejeitada (ou Denegada), cStat e motivo. Nas rejeições de cadastro do emitente (245, 203, 781, 230, 231, 164, 163, 213 e 301) vem também orientacao: a explicação e os passos, para você mostrar ao usuário em vez do texto cru da SEFAZ. Nos demais códigos, orientacao é null.

"resultado": {
  "status": "Rejeitada", "cStat": 245, "motivo": "Rejeição: CNPJ Emitente não cadastrado",
  "orientacao": {
    "cStat": 245,
    "titulo": "A SEFAZ não encontrou este CNPJ no cadastro de emissores de NF-e",
    "explicacao": "A SEFAZ da sua UF não reconhece o CNPJ do emitente como emissor de NF-e. ...",
    "passos": ["Confira se o CNPJ do emitente está correto em Cadastros → Emitentes.", "..."],
    "credenciamento": {
      "uf": "SP", "valeParaHomologacao": true,
      "orientacao": "Em São Paulo, o MEI precisa pedir o credenciamento como emissor de NF-e ...",
      "linkOficial": "https://servicos.sp.gov.br/fcarta/61E12444-9765-4974-9D98-11CF77E6FE95",
      "norma": "Portaria CAT 162/2008, art. 2º e art. 7º, §4º, item 5",
      "somenteRegimes": [4]
    },
    "linkAjuda": "/ajuda/troubleshooting#rejeicoes-de-cadastro-do-emitente"
  }
}

credenciamento só vem quando a rejeição pode ser falta de credenciamento e a UF do emitente tem essa exigência confirmada em fonte oficial para o regime dele (somenteRegimes vazio = todos; 4 = MEI). Nos outros casos é null. A tabela completa está em GET /api/credenciamento-nfe (portal).

Em vez de polling, configure um webhook — o Notavia chama seu sistema quando o job termina.