# Emitir Nota Fiscal
`POST /v1/invoices/notas`
**Área:** Notas Fiscais

**Scopes necessários:** `nota.fiscal/write`

Emite uma nota fiscal de serviço avulsa, sem vínculo com cobrança ou assinatura.

A emissão é imediata: o `invoiceTiming` da configuração fiscal vale apenas para as notas geradas a partir de cobranças, não para a avulsa.

Informe em `configId` qual configuração fiscal usar — uma conta pode ter configurações de mais de uma empresa, e a nota sai no CNPJ da configuração escolhida. Liste as disponíveis em `GET /v1/invoices/notas/config`.

O `ref` que você enviar passa a ser o identificador da nota nas demais rotas: consultar, cancelar, reemitir e reenviar. Omitido, a API gera um identificador próprio e o devolve na resposta.

O campo `type` indica o modelo do documento fiscal. O único valor aceito hoje é `NFSE` (nota fiscal de serviço), que também é o assumido quando o campo é omitido — qualquer outro valor retorna 400 com o código `NOTA_TYPE_NOT_SUPPORTED`.

Outros tipos de nota estarão disponíveis em breve. Envie `type` explicitamente desde já: quando cada modelo for liberado, nenhuma alteração no payload será necessária.

O tomador não precisa estar cadastrado. Se o endereço não trouxer `cityCode`, o código IBGE do município é resolvido a partir do CEP — assim como logradouro e bairro, quando faltarem.

A resposta volta com status `PROCESSING`: a prefeitura responde de forma assíncrona. Não há evento de webhook para nota fiscal — acompanhe o desfecho em `GET /v1/invoices/notas/{notaId}`, que passa a `AUTHORIZED` ou a `ERROR` com as mensagens da prefeitura.

Case de uso:

_Como prestador, quero emitir uma nota para um serviço cobrado fora da plataforma, informando apenas o tomador, o valor e a descrição._

### Request body

```json
{
  "configId": "unc_1776888897617_ppwgo7oef",
  "type": "NFSE",
  "amount": 150.00,
  "descricao": "Consultoria em tecnologia da informação",
  "ref": "pedido-2026-0912",
  "customer": {
    "document": "11144477735",
    "name": "Alexandre Souza",
    "email": "alexandre@exemplo.com.br",
    "phone": "5511987654321",
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 5",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityCode": "3550308"
    }
  }
}
```

### Campos do body

**Obrigatórios:** `configId`, `amount`, `descricao`, `customer`, `customer.document`, `customer.name`, `customer.address`, `customer.address.zipCode`, `customer.address.street`, `customer.address.number`, `customer.address.neighborhood`, `customer.address.city`, `customer.address.state`

| Campo | Descrição |
|---|---|
| `configId` | Configuração fiscal, de GET /v1/invoices/notas/config |
| `amount` | Valor do serviço em reais |
| `descricao` | Discriminação do serviço na nota |
| `customer` |  |
| `customer.document` | CPF (11) ou CNPJ (14), apenas dígitos |
| `customer.name` | Nome completo ou razão social do tomador |
| `customer.address` |  |
| `customer.address.zipCode` | 8 dígitos, apenas números |
| `customer.address.street` |  |
| `customer.address.number` |  |
| `customer.address.neighborhood` |  |
| `customer.address.city` |  |
| `customer.address.state` | UF com 2 letras |

**Opcionais**

| Campo | Descrição |
|---|---|
| `type` | Modelo do documento fiscal; único valor aceito hoje, outros tipos em breve. Padrão: NFSE |
| `ref` | Vira o identificador da nota nas demais rotas; se omitida, a API gera uma |
| `customer.email` |  |
| `customer.phone` |  |
| `customer.address.complement` |  |
| `customer.address.cityCode` | Código IBGE; resolvido pelo CEP quando ausente |

### Resposta 200 — 200

```json
{
  "success": true,
  "status": "PROCESSING",
  "ref": "nf_1788101026585_uqaspo7bn",
  "id": "nf_1788101026585_uqaspo7bn",
  "nfStatus": "processando_autorizacao",
  "tipo": "nacional",
  "issuedAt": "2026-08-30T14:43:49.719Z",
  "internalStatus": "PROCESSING"
}
```

### Resposta 400 — 400 - campos obrigatórios

```json
{
    "error": {
        "message": "customer.document, amount, descricao e configId são obrigatórios",
        "code": "MISSING_FIELDS",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

### Resposta 400 — 400 - configuração inválida

```json
{
    "error": {
        "message": "Configuração não encontrada ou desabilitada",
        "code": "NOTA_CONFIG_NOT_FOUND",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/post-emitir-nota-fiscal
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json