Manual do OSDfe

Conceitos essenciais

Seis ideias explicam quase tudo o que o sistema faz. Vale ler uma vez.

1. Distribuição: a Sefaz entrega, o sistema busca

Toda nota emitida contra o CNPJ da sua empresa fica disponível no Ambiente Nacional da Sefaz. O OSDfe consulta esse serviço a cada intervalo configurado (padrão: 1 hora por CNPJ) e baixa o que é novo. Cada documento vem com um número de sequência, o NSU. O sistema guarda o último NSU recebido e pergunta sempre "o que há depois deste?".

2. Resumo × XML completo

Quando uma NF-e chega para você, a Sefaz primeiro entrega só o resumo: emitente, valor, data e situação, sem itens nem impostos. O XML completo é liberado depois que a sua empresa se manifesta (a Ciência da Operação basta). Sem o XML completo não há DANFE, e o ERP não consegue dar entrada na nota.

O CT-e é diferente: chega completo direto, sem precisar de manifestação.

3. Manifestação do destinatário

É a resposta da sua empresa à Sefaz sobre cada NF-e recebida. São quatro eventos:

Os prazos contam a partir da data de autorização da nota. Desde 01/06/2026 (Ajuste SINIEF 14/26, NT 2020.001 v1.60) os três eventos conclusivos têm 90 dias; antes eram 180. Fora do prazo a Sefaz recusa, e o sistema nem oferece o botão.

4. Só a Ciência pode ser automática

A Ciência não tem efeito jurídico e pode ser enviada pelo sistema sozinho, se você ligar a Ciência automática na empresa. Confirmação, Desconhecimento e Operação não Realizada sempre exigem uma pessoa confirmando aquela ação específica. Não existe configuração que mude isso.

5. Consumo indevido (cStat 656)

A Sefaz bloqueia por 1 hora o CNPJ que consulta demais: repetir a consulta quando não há nada novo, ou fazer mais de 20 consultas pontuais por hora. O bloqueio vale para todos os sistemas que usam aquele CNPJ, inclusive o ERP. O OSDfe respeita esses limites sozinho; por isso o botão "Sincronizar" às vezes responde que ainda é cedo.

6. Produção × Homologação

Homologação é o ambiente de testes da Sefaz: não tem notas reais e nada tem valor jurídico. Produção é o ambiente real. Toda empresa nova nasce em homologação; passa para produção quando o cadastro e o certificado estiverem conferidos.

Entrar no sistema

Primeiro acesso

Quando o administrador cria o seu usuário, o sistema gera uma senha provisória. No primeiro acesso você é obrigado a trocá-la, informando a provisória e a nova duas vezes. Enquanto não trocar, o painel não abre.

Primeira instalação

Se o sistema ainda não tem nenhum usuário, a tela de entrada pede também o Nome: quem se cadastrar ali vira o Gestor do painel. Depois disso, usuários novos só entram por convite.

Papéis e permissões

O papel define o que a pessoa pode fazer. As empresas que ela enxerga são definidas à parte, pelos vínculos.

Implantar uma empresa nova, passo a passo

A ordem importa. Cada passo depende do anterior.

1. Crie o grupo do cliente (se ainda não existir), com os limites contratados. Grupos.
2. Cadastre a empresa em homologação: CNPJ, razão social, UF e grupo. Empresas.
3. Envie o certificado A1 (.pfx) com a senha. O sistema confere se a senha abre o arquivo, se o CNPJ do certificado é o da empresa e se não está vencido. Certificados.
4. Sincronize uma vez em homologação para conferir que o certificado conecta. A resposta esperada é "nenhum documento localizado".
5. Mude para produção em Empresas → botão "→ produção". Leia o aviso: a partir daí as consultas e manifestações são reais.
6. Decida sobre a Ciência automática. Ligada, as notas novas recebem Ciência sozinhas e o XML completo chega sem ninguém clicar.
7. Convide as pessoas e vincule-as ao grupo ou aos CNPJs. Usuários.
8. Configure a integração com o ERP, se houver. Integração.

Painel

A primeira tela depois de entrar. Mostra o que precisa de ação hoje.

Barra superior (vale para todas as telas)

Empresa ativa (canto inferior esquerdo)

Quem tem mais de uma empresa escolhe aqui com qual está trabalhando. O Painel e a lista de Documentos mostram só a empresa ativa. O sistema lembra a última escolha.

