Referência de endpoints

Todos os caminhos são relativos à base https://srv1839254.hstgr.cloud/api/v2 e exigem a chave de API (a exceção é GET /openapi.json). O contrato completo, com todos os campos e esquemas, é o /api/v2/openapi.json (OpenAPI 3.1).

Nas rotas de nota, {ref} é a ref que você deu à venda. A empresa é informada por cnpj_emitente (no corpo ou na query) e pode ser omitida quando a conta tem uma só. Nas rotas de empresa, {cnpj} aceita máscara.

Empresas

Método Caminho O que faz Sucesso Detalhes
GET /empresas Lista as empresas da conta 200 Empresas
POST /empresas Cadastra uma empresa (nasce em homologação) 201 Cadastrar
GET /empresas/{cnpj} Detalha uma empresa 200 Resposta da empresa
PATCH /empresas/{cnpj} Atualiza parcialmente 200 Atualizar
PUT /empresas/{cnpj}/ambiente Troca homologação e produção 200 Trocar de ambiente
GET /empresas/{cnpj}/series Séries da NF-e e o próximo número de cada uma 200 Numeração
PUT /empresas/{cnpj}/series/{serie} Define o próximo número da série (só para a frente) 200 Numeração
GET /empresas/{cnpj}/certificado Situação do certificado (nunca o arquivo) 200 Certificado
PUT /empresas/{cnpj}/certificado Envia o certificado A1 200 Certificado
DELETE /empresas/{cnpj}/certificado Remove o certificado 200 Certificado

Produtos

Método Caminho O que faz Sucesso Detalhes
GET /empresas/{cnpj}/produtos Lista o catálogo (paginado, filtro q) 200 Listar
POST /empresas/{cnpj}/produtos/importacao Importa vários (tudo ou nada) 200 Importar
GET /empresas/{cnpj}/produtos/{sku} Detalha um produto 200 Produtos
PUT /empresas/{cnpj}/produtos/{sku} Cria ou substitui (idempotente) 201 ou 200 Criar ou atualizar
DELETE /empresas/{cnpj}/produtos/{sku} Remove 204 Produtos

NF-e

Método Caminho O que faz Sucesso Detalhes
POST /nfe?ref={ref} Emite uma NF-e 202 (ou 200 no reenvio igual, já em estado final) Emitir NF-e
GET /nfe/{ref} Estado da nota, com chave, protocolo, links e eventos 200 Consultar
DELETE /nfe/{ref} Cancela a nota 202 Cancelar
POST /nfe/{ref}/carta_correcao Carta de correção (CC-e) 202 Carta de correção
GET /nfe/{ref}/xml XML da nota autorizada 200 (XML) XML e DANFE
GET /nfe/{ref}/danfe DANFE em PDF 200 (PDF) XML e DANFE
GET /nfe/{ref}/eventos/{event}/xml XML de um evento registrado (eventos[].id) 200 (XML) XML e DANFE
POST /nfe/inutilizacao Inutiliza uma faixa de numeração 202 Inutilizar
GET /nfe/inutilizacoes Histórico de inutilizações da empresa 200 Inutilizar
GET /nfe/inutilizacoes/{voiding}/xml XML de uma inutilização registrada 200 (XML) Inutilizar

Webhooks

Método Caminho O que faz Sucesso Detalhes
GET /webhooks Lista os endereços cadastrados 200 Webhooks
POST /webhooks Cadastra um endereço (devolve o segredo uma única vez) 201 Cadastrar
GET /webhooks/{webhook} Detalha (o segredo nunca volta) 200 Webhooks
PATCH /webhooks/{webhook} Altera endereço, eventos ou ativação 200 Webhooks
DELETE /webhooks/{webhook} Remove, com o histórico de entregas 204 Webhooks
POST /webhooks/{webhook}/segredo Gera um segredo novo (o antigo morre na hora) 200 Webhooks
POST /webhooks/{webhook}/teste Envia um evento webhook.teste 202 Webhooks
GET /webhooks/{webhook}/entregas Histórico de entregas (paginado, filtro status) 200 Histórico e reenvio
POST /webhooks/{webhook}/entregas/{delivery}/reenviar Reenvia uma entrega 202 Histórico e reenvio

Operação

Método Caminho O que faz Sucesso Detalhes
GET /requisicoes Log das chamadas da conta (só metadados, 30 dias) 200 X-Request-Id e log
GET /openapi.json Este contrato, público e sem chave 200 Comece aqui

Cabeçalhos

Cabeçalho Sentido Para quê
Authorization: Bearer nfe_... envio a chave de API (ou HTTP Basic com a chave como usuário)
Content-Type: application/json envio em toda chamada com corpo JSON
X-Request-Id resposta identifica a chamada do nosso lado: registre e informe ao suporte
X-RateLimit-Limit, X-RateLimit-Remaining resposta o limite por minuto da chave e quanto resta
Retry-After resposta (429) segundos a esperar antes de repetir
Allow resposta (405) os métodos que a rota aceita
X-Webhook-Id, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature webhook recebido veja Webhooks

Estados da nota (status)

Valor Final? Significado
processando_autorizacao não na fila ou aguardando a SEFAZ
autorizado sim autorizada: tem chave_nfe, protocolo, XML e DANFE
erro_autorizacao não (reenviável) a SEFAZ rejeitou: corrija e reenvie na mesma ref
erro_validacao não (reenviável) parou por uma pendência de cálculo ou cadastro antes da SEFAZ: corrija e reenvie na mesma ref
denegado sim a SEFAZ denegou o uso (problema fiscal do emitente ou do destinatário)
cancelado sim cancelada
inutilizado sim número inutilizado

Detalhes e transições em Conceitos. Trate um valor desconhecido como "não final".