# VNBR Fiscal API - Documentação Técnica Completa para LLMs e Agentes

> Guia de referência técnica completo contendo especificação de payloads JSON, schemas de entrada/saída, códigos de retorno SEFAZ, regras de validação e rotas da API VNBR (apivns.vnsistemas.com.br).

---

## 1. INFORMAÇÕES DE CONEXÃO E BASE URL
- **Base URL Produção**: `https://apivns.vnsistemas.com.br`
- **Roteador da API**: `https://apivns.vnsistemas.com.br/api`
- **Ambientes SEFAZ Suportados**: `producao` e `homologacao`
- **Fuso Horário Padrão**: `America/Sao_Paulo` (UTC-3)
- **Codificação Obrigatória**: `UTF-8`

---

## 2. AUTENTICAÇÃO OAUTH 2.0

### Gerar Token de Acesso
```http
POST /oauth/token
Host: apivns.vnsistemas.com.br
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "SEU_CLIENT_ID",
  "client_secret": "SEU_CLIENT_SECRET"
}
```

#### Resposta de Sucesso:
```json
{
  "access_token": "e8f3b1409d5c8942b...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "nfe nfce mdfe cte nfse"
}
```

#### Headers para todas as requisições autenticadas:
```http
Authorization: Bearer e8f3b1409d5c8942b...
Content-Type: application/json
X-Empresa-CNPJ: 12345678000190
```

---

## 3. VERIFICAÇÃO DE STATUS SEFAZ (HEALTHCHECK)

### Requisição:
```http
GET /api/status
Authorization: Bearer <token>
X-Empresa-CNPJ: 12345678000190
```

### Resposta:
```json
{
  "status": "online",
  "codigo_status": 107,
  "motivo_status": "Serviço em Operação",
  "uf": "RJ",
  "ambiente": "producao",
  "tempo_resposta_ms": 142
}
```

---

## 4. EMISSÃO DE NFC-E (MODELO 65)

### Endpoint: `POST /api/nfce`

### Exemplo de Payload JSON Completo:
```json
{
  "ambiente": "producao",
  "referencia": "VENDA-PDV-10294",
  "natureza_operacao": "VENDA AO CONSUMIDOR",
  "destinatario": {
    "cpf": "12345678909",
    "nome": "CONSUMIDOR FINAL TESTE",
    "email": "cliente@email.com"
  },
  "itens": [
    {
      "numero_item": 1,
      "codigo": "PRD-001",
      "descricao": "REFRIGERANTE LATA 350ML",
      "ncm": "22021000",
      "cfop": "5102",
      "unidade_comercial": "UN",
      "quantidade_comercial": 2,
      "valor_unitario_comercial": 5.00,
      "valor_bruto": 10.00,
      "icms": {
        "situacao_tributaria": "102",
        "origem": 0
      },
      "pis": {
        "situacao_tributaria": "49"
      },
      "cofins": {
        "situacao_tributaria": "49"
      }
    }
  ],
  "pagamento": {
    "formas_pagamento": [
      {
        "meio_pagamento": "01",
        "valor": 10.00
      }
    ]
  }
}
```

### Resposta de Autorização (200 OK):
```json
{
  "status": "autorizado",
  "codigo_status": 100,
  "motivo_status": "Autorizado o uso da NF-e",
  "chave_acesso": "33260949438010000100650010000000451000000458",
  "numero": 45,
  "serie": 1,
  "protocolo_sefaz": "133260000123456",
  "data_autorizacao": "2026-09-11T18:30:00-03:00",
  "pdf_url": "https://apivns.vnsistemas.com.br/api/nfce/33260949438010000100650010000000451000000458/pdf",
  "xml_url": "https://apivns.vnsistemas.com.br/api/nfce/33260949438010000100650010000000451000000458/xml"
}
```

---

## 5. EMISSÃO DE NF-E (MODELO 55)

### Endpoint: `POST /api/nfe`

