Issuance API

Issue NF-e documents on behalf of sellers. The domain exposes six endpoints, used in the order below:

All endpoints require the three signature headers — see Authentication & Signing. GET, DELETE and multipart requests sign the empty string as body; path variables are part of the signed path. Responses are bare (no platform envelope) and business errors come as an array of {codigo, mensagem} — see General Conventions.

Company status and prerequisites

• Registration places the company in the platform’s approval queue. The company can issue only after operations approve it and the certificate is linked. Issuing before that returns codigo 10004004 (company not issuable).
• Every company has one current environment: test (Homologacao) or production (Producao). Newly registered companies default to test; switching to production is an operations action. The ambienteEmissao of an issuance request must match the company’s current environment, otherwise the request is rejected with 10004030 — a hard guard against test invoices being issued into production. See Environments.

Company registration

POST /openapi/v2/empresas
Content-Type: application/json

Request

{
  "cnpj": "14422279000106",
  "inscricaoMunicipal": "999999",
  "inscricaoEstadual": "999999",
  "razaoSocial": "Empresa teste LTDA",
  "nomeFantasia": "Empresa teste",
  "optanteSimplesNacional": true,
  "mei": false,
  "email": "empresa-teste@example.com",
  "telefoneComercial": "6122222222",
  "endereco": {
    "pais": "Brasil",
    "uf": "MG",
    "cidade": "Belo Horizonte",
    "logradouro": "Rua Teste",
    "numero": "999",
    "bairro": "Bairro Teste",
    "cep": "85100000"
  },
  "emissaoNFeProduto": {
    "ambienteProducao": {
      "sequencialNFe": 1,
      "serieNFe": "10"
    }
  }
}

Response (HTTP 200)

{ "empresaId": "1934811222334455" }

A successful registration enters the approval queue; registering the same CNPJ again returns HTTP 400 with codigo 10003002.

Digital certificate association

POST /openapi/v1/empresas/{empresaId}/certificadoDigital
Content-Type: multipart/form-data

Platform checks: password matches (CER0005 otherwise), certificate not expired (10003011), certificate CNPJ matches the company (10003010), not identical to the currently active certificate (10003012). Success is HTTP 200 with no body. A successful upload replaces the company’s previous certificate.

Signing note: for multipart requests the body is the empty string.

APP_SECRET="<APP_SECRET>"
P="/openapi/v1/empresas/1934811222334455/certificadoDigital"
TS=$(date +%s)
SIGN=$(printf '%s' "${APP_SECRET}${P}${TS}" | md5sum | cut -d' ' -f1)
 
curl -X POST "https://api.v2.tffiscal.com${P}" \
  -H "token: ${APP_SECRET}" -H "timestamp: ${TS}" -H "sign: ${SIGN}" \
  -F "senha=certpass123" -F "arquivo=@uploaded-cert.pfx"

Webhook registration

POST /openapi/v1/webhooks
Content-Type: application/json

Request

{
  "uri": "https://example.com/tffiscal/callback",
  "contentType": "application/json",
  "token": "dGt6eXp5ZGRra2tzc3Nra2hoaGFha2tha2FhamFoaGFoNzc3Nz"
}

Response (HTTP 200)

{ "webHookId": "550001" }

One callback configuration per application: webHookId is the application identifier, and calling again overwrites the configuration. Registration automatically subscribes to the two result events, authorized and denied. An invalid registration (id mismatch or a non-JSON contentType) returns 10009033. The callback payload is documented in Webhooks — Issuance result callback.

NF-e issuance

POST /openapi/v2/empresas/{empresaId}/nf-e
Content-Type: application/json

Accepted requests return HTTP 200 with no body and enter the asynchronous issuance flow; the result arrives via webhook or the query endpoint. Re-submitting the same id within the idempotency window reuses the original task.

Request

{
  "id": "NFe-000014553",
  "ambienteEmissao": "Homologacao",
  "pedido": {
    "presencaConsumidor": "OperacaoPelaInternet",
    "pagamento": {
      "formas": [{
        "tipo": "CartaoDeCredito",
        "valor": 28.47,
        "credenciadoraCartao": {
          "tipoIntegracaoPagamento": "NaoIntegradoAoSistemaDeGestao",
          "bandeira": "Mastercard"
        }
      }]
    }
  },
  "cliente": {
    "tipoPessoa": "F",
    "nome": "Demo Client",
    "email": "demo.client@mail.com",
    "cpfCnpj": "88533234775",
    "telefone": "(41) 3278-0217",
    "endereco": {
      "uf": "PR",
      "cidade": "4106902",
      "logradouro": "Rua Presidente Wilson",
      "numero": "911",
      "bairro": "Uberaba",
      "cep": "81570440"
    }
  },
  "itens": [{
    "cfop": "6403",
    "codigo": "000068",
    "descricao": "Kingston DataTraveler SE9 DTSE9H 16GB USB Drive",
    "ncm": "85235190",
    "ean": "619659000424",
    "quantidade": 1,
    "unidadeMedida": "UN",
    "valorUnitario": 28.47,
    "impostos": {
      "icms": { "situacaoTributaria": "101" },
      "pis": { "situacaoTributaria": "49" },
      "cofins": { "situacaoTributaria": "49" }
    }
  }]
}

The line total is computed by the platform as quantidade × valorUnitario rounded to two decimals; do not send it.

