OpenNota — API de emissão fiscal (v1)#

Referência de máquina: openapi.json (OpenAPI 3.1, gerado do código; os exemplos deste guia passam na validação real da API).

Estado desta versão — leia primeiro#

O contrato abaixo é o definitivo: dá para escrever o cliente inteiro agora e testá-lo contra o /validar; quando cada modelo for habilitado, nada muda do seu lado.

1. Em uma frase#

Um endpoint só. POST https://api.opennota.com.br/v1/emissoes com modelo no corpo (NFCOM, NFSE ou NFE), o CNPJ do emitente e os dados do destinatário. O OpenNota monta o XML, assina com o A1 do emitente (guardado no cofre do OpenNota), transmite, guarda a nota e devolve número, chave, protocolo e XML.

O OpenNota não lê nem grava o banco do seu sistema. Você grava a nota no seu banco a partir da resposta. E o OpenNota também guarda tudo: a segunda via sai dele a qualquer momento (§8).

2. Emitente: por que só o CNPJ#

O emitente é cadastrado uma vez no OpenNota (plano administrativo): razão social, IE, IM, regime (CRT/Simples), endereço, padrões fiscais por modelo (CFOP, cClass, ICMS, FUST/FUNTTEL, cTribNac…), séries e o certificado A1 com a senha, cifrados. Por isso o pedido manda só emitente.cnpj:

• o certificado nunca trafega em pedido nem fica no seu sistema;
• os dados fiscais do emitente não podem divergir de um pedido para outro;
• trocar o A1 (renovação anual) não exige mudar nada no seu sistema.

A sua credencial recebe permissão para os CNPJs que ele pode usar. CNPJ fora da permissão responde 404 (igual a um CNPJ que não existe).

3. Ambientes e sandbox#

Mesmo endereço, credenciais diferentes. O ambiente é da credencial, nunca do corpo:

A credencial de sandbox não abre produção: um .env de teste copiado por engano não emite nota de verdade. Não existe campo ambiente no corpo.

4. Autenticação (todas as rotas)#

Mensagem assinada — cinco partes separadas por ponto:

{timestamp}.{nonce}.{MÉTODO}.{path}.{corpo}

• MÉTODO em maiúsculas (GET, POST).
• path = caminho com a query string, exatamente como vai na URL: /v1/emissoes?referenciaExterna=fin-1.
• corpo = os bytes exatos enviados (vazio em GET). Serialize o JSON uma vez, assine essa string e envie essa mesma string — reserializar muda um espaço e quebra a assinatura.

Nonce, método e path dentro da assinatura impedem reenviar uma requisição capturada e reaproveitar uma assinatura em outra rota.

Cliente Laravel (pronto para usar)#

// config/services.php
'opennota' => [
    'base'   => env('OPENNOTA_BASE', 'https://api.opennota.com.br'),
    'key_id' => env('OPENNOTA_KEY_ID'),       // sandbox ou produção
    'secret' => env('OPENNOTA_SECRET'),       // NUNCA no repositório nem em log
],

// app/Services/OpenNotaClient.php
namespace App\Services;

use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

class OpenNotaClient
{
    private function headers(string $metodo, string $pathComQuery, string $corpo): array
    {
        $ts    = (string) time();
        $nonce = (string) Str::uuid();               // UUID v4
        $msg   = "{$ts}.{$nonce}." . strtoupper($metodo) . ".{$pathComQuery}.{$corpo}";
        $sig   = hash_hmac('sha256', $msg, config('services.opennota.secret'));
        return [
            'X-OpenNota-Key'       => config('services.opennota.key_id'),
            'X-OpenNota-Timestamp' => $ts,
            'X-OpenNota-Nonce'     => $nonce,
            'X-OpenNota-Signature' => "sha256={$sig}",
        ];
    }

    private function get(string $pathComQuery): Response
    {
        return Http::withHeaders($this->headers('GET', $pathComQuery, ''))
            ->timeout(20)
            ->get(config('services.opennota.base') . $pathComQuery);
    }

