Leia antes:
../conectores.md(state map) andfichas.md(index of sheets).
What it is#
Downloads the NF-e distributed to your CNPJ by SEFAZ (Distribuição DFe, Ambiente Nacional) and loads them into the Bronze layer.
Supported ingestion modes:
- Nós buscamos — Nós buscamos os dados na sua fonte.
What it's for#
Bring NF-e (SEFAZ) data into your datalake and make it available to the Bronze/Silver/Gold layers, BI models and the natural language question wizard.
When to use / when not to use#
Use when you need to consolidate this source into the datalake on a scheduled basis, with isolation per workspace.
Remember that the first run with a real credential is followed by our team before the connector is fully released.
Plan and permissions#
- Plan: core product (connectors are part of all plans; the limit is the number of sources of the plan).
- Access: requires an active workspace — with the subscription overdue, suspended or cancelled, the run is blocked.
- Shutdown: ingestion runs can be temporarily turned off (maintenance or incident). When this happens, the screen indicates the resource is unavailable at the moment.
Prerequisites#
- An NF-e (SEFAZ) account with access to the data you want to ingest.
- Provide the company's CNPJ and the digital certificate A1 (.pfx/.p12): convert the file to base64 and paste it below, along with the password. Certificate and password are encrypted (AES-256-GCM), used only in the secure connection with SEFAZ and never shown again.
Credentials#
Authentication method: Digital certificate A1 (.pfx / PKCS#12) + password, used for mutual TLS with SEFAZ. Certificate and password are encrypted (AES-256-GCM), decrypted only inside the call and never appear in logs/errors.
Sensitive fields. They are encrypted (AES-256-GCM) and are never stored in the connection config, in the pipeline definition, in export or in the DAG. By default the encrypted value is stored in the database; moving the credential of this connection to the external credential vault is an explicit choice made per connection after saving — see ../../administracao/credenciais-e-rotacao.md.
- Certificado A1 (.pfx em base64) (
certificadoPfxB64) — In the terminal: base64 -i certificado.pfx (macOS/Linux) or certutil -encode (Windows). - Senha do certificado (
senhaCertificado)
Secrets are never re-displayed and go through redaction on any error/log (raw token, URL-encoded and in JSON).
Form fields#
| Campo | Rótulo | Tipo | Obrigatório | Observação |
|---|---|---|---|---|
cnpj | CNPJ | text | yes | CNPJ of the recipient/interested party — the invoices distributed to it. |
uf | UF | text | yes | State abbreviation of the company (will become the IBGE code in the query). |
ambiente | Ambiente | selection | no | default: producao; options: producao / homologacao |
certificadoPfxB64 🔒 | Certificado A1 (.pfx em base64) | password/secret | yes | secret (encrypted; external vault optional); In the terminal: base64 -i certificado.pfx (macOS/Linux) or certutil -encode (Windows). |
senhaCertificado 🔒 | Senha do certificado | password/secret | yes | secret (encrypted; external vault optional) |
Step by step#
- In the menu Dados → Conexões, use Nova conexão.
- Choose NF-e (SEFAZ) in the catalog.
- Fill in the form fields (see table above).
- Use Testar conexão. The result is shown broken down into Conectividade, Autenticação and Listagem/leitura — each with OK, Failed, Not applicable or Not tested. A capability with no test of its own for this connector shows as Not applicable, and Not applicable never counts as success.
- Use Salvar conexão. Saving does NOT start any ingestion.
- On the connection card, use Montar extração (or go to Orquestração → Pipelines and use Conectar fonte). The pipeline points to the saved connection — the credential is not copied.
- In the review, Publicar (agenda desligada) creates version 1 without executing anything. Then, Ativar agenda and Executar agora are separate actions.
Example — connection test#
Example configuration (all values are fictitious; secrets appear masked):
# Exemplo sintético (valores fictícios — não são credenciais reais)
cnpj = SEU_CNPJ (14 dígitos, sem pontuação real)
uf = MG
ambiente = producao
certificadoPfxB64 = •••••• (cifrado — nunca exibido)
senhaCertificado = •••••• (cifrado — nunca exibido)Expected result#
The Testar conexão returns the list of discovered tables/resources. After the first load, rows appear in the Bronze layer of your workspace, ready for the pipeline.
Limits and costs#
- Pagination: hard cap per run (default 10,000 pages / 5,000,000 rows); anti-loop guard.
- SaaS load: default
batchSize5,000,maxRows200,000 per resource. - Estimated volume: ~0.5 GB/month (catalog estimate, not measurement).
- Cost: the extraction itself is not charged by the platform; the Bronze load consumes datalake processing (billable).
Security#
- Scope per workspace: each client reads and writes only in their own datalake (
<prefixo>_bronze/_silver/_gold); there is never leakage between workspaces. - Encrypted secrets: sensitive material is encrypted with AES-256-GCM before being stored. The external credential vault is optional and enabled per connection; without it, the encrypted value remains in the database. Changing the value here does NOT revoke the credential at the origin.
- Redaction: every error/log goes through secret redaction (raw, URL-encoded and in JSON).
- Production does not mock: a path that would fall into a mock triggers the production guard (explicit failure instead of simulating success).
Common errors#
- Certificado recusado — the A1 certificate has expired, the password is wrong or the file is not a valid .pfx. Export the certificate again and update the credential.
- Nenhum documento localizado — SEFAZ responds like this when there are no new NF-e for the CNPJ since the last read point; not a credential failure.
- Consumo indevido (bloqueio temporário) — SEFAZ limits repeated queries without new documents; wait the indicated window before running again.
Troubleshooting#
- Use Testar conexão to isolate credential/network problems before scheduling.
- Monitor runs in the connector observability (error rate, p50/p95, freshness).
- A schema change at the source is signaled by schema drift (new column = info; removed column/type changed = attention).
Related#
../conectores.md— connector catalog by state../ingestao-incremental-backfill.md— full, incremental by watermark, backfill and checkpoint../pipeline-medalhao.md— Bronze/Silver/Gold layers and quality../agendamento-retry-dlq.md— scheduling, retry/backoff and DLQ../custo-limites-seguranca.md— cost, caps and security per workspace
Last updated: 2026-10-04. Sheet automatically generated from the product's connector catalog.