Tax codes and rates: the request carries tax codes only. Combinations that need no rate — CSOSN 102 / 103 / 300 / 400 for Simples Nacional companies together with PIS / COFINS 49 — issue directly; codes that require a rate (for example the ICMS rate for CST 00 under the regular regime, or the credit percentage for CSOSN 101) are currently rejected by the tax engine with 10005000 and will be enabled once the rate table is connected.

formas[].tipo values:

Scope of this phase

Values outside this range (presencaConsumidor, multiple payments, unknown payment type, tipoPessoa inconsistent with the document) are rejected with 10004031.

NF-e query

GET /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}

nfeId is the id sent at issuance. Unknown ids return HTTP 404 with codigo NFe0001.

Response (HTTP 200)

{
  "id": "NFe-000014553",
  "tipo": "NF-e",
  "status": "Autorizada",
  "ambienteEmissao": "Homologacao",
  "enviadaPorEmail": false,
  "dataCriacao": "2024-11-27T20:56:46Z",
  "dataUltimaAlteracao": "2024-11-27T20:56:56Z",
  "forcarEmissaoContingencia": false,
  "pedido": {
    "presencaConsumidor": "OperacaoPelaInternet",
    "pagamento": {
      "tipo": "PagamentoAVista",
      "formas": [{ "tipo": "CartaoDeCredito", "valor": 28.47 }]
    }
  },
  "cliente": {
    "indicadorContribuinteICMS": "NaoContribuinte",
    "tipoPessoa": "F",
    "nome": "Demo Client",
    "email": "demo.client@mail.com",
    "cpfCnpj": "88533234775",
    "endereco": {
      "uf": "PR",
      "cidade": "Curitiba",
      "logradouro": "Rua Presidente Wilson",
      "numero": "911",
      "bairro": "Uberaba",
      "cep": "81570440"
    }
  },
  "numero": "262",
  "serie": "10",
  "dataEmissao": "2024-11-27T20:56:46Z",
  "chaveAcesso": "35241104893402000113550020000002621202427463",
  "transporte": { "frete": { "modalidade": "SemFrete", "valor": 0 } },
  "dataAutorizacao": "2024-11-27T20:56:55Z",
  "linkDanfe": "https://api.v2.tffiscal.com/open/files/8802?token=eyJh...",
  "linkDownloadXml": "https://api.v2.tffiscal.com/open/files/8801?token=eyJh...",
  "linkConsultaPorChaveAcesso": "",
  "protocolo": { "numero": "135240009194753" },
  "emitidaEmContingencia": false,
  "itens": [{
    "cfop": "6403",
    "codigo": "000068",
    "descricao": "Kingston DataTraveler SE9 DTSE9H 16GB USB Drive",
    "ncm": "85235190",
    "quantidade": 1,
    "unidadeMedida": "UN",
    "valorUnitario": 28.47,
    "valorTotal": 28.47
  }],
  "valorTotal": 28.47
}

Top-level fields:

pedido:

cliente:

Status semantics: AguardandoAutorizacao from acceptance until SEFAZ replies; Autorizada once authorized; Negada when rejected (motivoStatus explains why — fix and resubmit under a new id); Cancelada after a successful cancellation.

NF-e cancellation

DELETE /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}

Cancels an authorized invoice; success is HTTP 200 with no body, and the query endpoint then returns Cancelada. Rules:

• Only Autorizada invoices can be cancelled; other statuses return 10004012.
• Within 24 hours of authorization (some states allow more, per platform configuration); outside the window returns 10004013, and only a return invoice can be issued instead.
• A SEFAZ refusal returns 10004014 with the SEFAZ status code and reason.
• Unknown nfeId returns HTTP 404 with codigo NFe0001.

Business error codes

Authentication-layer errors (401 / 403 / 429) use the platform envelope — see Authentication & Signing. The full cross-domain table is in Error Codes.

Integration checklist

1. Register a company → 200 + empresaId; register the same CNPJ again → 400 + 10003002.
2. Link the certificate → 200 with no body; wrong password → 400 + CER0005.
3. Register the webhook → 200 + webHookId.
4. After approval, issue with ambienteEmissao=Homologacao → 200 with no body; then query → AguardandoAutorizacao becomes Autorizada, and linkDanfe / linkDownloadXml download successfully.
5. Receive the authorized callback: the token header equals the registered value and the payload has nfeStatus=Autorizada.
6. Negative cases: ambienteEmissao=Producao → 400 + 10004030; presencaConsumidor=OperacaoPresencial → 400 + 10004031.
7. Cancel the just-authorized invoice → 200; query again → Cancelada; cancel an unknown id → 404 + NFe0001.
8. Failure paths: wrong sign → 401 + 10009003; unsubscribed endpoint → 403 + 10009005.

Troubleshooting

Issuance stuck in AguardandoAutorizacao? While the company is in the test environment, this depends on the availability of the SEFAZ test environment; if it persists for more than a few minutes, contact the platform with the empresaId and nfeId.

Issuance returns 10004004? The company has not been approved yet, or its certificate is not linked / has expired. Complete approval and certificate association after registration first.

Callbacks not arriving? Make sure uri is a publicly reachable https/http address that returns 2xx; the platform retries with backoff and trips a circuit breaker after consecutive failures — calling the registration endpoint again restores delivery.