# 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`](/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:

```bash
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):

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

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

```bash
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](03-empresas.md#certificado-digital-a1)):

```bash
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.

```bash
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](08-webhooks.md)):

```bash
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

| Página | Para quê |
|---|---|
| [Conceitos](01-conceitos.md) | conta, empresa, ambiente, `ref`, estados da nota, o que é síncrono e o que não é |
| [Autenticação e limites](02-autenticacao.md) | chave de API, formato de erro, limites por minuto, `X-Request-Id`, paginação |
| [Empresas e certificado](03-empresas.md) | cadastrar CNPJs, enviar o certificado A1, trocar para produção |
| [Produtos](04-produtos.md) | catálogo SKU → NCM/origem, que completa os itens da nota |
| [Emitir NF-e](05-emitir-nfe.md) | todos os campos, reenvio da `ref` e exemplos prontos |
| [Consultar e eventos](06-eventos.md) | consulta, XML/DANFE, cancelamento, carta de correção, inutilização |
| [Modo híbrido de tributação](07-modo-hibrido.md) | informar CFOP, situação tributária e alíquotas por item; o que a plataforma preenche |
| [Webhooks](08-webhooks.md) | avisos assinados de cada mudança de estado |
| [Erros](09-erros.md) | todos os códigos, o que fazer em cada um e as rejeições comuns da SEFAZ |
| [Ir para produção](10-producao.md) | checklist de entrada em produção e boas práticas |
| [Exemplos de código](11-exemplos-de-codigo.md) | integração completa em PHP, Node.js e Python |
| [Referência de endpoints](12-referencia.md) | lista de todas as rotas |
| [Novidades](13-novidades.md) | versão e política de compatibilidade |

> **Importante:** a nota de **produção** tem valor fiscal. Faça todos os testes em homologação e siga o [checklist](10-producao.md) antes de trocar o ambiente.