Primeiros passos

Aparece enquanto a empresa não tem cadastro, certificado e uma primeira sincronização. Some sozinho quando os três estão feitos; "Ocultar" esconde antes.

Indicadores

Precisa da sua ação

As notas pendentes, das mais urgentes para as menos. A etiqueta à esquerda é o prazo que falta (2d) ou quanto já passou (-3d). "Dar ciência" envia a Ciência daquela nota na hora; "Detalhes" abre a nota. Quando a Ciência já venceu, o botão vira "Fora do prazo": ainda dá para registrar Confirmação, Desconhecimento ou Operação não Realizada pelos Detalhes, dentro dos 90 dias.

Distribuição por tipo e Certificados A1

Quantidade e valor de NF-e e CT-e, e a validade de cada certificado. Barra amarela: vence em menos de 30 dias. Vermelha: vencido. Certificado vencido para a consulta da empresa inteira.

Documentos fiscais

Todas as NF-e e CT-e da empresa ativa, com filtros, ações em lote e exportação.

Filtros rápidos (botões)

Campos de filtro

Colunas da tabela

Etiquetas de situação

Ações em lote

Marque as notas e escolha o evento. Até 20 documentos por envio. A seleção precisa ser de um tipo só: manifestação é para NF-e, desacordo é para CT-e. Os eventos com efeito jurídico pedem confirmação explícita mesmo em lote.

Atualizar situação na Sefaz

Consulta a situação de hoje de cada nota: se foi cancelada depois de chegar, e quais eventos ela já tem (inclusive manifestações feitas por outro sistema, como o ERP ou o portal da Sefaz). Não envia evento nenhum. Use quando suspeitar que o fornecedor cancelou uma nota. O sistema já faz isso sozinho para as notas das últimas 48 horas.

Detalhe do documento

Clique em qualquer linha: o documento abre ao lado, sem perder a lista.

Como manifestar

Uma nota

1. Abra a nota (Painel → Detalhes, ou Documentos → clique na linha).
2. Escolha o evento em Manifestação.
3. Nos eventos com efeito jurídico, leia o aviso e clique em Confirmar envio.
4. O resultado aparece em segundos. O histórico passa a mostrar o protocolo da Sefaz.

Operação não Realizada: justificativa

Escreva o motivo de forma objetiva, como se fosse lido por um fiscal: "Mercadoria recusada na entrega por avaria", "Pedido cancelado antes do embarque". Evite só "não recebido".

Várias notas de uma vez

Em Documentos, marque as caixas, escolha o evento na barra de lote e confirme. Até 20 por envio.

Mudei de ideia: retificação

A Sefaz permite registrar cada evento conclusivo até duas vezes na mesma nota, e vale o último. Exemplo: você confirmou, depois percebeu que a mercadoria não chegou e registrou Operação não Realizada; se ela chegar afinal, pode confirmar de novo. O sistema escolhe o número de sequência certo sozinho.

A Ciência não é conclusiva: depois de um evento conclusivo, não se registra mais Ciência (a Sefaz recusa com 655).

Ciência automática

Com ela ligada (Empresas), a cada sincronização o sistema envia a Ciência das notas novas com menos de 9 dias, autorizadas e ainda sem manifestação. O histórico registra "automático" como origem. As notas canceladas ficam de fora.

Qual evento usar?

Responda as perguntas de cima para baixo. A primeira que for "sim" indica o evento.

XML completo e DANFE

Como o XML completo chega

1. A nota chega como resumo.
2. Alguém (ou a rotina automática) registra a Ciência, ou outro evento que não seja Desconhecimento.
3. A Sefaz libera o XML completo para a sua empresa.
4. Na próxima sincronização o sistema baixa o XML, e o DANFE e o envio ao ERP ficam disponíveis.

Normalmente isso leva um intervalo de sincronização (até 1 hora). Manifestações feitas em outro sistema, como o portal da Sefaz, também liberam o XML: ele chega pelo mesmo caminho.

Quando o XML demora: recuperação automática

Se a nota foi manifestada há mais de 3 horas e o XML ainda não veio, ela ganha a etiqueta sem XML há Nh e o sistema passa a buscá-la pela chave, direto na Sefaz. Essa busca pontual tem limite (a Sefaz permite 20 por hora por CNPJ), então o sistema usa no máximo 10 por hora, a mais antiga primeiro, e nunca durante um bloqueio. Você não precisa fazer nada.

