Documentação Oficial REST API

Visão Geral da API

A Heiser Fiscal API foi desenvolvida para conectar qualquer sistema de frente de caixa (PDV), e-commerce ou ERP aos servidores da Secretaria da Fazenda (SEFAZ) de forma descomplicada, robusta e em alta performance.

URL Base de Produção

https://notas.heiservendas.com/api

Padrão de Comunicação

REST JSON + UTF-8

Modelos Suportados

NF-e (55) & NFC-e (65)

Autenticação

Todas as chamadas aos endpoints privados exigem um Bearer Token gerado via Laravel Sanctum no cabeçalho Authorization.

Headers Obrigatórios

Authorization: Bearer SEU_TOKEN_DE_ACESSO

Content-Type: application/json

Accept: application/json

POST /api/auth/token

Gera um novo token de longa duração enviando as credenciais de e-mail e senha cadastradas na plataforma.

Parâmetros no Body (JSON):

email (string, obrigatório)
password (string, obrigatório)
device_name (string, opcional, ex: "PDV-Caixa-01")

Exemplo de Requisição

curl -X POST https://notas.heiservendas.com/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contato@suaempresa.com",
    "password": "sua_senha_secreta",
    "device_name": "PDV-Caixa-01"
  }'

const res = await fetch('https://notas.heiservendas.com/api/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'contato@suaempresa.com',
    password: 'sua_senha_secreta',
    device_name: 'PDV-Caixa-01'
  })
});
const { token } = await res.json();
console.log('Token Bearer:', token);

$client = new \GuzzleHttp\Client();
$response = $client->post('https://notas.heiservendas.com/api/auth/token', [
    'json' => [
        'email' => 'contato@suaempresa.com',
        'password' => 'sua_senha_secreta'
    ]
]);
$data = json_decode($response->getBody(), true);
$token = $data['token'];

import requests

res = requests.post('https://notas.heiservendas.com/api/auth/token', json={
    'email': 'contato@suaempresa.com',
    'password': 'sua_senha_secreta'
})
token = res.json()['token']

Ciclo de Emissão Assíncrona & Polling

Para garantir que sua frente de caixa nunca trave mesmo quando os servidores da SEFAZ estiverem lentos ou em instabilidade, a Heiser Fiscal API adota a arquitetura de enfileiramento (Redis Queue Workers):

Passo 1: Envio (HTTP 202)

Seu sistema envia a nota para /api/nfce/emitir. A API valida o schema, armazena o pedido e responde em milissegundos com status 202 Accepted e um invoice_id.

Passo 2: Assinatura & SEFAZ

Um worker dedicado assina o XML digitalmente com o certificado A1 da empresa, transmite para o webservice da SEFAZ e armazena o protocolo de autorização ou motivo de rejeição.

Passo 3: Polling ou Webhook

Seu sistema consulta GET /api/invoices/{id} em intervalos de 1 a 2 segundos até o status mudar para authorized ou recebe a notificação via Webhook.

POST /api/empresas

Cadastra ou atualiza os dados cadastrais da empresa emitente (formato compatível com padrão Focus NFe).

Campos Principais

Campo	Tipo	Descrição
cnpj	string(14)	CNPJ do emitente (obrigatório)
razao_social	string	Razão Social registrada na Receita
inscricao_estadual	string	Inscrição Estadual (I.E.)
regime_tributario	int	1: Simples, 2: Simples Excesso, 3: Normal
csc_val	string	Token CSC para NFC-e (obrigatório mod 65)
csc_id	string	Identificador do CSC (ex: "000001")
ambiente	string	"1" = Produção, "2" = Homologação

Payload JSON Exemplo

{
  "cnpj": "66003418000160",
  "razao_social": "GRIFFIN BRAND LTDA",
  "nome_fantasia": "GRIFFIN BRAND",
  "inscricao_estadual": "073258598",
  "regime_tributario": 1,
  "cep": "63430000",
  "logradouro": "RUA SAO JOSE",
  "numero": "1160",
  "bairro": "CENTRO",
  "municipio": "ICO",
  "uf": "CE",
  "codigo_municipio": "2305407",
  "telefone": "85991135249",
  "email": "fiscal@empresa.com",
  "csc_val": "EF98938B4007D2BF3A2298762D97052CB2B5291A",
  "csc_id": "000001",
  "ambiente": "1"
}

