> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notasx.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido

> Da Chave de API à primeira NFS-e em homologação, em cinco chamadas.

Tudo aqui acontece em **homologação** (produção restrita da Sefin, sem valor fiscal). Nenhuma Nota tem valor
fiscal até você ativar a produção do Prestador.

Você vai precisar de:

* uma **Chave de API** (`nx_...`);
* o **Certificado A1** (e-CNPJ, arquivo `.pfx`) do Prestador e a senha dele;
* o **código IBGE** do município do Prestador (Natal/RN: `2408102`).

```bash theme={null}
export NOTASX=https://notasx-api.fly.dev
export CHAVE=nx_...   # sua Chave de API
```

**1. Obtenha uma Chave de API**

A primeira Chave é criada com a sessão do painel. Com uma Chave em mãos, você cria outras pela API:

```bash theme={null}
curl -X POST $NOTASX/v1/chaves-api \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{"nome": "erp-homologacao"}'
```

O valor da nova chave (`chave`) aparece **só nesta resposta**. Guarde-o num cofre de segredos.

**2. Cadastre o Prestador**

```bash theme={null}
curl -X POST $NOTASX/v1/prestadores \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{"cnpj": "12345678000195", "codigo_municipio": "2408102", "op_simp_nac": 3}'
```

Guarde o `id`. O Prestador começa em `homologacao` e com `ativo: false`.
`op_simp_nac`: `1` não optante, `2` MEI, `3` ME/EPP do Simples Nacional.

**3. Envie o Certificado A1**

```bash theme={null}
curl -X POST $NOTASX/v1/prestadores/$PRESTADOR/certificado \
  -H "Authorization: Bearer $CHAVE" \
  -F arquivo=@certificado.pfx -F senha='senha-do-pfx'
```

O CNPJ do Certificado tem de ser o do Prestador. Depois disso, o Prestador fica `ativo: true`.

**4. Crie a Nota**

```bash theme={null}
curl -X POST $NOTASX/v1/notas \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-000123" \
  -d '{
    "prestador_id": "'$PRESTADOR'",
    "competencia": "2026-11-11",
    "dados": {"ctrib_nac": "010101", "descricao": "Desenvolvimento de software", "valor_servico": "1500.00"},
    "tomador": {"documento": "11222333000181", "nome": "Cliente Exemplo LTDA"}
  }'
```

A resposta é `202` com a Nota `pendente`. O `Idempotency-Key` protege contra duplicidade: se a chamada
falhar no meio, repita **com a mesma chave**. Veja [Idempotência](https://docs.notasx.com.br/guias/idempotencia.md).

**5. Acompanhe o resultado**

```bash theme={null}
curl $NOTASX/v1/notas/$NOTA -H "Authorization: Bearer $CHAVE"
```

Consulte até o `status` sair de `pendente`/`processando`. Com `emitida`, a NFS-e existe:

```json theme={null}
{
  "status": "emitida",
  "chave_acesso": "24081022242404473000102000000000002426114744866240",
  "numero_nfse": "24"
}
```

O XML oficial fica em `GET /v1/notas/{id}/xml`, que devolve um link válido por 5 minutos.

## Próximos passos

* Entenda os resultados possíveis em [Ciclo da Nota](https://docs.notasx.com.br/conceitos/ciclo-da-nota.md).
* Quando estiver tudo certo, [ative a produção](https://docs.notasx.com.br/conceitos/ambientes.md) do Prestador.
* Trate os erros pelo `codigo`: veja [Erros](https://docs.notasx.com.br/guias/erros.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.