O mesmo mecanismo cobre falhas na sequência de NSU: se um lote da Sefaz pular um número, o sistema pede aquele número individualmente.

Quando o XML não vem mais

A Sefaz guarda os documentos por 90 dias. Depois disso a etiqueta vira XML indisponível e a única saída é pedir o XML ao fornecedor. Desconhecimento não libera XML: nesse caso só há o resumo.

DANFE

Use "Imprimir / salvar PDF" e escolha "Salvar como PDF" no diálogo do navegador. O DANFE é gerado a partir do XML guardado: é idêntico ao do emitente em conteúdo. Para CT-e o documento equivalente é o DACTE.

CT-e e desacordo

• Não há manifestação do destinatário no CT-e. Ele chega completo para todos os participantes: remetente, destinatário, expedidor, recebedor e tomador.
• O tomador é quem importa. O CT-e que a empresa lança é aquele em que ela paga o frete. Use o filtro "Tomador (CT-e) → Esta empresa paga".
• Prestação do Serviço em Desacordo (610110): use quando a empresa é tomadora e o serviço não foi prestado como contratado (valor errado, frete não contratado, carga não entregue). Exige uma observação e confirmação explícita. Tem efeito jurídico, como os conclusivos da NF-e.
• O sistema também recebe CT-e OS (transporte de pessoas/valores) e GTV-e.

Relatórios e exportação

Todos usam o período em "Emissão de / até" (Documentos).

Empresas

Cada CNPJ que consulta a Sefaz. A lista vem em ordem alfabética.

Cadastrar

Ações de cada empresa

Quando ligar a Ciência automática?

Certificados A1

Validade

A coluna "Restam" mostra os dias até o vencimento. O sistema avisa por e-mail aos usuários da empresa aos 30, 15, 7, 3 e 1 dia, e no vencimento. Com o certificado vencido a empresa para de consultar a Sefaz.

Grupos de empresas

Um grupo é um cliente. Um cliente com 4 CNPJs é um grupo com 4 empresas.

Reduzir um limite abaixo do que já está em uso é permitido: é assim que se registra uma redução de contrato. Quem já está continua; o limite novo vale para o próximo cadastro. Só o Gestor cria grupos.

Usuários

Filtro por situação

O seletor Ativos / Inativos / Todos no alto da lista escolhe quem aparece. O padrão é Ativos: quem já saiu da empresa não atrapalha a busca. Use Inativos para reativar alguém ou conferir acessos antigos.

Convidar

Não há campo de senha: o sistema gera uma senha provisória e mostra uma única vez para você copiar e entregar à pessoa. No primeiro acesso ela é obrigada a trocar.

Editar e vínculos

Integração com o ERP

Ao fim de cada sincronização, os documentos vão para as tabelas do ERP (NFE_DESTINADA e XML_NFE).

Quem grava no ERP: servidor ou agente

Botões

Entrada no ERP: importada × entrada dada

A cada ciclo, o OSDfe pergunta ao ERP o que aconteceu com cada nota que já está em NFE_DESTINADA. São duas perguntas diferentes, e o ERP responde as duas:

Vale tanto para a nota importada pelo OSDfe quanto para a importada à mão pela tela de Nota Destinada do ERP. Funciona igual com o agente e com a conexão direta (Servidor).

Como funciona

1. Na primeira vez, o sistema confere todas as NF-e da empresa que já estão em NFE_DESTINADA. Depois, só as que ainda não tiveram entrada.
2. O ERP responde por nota: importada? entrada dada? O resultado é gravado também no próprio ERP, em NFE_DESTINADA, em quatro colunas novas: OSDFE_IMPORTADA e OSDFE_ENTRADA (S/N), OSDFE_IMPORTADA_EM e OSDFE_ENTRADA_EM (data e hora).
3. O resultado volta ao OSDfe e aparece no filtro, na etiqueta da coluna ERP, no histórico da nota e nos relatórios.
4. A nota com entrada dada sai da conferência: é o fim do caminho dela.

Não é preciso ligar nada: a conferência roda para toda empresa com integração ativa em banco Oracle. Nada é importado nem finalizado por ela; o OSDfe só lê NOTAS_ENTRADAS e anota o resultado.

Atualização do agente