    /** Emite. $idempotencyKey: estável por nota, ex.: "fin-{$financeiro->id}-nfcom". */
    public function emitir(array $pedido, string $idempotencyKey): Response
    {
        $corpo = json_encode($pedido, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
        return Http::withHeaders($this->headers('POST', '/v1/emissoes', $corpo) + ['Idempotency-Key' => $idempotencyKey])
            ->withBody($corpo, 'application/json')   // envia EXATAMENTE a string assinada
            ->timeout(90)                            // órgãos são síncronos e podem demorar
            ->post(config('services.opennota.base') . '/v1/emissoes');
    }

    /** Valida sem emitir (não consome número). */
    public function validar(array $pedido): Response
    {
        $corpo = json_encode($pedido, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
        return Http::withHeaders($this->headers('POST', '/v1/emissoes/validar', $corpo))
            ->withBody($corpo, 'application/json')->timeout(20)
            ->post(config('services.opennota.base') . '/v1/emissoes/validar');
    }

    public function ping(): Response                     { return $this->get('/v1/ping'); }
    public function consultar(string $id): Response       { return $this->get("/v1/emissoes/{$id}"); }
    public function xml(string $id): Response             { return $this->get("/v1/emissoes/{$id}/xml"); }
    public function porReferencia(string $ref): Response
    {
        return $this->get('/v1/emissoes?referenciaExterna=' . rawurlencode($ref));
    }
}

Na query, assine o path já codificado (o mesmo texto que vai na URL). rawurlencode dos dois lados resolve.

Prova do signer (antes de chamar a API)#

Com o segredo de teste 0123456789abcdef0123456789abcdef (só para este teste), timestamp 1788200000, nonce 11111111-1111-4111-8111-111111111111, GET /v1/ping, corpo vazio:

mensagem:  1788200000.11111111-1111-4111-8111-111111111111.GET./v1/ping.
assinatura: sha256=b8eac8d2bd190ea28ef83881ede730d94a29eb5605d072a9c183de6a9aa649ed

printf '%s' '1788200000.11111111-1111-4111-8111-111111111111.GET./v1/ping.' \
  | openssl dgst -sha256 -hmac '0123456789abcdef0123456789abcdef' | sed 's/^.* //'

curl#

BASE=https://api.opennota.com.br; KEY='<key_id>'; SECRET='<segredo>'   # segredo vem do cofre
TS=$(date +%s); NONCE=$(uuidgen | tr 'A-Z' 'a-z'); P=/v1/ping
SIG=$(printf '%s' "$TS.$NONCE.GET.$P." | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -sS "$BASE$P" -H "X-OpenNota-Key: $KEY" -H "X-OpenNota-Timestamp: $TS" \
  -H "X-OpenNota-Nonce: $NONCE" -H "X-OpenNota-Signature: sha256=$SIG"

GET /v1/ping responde o ambiente da credencial, os emitentes permitidos (com documentos e operações) e as séries daquele ambiente. Use no início do command: se o ping falhar, não percorra a fila.

5. Idempotência — a garantia contra nota duplicada#

Idempotency-Key é obrigatório no POST /v1/emissoes (até 128 caracteres visíveis). Use um valor estável por nota, ex.: fin-3816978-nfcom.

A ordem dos campos do JSON não importa para "mesmo corpo". Com isso, timeout + retentativa não gera nota duplicada (o problema que existia sem idempotência).

6. POST /v1/emissoes — o pedido#

Campos comuns (os três modelos)#

Destinatário completo:

Um destinatário pertence a um emitente: o mesmo codigoExterno em dois emitentes são dois cadastros independentes. A nota guarda uma cópia do destinatário no momento da emissão — mudar o cadastro depois não altera nota emitida.

NFCOM (mensalidade de acesso — modelo 62)#

Exemplo (o mesmo de docs/openapi.json):

{
  "modelo": "NFCOM",
  "emitente": { "cnpj": "11222333000181" },
  "destinatario": {
    "documento": "52998224725", "nome": "Fulano de Tal",
    "email": "fulano@example.com", "telefone": "21999998888",
    "endereco": { "logradouro": "Rua do Teste", "numero": "100", "complemento": "Casa 2",
                  "bairro": "Centro", "ibge": "3304557", "municipio": "Rio de Janeiro",
                  "uf": "RJ", "cep": "20040002" },
    "codigoExterno": "169162"
  },
  "referenciaExterna": "fin-3816978",
  "competencia": "2026-10",
  "vencimento": "2026-10-10",
  "contrato": { "numero": "169162", "inicio": "2026-10-01", "fim": "2026-10-31" },
  "tipoServicoUtilizado": 4,
  "itens": [{ "codigo": "3816978", "descricao": "Plano de acesso a Internet", "cClass": "0400401",
              "unidade": 4, "quantidade": 1, "valorUnitario": 99.9,
              "icms": { "cst": "90", "aliquota": 20, "fcp": 4 }, "fust": 1, "funttel": 0.5 }],
  "fatura": { "codigoBarras": "34191790010104351004791020150008291070026000" }
}

NFSE (serviço com ISS — NFS-e Nacional)#

Para outros serviços, informe o cTribNac e o cTribMun do seu serviço (confirme com a sua contabilidade).

NFE (mercadoria — modelo 55)#

naturezaOperacao, tipo (0/1), finalidade (1–4), consumidorFinal, presenca (indPres), destinoOperacao (1 interna · 2 interestadual · 3 exterior), itens[] (codigo, descricao, ncm 8 dígitos, cest, cfop, unidade, quantidade, valorUnitario, icms com cst OU csosn, ipi, pis.cst, cofins.cst), transporte.modalidade (9 = sem frete), pagamento[] (tPag 90 = sem pagamento, para remessa) e referencias[] (chaves de NF-e). Regras conferidas: CFOP coerente com tipo e destino (saída interna começa com 5, interestadual com 6…), soma dos pagamentos = total dos itens (exceto tPag 90), DV das chaves referenciadas.

7. Respostas#

Sucesso#

201 — autorizada:

{
  "emissao": {
    "id": "5b2c…", "modelo": "NFCOM", "ambiente": "PRODUCAO", "status": "AUTORIZADA",
    "emitenteCnpj": "…", "destinatarioId": "…", "serie": "2", "numero": "123",
    "chave": "33…", "protocolo": "3…", "valor": 99.9,
    "referenciaExterna": "fin-3816978", "idempotencyKey": "fin-3816978-nfcom",
    "origemFalha": null, "motivo": null,
    "criadaEm": "…", "autorizadaEm": "…",
    "links": { "self": "/v1/emissoes/5b2c…", "xml": "/v1/emissoes/5b2c…/xml" }
  },
  "xml": "<nfcomProc …>…</nfcomProc>"
}

202 — INDETERMINADA: a rede caiu depois de transmitir. O OpenNota consulta o órgão sozinho até ter certeza. Consulte GET /v1/emissoes/{id}; não reenvie com outra chave.

Erros#

Formato único:

{ "erro": { "codigo": "VALIDACAO_LOCAL", "mensagem": "…", "correlationId": "…",
            "origem": "VALIDACAO_LOCAL",
            "campos": [ { "campo": "/destinatario/telefone",
                          "mensagem": "telefone obrigatório na NFCom (NroTermPrinc)",
                          "correcao": "informe DDD + número, só dígitos" } ] } }

Regra de retentativa: só 429, 503 e 202 (consultando) são transitórios. 4xx nunca se repete sem mudar algo. Com a mesma Idempotency-Key, repetir é sempre seguro.

8. Consulta e segunda via#

As notas ficam gravadas no OpenNota (XML autorizado, protocolo, eventos), com guarda legal de 5 anos. A segunda via sai daqui a qualquer momento, mesmo que o seu sistema perca o arquivo.

Cada credencial só enxerga as emissões do próprio cliente, dos emitentes que pode ler e do próprio ambiente (sandbox não vê produção e vice-versa).

9. Limites e regras de uso#

• Rate limit: 10 req/s por credencial e por emitente (rajada de 30).
• 20 falhas de assinatura em 5 min bloqueiam a credencial por 15 min.
• Corpo até 256 KB. Timeout recomendado no cliente: 90 s na emissão, 20 s no resto.
• Segredo só no .env do servidor que chama; nunca em repositório, log, ticket ou e-mail junto com esta documentação.