POST /api/empresas/{cnpj}/certificado

Faz o upload seguro do Certificado Digital modelo A1 (extensões .pfx ou .p12). O arquivo é criptografado e validado imediatamente.

Formato: multipart/form-data

arquivo: arquivo binário .pfx/.p12
senha: string (senha do certificado digital)

curl -X POST https://notas.heiservendas.com/api/empresas/66003418000160/certificado \
  -H "Authorization: Bearer SEU_TOKEN" \
  -F "arquivo=@/caminho/do/certificado.pfx" \
  -F "senha=senha_do_certificado"

POST /api/nfce/emitir

Inicia a emissão assíncrona da Nota Fiscal de Consumidor Eletrônica (NFC-e modelo 65 para varejo e balcão presencial).

Regras & Validações Essenciais:

Itens: Quantidade, Preço, NCM (8 dígitos), CFOP (iniciando em 5 para operações internas) e CSOSN (ex: 102).
GTIN/EAN: Se não possuir código de barras oficial GS1 (EAN 8, 12, 13 ou 14 dígitos numéricos), envie "SEM GTIN".
Formas de Pagamento: Use "20" para PIX Estático (Chave da Loja / Digitação) ou "17" para PIX Dinâmico.
Consumidor Ceará: Na NFC-e presencial, informe apenas documento e nome. Nunca envie endereço fictício para evitar rejeição.

Exemplo de Payload NFC-e

{
  "cnpj": "66003418000160",
  "data": {
    "numero": 22,
    "serie": 1,
    "natureza_operacao": "VENDA DE MERCADORIA",
    "consumidor_final": 1,
    "presenca_comprador": 1,
    "modalidade_frete": 9,
    "frete": 0.00,
    "desconto": 0.00,
    "troco": 0.00,
    "cliente": {
      "nome": "Consumidor Final",
      "documento": "12345678901"
    },
    "itens": [
      {
        "codigo": "2814",
        "descricao": "LEGGING FIT CECILIA",
        "ncm": "61034300",
        "cfop": "5102",
        "ean": "SEM GTIN",
        "unidade": "UN",
        "quantidade": 1.0,
        "preco_unitario": 79.90,
        "csosn": "102"
      }
    ],
    "pagamento": [
      {
        "forma_pagamento": "20",
        "valor": 79.90
      }
    ]
  },
  "webhook_url": "https://seuerp.com/webhook/fiscal"
}

Retorno Imediato HTTP 202 Accepted:

{
  "success": true,
  "message": "Emissão recebida e enviada para processamento na fila.",
  "invoice_id": 40,
  "status": "processing"
}

POST /api/nfe/emitir

Emissão de Nota Fiscal Eletrônica (NF-e modelo 55 para vendas interestaduais, atacado, PJ ou entrega com endereço completo do destinatário).

O payload da NF-e (55) aceita a mesma estrutura da NFC-e, com o diferencial de que o bloco cliente deve conter os dados de endereço completos (logradouro, numero, bairro, cidade, uf, cep e codigo_municipio).

GET /api/invoices/{id}

Consulta o status em tempo real da nota fiscal transmitida utilizando o invoice_id recebido no momento da emissão.

Status possíveis:

processing Na fila / em transmissão

authorized Autorizada com Sucesso pela SEFAZ

rejected Rejeitada pela SEFAZ (ver xMotivo)

error Erro interno no webservice

Exemplo de Retorno Autorizado (HTTP 200)

{
  "success": true,
  "id": 40,
  "numero": 22,
  "serie": 1,
  "modelo": "65",
  "status": "authorized",
  "chave": "23260966003418000160650010000000221736472186",
  "protocolo": "223260869052550",
  "sefaz_response": {
    "cStat": "100",
    "xMotivo": "Autorizado o uso da NF-e",
    "dhRecbto": "2026-09-29T17:29:43-03:00"
  },
  "xml_autorizado": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48bmZlUHJvYy..."
}

