# Começando

Este guia leva você da chave de teste até a primeira NF-e autorizada em homologação, sem valor fiscal. Tudo aqui acontece no sandbox: nada vale como nota de verdade, e nada é cobrado.

## 1. Use a chave de teste no endereço do sandbox

Ao contratar a emitza você recebe duas chaves:

| Chave | Endereço | Para quê |
|---|---|---|
| `fsk_test_...` | `https://api-sandbox.emitza.com.br` | Integração e testes. Emite só em homologação. |
| `fsk_live_...` | `https://api.emitza.com.br` | Produção, notas com valor fiscal. |

Cada chave só funciona no seu endereço. Envie a chave no cabeçalho `Authorization` e confira:

```bash
curl https://api-sandbox.emitza.com.br/v1/me \
  -H "Authorization: Bearer $EMITZA_KEY"
```

A resposta traz `"mode": "test"`. Guarde a chave numa variável de ambiente ou num cofre de segredos, nunca no código.

## 2. Cadastre a empresa emitente

```json POST /v1/companies
{
  "cnpj": "11222333000181",
  "ie": "110042490114",
  "crt": 1,
  "legalName": "Calçados Exemplo Indústria Ltda",
  "address": {
    "street": "Rua das Indústrias", "number": "100", "district": "Distrito Industrial",
    "cityName": "Franca", "cityCode": "3516200", "uf": "SP", "zip": "14406000"
  }
}
```

`crt` é o regime: 1 Simples Nacional, 2 Simples com excesso de sublimite, 3 regime normal (Presumido ou Real), 4 MEI. `cityCode` é o código IBGE do município. A resposta traz o `id` da empresa: é o `companyId` de todas as emissões.

## 3. Envie o certificado digital A1

A SEFAZ só aceita nota assinada com o e-CNPJ da empresa. Envie o arquivo `.pfx` em base64 com a senha:

```bash
curl -X PUT https://api-sandbox.emitza.com.br/v1/companies/$COMPANY_ID/certificate \
  -H "Authorization: Bearer $EMITZA_KEY" -H "Content-Type: application/json" \
  -d "{\"pfxBase64\": \"$(base64 -w0 empresa.pfx)\", \"password\": \"$PFX_PASSWORD\"}"
```

A emitza confere se o certificado é do mesmo CNPJ, se está dentro da validade e se é da ICP-Brasil, e guarda o arquivo cifrado. A senha não fica guardada em texto. Antes de vencer, você recebe os webhooks `certificate.expiring` (30, 15 e 7 dias antes).

## 4. Cadastre a série da NF-e

```json POST /v1/companies/{id}/nfe-series
{ "number": 1, "next": 1 }
```

Se a empresa já emitia por outro sistema, use uma série nova ou informe em `next` o próximo número que ainda não foi usado.

## 5. Emita a NF-e

```json POST /v1/nfe
{
  "externalId": "pedido-1234",
  "companyId": "6710a1b2c3d4e5f601234567",
  "operation": "sale",
  "natureOfOperation": "Venda de produção do estabelecimento",
  "recipient": {
    "cnpj": "11444777000161",
    "name": "Loja Exemplo Comércio de Calçados Ltda",
    "ieIndicator": "1",
    "ie": "123456785004",
    "address": {
      "street": "Avenida Paulista", "number": "1000", "district": "Bela Vista",
      "cityName": "São Paulo", "cityCode": "3550308", "uf": "SP", "zip": "01310100"
    }
  },
  "items": [{
    "code": "BOT-COURO-38", "description": "Bota de couro nº 38", "ncm": "64039190",
    "origin": "0", "cfop": "5101", "unit": "PAR", "quantity": "10", "unitPrice": "129.90",
    "taxes": { "icms": { "csosn": "101", "creditRate": "1.25" }, "pis": { "cst": "49" }, "cofins": { "cst": "49" } }
  }],
  "transport": { "mode": "9" },
  "payments": [{ "method": "17" }]
}
```

A resposta chega na hora, com status `202` e `"status": "queued"`. A emitza calcula os impostos (o IBS/CBS inclusive), monta o XML, assina e envia à SEFAZ em segundo plano. Valores decimais vão sempre em texto, com ponto: `"129.90"`.

## 6. Acompanhe o resultado

Consulte a nota até ela sair de `queued`, `sending` ou `pending`:

```bash
curl https://api-sandbox.emitza.com.br/v1/nfe/$NFE_ID -H "Authorization: Bearer $EMITZA_KEY"
```

Em poucos segundos ela fica `authorized`, com `accessKey` (a chave de acesso de 44 dígitos) e `protocol`. Daí:

- `GET /v1/nfe/{id}/danfe` devolve o DANFE em PDF;
- `GET /v1/nfe/{id}/xml` devolve o XML autorizado, que a empresa deve guardar por 5 anos.

Em vez de consultar, prefira receber o resultado por [webhook](../webhooks/).

## Próximos passos

- [Conceitos](../conceitos/): emissão assíncrona, idempotência e erros. Leia antes de ir para produção.
- [Webhooks](../webhooks/): receba o resultado sem consultar.
- [NF-e](../nfe/) e [NFS-e](../nfse/): os detalhes de cada documento.
- [Indo para produção](../producao/): o que conferir antes de trocar a chave.