API de NF-e para ERPs: comece aqui#

Esta API emite NF-e (modelo 55) em nome de uma ou várias empresas (CNPJs) e devolve a nota ao seu sistema. Foi desenhada para quem já integrou com serviços como o Focus NFe: você manda os dados da venda em JSON, a plataforma calcula os tributos, assina, envia à SEFAZ e avisa o resultado.

• Base da API: https://srv1839254.hstgr.cloud/api/v2 (troque pelo endereço que você recebeu)
• Formato: JSON em UTF-8, datas em ISO 8601, valores em reais (número, ponto decimal)
• Autenticação: uma chave de API por conta, em Authorization: Bearer nfe_...
• Contrato OpenAPI 3.1: /api/v2/openapi.json, público, para importar no Postman, Insomnia ou num gerador de cliente
• Tudo que fala com a SEFAZ é assíncrono: você recebe 202 e acompanha por consulta ou por webhook

Em 5 minutos#

Os exemplos usam curl. Defina a chave e a base uma vez:

export CHAVE="nfe_SUA_CHAVE_AQUI"
export API="https://srv1839254.hstgr.cloud/api/v2"

1. Confirme que a chave funciona (deve listar as empresas da sua conta, ou uma lista vazia):

curl -s "$API/empresas" -H "Authorization: Bearer $CHAVE"

2. Cadastre a empresa que vai emitir (ela nasce em homologação, sem valor fiscal):

curl -s -X POST "$API/empresas" -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" -d '{
  "cnpj": "11.222.333/0001-81", "razao_social": "LOJA EXEMPLO LTDA", "ie": "111111111111", "regime": "simples",
  "uf": "SP", "municipio": "Sao Paulo", "logradouro": "Rua das Flores", "numero": "100",
  "bairro": "Centro", "cep": "01001-000", "email": "fiscal@loja.exemplo.com.br"
}'

3. Envie o certificado A1 da empresa (detalhes):

curl -s -X PUT "$API/empresas/11222333000181/certificado" -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d "{\"arquivo_certificado_base64\": \"$(base64 -w0 certificado.pfx)\", \"senha_certificado\": \"SENHA_DO_CERTIFICADO\"}"

4. Emita uma nota de teste. A ref é o identificador seu da venda (use o número do pedido): ela garante que repetir a chamada nunca emite duas notas.

curl -s -X POST "$API/nfe?ref=PEDIDO-1001" -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" -d '{
  "nome_destinatario": "Maria da Silva", "cpf_destinatario": "529.982.247-25",
  "logradouro_destinatario": "Av Atlantica", "numero_destinatario": "500", "bairro_destinatario": "Copacabana",
  "municipio_destinatario": "Rio de Janeiro", "codigo_municipio_destinatario": "3304557", "uf_destinatario": "RJ", "cep_destinatario": "22010-000",
  "items": [{ "codigo_produto": "CAMISA-P", "descricao": "Camiseta basica P", "codigo_ncm": "61091000", "icms_origem": 0,
              "quantidade_comercial": 1, "valor_unitario_comercial": 100.00 }],
  "formas_pagamento": [{ "forma_pagamento": "17" }]
}'

A resposta é 202 com "status": "processando_autorizacao".

5. Acompanhe até o estado final (ou receba por webhook):

curl -s "$API/nfe/PEDIDO-1001" -H "Authorization: Bearer $CHAVE"

Quando o status for autorizado, os campos caminho_xml_nota_fiscal e caminho_danfe trazem os links do XML e do PDF. Pronto: a nota de teste foi emitida na SEFAZ de homologação.

Onde está cada assunto#

Importante: a nota de produção tem valor fiscal. Faça todos os testes em homologação e siga o checklist antes de trocar o ambiente.