O agente instalado no cliente se atualiza sozinho. Quando uma versão nova é publicada no servidor, cada agente a encontra no ciclo seguinte, baixa, confere a assinatura digital e reinicia já na versão nova. Não é preciso acessar a máquina do cliente.

A condição é o agente ter a chave pública de verificação, que vem embutida no instalador. Um agente instalado antes disso recebe a chave na próxima vez em que o instalador novo for executado por cima dele ("Atualizar os agentes existentes"). Daí em diante, as atualizações seguintes são automáticas.

Tokens de API

Um token permite que outro programa (um assistente de IA via MCP, uma integração) use o OSDfe em seu nome, sem navegador. Ele tem exatamente o seu papel e as suas empresas.

Configurações

O que é salvo aqui vale na hora, sem reiniciar nada.

Minha senha

Ícone de chave, ao lado do seu nome no canto inferior esquerdo. Pede a senha atual e a nova duas vezes. Trocar a senha encerra as suas outras sessões e revoga os seus tokens de API: é o que fazer se suspeitar que alguém conhece a sua senha.

Rotinas recomendadas

Situações e o que fazer

Chegou uma nota que ninguém reconhece.

Dê Ciência (se quiser ver os itens no DANFE) e pergunte a compras e ao recebimento. Se ninguém reconhecer, registre Desconhecimento dentro de 90 dias e avise o responsável fiscal.

A mercadoria voltou sem nota de devolução / foi recusada no recebimento.

Operação não Realizada, com justificativa descrevendo o motivo.

Devolvemos parte da mercadoria com nota de devolução.

Confirmação da Operação. A devolução é tratada pela nota de devolução, não pela manifestação.

Manifestei o evento errado.

Registre o evento certo pela tela: cada conclusivo pode ser registrado até duas vezes e vale o último. Ciência não desfaz um conclusivo.

A Ciência venceu (mais de 10 dias).

Não dá mais para registrar Ciência. Os três conclusivos continuam disponíveis até 90 dias; qualquer um deles também libera o XML (menos o Desconhecimento).

A nota está "sem XML há muitas horas".

Nada a fazer: o sistema busca pela chave, até 10 por hora por empresa. Se passar de um dia, confira em Configurações se a sincronização está ligada e se a empresa não está bloqueada.

A tela diz que a empresa está bloqueada (656).

Aguarde 1 hora sem consultar. Consultar antes reinicia a contagem. Verifique se outro sistema (ERP, outro programa de NF-e) está consultando o mesmo CNPJ: todos dividem o mesmo limite.

O certificado venceu.

Envie o novo em Certificados. Enquanto isso a empresa não consulta a Sefaz; as notas não se perdem por alguns dias, mas a Ciência tem 10 dias e o XML fica na Sefaz por 90.

O fornecedor cancelou a nota depois que ela chegou.

O sistema detecta sozinho nas primeiras 48 horas, e a qualquer momento pelo botão "Atualizar situação na Sefaz". Nota cancelada não se manifesta e não se lança.

Recebemos cobrança de frete que não contratamos.

Encontre o CT-e (filtro Tomador → "Esta empresa paga"), selecione-o e registre Prestação do Serviço em Desacordo com a explicação.

A nota não foi para o ERP.

Filtre "Com erro no ERP", passe o mouse sobre o status para ver o motivo, corrija do lado do ERP (produto sem cadastro, fornecedor novo) e use "Reenviar ao ERP" no detalhe da nota.

A nota está no ERP mas ninguém deu entrada.

Filtre "Importados, sem entrada". Passe o mouse sobre a etiqueta importada para ver o estado do estoque no ERP (CONFERIDO, DESATUALIZADO…) e cobre o lançamento de quem cuida da entrada.

Dei entrada no ERP e o OSDfe ainda mostra "importada".

A conferência roda uma vez por ciclo (1 hora, por padrão). Aguarde a próxima sincronização. Se não mudar, confira no ERP se a nota foi mesmo finalizada: NOTAS_ENTRADAS.ESTOQUE precisa estar em ATUALIZADO ou LIBERADO.

Uma empresa ficou meses desativada.

Ao reativar, a Sefaz pode não entregar as notas do período parado pela sincronização normal. As de até 90 dias podem ser buscadas pela chave; as mais antigas só com o fornecedor.

Mensagens da Sefaz (cStat)

Glossário