POST /api/nfe/cancelar

Cancela uma NF-e ou NFC-e previamente autorizada dentro do prazo legal permitido pela SEFAZ de sua UF (geralmente 30 minutos a 24 horas).

Parâmetros Obrigatórios:

cnpj: CNPJ do emitente
chave: Chave de 44 dígitos da nota
protocolo: Número do protocolo de autorização
justificativa: Motivo do cancelamento (mínimo 15 caracteres)

{
  "cnpj": "66003418000160",
  "chave": "23260966003418000160650010000000221736472186",
  "protocolo": "223260869052550",
  "justificativa": "Cancelamento solicitado pelo cliente antes da saída da mercadoria"
}

POST /api/nfe/cce

Transmite uma Carta de Correção Eletrônica (CC-e) para corrigir dados permitidos na NF-e modelo 55.

{
  "cnpj": "66003418000160",
  "chave": "23260966003418000160550010000000121736472186",
  "correcao": "Correção de dados do transportador e volume de entrega para 3 caixas",
  "sequencia": 1
}

DANFE em PDF & Cupom 80mm

POST /api/danfe/pdf

Recebe o XML autorizado ou o invoice_id e retorna o binário do arquivo PDF pronto para download ou impressão em folha A4 (NF-e) ou bobina (NFC-e).

GET /invoices/{id}/cupom

Abre uma página HTML otimizada para impressoras térmicas não fiscais de 80mm ou 58mm (POS58, Epson, Bematech, Elgin), já contendo o QR Code oficial da SEFAZ para consulta direta com a câmera do celular.

Tabela de Meios de Pagamento SEFAZ

Conforme a Nota Técnica 2020.006 e Nota Técnica 2023.004, cada meio de pagamento possui regras de validação específicas:

Código (tPag)	Descrição Oficial	Grupo <card>	Rejeição 391?	Recomendação de Uso
01	Dinheiro	Não permitido	Não	Admite campo troco (`vTroco`)
03	Cartão de Crédito	Obrigatório	Sim (se faltar card)	Exige `tpIntegra` (1 ou 2)
04	Cartão de Débito	Obrigatório	Sim (se faltar card)	Exige `tpIntegra` (1 ou 2)
20	PIX Estático (Chave da Loja / Digitação)	Dispensado	Livre de Rejeição	Cliente digita Chave CNPJ no celular ou lê QR Code do balcão.
17	PIX Dinâmico (QR Code via Sistema/TEF)	Obrigatório (NT 2023.004)	Sim (se faltar card)	Exige `tpIntegra: 2` (não integrado) ou `1`
05	Crédito Loja / A Prazo	Não exigido	Não	Crediário próprio / faturamento futuro

Particularidades da SEFAZ Ceará (CE)

1. Dados do Consumidor no Balcão

Na NFC-e presencial no Ceará, a SEFAZ exige estritamente apenas o documento (CPF ou CNPJ) e o nome do destinatário. Não deve ser enviado endereço fictício (como "RUA NÃO INFORMADA"), pois a SEFAZ-CE valida a consistência cadastral.

2. Instrução Normativa SEFAZ-CE nº 87/2025

O Ceará exige a vinculação de pagamentos eletrônicos em operações com TEF, porém os pagamentos via PIX Estático (Código 20) estão expressamente dispensados de vinculação, permitindo operação ágil de balcão.

Principais Códigos de Retorno da SEFAZ (cStat)

cStat	Significado	Ação Recomendada
100	Autorizado o uso da NF-e / NFC-e	Venda autorizada. Imprimir DANFE e entregar ao cliente.
135	Evento registrado e vinculado à NF-e	Cancelamento ou Carta de Correção homologado.
391	Não informados os dados do cartão de crédito/débito	Ocorria se PIX fosse enviado no código 17 sem tags de cartão. Resolvido usando código 20.
539	Duplicidade de NF-e com diferença na Chave de Acesso	O número da nota já foi utilizado anteriormente. Incrementar para o próximo número.
685	Total do Valor Aproximado dos Tributos difere do somatório dos itens	A soma de `vTotTrib` de cada item deve ser idêntica ao `vTotTrib` do total.