### Exemplo de Payload JSON:
```json
{
  "ambiente": "producao",
  "referencia": "PEDIDO-88912",
  "natureza_operacao": "VENDA DE MERCADORIA",
  "destinatario": {
    "cnpj": "98765432000189",
    "razao_social": "EMPRESA COMPRADORA LTDA",
    "indicador_ie": 1,
    "inscricao_estadual": "12345678",
    "endereco": {
      "logradouro": "RUA DO COMERCIO",
      "numero": "100",
      "bairro": "CENTRO",
      "codigo_municipio": "3304102",
      "nome_municipio": "RIO DE JANEIRO",
      "uf": "RJ",
      "cep": "20000000"
    }
  },
  "itens": [
    {
      "numero_item": 1,
      "codigo": "MERC-90",
      "descricao": "PRODUTO INDUSTRIALIZADO X",
      "ncm": "84713012",
      "cfop": "5102",
      "unidade_comercial": "UN",
      "quantidade_comercial": 10,
      "valor_unitario_comercial": 120.00,
      "valor_bruto": 1200.00,
      "icms": {
        "situacao_tributaria": "102",
        "origem": 0
      }
    }
  ],
  "transporte": {
    "modalidade_frete": 9
  },
  "pagamento": {
    "formas_pagamento": [
      {
        "meio_pagamento": "15",
        "valor": 1200.00
      }
    ]
  }
}
```

---

## 6. EMISSÃO DE MDF-E (MODELO 58)

### Endpoint: `POST /api/mdfe`

### Dados Obrigatórios do MDF-e:
- **Percurso**: `uf_ini` (UF de carregamento) e `uf_fim` (UF de descarregamento).
- **Veículo Tração**: `placa`, `uf`, `tara_kg`, `capacidade_kg`.
- **Condutor**: `nome`, `cpf`.
- **Documentos Transportados**: Lista de Chaves de Acesso de NF-e ou CT-e vinculadas.
- **Valores**: `valor_total_carga` e `peso_bruto_total`.

### Encerramento Obrigatório do MDF-e:
```http
POST /api/mdfe/{chave}/encerramento
Content-Type: application/json

{
  "codigo_municipio": "3304102",
  "uf": "RJ"
}
```

---

## 7. CANCELAMENTO DE DOCUMENTOS FISCAIS
- **Prazo SEFAZ**: Até 24 horas após a autorização para NF-e (alguns estados permitem até 7 dias) e até 30 minutos a 2 horas para NFC-e dependendo da UF.
- **Justificativa**: Mínimo de 15 caracteres.

```http
POST /api/nfe/{chave}/cancelamento
Content-Type: application/json

{
  "justificativa": "Cancelamento solicitado pelo comprador devido a cancelamento do pedido de venda"
}
```

---

## 8. CÓDIGOS DE RESPOSTA E STATUS SEFAZ FREQUENTES

| Código cStat | Significado | Ação Recomendada |
|---|---|---|
| **100** | Autorizado o uso do Documento Fiscal | Sucesso! Documento válido e homologado |
| **101** | Cancelamento de Documento Homologado | Sucesso! Documento cancelado na SEFAZ |
| **135** | Evento registrado e vinculado | Sucesso! Evento de CC-e ou cancelamento aceito |
| **107** | Serviço em Operação | SEFAZ online e receptiva |
| **611 / 612** | Existe MDF-e não encerrado para a placa/motorista | Encerrar o manifesto anterior antes de emitir novo |
| **539** | Duplicidade de NF-e com diferença na Chave | Verificar numeração ou consultar chave existente |
| **204** | Duplicidade de NF-e | A nota já foi emitida e autorizada com este número |
| **215** | Falha de schema XML | Verificar campos obrigatórios informados no JSON |

---

## 9. GRADE DE PLANOS & CRÉDITOS

| Pacote | Quantidade de Documentos | Valor Oficial | Expiração |
|---|---|---|---|
| Starter 1K | 1.000 notas | R$ 49,90 | Sem expiração |
| Pro 3K | 3.000 notas | R$ 99,90 | Sem expiração |
| Growth 5K | 5.000 notas | R$ 149,90 | Sem expiração |
| Business 10K | 10.000 notas | R$ 199,90 | Sem expiração |
| Scale 20K | 20.000 notas | R$ 299,90 | Sem expiração |
| Enterprise 50K | 50.000 notas | R$ 499,90 | Sem expiração |
| Mega 100K | 100.000 notas | R$ 799,90 | Sem expiração |
| Ultra 200K | 200.000 notas | R$ 1.299,90 | Sem expiração |

---
*VNBR Fiscal API - Tecnologia de Alta Disponibilidade para Emissão Fiscal SEFAZ Brasil.*