# Referência de endpoints

Todos os caminhos são relativos à base `https://srv1839254.hstgr.cloud/api/v2` e exigem a [chave de API](02-autenticacao.md) (a exceção é `GET /openapi.json`). O contrato completo, com todos os campos e esquemas, é o [`/api/v2/openapi.json`](/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](03-empresas.md) |
| `POST` | `/empresas` | Cadastra uma empresa (nasce em homologação) | `201` | [Cadastrar](03-empresas.md#cadastrar-uma-empresa) |
| `GET` | `/empresas/{cnpj}` | Detalha uma empresa | `200` | [Resposta da empresa](03-empresas.md#resposta-da-empresa) |
| `PATCH` | `/empresas/{cnpj}` | Atualiza parcialmente | `200` | [Atualizar](03-empresas.md#atualizar-uma-empresa) |
| `PUT` | `/empresas/{cnpj}/ambiente` | Troca homologação e produção | `200` | [Trocar de ambiente](03-empresas.md#trocar-de-ambiente) |
| `GET` | `/empresas/{cnpj}/series` | Séries da NF-e e o próximo número de cada uma | `200` | [Numeração](03-empresas.md#numeracao-da-nf-e-series-e-proximo-numero) |
| `PUT` | `/empresas/{cnpj}/series/{serie}` | Define o próximo número da série (só para a frente) | `200` | [Numeração](03-empresas.md#numeracao-da-nf-e-series-e-proximo-numero) |
| `GET` | `/empresas/{cnpj}/certificado` | Situação do certificado (nunca o arquivo) | `200` | [Certificado](03-empresas.md#certificado-digital-a1) |
| `PUT` | `/empresas/{cnpj}/certificado` | Envia o certificado A1 | `200` | [Certificado](03-empresas.md#certificado-digital-a1) |
| `DELETE` | `/empresas/{cnpj}/certificado` | Remove o certificado | `200` | [Certificado](03-empresas.md#certificado-digital-a1) |

## Produtos

| Método | Caminho | O que faz | Sucesso | Detalhes |
|---|---|---|---|---|
| `GET` | `/empresas/{cnpj}/produtos` | Lista o catálogo (paginado, filtro `q`) | `200` | [Listar](04-produtos.md#listar) |
| `POST` | `/empresas/{cnpj}/produtos/importacao` | Importa vários (tudo ou nada) | `200` | [Importar](04-produtos.md#importar-varios-de-uma-vez) |
| `GET` | `/empresas/{cnpj}/produtos/{sku}` | Detalha um produto | `200` | [Produtos](04-produtos.md) |
| `PUT` | `/empresas/{cnpj}/produtos/{sku}` | Cria ou substitui (idempotente) | `201` ou `200` | [Criar ou atualizar](04-produtos.md#criar-ou-atualizar-um-produto) |
| `DELETE` | `/empresas/{cnpj}/produtos/{sku}` | Remove | `204` | [Produtos](04-produtos.md) |

## 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](05-emitir-nfe.md) |
| `GET` | `/nfe/{ref}` | Estado da nota, com chave, protocolo, links e eventos | `200` | [Consultar](06-eventos.md#consultar) |
| `DELETE` | `/nfe/{ref}` | Cancela a nota | `202` | [Cancelar](06-eventos.md#cancelar) |
| `POST` | `/nfe/{ref}/carta_correcao` | Carta de correção (CC-e) | `202` | [Carta de correção](06-eventos.md#carta-de-correcao-cc-e) |
| `GET` | `/nfe/{ref}/xml` | XML da nota autorizada | `200` (XML) | [XML e DANFE](06-eventos.md#xml-e-danfe) |
| `GET` | `/nfe/{ref}/danfe` | DANFE em PDF | `200` (PDF) | [XML e DANFE](06-eventos.md#xml-e-danfe) |
| `GET` | `/nfe/{ref}/eventos/{event}/xml` | XML de um evento registrado (`eventos[].id`) | `200` (XML) | [XML e DANFE](06-eventos.md#xml-e-danfe) |
| `POST` | `/nfe/inutilizacao` | Inutiliza uma faixa de numeração | `202` | [Inutilizar](06-eventos.md#inutilizar-numeracao) |
| `GET` | `/nfe/inutilizacoes` | Histórico de inutilizações da empresa | `200` | [Inutilizar](06-eventos.md#inutilizar-numeracao) |
| `GET` | `/nfe/inutilizacoes/{voiding}/xml` | XML de uma inutilização registrada | `200` (XML) | [Inutilizar](06-eventos.md#inutilizar-numeracao) |

## Webhooks

| Método | Caminho | O que faz | Sucesso | Detalhes |
|---|---|---|---|---|
| `GET` | `/webhooks` | Lista os endereços cadastrados | `200` | [Webhooks](08-webhooks.md) |
| `POST` | `/webhooks` | Cadastra um endereço (devolve o `segredo` uma única vez) | `201` | [Cadastrar](08-webhooks.md#cadastrar) |
| `GET` | `/webhooks/{webhook}` | Detalha (o segredo nunca volta) | `200` | [Webhooks](08-webhooks.md) |
| `PATCH` | `/webhooks/{webhook}` | Altera endereço, eventos ou ativação | `200` | [Webhooks](08-webhooks.md) |
| `DELETE` | `/webhooks/{webhook}` | Remove, com o histórico de entregas | `204` | [Webhooks](08-webhooks.md) |
| `POST` | `/webhooks/{webhook}/segredo` | Gera um segredo novo (o antigo morre na hora) | `200` | [Webhooks](08-webhooks.md) |
| `POST` | `/webhooks/{webhook}/teste` | Envia um evento `webhook.teste` | `202` | [Webhooks](08-webhooks.md) |
| `GET` | `/webhooks/{webhook}/entregas` | Histórico de entregas (paginado, filtro `status`) | `200` | [Histórico e reenvio](08-webhooks.md#historico-e-reenvio) |
| `POST` | `/webhooks/{webhook}/entregas/{delivery}/reenviar` | Reenvia uma entrega | `202` | [Histórico e reenvio](08-webhooks.md#historico-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](02-autenticacao.md#x-request-id-e-o-log-de-requisicoes) |
| `GET` | `/openapi.json` | Este contrato, público e sem chave | `200` | [Comece aqui](index.md) |

## 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](08-webhooks.md#confira-a-assinatura-sempre) |

## 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](01-conceitos.md#estados-da-nota). Trate um valor desconhecido como "não final".