# NFE.io : Documentação

> Documentação oficial da plataforma NFe.io. Disponível em https://nfe.io/docs

This file contains the full content of the documentation in a single document following the llmstxt.org standard.
## SDKs NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/index.md

# SDKs NFE.io

Esta seção contém a documentação das bibliotecas NFE.io para diferentes linguagens de programação, facilitando a integração e emissão de Notas Fiscais de forma simples e rápida.

## Como Utilizar as Bibliotecas NFE.io

Cada biblioteca possui sua própria documentação detalhada, incluindo instruções de instalação, exemplos de uso e guias para emissão de Notas Fiscais. Para começar, escolha a biblioteca correspondente à linguagem de programação que você está utilizando e siga as instruções fornecidas.


## Bibliotecas Disponíveis

- [Node.js](/desenvolvedores/bibliotecas/nodejs): Biblioteca completa para emissão de Nota Fiscal de Serviço (NFS-e) em Node.js.
- [PHP](/desenvolvedores/bibliotecas/php): Biblioteca completa para emissão de Nota Fiscal de Serviço (NFS-e) em PHP.
- [Ruby](/desenvolvedores/bibliotecas/ruby): Biblioteca completa para emissão de Nota Fiscal de Serviço (NFS-e) em Ruby.

---

## NFE.io SDK v3 - API Reference

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/API/index.md

# NFE.io SDK v3 - API Reference

Complete API reference for the NFE.io Node.js SDK v3.

## Table of Contents

- [Installation](#installation)
- [Client](#client)
  - [Constructor](#constructor)
  - [Configuration](#configuration)
  - [Utility Methods](#utility-methods)
- [Resources](#resources)
  - [Service Invoices](#service-invoices)
  - [Companies](#companies)
  - [Legal People](#legal-people)
  - [Natural People](#natural-people)
  - [Webhooks](#webhooks)
  - [Transportation Invoices (CT-e)](#transportation-invoices-ct-e)
  - [Inbound Product Invoices (NF-e Distribuição)](#inbound-product-invoices-nf-e-distribuição)
  - [Product Invoice Query (Consulta NF-e)](#product-invoice-query-consulta-nf-e)
  - [Consumer Invoice Query (Consulta CFe-SAT)](#consumer-invoice-query-consulta-cfe-sat)
  - [Legal Entity Lookup (Consulta CNPJ)](#legal-entity-lookup-consulta-cnpj)
  - [Natural Person Lookup (Consulta CPF)](#natural-person-lookup-consulta-cpf)
  - [Tax Calculation (Cálculo de Impostos)](#tax-calculation-cálculo-de-impostos)
  - [Tax Codes (Códigos Auxiliares)](#tax-codes-códigos-auxiliares)
  - [Product Invoices (NF-e Emissão)](#product-invoices-nf-e-emissão)
  - [State Taxes (Inscrições Estaduais)](#state-taxes-inscrições-estaduais)
- [Types](#types)
- [Error Handling](#error-handling)
- [Advanced Usage](#advanced-usage)

## Installation

```bash
npm install nfe-io
```

## Client

### Constructor

```typescript
new NfeClient(config: NfeConfig): NfeClient
```

Creates a new NFE.io API client instance.

**Parameters:**

- `config` - Client configuration object

**Configuration Options:**

| Property | Type | Required | Default | Description |
|----------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes* | `process.env.NFE_API_KEY` | NFE.io API key |
| `environment` | `'production' \| 'development'` | No | `'production'` | API environment (both use same endpoint: `https://api.nfe.io/v1`) |
| `baseUrl` | `string` | No | Auto-detected | Custom API base URL |
| `timeout` | `number` | No | `30000` | Request timeout in ms |
| `retryConfig` | `RetryConfig` | No | See below | Retry configuration |

\* API key is required but can be provided via `NFE_API_KEY` environment variable.

**Retry Configuration:**

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `maxRetries` | `number` | `3` | Maximum retry attempts |
| `baseDelay` | `number` | `1000` | Initial delay in ms |
| `maxDelay` | `number` | `30000` | Maximum delay in ms |
| `retryableStatuses` | `number[]` | `[408, 429, 500, 502, 503]` | HTTP status codes to retry |

**Examples:**

```typescript
// Basic usage
const nfe = new NfeClient({
  apiKey: 'your-api-key',
  environment: 'production'
});

// With environment variable
// Set NFE_API_KEY=your-api-key
const nfe = new NfeClient({
  environment: 'production'
});

// Custom configuration
const nfe = new NfeClient({
  apiKey: 'your-api-key',
  timeout: 60000,
  retryConfig: {
    maxRetries: 5,
    baseDelay: 2000,
    maxDelay: 60000
  }
});
```

### Configuration

#### `updateConfig(newConfig: Partial<NfeConfig>): void`

Update client configuration dynamically.

```typescript
nfe.updateConfig({
  environment: 'development',
  timeout: 60000
});
```

#### `setTimeout(timeout: number): void`

Set request timeout in milliseconds. (v2 compatibility)

```typescript
nfe.setTimeout(60000); // 60 seconds
```

#### `setApiKey(apiKey: string): void`

Set or update API key. (v2 compatibility)

```typescript
nfe.setApiKey('new-api-key');
```

#### `getConfig(): Readonly<RequiredNfeConfig>`

Get current client configuration.

```typescript
const config = nfe.getConfig();
console.log('Environment:', config.environment);
```

### Utility Methods

#### `pollUntilComplete<T>(locationUrl: string, options?: PollOptions): Promise<T>`

Poll a resource URL until it completes processing.

**Parameters:**

- `locationUrl` - URL or path to poll
- `options` - Polling configuration
  - `maxAttempts` (default: `30`) - Maximum polling attempts
  - `intervalMs` (default: `2000`) - Delay between attempts in ms

**Returns:** Promise resolving to the completed resource

**Example:**

```typescript
const result = await nfe.serviceInvoices.create(companyId, data);

if (result.status === 'pending') {
  const invoice = await nfe.pollUntilComplete(result.location, {
    maxAttempts: 60,
    intervalMs: 3000
  });
}
```

#### `healthCheck(): Promise<{ status: 'ok' | 'error', details?: any }>`

Check API connectivity and authentication.

```typescript
const health = await nfe.healthCheck();

if (health.status === 'ok') {
  console.log('API connection successful');
} else {
  console.error('API error:', health.details);
}
```

#### `getClientInfo(): ClientInfo`

Get client diagnostic information.

```typescript
const info = nfe.getClientInfo();
console.log('SDK Version:', info.version);
console.log('Node Version:', info.nodeVersion);
console.log('Environment:', info.environment);
```

## Resources

All resources follow a consistent pattern with standard CRUD operations plus resource-specific methods.

### Service Invoices

**Resource:** `nfe.serviceInvoices`

Complete service invoice (NFS-e) operations including creation, retrieval, email delivery, document downloads, and cancellation. Supports both synchronous and asynchronous invoice processing with automatic polling capabilities.

---

#### Core Operations

##### `create(companyId: string, data: ServiceInvoiceData): Promise<ServiceInvoiceCreateResult>`

Create a new service invoice. Returns either a completed invoice (201) or async processing result (202).

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID issuing the invoice |
| `data` | `ServiceInvoiceData` | Invoice data (see structure below) |

**Returns:** `Promise<ServiceInvoiceCreateResult>` - Discriminated union:
- **201 Created (Synchronous)**: Returns complete `ServiceInvoice` with `id`, `number`, `status`
- **202 Accepted (Asynchronous)**: Returns `{ flowStatus, flowMessage?, location? }` for polling

**Invoice Data Structure:**

```typescript
interface ServiceInvoiceData {
  // Required fields
  borrower: {
    federalTaxNumber: number;        // CPF (11 digits) or CNPJ (14 digits)
    name: string;
    email?: string;
    address?: {
      country: string;                // 'BRA'
      postalCode: string;             // CEP: '01310-100'
      street: string;
      number: string;
      additionalInformation?: string;
      district: string;
      city: {
        code: string;                  // IBGE code: '3550308'
        name: string;
      };
      state: string;                   // UF: 'SP'
    };
  };
  cityServiceCode: string;             // Municipal service code
  description: string;                 // Service description
  servicesAmount: number;              // Amount in BRL (e.g., 1500.00)

  // Optional fields
  rpsSerialNumber?: string;            // RPS series
  rpsNumber?: number;                  // RPS number
  issuedOn?: string;                   // ISO date: '2024-01-15'
  deductions?: number;                 // Deductions amount
  discountUnconditioned?: number;      // Unconditional discount
  discountConditioned?: number;        // Conditional discount
  taxes?: {
    retainIss?: boolean;
    iss?: number;
    pis?: number;
    cofins?: number;
    inss?: number;
    ir?: number;
    csll?: number;
  };
}
```

**Examples:**

```typescript
// Example 1: Basic invoice creation (may be sync or async)
const result = await nfe.serviceInvoices.create('company-id', {
  borrower: {
    federalTaxNumber: 12345678901,
    name: 'João da Silva',
    email: 'joao@example.com',
  },
  cityServiceCode: '10677',
  description: 'Consulting services',
  servicesAmount: 1500.00,
});

// Check if synchronous (201) or asynchronous (202)
if ('id' in result) {
  // Synchronous - invoice issued immediately
  console.log('Invoice issued:', result.number);
  console.log('Status:', result.status);
} else {
  // Asynchronous - needs polling
  console.log('Processing:', result.flowStatus);
  console.log('Poll URL:', result.location);
  
  // Use pollUntilComplete or createAndWait instead
  const invoice = await nfe.pollUntilComplete(result.location, {
    intervalMs: 2000,
    timeoutMs: 60000,
  });
  console.log('Invoice issued:', invoice.number);
}

// Example 2: Invoice with full details
const invoice = await nfe.serviceInvoices.create('company-id', {
  borrower: {
    federalTaxNumber: 12345678000190,
    name: 'Acme Corporation',
    email: 'finance@acme.com',
    address: {
      country: 'BRA',
      postalCode: '01310-100',
      street: 'Av. Paulista',
      number: '1578',
      district: 'Bela Vista',
      city: {
        code: '3550308',
        name: 'São Paulo',
      },
      state: 'SP',
    },
  },
  cityServiceCode: '01234',
  description: 'Software development services',
  servicesAmount: 5000.00,
  rpsSerialNumber: 'A',
  rpsNumber: 123,
  deductions: 100.00,
  taxes: {
    retainIss: false,
    iss: 5.0, // 5%
  },
});
```

**Error Handling:**

- `ValidationError` (400): Invalid invoice data
- `AuthenticationError` (401): Invalid API key
- `NotFoundError` (404): Company not found
- `InternalError` (500): Server error

```typescript
try {
  const result = await nfe.serviceInvoices.create(companyId, data);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid data:', error.message);
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  }
}
```

---

##### `createAndWait(companyId: string, data: ServiceInvoiceData, options?: WaitOptions): Promise<ServiceInvoice>`

**⭐ Recommended**: Create invoice with automatic polling for async processing. Simplifies async workflow.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID |
| `data` | `ServiceInvoiceData` | Invoice data |
| `options` | `WaitOptions` | Polling configuration (optional) |

**Wait Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `pollingInterval` | `number` | `2000` | Delay between status checks (ms) |
| `maxWaitTime` | `number` | `60000` | Maximum wait time (ms) |

**Returns:** `Promise<ServiceInvoice>` - Completed invoice with `id`, `number`, `status: 'Issued'`

**Examples:**

```typescript
// Example 1: Simple usage (recommended)
const invoice = await nfe.serviceInvoices.createAndWait('company-id', {
  borrower: {
    federalTaxNumber: 12345678901,
    name: 'João da Silva',
    email: 'joao@example.com',
  },
  cityServiceCode: '10677',
  description: 'Consulting services',
  servicesAmount: 1500.00,
});

console.log('Invoice issued:', invoice.number);
console.log('Status:', invoice.status); // 'Issued'

// Example 2: Custom polling configuration
const invoice = await nfe.serviceInvoices.createAndWait('company-id', data, {
  pollingInterval: 3000,  // Check every 3 seconds
  maxWaitTime: 120000,    // Wait up to 2 minutes
});

// Example 3: With error handling
try {
  const invoice = await nfe.serviceInvoices.createAndWait('company-id', data, {
    maxWaitTime: 60000,
  });
  
  console.log('✅ Invoice issued successfully');
  console.log(`   Number: ${invoice.number}`);
  console.log(`   Amount: R$ ${invoice.servicesAmount}`);
} catch (error) {
  if (error.message.includes('timeout')) {
    console.error('⏱️  Invoice processing timeout - may complete later');
  } else if (error.message.includes('failed')) {
    console.error('❌ Invoice processing failed:', error.message);
  }
}
```

**When to use:**
- ✅ You want immediate invoice results without manual polling
- ✅ You can wait 5-30 seconds for processing
- ✅ Simple workflows where async complexity isn't needed

**When NOT to use:**
- ❌ Background job processing (use `create()` + queue)
- ❌ Batch operations (use `createBatch()`)
- ❌ Need to track processing separately

---

##### `list(companyId: string, options?: ListOptions): Promise<ServiceInvoice[]>`

List service invoices for a company with pagination and filtering.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID |
| `options` | `ListOptions` | Filtering and pagination (optional) |

**List Options:**

| Option | Type | Description |
|--------|------|-------------|
| `pageCount` | `number` | Items per page (default: 25) |
| `pageIndex` | `number` | Page number, 0-indexed (default: 0) |
| `searchPeriod` | `object` | Date range filter |
| `searchPeriod.startDate` | `string` | Start date: 'YYYY-MM-DD' |
| `searchPeriod.endDate` | `string` | End date: 'YYYY-MM-DD' |

**Returns:** `Promise<ServiceInvoice[]>` - Array of invoices

**Examples:**

```typescript
// Example 1: List all (first page)
const invoices = await nfe.serviceInvoices.list('company-id');
console.log(`Found ${invoices.length} invoices`);

// Example 2: Pagination
const page2 = await nfe.serviceInvoices.list('company-id', {
  pageCount: 50,   // 50 per page
  pageIndex: 1,    // Second page (0-indexed)
});

// Example 3: Date filtering
const lastMonth = await nfe.serviceInvoices.list('company-id', {
  searchPeriod: {
    startDate: '2024-01-01',
    endDate: '2024-01-31',
  },
  pageCount: 100,
});

// Example 4: Process all invoices
let pageIndex = 0;
let allInvoices = [];

while (true) {
  const page = await nfe.serviceInvoices.list('company-id', {
    pageCount: 100,
    pageIndex,
  });
  
  allInvoices.push(...page);
  
  if (page.length < 100) break; // Last page
  pageIndex++;
}

console.log(`Total invoices: ${allInvoices.length}`);

// Example 5: Find specific invoices
const recentHighValue = await nfe.serviceInvoices.list('company-id', {
  searchPeriod: {
    startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
      .toISOString()
      .split('T')[0],
    endDate: new Date().toISOString().split('T')[0],
  },
});

const filtered = recentHighValue.filter(inv => inv.servicesAmount > 5000);
console.log(`High-value invoices: ${filtered.length}`);
```

---

##### `retrieve(companyId: string, invoiceId: string): Promise<ServiceInvoice>`

Get a specific service invoice by ID with complete details.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID |
| `invoiceId` | `string` | Invoice ID |

**Returns:** `Promise<ServiceInvoice>` - Complete invoice object

**Examples:**

```typescript
// Example 1: Basic retrieval
const invoice = await nfe.serviceInvoices.retrieve('company-id', 'invoice-id');

console.log('Invoice:', invoice.number);
console.log('Amount:', invoice.servicesAmount);
console.log('Status:', invoice.status);
console.log('Issued:', invoice.issuedOn);

// Example 2: Check invoice details
const invoice = await nfe.serviceInvoices.retrieve('company-id', 'invoice-id');

console.log('Borrower:', invoice.borrower.name);
console.log('Service:', invoice.description);
console.log('Tax Amount:', invoice.taxes?.iss || 0);

// Example 3: Verify invoice exists before operation
async function sendInvoiceIfExists(companyId, invoiceId) {
  try {
    const invoice = await nfe.serviceInvoices.retrieve(companyId, invoiceId);
    
    if (invoice.status === 'Issued') {
      await nfe.serviceInvoices.sendEmail(companyId, invoiceId, {
        emails: [invoice.borrower.email],
      });
      console.log('Email sent successfully');
    } else {
      console.log('Invoice not ready:', invoice.status);
    }
  } catch (error) {
    if (error instanceof NotFoundError) {
      console.error('Invoice not found');
    }
  }
}
```

**Error Handling:**

- `NotFoundError` (404): Invoice or company not found
- `AuthenticationError` (401): Invalid API key

---

##### `getStatus(companyId: string, invoiceId: string): Promise<InvoiceStatus>`

Check invoice processing status (useful for async invoices).

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID |
| `invoiceId` | `string` | Invoice ID |

**Returns:** `Promise<InvoiceStatus>` with:

| Field | Type | Description |
|-------|------|-------------|
| `status` | `string` | Current status (see status values below) |
| `isComplete` | `boolean` | `true` if processing finished (success or failure) |
| `isFailed` | `boolean` | `true` if processing failed |

**Status Values:**

| Status | isComplete | isFailed | Description |
|--------|-----------|----------|-------------|
| `Issued` | `true` | `false` | ✅ Invoice issued successfully |
| `IssueFailed` | `true` | `true` | ❌ Issuance failed |
| `Cancelled` | `true` | `false` | 🚫 Invoice cancelled |
| `CancellationFailed` | `true` | `true` | ❌ Cancellation failed |
| `WaitingSend` | `false` | `false` | ⏳ Pending |
| `WaitingSendAuthorize` | `false` | `false` | ⏳ Awaiting authorization |
| `Processing` | `false` | `false` | ⏳ Processing |

**Examples:**

```typescript
// Example 1: Simple status check
const status = await nfe.serviceInvoices.getStatus('company-id', 'invoice-id');

console.log('Status:', status.status);
console.log('Complete:', status.isComplete ? 'Yes' : 'No');
console.log('Failed:', status.isFailed ? 'Yes' : 'No');

// Example 2: Manual polling loop
async function waitForInvoice(companyId, invoiceId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const status = await nfe.serviceInvoices.getStatus(companyId, invoiceId);
    
    if (status.isComplete) {
      if (status.isFailed) {
        throw new Error(`Invoice processing failed: ${status.status}`);
      }
      
      console.log('Invoice complete:', status.status);
      return await nfe.serviceInvoices.retrieve(companyId, invoiceId);
    }
    
    console.log(`Attempt ${i + 1}: ${status.status}`);
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
  
  throw new Error('Polling timeout');
}

// Example 3: Status-based logic
const status = await nfe.serviceInvoices.getStatus('company-id', 'invoice-id');

if (status.status === 'Issued') {
  console.log('✅ Ready to send email');
  await nfe.serviceInvoices.sendEmail(/* ... */);
} else if (status.isFailed) {
  console.error('❌ Failed:', status.status);
} else {
  console.log('⏳ Still processing:', status.status);
}
```

---

##### `cancel(companyId: string, invoiceId: string): Promise<ServiceInvoice>`

Cancel an issued service invoice.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID |
| `invoiceId` | `string` | Invoice ID to cancel |

**Returns:** `Promise<ServiceInvoice>` - Cancelled invoice with `status: 'Cancelled'`

**Examples:**

```typescript
// Example 1: Simple cancellation
const cancelled = await nfe.serviceInvoices.cancel('company-id', 'invoice-id');
console.log('Status:', cancelled.status); // 'Cancelled'

// Example 2: Conditional cancellation
const invoice = await nfe.serviceInvoices.retrieve('company-id', 'invoice-id');

if (invoice.status === 'Issued') {
  const cancelled = await nfe.serviceInvoices.cancel('company-id', 'invoice-id');
  console.log('✅ Invoice cancelled');
} else {
  console.log('⚠️  Invoice cannot be cancelled:', invoice.status);
}

// Example 3: Batch cancellation with error handling
const invoiceIds = ['id-1', 'id-2', 'id-3'];

for (const invoiceId of invoiceIds) {
  try {
    await nfe.serviceInvoices.cancel('company-id', invoiceId);
    console.log(`✅ Cancelled: ${invoiceId}`);
  } catch (error) {
    if (error instanceof NotFoundError) {
      console.log(`⚠️  Not found: ${invoiceId}`);
    } else {
      console.error(`❌ Error cancelling ${invoiceId}:`, error.message);
    }
  }
}
```

**Error Handling:**

- `NotFoundError` (404): Invoice not found
- `ValidationError` (400): Invoice cannot be cancelled (already cancelled, etc.)

---

#### Email & Downloads

##### `sendEmail(companyId: string, invoiceId: string, options: SendEmailOptions): Promise<void>`

Send invoice via email to specified recipients.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID |
| `invoiceId` | `string` | Invoice ID |
| `options` | `SendEmailOptions` | Email configuration |

**Email Options:**

| Field | Type | Description |
|-------|------|-------------|
| `emails` | `string[]` | Recipient email addresses |

**Examples:**

```typescript
// Example 1: Send to single recipient
await nfe.serviceInvoices.sendEmail('company-id', 'invoice-id', {
  emails: ['client@example.com'],
});

console.log('✅ Email sent');

// Example 2: Send to multiple recipients
await nfe.serviceInvoices.sendEmail('company-id', 'invoice-id', {
  emails: [
    'client@example.com',
    'finance@example.com',
    'accounting@example.com',
  ],
});

// Example 3: Send after invoice creation
const invoice = await nfe.serviceInvoices.createAndWait('company-id', data);

await nfe.serviceInvoices.sendEmail('company-id', invoice.id, {
  emails: [invoice.borrower.email],
});

console.log(`Email sent to ${invoice.borrower.email}`);

// Example 4: Bulk email sending
const invoices = await nfe.serviceInvoices.list('company-id');

for (const invoice of invoices) {
  if (invoice.status === 'Issued' && invoice.borrower.email) {
    try {
      await nfe.serviceInvoices.sendEmail('company-id', invoice.id, {
        emails: [invoice.borrower.email],
      });
      console.log(`✅ Sent: ${invoice.number}`);
    } catch (error) {
      console.error(`❌ Failed ${invoice.number}:`, error.message);
    }
  }
}
```

---

##### `downloadPdf(companyId: string, invoiceId?: string): Promise<Buffer>`

Download invoice PDF. If `invoiceId` is omitted, downloads all invoices as ZIP.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID |
| `invoiceId` | `string` | Invoice ID (optional - omit for bulk ZIP) |

**Returns:** `Promise<Buffer>` - PDF file as Buffer (or ZIP for bulk)

**Examples:**

```typescript

// Example 1: Download single invoice PDF
const pdfBuffer = await nfe.serviceInvoices.downloadPdf('company-id', 'invoice-id');

// Validate PDF signature
if (pdfBuffer.toString('utf8', 0, 4) === '%PDF') {
  console.log('✅ Valid PDF');
}

// Save to file
writeFileSync('invoice.pdf', pdfBuffer);
console.log('Saved invoice.pdf');

// Example 2: Download all invoices as ZIP
const zipBuffer = await nfe.serviceInvoices.downloadPdf('company-id');

writeFileSync(`invoices_${Date.now()}.zip`, zipBuffer);
console.log('Saved ZIP with all invoices');

// Example 3: Download and send via HTTP response (Express)
app.get('/invoice/:id/pdf', async (req, res) => {
  try {
    const pdfBuffer = await nfe.serviceInvoices.downloadPdf(
      req.user.companyId,
      req.params.id
    );
    
    res.setHeader('Content-Type', 'application/pdf');
    res.setHeader('Content-Disposition', `attachment; filename="invoice-${req.params.id}.pdf"`);
    res.send(pdfBuffer);
  } catch (error) {
    res.status(404).json({ error: 'Invoice not found' });
  }
});

// Example 4: Download after creation
const invoice = await nfe.serviceInvoices.createAndWait('company-id', data);

const pdf = await nfe.serviceInvoices.downloadPdf('company-id', invoice.id);
writeFileSync(`invoice_${invoice.number}.pdf`, pdf);
console.log(`Downloaded invoice ${invoice.number}`);
```

**Error Handling:**

- `NotFoundError` (404): Invoice not ready or not found

---

##### `downloadXml(companyId: string, invoiceId?: string): Promise<Buffer>`

Download invoice XML. If `invoiceId` is omitted, downloads all invoices as ZIP.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID |
| `invoiceId` | `string` | Invoice ID (optional - omit for bulk ZIP) |

**Returns:** `Promise<Buffer>` - XML file as Buffer (or ZIP for bulk)

**Examples:**

```typescript

// Example 1: Download single invoice XML
const xmlBuffer = await nfe.serviceInvoices.downloadXml('company-id', 'invoice-id');

// Convert Buffer to string
const xmlString = xmlBuffer.toString('utf8');
console.log('XML preview:', xmlString.substring(0, 100));

// Validate XML signature
if (xmlString.startsWith('<?xml')) {
  console.log('✅ Valid XML');
}

// Save to file
writeFileSync('invoice.xml', xmlBuffer);

// Example 2: Download all invoices as ZIP
const zipBuffer = await nfe.serviceInvoices.downloadXml('company-id');
writeFileSync(`invoices_xml_${Date.now()}.zip`, zipBuffer);

// Example 3: Parse XML for integration

const xmlBuffer = await nfe.serviceInvoices.downloadXml('company-id', 'invoice-id');
const xmlString = xmlBuffer.toString('utf8');

parseString(xmlString, (err, result) => {
  if (err) throw err;
  console.log('Parsed XML:', result);
  // Process structured data
});

// Example 4: Bulk download and extract
const zipBuffer = await nfe.serviceInvoices.downloadXml('company-id');
writeFileSync('invoices.zip', zipBuffer);

// Extract ZIP using library like 'adm-zip'
// const AdmZip = require('adm-zip');
// const zip = new AdmZip(zipBuffer);
// zip.extractAllTo('./invoices/', true);
```

---

#### Advanced Operations

##### `createBatch(companyId: string, invoicesData: ServiceInvoiceData[], options?: BatchOptions): Promise<ServiceInvoice[]>`

Create multiple invoices concurrently with concurrency control.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `companyId` | `string` | Company ID |
| `invoicesData` | `ServiceInvoiceData[]` | Array of invoice data |
| `options` | `BatchOptions` | Batch configuration (optional) |

**Batch Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `waitForComplete` | `boolean` | `true` | Wait for all invoices to complete processing |
| `maxConcurrent` | `number` | `5` | Maximum concurrent requests |
| `pollingInterval` | `number` | `2000` | Polling interval in ms (if waitForComplete=true) |
| `maxWaitTime` | `number` | `60000` | Max wait time per invoice in ms |

**Returns:** `Promise<ServiceInvoice[]>` - Array of created invoices

**Examples:**

```typescript
// Example 1: Basic batch creation
const invoicesData = [
  {
    borrower: { federalTaxNumber: 111, name: 'Client 1', email: 'client1@example.com' },
    cityServiceCode: '10677',
    description: 'Service 1',
    servicesAmount: 1000,
  },
  {
    borrower: { federalTaxNumber: 222, name: 'Client 2', email: 'client2@example.com' },
    cityServiceCode: '10677',
    description: 'Service 2',
    servicesAmount: 2000,
  },
  {
    borrower: { federalTaxNumber: 333, name: 'Client 3', email: 'client3@example.com' },
    cityServiceCode: '10677',
    description: 'Service 3',
    servicesAmount: 3000,
  },
];

const invoices = await nfe.serviceInvoices.createBatch('company-id', invoicesData);

console.log(`Created ${invoices.length} invoices`);
invoices.forEach(inv => console.log(`- ${inv.number}: R$ ${inv.servicesAmount}`));

// Example 2: Custom concurrency
const invoices = await nfe.serviceInvoices.createBatch('company-id', invoicesData, {
  maxConcurrent: 3,      // Process 3 at a time
  waitForComplete: true, // Wait for all to finish
});

// Example 3: Batch without waiting (fire and forget)
const results = await nfe.serviceInvoices.createBatch('company-id', invoicesData, {
  waitForComplete: false, // Don't wait for async processing
  maxConcurrent: 10,
});

// Results may contain async processing info (location, flowStatus)
results.forEach(result => {
  if ('id' in result) {
    console.log(`Issued: ${result.id}`);
  } else {
    console.log(`Processing: ${result.location}`);
  }
});

// Example 4: Read from CSV and batch create


const csv = readFileSync('invoices.csv', 'utf8');
const records = parse(csv, { columns: true });

const invoicesData = records.map(row => ({
  borrower: {
    federalTaxNumber: parseInt(row.cpf),
    name: row.name,
    email: row.email,
  },
  cityServiceCode: row.serviceCode,
  description: row.description,
  servicesAmount: parseFloat(row.amount),
}));

console.log(`Creating ${invoicesData.length} invoices from CSV...`);

const invoices = await nfe.serviceInvoices.createBatch('company-id', invoicesData, {
  maxConcurrent: 5,
  waitForComplete: true,
});

console.log(`✅ Created ${invoices.length} invoices`);

// Example 5: Error handling in batch
try {
  const invoices = await nfe.serviceInvoices.createBatch('company-id', invoicesData);
  console.log('All succeeded');
} catch (error) {
  console.error('Batch creation failed:', error.message);
  // Note: Some invoices may have been created successfully
  // Check partial results if needed
}
```

**Performance Notes:**

- Default concurrency (5) is safe for most APIs
- Increase `maxConcurrent` carefully to avoid rate limiting
- Large batches (>100 invoices) should be split into chunks
- Use `waitForComplete: false` for background processing

---

#### Type Reference

**ServiceInvoice:**

```typescript
interface ServiceInvoice {
  id: string;
  number?: string;
  status: 'Issued' | 'Cancelled' | 'Processing' | 'IssueFailed';
  flowStatus?: string;
  flowMessage?: string;
  borrower: {
    federalTaxNumber: number;
    name: string;
    email?: string;
    address?: Address;
  };
  cityServiceCode: string;
  description: string;
  servicesAmount: number;
  deductions?: number;
  discountUnconditioned?: number;
  discountConditioned?: number;
  issuedOn?: string;
  rpsSerialNumber?: string;
  rpsNumber?: number;
  taxes?: {
    retainIss?: boolean;
    iss?: number;
    pis?: number;
    cofins?: number;
    inss?: number;
    ir?: number;
    csll?: number;
  };
}
```

---

### Companies

**Resource:** `nfe.companies`

Company management operations including CRUD, certificate management, and search capabilities.

#### Core CRUD Operations

##### `create(data: Omit<Company, 'id' | 'createdOn' | 'modifiedOn'>): Promise<Company>`

Create a new company with automatic CNPJ/CPF validation.

```typescript
const company = await nfe.companies.create({
  federalTaxNumber: 12345678000190, // CNPJ (14 digits) or CPF (11 digits)
  name: 'My Company',
  email: 'company@example.com',
  address: {
    country: 'BRA',
    postalCode: '01310-100',
    street: 'Av. Paulista',
    number: '1000',
    city: {
      code: '3550308',
      name: 'São Paulo'
    },
    state: 'SP'
  }
});
```

##### `list(options?: PaginationOptions): Promise<ListResponse<Company>>`

List companies with pagination.

```typescript
const companies = await nfe.companies.list({
  pageCount: 20,
  pageIndex: 0
});
```

##### `listAll(): Promise<Company[]>`

Get all companies (auto-pagination).

```typescript
// Automatically fetches all pages
const allCompanies = await nfe.companies.listAll();
console.log(`Total: ${allCompanies.length} companies`);
```

##### `listIterator(): AsyncIterableIterator<Company>`

Memory-efficient streaming of companies.

```typescript
// Process companies one at a time
for await (const company of nfe.companies.listIterator()) {
  console.log(company.name);
  // Process company...
}
```

##### `retrieve(companyId: string): Promise<Company>`

Get a specific company by ID.

```typescript
const company = await nfe.companies.retrieve('company-id');
console.log(company.name);
```

##### `update(companyId: string, data: Partial<Company>): Promise<Company>`

Update company information with validation.

```typescript
const updated = await nfe.companies.update('company-id', {
  name: 'New Company Name',
  email: 'newemail@example.com'
});
```

##### `remove(companyId: string): Promise<{ deleted: boolean; id: string }>`

Delete a company (named `remove` to avoid JS keyword conflict).

```typescript
const result = await nfe.companies.remove('company-id');
console.log(`Deleted: ${result.deleted}`);
```

#### Certificate Management

##### `validateCertificate(file: Buffer, password: string): Promise<CertificateValidationResult>`

Pre-validate a certificate before upload.

```typescript

const certBuffer = await readFile('./certificate.pfx');
const validation = await nfe.companies.validateCertificate(certBuffer, 'password');

if (validation.valid) {
  console.log('Valid until:', validation.metadata?.validTo);
} else {
  console.error('Invalid:', validation.error);
}
```

##### `uploadCertificate(companyId: string, data: CertificateData): Promise<{ uploaded: boolean; message?: string }>`

Upload digital certificate with automatic validation.

```typescript

const certBuffer = await readFile('./certificate.pfx');

const result = await nfe.companies.uploadCertificate('company-id', {
  file: certBuffer,
  password: 'certificate-password',
  filename: 'certificate.pfx' // Optional
});

console.log(result.message);
```

##### `getCertificateStatus(companyId: string): Promise<CertificateStatus>`

Get certificate status with expiration calculation.

```typescript
const status = await nfe.companies.getCertificateStatus('company-id');

console.log('Has certificate:', status.hasCertificate);
console.log('Expires on:', status.expiresOn);
console.log('Days until expiration:', status.daysUntilExpiration);

if (status.isExpiringSoon) {
  console.warn('⚠️  Certificate expiring soon!');
}
```

##### `replaceCertificate(companyId: string, data: CertificateData): Promise<{ uploaded: boolean; message?: string }>`

Replace existing certificate (alias for upload).

```typescript
const result = await nfe.companies.replaceCertificate('company-id', {
  file: newCertBuffer,
  password: 'new-password',
  filename: 'new-certificate.pfx'
});
```

##### `checkCertificateExpiration(companyId: string, thresholdDays?: number): Promise<ExpirationWarning | null>`

Check if certificate is expiring soon.

```typescript
// Check with 30-day threshold (default)
const warning = await nfe.companies.checkCertificateExpiration('company-id', 30);

if (warning) {
  console.warn(`Certificate expiring in ${warning.daysRemaining} days`);
  console.log('Expires on:', warning.expiresOn);
}
```

#### Search & Helper Methods

##### `findByTaxNumber(taxNumber: number): Promise<Company | null>`

Find company by federal tax number (CNPJ or CPF).

```typescript
// Search by CNPJ (14 digits)
const company = await nfe.companies.findByTaxNumber(12345678000190);

// Or by CPF (11 digits)
const company = await nfe.companies.findByTaxNumber(12345678901);

if (company) {
  console.log('Found:', company.name);
} else {
  console.log('Company not found');
}
```

##### `findByName(name: string): Promise<Company[]>`

Find companies by name (case-insensitive partial match).

```typescript
// Find all companies with "Acme" in the name
const companies = await nfe.companies.findByName('Acme');

companies.forEach(company => {
  console.log(`Match: ${company.name}`);
});
```

##### `getCompaniesWithCertificates(): Promise<Company[]>`

Get all companies that have valid certificates.

```typescript
const companiesWithCerts = await nfe.companies.getCompaniesWithCertificates();

console.log(`${companiesWithCerts.length} companies with valid certificates`);
```

##### `getCompaniesWithExpiringCertificates(thresholdDays?: number): Promise<Company[]>`

Get companies with expiring certificates.

```typescript
// Find companies with certificates expiring within 30 days
const expiring = await nfe.companies.getCompaniesWithExpiringCertificates(30);

expiring.forEach(company => {
  console.warn(`⚠️  ${company.name} certificate expiring soon`);
});
```

#### Certificate Validator Utility

The `CertificateValidator` utility can also be used independently:

```typescript

// Check if format is supported
if (CertificateValidator.isSupportedFormat('cert.pfx')) {
  console.log('✓ Supported format');
}

// Calculate days until expiration
const expirationDate = new Date('2026-12-31');
const days = CertificateValidator.getDaysUntilExpiration(expirationDate);
console.log(`Days remaining: ${days}`);

// Check if expiring soon
if (CertificateValidator.isExpiringSoon(expirationDate, 30)) {
  console.warn('Certificate expiring within 30 days!');
}
```

### Legal People

**Resource:** `nfe.legalPeople`

Legal person (PJ/CNPJ) operations, scoped by company.

#### `create(companyId: string, data: Partial<LegalPerson>): Promise<LegalPerson>`

Create a legal person.

```typescript
const legalPerson = await nfe.legalPeople.create('company-id', {
  federalTaxNumber: '12345678000190',
  name: 'Legal Person Company',
  email: 'legal@example.com'
});
```

#### `list(companyId: string, options?: PaginationOptions): Promise<ListResponse<LegalPerson>>`

List legal people for a company.

```typescript
const people = await nfe.legalPeople.list('company-id');
```

#### `retrieve(companyId: string, legalPersonId: string): Promise<LegalPerson>`

Get a specific legal person.

```typescript
const person = await nfe.legalPeople.retrieve('company-id', 'person-id');
```

#### `update(companyId: string, legalPersonId: string, data: Partial<LegalPerson>): Promise<LegalPerson>`

Update legal person information.

```typescript
const updated = await nfe.legalPeople.update('company-id', 'person-id', {
  name: 'Updated Name'
});
```

#### `delete(companyId: string, legalPersonId: string): Promise<void>`

Delete a legal person.

```typescript
await nfe.legalPeople.delete('company-id', 'person-id');
```

#### `findByTaxNumber(companyId: string, cnpj: string): Promise<LegalPerson | null>`

Find legal person by CNPJ.

```typescript
const person = await nfe.legalPeople.findByTaxNumber('company-id', '12345678000190');
```

### Natural People

**Resource:** `nfe.naturalPeople`

Natural person (PF/CPF) operations, scoped by company.

#### `create(companyId: string, data: Partial<NaturalPerson>): Promise<NaturalPerson>`

Create a natural person.

```typescript
const person = await nfe.naturalPeople.create('company-id', {
  federalTaxNumber: '12345678901',
  name: 'John Doe',
  email: 'john@example.com'
});
```

#### `list(companyId: string, options?: PaginationOptions): Promise<ListResponse<NaturalPerson>>`

List natural people for a company.

```typescript
const people = await nfe.naturalPeople.list('company-id');
```

#### `retrieve(companyId: string, personId: string): Promise<NaturalPerson>`

Get a specific natural person.

```typescript
const person = await nfe.naturalPeople.retrieve('company-id', 'person-id');
```

#### `update(companyId: string, personId: string, data: Partial<NaturalPerson>): Promise<NaturalPerson>`

Update natural person information.

```typescript
const updated = await nfe.naturalPeople.update('company-id', 'person-id', {
  name: 'Jane Doe'
});
```

#### `delete(companyId: string, personId: string): Promise<void>`

Delete a natural person.

```typescript
await nfe.naturalPeople.delete('company-id', 'person-id');
```

#### `findByTaxNumber(companyId: string, cpf: string): Promise<NaturalPerson | null>`

Find natural person by CPF.

```typescript
const person = await nfe.naturalPeople.findByTaxNumber('company-id', '12345678901');
```

### Webhooks

**Resource:** `nfe.webhooks`

Webhook configuration and management.

#### `create(data: Partial<Webhook>): Promise<Webhook>`

Create a webhook.

```typescript
const webhook = await nfe.webhooks.create({
  url: 'https://example.com/webhook',
  events: ['invoice.issued', 'invoice.cancelled'],
  secret: 'webhook-secret'
});
```

#### `list(options?: PaginationOptions): Promise<ListResponse<Webhook>>`

List all webhooks.

```typescript
const webhooks = await nfe.webhooks.list();
```

#### `retrieve(webhookId: string): Promise<Webhook>`

Get a specific webhook.

```typescript
const webhook = await nfe.webhooks.retrieve('webhook-id');
```

#### `update(webhookId: string, data: Partial<Webhook>): Promise<Webhook>`

Update webhook configuration.

```typescript
const updated = await nfe.webhooks.update('webhook-id', {
  events: ['invoice.issued', 'invoice.cancelled', 'invoice.error']
});
```

#### `delete(webhookId: string): Promise<void>`

Delete a webhook.

```typescript
await nfe.webhooks.delete('webhook-id');
```

#### `validateSignature(payload: Buffer | string, signature: string | string[] | undefined, secret: string): boolean`

Validate the signature on a webhook delivery from NFE.io.

NFE.io signs every webhook with **`HMAC-SHA1(secret, raw_body_bytes)`**, encoded as hex (uppercase on the wire, compared case-insensitively) and prefixed with **`sha1=`**. The signed value is delivered in the **`X-Hub-Signature`** HTTP header. The method returns `false` (never throws) for any mismatch or malformed input.

> ⚠ **Use raw body bytes.** Re-serializing JSON (`JSON.stringify(req.body)`) does NOT work — property order and whitespace will differ from what NFE.io signed. Use `express.raw()` (or equivalent) so you receive the exact bytes:

```typescript

// Capture the raw body BEFORE any JSON parser
app.post(
  '/webhook',
  express.raw({ type: '*/*' }),
  (req, res) => {
    const ok = nfe.webhooks.validateSignature(
      req.body,                              // Buffer with exact bytes
      req.headers['x-hub-signature'],        // correct header (not "x-nfe-signature")
      process.env.NFE_WEBHOOK_SECRET ?? ''
    );
    if (!ok) return res.status(401).end();

    const event = JSON.parse(req.body.toString('utf8'));
    // process event...
    res.status(204).end();
  }
);
```

#### `test(webhookId: string): Promise<void>`

Test webhook delivery.

```typescript
await nfe.webhooks.test('webhook-id');
```

#### `getAvailableEvents(): Promise<WebhookEvent[]>`

Get list of available webhook event types.

```typescript
const events = await nfe.webhooks.getAvailableEvents();
// ['invoice.issued', 'invoice.cancelled', ...]
```

---

### Transportation Invoices (CT-e)

**Resource:** `nfe.transportationInvoices`

Manage CT-e (Conhecimento de Transporte Eletrônico) documents via SEFAZ Distribuição DFe.

> **Note:** This resource uses a separate API host (`api.nfse.io`). You can configure a specific API key with `dataApiKey`, or the SDK will use `apiKey` as fallback.

**Prerequisites:**
- Company must be registered with a valid A1 digital certificate
- Webhook must be configured to receive CT-e notifications

#### `enable(companyId: string, options?: EnableTransportationInvoiceOptions): Promise<TransportationInvoiceInboundSettings>`

Enable automatic CT-e search for a company.

```typescript
// Enable with default settings
const settings = await nfe.transportationInvoices.enable('company-id');

// Enable starting from a specific NSU
const settings = await nfe.transportationInvoices.enable('company-id', {
  startFromNsu: 12345
});

// Enable starting from a specific date
const settings = await nfe.transportationInvoices.enable('company-id', {
  startFromDate: '2024-01-01T00:00:00Z'
});
```

**Options:**

| Property | Type | Description |
|----------|------|-------------|
| `startFromNsu` | `number` | Start searching from this NSU number |
| `startFromDate` | `string` | Start searching from this date (ISO 8601) |

#### `disable(companyId: string): Promise<TransportationInvoiceInboundSettings>`

Disable automatic CT-e search for a company.

```typescript
const settings = await nfe.transportationInvoices.disable('company-id');
console.log('Status:', settings.status); // 'Disabled'
```

#### `getSettings(companyId: string): Promise<TransportationInvoiceInboundSettings>`

Get current automatic CT-e search settings.

```typescript
const settings = await nfe.transportationInvoices.getSettings('company-id');
console.log('Status:', settings.status);
console.log('Start NSU:', settings.startFromNsu);
console.log('Created:', settings.createdOn);
```

**Response:**

| Property | Type | Description |
|----------|------|-------------|
| `status` | `string` | Current status ('Active', 'Disabled', etc.) |
| `startFromNsu` | `number` | Starting NSU number |
| `startFromDate` | `string` | Starting date (if configured) |
| `createdOn` | `string` | Creation timestamp |
| `modifiedOn` | `string` | Last modification timestamp |

#### `retrieve(companyId: string, accessKey: string): Promise<TransportationInvoiceMetadata>`

Retrieve CT-e metadata by its 44-digit access key.

```typescript
const cte = await nfe.transportationInvoices.retrieve(
  'company-id',
  '35240112345678000190570010000001231234567890'
);
console.log('Sender:', cte.nameSender);
console.log('CNPJ:', cte.federalTaxNumberSender);
console.log('Amount:', cte.totalInvoiceAmount);
console.log('Issued:', cte.issuedOn);
```

**Response:**

| Property | Type | Description |
|----------|------|-------------|
| `accessKey` | `string` | 44-digit access key |
| `type` | `string` | Document type |
| `status` | `string` | Document status |
| `nameSender` | `string` | Sender company name |
| `federalTaxNumberSender` | `string` | Sender CNPJ |
| `totalInvoiceAmount` | `number` | Total invoice amount |
| `issuedOn` | `string` | Issue date |
| `receivedOn` | `string` | Receipt date |

#### `downloadXml(companyId: string, accessKey: string): Promise<string>`

Download CT-e XML content.

```typescript
const xml = await nfe.transportationInvoices.downloadXml(
  'company-id',
  '35240112345678000190570010000001231234567890'
);
fs.writeFileSync('cte.xml', xml);
```

#### `getEvent(companyId: string, accessKey: string, eventKey: string): Promise<TransportationInvoiceMetadata>`

Retrieve CT-e event metadata.

```typescript
const event = await nfe.transportationInvoices.getEvent(
  'company-id',
  '35240112345678000190570010000001231234567890',
  'event-key-123'
);
console.log('Event type:', event.type);
console.log('Event status:', event.status);
```

#### `downloadEventXml(companyId: string, accessKey: string, eventKey: string): Promise<string>`

Download CT-e event XML content.

```typescript
const eventXml = await nfe.transportationInvoices.downloadEventXml(
  'company-id',
  '35240112345678000190570010000001231234567890',
  'event-key-123'
);
fs.writeFileSync('cte-event.xml', eventXml);
```

---

### Inbound Product Invoices (NF-e Distribuição)

**Resource:** `nfe.inboundProductInvoices`

Query NF-e (Nota Fiscal Eletrônica de Produto) documents received via SEFAZ Distribuição NF-e.

> **Note:** This resource uses a separate API host (`api.nfse.io`). You can configure a specific API key with `dataApiKey`, or the SDK will use `apiKey` as fallback.

**Prerequisites:**
- Company must be registered with a valid A1 digital certificate
- Webhook must be configured to receive NF-e notifications

#### `enableAutoFetch(companyId: string, options: EnableInboundOptions): Promise<InboundSettings>`

Enable automatic NF-e inbound fetching for a company.

```typescript
// Enable with production environment and webhook v2
const settings = await nfe.inboundProductInvoices.enableAutoFetch('company-id', {
  environmentSEFAZ: 'Production',
  webhookVersion: '2',
});

// Enable starting from a specific NSU
const settings = await nfe.inboundProductInvoices.enableAutoFetch('company-id', {
  startFromNsu: '999999',
  environmentSEFAZ: 'Production',
});

// Enable with automatic manifesting
const settings = await nfe.inboundProductInvoices.enableAutoFetch('company-id', {
  environmentSEFAZ: 'Production',
  automaticManifesting: { minutesToWaitAwarenessOperation: '30' },
});
```

**Options:**

| Property | Type | Description |
|----------|------|-------------|
| `startFromNsu` | `string` | Start searching from this NSU number |
| `startFromDate` | `string` | Start searching from this date (ISO 8601) |
| `environmentSEFAZ` | `string \| null` | SEFAZ environment ('Production', etc.) |
| `automaticManifesting` | `AutomaticManifesting` | Auto-manifest configuration |
| `webhookVersion` | `string` | Webhook version ('1' or '2') |

#### `disableAutoFetch(companyId: string): Promise<InboundSettings>`

Disable automatic NF-e inbound fetching for a company.

```typescript
const settings = await nfe.inboundProductInvoices.disableAutoFetch('company-id');
console.log('Status:', settings.status); // 'Inactive'
```

#### `getSettings(companyId: string): Promise<InboundSettings>`

Get current automatic NF-e inbound settings.

```typescript
const settings = await nfe.inboundProductInvoices.getSettings('company-id');
console.log('Status:', settings.status);
console.log('Environment:', settings.environmentSEFAZ);
console.log('Webhook version:', settings.webhookVersion);
console.log('Start NSU:', settings.startFromNsu);
```

**Response (`InboundSettings`):**

| Property | Type | Description |
|----------|------|-------------|
| `status` | `string` | Current status ('Active', 'Inactive', etc.) |
| `startFromNsu` | `string` | Starting NSU number |
| `startFromDate` | `string` | Starting date (if configured) |
| `environmentSEFAZ` | `string \| null` | SEFAZ environment |
| `automaticManifesting` | `AutomaticManifesting` | Auto-manifest configuration |
| `webhookVersion` | `string` | Webhook version |
| `companyId` | `string` | Company ID |
| `createdOn` | `string` | Creation timestamp |
| `modifiedOn` | `string` | Last modification timestamp |

#### `getDetails(companyId: string, accessKey: string): Promise<InboundInvoiceMetadata>`

Retrieve NF-e metadata by 44-digit access key (webhook v1 format).

```typescript
const nfeDoc = await nfe.inboundProductInvoices.getDetails(
  'company-id',
  '35240112345678000190550010000001231234567890'
);
console.log('Issuer:', nfeDoc.issuer?.name);
console.log('Amount:', nfeDoc.totalInvoiceAmount);
console.log('Issued:', nfeDoc.issuedOn);
```

#### `getProductInvoiceDetails(companyId: string, accessKey: string): Promise<InboundProductInvoiceMetadata>`

Retrieve NF-e metadata by 44-digit access key (webhook v2 format, recommended).

```typescript
const nfeDoc = await nfe.inboundProductInvoices.getProductInvoiceDetails(
  'company-id',
  '35240112345678000190550010000001231234567890'
);
console.log('Issuer:', nfeDoc.issuer?.name);
console.log('Amount:', nfeDoc.totalInvoiceAmount);
console.log('Product invoices:', nfeDoc.productInvoices?.length);
```

**Response (`InboundInvoiceMetadata` / `InboundProductInvoiceMetadata`):**

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Document ID |
| `accessKey` | `string` | 44-digit access key |
| `nsu` | `string` | NSU number |
| `nfeNumber` | `string` | NF-e number |
| `issuer` | `InboundIssuer` | Issuer information |
| `buyer` | `InboundBuyer` | Buyer information |
| `totalInvoiceAmount` | `string` | Total amount |
| `issuedOn` | `string` | Issue date |
| `description` | `string` | Description |
| `links` | `InboundLinks` | XML/PDF download links |
| `productInvoices` | `InboundProductInvoice[]` | Product invoices (v2 only) |

#### `getEventDetails(companyId: string, accessKey: string, eventKey: string): Promise<InboundInvoiceMetadata>`

Retrieve NF-e event metadata (webhook v1 format).

```typescript
const event = await nfe.inboundProductInvoices.getEventDetails(
  'company-id',
  '35240112345678000190550010000001231234567890',
  'event-key-123'
);
```

#### `getProductInvoiceEventDetails(companyId: string, accessKey: string, eventKey: string): Promise<InboundProductInvoiceMetadata>`

Retrieve NF-e event metadata (webhook v2 format).

```typescript
const event = await nfe.inboundProductInvoices.getProductInvoiceEventDetails(
  'company-id',
  '35240112345678000190550010000001231234567890',
  'event-key-123'
);
```

#### `getXml(companyId: string, accessKey: string): Promise<string>`

Download NF-e XML content.

```typescript
const xml = await nfe.inboundProductInvoices.getXml(
  'company-id',
  '35240112345678000190550010000001231234567890'
);
fs.writeFileSync('nfe.xml', xml);
```

#### `getEventXml(companyId: string, accessKey: string, eventKey: string): Promise<string>`

Download NF-e event XML content.

```typescript
const eventXml = await nfe.inboundProductInvoices.getEventXml(
  'company-id',
  '35240112345678000190550010000001231234567890',
  'event-key-123'
);
fs.writeFileSync('nfe-event.xml', eventXml);
```

#### `getPdf(companyId: string, accessKey: string): Promise<string>`

Download NF-e PDF (DANFE).

```typescript
const pdf = await nfe.inboundProductInvoices.getPdf(
  'company-id',
  '35240112345678000190550010000001231234567890'
);
```

#### `getJson(companyId: string, accessKey: string): Promise<InboundInvoiceMetadata>`

Get NF-e data in JSON format.

```typescript
const json = await nfe.inboundProductInvoices.getJson(
  'company-id',
  '35240112345678000190550010000001231234567890'
);
```

#### `manifest(companyId: string, accessKey: string, tpEvent?: ManifestEventType): Promise<string>`

Send a manifest event for an NF-e. Defaults to `210210` (Ciência da Operação).

```typescript
// Ciência da Operação (default)
await nfe.inboundProductInvoices.manifest(
  'company-id',
  '35240112345678000190550010000001231234567890'
);

// Confirmação da Operação
await nfe.inboundProductInvoices.manifest(
  'company-id',
  '35240112345678000190550010000001231234567890',
  210220
);

// Operação não Realizada
await nfe.inboundProductInvoices.manifest(
  'company-id',
  '35240112345678000190550010000001231234567890',
  210240
);
```

**Manifest Event Types:**

| Code | Event |
|------|-------|
| `210210` | Ciência da Operação (awareness, default) |
| `210220` | Confirmação da Operação (confirmation) |
| `210240` | Operação não Realizada (operation not performed) |

#### `reprocessWebhook(companyId: string, accessKeyOrNsu: string): Promise<InboundProductInvoiceMetadata>`

Reprocess a webhook notification by access key or NSU.

```typescript
// By access key
await nfe.inboundProductInvoices.reprocessWebhook(
  'company-id',
  '35240112345678000190550010000001231234567890'
);

// By NSU
await nfe.inboundProductInvoices.reprocessWebhook(
  'company-id',
  '12345'
);
```

---

### Product Invoice Query (Consulta NF-e)

**Resource:** `nfe.productInvoiceQuery`

Query NF-e (Nota Fiscal Eletrônica) product invoices directly on SEFAZ by access key. This is a read-only resource that does not require company scope.

> **Note:** This resource uses a separate API host (`nfe.api.nfe.io`). You can configure a specific API key with `dataApiKey`, or the SDK will use `apiKey` as fallback.

#### `retrieve(accessKey: string): Promise<ProductInvoiceDetails>`

Retrieve full product invoice details from SEFAZ by access key.

```typescript
const invoice = await nfe.productInvoiceQuery.retrieve(
  '35240112345678000190550010000001231234567890'
);
console.log(invoice.currentStatus); // 'authorized'
console.log(invoice.issuer?.name);
console.log(invoice.totals?.icms?.invoiceAmount);
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `accessKey` | `string` | Yes | 44-digit numeric access key (Chave de Acesso) |

**Returns:** `ProductInvoiceDetails` — Full invoice details including issuer, buyer, items, totals, transport, and payment.

**Throws:**
- `ValidationError` if access key format is invalid
- `NotFoundError` if no invoice matches the access key (HTTP 404)
- `AuthenticationError` if API key is invalid (HTTP 401)

#### `downloadPdf(accessKey: string): Promise<Buffer>`

Download the DANFE PDF for a product invoice.

```typescript
const pdfBuffer = await nfe.productInvoiceQuery.downloadPdf(
  '35240112345678000190550010000001231234567890'
);
fs.writeFileSync('danfe.pdf', pdfBuffer);
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `accessKey` | `string` | Yes | 44-digit numeric access key |

**Returns:** `Buffer` containing the PDF binary content.

#### `downloadXml(accessKey: string): Promise<Buffer>`

Download the raw NF-e XML for a product invoice.

```typescript
const xmlBuffer = await nfe.productInvoiceQuery.downloadXml(
  '35240112345678000190550010000001231234567890'
);
fs.writeFileSync('nfe.xml', xmlBuffer);
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `accessKey` | `string` | Yes | 44-digit numeric access key |

**Returns:** `Buffer` containing the XML binary content.

#### `listEvents(accessKey: string): Promise<ProductInvoiceEventsResponse>`

List fiscal events (cancellations, corrections, manifestations) for a product invoice.

```typescript
const result = await nfe.productInvoiceQuery.listEvents(
  '35240112345678000190550010000001231234567890'
);
for (const event of result.events ?? []) {
  console.log(event.description, event.authorizedOn);
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `accessKey` | `string` | Yes | 44-digit numeric access key |

**Returns:** `ProductInvoiceEventsResponse` with an array of fiscal events and query timestamp.

---

### Consumer Invoice Query (Consulta CFe-SAT)

**Resource:** `nfe.consumerInvoiceQuery`

Query CFe-SAT (Cupom Fiscal Eletrônico) consumer invoices by access key. This is a read-only resource that does not require company scope.

> **Note:** This resource uses a separate API host (`nfe.api.nfe.io`). You can configure a specific API key with `dataApiKey`, or the SDK will use `apiKey` as fallback.

#### `retrieve(accessKey: string): Promise<TaxCoupon>`

Retrieve full CFe-SAT coupon details by access key.

```typescript
const coupon = await nfe.consumerInvoiceQuery.retrieve(
  '35240112345678000190590000000012341234567890'
);
console.log(coupon.currentStatus); // 'Authorized'
console.log(coupon.issuer?.name);
console.log(coupon.totals?.couponAmount);
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `accessKey` | `string` | Yes | 44-digit numeric access key (Chave de Acesso) |

**Returns:** `TaxCoupon` — Full coupon details including issuer, buyer, items, totals, and payment.

**Throws:**
- `ValidationError` if access key format is invalid
- `NotFoundError` if no coupon matches the access key (HTTP 404)
- `AuthenticationError` if API key is invalid (HTTP 401)

#### `downloadXml(accessKey: string): Promise<Buffer>`

Download the raw CFe XML for a consumer invoice.

```typescript
const xmlBuffer = await nfe.consumerInvoiceQuery.downloadXml(
  '35240112345678000190590000000012341234567890'
);
fs.writeFileSync('cfe.xml', xmlBuffer);
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `accessKey` | `string` | Yes | 44-digit numeric access key |

**Returns:** `Buffer` containing the XML binary content.

---

### Legal Entity Lookup (Consulta CNPJ)

**Resource:** `nfe.legalEntityLookup`

Query Brazilian company (CNPJ) data from Receita Federal and state tax registries (SEFAZ). This is a read-only resource that does not require company scope.

> **Note:** This resource uses a separate API host (`legalentity.api.nfe.io`). You can configure a specific API key with `dataApiKey`, or the SDK will use `apiKey` as fallback.

#### `getBasicInfo(federalTaxNumber: string, options?: LegalEntityBasicInfoOptions): Promise<LegalEntityBasicInfoResponse>`

Lookup basic company information by CNPJ from Receita Federal. Returns legal name, trade name, address, phone numbers, economic activities (CNAE), legal nature, partners, and registration status.

```typescript
const result = await nfe.legalEntityLookup.getBasicInfo('12.345.678/0001-90');
console.log(result.legalEntity?.name);       // 'EMPRESA LTDA'
console.log(result.legalEntity?.status);      // 'Active'
console.log(result.legalEntity?.address?.city?.name);

// With options
const result = await nfe.legalEntityLookup.getBasicInfo('12345678000190', {
  updateAddress: false,
  updateCityCode: true,
});
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federalTaxNumber` | `string` | Yes | CNPJ, with or without punctuation (e.g., `"12345678000190"` or `"12.345.678/0001-90"`) |
| `options` | `LegalEntityBasicInfoOptions` | No | Lookup options |

**Options:**

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `updateAddress` | `boolean` | `true` | Update address from postal service data |
| `updateCityCode` | `boolean` | `false` | Update only the city IBGE code when `updateAddress` is `false` |

**Returns:** `LegalEntityBasicInfoResponse` — Company basic information including address, phones, activities, partners.

**Throws:**
- `ValidationError` if CNPJ format is invalid (not 14 digits after stripping punctuation)
- `NotFoundError` if no company found for the given CNPJ (HTTP 404)
- `AuthenticationError` if API key is invalid (HTTP 401)

#### `getStateTaxInfo(state: string, federalTaxNumber: string): Promise<LegalEntityStateTaxResponse>`

Lookup state tax registration (Inscrição Estadual) by CNPJ and state. Returns tax regime, legal nature, and state tax registration details including fiscal document indicators (NFe, NFSe, CTe, NFCe).

```typescript
const result = await nfe.legalEntityLookup.getStateTaxInfo('SP', '12345678000190');
console.log(result.legalEntity?.taxRegime);  // 'SimplesNacional'

for (const tax of result.legalEntity?.stateTaxes ?? []) {
  console.log(`IE: ${tax.taxNumber} — Status: ${tax.status}`);
  console.log(`  NFe: ${tax.nfe?.status}, NFSe: ${tax.nfse?.status}`);
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `state` | `string` | Yes | Brazilian state code (e.g., `"SP"`, `"RJ"`, `"MG"`). Case-insensitive. |
| `federalTaxNumber` | `string` | Yes | CNPJ, with or without punctuation |

**Returns:** `LegalEntityStateTaxResponse` — State tax registration information.

**Throws:**
- `ValidationError` if state code is invalid or CNPJ format is invalid
- `AuthenticationError` if API key is invalid (HTTP 401)

#### `getStateTaxForInvoice(state: string, federalTaxNumber: string): Promise<LegalEntityStateTaxForInvoiceResponse>`

Evaluate state tax registration for invoice issuance. Returns extended status information (including `UnabledTemp`, `UnabledNotConfirmed`) useful for determining whether product invoices (NF-e) can be issued.

```typescript
const result = await nfe.legalEntityLookup.getStateTaxForInvoice('MG', '12345678000190');
for (const tax of result.legalEntity?.stateTaxes ?? []) {
  if (tax.status === 'Abled') {
    console.log(`Can issue invoices with IE: ${tax.taxNumber}`);
  }
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `state` | `string` | Yes | Brazilian state code. Case-insensitive. |
| `federalTaxNumber` | `string` | Yes | CNPJ, with or without punctuation |

**Returns:** `LegalEntityStateTaxForInvoiceResponse` — State tax data with extended status for invoice evaluation.

**Throws:**
- `ValidationError` if state code is invalid or CNPJ format is invalid
- `AuthenticationError` if API key is invalid (HTTP 401)

#### `getSuggestedStateTaxForInvoice(state: string, federalTaxNumber: string): Promise<LegalEntityStateTaxForInvoiceResponse>`

Get the best (suggested) state tax registration for invoice issuance. When multiple registrations are enabled in a state, NFE.io applies evaluation criteria to recommend the optimal IE.

```typescript
const result = await nfe.legalEntityLookup.getSuggestedStateTaxForInvoice('SP', '12345678000190');
const bestIE = result.legalEntity?.stateTaxes?.[0];
if (bestIE) {
  console.log(`Recommended IE: ${bestIE.taxNumber} (${bestIE.status})`);
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `state` | `string` | Yes | Brazilian state code. Case-insensitive. |
| `federalTaxNumber` | `string` | Yes | CNPJ, with or without punctuation |

**Returns:** `LegalEntityStateTaxForInvoiceResponse` — Suggested state tax data prioritized by NFE.io criteria.

**Throws:**
- `ValidationError` if state code is invalid or CNPJ format is invalid
- `AuthenticationError` if API key is invalid (HTTP 401)

#### Types

```typescript
type BrazilianState =
  | 'AC' | 'AL' | 'AM' | 'AP' | 'BA' | 'CE' | 'DF' | 'ES' | 'GO'
  | 'MA' | 'MG' | 'MS' | 'MT' | 'PA' | 'PB' | 'PE' | 'PI' | 'PR'
  | 'RJ' | 'RN' | 'RO' | 'RR' | 'RS' | 'SC' | 'SE' | 'SP' | 'TO'
  | 'EX' | 'NA';

interface LegalEntityBasicInfoOptions {
  updateAddress?: boolean;
  updateCityCode?: boolean;
}

interface LegalEntityBasicInfoResponse {
  legalEntity?: LegalEntityBasicInfo;
}

interface LegalEntityBasicInfo {
  tradeName?: string;
  name?: string;
  federalTaxNumber?: number;
  size?: 'Unknown' | 'ME' | 'EPP' | 'DEMAIS';
  openedOn?: string;
  address?: LegalEntityAddress;
  phones?: LegalEntityPhone[];
  status?: 'Unknown' | 'Active' | 'Suspended' | 'Cancelled' | 'Unabled' | 'Null';
  email?: string;
  shareCapital?: number;
  economicActivities?: LegalEntityEconomicActivity[];
  legalNature?: LegalEntityNature;
  partners?: LegalEntityPartner[];
  unit?: 'Headoffice' | 'Subsidiary';
  // ... and more fields
}

interface LegalEntityStateTaxResponse {
  legalEntity?: LegalEntityStateTaxInfo;
}

interface LegalEntityStateTaxForInvoiceResponse {
  legalEntity?: LegalEntityStateTaxForInvoiceInfo;
}

interface LegalEntityStateTax {
  status?: 'Abled' | 'Unabled' | 'Cancelled' | 'Unknown';
  taxNumber?: string;
  code?: BrazilianState;
  nfe?: LegalEntityFiscalDocumentInfo;
  nfse?: LegalEntityFiscalDocumentInfo;
  cte?: LegalEntityFiscalDocumentInfo;
  nfce?: LegalEntityFiscalDocumentInfo;
  // ... and more fields
}

interface LegalEntityStateTaxForInvoice {
  status?: 'Abled' | 'Unabled' | 'Cancelled' | 'UnabledTemp' | 'UnabledNotConfirmed'
    | 'Unknown' | 'UnknownTemp' | 'UnknownNotConfirmed';
  taxNumber?: string;
  // ... same structure as LegalEntityStateTax with extended status
}
```

> See [src/core/types.ts](../src/core/types.ts) for the complete type definitions.

---

### Natural Person Lookup (Consulta CPF)

**Resource:** `nfe.naturalPersonLookup`
**API Host:** `naturalperson.api.nfe.io`
**Authentication:** Uses `dataApiKey` (falls back to `apiKey`)

Lookup CPF cadastral status (situação cadastral) at the Brazilian Federal Revenue Service (Receita Federal).

#### `getStatus(federalTaxNumber: string, birthDate: string | Date): Promise<NaturalPersonStatusResponse>`

Query the cadastral status of a CPF, returning the person's name, CPF, birth date, status, and query timestamp.

```typescript
// With string date
const result = await nfe.naturalPersonLookup.getStatus('123.456.789-01', '1990-01-15');
console.log(result.name);    // 'JOÃO DA SILVA'
console.log(result.status);  // 'Regular'

// With Date object
const result = await nfe.naturalPersonLookup.getStatus('12345678901', new Date(1990, 0, 15));
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federalTaxNumber` | `string` | Yes | CPF number, with or without punctuation (e.g., `"12345678901"` or `"123.456.789-01"`) |
| `birthDate` | `string \| Date` | Yes | Date of birth in `YYYY-MM-DD` format or a `Date` object |

**Returns:** `NaturalPersonStatusResponse` — CPF cadastral status data.

**Throws:**
- `ValidationError` if CPF format is invalid (not 11 digits) or birth date format is invalid
- `NotFoundError` if CPF is not found or birth date does not match (HTTP 404)
- `AuthenticationError` if API key is invalid (HTTP 401)

#### Types

```typescript
type NaturalPersonStatus =
  | 'Regular'
  | 'Suspensa'
  | 'Cancelada'
  | 'Titular Falecido'
  | 'Pendente de Regularização'
  | 'Nula'
  | (string & {});

interface NaturalPersonStatusResponse {
  name?: string;
  federalTaxNumber: string;
  birthOn?: string;
  status?: NaturalPersonStatus;
  createdOn?: string;
}
```

> See [src/core/types.ts](../src/core/types.ts) for the complete type definitions.

---

### Tax Calculation (Cálculo de Impostos)

**Resource:** `nfe.taxCalculation`
**API Host:** `api.nfse.io`
**Authentication:** Uses `dataApiKey` (falls back to `apiKey`)

Compute all applicable Brazilian taxes (ICMS, ICMS-ST, PIS, COFINS, IPI, II) for product operations using the Tax Calculation Engine (Motor de Cálculo de Tributos).

#### `calculate(tenantId: string, request: CalculateRequest): Promise<CalculateResponse>`

Submit an operation with issuer, recipient, operation type, and product items to compute per-item tax breakdowns.

```typescript
const result = await nfe.taxCalculation.calculate('tenant-id', {
  operationType: 'Outgoing',
  issuer: { state: 'SP', taxRegime: 'RealProfit' },
  recipient: { state: 'RJ' },
  items: [{
    id: 'item-1',
    operationCode: 121,
    origin: 'National',
    ncm: '61091000',
    quantity: 10,
    unitAmount: 100.00
  }]
});

for (const item of result.items ?? []) {
  console.log(`Item ${item.id}: CFOP ${item.cfop}`);
  console.log(`  ICMS CST: ${item.icms?.cst}, value: ${item.icms?.vICMS}`);
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tenantId` | `string` | Yes | Subscription/account ID that scopes the tax rules |
| `request` | `CalculateRequest` | Yes | Tax calculation request payload |

**Returns:** `CalculateResponse` — Per-item tax breakdowns including CFOP, ICMS, PIS, COFINS, IPI, II.

**Throws:**
- `ValidationError` if `tenantId` is empty
- `ValidationError` if required fields are missing (issuer, recipient, operationType, items)
- `AuthenticationError` if API key is invalid (HTTP 401)
- `BadRequestError` if the API rejects the payload (HTTP 400)

#### Types

```typescript
type TaxOperationType = 'Outgoing' | 'Incoming';

type TaxOrigin =
  | 'National' | 'ForeignDirectImport' | 'ForeignInternalMarket'
  | 'NationalWith40To70Import' | 'NationalPpb' | 'NationalWithLess40Import'
  | 'ForeignDirectImportWithoutNationalSimilar'
  | 'ForeignInternalMarketWithoutNationalSimilar'
  | 'NationalWithGreater70Import';

type TaxCalcTaxRegime =
  | 'NationalSimple' | 'RealProfit' | 'PresumedProfit'
  | 'NationalSimpleSublimitExceeded' | 'IndividualMicroEnterprise' | 'Exempt';

interface CalculateRequest {
  collectionId?: string;
  issuer: CalculateRequestIssuer;       // required: state, taxRegime
  recipient: CalculateRequestRecipient; // required: state
  operationType: TaxOperationType;
  items: CalculateItemRequest[];        // required: id, operationCode, origin, quantity, unitAmount
  isProductRegistration?: boolean;
}

interface CalculateResponse {
  items?: CalculateItemResponse[];  // per-item: cfop, icms, pis, cofins, ipi, ii, icmsUfDest
}
```

> See [src/core/types.ts](../src/core/types.ts) for the complete type definitions including all tax component interfaces (TaxIcms, TaxPis, TaxCofins, TaxIpi, TaxIi, TaxIcmsUfDest).

---

### Tax Codes (Códigos Auxiliares)

**Resource:** `nfe.taxCodes`
**API Host:** `api.nfse.io`
**Authentication:** Uses `dataApiKey` (falls back to `apiKey`)

Paginated listings of auxiliary tax code reference tables needed as inputs for the Tax Calculation Engine.

#### `listOperationCodes(options?: TaxCodeListOptions): Promise<TaxCodePaginatedResponse>`

List operation codes (natureza de operação) — e.g., 121 = "Venda de mercadoria".

```typescript
const result = await nfe.taxCodes.listOperationCodes({ pageIndex: 1, pageCount: 20 });
console.log(`Total: ${result.totalCount}, Page ${result.currentPage} of ${result.totalPages}`);
for (const code of result.items ?? []) {
  console.log(`${code.code} - ${code.description}`);
}
```

#### `listAcquisitionPurposes(options?: TaxCodeListOptions): Promise<TaxCodePaginatedResponse>`

List acquisition purposes (finalidade de aquisição).

#### `listIssuerTaxProfiles(options?: TaxCodeListOptions): Promise<TaxCodePaginatedResponse>`

List issuer tax profiles (perfil fiscal do emissor).

#### `listRecipientTaxProfiles(options?: TaxCodeListOptions): Promise<TaxCodePaginatedResponse>`

List recipient tax profiles (perfil fiscal do destinatário).

**All methods accept:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options.pageIndex` | `number` | No | Page index, 1-based (default: 1) |
| `options.pageCount` | `number` | No | Items per page (default: 50) |

**Returns:** `TaxCodePaginatedResponse` — Paginated list of tax codes.

#### Types

```typescript
interface TaxCode {
  code?: string;
  description?: string;
}

interface TaxCodePaginatedResponse {
  items?: TaxCode[];
  currentPage?: number;
  totalPages?: number;
  totalCount?: number;
}

interface TaxCodeListOptions {
  pageIndex?: number;
  pageCount?: number;
}
```

> See [src/core/types.ts](../src/core/types.ts) for the complete type definitions.

---

### Product Invoices (NF-e Emissão)

**Resource:** `nfe.productInvoices`
**API Host:** `api.nfse.io`
**Authentication:** Uses `dataApiKey` (falls back to `apiKey`)

Full lifecycle management for NF-e (Nota Fiscal Eletrônica de Produto) product invoices — issue, list, retrieve, cancel, send correction letters (CC-e), disable invoice numbers, and download files (PDF/XML).

> **Important:** Issue, cancel, correction letter, and disablement operations are asynchronous — they return 202/204 indicating the request was enqueued. Completion is notified via webhooks.

#### `create(companyId, data): Promise<NfeProductInvoiceIssueData>`

Issue a product invoice (NF-e) by posting it to the processing queue.

```typescript
const result = await nfe.productInvoices.create('company-id', {
  operationNature: 'Venda de mercadoria',
  operationType: 'Outgoing',
  buyer: { name: 'Empresa LTDA', federalTaxNumber: 12345678000190 },
  items: [{ code: 'PROD-001', description: 'Produto X', quantity: 1, unitAmount: 100 }],
  payment: [{ paymentDetail: [{ method: 'Cash', amount: 100 }] }],
});
```

#### `createWithStateTax(companyId, stateTaxId, data): Promise<NfeProductInvoiceIssueData>`

Issue an NF-e specifying a particular state tax registration (Inscrição Estadual).

```typescript
const result = await nfe.productInvoices.createWithStateTax('company-id', 'state-tax-id', invoiceData);
```

#### `list(companyId, options): Promise<NfeProductInvoiceListResponse>`

List product invoices with cursor-based pagination. The `environment` option is **required**.

```typescript
const invoices = await nfe.productInvoices.list('company-id', {
  environment: 'Production',   // Required: 'Production' or 'Test'
  limit: 10,                   // Optional (default: 10)
  startingAfter: 'cursor-id',  // Optional: cursor-based pagination
  q: "buyer.name:'EMPRESA'",   // Optional: ElasticSearch query
});
for (const inv of invoices.productInvoices ?? []) {
  console.log(inv.id, inv.status);
}
```

#### `retrieve(companyId, invoiceId): Promise<NfeProductInvoice>`

Retrieve full details of a single NF-e invoice.

```typescript
const invoice = await nfe.productInvoices.retrieve('company-id', 'invoice-id');
console.log(invoice.status, invoice.authorization?.accessKey);
```

#### `cancel(companyId, invoiceId, reason?): Promise<NfeRequestCancellationResource>`

Cancel a product invoice (asynchronous — enqueues for cancellation).

```typescript
const result = await nfe.productInvoices.cancel('company-id', 'invoice-id', 'Erro de digitação');
```

#### `listItems(companyId, invoiceId, options?): Promise<NfeInvoiceItemsResponse>`

List items (products/services) for a specific invoice.

```typescript
const items = await nfe.productInvoices.listItems('company-id', 'invoice-id', { limit: 20 });
```

#### `listEvents(companyId, invoiceId, options?): Promise<NfeProductInvoiceEventsResponse>`

List fiscal events for a specific invoice.

```typescript
const events = await nfe.productInvoices.listEvents('company-id', 'invoice-id');
```

#### `downloadPdf(companyId, invoiceId, force?): Promise<NfeFileResource>`

Get the URL for the DANFE PDF file.

```typescript
const pdf = await nfe.productInvoices.downloadPdf('company-id', 'invoice-id');
console.log('PDF URL:', pdf.uri);

// Force regeneration
const pdfForced = await nfe.productInvoices.downloadPdf('company-id', 'invoice-id', true);
```

#### `downloadXml(companyId, invoiceId): Promise<NfeFileResource>`

Get the URL for the authorized NF-e XML file.

```typescript
const xml = await nfe.productInvoices.downloadXml('company-id', 'invoice-id');
console.log('XML URL:', xml.uri);
```

#### `downloadRejectionXml(companyId, invoiceId): Promise<NfeFileResource>`

Get the URL for the NF-e rejection XML (uses `/xml-rejection` canonical path).

#### `downloadEpecXml(companyId, invoiceId): Promise<NfeFileResource>`

Get the URL for the contingency authorization (EPEC) XML.

#### `sendCorrectionLetter(companyId, invoiceId, reason): Promise<NfeRequestCancellationResource>`

Send a correction letter (Carta de Correção — CC-e). The reason must be 15–1,000 characters.

```typescript
const result = await nfe.productInvoices.sendCorrectionLetter(
  'company-id',
  'invoice-id',
  'Correcao do endereco do destinatario conforme novo cadastro'
);
```

#### `downloadCorrectionLetterPdf(companyId, invoiceId): Promise<NfeFileResource>`

Get the URL for the CC-e DANFE PDF.

#### `downloadCorrectionLetterXml(companyId, invoiceId): Promise<NfeFileResource>`

Get the URL for the CC-e XML.

#### `disable(companyId, invoiceId, reason?): Promise<NfeRequestCancellationResource>`

Disable (inutilizar) a specific product invoice by ID.

```typescript
await nfe.productInvoices.disable('company-id', 'invoice-id', 'Numeração inutilizada');
```

#### `disableRange(companyId, data): Promise<NfeDisablementResource>`

Disable a range of invoice numbers.

```typescript
const result = await nfe.productInvoices.disableRange('company-id', {
  environment: 'Production',
  serie: 1,
  state: 'SP',
  beginNumber: 100,
  lastNumber: 110,
  reason: 'Faixa de numeração inutilizada',
});
```

**Parameters common to sub-list methods (`listItems`, `listEvents`):**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options.limit` | `number` | No | Items per page (default: 10) |
| `options.startingAfter` | `number` | No | Cursor for pagination |

---

### State Taxes (Inscrições Estaduais)

**Resource:** `nfe.stateTaxes`
**API Host:** `api.nfse.io`
**Authentication:** Uses `dataApiKey` (falls back to `apiKey`)

CRUD operations for company state tax registrations (Inscrições Estaduais). State taxes define the series, numbering, environment, and state code configuration required for NF-e issuance.

#### `list(companyId, options?): Promise<NfeStateTaxListResponse>`

List all state tax registrations for a company.

```typescript
const result = await nfe.stateTaxes.list('company-id');
for (const tax of result.stateTaxes ?? []) {
  console.log(tax.id, tax.taxNumber, tax.code, tax.serie, tax.status);
}
```

#### `create(companyId, data): Promise<NfeStateTax>`

Create a new state tax registration. Body is automatically wrapped as `{ stateTax: data }`.

```typescript
const tax = await nfe.stateTaxes.create('company-id', {
  taxNumber: '123456789',
  serie: 1,
  number: 1,
  code: 'sP',
  environmentType: 'production',
  type: 'nFe',
});
console.log('Created:', tax.id);
```

#### `retrieve(companyId, stateTaxId): Promise<NfeStateTax>`

Retrieve a specific state tax registration by ID.

```typescript
const tax = await nfe.stateTaxes.retrieve('company-id', 'state-tax-id');
```

#### `update(companyId, stateTaxId, data): Promise<NfeStateTax>`

Update an existing state tax registration. Body is automatically wrapped as `{ stateTax: data }`.

```typescript
const updated = await nfe.stateTaxes.update('company-id', 'state-tax-id', {
  serie: 2,
  environmentType: 'test',
});
```

#### `delete(companyId, stateTaxId): Promise<void>`

Delete a state tax registration.

```typescript
await nfe.stateTaxes.delete('company-id', 'state-tax-id');
```

#### Types

```typescript
type NfeStateTaxType = 'default' | 'nFe' | 'nFCe';
type NfeStateTaxEnvironmentType = 'none' | 'production' | 'test';
type NfeStateTaxStatus = 'inactive' | 'none' | 'active';

interface NfeStateTax {
  id?: string;
  companyId?: string;
  accountId?: string;
  code?: NfeStateTaxStateCode;
  environmentType?: NfeStateTaxEnvironmentType;
  taxNumber?: string;
  serie?: number;
  number?: number;
  status?: NfeStateTaxStatus;
  specialTaxRegime?: string;
  securityCredential?: NfeStateTaxSecurityCredential;
  type?: NfeStateTaxType;
  series?: NfeStateTaxSeries[];
  batchId?: string;
  createdOn?: string;
  modifiedOn?: string;
}
```

> See [src/core/types.ts](../src/core/types.ts) for the complete type definitions.

---

## Types

### Core Types

```typescript
interface NfeConfig {
  apiKey?: string;
  dataApiKey?: string;     // API key for data/query services (Addresses, CT-e, CNPJ, CPF)
  environment?: 'production' | 'development';
  baseUrl?: string;
  timeout?: number;
  retryConfig?: RetryConfig;
}

interface RetryConfig {
  maxRetries?: number;
  baseDelay?: number;
  maxDelay?: number;
  retryableStatuses?: number[];
}

interface PaginationOptions {
  pageCount?: number;
  pageIndex?: number;
}

interface PollOptions {
  maxAttempts?: number;
  intervalMs?: number;
}

interface ListResponse<T> {
  items: T[];
  totalCount: number;
  pageIndex: number;
  pageCount: number;
}
```

### Entity Types

```typescript
interface Company {
  id: string;
  name: string;
  federalTaxNumber: string;
  email: string;
  address: Address;
  // ... other fields
}

interface ServiceInvoice {
  id: string;
  number?: string;
  status: ServiceInvoiceStatus;
  borrower: ServiceInvoiceBorrower;
  cityServiceCode: string;
  servicesAmount: number;
  // ... other fields
}

interface LegalPerson {
  id: string;
  name: string;
  federalTaxNumber: string; // CNPJ
  email?: string;
  // ... other fields
}

interface NaturalPerson {
  id: string;
  name: string;
  federalTaxNumber: string; // CPF
  email?: string;
  // ... other fields
}

interface Webhook {
  id: string;
  url: string;
  events: string[];
  secret?: string;
  active: boolean;
  // ... other fields
}

interface Address {
  country: string;
  postalCode: string;
  street: string;
  number: string;
  additionalInformation?: string;
  district?: string;
  city: City;
  state: string;
}

interface City {
  code: string;
  name: string;
}

type ServiceInvoiceStatus = 
  | 'pending' 
  | 'issued' 
  | 'cancelled' 
  | 'error';
```

## Error Handling

The SDK uses a comprehensive error hierarchy:

```typescript
import { 
  NfeError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  ServerError,
  ConnectionError,
  TimeoutError,
  PollingTimeoutError,
  isNfeError,
  isAuthenticationError
} from 'nfe-io';
```

### Error Types

| Error Class | HTTP Status | Description |
|-------------|-------------|-------------|
| `AuthenticationError` | 401 | Invalid API key |
| `ValidationError` | 400, 422 | Request validation failed |
| `NotFoundError` | 404 | Resource not found |
| `ConflictError` | 409 | Resource conflict |
| `RateLimitError` | 429 | Rate limit exceeded |
| `ServerError` | 500, 502, 503 | Server error |
| `ConnectionError` | - | Network/connection failure |
| `TimeoutError` | 408 | Request timeout |
| `PollingTimeoutError` | - | Polling exceeded max attempts |

### Error Handling Example

```typescript
import { 
  AuthenticationError, 
  ValidationError, 
  NotFoundError,
  isNfeError 
} from 'nfe-io';

try {
  const invoice = await nfe.serviceInvoices.create(companyId, data);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Validation errors:', error.details);
  } else if (error instanceof NotFoundError) {
    console.error('Company not found');
  } else if (isNfeError(error)) {
    console.error('NFE.io error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

### Error Properties

All NFE.io errors extend `NfeError` and include:

```typescript
class NfeError extends Error {
  type: ErrorType;
  statusCode?: number;
  details?: any;
  requestId?: string;
}
```

## Advanced Usage

### Custom Retry Logic

```typescript
const nfe = new NfeClient({
  apiKey: 'your-api-key',
  retryConfig: {
    maxRetries: 5,
    baseDelay: 2000,
    maxDelay: 60000,
    retryableStatuses: [408, 429, 500, 502, 503, 504]
  }
});
```

### Async Invoice Processing

NFE.io uses async processing for invoices (202 responses). The SDK provides two approaches:

**Manual Polling:**

```typescript
const result = await nfe.serviceInvoices.create(companyId, data);

if (result.status === 'pending') {
  const invoice = await nfe.pollUntilComplete(result.location, {
    maxAttempts: 60,
    intervalMs: 3000
  });
  console.log('Invoice issued:', invoice.number);
} else {
  console.log('Invoice issued immediately:', result.number);
}
```

**Automatic Polling (Recommended):**

```typescript
const invoice = await nfe.serviceInvoices.createAndWait(companyId, data, {
  maxAttempts: 30,
  interval: 2000
});

console.log('Invoice issued:', invoice.number);
```

### Environment Detection

```typescript

// Check environment compatibility
const support = isEnvironmentSupported();
if (!support.supported) {
  console.error('Environment issues:', support.issues);
}

// Get runtime information
const info = getRuntimeInfo();
console.log('SDK Version:', info.sdkVersion);
console.log('Node Version:', info.nodeVersion);
console.log('Platform:', info.platform);
```

### Quick Start Helpers

```typescript

// Create client from environment variable
// Requires NFE_API_KEY environment variable
const nfe = createClientFromEnv('production');

// Validate API key format
const validation = validateApiKeyFormat('my-api-key');
if (!validation.valid) {
  console.error('API key issues:', validation.issues);
}
```

### TypeScript Support

The SDK is fully typed with TypeScript:

```typescript
import type {
  NfeConfig,
  ServiceInvoice,
  ServiceInvoiceData,
  Company,
  LegalPerson,
  NaturalPerson,
  Webhook,
  ListResponse,
  PaginationOptions,
  InboundInvoiceMetadata,
  InboundProductInvoiceMetadata,
  InboundSettings,
  EnableInboundOptions,
  ManifestEventType
} from 'nfe-io';

const config: NfeConfig = {
  apiKey: 'your-api-key',
  environment: 'production'
};

const invoice: ServiceInvoice = await nfe.serviceInvoices.retrieve(
  'company-id',
  'invoice-id'
);
```

## Extension Development

The SDK is designed to be extensible. See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidance on:

- Creating MCP (Model Context Protocol) integrations
- Building n8n workflow nodes
- Developing custom adapters
- Extending the HTTP client

### Example: Custom Resource Extension

```typescript

class CustomResource {
  constructor(private http: HttpClient) {}
  
  async customMethod(id: string): Promise<any> {
    return this.http.get(`/custom/${id}`);
  }
}

// Extend NfeClient

class ExtendedNfeClient extends NfeClient {
  public readonly custom: CustomResource;
  
  constructor(config: NfeConfig) {
    super(config);
    this.custom = new CustomResource(this.http);
  }
}
```

## Support

- **Documentation:** https://nfe.io/docs
- **Repository:** https://github.com/nfe/client-nodejs
- **Issues:** https://github.com/nfe/client-nodejs/issues

## License

MIT License - see [LICENSE](../LICENSE) for details

---

## Emissão assíncrona e polling no SDK Node.js da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/assincrono-e-polling/index.md

# Emissão assíncrona e polling

A emissão fiscal costuma ser **assíncrona**. O SDK expõe isso de duas formas,
dependendo do produto: **polling** (NFS-e) e **webhook-driven** (NF-e/NFC-e).

## Retorno discriminado (NFS-e)

`serviceInvoices.create` (e `serviceInvoicesRtc.create`) devolvem uma união
discriminada pela tag `status`:

```typescript
const r = await nfe.serviceInvoices.create(companyId, data);
if (r.status === 'async') {
  // HTTP 202 — enfileirada
  r.response.invoiceId; // id para reconsultar
  r.response.location;  // header Location
} else {
  // HTTP 201 — já materializada
  r.invoice;            // ServiceInvoiceData
}
```

## createAndWait (polling embutido)

Combina `create` + polling com backoff exponencial e devolve a nota em estado
terminal. Lança `InvoiceProcessingError` em `IssueFailed`/`CancelFailed`.

```typescript
const invoice = await nfe.serviceInvoices.createAndWait(companyId, data, {
  timeout: 120000,     // total, ms (padrão 2 min)
  initialDelay: 1000,  // ms antes do 1º poll
  maxDelay: 10000,     // teto entre polls
  backoffFactor: 1.5,
  onPoll: (attempt, flowStatus) => console.log(attempt, flowStatus),
});
```

`cancelAndWait` faz o mesmo para cancelamento (também assíncrono).

## Estados de `FlowStatus`

| Terminal | Em processamento |
|---|---|
| `Issued`, `IssueFailed`, `Cancelled`, `CancelFailed` | `WaitingCalculateTaxes`, `WaitingDefineRpsNumber`, `WaitingSend`, `WaitingSendCancel`, `WaitingReturn`, `WaitingDownload`, `PullFromCityHall` |

O polling encerra ao atingir um estado **terminal**.

## Webhook-driven (NF-e / NFC-e)

`productInvoices.create`, `productInvoicesRtc.create` e `consumerInvoices.create`
**não fazem polling**: um `202` indica que a nota foi enfileirada e a conclusão
é notificada por **webhook**. Configure webhooks e reaja aos eventos em vez de
consultar em loop.

:::tip Escolha o padrão certo
- NFS-e: `createAndWait` (polling) para um fluxo síncrono simples.
- NF-e/NFC-e: emita e trate a conclusão via [Webhooks](./webhooks.md).
:::

## Próximos passos

- [Webhooks](./webhooks.md)
- [Notas de serviço (NFS-e)](./recursos/service-invoices.md)
- [Emissão RTC](./rtc-emission.md)

---

## Configuração do SDK Node.js da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/configuracao/index.md

# Configuração

O `NfeClient` recebe um objeto `NfeConfig`. Todos os campos são opcionais, mas
ao menos uma chave de API é necessária para a maioria dos recursos.

```typescript

const nfe = new NfeClient({
  apiKey: process.env.NFE_API_KEY,        // chave principal (emissão, empresas, ...)
  dataApiKey: process.env.NFE_DATA_API_KEY, // chave de dados/consulta (opcional)
  environment: 'production',                // 'production' | 'development'
  timeout: 30000,                           // ms
  retryConfig: { maxRetries: 3, baseDelay: 1000, maxDelay: 5000, backoffMultiplier: 2 },
});
```

## Campos

| Campo | Tipo | Descrição |
|---|---|---|
| `apiKey` | `string` | Chave principal: emissão (NFS-e/NF-e/NFC-e), empresas, webhooks, tax-codes. |
| `dataApiKey` | `string` | Chave de dados/consulta: CEP, CNPJ, CPF, CT-e. Faz fallback para `apiKey`. |
| `environment` | `'production' \| 'development'` | Seleciona homologação vs produção. |
| `baseUrl` | `string` | Sobrescreve o host padrão (uso avançado/testes). |
| `timeout` | `number` | Timeout por requisição, em ms. |
| `retryConfig` | `RetryConfig` | `maxRetries`, `baseDelay`, `maxDelay?`, `backoffMultiplier?`. |

:::info Duas chaves, dois escopos
Recursos de **dados/consulta** (endereço, CNPJ, CPF) usam `dataApiKey` (com
fallback para `apiKey`). Os demais usam `apiKey`. Veja
[Roteamento multi-host / multi-chave](./multi-host-routing.md).
:::

## A partir do ambiente

```typescript

// lê NFE_API_KEY (e NFE_DATA_API_KEY, se houver)
const nfe = createClientFromEnv('production');
```

## Reconfigurar em runtime

`updateConfig` reaplica a configuração e **invalida todos os caches** de
recursos e clientes HTTP — nenhuma instância retém host/chave/timeout antigos.

```typescript
nfe.updateConfig({ timeout: 60000 });
```

## Próximos passos

- [Roteamento multi-host / multi-chave](./multi-host-routing.md)
- [Erros](./errors.md) e política de retry
- [Primeiros passos](./getting-started.md)

---

## Downloads de PDF e XML no SDK Node.js da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/downloads-pdf-xml/index.md

# Downloads (PDF/XML)

Os métodos de download retornam um **`Buffer`** com os bytes do arquivo. Passar
o `invoiceId` baixa a nota individual; **omitir** o `invoiceId` baixa um **ZIP**
com todas as notas da empresa (quando o recurso suporta).

```typescript

// PDF individual
const pdf = await nfe.serviceInvoices.downloadPdf(companyId, invoiceId);
writeFileSync('nota.pdf', pdf);

// XML individual
const xml = await nfe.serviceInvoices.downloadXml(companyId, invoiceId);
writeFileSync('nota.xml', xml);

// ZIP de todas as notas da empresa (sem invoiceId)
const zip = await nfe.serviceInvoices.downloadPdf(companyId);
writeFileSync('notas.zip', zip);
```

## Disponibilidade por estado

O PDF/XML só existe após a nota atingir um **estado terminal**
(`Issued`/`Cancelled`). Antes disso, o download pode retornar `404` — use
[polling ou webhooks](./async-and-polling.md) para aguardar a emissão.

## Outros downloads

| Recurso | Métodos |
|---|---|
| `serviceInvoices` | `downloadPdf`, `downloadXml` |
| `serviceInvoicesRtc` | `downloadCancellationXml` (XML do evento de cancelamento) |
| `consumerInvoices` (NFC-e) | `downloadPdf`, `downloadXml`, `downloadRejectionXml` (aceitam `environment`) |
| `productInvoices` | `downloadPdf`, `downloadXml` |
| `productInvoiceQuery` / `consumerInvoiceQuery` | `downloadPdf`/`downloadXml` por chave de acesso |

:::tip Streaming para arquivos grandes
Os métodos carregam o arquivo inteiro em memória (`Buffer`). Para lotes grandes
(ZIP da empresa), considere baixar fora do horário de pico e persistir em disco
logo após o retorno.
:::

## Próximos passos

- [Notas de serviço (NFS-e)](./recursos/service-invoices.md)
- [NFC-e](./recursos/consumer-invoices.md)

---

## Tratamento de erros no SDK Node.js da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/erros/index.md

# Erros

Todos os erros do SDK herdam de **`NfeError`**. Cada classe mapeia um tipo de
falha; use `instanceof` ou os **type guards** para ramificar.

## Hierarquia

| Classe | Quando ocorre |
|---|---|
| `NfeError` | Base de todos os erros do SDK. |
| `ValidationError` | 400 / validação local (inputs inválidos) — lançado **antes** do HTTP quando possível. |
| `AuthenticationError` | 401 (chave inválida/ausente). |
| `NotFoundError` | 404. |
| `ConflictError` | 409. |
| `RateLimitError` | 429 (com informação de retry). |
| `TimeoutError` | Timeout da requisição. |
| `ConnectionError` | Falha de rede/conexão. |
| `ServerError` / `InternalServerError` | 5xx. |
| `InvoiceProcessingError` | Emissão/cancelamento falhou (`IssueFailed`/`CancelFailed`) ou 202 sem `Location`. |
| `PollingTimeoutError` | Polling excedeu o `timeout` sem atingir estado terminal. |
| `ConfigurationError` | Configuração inválida (ex.: recurso sem chave). |

## Type guards

```typescript
import {
  isNfeError, isValidationError, isAuthenticationError,
  isNotFoundError, isTimeoutError, isConnectionError, isPollingTimeoutError,
} from 'nfe-io';

try {
  await nfe.serviceInvoices.createAndWait(companyId, data);
} catch (err) {
  if (isValidationError(err)) {
    // erro de dados — corrija o payload
  } else if (isPollingTimeoutError(err)) {
    // ainda processando — reconsulte depois com retrieve()
  } else if (isNfeError(err)) {
    console.error(err.message);
  } else {
    throw err;
  }
}
```

## Retry

O cliente HTTP repete automaticamente falhas transitórias (rede, 429, 5xx)
conforme o `retryConfig` (`maxRetries`, `baseDelay`, `maxDelay?`,
`backoffMultiplier?`). Erros de validação e 4xx **não** são repetidos.

:::warning POST não é repetido às cegas
Requisições que criam documentos fiscais **não** são repetidas automaticamente.
Em timeouts, reconsulte por `retrieveByExternalId`/`retrieve` (ou reenvie com a
mesma chave de idempotência) para evitar emissão duplicada.
:::

## Próximos passos

- [Configuração](./configuration.md) (retry/timeout)
- [Assíncrono e polling](./async-and-polling.md)

---

## Primeiros passos com o SDK Node.js da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/primeiros-passos/index.md

# Primeiros passos

Este guia cobre a instalação, a criação do cliente e a emissão da sua primeira
nota fiscal de serviço (NFS-e), incluindo o acompanhamento do processamento.

## 1. Instale o pacote

```sh
npm install nfe-io
# ou: pnpm add nfe-io / yarn add nfe-io
```

Requer **Node.js 22+**. O pacote publica ESM e CommonJS com tipos `.d.ts`.

## 2. Crie um cliente

```typescript

const nfe = new NfeClient({
  apiKey: process.env.NFE_API_KEY,
  environment: 'development', // 'development' (homologação) ou 'production'
});
```

Ou a partir do ambiente (lê `NFE_API_KEY`):

```typescript

const nfe = createClientFromEnv('production');
```

## 3. Emita uma NFS-e

```typescript
const result = await nfe.serviceInvoices.create('55df4dc6b6cd9007e4f13ee8', {
  cityServiceCode: '2690',
  description: 'Manutenção e suporte técnico',
  servicesAmount: 100.0,
  borrower: { federalTaxNumber: 191, name: 'Banco do Brasil SA' },
});
```

## 4. Trate o retorno discriminado

`create` devolve uma união discriminada: `{ status: 'async' }` (HTTP 202,
enfileirada) ou `{ status: 'immediate' }` (HTTP 201, já materializada).

```typescript
if (result.status === 'async') {
  console.log('em processamento:', result.response.invoiceId);
  // reconsulte com retrieve(...) ou use createAndWait (passo 5)
} else {
  console.log('emitida:', result.invoice.id, result.invoice.number);
}
```

## 5. Acompanhe até um estado terminal (polling)

Para uma experiência síncrona, `createAndWait` combina `create` + polling com
backoff exponencial e devolve a nota já em estado terminal.

```typescript
const invoice = await nfe.serviceInvoices.createAndWait(
  '55df4dc6b6cd9007e4f13ee8',
  {
    cityServiceCode: '2690',
    description: 'Manutenção e suporte técnico',
    servicesAmount: 100.0,
    borrower: { federalTaxNumber: 191, name: 'Banco do Brasil SA' },
  },
  { timeout: 120000, onPoll: (attempt, status) => console.log(attempt, status) }
);

console.log(invoice.flowStatus); // 'Issued' (ou lança InvoiceProcessingError em 'IssueFailed')
```

:::tip Idempotência em retentativas
O SDK nunca refaz o POST sozinho. Em um timeout de rede, reinvoque `create`
com o mesmo `externalId`/idempotency para o servidor deduplicar e não emitir
documento fiscal duplicado.
:::

## Próximos passos

- [Emissão assíncrona e polling](./async-and-polling.md)
- [Configuração](./configuration.md) (timeout, retry, multi-chave)
- [Erros](./errors.md) e [Webhooks](./webhooks.md)
- Cookbook por recurso em [Recursos](./recursos/)

---

## Biblioteca NFE.io em Node.js para Emissão de Notas Fiscais (NFS-e, NF-e, NFC-e, CT-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/node/index.md

# Biblioteca Node.js NFE.io

SDK oficial da [NFE.io](https://nfe.io) para Node.js: emissão e gestão de
documentos fiscais eletrônicos brasileiros (NFS-e, NF-e, NFC-e, CT-e) com
ergonomia moderna e **zero dependências de runtime**.

- **Cliente único** `NfeClient` com acessores `camelCase` por recurso, inicializados sob demanda (lazy).
- **TypeScript nativo** — tipos gerados das specs OpenAPI oficiais; autocompletar e checagem no editor.
- **Respostas discriminadas** para emissão assíncrona (`{ status: 'immediate' | 'async' }`) e utilitários de polling.
- **ESM + CommonJS** no mesmo pacote; alvo **Node.js 22+**.

## Requisitos

- Node.js **22** ou superior.
- **Zero dependências de runtime** — apenas APIs nativas do Node (fetch, AbortController, Buffer).

## Instalação

```sh
npm install nfe-io
# ou: pnpm add nfe-io / yarn add nfe-io
```

## Primeiros passos

```typescript

const nfe = new NfeClient({ apiKey: process.env.NFE_API_KEY });

const result = await nfe.serviceInvoices.create('55df4dc6b6cd9007e4f13ee8', {
  cityServiceCode: '2690',
  description: 'Manutenção e suporte técnico',
  servicesAmount: 100.0,
  borrower: { federalTaxNumber: 191, name: 'Banco do Brasil SA' },
});
```

O fluxo completo (retorno discriminado + polling) está em
[Primeiros passos](./getting-started.md).

## Guias

- [Primeiros passos](./getting-started.md) — instalação, cliente e primeira NFS-e.
- [Configuração](./configuration.md) — chaves de API, ambiente, timeout e retry.
- [Emissão assíncrona e polling](./async-and-polling.md) — retorno discriminado e `createAndWait`.
- [Roteamento multi-host / multi-chave](./multi-host-routing.md) — quais recursos usam qual host e chave.
- [Paginação](./pagination.md) — listas page-style e cursor.
- [Downloads (PDF/XML)](./downloads.md) — bytes binários e ZIPs.
- [Webhooks](./webhooks.md) — assinatura, eventos e webhooks de conta.
- [Erros](./errors.md) — hierarquia de erros e type guards.
- [Emissão RTC (Reforma Tributária)](./rtc-emission.md) — leiautes IBS/CBS/IS.

## Recursos (cookbook)

Um guia prático por recurso em [Recursos](./recursos/). Destaques:

- [Notas de serviço (NFS-e)](./recursos/service-invoices.md)
- [Notas de produto (NF-e)](./recursos/product-invoices.md)
- [NFC-e (consumidor)](./recursos/consumer-invoices.md)
- [Empresas](./recursos/companies.md) · [Inscrições municipais](./recursos/municipal-taxes.md) · [Inscrições estaduais](./recursos/state-taxes.md)
- [Consulta CNPJ](./recursos/legal-entity-lookup.md) · [Consulta CPF](./recursos/natural-person-lookup.md) · [Consulta CEP](./recursos/addresses.md)

---

## Roteamento multi-host e multi-chave no SDK Node.js da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/multi-host-e-multi-chave/index.md

# Roteamento multi-host / multi-chave

A plataforma NFE.io não é uma única API: são **vários serviços em hosts
distintos**, e há **duas chaves** — a principal (`apiKey`) e a de dados
(`dataApiKey`). O SDK roteia cada recurso para o host/chave corretos; você só
precisa fornecer as chaves na configuração.

## Hosts e chaves por recurso

| Host | Chave | Recursos |
|---|---|---|
| `api.nfe.io/v1` | principal | `serviceInvoices`, `serviceInvoicesRtc`, `companies`, `legalPeople`, `naturalPeople`, `notifications` |
| `api.nfe.io/v2` | principal | `webhooks` (nível de **conta**) |
| `api.nfse.io` | principal | `consumerInvoices` (NFC-e), `taxCodes` |
| `api.nfse.io` | dados | `productInvoices`, `productInvoicesRtc`, `stateTaxes`, `municipalTaxes`, `certificates`, `transportationInvoices`, `inboundProductInvoices` |
| `address.api.nfe.io/v2` | dados | `addresses` |
| `legalentity.api.nfe.io` | dados | `legalEntityLookup` (CNPJ) |
| `naturalperson.api.nfe.io` | dados | `naturalPersonLookup` (CPF) |
| `nfe.api.nfe.io` | dados | `productInvoiceQuery`, `consumerInvoiceQuery` |

:::info Fallback de chave
`dataApiKey` faz fallback para `apiKey` quando não informada. Se você usa **uma
só chave** com todos os escopos, basta configurar `apiKey`.
:::

:::warning Contas com chaves separadas
Se sua conta usa chaves **distintas** para dados e emissão, garanta que a chave
principal tenha acesso aos produtos de emissão/consulta que você vai usar
(NFС-e, tax-codes e emissão usam a chave principal). Uma chave sem escopo
retorna `403`.
:::

## Por que isso importa

O SDK já embute o mapeamento acima. Isso evita erros clássicos como montar o
host/caminho errado ou usar a chave sem permissão para um endpoint. Ao abrir um
chamado ou depurar um `403`/`404`, confira se a **chave** informada cobre o
escopo do recurso na tabela.

## Próximos passos

- [Configuração](./configuration.md)
- [Erros](./errors.md)

---

## Paginação no SDK Node.js da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/paginacao/index.md

# Paginação

Os recursos de listagem retornam **envelopes** — o array vem sob uma chave
específica, não na raiz. O formato varia por recurso.

## Envelopes por recurso

| Recurso | Formato |
|---|---|
| `serviceInvoices.list` | `{ serviceInvoices, page }` |
| `companies.list` | `{ data, page }` (via `ListResponse<Company>`) |
| `municipalTaxes.list` / `stateTaxes.list` | `{ municipalTaxes \| stateTaxes, hasMore }` |
| `consumerInvoices.list` | `{ consumerInvoices, hasMore }` |
| `certificates.list` | `{ certificates }` |
| `notifications.list` | `{ notifications }` |

```typescript
const { serviceInvoices = [], page } = await nfe.serviceInvoices.list(companyId, {
  pageIndex: 1,   // 1-based
  pageCount: 20,  // até 50
  issuedBegin: '2026-01-01',
  issuedEnd: '2026-01-31',
});
```

:::warning Índice 1-based e limite de página
As listas page-style da plataforma são **1-based** (`pageIndex` começa em 1) e
`pageCount` tem teto (tipicamente 50). Valores fora disso podem ser rejeitados
pela API com `400`.
:::

## Iterar todas as empresas

`companies` oferece iteração automática, cuidando das páginas para você:

```typescript
// Coleta tudo em memória:
const all = await nfe.companies.listAll();

// Ou itere lazily (async iterator):
for await (const company of nfe.companies.listIterator()) {
  console.log(company.id, company.name);
}
```

## Filtros por data (NFS-e)

`serviceInvoices.list` aceita `issuedBegin`/`issuedEnd` e
`createdBegin`/`createdEnd` (formato `yyyy-MM-dd`), além de `hasTotals`.

## Próximos passos

- [Notas de serviço (NFS-e)](./recursos/service-invoices.md)
- [Empresas](./recursos/companies.md)

---

## Consulta de endereço (CEP)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/consulta-cep/index.md

# Consulta de endereço (CEP)

`nfe.addresses` (host `address.api.nfe.io/v2`, chave de dados) consulta
endereços brasileiros por CEP. A API real suporta **somente lookup por CEP**.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `lookupByPostalCode(postalCode)` | Consulta o endereço do CEP. | `Address` |

## Exemplo

```typescript
const address = await nfe.addresses.lookupByPostalCode('01310-100');
console.log(address.street);     // 'Paulista'
console.log(address.city.name);  // 'São Paulo'
console.log(address.postalCode); // '01310-100' (com hífen)
```

O CEP é validado (8 dígitos, com ou sem hífen) **antes** da chamada.

:::warning Removido na v5
`addresses.search()` e `addresses.lookupByTerm()` foram removidos — os endpoints
retornavam `404` no host real. Use `lookupByPostalCode`.
:::

## Próximos passos

- [Consulta CNPJ](./legal-entity-lookup.md) · [Consulta CPF](./natural-person-lookup.md)
- [Roteamento multi-host / multi-chave](../multi-host-routing.md)

---

## Certificados digitais (por thumbprint)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/certificados/index.md

# Certificados (por thumbprint)

`nfe.certificates` (host `api.nfse.io`) lista, consulta e remove certificados
digitais por **thumbprint**. Complementa o upload legado
(`companies.uploadCertificate`, host `api.nfe.io`).

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list(companyId)` | Lista os certificados da empresa. | `{ certificates }` |
| `getByThumbprint(companyId, thumbprint)` | Consulta por thumbprint. | metadados do certificado |
| `deleteByThumbprint(companyId, thumbprint)` | Remove por thumbprint. | `void` |
| `getByThumbprintV1(companyId, thumbprint)` | Variante v1. | metadados |
| `deleteByThumbprintV1(companyId, thumbprint)` | Variante v1. | `void` |

## Exemplo

```typescript
const { certificates = [] } = await nfe.certificates.list(companyId);

const thumb = certificates[0]?.thumbprint;
if (thumb) {
  const cert = await nfe.certificates.getByThumbprint(companyId, thumb);
  // await nfe.certificates.deleteByThumbprint(companyId, thumb);
}
```

:::info Upload de certificado
O envio do `.pfx` é feito por `companies.uploadCertificate` (host `api.nfe.io`).
Aqui você consulta/remove o que já foi enviado.
:::

## Próximos passos

- [Empresas](./companies.md)

---

## Empresas (emitentes)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/empresas/index.md

# Empresas (emitentes)

`nfe.companies` gerencia as empresas emitentes (host `api.nfe.io`). A empresa é
o pré-requisito de toda emissão — e precisa de inscrição
([municipal](./municipal-taxes.md)/[estadual](./state-taxes.md)) e certificado.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create(data)` | Cria uma empresa. | `Company` |
| `retrieve(id)` / `update(id, data)` / `remove(id)` | CRUD. | `Company` / `void` |
| `exists(id)` | Existência via `HEAD` (404 → `false`). | `boolean` |
| `list(options?)` | Lista paginada. | `ListResponse<Company>` (`{ data, page }`) |
| `listAll()` | Coleta todas as páginas. | `Company[]` |
| `listIterator()` | Async iterator (lazy). | `AsyncIterableIterator<Company>` |
| `findByTaxNumber(cnpj)` / `findByName(name)` | Busca. | `Company` / lista |
| `uploadCertificate` / `replaceCertificate` / `validateCertificate` | Certificado (.pfx). | metadados |
| `getCertificateStatus` / `checkCertificateExpiration` | Status/validade do certificado. | info |

## Criar e verificar

```typescript
const company = await nfe.companies.create({
  name: 'Minha Empresa LTDA',
  federalTaxNumber: 11222333000181,
  email: 'fiscal@empresa.com',
});

if (await nfe.companies.exists(company.id)) {
  // pronta para configurar inscrições e certificado
}
```

## Iterar todas as empresas

```typescript
for await (const c of nfe.companies.listIterator()) {
  console.log(c.id, c.name);
}
```

:::info Certificado
O upload do certificado (`uploadCertificate`) vive no host `api.nfe.io`. A
consulta/remoção por thumbprint fica em [Certificados](./certificates.md)
(host `api.nfse.io`).
:::

## Próximos passos

- [Inscrições municipais](./municipal-taxes.md) e [estaduais](./state-taxes.md)
- [Certificados](./certificates.md)
- [Paginação](../pagination.md)

---

## Consulta de cupom (CFe-SAT)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/consulta-cfe-sat/index.md

# Consulta de cupom (CFe-SAT)

`nfe.consumerInvoiceQuery` (host `nfe.api.nfe.io`, chave de dados) consulta
cupons fiscais CFe-SAT por **chave de acesso**. É somente leitura — distinto de
[`consumerInvoices`](./consumer-invoices.md) (emissão de NFC-e).

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `retrieve(accessKey)` | Consulta o cupom por chave. | dados do cupom |
| `downloadXml(accessKey)` | XML do cupom. | `Buffer` |

## Exemplo

```typescript
const coupon = await nfe.consumerInvoiceQuery.retrieve(accessKey);
const xml = await nfe.consumerInvoiceQuery.downloadXml(accessKey);
```

## Próximos passos

- [Consulta de NF-e](./product-invoice-query.md)
- [NFC-e (emissão)](./consumer-invoices.md)

---

## NFC-e — notas de consumidor

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/nfc-e/index.md

# NFC-e (notas de consumidor)

`nfe.consumerInvoices` cobre o ciclo de vida da NFC-e (host `api.nfse.io`). A
emissão é **webhook-driven** (202 = enfileirada; conclusão via webhook). É
distinto de `nfe.consumerInvoiceQuery` (consulta de cupom CFe-SAT, somente
leitura).

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create(companyId, data)` | Emite a NFC-e (webhook-driven). | `ConsumerInvoice` |
| `list(companyId, options)` | Lista NFC-e. **`options.environment` é obrigatório.** | `{ consumerInvoices, hasMore }` |
| `retrieve(companyId, invoiceId, environment?)` | Consulta por id. | `ConsumerInvoice` |
| `cancel(companyId, invoiceId)` | Cancela a NFC-e. | `ConsumerInvoice` |
| `getItems(companyId, invoiceId, environment?)` | Itens da nota. | resposta de itens |
| `getEvents(companyId, invoiceId, environment?)` | Eventos da nota. | resposta de eventos |
| `downloadPdf` / `downloadXml` / `downloadRejectionXml` (`, environment?`) | Downloads (Buffer). | `Buffer` |
| `disable(companyId, data)` | Inutilização de numeração. | resultado |

`ConsumerInvoiceListOptions = { environment: 'Production' \| 'Test'; startingAfter?; endingBefore?; limit?; q? }`.

:::warning `environment` obrigatório
A API exige `environment` (`Production`/`Test`) na listagem; as leituras aceitam
`environment` opcional. Sem ele, a listagem retorna `400`.
:::

## Listar e emitir

```typescript
const { consumerInvoices = [] } = await nfe.consumerInvoices.list(companyId, {
  environment: 'Test',
  limit: 5,
});

const invoice = await nfe.consumerInvoices.create(companyId, {
  buyer: { federalTaxNumber: 52998224725, name: 'Consumidor Final' },
  items: [{ code: '001', description: 'Produto', quantity: 1, unitAmount: 10.0 }],
  payment: { method: 'Cash', amount: 10.0 },
});
// 202: aguarde o webhook
```

## Próximos passos

- [Webhooks](../webhooks.md) e [Downloads](../downloads.md)
- [NFC-e RTC](./rtc.md)

---

## NF-e de entrada (inbound / distribuição)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/nfe-de-entrada/index.md

# NF-e de entrada (inbound)

`nfe.inboundProductInvoices` (host `api.nfse.io`, chave de dados) gerencia a
captura automática de NF-e de entrada (distribuição DF-e) e a consulta dos
documentos capturados.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `enableAutoFetch(companyId, data)` / `disableAutoFetch(companyId)` | Liga/desliga a captura automática. | settings |
| `getSettings(companyId)` | Configuração atual. | settings |
| `getDetails(companyId, ...)` / `getProductInvoiceDetails(...)` | Detalhes dos documentos. | dados |
| `getEventDetails(...)` / `getProductInvoiceEventDetails(...)` | Detalhes de eventos. | dados |
| `getXml(companyId, accessKey)` | XML do documento capturado. | XML |

## Exemplo

```typescript
await nfe.inboundProductInvoices.enableAutoFetch(companyId, { /* config */ });
const settings = await nfe.inboundProductInvoices.getSettings(companyId);
```

## Próximos passos

- [CT-e](./transportation-invoices.md)
- [Consulta de NF-e por chave](./product-invoice-query.md)

---

## Consulta de CNPJ (pessoa jurídica)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/consulta-cnpj/index.md

# Consulta de CNPJ

`nfe.legalEntityLookup` (host `legalentity.api.nfe.io`, chave de dados) consulta
dados cadastrais de pessoa jurídica na Receita Federal e informações de
inscrição estadual.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `getBasicInfo(cnpj)` | Dados cadastrais (razão social, endereço, CNAE, etc.). | `{ legalEntity }` |
| `getStateTaxInfo(cnpj)` | Inscrição estadual. | dados de IE |
| `getStateTaxForInvoice(cnpj, ...)` | IE adequada para emissão. | dados de IE |
| `getSuggestedStateTaxForInvoice(cnpj, ...)` | IE sugerida para emissão. | dados de IE |

## Exemplo

```typescript
const { legalEntity } = await nfe.legalEntityLookup.getBasicInfo('06990590000123');
console.log(legalEntity.name, legalEntity.address?.city?.name);
```

## Próximos passos

- [Consulta CPF](./natural-person-lookup.md) · [Consulta CEP](./addresses.md)

---

## Pessoas jurídicas (tomadores PJ)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/pessoas-juridicas/index.md

# Pessoas jurídicas (tomadores PJ)

`nfe.legalPeople` (host `api.nfe.io`) gerencia pessoas jurídicas vinculadas a
uma empresa (tomadores/clientes PJ).

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list(companyId)` | Lista as PJ. | `ListResponse<LegalPerson>` |
| `create(companyId, data)` | Cria uma PJ. | `LegalPerson` |
| `retrieve(companyId, personId)` / `update(...)` / `delete(...)` | CRUD. | `LegalPerson` / `void` |
| `createBatch(companyId, data)` | Criação em lote. | resultado do lote |
| `findByTaxNumber(companyId, cnpj)` | Busca por CNPJ. | `LegalPerson` |

## Exemplo

```typescript
const person = await nfe.legalPeople.create(companyId, {
  federalTaxNumber: 11444555000149,
  name: 'Cliente PJ LTDA',
  email: 'cliente-pj@exemplo.com',
});
```

## Próximos passos

- [Pessoas físicas](./natural-people.md)
- [Empresas](./companies.md)

---

## Inscrições municipais

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/inscricoes-municipais/index.md

# Inscrições municipais

`nfe.municipalTaxes` (host `api.nfse.io`) gerencia as inscrições municipais da
empresa — **pré-requisito para emissão de NFS-e**. Espelha
[`stateTaxes`](./state-taxes.md).

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list(companyId)` | Lista as inscrições. | `{ municipalTaxes, hasMore }` |
| `create(companyId, data)` | Cria uma inscrição. | `MunicipalTax` |
| `retrieve(companyId, municipalTaxId)` | Consulta por id. | `MunicipalTax` |
| `update(companyId, municipalTaxId, data)` | Atualiza. | `MunicipalTax` |
| `delete(companyId, municipalTaxId)` | Remove. | `void` |
| `updatePrefecture(companyId, municipalTaxId, data)` | Atualiza credenciais da prefeitura (HTTP **PATCH**). | `MunicipalTax` |
| `getSeries(companyId, municipalTaxId, serie)` | Consulta uma série de RPS. | dados da série |

## Exemplo

```typescript
const { municipalTaxes = [] } = await nfe.municipalTaxes.list(companyId);

const created = await nfe.municipalTaxes.create(companyId, {
  code: '123456',
  // ...credenciais/config da prefeitura
});

await nfe.municipalTaxes.updatePrefecture(companyId, created.id, {
  // login/senha da prefeitura
});
```

## Próximos passos

- [Notas de serviço (NFS-e)](./service-invoices.md)
- [Empresas](./companies.md)

---

## Pessoas físicas (tomadores PF)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/pessoas-fisicas/index.md

# Pessoas físicas (tomadores PF)

`nfe.naturalPeople` (host `api.nfe.io`) gerencia pessoas físicas vinculadas a
uma empresa (tomadores/clientes PF).

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list(companyId)` | Lista as PF. | `ListResponse<NaturalPerson>` |
| `create(companyId, data)` | Cria uma PF. | `NaturalPerson` |
| `retrieve(companyId, personId)` / `update(...)` / `delete(...)` | CRUD. | `NaturalPerson` / `void` |
| `createBatch(companyId, data)` | Criação em lote. | resultado do lote |
| `findByTaxNumber(companyId, cpf)` | Busca por CPF. | `NaturalPerson` |

## Exemplo

```typescript
const person = await nfe.naturalPeople.create(companyId, {
  federalTaxNumber: 52998224725,
  name: 'Cliente PF',
  email: 'cliente-pf@exemplo.com',
});
```

## Próximos passos

- [Pessoas jurídicas](./legal-people.md)
- [Empresas](./companies.md)

---

## Consulta de CPF (pessoa física)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/consulta-cpf/index.md

# Consulta de CPF

`nfe.naturalPersonLookup` (host `naturalperson.api.nfe.io`, chave de dados)
consulta a situação cadastral de uma pessoa física.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `getStatus(cpf, birthDate)` | Situação cadastral do CPF. | dados de situação |

:::warning Data de nascimento é obrigatória
A API exige a **data de nascimento** junto do CPF. Chamar sem ela retorna
erro de validação.
:::

## Exemplo

```typescript
const status = await nfe.naturalPersonLookup.getStatus('52998224725', '1990-01-31');
```

## Próximos passos

- [Consulta CNPJ](./legal-entity-lookup.md) · [Consulta CEP](./addresses.md)

---

## Notificações

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/notificacoes/index.md

# Notificações

`nfe.notifications` (host `api.nfe.io`) gerencia as notificações da empresa.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list(companyId)` | Lista as notificações. | `{ notifications }` |
| `retrieve(companyId, notificationId)` | Consulta por id. | `Notification` |
| `delete(companyId, notificationId)` | Remove. | `void` |
| `sendEmail(companyId, data?)` | Envia notificação por e-mail. | `void` |

## Exemplo

```typescript
const { notifications = [] } = await nfe.notifications.list(companyId);

await nfe.notifications.sendEmail(companyId, { to: 'destino@exemplo.com' });
```

## Próximos passos

- [Webhooks](../webhooks.md)
- [Empresas](./companies.md)

---

## Consulta de NF-e por chave (SEFAZ)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/consulta-nfe/index.md

# Consulta de NF-e por chave (SEFAZ)

`nfe.productInvoiceQuery` (host `nfe.api.nfe.io`, chave de dados) consulta NF-e
por **chave de acesso** e baixa os arquivos. É somente leitura (não emite).

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `retrieve(accessKey)` | Consulta a NF-e por chave. | dados da NF-e |
| `downloadPdf(accessKey)` | DANFE em PDF. | `Buffer` |
| `downloadXml(accessKey)` | XML da NF-e. | `Buffer` |
| `listEvents(accessKey)` | Eventos da NF-e. | lista de eventos |

## Exemplo

```typescript
const nfe_ = await nfe.productInvoiceQuery.retrieve(accessKey);
const pdf = await nfe.productInvoiceQuery.downloadPdf(accessKey);
```

## Próximos passos

- [Consulta de cupom (CFe-SAT)](./consumer-invoice-query.md)
- [NF-e de entrada](./inbound-product-invoices.md)

---

## Notas fiscais de produto (NF-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/notas-fiscais-de-produto/index.md

# Notas fiscais de produto (NF-e)

`nfe.productInvoices` fala com o host `api.nfse.io` e cobre o ciclo de vida da
NF-e. A emissão é **webhook-driven**: um `202` indica que a nota foi enfileirada
e a conclusão é notificada por [webhook](../webhooks.md) (sem polling).

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create(companyId, data)` | Emite a NF-e (webhook-driven). | `NfeProductInvoiceIssueData` |
| `createWithStateTax(companyId, data)` | Emite garantindo a inscrição estadual. | `NfeProductInvoiceIssueData` |
| `list(companyId, options)` | Lista NF-e. **Requer `environment`** (`Production`/`Test`). | envelope `{ productInvoices, hasMore }` |
| `retrieve(companyId, invoiceId)` | Consulta por id. | dados da NF-e |
| `cancel(companyId, invoiceId)` | Cancela a NF-e. | dados da NF-e |
| `listItems` / `listEvents` | Itens e eventos da nota. | respostas específicas |
| `downloadPdf` / `downloadXml` / `downloadRejectionXml` / `downloadEpecXml` | Downloads (Buffer). | `Buffer` |
| `sendCorrectionLetter(companyId, id, data)` | Emite carta de correção (CC-e). | evento |
| `downloadCorrectionLetterPdf` / `downloadCorrectionLetterXml` | Downloads da CC-e. | `Buffer` |
| `disable` / `disableRange` | Inutilização de numeração. | resultado |

:::warning `environment` obrigatório na listagem
`list` exige `environment` (`'Production'` ou `'Test'`). Chamar sem o parâmetro
retorna `400`.
:::

## Emitir e acompanhar

```typescript
const invoice = await nfe.productInvoices.create(companyId, {
  buyer: { federalTaxNumber: 52998224725, name: 'Cliente Teste' },
  items: [{ code: '001', description: 'Produto', quantity: 1, unitAmount: 100.0 }],
});
// 202: aguarde o webhook de conclusão (não faz polling)
```

## Carta de correção (CC-e)

```typescript
await nfe.productInvoices.sendCorrectionLetter(companyId, invoiceId, {
  correction: 'Correção da descrição do item 1',
});
```

## Próximos passos

- [Webhooks](../webhooks.md) e [Assíncrono](../async-and-polling.md)
- [Inscrições estaduais](./state-taxes.md) (pré-requisito da NF-e)
- [NF-e RTC](./rtc.md)

---

## Emissão RTC (recursos)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/recursos-rtc/index.md

# RTC (recursos)

O leiaute RTC (IBS/CBS/IS) é selecionado pelo **payload**, nos mesmos endpoints
da emissão atual. Para o guia conceitual, veja [Emissão RTC](../rtc-emission.md).

## `nfe.serviceInvoicesRtc` (NFS-e RTC · api.nfe.io)

| Método | Descrição | Retorno |
|---|---|---|
| `create(companyId, data)` | Emite NFS-e RTC. | `CreateInvoiceResponse` (união discriminada) |
| `createAndWait(companyId, data, options?)` | Emite + polling até terminal. | `ServiceInvoiceData` |
| `retrieve(companyId, invoiceId)` | Consulta por id. | `ServiceInvoiceData` |
| `downloadCancellationXml(companyId, invoiceId)` | XML do evento de cancelamento. | `Buffer` |

Tipo de request: `NFSeRtcRequest` (grupo `ibsCbs`).

## `nfe.productInvoicesRtc` (NF-e/NFC-e RTC · api.nfse.io)

| Método | Descrição | Retorno |
|---|---|---|
| `create(companyId, data)` | Emite NF-e/NFC-e RTC (webhook-driven, sem polling). | `NfeProductInvoiceIssueData` |

Tipo de request: `ProductInvoiceRtcRequest` (IBS estadual/municipal, CBS, IS).

## Exemplo

```typescript
const invoice = await nfe.serviceInvoicesRtc.createAndWait(companyId, {
  borrower: { federalTaxNumber: 52998224725, name: 'Cliente Teste' },
  cityServiceCode: '10677',
  description: 'Serviço (RTC)',
  servicesAmount: 100.0,
  ibsCbs: {},
});
```

## Próximos passos

- [Emissão RTC (guia)](../rtc-emission.md)
- [Notas de serviço](./service-invoices.md) · [Notas de produto](./product-invoices.md)

---

## Notas fiscais de serviço (NFS-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/notas-fiscais-de-servico/index.md

# Notas fiscais de serviço (NFS-e)

`nfe.serviceInvoices` é o recurso canônico de emissão da plataforma. Ele fala
com o host `api.nfe.io` no caminho `/v1` e cobre todo o ciclo de vida da nota:
emissão (síncrona ou assíncrona), consulta, listagem, cancelamento, envio por
e-mail e download de PDF/XML.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create(companyId, data)` | Emite a NFS-e. | `CreateInvoiceResponse` (união discriminada) |
| `createAndWait(companyId, data, options?)` | Emite e faz polling até um estado terminal. | `ServiceInvoiceData` |
| `list(companyId, options?)` | Lista paginada (page-style) com filtros de data. | `ServiceInvoiceListResponse` (`{ serviceInvoices, page }`) |
| `retrieve(companyId, invoiceId)` | Consulta uma NFS-e por id. | `ServiceInvoiceData` |
| `retrieveByExternalId(companyId, externalId)` | Consulta por id externo (idempotência/reconciliação). | `ServiceInvoiceData` |
| `cancel(companyId, invoiceId)` | Cancela (assíncrono). | `CancelInvoiceResponse` (união discriminada) |
| `cancelAndWait(companyId, invoiceId, options?)` | Cancela e faz polling até concluir. | `ServiceInvoiceData` |
| `sendEmail(companyId, invoiceId)` | Reenvia a nota por e-mail ao tomador. | `{ sent, message }` |
| `downloadPdf(companyId, invoiceId?)` | PDF da nota; sem `invoiceId`, baixa o ZIP da empresa. | `Buffer` |
| `downloadXml(companyId, invoiceId?)` | XML da nota; sem `invoiceId`, baixa o ZIP da empresa. | `Buffer` |

As opções de `list` são `pageIndex`, `pageCount`, `issuedBegin`, `issuedEnd`,
`createdBegin`, `createdEnd` e `hasTotals`.

:::warning Validação fail-fast
Os métodos validam `companyId`/`invoiceId` **antes** de qualquer chamada HTTP.
Ids vazios ou em branco lançam `ValidationError` sem tráfego de rede.
:::

## Emitir uma NFS-e e tratar o retorno discriminado

`create` devolve `{ status: 'async' }` (HTTP 202, enfileirada) ou
`{ status: 'immediate' }` (HTTP 201, já materializada). Distinga pela tag
`status` — o TypeScript estreita o tipo em cada ramo.

```typescript
const result = await nfe.serviceInvoices.create('55df4dc6b6cd9007e4f13ee8', {
  cityServiceCode: '2690',
  description: 'Manutenção e suporte técnico',
  servicesAmount: 100.0,
  borrower: { federalTaxNumber: 191, name: 'Banco do Brasil SA' },
});

if (result.status === 'async') {
  result.response.invoiceId; // id para reconsultar enquanto processa
  result.response.location;  // caminho do header Location
} else {
  result.invoice;            // ServiceInvoiceData já emitida
}
```

## Acompanhar até um estado terminal (polling)

`createAndWait` combina `create` + polling (backoff exponencial) e devolve a
nota já em estado terminal, lançando `InvoiceProcessingError` em `IssueFailed`.

```typescript
const invoice = await nfe.serviceInvoices.createAndWait(companyId, data, {
  timeout: 120000,       // padrão: 2 min
  initialDelay: 1000,
  onPoll: (attempt, flowStatus) => console.log(attempt, flowStatus),
});

invoice.flowStatus; // 'Issued'
```

Veja [Emissão assíncrona e polling](../async-and-polling.md) para os estados de
`FlowStatus` e as opções de polling.

## Baixar PDF e XML (bytes binários)

```typescript

const pdf = await nfe.serviceInvoices.downloadPdf(companyId, invoiceId);
writeFileSync('nota.pdf', pdf);

// ZIP de todas as notas da empresa (sem invoiceId):
const zip = await nfe.serviceInvoices.downloadXml(companyId);
writeFileSync('notas-xml.zip', zip);
```

## Cancelar e reenviar por e-mail

O cancelamento é **assíncrono** (HTTP 202 + `Location`). Use `cancelAndWait`
para bloquear até o cancelamento concluir.

```typescript
const settled = await nfe.serviceInvoices.cancelAndWait(companyId, invoiceId);
settled.flowStatus; // 'Cancelled'

// Sem bloquear — trate a união discriminada:
const c = await nfe.serviceInvoices.cancel(companyId, invoiceId);
if (c.status === 'async') console.log('cancelando:', c.response.invoiceId);

await nfe.serviceInvoices.sendEmail(companyId, invoiceId);
```

## Próximos passos

- [Emissão assíncrona e polling](../async-and-polling.md)
- [Downloads (PDF/XML)](../downloads.md) e [Paginação](../pagination.md)
- [Empresas](./companies.md) e [Inscrições municipais](./municipal-taxes.md) (pré-requisitos da emissão de NFS-e)

---

## Inscrições estaduais

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/inscricoes-estaduais/index.md

# Inscrições estaduais

`nfe.stateTaxes` (host `api.nfse.io`) gerencia as inscrições estaduais (IE) da
empresa — **pré-requisito para emissão de NF-e**.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list(companyId)` | Lista as inscrições. | `{ stateTaxes, hasMore }` |
| `create(companyId, data)` | Cria uma inscrição. | `StateTax` |
| `retrieve(companyId, stateTaxId)` | Consulta por id. | `StateTax` |
| `update(companyId, stateTaxId, data)` | Atualiza. | `StateTax` |
| `delete(companyId, stateTaxId)` | Remove. | `void` |
| `switchAuthorizer(companyId, stateTaxId, data?)` | Troca o autorizador NF-e (ex.: SVRS). | `StateTax` |

## Exemplo

```typescript
const { stateTaxes = [] } = await nfe.stateTaxes.list(companyId);

await nfe.stateTaxes.switchAuthorizer(companyId, stateTaxes[0].id, {
  authorizer: 'SVRS',
});
```

## Próximos passos

- [Notas de produto (NF-e)](./product-invoices.md)
- [Empresas](./companies.md)

---

## Cálculo de impostos

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/calculo-de-impostos/index.md

# Cálculo de impostos

`nfe.taxCalculation` (host `api.nfse.io`) expõe o motor de cálculo de tributos
para operações com produtos.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `calculate(tenantId, request)` | Calcula os tributos da operação. | detalhamento por item |

Os códigos usados no request (operação, finalidade, perfis fiscais) vêm de
[Códigos de tributos](./tax-codes.md).

## Exemplo

```typescript
const result = await nfe.taxCalculation.calculate(tenantId, {
  // operação + itens conforme os códigos auxiliares
  items: [{ /* ... */ }],
});
// result contém o detalhamento (ICMS, PIS, COFINS, IPI, II) por item
```

## Próximos passos

- [Códigos de tributos](./tax-codes.md)
- [Notas de produto (NF-e)](./product-invoices.md)

---

## Códigos auxiliares de tributos (tax codes)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/codigos-de-tributos/index.md

# Códigos auxiliares (tax codes)

`nfe.taxCodes` (host `api.nfse.io`, **chave principal**) lista os códigos
auxiliares usados no motor de [cálculo de impostos](./tax-calculation.md).

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `listOperationCodes(options?)` | Códigos de operação. | paginado (`{ items, currentPage, totalPages, totalCount }`) |
| `listAcquisitionPurposes(options?)` | Finalidades de aquisição. | paginado |
| `listIssuerTaxProfiles(options?)` | Perfis fiscais do emissor. | paginado |
| `listRecipientTaxProfiles(options?)` | Perfis fiscais do destinatário. | paginado |

## Exemplo

```typescript
const ops = await nfe.taxCodes.listOperationCodes({ pageIndex: 1, pageCount: 20 });
for (const code of ops.items ?? []) console.log(code.code, code.description);
```

:::info Chave principal
Ao contrário de outros recursos em `api.nfse.io`, `taxCodes` usa a **chave
principal** (`apiKey`). Em contas com `dataApiKey` separada, o SDK já roteia
para a chave correta.
:::

## Próximos passos

- [Cálculo de impostos](./tax-calculation.md)

---

## CT-e (conhecimento de transporte)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/cte-transporte/index.md

# CT-e (conhecimento de transporte)

`nfe.transportationInvoices` (host `api.nfse.io`, chave de dados) habilita a
captura de CT-e e consulta documentos por chave de acesso.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `enable(companyId, data)` / `disable(companyId)` | Habilita/desabilita a captura de CT-e. | settings |
| `getSettings(companyId)` | Configuração atual. | settings |
| `retrieve(companyId, accessKey)` | Consulta um CT-e por chave. | dados do CT-e |
| `downloadXml(companyId, accessKey)` | XML do CT-e. | XML |
| `getEvent(companyId, ...)` / `downloadEventXml(companyId, ...)` | Eventos do CT-e. | evento / XML |

## Exemplo

```typescript
const settings = await nfe.transportationInvoices.getSettings(companyId);
const cte = await nfe.transportationInvoices.retrieve(companyId, accessKey);
```

## Próximos passos

- [NF-e de entrada (inbound)](./inbound-product-invoices.md)
- [Roteamento multi-host / multi-chave](../multi-host-routing.md)

---

## Webhooks (recurso)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/recursos/recurso-webhooks/index.md

# Webhooks (recurso)

`nfe.webhooks` gerencia assinaturas de webhook e verifica assinaturas de
entrega. Para o guia conceitual (assinatura HMAC, `express.raw`), veja
[Webhooks](../webhooks.md).

## Métodos — por empresa (`/companies/{id}/webhooks`)

| Método | Descrição |
|---|---|
| `list(companyId)` | Lista os webhooks da empresa. |
| `create(companyId, data)` | Cria um webhook. |
| `retrieve(companyId, webhookId)` / `update(...)` / `delete(...)` | CRUD. |
| `test(companyId, webhookId)` | Dispara um teste. |
| `validateSignature(payload, signature, secret)` | Valida a assinatura HMAC-SHA1 (`x-hub-signature`). |

## Métodos — por conta (`/v2/webhooks`, sem `companyId`)

| Método | Descrição |
|---|---|
| `listAccountWebhooks()` | Lista webhooks da conta (`{ data }`). |
| `createAccountWebhook(data)` | Cria webhook de conta. |
| `retrieveAccountWebhook(id)` / `updateAccountWebhook(id, data)` / `deleteAccountWebhook(id)` | CRUD. |
| `pingAccountWebhook(id)` | Dispara um ping de teste. |
| `deleteAllAccountWebhooks()` | ⚠️ Remove **todos** os webhooks da conta. |
| `fetchEventTypes()` | Lista de tipos de evento **ao vivo** (`string[]`). |

## Exemplo

```typescript
const eventTypes = await nfe.webhooks.fetchEventTypes();

const created = await nfe.webhooks.createAccountWebhook({
  uri: 'https://seu-site.com/webhook',
  events: eventTypes.slice(0, 2),
});
await nfe.webhooks.pingAccountWebhook(created.id);
```

## Próximos passos

- [Webhooks (guia)](../webhooks.md)
- [Assíncrono e webhook-driven](../async-and-polling.md)

---

## Emissão RTC (Reforma Tributária) no SDK Node.js da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/emissao-rtc/index.md

# Emissão RTC (Reforma Tributária do Consumo)

O leiaute RTC (grupos **IBS**, **CBS** e **IS**) é **selecionado pelo payload** —
os endpoints são os mesmos da emissão atual. O SDK expõe recursos dedicados para
deixar o opt-in explícito e tipado.

- `nfe.serviceInvoicesRtc` — NFS-e no leiaute RTC (grupo `ibsCbs`).
- `nfe.productInvoicesRtc` — NF-e/NFC-e no leiaute RTC (IBS estadual/municipal, CBS, IS).

Os recursos de emissão existentes (`serviceInvoices`/`productInvoices`)
permanecem inalterados; RTC é opt-in.

## NFS-e RTC (com polling)

`serviceInvoicesRtc.create` retorna a mesma união discriminada de
`serviceInvoices`; `createAndWait` faz polling até o estado terminal.

```typescript
const invoice = await nfe.serviceInvoicesRtc.createAndWait(companyId, {
  borrower: { federalTaxNumber: 52998224725, name: 'Cliente Teste' },
  cityServiceCode: '10677',
  description: 'Serviço (RTC)',
  servicesAmount: 100.0,
  ibsCbs: { /* grupo RTC conforme a NT_2025.002 */ },
});
```

Também há `retrieve` e `downloadCancellationXml` (XML do evento de cancelamento,
Ambiente Nacional).

## NF-e/NFC-e RTC (webhook-driven)

`productInvoicesRtc.create` **não faz polling** (202 = enfileirada; conclusão
via webhook), espelhando `productInvoices`.

```typescript
const invoice = await nfe.productInvoicesRtc.create(companyId, {
  buyer: { federalTaxNumber: 52998224725, name: 'Cliente Teste' },
  items: [{ code: '001', description: 'Produto', quantity: 1, unitAmount: 100.0 }],
  ibsCbsIs: { /* grupos RTC conforme a NT_2025.002 */ },
});
```

:::info Tipos de request
`NFSeRtcRequest` (NFS-e) e `ProductInvoiceRtcRequest` (NF-e/NFC-e) são derivados
das specs oficiais. A proveniência das specs está registrada em
`openapi/spec/SOURCES.json` (NT_2025.002_v1.30).
:::

## Próximos passos

- [Assíncrono e polling](./async-and-polling.md) e [Webhooks](./webhooks.md)
- [Notas de serviço (NFS-e)](./recursos/service-invoices.md) · [Notas de produto (NF-e)](./recursos/product-invoices.md)

---

## Webhooks no SDK Node.js da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/nodejs/webhooks/index.md

# Webhooks

A NFE.io notifica eventos (emissão, cancelamento, falha, etc.) por webhook. O
SDK cobre a configuração dos webhooks e a **verificação de assinatura**.

## Verificar a assinatura (obrigatório)

As entregas são assinadas com **HMAC-SHA1** no header `x-hub-signature`
(hex maiúsculo, prefixo `sha1=`). Verifique usando o **corpo bruto** (bytes),
não o JSON já parseado.

```typescript

app.post('/webhook/nfe', express.raw({ type: '*/*' }), (req, res) => {
  const ok = nfe.webhooks.validateSignature(
    req.body,                       // Buffer bruto — NÃO use express.json()
    req.headers['x-hub-signature'], // string | string[] | undefined
    process.env.NFE_WEBHOOK_SECRET  // seu segredo
  );
  if (!ok) return res.sendStatus(401);
  // ... processe o evento
  res.sendStatus(200);
});
```

:::warning Use o corpo bruto
`validateSignature` compara os bytes exatos que a NFE.io assinou. Se você
parsear o corpo antes (`express.json()`), a reserialização muda os bytes e a
verificação falha. Use `express.raw()` e passe o `Buffer`.
:::

A comparação é feita com `timingSafeEqual` (resistente a timing attacks) e
aceita a assinatura como `string` ou `string[]`.

## Webhooks por empresa vs por conta

| Escopo | Acesso | Caminho |
|---|---|---|
| Empresa | `nfe.webhooks.list/create/retrieve/update/delete(companyId, ...)` | `/companies/{id}/webhooks` |
| Conta | `nfe.webhooks.listAccountWebhooks/createAccountWebhook/...` | `/v2/webhooks` (host-root) |

Métodos de conta (sem `companyId`): `listAccountWebhooks`, `createAccountWebhook`,
`retrieveAccountWebhook`, `updateAccountWebhook`, `deleteAccountWebhook`,
`pingAccountWebhook` e `deleteAllAccountWebhooks` (⚠️ remove **todos**).

## Tipos de evento ao vivo

Prefira `fetchEventTypes()` (fonte da verdade é o servidor) ao invés da lista
fixa `getAvailableEvents()` (marcada como `@deprecated`).

```typescript
const eventTypes = await nfe.webhooks.fetchEventTypes(); // string[]
```

## Próximos passos

- [Emissão assíncrona e webhook-driven](./async-and-polling.md)
- [Erros](./errors.md)

---

## Emissão assíncrona e polling no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/emissao-assincrona-e-polling/index.md

# Emissão assíncrona e polling

A emissão de documentos fiscais é, em geral, **assíncrona**: a API aceita a
requisição (HTTP 202) e segue processando. Esta página explica o contrato de
retorno, os dois tipos de resultado e como acompanhar o processamento até um
estado terminal.

## O contrato HTTP 202

Quando a API responde **202 Accepted**, o documento ainda **não** foi
materializado — ela apenas aceitou o pedido. Quando responde **201/200**, o
documento já está pronto. O `create()` traduz isso em um **union type nativo do
PHP**: um de dois tipos.

| Resposta HTTP | Tipo de resultado | Significado |
| --- | --- | --- |
| 202 Accepted | `*Pending` | Em processamento; reconsulte depois. |
| 201 / 200 | `*Issued` | Documento já materializado. |

:::note `*Pending` e `*Issued` por recurso
Cada recurso expõe seu par de resultados — por exemplo,
`Nfe\Response\ServiceInvoicePending` e `Nfe\Response\ServiceInvoiceIssued` (o
mesmo vale para `ProductInvoice*` e `ConsumerInvoice*`). Todos implementam as
interfaces marcadoras `Nfe\Response\Pending` e `Nfe\Response\Issued`, que é
contra o que você testa com `instanceof`.
:::

## Os dois tipos de resultado

### `*Pending` (202)

- `invoiceId()` — id extraído do último segmento do header `Location`; use-o
  para reconsultar enquanto processa.
- `location()` — o valor bruto do header `Location`.

:::warning `Pending` não tem corpo de nota
Um HTTP 202 não traz o documento — o objeto `Pending` carrega **apenas**
`invoiceId()` e `location()`. Não é possível ler valores de imposto ou número da
nota dele; busque com `retrieve()` depois que o processamento chegar a um estado
terminal. Um 202 **sem** header `Location` lança
`Nfe\Exception\InvalidRequestException`.
:::

### `*Issued` (201/200)

- `resource()` — o documento já materializado (DTO hidratado).

## Distinguindo o resultado

Não há campo `status` nem métodos `pending?()`/`issued?()` — use `instanceof`:

```php
use Nfe\Response\Pending;

$result = $nfe->serviceInvoices->create($companyId, [
    'cityServiceCode' => '2690',
    'servicesAmount'  => 100.0,
    'description'     => 'Suporte',
    'borrower'        => ['federalTaxNumber' => 191, 'name' => 'Banco do Brasil SA'],
]);

if ($result instanceof Pending) {
    $invoiceId = $result->invoiceId();   // reconsulte com este id
} else {
    $invoice = $result->resource();      // NFS-e já pronta
}
```

## Loop de polling manual

Para NFS-e, faça polling com `getStatus()` (endpoint leve de status) até um
**estado terminal**, decidido por `Nfe\Util\FlowStatus::isTerminal()`:

```php
use Nfe\Response\Pending;
use Nfe\Util\FlowStatus;

if ($result instanceof Pending) {
    $invoiceId = $result->invoiceId();
    $deadline  = time() + 300;           // defina seu próprio orçamento de tempo
    $delay     = 1;

    do {
        sleep($delay);
        $delay = min($delay * 2, 10);    // backoff próprio
        $flow  = $nfe->serviceInvoices->getStatus($companyId, $invoiceId)['flowStatus'] ?? '';
    } while (!FlowStatus::isTerminal($flow) && time() < $deadline);

    if ($flow === 'Issued') {
        $invoice = $nfe->serviceInvoices->retrieve($companyId, $invoiceId);
    } else {
        // 'IssueFailed' | 'Cancelled' | 'CancelFailed' — ou estourou o prazo
    }
}
```

### Estados de fluxo (`flowStatus`)

Estados **terminais** (encerram o polling — `FlowStatus::TERMINAL`):

| Status | Significado |
| --- | --- |
| `Issued` | Emitido com sucesso. |
| `IssueFailed` | Falha na emissão. |
| `Cancelled` | Cancelado. |
| `CancelFailed` | Falha no cancelamento. |

Estados **não terminais** (continue o polling): `WaitingSend`, `WaitingReturn`,
`WaitingDownload`, `WaitingCalculateTaxes`, `WaitingDefineRpsNumber`,
`WaitingSendCancel`, `PullFromCityHall`.

:::warning Terminal ≠ sucesso
`FlowStatus::isTerminal()` retorna `true` para **sucesso e falha**. Sempre
compare o status concreto (`=== 'Issued'`) antes de considerar a nota emitida.
:::

:::note `getStatus()` só existe em `serviceInvoices`
Para `productInvoices` e `consumerInvoices` não há `getStatus()` — faça polling
com `retrieve()` e leia o campo de fluxo do DTO. Mas a emissão de NF-e/NFC-e é
**orientada a webhook**: prefira [Webhooks](./webhooks.md) a polling nesses
recursos.
:::

## Por que não existe `createAndWait`?

A `v3.0` **não** implementa `createAndWait()`, `pollUntilComplete()` nem
qualquer helper de espera. O contrato discriminado `*Pending`/`*Issued` somado a
`FlowStatus::isTerminal()` é suficiente para escrever loops de polling manuais,
e esses auxiliares ficam deliberadamente adiados para uma versão futura — sem
quebrar o contrato público.

:::warning Não chame helpers inexistentes
Referenciar `$nfe->serviceInvoices->createAndWait(...)` na `v3.0` gera um erro
fatal (`Call to undefined method`), pois o método não está definido.
:::

## Próximos passos

- [Tratamento de erros](./errors.md) — trate falhas durante o polling.
- [Webhooks](./webhooks.md) — receba a conclusão por push em vez de polling.
- [Primeiros passos](./getting-started.md) — a primeira emissão de ponta a ponta.

---

## Configuração do cliente do SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/configuracao/index.md

# Configuração

Esta página descreve como configurar o `Nfe\Client`: os argumentos de
conveniência do construtor, as opções avançadas que vivem em `Nfe\Config`, o
modelo de duas chaves, a política de retry e os overrides por requisição com
`Nfe\Http\RequestOptions`.

## Argumentos de `new Nfe\Client(...)`

O construtor aceita **argumentos nomeados**:

```php
use Nfe\Client;
use Nfe\Environment;

$nfe = new Client(
    apiKey: $_ENV['NFE_API_KEY'],
    dataApiKey: $_ENV['NFE_DATA_API_KEY'] ?? null,
    environment: Environment::Production,
    timeout: 60,
    userAgentSuffix: 'meu-integrador/1.0',
);
```

| Argumento | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `apiKey` | `?string` | `null` | Chave principal. Obrigatória quando `config` não é informado. |
| `dataApiKey` | `?string` | `null` | Chave dos serviços de dados (CEP/CNPJ/CPF/consultas). Fallback para `apiKey`. |
| `config` | `?Nfe\Config` | `null` | Quando informado, **os demais argumentos de conveniência são ignorados**. |
| `environment` | `Nfe\Environment` | `Environment::Production` | `Production` ou `Sandbox`. Reservado para uso futuro (sem efeito sobre os endpoints hoje). |
| `timeout` | `int` | `60` | Timeout por requisição, em segundos (deve ser positivo). |
| `transport` | `?Nfe\Http\Transport` | `null` | Transporte HTTP customizado (adaptador PSR-18, mock). `null` = cURL padrão. |
| `userAgentSuffix` | `?string` | `null` | Sufixo anexado ao `User-Agent` do SDK. |

:::note Validação na construção
As opções são validadas na criação. `apiKey` vazia, `dataApiKey` vazia (quando
não nula) ou `timeout` não positivo lançam `Nfe\Exception\InvalidRequestException`
antes de qualquer requisição HTTP. Veja [Tratamento de erros](./errors.md).
:::

:::note Sem fallback por variáveis de ambiente
O SDK **não** lê `NFE_API_KEY`/`NFE_DATA_API_KEY` automaticamente — resolva as
variáveis você mesmo (`$_ENV`, `getenv()`, secrets do framework) e passe-as ao
construtor.
:::

## Opções avançadas — somente em `Nfe\Config`

Retry e logger **não** são aceitos diretamente por `new Client(...)`. Eles vivem
em `Nfe\Config`, que é injetado via `config:` (e então substitui todos os
argumentos de conveniência):

```php
use Nfe\Client;
use Nfe\Config;
use Nfe\Http\RetryPolicy;

$nfe = new Client(config: new Config(
    apiKey: $_ENV['NFE_API_KEY'],
    dataApiKey: $_ENV['NFE_DATA_API_KEY'] ?? null,
    timeout: 60,
    retry: new RetryPolicy(maxRetries: 5, baseDelay: 0.5, maxDelay: 20.0, jitter: 0.3),
    logger: $meuLoggerPsr3,           // Psr\Log\LoggerInterface (opcional)
    userAgentSuffix: 'meu-integrador/1.0',
));
```

| Opção | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `retry` | `Nfe\Http\RetryPolicy` | `new RetryPolicy()` | Política de retentativas (veja abaixo). |
| `logger` | `?Psr\Log\LoggerInterface` | `null` | Logger PSR-3 opcional. O pacote `psr/log` **não** é exigido em runtime. |
| `transport` | `?Nfe\Http\Transport` | `null` | Transporte HTTP customizado. |

## Retry (`Nfe\Http\RetryPolicy`)

O transporte retenta automaticamente respostas **HTTP 429** e **5xx** com
backoff exponencial e jitter. O padrão é `maxRetries: 3`, `baseDelay: 1.0`s,
`maxDelay: 30.0`s, `jitter: 0.3` (±30%). Erros 4xx de negócio **não** são
retentados.

```php
use Nfe\Http\RetryPolicy;

// Desabilitar completamente:
$config = new Nfe\Config(apiKey: $key, retry: RetryPolicy::none());
```

## Modelo de duas chaves

A plataforma separa a cobrança entre a API principal (emissão — cobrada por
documento) e os serviços de **dados** (consultas — cobrados por consulta, muitas
vezes em outro plano). As famílias de dados — `addresses` (CEP), `legal-entity`
(CNPJ), `natural-person` (CPF) e `nfe-query` (consultas de NF-e/NFC-e) — usam a
`dataApiKey` quando presente, com **fallback** para a `apiKey`. Todas as demais
famílias usam a `apiKey`.

```php
$nfe = new Nfe\Client(
    apiKey: 'chave-de-emissao',
    dataApiKey: 'chave-de-consulta',
);

// - $nfe->addresses           → usa dataApiKey (família de dados)
// - $nfe->legalEntityLookup   → usa dataApiKey
// - $nfe->serviceInvoices     → usa apiKey (emissão)
// - $nfe->companies           → usa apiKey
```

:::warning `api.nfse.io` usa a chave principal
`taxCalculation`, `taxCodes`, `transportationInvoices` e
`inboundProductInvoices` (host `api.nfse.io`) **não** são famílias de dados:
sempre usam a `apiKey`. Um 403 nas famílias de dados com uma chave principal
válida normalmente significa que o plano da chave não inclui o produto de
dados — informe uma `dataApiKey` provisionada. Veja
[Roteamento multi-host](./multi-host-routing.md).
:::

## Overrides por requisição (`Nfe\Http\RequestOptions`)

Todo método de recurso aceita um `RequestOptions` opcional como último argumento
para sobrescrever chave, host ou timeout **de uma única chamada** — útil em
integrações multi-tenant:

```php
use Nfe\Http\RequestOptions;

$invoice = $nfe->serviceInvoices->retrieve(
    $companyId,
    $invoiceId,
    new RequestOptions(apiKey: $chaveDoTenant, timeout: 120),
);
```

| Campo | Efeito |
| --- | --- |
| `apiKey` | Substitui a chave resolvida para esta chamada. |
| `baseUrl` | Aponta a chamada para outro host (mock, proxy, ambiente próprio). |
| `timeout` | Timeout específico desta chamada, em segundos. |

:::note Sem `idempotencyKey`
A API da NFE.io não honra o header `Idempotency-Key` atualmente, então o
`RequestOptions` não expõe esse campo. Quando a API adicionar suporte, ele
entrará em uma release menor aditiva.
:::

## Sandbox vs. Produção

:::warning A separação produção vs. teste fica na conta, não no SDK
A escolha entre **produção** e **teste (homologação)** é definida na
configuração da sua conta em [app.nfe.io](https://app.nfe.io) (lado servidor) —
**não** pela chave de API nem pelo SDK.
:::

O enum `Nfe\Environment` (`Production` / `Sandbox`) é aceito e validado, mas
hoje **não altera** endpoints, chaves ou comportamento — está reservado para uso
futuro.

:::note Ambiente SEFAZ é outra coisa
Os recursos de produto e consumidor (NF-e/NFC-e) aceitam um parâmetro
**separado** `environment` do tipo `string` (`"Production"` / `"Test"`) nas
operações de listagem — esse é o ambiente da SEFAZ e é tratado nos guias
daqueles recursos, não aqui.
:::

## Transporte PSR-18 (Guzzle, Symfony HttpClient…)

Por padrão o SDK fala HTTP com cURL (`Nfe\Http\CurlTransport`). Para rotear pelo
cliente HTTP do seu framework, use `Nfe\Http\Psr18Transport` com qualquer
cliente PSR-18 + fábricas PSR-17 (exige `psr/http-client` e `psr/http-factory`
instalados no seu projeto):

```php
use Nfe\Client;
use Nfe\Config;
use Nfe\Http\Psr18Transport;

$transport = new Psr18Transport($psr18Client, $requestFactory, $streamFactory);
$nfe = new Client(config: new Config(apiKey: $key, transport: $transport));
```

## Próximos passos

- [Emissão assíncrona e polling](./async-and-polling.md) — o contrato HTTP 202.
- [Tratamento de erros](./errors.md) — `catch` por tipo.
- [Roteamento multi-host](./multi-host-routing.md) — hosts e chaves por família.

---

## Downloads de PDF e XML no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/downloads/index.md

# Downloads

Os recursos de nota expõem métodos para baixar PDF e XML. No SDK PHP o contrato
é **um só**: todo método `download*()` / `getPdf()` / `getXml()` retorna os
**bytes crus do arquivo como uma `string` PHP** — não um stream, não um objeto
de arquivo, não uma URI.

## Salvando um arquivo

```php
file_put_contents(
    'nota.pdf',
    $nfe->serviceInvoices->downloadPdf($companyId, $invoiceId),
);

file_put_contents(
    'nota.xml',
    $nfe->serviceInvoices->downloadXml($companyId, $invoiceId),
);
```

O mesmo padrão vale para todos os recursos:

```php
// NF-e (DANFE) emitida pela sua empresa:
$pdf = $nfe->productInvoices->downloadPdf($companyId, $invoiceId);

// NF-e de terceiros, por chave de acesso (44 dígitos):
$danfe = $nfe->productInvoiceQuery->downloadPdf($accessKey);

// XML de CT-e recebido:
$xml = $nfe->transportationInvoices->downloadXml($companyId, $accessKey);

// Documentos de entrada (DF-e):
$pdf = $nfe->inboundProductInvoices->getPdf($companyId, $accessKey);
```

:::tip Diferença em relação aos SDKs Node.js e Ruby
No SDK Ruby, os downloads de `product_invoices` devolvem um objeto com a URI do
arquivo; no Node, um `Buffer`. No PHP não há exceção: **todos** os downloads —
inclusive os de `productInvoices` — devolvem a `string` de bytes pronta para
gravar. Não portar esse detalhe cegamente de outro SDK.
:::

## Métodos de download por recurso

| Recurso | Métodos |
| --- | --- |
| `serviceInvoices` | `downloadPdf`, `downloadXml` |
| `productInvoices` | `downloadPdf`, `downloadXml`, `downloadRejectionXml`, `downloadEpecXml`, `downloadCorrectionLetterPdf`, `downloadCorrectionLetterXml` |
| `consumerInvoices` | `downloadPdf`, `downloadXml`, `downloadRejectionXml` |
| `transportationInvoices` | `downloadXml`, `downloadEventXml` |
| `inboundProductInvoices` | `getPdf`, `getXml`, `getEventXml` |
| `productInvoiceQuery` | `downloadPdf`, `downloadXml` |
| `consumerInvoiceQuery` | `downloadXml` |

## Como o SDK segue o redirecionamento para o CDN

Alguns endpoints de download respondem com um redirect (302/303/307) para um CDN
(por exemplo, S3). O SDK segue o redirecionamento **em uma segunda requisição
sem o header `Authorization`** — sua chave de API nunca chega ao host do CDN.
Isso é transparente: você recebe os bytes finais.

:::note Memória
Como o retorno é uma `string` em memória, arquivos muito grandes (ZIPs de
período inteiro, por exemplo) ocupam RAM proporcional ao tamanho. Para volumes
altos, baixe em lotes menores.
:::

## Próximos passos

- [Roteamento multi-host](./multi-host-routing.md) — em qual host cada download vive.
- [Paginação](./pagination.md) — liste notas antes de baixá-las.
- [Cookbook por recurso](./recursos/) — exemplos completos por recurso.

---

## Tratamento de erros no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/tratamento-de-erros/index.md

# Tratamento de erros

Todos os erros de API do SDK derivam de `Nfe\Exception\ApiErrorException` (que
estende `RuntimeException`), então você pode capturar a família inteira com um
único `catch`. Esta página descreve a hierarquia, os códigos HTTP mapeados,
padrões de `catch` por tipo, a validação client-side e os erros de rede.

## A hierarquia de erros

Todas as classes vivem em `Nfe\Exception\`:

| Classe | Código HTTP | Quando ocorre |
| --- | --- | --- |
| `ApiErrorException` | — | Base de toda a família. |
| `AuthenticationException` | 401 | Chave de API ausente ou inválida. |
| `AuthorizationException` | 403 | Chave válida, mas sem permissão/plano para o recurso. |
| `InvalidRequestException` | 400 / 422 | Requisição malformada, reprovada na validação — ou validação **local** (síncrona, antes do HTTP). |
| `NotFoundException` | 404 | Recurso não existe. |
| `RateLimitException` | 429 | Excesso de requisições. |
| `ServerException` | 5xx | Falha no servidor da API. |
| `ApiConnectionException` | — | Falha de rede/cURL (DNS, conexão recusada, TLS, timeout). |
| `SignatureVerificationException` | — | Assinatura de webhook reprovada. |

:::note Não há type guards — use `instanceof`
O SDK não expõe funções `isXxx()`. Capture as subclasses específicas primeiro e
`ApiErrorException` como rede de segurança.
:::

## Contexto carregado pelos erros HTTP

Erros derivados de uma resposta HTTP carregam contexto público para
diagnóstico: `->statusCode`, `->responseBody`, `->responseHeaders` e
`->errorCode`, além do `getMessage()` usual.

```php
use Nfe\Exception\ApiErrorException;

try {
    $nfe->serviceInvoices->retrieve($companyId, $invoiceId);
} catch (ApiErrorException $e) {
    $e->statusCode;      // ex.: 404
    $e->errorCode;       // código de erro legível por máquina, quando presente
    $e->getMessage();    // mensagem de diagnóstico
}
```

:::warning Cuidado ao logar `responseBody`/`responseHeaders`
O corpo e os headers brutos podem conter dados sensíveis (PII do payload,
detalhes da conta). Prefira logar `statusCode` + `errorCode` + `getMessage()` e
reserve o corpo bruto para depuração pontual.
:::

## Padrões de `catch` por tipo

Capture do mais específico para o mais genérico:

```php
use Nfe\Exception\ApiConnectionException;
use Nfe\Exception\ApiErrorException;
use Nfe\Exception\AuthenticationException;
use Nfe\Exception\AuthorizationException;
use Nfe\Exception\InvalidRequestException;
use Nfe\Exception\RateLimitException;
use Nfe\Exception\ServerException;

try {
    $result = $nfe->serviceInvoices->create($companyId, $payload);
} catch (AuthenticationException $e) {
    // 401 — revise a chave de API.
    throw $e;
} catch (AuthorizationException $e) {
    // 403 — a chave não tem permissão/plano para este recurso.
    throw $e;
} catch (InvalidRequestException $e) {
    // 400/422 ou validação local — corrija o payload.
    error_log("Requisição inválida: {$e->getMessage()}");
} catch (RateLimitException $e) {
    // 429 — aguarde antes de tentar de novo (o SDK já retentou com backoff).
    throw $e;
} catch (ServerException $e) {
    // 5xx — falha do lado do servidor; reportar/retentar com backoff.
    throw $e;
} catch (ApiConnectionException $e) {
    // Falha de rede (DNS, conexão recusada, TLS, timeout).
    throw $e;
} catch (ApiErrorException $e) {
    // Rede de segurança para qualquer erro do SDK.
    error_log("[{$e->errorCode}] HTTP {$e->statusCode}: {$e->getMessage()}");
    throw $e;
}
```

## Validação client-side (fail-fast)

Validações client-side (id de empresa vazio, chave de acesso com tamanho errado,
CEP/UF inválidos, texto de carta de correção vazio) lançam
`InvalidRequestException` **antes** de qualquer requisição HTTP:

```php
use Nfe\Exception\InvalidRequestException;

try {
    $nfe->serviceInvoices->retrieve('', 'abc');
} catch (InvalidRequestException $e) {
    // Lançada de forma síncrona, sem rede. $e->statusCode é null aqui.
    error_log($e->getMessage());
}
```

:::note Sem `statusCode` na validação local
Por não vir de uma resposta HTTP, um `InvalidRequestException` client-side tem
`statusCode` nulo — diferente do mesmo erro vindo de um 400/422.
:::

## Retentativas automáticas

Antes de qualquer exceção chegar ao seu código, o transporte já retentou
**HTTP 429** e **5xx** conforme a `Nfe\Http\RetryPolicy` configurada (padrão: 3
retentativas com backoff exponencial e jitter). Um `RateLimitException` ou
`ServerException` capturado significa que o orçamento de retentativas se
esgotou. Erros 4xx de negócio não são retentados. Veja
[Configuração](./configuration.md).

## Erros de rede

Quando nenhuma troca HTTP se completa, o SDK lança `ApiConnectionException` em
vez de devolver uma resposta — DNS, conexão recusada, falha de TLS, timeout de
conexão ou leitura.

```php
use Nfe\Exception\ApiConnectionException;

try {
    $nfe->companies->list();
} catch (ApiConnectionException $e) {
    error_log("Falha de conexão: {$e->getMessage()}");
}
```

## Próximos passos

- [Emissão assíncrona e polling](./async-and-polling.md) — trate falhas no loop.
- [Configuração](./configuration.md) — `timeout` e `RetryPolicy`.
- [Webhooks](./webhooks.md) — `SignatureVerificationException` na prática.

---

## Primeiros passos com o SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/primeiros-passos/index.md

# Primeiros passos

Este guia cobre a instalação, a criação do cliente e a emissão da sua primeira
nota fiscal de serviço (NFS-e), incluindo o acompanhamento do processamento.

## 1. Instale o pacote

```sh
composer require "nfe/nfe:^3.0"
```

:::note Requisitos
PHP **8.2** ou superior, com as extensões `ext-curl`, `ext-json` e
`ext-mbstring`. O SDK não tem dependências de runtime — usa o cURL nativo do
PHP.
:::

## 2. Crie um cliente

O construtor usa **argumentos nomeados**:

```php
use Nfe\Client;

$nfe = new Client(apiKey: $_ENV['NFE_API_KEY']);
```

Recursos de **dados** (CEP, CNPJ, CPF, consultas de NF-e/NFC-e) usam uma segunda
chave opcional, `dataApiKey:`, com fallback para `apiKey`. Todas as opções estão
em [Configuração](./configuration.md).

:::note O SDK não lê variáveis de ambiente sozinho
Diferente de outros SDKs da NFE.io, o cliente PHP **não** faz fallback
automático para `NFE_API_KEY`/`NFE_DATA_API_KEY` — passe as chaves
explicitamente (por exemplo via `$_ENV`, como acima).
:::

## 3. Emita uma NFS-e

Os recursos ficam em propriedades `public readonly` do cliente — acesse-os
diretamente:

```php
$result = $nfe->serviceInvoices->create('55df4dc6b6cd9007e4f13ee8', [
    'cityServiceCode' => '2690',
    'description'     => 'Manutenção e suporte técnico',
    'servicesAmount'  => 100.0,
    'borrower'        => [
        'federalTaxNumber' => 191,
        'name'             => 'Banco do Brasil SA',
    ],
]);
```

:::tip Chaves em camelCase
O corpo (`array $data`) usa as chaves em camelCase, exatamente como a API
espera.
:::

## 4. Trate o retorno discriminado

A emissão é assíncrona. `create()` devolve um **union type nativo**
(`ServiceInvoicePending|ServiceInvoiceIssued`) — distinga com `instanceof`
contra as interfaces marcadoras `Nfe\Response\Pending` e `Nfe\Response\Issued`:

```php
use Nfe\Response\Pending;

if ($result instanceof Pending) {
    $invoiceId = $result->invoiceId();  // id para reconsultar enquanto processa (HTTP 202)
    $location  = $result->location();   // valor bruto do header Location
} else {
    $invoice = $result->resource();     // NFS-e já materializada (HTTP 201)
}
```

## 5. Acompanhe até um estado terminal (polling)

Não existe `createAndWait()` na `v3.0` — faça polling com `getStatus()` até um
estado terminal, usando `Nfe\Util\FlowStatus::isTerminal()`:

```php
use Nfe\Response\Pending;
use Nfe\Util\FlowStatus;

if ($result instanceof Pending) {
    $companyId = '55df4dc6b6cd9007e4f13ee8';
    $invoiceId = $result->invoiceId();

    do {
        sleep(3); // algumas prefeituras levam minutos
        $status = $nfe->serviceInvoices->getStatus($companyId, $invoiceId);
        $flow   = $status['flowStatus'] ?? '';
    } while (!FlowStatus::isTerminal($flow));

    if ($flow === 'Issued') {
        $invoice = $nfe->serviceInvoices->retrieve($companyId, $invoiceId);
    } else {
        // 'IssueFailed' | 'Cancelled' | 'CancelFailed'
    }
}
```

:::warning Terminal não significa sucesso
`FlowStatus::isTerminal()` retorna `true` também para os estados de **falha**
(`IssueFailed`, `CancelFailed`). Sempre inspecione o status concreto antes de
considerar a nota emitida. Veja
[Emissão assíncrona e polling](./async-and-polling.md).
:::

:::warning Produção vs. teste
A separação **produção vs. teste (homologação)** é definida na configuração da
sua conta em [app.nfe.io](https://app.nfe.io) — **não** pela chave de API nem
pelo SDK. O argumento `environment:` do cliente está reservado para uso futuro.
:::

## Próximos passos

- [Configuração](./configuration.md) — todas as opções do cliente.
- [Emissão assíncrona e polling](./async-and-polling.md) — o contrato 202 em detalhe.
- [Tratamento de erros](./errors.md) — `catch` por tipo.
- [Webhooks](./webhooks.md) — receba a conclusão por push em vez de polling.

---

## Biblioteca NFE.io em PHP para Emissão de Notas Fiscais (NFS-e, NF-e, NFC-e, CT-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/index.md

# Biblioteca PHP NFE.io

SDK oficial da [NFE.io](https://nfe.io) para PHP: emissão e gestão de documentos
fiscais eletrônicos brasileiros (NFS-e, NF-e, NFC-e, CT-e) com PHP moderno e
**zero dependências de runtime**.

- **Cliente único** `Nfe\Client` com acessores `camelCase` por recurso, em
  propriedades `public readonly`.
- **PHP 8.2+ estrito** — `readonly`, enums, argumentos nomeados e **union types
  nativos** para o retorno discriminado da emissão assíncrona.
- **Paridade 1:1** com o [SDK Node.js](https://github.com/nfe/client-nodejs) —
  mesmos recursos, mesmos hosts, mesmos payloads.

## Requisitos

- PHP **8.2**, **8.3** ou **8.4**.
- Extensões: `ext-curl`, `ext-json`, `ext-mbstring`.
- **Zero dependências de runtime** — cURL nativo; PSR-3 (log) e PSR-18
  (transporte HTTP) são opcionais.

## Instalação

```sh
composer require "nfe/nfe:^3.0"
```

## Primeiros passos

```php
use Nfe\Client;

$nfe = new Client(apiKey: $_ENV['NFE_API_KEY']);

$result = $nfe->serviceInvoices->create('55df4dc6b6cd9007e4f13ee8', [
    'cityServiceCode' => '2690',
    'description'     => 'Manutenção e suporte técnico',
    'servicesAmount'  => 100.0,
    'borrower'        => [
        'federalTaxNumber' => 191,
        'name'             => 'Banco do Brasil SA',
    ],
]);
```

O fluxo completo (retorno discriminado + polling) está em
[Primeiros passos](./getting-started.md).

## Guias

| Guia | Conteúdo |
|---|---|
| [Primeiros passos](./getting-started.md) | Instalação, cliente, primeira emissão e polling. |
| [Configuração](./configuration.md) | Argumentos do cliente, `Nfe\Config`, modelo de duas chaves, retry e transportes. |
| [Emissão assíncrona e polling](./async-and-polling.md) | Contrato 202 `Pending`/`Issued` e o laço de polling com `FlowStatus`. |
| [Tratamento de erros](./errors.md) | Hierarquia `Nfe\Exception\*` e padrões de `catch`. |
| [Webhooks](./webhooks.md) | Verificação HMAC-SHA1 com `Nfe\Webhook` e idempotência/replay. |
| [Paginação](./pagination.md) | Estilos page e cursor; `ListResponse` e `ListPage`. |
| [Downloads](./downloads.md) | PDF/XML como bytes em `string`. |
| [Roteamento multi-host](./multi-host-routing.md) | Os hosts por família de recurso. |
| [Cookbook por recurso](./recursos/) | Um exemplo por recurso (os 17 recursos do cliente). |

## Migração

Vindo da série `2.x` (`NFe_io`, prefixo `NFe_`)? Veja o
[guia de migração](https://github.com/nfe/client-php/blob/master/MIGRATION.md) —
a `v3.0` é uma reescrita completa, sem camada de compatibilidade. As linhas v2 e
v3 compartilham o mesmo pacote Composer (`nfe/nfe`); o Composer resolve cada
constraint (`^2.0` / `^3.0`) para a major correta automaticamente.

---

## Roteamento multi-host no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/roteamento-multi-host/index.md

# Roteamento multi-host

A plataforma NFE.io expõe várias APIs em hosts diferentes. O SDK roteia cada
recurso **automaticamente** para o host certo — nenhum recurso hard-codeia uma
URL. Cada recurso declara uma **família** de API e obtém seu host e sua chave a
partir do `Nfe\Config`.

## Famílias, hosts e recursos

| Família | Host | Recursos |
| --- | --- | --- |
| `main` | `api.nfe.io` (`/v1`) | `serviceInvoices`, `companies`, `legalPeople`, `naturalPeople`, `webhooks` |
| `cte` | `api.nfse.io` (`/v2`) | `productInvoices`, `consumerInvoices`, `transportationInvoices`, `inboundProductInvoices`, `taxCalculation`, `taxCodes`, `stateTaxes` |
| `addresses` | `address.api.nfe.io/v2` | consulta de endereços (CEP) |
| `legal-entity` | `legalentity.api.nfe.io` | consulta de pessoa jurídica (CNPJ) |
| `natural-person` | `naturalperson.api.nfe.io` | consulta de pessoa física (CPF) |
| `nfe-query` | `nfe.api.nfe.io` | `productInvoiceQuery`, `consumerInvoiceQuery` |

:::note O segmento de versão
Para a família `main`, o `/v1` é fornecido pela versão de API de cada recurso,
não pelo host. O host de `addresses` já embute o `/v2`. Uma família desconhecida
cai no host `main` como padrão seguro.
:::

## Modelo de duas chaves

O SDK usa duas chaves de API. As **famílias de dados** preferem `dataApiKey`
(com fallback para `apiKey`); todas as outras famílias usam `apiKey`.

As famílias de dados são:

- `addresses` (CEP)
- `legal-entity` (CNPJ)
- `natural-person` (CPF)
- `nfe-query` (consultas de NF-e/NFC-e por chave de acesso)

```php
$nfe = new Nfe\Client(
    apiKey: $_ENV['NFE_API_KEY'],
    dataApiKey: $_ENV['NFE_DATA_API_KEY'] ?? null,
);
```

:::warning `cte` NÃO é família de dados
A família `cte` (`api.nfse.io` — emissão de NF-e/NFC-e, CT-e, entrada, cálculo
de impostos, tax codes e inscrições estaduais) usa a **`apiKey` principal**, e
não a `dataApiKey`. Neste SDK a emissão é uma capacidade central, não uma
consulta de dados. Código Node portado que dependia de `dataApiKey` para
`api.nfse.io` passa a enviar silenciosamente a chave principal.
:::

:::tip 403 nas famílias de dados
Um `AuthorizationException` (403) em `addresses`/`legalEntityLookup`/
`naturalPersonLookup`/`productInvoiceQuery` com uma chave principal válida
normalmente significa que o plano dessa chave não inclui o produto de dados.
Informe uma `dataApiKey` provisionada para o plano de dados.
:::

## Override por requisição: `RequestOptions->baseUrl`

Para apontar **uma chamada** para outro host (mock, proxy, ambiente de testes
próprio), use o `Nfe\Http\RequestOptions` que todo método aceita como último
argumento:

```php
use Nfe\Http\RequestOptions;

$invoice = $nfe->serviceInvoices->retrieve(
    $companyId,
    $invoiceId,
    new RequestOptions(baseUrl: 'https://mock.local/nfe'),
);
```

Para redirecionar **todo** o tráfego (testes de integração, gravação de
cassetes), injete um `Nfe\Http\Transport` customizado no `Nfe\Config` — o SDK
não tem um mapa global de overrides por família.

## Próximos passos

- [Configuração](./configuration.md) — duas chaves, `RequestOptions` e transportes.
- [Downloads](./downloads.md) — o hop para o CDN sem `Authorization`.
- [Paginação](./pagination.md) — formas de paginação por família.

---

## Paginação de listas no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/paginacao/index.md

# Paginação

Os métodos `list()` retornam um `Nfe\Util\ListResponse` com os itens hidratados
em `->data` e os metadados de paginação em `->page`. **Não há iterador
auto-paginante** — para avançar, chame `list()` de novo com a próxima página ou
o próximo cursor.

## `Nfe\Util\ListResponse`

Tem dois membros públicos:

- `->data` — o array de DTOs hidratados (`list<T>`).
- `->page` — um `Nfe\Util\ListPage` com os metadados de paginação.

```php
$page = $nfe->serviceInvoices->list($companyId, ['pageIndex' => 1, 'pageCount' => 50]);

foreach ($page->data as $invoice) {
    echo $invoice->id, PHP_EOL;
}

$ids = array_map(fn($i) => $i->id, $page->data);
```

## `Nfe\Util\ListPage`

Os endpoints da NFE.io paginam em **uma de duas formas**, e cada recurso
preenche apenas a metade relevante (a outra fica `null`):

- **Por página** — `->pageIndex` / `->pageCount`.
- **Por cursor** — `->startingAfter` / `->endingBefore`.

`->total` é opcional e pode aparecer em qualquer uma das formas.

:::warning `pageIndex` é 1-based
O primeiro índice de página é **1**, não 0 — em `serviceInvoices`,
`consumerInvoices`, `companies` e `taxCodes`. Pedir `pageIndex => 0` não retorna
a primeira página.
:::

## Qual recurso usa qual forma

| Recurso | Forma de paginação |
| --- | --- |
| `serviceInvoices->list()` | por página (`pageIndex` 1-based / `pageCount`) |
| `consumerInvoices->list()` | por página |
| `companies->list()` | por página (+ `listAll()` client-side) |
| `taxCodes->list*()` | por página (`pageCount` máx. 50; resposta própria) |
| `productInvoices->list()` | por cursor (`startingAfter` / `limit`) — `environment` obrigatório |
| `stateTaxes->list()` | por cursor |

### Por página: `serviceInvoices`

```php
$page = $nfe->serviceInvoices->list($companyId, [
    'pageIndex' => 1,
    'pageCount' => 50,
]);

// Próxima página:
$page2 = $nfe->serviceInvoices->list($companyId, [
    'pageIndex' => 2,
    'pageCount' => 50,
]);
```

`serviceInvoices` também aceita filtros de data como `issuedBegin` e
`issuedEnd` nas mesmas opções.

### Por cursor: `productInvoices`

:::warning `environment` é obrigatório
Em `productInvoices->list()`, o argumento `$options` é **obrigatório** (não tem
default) e precisa conter `environment` — uma string `"Production"` ou
`"Test"` (o ambiente da SEFAZ).
:::

```php
$page = $nfe->productInvoices->list($companyId, [
    'environment' => 'Production',
    'limit'       => 50,
]);

// Avance usando o cursor da página anterior:
$next = $nfe->productInvoices->list($companyId, [
    'environment'   => 'Production',
    'startingAfter' => $page->page->startingAfter,
    'limit'         => 50,
]);
```

### Auto-paginação client-side: `companies->listAll()`

`companies` oferece um helper que percorre todas as páginas por você e devolve
um array simples:

```php
$todas = $nfe->companies->listAll(); // array<Company>
```

:::note `taxCodes` retorna um tipo próprio
Os métodos de `taxCodes` retornam `TaxCodePaginatedResponse` (com
`currentPage`, `totalPages`, `totalCount` e `items`) em vez de `ListResponse` —
veja o [cookbook de códigos fiscais](./recursos/tax-codes.md).
:::

## Próximos passos

- [Downloads](./downloads.md) — baixe os arquivos das notas listadas.
- [Webhooks](./webhooks.md) — receba eventos por push em vez de listar.
- [Roteamento multi-host](./multi-host-routing.md) — em qual host cada recurso vive.

---

## Consulta de endereços (addresses) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/enderecos/index.md

# Consulta de endereços (`addresses`)

O recurso `$nfe->addresses` consulta endereços **por CEP**. Faz parte da família
de **dados** `addresses`, servida por `address.api.nfe.io/v2` (o host já embute
a versão).

:::note Família de dados — configure `dataApiKey`
`addresses` usa a `dataApiKey` quando presente, com **fallback** para a
`apiKey`. Configure `dataApiKey:` para separar a chave de consulta da chave de
emissão. Veja [Configuração](../configuration.md).
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `lookupByPostalCode($cep)` | Consulta um endereço por CEP. | `AddressLookupResponse` |

:::warning CEP é o único endpoint
Não existe busca por termo livre nem por filtro — `lookupByPostalCode()` é o
único método. Não procure `search()`/`lookupByTerm()`: esses endpoints não
existem mais na API.
:::

## Consultar por CEP

```php
$nfe = new Nfe\Client(
    apiKey: $_ENV['NFE_API_KEY'],
    dataApiKey: $_ENV['NFE_DATA_API_KEY'] ?? null,
);

$resposta = $nfe->addresses->lookupByPostalCode('01310-100');

$endereco = $resposta->addresses[0];
$endereco['street'];         // "Avenida Paulista"
$endereco['city'] ?? null;   // dados do município

$resposta->raw;              // payload original completo, se precisar
```

O CEP é aceito com ou sem hífen e é normalizado para 8 dígitos.

:::warning CEP é validado antes do HTTP
Um CEP que não normalize para **8 dígitos** lança
`Nfe\Exception\InvalidRequestException` **antes** de qualquer requisição. Veja
[Tratamento de erros](../errors.md).
:::

:::note O envelope `{ address }` é desembrulhado
A API responde `{ "address": { … } }`; o SDK desembrulha para
`->addresses` — uma lista de **1 elemento** — para manter o shape estável.
:::

## Veja também

- [Configuração](../configuration.md) — modelo de duas chaves e `dataApiKey`.
- [Consulta de CNPJ](./legal-entity-lookup.md) e [Consulta de CPF](./natural-person-lookup.md) — outras famílias de dados.

---

## Empresas (companies) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/empresas/index.md

# Empresas (`companies`)

O recurso `$nfe->companies` gerencia as empresas emissoras da sua conta — CRUD
completo mais a **leitura** do status do certificado digital. Tem escopo de
**conta** (não recebe `$companyId` como primeiro argumento), faz parte da
família `main` servida por `api.nfe.io` (`/v1`) e usa a `apiKey`.

:::note Exclusão é `remove()`, não `delete()`
Para excluir uma empresa, chame `companies->remove($companyId)` — retorna um
`array{deleted, id}`. O nome mantém paridade com os SDKs Node e Ruby.
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create($data)` | Cria uma empresa emissora. | `Company` |
| `list($options = [])` | Lista paginada (`pageIndex` **1-based**). | `ListResponse` |
| `listAll()` | Todas as empresas (auto-paginação client-side). | `array<Company>` |
| `retrieve($companyId)` | Consulta por id. | `Company` |
| `update($companyId, $data)` | Atualiza. | `Company` |
| `remove($companyId)` | Exclui. | `array{deleted, id}` |
| `findByTaxNumber($taxNumber)` | Busca por CNPJ/CPF (varredura client-side). | `?Company` |
| `findByName($name)` | Busca por nome (varredura client-side). | `array<Company>` |
| `getCertificateStatus($companyId, $expiringSoonThreshold = 30)` | Status do certificado digital. | `CertificateStatus` |
| `checkCertificateExpiration($companyId, $thresholdDays = 30)` | Alerta de expiração. | `array` |
| `getCompaniesWithCertificates()` | Empresas com certificado instalado. | `array<Company>` |
| `getCompaniesWithExpiringCertificates($thresholdDays = 30)` | Empresas com certificado a vencer. | `array<Company>` |

:::warning Upload de certificado não está no SDK
O transporte do SDK é JSON-only (sem multipart) — **não** há
`uploadCertificate()`/`validateCertificate()` na `v3.0`. Faça o upload do
certificado `.pfx` pelo painel [app.nfe.io](https://app.nfe.io) (ou pela API
REST diretamente); use o SDK para **ler** o status e monitorar a expiração.
:::

## Exemplos

### Criar e recuperar uma empresa

```php
$company = $nfe->companies->create([
    'name'             => 'Acme Serviços LTDA',
    'federalTaxNumber' => 12345678000199,
    'email'            => 'fiscal@acme.com.br',
]);

$nfe->companies->retrieve($company->id);
```

:::note `federalTaxNumber` é `int` para empresas
No DTO `Company` (e `LegalPerson`), `federalTaxNumber` é inteiro; em
`NaturalPerson` é string. O SDK não valida nem coage no create — envie o tipo
que a API espera.
:::

### Paginar e localizar empresas

```php
// Uma página por vez (pageIndex é 1-based):
$page = $nfe->companies->list(['pageIndex' => 1, 'pageCount' => 50]);
foreach ($page->data as $c) {
    echo $c->name, PHP_EOL;
}

// Todas as empresas (auto-paginação client-side):
$todas = $nfe->companies->listAll();

// Buscas auxiliares (filtragem no cliente):
$acme = $nfe->companies->findByTaxNumber('12.345.678/0001-99');
$semelhantes = $nfe->companies->findByName('acme');
```

:::warning Helpers de busca não são otimizados
`findByTaxNumber`, `findByName`, `listAll`, `getCompaniesWithCertificates` e
`getCompaniesWithExpiringCertificates` percorrem **todas** as páginas e filtram
no cliente. Evite em contas com muitas empresas.
:::

### Monitorar o certificado digital

```php
$status = $nfe->companies->getCertificateStatus($company->id);
$status->daysUntilExpiration;   // calculado client-side a partir de expiresOn
$status->isExpiringSoon;        // threshold padrão: 30 dias

$alerta = $nfe->companies->checkCertificateExpiration($company->id, thresholdDays: 15);

// Varredura da conta inteira:
$vencendo = $nfe->companies->getCompaniesWithExpiringCertificates(thresholdDays: 30);
```

## Veja também

- [Pessoas jurídicas](./legal-people.md) e [Pessoas físicas](./natural-people.md) — tomadores vinculados à empresa.
- [Webhooks](./webhooks.md) — eventos por empresa.
- [Tratamento de erros](../errors.md).

---

## Consulta de cupons fiscais (consumerInvoiceQuery)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/consulta-nfce/index.md

# Consulta de cupons fiscais (`consumerInvoiceQuery`)

`$nfe->consumerInvoiceQuery` consulta **cupons fiscais** — CFe-SAT e NFC-e —
pela **chave de acesso de 44 dígitos**. Recurso **global**, servido por
`nfe.api.nfe.io`.

:::note Família de dados — usa `dataApiKey`
Como [`productInvoiceQuery`](./product-invoice-query.md), pertence à família
`nfe-query`: usa a `dataApiKey` com fallback para `apiKey`. Veja
[Configuração](../configuration.md).
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `retrieve($accessKey)` | Consulta o cupom pela chave de acesso. | `TaxCoupon` |
| `downloadXml($accessKey)` | XML do cupom. | `string` (bytes crus) |

## Consultar um cupom

```php
$accessKey = '35260159596908000152590008719000024150288589'; // 44 dígitos

$cupom = $nfe->consumerInvoiceQuery->retrieve($accessKey);
```

:::warning Chave de acesso é validada localmente
A chave precisa ter **44 dígitos numéricos**; um valor fora do formato lança
`Nfe\Exception\InvalidRequestException` antes de qualquer requisição.
:::

## Baixar o XML

```php
file_put_contents('cupom.xml', $nfe->consumerInvoiceQuery->downloadXml($accessKey));
```

:::note Sem PDF
Diferente da consulta de NF-e, a consulta de cupons expõe apenas o XML — não há
`downloadPdf()`.
:::

## Veja também

- [Consulta de NF-e](./product-invoice-query.md) — o equivalente para NF-e modelo 55.
- [Notas de consumidor (NFC-e)](./consumer-invoices.md) — emissão de NFC-e.
- [Configuração](../configuration.md) — modelo de duas chaves.

---

## Notas fiscais de consumidor (NFC-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/notas-fiscais-de-consumidor/index.md

# Notas fiscais de consumidor (NFC-e)

`$nfe->consumerInvoices` cobre a NFC-e (modelo 65) no host `api.nfse.io`, sob
`/v2`: emissão, listagem, consulta, cancelamento, inutilização de faixa e
downloads.

A emissão segue o **contrato 202 discriminado** (assíncrona; conclusão via
webhook): `create()` / `createWithStateTax()` devolvem
`ConsumerInvoicePending|ConsumerInvoiceIssued`.

:::tip Prefira webhooks
Como na NF-e, não há `getStatus()` — a conclusão da emissão é orientada a
webhook. Se precisar de polling, use `retrieve()` e leia o campo de fluxo do
DTO.
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create($companyId, $data)` | Emite a NFC-e. | `ConsumerInvoicePending\|ConsumerInvoiceIssued` |
| `createWithStateTax($companyId, $stateTaxId, $data)` | Emite vinculada a uma inscrição estadual. | `ConsumerInvoicePending\|ConsumerInvoiceIssued` |
| `list($companyId, $options = [])` | Lista paginada. | `ListResponse` |
| `retrieve($companyId, $invoiceId)` | Consulta por id. | `ConsumerInvoice` |
| `cancel($companyId, $invoiceId)` | Cancela e devolve o modelo atualizado. | `ConsumerInvoice` |
| `listItems($companyId, $invoiceId)` | Lista os itens da nota. | `array` (arrays crus) |
| `listEvents($companyId, $invoiceId)` | Lista os eventos fiscais. | `array` (arrays crus) |
| `downloadPdf($companyId, $invoiceId)` | DANFE NFC-e (PDF). | `string` (bytes crus) |
| `downloadXml($companyId, $invoiceId)` | XML autorizado. | `string` |
| `downloadRejectionXml($companyId, $invoiceId)` | XML de rejeição. | `string` |
| `disableRange($companyId, $data)` | Inutiliza uma faixa de numeração. | `array` |

:::note Diferenças em relação à NF-e
NFC-e **não** tem carta de correção (CC-e), contingência EPEC nem inutilização
por nota individual — apenas `disableRange()`. A inutilização aqui usa
`POST .../disablement` (caminho e verbo diferentes do `disable` da NF-e).
:::

## Emitir uma NFC-e

```php
use Nfe\Response\Pending;

$result = $nfe->consumerInvoices->create('55df4dc6b6cd9007e4f13ee8', [
    'items' => [
        ['code' => '001', 'description' => 'Produto X', 'quantity' => 2, 'unitAmount' => 25.0],
    ],
    'payment' => [
        ['method' => 'Money', 'amount' => 50.0],
    ],
]);

if ($result instanceof Pending) {
    $result->invoiceId();   // acompanhe via webhook ou retrieve()
} else {
    $result->resource();    // Nfe\ConsumerInvoice
}
```

## Listar, consultar e cancelar

```php
$pagina = $nfe->consumerInvoices->list($companyId, [
    'pageIndex' => 1,      // 1-based
    'pageCount' => 50,
]);

$nota = $nfe->consumerInvoices->retrieve($companyId, $invoiceId);

$cancelada = $nfe->consumerInvoices->cancel($companyId, $invoiceId);
```

## Baixar arquivos

```php
file_put_contents('nfce.pdf', $nfe->consumerInvoices->downloadPdf($companyId, $invoiceId));
file_put_contents('nfce.xml', $nfe->consumerInvoices->downloadXml($companyId, $invoiceId));
```

## Inutilizar uma faixa de numeração

```php
$nfe->consumerInvoices->disableRange($companyId, [
    'environment' => 'Production',
    'serie'       => 1,
    'state'       => 'SP',
    'beginNumber' => 200,
    'lastNumber'  => 210,
    'reason'      => 'Falha de impressão',
]);
```

## Próximos passos

- [Consulta de cupons (CFe-SAT/NFC-e)](./consumer-invoice-query.md) — consulta por chave de acesso.
- [Notas de produto (NF-e)](./product-invoices.md) — modelo 55.
- [Webhooks](../webhooks.md) — conclusão por push.

---

## Notas de entrada (NF-e recebidas / DF-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/notas-de-entrada/index.md

# Notas de entrada (NF-e recebidas)

`$nfe->inboundProductInvoices` cobre a **distribuição DF-e**: NF-e emitidas por
terceiros contra o seu CNPJ. Vive no host `api.nfse.io`, sob `/v2`, e permite
ativar a busca automática, consultar documentos e eventos por chave de acesso,
baixar XML/PDF/JSON e registrar a **manifestação do destinatário**.

:::note Usa a `apiKey` principal
Apesar de ser um recurso de consulta, a distribuição DF-e **não** é família de
dados — sempre usa a chave principal.
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `enableAutoFetch($companyId, $data)` | Ativa a busca automática de documentos. | `InboundSettings` |
| `disableAutoFetch($companyId)` | Desativa a busca automática. | `InboundSettings` |
| `getSettings($companyId)` | Configurações atuais. | `InboundSettings` |
| `getDetails($companyId, $accessKey)` | Detalhes do documento distribuído. | `array` |
| `getProductInvoiceDetails($companyId, $accessKey)` | Detalhes da NF-e completa. | `array` |
| `getEventDetails($companyId, $accessKey, $eventKey)` | Detalhes de um evento distribuído. | `array` |
| `getProductInvoiceEventDetails($companyId, $accessKey, $eventKey)` | Detalhes de um evento da NF-e. | `array` |
| `getXml($companyId, $accessKey)` | XML do documento. | `string` (bytes crus) |
| `getEventXml($companyId, $accessKey, $eventKey)` | XML de um evento. | `string` |
| `getPdf($companyId, $accessKey)` | DANFE em PDF. | `string` |
| `getJson($companyId, $accessKey)` | Representação JSON do documento. | `array` |
| `manifest($companyId, $accessKey, $manifestType, $data = [])` | Manifestação do destinatário. | `array` |
| `reprocessWebhook($companyId, $accessKey)` | Reenvia o webhook do documento. | `array` |

## Ativar a busca automática

```php
$settings = $nfe->inboundProductInvoices->enableAutoFetch('55df4dc6b6cd9007e4f13ee8', [
    'startFromDate' => '2026-01-01',
]);
```

Depois de ativada, os documentos chegam por [webhook](../webhooks.md) conforme a
SEFAZ os distribui.

## Consultar um documento recebido

```php
$accessKey = '35260111222333000181550010000012341000012349';

$detalhes = $nfe->inboundProductInvoices->getDetails($companyId, $accessKey);
$nfeCompleta = $nfe->inboundProductInvoices->getProductInvoiceDetails($companyId, $accessKey);

file_put_contents('entrada.xml', $nfe->inboundProductInvoices->getXml($companyId, $accessKey));
file_put_contents('entrada.pdf', $nfe->inboundProductInvoices->getPdf($companyId, $accessKey));
```

## Manifestação do destinatário

```php
// Ex.: confirmar a operação
$nfe->inboundProductInvoices->manifest($companyId, $accessKey, 'Confirmation');

// Ex.: desconhecer a operação, com justificativa no corpo
$nfe->inboundProductInvoices->manifest($companyId, $accessKey, 'Ignorance', [
    'reason' => 'Operação não reconhecida',
]);
```

## Reprocessar o webhook

Se a sua aplicação perdeu uma entrega, peça o reenvio do evento do documento:

```php
$nfe->inboundProductInvoices->reprocessWebhook($companyId, $accessKey);
```

## Próximos passos

- [CT-e (entrada)](./transportation-invoices.md) — o equivalente para conhecimentos de transporte.
- [Webhooks](../webhooks.md) — verificação de assinatura das entregas.
- [Consulta de NF-e](./product-invoice-query.md) — consulta pontual por chave de acesso.

---

## Consulta de CNPJ (legalEntityLookup) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/consulta-cnpj/index.md

# Consulta de CNPJ (`legalEntityLookup`)

`$nfe->legalEntityLookup` consulta dados cadastrais de **pessoa jurídica** por
CNPJ, incluindo a inscrição estadual (IE) por UF. Recurso **global** (não recebe
`$companyId`), servido por `legalentity.api.nfe.io`.

:::note Família de dados — usa `dataApiKey`
Com fallback para `apiKey`. Um 403 com chave principal válida normalmente
significa que o plano não inclui o produto de dados. Veja
[Configuração](../configuration.md).
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `getBasicInfo($cnpj, $opts = null)` | Dados cadastrais básicos da Receita. | `LegalEntityResponse` |
| `getStateTaxInfo($state, $cnpj)` | Inscrição estadual na UF. | `LegalEntityResponse` |
| `getStateTaxForInvoice($state, $cnpj)` | IE apta para emissão de NF-e. | `LegalEntityResponse` |
| `getSuggestedStateTaxForInvoice($state, $cnpj)` | IE sugerida para a NF-e. | `LegalEntityResponse` |

## Consultar os dados básicos

```php
$resposta = $nfe->legalEntityLookup->getBasicInfo('11.444.555/0001-49');

$pj = $resposta->legalEntity;      // array com os dados desembrulhados (ou null)
$pj['name'] ?? null;
$pj['address'] ?? null;

$resposta->raw;                    // payload completo original
```

`getBasicInfo()` aceita um segundo argumento com parâmetros de query — por
exemplo, `['updateAddress' => false, 'updateCityCode' => true]`.

## Consultar a inscrição estadual por UF

```php
$ie = $nfe->legalEntityLookup->getStateTaxInfo('SP', '11444555000149');

// Variantes voltadas à emissão de NF-e:
$nfe->legalEntityLookup->getStateTaxForInvoice('SP', '11444555000149');
$nfe->legalEntityLookup->getSuggestedStateTaxForInvoice('SP', '11444555000149');
```

:::warning UF é validada localmente
`$state` é normalizada para maiúsculas; uma UF desconhecida lança
`Nfe\Exception\InvalidRequestException` antes de qualquer requisição.
:::

:::tip Enriquecendo cadastros
Um fluxo comum: consultar o CNPJ aqui e usar o resultado para pré-preencher o
cadastro do tomador em [`legalPeople`](./legal-people.md) antes de emitir a
nota.
:::

## Veja também

- [Consulta de CPF](./natural-person-lookup.md) — o equivalente PF.
- [Inscrições estaduais](./state-taxes.md) — IEs da **sua** empresa emissora.
- [Configuração](../configuration.md) — modelo de duas chaves.

---

## Pessoas jurídicas (legalPeople) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/pessoas-juridicas/index.md

# Pessoas jurídicas (`legalPeople`)

`$nfe->legalPeople` gerencia o cadastro de **pessoas jurídicas** (tomadores PJ)
vinculadas a uma empresa emissora. Escopo de **empresa** (todo método recebe
`$companyId` como primeiro argumento), família `main` (`api.nfe.io` `/v1`),
chave principal.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list($companyId)` | Lista as pessoas jurídicas da empresa. | `ListResponse` |
| `create($companyId, $data)` | Cadastra uma PJ. | `LegalPerson` |
| `retrieve($companyId, $personId)` | Consulta por id. | `LegalPerson` |
| `update($companyId, $personId, $data)` | Atualiza. | `LegalPerson` |
| `delete($companyId, $personId)` | Exclui. | `void` |
| `createBatch($companyId, $batch)` | Cadastra várias em sequência. | `array` |
| `findByTaxNumber($companyId, $taxNumber)` | Busca por CNPJ (client-side). | `?LegalPerson` |

:::note Exclusão aqui é `delete(): void`
Diferente de `companies->remove()` (que retorna `{deleted, id}`), pessoas usam
`delete()` e não retornam corpo.
:::

## Exemplos

### Cadastrar uma pessoa jurídica

```php
$pessoa = $nfe->legalPeople->create('55df4dc6b6cd9007e4f13ee8', [
    'federalTaxNumber' => 11444555000149,   // int para PJ
    'name'             => 'Cliente Exemplo LTDA',
    'email'            => 'contato@exemplo.com.br',
    'address'          => [
        'postalCode' => '01310-100',
        'street'     => 'Avenida Paulista',
        'number'     => '1000',
        'city'       => ['code' => '3550308', 'name' => 'São Paulo'],
        'state'      => 'SP',
    ],
]);
```

:::warning `federalTaxNumber` é `int` para PJ
No DTO `LegalPerson`, `federalTaxNumber` é `?int` (em `NaturalPerson` é
`?string`). O SDK não valida nem coage no create — envie o tipo correto.
:::

### Lote sequencial

```php
$resultado = $nfe->legalPeople->createBatch($companyId, [
    ['federalTaxNumber' => 11444555000149, 'name' => 'Empresa A'],
    ['federalTaxNumber' => 61365284000104, 'name' => 'Empresa B'],
]);
```

:::note `createBatch` é sequencial
As criações são feitas **uma a uma** (sem paralelismo) — para listas grandes,
espere tempo proporcional ao tamanho do lote.
:::

### Buscar, atualizar e excluir

```php
$pj = $nfe->legalPeople->findByTaxNumber($companyId, 11444555000149);

if ($pj !== null) {
    $nfe->legalPeople->update($companyId, $pj->id, ['email' => 'novo@exemplo.com.br']);
    $nfe->legalPeople->delete($companyId, $pj->id);   // void
}
```

## Veja também

- [Pessoas físicas](./natural-people.md) — o equivalente PF.
- [Consulta de CNPJ](./legal-entity-lookup.md) — enriqueça o cadastro com dados da Receita.
- [Notas de serviço](./service-invoices.md) — use a PJ como `borrower`.

---

## Pessoas físicas (naturalPeople) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/pessoas-fisicas/index.md

# Pessoas físicas (`naturalPeople`)

`$nfe->naturalPeople` gerencia o cadastro de **pessoas físicas** (tomadores PF)
vinculadas a uma empresa emissora. Escopo de **empresa**, família `main`
(`api.nfe.io` `/v1`), chave principal. A API é idêntica à de
[pessoas jurídicas](./legal-people.md), com uma diferença de tipo importante.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list($companyId)` | Lista as pessoas físicas da empresa. | `ListResponse` |
| `create($companyId, $data)` | Cadastra uma PF. | `NaturalPerson` |
| `retrieve($companyId, $personId)` | Consulta por id. | `NaturalPerson` |
| `update($companyId, $personId, $data)` | Atualiza. | `NaturalPerson` |
| `delete($companyId, $personId)` | Exclui. | `void` |
| `createBatch($companyId, $batch)` | Cadastra várias em sequência. | `array` |
| `findByTaxNumber($companyId, $taxNumber)` | Busca por CPF (client-side). | `?NaturalPerson` |

## Exemplos

### Cadastrar uma pessoa física

```php
$pessoa = $nfe->naturalPeople->create('55df4dc6b6cd9007e4f13ee8', [
    'federalTaxNumber' => '31119298000',   // string para PF
    'name'             => 'Maria da Silva',
    'email'            => 'maria@example.com',
]);
```

:::warning `federalTaxNumber` é `string` para PF
No DTO `NaturalPerson`, `federalTaxNumber` é `?string` — diferente de
`LegalPerson`/`Company`, onde é `?int`. O SDK não valida nem coage no create;
enviar o tipo errado pode causar rejeição ou perda de zeros à esquerda do CPF.
:::

### Lote, busca e exclusão

```php
$nfe->naturalPeople->createBatch($companyId, [
    ['federalTaxNumber' => '31119298000', 'name' => 'Maria da Silva'],
    ['federalTaxNumber' => '19100000000', 'name' => 'João Souza'],
]); // sequencial, sem paralelismo

$pf = $nfe->naturalPeople->findByTaxNumber($companyId, '31119298000');

if ($pf !== null) {
    $nfe->naturalPeople->delete($companyId, $pf->id);   // void
}
```

## Veja também

- [Pessoas jurídicas](./legal-people.md) — o equivalente PJ.
- [Consulta de CPF](./natural-person-lookup.md) — valide a situação cadastral na Receita.
- [Notas de serviço](./service-invoices.md) — use a PF como `borrower`.

---

## Consulta de CPF (naturalPersonLookup) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/consulta-cpf/index.md

# Consulta de CPF (`naturalPersonLookup`)

`$nfe->naturalPersonLookup` consulta a **situação cadastral** de uma pessoa
física na Receita Federal. Recurso **global**, servido por
`naturalperson.api.nfe.io`.

:::note Família de dados — usa `dataApiKey`
Com fallback para `apiKey`. Veja [Configuração](../configuration.md).
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `getStatus($cpf, $birthDate)` | Situação cadastral do CPF. | `NaturalPersonStatus` |

A consulta de CPF exige **duas credenciais do titular**: o CPF e a data de
nascimento.

## Consultar a situação cadastral

```php
$status = $nfe->naturalPersonLookup->getStatus('311.192.980-00', '1990-05-20');
```

`$birthDate` aceita uma string ISO (`YYYY-MM-DD`) ou um `\DateTimeImmutable`:

```php
$status = $nfe->naturalPersonLookup->getStatus(
    '31119298000',
    new \DateTimeImmutable('1990-05-20'),
);
```

:::warning Validação local da data
Datas malformadas ou fora de faixa lançam
`Nfe\Exception\InvalidRequestException` **antes** de qualquer requisição. O CPF
também é validado quanto ao formato.
:::

:::note Dado sensível
CPF e data de nascimento são dados pessoais — trate o resultado conforme a
LGPD: não logue o payload bruto e restrinja o acesso ao propósito da consulta.
:::

## Veja também

- [Consulta de CNPJ](./legal-entity-lookup.md) — o equivalente PJ.
- [Pessoas físicas](./natural-people.md) — cadastro de tomadores PF.
- [Configuração](../configuration.md) — modelo de duas chaves.

---

## Consulta de NF-e por chave de acesso (productInvoiceQuery)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/consulta-nfe/index.md

# Consulta de NF-e (`productInvoiceQuery`)

`$nfe->productInvoiceQuery` consulta **qualquer NF-e** (emitida por você ou por
terceiros) pela **chave de acesso de 44 dígitos**. Recurso **global** (não
recebe `$companyId`), servido por `nfe.api.nfe.io`.

:::note Consulta ≠ emissão
Este recurso é distinto de [`productInvoices`](./product-invoices.md) (emissão).
É família de **dados** (`nfe-query`): usa a `dataApiKey` com fallback para
`apiKey`. Veja [Configuração](../configuration.md).
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `retrieve($accessKey)` | Consulta a NF-e pela chave de acesso. | `ProductInvoiceDetails` |
| `downloadPdf($accessKey)` | DANFE em PDF. | `string` (bytes crus) |
| `downloadXml($accessKey)` | XML autorizado. | `string` |
| `listEvents($accessKey)` | Eventos fiscais da nota. | `array` |

## Consultar uma NF-e

```php
$accessKey = '35260111222333000181550010000012341000012349'; // 44 dígitos

$detalhes = $nfe->productInvoiceQuery->retrieve($accessKey);
```

:::warning Chave de acesso é validada localmente
A chave precisa ter **44 dígitos numéricos** — um valor fora do formato lança
`Nfe\Exception\InvalidRequestException` antes de qualquer requisição.
:::

## Baixar DANFE e XML

```php
file_put_contents('danfe.pdf', $nfe->productInvoiceQuery->downloadPdf($accessKey));
file_put_contents('nfe.xml', $nfe->productInvoiceQuery->downloadXml($accessKey));
```

## Listar os eventos fiscais

```php
$eventos = $nfe->productInvoiceQuery->listEvents($accessKey);
// cancelamentos, cartas de correção, manifestações...
```

## Veja também

- [Consulta de cupons (CFe-SAT/NFC-e)](./consumer-invoice-query.md) — o equivalente para cupons.
- [Notas de entrada](./inbound-product-invoices.md) — captura automática de NF-e contra o seu CNPJ.
- [Downloads](../downloads.md) — o contrato de bytes crus.

---

## Notas fiscais de produto (NF-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/notas-fiscais-de-produto/index.md

# Notas fiscais de produto (NF-e)

`$nfe->productInvoices` cobre o ciclo de vida completo da NF-e (modelo 55) no
host `api.nfse.io`, sob `/v2`: emissão, listagem por cursor, consulta,
cancelamento, carta de correção (CC-e), inutilização e downloads.

A emissão segue o **contrato 202 discriminado** (assíncrona; conclusão via
webhook): `create()` / `createWithStateTax()` devolvem
`ProductInvoicePending|ProductInvoiceIssued`. Não há `createAndWait()` nem
`createBatch()`.

:::tip Prefira webhooks para NF-e
Diferente da NFS-e, `productInvoices` **não** tem `getStatus()`. A conclusão da
emissão é orientada a webhook — configure um alvo em
[Webhooks](../webhooks.md). Se precisar de polling, use `retrieve()` e leia o
campo de fluxo do DTO.
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create($companyId, $data)` | Emite a NF-e. | `ProductInvoicePending\|ProductInvoiceIssued` |
| `createWithStateTax($companyId, $stateTaxId, $data)` | Emite vinculada a uma inscrição estadual. | `ProductInvoicePending\|ProductInvoiceIssued` |
| `list($companyId, $options)` | Lista por cursor; `$options` **obrigatório** com `environment`. | `ListResponse` |
| `retrieve($companyId, $invoiceId)` | Consulta por id. | `ProductInvoice` |
| `cancel($companyId, $invoiceId, $reason = null)` | Cancela; `reason` opcional vai na query. | `ProductInvoice` |
| `listItems($companyId, $invoiceId)` | Lista os itens da nota. | `array` (arrays crus) |
| `listEvents($companyId, $invoiceId)` | Lista os eventos fiscais. | `array` (arrays crus) |
| `downloadPdf($companyId, $invoiceId)` | DANFE PDF. | `string` (bytes crus) |
| `downloadXml($companyId, $invoiceId)` | XML autorizado. | `string` |
| `downloadRejectionXml($companyId, $invoiceId)` | XML de rejeição. | `string` |
| `downloadEpecXml($companyId, $invoiceId)` | XML de contingência EPEC. | `string` |
| `sendCorrectionLetter($companyId, $invoiceId, $correction)` | Emite CC-e. | `array` |
| `downloadCorrectionLetterPdf($companyId, $invoiceId)` | PDF da CC-e. | `string` |
| `downloadCorrectionLetterXml($companyId, $invoiceId)` | XML da CC-e. | `string` |
| `disable($companyId, $invoiceId, $data)` | Inutiliza uma nota específica. | `array` |
| `disableRange($companyId, $data)` | Inutiliza uma faixa de numeração. | `array` |

## Emitir uma NF-e

```php
use Nfe\Response\Pending;

$result = $nfe->productInvoices->create('55df4dc6b6cd9007e4f13ee8', [
    'buyer' => [
        'federalTaxNumber' => 11111111111111,
        'name'             => 'Cliente Exemplo LTDA',
    ],
    'items' => [
        ['code' => '001', 'description' => 'Produto X', 'quantity' => 1, 'unitAmount' => 99.9],
    ],
]);

if ($result instanceof Pending) {
    $result->invoiceId();   // acompanhe via webhook ou retrieve()
} else {
    $result->resource();    // Nfe\ProductInvoice
}
```

Para emitir vinculada a uma inscrição estadual específica (veja
[Inscrições estaduais](./state-taxes.md)):

```php
$result = $nfe->productInvoices->createWithStateTax($companyId, $stateTaxId, $data);
```

## Listar com `environment` obrigatório

A paginação é por cursor e o argumento `$options` é **obrigatório** — precisa
conter `environment` (string `"Production"` ou `"Test"`).

```php
$pagina = $nfe->productInvoices->list($companyId, [
    'environment' => 'Production',
    'limit'       => 50,
]);

foreach ($pagina->data as $nf) {
    echo $nf->id, PHP_EOL;
}

// Próxima página:
$proxima = $nfe->productInvoices->list($companyId, [
    'environment'   => 'Production',
    'startingAfter' => $pagina->page->startingAfter,
    'limit'         => 50,
]);
```

:::note `environment` é o ambiente da SEFAZ
Este `environment` (string) é um parâmetro real de ambiente da SEFAZ, separado
da configuração produção/teste da conta (definida em
[app.nfe.io](https://app.nfe.io)). O enum `Nfe\Environment` do cliente está
reservado para uso futuro.
:::

## Baixar arquivos (bytes crus)

Todos os downloads devolvem a `string` de bytes — grave com
`file_put_contents()`:

```php
file_put_contents('danfe.pdf', $nfe->productInvoices->downloadPdf($companyId, $invoiceId));
file_put_contents('nfe.xml', $nfe->productInvoices->downloadXml($companyId, $invoiceId));
```

## Carta de correção (CC-e)

Um texto vazio ou só com espaços lança
`Nfe\Exception\InvalidRequestException` antes de qualquer HTTP.

```php
$nfe->productInvoices->sendCorrectionLetter(
    $companyId,
    $invoiceId,
    'Correção do endereço de entrega do destinatário',
);

file_put_contents(
    'cce.pdf',
    $nfe->productInvoices->downloadCorrectionLetterPdf($companyId, $invoiceId),
);
```

## Cancelar e inutilizar

```php
// Cancelamento (com justificativa opcional na query):
$nfe->productInvoices->cancel($companyId, $invoiceId, 'Pedido cancelado pelo cliente');

// Inutilizar uma nota específica:
$nfe->productInvoices->disable($companyId, $invoiceId, [
    'reason' => 'Numeração não utilizada',
]);

// Inutilizar uma faixa de numeração:
$nfe->productInvoices->disableRange($companyId, [
    'environment' => 'Production',
    'serie'       => 1,
    'state'       => 'SP',
    'beginNumber' => 100,
    'lastNumber'  => 110,
    'reason'      => 'Falha de impressão',
]);
```

## Próximos passos

- [Notas de consumidor (NFC-e)](./consumer-invoices.md) — modelo 65.
- [Inscrições estaduais](./state-taxes.md) — pré-requisito para emitir NF-e.
- [Paginação](../pagination.md) — cursor vs. página.

---

## Notas fiscais de serviço (NFS-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/notas-fiscais-de-servico/index.md

# Notas fiscais de serviço (NFS-e)

`$nfe->serviceInvoices` é o recurso canônico de emissão da plataforma. Ele fala
com o host `api.nfe.io` no caminho `/v1` e cobre todo o ciclo de vida da NFS-e:
emissão assíncrona, listagem paginada, consulta, cancelamento, envio por e-mail
e download de PDF/XML.

A emissão segue o **contrato 202 discriminado**: `create()` devolve um union
type nativo, e você acompanha o processamento com `getStatus()` até um estado
terminal. Não existe `createAndWait()` nem `createBatch()` na `v3.0`.

:::note Host e versão
Todas as URLs efetivas ficam sob `https://api.nfe.io/v1/...`. Este é o único
recurso de nota que usa o host `api.nfe.io`; os demais usam `api.nfse.io`.
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create($companyId, $data)` | Emite a NFS-e. | `ServiceInvoicePending\|ServiceInvoiceIssued` |
| `list($companyId, $options = [])` | Lista paginada (page-style, `pageIndex` 1-based) com filtros de data. | `ListResponse` |
| `retrieve($companyId, $invoiceId)` | Consulta uma NFS-e por id. | `ServiceInvoice` |
| `cancel($companyId, $invoiceId)` | Cancela (síncrono) e devolve o modelo atualizado. | `ServiceInvoice` |
| `sendEmail($companyId, $invoiceId)` | Reenvia a nota por e-mail ao tomador. | `array` (típico: `{sent, message}`) |
| `downloadPdf($companyId, $invoiceId)` | PDF da nota. | `string` (bytes crus) |
| `downloadXml($companyId, $invoiceId)` | XML da nota. | `string` (bytes crus) |
| `getStatus($companyId, $invoiceId)` | Snapshot leve de status. | `array` (`flowStatus`, `flowMessage`, …) |

As opções de `list()` incluem `pageIndex` (**1-based**), `pageCount`,
`issuedBegin` e `issuedEnd`. Todo método aceita ainda um
`Nfe\Http\RequestOptions` opcional como último argumento.

:::warning Validação fail-fast
Todo método valida `companyId` e `invoiceId` **antes** de qualquer chamada HTTP.
Ids vazios ou em branco lançam `Nfe\Exception\InvalidRequestException` sem
tráfego de rede.
:::

## Emitir uma NFS-e e tratar o retorno discriminado

`create()` devolve `ServiceInvoicePending` (HTTP 202, enfileirada) ou
`ServiceInvoiceIssued` (HTTP 201, já materializada). Distinga com `instanceof`
contra as interfaces marcadoras `Nfe\Response\Pending` / `Nfe\Response\Issued`.

```php
use Nfe\Response\Pending;

$result = $nfe->serviceInvoices->create('55df4dc6b6cd9007e4f13ee8', [
    'cityServiceCode' => '2690',
    'description'     => 'Manutenção e suporte técnico',
    'servicesAmount'  => 100.0,
    'borrower'        => [
        'federalTaxNumber' => 191,
        'name'             => 'Banco do Brasil SA',
    ],
]);

if ($result instanceof Pending) {
    $result->invoiceId();   // id para reconsultar enquanto processa
    $result->location();    // caminho do header Location
} else {
    $result->resource();    // Nfe\ServiceInvoice já emitida
}
```

## Acompanhar até um estado terminal (polling)

Use `getStatus()` — endpoint leve que devolve `flowStatus`/`flowMessage` — com
`Nfe\Util\FlowStatus::isTerminal()`:

```php
use Nfe\Util\FlowStatus;

$companyId = '55df4dc6b6cd9007e4f13ee8';
$invoiceId = $result instanceof Pending ? $result->invoiceId() : $result->resource()->id;

do {
    sleep(3);
    $flow = $nfe->serviceInvoices->getStatus($companyId, $invoiceId)['flowStatus'] ?? '';
} while (!FlowStatus::isTerminal($flow));

if ($flow === 'Issued') {
    $invoice = $nfe->serviceInvoices->retrieve($companyId, $invoiceId);
}
```

:::warning Terminal ≠ sucesso
`isTerminal()` também é `true` para `IssueFailed`/`CancelFailed`. Compare o
status concreto. Veja [Emissão assíncrona e polling](../async-and-polling.md).
:::

## Baixar PDF e XML (bytes crus)

Os downloads retornam uma `string` com os bytes do arquivo — grave com
`file_put_contents()`:

```php
file_put_contents('nfse.pdf', $nfe->serviceInvoices->downloadPdf($companyId, $invoiceId));
file_put_contents('nfse.xml', $nfe->serviceInvoices->downloadXml($companyId, $invoiceId));
```

## Cancelar e reenviar por e-mail

```php
$cancelada = $nfe->serviceInvoices->cancel($companyId, $invoiceId);
$cancelada->flowStatus;   // "Cancelled"

$envio = $nfe->serviceInvoices->sendEmail($companyId, $invoiceId);
$envio['sent'] ?? null;   // true/false
```

## Próximos passos

- [Primeiros passos](../getting-started.md) — instalação e primeira emissão.
- [Notas de produto (NF-e)](./product-invoices.md) — host `api.nfse.io`, cursor e CC-e.
- [Webhooks](../webhooks.md) — conclusão por push em vez de polling.

---

## Inscrições estaduais (stateTaxes) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/inscricoes-estaduais/index.md

# Inscrições estaduais (`stateTaxes`)

`$nfe->stateTaxes` gerencia as **inscrições estaduais (IE)** de uma empresa
emissora — pré-requisito para emitir [NF-e](./product-invoices.md) e
[NFC-e](./consumer-invoices.md). Escopo de **empresa**, host `api.nfse.io`
(`/v2`), chave principal.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list($companyId, $opts = null)` | Lista por cursor. | `ListResponse` |
| `create($companyId, $data)` | Cadastra uma IE. | `NfeStateTax` |
| `retrieve($companyId, $stateTaxId)` | Consulta por id. | `NfeStateTax` |
| `update($companyId, $stateTaxId, $data)` | Atualiza. | `NfeStateTax` |
| `delete($companyId, $stateTaxId)` | Exclui. | `void` |

:::note Envelope `{ stateTax }` no corpo
`create()` e `update()` embrulham o corpo como `{ "stateTax": { … } }`
automaticamente (paridade com o SDK Node) — você passa só o conteúdo interno; a
resposta volta hidratada sem envelope.
:::

## Cadastrar uma inscrição estadual

```php
$ie = $nfe->stateTaxes->create('55df4dc6b6cd9007e4f13ee8', [
    'code'            => 'SP',
    'taxNumber'       => '111.111.111.111',
    'serie'           => 1,
    'number'          => 1,
    'environmentType' => 'Production',
]);
```

## Listar (cursor) e consultar

```php
$pagina = $nfe->stateTaxes->list($companyId, ['limit' => 25]);

foreach ($pagina->data as $ie) {
    echo $ie->code, PHP_EOL;
}

// Próxima página:
$proxima = $nfe->stateTaxes->list($companyId, [
    'startingAfter' => $pagina->page->startingAfter,
    'limit'         => 25,
]);

$ie = $nfe->stateTaxes->retrieve($companyId, $stateTaxId);
```

## Atualizar e excluir

```php
$nfe->stateTaxes->update($companyId, $stateTaxId, ['serie' => 2]);

$nfe->stateTaxes->delete($companyId, $stateTaxId);   // void
```

:::tip Emissão vinculada à IE
Com a IE cadastrada, emita NF-e/NFC-e vinculadas a ela via
`createWithStateTax($companyId, $stateTaxId, $data)` nos recursos de
[produto](./product-invoices.md) e [consumidor](./consumer-invoices.md).
:::

## Veja também

- [Notas de produto (NF-e)](./product-invoices.md) — emissão que depende da IE.
- [Consulta de CNPJ](./legal-entity-lookup.md) — descubra a IE de terceiros por UF.
- [Paginação](../pagination.md) — cursor vs. página.

---

## Cálculo de impostos (taxCalculation) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/calculo-de-impostos/index.md

# Cálculo de impostos (`taxCalculation`)

`$nfe->taxCalculation` aciona o **motor tributário** da NFE.io para calcular os
impostos de uma operação. Escopo de **tenant** (recebe `$tenantId` como primeiro
argumento), host `api.nfse.io` (`/v2`).

:::note Usa a `apiKey` principal
Apesar de ser um serviço de consulta, o cálculo de impostos **não** é família de
dados — sempre usa a chave principal.
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `calculate($tenantId, $request)` | Calcula os impostos da operação. | `array` (resposta crua) |

Requisição e resposta são arrays associativos sem DTO. Como referência do shape
esperado, o SDK embarca a classe gerada
`Nfe\Generated\CalculoImpostosV1\CalculateRequest` — você pode espelhá-la, mas
não é um tipo obrigatório.

## Calcular os impostos de uma operação

```php
$resultado = $nfe->taxCalculation->calculate($tenantId, [
    'operationType' => 'Sale',
    'issuer'        => ['federalTaxNumber' => 11444555000149, 'state' => 'SP'],
    'recipient'     => ['federalTaxNumber' => 61365284000104, 'state' => 'RJ'],
    'items'         => [
        [
            'code'       => '001',
            'ncm'        => '85171231',
            'quantity'   => 1,
            'unitAmount' => 1999.90,
        ],
    ],
]);

// A resposta é um array cru com os tributos calculados por item.
```

:::warning Validação local
`$tenantId` vazio ou `items` vazio lançam
`Nfe\Exception\InvalidRequestException` **antes** de qualquer requisição.
:::

:::tip Combine com os códigos fiscais
Os valores aceitos em campos de classificação (código de operação, finalidade de
aquisição, perfis de contribuinte) vêm de [`taxCodes`](./tax-codes.md).
:::

## Veja também

- [Códigos fiscais](./tax-codes.md) — dados de referência do motor.
- [Notas de produto (NF-e)](./product-invoices.md) — emissão com os valores calculados.
- [Tratamento de erros](../errors.md).

---

## Códigos fiscais (taxCodes) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/codigos-fiscais/index.md

# Códigos fiscais (`taxCodes`)

`$nfe->taxCodes` expõe os **dados de referência** do motor tributário: códigos
de operação, finalidades de aquisição e perfis fiscais de emitente e
destinatário. Recurso **global** (não recebe `$companyId`), host `api.nfse.io`
(`/v2`), chave principal.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `listOperationCodes($opts = [])` | Códigos de operação. | `TaxCodePaginatedResponse` |
| `listAcquisitionPurposes($opts = [])` | Finalidades de aquisição. | `TaxCodePaginatedResponse` |
| `listIssuerTaxProfiles($opts = [])` | Perfis fiscais de emitente. | `TaxCodePaginatedResponse` |
| `listRecipientTaxProfiles($opts = [])` | Perfis fiscais de destinatário. | `TaxCodePaginatedResponse` |

As opções de paginação são `pageIndex` (**1-based**, padrão 1) e `pageCount`
(padrão 50, **máximo 50**).

:::note Tipo de resposta próprio
Estes métodos retornam `TaxCodePaginatedResponse` — com `items`, `currentPage`,
`totalPages` e `totalCount` — em vez do `ListResponse` dos demais recursos.
:::

## Listar códigos de operação

```php
$pagina = $nfe->taxCodes->listOperationCodes(['pageIndex' => 1, 'pageCount' => 50]);

foreach ($pagina->items as $codigo) {
    // dados de referência de cada código de operação
}

// Percorrer todas as páginas:
for ($i = 1; $i <= $pagina->totalPages; $i++) {
    $p = $nfe->taxCodes->listOperationCodes(['pageIndex' => $i, 'pageCount' => 50]);
    // ... $p->items
}
```

## Demais catálogos

```php
$nfe->taxCodes->listAcquisitionPurposes();
$nfe->taxCodes->listIssuerTaxProfiles();
$nfe->taxCodes->listRecipientTaxProfiles();
```

:::tip Cacheie localmente
São catálogos de referência que mudam raramente — cacheie o resultado na sua
aplicação em vez de consultar a cada operação.
:::

## Veja também

- [Cálculo de impostos](./tax-calculation.md) — onde esses códigos são usados.
- [Paginação](../pagination.md) — as formas de paginação do SDK.

---

## Conhecimentos de transporte (CT-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/conhecimentos-de-transporte/index.md

# Conhecimentos de transporte (CT-e)

`$nfe->transportationInvoices` gerencia o recebimento de **CT-e de entrada**
(conhecimentos de transporte emitidos contra a sua empresa) no host
`api.nfse.io`, sob `/v2`: habilitação/desabilitação da captura, consulta de
documentos por chave de acesso e download de XMLs.

:::note Recurso de entrada, não de emissão
Este recurso **consome** CT-e emitidos por terceiros. Ele usa a `apiKey`
principal (não é família de dados).
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `enable($companyId, $data)` | Habilita o recebimento de CT-e para a empresa. | `InboundSettings` |
| `disable($companyId)` | Desabilita o recebimento. | `InboundSettings` |
| `getSettings($companyId)` | Configurações atuais de captura. | `InboundSettings` |
| `retrieve($companyId, $accessKey)` | Consulta um CT-e por chave de acesso (44 dígitos). | `array` |
| `downloadXml($companyId, $accessKey)` | XML do CT-e. | `string` (bytes crus) |
| `getEvent($companyId, $accessKey, $eventKey)` | Consulta um evento do CT-e. | `array` |
| `downloadEventXml($companyId, $accessKey, $eventKey)` | XML de um evento. | `string` |

## Habilitar o recebimento

```php
$settings = $nfe->transportationInvoices->enable('55df4dc6b6cd9007e4f13ee8', [
    'startFromDate' => '2026-01-01',
]);

// Conferir depois:
$settings = $nfe->transportationInvoices->getSettings($companyId);
```

## Consultar um CT-e e baixar o XML

```php
$accessKey = '35260111222333000181570010000012341000012349';

$cte = $nfe->transportationInvoices->retrieve($companyId, $accessKey);

file_put_contents(
    'cte.xml',
    $nfe->transportationInvoices->downloadXml($companyId, $accessKey),
);
```

:::warning Chave de acesso é validada localmente
A chave de acesso precisa ter **44 dígitos**; um valor com tamanho errado lança
`Nfe\Exception\InvalidRequestException` antes de qualquer requisição.
:::

## Eventos do CT-e

```php
$evento = $nfe->transportationInvoices->getEvent($companyId, $accessKey, $eventKey);

file_put_contents(
    'cte-evento.xml',
    $nfe->transportationInvoices->downloadEventXml($companyId, $accessKey, $eventKey),
);
```

## Desabilitar

```php
$nfe->transportationInvoices->disable($companyId);
```

## Próximos passos

- [Notas de entrada (NF-e)](./inbound-product-invoices.md) — o equivalente para NF-e recebidas.
- [Webhooks](../webhooks.md) — receba os documentos capturados por push.
- [Downloads](../downloads.md) — o contrato de bytes crus.

---

## Webhooks (CRUD) no SDK PHP da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/recursos/webhooks/index.md

# Webhooks (`webhooks`)

`$nfe->webhooks` gerencia os **alvos de entrega** de webhook por empresa —
URLs que a NFE.io chama quando eventos acontecem (nota emitida, cancelada,
documento de entrada recebido…). Escopo de **empresa**, família `main`
(`api.nfe.io` `/v1`), chave principal.

:::warning CRUD aqui, verificação lá
Este recurso é só o **CRUD** dos alvos. A verificação de assinatura das
entregas (`HMAC-SHA1`, header `X-Hub-Signature`) fica na classe **estática**
`Nfe\Webhook` — veja o guia de [Webhooks](../webhooks.md).
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `list($companyId)` | Lista os webhooks da empresa. | `ListResponse` |
| `create($companyId, $data)` | Registra um novo alvo. | `Webhook` |
| `retrieve($companyId, $webhookId)` | Consulta por id. | `Webhook` |
| `update($companyId, $webhookId, $data)` | Atualiza URL/eventos/segredo. | `Webhook` |
| `delete($companyId, $webhookId)` | Exclui. | `void` |
| `test($companyId, $webhookId)` | Dispara uma entrega de teste. | `array` |
| `getAvailableEvents()` | Lista de eventos suportados (hard-coded, sem HTTP). | `array` |

## Exemplos

### Registrar um alvo de entrega

```php
$webhook = $nfe->webhooks->create('55df4dc6b6cd9007e4f13ee8', [
    'url'    => 'https://minha-app.example.com/webhooks/nfe',
    'secret' => $_ENV['NFE_WEBHOOK_SECRET'],
]);
```

Guarde o mesmo `secret` na sua aplicação — ele é o HMAC usado para assinar cada
entrega, e você o passa a `Nfe\Webhook::verifySignature()` no seu endpoint.

### Testar, atualizar e excluir

```php
// Entrega de teste para validar o endpoint de ponta a ponta:
$nfe->webhooks->test($companyId, $webhook->id);

$nfe->webhooks->update($companyId, $webhook->id, [
    'url' => 'https://minha-app.example.com/webhooks/nfe/v2',
]);

$nfe->webhooks->delete($companyId, $webhook->id);   // void
```

### Eventos disponíveis

```php
// Lista embutida no SDK — não faz chamada de rede:
$eventos = $nfe->webhooks->getAvailableEvents();
```

## Veja também

- [Guia de webhooks](../webhooks.md) — verificação de assinatura e idempotência.
- [Emissão assíncrona e polling](../async-and-polling.md) — push vs. polling.
- [Empresas](./companies.md) — o escopo dos alvos.

---

## Verificação de webhooks da NFE.io em PHP

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/php/webhooks/index.md

# Webhooks

Em vez de fazer polling até um estado terminal, você pode receber a conclusão da
emissão por push. A NFE.io entrega um webhook; seu endpoint **verifica a
assinatura** e reage ao evento. Este guia cobre a verificação canônica via
`Nfe\Webhook`.

## Como a NFE.io assina as entregas

Cada entrega traz o cabeçalho `X-Hub-Signature` com um HMAC-SHA1 calculado sobre
os **bytes exatos** do corpo da requisição, no formato `sha1=<40 hex>`:

```text
X-Hub-Signature: sha1=BCD17C02B9E3B40A18E745E7E04247E4AD2DD935
```

## A API de verificação

A verificação vive na classe **estática** `Nfe\Webhook` — ela não precisa de um
`Nfe\Client`, não lê configuração e não faz nenhuma chamada de rede.

:::warning `Nfe\Webhook` ≠ `$nfe->webhooks`
`$nfe->webhooks` é o **CRUD** de webhooks (criar/listar/atualizar alvos de
entrega — veja o [cookbook](./recursos/webhooks.md)). A verificação de
assinatura é a classe estática `Nfe\Webhook`; não procure
`$nfe->webhooks->verifySignature()` — não existe.
:::

```php
use Nfe\Webhook;

$ok = Webhook::verifySignature(
    payload: file_get_contents('php://input'),
    signature: $_SERVER['HTTP_X_HUB_SIGNATURE'] ?? '',
    secret: $_ENV['NFE_WEBHOOK_SECRET'],
);
```

### `verifySignature(): bool`

Retorna `true` **somente** quando o HMAC-SHA1 confere exatamente. A comparação é
feita em tempo constante (`hash_equals()`), o prefixo `sha1=` é opcional (hex
puro também é aceito) e a comparação de algoritmo/hex é case-insensitive. Um
quarto argumento `$algo` (padrão `'sha1'`) permite outro algoritmo — um header
`sha256=` contra `$algo = 'sha1'` é **rejeitado** (sem downgrade).

:::tip Nunca lança exceção
`verifySignature()` **nunca** lança. Entrada ausente, malformada, com algoritmo
errado ou conteúdo não hexadecimal resulta em `false`.
:::

### `constructEvent(): Nfe\WebhookEvent`

Quando você quer não só validar, mas também desempacotar o evento, use
`constructEvent()`. Ele verifica primeiro; em caso de falha de assinatura **ou**
de JSON inválido, lança `Nfe\Exception\SignatureVerificationException`.

```php
use Nfe\Webhook;

$event = Webhook::constructEvent(
    payload: $raw,
    sigHeader: $signature,
    secret: $_ENV['NFE_WEBHOOK_SECRET'],
);

$event->type;       // ex.: "invoice.issued" (a chave `action` do envelope v2)
$event->data;       // array com o payload (a chave `payload` do envelope)
$event->id;         // id estável para deduplicação, ou null
$event->createdAt;  // timestamp ISO-8601 da entrega, ou null
```

`Nfe\WebhookEvent` é um objeto de valor imutável (`final readonly`). Se o corpo
carrega o envelope v2 `{ action, payload }`, ele é desembrulhado: `type` recebe
`action` e `data` recebe o `payload` interno. Sem envelope, o helper procura um
campo `type`/`event_type`/`action` no nível raiz.

## Leia o corpo CRU antes de parsear o JSON

A NFE.io assina os bytes que entregou. Leia o corpo cru **antes** de qualquer
parsing de JSON e passe esses bytes ao verificador.

:::warning Não re-serialize o payload
Nunca passe um array já parseado e re-serializado (por exemplo
`json_encode($payload)`). A ordem das chaves e os espaços em branco vão diferir
dos bytes assinados, e a verificação falhará de forma imprevisível. Sempre use o
corpo cru — `file_get_contents('php://input')` (ou `$request->getContent()` no
Laravel/Symfony).
:::

## Exemplo: endpoint em PHP puro

```php
<?php

use Nfe\Exception\SignatureVerificationException;
use Nfe\Webhook;

require __DIR__ . '/vendor/autoload.php';

$raw       = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE'] ?? '';

try {
    $event = Webhook::constructEvent($raw, $signature, $_ENV['NFE_WEBHOOK_SECRET']);
} catch (SignatureVerificationException) {
    http_response_code(401);
    exit;
}

// Dedupe pelo id do evento/nota antes de aplicar efeitos colaterais.
processarEventoIdempotente($event->type, $event->data, $event->id);

http_response_code(200);
```

:::note No Laravel
Use `$request->getContent()` como corpo cru e
`$request->header('X-Hub-Signature')` como assinatura, e **exclua a rota do
middleware de CSRF** (webhooks não têm token CSRF).
:::

## Validade não é frescor — handlers devem ser idempotentes

A NFE.io **não** envia primitiva de anti-replay: as entregas trazem apenas o
HMAC-SHA1 sobre o corpo, sem timestamp e sem nonce. Uma assinatura válida prova
**autenticidade**, mas não **frescor** — uma entrega reproduzida (replay)
carrega uma assinatura perfeitamente válida.

:::warning Sempre dedupe
Trate seus handlers como **idempotentes** e faça **deduplicação pelo
`$event->id`** (id do evento ou da nota). Processar a mesma entrega duas vezes
não pode gerar efeitos colaterais duplicados.
:::

## Próximos passos

- [Cookbook de webhooks](./recursos/webhooks.md) — CRUD dos alvos de entrega.
- [Emissão assíncrona e polling](./async-and-polling.md) — polling como alternativa ao push.
- [Tratamento de erros](./errors.md) — `SignatureVerificationException` na hierarquia.

---

## Emissão assíncrona e polling no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/emissao-assincrona-e-polling/index.md

# Emissão assíncrona e polling

A emissão de documentos fiscais é, em geral, **assíncrona**: a API aceita a
requisição (HTTP 202) e segue processando. Esta página explica o contrato de
retorno, os dois tipos de resultado e como acompanhar o processamento até um
estado terminal.

## O contrato HTTP 202

Quando a API responde **202 Accepted**, o documento ainda **não** foi
materializado — ela apenas aceitou o pedido. Quando responde **201/200**, o
documento já está pronto. O `create` traduz isso em um **resultado discriminado**:
um de dois tipos.

| Resposta HTTP | Tipo de resultado | Significado |
| --- | --- | --- |
| 202 Accepted | `Nfe::*Pending` | Em processamento; reconsulte depois. |
| 201 / 200 | `Nfe::*Issued` | Documento já materializado. |

:::note `*Pending` e `*Issued` por recurso
Cada recurso expõe seu par de resultados (por exemplo,
`Nfe::Resources::ServiceInvoicePending` e `Nfe::Resources::ServiceInvoiceIssued`).
O tipo base `Nfe::Pending` carrega `invoice_id` e `location`; o `Nfe::Issued`
carrega `resource`.
:::

## Os dois tipos de resultado

### `*Pending` (202)

- `#invoice_id` — id extraído do último segmento do header `Location`; use-o para
  reconsultar enquanto processa.
- `#location` — o valor bruto do header `Location`.
- `#pending?` → `true`.

### `*Issued` (201/200)

- `#resource` — o documento já materializado (DTO hidratado).
- `#issued?` → `true`.

## Distinguindo o resultado

Você pode discriminar com os predicados `pending?` / `issued?` ou com pattern
matching:

```ruby
result = client.service_invoices.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: { cityServiceCode: "2690", servicesAmount: 100.0, description: "Suporte" }
)

case result
in Nfe::Resources::ServiceInvoicePending => pending
  pending.invoice_id    # reconsulte com este id
in Nfe::Resources::ServiceInvoiceIssued => issued
  issued.resource       # NFS-e já pronta
end
```

Com predicados:

```ruby
invoice_id = result.pending? ? result.invoice_id : result.resource.id
```

## Loop de polling manual

Faça polling com `retrieve` até um **estado terminal**, decidido por
`Nfe::FlowStatus.terminal?`:

```ruby
company_id = "55df4dc6b6cd9007e4f13ee8"
invoice_id = result.pending? ? result.invoice_id : result.resource.id

invoice =
  loop do
    current = client.service_invoices.retrieve(
      company_id: company_id,
      invoice_id: invoice_id
    )
    break current if Nfe::FlowStatus.terminal?(current.flow_status)

    sleep 2
  end

# `invoice.flow_status` agora é um estado terminal.
```

### Estados de fluxo (`flow_status`)

Estados **terminais** (encerram o polling):

| Status | Significado |
| --- | --- |
| `Issued` | Emitido com sucesso. |
| `IssueFailed` | Falha na emissão. |
| `Cancelled` | Cancelado. |
| `CancelFailed` | Falha no cancelamento. |

`Nfe::FlowStatus.terminal?` aceita `String` ou `Symbol` e retorna `true` apenas
para os quatro acima; qualquer outro valor (como `WaitingSend` ou
`PullFromCityHall`) retorna `false`.

:::tip `get_status` em `service_invoices`
O recurso `service_invoices` oferece `get_status`, derivado do `retrieve` (sem
HTTP extra), como atalho para inspecionar o estado atual.
:::

## Por que não existe `create_and_wait`?

A `v1.0` **não** implementa `create_and_wait`, `create_batch` nem
`poll_until_complete`. O contrato discriminado `*Pending` / `*Issued` somado a
`Nfe::FlowStatus.terminal?` é suficiente para escrever loops de polling manuais,
e esses auxiliares ficam deliberadamente adiados para uma versão futura — sem
quebrar o contrato público.

:::warning Não chame helpers inexistentes
Referenciar `client.poll_until_complete(...)` ou `resource.create_and_wait(...)`
na `v1.0` levanta `NoMethodError`, pois o método não está definido.
:::

## Próximos passos

- [Tratamento de erros](./errors.md) — trate falhas durante o polling.
- [Configuração](./configuration.md) — ajuste `timeout` e `max_retries`.
- [Primeiros passos](./getting-started.md) — a primeira emissão de ponta a ponta.

---

## Configuração do cliente do SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/configuracao/index.md

# Configuração

Esta página descreve como configurar o `Nfe::Client`: os argumentos aceitos
diretamente no construtor, as opções avançadas que vivem em `Nfe::Configuration`,
o fallback por variáveis de ambiente, o modelo de duas chaves e as configurações
de rede (TLS e proxy).

## Argumentos de `Nfe::Client.new`

O construtor aceita um conjunto enxuto de opções de conveniência:

```ruby
client = Nfe::Client.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  data_api_key: nil,
  configuration: nil,
  environment: :production,
  timeout: 30,
  max_retries: 3,
  logger: nil,
  user_agent_suffix: nil
)
```

| Argumento | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `api_key` | `String`, `nil` | `nil` | Chave principal. Cai para `NFE_API_KEY` quando ausente. |
| `data_api_key` | `String`, `nil` | `nil` | Chave dos serviços de dados. Cai para `NFE_DATA_API_KEY`. |
| `configuration` | `Nfe::Configuration`, `nil` | `nil` | Quando informado, **os demais argumentos de conveniência são ignorados**. |
| `environment` | `Symbol` | `:production` | `:production` ou `:development`. Reservado para uso futuro (sem efeito hoje). |
| `timeout` | `Integer` | `30` | Timeout de leitura em segundos (deve ser positivo). |
| `max_retries` | `Integer` | `3` | Orçamento de retentativas (inteiro não negativo). |
| `logger` | objeto, `nil` | `nil` | Logger opcional (responde a `info`/`warn`/`error`). |
| `user_agent_suffix` | `String`, `nil` | `nil` | Sufixo anexado ao `User-Agent` do SDK. |

:::note Validação na construção
As opções são validadas na criação. Valores inválidos (por exemplo, `timeout`
não positivo, `max_retries` negativo ou `environment` desconhecido) levantam
`Nfe::ConfigurationError` antes de qualquer requisição HTTP. Veja
[Tratamento de erros](./errors.md).
:::

## Opções avançadas — somente em `Nfe::Configuration`

Algumas opções **não** são aceitas diretamente por `Nfe::Client.new`. Elas vivem
em `Nfe::Configuration` e são injetadas via `configuration:`:

| Opção | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `open_timeout` | `Integer` | `10` | Timeout de conexão em segundos (deve ser positivo). |
| `base_url_overrides` | `Hash{Symbol=>String}` | `{}` | Sobrescreve o host por família (escape hatch). |
| `ca_file` | `String`, `nil` | `nil` | Caminho de um bundle de CA a **adicionar** ao trust store. |
| `ca_path` | `String`, `nil` | `nil` | Diretório de certificados de CA a **adicionar** ao trust store. |
| `proxy` | `String`, `URI`, `nil` | `nil` | Repassado ao `Net::HTTP`. |

Para usá-las, construa um `Nfe::Configuration` e passe-o ao cliente. Note que ao
informar `configuration:`, os argumentos de conveniência (como `api_key:` ou
`timeout:`) passados ao `Client.new` são ignorados — tudo deve estar na
configuração:

```ruby
configuration = Nfe::Configuration.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  data_api_key: ENV.fetch("NFE_DATA_API_KEY", nil),
  timeout: 60,
  open_timeout: 15,
  max_retries: 5,
  proxy: "http://proxy.interno:3128",
  ca_file: "/etc/ssl/certs/corporate-ca.pem"
)

client = Nfe::Client.new(configuration: configuration)
```

:::tip Quando preciso de `Nfe::Configuration`?
Para o caso comum, basta `Nfe::Client.new(api_key: "...")`. Use a configuração
explícita quando precisar de `open_timeout`, `proxy`, `ca_file`/`ca_path` ou
`base_url_overrides`.
:::

## Fallback por variáveis de ambiente

As chaves resolvem nesta ordem de precedência: **argumento explícito não vazio
vence**; caso contrário, a variável de ambiente (quando presente) é adotada.

- `api_key` cai para `NFE_API_KEY`.
- `data_api_key` cai para `NFE_DATA_API_KEY`.

```sh
export NFE_API_KEY="sua-chave-principal"
export NFE_DATA_API_KEY="sua-chave-de-dados"
```

```ruby
# Sem argumentos: ambas as chaves vêm do ambiente.
client = Nfe::Client.new
```

:::note Pelo menos uma chave
A validação "ao menos uma chave informada" roda **após** o fallback. Se nenhuma
chave for resolvida (nem por argumento, nem por ambiente), a construção levanta
`Nfe::ConfigurationError`. Um cliente apenas com `data_api_key` é válido — a
exigência da chave principal é adiada até que um recurso da família `main` seja
acessado.
:::

## Modelo de duas chaves

O SDK usa duas chaves. As famílias de **dados** — `addresses` (CEP),
`legal_entity` (CNPJ), `natural_person` (CPF) e `nfe_query` (consultas) — usam a
`data_api_key` quando presente, com **fallback** para a `api_key`. Todas as
demais famílias usam a `api_key`.

```ruby
# Cliente com as duas chaves:
client = Nfe::Client.new(
  api_key: "chave-de-emissao",
  data_api_key: "chave-de-consulta"
)

# - client.addresses          → usa data_api_key (família de dados)
# - client.legal_entity_lookup → usa data_api_key
# - client.service_invoices    → usa api_key (emissão)
# - client.companies           → usa api_key
```

Quando nenhuma chave resolve para a família acessada, o SDK levanta
`Nfe::ConfigurationError` no momento da requisição.

:::note CT-e usa a chave principal
A família `cte` (`api.nfse.io` — emissão de NF-e/NFC-e/CT-e e regras tributárias)
**não** é uma família de dados: usa a `api_key`. Emissão é capacidade central,
não consulta de dados.
:::

## Sandbox vs. Produção

:::warning A separação produção vs. teste fica na conta, não no SDK
A escolha entre **produção** e **teste (homologação)** é definida na configuração
da sua conta em [app.nfe.io](https://app.nfe.io) (lado servidor) — **não** pela
chave de API nem pelo SDK. Não existe "URL de sandbox": produção e desenvolvimento
apontam para os mesmos endpoints.
:::

O argumento `environment:` do cliente (`:production` / `:development`) está
**reservado para uso futuro**: ele é validado, mas hoje **não tem efeito** sobre
endpoints, chaves ou comportamento. Suporte completo a `environment:` está
planejado para uma versão futura.

:::note Ambiente SEFAZ é outra coisa
Os recursos de produto e consumidor (NF-e/NFC-e) aceitam um parâmetro
**separado** `environment:` do tipo `String` (`"Production"` / `"Test"`) nas
operações de listagem e emissão — esse é o ambiente da SEFAZ e é tratado nos
guias daqueles recursos, não aqui.
:::

## TLS e proxy

### TLS — confiança só pode ser adicionada

`ca_file` (e, opcionalmente, `ca_path`) é o **único** override do trust store de
TLS e só pode **adicionar/substituir** o bundle de CA usado para verificar o par.
A verificação completa do certificado do servidor permanece ativa em toda
requisição.

```ruby
configuration = Nfe::Configuration.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  ca_file: "/etc/ssl/certs/corporate-ca.pem"
)
```

:::warning Não há como desabilitar a verificação
Por design, **não existe** API pública para desabilitar a verificação do par
(sem `VERIFY_NONE`, sem `insecure_ssl`). O atributo `insecureSsl` que você possa
ver na API é uma propriedade do **alvo de entrega de webhook** (lado servidor) e
não tem relação com a configuração de TLS de saída do SDK.
:::

### Proxy

Defina `proxy` em `Nfe::Configuration` para repassá-lo ao `Net::HTTP`:

```ruby
configuration = Nfe::Configuration.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  proxy: "http://usuario:senha@proxy.interno:3128"
)
```

## Próximos passos

- [Emissão assíncrona e polling](./async-and-polling.md) — o contrato HTTP 202.
- [Tratamento de erros](./errors.md) — `rescue` por tipo.
- [Primeiros passos](./getting-started.md) — instalação e primeira emissão.

---

## Downloads de PDF e XML no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/downloads/index.md

# Downloads

Os recursos de nota expõem métodos para baixar PDF e XML. Há **dois contratos de
retorno distintos** — leia esta página com atenção antes de salvar o arquivo.

## Contrato 1: bytes binários (a maioria dos recursos)

Os métodos de download de `service_invoices`, `consumer_invoices`,
`transportation_invoices`, `inbound_product_invoices`, além de
`product_invoice_query` e `consumer_invoice_query`, retornam uma **String
binária** (encoding `ASCII-8BIT`). Salve sempre com `File.binwrite` para não
corromper o conteúdo:

```ruby
pdf_bytes = client.service_invoices.download_pdf(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  invoice_id: "abc-123"
)

File.binwrite("nota.pdf", pdf_bytes)
```

O mesmo vale para o XML:

```ruby
xml_bytes = client.service_invoices.download_xml(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  invoice_id: "abc-123"
)

File.binwrite("nota.xml", xml_bytes)
```

:::tip ZIP de toda a empresa
Em `service_invoices`, omitir `invoice_id:` (ou passar `nil`) baixa o **ZIP** com
os documentos da empresa em vez de um único arquivo. O retorno continua sendo
bytes binários.
:::

## Contrato 2: `Nfe::NfeFileResource` (product invoices)

:::warning Exceção importante
Os métodos `download_*` de `product_invoices` e `product_invoices_rtc` **NÃO**
retornam bytes. Eles retornam um `Nfe::NfeFileResource` — um objeto de valor que
carrega a **URI** do arquivo, porque o host `api.nfse.io/v2` responde com um
envelope JSON `{ uri }`, e não com o arquivo em si.
:::

`Nfe::NfeFileResource` expõe `#uri`, `#name`, `#content_type` e `#size`. Para
obter os bytes, faça o download da `uri` separadamente:

```ruby
file = client.product_invoices.download_pdf(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  invoice_id: "abc-123"
)

file.uri          # ex.: "https://.../danfe.pdf"
file.content_type # ex.: "application/pdf"

require "open-uri"
File.binwrite("danfe.pdf", URI.open(file.uri).read)
```

Os demais downloads de `product_invoices` seguem o mesmo contrato e também
devolvem um `Nfe::NfeFileResource`: `download_xml`, `download_rejection_xml`,
`download_epec_xml`, `download_correction_letter_pdf` e
`download_correction_letter_xml`.

## Resumo dos contratos

| Recurso | Retorno do `download_*` | Como salvar |
| --- | --- | --- |
| `service_invoices` | String binária (`ASCII-8BIT`) | `File.binwrite` direto |
| `consumer_invoices` | String binária | `File.binwrite` direto |
| `transportation_invoices` | String binária | `File.binwrite` direto |
| `inbound_product_invoices` | String binária | `File.binwrite` direto |
| `product_invoice_query` | String binária | `File.binwrite` direto |
| `consumer_invoice_query` | String binária | `File.binwrite` direto |
| `product_invoices` | `Nfe::NfeFileResource` (URI) | baixe a `#uri` e então `File.binwrite` |
| `product_invoices_rtc` | `Nfe::NfeFileResource` (URI) | baixe a `#uri` e então `File.binwrite` |

## Próximos passos

- [Roteamento multi-host](./multi-host-routing.md) — por que os dois contratos existem (hosts diferentes).
- [Emissão RTC](./rtc-emission.md) — NF-e/NFC-e e NFS-e da Reforma Tributária.
- [Paginação](./pagination.md) — liste notas antes de baixá-las.

---

## Tratamento de erros no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/tratamento-de-erros/index.md

# Tratamento de erros

Todos os erros do SDK derivam de `Nfe::Error`, então você pode capturar a
família inteira com um único `rescue Nfe::Error`. Esta página descreve a
hierarquia, os códigos HTTP mapeados, padrões de `rescue` por tipo, a validação
client-side e os erros de rede.

## A hierarquia de erros

| Classe | Código HTTP | Quando ocorre |
| --- | --- | --- |
| `Nfe::Error` | — | Base de toda a família. |
| `Nfe::AuthenticationError` | 401 | Chave de API ausente ou inválida. |
| `Nfe::AuthorizationError` | 403 | Chave válida, mas sem permissão para o recurso. |
| `Nfe::InvalidRequestError` | 400 / 422 | Requisição malformada ou reprovada na validação. |
| `Nfe::NotFoundError` | 404 | Recurso não existe. |
| `Nfe::ConflictError` | 409 | Conflito com o estado atual do recurso. |
| `Nfe::RateLimitError` | 429 | Excesso de requisições; expõe `#retry_after`. |
| `Nfe::ServerError` | 5xx | Falha no servidor da API. |
| `Nfe::ApiConnectionError` | — | Falha de rede (DNS, conexão recusada, TLS, reset). |
| `Nfe::TimeoutError` | — | Timeout de conexão/leitura (`< ApiConnectionError`). |
| `Nfe::SignatureVerificationError` | — | Assinatura de webhook reprovada. |
| `Nfe::ConfigurationError` | — | SDK mal configurado (chave ausente, `environment` inválido). |
| `Nfe::InvoiceProcessingError` | — | Resposta 202 viola o protocolo (ex.: sem header `Location`). |

:::note `TimeoutError` é subclasse de `ApiConnectionError`
Um `rescue Nfe::ApiConnectionError` também captura `Nfe::TimeoutError`. Trate o
timeout antes, se quiser distingui-lo.
:::

## Contexto carregado pelos erros HTTP

Erros derivados de uma resposta HTTP carregam contexto para diagnóstico:
`#status_code`, `#request_id`, `#error_code`, `#response_body` e
`#response_headers`.

```ruby
begin
  client.service_invoices.retrieve(company_id: "...", invoice_id: "...")
rescue Nfe::Error => e
  e.status_code   # ex.: 404
  e.request_id    # id de correlação do servidor
  e.error_code    # código de erro legível por máquina
end
```

:::tip `#to_h` é seguro para logs
`Nfe::Error#to_h` devolve um Hash com `type`, `message`, `status_code`,
`request_id` e `error_code` — e **omite deliberadamente** o corpo e os headers
brutos, que podem conter a chave de API ou PII. Prefira-o ao logar erros.
:::

## Padrões de `rescue` por tipo

Capture do mais específico para o mais genérico:

```ruby
begin
  client.service_invoices.create(company_id: company_id, data: payload)
rescue Nfe::AuthenticationError
  # 401 — revise a chave de API.
  raise
rescue Nfe::AuthorizationError
  # 403 — a chave não tem permissão para este recurso.
  raise
rescue Nfe::InvalidRequestError => e
  # 400/422 — corrija o payload; e.message traz o detalhe do servidor.
  warn "Requisição inválida: #{e.message}"
rescue Nfe::RateLimitError => e
  # 429 — respeite o retry_after antes de tentar de novo.
  sleep(e.retry_after || 5)
  retry
rescue Nfe::ServerError
  # 5xx — falha do lado do servidor; reportar/retentar com backoff.
  raise
rescue Nfe::TimeoutError
  # Timeout de conexão/leitura.
  raise
rescue Nfe::ApiConnectionError
  # Outras falhas de rede.
  raise
rescue Nfe::Error => e
  # Rede de segurança para qualquer erro do SDK.
  warn e.to_h.inspect
  raise
end
```

## Validação client-side (fail-fast)

Validações client-side (id de empresa vazio, chave de acesso com tamanho
errado, CNPJ/CPF/CEP/UF inválidos) levantam `Nfe::InvalidRequestError` com uma
mensagem em pt-BR **antes** de qualquer requisição HTTP:

```ruby
begin
  client.service_invoices.retrieve(company_id: "", invoice_id: "abc")
rescue Nfe::InvalidRequestError => e
  # Levantado de forma síncrona, sem rede. e.status_code é nil aqui.
  warn e.message   # mensagem em português identificando o argumento inválido
end
```

:::note Sem `status_code` na validação local
Por não vir de uma resposta HTTP, um `InvalidRequestError` client-side tem
`status_code` igual a `nil` — diferente do mesmo erro vindo de um 400/422.
:::

## `RateLimitError#retry_after`

No HTTP 429, o SDK lê o header `Retry-After` (quando presente) e o expõe como um
inteiro de segundos em `#retry_after`. Pode ser `nil` se o servidor não anunciar.

```ruby
begin
  client.addresses.retrieve(postal_code: "01310100")
rescue Nfe::RateLimitError => e
  wait = e.retry_after || 5
  sleep wait
  retry
end
```

## Erros de rede

Quando nenhuma troca HTTP se completa, o SDK levanta um erro de rede em vez de
devolver uma resposta:

- `Nfe::ApiConnectionError` — DNS, conexão recusada, TLS, reset de conexão.
- `Nfe::TimeoutError` — timeout de conexão ou de leitura; subclasse de
  `ApiConnectionError`. A exceção original fica preservada em `cause`.

```ruby
begin
  client.companies.list
rescue Nfe::TimeoutError => e
  warn "Timeout: #{e.message}; causa original: #{e.cause&.class}"
rescue Nfe::ApiConnectionError => e
  warn "Falha de conexão: #{e.message}"
end
```

## Próximos passos

- [Emissão assíncrona e polling](./async-and-polling.md) — trate falhas no loop.
- [Configuração](./configuration.md) — `timeout`, `max_retries` e TLS.
- [Primeiros passos](./getting-started.md) — visão geral do SDK.

---

## Primeiros passos com o SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/primeiros-passos/index.md

# Primeiros passos

Este guia cobre a instalação, a criação do cliente e a emissão da sua primeira
nota fiscal de serviço (NFS-e), incluindo o acompanhamento do processamento.

## 1. Instale o gem

```ruby
# Gemfile
gem "nfe-io", "~> 1.0"
```

```sh
bundle install
# ou, sem editar o Gemfile:
bundle add nfe-io
```

:::note Requisitos
Ruby **3.2** ou superior. O SDK não tem dependências de runtime — apenas a
biblioteca padrão do Ruby.
:::

## 2. Crie um cliente

```ruby
require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))
```

A chave também pode vir da variável de ambiente `NFE_API_KEY` — o argumento
explícito sempre vence. Recursos de **dados** (CEP, CNPJ, CPF, consultas) usam
uma segunda chave, `data_api_key:`, com fallback para `api_key`. Todas as opções
estão em [Configuração](./configuration.md).

## 3. Emita uma NFS-e

```ruby
result = client.service_invoices.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    cityServiceCode: "2690",
    description: "Manutenção e suporte técnico",
    servicesAmount: 100.0,
    borrower: { federalTaxNumber: "191", name: "Banco do Brasil SA" }
  }
)
```

:::tip Chaves em camelCase
O corpo (`data:`) usa as chaves em camelCase, exatamente como a API espera.
:::

## 4. Trate o retorno discriminado

A emissão é assíncrona. `create` devolve **um de dois tipos**, que você pode
distinguir com pattern matching ou com os predicados `pending?`/`issued?`:

```ruby
case result
in Nfe::Resources::ServiceInvoicePending => pending
  pending.invoice_id           # id para reconsultar enquanto processa
in Nfe::Resources::ServiceInvoiceIssued => issued
  issued.resource              # NFS-e já materializada (HTTP 201)
end
```

## 5. Acompanhe até um estado terminal (polling)

Não existe `create_and_wait` na `v1.0` — faça polling com `retrieve` até um
estado terminal, usando `Nfe::FlowStatus.terminal?`:

```ruby
company_id = "55df4dc6b6cd9007e4f13ee8"
invoice_id = result.pending? ? result.invoice_id : result.resource.id

loop do
  invoice = client.service_invoices.retrieve(
    company_id: company_id,
    invoice_id: invoice_id
  )
  break if Nfe::FlowStatus.terminal?(invoice.flow_status)

  sleep 2
end
```

:::warning Produção vs. teste
A separação **produção vs. teste (homologação)** é definida na configuração da
sua conta em [app.nfe.io](https://app.nfe.io) — **não** pela chave de API nem
pelo SDK. O argumento `environment:` do cliente está reservado para uso futuro.
:::

## Próximos passos

- [Configuração](./configuration.md) — todas as opções do cliente.
- [Emissão assíncrona e polling](./async-and-polling.md) — o contrato 202 em detalhe.
- [Tratamento de erros](./errors.md) — `rescue` por tipo.
- [Webhooks](./webhooks.md) — receba a conclusão por push em vez de polling.

---

## Biblioteca NFE.io em Ruby para Emissão de Notas Fiscais (NFS-e, NF-e, NFC-e, CT-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/index.md

# Biblioteca Ruby NFE.io

SDK oficial da [NFE.io](https://nfe.io) para Ruby: emissão e gestão de documentos
fiscais eletrônicos brasileiros (NFS-e, NF-e, NFC-e, CT-e) com ergonomia estilo
Stripe e **zero dependências de runtime**.

- **Cliente único** `Nfe::Client` com acessores `snake_case` por recurso.
- **Tipado** — assinaturas RBS empacotadas no gem; type-check com Steep.
- **Modelos imutáveis** (`Data.define`) gerados das specs OpenAPI oficiais.

## Requisitos

- Ruby **3.2** ou superior.
- **Zero dependências de runtime** — apenas a biblioteca padrão do Ruby.

## Instalação

```ruby
# Gemfile
gem "nfe-io", "~> 1.0"
```

```sh
bundle install   # ou: gem install nfe-io
```

## Primeiros passos

```ruby
require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))

result = client.service_invoices.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    cityServiceCode: "2690",
    description: "Manutenção e suporte técnico",
    servicesAmount: 100.0,
    borrower: { federalTaxNumber: "191", name: "Banco do Brasil SA" }
  }
)
```

O fluxo completo (retorno discriminado + polling) está em
[Primeiros passos](./getting-started.md).

## Guias

| Guia | Conteúdo |
|---|---|
| [Primeiros passos](./getting-started.md) | Instalação, cliente, primeira emissão e polling. |
| [Configuração](./configuration.md) | Todas as opções, modelo de duas chaves, fallback de ENV, TLS/proxy. |
| [Emissão assíncrona e polling](./async-and-polling.md) | Contrato 202 `Pending`/`Issued` e o laço de polling com `FlowStatus`. |
| [Tratamento de erros](./errors.md) | Hierarquia `Nfe::Error` e padrões de `rescue`. |
| [Webhooks](./webhooks.md) | Verificação HMAC-SHA1 e idempotência/replay. |
| [Paginação](./pagination.md) | Estilos page e cursor; `ListResponse` enumerável. |
| [Downloads](./downloads.md) | Bytes binários vs. `NfeFileResource`. |
| [Roteamento multi-host](./multi-host-routing.md) | Os hosts por família de recurso. |
| [Emissão RTC](./rtc-emission.md) | IBS/CBS/IS; leiaute `ibsCbs`/`IBSCBS`. |
| [Cookbook por recurso](./recursos/) | Um exemplo por recurso (os 17 canônicos + RTC). |

## Referência da API

A referência completa de classes e métodos é gerada com **YARD** a partir do
código-fonte (e dos comentários YARD):

```sh
bundle exec rake doc   # gera docs/api/
```

A versão publicada fica em [`/api/ruby/`](https://nfe.io/api/ruby/) (HTML estático).

## Migração

Vindo da série `0.x`? Veja o [guia de migração](../MIGRATION.md) — a `v1.0` é uma
reescrita greenfield, sem camada de compatibilidade.

---

## Roteamento multi-host no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/roteamento-multi-host/index.md

# Roteamento multi-host

A plataforma NFE.io expõe várias APIs em hosts diferentes. O SDK roteia cada
recurso **automaticamente** para o host certo — nenhum recurso hard-codeia uma
URL. Cada recurso declara uma **família** (`api_family`) e obtém seu host a
partir da `Nfe::Configuration`.

## Famílias, hosts e recursos

| Família | Host | Recursos |
| --- | --- | --- |
| `main` | `api.nfe.io` (`/v1`) | `service_invoices`, `service_invoices_rtc`, entidades (companies, legal/natural people), `webhooks` |
| `cte` | `api.nfse.io` (`/v2`) | `product_invoices`, `product_invoices_rtc`, `consumer_invoices`, `transportation_invoices`, `inbound_product_invoices`, `tax_calculation`, `tax_codes`, `state_taxes` |
| `addresses` | `address.api.nfe.io/v2` | consulta de endereços (CEP) |
| `legal-entity` | `legalentity.api.nfe.io` | consulta de pessoa jurídica (CNPJ) |
| `natural-person` | `naturalperson.api.nfe.io` | consulta de pessoa física (CPF) |
| `nfe-query` | `nfe.api.nfe.io` | `product_invoice_query`, `consumer_invoice_query` |

:::note O segmento de versão
Para a família `main`, o `/v1` é fornecido pelo `api_version` de cada recurso,
não pelo host. O host de `addresses` já embute o `/v2`.
:::

## Modelo de duas chaves

O SDK usa duas chaves de API. As **famílias de dados** preferem `data_api_key`
(com fallback para `api_key`); todas as outras famílias usam `api_key`.

As famílias de dados são:

- `addresses`
- `legal-entity`
- `natural-person`
- `nfe-query`

```ruby
client = Nfe::Client.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  data_api_key: ENV.fetch("NFE_DATA_API_KEY")
)
```

Qualquer das chaves pode vir das variáveis de ambiente `NFE_API_KEY` /
`NFE_DATA_API_KEY` (o argumento explícito sempre vence).

:::warning `:cte` NÃO é família de dados
A família `:cte` (`api.nfse.io` — emissão de NF-e/NFC-e/CT-e + regras de imposto,
tax codes e state taxes) usa a **`api_key` principal**, e não a `data_api_key`.
Neste SDK a emissão é uma capacidade central, não uma consulta de dados. Isso é
uma **divergência deliberada do SDK Node** (que roteia `api.nfse.io` pela cadeia
de fallback da chave de dados).
:::

## Escape hatch: `base_url_overrides`

Para apontar uma família para outro host (ambiente de testes próprio, proxy,
mock), use `base_url_overrides:` na configuração. Um override por família vence
o host padrão:

```ruby
client = Nfe::Client.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  base_url_overrides: {
    cte: "https://mock.local/nfse"
  }
)
```

Uma família desconhecida cai no host `main` como padrão seguro.

## Próximos passos

- [Downloads](./downloads.md) — por que `product_invoices` (host `cte`) devolve uma URI em vez de bytes.
- [Emissão RTC](./rtc-emission.md) — os recursos RTC e seus hosts.
- [Paginação](./pagination.md) — formas de paginação por família.

---

## Paginação de listas no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/paginacao/index.md

# Paginação

Os métodos `list` retornam um `Nfe::ListResponse`. Ele inclui `Enumerable`, então
você itera diretamente sobre os itens hidratados — sem precisar acessar `#data` —
e lê os metadados de paginação em `#page`.

## `Nfe::ListResponse`

Tem dois membros:

- `#data` — o `Array` de DTOs hidratados.
- `#page` — um `Nfe::ListPage` com os metadados de paginação.

Como inclui `Enumerable` (delegando `each` a `#data`), você usa `map`, `select`,
`each_with_index` e os demais métodos diretamente:

```ruby
list = client.service_invoices.list(company_id: "55df4dc6b6cd9007e4f13ee8")

list.each do |invoice|
  puts invoice.id
end

ids = list.map(&:id)   # Enumerable direto, sem list.data
total = list.count
```

## `Nfe::ListPage`

Os endpoints da NFE.io paginam em **uma de duas formas**, e cada recurso
preenche apenas a metade relevante:

- **Por página** — `#page_index` / `#page_count` (campos de cursor ficam `nil`).
- **Por cursor** — `#starting_after` / `#ending_before` (`#page_index` fica `nil`).

`#total` é opcional e pode aparecer em qualquer uma das formas.

```ruby
page = list.page

if page.page_index
  puts "Página #{page.page_index} de #{page.page_count}"
else
  puts "Próximo cursor: #{page.starting_after}"
end

page.total # pode ser nil
```

## Qual recurso usa qual forma

| Recurso | Forma de paginação |
| --- | --- |
| `service_invoices.list` | por página (`page_index`/`page_count`) |
| `product_invoices.list` | por cursor (`starting_after`/`ending_before`) |
| `product_invoices_rtc.list` | por cursor |
| `consumer_invoices.list` | por cursor |
| `state_taxes.list` | por cursor |

### Por página: `service_invoices`

```ruby
list = client.service_invoices.list(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  page_index: 1,
  page_count: 50
)

list.each { |inv| puts inv.id }
```

### Por cursor: `product_invoices`

:::warning `environment:` é obrigatório
`product_invoices.list` e `product_invoices_rtc.list` **exigem** o argumento
`environment:` — uma String `"Production"` ou `"Test"`. Omiti-lo levanta
`Nfe::InvalidRequestError`.
:::

```ruby
list = client.product_invoices.list(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  environment: "Production",
  limit: 50
)

# Avance usando o cursor da página anterior:
next_page = client.product_invoices.list(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  environment: "Production",
  starting_after: list.page.starting_after,
  limit: 50
)
```

## Próximos passos

- [Downloads](./downloads.md) — baixe os arquivos das notas listadas.
- [Webhooks](./webhooks.md) — receba eventos por push em vez de listar.
- [Roteamento multi-host](./multi-host-routing.md) — entenda em qual host cada recurso vive.

---

## Consulta de endereços (addresses) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/enderecos/index.md

# Consulta de endereços (`addresses`)

O recurso `addresses` consulta endereços por CEP, por termo livre ou por filtro
OData. Faz parte da família de **dados** `addresses`, servida por
`address.api.nfe.io/v2`. Como host já embute a versão, os caminhos são usados como
estão.

:::note Família de dados — configure `data_api_key`
`addresses` é um serviço de **dados**: usa a `data_api_key` quando presente, com
**fallback** para a `api_key`. Configure `data_api_key:` (ou `NFE_DATA_API_KEY`)
para separar a chave de consulta da chave de emissão. Veja
[Configuração](../configuration.md).
:::

## Métodos públicos

```ruby
addresses.lookup_by_postal_code(postal_code)   # => Nfe::AddressLookupResponse
addresses.lookup_by_term(term)                 # => Nfe::AddressLookupResponse
addresses.search(filter: nil)                  # => Nfe::AddressLookupResponse
```

## Exemplos

### Consultar por CEP

```ruby
require "nfe"

client = Nfe::Client.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  data_api_key: ENV.fetch("NFE_DATA_API_KEY")
)

resposta = client.addresses.lookup_by_postal_code("01310-100")
resposta.addresses
```

:::warning CEP é validado antes do HTTP
O CEP precisa ter **8 dígitos** (separadores são removidos). Um CEP inválido
levanta `Nfe::InvalidRequestError` **antes** de qualquer requisição. Veja
[Tratamento de erros](../errors.md).
:::

### Consultar por termo livre

```ruby
client.addresses.lookup_by_term("Avenida Paulista, São Paulo")
```

Um `term` vazio ou só com espaços levanta `Nfe::InvalidRequestError`.

### Buscar com filtro OData

```ruby
client.addresses.search(filter: "city eq 'São Paulo'")

# Sem filtro: lista o que a API retornar por padrão.
client.addresses.search
```

:::note `filter` é opaco
O argumento `filter:` é repassado verbatim como `$filter` na query — o SDK não
interpreta nem valida a expressão OData.
:::

## Veja também

- [Configuração](../configuration.md) — modelo de duas chaves e `data_api_key`.
- [Consulta de CNPJ](./legal-entity-lookup.md) e [Consulta de CPF](./natural-person-lookup.md) — outras famílias de dados.

---

## Empresas (companies) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/empresas/index.md

# Empresas (`companies`)

O recurso `companies` gerencia as empresas emissoras da sua conta — CRUD completo
mais o ciclo de vida do certificado digital (upload, substituição, validação e
status). Faz parte da família `main`, servida por `api.nfe.io` (`/v1`), e usa a
`api_key`.

:::note Exclusão é `remove`, não `delete`
Para excluir uma empresa, chame `companies.remove(company_id)`. O nome evita
conflito de semântica com `delete` e mantém paridade com os SDKs Node e PHP.
:::

## Métodos públicos

```ruby
companies.create(data)                                  # => Nfe::Company
companies.list(page_index: 0, page_count: 100)          # => Nfe::ListResponse
companies.list_all                                      # => Array<Nfe::Company>
companies.list_each                                     # => Enumerator<Nfe::Company>
companies.retrieve(company_id)                          # => Nfe::Company
companies.update(company_id, data)                      # => Nfe::Company
companies.remove(company_id)                            # => { deleted: true, id: ... }
companies.find_by_tax_number(tax_number)                # => Nfe::Company | nil
companies.find_by_name(name)                            # => Array<Nfe::Company>

# Certificado digital
companies.validate_certificate(file:, password:)        # => Nfe::CertificateInfo (sem HTTP)
companies.upload_certificate(company_id, file:, password:, filename: nil)
companies.replace_certificate(company_id, file:, password:, filename: nil)
companies.get_certificate_status(company_id)            # => Nfe::CertificateStatus
companies.check_certificate_expiration(company_id, threshold_days: 30)
companies.get_companies_with_certificates               # => Array<Nfe::Company>
companies.get_companies_with_expiring_certificates(threshold_days: 30)
```

## Exemplos

### Criar e recuperar uma empresa

```ruby
require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))

company = client.companies.create(
  name: "Acme Serviços LTDA",
  federalTaxNumber: "12345678000199",
  email: "fiscal@acme.com.br"
)

client.companies.retrieve(company.id)
```

:::tip Validação local de `federalTaxNumber`
`create` e `update` validam o formato de `federalTaxNumber` (11 dígitos para CPF
ou 14 para CNPJ) e o formato do `email` quando presente, levantando
`Nfe::InvalidRequestError` **antes** de qualquer requisição HTTP. Não há
verificação de dígito verificador.
:::

### Paginar e localizar empresas

```ruby
# Uma página por vez (page_index é 0-based no SDK):
page = client.companies.list(page_index: 0, page_count: 50)
page.data.each { |c| puts c.name }

# Todas as empresas (auto-paginação) ou stream preguiçoso:
client.companies.list_all
client.companies.list_each.each { |c| puts c.id }

# Buscas auxiliares (filtragem no cliente):
client.companies.find_by_tax_number("12.345.678/0001-99")
client.companies.find_by_name("acme")
```

:::warning Helpers de busca não são otimizados
`find_by_tax_number`, `find_by_name`, `list_all`, `get_companies_with_certificates`
e `get_companies_with_expiring_certificates` percorrem **todas** as páginas e
filtram no cliente. Evite em contas com muitas empresas.
:::

### Validar e enviar o certificado digital

```ruby
# Validação puramente local (não faz HTTP): confere senha e DER.
info = client.companies.validate_certificate(
  file: "/caminho/certificado.pfx",
  password: ENV.fetch("CERT_PASSWORD")
)

# Upload: pré-valida localmente (fail-fast) e então envia multipart/form-data.
client.companies.upload_certificate(
  company.id,
  file: "/caminho/certificado.pfx",
  password: ENV.fetch("CERT_PASSWORD"),
  filename: "certificado.pfx"
)

# Status e alerta de expiração:
status = client.companies.get_certificate_status(company.id)
status.days_until_expiration

client.companies.check_certificate_expiration(company.id, threshold_days: 30)
```

:::note Apenas `.pfx` e `.p12`
Quando você informa `filename:`, o SDK rejeita extensões diferentes de `.pfx` e
`.p12` com `Nfe::InvalidRequestError`. O parâmetro `file:` aceita um caminho de
arquivo ou os bytes brutos do certificado.
:::

## Veja também

- [Pessoas jurídicas](./legal-people.md) e [Pessoas físicas](./natural-people.md) — tomadores vinculados à empresa.
- [Webhooks](./webhooks.md) — eventos por empresa.
- [Tratamento de erros](../errors.md).

---

## Consulta de NFC-e (consumer_invoice_query) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/consulta-nfce/index.md

# Consulta de NFC-e (`consumer_invoice_query`)

O recurso `consumer_invoice_query` consulta cupons fiscais NFC-e (CFe-SAT) já
emitidos, pela chave de acesso. Faz parte da família de **dados** `nfe_query`,
servida por `nfe.api.nfe.io` (`/v1`, caminho `/coupon/`).

:::warning Não confunda com a emissão de NFC-e
Este recurso é **distinto** de `consumer_invoices` (emissão de NFC-e): host e
versão de API diferentes. Aqui apenas recuperamos e baixamos um cupom **já
emitido**.
:::

:::note Família de dados — configure `data_api_key`
Esta é uma família de **dados**: usa a `data_api_key` quando presente, com
**fallback** para a `api_key`. Configure `data_api_key:` (ou `NFE_DATA_API_KEY`).
Veja [Configuração](../configuration.md).
:::

## Métodos públicos

```ruby
consumer_invoice_query.retrieve(access_key)     # => Nfe::TaxCoupon
consumer_invoice_query.download_xml(access_key) # => String (bytes ASCII-8BIT)
```

## Exemplos

### Recuperar um cupom e baixar o XML

```ruby
require "nfe"

client = Nfe::Client.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  data_api_key: ENV.fetch("NFE_DATA_API_KEY")
)

chave = "35200114200166000187650010000000071234567890"

cupom = client.consumer_invoice_query.retrieve(chave)

xml = client.consumer_invoice_query.download_xml(chave)
File.binwrite("nfce.xml", xml)
```

:::warning Chave de acesso é validada antes do HTTP
A chave de acesso precisa ter **44 dígitos**. Uma chave inválida levanta
`Nfe::InvalidRequestError` **antes** de qualquer requisição.
:::

:::tip `download_xml` retorna bytes binários
O retorno são os **bytes** do XML (`ASCII-8BIT`); grave com `File.binwrite`. Veja
o guia de [Downloads](../downloads.md).
:::

## Veja também

- [Consulta de NF-e (product_invoice_query)](./product-invoice-query.md) — o equivalente para NF-e.
- [Downloads](../downloads.md) — manipulação de XML binário.
- [Configuração](../configuration.md) — modelo de duas chaves.

---

## Notas fiscais de consumidor (NFC-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/notas-fiscais-de-consumidor/index.md

# Notas fiscais de consumidor (NFC-e)

`client.consumer_invoices` cobre o ciclo de vida da NFC-e (Nota Fiscal de
Consumidor Eletrônica, modelo 65) no host `api.nfse.io`, sob `/v2`. É útil para
integrações de PDV e e-commerce.

:::note Adição parity-plus
Este recurso vai além do SDK Node.js, que não expõe emissão de NFC-e. A API
NFE.io suporta o ciclo completo da NFC-e desde a v2.
:::

A emissão segue o **contrato 202 discriminado**: `create` /
`create_with_state_tax` devolvem `ConsumerInvoicePending` ou
`ConsumerInvoiceIssued`. Não há `create_and_wait` nem `create_batch`.

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create(company_id:, data:, idempotency_key: nil, request_options: nil)` | Emite a NFC-e. | `ConsumerInvoicePending` ou `ConsumerInvoiceIssued` |
| `create_with_state_tax(company_id:, state_tax_id:, data:, idempotency_key: nil, request_options: nil)` | Emite vinculada a uma inscrição estadual. | `ConsumerInvoicePending` ou `ConsumerInvoiceIssued` |
| `list(company_id:, environment:, **options)` | Lista por cursor. `environment` (`"Production"`/`"Test"`) é **obrigatório**. | `Nfe::ListResponse` |
| `retrieve(company_id:, invoice_id:)` | Consulta por id. | `Nfe::ConsumerInvoice` |
| `cancel(company_id:, invoice_id:)` | Cancela (síncrono). | `Nfe::ConsumerInvoice` |
| `list_items(company_id:, invoice_id:)` | Lista os itens. | `Array` |
| `list_events(company_id:, invoice_id:)` | Lista os eventos. | `Array` |
| `download_pdf(company_id:, invoice_id:)` | DANFE NFC-e PDF. | `String` binária |
| `download_xml(company_id:, invoice_id:)` | XML autorizado. | `String` binária |
| `download_rejection_xml(company_id:, invoice_id:)` | XML de rejeição. | `String` binária |
| `disable_range(company_id:, data:)` | Inutilização coletiva de uma faixa. | `Hash` |

:::warning Métodos ausentes por lei fiscal
A NFC-e não tem carta de correção, EPEC, nem inutilização individual. Logo,
`send_correction_letter`, `download_epec_xml` e `disable` **não existem** neste
recurso — chamá-los levanta `NoMethodError`. Para inutilizar, use apenas
`disable_range` (coletiva).
:::

## Emitir uma NFC-e

```ruby
result = client.consumer_invoices.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    items: [
      { code: "001", description: "Café 250g", quantity: 2, unitAmount: 19.9 }
    ],
    payment: [{ method: "Cash", amount: 39.8 }]
  }
)

case result
in Nfe::Resources::ConsumerInvoicePending => pending
  pending.invoice_id
in Nfe::Resources::ConsumerInvoiceIssued => issued
  issued.resource   # Nfe::ConsumerInvoice
end
```

:::tip Idempotência
`create` e `create_with_state_tax` aceitam `idempotency_key:` (header
`Idempotency-Key`) e `request_options:`. Reutilize a mesma chave em retentativas
para evitar emissão duplicada.
:::

## Acompanhar até um estado terminal

```ruby
loop do
  nfce = client.consumer_invoices.retrieve(
    company_id: company_id,
    invoice_id: invoice_id
  )
  break if Nfe::FlowStatus.terminal?(nfce.flow_status)

  sleep 2
end
```

## Baixar PDF e XML (bytes binários)

Ao contrário das notas de produto, aqui os downloads retornam uma `String`
binária (`ASCII-8BIT`) — grave com `File.binwrite`.

```ruby
pdf = client.consumer_invoices.download_pdf(
  company_id: company_id,
  invoice_id: invoice_id
)
File.binwrite("danfe-nfce.pdf", pdf)
```

## Inutilização coletiva

```ruby
client.consumer_invoices.disable_range(
  company_id: company_id,
  data: {
    environment: "Production", serie: 1, state: "SP",
    beginNumber: 50, lastNumber: 60, reason: "Falha de comunicação com a SEFAZ"
  }
)
```

## Próximos passos

- [Notas de produto (NF-e)](./product-invoices.md) — modelo 55 com downloads por URI.
- [Emissão RTC](./rtc.md) — layout da Reforma Tributária para produto.

---

## NF-e de entrada e manifestação do destinatário

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/notas-de-entrada/index.md

# NF-e de entrada e manifestação do destinatário

`client.inbound_product_invoices` gerencia NF-e **emitidas por fornecedores**
(entrada), no host `api.nfse.io`, sob `/v2`. Ele habilita a busca automática via
SEFAZ Distribuição DFe, lê documentos e eventos por chave de acesso, envia a
Manifestação do Destinatário e reprocessa webhooks.

:::note Recurso de entrada, não de emissão
É um recurso de consulta/configuração; não há contrato 202 `Pending` / `Issued`.
Existem duas superfícies de detalhe: o formato webhook-v1
(`.../inbound/{chave}`) e o formato webhook-v2 recomendado
(`.../inbound/productinvoice/{chave}`, que adiciona o array de NF-e de produto).
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `enable_auto_fetch(company_id:, **opts)` | Habilita a busca automática de NF-e. | `Nfe::InboundSettings` |
| `disable_auto_fetch(company_id:)` | Desabilita a busca automática. | `Nfe::InboundSettings` |
| `get_settings(company_id:)` | Lê as configurações atuais. | `Nfe::InboundSettings` |
| `get_details(company_id:, access_key:)` | Detalhes (webhook-v1). | `Nfe::InboundInvoiceMetadata` |
| `get_product_invoice_details(company_id:, access_key:)` | Detalhes da NF-e (webhook-v2). | `Nfe::InboundInvoiceMetadata` |
| `get_event_details(company_id:, access_key:, event_key:)` | Detalhes de um evento (webhook-v1). | `Nfe::InboundInvoiceMetadata` |
| `get_product_invoice_event_details(company_id:, access_key:, event_key:)` | Detalhes de um evento (webhook-v2). | `Nfe::InboundInvoiceMetadata` |
| `get_xml(company_id:, access_key:)` | XML do documento. | `String` binária |
| `get_event_xml(company_id:, access_key:, event_key:)` | XML de um evento. | `String` binária |
| `get_pdf(company_id:, access_key:)` | DANFE PDF da NF-e. | `String` binária |
| `get_json(company_id:, access_key:)` | Representação JSON estruturada. | `Nfe::InboundInvoiceMetadata` |
| `manifest(company_id:, access_key:, tp_event: 210210)` | Envia a manifestação do destinatário. | `String` |
| `reprocess_webhook(company_id:, access_key_or_nsu:)` | Reprocessa o webhook por chave ou NSU. | `Nfe::InboundInvoiceMetadata` |

As opções de `enable_auto_fetch` são `start_from_nsu`, `start_from_date`,
`environment_sefaz`, `automatic_manifesting` e `webhook_version`.

:::tip Constantes de tipo de evento da manifestação
O módulo expõe constantes para `tp_event`:

```ruby
Nfe::Resources::InboundProductInvoices::MANIFEST_AWARENESS      # 210210 (padrão) — Ciência da Operação
Nfe::Resources::InboundProductInvoices::MANIFEST_CONFIRMATION   # 210220 — Confirmação da Operação
Nfe::Resources::InboundProductInvoices::MANIFEST_NOT_PERFORMED  # 210240 — Operação não Realizada
```
:::

## Habilitar a busca automática

```ruby
settings = client.inbound_product_invoices.enable_auto_fetch(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  start_from_date: "2026-01-01",
  webhook_version: "2"
)
```

## Ler uma NF-e de fornecedor

```ruby
access_key = "35240611111111000199550010000012341000012345"

detalhes = client.inbound_product_invoices.get_product_invoice_details(
  company_id: company_id,
  access_key: access_key
)

pdf = client.inbound_product_invoices.get_pdf(
  company_id: company_id,
  access_key: access_key
)
File.binwrite("nfe-entrada.pdf", pdf)   # bytes binários (ASCII-8BIT)
```

## Manifestar o destinatário

`tp_event` é numérico e default `210210` (Ciência da Operação). Use as
constantes para confirmar ou recusar a operação.

```ruby
# Ciência da operação (padrão):
client.inbound_product_invoices.manifest(
  company_id: company_id,
  access_key: access_key
)

# Confirmação da operação:
client.inbound_product_invoices.manifest(
  company_id: company_id,
  access_key: access_key,
  tp_event: Nfe::Resources::InboundProductInvoices::MANIFEST_CONFIRMATION
)
```

## Reprocessar webhook (por chave ou NSU)

`reprocess_webhook` aceita tanto uma chave de acesso de 44 dígitos quanto um NSU
numérico — um NSU não é rejeitado como chave inválida.

```ruby
client.inbound_product_invoices.reprocess_webhook(
  company_id: company_id,
  access_key_or_nsu: "123456"
)
```

## Próximos passos

- [CT-e de entrada](./transportation-invoices.md) — busca automática de CT-e.
- [Webhooks](../webhooks.md) — receba a chegada de novos documentos por push.

---

## Consulta de CNPJ (legal_entity_lookup) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/consulta-cnpj/index.md

# Consulta de CNPJ (`legal_entity_lookup`)

O recurso `legal_entity_lookup` consulta dados cadastrais de pessoa jurídica por
CNPJ: informações básicas e inscrição estadual (inclusive a versão adequada para
emissão). Faz parte da família de **dados** `legal_entity`, servida por
`legalentity.api.nfe.io`. O segmento de versão (`/v2`) já vem no caminho de cada
requisição.

:::note Família de dados — configure `data_api_key`
Esta é uma família de **dados**: usa a `data_api_key` quando presente, com
**fallback** para a `api_key`. Configure `data_api_key:` (ou `NFE_DATA_API_KEY`).
Veja [Configuração](../configuration.md).
:::

## Métodos públicos

```ruby
legal_entity_lookup.get_basic_info(federal_tax_number, update_address: nil, update_city_code: nil)
# => Nfe::LegalEntityBasicInfoResponse

legal_entity_lookup.get_state_tax_info(state, federal_tax_number)
# => Nfe::LegalEntityStateTaxResponse

legal_entity_lookup.get_state_tax_for_invoice(state, federal_tax_number)
# => Nfe::LegalEntityStateTaxForInvoiceResponse

legal_entity_lookup.get_suggested_state_tax_for_invoice(state, federal_tax_number)
# => Nfe::LegalEntityStateTaxForInvoiceResponse
```

## Exemplos

### Dados básicos de um CNPJ

```ruby
require "nfe"

client = Nfe::Client.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  data_api_key: ENV.fetch("NFE_DATA_API_KEY")
)

info = client.legal_entity_lookup.get_basic_info("00.000.000/0001-91")
info

# Opcionalmente força atualização de endereço/código de município:
client.legal_entity_lookup.get_basic_info(
  "00000000000191",
  update_address: true,
  update_city_code: true
)
```

:::warning CNPJ é validado antes do HTTP
O CNPJ precisa ter **14 dígitos** (separadores removidos). Um CNPJ inválido
levanta `Nfe::InvalidRequestError` **antes** de qualquer requisição.
:::

### Inscrição estadual para emissão

```ruby
# Inscrição estadual em um estado (UF):
client.legal_entity_lookup.get_state_tax_info("SP", "00000000000191")

# Versão adequada para uso em uma nota:
client.legal_entity_lookup.get_state_tax_for_invoice("SP", "00000000000191")

# Sugestão da inscrição estadual para a nota:
client.legal_entity_lookup.get_suggested_state_tax_for_invoice("SP", "00000000000191")
```

:::note UF e CNPJ validados localmente
`state` é validado como UF (case-insensitive) e o CNPJ como 14 dígitos. Qualquer
um inválido levanta `Nfe::InvalidRequestError` antes do HTTP.
:::

## Veja também

- [Consulta de CPF](./natural-person-lookup.md) — o equivalente para PF.
- [Inscrições estaduais (state_taxes)](./state-taxes.md) — cadastro de IE da sua empresa.
- [Configuração](../configuration.md) — modelo de duas chaves.

---

## Pessoas jurídicas (legal_people) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/pessoas-juridicas/index.md

# Pessoas jurídicas (`legal_people`)

O recurso `legal_people` gerencia pessoas jurídicas (tomadores PJ) **escopadas por
empresa**, sob `/companies/{id}/legalpeople`. Faz parte da família `main`, servida
por `api.nfe.io` (`/v1`), e usa a `api_key`.

## Métodos públicos

```ruby
legal_people.list(company_id)                                  # => Nfe::ListResponse
legal_people.create(company_id, data)                          # => Nfe::LegalPerson
legal_people.retrieve(company_id, legal_person_id)             # => Nfe::LegalPerson
legal_people.update(company_id, legal_person_id, data)         # => Nfe::LegalPerson
legal_people.delete(company_id, legal_person_id)               # => nil
legal_people.create_batch(company_id, list)                    # => Array<Nfe::LegalPerson>
legal_people.find_by_tax_number(company_id, federal_tax_number) # => Nfe::LegalPerson | nil
```

:::note `list` não pagina
`list(company_id)` devolve todas as pessoas jurídicas da empresa em um único
`Nfe::ListResponse` (paridade com o SDK Node), sem cursores nem páginas.
:::

## Exemplos

### Criar e recuperar

```ruby
require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))
company_id = "55df4dc6b6cd9007e4f13ee8"

person = client.legal_people.create(
  company_id,
  name: "Banco do Brasil SA",
  federalTaxNumber: "00000000000191"
)

client.legal_people.retrieve(company_id, person.id)
```

### Criar várias de uma vez

```ruby
people = client.legal_people.create_batch(company_id, [
  { name: "Fornecedor A LTDA", federalTaxNumber: "12345678000199" },
  { name: "Fornecedor B LTDA", federalTaxNumber: "98765432000188" }
])
```

:::tip `create_batch` é sequencial
Diferente do SDK Node (que usa `Promise.all`), o `create_batch` executa as
criações **em sequência** e devolve os resultados na mesma ordem da lista.
:::

### Localizar por CNPJ

```ruby
person = client.legal_people.find_by_tax_number(company_id, "12.345.678/0001-99")
```

:::note Filtragem no cliente
`find_by_tax_number` chama `list` e filtra localmente, normalizando os dígitos do
CNPJ antes de comparar.
:::

## Veja também

- [Pessoas físicas](./natural-people.md) — o equivalente para PF.
- [Empresas](./companies.md) — o escopo (`company_id`) destes recursos.
- [Consulta de CNPJ](./legal-entity-lookup.md) — dados cadastrais de uma PJ na Receita.

---

## Pessoas físicas (natural_people) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/pessoas-fisicas/index.md

# Pessoas físicas (`natural_people`)

O recurso `natural_people` gerencia pessoas físicas (tomadores PF) **escopadas por
empresa**, sob `/companies/{id}/naturalpeople`. Faz parte da família `main`,
servida por `api.nfe.io` (`/v1`), e usa a `api_key`.

## Métodos públicos

```ruby
natural_people.list(company_id)                                  # => Nfe::ListResponse
natural_people.create(company_id, data)                          # => Nfe::NaturalPerson
natural_people.retrieve(company_id, natural_person_id)           # => Nfe::NaturalPerson
natural_people.update(company_id, natural_person_id, data)       # => Nfe::NaturalPerson
natural_people.delete(company_id, natural_person_id)             # => nil
natural_people.create_batch(company_id, list)                    # => Array<Nfe::NaturalPerson>
natural_people.find_by_tax_number(company_id, federal_tax_number) # => Nfe::NaturalPerson | nil
```

:::note `list` não pagina
`list(company_id)` devolve todas as pessoas físicas da empresa em um único
`Nfe::ListResponse` (paridade com o SDK Node), sem cursores nem páginas.
:::

## Exemplos

### Criar e recuperar

```ruby
require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))
company_id = "55df4dc6b6cd9007e4f13ee8"

person = client.natural_people.create(
  company_id,
  name: "Maria da Silva",
  federalTaxNumber: "39053344705"
)

client.natural_people.retrieve(company_id, person.id)
```

### Criar várias e localizar por CPF

```ruby
client.natural_people.create_batch(company_id, [
  { name: "João Souza", federalTaxNumber: "11144477735" },
  { name: "Ana Lima",   federalTaxNumber: "39053344705" }
])

# find_by_tax_number normaliza para 11 dígitos antes de filtrar:
client.natural_people.find_by_tax_number(company_id, "390.533.447-05")
```

:::tip `create_batch` é sequencial
As criações são executadas **em sequência** e devolvidas na ordem da lista
informada — não em paralelo.
:::

## Veja também

- [Pessoas jurídicas](./legal-people.md) — o equivalente para PJ.
- [Empresas](./companies.md) — o escopo (`company_id`) destes recursos.
- [Consulta de CPF](./natural-person-lookup.md) — situação cadastral de uma PF na Receita.

---

## Consulta de CPF (natural_person_lookup) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/consulta-cpf/index.md

# Consulta de CPF (`natural_person_lookup`)

O recurso `natural_person_lookup` consulta a situação cadastral de uma pessoa
física na Receita Federal a partir do CPF e da data de nascimento. Faz parte da
família de **dados** `natural_person`, servida por `naturalperson.api.nfe.io`. O
segmento de versão (`/v1`) já vem no caminho da requisição.

:::note Família de dados — configure `data_api_key`
Esta é uma família de **dados**: usa a `data_api_key` quando presente, com
**fallback** para a `api_key`. Configure `data_api_key:` (ou `NFE_DATA_API_KEY`).
Veja [Configuração](../configuration.md).
:::

## Métodos públicos

```ruby
natural_person_lookup.get_status(federal_tax_number, birth_date)
# => Nfe::NaturalPersonStatusResponse | nil
```

O `birth_date` aceita `String`, `Date`, `Time` ou `DateTime` — o SDK normaliza
para `YYYY-MM-DD` via `Nfe::DateNormalizer` antes da requisição.

## Exemplos

### Consultar a situação cadastral

```ruby
require "nfe"
require "date"

client = Nfe::Client.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  data_api_key: ENV.fetch("NFE_DATA_API_KEY")
)

# Data como String:
client.natural_person_lookup.get_status("390.533.447-05", "1985-03-12")

# Ou como objeto Date/Time/DateTime:
client.natural_person_lookup.get_status("39053344705", Date.new(1985, 3, 12))
```

:::warning CPF e data validados antes do HTTP
O CPF é normalizado para **11 dígitos** e a data de nascimento é normalizada para
`YYYY-MM-DD`. Entradas inválidas levantam `Nfe::InvalidRequestError` **antes** de
qualquer requisição. Veja [Tratamento de erros](../errors.md).
:::

## Veja também

- [Consulta de CNPJ](./legal-entity-lookup.md) — o equivalente para PJ.
- [Pessoas físicas](./natural-people.md) — cadastro de tomadores PF na sua conta.
- [Configuração](../configuration.md) — modelo de duas chaves.

---

## Consulta de NF-e (product_invoice_query) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/consulta-nfe/index.md

# Consulta de NF-e (`product_invoice_query`)

O recurso `product_invoice_query` faz consultas somente-leitura de NF-e (nota
fiscal de produto) pela chave de acesso: detalhes, download de PDF (DANFE) e XML,
e listagem de eventos. Faz parte da família de **dados** `nfe_query`, servida por
`nfe.api.nfe.io`. O segmento de versão (`/v2`) já vem no caminho da requisição.

:::note Família de dados — configure `data_api_key`
Esta é uma família de **dados**: usa a `data_api_key` quando presente, com
**fallback** para a `api_key`. Configure `data_api_key:` (ou `NFE_DATA_API_KEY`).
Veja [Configuração](../configuration.md).
:::

## Métodos públicos

```ruby
product_invoice_query.retrieve(access_key)      # => Nfe::ProductInvoiceDetails | nil
product_invoice_query.download_pdf(access_key)  # => String (bytes ASCII-8BIT)
product_invoice_query.download_xml(access_key)  # => String (bytes ASCII-8BIT)
product_invoice_query.list_events(access_key)   # => Nfe::ProductInvoiceEventsResponse | nil
```

## Exemplos

### Consultar detalhes e eventos

```ruby
require "nfe"

client = Nfe::Client.new(
  api_key: ENV.fetch("NFE_API_KEY"),
  data_api_key: ENV.fetch("NFE_DATA_API_KEY")
)

chave = "35200114200166000187550010000000071234567890"

detalhes = client.product_invoice_query.retrieve(chave)
eventos  = client.product_invoice_query.list_events(chave)
```

:::warning Chave de acesso é validada antes do HTTP
A chave de acesso precisa ter **44 dígitos**. Uma chave inválida levanta
`Nfe::InvalidRequestError` **antes** de qualquer requisição. Veja
[Tratamento de erros](../errors.md).
:::

### Baixar PDF (DANFE) e XML

```ruby
pdf = client.product_invoice_query.download_pdf(chave)
File.binwrite("danfe.pdf", pdf)

xml = client.product_invoice_query.download_xml(chave)
File.binwrite("nfe.xml", xml)
```

:::tip Downloads retornam bytes binários
`download_pdf` e `download_xml` devolvem os **bytes** (`ASCII-8BIT`), não um
objeto hidratado. Grave-os com `File.binwrite`. Veja o guia de
[Downloads](../downloads.md).
:::

## Veja também

- [Consulta de NFC-e (consumer_invoice_query)](./consumer-invoice-query.md) — o equivalente para cupons.
- [Downloads](../downloads.md) — manipulação de PDF/XML binários.
- [Configuração](../configuration.md) — modelo de duas chaves.

---

## Notas fiscais de produto (NF-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/notas-fiscais-de-produto/index.md

# Notas fiscais de produto (NF-e)

`client.product_invoices` cobre o ciclo de vida completo da NF-e (modelo 55) no
host `api.nfse.io`, sob `/v2`: emissão, listagem por cursor, consulta,
cancelamento, carta de correção (CC-e), inutilização e downloads.

A emissão segue o **contrato 202 discriminado** (assíncrona; conclusão via
webhook): `create` / `create_with_state_tax` devolvem `ProductInvoicePending`
ou `ProductInvoiceIssued`. Não há `create_and_wait` nem `create_batch`.

:::warning Downloads retornam URI, não bytes
Diferente das demais notas, os métodos de download desta classe retornam um
`Nfe::NfeFileResource` com o atributo `uri` — **não** os bytes do arquivo. Use a
`uri` para baixar o conteúdo separadamente.
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create(company_id:, data:, idempotency_key: nil, request_options: nil)` | Emite a NF-e. | `ProductInvoicePending` ou `ProductInvoiceIssued` |
| `create_with_state_tax(company_id:, state_tax_id:, data:, idempotency_key: nil, request_options: nil)` | Emite vinculada a uma inscrição estadual. | `ProductInvoicePending` ou `ProductInvoiceIssued` |
| `list(company_id:, environment:, **options)` | Lista por cursor; `environment` obrigatório. | `Nfe::ListResponse` |
| `retrieve(company_id:, invoice_id:)` | Consulta por id. | `Nfe::ProductInvoice` |
| `cancel(company_id:, invoice_id:, reason: nil)` | Cancela (assíncrono); `reason` vai na query. | `Hash` |
| `list_items(company_id:, invoice_id:, limit: nil, starting_after: nil)` | Lista os itens da nota. | `Nfe::ListResponse` |
| `list_events(company_id:, invoice_id:, limit: nil, starting_after: nil)` | Lista os eventos fiscais. | `Nfe::ListResponse` |
| `download_pdf(company_id:, invoice_id:, force: nil)` | DANFE PDF (URI). | `Nfe::NfeFileResource` |
| `download_xml(company_id:, invoice_id:)` | XML autorizado (URI). | `Nfe::NfeFileResource` |
| `download_rejection_xml(company_id:, invoice_id:)` | XML de rejeição (URI). | `Nfe::NfeFileResource` |
| `download_epec_xml(company_id:, invoice_id:)` | XML de contingência EPEC (URI). | `Nfe::NfeFileResource` |
| `send_correction_letter(company_id:, invoice_id:, reason:)` | Emite CC-e; `reason` de 15 a 1000 caracteres. | `Hash` |
| `download_correction_letter_pdf(company_id:, invoice_id:)` | PDF da CC-e (URI). | `Nfe::NfeFileResource` |
| `download_correction_letter_xml(company_id:, invoice_id:)` | XML da CC-e (URI). | `Nfe::NfeFileResource` |
| `disable(company_id:, invoice_id:, reason: nil)` | Inutiliza uma nota (assíncrono). | `Hash` |
| `disable_range(company_id:, data:)` | Inutiliza uma faixa de numeração. | `Hash` |

As opções de cursor em `list`, `list_items` e `list_events` são
`starting_after`, `ending_before`, `limit` e `q`.

## Emitir uma NF-e

```ruby
result = client.product_invoices.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    buyer: { federalTaxNumber: 11111111111111, name: "Cliente Exemplo LTDA" },
    items: [
      { code: "001", description: "Produto X", quantity: 1, unitAmount: 99.9 }
    ]
  }
)

if result.pending?
  result.invoice_id   # acompanhe via retrieve
else
  result.resource     # Nfe::ProductInvoice
end
```

:::tip Idempotência
Tanto `create` quanto `create_with_state_tax` aceitam `idempotency_key:` (header
`Idempotency-Key`) e `request_options:` (overrides por chamada). Em retentativas,
reutilize a **mesma** chave para evitar emissão duplicada.
:::

## Listar com `environment` obrigatório

A paginação é por cursor e o parâmetro `environment` (String `"Production"` ou
`"Test"`) é **obrigatório** — chamar `list` sem ele levanta
`Nfe::InvalidRequestError` sem chamada HTTP.

```ruby
pagina = client.product_invoices.list(
  company_id: company_id,
  environment: "Production",
  limit: 50
)
pagina.each { |nf| puts nf.id }
```

:::note `environment` é o ambiente da SEFAZ
Este `environment` (String) é um parâmetro real de ambiente da SEFAZ, separado
da configuração produção/teste da conta (definida em
[app.nfe.io](https://app.nfe.io)). O `environment:` (símbolo) do `Nfe::Client`
está reservado para uso futuro.
:::

## Acompanhar até um estado terminal

```ruby
loop do
  nf = client.product_invoices.retrieve(
    company_id: company_id,
    invoice_id: invoice_id
  )
  break if Nfe::FlowStatus.terminal?(nf.flow_status)

  sleep 2
end
```

## Baixar arquivos (via URI)

```ruby
arquivo = client.product_invoices.download_pdf(
  company_id: company_id,
  invoice_id: invoice_id
)
arquivo.uri   # URL para baixar o DANFE PDF
```

## Carta de correção (CC-e)

O `reason` precisa ter entre 15 e 1000 caracteres; fora dessa faixa o SDK
levanta `Nfe::InvalidRequestError` antes de qualquer HTTP.

```ruby
client.product_invoices.send_correction_letter(
  company_id: company_id,
  invoice_id: invoice_id,
  reason: "Correção do endereço de entrega do destinatário"
)
```

## Inutilizar (disablement)

```ruby
# Uma nota específica:
client.product_invoices.disable(
  company_id: company_id,
  invoice_id: invoice_id,
  reason: "Numeração não utilizada"
)

# Uma faixa de numeração:
client.product_invoices.disable_range(
  company_id: company_id,
  data: {
    environment: "Production", serie: 1, state: "SP",
    beginNumber: 100, lastNumber: 110, reason: "Falha de impressão"
  }
)
```

## Próximos passos

- [Notas de consumidor (NFC-e)](./consumer-invoices.md) — downloads em bytes.
- [Emissão RTC](./rtc.md) — `product_invoices_rtc` com IBS/CBS/IS no item.
- [Paginação](../pagination.md) — cursor vs. página.

---

## Emissão RTC (Reforma Tributária — IBS, CBS e IS)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/rtc/index.md

# Emissão RTC (Reforma Tributária do Consumo)

A Reforma Tributária do Consumo (RTC) adiciona os grupos de tributos IBS, CBS e
IS aos documentos fiscais. O SDK expõe dois recursos dedicados e **opt-in** para
emitir no layout RTC, sem alterar os recursos clássicos:

- `client.service_invoices_rtc` — NFS-e RTC, host `api.nfe.io` sob `/v1`.
- `client.product_invoices_rtc` — NF-e (mod 55) e NFC-e (mod 65) RTC, host `api.nfse.io` sob `/v2`.

Ambos reutilizam os **mesmos endpoints** dos recursos clássicos. Não há header
nem parâmetro de discriminação: o layout RTC é selecionado pela **presença dos
grupos de imposto no payload**.

:::note O que seleciona o layout RTC
- Em serviço: o grupo `ibsCbs` na raiz do payload (camelCase).
- Em produto: o grupo `IBSCBS` no nível do item (`items[].tax.IBSCBS`).

Quando esses grupos estão ausentes, a API usa o layout clássico.
:::

:::tip `data:` é sempre um Hash em camelCase
Em ambos os recursos, `create(data:)` recebe um **Hash** com chaves camelCase,
serializado como está. As DTOs geradas (`Nfe::Generated::ServiceInvoiceRtcV1` e
`Nfe::Generated::ProductInvoiceRtcV1`) documentam a **forma** esperada do
payload, mas só desserializam respostas — não são aceitas como entrada.
:::

Consulte o guia conceitual em [Emissão RTC](../rtc-emission.md) para o contexto
fiscal completo.

---

## NFS-e RTC — `client.service_invoices_rtc`

Host `api.nfe.io` sob `/v1`, mesmo host do `client.service_invoices` clássico.

### Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create(company_id:, data:, idempotency_key: nil, request_options: nil)` | Emite a NFS-e RTC. | `ServiceInvoiceRtcPending` ou `ServiceInvoiceRtcIssued` |
| `retrieve(company_id:, invoice_id:)` | Consulta por id. | `Nfe::ServiceInvoice` |
| `cancel(company_id:, invoice_id:)` | Cancela (síncrono). | `Nfe::ServiceInvoice` |
| `download_cancellation_xml(company_id:, invoice_id:)` | XML do evento de cancelamento (e110001). | `String` binária |

### Emitir uma NFS-e RTC

O grupo `ibsCbs` (com `operationIndicator` e `classCode`) seleciona o layout.

```ruby
result = client.service_invoices_rtc.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    borrower: { federalTaxNumber: "191", name: "Banco do Brasil SA" },
    cityServiceCode: "2690",
    federalServiceCode: "01.01",
    description: "Consultoria",
    servicesAmount: 100.0,
    nbsCode: "1.0101",
    ibsCbs: {
      operationIndicator: "000000",
      classCode: "000001",
      cbs: { rate: 0.088, amount: 8.8 },
      ibs: { state: { rate: 0.177, amount: 17.7 }, municipal: { rate: 0.0, amount: 0.0 } }
    }
  }
)

if result.is_a?(Nfe::Resources::ServiceInvoiceRtcPending)
  result.invoice_id   # acompanhe via retrieve
else
  result.resource     # Nfe::ServiceInvoice
end
```

:::warning Cancellation XML é apenas do Ambiente Nacional
`download_cancellation_xml` só está disponível para notas do Ambiente Nacional
(ADN) e depois que a nota atinge o status `Cancelled`. Provedores
municipais/ABRASF não têm esse evento; nesse caso a API responde 404 e o SDK
levanta `Nfe::NotFoundError`.
:::

### Acompanhar até um estado terminal

```ruby
loop do
  nf = client.service_invoices_rtc.retrieve(
    company_id: company_id,
    invoice_id: invoice_id
  )
  break if Nfe::FlowStatus.terminal?(nf.flow_status)

  sleep 2
end
```

---

## NF-e / NFC-e RTC — `client.product_invoices_rtc`

Host `api.nfse.io` sob `/v2`, mesmo host do `client.product_invoices` clássico.
Um único `create` emite tanto NF-e (mod 55) quanto NFC-e (mod 65) — a distinção
vem da forma do payload (`printType`, `consumerType`/`presenceType`, presença de
`buyer`).

### Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create(company_id:, data:, idempotency_key: nil, request_options: nil)` | Emite a NF-e/NFC-e RTC. | `ProductInvoiceRtcPending` ou `ProductInvoiceRtcIssued` |
| `create_with_state_tax(company_id:, state_tax_id:, data:, idempotency_key: nil, request_options: nil)` | Emite vinculada a uma inscrição estadual. | `ProductInvoiceRtcPending` ou `ProductInvoiceRtcIssued` |
| `list(company_id:, environment:, starting_after: nil, ending_before: nil, limit: nil, q: nil)` | Lista por cursor; `environment` obrigatório. | `Nfe::ListResponse` |
| `retrieve(company_id:, invoice_id:)` | Consulta por id. | `InvoiceResource` |
| `cancel(company_id:, invoice_id:, reason: nil)` | Cancela (assíncrono). | `RequestCancellationResource` |
| `list_items(company_id:, invoice_id:)` | Lista os itens. | `InvoiceItemsResource` |
| `list_events(company_id:, invoice_id:)` | Lista os eventos. | `InvoiceEventsResource` |
| `download_pdf(company_id:, invoice_id:, force: false)` | DANFE PDF (URI). | `Nfe::NfeFileResource` |
| `download_xml(company_id:, invoice_id:)` | XML autorizado (URI). | `Nfe::NfeFileResource` |
| `download_rejection_xml(company_id:, invoice_id:)` | XML de rejeição (URI). | `Nfe::NfeFileResource` |
| `download_epec_xml(company_id:, invoice_id:)` | XML de contingência EPEC (URI). | `Nfe::NfeFileResource` |
| `send_correction_letter(company_id:, invoice_id:, reason:)` | Emite CC-e; `reason` de 15 a 1000 caracteres. | `RequestCancellationResource` |
| `download_correction_letter_pdf(company_id:, invoice_id:)` | PDF da CC-e (URI). | `Nfe::NfeFileResource` |
| `download_correction_letter_xml(company_id:, invoice_id:)` | XML da CC-e (URI). | `Nfe::NfeFileResource` |
| `disable(company_id:, invoice_id:, reason: nil)` | Inutiliza uma nota. | `DisablementResource` |
| `disable_range(company_id:, data:)` | Inutiliza uma faixa de numeração. | `DisablementResource` |

Os tipos `InvoiceResource`, `RequestCancellationResource`, `DisablementResource`
etc. pertencem a `Nfe::Generated::ProductInvoiceRtcV1`.

:::warning Downloads retornam URI, não bytes
Como no recurso clássico de produto, os downloads retornam um
`Nfe::NfeFileResource` (atributo `uri`), e não os bytes do arquivo.
:::

### Emitir uma NF-e RTC

O grupo `IBSCBS` no item (`items[].tax.IBSCBS`) seleciona o layout. O grupo `IS`
(Imposto Seletivo) existe apenas no payload de produto.

```ruby
result = client.product_invoices_rtc.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    buyer: { federalTaxNumber: 11111111111111, name: "Cliente Exemplo LTDA" },
    items: [
      {
        code: "001", description: "Produto X", quantity: 1, unitAmount: 100.0,
        tax: {
          IBSCBS: {
            state: { rate: 0.177, amount: 17.7 },
            municipal: { rate: 0.0, amount: 0.0 },
            cbs: { rate: 0.088, amount: 8.8 }
          },
          IS: {
            situationCode: "00", classificationCode: "000",
            basis: 100.0, rate: 0.0, amount: 0.0
          }
        }
      }
    ]
  }
)

if result.is_a?(Nfe::Resources::ProductInvoiceRtcPending)
  result.invoice_id
else
  result.resource   # Nfe::Generated::ProductInvoiceRtcV1::InvoiceResource
end
```

### Listar com `environment` obrigatório

```ruby
pagina = client.product_invoices_rtc.list(
  company_id: company_id,
  environment: "Production",
  limit: 50
)
pagina.each { |nf| puts nf.flow_status }
```

:::note `environment` é o ambiente da SEFAZ
O `environment` (String `"Production"`/`"Test"`) é o ambiente real da SEFAZ,
separado da configuração produção/teste da conta em
[app.nfe.io](https://app.nfe.io). Omiti-lo levanta `Nfe::InvalidRequestError`
sem chamada HTTP.
:::

### Acompanhar até um estado terminal

```ruby
loop do
  nf = client.product_invoices_rtc.retrieve(
    company_id: company_id,
    invoice_id: invoice_id
  )
  break if Nfe::FlowStatus.terminal?(nf.flow_status)

  sleep 2
end
```

## Próximos passos

- [Emissão RTC (guia conceitual)](../rtc-emission.md) — IBS/CBS/IS em detalhe.
- [Notas de serviço](./service-invoices.md) e [Notas de produto](./product-invoices.md) — os recursos clássicos.

---

## Notas fiscais de serviço (NFS-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/notas-fiscais-de-servico/index.md

# Notas fiscais de serviço (NFS-e)

`client.service_invoices` é o recurso canônico de emissão da plataforma. Ele
fala com o host `api.nfe.io` no caminho `/v1` e cobre todo o ciclo de vida da
NFS-e: emissão assíncrona, listagem paginada, consulta, cancelamento, envio por
e-mail e download de PDF/XML.

A emissão segue o **contrato 202 discriminado**: `create` devolve um de dois
tipos, e você acompanha o processamento com `retrieve` (ou `get_status`) até um
estado terminal. Não existe `create_and_wait` nem `create_batch` na `v1.0`.

:::note Host e versão
Todas as URLs efetivas ficam sob `https://api.nfe.io/v1/...`. Este é o único
recurso de nota que usa o host `api.nfe.io`; os demais usam `api.nfse.io`.
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `create(company_id:, data:, idempotency_key: nil, request_options: nil)` | Emite a NFS-e. | `ServiceInvoicePending` ou `ServiceInvoiceIssued` |
| `list(company_id:, **options)` | Lista paginada (page-style) com filtros de data. | `Nfe::ListResponse` |
| `retrieve(company_id:, invoice_id:)` | Consulta uma NFS-e por id. | `Nfe::ServiceInvoice` |
| `cancel(company_id:, invoice_id:)` | Cancela (síncrono) e devolve o modelo atualizado. | `Nfe::ServiceInvoice` |
| `send_email(company_id:, invoice_id:)` | Reenvia a nota por e-mail ao tomador. | `Hash` com `sent:` e `message:` |
| `download_pdf(company_id:, invoice_id: nil)` | PDF da nota; sem `invoice_id`, baixa o ZIP da empresa. | `String` binária |
| `download_xml(company_id:, invoice_id: nil)` | XML da nota; sem `invoice_id`, baixa o ZIP da empresa. | `String` binária |
| `get_status(company_id:, invoice_id:)` | Snapshot de status derivado de `retrieve` (sem HTTP extra). | `StatusResult` |

As opções de `list` (em snake_case) são `page_index`, `page_count`,
`issued_begin`, `issued_end`, `created_begin`, `created_end` e `has_totals`.

:::warning Validação fail-fast
Todo método valida `company_id` e `invoice_id` via `Nfe::IdValidator` **antes**
de qualquer chamada HTTP. Ids vazios ou em branco levantam
`Nfe::InvalidRequestError` sem tráfego de rede.
:::

## Emitir uma NFS-e e tratar o retorno discriminado

`create` devolve `ServiceInvoicePending` (HTTP 202, enfileirada) ou
`ServiceInvoiceIssued` (HTTP 201, já materializada). Distinga por pattern
matching ou pelos predicados `pending?` / `issued?`.

```ruby
result = client.service_invoices.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    cityServiceCode: "2690",
    description: "Manutenção e suporte técnico",
    servicesAmount: 100.0,
    borrower: { federalTaxNumber: "191", name: "Banco do Brasil SA" }
  }
)

case result
in Nfe::Resources::ServiceInvoicePending => pending
  pending.invoice_id   # id para reconsultar enquanto processa
  pending.location     # caminho do header Location
in Nfe::Resources::ServiceInvoiceIssued => issued
  issued.resource      # Nfe::ServiceInvoice já emitida
end
```

:::tip Idempotência em retentativas
Passe `idempotency_key:` para enviar o header `Idempotency-Key`. O SDK nunca
refaz o POST sozinho; em um timeout, reinvoque `create` com a **mesma** chave
para o servidor deduplicar e não emitir documento fiscal duplicado.
:::

## Acompanhar até um estado terminal (polling)

Use `get_status`, que deriva o status de um único `retrieve` (sem chamada HTTP
adicional) e expõe `complete?` e `failed?`.

```ruby
company_id = "55df4dc6b6cd9007e4f13ee8"
invoice_id = result.pending? ? result.invoice_id : result.resource.id

loop do
  status = client.service_invoices.get_status(
    company_id: company_id,
    invoice_id: invoice_id
  )
  break if status.complete?   # via Nfe::FlowStatus.terminal?

  sleep 2
end
```

Como alternativa, você pode chamar `retrieve` diretamente e testar
`Nfe::FlowStatus.terminal?(invoice.flow_status)`.

## Baixar PDF e XML (bytes binários)

Os downloads retornam uma `String` binária (`ASCII-8BIT`) — grave com
`File.binwrite`. Omitir `invoice_id` baixa o ZIP de todas as notas da empresa.

```ruby
pdf = client.service_invoices.download_pdf(
  company_id: company_id,
  invoice_id: invoice_id
)
File.binwrite("nfse.pdf", pdf)

# ZIP de todas as notas da empresa (sem invoice_id):
zip = client.service_invoices.download_xml(company_id: company_id)
File.binwrite("notas.zip", zip)
```

## Cancelar e reenviar por e-mail

```ruby
cancelada = client.service_invoices.cancel(
  company_id: company_id,
  invoice_id: invoice_id
)
cancelada.flow_status   # "Cancelled"

envio = client.service_invoices.send_email(
  company_id: company_id,
  invoice_id: invoice_id
)
envio[:sent]   # true/false
```

## Próximos passos

- [Primeiros passos](../getting-started.md) — instalação e primeira emissão.
- [Notas de produto (NF-e)](./product-invoices.md) — host `api.nfse.io` e downloads por URI.
- [Emissão RTC](./rtc.md) — layout da Reforma Tributária.

---

## Inscrições estaduais (state_taxes) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/inscricoes-estaduais/index.md

# Inscrições estaduais (`state_taxes`)

O recurso `state_taxes` gerencia as inscrições estaduais (Inscrição Estadual) de
uma empresa. Faz parte da família `cte`, servida por
`api.nfse.io` (`/v2/companies/{companyId}/statetaxes`), e usa a `api_key`.

## Métodos públicos

```ruby
state_taxes.list(company_id, starting_after: nil, ending_before: nil, limit: nil)
# => Nfe::ListResponse

state_taxes.create(company_id, data)                  # => Nfe::NfeStateTax
state_taxes.retrieve(company_id, state_tax_id)        # => Nfe::NfeStateTax
state_taxes.update(company_id, state_tax_id, data)    # => Nfe::NfeStateTax
state_taxes.delete(company_id, state_tax_id)          # => nil
```

:::note Lista cursor-style
`list` usa paginação **cursor-style** (`starting_after`/`ending_before`/`limit`) e
devolve um `Nfe::ListResponse` — diferente das listas page-style de
[tax_codes](./tax-codes.md). Veja [Paginação](../pagination.md).
:::

## Exemplos

### Criar e recuperar uma inscrição

```ruby
require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))
company_id = "55df4dc6b6cd9007e4f13ee8"

ie = client.state_taxes.create(
  company_id,
  code: "SP",
  taxNumber: "1234567890"
)

client.state_taxes.retrieve(company_id, ie.id)
```

:::tip O corpo é embrulhado em `stateTax`
Você passa apenas os atributos (em camelCase). O SDK embrulha o corpo como
`{ "stateTax": { ... } }` em `create`/`update` e desembrulha a resposta
automaticamente antes de hidratar `Nfe::NfeStateTax`.
:::

### Listar com cursor e atualizar

```ruby
pagina = client.state_taxes.list(company_id, limit: 50)
pagina.data.each { |ie| puts ie.code }

client.state_taxes.update(company_id, ie.id, taxNumber: "0987654321")
client.state_taxes.delete(company_id, ie.id)
```

## Veja também

- [Empresas](./companies.md) — o escopo (`company_id`) das inscrições.
- [Consulta de CNPJ](./legal-entity-lookup.md) — consultar a IE de terceiros para emissão.
- [Paginação](../pagination.md) — paginação cursor-style.

---

## Cálculo de impostos (tax_calculation) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/calculo-de-impostos/index.md

# Cálculo de impostos (`tax_calculation`)

O recurso `tax_calculation` executa o motor de regras tributárias de um tenant e
devolve o detalhamento de impostos por item. Faz parte da família `cte`, servida
por `api.nfse.io`, e usa a `api_key` (emissão é capacidade central, não consulta
de dados).

## Métodos públicos

```ruby
tax_calculation.calculate(tenant_id, request)
# => Nfe::Generated::CalculoImpostosV1::CalculateResponse
```

O `request` é um `Hash` com chaves em camelCase. Para type-safety, você pode
construí-lo a partir de `Nfe::Generated::CalculoImpostosV1::CalculateRequest#to_h`.

## Exemplo

### Calcular impostos de um pedido

```ruby
require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))

resultado = client.tax_calculation.calculate(
  "tenant-123",
  {
    operationType: "Sale",
    items: [
      { code: "SKU-1", quantity: 2, unitAmount: 49.90, ncm: "61091000" }
    ]
  }
)

resultado
```

:::warning Validação fail-fast (sem HTTP)
Antes de qualquer requisição, o SDK valida que `tenant_id` é não vazio e que o
`request` é um `Hash` contendo `operation_type` (ou `operationType`) e um array
`items` **não vazio**. Caso contrário, levanta `Nfe::InvalidRequestError`.
:::

:::tip Use o request tipado quando quiser segurança de tipos
`CalculateRequest#to_h` ajuda a montar o corpo com a forma esperada (ICMS, IPI,
PIS, COFINS, II, ICMS-UF-Dest etc.) sem digitar as chaves à mão.
:::

## Veja também

- [Tabelas tributárias (tax_codes)](./tax-codes.md) — códigos de referência para montar o request.
- [Inscrições estaduais (state_taxes)](./state-taxes.md) — outro recurso da família `cte`.

---

## Tabelas tributárias (tax_codes) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/codigos-fiscais/index.md

# Tabelas tributárias (`tax_codes`)

O recurso `tax_codes` expõe as quatro listas de referência consumidas ao montar um
CT-e: códigos de operação, finalidades de aquisição e os perfis tributários do
emitente e do destinatário. Faz parte da família `cte`, servida por `api.nfse.io`,
e usa a `api_key`.

## Métodos públicos

```ruby
tax_codes.list_operation_codes(page_index: nil, page_count: nil)        # => Nfe::TaxCodePaginatedResponse
tax_codes.list_acquisition_purposes(page_index: nil, page_count: nil)   # => Nfe::TaxCodePaginatedResponse
tax_codes.list_issuer_tax_profiles(page_index: nil, page_count: nil)    # => Nfe::TaxCodePaginatedResponse
tax_codes.list_recipient_tax_profiles(page_index: nil, page_count: nil) # => Nfe::TaxCodePaginatedResponse
```

:::note Paginação page-style (1-based)
Diferente das listas cursor-style do SDK, estes endpoints paginam por página
**1-based** (`page_index`/`page_count`) e devolvem um `Nfe::TaxCodePaginatedResponse`
(não um `Nfe::ListResponse`). Os parâmetros de paginação só são enviados quando
informados.
:::

## Exemplos

### Listar códigos de operação

```ruby
require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))

# Sem paginação explícita:
client.tax_codes.list_operation_codes

# Página 2, 20 itens (page_index é 1-based):
client.tax_codes.list_operation_codes(page_index: 2, page_count: 20)
```

### Listar perfis tributários e finalidades

```ruby
client.tax_codes.list_acquisition_purposes
client.tax_codes.list_issuer_tax_profiles
client.tax_codes.list_recipient_tax_profiles
```

## Veja também

- [Cálculo de impostos (tax_calculation)](./tax-calculation.md) — consome estes códigos.
- [Paginação](../pagination.md) — diferenças entre listas page-style e cursor-style.

---

## Conhecimentos de transporte recebidos (CT-e)

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/conhecimentos-de-transporte/index.md

# Conhecimentos de transporte recebidos (CT-e)

`client.transportation_invoices` gerencia CT-e (Conhecimento de Transporte
Eletrônico) **recebidos**, no host `api.nfse.io`, sob `/v2`. Ele habilita a
busca automática via SEFAZ Distribuição DFe e lê documentos e eventos por chave
de acesso de 44 dígitos.

:::note Recurso de entrada, não de emissão
Este é um recurso de consulta/configuração (settings + buscas por chave de
acesso). Não há contrato 202 `Pending` / `Issued` aqui — não se emite CT-e por
este recurso.
:::

## Métodos

| Método | Descrição | Retorno |
|---|---|---|
| `enable(company_id:, start_from_nsu: nil, start_from_date: nil)` | Habilita a busca automática de CT-e. | `Nfe::InboundSettings` |
| `disable(company_id:)` | Desabilita a busca automática. | `Nfe::InboundSettings` |
| `get_settings(company_id:)` | Lê as configurações atuais de busca. | `Nfe::InboundSettings` |
| `retrieve(company_id:, access_key:)` | Metadados do CT-e por chave de acesso. | `Nfe::InboundInvoiceMetadata` |
| `download_xml(company_id:, access_key:)` | XML do CT-e. | `String` binária |
| `get_event(company_id:, access_key:, event_key:)` | Metadados de um evento do CT-e. | `Nfe::InboundInvoiceMetadata` |
| `download_event_xml(company_id:, access_key:, event_key:)` | XML de um evento do CT-e. | `String` binária |

:::warning Chave de acesso normalizada
A `access_key` é normalizada por `Nfe::IdValidator.access_key`: separadores
(espaços, pontos, traços) são removidos e o valor precisa ter exatamente 44
dígitos. Caso contrário, o SDK levanta `Nfe::InvalidRequestError` antes de
qualquer chamada HTTP.
:::

## Habilitar a busca automática

```ruby
settings = client.transportation_invoices.enable(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  start_from_date: "2026-01-01"
)
settings   # Nfe::InboundSettings
```

`start_from_nsu` e `start_from_date` são opcionais; quando `nil`, são omitidos
do corpo da requisição.

## Ler um CT-e recebido por chave de acesso

```ruby
access_key = "35240611111111000199570010000012341000012345"

cte = client.transportation_invoices.retrieve(
  company_id: company_id,
  access_key: access_key
)

xml = client.transportation_invoices.download_xml(
  company_id: company_id,
  access_key: access_key
)
File.binwrite("cte.xml", xml)
```

## Consultar e baixar um evento

```ruby
evento = client.transportation_invoices.get_event(
  company_id: company_id,
  access_key: access_key,
  event_key: "35240611111111000199570010000012341000012345-110111-01"
)

xml = client.transportation_invoices.download_event_xml(
  company_id: company_id,
  access_key: access_key,
  event_key: evento.id
)
File.binwrite("cte-evento.xml", xml)
```

## Próximos passos

- [NF-e de entrada (manifestação)](./inbound-product-invoices.md) — ingestão de NF-e de fornecedores.
- [Webhooks](../webhooks.md) — receba notificações de novos documentos.

---

## Webhooks no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/recursos/webhooks/index.md

# Webhooks

O recurso `webhooks` gerencia as assinaturas de webhook **escopadas por empresa**,
sob `/companies/{id}/webhooks`. Faz parte da família `main`, servida por
`api.nfe.io` (`/v1`), e usa a `api_key`. Além do CRUD, expõe um disparo de teste,
a lista estática de eventos e a verificação de assinatura.

## Métodos públicos

```ruby
webhooks.list(company_id)                          # => Nfe::ListResponse
webhooks.create(company_id, data)                  # => Nfe::WebhookSubscription
webhooks.retrieve(company_id, webhook_id)          # => Nfe::WebhookSubscription
webhooks.update(company_id, webhook_id, data)      # => Nfe::WebhookSubscription
webhooks.delete(company_id, webhook_id)            # => nil
webhooks.test(company_id, webhook_id)              # => { success: bool, message: String? }
webhooks.get_available_events                      # => Array<String>
webhooks.verify_signature(payload:, signature:, secret:) # => Boolean
```

Os eventos disponíveis (`get_available_events`) são:
`invoice.issued`, `invoice.cancelled`, `invoice.failed`, `invoice.processing`,
`company.created`, `company.updated` e `company.deleted`.

## Exemplos

### Criar e testar uma assinatura

```ruby
require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))
company_id = "55df4dc6b6cd9007e4f13ee8"

hook = client.webhooks.create(
  company_id,
  url: "https://app.exemplo.com.br/webhooks/nfe",
  events: ["invoice.issued", "invoice.failed"],
  secret: ENV.fetch("NFE_WEBHOOK_SECRET"),
  active: true
)

# Dispara uma entrega sintética para validar que o endpoint responde:
result = client.webhooks.test(company_id, hook.id)
result[:success]
```

### Verificar a assinatura de um payload recebido

```ruby
ok = client.webhooks.verify_signature(
  payload: request.raw_post,
  signature: request.get_header("HTTP_X_NFE_SIGNATURE"),
  secret: ENV.fetch("NFE_WEBHOOK_SECRET")
)

head :unauthorized unless ok
```

:::tip Use o módulo `Nfe::Webhook` no handler
`webhooks.verify_signature` é uma delegação fina para `Nfe::Webhook.verify_signature`,
oferecida por paridade com o SDK Node. No seu controlador HTTP, prefira chamar o
módulo diretamente — ele não exige um `Nfe::Client` e **nunca** levanta exceção,
apenas devolve `true`/`false`. Veja o guia de [Webhooks](../webhooks.md).
:::

:::note `list` tolera vários formatos
`list(company_id)` aceita a resposta da API como array puro, embrulhada em `data`
ou em um envelope `webhooks`, sempre devolvendo um `Nfe::ListResponse`.
:::

## Veja também

- [Webhooks (guia)](../webhooks.md) — verificação de assinatura e recebimento por push.
- [Empresas](./companies.md) — o escopo (`company_id`) das assinaturas.
- [Emissão assíncrona e polling](../async-and-polling.md) — alternativa por polling.

---

## Emissão RTC (Reforma Tributária do Consumo) no SDK Ruby da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/emissao-rtc/index.md

# Emissão RTC

A **Reforma Tributária do Consumo (RTC)** introduz os novos grupos de imposto
(IBS, CBS e, para produtos, o Imposto Seletivo — IS). O SDK expõe a emissão RTC
de forma **opt-in**, por meio de dois recursos dedicados:

- `service_invoices_rtc` — NFS-e, host `api.nfe.io` (família `main`).
- `product_invoices_rtc` — NF-e (mod 55) e NFC-e (mod 65), host `api.nfse.io` (família `cte`).

Os recursos clássicos (`service_invoices` e `product_invoices`) permanecem
inalterados.

## O layout RTC é selecionado pela forma do payload

Os recursos RTC usam os **mesmos endpoints** e o mesmo fluxo dos recursos
clássicos. **Não existe header discriminador nem parâmetro de query**: a API
seleciona o layout RTC a partir da **presença** de um grupo no payload.

- NFS-e: presença do grupo `ibsCbs` na raiz do payload.
- Produto: presença do grupo a nível de item em `items[].tax.IBSCBS`.

Quando esses grupos estão ausentes, a API recai no layout clássico.

:::note `create(data:)` recebe um Hash
`create` recebe um **Hash** com chaves em **camelCase** (serializado como JSON
tal como está). Os DTOs gerados (`Nfe::Generated::ServiceInvoiceRtcV1::NFSeRequest`
e `Nfe::Generated::ProductInvoiceRtcV1::ProductInvoiceRequest`) **documentam a
forma** do payload, mas não são aceitos como entrada — eles apenas desserializam
respostas (`from_api`) e não têm caminho de re-serialização camelCase.
:::

## NFS-e RTC: o grupo `ibsCbs`

```ruby
result = client.service_invoices_rtc.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    cityServiceCode: "2690",
    federalServiceCode: "0107",
    description: "Manutenção e suporte técnico",
    servicesAmount: 100.0,
    nbsCode: "123456789",
    borrower: { federalTaxNumber: "191", name: "Banco do Brasil SA" },
    ibsCbs: {
      operationIndicator: "000000",
      classCode: "000001",
      cbs: { rate: 0.009, amount: 0.9 },
      ibs: {
        state: { rate: 0.001, amount: 0.1 },
        municipal: { rate: 0.0, amount: 0.0 }
      }
    }
  }
)
```

Dentro de `ibsCbs`, `operationIndicator` (6 dígitos, `^[0-9]{6}$`) e `classCode`
(até 6 caracteres) são obrigatórios.

## Produto RTC: `items[].tax.IBSCBS` e `IS`

No payload de produto, os grupos RTC ficam **a nível de item**, em `items[].tax`,
ao lado dos grupos legados. O `IBSCBS` divide o IBS em esfera estadual (`state`)
e municipal (`municipal`), com o `cbs` (federal) sem divisão. O grupo `IS`
(Imposto Seletivo) é **exclusivo do payload de produto** — não há equivalente na
NFS-e.

```ruby
result = client.product_invoices_rtc.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    printType: "Normal",
    items: [
      {
        code: "001",
        description: "Produto exemplo",
        quantity: 1,
        unitAmount: 100.0,
        tax: {
          IBSCBS: {
            state: { rate: 0.001, amount: 0.1 },
            municipal: { rate: 0.0, amount: 0.0 },
            cbs: { rate: 0.009, amount: 0.9 }
          },
          IS: {
            situationCode: "000",
            classificationCode: "000000",
            basis: 100.0,
            rate: 0.0,
            amount: 0.0
          }
        }
      }
    ]
  }
)
```

:::tip NF-e (mod 55) vs NFC-e (mod 65)
Os dois modelos são emitidos pelo mesmo `create` e pelo mesmo endpoint. A
distinção vem da **forma do payload** (`printType`, `consumerType`/`presenceType`,
presença de `buyer`, presença de `expectedDeliveryOn`) — nenhum discriminador de
`model`/`mod` é enviado na raiz da requisição.
:::

## Retorno discriminado e polling

Como na emissão clássica, `create` devolve **um de dois tipos**, distinguíveis
por pattern matching ou pelos predicados `pending?`/`issued?`. As classes RTC são
distintas das clássicas:

- NFS-e: `Nfe::Resources::ServiceInvoiceRtcPending` / `ServiceInvoiceRtcIssued`.
- Produto: `Nfe::Resources::ProductInvoiceRtcPending` / `ProductInvoiceRtcIssued`.

```ruby
case result
in Nfe::Resources::ServiceInvoiceRtcPending => pending
  pending.invoice_id   # reconsultar enquanto processa
in Nfe::Resources::ServiceInvoiceRtcIssued => issued
  issued.resource      # nota já materializada
end
```

Não existe `create_and_wait`/`create_batch` — faça polling com `retrieve` até um
estado terminal usando `Nfe::FlowStatus.terminal?`:

```ruby
company_id = "55df4dc6b6cd9007e4f13ee8"
invoice_id = result.pending? ? result.invoice_id : result.resource.id

loop do
  invoice = client.service_invoices_rtc.retrieve(
    company_id: company_id,
    invoice_id: invoice_id
  )
  break if Nfe::FlowStatus.terminal?(invoice.flow_status)

  sleep 2
end
```

:::note Downloads de produto continuam devolvendo uma URI
Os `download_*` de `product_invoices_rtc` retornam um `Nfe::NfeFileResource`
(URI), exatamente como o recurso clássico de produto. Veja [Downloads](./downloads.md).
:::

## Próximos passos

- [Primeiros passos](./getting-started.md) — emissão clássica e o contrato 202.
- [Downloads](./downloads.md) — bytes vs. `Nfe::NfeFileResource`.
- [Roteamento multi-host](./multi-host-routing.md) — os hosts `main` e `cte`.
- [Webhooks](./webhooks.md) — receba a conclusão por push.

---

## Verificação de webhooks da NFE.io

Source: https://nfe.io/docs/desenvolvedores/bibliotecas/ruby/webhooks/index.md

# Webhooks

Em vez de fazer polling até um estado terminal, você pode receber a conclusão da
emissão por push. A NFE.io entrega um webhook; seu endpoint **verifica a
assinatura** e reage ao evento. Este guia cobre a verificação canônica via
`Nfe::Webhook`.

## Como a NFE.io assina as entregas

Cada entrega traz o cabeçalho `X-Hub-Signature` com um HMAC-SHA1 calculado sobre
os **bytes exatos** do corpo da requisição, no formato `sha1=<40 hex>`:

```text
X-Hub-Signature: sha1=BCD17C02B9E3B40A18E745E7E04247E4AD2DD935
```

:::warning Documentação antiga está errada
Apenas o esquema `X-Hub-Signature` + **HMAC-SHA1** é suportado. Material de
distribuição mais antigo que menciona `X-NFe-Signature`, **SHA-256** ou
**Base64** está incorreto — um cabeçalho `sha256=` é rejeitado.
:::

## A API de verificação

`Nfe::Webhook` é um módulo de funções **sem estado**: não precisa de um
`Nfe::Client`, não lê a `Nfe::Configuration` e não faz nenhuma chamada de rede.
Você fornece os três argumentos: o corpo cru, o valor do cabeçalho e o segredo.

```ruby
require "nfe"

ok = Nfe::Webhook.verify_signature(
  payload: raw_body,
  signature: signature_header,
  secret: ENV.fetch("NFE_WEBHOOK_SECRET")
)
```

### `verify_signature` → Boolean

Retorna `true` **somente** quando o HMAC-SHA1 confere exatamente. A comparação é
feita em tempo constante (`OpenSSL.secure_compare`) e o prefixo `sha1=` é
comparado de forma **case-insensitive** (a NFE.io envia o hex em maiúsculas).

:::tip Nunca levanta exceção
`verify_signature` **nunca** levanta. Qualquer entrada ausente, malformada, com
algoritmo errado, comprimento errado ou conteúdo não-hexadecimal resulta em
`false`. Um segredo ou assinatura `nil`/vazia também retorna `false`.
:::

Se o cabeçalho chegar como um array de um elemento (formato que algumas pilhas
Rack/HTTP usam para cabeçalhos repetidos), o primeiro elemento é usado.

### `construct_event` → `Nfe::WebhookEvent`

Quando você quer não só validar, mas também desempacotar o evento, use
`construct_event`. Ele verifica primeiro; em caso de falha de assinatura **ou**
de JSON inválido, levanta `Nfe::SignatureVerificationError`.

```ruby
event = Nfe::Webhook.construct_event(
  payload: raw_body,
  signature: signature_header,
  secret: ENV.fetch("NFE_WEBHOOK_SECRET")
)

event.type       # ex.: "invoice.issued"
event.data       # Hash com o payload (a chave "payload" ou "data" do envelope)
event.id         # id estável para deduplicação, ou nil
event.created_at # timestamp da entrega como String, ou nil
```

`Nfe::WebhookEvent` é um objeto de valor imutável (`Data.define`). O `type` é
desempacotado da chave `action`/`event`/`type`/`event_type` do envelope, e o
`data` da chave `payload`/`data`.

## Leia o corpo CRU antes de parsear o JSON

A NFE.io assina os bytes que entregou. Leia o corpo cru **antes** de qualquer
parsing de JSON e passe esses bytes ao verificador.

:::warning Não re-serialize o payload
Nunca passe um objeto já parseado e re-serializado (por exemplo
`payload.to_json`). A ordem das chaves e os espaços em branco vão diferir dos
bytes assinados, e a verificação falhará de forma imprevisível. Sempre use o
corpo cru — `request.raw_post` ou `request.body.read`.
:::

## Exemplo: controller Rails

```ruby
class NfeWebhooksController < ActionController::Base
  # Webhooks não têm token CSRF.
  skip_before_action :verify_authenticity_token

  def create
    raw = request.raw_post
    signature = request.headers["X-Hub-Signature"]
    secret = ENV.fetch("NFE_WEBHOOK_SECRET")

    unless Nfe::Webhook.verify_signature(payload: raw, signature: signature, secret: secret)
      head :unauthorized
      return
    end

    event = Nfe::Webhook.construct_event(payload: raw, signature: signature, secret: secret)
    process_event(event) # idempotente — veja abaixo
    head :ok
  rescue Nfe::SignatureVerificationError
    head :unauthorized
  end

  private

  def process_event(event)
    # Dedupe pelo id do evento/nota antes de aplicar efeitos colaterais.
    return if already_handled?(event.id)

    mark_handled(event.id)
    # ... reaja a event.type / event.data ...
  end
end
```

:::note Em Rack puro
O valor do cabeçalho está em `request.get_header("HTTP_X_HUB_SIGNATURE")` e o
corpo cru em `request.body.read` (rebobine com `request.body.rewind` se for ler
de novo depois).
:::

## Validade não é frescor — handlers devem ser idempotentes

A NFE.io **não** envia primitiva de anti-replay: as entregas trazem apenas o
HMAC-SHA1 sobre o corpo, sem timestamp e sem nonce. Uma assinatura válida prova
**autenticidade**, mas não **frescor** — uma entrega reproduzida (replay) carrega
uma assinatura perfeitamente válida.

:::warning Sempre dedupe
Trate seus handlers como **idempotentes** e faça **deduplicação pelo
`event.id`** (id do evento ou da nota). Processar a mesma entrega duas vezes não
pode gerar efeitos colaterais duplicados.
:::

## Próximos passos

- [Primeiros passos](./getting-started.md) — emissão e polling como alternativa ao push.
- [Paginação](./pagination.md) — percorra listas de notas.
- [Downloads](./downloads.md) — baixe PDF/XML das notas.

---

## Documentação para agentes e LLMs

Source: https://nfe.io/docs/docs-para-agentes/index.md

# Documentação para agentes e LLMs

A documentação da NFe.io é publicada em formato amigável para agentes de IA, pipelines de RAG (Retrieval-Augmented Generation) e modelos de contexto longo. Esta página descreve os recursos disponíveis para que sua ferramenta consuma o conteúdo de forma eficiente, mantendo as respostas atualizadas e fundamentadas em fontes oficiais.

## Início rápido

Três caminhos, do mais simples ao mais completo:

1. **Página única em Markdown** — anexe `/index.md` a qualquer URL pra obter a versão Markdown puro daquela página.
2. **Catálogo de uma área** — leia o `llms.txt` do produto que interessa (ex.: `/docs/integracoes/llms.txt`) para um índice das páginas e use os links pra puxar cada `index.md`.
3. **Documentação completa de uma área** — leia o `llms-full.txt` daquele produto pra obter todas as páginas concatenadas em um único arquivo.

## Markdown por página

Cada página de documentação possui um arquivo Markdown companheiro publicado no mesmo diretório, ao lado do `index.html`, seguindo a convenção do padrão **append `/index.md`**:

```text
https://nfe.io/docs/documentacao/conceitos/introducao/           ← HTML
https://nfe.io/docs/documentacao/conceitos/introducao/index.md   ← Markdown
```

No topo de cada página de documentação você encontra dois botões para a mesma URL:

- **Ver como Markdown** — abre o arquivo em uma nova aba (link HTML puro, funciona com JavaScript desabilitado).
- **Copiar como Markdown** — copia o conteúdo bruto para a área de transferência.

### Negociação por header `Accept: text/markdown`

Requisite qualquer página com o header `Accept: text/markdown` e o servidor responde com a versão Markdown ao invés do HTML — sem precisar trocar a URL:

```bash
curl "https://nfe.io/docs/documentacao/conceitos/introducao/" \
  --header "Accept: text/markdown"
```

Útil quando o agente já tem a URL canônica e quer evitar o `index.md` extra na string.

### Conteúdo limpo

O arquivo `.md` é gerado a partir da fonte com as seguintes transformações:

- Componentes MDX (`<Tabs>`, `<TabItem>`, `<details>`, `<summary>`, iframes do YouTube) convertidos para Markdown legível.
- Imports MDX e componentes React personalizados removidos.
- Caminhos de imagem reescritos para URLs absolutas, permitindo renderização em qualquer cliente.
- Frontmatter YAML com metadados úteis (ver abaixo).

### Frontmatter de cada arquivo Markdown

Cada `index.md` começa com um cabeçalho YAML mínimo com os campos:

```yaml
---
title: "Título da página"
description: "Resumo curto extraído do front-matter da fonte."
source_url: https://nfe.io/docs/caminho-canonico/
last_updated: 2026-04-22
---
```

| Campo | Descrição |
|---|---|
| `title` | Título exibido na página HTML. |
| `description` | Resumo da página (mesmo usado em meta tags da versão HTML). |
| `source_url` | URL canônica da versão HTML — útil para o agente citar a fonte original. |
| `last_updated` | Data em ISO 8601 (`YYYY-MM-DD`). Vem do `last_update.date` do front-matter da fonte ou do mtime do arquivo. |

## Manifestos `llms.txt`

A documentação segue o padrão [llmstxt.org](https://llmstxt.org), com endpoints em dois níveis (site-wide e por produto).

### Endpoints site-wide

| Endpoint | Descrição |
|---|---|
| <a href="/docs/llms.txt"><code>/docs/llms.txt</code></a> | Índice dos produtos disponíveis, agrupados por categoria, com link para o `llms.txt` de cada um. |
| <a href="/docs/llms-full.txt"><code>/docs/llms-full.txt</code></a> | Arquivo único com o conteúdo concatenado da documentação institucional. APIs REST e Prefeituras integradas ficam de fora — cada produto tem o seu próprio `llms-full.txt`. |

### Endpoints por produto

Cada produto publica seus próprios manifestos sob o prefixo da URL pública:

| Produto | Manifesto |
|---|---|
| Documentação da plataforma | <a href="/docs/documentacao/llms.txt"><code>/docs/documentacao/llms.txt</code></a> |
| Integrações com plataformas | <a href="/docs/integracoes/llms.txt"><code>/docs/integracoes/llms.txt</code></a> |
| SDKs e Bibliotecas | <a href="/docs/desenvolvedores/bibliotecas/llms.txt"><code>/docs/desenvolvedores/bibliotecas/llms.txt</code></a> |
| Legislação tributária | <a href="/docs/legislacao/llms.txt"><code>/docs/legislacao/llms.txt</code></a> |
| Release notes | <a href="/docs/release-notes/llms.txt"><code>/docs/release-notes/llms.txt</code></a> |
| Dúvidas frequentes | <a href="/docs/duvidas-frequentes/llms.txt"><code>/docs/duvidas-frequentes/llms.txt</code></a> |

Cada um desses caminhos também tem um companheiro `llms-full.txt` com o conteúdo completo daquela área.

## Especificações OpenAPI

As APIs REST da NFe.io são documentadas em arquivos OpenAPI (YAML ou JSON) publicados em `/docs/api/`. Use estes endpoints quando seu agente precisar gerar chamadas para a API sem consultar a documentação HTML manualmente:

| API | Arquivo |
|---|---|
| Nota Fiscal de Serviço (NFS-e) v1 | <a href="/docs/api/nf-servico-v1.yaml"><code>/docs/api/nf-servico-v1.yaml</code></a> |
| Nota Fiscal de Produto (NF-e) v2 | <a href="/docs/api/nf-produto-v2.yaml"><code>/docs/api/nf-produto-v2.yaml</code></a> |
| Nota Fiscal de Consumidor (NFC-e) v2 | <a href="/docs/api/nf-consumidor-v2.yaml"><code>/docs/api/nf-consumidor-v2.yaml</code></a> |
| NFS-e RTC (Reforma Tributária) | <a href="/docs/api/service-invoice-rtc-v1.yaml"><code>/docs/api/service-invoice-rtc-v1.yaml</code></a> |
| NF-e/NFC-e RTC (Reforma Tributária) | <a href="/docs/api/product-invoice-rtc-v1.yaml"><code>/docs/api/product-invoice-rtc-v1.yaml</code></a> |
| Cálculo de Impostos v1 | <a href="/docs/api/calculo-impostos-v1.yaml"><code>/docs/api/calculo-impostos-v1.yaml</code></a> |
| Cadastro de Produtos v1 | <a href="/docs/api/product-register-pt-br-v1.yaml"><code>/docs/api/product-register-pt-br-v1.yaml</code></a> |
| Contribuintes v2 | <a href="/docs/api/contribuintes-v2.json"><code>/docs/api/contribuintes-v2.json</code></a> |
| Consulta de NF-e v2 | <a href="/docs/api/consulta-nf.yaml"><code>/docs/api/consulta-nf.yaml</code></a> |
| Consulta de CNPJ v1 | <a href="/docs/api/consulta-cnpj.yaml"><code>/docs/api/consulta-cnpj.yaml</code></a> |
| Consulta de CPF v1 | <a href="/docs/api/cpf-api.yaml"><code>/docs/api/cpf-api.yaml</code></a> |
| Consulta de Endereços v1 | <a href="/docs/api/consulta-endereco.yaml"><code>/docs/api/consulta-endereco.yaml</code></a> |
| Consulta de CT-e v2 | <a href="/docs/api/consulta-cte-v2.yaml"><code>/docs/api/consulta-cte-v2.yaml</code></a> |
| Consulta NF-e Distribuição v1 | <a href="/docs/api/consulta-nfe-distribuicao-v1.yaml"><code>/docs/api/consulta-nfe-distribuicao-v1.yaml</code></a> |
| Consulta DFe Distribuição v2 | <a href="/docs/api/consulta-dfe-distribuicao-v2.yaml"><code>/docs/api/consulta-dfe-distribuicao-v2.yaml</code></a> |

## Áreas excluídas do fluxo Markdown

Duas áreas da documentação **não** participam do fluxo Markdown — só HTML — porque sua versão `.md` não agregaria valor real para um agente:

- **APIs REST (`/docs/desenvolvedores/rest-api/...`)** — as páginas são geradas a partir das especificações OpenAPI e usam intensivamente componentes MDX (Tabs de exemplos, Schemas, Responses) que não traduzem bem para Markdown puro. Use diretamente os arquivos OpenAPI listados acima para consumir essas APIs de forma programática.
- **Prefeituras integradas (`/docs/prefeituras-integradas/...`)** — conteúdo sem informação técnica acionável para um agente.

Essas páginas continuam acessíveis em HTML normalmente e podem ser citadas como fonte, mas não aparecem nos manifestos `llms.txt` nem têm `index.md` gerado.

## Boas práticas para agentes

- **Use o `source_url` do frontmatter** ao citar fontes — é a URL canônica e estável da página HTML.
- **Cheque o `last_updated`** antes de confiar em conteúdo sobre legislação ou reforma tributária: a regulamentação muda com frequência.
- **Para fluxos longos**, prefira o `llms-full.txt` do produto específico ao invés do site-wide — economiza tokens e mantém o foco no que importa.
- **Para chamadas de API**, prefira as especificações OpenAPI em `/docs/api/` ao invés de raspar páginas HTML; assim você obtém schemas e exemplos estruturados.

---

## Conceitos - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/certificado-digital/conceitos/index.md

# Tudo sobre Certificado Digital

O [Certificado Digital][7] é a identificação virtual de uma empresa. Assim como o CPF e RG representam a identidade de uma [pessoa física][8], para [Certificado Digital][7], o arquivo é representado pelo e-CNPJ (CNPJ eletrônico).  
[pessoa jurídica][9] obter o documento. Neste caso, o certificado digital adquirido é o e-CPF (CPF eletrônico).

## Tipos de Certificado Digital

Para emissão de notas através da nossa API, você precisará do certificado A1\. Existem 4 tipos de Certifidado Digital:

* A1: certificado digital em forma de arquivo guardado no computador;
* A3: certificado digital em forma de cartão ou token criptográfico;
* S3: certificado digital de sigilo e confidencialidade;
* T3: certificado tipo “T”, chamado de Carimbo do Tempo, atesta temporalidade, como um evento ocorrido dentro de determinado prazo;

Os certificados mais comuns são do tipo A1 e A3\. O primeiro deverá ser baixado pelo cliente para usar o documento pelo computador, já o certificado do tipo A3 será entregue em cartão ou token pela autoridade reguladora.

**Importante**: Se você se pergunta se o certificado digital é pago, a resposta é Sim.

Para adquirir qualquer modelo junto a uma autoridade certificadora, o interessado deverá optar por uma plano de pagamento apresentado pela empresa.

Cada uma oferece um valor diferente. Pesquise e encontre o modelo mais adequado à sua empresa ou pessoa física.

Vale lembrar que empresários, autônomos e pessoas físicas de diversos setores podem pedir o certificado digital para emitir nota fiscal eletrônica e outros fins.

## Vantagens do Certificado Digital

Muitas empresas focam na obtenção do Certificado Digital para emitir nota fiscal, mas o arquivo vai além desta tarefa.

Ele também agiliza e serve para autenticar atividades operacionais, financeiras e administrativas, de uma empresa.

Para quem usa o arquivo, há vantagens nítidas como, por exemplo, a apresentação do arquivo para realizar depósitos, fazer operações bancárias e assinar contratos.

Confira a lista de benefícios com a obtenção do certificado digital:

* Aplicações no comércio eletrônico;
* Assinatura de contratos digitais;
* Realizar operações bancárias;
* Assinar notas fiscais;
* Acessar o sistema de notas fiscais pela internet.

## Obrigatoriedade do Certificado Digital

As empresas que desejam emitir notas fiscais via serviços da web são obrigadas a ter um certificado digital. Além do certificado ser usado no envio de notas ficais eletrônicas, exitem outras ocasiões em que ele também é necessário.

### Certificado Digital e NF-e

O Certificado Digital é utilizado para dar validade jurídica às Notas Fiscais Eletrônicas, garantindo a autenticidade e integridade do documento que será emitido. Ter o certificado digital para emissão de nota fiscal eletrônica proporciona agilidade em tarefas como o envio e despacho de mercadorias, reduzindo custos.

## Como adquirir um Certificado Digital para emitir nota fiscal eletrônica?

O Certificado Digital usado na emissão de nota fiscal eletrônica é do tipo **A1**, e deve ser adquirido através de empresas chamadas de Autoridades Certificadoras – AC.

Toda AC é credenciada junto ao Instituto Nacional de Tecnologia da Informação – ITI e tem como função ser uma terceira parte confiável, gerando e assinando documentos eletrônicos para garantir a autenticidade desses documentos junto ao governo.

Vamos ao passo a passo de como solicitar seu e-CNPJ A1 para emissão de notas fiscais eletrônicas:

1. [Escolha uma Autoridade Certificadora - AC;][7]

> [Clicando aqui][10] você pode obter seu Certificado e-CNPJ A1 com desconto.

1. Solicite no site da AC escolhida a emissão do seu certificado digital.
2. Agende o dia e horário de comparecimento na Autoridade de Registro – AR indicada pelo site da Autoridade Certificadora.
3. Vá até a AR no dia e horário agendado. Nesta etapa o solicitante, além de levar os documentos obrigatórios, passará pelo processo de cadastramento biométrico, com a coleta da biografia facial (foto) e das digitais.
4. Após a verificação de todos os documentos e confirmação da identidade do solicitante na AR, o certificado já estará pronto e a AC notificará o cliente sobre os procedimentos para baixar o certificado.

[1]: #Tudo%5Fsobre%5FCertificado%5FDigital
[2]: #Tipos%5Fde%5FCertificado%5FDigital
[3]: #Vantagens%5Fdo%5FCertificado%5FDigital
[4]: #Obrigatoriedade%5Fdo%5FCertificado%5FDigital
[5]: #Certificado%5FDigital%5Fe%5FNF-e
[6]: #Como%5Fadquirir%5Fum%5FCertificado%5FDigital%5Fpara%5Femitir%5Fnota%5Ffiscal%5Feletronica
[7]: https://www.gov.br/iti/pt-br
[8]: https://nfe.io/docs/conceitos/pessoa-fisica/
[9]: https://nfe.io/docs/conceitos/pessoa-juridica/
[10]: https://p.nfe.io/pt-br/certificado-digital-20off

---

## Guia para exportar seu certificado digital no Mac OS - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/certificado-digital/guia-para-exportar-certificado-mac-os/index.md

# Guia definitivo para exportar seu certificado digital no Mac OS

O certificado digital e-CNPJ ou NF-e A1 é um arquivo utilizado para autenticação online e para estabelecer conexão com sistemas do Governo.

Ele funciona como senha para autorizar determinadas ações de uma empresa, com validade jurídica, é mais seguro.

Existem alguns tipos de certificado digitais, porém o mais comum é o certificado digital do tipo A1, ele é um arquivo digital válido por um ano.

Caso você ainda não tenha o seu certificado digital e-CNPJ ou NF-e do tipo A1, [saiba como você pode comprar qualquer tipo de certificado digital com desconto de 20%.][8]

Caso você já tenha comprado e instalado o seu certificado, você precisa fazer um backup dele em arquivo para que você possa transferir para um outro computador, ou colocá-lo em um lugar seguro, por exemplo.

## Ao final desse tutorial, você será capaz de:

* [Exportar um Certificado Digital do tipo A1 usando o Mac OS][9]

## Requisitos

* [Ter comprado e instalado no computador um Certificado Digital do tipo A1][10]

## Guia de Exportação do Certificado Digital A1

Segue nosso guia simples e rápido de como exportar seu certificado digital do Tipo A1 na sua máquina.

## Passo a passo no formato de video

## Passo a passo no formato de texto

1. Abra o “Finder” no seu MAC;
2. Acesse a pasta Application" em seguida;
3. Acesse a pasta "Utilities";
4. Abra o "Access Keys";
5. Clique em "Login";
6. Clique em "Meus certificados";
7. Selecione o certificado que deseja exportar;
8. Sobre o certificado A1 pressione a tecla "control" e clique sobre o certificado a ser exportado;
9. Selecione a opção export "nome do certificado";
10. Nomeie o arquivo e indique o local para exportação;
11. Ao clicar em "Save", será solicitado uma senha para o certificado e em seguida a senha do computador;
12. Após a exportação, confira o arquivo no local indicado.

## Próximos passos

* [Fazer upload do certificado digital][11]
* [Emitir uma nota fiscal de serviço][12]
* [Nossos segmentos][13]
* [Sobre a NFE.io][14]
* [Junte-se ao nosso time][15]

[1]: #Guia%5Fdefinitivo%5Fpara%5Fexportar%5Fseu%5Fcertificado%5Fdigital%5Fno%5FMac%5FOS
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Requisitos
[4]: #Guia%5Fde%5FExportacao%5Fdo%5FCertificado%5FDigital%5FA1
[5]: #Passo%5Fa%5Fpasso%5Fno%5Fformato%5Fde%5Fvideo
[6]: #Passo%5Fa%5Fpasso%5Fno%5Fformato%5Fde%5Ftexto
[7]: #Proximos%5Fpassos
[8]: https://p.nfe.io/pt-br/certificado-digital-20off
[9]: https://nfe.io/docs/documentacao/certificado-digital/guia-para-exportar-certificado-mac-os/#Guia%5Fde%5FExportacao%5Fdo%5FCertificado%5FDigital%5FA1
[10]: https://nfe.io/docs/documentacao/certificado-digital/conceitos/
[11]: https://nfe.io/docs/nossa-plataforma/upload-certificado/
[12]: https://nfe.io/docs/nossa-plataforma/nota-fiscal-servico/emitir-nota-servico/
[13]: https://nfe.io/segmentos/
[14]: https://nfe.io/sobre/
[15]: https://nfe.io/carreira/

---

## Guia para exportar seu certificado digital no Windows - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/certificado-digital/guia-para-exportar-certificado-windows/index.md

# Guia definitivo para exportar seu certificado digital no Windows

O certificado digital e-CNPJ ou NF-e A1 é um arquivo utilizado para autenticação online e para estabelecer conexão com sistemas do Governo.

Ele funciona como senha para autorizar determinadas ações de uma empresa, com validade jurídica, é mais seguro.

Existem alguns tipos de certificado digitais, porém o mais comum é o certificado digital do tipo A1, ele é um arquivo digital válido por um ano.

Caso você ainda não tenha o seu certificado digital e-CNPJ ou NF-e do tipo A1, [saiba como você pode comprar qualquer tipo de certificado digital com desconto de 20%.][8]

Caso você já tenha comprado e instalado o seu certificado, você precisa fazer um backup dele em arquivo para que você possa transferir para um outro computador, ou colocá-lo em um lugar seguro, por exemplo.

## Ao final desse tutorial, você será capaz de:

* [Exportar um Certificado Digital do tipo A1 usando o Windows][9]

## Requisitos

* [Ter comprado e instalado no computador um Certificado Digital do tipo A1][10]

## Guia de Exportação do Certificado Digital A1

Segue nosso guia simples e rápido de como exportar seu certificado digital do Tipo A1 na sua máquina.

> **Observação:** Esse exemplo é utilizando o Windows 10, porém deve funcionar normalmente em outros sistemas operacionais.

## Passo a passo no formato de video

## Passo a passo no formato de texto

1. Abra o “Painel de Controle” no seu Windows.
2. Pesquise por “Certificado” e depois selecione a opção “Gerenciar Certificados de Usuário”.
3. Nesse gerenciador haverão várias pastas, você tem que buscar e abrir a pasta “Pessoal”, em seguida a pasta “Certificados”.
4. Na lista de certificados localize o seu, em seguida clique com o botão direito do mouse em cima dele e depois vá na opção do menu “Todas as Tarefas” e em seguida clique na última opção “Exportar”.
5. Assim você verá a janela do “Assistente para Exportação de Certificados”, nessa primeira etapa basta clicar em “Avançar” no final da primeira página.
6. Na próxima etapa você vai selecionar a opção “Sim, exportar a chave privada” e depois avançar novamente.
7. Na próxima tela você precisa marcar as opções abaixo como selecionadas, depois clique em avançar  
   * “Incluir todos os certificados no caminho de certificação, se possível”  
   * “Exportar todas as propriedades estendidas”  
   * “Habilitar privacidade de certificados”
8. Nessa tela você precisa selecionar a opção “Senha” e depois digitar a senha para manter a segurança do certificado digital que será exportado, depois clique em “Avançar”.
9. Nesta tela você vai escolher o nome do arquivo e onde deseja que ele seja salvo, para isso clique no botão “Procurar“ e escolha a pasta de destino e o nome do arquivo, nossa sugestão é deixar o nome do arquivo assim “Certificado-Digital-A1”, ao final clique no botão “Avançar”.
10. Na tela de conclusão pode verificar onde será salvo o arquivo e os detalhes do que você escolheu durante o processo, depois de revisar é só clicar em “Concluir” e você terá exportado o arquivo
11. Ao final valide se o arquivo realmente foi salvo e você já poderá copiar ele para um local seguro afinal ele é um backup do seu certificado digital.

## Próximos passos

[Fazer upload do certificado digital][11]  
[Emitir uma nota fiscal de serviço][12]


[1]: #Guia%5Fdefinitivo%5Fpara%5Fexportar%5Fseu%5Fcertificado%5Fdigital%5Fno%5FWindows
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Requisitos
[4]: #Guia%5Fde%5FExportacao%5Fdo%5FCertificado%5FDigital%5FA1
[5]: #Passo%5Fa%5Fpasso%5Fno%5Fformato%5Fde%5Fvideo
[6]: #Passo%5Fa%5Fpasso%5Fno%5Fformato%5Fde%5Ftexto
[7]: #Proximos%5Fpassos
[8]: https://p.nfe.io/pt-br/certificado-digital-20off
[9]: https://nfe.io/docs/documentacao/certificado-digital/guia-para-exportar-certificado-windows/#Guia%5Fde%5FExportacao%5Fdo%5FCertificado%5FDigital%5FA1
[10]: https://nfe.io/docs/certificado-digital/conceitos/
[11]: https://nfe.io/docs/nossa-plataforma/upload-certificado/
[12]: https://nfe.io/docs/nossa-plataforma/nota-fiscal-servico/emitir-nota-servico/

---

## Introdução à documentação das API's

Source: https://nfe.io/docs/documentacao/conceitos/introducao/index.md

# Introdução

Seja bem vindo à nossa documentação. Criamos este conteúdo para que você consiga aprender tudo o que é necessário para utilizar qualquer uma de nossas API’s.

Nossa ideia com essa seção de nosso site é oferecer algo dinâmico. Por isso, se tiver sugestões, entre em contato conosco pelo: [suporte@nfe.io][11].

A partir de agora, apresentaremos conceitos básicos sobre Notas Fiscais, CPF, CNPJ, entre outros. Por meio desses conceitos você poderá decidir qual das nossas API’s se encaixa com o seu negócio.

## O que é uma API?

API é uma sigla em inglês para **Aplication Program Interface**, que traduzido seria “Interface de Programação de Aplicações”. Mas o que isso significa?

Basicamente, API é um conjunto de padrões de programação estabelecidos por um software para a utilização das suas funcionalidades por outros aplicativos que pretendem usar seus serviços. Com isso, torna-se possível que dois aplicativos conversem entre si.

Um exemplo muito comum é a integração de e-commerce com meios de pagamento (PagSeguro, por exemplo). Você já deve ter efetuado uma compra em um site e no momento da compra ser direcionado para um ambiente diferente para deixar os dados do cartão de crédito, por exemplo, e efetuar seu pagamento. Essa integração entre o site que vendeu o produto e a plataforma onde ocorreu o pagamento funcona através de API´s.

Nossas API’s foram criadas utilizando o padrão REST, o que possibilita a integração de seu sistema ao nosso.

## Conheça nossas APIs

### Consultar dados de Pessoa Jurídica

Nessa consulta nossa API retornará os dados de uma Pessoas Jurídica através de um CNPJ, [confira os dados que a gente pega][12]. Possuímos diversas fontes de busca para puxar os dados e retorná-los de maneira bem organizada, acesse nossa documentação para conhecer melhor.

### Consultar dados de Pessoa Física

Essa API retornará os [dados de uma Pessoa Física][13] a partir de um CPF. Assim você pode ter acesso a situação cadastral de uma pessoa física, [clique aqui][13] para acessar nossa documentação.

### Consultar dados de endereços

Nossa API de endereços retornará os dados de endereço a partir de um CEP. Nós também disponibilizamos outras formas de fazer essa consulta, [clique aqui][14] para acessar nossa documentação.

### Consultar de Notas Fiscais Eletrônicas (NF-e)

Nessa consulta nossa API retorna os [dados de uma NF-e][15] (em diferentes formatos de arquivos) a partir da chave de acesso da nota. Conheça a [documentação da API][16].

### Emissão Automática de Nota Fiscal de Serviço (NFS-e)

Com a nossa API é possivel emitir notas fiscais de serviço de forma automatizada. Além do calculo automático de impostos, nosso sistema possui diversas funcionalidades como, envio automático de email com a nota emitida para o seu cliente, cancelamento de notas, consulta de pdf ou xml, dentre outros. [Clique aqui][17] e confira nossa documentação.

Nós possuímos integração com as principais plataformas de pagamento, caso tenha interesse clique aqui e veja qual a melhor solução para você. Além disso, é possível integrar nossa API com outros sistemas através de plugins, [clique aqui][18] e saiba mais sobre nossos plugins.

### Emissão Automática de Nota Fiscal de Produtos (NF-e)

Temos também uma API para emitir NFe de Produtos, que nesse momento está em BETA e estamos disponibilizando nossa API para quem deseja integrar em seu sistema. Como ela está em BETA, o uso dela é sem custos, por tempo indeterminado, e quem tem interesse em desenvolver uma integração pode começar agora, olhando [nossa documentação][19].

### Contato

Possui alguma dúvida ou sugestão? Entre contato conosco através do email [suporte@nfe.io][11]., ou por telefone (11) 4063-8091 se preferir. Estaremos a disposição para melhor atendê-lo.


[1]: #Introducao
[2]: #O%5Fque%5Fe%5Fuma%5FAPI
[3]: #Conheca%5Fnossas%5FAPIs
[4]: #Consultar%5Fdados%5Fde%5FPessoa%5FJuridica
[5]: #Consultar%5Fdados%5Fde%5FPessoa%5FFisica
[6]: #Consultar%5Fdados%5Fde%5Fenderecos
[7]: #Consultar%5Fde%5FNotas%5FFiscais%5FEletronicas%5FNF-e
[8]: #Emissao%5FAutomatica%5Fde%5FNota%5FFiscal%5Fde%5FServico%5FNFS-e
[9]: #Emissao%5FAutomatica%5Fde%5FNota%5FFiscal%5Fde%5FProdutos%5FNF-e
[10]: #Contato
[11]: mailto:suporte@nfe.io
[12]: https://nfe.io/docs/documentacao/consultas/pessoa-juridica/
[13]: https://nfe.io/docs/documentacao/consultas/pessoa-fisica/
[14]: https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-enderecos-v1/
[15]: https://nfe.io/docs/documentacao/consultas/notas-fiscais/
[16]: https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-nota-fiscal/v2/
[17]: https://nfe.io/docs/documentacao/conceitos/notas-fiscais/
[18]: https://nfe.io/docs/integracoes/
[19]: https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-produto-v2/

---

## Notas Fiscais

Source: https://nfe.io/docs/documentacao/conceitos/notas-fiscais/index.md

# Tudo sobre Nota Fiscal Eletrônica

Você deseja automatizar o seu processo de emissão de notas fiscais? Pode contar com a gente! Através das nossas API's você pode emitir suas notas online e automaticamente sem preocupação.

Abaixo estão os tipos de notas ficais existentes. Atualmente nós disponibilizamos comercialmente API para emissão de NFS-e. As APIs de NF-e e NFC-e estão em versão beta para testes, podendo ser integradas por quem estiver disposto a testar.

Veja nossas [referências das API´s.][7]

## Nota Fiscal Eletrônica (NF-e)

A Nota Fiscal Eletrônica (NF-e) é um documento de existência apenas digital, emitido e armazenado eletronicamente, com o intuito de documentar, para fins fiscais, uma operação de circulação de mercadorias ocorrida entre as partes.

Normalmente quando compramos um produto numa loja online é comum recebermos no email cadastrado na loja, um arquivo no formato XML, esse arquivo é a NF-e. Além disso, recebemos com a encomenda uma representação da nota fiscal eletrônica, esse arquivo é o DANFE(Documento Auxiliar da Nota Fiscal Eletrônica) que é necessário para que a mercadoria possa ser legalmente transportada.

Quer saber mais sobre Nota Fiscal Eletrônica? [Clique aqui][8].

## Nota Fiscal de Serviço (NFS-e)

A NFS-e é a versão da Nota Fiscal eletrônica que cumpre a **função de documentar uma prestação de serviço** ocorrido entre as partes. Caso você compre um curso online, por exemplo, a empresa que vendeu o curso deve emitir uma NFS-e e te enviar.

O objetivo desse documento é justamente facilitar a comunicação entre os prestadores de serviço e a prefeitura, para que seja possível ter um controle maior sobre as suas responsabilidades fiscais.

A responsabilidade sobre a NFS-e é municipal, sendo assim, cabe às prefeituras fazer a implantação e a fiscalização das emissões realizadas em sua área de coordenação.

Quer saber mais sobre Nota Fiscal de Serviço? [Clique aqui][9].

## Nota Fiscal do Consumidor (NFC-e)

A **Nota Fiscal do Consumidor (NFC-e)** surgiu com o intuito de documentar as operações comerciais de venda presencial ou venda para entrega em domicílio a consumidor final (pessoa física ou jurídica) em operação interna e sem geração de crédito de ICMS ao adquirente.

Essa nota é a mais comum no nosso dia a dia (normalmente nos referimos à NFC-e como Cupom Fiscal), ela está presente nos comércios e sempre recebemos quando fazemos compras no supermercado, por exemplo. Esse papel impresso contém a chave de acesso e o famoso QR Code para que o consumidor final consulte a validade do cupom fiscal.

## O que é um XML da nota fiscal?

Quando algum bem ou serviço é adquirido, o cliente recebe uma nota fiscal em formato XML. Esse arquivo XML é a versão digital da nota fiscal eletrônica e cumpre o papel de comprovar a propriedade sobre o bem ou serviço. É por meio dele que o governo pode verificar os detalhes sobre as transações realizadas.

## Data de emissão X Data de competência

A data de emissão refere-se ao dia e hora exatos em que a nota fiscal foi enviada à prefeitura, não podendo ser alterada.

A data de competência refere-se ao dia em que o serviço foi efetivamente prestado. Assim, é possivel emitir uma nota fiscal com uma data anterior a data em que realmente está sendo emitida.


[1]: #Tudo%5Fsobre%5FNota%5FFiscal%5FEletronica
[2]: #Nota%5FFiscal%5FEletronica%5FNF-e
[3]: #Nota%5FFiscal%5Fde%5FServico%5FNFS-e
[4]: #Nota%5FFiscal%5Fdo%5FConsumidor%5FNFC-e
[5]: #O%5Fque%5Fe%5Fum%5FXML%5Fda%5Fnota%5Ffiscal
[6]: #Data%5Fde%5Femissao%5FX%5FData%5Fde%5Fcompetencia
[7]: https://nfe.io/docs/desenvolvedores/
[8]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/conceitos/
[9]: https://nfe.io/docs/documentacao/conceitos/notas-fiscais/#Nota%5FFiscal%5Fde%5FServico%5FNFS-e

---

## Pessoa Física - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/conceitos/pessoa-fisica/index.md

# Tudo sobre Pessoa Física

Quer consultar dados sobre Pessoas Física? Nós temos um serviço para esse tipo de consulta. Clique aqui e confira mais informações sobre nossa API.

## O que é uma Pessoa Física?

A designação pessoa física é um conceito jurídico e se refere especificamente ao indivíduo enquanto sujeito detentor de direitos e de deveres. Para ser considerado uma pessoa física, porém, não é preciso ter um CPF.

## O que é um CPF?

O CPF é um documento de identificação emitido pela Receita Federal Brasileira que serve para comprovar que a pessoa contribui com a Receita Federal ou é dependente de alguém que contribui.

Ele contém um número identificador de 11 dígitos que não mudam mesmo em caso de necessidade de uma nova via. Não é obrigatório o porte do cartão, porém o número do CPF é exigido em diversas situações, principalmente em operações financeiras, como abertura de contas em banco

## Obrigatoriedade de inscrição

Qualquer pessoa pode se inscrever no Cadastro de Pessoa Física, mesmo que não seja obrigada. Veja abaixo para quais perfis de pessoa física a inscrição no CPF é obrigatória:

* Pessoas com mais de 18 anos que constarem como dependentes em Declaração de Ajuste Anual do Imposto de Renda e Pessoa Física (DIRPF).
* Inventariantes, cônjuges ou conviventes, sucessores a qualquer título ou representantes que tenham a obrigação de apresentar a DIRPF em nome do espólio ou do contribuinte falecido.
* Pessoas cujos rendimentos estejam sujeitos à retenção do imposto de renda na fonte, ou que estejam obrigadas ao pagamento desse imposto.
* Profissionais liberais, assim entendidos aqueles que exerçam, sem vínculo empregatício, atividades que os sujeitem a registro em órgão de fiscalização profissional.
* Locadoras de bens imóveis.
* Participantes de operações imobiliárias.
* Pessoas obrigadas a reter imposto de renda na fonte.
* Titulares de contas bancárias, de contas de poupança ou de aplicações financeiras.
* Que operam em bolsas de valores, de mercadorias, de futuros e assemelhadas.
* Inscritas como contribuintes individuais ou requerentes de benefícios de qualquer espécie junto ao Instituto Nacional do Seguro Social (INSS).
* Residentes no exterior que possuam no Brasil bens e direitos sujeitos a registro público, incluindo imóveis, veículos, embarcações, aeronaves, participações societárias, contas bancárias e aplicações no mercado financeiro ou no mercado de capitais.
* Pessoas que solicitarem Carteira de Trabalho e Previdência Social (CTPS).  
Situações cadastrais  
A situação cadastral CPF é responsável por informar se você possui ou não algum tipo de pendência com a Receita Federal, referente ao cadastro apenas, não à situação fiscal. O CPF poderá assumir os seguintes tipos de

## Situações Cadastrais:

* ### Regular  
Essa situação atesta que não existe nenhuma pendência no seu CPF. Mas mesmo que a situação cadastral do contribuinte constar como "Regular", não significa que o CPF esteja com regularidade fiscal, ou seja, é possível estar com a situação cadastral regular mesmo com débitos perante a receita.
* ### Pendente de regularização  
A Situação Pendente de Regularização significa que o portador do CPF não apresentou alguma declaração de Imposto de Renda da Pessoa Física (IRPF), da qual havia a exigência de entrega em pelo menos um dos últimos cinco anos.
* ### Suspensa  
A suspensão do CPF ocorre quando ele está com problema de cadastro ou com problemas perante a Justiça Eleitoral. O portador não poderá abrir conta em bancos ou participar de concursos, por exemplo, até regularizar a situação.
* ### Cancelada  
O cancelamento do CPF do contribuinte só poderá ser realizado em caso de falecimento do contribuinte ou por decisões administrativas, como duplicidade de cadastro ou por determinação judicial.
* ### Nula  
A situação nula indica que foi constatada fraude e a Receita Federal anulou o CPF. Isso pode ocorrer quando um contribuinte que não existe é cadastrado, para que o documento falso seja utilizado para usufruir ilegalmente de benefícios.

[1]: #Tudo%5Fsobre%5FPessoa%5FFisica
[2]: #O%5Fque%5Fe%5Fuma%5FPessoa%5FFisica
[3]: #O%5Fque%5Fe%5Fum%5FCPF
[4]: #Obrigatoriedade%5Fde%5Finscricao
[5]: #Situacoes%5FCadastrais
[6]: #Regular
[7]: #Pendente%5Fde%5Fregularizacao
[8]: #Suspensa
[9]: #Cancelada
[10]: #Nula

---

## Pessoa Jurídica - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/conceitos/pessoa-juridica/index.md

# Tudo sobre Pessoa Jurídica

Quer consultar informações sobre Pessoas Jurídicas? Nós temos um serviço para esse tipo de consulta. Clique aqui e confira mais informações sobre nossa API.

## O que é uma Pessoa Jurídica?

Pessoa jurídica é um individuo reconhecido pelo Estado que possui direitos e deveres. A pessoa jurídica, deve ser constituída por outros indivíduos, sejam pessoas físicas ou jurídicas.

Em resumo, uma pessoa jurídica pode ser usada para definir: empresas, governos, fundações, organizações ou qualquer grupo criado com finalidades específicas.

Mesmo com a presença de responsáveis pela entidade, sejam uma ou mais pessoas físicas, a pessoa jurídica tem personalidade jurídica independente e separada dos seus membros.

Por isso, podemos dizer que a pessoa jurídica representa uma entidade própria que responde por seus atos diante do Governo e Justiça, ou seja, pessoas jurídicas não podem ser confundida com pessoas físicas ou seus membros.

## O que é um CNPJ?

O Cadastro Nacional de Pessoa Jurídica (CNPJ) é um registro que identifica uma empresa na Receita Federal e que toda empresa precisa ter antes de iniciar suas atividades. Nele, constam dados como: razão social, data de abertura da empresa, nome fantasia (se houver), descrição das atividades econômicas, natureza jurídica, endereço e contato. O número do CNPJ contém 14 dígitos no seguinte formato: XX.XXX.XXX/YYYY-ZZ.

O número de registro no CNPJ é a “identidade” da empresa. Ele serve para comprovar sua existência e situação legal em qualquer atividade para o governo, clientes, parceiros e fornecedores.

## Quais os tipos de pessoa jurídica?

De acordo com o Código Civil, existem diferentes tipos de constituição de pessoas jurídicas variando também as leis que devem seguir.

### Pessoa jurídica de direito público interno

São criadas na maior parte dos casos por força da lei, sendo essas entidades que representam juridicamente o Estado na forma de União, Estados, Municípios, além de autarquias e de todos os outros órgãos de administração pública.

### Pessoa jurídica de direito público externo

Essas entidades representam Estados fora do Brasil e organizações internacionais, por exemplo: Fundo Monetário Internacional (FMI), Organização das Nações Unidas (ONU) e Federação Internacional de Futebol (FIFA). Essas pessoas jurídicas respondem pelas normas do direito internacional, que são reconhecidas pela legislação interna brasileira.

### Pessoa jurídica de direito privado

Essas entidades nascem de um processo administrativo, perante ao Estado. Este ato jurídico é chamado de constituição. É a partir da constituição da pessoa jurídica por seus membros, sejam eles pessoas físicas ou outras pessoas jurídicas, que nascem esse tipos de pessoa jurídica.

Esse processo de constituição deve ser elaborado entre os membros e depois registrado formalmente nos órgãos competentes para que sejam reconhecidas perante ao Estado e Sociedade. Alguns registros necessários nesse trâmite são: Cadastro Nacional de Pessoa Jurídica (CNPJ), através da Receita Federal; a inscrição na Junta Comercial do Estado (NIRE); a Inscrição no Município e, quando necessário, a Inscrição no Estadual, através da SEFAZ.


[1]: #Tudo%5Fsobre%5FPessoa%5FJuridica
[2]: #O%5Fque%5Fe%5Fuma%5FPessoa%5FJuridica
[3]: #O%5Fque%5Fe%5Fum%5FCNPJ
[4]: #Quais%5Fos%5Ftipos%5Fde%5Fpessoa%5Fjuridica
[5]: #Pessoa%5Fjuridica%5Fde%5Fdireito%5Fpublico%5Finterno
[6]: #Pessoa%5Fjuridica%5Fde%5Fdireito%5Fpublico%5Fexterno
[7]: #Pessoa%5Fjuridica%5Fde%5Fdireito%5Fprivado

---

## Webhook

Source: https://nfe.io/docs/documentacao/conceitos/webhook/index.md

# Webhook

O webhook foi criado para facilitar a troca de informações entre diferentes sistemas, funcionando de maneira passiva, através de eventos.

Ele tem como função principal transmitir informações sobre algum fato ocorrido de um sistema para o outro. É, basicamente, ligar dois sistemas a partir de algum evento. Para entendermos melhor o que é um webhook, vamos a um exemplo simples:

Você quer comprar um jogo para seu videogame, entra em um site e o produto está esgotado, mas no site há um aviso de que em breve o produto estará em estoque e eles perguntam se você quer receber uma notificação quando o produto chegar.

Se você quiser o jogo, vai inserir seu e-mail e receber a notificação sobre a chegada do jogo. Essa notificação por e-mail faz a ponte entre você (sistema 1) e a loja (sistema 2). Essa é a função do webhook.

### Como funciona um Webhook?

Conforme exemplificado, para criar um webhook, você só precisa criar a "ponte" entre os sistemas, para que, quando determinado evento aconteça, a troca de informações ocorra instantaneamente, sem que você precise executar rotinas de chamadas para saber se houve alguma ocorrência no sistema.

Quando há uma ocorrência, a aplicação origem enviará as informações via requisição HTTP para uma URL, anteriormente configurada no webhook, transmitindo as informações da ocorrência, fazendo com que, ferramentas de comunicação ou sistemas recebam essa informação de maneira rápida e eficiente.

### Webhook x API

Embora parecidos, o webhook trabalha de forma diferente de uma API. Enquanto uma API fornece dados quando você solicita (via requisição HTTPs), havendo uma integração direta, o webhook trabalha de forma autônoma e lhe envia as informações sem que você precise executar uma requisição HTTP, sendo assim, uma integração passiva.

### Saiba mais:

[WebHook na NFE.io][5]  
[Cadastrar um webhook][6]


[1]: #Webhook
[2]: #Como%5Ffunciona%5Fum%5FWebhook
[3]: #Webhook%5Fx%5FAPI
[4]: #Saiba%5Fmais
[5]: https://nfe.io/docs/documentacao/webhooks/conceitos/
[6]: https://nfe.io/docs/documentacao/webhooks/integracao/

---

## Endereços - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/consultas/enderecos/index.md

# Consulta de Endereços

Com o nosso serviço você pode realizar consultas de dados e endereços utilizando o número do CEP. Confira abaixo quais métodos de consultas disponibilizamos e como utilizar nosso serviço.

> Para utilizar nossa API de consulta de Nota Fiscal Eletônica, acesse nosso [ambiente de testes][4]. Você deverá possuir uma conta em [nossa plataforma][5] para a utilização de sua [chave de acesso da API.][6]

## Quais dados nossa API retorna?

Nossa API possui os seguintes métodos de consultas:

* **CEP**: utilize este método para consultar os dados de um Endereço através do Código de Endereçamento Postal (CEP);
* **Campos**: Utilize este método para consultar os dados de um Endereço através de um filtro genérico de pesquisa.
* **Termo genérico**: Utilize este método para consultar os dados de um Endereço através de um termo genérico de pesquisa.

As consultas são feitas através da base de dados do Diretório Nacional de Endereço (DNE) dos Correios, unificando com os dados de Cidades do IBGE. Saiba mais [nesse link][7].

## Como faço para ter acesso à documentação da API?

[Clique aqui][4] para acessar a documentação da API de consulta de Endereços e, caso possua alguma dúvida ou sugestão de melhoria, sinta-se à vontade para [entrar em contato conosco][8], e nossa equipe estará disponível para ajudá-lo(a)!


[1]: #Consulta%5Fde%5FEnderecos
[2]: #Quais%5Fdados%5Fnossa%5FAPI%5Fretorna
[3]: #Como%5Ffaco%5Fpara%5Fter%5Facesso%5Fa%5Fdocumentacao%5Fda%5FAPI
[4]: /desenvolvedores/rest-api/consulta-de-enderecos-v1/consulta-de-endereco
[5]: /documentacao/nossa-plataforma/criar-conta
[6]: /documentacao/nossa-plataforma/chaves-de-autenticacao
[7]: https://www.correios.com.br/acl%5Fusers/credentials%5Fcookie%5Fauth/require%5Flogin?came%5Ffrom=https%3A//www.correios.com.br/a-a-z/dne
[8]: https://nfe.io/#contato

---

## Introdução à consulta de CNPJ com a NFE.io - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/consultas/introducao-a-consulta-de-cnpj-com-anfe-io/index.md

# Introdução à consulta de CNPJ com a NFE.io

> Nesse artigo vamos introduzir como é feita a consulta de CPF via API da NFE.io

A consulta de CNPJ tem como base a busca dos dados do cartão CNPJ de empresas que estão disponíveis no site da Receita Federal. Os dados que a API retorna são as informações encontradas a partir da consulta feita na seguinte url: 

[][5][https://servicos.receita.fazenda.gov.br/servicos/cnpjreva/cnpjreva\_solicitacao.asp][5] 

Ao acessar a url acima, você é direcionado para a página mostrada abaixo. Nessa imagem, é possível observar que, a partir da informação de um CNPJ, são retornados os dados cadastrais da informação usada na consulta.

> ![](https://nfe.io/docs/static/docs/consultas/consulta-cnpj.png)**Figura 1\. Imagem de exemplo da página de consulta do cartão CNPJ**

Abaixo segue um exemplo do cartão CNPJ de uma consulta feita.

> ![](https://nfe.io/docs/static/docs/consultas/Cartao-CNPJ.png)**Figura 2\. Cartão CNPJ econtrado na busca**

### **1\. Base para a consulta de CNPJ**

Para poder se consultar os dados cadastrais do cartão CNPJ a partir da API da NFE.io é necessário informar o CNPJ da empresa a ser consultada. É possível encontrar mais informações sobre a API na documentação da NFE.io na seguinte url:

[][6][https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-cnpj-v1/][6] 

A versão recomendada e atual é a **V2**, cuja URL está abaixo.

| Método | URL                                                                                 |
| ------ | ----------------------------------------------------------------------------------- |
| GET    | [https://legalentity.api.nfe.io/v2/legalentities/basicInfo/\{federalTaxNumber][8]\} |

O CNPJ a ser informado deve estar no mesmo campo da informação _federalTaxNumber_. O número deve ser informado sem barras traços e pontos.

> **Versão V1 (legada):** a V1 (`https://legalentity.api.nfe.io/v1/legalentities/basicInfo/{federalTaxNumber}`) ainda responde, porém está descontinuada — utilize a V2 em novas integrações. Ambas trazem os mesmos dados; a diferença é que na V1 a situação cadastral é retornada exatamente como disposta pela RFB, enquanto na V2 esse dado é parametrizado segundo uma lista de status pré-determinada com os parâmetros em inglês.

O parâmametro necessário para conseguir autenticar a chamada na API é a informação da api key. Ela está disponível na plataforma da NFE.io, e é necessário que seja utilizada a autenticação referente a consulta de dados.

Abaixo segue o exemplo de uma chamada feita. Nela o número 191 representa o número do CNPJ a ser consultado e dado 5th... é início de uma api key de autenticação.

_url:_ [][9][https://legalentity.api.nfe.io/v2/legalentities/basicInfo/191?apiKey=5th][9]...

## **2\. Parâmetros retornados**

A consulta da API pode retornar os seguintes status:

| **Tabela 1\. Tipos de status que a API retorna** | **Status**                                                |
| ------------------------------------------------ | --------------------------------------------------------- |
| 200                                              | Dados consultados da RFB                                  |
| 400                                              | Parâmetro informado de forma incorreta                    |
| 401                                              | Não autorizado. Autenticação informada da forma incorreta |
| 403                                              | Acesso proibido                                           |
| 404                                              | Empresa não encontrada na consulta                        |
| 500                                              | Erro no processamento da API                              |

Abaixo segue o formato no qual os dados serão retornados no json de retorno da consulta. Nesse json é possível constatar a chave de cada um dos campos bem como o valor retornado e na forma que ele retorna. Também é possível observar como é feito o encadeamento das informações na consulta.

```
{
  "legalEntity": {
    "tradeName": "string",
    "name": "string",
    "federalTaxNumber": 0,
    "createdOn": "2021-05-04T01:26:00.526Z",
    "taxRegime": "Unknown",
    "legalNature": "EmpresaPublica",
    "fiscalUnit": "string",
    "createdUnit": "string",
    "checkCode": "string",
    "stateTaxes": [
      {
        "status": "Abled",
        "taxNumber": "string",
        "statusOn": "2021-05-04T01:26:00.526Z",
        "openedOn": "2021-05-04T01:26:00.526Z",
        "closedOn": "2021-05-04T01:26:00.526Z",
        "additionalInformation": "string",
        "code": "AC",
        "address": {
          "state": "string",
          "city": {
            "code": "string",
            "name": "string"
          },
          "district": "string",
          "additionalInformation": "string",
          "streetSuffix": "string",
          "street": "string",
          "number": "string",
          "numberMin": "string",
          "numberMax": "string",
          "postalCode": "string",
          "country": "string"
        },
        "economicActivities": [
          {
            "type": "Main",
            "code": 0,
            "description": "string"
          }
        ],
        "nfe": {
          "status": "Abled",
          "description": "string"
        },
        "nfse": {
          "status": "Abled",
          "description": "string"
        },
        "cte": {
          "status": "Abled",
          "description": "string"
        },
        "nfce": {
          "status": "Abled",
          "description": "string"
        }
      }
    ]
  }
}
```

Na Tabela abaixo é possível observar o significado de cada um dos campos consultados pela API, bem como os parâmetros retornados em todos eles.

## **Dados de retorno**

---

**tradeName** _string_  
Nome fantasia

---

**name** _string_  
Razão social

---

**federalTaxNumber** _integer($int64)_  
Número da inscrição na Receita Federal (CNPJ)

---

**size** _string(enum)_  
Porte

| Texto do retorno | Significado              |
| ---------------- | ------------------------ |
| **_Unknown_**    | Desconhecido (mapear)    |
| **_ME_**         | Micro Empresa            |
| **_EPP_**        | Empresa de Pequeno Porte |
| **_DEMAIS_**     | Demais tipos             |

---

**openedOn** _string($date-time)_  
Data da abertura

---

**address**

> **state** _string_  
> Estado
> 
> ---
> 
> **city**
> 
>> **code** _string_  
>> Código do município (cMun)
>> 
>> **name** _string_  
>> Nome do município (xMun)
> 
> ---
> 
> **district** _string_  
> Bairro
> 
> ---
> 
> **additionalInformation** _string_  
> Informações adicionais
> 
> ---
> 
> **streetSuffix** _string_  
> Sufixo da rua
> 
> ---
> 
> **street** _string_  
> Nome da rua
> 
> ---
> 
> **number** _string_  
> Número
> 
> ---
> 
> **numberMin** _string_
> 
> ---
> 
> **numberMax** _string_
> 
> ---
> 
> **postalCode** _string_  
> CEP
> 
> ---
> 
> **country** _string_
> 
> País
> 
> ---

**phones**

> **ddd** _string_  
> Prefixo
> 
> ---
> 
> **number** _string_  
> Origem da Informação
> 
> ---
> 
> | _string(enum)_ \- Origem da Informação | significado campo         |
> | -------------------------------------- | ------------------------- |
> | **RFB**                                | Receita Federal do Brasil |

---

**statusOn** _string($date-time)_  
Data da situação cadastral

---

**status** _string(enum)_

| Texto do retorno | significado campo |
| ---------------- | ----------------- |
| **Unknown**      | Desconhecido      |
| **Active**       | Ativa             |
| **Unknown**      | Desconhecido      |
| **Suspended**    | Suspensa          |
| **Cancelled**    | Cancelada         |
| **Unabled**      | Desabilitada      |
| **Null**         | Nula              |

---

**email** _string_  
Correio eletrônico

---

**responsableEntity** _string_  
Ente Federativo Responsável (EFR)

---

**specialStatus** _string_  
Situação Especial

---

**specialStatusOn** _string($date-time)_  
Data da Situação Especial

---

**issuedOn** _string($date-time)_  
Data de Consulta do usuário

---

**statusReason** _string_  
Motivo da Situação Cadastral

---

**shareCapital** _number($double)_  
Capital sócial (em reais)

---

**economicActivities**

> **description**  
> Objeto com Código e descrição das atividades econômicas principal e secundárias
> 
>> **type** _string(enum)_  
>> Classificação da atividade
>> 
>> | Texto do retorno | significado campo |
>> | ---------------- | ----------------- |
>> | **Main**         | Principal         |
>> | **Secondary**    | Secundária        |
>> 
>> ---
>> 
>> **code** _string_  
>> Código da atividade (CNAE)
>> 
>> ---
>> 
>> **description** _string_  
>> Descrição da atividade (CNAE)

---

**legalNature**

> **code** _string_  
> Código da Natureza Legal
> 
> ---
> 
> **description** _string_  
> Descrição da Natureza Legal

---

**partners**

> Objeto com nome e qualificação dos sócios e administradores
> 
> **name** _string_  
> Nome/Nome Empresarial
> 
> ---
> 
> **qualification**
> 
>> **code** _string_  
>> Código Qualificação do Quadro de Sócios e Administradores
>> 
>> ---
>> 
>> **description** _string_  
>> Descrição da Qualificação do Quadro de Sócios e Administradores

---

**registrationUnit** _string_  
Objeto com a cidade/unidade registradora do certificado de baixa

---

**unit** _string(enum)_  
Objeto que define se é matriz, filial ou sucursal

| Texto do retorno | significado campo |
| ---------------- | ----------------- |
| **Headoffice**   | Matriz            |
| **Subsidiary**   | Filial            |

---


[1]: #Introducao%5Fa%5Fconsulta%5Fde%5FCNPJ%5Fcom%5Fa%5FNFEio
[2]: #1%5FBase%5Fpara%5Fa%5Fconsulta%5Fde%5FCNPJ
[3]: #2%5FParametros%5Fretornados
[4]: #Dados%5Fde%5Fretorno
[5]: https://servicos.receita.fazenda.gov.br/servicos/cnpjreva/cnpjreva%5Fsolicitacao.asp
[6]: /desenvolvedores/rest-api/consulta-de-cnpj-v1/legal-entities-api
[7]: https://legalentity.api.nfe.io/v1/legalentities/basicInfo/%7BfederalTaxNumber
[8]: https://legalentity.api.nfe.io/v2/legalentities/basicInfo/%7BfederalTaxNumber
[9]: https://legalentity.api.nfe.io/v2/legalentities/basicInfo/191?apiKey=5th

---

## Introdução à consulta de CPF com a NFE.io - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/consultas/documentacao-introducao-a-consulta-de-cpf/index.md

# Introdução à consulta de CPF com a NFE.io

> Nesse artigo vamos introduzir como é feita a consulta de CPF via API da NFE.io

A consulta de CPF tem como base a busca dos dados do Comprovante de Situação Cadastral de pessoa física que estão disponíveis no site da Receita Federal. Os dados que a API retorna são as informações encontradas a partir da consulta feita na seguinte url:

[https://servicos.receita.fazenda.gov.br/servicos/cpf/consultasituacao/consultapublica.asp][5]

Ao acessar a url acima, você é direcionado para a página mostrada abaixo. Nessa imagem, é possível observar que, a partir da informação de um CPF e a data de nascimento do seu portador, são retornados os dados cadastrais da informação usada na consulta.

> ![](https://nfe.io/docs/static/docs/consultas/image_2021-05-06_101847.png)  
> **Figura 1\. Imagem de exemplo da página de consulta do de Situação Cadastral no CPF**

Abaixo segue um exemplo de uma Situação Cadastral do CPF de uma consulta feita.

> ![](https://nfe.io/docs/static/docs/consultas/image_2021-05-06_103732.png)  
> **Figura 2\. Imagem de exemplo do retorno da consulta do de Situação Cadastral no CPF**

### **1\. Base para a consulta de CPF**

Para poder se consultar os dados cadastrais do cartão CPF a partir da API da NFE.io é necessário informar o CPF e a data de nascimento da pessoa a ser consultada. É possível encontrar mais informações sobre a API na documentação da NFE.io na seguinte url:

[https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-cpf-v1/][6]

Nela é possível observar a existência da versão para a consulta de CPF. Essa url de consulta está abaixo.

| Método | URL                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------ |
| GET    | [https://naturalperson.api.nfe.io/v1/naturalperson/status/\{federalTaxNumber\}/\{birthDate][7]\} |

O CPF a ser informado deve estar no mesmo campo da informação _federalTaxNumber_. O número deve ser informado sem barras traços e pontos. A data de nascimento deve estar no campo _birthDate_ no formato _aaaa-mm-dd_.

O parâmametro necessário para conseguir autenticar a chamada na API é a informação da api key. Ela está disponível na plataforma da NFE.io, e é necessário que seja utilizada a autenticação referente a consulta de dados.

Abaixo segue o exemplo de uma chamada feita. Nela o número "72946154\*" representa o número do CPF a ser consultado, o parâmetro "\*\*\*\*-" a data de nascimento no formato _aaaa-mm-dd_ e dado 5th... é início de uma api key de autenticação.

```json
https://naturalperson.api.nfe.io/v1/naturalperson/status/72946154***/****-**-**?apiKey=5th...
```

### **2\. Dados de retorno da API**

A consulta da API pode retornar os seguintes status:  

**Tabela 1\. Tipos de status que a API retorna**

| Status | Dado de retorno                                           |
| ------ | --------------------------------------------------------- |
| 200    | Dados consultados da RFB                                  |
| 400    | Parâmetro informado de forma incorreta                    |
| 401    | Não autorizado. Autenticação informada da forma incorreta |
| 403    | Acesso proibido                                           |
| 404    | Empresa não encontrada na consulta                        |
| 500    | Erro no processamento da API                              |
| 503    | Serviço indisponível                                      |

Abaixo segue o formato no qual os dados serão retornados no json de retorno da consulta. Nesse json é possível constatar a chave de cada um dos campos bem como o valor retornado e na forma que ele retorna. Também é possível observar como é feito o encadeamento das informações na consulta.

```json
{
  "createdOn": "2021-05-05T13:09:16.346Z",
  "name": "string",
  "federalTaxNumber": "string",
  "birthOn": "2021-05-05T13:09:16.346Z",
  "status": "string"
}
```

Na Tabela abaixo é possível observar o significado de cada um dos campos consultados pela API, bem como os parâmetros retornados em todos eles.

### **Dados de retorno**

---

**createdOn** _string($date-time)_  
Data da consulta

---

**name** _string_  
Nome da pessoa consultada

---

**federalTaxNumber** _string_  
CPF consultado

---

**birthOn** _string($date-time)_  
Data de nascimento da pessoa consultada

---

**status** _string_  
Status da situação cadastral

---


[1]: #Introducao%5Fa%5Fconsulta%5Fde%5FCPF%5Fcom%5Fa%5FNFEio
[2]: #1%5FBase%5Fpara%5Fa%5Fconsulta%5Fde%5FCPF
[3]: #2%5FDados%5Fde%5Fretorno%5Fda%5FAPI
[4]: #Dados%5Fde%5Fretorno
[5]: https://servicos.receita.fazenda.gov.br/servicos/cpf/consultasituacao/consultapublica.asp
[6]: /desenvolvedores/rest-api/consulta-de-cpf-v1/consulta-de-pessoa-fisica
[7]: https://naturalperson.api.nfe.io/v1/naturalperson/status/{federalTaxNumber}/{birthDate

---

## Consulta Irrestrita

Source: https://nfe.io/docs/documentacao/consultas/notas-fiscais/consulta-irrestrita/index.md

# Consulta Irrestrita

A **Consulta Irrestrita** é a forma da NFE.io para você recuperar uma Nota Fiscal Eletrônica (NF-e) autorizada pela chave de acesso, sem depender de portais estaduais individuais. Você recebe o documento em **JSON estruturado**, **XML oficial** e **DANFE em PDF** chamando o mesmo endpoint com sufixos diferentes.

Use quando precisar de uma fonte nacional única que cubra qualquer UF (SP, RJ, CE, etc.) pela mesma chamada. Para a referência REST completa, veja a [Consulta de Nota Fiscal V2](/desenvolvedores/rest-api/consulta-de-nota-fiscal/v2/).

## Fluxo da chamada

```mermaid
flowchart LR
    A[Cliente] --> B[NFE.io]
    B --> C[Provedor oficial<br/>de NF-e]
    C --> B
    B --> A
```

Você chama a NFE.io. A NFE.io chama o provedor oficial autorizado pela autoridade federal e devolve o documento normalizado.

## Contrato HTTP

| Item | Valor |
|---|---|
| Host | `nfe.api.nfe.io` |
| Método | `GET` |
| Path JSON | `/v2/productinvoices/serpro/{accessKey}` |
| Path XML | `/v2/productinvoices/serpro/{accessKey}.xml` |
| Path PDF | `/v2/productinvoices/serpro/{accessKey}.pdf` |
| `accessKey` | string com **44 dígitos numéricos** (chave de acesso da NF-e) |
| Header `Authorization` | Sua **Chave de Dados** da NFE.io, enviada direto **sem prefixo `Bearer`** |
| Content-Type da resposta | `application/json` (JSON), `application/xml` (XML), `application/pdf` (PDF) |

Detalhes da chave de autenticação em [Chaves de Autenticação](/documentacao/nossa-plataforma/chaves-de-autenticacao/).

## Como chamar

A consulta expõe o **mesmo recurso em três formatos**. Apenas a URL muda — método, autenticação e parâmetros são idênticos.

```bash
# JSON estruturado (default)
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/serpro/35200714200166000166550010000000071000000007" \
  -H "Authorization: SUA_CHAVE_DE_DADOS"

# XML oficial
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/serpro/35200714200166000166550010000000071000000007.xml" \
  -H "Authorization: SUA_CHAVE_DE_DADOS" \
  -o nota.xml

# DANFE em PDF
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/serpro/35200714200166000166550010000000071000000007.pdf" \
  -H "Authorization: SUA_CHAVE_DE_DADOS" \
  -o nota.pdf
```

## Campos do retorno (JSON)

Os campos abaixo aparecem na resposta `200 OK` em JSON. O conteúdo é equivalente ao XML oficial (`nfeProc`), mas com nomes normalizados em `camelCase` para consumo por sistemas. Os nomes originais do XML (`cStat`, `cUF`, `natOp`, `emit`, `dest` etc.) **não aparecem no JSON** — use o sufixo `.xml` se precisar do schema oficial.

| Campo | Descrição |
|---|---|
| `currentStatus` | Situação atual da NF-e. Valores: `Authorized`, `Canceled`, `Unknown`. |
| `stateCode` | UF do emitente (equivale a `cUF` no XML). |
| `operationNature` | Natureza da operação (`natOp`). |
| `codeModel`, `serie`, `number` | Modelo, série e número da NF-e (`mod`, `serie`, `nNF`). |
| `issuedOn`, `operationOn` | Data/hora de emissão e da operação (`dhEmi`, `dhSaiEnt`). |
| `environmentType` | Ambiente de emissão (`Production` ou `Homologation`). |
| `issuer` | Dados do emitente: `federalTaxNumber` (CNPJ), `name`, `tradeName`, `stateTaxNumber` (IE), `codeTaxRegime`, `address`. |
| `buyer` | Dados do destinatário: `federalTaxNumber` (CNPJ/CPF), `name`, `address`, `stateTaxNumberIndicator`. |
| `items[]` | Itens da nota: `code`, `description`, `ncm`, `cfop`, `unit`, `quantity`, `unitAmount`, `totalAmount`, `tax`. |
| `totals.icms` | Totais da nota: `productAmount`, `invoiceAmount`, `discountAmount`, `freightAmount`, `icmsAmount` etc. |
| `transport` | Dados de transporte e volumes (`freightModality`, `transportGroup`, `volume`). |
| `payment[]` | Formas de pagamento (`paymentDetail[].method`, `paymentDetail[].amount`). |
| `protocol` | Protocolo de autorização: `accessKey`, `protocolNumber`, `receiptOn`, `statusCode`. **`statusCode == 100` = nota autorizada** (equivale a `cStat` no XML). |

### Exemplo de resposta (recorte)

```json
{
  "currentStatus": "Authorized",
  "stateCode": 35,
  "operationNature": "Venda de Produção",
  "codeModel": 55,
  "serie": 1,
  "number": 7,
  "issuedOn": "2020-07-15T14:32:00-03:00",
  "environmentType": "Production",
  "xmlVersion": "4.00",
  "issuer": {
    "federalTaxNumber": 14200166000166,
    "name": "Empresa Emitente LTDA",
    "stateTaxNumber": "111222333444",
    "address": {
      "state": "SP",
      "city": { "code": "3550308", "name": "SAO PAULO" }
    }
  },
  "buyer": {
    "federalTaxNumber": 99887766000155,
    "name": "Empresa Destinatária SA"
  },
  "items": [
    {
      "code": "PROD-001",
      "description": "Produto exemplo",
      "ncm": "61143000",
      "cfop": 6102,
      "unit": "UN",
      "quantity": 1.0,
      "totalAmount": 13.52
    }
  ],
  "totals": {
    "icms": { "productAmount": 13.52, "invoiceAmount": 12.66 }
  },
  "protocol": {
    "environmentType": "Production",
    "accessKey": "35200714200166000166550010000000071000000007",
    "protocolNumber": "135200000000007",
    "statusCode": 100
  }
}
```

## Status HTTP

| Código | Significado | O que fazer |
|---|---|---|
| `200` | Nota encontrada e retornada. | Leia `protocol.statusCode`. `100` = autorizada (ou `currentStatus == "Authorized"`). |
| `400` | `accessKey` inválida (formato fora dos 44 dígitos). | Valide a chave antes de chamar. |
| `401` | Chave de Dados ausente, incorreta ou com prefixo `Bearer`. | Confira [Chaves de Autenticação](/documentacao/nossa-plataforma/chaves-de-autenticacao/). |
| `403` | Chave de Dados sem permissão para Consulta de NF-e. | Solicite ativação no painel NFE.io. |
| `404` | Chave válida em formato mas NF-e não localizada. | Tratar como regra de negócio. A nota pode não estar disponível ainda. |
| `5xx` | Indisponibilidade temporária. | Nova tentativa em alguns minutos. |

## Armadilhas comuns

- **Chamar sem validar a chave.** Sempre confirme que `accessKey` tem exatamente 44 dígitos numéricos antes de chamar. Chaves inválidas geram `400` e poluem seu monitoramento.
- **Tratar `HTTP 404` como erro de sistema.** Não é. Significa que a NF-e ainda não está disponível ou aponta para nota inexistente. É **regra de negócio**, não falha.
- **Usar prefixo `Bearer` no header `Authorization`.** A NFE.io aceita a Chave de Dados direto, sem `Bearer`. Com prefixo errado, retorno é `HTTP 401`.
- **Confiar no JSON sem checar `protocol.statusCode`.** Uma nota pode estar na base sem estar autorizada (rejeitada ou denegada). Sempre verifique `protocol.statusCode == 100` — equivalente ao `cStat` no XML. O campo `currentStatus == "Authorized"` é a forma textual do mesmo sinal.
- **Não armazenar o XML.** O JSON é conveniente para sistemas; o XML é o **documento fiscal oficial**. Para fins legais, guarde o `.xml` pelos 5 anos exigidos.

## Como uma IA deve consumir esta API

Esta seção é dirigida a agentes de IA construindo integrações ou respondendo perguntas sobre a Consulta Irrestrita da NFE.io.

**Modelo mental.** Trate a API como uma fonte fiscal nacional sobre NF-e autorizadas. A chave de acesso é a única dimensão de consulta. O JSON retornado é equivalente, em conteúdo, ao XML oficial.

**Plano de ação típico.**

1. Receba a chave de acesso da entrada do usuário (44 dígitos).
2. Valide pelo regex `^[0-9]{44}$`.
3. Chame `GET https://nfe.api.nfe.io/v2/productinvoices/serpro/{accessKey}` com header `Authorization: <Chave de Dados>` — sem `Bearer`.
4. Se `200`, leia `protocol.statusCode`. `100` indica autorizada (equivale a `cStat` no XML). O campo `currentStatus == "Authorized"` é a forma textual do mesmo sinal.
5. Se `404`, informe ao usuário que a nota não está disponível.
6. Se `5xx`, instrua nova tentativa em alguns minutos.

**Dado autorizativo essencial.** O campo `protocol.statusCode == 100` é a única evidência de autorização. Sem ela, a nota não tem valor fiscal mesmo aparecendo no JSON.

## Variante V3 — Consulta Irrestrita (XML cru, sem normalização)

Existe uma variante V3 que devolve o XML **exatamente como o provedor SERPRO entrega**, sem a tradução para o esquema canônico camelCase da NFE.io. Use quando precisa preservar autenticidade fiscal ou repassar para sistemas que esperam o XML original do provedor.

### Contrato HTTP

| Item | Valor |
|---|---|
| Host | `nfe.api.nfe.io` |
| Método | `GET` |
| Path | `/v3/productinvoices/serpro/{accessKey}.xml` |
| `accessKey` | string com 44 dígitos numéricos |
| Header `Authorization` | Sua Chave de Dados (sem prefixo `Bearer`) |
| Header `X-Client-Timeout-Seconds` (opcional) | Timeout customizado em segundos. Default `180`. |
| Content-Type da resposta | `application/xml` |

### Exemplo

```bash
curl -X GET \
  "https://nfe.api.nfe.io/v3/productinvoices/serpro/35200714200166000166550010000000071000000007.xml" \
  -H "Authorization: SUA_CHAVE_DE_DADOS" \
  -H "X-Client-Timeout-Seconds: 60" \
  -o nota-v3.xml
```

### Status HTTP adicionais

Além dos status documentados acima para a V2, a V3 adiciona:

| Código | Significado | O que fazer |
|---|---|---|
| `504` | Timeout ao consultar o provedor SERPRO. | Tente novamente, opcionalmente aumentando `X-Client-Timeout-Seconds`. |

### V2 ou V3 — qual escolher?

| Critério | V2 (`/v2/productinvoices/serpro/`) | V3 (`/v3/productinvoices/serpro/`) |
|---|---|---|
| Formatos de retorno | JSON normalizado + XML traduzido + DANFE PDF | XML cru do provedor apenas |
| Tradução de campos | Normaliza para o esquema NFE.io (`camelCase`) | Sem tradução — campos exatamente como o provedor devolve |
| Caso típico | Integração com sistemas que consomem JSON | Auditoria fiscal, repasse legal, sistemas legados que esperam o XML original |
| Timeout customizável | Não | Sim (header `X-Client-Timeout-Seconds`) |
| Status `504` documentado | Não | Sim |

Para a maioria das integrações, a **V2 continua sendo a recomendada**. A V3 é uma opção avançada para casos específicos de autenticidade do payload do provedor ou compatibilidade com sistemas legados.

## Veja também

- [Consulta de Nota Fiscal Eletrônica — visão geral](/documentacao/consultas/notas-fiscais/)
- [Referência REST: Consulta de Nota Fiscal V2](/desenvolvedores/rest-api/consulta-de-nota-fiscal/v2/)
- [Chaves de Autenticação NFE.io](/documentacao/nossa-plataforma/chaves-de-autenticacao/)

---

## Consulta SEFAZ

Source: https://nfe.io/docs/documentacao/consultas/notas-fiscais/consulta-sefaz/index.md

# Consulta SEFAZ

A **Consulta SEFAZ** é o caminho da NFE.io para você recuperar uma Nota Fiscal Eletrônica (NF-e) autorizada pela chave de acesso, consultando o **portal público nacional da Receita Federal** (`nfe.fazenda.gov.br`). Cobertura nacional, retorno em **JSON estruturado**, **XML oficial**, **DANFE em PDF** e **histórico de eventos** da nota (cancelamento, CC-e, manifestação).

Use quando precisar consultar a NF-e e seus eventos a partir da fonte pública oficial. Para uma alternativa via provedor oficial com maior previsibilidade, veja a [Consulta Irrestrita](/documentacao/consultas/notas-fiscais/consulta-irrestrita/). Para a referência REST completa, veja a [Consulta de Nota Fiscal V2](/desenvolvedores/rest-api/consulta-de-nota-fiscal/v2/).

## Fluxo da chamada

```mermaid
flowchart LR
    A[Cliente] --> B[NFE.io]
    B --> C[Portal Receita Federal<br/>nfe.fazenda.gov.br]
    C --> B
    B --> A
```

Você chama a NFE.io. A NFE.io consulta o portal público nacional da Receita Federal e devolve o documento normalizado.

## Contrato HTTP

| Item | Valor |
|---|---|
| Host | `nfe.api.nfe.io` |
| Método | `GET` |
| Path JSON | `/v2/productinvoices/{accessKey}` |
| Path XML | `/v2/productinvoices/{accessKey}.xml` |
| Path PDF | `/v2/productinvoices/{accessKey}.pdf` |
| Path Eventos | `/v2/productinvoices/events/{accessKey}` |
| `accessKey` | string com **44 dígitos numéricos** (chave de acesso da NF-e) |
| Header `Authorization` | Sua **Chave de Dados** da NFE.io, enviada direto **sem prefixo `Bearer`** |
| Content-Type da resposta | `application/json` (JSON e Eventos), `application/xml` (XML), `application/pdf` (PDF) |

Detalhes da chave de autenticação em [Chaves de Autenticação](/documentacao/nossa-plataforma/chaves-de-autenticacao/).

## Como chamar

A consulta expõe o mesmo recurso em três formatos. Apenas a URL muda — método, autenticação e parâmetros são idênticos.

```bash
# JSON estruturado (default)
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/35200714200166000166550010000000071000000007" \
  -H "Authorization: SUA_CHAVE_DE_DADOS"

# XML oficial
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/35200714200166000166550010000000071000000007.xml" \
  -H "Authorization: SUA_CHAVE_DE_DADOS" \
  -o nota.xml

# DANFE em PDF
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/35200714200166000166550010000000071000000007.pdf" \
  -H "Authorization: SUA_CHAVE_DE_DADOS" \
  -o nota.pdf
```

## Consultar eventos da nota

A Consulta SEFAZ permite recuperar o **histórico de eventos** da NF-e (cancelamento, Carta de Correção, manifestação do destinatário), separadamente da consulta da nota em si.

```bash
curl -X GET \
  "https://nfe.api.nfe.io/v2/productinvoices/events/35200714200166000166550010000000071000000007" \
  -H "Authorization: SUA_CHAVE_DE_DADOS"
```

Use eventos para verificar se a nota foi cancelada, corrigida ou se o destinatário manifestou ciência da operação — informações que não vêm na resposta principal da nota.

## Campos do retorno (JSON)

Os campos abaixo aparecem na resposta `200 OK` em JSON. O conteúdo é equivalente ao XML oficial (`nfeProc`), mas com nomes normalizados em `camelCase` para consumo por sistemas. Os nomes originais do XML (`cStat`, `cUF`, `natOp`, `emit`, `dest` etc.) **não aparecem no JSON** — use o sufixo `.xml` se precisar do schema oficial.

| Campo | Descrição |
|---|---|
| `currentStatus` | Situação atual da NF-e. Valores: `Authorized`, `Canceled`, `Unknown`. |
| `stateCode` | UF do emitente (equivale a `cUF` no XML). |
| `operationNature` | Natureza da operação (`natOp`). |
| `codeModel`, `serie`, `number` | Modelo, série e número da NF-e (`mod`, `serie`, `nNF`). |
| `issuedOn`, `operationOn` | Data/hora de emissão e da operação (`dhEmi`, `dhSaiEnt`). |
| `environmentType` | Ambiente de emissão (`Production` ou `Homologation`). |
| `issuer` | Dados do emitente: `federalTaxNumber` (CNPJ), `name`, `tradeName`, `stateTaxNumber` (IE), `codeTaxRegime`, `address`. |
| `buyer` | Dados do destinatário: `federalTaxNumber` (CNPJ/CPF), `name`, `address`, `stateTaxNumberIndicator`. |
| `items[]` | Itens da nota: `code`, `description`, `ncm`, `cfop`, `unit`, `quantity`, `unitAmount`, `totalAmount`, `tax`. |
| `totals.icms` | Totais da nota: `productAmount`, `invoiceAmount`, `discountAmount`, `freightAmount`, `icmsAmount` etc. |
| `transport` | Dados de transporte e volumes (`freightModality`, `transportGroup`, `volume`). |
| `payment[]` | Formas de pagamento (`paymentDetail[].method`, `paymentDetail[].amount`). |
| `protocol` | Protocolo de autorização: `accessKey`, `protocolNumber`, `receiptOn`, `statusCode`. **`statusCode == 100` = nota autorizada** (equivale a `cStat` no XML). |

### Exemplo de resposta (recorte)

```json
{
  "currentStatus": "Authorized",
  "stateCode": 35,
  "operationNature": "Venda de Produção",
  "codeModel": 55,
  "serie": 1,
  "number": 7,
  "issuedOn": "2020-07-15T14:32:00-03:00",
  "environmentType": "Production",
  "xmlVersion": "4.00",
  "issuer": {
    "federalTaxNumber": 14200166000166,
    "name": "Empresa Emitente LTDA",
    "stateTaxNumber": "111222333444",
    "address": {
      "state": "SP",
      "city": { "code": "3550308", "name": "SAO PAULO" }
    }
  },
  "buyer": {
    "federalTaxNumber": 99887766000155,
    "name": "Empresa Destinatária SA"
  },
  "items": [
    {
      "code": "PROD-001",
      "description": "Produto exemplo",
      "ncm": "61143000",
      "cfop": 6102,
      "unit": "UN",
      "quantity": 1.0,
      "totalAmount": 13.52
    }
  ],
  "totals": {
    "icms": { "productAmount": 13.52, "invoiceAmount": 12.66 }
  },
  "protocol": {
    "environmentType": "Production",
    "accessKey": "35200714200166000166550010000000071000000007",
    "protocolNumber": "135200000000007",
    "statusCode": 100
  }
}
```

## Status HTTP

| Código | Significado | O que fazer |
|---|---|---|
| `200` | Nota encontrada e retornada. | Leia `protocol.statusCode`. `100` = autorizada (ou `currentStatus == "Authorized"`). |
| `400` | `accessKey` inválida (formato fora dos 44 dígitos). | Valide a chave antes de chamar. |
| `401` | Chave de Dados ausente, incorreta ou com prefixo `Bearer`. | Confira [Chaves de Autenticação](/documentacao/nossa-plataforma/chaves-de-autenticacao/). |
| `403` | Chave de Dados sem permissão para Consulta de NF-e. | Solicite ativação no painel NFE.io. |
| `404` | Chave válida em formato mas NF-e não localizada. | Tratar como regra de negócio. A nota pode não estar disponível ainda. |
| `5xx` | Indisponibilidade temporária. | Nova tentativa em alguns minutos. |

## Armadilhas comuns

- **Chamar sem validar a chave.** Sempre confirme que `accessKey` tem exatamente 44 dígitos numéricos antes de chamar. Chaves inválidas geram `400` e poluem seu monitoramento.
- **Tratar `HTTP 404` como erro de sistema.** Não é. Significa que a NF-e ainda não está disponível ou aponta para nota inexistente. É **regra de negócio**, não falha.
- **Usar prefixo `Bearer` no header `Authorization`.** A NFE.io aceita a Chave de Dados direto, sem `Bearer`. Com prefixo errado, retorno é `HTTP 401`.
- **Confiar no JSON sem checar `protocol.statusCode`.** Uma nota pode estar na base sem estar autorizada (rejeitada ou denegada). Sempre verifique `protocol.statusCode == 100` — equivalente ao `cStat` no XML. O campo `currentStatus == "Authorized"` é a forma textual do mesmo sinal.
- **Não consultar eventos quando precisa do estado atual.** A resposta principal traz a nota autorizada inicialmente, mas eventos posteriores (cancelamento, CC-e) só aparecem em `/events/{accessKey}`. Para decisões de negócio críticas, valide eventos.
- **Não armazenar o XML.** O JSON é conveniente para sistemas; o XML é o **documento fiscal oficial**. Para fins legais, guarde o `.xml` pelos 5 anos exigidos.

## Como uma IA deve consumir esta API

Esta seção é dirigida a agentes de IA construindo integrações ou respondendo perguntas sobre a Consulta SEFAZ da NFE.io.

**Modelo mental.** Trate a API como uma fonte fiscal nacional sobre NF-e autorizadas, com acesso ao histórico de eventos da nota. A chave de acesso é a única dimensão de consulta. O JSON retornado é equivalente, em conteúdo, ao XML oficial.

**Plano de ação típico.**

1. Receba a chave de acesso da entrada do usuário (44 dígitos).
2. Valide pelo regex `^[0-9]{44}$`.
3. Chame `GET https://nfe.api.nfe.io/v2/productinvoices/{accessKey}` com header `Authorization: <Chave de Dados>` — sem `Bearer`.
4. Se `200`, leia `protocol.statusCode`. `100` indica autorizada (equivale a `cStat` no XML). O campo `currentStatus == "Authorized"` é a forma textual do mesmo sinal.
5. Para decisões críticas, consulte também `/v2/productinvoices/events/{accessKey}` para verificar cancelamento ou correções posteriores.
6. Se `404`, informe ao usuário que a nota não está disponível.
7. Se `5xx`, instrua nova tentativa em alguns minutos.

**Dado autorizativo essencial.** O campo `protocol.statusCode == 100` na resposta principal é evidência de autorização inicial. Eventos posteriores podem alterar o estado da nota — consulte `/events/` quando o caso de uso exigir estado atualizado.

## Veja também

- [Consulta Irrestrita](/documentacao/consultas/notas-fiscais/consulta-irrestrita/) — alternativa via provedor oficial, sem dependência do portal público.
- [Consulta de Nota Fiscal Eletrônica — visão geral](/documentacao/consultas/notas-fiscais/)
- [Referência REST: Consulta de Nota Fiscal V2](/desenvolvedores/rest-api/consulta-de-nota-fiscal/v2/)
- [Chaves de Autenticação NFE.io](/documentacao/nossa-plataforma/chaves-de-autenticacao/)

---

## Notas Fiscais - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/consultas/notas-fiscais/index.md

# Consulta de Nota Fiscal Eletrônica (NF-e)

Com o serviço de consulta de Notas Fiscais Eletrônicas (NF-e) você se informa sobre uma nota apenas informando a chave de acesso de 44 dígitos. A NFE.io oferece **duas opções** de consulta, ambas com cobertura nacional e retorno em **JSON**, **XML** e **DANFE em PDF** pela mesma autenticação.

> Para utilizar nossa API, acesse a [referência REST][4]. Você precisa de uma conta em [nossa plataforma][5] com uma [Chave de Dados][6] ativa.

## Opções disponíveis

| Opção | Fonte de dados | Eventos da nota | Quando usar |
|---|---|---|---|
| [**Consulta SEFAZ**](/documentacao/consultas/notas-fiscais/consulta-sefaz/) | Portal público nacional da Receita Federal (`nfe.fazenda.gov.br`) | ✅ Sim — endpoint `/events/{accessKey}` | Quando precisa do **histórico de eventos** (cancelamento, CC-e, manifestação) ou prefere a fonte pública oficial. |
| [**Consulta Irrestrita**](/documentacao/consultas/notas-fiscais/consulta-irrestrita/) | Provedor oficial autorizado pela autoridade federal | ❌ Não nesta versão | Quando precisa de **maior previsibilidade** em momentos de instabilidade do portal público. |

Ambas usam a mesma chave de acesso de 44 dígitos e a mesma Chave de Dados no header `Authorization` (sem prefixo `Bearer`). A diferença está na **origem técnica** dos dados e na disponibilidade do endpoint de eventos.

## Quais dados nossa API retorna?

Através da chave de acesso da nota fiscal eletrônica, nossa API retorna os dados da nota em três formatos:

- **JSON estruturado** — pronto para consumo por sistemas.
- **XML oficial** (`nfeProc`) — documento fiscal para arquivamento legal.
- **DANFE em PDF** — documento visual para anexo e apresentação.

O conteúdo é equivalente entre os formatos. Para fins legais, o XML é a evidência probatória — guarde-o pelos 5 anos exigidos por lei.

## Como faço para ter acesso à documentação da API?

Veja a [referência REST completa][4] no menu Desenvolvedores. Caso tenha dúvidas ou sugestões, entre em contato — nossa equipe está disponível.


[4]: /desenvolvedores/rest-api/consulta-de-nota-fiscal/v2/
[5]: /documentacao/nossa-plataforma/criar-conta/
[6]: /documentacao/nossa-plataforma/chaves-de-autenticacao/

---

## Consulta de CPF — Irrestrita | NFE.io Docs

Source: https://nfe.io/docs/documentacao/consultas/consulta-cpf-irrestrita/index.md

# Consulta de CPF — Irrestrita

> Esta modalidade consulta a situação cadastral de um CPF diretamente em uma base de dados irrestrita. É a opção indicada para consultas críticas que exigem maior cobertura de campos como o nome social.

A consulta vai à base de dados irrestrita autenticada via credenciais comerciais. Cada chamada percorre toda a cadeia até a fonte de dados. O contrato de resposta é o mesmo da consulta [Receita Federal](/docs/documentacao/consultas/consulta-cpf-receita-federal/), com maior probabilidade de retorno do campo `socialName` quando ele consta na base.

## 1. Base para a consulta

Para consultar a situação cadastral de um CPF nesta modalidade, informe o número do CPF e a data de nascimento da pessoa. O endpoint é único e está descrito abaixo.

| Método | URL                                                                                                         |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| GET    | `https://naturalperson.api.nfe.io/v1/naturalperson/serpro/status/{federalTaxNumber}/{birthDate}`            |

Parâmetros de caminho:

- `federalTaxNumber` — CPF sem máscara, somente dígitos (sem pontos nem traços).
- `birthDate` — data de nascimento no formato `aaaa-mm-dd`.

### Autenticação

Você precisa de uma chave de API. Crie sua conta em [nossa plataforma](/docs/documentacao/nossa-plataforma/criar-conta/) e gere a chave conforme [chaves de autenticação](/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/). A API aceita três formas equivalentes de envio:

| Modo                 | Exemplo                                              |
| -------------------- | ---------------------------------------------------- |
| Header `Authorization` | `Authorization: Bearer {apiKey}`                   |
| Header `X-NFEIO-APIKEY` | `X-NFEIO-APIKEY: {apiKey}`                        |
| Query string          | `?apiKey={apiKey}`                                  |

### Exemplo de chamada

```bash
curl -X GET \
  "https://naturalperson.api.nfe.io/v1/naturalperson/serpro/status/72946154***/****-**-**" \
  -H "Authorization: Bearer 5th************"
```

:::info
Esta modalidade depende de habilitação comercial na conta NFE.io. Se a consulta retornar `403`, verifique a habilitação com seu gerente comercial.
:::

## 2. Quando usar esta modalidade

Use a consulta Irrestrita quando você precisa de cobertura mais ampla de campos como `socialName`. O custo por chamada é maior.

| Aspecto              | Irrestrita                                           | Receita Federal                                       |
| -------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
| Fonte                | Base de dados irrestrita (comercial)                 | Página pública da RFB (coleta direta)                 |
| Latência             | Consistente                                          | Pode variar com o portal público da RFB               |
| `socialName`         | Confiável quando consta na base                      | Pode não vir                                          |
| Custo                | Maior (consulta comercial)                           | Menor                                                 |
| Recomendado para     | Consultas críticas com cobertura ampla               | Volume alto e menor custo                             |

Para a outra modalidade, veja [Consulta de CPF — Receita Federal](/docs/documentacao/consultas/consulta-cpf-receita-federal/).

## 3. Dados de retorno

A API responde com os seguintes códigos HTTP:

| Status | Significado                                                |
| ------ | ---------------------------------------------------------- |
| 200    | Sucesso na requisição                                      |
| 400    | Parâmetro informado de forma incorreta                     |
| 401    | Autenticação inválida                                      |
| 403    | Sem permissão para o recurso                               |
| 404    | CPF não encontrado ou data de nascimento divergente        |
| 500    | Erro no processamento                                      |
| 503    | Temporariamente indisponível                               |

O payload de retorno segue o formato abaixo.

```json
{
  "createdOn": "2026-05-27T13:09:16.346Z",
  "name": "string",
  "socialName": "string",
  "federalTaxNumber": "string",
  "birthOn": "1980-01-01T00:00:00.000Z",
  "status": "Regular"
}
```

### Dicionário de campos

---

**createdOn** _string($date-time)_
Data da consulta.

---

**name** _string_
Nome da pessoa consultada.

---

**socialName** _string?_
Nome social. Retornado com mais frequência nesta modalidade, pois a base irrestrita o entrega quando ele consta no cadastro do contribuinte.

---

**federalTaxNumber** _string_
CPF consultado.

---

**birthOn** _string($date-time)_
Data de nascimento.

---

**status** _string(enum)_
Situação cadastral do CPF.

| Texto do retorno          | Significado                |
| ------------------------- | -------------------------- |
| **Unknown**               | Desconhecido               |
| **Regular**               | Regular / ativo            |
| **Null**                  | Nulo                       |
| **Suspended**             | Suspenso                   |
| **Canceled**              | Cancelado                  |
| **RegularizationPending** | Pendente de regularização  |
| **OwnerDeceased**         | Titular falecido           |

---

---

## Consulta de CPF — Receita Federal | NFE.io Docs

Source: https://nfe.io/docs/documentacao/consultas/consulta-cpf-receita-federal/index.md

# Consulta de CPF — Receita Federal

> Esta modalidade consulta a situação cadastral de um CPF a partir da página pública da Receita Federal. É a opção indicada para volumes altos e menor custo por consulta.

A consulta retorna os dados do Comprovante de Situação Cadastral disponíveis em [servicos.receita.fazenda.gov.br](https://servicos.receita.fazenda.gov.br/servicos/cpf/consultasituacao/consultapublica.asp). A API faz a coleta direta no portal público da RFB a cada requisição e retorna a situação cadastral correspondente.

> ![Tela de consulta de Situação Cadastral do CPF no portal da Receita Federal](https://nfe.io/docs/static/docs/consultas/image_2021-05-06_101847.png)
> **Figura 1.** Página pública de consulta de Situação Cadastral do CPF.

> ![Exemplo de retorno do Comprovante de Situação Cadastral do CPF](https://nfe.io/docs/static/docs/consultas/image_2021-05-06_103732.png)
> **Figura 2.** Comprovante de Situação Cadastral retornado pela Receita Federal.

## 1. Base para a consulta

Para consultar a situação cadastral de um CPF nesta modalidade, informe o número do CPF e a data de nascimento da pessoa. O endpoint é único e está descrito abaixo.

| Método | URL                                                                                                  |
| ------ | ---------------------------------------------------------------------------------------------------- |
| GET    | `https://naturalperson.api.nfe.io/v1/naturalperson/status/{federalTaxNumber}/{birthDate}`            |

Parâmetros de caminho:

- `federalTaxNumber` — CPF sem máscara, somente dígitos (sem pontos nem traços).
- `birthDate` — data de nascimento no formato `aaaa-mm-dd`.

### Autenticação

Você precisa de uma chave de API. Crie sua conta em [nossa plataforma](/docs/documentacao/nossa-plataforma/criar-conta/) e gere a chave conforme [chaves de autenticação](/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/). A API aceita três formas equivalentes de envio:

| Modo                 | Exemplo                                              |
| -------------------- | ---------------------------------------------------- |
| Header `Authorization` | `Authorization: Bearer {apiKey}`                   |
| Header `X-NFEIO-APIKEY` | `X-NFEIO-APIKEY: {apiKey}`                        |
| Query string          | `?apiKey={apiKey}`                                  |

### Exemplo de chamada

```bash
curl -X GET \
  "https://naturalperson.api.nfe.io/v1/naturalperson/status/72946154***/****-**-**" \
  -H "Authorization: Bearer 5th************"
```

## 2. Quando usar esta modalidade

Use a consulta Receita Federal quando o seu fluxo prioriza menor custo por consulta. A latência pode variar conforme a disponibilidade do portal público da RFB (coleta direta com solver de captcha).

| Aspecto              | Receita Federal                                       | Irrestrita                                           |
| -------------------- | ----------------------------------------------------- | ---------------------------------------------------- |
| Fonte                | Página pública da RFB (coleta direta)                 | Base de dados irrestrita (comercial)                 |
| Latência             | Pode variar com o portal público da RFB               | Consistente                                          |
| `socialName`         | Pode não vir                                          | Confiável quando consta na base                      |
| Custo                | Menor                                                 | Maior (consulta comercial)                           |
| Recomendado para     | Volume alto e menor custo                             | Consultas críticas com cobertura ampla               |

Para a outra modalidade, veja [Consulta de CPF — Irrestrita](/docs/documentacao/consultas/consulta-cpf-irrestrita/).

## 3. Dados de retorno

A API responde com os seguintes códigos HTTP:

| Status | Significado                                                |
| ------ | ---------------------------------------------------------- |
| 200    | Sucesso na requisição                                      |
| 400    | Parâmetro informado de forma incorreta                     |
| 401    | Autenticação inválida                                      |
| 403    | Sem permissão para o recurso                               |
| 404    | CPF não encontrado ou data de nascimento divergente        |
| 500    | Erro no processamento                                      |
| 503    | Temporariamente indisponível                               |

O payload de retorno segue o formato abaixo.

```json
{
  "createdOn": "2026-05-27T13:09:16.346Z",
  "name": "string",
  "socialName": "string",
  "federalTaxNumber": "string",
  "birthOn": "1980-01-01T00:00:00.000Z",
  "status": "Regular"
}
```

### Dicionário de campos

---

**createdOn** _string($date-time)_
Data da consulta.

---

**name** _string_
Nome da pessoa consultada.

---

**socialName** _string?_
Nome social. Pode vir nulo nesta modalidade quando o portal público não expõe o campo. Para retorno mais confiável de nome social, use a consulta [Irrestrita](/docs/documentacao/consultas/consulta-cpf-irrestrita/).

---

**federalTaxNumber** _string_
CPF consultado.

---

**birthOn** _string($date-time)_
Data de nascimento.

---

**status** _string(enum)_
Situação cadastral do CPF.

| Texto do retorno          | Significado                |
| ------------------------- | -------------------------- |
| **Unknown**               | Desconhecido               |
| **Regular**               | Regular / ativo            |
| **Null**                  | Nulo                       |
| **Suspended**             | Suspenso                   |
| **Canceled**              | Cancelado                  |
| **RegularizationPending** | Pendente de regularização  |
| **OwnerDeceased**         | Titular falecido           |

---

---

## Pessoa Física - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/consultas/pessoa-fisica/index.md

# Consulta de dados de Pessoa Física

Com o nosso serviço você pode consultar dados de situação cadastral de Pessoas Físicas através de diferentes fontes, utilizando apenas o número do CPF.

> Para utilizar nossa API de consulta de CPF, acesse nosso [ambiente de testes][4]. Você deverá possuir uma conta em [nossa plataforma][5] para a utilização de sua [chave de acesso da API.][6]

Confira abaixo quais dados nossas consultas retornam e como utilizar nosso serviço.

## Quais dados você consegue acessar

Nossa API possui as seguintes modalidades de consulta de Situação Cadastral:

* **[Consulta Receita Federal](/docs/documentacao/consultas/consulta-cpf-receita-federal/)**: situação cadastral por coleta direta na página pública da [Receita Federal][7]. Indicada para volume alto e menor custo por consulta.
* **[Consulta Irrestrita](/docs/documentacao/consultas/consulta-cpf-irrestrita/)**: situação cadastral via base de dados irrestrita, com maior cobertura de campos como o nome social. Indicada para consultas críticas que exigem cobertura ampla de dados.

## Como faço para ter acesso à documentação da API?

[Clique aqui][4] para acessar a documentação da API de consulta de Pessoa Física, e caso possua alguma dúvida ou sugestão de melhoria, sinta-se à vontade para entrar em contato conosco, e nossa equipe estará disponível para ajudá-lo(a)!

## Saiba mais

* [Introdução à consulta de CPF com a NFE.io](/docs/documentacao/consultas/documentacao-introducao-a-consulta-de-cpf/) — material introdutório com exemplos de chamada e detalhamento de campos retornados.


[1]: #Consulta%5Fde%5Fdados%5Fde%5FPessoa%5FFisica
[2]: #Quais%5Fdados%5Fvoce%5Fconsegue%5Facessar
[3]: #Como%5Ffaco%5Fpara%5Fter%5Facesso%5Fa%5Fdocumentacao%5Fda%5FAPI
[4]: https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-cpf-v1/
[5]: https://nfe.io/docs/documentacao/nossa-plataforma/criar-conta/
[6]: https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/
[7]: https://servicos.receita.fazenda.gov.br/Servicos/CPF/ConsultaSituacao/ConsultaPublica.asp

---

## Pessoa Jurídica - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/consultas/pessoa-juridica/index.md

# Consulta de dados de Pessoa Jurídica

Com o nosso serviço você pode consultar as principais informações que precisa sobre Pessoas Jurídicas através de diferentes fontes utilizando apenas o número do CNPJ. Confira abaixo os tipos de consultas que disponibilizamos.

> Para utilizar nossa API de consulta de CNPJ, acesse nosso ambiente de testes. Você deverá possuir uma conta em nossa plataforma para a utilização de sua chave de acesso da API. Para utilizar nossa API de consulta de CNPJ, acesse nosso [ambiente de testes][4]. Você deverá possuir uma conta em [nossa plataforma ][5]para a utilização de sua [chave de acesso da API][6].

## Quais dados você consegue ver?

Nossa API possui os seguintes tipos de consultas.

**Simples Nacional**: Esse tipo de consulta é feito através do site da Receita Federal e retorna os dados de regime tributário de uma pessoa jurídica.  
**Dados básicos**: Esse tipo de consulta é feito através do site da Receita Federal e retorna os dados básicos de uma pessoa jurídica.  
**Inscrição Estadual**: Esse tipo de consulta é feito através do site da Sintegra e retorna os dados de inscrição estadual de uma pessoa jurídica.

## Como faço para ter acesso à documentação da API?

[Clique aqui][4] para acessar a documentação da API de consulta de Pessoa Jurídica, e caso possua alguma dúvida ou sugestão de melhoria, sinta-se à vontade para [entrar em contato conosco][7]. Nossa equipe estará disponível para ajudá-lo(a)!


[1]: #Consulta%5Fde%5Fdados%5Fde%5FPessoa%5FJuridica
[2]: #Quais%5Fdados%5Fvoce%5Fconsegue%5Fver
[3]: #Como%5Ffaco%5Fpara%5Fter%5Facesso%5Fa%5Fdocumentacao%5Fda%5FAPI
[4]: /desenvolvedores/rest-api/consulta-de-cnpj-v1/legal-entities-api
[5]: /documentacao/nossa-plataforma/criar-conta
[6]: /documentacao/nossa-plataforma/chaves-de-autenticacao
[7]: /documentacao/conceitos/introducao#Contato

---

## DFe Inbound: Guia do Usuário para Clientes

Source: https://nfe.io/docs/documentacao/distribuicao/dfe-inbound-documentacao-funcional-clientes/index.md

# Guia do Usuário — Recebimento Automático de NF-e, CT-e e NFS-e (nfe.io)

**Produto:** DFe Inbound — Recepção Automática de Documentos Fiscais
**Público:** Clientes (empresas usuárias do serviço)
**Atualizado em:** 2026-04-30

---

## Índice

1. [O que é o DFe Inbound?](#1-o-que-é-o-dfe-inbound)
2. [Como o Sistema Funciona?](#2-como-o-sistema-funciona)
3. [Comparativo: NF-e, CT-e e NFS-e](#3-comparativo-nf-e-ct-e-e-nfs-e)
4. [Nota Fiscal Eletrônica (NF-e)](#4-nota-fiscal-eletrônica-nf-e)
5. [Conhecimento de Transporte Eletrônico (CT-e)](#5-conhecimento-de-transporte-eletrônico-ct-e)
6. [Nota Fiscal de Serviços Eletrônica (NFS-e)](#6-nota-fiscal-de-serviços-eletrônica-nfs-e)
7. [O que é o Certificado Digital?](#7-o-que-é-o-certificado-digital)
8. [Ativando o Serviço — Passo a Passo Detalhado](#8-ativando-o-serviço--passo-a-passo-detalhado)
9. [Consultando Documentos Recebidos](#9-consultando-documentos-recebidos)
10. [Listagem em Lote via API — Para Grandes Volumes](#10-listagem-em-lote-via-api--para-grandes-volumes)
11. [Exportação em Massa — XML, PDF e CSV (Bulk Export)](#11-exportação-em-massa--xml-pdf-e-csv-bulk-export)
12. [Manifestação de Documentos — O que é e Por que Importa](#12-manifestação-de-documentos--o-que-é-e-por-que-importa)
13. [Notificações Automáticas (Webhooks)](#13-notificações-automáticas-webhooks)
14. [Segurança e Privacidade dos Dados](#14-segurança-e-privacidade-dos-dados)
15. [Reforma Tributária — O que Muda para Minha Empresa?](#15-reforma-tributária--o-que-muda-para-minha-empresa)
16. [Dúvidas Comuns](#16-dúvidas-comuns)
17. [Glossário](#17-glossário)

---

## 1. O que é o DFe Inbound?

Imagine que você tem uma empresa e recebe dezenas ou centenas de **Notas Fiscais Eletrônicas (NF-e)**, **Conhecimentos de Transporte (CT-e)** e **Notas Fiscais de Serviços (NFS-e)** de fornecedores por mês. Antes, você precisaria:

- Acessar múltiplos portais (SEFAZ, prefeituras, SEFIN Nacional) manualmente
- Baixar cada documento um por um
- Guardar os arquivos XML em algum lugar
- Avisar seu sistema de gestão sobre cada documento novo

O **DFe Inbound da nfe.io** faz tudo isso automaticamente para você, cobrindo os três tipos de documento fiscal eletrônico mais relevantes para quem **recebe**:

1. **Monitora** continuamente o Ambiente Nacional da SEFAZ (NF-e / CT-e) e o Ambiente de Distribuição Nacional da SEFIN (NFS-e) em busca de novos documentos destinados ao seu CNPJ
2. **Baixa e armazena** todos os XMLs de forma segura na nuvem
3. **Organiza os dados** (emitente, valor, data, etc.) para consulta rápida
4. **Avisa seu sistema** automaticamente quando um documento novo chega

### Para quem é este serviço?

- Empresas que **compram mercadorias** de fornecedores e precisam controlar as NF-es recebidas
- Empresas que **contratam serviços de transporte** e precisam controlar os CT-es
- Empresas que **contratam serviços** (consultoria, manutenção, software, etc.) e precisam controlar as NFS-es tomadas
- Empresas que precisam fazer a **manifestação fiscal** das NF-es e NFS-es recebidas
- Equipes de TI ou contabilidade que precisam integrar documentos fiscais com sistemas de gestão (ERP, TMS, etc.)

### Os três subsistemas em uma frase

| Subsistema | O que captura |
|---|---|
| **DFe Inbound NF-e** | Notas de compra de produtos que chegam para sua empresa |
| **DFe Inbound CT-e** | Conhecimentos de transporte emitidos por transportadoras onde sua empresa aparece como tomadora, expedidora, recebedora ou destinatária |
| **DFe Inbound NFS-e** | Notas de serviços tomados pela sua empresa (novo padrão nacional da LC 214/2025) |

Cada subsistema pode ser ativado **independentemente** por CNPJ — você pode ligar só NF-e, só NFS-e, ou os três juntos, conforme a realidade da sua operação.

---

## 2. Como o Sistema Funciona?

### O Fluxo Completo em 7 Passos

```
PASSO 1: Fornecedor emite o documento fiscal destinado à sua empresa
         (NF-e, CT-e ou NFS-e)
         ↓
PASSO 2: SEFAZ (NF-e/CT-e) ou Prefeitura/SEFIN (NFS-e) autoriza o documento
         ↓
PASSO 3: O documento é sincronizado com o Ambiente Nacional correspondente
         (SEFAZ AN para NF-e/CT-e; ADN/SEFIN para NFS-e)
         ↓
PASSO 4: O Ambiente Nacional registra o documento com um NSU
         (número sequencial único por CNPJ)
         ↓
PASSO 5: nfe.io detecta o novo documento consultando o Ambiente Nacional
         ↓
PASSO 6: nfe.io baixa o XML, extrai os dados e armazena tudo com segurança
         ↓
PASSO 7: Seu sistema é notificado automaticamente (webhook)
         ou você consulta quando precisar (API / painel)
```

### Quanto tempo leva?

- **NF-e e CT-e:** entre 15 minutos e 4 horas após a autorização da SEFAZ. Em picos (final de mês, campanhas), pode aumentar.
- **NFS-e:** até cerca de 30 segundos após a disponibilização no ADN (pollings curtos). Quanto tempo a prefeitura/SEFIN leva para autorizar e publicar o documento depende do município emissor.

### O que é o NSU?

O **NSU (Número Sequencial Único)** é um número que os ambientes nacionais atribuem a cada documento fiscal destinado ao seu CNPJ. Funciona como um "contador de correspondências":

- NSU 1000 → NF-e do fornecedor A
- NSU 1001 → NFS-e da empresa de consultoria B
- NSU 1002 → Cancelamento da NF-e do fornecedor A

Cada subsistema (NF-e/CT-e e NFS-e) tem **seu próprio NSU**, controlado separadamente. O nosso sistema usa o NSU para saber quais documentos já foram buscados e quais ainda precisam ser baixados — assim, nenhum documento é perdido ou duplicado.

---

## 3. Comparativo: NF-e, CT-e e NFS-e

As três operações são diferentes e têm regras próprias. Este quadro resume o essencial:

| Aspecto | NF-e (modelo 55) | CT-e (modelo 57) | NFS-e (padrão nacional) |
|---|---|---|---|
| **O que é** | Nota fiscal de venda de produtos/mercadorias | Conhecimento de transporte de cargas | Nota fiscal de prestação de serviços |
| **Quem emite** | Vendedor (fornecedor de produtos) | Transportadora | Prestador de serviços |
| **Quem recebe** | Destinatário (comprador) | Tomador, expedidor, recebedor ou destinatário | Tomador do serviço |
| **Fonte de distribuição** | SEFAZ — Ambiente Nacional (AN) | SEFAZ — Ambiente Nacional (AN) | SEFIN Nacional — ADN (Ambiente de Distribuição Nacional) |
| **Base legal/padrão** | NT 2014/002, regime nacional | NT 2013/003, regime nacional | LC 214/2025 + padrão nacional NFS-e (transição municipal → nacional) |
| **Chave de acesso** | 44 dígitos | 44 dígitos | 50 dígitos |
| **Frequência de sincronização** | A cada ~3 min | A cada ~3 min | A cada ~30 s |
| **Documento complementar (PDF)** | DANFE | DACTE | DANFSe |
| **Manifestação do destinatário** | 4 tipos (Ciência, Confirmação, Desconhecimento, Operação Não Realizada) | Não aplicável (apenas consulta) | 2 tipos (Ciência `203202`, Rejeição `203206`) |
| **Prazo de retroatividade SEFAZ/SEFIN** | 90 dias | 90 dias | Desde o início da produção do ADN (aprox. 2026) |
| **Impostos destacados no XML** | ICMS, IPI, PIS, COFINS + IBS/CBS/IS (Reforma Tributária) | ICMS, PIS, COFINS + IBS/CBS (Reforma) | ISS (municipal) + IBS/CBS (Reforma) |

### Quando eu preciso de cada um?

| Sua situação | Você precisa de... |
|---|---|
| Sua empresa compra matéria-prima, mercadoria para revenda ou ativos fixos | **NF-e** |
| Sua empresa contrata frete, transporte rodoviário, aquaviário, ferroviário ou aéreo | **CT-e** |
| Sua empresa contrata serviços (consultoria, software, manutenção, terceirização, assessoria jurídica, etc.) | **NFS-e** |
| Sua empresa faz tudo isso | **Os três juntos** |

> Você pode ativar apenas os subsistemas que fazem sentido para sua operação. O plano contratado determina quais estão disponíveis.

---

## 4. Nota Fiscal Eletrônica (NF-e)

### O que é uma NF-e?

A **Nota Fiscal Eletrônica (modelo 55)** é o documento fiscal digital emitido quando uma empresa vende produtos ou presta serviços para outra empresa. É o equivalente digital da antiga nota fiscal de papel.

Cada NF-e tem:

- Uma **Chave de Acesso** de 44 dígitos que a identifica unicamente no Brasil
- Um **XML** com todos os dados fiscais (emitente, destinatário, produtos, valores, impostos)
- Um **DANFE** (Documento Auxiliar) em PDF para visualização

### Tipos de Registros de NF-e que você pode receber

| Tipo | O que significa |
|---|---|
| **NF-e Completa** | Documento autorizado com XML completo disponível |
| **Resumo de NF-e** | Dados básicos disponíveis antes do XML completo chegar |
| **Evento** | Uma ação sobre a NF-e (cancelamento, correção, manifestação) |
| **Resumo de Evento** | Dados básicos de um evento |

### Eventos de NF-e

Além da NF-e em si, existem **eventos** que registram ações sobre ela:

| Evento | O que significa para você |
|---|---|
| **Cancelamento** | O emitente cancelou a NF-e. Atenção: se você já recebeu a mercadoria, entre em contato com o fornecedor |
| **Carta de Correção** | O emitente corrigiu um dado da NF-e (exceto dados fiscais críticos) |
| **Ciência da Operação** | Você (ou o sistema automaticamente) confirmou que tem ciência desta NF-e |
| **Confirmação da Operação** | Você confirmou que recebeu a mercadoria conforme descrito |
| **Desconhecimento da Operação** | Você informou à SEFAZ que não reconhece esta NF-e |
| **Operação Não Realizada** | Você informou que a operação não foi concluída |

---

## 5. Conhecimento de Transporte Eletrônico (CT-e)

### O que é um CT-e?

O **Conhecimento de Transporte Eletrônico (CT-e)** é o documento fiscal obrigatório emitido pelas transportadoras para acobertar as prestações de serviço de transporte de cargas.

Quando você compra mercadorias de um fornecedor e a transportadora é diferente do fornecedor, você pode receber:

- Uma NF-e (da venda das mercadorias pelo fornecedor)
- Um CT-e (do serviço de transporte pela transportadora)

### Partes Envolvidas em um CT-e

| Parte | Descrição |
|---|---|
| **Emitente** | A transportadora que emitiu o CT-e |
| **Tomador** | Quem contratou o serviço de transporte (pode ser você) |
| **Expedidor** | Quem entregou a carga para transporte |
| **Receptor** | Quem recebeu a carga no destino |
| **Destinatário** | Para quem a carga foi enviada (geralmente você) |

Você pode aparecer em **qualquer um** desses papéis, e o CT-e será distribuído para o seu CNPJ em todos os casos.

---

## 6. Nota Fiscal de Serviços Eletrônica (NFS-e)

### O que é uma NFS-e?

A **Nota Fiscal de Serviços Eletrônica (NFS-e)** é o documento fiscal emitido sempre que uma empresa presta um serviço para outra empresa ou para um consumidor. Diferente da NF-e (que cobre produtos), a NFS-e cobre **serviços** — consultoria, software, transporte de pessoas, manutenção, educação, saúde, assessoria, tecnologia, entre muitos outros.

### Por que existe um novo padrão nacional?

Historicamente, a NFS-e era emitida pela prefeitura de cada município, e cada prefeitura tinha seu próprio layout, site e regras. Para uma empresa com fornecedores de vários municípios, isso significava acompanhar dezenas de portais diferentes.

A **Lei Complementar 214/2025** (Reforma Tributária) criou um padrão **nacional e unificado** de NFS-e. Agora os documentos são centralizados no **Ambiente de Distribuição Nacional (ADN) da SEFIN Nacional**, da mesma forma que a SEFAZ centraliza NF-e e CT-e. O DFe Inbound NFS-e consome esse ambiente nacional.

### Como a NFS-e funciona no padrão nacional?

O fluxo envolve dois documentos distintos:

1. **DPS (Declaração de Prestação de Serviço)** — é o XML **antes** da autorização, submetido pelo prestador à SEFIN Nacional
2. **NFS-e** — é o XML **após** a autorização, assinado pela SEFIN, com a chave de acesso definitiva

Do ponto de vista de quem **recebe** (tomador do serviço), o que importa é a NFS-e autorizada — é ela que o DFe Inbound captura.

### Tipos de Registros de NFS-e que você pode receber

| Tipo | O que significa |
|---|---|
| **NFS-e autorizada** | Nota fiscal de serviço autorizada pela SEFIN, com XML completo |
| **DPS** | Declaração pré-autorização (geralmente só relevante para auditoria e casos de inconsistência) |
| **Evento de registro** | Registros oficiais vinculados à NFS-e (ex.: eventos fiscais, eventos do prestador) |
| **Evento** | Eventos vinculados diretamente a uma NFS-e (incluindo manifestação do tomador) |

### Partes Envolvidas em uma NFS-e

| Parte | Descrição |
|---|---|
| **Prestador** (Provider) | A empresa que realizou o serviço e emitiu a NFS-e |
| **Tomador** (Borrower) | A empresa que contratou e pagou pelo serviço — geralmente você |
| **Intermediário** (opcional) | Uma terceira parte envolvida na contratação (ex.: plataforma, holding) |

O DFe Inbound NFS-e captura toda NFS-e em que o seu CNPJ apareça como **tomador**.

### Manifestação de NFS-e pelo Tomador

Diferente da NF-e, o padrão nacional da NFS-e oferece **dois** tipos de manifestação que o tomador (quem recebe o serviço) pode submeter:

| Evento | Código | O que significa |
|---|---|---|
| **Ciência** | `203202` | "Estou ciente desta NFS-e destinada ao meu CNPJ" |
| **Rejeição** | `203206` | "Rejeito esta NFS-e — não reconheço o serviço, ou há inconsistência fiscal" |

Para a **Rejeição**, a SEFIN exige um **motivo codificado**:

| Código do motivo | Descrição |
|---|---|
| `1` | Duplicata |
| `2` | Já emitida pelo tomador |
| `3` | Sem fato gerador |
| `4` | Erro de responsabilidade tributária |
| `5` | Erro de valor, serviço ou data |
| `9` | Outros (texto livre em `justification`) |

A Ciência pode ser **automatizada** pela plataforma, igual à Ciência da NF-e. A Rejeição é sempre manual por envolver juízo fiscal.

### Identificando a NFS-e

| Campo | Formato |
|---|---|
| **Chave de Acesso NFS-e** | 50 dígitos (diferente da NF-e/CT-e, que têm 44) |
| **Código do Serviço** | Código municipal do serviço prestado (ex.: `01.01` = Análise e desenvolvimento de sistemas) |
| **Código do Município** | Código IBGE do município onde o serviço foi prestado |

### Diferenças práticas em relação à NF-e

- Não há **conferência de mercadoria física** — o serviço é imaterial. Por isso, as manifestações são apenas Ciência e Rejeição (não há "Confirmação de Operação" como na NF-e)
- A NFS-e **pode ser emitida após o serviço já ter sido prestado**, então a data de emissão não corresponde necessariamente à data da execução
- O valor do serviço fica em `servicesAmount`; não há campos equivalentes aos do XML da NF-e para quantidade de mercadoria, peso, etc.

---

## 7. O que é o Certificado Digital?

### Por que precisamos do seu certificado?

O serviço de inbound se comunica com a SEFAZ (NF-e/CT-e) e com a SEFIN Nacional (NFS-e) em nome da sua empresa para buscar os documentos. Esses ambientes exigem **autenticação por certificado digital** — é como uma "assinatura eletrônica" que prova que somos você.

Sem o certificado configurado na plataforma, o sistema não consegue consultar esses ambientes e não há como receber os documentos. O **mesmo certificado** atende aos três subsistemas (NF-e, CT-e e NFS-e).

### O que é um certificado digital?

É um arquivo eletrônico (ou cartão/token físico) que funciona como uma **carteira de identidade digital** da sua empresa. Ele contém:

- O CNPJ da empresa
- A chave criptográfica que prova a identidade
- A validade (geralmente 1 ou 3 anos)

### Tipos de Certificado

| Tipo | Como funciona | Quando usar |
| --- | --- | --- |
| **A1** | Arquivo `.pfx` ou `.p12` salvo no computador | Mais simples de usar. Ideal para integração com sistemas automatizados |
| **A3** | Cartão físico ou token USB | Mais seguro. O certificado não sai do dispositivo físico |

Para o DFe Inbound, o **certificado A1** é obrigatório, pois permite que nosso sistema faça as consultas automaticamente sem interação humana.

### Como obter um certificado digital?

1. Acesse um dos **Agentes de Registro** credenciados pela ICP-Brasil (exemplos: Certisign, Serasa Experian, Valid, Soluti, SERPRO)
2. Escolha um certificado **e-CNPJ** (para pessoa jurídica)
3. O custo varia entre R$ 150 e R$ 400, dependendo da autoridade certificadora e da validade

### Como configurar na plataforma nfe.io?

1. Acesse o Painel nfe.io → Empresas → \{sua empresa\} → **Certificado Digital**
2. Faça upload do arquivo `.pfx` ou `.p12`
3. Informe a senha do certificado
4. Clique em **Salvar**

> **Importante:** Fique atento ao vencimento do seu certificado. Quando ele expirar, o sistema para de buscar novos documentos automaticamente. Configure um lembrete 30 dias antes do vencimento para renová-lo.

---

## 8. Ativando o Serviço — Passo a Passo Detalhado

Esta seção descreve em detalhe todo o processo de onboarding, da criação da conta até o primeiro documento capturado. Se você já completou alguma destas etapas, pode pular para a próxima.

### Visão Geral do Onboarding

```
1. Criar conta principal (conta guarda-chuva) ─────► só uma vez por organização
                    ↓
2. Cadastrar empresa (CNPJ) na conta ─────────────► repetir por CNPJ
                    ↓
3. Enviar certificado digital A1 da empresa
                    ↓
4. Ativar o(s) subsistema(s) desejado(s) ──────────► NF-e, CT-e e/ou NFS-e
                    ↓
5. Configurar webhook (opcional mas recomendado)
                    ↓
6. Configurar manifestação automática (opcional)
                    ↓
7. Gerar API Key para integração com seu ERP
                    ↓
8. Monitorar os primeiros documentos capturados
```

### Passo 1 — Criar a Conta Principal (Conta Guarda-Chuva)

A **conta principal** é o "teto" organizacional da sua empresa dentro da nfe.io. Ela agrupa todas as empresas (CNPJs), usuários, permissões e dados faturáveis em um único lugar. Em grupos econômicos com várias filiais ou marcas, **uma única conta principal** hospeda todos os CNPJs do grupo.

**Como criar:**

1. Acesse [nfe.io](https://nfe.io) e clique em **"Criar conta"**
2. Preencha dados do responsável (nome, e-mail corporativo, senha)
3. Confirme o e-mail (link enviado para a caixa de entrada)
4. Faça login em [app.nfe.io](https://app.nfe.io)
5. Na primeira sessão, você será guiado a preencher dados da organização (razão social, CNPJ principal, endereço, telefone de contato)

> Se sua empresa já possui conta na nfe.io, pule este passo. Peça ao administrador da conta que adicione você como usuário com o papel apropriado.

### Passo 2 — Cadastrar uma Empresa (CNPJ) na Conta

Dentro da conta principal, cada **CNPJ monitorado** é cadastrado como uma "empresa" independente. Você pode ter quantos CNPJs quiser, e ativar cada um de forma isolada.

**Como cadastrar uma empresa:**

1. No Painel, menu lateral → **"Empresas"** → **"+ Nova Empresa"**
2. Preencha:
   - **CNPJ**: o CNPJ da filial/matriz que deseja monitorar
   - **Razão Social** e **Nome Fantasia**
   - **Endereço completo** (CEP, logradouro, município, UF)
   - **Inscrição Estadual** (se aplicável)
   - **Inscrição Municipal** (obrigatória para NFS-e)
   - **Regime Tributário** (Simples Nacional, Lucro Presumido, Lucro Real)
3. Clique em **"Salvar"**

Ao salvar, a empresa fica cadastrada porém ainda **inativa** para inbound — os próximos passos ligam o recebimento.

### Passo 3 — Enviar o Certificado Digital

Com a empresa cadastrada, o próximo passo é o **certificado digital A1** (arquivo `.pfx`/`.p12`). Sem ele, nenhum subsistema de inbound consegue operar.

1. Painel → Empresas → \{sua empresa\} → **"Certificado Digital"**
2. Clique em **"Enviar Certificado"**
3. Selecione o arquivo `.pfx` ou `.p12`
4. Informe a senha do certificado
5. Clique em **"Salvar"**

O sistema valida:

- Se o CNPJ do certificado bate com o CNPJ da empresa
- Se o certificado ainda está dentro da validade
- Se a senha está correta
- Se a chave privada é acessível (necessária para assinar as requisições)

Em caso de erro, a plataforma mostra a mensagem específica. Os problemas mais comuns são **CNPJ divergente** e **senha incorreta**.

### Passo 4 — Ativar o(s) Subsistema(s) de Inbound

Agora vem a parte principal: ligar o recebimento de documentos. Cada subsistema é ativado **separadamente** pela sua própria tela, pois tem configurações específicas.

#### 4a. Ativando NF-e Inbound

1. Painel → Empresas → \{sua empresa\} → **"Inbound" → "NF-e"**
2. Clique em **"Ativar"**
3. Preencha:
   - **Data de Início**: a partir de qual data buscar documentos históricos (máx. 90 dias atrás — limite da SEFAZ)
   - **Ambiente SEFAZ**: `Produção` (operação real) ou `Homologação` (testes)
   - **Manifestação Automática**: habilitar/desabilitar, e delay em minutos (recomendado **60 minutos**)
4. Clique em **"Salvar e Ativar"**

O sistema começa a consultar a SEFAZ Ambiente Nacional imediatamente.

#### 4b. Ativando CT-e Inbound

1. Painel → Empresas → \{sua empresa\} → **"Inbound" → "CT-e"**
2. Clique em **"Ativar"**
3. Preencha **Data de Início** e **Ambiente SEFAZ**
4. Clique em **"Salvar e Ativar"**

> CT-e não tem manifestação do destinatário, então não existe "Manifestação Automática" aqui.

#### 4c. Ativando NFS-e Inbound

1. Painel → Empresas → \{sua empresa\} → **"Inbound" → "NFS-e"**
2. Clique em **"Ativar"**
3. Preencha:
   - **NSU Inicial**: por padrão `0` (começa do mais antigo disponível no ADN)
   - **Ambiente SEFIN**: `Produção` ou `Homologação`
   - **Manifestação Automática (Ciência)**: habilitar/desabilitar, delay em segundos (máx. 604.800 = 7 dias; recomendado 3.600 = 1 hora)
4. Clique em **"Salvar e Ativar"**

> A manifestação automática da NFS-e envia apenas o evento de **Ciência** (`203202`). A **Rejeição** é sempre manual.

### Passo 5 — Configurar o Webhook (Opcional, Mas Recomendado)

Sem webhook, você depende de consultar periodicamente o painel ou a API. Com webhook, seu ERP é avisado **no instante em que o documento chega**.

1. Painel → **"Webhooks"** → **"+ Adicionar URL"**
2. Informe:
   - **URL**: o endpoint do seu sistema (ex.: `https://meu-erp.com/api/webhooks/nfe`)
   - **Eventos**: selecione quais eventos quer receber (NF-e nova, evento de NF-e, CT-e novo, NFS-e nova, manifestação submetida, etc.)
   - **Cabeçalhos customizados** (opcional, útil se seu endpoint exige autenticação)
3. Clique em **"Testar"** — o painel dispara uma notificação de teste para validar que o endpoint responde HTTP 200
4. Clique em **"Salvar"**

Veja [seção 13](#13-notificações-automáticas-webhooks) para mais detalhes.

### Passo 6 — Configurar Manifestação Automática (Opcional)

Se você habilitou manifestação automática no Passo 4, o sistema registra automaticamente:

- **NF-e**: Ciência da Operação após o delay configurado
- **NFS-e**: Ciência (`203202`) após o delay configurado

Isso garante conformidade fiscal sem intervenção manual. Você ainda pode registrar manifestações mais específicas (Confirmação, Desconhecimento, Operação Não Realizada para NF-e; Rejeição para NFS-e) quando aplicável.

### Passo 7 — Gerar uma API Key para Integração

Para que o ERP consuma a API nfe.io:

1. Painel → **"API Keys"** → **"+ Nova API Key"**
2. Nomeie a chave (ex.: `ERP Produção`)
3. Selecione os **papéis (roles)** que a chave terá:
   - `Nota Fiscal (api.nfe.io)` — cobre NF-e, CT-e e listagem em lote
   - `NFS-e Inbound` — cobre endpoints de NFS-e
   - Outros conforme contratado
4. Clique em **"Gerar"**
5. **Copie e guarde a chave em local seguro** — ela é exibida apenas uma vez

> Trate a API Key como uma senha. Nunca exponha em código versionado em repositório público, em logs ou em prints.

### Passo 8 — Monitorar os Primeiros Documentos

Nas primeiras horas após ativação, você deve ver:

- Documentos aparecendo na lista **"Documentos Recebidos"**
- O indicador **"Último NSU processado"** avançando
- Webhooks sendo disparados (se configurados)

Sinais de problema a observar:

| Sintoma | Possível causa | O que fazer |
|---|---|---|
| Último NSU não avança | Certificado expirado ou CNPJ não habilitado na SEFAZ/SEFIN | Renovar certificado; abrir chamado na SEFAZ |
| Status "Inativo" em vermelho | Falhas consecutivas (circuit breaker acionou) | Ver detalhe do erro no painel; reativar após corrigir |
| Webhooks não chegam | URL incorreta ou servidor recusando | Testar URL no painel; checar logs do seu endpoint |
| "Rate limited until \{data\}" | SEFAZ/SEFIN aplicou throttle temporário | Aguardar — a captura retoma automaticamente |

### Como Saber se Está Funcionando?

No painel de cada subsistema, você verá:

- **Status:** "Ativo" (verde) ou "Inativo" (vermelho)
- **Último NSU processado:** número do último documento buscado
- **NSU máximo disponível:** indica se há documentos pendentes
- **Data da última execução:** quando ocorreu a última busca
- **Falhas consecutivas:** contador que dispara o circuit breaker se muito alto

Se "Último NSU processado" estiver igual ao "NSU máximo disponível", estamos em dia — não há documentos novos.

---

## 9. Consultando Documentos Recebidos

### Via Painel nfe.io

No painel da empresa, acesse **"Documentos Recebidos"** e escolha o subsistema (NF-e, CT-e ou NFS-e). Você verá uma lista com:

- Data de emissão
- Emitente/Prestador (CNPJ e nome)
- Valor total / Valor do serviço
- Tipo (documento ou evento)
- Status

Clique em qualquer documento para:

- Ver todos os dados detalhados
- Baixar o XML
- Baixar o DANFE/DACTE/DANFSe (PDF)
- Consultar eventos vinculados (quando houver)

### Filtros Disponíveis

| Filtro | NF-e | CT-e | NFS-e |
|---|:---:|:---:|:---:|
| Período de emissão | ✔ | ✔ | ✔ |
| Tipo (documento/evento) | ✔ | ✔ | ✔ |
| Emitente/Prestador (CNPJ/nome) | ✔ | ✔ | ✔ |
| Faixa de valor | ✔ | ✔ | ✔ |
| Status de processamento | ✔ | ✔ | ✔ |
| Status do webhook | ✔ | ✔ | ✔ |
| Intervalo de NSU | ✔ | ✔ | ✔ |
| Código do serviço | — | — | ✔ |

### Baixando o XML

O XML é o arquivo oficial — contém todos os dados com validade jurídica e fiscal.

1. Encontre o documento na lista
2. Clique em **"Baixar XML"**
3. O arquivo `.xml` será baixado para o seu computador

> **Guarde os XMLs!** A legislação exige que você mantenha os arquivos XML por **pelo menos 5 anos**.

### Baixando o PDF (DANFE / DACTE / DANFSe)

O PDF é a representação visual do documento, usado para conferência e arquivo físico.

1. Encontre o documento na lista
2. Clique em **"Baixar PDF"**
3. O arquivo `.pdf` será baixado

---

## 10. Listagem em Lote via API — Para Grandes Volumes

Além das consultas individuais no painel e do recebimento automático via webhook, a nfe.io oferece **endpoints de listagem em lote** que permitem à sua equipe de TI baixar **vários documentos de uma vez só**. Essa funcionalidade é útil quando você precisa:

- **Sincronizar um histórico completo** — por exemplo, ao integrar um novo sistema de gestão (ERP) e precisar carregar todos os documentos dos últimos meses de uma só vez
- **Fazer auditorias e conciliações contábeis** — listar todos os documentos de um período para conferir com o livro fiscal
- **Gerar relatórios consolidados** — comparar volume de compras mês a mês, ticket médio por fornecedor, etc.
- **Reprocessar documentos** — caso o seu sistema ERP tenha ficado fora do ar e perdido webhooks, você pode "recuperar" os documentos em lote

### Como funciona?

A ideia é simples: em vez de consultar **um documento por vez**, sua equipe de TI faz uma única chamada à API e recebe uma **lista paginada** de documentos.

```text
┌─────────────────────────────────────────────────┐
│  Seu sistema ERP                                │
└────────────────────┬────────────────────────────┘
                     │
                     │ 1. Pede "me dê as próximas 100 notas"
                     ▼
┌─────────────────────────────────────────────────┐
│  API nfe.io — Listagem em Lote                  │
└────────────────────┬────────────────────────────┘
                     │
                     │ 2. Retorna 100 notas de uma vez
                     ▼
┌─────────────────────────────────────────────────┐
│  Seu sistema processa as 100 notas              │
└────────────────────┬────────────────────────────┘
                     │
                     │ 3. Pede as próximas 100 (paginação)
                     ▼
              ... até acabar
```

### O que pode ser listado em lote?

| Listagem | O que retorna |
|---|---|
| **NF-e (ProductInvoices)** | Todas as notas fiscais de produto destinadas ao seu CNPJ, filtradas por ambiente (produção ou homologação) |
| **Eventos de NF-e (ProductInvoiceEvents)** | Todos os eventos de uma NF-e específica (ciência, confirmação, cancelamento, carta de correção, etc.) |
| **CT-e (TransportationInvoices)** | Todos os conhecimentos de transporte destinados ao seu CNPJ de uma data específica |
| **Eventos de CT-e (TransportationInvoiceEvents)** | Todos os eventos de CT-e recebidos em uma data específica |
| **NFS-e (ServiceInvoicesInbound)** | Todas as NFS-es tomadas pela sua empresa — paginação por NSU, suporta filtros por ambiente, CNPJ do prestador, período de emissão e de recebimento |
| **Eventos de NFS-e** | Eventos vinculados a uma NFS-e específica (incluindo manifestações) |

### Paginação — como "virar de página"

Como o volume pode ser grande (milhares ou até milhões), a API **entrega os documentos em páginas** de até 1000 registros por vez (tamanho recomendado: **100 registros**).

- **NF-e e CT-e** usam um cursor do tipo `skiptoken` (OData)
- **NFS-e** usa paginação **pageIndex/pageCount** baseada em NSU ascendente — você passa `pageIndex=1, 2, 3...` até a API devolver uma página vazia

Em todos os casos, a ordenação é **crescente por NSU** — isso garante que nenhum documento seja pulado, mesmo se chegarem novos durante a iteração.

### Por que usar listagem em lote em vez de webhooks?

Use a **listagem em lote** quando:

- Você está integrando pela **primeira vez** e precisa processar os documentos já recebidos
- Seu sistema **ficou fora do ar** por um período e perdeu webhooks
- Você precisa gerar um **relatório histórico** ou fazer uma conciliação contábil
- Você quer fazer um **processamento periódico** (ex: rotina noturna que consulta tudo do dia)

Use os **webhooks** quando:

- Você quer ser notificado **em tempo real** sobre cada documento novo
- Seu sistema precisa **reagir imediatamente** à chegada de uma nota (ex: liberar um pagamento, abrir uma OS)

> Dica: o ideal é usar **os dois mecanismos juntos** — webhooks para o dia a dia e listagem em lote para situações especiais (integração inicial, recuperação, auditorias).

### Quem pode usar a listagem em lote?

- **Sua equipe de TI** (através da nossa API, documentada em detalhes no guia técnico para desenvolvedores)
- O uso exige uma **API Key** com a role apropriada (`Nota Fiscal (api.nfe.io)` para NF-e/CT-e; `NFS-e Inbound` para NFS-e)

Se a sua empresa não tem equipe de TI interna, entre em contato com o suporte nfe.io para recomendarmos parceiros integradores.

### Perguntas frequentes sobre listagem em lote

**Quanto custa usar a listagem em lote?**

Depende do seu plano na nfe.io. Em geral, as requisições de listagem estão incluídas no plano normal, sem custo adicional. Consulte seu contrato ou o time comercial.

**Há limite de requisições?**

Sim, há um limite de requisições por minuto (*rate limit*) para proteger o sistema contra sobrecarga. Em geral, esse limite é suficiente para qualquer integração normal. Sua equipe de TI receberá informações sobre o limite em headers de resposta.

**Existe ordenação fixa dos resultados?**

Sim. As listagens são **sempre ordenadas do NSU mais antigo para o mais recente** (ascendente). Isso garante que a paginação funcione de forma consistente e que nenhum documento seja pulado.

**E se chegarem documentos novos durante a listagem?**

Sem problemas. Como a paginação é baseada em cursor (NSU), novos documentos recebidos durante a iteração terão NSU maior que o cursor atual e serão incluídos naturalmente quando você chegar naquele ponto.

**Posso filtrar por data de emissão, fornecedor ou valor?**

Os filtros suportados variam por subsistema:

- **NF-e**: ambiente (`environmentType`)
- **Eventos de NF-e**: chave de acesso da NF-e pai
- **CT-e**: data de emissão (`issuedOn`)
- **Eventos de CT-e**: data de recebimento (`receiptOn`)
- **NFS-e**: ambiente, CNPJ do prestador/tomador, intervalo de NSU, período de criação, período de emissão, status de processamento, status de webhook, código do serviço

Para filtros mais específicos (fornecedor, faixa de valor, etc.), sua equipe de TI pode baixar os documentos e aplicar os filtros localmente depois.

---

## 11. Exportação em Massa — XML, PDF e CSV (Bulk Export)

### 11.1 O que é a Exportação em Massa?

Imagine que sua empresa recebeu **2.000 NF-es no mês passado** e o pessoal
da contabilidade pediu *"manda todos os XMLs e uma planilha com o resumo
de cada nota pra eu fazer o fechamento"*. Sem a Exportação em Massa, você
teria duas opções dolorosas:

- **Baixar uma por uma pelo console** — clicar em cada nota, abrir,
  baixar XML, baixar PDF, repetir 2.000 vezes. Inviável.
- **Implementar uma integração com a API** — chamar
  [`GET /v2/companies/{id}/inbound/nfse`](#10-listagem-em-lote-via-api--para-grandes-volumes)
  paginado, depois para cada nota chamar `GET /{id}/xml`, `GET /{id}/pdf`
  ou `GET /{id}/json`, juntar tudo num ZIP, gerar planilha. Funciona mas
  exige programação + servidor + tempo.

A **Exportação em Massa** resolve isso com **um clique no console** ou
**uma única chamada de API**. Você define um período (ex.: 01/04/2026 a
30/04/2026), escolhe um formato (XML, PDF ou CSV), e a NFE.io processa
tudo nos servidores dela e te envia por e-mail um link para baixar **um
único arquivo** com tudo pronto.

### 11.2 Os três formatos disponíveis

A NFE.io oferece **três formatos** de exportação, cada um com um caso de
uso específico:

#### 📑 XML — Para guarda fiscal e auditoria

- **Conteúdo:** todos os arquivos `.xml` originais e assinados das notas
  do período, **compactados em um único arquivo `.zip`**.
- **Tamanho típico:** 2.000 notas ≈ 80-200 MB de ZIP (cada XML tem 5-50 KB
  dependendo da complexidade).
- **Quando usar:**
  - Guardar pelos **5 anos** que a legislação fiscal exige.
  - Enviar para **auditoria fiscal** (a Receita pede o XML, não o PDF).
  - Importar em sistemas contábeis que processam XML (Domínio, Sage,
    Conta Azul, etc.).
- **O que **não** dá pra fazer com o XML:** abrir e ler como um humano —
  é um formato técnico, cheio de tags. Para isso, use o PDF ou o CSV.

#### 📄 PDF — Para visualização humana e impressão

- **Conteúdo:** todos os **DANFEs** (NF-e) ou **DANFSes** (NFS-e) em
  PDF, compactados em ZIP.
- **Tamanho típico:** 2.000 notas ≈ 200-500 MB de ZIP (PDFs são
  proporcionalmente maiores).
- **Quando usar:**
  - **Imprimir** pra anexar a processos físicos.
  - **Enviar pra alguém** que não tem leitor de XML (advogado, gerente,
    auditor independente).
  - **Arquivar visualmente** — alguns clientes preferem ler o PDF antes
    de processar o XML.
- **Limitação importante:** **eventos de NF-e** (cancelamento, carta de
  correção, ciência, etc.) e **NFC-e (modelo 65)** **não têm DANFE** —
  esses documentos são *silenciosamente pulados* na exportação PDF
  (sem mensagem de erro). Se você está esperando 2.000 PDFs e só recebeu
  1.850, é provavelmente isso.

#### 📊 CSV — Para análise, conciliação e BI ⭐ (mais usado pelo time fiscal)

- **Conteúdo:** **uma única planilha** (arquivo `.csv`) com **uma linha
  por nota**, contendo dados estruturados nas colunas (chave de acesso,
  emitente, valor, CFOP, status, evento relacionado, etc.).
- **Tamanho típico:** 2.000 notas ≈ 1-3 MB. Tamanho desprezível
  comparado a XML/PDF.
- **Por que é o mais usado:**
  - **Abre direto no Excel / Google Sheets / Power BI / Tableau** sem
    nenhuma conversão.
  - Permite **filtros, agrupamentos, somas e gráficos** em segundos.
  - Ideal para **conciliação** (cruzar com contas a pagar, com pedidos,
    com lançamentos contábeis).
- **Quando usar:**
  - **Fechamento contábil mensal** (somar valores, separar por CFOP,
    identificar notas canceladas).
  - **Auditoria interna** ("quantas notas vieram do fornecedor X?",
    "quanto pagamos de ICMS-ST esse mês?").
  - **Relatórios para diretoria** (importar no Power BI / Tableau /
    Looker).
  - **Detectar anomalias** (notas com valor muito maior que a média do
    fornecedor, divergências em CFOP, eventos de cancelamento que você
    não estava esperando).

### 11.3 Disponibilidade por subsistema

| Subsistema | XML | PDF | CSV |
|---|---|---|---|
| **NF-e Recebidas** | ✅ disponível | ✅ disponível | ✅ disponível (a partir de mai/2026) |
| **NFS-e Recebidas** | ✅ disponível | ✅ disponível | ✅ disponível (a partir de mai/2026) |
| **CT-e Recebidas** | ⏳ no roadmap | ⏳ no roadmap | ⏳ no roadmap |

> O suporte a CT-e em bulk export está sendo planejado para versões
> futuras. No momento, para baixar CT-es em massa, use a API de
> [Listagem em Lote](#10-listagem-em-lote-via-api--para-grandes-volumes)
> com download individual via `GET /{accessKey}/xml` e `/pdf`.

**Per-document JSON (apenas NFS-e):** além do bulk export em XML/PDF/CSV,
o subsistema NFS-e Recebidas oferece um endpoint adicional por documento
— `GET /v2/companies/{companyId}/inbound/nfse/{id}/json` — que devolve
o XML capturado convertido em JSON literal, útil para integrações que
preferem JSON ao XML. Não é um formato de exportação em massa: é um
download alternativo do mesmo conteúdo do XML, uma nota por vez. Detalhes
em `02-doc-tecnica-clientes-dev-nfse-inbound-api.md`.

### 11.4 Como funciona por dentro (visão simplificada)

A exportação é **assíncrona** — significa que ela não acontece na hora
em que você clica. O fluxo:

```
1. Você clica em "Exportar" no console (ou faz POST via API)
       ↓
2. NFE.io recebe o pedido e cria um "job" na fila
       ↓ (responde imediatamente: "ok, vou processar")
       ↓
3. Um worker da NFE.io pega o job:
   - Para cada dia do período, busca a lista de notas
   - Para cada nota, baixa o conteúdo (XML, PDF ou monta linha do CSV)
   - Vai escrevendo num arquivo temporário
       ↓
4. Quando termina, sobe o arquivo para um blob storage seguro (Azure)
       ↓
5. Gera um link expirável (válido por 7 dias) e envia por e-mail
       ↓
6. Você clica no link e baixa o arquivo
```

**Tempo típico de processamento:**

| Volume | XML/PDF | CSV |
|---|---|---|
| 100 notas (1 mês de empresa pequena) | 30-60 segundos | 10-20 segundos |
| 1.000 notas (1 mês de empresa média) | 3-8 minutos | 30-60 segundos |
| 10.000 notas (1 mês de empresa grande) | 30-90 minutos | 5-10 minutos |

> **Por que CSV é tão mais rápido?** Porque o CSV não baixa o XML/PDF
> de cada nota — ele só lê os metadados (que já estão indexados na base
> de dados da NFE.io). XML e PDF exigem download de cada arquivo
> individual, multiplicando o tempo.

### 11.5 O que tem dentro do CSV (a regra de "achatamento")

Esta é a parte mais importante de entender, porque o CSV tem uma
**peculiaridade conceitual** que pode confundir no primeiro contato.

#### Por que existem "eventos relacionados"

Uma nota fiscal não fica estática depois de emitida. Ela pode receber
**eventos** ao longo do tempo:

- **Cancelamento** — o emitente desistiu da operação.
- **Substituição** (NFS-e) — uma nova nota foi emitida no lugar dessa.
- **Carta de Correção** (NF-e) — pequenas correções textuais (não fiscais).
- **Manifestação** — você (destinatário) confirmou/discordou da operação.

Esses eventos são **documentos separados** na base da NFE.io, vinculados
à nota original. Se você fizer a listagem completa (sem bulk export),
pode trazer 2.000 notas + 350 eventos misturados. Confuso para análise.

#### A regra do "evento primário"

O CSV resolve isso assim:

> "Cada linha do CSV é uma nota fiscal. Se essa nota tem eventos
> relacionados, eu escolho **o evento mais relevante** e coloco os
> dados dele nas últimas colunas. Os outros eventos não aparecem."

A **escolha do evento mais relevante** segue uma regra de prioridade
(diferente entre NF-e e NFS-e, porque os domínios têm conceitos
diferentes):

**Para NFS-e Recebidas:**

1. Se há um evento de **Substituição** (código 310611), ele vence —
   pega o mais recente.
2. Senão, se há um evento de **Cancelamento** (código 310610), ele vence
   — pega o mais recente.
3. Senão, pega o evento mais recente por data de geração (`GeneratedOn`).

**Para NF-e Recebidas:**

1. Pega o evento **mais recente** por data de emissão (`IssuedOn`).
2. Em caso de empate (mesma data), desempata pela chave de acesso (ordem
   alfanumérica) — garantia de ordem determinística.

> **Por que NFS-e tem prioridade Substituição/Cancelamento mas NF-e
> não?** Porque o NFS-e expõe o `EventCode` (310610, 310611, etc.) como
> um campo separado nos metadados, e dá pra detectar Substituição vs
> Cancelamento sem abrir o XML. Já no NF-e, esse código vive dentro do
> XML do evento, e detectá-lo exigiria parsing extra. A regra "mais
> recente" funciona bem porque eventos NF-e em sequência cronológica
> (ciência → confirmação → cancelamento) seguem o ciclo de vida natural
> — o último evento é normalmente o mais relevante.

#### Quando uma nota não tem evento

As **colunas de evento ficam vazias** — mas a linha da nota **continua
sendo emitida**. Você nunca perde uma nota por não ter evento.

#### Schema completo das colunas

> 📑 **Para o detalhamento coluna-por-coluna** (24 colunas no CSV de
> NFS-e, 18 no de NF-e), consulte o Guia de Uso do Console — seção
> 10.
> Lá tem a descrição de cada coluna individual.

### 11.6 Casos de uso típicos (real-world)

#### Caso 1 — Fechamento contábil mensal

A contadora roda no console no dia 5 de cada mês:

1. Acessa NF-e Recebidas → Exportar → CSV → período: mês anterior.
2. Recebe e-mail em ~2 minutos com o link.
3. Abre no Excel.
4. Filtra por status `Issued` (exclui canceladas).
5. Cria pivot table somando valor por CFOP.
6. Exporta o resumo para o sistema contábil.
7. Repete para NFS-e Recebidas.

**Tempo total:** 15-20 minutos para fechar o mês inteiro de uma empresa
com 1.500 notas. Sem o CSV, seriam horas.

#### Caso 2 — Conciliação com contas a pagar

Time financeiro precisa cruzar NF-es recebidas com pagamentos efetuados:

1. Exporta CSV de NF-e do mês.
2. Exporta extrato de contas a pagar do ERP.
3. No Excel, faz `VLOOKUP` cruzando CNPJ do fornecedor + valor.
4. Identifica:
   - Notas sem pagamento correspondente (atrasadas ou não lançadas).
   - Pagamentos sem nota (problema fiscal — sem documento suporte).

#### Caso 3 — Power BI / dashboard executivo

Diretoria quer um dashboard mensal com:
- Top 10 fornecedores por valor.
- Variação YoY (year over year).
- % de notas canceladas (indicador de qualidade da operação).

Solução: agendar exportação CSV via API (curl + cron), salvar histórico
em tabela do Power BI, montar visualizações. Atualiza sozinho todo mês.

#### Caso 4 — Auditoria SEFAZ

A SEFAZ pede "todos os XMLs do trimestre Q1 2026". Resposta:

1. Faz **3 exportações XML** (uma por mês: jan, fev, mar — ou usa
   `splitDays=true` pra arquivos por dia).
2. Recebe 3 arquivos ZIP.
3. Envia para o auditor via canal seguro.

Tempo: minutos. Sem bulk export, seria proibitivo.

### 11.7 Como acompanhar uma exportação em andamento

#### Pelo console

Acesse **Conta** (no menu superior) → **Exportações**. A página lista
todas as suas exportações dos últimos **90 dias**, com colunas:

- Data de criação
- Tipo (NF-e XML, NFS-e CSV, etc.)
- Período solicitado
- Status (Pendente / Em Processamento / Concluído / Falhou)
- Quantidade de itens processados
- Tamanho do arquivo final
- Botão de **Baixar** (se Concluído)

Os estados possíveis:

- **Pendente** (cinza) — está na fila aguardando ser pega por um worker.
- **Em processamento** (azul, com ícone giratório) — em execução.
- **Concluído** (verde) — pronto, link disponível.
- **Falhou** (vermelho) — erro durante a execução. Clique em "Detalhes"
  pra ver a causa.

#### Por API (para integrações automatizadas)

Para times técnicos que querem integrar o status no próprio sistema:

```http
GET /accounts({accountId})/subscriptions({subscriptionId})/exports({jobId})
Authorization: <SUA_API_KEY>
```

Resposta inclui `status`, `downloadUrl` (quando concluído), `errorMessage`
(quando falhou), `totalLines`, `failed` (notas que erraram individualmente
mas não pararam o job).

> Detalhes técnicos completos no
> [02-doc-tecnica-clientes-nfe-cte-dev-pt.md](/documentacao/distribuicao/dfe-inbound-documentacao-tecnica-desenvolvedores)
> e na Postman collection
> (folder **6. Bulk Export (shared-usage-api)**).

### 11.8 Limites e boas práticas

#### Tamanho do período

- **Recomendado:** 1 mês por exportação (alinha com fechamento contábil).
- **Máximo prático:** 6 meses — acima disso o tempo de processamento e o
  tamanho do arquivo ficam inconvenientes.
- **Para períodos longos:** use o parâmetro `splitDays=true` (disponível
  via API e no console em opções avançadas) — gera **um arquivo por dia**
  em vez de um único arquivo gigante. Mais arquivos, mais fáceis de
  processar.

#### Notificação por e-mail

Se sua exportação vai levar mais de 1 minuto, **marque "Notificar por
e-mail"** no console. Senão você precisa acompanhar manualmente em
**Conta → Exportações**. O e-mail traz o link direto.

#### Idioma das colunas (CSV)

O CSV vem **com cabeçalhos em português** por padrão. Para receber em
inglês, use o parâmetro `language=en-US` na chamada de API. **No console
ainda não há essa opção exposta** — sai sempre em PT-BR.

#### Reexecução

A página de **Conta → Exportações** tem um menu **⋮** em cada linha com
opção **Reexecutar** — útil quando o período é o mesmo mas você quer
pegar dados atualizados (notas que chegaram entre a primeira execução e
agora).

#### Quanto tempo o link de download fica disponível?

**7 dias** após conclusão. Depois disso o arquivo é deletado por política
de privacidade e você precisa rodar nova exportação. **Baixe rápido** ou
encaminhe o link pra quem precisa antes do prazo.

### 11.9 O que fazer se algo der errado

#### "Não foi possível enfileirar a exportação"

Erro temporário do servidor. Aguarde 30 segundos e tente novamente. Se
persistir após 3 tentativas, verifique o status da NFE.io em
[status.nfe.io](https://status.nfe.io) e, se estiver tudo "verde", abra
chamado no suporte.

#### "Não foi encontrada uma chave de API ativa"

Sua conta tem várias API Keys e nenhuma delas está marcada como **Ativa**
com a descrição **"Nota Fiscal (api.nfe.io)"**. Vá em **Conta → API
Keys** e ative (ou crie) uma chave com essa descrição.

#### Job está "Em processamento" há mais de 1 hora

Pode estar travado. Vá em **Conta → Exportações** e verifique se o status
mudou. Se continuar "Em processamento" sem progresso, contate o suporte
mencionando o ID do job (visível na URL ou nos detalhes).

#### CSV abriu no Excel com tudo numa coluna só

O Excel está usando o delimitador errado. Solução:
1. Abra o Excel **antes** do arquivo.
2. **Dados → Obter Dados → Do Arquivo → CSV/Texto**.
3. Selecione o arquivo CSV.
4. Na janela de importação, escolha **delimitador: ponto-e-vírgula `;`**.
5. **Encoding: ISO-8859-1** (ou Windows-1252).

Alternativa: Google Sheets detecta automaticamente o delimitador na
maioria das vezes — basta arrastar o arquivo pra dentro.

#### Algumas notas estão como "failed" no resumo do job

O CSV/XML/PDF foi gerado, mas algumas notas não puderam ser processadas
individualmente (problema de download, parsing, etc.). O resumo do job
mostra `totalLines` (notas escritas) e `failed` (notas que erraram). Se
`failed > 0`, abra os **detalhes do job** no console para ver os erros
específicos por chave de acesso.

### 11.10 Por dentro: arquitetura (para quem se interessa)

A Exportação em Massa **não roda no `dfetech-distribution-api`** — roda
num serviço separado chamado **`shared-usage-api`** (que originalmente
foi feito para o módulo de medição de uso da plataforma e ganhou esse
módulo de export depois).

O fluxo técnico:

1. Console / cliente API faz `POST .../exports` para o `shared-usage-api`
   com `resource: "company-{nfse|nfe}-inbound-{xml|pdf|analytical-csv}"`.
2. O `shared-usage-api` cria um `ExportJob` no Azure Storage (state:
   Pending) e publica mensagem na fila Rebus.
3. Um Azure Function (`AzExport`) pega a mensagem, instancia o
   `IExporter` correspondente (ex.: `NfeInboundAnalyticalDataExporter`),
   e começa o processamento.
4. O exporter consome **a mesma API pública do
   `dfetech-distribution-api`** — exatamente os mesmos endpoints que
   sua integração usaria (`GET /v2/companies/{id}/inbound/nfse?type=Nfse`,
   `GET /{id}`, `GET /{id}/xml`, etc.). Não há atalho privado.
5. À medida que o exporter recebe dados, vai escrevendo em arquivo temp
   local. Quando termina (todos os dias do período processados), sobe o
   arquivo para o blob storage final.
6. Gera URL pré-assinada (HMAC, válida por 7 dias) e dispara
   notificação por e-mail via `notification-sender-api`.

> **Por que esse design?** Porque centralizar exportações num único
> serviço permite **observabilidade unificada** (todas as exportações
> de NF-e, NFS-e, CT-e, faturas de uso, relatórios, etc. passam pelo
> mesmo pipeline e gravam log no mesmo lugar) e **escala
> independentemente** da API principal — picos de exportação (fechamento
> de mês) não impactam latência de quem está consultando uma nota
> individual.

---

## 12. Manifestação de Documentos — O que é e Por que Importa

### O que é a Manifestação?

A manifestação é a forma como **você comunica à SEFAZ ou SEFIN** o que aconteceu com um documento destinado à sua empresa. É um processo legalmente relevante para empresas que utilizam a Escrituração Fiscal Digital (EFD).

### Manifestação de NF-e

#### Por que é importante?

A SEFAZ precisa saber se você:

- Recebeu a mercadoria conforme descrito na NF-e
- Não reconhece aquela operação
- A operação não foi concluída (mercadoria devolvida, por exemplo)

Sem a manifestação, você pode ter problemas em auditorias fiscais.

#### Prazos para Manifestar NF-e

Os prazos são contados a partir da **data de autorização** da NF-e pela SEFAZ:

| Tipo de Manifestação | Prazo Máximo |
|---|---|
| **Ciência da Operação** | Sem prazo fixo, mas recomendado o quanto antes |
| **Confirmação da Operação** | 180 dias após a autorização da NF-e |
| **Desconhecimento da Operação** | 180 dias após a autorização da NF-e |
| **Operação Não Realizada** | 180 dias após a autorização da NF-e |

> **Atenção:** Após 180 dias sem manifestação de confirmação, desconhecimento ou operação não realizada, a SEFAZ pode considerar a operação como confirmada automaticamente. Mantenha seus registros em dia.

#### Tipos de Manifestação de NF-e

##### Ciência da Operação

**O que significa:** "Eu sei que existe esta NF-e destinada para mim."

Esta é a manifestação mais básica e deve ser feita assim que você toma conhecimento da NF-e. **Não confirma recebimento físico.**

**Quando usar:** Sempre que uma NF-e chegar para sua empresa — mesmo que você ainda não tenha recebido a mercadoria.

##### Confirmação da Operação

**O que significa:** "Recebi a mercadoria exatamente como descrito nesta NF-e."

**Quando usar:** Após conferir que a mercadoria chegou e está de acordo com o que foi faturado.

##### Desconhecimento da Operação

**O que significa:** "Não reconheço esta operação — não comprei nada disso."

**Quando usar:** Quando chega uma NF-e de uma compra que sua empresa não realizou. Pode ser uma fraude ou erro do emitente.

> Atenção: Use com cuidado. Esta manifestação tem implicações legais e pode acionar investigação da SEFAZ sobre o emitente.

**O que fazer se suspeitar de fraude:**

1. Registre o **Desconhecimento da Operação** imediatamente
2. Documente a ocorrência internamente
3. Se identificar uso indevido do seu CNPJ, registre um **Boletim de Ocorrência** e notifique a Receita Federal
4. Entre em contato com sua assessoria jurídica ou contábil

##### Operação Não Realizada

**O que significa:** "A operação estava prevista, mas não foi concluída."

**Quando usar:** Quando a mercadoria foi devolvida, o pedido foi cancelado após a emissão da NF-e, ou qualquer situação onde a operação não se concretizou conforme descrito.

### Manifestação de NFS-e

Diferente da NF-e, a NFS-e do padrão nacional aceita apenas **duas** manifestações pelo tomador:

#### Ciência (código `203202`)

**O que significa:** "Estou ciente desta NFS-e destinada ao meu CNPJ."

**Quando usar:** Sempre que uma NFS-e chegar para sua empresa. É o equivalente à Ciência da Operação da NF-e.

#### Rejeição (código `203206`)

**O que significa:** "Rejeito esta NFS-e — não reconheço ou há inconsistência."

**Quando usar:** Quando a NFS-e recebida tem algum problema fiscal ou não corresponde a nenhum serviço que sua empresa tomou.

A Rejeição exige um **motivo codificado** (ver [seção 6](#6-nota-fiscal-de-serviços-eletrônica-nfs-e)) e pode incluir uma **justificativa em texto livre** (até 255 caracteres).

> Não existem eventos de "Confirmação de Operação" ou "Operação Não Realizada" para NFS-e — a natureza imaterial do serviço não comporta esses conceitos.

### Manifestação Automática

O serviço pode registrar automaticamente a manifestação de Ciência:

- **NF-e**: registra **Ciência da Operação** após o delay configurado (ex.: 60 minutos)
- **NFS-e**: registra **Ciência** (`203202`) após o delay configurado (ex.: 3.600 segundos = 1 hora)

**Vantagens:**

- Você não precisa manifestar manualmente cada documento
- Garante conformidade legal de forma automática
- Economiza tempo

**Importante:** A manifestação automática registra apenas a **Ciência**. Você ainda precisa registrar manualmente:

- **NF-e**: Confirmação da Operação, Desconhecimento ou Operação Não Realizada quando aplicável
- **NFS-e**: Rejeição (`203206`) quando aplicável

### Como Manifestar Manualmente

**No painel:**

1. Abra o documento
2. Clique em **"Manifestar"**
3. Escolha o tipo de manifestação
4. Para Rejeição de NFS-e ou Desconhecimento/Operação Não Realizada de NF-e, informe o motivo/justificativa
5. Clique em **"Enviar"**

**Via API:** sua equipe de TI pode acionar a manifestação diretamente do ERP — veja o guia técnico para desenvolvedores.

O resultado da manifestação (aceite ou rejeição pela SEFAZ/SEFIN) chega via webhook, na API (`GET /manifestations/{id}`) ou no painel.

---

## 13. Notificações Automáticas (Webhooks)

### O que é um Webhook?

Um webhook é uma **notificação automática** que enviamos para o seu sistema assim que um evento acontece — como quando uma NF-e, CT-e ou NFS-e nova é recebida.

Funciona como um "aviso automático": em vez de você ficar perguntando periodicamente "chegou algum documento novo?", nós avisamos você no momento exato em que algo acontece.

### Para que serve?

Com webhooks, seu sistema pode:

- Importar automaticamente NF-es, CT-es e NFS-es para o ERP
- Iniciar o processo de conferência de mercadoria automaticamente
- Gerar alertas quando chegam documentos de alto valor
- Sincronizar dados fiscais em tempo real
- Liberar pagamentos a fornecedores mediante chegada da nota correspondente

### Eventos que disparam um Webhook

| Evento | Quando dispara |
|---|---|
| `inbound.nfe.received` | Nova NF-e capturada |
| `inbound.nfe.event.received` | Novo evento de NF-e (cancelamento, CC-e, manifestação) |
| `inbound.cte.received` | Novo CT-e capturado |
| `inbound.cte.event.received` | Novo evento de CT-e |
| `inbound.nfse.received` | Nova NFS-e capturada |
| `inbound.nfse.event.received` | Novo evento de NFS-e (inclui manifestações de outros atores) |
| `inbound.manifestation.submitted` | Resultado de manifestação submetida pela sua empresa |

### Como Configurar?

1. Acesse o Painel nfe.io → **Webhooks**
2. Clique em **"Adicionar URL"**
3. Informe a URL do endpoint no seu sistema que vai receber as notificações
4. Selecione os eventos que deseja receber
5. (Opcional) Adicione cabeçalhos customizados se seu endpoint exige autenticação
6. Clique em **"Testar"** para validar
7. Salve e ative

Sua equipe de TI precisará criar um endpoint (uma URL) que recebe e processa as notificações.

### O que você recebe na notificação?

Quando um documento chega, enviamos uma notificação com:

- Tipo do evento
- Chave de acesso do documento
- NSU
- Data de emissão
- Dados do emitente/prestador
- Valor total / valor do serviço

Com esses dados, seu sistema pode buscar o XML completo via API se necessário.

### Reentrega de Webhooks

Se o seu endpoint responder com erro (status HTTP 4xx/5xx) ou estiver fora do ar, o sistema **tenta novamente automaticamente** com backoff exponencial por até **24 horas**. Se após o limite ainda não tivermos sucesso, marcamos a entrega como falha — mas o documento fica disponível para consulta via painel ou API (nenhum dado é perdido).

### Reprocessando uma Notificação

Se você quiser receber novamente uma notificação específica (por exemplo, após corrigir um bug no seu endpoint):

- Via painel: abra o documento → **"Reprocessar Webhook"**
- Via API: endpoint de reprocessamento (consulte o guia técnico)

---

## 14. Segurança e Privacidade dos Dados

### Onde os dados ficam armazenados?

Todos os XMLs e metadados dos seus documentos fiscais são armazenados em servidores na nuvem com:

- **Criptografia em trânsito:** Toda comunicação usa HTTPS/TLS 1.2+
- **Criptografia em repouso:** Os arquivos XML são armazenados com criptografia no storage
- **Acesso isolado:** Os dados da sua empresa são acessíveis apenas com sua API Key ou credenciais de usuário — nenhum outro cliente da plataforma tem acesso aos seus documentos

### Por quanto tempo os dados ficam armazenados?

Os XMLs e metadados ficam armazenados por no mínimo **5 anos**, em conformidade com o prazo de guarda exigido pela legislação fiscal brasileira (Art. 195 do CTN).

Após esse período, os dados podem ser arquivados ou excluídos conforme a política de retenção da plataforma. Você será notificado antes de qualquer exclusão.

### LGPD — Lei Geral de Proteção de Dados

O processamento dos dados fiscais pela nfe.io está em conformidade com a **Lei nº 13.709/2018 (LGPD)**:

- Os dados são tratados com base legal na **obrigação legal** (art. 7º, II) — a guarda de documentos fiscais é exigida pela legislação tributária
- Não compartilhamos seus dados fiscais com terceiros sem sua autorização explícita
- Você pode solicitar relatório de dados pessoais tratados pela plataforma através do suporte

### Quem pode acessar os meus documentos?

Apenas:

1. **Usuários da sua conta** com as permissões corretas
2. **Sistemas integrados** que usam sua API Key
3. **Equipe de suporte nfe.io** em caso de acionamento para investigar problemas — sempre com registro de acesso

### E o certificado digital?

Seu certificado digital A1 é armazenado com **criptografia adicional**. A senha que você informou não é armazenada em texto puro — é usada apenas no momento de carregar o certificado para comunicação com a SEFAZ/SEFIN.

Recomendamos **renovar o certificado periodicamente** e **revogar imediatamente** caso suspeite de uso indevido.

---

## 15. Reforma Tributária — O que Muda para Minha Empresa?

A **Lei Complementar 214/2025** introduziu a Reforma Tributária brasileira, criando novos tributos que substituirão gradualmente os impostos atuais sobre consumo — e também unificou o padrão da NFS-e em nível nacional.

### Os novos tributos em linguagem simples

| Novo Tributo | O que é | Substitui |
|---|---|---|
| **IBS** (Imposto sobre Bens e Serviços) | Imposto sobre consumo cobrado pelos estados e municípios | ICMS e ISS |
| **CBS** (Contribuição sobre Bens e Serviços) | Contribuição federal sobre consumo | PIS e COFINS |
| **IS** (Imposto Seletivo) | Imposto sobre produtos prejudiciais à saúde/ambiente | IPI (parcialmente) |

### O que muda na prática nas notas fiscais?

As NF-es, CT-es e NFS-es emitidas a partir da implementação da Reforma Tributária passarão a ter **novos campos** no XML para informar os valores de IBS, CBS e IS, além dos impostos tradicionais (ICMS, ISS, PIS, COFINS, etc.).

Nossa plataforma já está preparada para receber e processar documentos com esses novos campos. Você não precisa fazer nenhuma configuração adicional — a atualização é transparente.

### E a NFS-e?

A Reforma Tributária **criou o padrão nacional único da NFS-e** — é por isso que o subsistema NFS-e do DFe Inbound existe. Antes da LC 214/2025, cada prefeitura tinha seu próprio layout e portal. Agora:

- O layout é **único** em todo o Brasil
- A distribuição é **centralizada** no ADN da SEFIN Nacional
- A chave de acesso é **padronizada** em 50 dígitos

Municípios que ainda não migraram totalmente podem continuar a emitir localmente durante o período de transição — nesses casos, a nota é replicada no ADN.

### O que muda para quem recebe documentos?

Para empresas que recebem NF-es, CT-es e NFS-es (como destinatárias/tomadoras), as mudanças são:

- Os documentos que chegarem terão mais informações de impostos no XML
- O processo de recebimento e manifestação **não muda** — continua igual
- Os dados de IBS, CBS e IS estarão disponíveis na consulta via API e no painel quando aplicável

### Período de transição

A reforma prevê um **período de transição** de vários anos (até 2033). Durante esse período, os impostos antigos e os novos vão coexistir gradualmente. Isso significa que você vai receber documentos com os impostos antigos, com os novos, ou com ambos, dependendo do período e do fornecedor.

Nossa plataforma trata todos os formatos automaticamente.

### Preciso fazer algo agora?

Não. Do ponto de vista da **recepção de documentos**, nenhuma ação é necessária da sua parte. O sistema da nfe.io se adapta automaticamente às novas versões do leiaute das notas fiscais.

Para **emissão** de NF-es, CT-es ou NFS-es, consulte seu contador ou o emissor de notas que você utiliza.

---

## 16. Dúvidas Comuns

### O serviço cobre todos os documentos destinados ao meu CNPJ?

Sim. O DFe Inbound consulta os **Ambientes Nacionais** correspondentes:

- NF-e e CT-e → SEFAZ Ambiente Nacional
- NFS-e → SEFIN Nacional (ADN)

Esses ambientes concentram **todos os documentos destinados ao seu CNPJ**, independentemente do estado ou município emissor.

### Posso ativar só um dos subsistemas?

Sim. NF-e, CT-e e NFS-e são ativados **independentemente** por CNPJ. Se sua empresa só contrata serviços (sem compras de mercadoria), basta ativar NFS-e. Se só recebe produtos e fretes, ative NF-e e CT-e. A combinação é sua escolha.

### Qual a diferença entre webhook e listagem em lote?

- **Webhook:** notificação automática em tempo real. Cada documento novo gera uma notificação HTTP para o seu sistema assim que ele é recebido. Ideal para o fluxo normal do dia a dia.
- **Listagem em lote:** você faz uma requisição pontual à API e recebe vários documentos de uma vez. Ideal para sincronização inicial de histórico, recuperação após indisponibilidade do seu sistema, auditorias e relatórios consolidados.

O ideal é usar **os dois mecanismos em conjunto** — webhooks para o tempo real e listagem em lote para situações específicas. Veja a [seção 10](#10-listagem-em-lote-via-api--para-grandes-volumes) para mais detalhes.

### Documentos emitidos antes da ativação aparecem?

- **NF-e e CT-e:** sim, **até 90 dias antes** da ativação (limite da SEFAZ).
- **NFS-e:** sim, desde o início da disponibilidade no ADN (a SEFIN mantém histórico mais longo que a SEFAZ nos primeiros anos do padrão).

Se você precisar de documentos mais antigos que esses limites, será necessário obtê-los diretamente com o emitente.

### O que acontece se a SEFAZ ou SEFIN ficar fora do ar?

Nosso sistema fica tentando a consulta periodicamente. Quando o ambiente voltar, ele retoma de onde parou e busca todos os documentos que chegaram durante a indisponibilidade. Nenhum documento é perdido.

### Posso receber documentos de mais de um CNPJ?

Sim. Você pode ativar o serviço para cada CNPJ da sua empresa separadamente. Cada CNPJ tem sua própria configuração de inbound (por subsistema).

### Meu fornecedor diz que emitiu a nota, mas não aparece no sistema. O que fazer?

1. Aguarde o tempo de sincronização: até 4h para NF-e/CT-e, até alguns minutos para NFS-e
2. Verifique se o CNPJ destinatário/tomador da nota é o mesmo que está configurado
3. Confirme com o fornecedor se a nota foi **autorizada** pela SEFAZ/SEFIN (não apenas emitida localmente)
4. Para NFS-e: confirme que o município emitente aderiu ao padrão nacional — municípios em transição podem ter latência adicional
5. Se o problema persistir, entre em contato com o suporte nfe.io informando a chave de acesso

### Qual a diferença entre NF-e e NFC-e?

| Documento | Modelo | Uso |
|---|---|---|
| NF-e | 55 | Venda entre empresas (B2B) |
| NFC-e | 65 | Venda para consumidor final (B2C) — substitui o cupom fiscal |

O serviço de inbound foca em NF-e (modelo 55), pois são as notas destinadas à sua empresa.

### Qual a diferença entre NFS-e e NF-e?

- **NF-e** cobre venda de **produtos/mercadorias**
- **NFS-e** cobre prestação de **serviços**

Uma mesma empresa pode emitir tanto NF-e quanto NFS-e, dependendo de o que está vendendo. Como destinatário, você pode receber dos dois tipos e cada um é tratado pelo subsistema correspondente.

### Preciso pagar por cada documento recebido?

Depende do seu plano na nfe.io. Consulte a tabela de preços ou entre em contato com nosso time comercial.

### O serviço funciona em ambiente de testes (homologação)?

Sim. Para cada subsistema, você pode configurar o ambiente:

- **NF-e/CT-e**: ambiente SEFAZ (Produção ou Homologação)
- **NFS-e**: ambiente SEFIN (Produção ou Homologação)

Documentos de homologação não têm validade fiscal — use apenas para testes de integração.

### O que fazer se chegar um documento que parece fraude?

1. **Não confirme** a operação
2. Registre o **Desconhecimento da Operação** (NF-e) ou a **Rejeição** (NFS-e, código `203206` com motivo apropriado) imediatamente na plataforma
3. Verifique com seu departamento financeiro se houve alguma compra/serviço que não reconhece
4. Se confirmar fraude, registre um Boletim de Ocorrência (BO) e notifique a Receita Federal pelo e-CAC
5. Contate sua assessoria jurídica para avaliar as medidas cabíveis

---

## 17. Glossário

| Termo | Definição |
|---|---|
| **ADN** | Ambiente de Distribuição Nacional — sistema central da SEFIN Nacional que concentra NFS-e do padrão nacional unificado |
| **AN** | Ambiente Nacional — sistema central da SEFAZ que concentra NF-e e CT-e de todos os estados |
| **API** | Interface de Programação de Aplicações — conjunto de endpoints HTTP que permitem que sistemas externos interajam com a plataforma nfe.io |
| **API Key** | Chave secreta de autenticação usada por sistemas para se identificar ao consumir a API nfe.io |
| **CBS** | Contribuição sobre Bens e Serviços — novo tributo federal criado pela Reforma Tributária (substitui PIS e COFINS) |
| **Circuit Breaker** | Mecanismo que desativa automaticamente a captura de uma empresa após muitas falhas consecutivas, para evitar punição por rate limit. Requer reativação manual após correção |
| **CNPJ** | Cadastro Nacional da Pessoa Jurídica — número de identificação fiscal da empresa |
| **Conta guarda-chuva** | Conta principal da nfe.io que agrupa todos os CNPJs, usuários e permissões de um mesmo grupo econômico |
| **CT-e** | Conhecimento de Transporte Eletrônico — documento fiscal obrigatório para transporte de cargas |
| **Cursor (paginação cursor-based)** | Técnica de paginação em que o ponto de continuação é um valor sequencial (NSU) em vez de um número de página |
| **DACTE** | Documento Auxiliar do CT-e — representação visual em PDF do CT-e |
| **DANFE** | Documento Auxiliar da NF-e — representação visual em PDF da NF-e |
| **DANFSe** | Documento Auxiliar da NFS-e — representação visual em PDF da NFS-e |
| **DFe** | Documento Fiscal Eletrônico — termo genérico para documentos fiscais digitais (NF-e, CT-e, NFS-e) |
| **DPS** | Declaração de Prestação de Serviço — XML submetido pelo prestador à SEFIN **antes** da autorização da NFS-e |
| **EFD** | Escrituração Fiscal Digital — obrigação de escriturar os documentos fiscais digitalmente |
| **Evento** | Ação que modifica ou complementa um documento fiscal (cancelamento, correção, manifestação) |
| **Homologação** | Ambiente de testes da SEFAZ/SEFIN — documentos sem validade fiscal real |
| **IBS** | Imposto sobre Bens e Serviços — novo tributo estadual/municipal criado pela Reforma Tributária (substitui ICMS e ISS) |
| **Inbound** | Recebimento — neste contexto, recepção de documentos fiscais de terceiros |
| **IS** | Imposto Seletivo — novo tributo sobre produtos prejudiciais à saúde ou ao meio ambiente |
| **Listagem em lote** | Consulta à API que retorna vários documentos de uma só vez (em páginas), em vez de um a um |
| **LC 214/2025** | Lei Complementar da Reforma Tributária — introduziu IBS, CBS e IS no sistema tributário brasileiro, e criou o padrão nacional da NFS-e |
| **LGPD** | Lei Geral de Proteção de Dados — lei brasileira que regula o tratamento de dados pessoais |
| **Manifestação** | Comunicado do destinatário/tomador à SEFAZ/SEFIN sobre o que aconteceu com um documento |
| **NF-e** | Nota Fiscal Eletrônica — documento fiscal digital para venda de produtos entre empresas (modelo 55) |
| **NFC-e** | Nota Fiscal de Consumidor Eletrônica — nota para venda ao consumidor final (modelo 65) |
| **NFS-e** | Nota Fiscal de Serviços Eletrônica — documento fiscal para prestação de serviços (padrão nacional LC 214/2025) |
| **NSU** | Número Sequencial Único — contador de documentos fiscais por CNPJ, atribuído pelo ambiente nacional (AN ou ADN). Também funciona como cursor de paginação nas listagens em lote |
| **OData** | Protocolo padronizado de consulta REST utilizado por alguns endpoints de listagem em lote |
| **Prestador** | Quem presta o serviço e emite a NFS-e — equivalente ao emitente na NF-e |
| **Rejeição (NFS-e)** | Manifestação do tomador indicando que a NFS-e não é reconhecida ou tem inconsistência (evento `203206`) |
| **SEFAZ** | Secretaria da Fazenda — órgão estadual responsável pela administração tributária (NF-e, CT-e) |
| **SEFIN Nacional** | Secretaria Especial da Fazenda Nacional — órgão federal responsável pelo padrão nacional da NFS-e |
| **Tomador** | Quem contrata e paga pelo serviço — equivalente ao destinatário na NF-e |
| **Webhook** | Notificação automática enviada para um sistema externo quando um evento ocorre |
| **XML** | Formato do arquivo oficial de documentos fiscais eletrônicos |

---

*Para suporte, acesse [nfe.io/suporte](https://nfe.io/suporte) ou envie e-mail para suporte@nfe.io.*

*Esta documentação é mantida pela nfe.io. Versão atual: 2026-04-24.*

---

## DFe Inbound: Documentação para Desenvolvedores

Source: https://nfe.io/docs/documentacao/distribuicao/dfe-inbound-documentacao-tecnica-desenvolvedores/index.md

# Documentação Técnica para Desenvolvedores — DFe Inbound (nfe.io)

**Produto:** DFe Inbound — Recepção de NF-e e CT-e
**Público:** Desenvolvedores que integram sistemas com a API nfe.io
**Versão da API:** v2
**Atualizado em:** 2026-05-07

> 📑 **Este documento cobre os subsistemas NF-e e CT-e.** Para o subsistema
> **NFS-e Recebidas** (captura via ADN — Ambiente de Dados Nacional), consulte:
>
> - 02-doc-tecnica-clientes-dev-nfse-inbound-api.md — referência completa de endpoints REST do NFS-e
> - 02-doc-tecnica-clientes-dev-nfse-inbound-webhook.md — contrato dos webhooks do NFS-e
>
> Para a visão geral dos três subsistemas (NF-e, CT-e e NFS-e), abra
> README.md e [03-doc-funcional-clientes.md](/documentacao/distribuicao/dfe-inbound-documentacao-funcional-clientes).

## Fontes autoritativas

A API é descrita em três artefatos sincronizados. Em caso de divergência,
**o OpenAPI é a fonte canônica do contrato**:

| Artefato | Para quê | Conteúdo |
| --- | --- | --- |
| `openapi-inbound-api.yaml` (PT) / `.en.yaml` (EN) | Contrato da API | Schemas de request **e response** com `example` por schema, parâmetros, autenticação, todos os códigos de status (200/201/202/302/400/401/403/404/409/422/500). Importável em Swagger UI, Postman e geradores de cliente. |
| `DFeDistribution-Inbound-API-Full.postman_collection.json` (PT) / `.en.postman_collection.json` (EN) | Testes manuais | 55 endpoints com request body de exemplo + **`response[]` populado** (200, 202, 400, 404 conforme aplicável). Visível na aba **Examples** de cada request no Postman. |
| Este Markdown | Guia de integração | Visão narrativa dos fluxos NF-e/CT-e, dicas de implementação, troubleshooting e exemplos em código (curl/Python/Node/C#). |

> Para testes manuais, importe a Postman collection acima — todos os 55
> endpoints já trazem exemplo de resposta salvo (visível na aba **Examples**
> de cada request no Postman).

---

## Índice

1. [Introdução](#1-introdução)
2. [Guia de Primeiros Passos](#2-guia-de-primeiros-passos)
3. [Conceitos Fundamentais](#3-conceitos-fundamentais)
4. [Autenticação](#4-autenticação)
5. [URL Base e Ambientes](#5-url-base-e-ambientes)
6. [Ativando o Serviço de Inbound](#6-ativando-o-serviço-de-inbound)
7. [Endpoints de NF-e](#7-endpoints-de-nf-e)
8. [Endpoints de CT-e](#8-endpoints-de-ct-e)
9. [Listagem Paginada via OData (NF-e e CT-e)](#9-listagem-paginada-via-odata-nf-e-e-ct-e)
10. [Webhooks — Recebendo Notificações](#10-webhooks--recebendo-notificações)
11. [Referência de Tipos e Enums](#11-referência-de-tipos-e-enums)
12. [Tratamento de Erros](#12-tratamento-de-erros)
13. [Exemplos de Integração](#13-exemplos-de-integração)
14. [Perguntas Frequentes (FAQ)](#14-perguntas-frequentes-faq)

---

## 1. Introdução

O **DFe Inbound** da nfe.io é um serviço que **monitora automaticamente a SEFAZ** e captura todos os Documentos Fiscais Eletrônicos (NF-e e CT-e) emitidos por terceiros que têm como destinatário o CNPJ da sua empresa.

### O que você ganha com este serviço?

- **Recepção automática:** Sem precisar acessar o portal da SEFAZ manualmente.
- **XML armazenado:** Os XMLs ficam disponíveis para download via API a qualquer momento.
- **Notificações em tempo real:** Receba webhooks assim que um documento chegar.
- **Dados estruturados:** Consulte metadados (emitente, valor, data) sem precisar parsear XML.
- **Histórico completo:** Acesso a documentos recebidos nos últimos 90 dias (ou desde o NSU configurado).

### Visão Geral da Integração

```
SEFAZ (Ambiente Nacional)
  │
  │ (Polling automático via NSU)
  ▼
nfe.io DFe Inbound
  │
  ├──▶ Armazena XML no cloud storage
  ├──▶ Salva metadados (emitente, valor, data...)
  └──▶ Dispara Webhook ──▶ SEU SISTEMA
                              │
                              ├── Consulta metadados via API
                              └── Baixa XML via API
```

---

## 2. Guia de Primeiros Passos

Se você está integrando pela primeira vez, siga esta sequência em ordem. Não pule etapas.

### Etapa 1 — Obter credenciais

No painel nfe.io, crie uma API Key em **Configurações → Chaves de API**. Guarde-a com segurança — ela só é exibida uma vez.

### Etapa 2 — Localizar seu company_id

Em **Empresas**, clique na empresa que deseja integrar e copie o `company_id` exibido na URL ou nos detalhes da empresa.

### Etapa 3 — Ativar o inbound

Faça uma requisição para ativar o monitoramento do CNPJ:

```bash
curl -X POST \
  "https://api.nfse.io/v2/companies/SEU_COMPANY_ID/inbound/productinvoices" \
  --header "Authorization: SUA_API_KEY" \
  --header "Content-Type: application/json" \
  -d '{
    "StartFromNsu": 0,
    "EnvironmentSEFAZ": "Production",
    "WebhookVersion": 2
  }'
```

Resposta esperada: `{ "status": "Active", ... }`

### Etapa 4 — Configurar seu endpoint de webhook

No painel nfe.io, vá em **Webhooks** e cadastre a URL do seu servidor que vai receber as notificações.

Mínimo necessário no seu endpoint:

```python
# Python (Flask)
@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    access_key = data['accessKey']
    # Processar...
    return '', 200  # OBRIGATÓRIO retornar 200
```

### Etapa 5 — Verificar que documentos chegam

Após ativar, aguarde entre 15 minutos e 4 horas. Consulte documentos recebidos:

```bash
curl "https://api.nfse.io/v2/companies/SEU_COMPANY_ID/inbound/productinvoices/CHAVE_44_DIGITOS" \
  --header "Authorization: SUA_API_KEY"
```

### Etapa 6 — Migrar para produção

Quando seus testes estiverem OK com `"EnvironmentSEFAZ": "Test"`, recrie a configuração com `"Production"`:

```bash
# 1. Desativar o inbound de homologação
curl -X DELETE \
  "https://api.nfse.io/v2/companies/SEU_COMPANY_ID/inbound/productinvoices" \
  --header "Authorization: SUA_API_KEY"

# 2. Ativar com ambiente de produção
curl -X POST \
  "https://api.nfse.io/v2/companies/SEU_COMPANY_ID/inbound/productinvoices" \
  --header "Authorization: SUA_API_KEY" \
  --header "Content-Type: application/json" \
  -d '{
    "StartFromNsu": 0,
    "EnvironmentSEFAZ": "Production",
    "WebhookVersion": 2
  }'
```

> **Importante:** Documentos de ambiente `Test` (homologação SEFAZ) e `Production` são separados. Nunca misture os dois na mesma configuração.

---

## 3. Conceitos Fundamentais

### NSU — Número Sequencial Único

O NSU é um número mantido pela SEFAZ que cresce a cada documento recebido pelo seu CNPJ. Pense nele como um "contador de correspondências" da SEFAZ para a sua empresa.

Exemplo:

- NSU 1000: NF-e de fornecedor A, valor R$ 500
- NSU 1001: NF-e de fornecedor B, valor R$ 1.200
- NSU 1002: Evento de cancelamento da NF-e do fornecedor A

Nosso serviço consulta a SEFAZ periodicamente e baixa todos os documentos a partir do último NSU processado.

### Chave de Acesso (access_key)

É um código de **44 dígitos** que identifica unicamente uma NF-e ou CT-e. Exemplo:

```
35240112345678000195550010000012341234567890
│  │ │              │    │  │
│  │ │              │    │  └─── Dígito verificador
│  │ │              │    └────── Número NF-e
│  │ │              └─────────── Série
│  │ └────────────────────────── CNPJ emitente
│  └──────────────────────────── Mês/Ano emissão (AAAAMM)
└─────────────────────────────── UF (35 = SP)
```

Para **eventos** (cancelamento, ciência, etc.), a chave tem **55 dígitos**.

### Identificando o tipo de documento pela chave

A posição 20-21 da chave de acesso (0-indexed) indica o modelo do documento:

| Posição 20-21 | Tipo | Descrição |
|---|---|---|
| `55` | NF-e | Nota Fiscal Eletrônica |
| `57` | CT-e | Conhecimento de Transporte Eletrônico |
| `65` | NFC-e | Nota Fiscal de Consumidor |
| `67` | CT-eOS | CT-e para Outros Serviços |

```python
def get_document_type(access_key: str) -> str:
    model = access_key[20:22]  # posições 20 e 21
    types = {"55": "NF-e", "57": "CT-e", "65": "NFC-e", "67": "CT-eOS"}
    return types.get(model, "Desconhecido")
```

### Tipos de Registro retornados pela API

| MetadataResourceType | Significado |
|---|---|
| `productInvoice` | NF-e completa (XML disponível) |
| `productInvoiceEvent` | Evento de NF-e (cancelamento, ciência, etc.) |
| `productInvoiceSummary` | Resumo de NF-e (apenas metadados básicos) |
| `productInvoiceEventSummary` | Resumo de evento |
| `transportationInvoice` | CT-e completo |
| `transportationInvoiceEvent` | Evento de CT-e |

---

## 4. Autenticação

Todas as requisições exigem autenticação. Suportamos dois métodos:

### Método 1 — API Key (recomendado para integração server-to-server)

Passe a chave de API no header `Authorization`:

```http
Authorization: SUA_API_KEY_AQUI
```

Onde obter a API Key: Painel nfe.io → Configurações → Chaves de API.

### Método 2 — Bearer Token (JWT)

Use um token JWT gerado via `https://id.nfe.io`:

```http
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```

### Exemplo de Requisição com Autenticação

```bash
curl -X GET \
  "https://api.nfse.io/v2/companies/comp_123/inbound/productinvoices" \
  --header "Authorization: sk_live_abc123..."
```

---

## 5. URL Base e Ambientes

A API tem **uma única URL base** para todos os clientes:

```
https://api.nfse.io
```

Não existe um host separado para testes. Para emitir/receber documentos em ambiente de homologação da SEFAZ (sem validade fiscal), use o campo `EnvironmentSEFAZ: "Test"` no corpo da requisição de ativação do inbound — ver §6. O switch entre homologação e produção é feito por configuração, não trocando de host.

**Estrutura da URL:**

```
https://api.nfse.io/v2/companies/{company_id}/inbound/...
```

O `company_id` é o identificador da sua empresa na plataforma nfe.io (encontrado no Painel → Empresas).

---

## 6. Ativando o Serviço de Inbound

Antes de receber documentos, você precisa ativar o serviço de inbound para cada CNPJ que deseja monitorar.

### Ativar Inbound de NF-e

```http
POST /v2/companies/{company_id}/inbound/productinvoices
Authorization: {api_key}
Content-Type: application/json

{
  "StartFromNsu": 0,
  "EnvironmentSEFAZ": "Production",
  "AutomaticManifesting": {
    "MinutesToWaitAwarenessOperation": 60
  },
  "WebhookVersion": 2
}
```

**Campos do corpo:**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `StartFromNsu` | `long` | Não | NSU inicial. `0` = busca desde o início. Use um NSU específico para sincronizar com histórico |
| `EnvironmentSEFAZ` | `string` | Sim | `"Production"` (produção SEFAZ) ou `"Test"` (homologação SEFAZ) |
| `EventType` | `string` | Não | Filtro de tipos de evento (códigos separados por vírgula). `null` = todos |
| `Schema` | `int` | Não | `0`=NF-e + Eventos, `1`=Somente NF-e, `2`=Somente Eventos |
| `AutomaticManifesting.MinutesToWaitAwarenessOperation` | `int` | Não | Minutos aguardados antes de auto-manifestar ciência. Mínimo: 5 |
| `WebhookVersion` | `int` | Não | Versão do formato de webhook. Use `2` (mais recente) |

**Resposta de sucesso (200):**

```json
{
  "companyId": "comp_123",
  "environmentSEFAZ": "Production",
  "startFromNsu": 0,
  "startFromDate": "2024-01-01T00:00:00Z",
  "status": "Active",
  "createdOn": "2024-03-15T10:30:00Z"
}
```

### Ativar Inbound de CT-e

```http
POST /v2/companies/{company_id}/inbound/transportationinvoices
Authorization: {api_key}
Content-Type: application/json

{
  "StartFromNsu": 0,
  "EnvironmentSEFAZ": "Production"
}
```

### Verificar Configuração Atual

```http
GET /v2/companies/{company_id}/inbound/productinvoices
Authorization: {api_key}
```

### Desativar Inbound

```http
DELETE /v2/companies/{company_id}/inbound/productinvoices
Authorization: {api_key}
```

---

## 7. Endpoints de NF-e

### Buscar Metadados de uma NF-e

Retorna os dados estruturados de uma NF-e pela sua chave de acesso.

```http
GET /v2/companies/{company_id}/inbound/productinvoices/{access_key}
Authorization: {api_key}
```

**Parâmetros de URL:**

- `company_id`: ID da sua empresa na nfe.io
- `access_key`: Chave de acesso de 44 dígitos da NF-e

**Resposta de sucesso (200):**

```json
{
  "accessKey": "35240112345678000195550010000012341234567890",
  "createdOn": "2024-03-15T14:22:10Z",
  "nsu": "21825",
  "nsuParent": null,
  "nfeNumber": "1234",
  "nfeSerialNumber": "1",
  "issuedOn": "2024-03-15T10:00:00Z",
  "type": "productInvoice",
  "description": "Autorizado o uso da NF-e",
  "totalInvoiceAmount": "1500.00",
  "operationType": "Incoming",
  "issuer": {
    "federalTaxNumber": "12345678000195",
    "name": "Fornecedor LTDA"
  },
  "buyer": {
    "federalTaxNumber": "98765432000100",
    "name": "Minha Empresa S.A."
  },
  "company": {
    "id": "comp_123",
    "federalTaxNumber": "98765432000100"
  },
  "links": {
    "xml": "https://storage.nfe.io/temp/xml/...",
    "pdf": "https://storage.nfe.io/temp/pdf/..."
  }
}
```

**Descrição dos campos:**

| Campo | Tipo | Descrição |
|---|---|---|
| `accessKey` | `string` | Chave de acesso 44 dígitos |
| `createdOn` | `DateTime` | Quando o documento entrou no sistema |
| `nsu` | `string` | Número Sequencial Único na SEFAZ |
| `nfeNumber` | `string` | Número da NF-e |
| `nfeSerialNumber` | `string` | Série da NF-e |
| `issuedOn` | `DateTime` | Data de emissão |
| `type` | `string` | `productInvoice`, `productInvoiceEvent`, `productInvoiceSummary` |
| `description` | `string` | Status da NF-e (ex: "Autorizado o uso da NF-e") |
| `totalInvoiceAmount` | `string` | Valor total em reais |
| `operationType` | `string` | `Incoming` (destinatário) ou `Outgoing` (emitente) |
| `issuer` | `object` | Dados do emitente (quem emitiu a NF-e) |
| `buyer` | `object` | Dados do destinatário (comprador) |
| `links.xml` | `string` | URL temporária para download do XML (expira em 1 hora) |
| `links.pdf` | `string` | URL temporária para download do PDF/DANFE |

### Baixar XML de uma NF-e

```http
GET /v2/companies/{company_id}/inbound/productinvoices/{access_key}/xml
Authorization: {api_key}

# Retorna o arquivo XML diretamente (Content-Type: application/xml)
```

Alternativamente, use a URL temporária retornada em `links.xml` para download direto do storage (sem precisar passar pela API). Esse link expira em **1 hora**.

### Baixar PDF (DANFE) de uma NF-e

```http
GET /v2/companies/{company_id}/inbound/productinvoices/{access_key}/pdf
Authorization: {api_key}

# Retorna o arquivo PDF (Content-Type: application/pdf)
```

### Buscar Dados de um Evento de NF-e

Eventos são ações sobre a NF-e: cancelamento, ciência, confirmação de operação, etc.

```http
GET /v2/companies/{company_id}/inbound/productinvoices/{access_key}/events/{event_key}
Authorization: {api_key}
```

O `event_key` tem **55 dígitos** (chave de acesso da NF-e + código do evento + sequência).

### Registrar Manifestação

A manifestação é o processo pelo qual o destinatário comunica à SEFAZ que tem conhecimento da NF-e. É obrigatória para NF-es de entrada.

```http
POST /v2/companies/{company_id}/inbound/{access_key}/manifest?tpEvent=210210
Authorization: {api_key}
```

**Tipos de manifestação (tpEvent):**

| Código | Tipo | Descrição |
|---|---|---|
| `210210` | Ciência da Operação | "Estou ciente desta NF-e" (não confirma recebimento físico) |
| `210200` | Confirmação da Operação | "Recebi a mercadoria conforme NF-e" |
| `210220` | Desconhecimento da Operação | "Não reconheço esta operação" |
| `210240` | Operação não Realizada | "A operação não foi concluída" |

**Resposta (200):**

```json
"Manifestação registrada com sucesso"
```

> **Manifestação Automática:** Se você configurou `AutomaticManifesting.MinutesToWaitAwarenessOperation`, o sistema registrará "Ciência da Operação" automaticamente após esse intervalo. Você não precisa chamar este endpoint para ciência se tiver auto-manifestação ativa.

### Reprocessar Webhook de uma NF-e

Use quando o webhook não foi entregue ou precisa ser reenviado.

```http
POST /v2/companies/{company_id}/inbound/productinvoices/{access_key}/processwebhook
Authorization: {api_key}

# Ou por NSU:
POST /v2/companies/{company_id}/inbound/productinvoices/{nsu}/processwebhook
```

---

## 8. Endpoints de CT-e

### Ativar e Configurar CT-e

Veja a seção [Ativando o Serviço de Inbound](#6-ativando-o-serviço-de-inbound) — o processo é idêntico ao NF-e mas no endpoint `/transportationinvoices`.

### Buscar Metadados de um CT-e

```http
GET /v2/companies/{company_id}/inbound/{access_key}
Authorization: {api_key}
```

**Resposta (200):**

```json
{
  "id": "abc123",
  "accessKey": "35240198765432000100570010000009871234567890",
  "parentAccessKey": "",
  "createdOn": "2024-03-15T14:22:10Z",
  "nsu": 10042,
  "type": "transportationInvoice",
  "description": "Autorizado o uso do CT-e",
  "company": {
    "id": "comp_123",
    "federalTaxNumber": "98765432000100"
  },
  "issuedOn": "2024-03-15T10:00:00Z",
  "xmlUrl": "https://api.nfse.io/v2/companies/comp_123/inbound/35240198765432000100570010000009871234567890/xml"
}
```

**Campos do CT-e:**

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | `string` | Id gerado pela plataforma. |
| `accessKey` | `string` | Chave de acesso 44 dígitos do CT-e. |
| `parentAccessKey` | `string` | Vazio em respostas REST de CT-e (só populado em eventos). |
| `createdOn` | `DateTime` | Quando o documento entrou no sistema. |
| `nsu` | `long` | NSU. **Atenção: em CT-e o NSU é numérico** (em NF-e é string). |
| `type` | `string` | Sempre `"transportationInvoice"` neste endpoint. |
| `description` | `string` | Status fixo: `"Autorizado o uso do CT-e"`. |
| `company` | `object` | Sua empresa nfe.io (`id`, `federalTaxNumber`). |
| `issuedOn` | `DateTime` | Data de emissão do CT-e. |
| `xmlUrl` | `string` | URL para download do XML via API (válida via `GET .../xml`). |

> **Observação:** dados de **emitente (transportadora), destinatário, tomador, expedidor, recebedor e valor total** **não** vêm nesta resposta REST. Esses campos só são entregues no **payload do webhook** de CT-e (`transportationInvoice` / `issued_successfully`). Para reprocessar o webhook e obter o payload completo, use o endpoint `processwebhook` documentado abaixo.

### Baixar XML de um CT-e

```http
GET /v2/companies/{company_id}/inbound/{access_key}/xml
Authorization: {api_key}

# Retorna o arquivo XML (Content-Type: application/xml)
```

### Reprocessar Webhooks de CT-e

```http
POST /v2/companies/{company_id}/inbound/transportationinvoices/reprocess/webhook
Authorization: {api_key}
Content-Type: application/json

{
  "Key": "35240198765432000100570010000009871234567890",
  "Date": "2024-03-15"
}
```

### Reprocessar NSUs Específicos

Útil quando um NSU falhou no processamento:

```http
PUT /v2/companies/{company_id}/inbound/transportationinvoices/reprocess/item
Authorization: {api_key}
Content-Type: application/json

[10042, 10043, 10044]
```

### Consolidação de Batch

Consolida batches em um intervalo de NSU:

```http
PUT /v2/companies/{company_id}/inbound/transportationinvoices/batch/consolidation
Authorization: {api_key}
Content-Type: application/json

{
  "StartNSU": 10000,
  "EndNSU": 10500
}
```

---

## 9. Listagem Paginada via OData (NF-e e CT-e)

Esses endpoints permitem **listar documentos em lote** com paginação cursor-based. São a forma mais eficiente de processar grandes volumes de documentos fiscais quando você precisa sincronizar um histórico completo ou fazer auditorias.

Existem quatro endpoints OData, todos sob o mesmo prefixo `/v2/companies/{company_id}/inbound/odata/`:

| Endpoint | Retorna | Filtro obrigatório |
| --- | --- | --- |
| `ProductInvoices` | Listagem de NF-e da sua empresa | `environmentType eq {1 ou 2}` |
| `ProductInvoiceEvents` | Listagem de eventos de uma NF-e específica | `accessKey eq '{chave_44_dígitos}'` |
| `TransportationInvoices` | Listagem de CT-e da sua empresa | `issuedOn eq {data_ISO}` |
| `TransportationInvoiceEvents` | Listagem de eventos de CT-e | `receiptOn eq {data_ISO}` |

### 9.1. Autenticação e permissões

- Endpoints `ProductInvoices` e `ProductInvoiceEvents` exigem role `Nota Fiscal (api.nfe.io)` **ou** `NFeDist (dfe.nfe.io)`.
- Endpoints `TransportationInvoices` e `TransportationInvoiceEvents` exigem role `Nota Fiscal (api.nfe.io)` **ou** `CTeDist (dfe.nfe.io)`.

### 9.2. Parâmetros OData suportados

| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `$filter` | string | **Sim** | Filtro simples no formato `propriedade eq valor`. Veja restrições abaixo. |
| `$top` | int | Não | Quantidade máxima de registros por página. **Máximo: 1000, padrão: 50**. |
| `$skiptoken` | long | Não | Cursor de paginação — use o `nsu` do último item da página anterior. |
| `$count` | bool | Não | Se `true`, inclui a contagem total na resposta. |

> **Restrição importante sobre `$filter`:** apenas expressões simples de igualdade (`prop eq valor`) são suportadas. Filtros compostos com `and`/`or` **não funcionam** — use um único predicado por requisição. Essa limitação existe para manter a performance dos índices MongoDB.

### 9.3. Paginação cursor-based via `$skiptoken`

A paginação funciona por cursor incremental usando o NSU (ascendente):

1. Cliente faz a primeira requisição **sem** `$skiptoken`.
2. API retorna até `$top` registros ordenados por `nsu` ascendente (do menor para o maior).
3. Cliente pega o `nsu` do **último** item retornado.
4. Cliente faz a próxima requisição passando esse valor em `$skiptoken`.
5. API retorna os próximos registros com `nsu` **maior** que o `$skiptoken`.
6. Quando a resposta vier com menos registros que `$top` (ou vazia), você chegou ao fim.

> A ordem é **sempre ascendente** (menor NSU primeiro). Você sempre começa pelos documentos mais antigos e avança no tempo.

### 9.4. Listar NF-e — `ProductInvoices`

```http
GET /v2/companies/{company_id}/inbound/odata/ProductInvoices?$filter=environmentType eq 1&$top=100
Authorization: {api_key}
```

**Valores aceitos para `environmentType`:**

| Valor | Significado |
| --- | --- |
| `1` | Produção |
| `2` | Homologação (testes) |

**Resposta (200):**

```json
{
  "@odata.context": "https://api.nfse.io/v2/companies/comp_123/inbound/odata/$metadata#ProductInvoices",
  "value": [
    {
      "accessKey": "35240612345678000195550010000012341123456789",
      "createdOn": "2026-04-09T10:30:00Z",
      "company": {
        "id": "comp_123",
        "federalTaxNumber": "12345678000195"
      },
      "type": "productInvoice",
      "nsu": 373289,
      "environmentType": 1,
      "issuedOn": "2026-04-08T14:00:00Z",
      "nfeNumber": "1234",
      "nfeSerialNumber": "1",
      "operationType": "Incoming",
      "totalInvoiceAmount": "1500.50",
      "federalTaxNumberSender": "98765432000100",
      "nameSender": "Fornecedor LTDA",
      "xmlUrl": "https://api.nfse.io/v2/companies/comp_123/inbound/3524.../xml"
    }
  ]
}
```

> **Atenção ao tipo de `nsu`:** neste endpoint OData o `nsu` é **`long` (número)**. Nos endpoints REST individuais (`/productinvoices/{access_key}`), o mesmo campo é **string**. Essa diferença é histórica e deve ser tratada no cliente conforme o contexto.

### 9.5. Listar Eventos de NF-e — `ProductInvoiceEvents`

```http
GET /v2/companies/{company_id}/inbound/odata/ProductInvoiceEvents?$filter=accessKey eq '35240612345678000195550010000012341123456789'&$top=50
Authorization: {api_key}
```

O filtro é **obrigatoriamente** por `accessKey` — a chave de acesso de 44 dígitos da NF-e pai. O fluxo típico é:

1. Listar NF-e via `ProductInvoices` (passo 9.4).
2. Para cada NF-e retornada, chamar `ProductInvoiceEvents` com a `accessKey` dela para obter os eventos relacionados (ciência, confirmação, cancelamento, CC-e, etc.).

**Resposta (200):**

```json
{
  "value": [
    {
      "id": "comp_123_abc_35240612345678000195550010000012341123456789110111",
      "createdOn": "2026-04-09T11:00:00Z",
      "company": {
        "id": "comp_123",
        "federalTaxNumber": "12345678000195"
      },
      "accessKey": "35240612345678000195550010000012341123456789",
      "type": "productInvoiceEvent",
      "nsu": 373290,
      "receiptOn": "2026-04-09T10:55:00Z",
      "description": "Ciência da Operação",
      "xmlUrl": "https://api.nfse.io/v2/companies/comp_123/inbound/3524.../xml"
    }
  ]
}
```

### 9.6. Listar CT-e — `TransportationInvoices`

```http
GET /v2/companies/{company_id}/inbound/odata/TransportationInvoices?$filter=issuedOn eq 2026-04-01&$top=100
Authorization: {api_key}
```

O filtro é **obrigatoriamente** pela data de emissão (`issuedOn`). Passe a data no formato `yyyy-MM-dd` (sem hora). A API retorna todos os CT-e emitidos exatamente **naquele dia**.

**Resposta (200):**

```json
{
  "value": [
    {
      "id": "comp_123_trans_35240198765432000100570010000009871234567890",
      "createdOn": "2026-04-01T14:22:10Z",
      "company": {
        "id": "comp_123",
        "federalTaxNumber": "98765432000100"
      },
      "accessKey": "35240198765432000100570010000009871234567890",
      "parentAccessKey": "",
      "type": "transportationInvoice",
      "nsu": 10042,
      "issuedOn": "2026-04-01T10:00:00Z",
      "description": "Autorizado o uso do CT-e",
      "xmlUrl": "https://api.nfse.io/v2/companies/comp_123/inbound/3524.../xml"
    }
  ]
}
```

### 9.7. Listar Eventos de CT-e — `TransportationInvoiceEvents`

```http
GET /v2/companies/{company_id}/inbound/odata/TransportationInvoiceEvents?$filter=receiptOn eq 2026-04-01&$top=100
Authorization: {api_key}
```

Similar ao endpoint de CT-e, mas o filtro é pela data de **recebimento** do evento (`receiptOn`), não pela data de emissão.

### 9.8. Exemplo completo de paginação (NF-e)

**Primeira página (sem `$skiptoken`):**

```bash
curl -G "https://api.nfse.io/v2/companies/comp_123/inbound/odata/ProductInvoices" \
  --header "Authorization: sk_live_abc123" \
  --data-urlencode '$filter=environmentType eq 1' \
  --data-urlencode '$top=100'
```

Suponha que a resposta contenha 100 NF-e e o último item tenha `nsu = 373388`.

**Próxima página (passando o último NSU como `$skiptoken`):**

```bash
curl -G "https://api.nfse.io/v2/companies/comp_123/inbound/odata/ProductInvoices" \
  --header "Authorization: sk_live_abc123" \
  --data-urlencode '$filter=environmentType eq 1' \
  --data-urlencode '$top=100' \
  --data-urlencode '$skiptoken=373388'
```

**Critério de parada:** quando a resposta vier com `value` vazio **ou** com menos itens que `$top`, você chegou ao fim dos registros.

### 9.9. Erros comuns e troubleshooting

| Erro | Causa | Como corrigir |
| --- | --- | --- |
| **400** `filter environmentType eq is required` | O `$filter` está ausente ou malformado | Adicione `$filter=environmentType eq 1` (ou `2`) na URL |
| **400** `filter accessKey eq is required` | Faltou o filtro por `accessKey` em `ProductInvoiceEvents` | Adicione `$filter=accessKey eq '{chave_44}'` |
| **400** `Could not find a property named 'X'` | Nome da propriedade no filtro está errado (case sensitive) | Use exatamente `environmentType`, `accessKey`, `issuedOn`, `receiptOn` |
| **400** `The query specified in the URI is not valid` com `and`/`or` | Tentativa de filtro composto | Use **apenas um** predicado simples por requisição |
| **401** `Unauthorized` | API Key ausente ou inválida | Verifique o header `Authorization` |
| **403** `Forbidden` | API Key sem a role correta | Confirme se a role inclui `Nota Fiscal (api.nfe.io)` ou a role específica do endpoint |
| **Página vazia** na primeira requisição | Não há dados no ambiente solicitado | Verifique se está consultando o ambiente correto (`environmentType eq 1` vs `2`) |

---

## 10. Webhooks — Recebendo Notificações

> 📘 **Doc dedicada:** o contrato completo do webhook (envelope, payloads
> por evento, validação HMAC, reprocessamento) está em
> **[02-doc-tecnica-clientes-dev-nfe-cte-inbound-webhook.md](/documentacao/distribuicao/dfe-inbound-webhook-nfe-cte)**.
> Esta seção contém apenas o resumo essencial.

### Como configurar

1. Acesse o Painel nfe.io → Empresas → \{sua empresa\} → Webhooks.
2. Cadastre a URL do seu endpoint HTTPS.
3. Configure o **Webhook Secret** (usado para validação HMAC-SHA256).
4. Ative o inbound (seção 6) com `WebhookVersion: 2`.

### Famílias de evento entregues

Quando um documento ou evento é recebido, fazemos um `POST` para sua URL.
O envelope traz `body.type` (um de seis valores: `productInvoice`,
`productInvoiceEvent`, `productInvoiceSummary`,
`productInvoiceEventSummary`, `transportationInvoice`,
`transportationInvoiceEvent`) e `body.action` (`issued_successfully`,
`event_raised_successfully`, `input_event_raised_successfully`). A tabela
completa de pares `body.type` × `body.action` e o payload de cada um estão
na §12 da **doc dedicada** acima.

### Resposta esperada

- Seu endpoint deve retornar **HTTP 2xx** em até **30 segundos**.
- Em caso de falha, retentamos até **50x em 24h** com backoff exponencial.
- Status 4xx (exceto 408/429) marca a entrega como `DefinitivelyFailed`
  (sem retry). Use `POST .../processwebhook` para reprocessar manualmente.

---

## 11. Referência de Tipos e Enums

### EnvironmentSEFAZ

| Valor | Descrição |
|---|---|
| `"Test"` | Ambiente de homologação SEFAZ — documentos sem validade fiscal |
| `"Production"` | Ambiente de produção SEFAZ — documentos com validade fiscal real |

### OperationType

| Valor | Descrição |
|---|---|
| `"Incoming"` | Você é o destinatário (recebeu o documento) |
| `"Outgoing"` | Você é o emitente (emitiu o documento) |

### MetadataResourceType

| Valor | Descrição |
|---|---|
| `"productInvoice"` | NF-e completa |
| `"productInvoiceEvent"` | Evento de NF-e |
| `"productInvoiceSummary"` | Resumo de NF-e (sem XML completo) |
| `"productInvoiceEventSummary"` | Resumo de evento de NF-e |
| `"transportationInvoice"` | CT-e |
| `"transportationInvoiceEvent"` | Evento de CT-e |

### EntityStatus

| Valor | Descrição |
|---|---|
| `"Active"` | Configuração ativa — sistema monitorando |
| `"Inactive"` | Configuração inativa — sem monitoramento |

### Campo `relatedIds` em NFeMetadata

A collection `NFeMetadata` possui o campo `relatedIds` (array de strings) que armazena os **IDs dos eventos** relacionados àquela NF-e. Esse campo é populado automaticamente pelo worker `DFeTech.App.Inbound.NFe` sempre que um `NFeEventMetadata` é persistido:

| Propriedade | Tipo | Descrição |
| --- | --- | --- |
| `relatedIds` | `string[]` | IDs dos eventos (`{accountId}_{companyId}_{eventId}`) vinculados a esta NF-e |

**Semântica:**

- O link é **implícito via `accessKey`** — o worker identifica a NF-e pai pelo `accessKey` compartilhado entre NF-e e seus eventos
- A operação de append é **atômica e idempotente** no MongoDB (usa `$addToSet`)
- Se a NF-e pai ainda não existir quando o evento chegar (ordem de chegada não garantida pela SEFAZ), o evento é persistido normalmente e apenas um `warning` é logado — **o link não é criado retroativamente nessa versão**
- Documentos antigos (persistidos antes desta implementação) podem não ter o campo `relatedIds` — o consumidor deve tratar ausência/null como array vazio

**Exemplo de documento:**

```json
{
  "_id": "acc-1_comp-1_35240612345678000195550010000012341123456789",
  "accountId": "acc-1",
  "companyId": "comp-1",
  "accessKey": "35240612345678000195550010000012341123456789",
  "nsu": 373289,
  "environmentType": 1,
  "relatedIds": [
    "acc-1_comp-1_35240612345678000195550010000012341123456789110111",
    "acc-1_comp-1_35240612345678000195550010000012341123456789110222"
  ]
}
```

---

## 12. Tratamento de Erros

### Formato do Erro

Quando ocorre um erro, a API retorna um JSON no seguinte formato:

```json
{
  "errors": [
    {
      "code": 404,
      "message": "Document not found for the given access key."
    }
  ]
}
```

### Códigos HTTP

| HTTP | Significa | O que fazer |
| --- | --- | --- |
| `200` | Sucesso | Processe a resposta normalmente |
| `202` | Aceito (assíncrono) | Operação enfileirada — acompanhe via webhook ou GET correspondente |
| `204` | Sucesso sem conteúdo | Operação realizada, sem corpo de resposta |
| `302` | Redirect | Quando um endpoint redireciona para uma URL assinada, siga o header `Location` (a maioria dos clientes HTTP faz isso automaticamente) |
| `400` | Requisição inválida | Verifique os parâmetros enviados |
| `401` | Não autorizado | Verifique sua API Key ou token |
| `403` | Proibido | API Key sem a *policy* exigida (`NFeDist`/`CTeDist`) |
| `404` | Não encontrado | O documento/empresa não existe |
| `409` | Conflito (duplicado) | Recurso já existe |
| `422` | Entidade não processável | Dados válidos mas não processáveis (ex: NF-e cancelada) |
| `503` | Serviço indisponível | SEFAZ temporariamente fora. Tente novamente em alguns minutos |
| `504` | Timeout | A operação demorou muito. Tente novamente |
| `500` | Erro interno | Entre em contato com o suporte |

> **Formato do corpo de erro.** Os controllers que herdam de
> `ApiBaseController` (a grande maioria) devolvem o wrapper `ErrorsResource`
> (JSON `{ "errors": [{ "code", "message" }] }`) em qualquer 4xx/5xx — é o
> exemplo mostrado acima. Exceções (texto puro, **não** JSON):
>
> - `BadRequest("...")` direto — usado em validações de paginação e em alguns
>   filtros OData (ex.: `pageCount must not exceed 100`).
> - `NFSeDownloadController` (endpoint público `/blob/download`) — sempre
>   `text/plain` (`"Invalid parameters."`, `"Link expired."`, etc.).
>
> Para o shape exato por endpoint e a lista completa de status documentados,
> consulte `openapi-inbound-api.yaml`.

### Eventos NF-e (`tpEvento`) e códigos de retorno SEFAZ

Os eventos NF-e mais comuns retornados nos endpoints inbound e nas respostas
de `POST /manifest`:

| `tpEvento` | Nome | Quem emite | Quando aparece no inbound |
| --- | --- | --- | --- |
| `110110` | Carta de Correção (CC-e) | Emissor | Recebida automaticamente após autorização SEFAZ. |
| `110111` | Cancelamento | Emissor | Recebido automaticamente após autorização SEFAZ. |
| `210200` | Confirmação da Operação | Destinatário | Disparado por `POST /manifest?tpEvent=210200` ou pela política de manifestação automática. |
| `210210` | Ciência da Operação | Destinatário | **Default** de `POST /manifest`. |
| `210220` | Operação Não Realizada | Destinatário | Disparado manualmente — exige justificativa SEFAZ. |
| `210240` | Desconhecimento da Operação | Destinatário | Disparado manualmente quando a NF-e foi emitida indevidamente contra o CNPJ. |

Códigos `cStat` de retorno SEFAZ mais frequentes na operação de manifestação:

| `cStat` | Significado | Ação |
| --- | --- | --- |
| `135` | Evento registrado e vinculado | Sucesso. |
| `136` | Evento registrado, não vinculado | Sucesso parcial — chave pode estar incorreta. |
| `573` | Duplicidade de evento | Já existe evento de mesmo tipo. |
| `217` | NF-e não consta na base | Aguarde alguns minutos (latência SEFAZ). |
| `999` | Erro interno SEFAZ | Retentar após 5–10 min. |

Para a lista completa de `cStat`, consulte o [Manual de Orientação do
Contribuinte da SEFAZ](https://www.nfe.fazenda.gov.br/portal/manualOrientacao.aspx).

---

## 13. Exemplos de Integração

### Exemplo 1 — Buscar NF-e por Chave de Acesso (C#)

```csharp
using System.Net.Http;
using System.Text.Json;

public class NfeIoClient
{
    private readonly HttpClient _http;
    private readonly string _companyId;
    private readonly string _baseUrl = "https://api.nfse.io";

    public NfeIoClient(string apiKey, string companyId)
    {
        _companyId = companyId;
        _http = new HttpClient();
        _http.DefaultRequestHeaders.Add("Authorization", $"ApiKey {apiKey}");
    }

    public async Task<NfeMetadata> GetNfeAsync(string accessKey)
    {
        var url = $"{_baseUrl}/v2/companies/{_companyId}/inbound/productinvoices/{accessKey}";
        var response = await _http.GetAsync(url);

        response.EnsureSuccessStatusCode();

        var content = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<NfeMetadata>(content);
    }

    public async Task<Stream> GetNfeXmlAsync(string accessKey)
    {
        var url = $"{_baseUrl}/v2/companies/{_companyId}/inbound/productinvoices/{accessKey}/xml";
        return await _http.GetStreamAsync(url);
    }
}
```

### Exemplo 2 — Consumir Webhook e Baixar XML (Node.js)

```javascript
const express = require('express');
const axios = require('axios');
const crypto = require('crypto');
const app = express();

app.use(express.raw({ type: 'application/json' })); // raw para validar assinatura

const API_KEY = 'sk_live_sua_chave_aqui';
const COMPANY_ID = 'comp_123';
const WEBHOOK_SECRET = 'seu_webhook_secret';
const BASE_URL = 'https://api.nfse.io';

function validateSignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

app.post('/webhooks/nfeio', async (req, res) => {
    // Validar assinatura
    const signature = req.headers['x-nfe-signature'] || '';
    if (!validateSignature(req.body, signature, WEBHOOK_SECRET)) {
        return res.status(401).send('Assinatura inválida');
    }

    const payload = JSON.parse(req.body);
    const { event, accessKey, type, issuer, totalAmount } = payload;

    console.log(`Novo documento: ${accessKey} - ${event}`);

    try {
        const xmlResponse = await axios.get(
            `${BASE_URL}/v2/companies/${COMPANY_ID}/inbound/productinvoices/${accessKey}/xml`,
            { headers: { 'Authorization': `ApiKey ${API_KEY}` }, responseType: 'text' }
        );

        await saveDocumentToDatabase({ accessKey, type, issuer, totalAmount, xml: xmlResponse.data });

        res.status(200).json({ status: 'ok' });
    } catch (error) {
        console.error('Erro:', error);
        res.status(500).json({ error: error.message });
    }
});

app.listen(3000);
```

### Exemplo 3 — Listar CT-es do Último Mês com Paginação (Python)

```python
import requests
from datetime import datetime, timedelta

API_KEY = "sk_live_sua_chave"
COMPANY_ID = "comp_123"
BASE_URL = "https://api.nfse.io"

def get_all_ctes_last_month():
    """Busca os CT-es do último mês.

    A API não suporta filtro por intervalo de datas (`$filter` aceita apenas
    igualdade simples — ver §9). A paginação é cursor-based via `$skiptoken`
    (NSU). Portanto, percorremos as páginas em ordem de NSU e filtramos por
    data no lado do cliente.
    """

    cutoff = datetime.utcnow() - timedelta(days=30)
    headers = {"Authorization": API_KEY}
    all_ctes = []
    skiptoken = None

    while True:
        url = (
            f"{BASE_URL}/v2/companies/{COMPANY_ID}/inbound/odata/TransportationInvoices"
            f"?$top=100"
        )
        if skiptoken is not None:
            url += f"&$skiptoken={skiptoken}"

        response = requests.get(url, headers=headers)
        response.raise_for_status()
        page = response.json().get("value", [])
        if not page:
            break

        all_ctes.extend(
            c for c in page
            if datetime.fromisoformat(c["issuedOn"].replace("Z", "")) >= cutoff
        )

        # Cursor: NSU do último item desta página (ordenada por NSU ascendente).
        skiptoken = page[-1]["nsu"]
        print(f"Processados {len(all_ctes)} CT-es do período até agora...")

    return all_ctes

ctes = get_all_ctes_last_month()
print(f"Total: {len(ctes)} CT-es")
for cte in ctes[:5]:
    print(f"  - {cte['accessKey']} | Emitido em: {cte['issuedOn']}")
```

### Exemplo 4 — Ativar Inbound e Aguardar Primeiro Documento (PHP)

```php
<?php

class NfeIoInbound
{
    private string $apiKey;
    private string $companyId;
    private string $baseUrl = 'https://api.nfse.io';

    public function __construct(string $apiKey, string $companyId)
    {
        $this->apiKey = $apiKey;
        $this->companyId = $companyId;
    }

    private function makeRequest(string $method, string $path, ?array $body = null): array
    {
        $url = "{$this->baseUrl}/v2/companies/{$this->companyId}/{$path}";

        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => [
                "Authorization: {$this->apiKey}",
                "Content-Type: application/json"
            ],
        ]);

        if ($body) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        }

        $response = curl_exec($ch);
        $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($statusCode >= 400) {
            throw new RuntimeException("API Error {$statusCode}: {$response}");
        }

        return json_decode($response, true);
    }

    public function enableNfeInbound(int $startFromNsu = 0): array
    {
        return $this->makeRequest('POST', 'inbound/productinvoices', [
            'StartFromNsu' => $startFromNsu,
            'EnvironmentSEFAZ' => 'Production',
            'WebhookVersion' => 2,
        ]);
    }

    public function getNfeMetadata(string $accessKey): array
    {
        return $this->makeRequest('GET', "inbound/productinvoices/{$accessKey}");
    }
}

// Uso:
$client = new NfeIoInbound('sk_live_abc123', 'comp_123');
$config = $client->enableNfeInbound();
echo "Inbound ativado! Status: " . $config['status'];
```

### Exemplo 5 — Listar todas as NF-e de produção com paginação OData (Node.js)

Este exemplo usa o endpoint `ProductInvoices` para iterar sobre **todas** as NF-e da sua empresa no ambiente de produção. Ideal para sincronização de histórico ou auditorias.

```javascript
const axios = require('axios');

const API_KEY = 'sk_live_abc123';
const COMPANY_ID = 'comp_123';
const BASE_URL = 'https://api.nfse.io';
const PAGE_SIZE = 100;

const http = axios.create({
    baseURL: BASE_URL,
    headers: { Authorization: API_KEY }
});

async function listAllNFeProducao() {
    const allDocuments = [];
    let skipToken = null;
    let pageNumber = 1;

    while (true) {
        const params = {
            '$filter': 'environmentType eq 1', // 1 = Produção
            '$top': PAGE_SIZE
        };

        if (skipToken !== null) {
            params['$skiptoken'] = skipToken;
        }

        const response = await http.get(
            `/v2/companies/${COMPANY_ID}/inbound/odata/ProductInvoices`,
            { params }
        );

        const items = response.data.value || [];
        console.log(`Página ${pageNumber}: ${items.length} NF-e recebidas`);

        if (items.length === 0) break;

        allDocuments.push(...items);

        // Critério de parada: última página veio com menos itens que o $top
        if (items.length < PAGE_SIZE) break;

        // Próximo cursor = NSU do último item da página atual
        skipToken = items[items.length - 1].nsu;
        pageNumber++;
    }

    return allDocuments;
}

// Para cada NF-e, buscar os eventos relacionados
async function listEventsForNFe(accessKey) {
    const events = [];
    let skipToken = null;

    while (true) {
        const params = {
            '$filter': `accessKey eq '${accessKey}'`,
            '$top': 50
        };
        if (skipToken !== null) params['$skiptoken'] = skipToken;

        const response = await http.get(
            `/v2/companies/${COMPANY_ID}/inbound/odata/ProductInvoiceEvents`,
            { params }
        );

        const items = response.data.value || [];
        if (items.length === 0) break;

        events.push(...items);
        if (items.length < 50) break;

        skipToken = items[items.length - 1].nsu;
    }

    return events;
}

// Execução
(async () => {
    try {
        const notas = await listAllNFeProducao();
        console.log(`\nTotal de NF-e encontradas: ${notas.length}`);

        // Exemplo: buscar eventos da primeira NF-e
        if (notas.length > 0) {
            const eventos = await listEventsForNFe(notas[0].accessKey);
            console.log(`Eventos da NF-e ${notas[0].accessKey}: ${eventos.length}`);
        }
    } catch (err) {
        console.error('Erro:', err.response?.data || err.message);
    }
})();
```

**Pontos importantes deste exemplo:**

- `PAGE_SIZE` está em 100 para equilibrar número de requisições e tamanho de resposta. Você pode subir até 1000.
- O critério de parada é duplo: **ou** a resposta vem vazia, **ou** vem com menos itens que `$top` (indicando fim dos dados).
- O `$skiptoken` sempre recebe o `nsu` do **último** item da página atual — nunca o primeiro.
- A iteração é **cursor-based**, então é segura mesmo que novos documentos cheguem durante a execução (novos registros terão NSU maior e serão incluídos naturalmente).
- Para buscar eventos de uma NF-e, use `ProductInvoiceEvents` passando a `accessKey` da NF-e pai.

### Exemplo 6 — Listar NF-e paginado em C# (.NET)

```csharp
using System.Net.Http.Headers;
using System.Text.Json;

var httpClient = new HttpClient { BaseAddress = new Uri("https://api.nfse.io") };
// A API Key é o valor direto do header Authorization (sem prefixo/esquema).
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("Authorization", "sk_live_abc123");

var companyId = "comp_123";
var pageSize = 100;
long? skipToken = null;
var allDocuments = new List<JsonElement>();

while (true)
{
    var url = $"/v2/companies/{companyId}/inbound/odata/ProductInvoices" +
              $"?$filter=environmentType eq 1&$top={pageSize}";

    if (skipToken.HasValue)
        url += $"&$skiptoken={skipToken.Value}";

    var response = await httpClient.GetAsync(url);
    response.EnsureSuccessStatusCode();

    var json = await response.Content.ReadAsStringAsync();
    var doc = JsonDocument.Parse(json);
    var items = doc.RootElement.GetProperty("value").EnumerateArray().ToList();

    if (items.Count == 0) break;

    allDocuments.AddRange(items);
    Console.WriteLine($"Recebidas {items.Count} NF-e (total: {allDocuments.Count})");

    if (items.Count < pageSize) break;

    // Próximo cursor = NSU (long) do último item
    skipToken = items.Last().GetProperty("nsu").GetInt64();
}

Console.WriteLine($"\nTotal final: {allDocuments.Count} NF-e");
```

---

## 14. Perguntas Frequentes (FAQ)

### Quanto tempo leva para receber um documento após a emissão?

Em condições normais, entre **30 minutos e 4 horas** após a autorização da SEFAZ. O nosso sistema faz polling periódico na SEFAZ; o intervalo depende da configuração, da sincronização entre a SEFAZ de origem e o Ambiente Nacional e da disponibilidade da SEFAZ.

### O que é um "resumo" (productInvoiceSummary)?

A SEFAZ disponibiliza o `productInvoiceSummary` enquanto a NF-e ainda não tem uma manifestação do destinatário registrada — nesse estado, apenas os dados básicos da nota são liberados, sem o XML completo. O XML completo só é disponibilizado pela SEFAZ depois que o destinatário registra um evento de manifestação.

Para automatizar esse fluxo, o nosso sistema oferece a configuração `AutomaticManifesting`: ao receber um `productInvoiceSummary`, o destinatário pode ter a manifestação **"Ciência da Operação"** enviada automaticamente em seu nome. Assim que a SEFAZ processa essa manifestação, ela libera o XML completo, que é entregue por uma nova notificação (`product_invoice_inbound` / `issued_successfully`).

### Posso buscar documentos históricos?

Sim. A SEFAZ mantém documentos disponíveis por até **90 dias** para consulta via NSU. Configure `StartFromNsu` ao ativar o inbound para sincronizar o histórico.

### A URL do XML expira?

Sim. As URLs retornadas em `links.xml` e `links.pdf` expiram em **1 hora**. Para download, use a URL logo após obtê-la, ou chame o endpoint `/xml` a qualquer momento para obter uma nova URL.

### O que acontece se meu webhook estiver fora do ar?

O sistema tentará reenviar o webhook com backoff exponencial por até 24 horas. Após esse período, você pode usar o endpoint de reprocessamento para solicitar novo envio.

### Preciso manifestar todas as NF-es?

Pela legislação brasileira, o destinatário deve registrar **uma das 4 manifestações** para NF-es de entrada (que você está comprando): **Ciência da Operação**, **Confirmação da Operação**, **Operação Não Realizada** ou **Desconhecimento da Operação**. Não é obrigatório que seja a Ciência da Operação especificamente.

Para automatizar parte desse fluxo, o sistema oferece a configuração `AutomaticManifesting`, que envia a **Ciência da Operação** automaticamente em nome do destinatário. Essa manifestação foi escolhida para automação porque **não impede** que o destinatário, posteriormente, registre uma das demais manifestações (Confirmação, Operação Não Realizada ou Desconhecimento) caso o contexto fiscal exija.

### Como testar sem afetar o ambiente de produção?

Configure com `EnvironmentSEFAZ: "Test"` para usar o ambiente de homologação SEFAZ. Documentos emitidos em homologação não têm validade fiscal. Ao terminar os testes, basta atualizar a configuração para `"Production"` — não é necessário deletá-la antes.

### Como saber se o inbound está atrasado?

Consulte `GET /productinvoices` e compare `OperationDetail_CurrentNsu` com `OperationDetail_MaxNsu`. Se a diferença for grande e `OperationDetail_ExecutedOn` for antigo, pode haver um problema. Verifique se a configuração está `Active` e se o certificado digital não expirou.

---

*Documentação mantida pela equipe de desenvolvimento nfe.io. Para reportar problemas ou solicitar funcionalidades, acesse o suporte em [nfe.io/suporte](https://nfe.io/suporte).*

---

## DFe Inbound: Webhook de NF-e e CT-e Recebidas

Source: https://nfe.io/docs/documentacao/distribuicao/dfe-inbound-webhook-nfe-cte/index.md

# Documentação Técnica — Webhook NF-e/CT-e Inbound (Devs de Clientes)

> **Público-alvo:** Desenvolvedores de sistemas que integram com a NFE.io
> para receber automaticamente NF-e e CT-e capturadas via DistribuicaoDFe
> (SEFAZ Ambiente Nacional).
> **Objetivo:** Referência técnica completa para integrar via webhook:
> payload, campos, tipos, eventos, validação de assinatura, boas práticas.
> **Atualizado em:** 2026-05-22
>
> 📑 Este documento cobre **apenas o webhook do NF-e/CT-e Recebidas**. Para
> a referência REST (consulta, download, manifestação) consulte
> [02-doc-tecnica-clientes-nfe-cte-dev-pt.md](/documentacao/distribuicao/dfe-inbound-documentacao-tecnica-desenvolvedores).
> Para o webhook do NFS-e Recebidas, consulte
> 02-doc-tecnica-clientes-dev-nfse-inbound-webhook.md.
> Para a visão geral, abra README.md.

## Índice

- [1. Visão geral](#1-visão-geral)
- [2. Webhook — Contrato técnico](#2-webhook--contrato-técnico)
- [3. Envelope de entrega](#3-envelope-de-entrega)
- [4. Payloads de NF-e](#4-payloads-de-nf-e)
  - [4.1. `product_invoice_inbound` / `issued_successfully`](#41-product_invoice_inbound--issued_successfully)
  - [4.2. `product_invoice_inbound` / `event_raised_successfully`](#42-product_invoice_inbound--event_raised_successfully)
  - [4.3. `product_invoice_inbound` / `input_event_raised_successfully` (manifestação)](#43-product_invoice_inbound--input_event_raised_successfully-manifestação)
  - [4.4. Resumos (`product_invoice_inbound_summary`)](#44-resumos-product_invoice_inbound_summary)
- [5. Payloads de CT-e](#5-payloads-de-ct-e)
  - [5.1. `transportation_invoice_inbound` / `issued_successfully`](#51-transportation_invoice_inbound--issued_successfully)
  - [5.2. `transportation_invoice_inbound` / `event_raised_successfully`](#52-transportation_invoice_inbound--event_raised_successfully)
- [6. Mapeamento `tpEvento` SEFAZ → `eventAction`](#6-mapeamento-tpevento-sefaz--eventaction)
- [7. Validação HMAC](#7-validação-hmac)
- [8. URLs de download do XML](#8-urls-de-download-do-xml)
- [9. Reprocessamento de webhook](#9-reprocessamento-de-webhook)
- [10. Idempotência](#10-idempotência)
- [11. Boas práticas de integração](#11-boas-práticas-de-integração)
- [12. Troubleshooting](#12-troubleshooting)
- [13. Anatomia da chave de acesso (NF-e/NFC-e e CT-e)](#13-anatomia-da-chave-de-acesso-nf-enfc-e-e-ct-e)
  - [13.1. NF-e (modelo 55) e NFC-e (modelo 65) — 44 dígitos](#131-nf-e-modelo-55-e-nfc-e-modelo-65--44-dígitos)
  - [13.2. Chave do evento NF-e — 51 dígitos (sem prefixo `ID`)](#132-chave-do-evento-nf-e--51-dígitos-sem-prefixo-id)
  - [13.3. CT-e (modelo 57) — 44 dígitos](#133-ct-e-modelo-57--44-dígitos)
  - [13.4. Chave do evento CT-e — 55 caracteres (com prefixo `ID`)](#134-chave-do-evento-ct-e--55-caracteres-com-prefixo-id)
  - [13.5. Validação do DV (módulo 11)](#135-validação-do-dv-módulo-11)

---

## 1. Visão geral

O serviço **Inbound** da NFE.io captura automaticamente NF-e e CT-e da
SEFAZ via DFe (Distribuição de DF-e) e entrega ao seu sistema via
**webhook HTTP POST**.

**Fluxo resumido:**

```text
SEFAZ (DFe) → NFE.io Inbound Worker → Webhook POST → Seu sistema
```

Você **não** precisa consultar a SEFAZ — o NFE.io faz isso automaticamente
em intervalos regulares por empresa ativa.

**Famílias de evento entregues por este serviço:**

| Família | `eventType` | `eventAction` | Quando ocorre |
|---|---|---|---|
| NF-e completa | `product_invoice_inbound` | `issued_successfully` | Nova NF-e autorizada recebida via DistribuicaoDFe, XML completo |
| Evento de NF-e | `product_invoice_inbound` | `event_raised_successfully` | Evento emitido pela própria origem da NF-e (cancelamento, EPEC, CC-e, registro de passagem, etc.) |
| Manifestação do destinatário | `product_invoice_inbound` | `input_event_raised_successfully` | Manifestação registrada pelo destinatário (confirmação, ciência, desconhecimento, operação não realizada) |
| Resumo de NF-e | `product_invoice_inbound_summary` | `issued_successfully` | Resumo de NF-e (metadados apenas — XML completo não disponível até manifestação ou via consulta on-demand) |
| Resumo de evento de NF-e | `product_invoice_inbound_summary` | `event_raised_successfully` | Resumo de evento — metadados do evento sem XML completo |
| CT-e completo | `transportation_invoice_inbound` | `issued_successfully` | Novo CT-e autorizado recebido via DistribuicaoDFe |
| Evento de CT-e | `transportation_invoice_inbound` | `event_raised_successfully` | Evento de CT-e (cancelamento, prestação em desacordo, etc.) |

**Resumo vs documento completo** (NF-e apenas):

A SEFAZ entrega via DFe **resumos** (`NFeSummary...`) com poucos metadados
(empresa, chave, NSU, descrição) ou **documentos completos**
(`NFeMetadata`, `NFeEventMetadata`) com participantes, valores e links
detalhados. O serviço NFE.io repassa cada um como webhook distinto
(`*_inbound` vs `*_inbound_summary`). Quando você recebe um resumo e
quer o documento completo, chame `GET .../inbound/{accessKey}/xml`.

---

## 2. Webhook — Contrato técnico

### Método e headers

```http
POST <sua-url-configurada>
Content-Type: application/json; charset=utf-8
```

### Resposta esperada do seu endpoint

| HTTP Status | Comportamento NFE.io |
|---|---|
| **2xx** (200, 201, 204) | Entrega confirmada — não reenvia |
| **4xx** (exceto 408, 429) | Marca falha definitiva — **não** reenvia |
| **408** (timeout) | Falha temporária — reenvia com backoff |
| **429** (rate limit) | Falha temporária — reenvia com backoff |
| **5xx** | Falha temporária — reenvia com backoff |
| **Timeout** (> 30s) | Falha temporária — reenvia |

### Política de retry

- Até **50 tentativas** em uma janela de **24 horas**.
- Backoff exponencial: 30s → 60s → 120s → ... → max 7200s (2h).
- Jitter de ±20% em cada delay.
- Após exaurir: documento permanece disponível via API
  (`GET /v2/companies/{companyId}/inbound/productinvoices/{accessKey}` ou
  `.../transportationinvoices/{accessKey}`) e pode ser **reprocessado**
  manualmente (ver §9).

---

## 3. Envelope de entrega

O payload entregue ao seu endpoint vem **dentro de um envelope**
`{ "body": { ... } }` adicionado pela camada de entrega de webhooks da
NFE.io (events-api). É o mesmo wrapper usado pelo webhook NFS-e Inbound
(ver `02-doc-tecnica-clientes-dev-nfse-inbound-webhook.md` §3) — os
campos do objeto enviado ao transporte são **espalhados** dentro de
`body`, e `body.action` reflete o `eventAction` da rota.

**Estrutura completa do envelope final entregue:**

```json
{
  "body": {
    "action": "issued_successfully",
    "accountId": "acc-123",
    "type": "productInvoice",
    "accessKey": "...",
    "company": { /* ... */ },
    "issuer": { /* ... */ },
    "buyer": { /* ... */ }
    /* demais campos do payload — ver §4 e §5 */
  }
}
```

- **`body.action`** — corresponde ao `eventAction` da rota interna
  (`issued_successfully`, `event_raised_successfully`,
  `input_event_raised_successfully`). Use-o para diferenciar **ação**.
- **`body.type`** — campo do próprio payload (ver `Type` em §4/§5).
  Valores: `productInvoice`, `productInvoiceEvent`, `productInvoiceSummary`,
  `productInvoiceEventSummary`, `transportationInvoice`,
  `transportationInvoiceEvent`. Use-o para diferenciar **variante**.
- **Demais campos** (`accessKey`, `company`, `issuer`, etc.) — espalhados
  diretamente em `body` (não há sub-objeto `data` ou `document` aninhado
  para NF-e/CT-e — diferente do NFS-e, cujo handler embrulha em
  `body.document`).

> **Roteamento por `eventType`/`eventAction`**: o filtro de webhook
> registrado no painel nfe.io usa o par `(eventType, eventAction)` para
> decidir entregar a notificação. Os 3 `eventType` (`product_invoice_inbound`,
> `product_invoice_inbound_summary`, `transportation_invoice_inbound`)
> aparecem na URL interna da events-api (`v2/events/{eventType}/{eventAction}`)
> e definem qual webhook do painel será disparado, mas **não são
> necessariamente propagados** dentro de `body`. Para discriminar o
> payload recebido, use `(body.action, body.type)`.
>
> **Discriminação no consumer**: use o par `(body.action, body.type)` —
> a matriz completa está na §12 ("Troubleshooting").
>
> **Nota de validação**: o wrapper acima reflete o padrão da events-api
> documentado no webhook NFS-e Inbound (mesma camada de entrega). Recomenda-se
> validar o shape contra uma entrega real de homologação antes de codar
> contratos rígidos de parser.

Os exemplos JSON nas seções 4 e 5 abaixo mostram apenas o **conteúdo
top-level do payload** (sem o wrapper `{ "body": { ... } }`) para clareza.
O wrapper é sempre o mesmo.

### Serialização: campos `null` são omitidos por padrão

⚠️ **Mudança em relação a versões anteriores deste documento.** O
serializador JSON da API **omite campos com valor `null`** — está
configurado globalmente com
`JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull`
(`Program.cs`). Consequências práticas:

1. **Não confie em chave presente como indicador.** Todo campo opcional
   documentado nas tabelas abaixo pode estar **ausente** quando o valor
   real seria `null`. Acesse com checagem defensiva (`obj?.field`,
   `obj.get("field")`, etc.), nunca assuma que a chave existe.
2. **Objetos com todas as propriedades internas `null` aparecem como
   `{}`.** Por exemplo, em um evento NF-e em que a NF-e pai ainda não foi
   indexada, `transportation` pode chegar como `{}` (objeto vazio) em vez
   de `{ "federalTaxNumber": null, "name": null }`. O container existe
   porque foi instanciado em código; as chaves internas foram omitidas
   pelo serializador.
3. **Containers que nem foram instanciados ficam totalmente ausentes.**
   Em resumos (§4.4.1, §4.4.2) e em CT-es que não declaram um participante
   opcional, o objeto pai não aparece na resposta — não vem como `null`
   nem como `{}`.
4. **Os exemplos das seções 4 e 5 refletem payloads reais observados em
   produção** (anonimizados). Use-os como contrato de referência; as
   tabelas listam quais campos podem aparecer, não garantem presença.

⚠️ **Diferença para a doc do webhook NFS-e:** o handler do NFS-e usa um
`JsonSerializerOptions` próprio que serializa `null` explicitamente. Não
extrapole o comportamento de um webhook para o outro.

### Estabilidade contra novos campos

A API pode adicionar **novos campos opcionais** ao payload sem aviso
prévio (mudança não-breaking). Seu parser deve **ignorar chaves
desconhecidas** em vez de falhar. Configurações recomendadas:

- TypeScript: evite `exactOptionalPropertyTypes` para o shape do webhook;
  trate todos os campos como `string | null | undefined`.
- C#: configure `JsonSerializer` com
  `JsonSerializerOptions { UnknownTypeHandling = ... }` permissivo, ou
  use `JsonElement` para campos não documentados.
- Go: use `json.RawMessage` ou structs com tags `json:",omitempty"` e
  não falhe em campos extras (comportamento default de `encoding/json`).

---

## 4. Payloads de NF-e

Todas as 5 variantes NF-e compartilham o mesmo **shape** de payload. O
que diferencia uma da outra é:

- o **campo `type`** dentro do `data` (`productInvoice`, `productInvoiceEvent`, `productInvoiceSummary`, `productInvoiceEventSummary`);
- e **quais campos opcionais vêm populados** (resumos têm muitos campos `null`; eventos têm campos de enrichment da NF-e referenciada que podem vir `null` durante in-flight).

Valores possíveis de `type`:

| `type` | Quando ocorre |
|---|---|
| `productInvoice` | NF-e completa recebida via DFe |
| `productInvoiceEvent` | Evento de NF-e (cancelamento, EPEC, etc.) |
| `productInvoiceSummary` | Resumo de NF-e (metadados parciais) |
| `productInvoiceEventSummary` | Resumo de evento de NF-e |

### 4.1. `product_invoice_inbound` / `issued_successfully`

Enviado quando uma **NF-e nova completa** é recebida via DistribuicaoDFe
e o XML é desempacotado com sucesso. Carrega os participantes, valores
e links de download.

#### Campos populados vs sempre `null`

Igual ao que descrevemos em §4.2 para eventos, o shape de `NFeMetadataResource`
é compartilhado com outros endpoints e contém campos que **este webhook não popula**.

**Sempre populados:**

| Campo | Origem |
|---|---|
| `accessKey` | `infNFe/@Id` (sem prefixo `NFe`) — chave de 44 dígitos. |
| `parentAccessKey` | `""` (string vazia — NF-e raiz não tem documento pai). |
| `createdOn` | Quando o documento entrou no nosso sistema. |
| `nsu` | NSU atribuído pela SEFAZ ao envelope DistribuicaoDFe (string). |
| `nsuParent` | `""` (string vazia para NF-e raiz). |
| `type` | Sempre `"productInvoice"`. |
| `description` | Sempre o literal `"Autorizado o uso da NF-e"`. |
| `nfeNumber`, `nfeSerialNumber` | `infNFe/ide/nNF` e `infNFe/ide/serie`. |
| `issuedOn` | `infNFe/ide/dhEmi`. |
| `totalInvoiceAmount` | `infNFe/total/ICMSTot/vNF` formatado como `"0.00"`. |
| `operationType` | `infNFe/ide/tpNF` — `"Incoming"` (`tpNF=0`) ou `"Outgoing"` (`tpNF=1`). |
| `company.id`, `company.federalTaxNumber` | Sua empresa nfe.io. |
| `issuer.federalTaxNumber`, `issuer.name` | `infNFe/emit/{CNPJ\|CPF}` e `xNome`. |
| `buyer.federalTaxNumber`, `buyer.name` | `infNFe/dest/{CNPJ\|CPF}` e `xNome`. |
| `transportation.federalTaxNumber`, `transportation.name` | `infNFe/transp/transporta/{CNPJ\|CPF, xNome}`. Se a NF-e não declarou transportadora, vêm **string vazia** (`""`), não null. |
| `links.xml` | URL para baixar o XML completo via API. |
| `links.pdf` | URL para baixar o DANFE (PDF) via API. |

**Containers `issuer`, `buyer`, `transportation`, `links`:** o código
sempre instancia esses objetos. Quando o XML da NF-e declara o
participante, todos os campos internos vêm preenchidos. Quando algum
campo interno é `null`, ele é **omitido** pela serialização global
(§3). Se a NF-e não declarou uma transportadora, por exemplo,
`transportation` pode chegar como `{ "federalTaxNumber": "", "name": "" }`
(strings vazias preenchidas pelo parser) ou apenas `{}` (objeto vazio
após filtro de `null`).

**Campos do shape que NÃO são populados (omitidos do JSON):**

| Campo | Comportamento real |
|---|---|
| `xmlUrl` (top-level) | **Ausente do JSON.** Use `links.xml`. Há `[JsonIgnore(WhenWritingNull)]` explícito no shape e o valor é `null` para NF-e completa. Só é populada em webhooks de resumo de evento (§4.4.2). |
| `federalTaxNumberSender` | **Ausente do JSON** (`null` no servidor, omitido pelo serializador global). Use `issuer.federalTaxNumber`. |
| `nameSender` | **Ausente do JSON.** Use `issuer.name`. |
| `environmentType` | `0` (default de `int`; presente no JSON porque tipos de valor não-nullable não são afetados pelo filtro de `null`). Não é confiável — para saber o ambiente SEFAZ, use a configuração do inbound (`EnvironmentSEFAZ`). |

#### Exemplo (payload real anonimizado)

Conteúdo top-level de `body` (sem o wrapper do §3):

```json
{
  "accessKey": "35260557622466000146550010011320981999999993",
  "createdOn": "2026-05-19T11:41:44.695Z",
  "parentAccessKey": "",
  "company": {
    "id": "9999999999999999999999999999997",
    "federalTaxNumber": "99999999999999"
  },
  "issuer": {
    "federalTaxNumber": "57622466000146",
    "name": "DISTRIBUIDORA DE CARNES VALE DO MOGI IMP EXP LTDA"
  },
  "buyer": {
    "federalTaxNumber": "99999999999999",
    "name": "CHURRASCARIA CACADOR LTDA"
  },
  "transportation": {
    "federalTaxNumber": "57622466000146",
    "name": "DISTRIBUIDORA VALE DO MOGI IMP E EXP LTDA"
  },
  "links": {
    "xml": "https://api.nfse.io/v2/companies/9999999999999999999999999999997/inbound/35260557622466000146550010011320981999999993/xml",
    "pdf": "https://api.nfse.io/v2/companies/9999999999999999999999999999997/inbound/35260557622466000146550010011320981999999993/pdf"
  },
  "type": "productInvoice",
  "nsu": "34691",
  "nsuParent": "",
  "nfeNumber": "1132098",
  "nfeSerialNumber": "1",
  "issuedOn": "2026-05-18T04:08:27Z",
  "description": "Autorizado o uso da NF-e",
  "totalInvoiceAmount": "980.72",
  "operationType": "Incoming",
  "environmentType": 0
}
```

**Notas sobre o exemplo:**

- `createdOn` traz milissegundos (`.695Z`). Não assuma resolução de
  segundos no parsing.
- `federalTaxNumberSender`/`nameSender` **não aparecem** — foram omitidos
  por serem `null` no servidor (ver §3 e tabela acima).
- A `accessKey` da NF-e tem 44 dígitos (sem prefixo `NFe`). Ver §13 para
  a anatomia completa.

### 4.2. `product_invoice_inbound` / `event_raised_successfully`

Enviado quando um **evento da SEFAZ** é recebido para uma NF-e
(cancelamento, Carta de Correção, EPEC, registro de passagem, etc.).
Para a lista completa de `tpEvento` e mapeamento para `eventAction`, ver §6.1.

#### Quais campos vêm populados

O payload reaproveita o shape de `NFeMetadataResource` da §4.1, mas para
eventos o servidor preenche um subconjunto específico:

**Sempre populados (vêm do próprio evento):**

| Campo | Origem |
|---|---|
| `accessKey` | **51 dígitos**: concatenação `{tpEvento}{chaveNFe}{sequência}` — **sem prefixo `ID`**. Ex.: `110111412605...41` (cancelamento). Diferente do CT-e (§5.2), que mantém o prefixo `ID` por usar o `Id` original do XML sem reescrita. |
| `parentAccessKey` | Chave da NF-e referenciada (44 dígitos). |
| `createdOn` | Quando o evento entrou no nosso sistema (com milissegundos). |
| `nsu` | NSU do evento (string). |
| `type` | Sempre `"productInvoiceEvent"`. |
| `description` | Texto literal vindo do XML do evento. Cancelamento → `"Cancelamento"`. CC-e → `"Carta de Correcao"` (sem cedilha/acento, vindo do `<descEvento>` da SEFAZ). EPEC → `"EPEC"`. |
| `company.id`, `company.federalTaxNumber` | Sua empresa. |
| `links.xml` | URL do **XML do evento** (não da NF-e). |
| `links.pdf` | Sempre **string vazia** (`""`). Eventos não geram PDF. |

**Condicionais — só populados quando a NF-e pai está indexada** (caso típico
após captura prévia via SEFAZ ADN; vêm `null` se o evento chegou antes do
documento — janela transiente):

| Campo | Tipo | Quando vem null |
|---|---|---|
| `nsuParent` | string | NF-e pai não indexada. |
| `nfeNumber`, `nfeSerialNumber` | string | NF-e pai não indexada. |
| `issuedOn` | DateTime | NF-e pai não indexada. |
| `totalInvoiceAmount` | string | NF-e pai não indexada. |
| `issuer.federalTaxNumber`, `issuer.name` | string | NF-e pai não indexada. |
| `buyer.federalTaxNumber`, `buyer.name` | string | NF-e pai não indexada. |
| `transportation.federalTaxNumber`, `transportation.name` | string | NF-e pai não indexada ou NF-e sem transportadora. |

> ⚠️ **`operationType` é sempre serializado**, mas se a NF-e pai **não**
> estiver indexada, o servidor não consegue determinar a operação real e
> emite `"Outgoing"` por default. Trate esse campo como confiável apenas
> quando os demais campos condicionais (`nfeNumber`, `issuer`, etc.) também
> vierem populados.

**Containers `issuer`, `buyer`, `transportation` e `links`:** o código
instancia esses objetos. Os campos internos podem vir omitidos quando
forem `null` (regra global de serialização, §3). É comum, por exemplo,
ver `"transportation": {}` (objeto vazio) num evento de uma NF-e que
não declarou transportadora.

**Campos do shape que NÃO são populados em eventos (omitidos do JSON):**

| Campo | Comportamento real |
|---|---|
| `xmlUrl` (top-level) | **Ausente do JSON.** Use `links.xml`. |
| `federalTaxNumberSender` | **Ausente do JSON.** Use `issuer.federalTaxNumber`. |
| `nameSender` | **Ausente do JSON.** Use `issuer.name`. |
| `environmentType` | `0` (presente no JSON; valor de tipo `int` não é afetado pelo filtro de `null`). Não é confiável. |

#### Exemplo — Cancelamento (`tpEvento=110111`)

Conteúdo top-level de `body` (sem o wrapper do §3) — payload real anonimizado:

```json
{
  "accessKey": "110111412605999999999999995500200059985119999999941",
  "createdOn": "2026-05-18T19:21:54.06Z",
  "parentAccessKey": "41260599999999999999550020005998511999999994",
  "company": {
    "id": "99999999999999999999",
    "federalTaxNumber": "99999999999999"
  },
  "issuer": {
    "federalTaxNumber": "99999999999999",
    "name": "TESTE DISTRIBUIDORA DE FERRO E ACO LTDA"
  },
  "buyer": {
    "federalTaxNumber": "99999999999999",
    "name": "TESTE E TESTE LTDA"
  },
  "transportation": {},
  "links": {
    "xml": "https://api.nfse.io/v2/companies/99999999999999999999/inbound/41260599999999999999550020005998511999999994/events/110111412605999999999999995500200059985119999999941/xml",
    "pdf": ""
  },
  "type": "productInvoiceEvent",
  "nsu": "3272",
  "nsuParent": "3271",
  "nfeNumber": "599851",
  "nfeSerialNumber": "2",
  "issuedOn": "2026-05-15T15:22:30Z",
  "description": "Cancelamento",
  "totalInvoiceAmount": "7723.76",
  "operationType": "Incoming",
  "environmentType": 0
}
```

**Notas sobre o exemplo:**

- `accessKey` começa com `110111` (tpEvento de cancelamento), **sem o
  prefixo `ID`**. Veja §13.1 para a anatomia.
- `transportation: {}` — a NF-e original não declarou transportadora, então
  os campos internos foram omitidos pela serialização global e o container
  ficou vazio.
- Campos como `issuer`, `buyer`, `nfeNumber`, `totalInvoiceAmount` vieram
  preenchidos porque a NF-e pai já estava indexada no momento da entrega
  do evento. Em janelas transientes (evento chega antes da NF-e),
  os containers de enrichment podem vir vazios e os campos escalares
  podem estar omitidos.

#### Exemplo — Carta de Correção (`tpEvento=110110`)

Mesmo shape; apenas `accessKey` (começa com `110110…`) e `description`
mudam. O **texto da correção** (`xCorrecao`, item alterado, etc.) **não**
vem no payload — baixe o XML do evento via `links.xml` e leia
`procEventoNFe/evento/infEvento/detEvento/xCorrecao`.

Payload real anonimizado:

```json
{
  "accessKey": "110110332605685839540001085500100010826019999999931",
  "createdOn": "2026-05-18T20:29:35.898Z",
  "parentAccessKey": "33260568583954000108550010001082601999999993",
  "company": {
    "id": "999999999999999999999999",
    "federalTaxNumber": "99999999999999"
  },
  "issuer": {
    "federalTaxNumber": "99999999999999",
    "name": "TESTE  LTDA"
  },
  "buyer": {
    "federalTaxNumber": "99999999999999",
    "name": "CASA DE SAUDE E TESTE SA"
  },
  "transportation": {},
  "links": {
    "xml": "https://api.nfse.io/v2/companies/999999999999999999999999/inbound/33260568583954000108550010001082601999999993/events/110110332605685839540001085500100010826019999999931/xml",
    "pdf": ""
  },
  "type": "productInvoiceEvent",
  "nsu": "62313",
  "nsuParent": "62305",
  "nfeNumber": "108260",
  "nfeSerialNumber": "1",
  "issuedOn": "2026-05-18T00:00:00Z",
  "description": "Carta de Correcao",
  "totalInvoiceAmount": "1967.55",
  "operationType": "Incoming",
  "environmentType": 0
}
```

> ⚠️ Observe que `description` chega como `"Carta de Correcao"` (sem
> cedilha/acento) — o valor é repassado verbatim do `<descEvento>` da
> SEFAZ. Não normalize/traduza no consumer.

### 4.3. `product_invoice_inbound` / `input_event_raised_successfully` (manifestação)

Enviado quando o **destinatário** registra uma **manifestação** sobre a
NF-e. A SEFAZ define 4 `tpEvento` para manifestações; este serviço usa
o `eventAction = input_event_raised_successfully` exclusivamente para
esses 4 códigos. Eventos do **emissor** (cancelamento, CC-e, EPEC, etc.)
saem como `event_raised_successfully` (§4.2).

**Mapeamento dos 4 `tpEvento`:**

| `tpEvento` | Manifestação | Significado |
|---|---|---|
| `210200` | Confirmação da Operação | O destinatário recebeu a mercadoria como descrito. |
| `210210` | Ciência da Operação | O destinatário está ciente, mas não confirma recebimento. |
| `210220` | Operação Desconhecida | O destinatário não reconhece a operação. |
| `210240` | Operação Não Realizada | A operação não foi concluída (devolução etc.). |

**Por que esse split existe?** A manifestação é uma ação **proativa do
tomador** (não do emissor). Muitos clientes querem filtrar manifestações
distintas de eventos do emissor (cancelamento, CC-e). O split por
`eventAction` permite filtros simples no seu consumer:

```python
if body['action'] == 'input_event_raised_successfully':
    # Manifestação do destinatário — processar fluxo de aceitação/rejeição
    ...
elif body['action'] == 'event_raised_successfully':
    # Evento do emissor — atualizar status da NF-e (cancelado, CC-e aplicada)
    ...
```

**Shape do payload é idêntico ao §4.2** — mesma estrutura, com
`type: "productInvoiceEvent"`. O que muda é apenas `body.action` no
envelope.

### 4.4. Resumos (`product_invoice_inbound_summary`)

A SEFAZ pode entregar via DFe **apenas metadados resumidos** (não o
documento completo). Isso acontece quando:

1. A empresa **ainda não está manifestada** sobre a operação — a SEFAZ
   restringe acesso ao XML completo até que o destinatário confirme
   ciência ou confirmação.
2. O documento tem mais de **3 meses** desde a emissão (limite de
   retenção do DFe para XMLs completos).

Nesses casos, você recebe um **webhook de resumo** ao invés do webhook
completo (§4.1/§4.2). Os campos vêm parcialmente populados (vide tabelas
abaixo).

#### 4.4.1. `product_invoice_inbound_summary` / `issued_successfully`

Compartilha o shape de `NFeMetadataResource` com §4.1, mas com `type: "productInvoiceSummary"` e um subconjunto bem menor de campos populados. Helper: `NFePersistenceService.GetNFeMetadataResource(NFeSummaryNFeMetadata)`.

**Sempre populados:**

- `accessKey`, `createdOn`, `nsu`.
- `type` = `"productInvoiceSummary"`.
- `nfeNumber` — extraído da `accessKey`.
- `issuedOn` — vem do `receiptOn` do resumo SEFAZ (não da emissão original — esse dado não está no resumo).
- `totalInvoiceAmount` — formato `"0.00"`.
- `company.id`, `company.federalTaxNumber`.
- `issuer.federalTaxNumber`, `issuer.name` — vêm do envelope DistribuicaoDFe.
- `links.xml` — URL para baixar o XML quando estiver disponível.

**Conditional:** `description` = `nfeObject.Reason` — o `xMotivo` do SEFAZ retornado junto com o resumo. No fluxo de sucesso típico vem `null` (não setado pelo gateway); pode trazer texto da SEFAZ em casos de erro/aviso.

**Não populados (vêm `null`/`0`):**

| Campo | Valor real |
|---|---|
| `parentAccessKey` | `null`. |
| `nsuParent` | `null`. |
| `nfeSerialNumber` | `null` (não está no resumo SEFAZ). |
| `operationType` | `"Outgoing"` (default do enum `int 0` — não é confiável aqui, **ignorar**). |
| `environmentType` | `0`. |
| `federalTaxNumberSender`, `nameSender` | `null`. |
| `xmlUrl` (top-level) | **Ausente do JSON** (`[JsonIgnore(WhenWritingNull)]` aplicado). Use `links.xml`. |
| `buyer`, `transportation` | objetos **não instanciados**, vêm `null` no JSON (diferente do §4.1, onde sempre vêm como objeto). |
| `links.pdf` | `null` (resumos não geram PDF). |

**Exemplo JSON (conteúdo top-level de `body`, sem o wrapper — ver §3):**

```json
{
  "accessKey": "35240112345678000195550010000012341234567890",
  "createdOn": "2026-05-13T14:42:15Z",
  "parentAccessKey": null,
  "company": {
    "id": "54244e0ee340420fdc94ad10",
    "federalTaxNumber": "98765432000100"
  },
  "issuer": {
    "federalTaxNumber": "12345678000195",
    "name": "FORNECEDOR LTDA"
  },
  "buyer": null,
  "transportation": null,
  "links": {
    "xml": "https://api.nfse.io/v2/companies/54244e0ee340420fdc94ad10/inbound/35240112345678000195550010000012341234567890/xml",
    "pdf": null
  },
  "federalTaxNumberSender": null,
  "nameSender": null,
  "type": "productInvoiceSummary",
  "nsu": "21825",
  "nsuParent": null,
  "nfeNumber": "1234",
  "nfeSerialNumber": null,
  "issuedOn": "2026-05-13T10:00:00Z",
  "description": null,
  "totalInvoiceAmount": "1500.00",
  "operationType": "Outgoing",
  "environmentType": 0
}
```

**Quando o cliente recebe summary e quer dados completos:** veja §6.4 — a SEFAZ libera o XML completo após o destinatário registrar a manifestação. O webhook subsequente virá como §4.1 (`type: "productInvoice"`).

#### 4.4.2. `product_invoice_inbound_summary` / `event_raised_successfully`

Mesmo shape de `NFeMetadataResource`, com `type: "productInvoiceEventSummary"`. ⚠️ **Diferença importante**: este é o **único webhook que usa `xmlUrl` (top-level) ao invés de `links.xml`** — o helper `GetMetadataResource(NFeSummaryEventMetadata)` emite o link do XML do evento em `xmlUrl`, e o objeto `links` vem `null`.

**Sempre populados:**

- `accessKey` (chave do evento), `parentAccessKey` (chave NF-e referenciada).
- `createdOn`, `nsu`.
- `type` = `"productInvoiceEventSummary"`.
- `description` — `xEvento` literal do SEFAZ (ex.: `"Cancelamento de NF-e homologado"`, `"Carta de Correção registrada"`).
- `nfeNumber` — extraído da `parentAccessKey`.
- `issuedOn` — vem do `receiptOn` do evento.
- `company.id`, `company.federalTaxNumber`.
- `xmlUrl` — URL para baixar o XML do evento.

**Não populados (vêm `null`/`0`):**

| Campo | Valor real |
|---|---|
| `nsuParent` | `null`. |
| `nfeSerialNumber` | `null`. |
| `totalInvoiceAmount` | `null`. |
| `operationType` | `"Outgoing"` (default — **ignorar**). |
| `environmentType` | `0`. |
| `federalTaxNumberSender`, `nameSender` | `null`. |
| `issuer`, `buyer`, `transportation`, `links` | objetos **não instanciados**, vêm `null` no JSON. |

**Exemplo JSON — Cancelamento (resumo):**

```json
{
  "accessKey": "ID110111352401123456780001955500100000123412345678901",
  "createdOn": "2026-05-13T15:10:00Z",
  "parentAccessKey": "35240112345678000195550010000012341234567890",
  "company": {
    "id": "54244e0ee340420fdc94ad10",
    "federalTaxNumber": "98765432000100"
  },
  "issuer": null,
  "buyer": null,
  "transportation": null,
  "links": null,
  "xmlUrl": "https://api.nfse.io/v2/companies/54244e0ee340420fdc94ad10/inbound/35240112345678000195550010000012341234567890/events/ID110111352401123456780001955500100000123412345678901/xml",
  "federalTaxNumberSender": null,
  "nameSender": null,
  "type": "productInvoiceEventSummary",
  "nsu": "21850",
  "nsuParent": null,
  "nfeNumber": "1234",
  "nfeSerialNumber": null,
  "issuedOn": "2026-05-13T15:00:00Z",
  "description": "Cancelamento de NF-e homologado",
  "totalInvoiceAmount": null,
  "operationType": "Outgoing",
  "environmentType": 0
}
```

---

## 5. Payloads de CT-e

CT-e usa um **shape distinto** do payload de NF-e — campos típicos do
transporte (`recipient`, `sender`, `taker`, `dispatcher`,
`productInvoices`) substituem `issuer`/`buyer`/`transportation`. O CT-e
também carrega um `id` próprio (GUID gerado pela API) e `nsu` como
**número** (em NF-e é string).

### 5.1. `transportation_invoice_inbound` / `issued_successfully`

Enviado quando um **CT-e novo autorizado** é recebido via DistribuicaoDFe. Helper: `CTeService.SendCTeWebhook`, que emite um `CTeMetadataWebhookResource`.

**Sempre populados (no servidor):**

| Campo | Tipo | Fonte | Descrição |
|---|---|---|---|
| `id` | string (GUID) | gerado API | Identificador interno NFE.io. |
| `createdOn` | DateTime? | gerado API | Quando o NFE.io recebeu o documento (com milissegundos). |
| `accessKey` | string (44 dígitos) | `infCte/@Id` (sem prefixo `CTe`) | Chave de acesso do CT-e. |
| `parentAccessKey` | string | gerado API | Sempre `""` (string vazia) para CT-e raiz. |
| `nsu` | long (number) | Envelope DistribuicaoDFe | NSU do registro. ⚠️ É `long`, não string (em NF-e é string). |
| `company.id` | string | gerado API | ID da empresa NFE.io. |
| `type` | string | gerado API | Sempre `"transportationInvoice"`. |
| `description` | string | gerado API | Sempre o literal `"Autorizado o uso do CT-e"`. |
| `xmlUrl` | string | gerado API | URL absoluta do XML do CT-e. |

**Campos opcionais (podem estar ausentes quando todos os internos forem
`null` — comportamento da serialização global, §3):**

| Campo | Fonte XML | Quando some |
|---|---|---|
| `company.federalTaxNumber` | gerado API | Se o servidor não populou (raro). Sempre presente em fluxo normal. |
| `recipient.federalTaxNumber`, `recipient.name` | `infCte/dest/{CNPJ\|CPF, xNome}` | Se o CT-e não declarou destinatário ou só um dos campos veio nulo. |
| `sender.federalTaxNumber`, `sender.name` | `infCte/rem/{CNPJ\|CPF, xNome}` | Idem para remetente. |
| `taker.federalTaxNumber`, `taker.name` | `infCte/ide/toma3` ou `toma4` | Idem para tomador. |
| `dispatcher.federalTaxNumber`, `dispatcher.name` | `infCte/exped/{CNPJ\|CPF, xNome}` | Expedidor é opcional na SEFAZ; ausente quando não declarado. |
| `issuedOn` | `infCte/ide/dhEmi` | Apenas se anomalia no XML. |
| `productInvoices` | NF-es referenciadas | Array com objetos `{ accessKey }`. Pode vir vazio (`[]`) ou ausente se o CT-e não declara NF-es. |
| `totalAmount` | `infCte/vPrest/vTPrest` (formato `"0.00"`) | Se o XML não tem o campo `vTPrest`. |

**Campos do shape NÃO populados (sempre ausentes):**

- `issuer` e `buyer` — herdados do `MetadataResource`, mas o helper de
  CT-e não os instancia. CT-e usa `sender`/`recipient` em vez disso.

> ⚠️ **Em produção, os payloads de CT-e podem chegar bastante enxutos.**
> Quando o XML não declara participantes opcionais e o NSU foi emitido
> sem `vPrest`, é normal o payload conter só os campos do primeiro bloco
> da tabela acima (Sempre populados) — sem `recipient`, `sender`,
> `productInvoices` ou `totalAmount`. Veja o exemplo abaixo.

**Exemplo JSON — payload real enxuto (anonimizado), conteúdo top-level
de `body` (sem o wrapper do §3):**

```json
{
  "issuedOn": "2026-05-19T07:48:34Z",
  "id": "94152fd4-07ec-4145-88c7-01c2595da531",
  "createdOn": "2026-05-19T11:51:53.896Z",
  "accessKey": "35260542584754000267570023199390221999999996",
  "parentAccessKey": "",
  "nsu": 53642910,
  "company": {
    "id": "99999999999999999999999"
  },
  "type": "transportationInvoice",
  "description": "Autorizado o uso do CT-e",
  "xmlUrl": "https://api.nfse.io/v2/companies/99999999999999999999999/inbound/35260542584754000267570023199390221999999996/xml"
}
```

**Notas sobre o exemplo:**

- `company.federalTaxNumber` está omitido neste payload — o servidor não
  o populou. Use o `id` para casar com a sua empresa.
- Nenhum dos participantes (`recipient`, `sender`, `taker`, `dispatcher`)
  aparece — todos foram omitidos pelo filtro de `null` da serialização.
  **Isso não significa que a CT-e não os teve no XML** — pode ser que o
  parser ainda não popule esses campos do XML completo. Para os dados
  fiscais detalhados, baixe o XML via `xmlUrl`.
- `productInvoices` e `totalAmount` também estão ausentes — caso típico.

**Exemplo JSON — payload completo (quando o XML declara todos os
participantes):**

```json
{
  "id": "c0b3a1f2-e340-420f-dc94-ad10c0b3a1f2",
  "createdOn": "2026-05-13T16:20:00.000Z",
  "accessKey": "35240187654321000111570010000045671234567890",
  "parentAccessKey": "",
  "nsu": 21900,
  "company": {
    "id": "54244e0ee340420fdc94ad10",
    "federalTaxNumber": "98765432000100"
  },
  "type": "transportationInvoice",
  "description": "Autorizado o uso do CT-e",
  "xmlUrl": "https://api.nfse.io/v2/companies/54244e0ee340420fdc94ad10/inbound/35240187654321000111570010000045671234567890/xml",
  "recipient": {
    "federalTaxNumber": "12345678000195",
    "name": "DESTINATARIO LTDA"
  },
  "sender": {
    "federalTaxNumber": "98765432000100",
    "name": "REMETENTE S.A."
  },
  "taker": {
    "federalTaxNumber": "55566677000188",
    "name": "TOMADOR DO SERVICO LTDA"
  },
  "dispatcher": {
    "federalTaxNumber": "11122233000144",
    "name": "EXPEDIDOR LOGISTICA LTDA"
  },
  "issuedOn": "2026-05-13T15:00:00Z",
  "productInvoices": [
    { "accessKey": "35240112345678000195550010000012341234567890" },
    { "accessKey": "35240112345678000195550010000012351234567891" }
  ],
  "totalAmount": "850.00"
}
```

> ⚠️ **Diferenças de tipos vs NF-e**: o CT-e tem `id` próprio (GUID) — a
> NF-e usa apenas `accessKey`. O CT-e tem `nsu` como **long**; a NF-e
> tem `nsu` como **string**.

### 5.2. `transportation_invoice_inbound` / `event_raised_successfully`

Enviado quando um **evento de CT-e** é recebido (cancelamento, prestação
em desacordo, etc.). Helper: `CTeService.SendCTeEventWebhook`, que emite um `CTeEventMetadataResource` — payload **bem mais enxuto** que CT-e completo: sem participantes, sem `productInvoices`, sem `totalAmount`.

**Campos do shape (10 ao todo):**

| Campo | Tipo | Fonte | Descrição |
|---|---|---|---|
| `id` | string (GUID) | gerado API | Identificador interno NFE.io. |
| `createdOn` | DateTime? | gerado API | Quando o NFE.io recebeu o evento (com milissegundos). |
| `accessKey` | string | `evento/infEvento/@Id` — **mantém o prefixo `ID`** vindo do XML | Chave do **evento** (não do CT-e pai). Ex.: `ID110111352605...0001`. |
| `parentAccessKey` | string | `evento/infEvento/chCTe` | Chave do CT-e referenciado (44 dígitos). |
| `nsu` | long | Envelope DistribuicaoDFe | NSU do registro do evento (numérico, não string). |
| `company.id` | string | gerado API | ID da empresa NFE.io. |
| `company.federalTaxNumber` | string (opcional) | gerado API | Pode estar ausente. |
| `type` | string | gerado API | Sempre `"transportationInvoiceEvent"`. |
| `description` | string | `procEventoCTe/retEventoCTe/infEvento/xEvento` | Texto curto do evento (lido apenas de `xEvento`, sem fallback para `descEvento` — ver `CTeGateway.cs` L342). **Cancelamento** chega como `"Cancelamento"` (não `"Cancelamento de CT-e homologado"` como versões anteriores deste documento afirmavam). |
| `xmlUrl` | string | gerado API | URL para baixar o XML do evento. |
| `receiptOn` | DateTime? | `procEventoCTe/retEventoCTe/infEvento/dhRegEvento` | Data/hora em que a SEFAZ registrou o evento. |

⚠️ **Diferença vs NF-e (§4.2):** o `accessKey` do evento de CT-e **preserva o
prefixo `ID`** (resultado da leitura direta do `Id` do XML pelo gateway),
enquanto o evento de NF-e tem o `ID` removido pelo serviço (`{tpEvento}{chave}{seq}`).

**Não há campos de enrichment para CT-e evento** — o shape
`CTeEventMetadataResource` não declara `recipient`, `sender`, etc. Se
você precisa dos dados do CT-e pai, consulte-o via
`GET /v2/companies/{companyId}/inbound/{parentAccessKey}` (mas note a §8.2
do doc combinado: aquele endpoint REST também não retorna participantes —
só o payload do webhook §5.1 carrega isso).

**Exemplo JSON — payload real anonimizado (conteúdo top-level de `body`,
sem o wrapper do §3):**

```json
{
  "receiptOn": "2026-05-16T00:03:27Z",
  "id": "493d2525-d9e8-4c3f-b30f-c70510147e06",
  "createdOn": "2026-05-16T03:21:04.943Z",
  "accessKey": "ID11011135260555442952000157570010168676041999999990001",
  "parentAccessKey": "35260555442952000157570010168676041999999990",
  "nsu": 55125,
  "company": {
    "id": "999999999999999999999999999999",
    "federalTaxNumber": "55271322000167"
  },
  "type": "transportationInvoiceEvent",
  "description": "Cancelamento",
  "xmlUrl": "https://api.nfse.io/v2/companies/999999999999999999999999999999/inbound/35260555442952000157570010168676041999999990/events/ID11011135260555442952000157570010168676041999999990001/xml"
}
```

**Notas sobre o exemplo:**

- `accessKey` começa com `ID110111` — prefixo `ID` + `tpEvento` (110111
  = cancelamento) + chave do CT-e (44 dígitos) + sequência (`001`,
  3 dígitos padded).
  Total: 55 caracteres (2 letras + 53 dígitos).
- `description` é apenas `"Cancelamento"` — texto curto vindo do XML do
  evento, **não** `"Cancelamento de CT-e homologado"`.
- A ordem dos campos no JSON pode variar — não dependa dela.

> Se você precisa de detalhes do CT-e parent (participantes, valores,
> NF-es transportadas), busque-o via
> `GET /v2/companies/{companyId}/inbound/transportationinvoices/{parentAccessKey}`.

---

## 6. Mapeamento `tpEvento` SEFAZ → `eventAction`

### 6.1. NF-e

A SEFAZ usa códigos `tpEvento` de 6 dígitos para identificar cada tipo de
evento. O serviço NFE.io mapeia os 4 códigos de manifestação do
destinatário (`21020x`/`21024x`) para `input_event_raised_successfully`
e demais para `event_raised_successfully`:

| `tpEvento` | Descrição | `eventAction` |
|---|---|---|
| `110110` | Carta de Correção (CC-e) | `event_raised_successfully` |
| `110111` | Cancelamento de NF-e | `event_raised_successfully` |
| `110140` | EPEC (Evento Prévio de Emissão em Contingência) | `event_raised_successfully` |
| `110150` | Registro de Passagem Eletrônico | `event_raised_successfully` |
| `110160` | Manifestação do Fisco | `event_raised_successfully` |
| `210200` | Confirmação da Operação (destinatário) | `input_event_raised_successfully` |
| `210210` | Ciência da Operação (destinatário) | `input_event_raised_successfully` |
| `210220` | Operação Desconhecida (destinatário) | `input_event_raised_successfully` |
| `210240` | Operação Não Realizada (destinatário) | `input_event_raised_successfully` |

Outros `tpEvento` da SEFAZ (não listados acima) caem por default em
`event_raised_successfully`.

### 6.2. CT-e

| `tpEvento` | Descrição | `eventAction` |
|---|---|---|
| `110110` | Carta de Correção CT-e | `event_raised_successfully` |
| `110111` | Cancelamento de CT-e | `event_raised_successfully` |
| `110140` | EPEC para CT-e | `event_raised_successfully` |
| `610110` | Prestação de Serviço em Desacordo | `event_raised_successfully` |

CT-e não tem split de manifestação como NF-e — todos os eventos saem com
`event_raised_successfully`.

---

## 7. Validação HMAC

Para garantir que o webhook realmente veio da nfe.io (e não de terceiros
mal-intencionados), valide a assinatura HMAC-SHA256 no header da
requisição:

**Python (Flask):**

```python
import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = b"seu_secret_aqui"  # configurado no painel nfe.io

def validate_webhook(payload_bytes: bytes, received_signature: str) -> bool:
    expected = hmac.new(WEBHOOK_SECRET, payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_signature)

@app.route('/webhooks/nfeio', methods=['POST'])
def receive():
    signature = request.headers.get('X-NFe-Signature', '')
    if not validate_webhook(request.data, signature):
        abort(401, 'Assinatura inválida')

    body = request.json['body']
    event_action = body['action']                # ex.: issued_successfully
    document_type = body['type']                 # ex.: productInvoice / transportationInvoiceEvent
    access_key = body.get('accessKey')

    # Despache por (event_action, document_type) — ver matriz no §12.
    # Os campos do payload (accessKey, company, issuer, ...) estão
    # espalhados em `body`, não sob `body.data`.
    return '', 200
```

**Node.js (Express):**

```javascript
const crypto = require('crypto');
const express = require('express');
const app = express();

const WEBHOOK_SECRET = 'seu_secret_aqui';

app.post('/webhooks/nfeio', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-nfe-signature'] || '';
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(401).send('Assinatura inválida');
  }

  const body = JSON.parse(req.body).body;
  const { action, type, accessKey } = body;
  // `action` é o eventAction (ex.: issued_successfully).
  // `type` é o tipo do documento (ex.: productInvoice, transportationInvoiceEvent).
  // Demais campos (`company`, `issuer`, ...) estão diretamente em `body`.
  // Despache por (action, type) — ver matriz no §12.
  res.status(200).end();
});
```

> Configure o **Webhook Secret** no painel nfe.io → Empresas → \{sua
> empresa\} → Webhooks. Sem ele, qualquer pessoa que descobrir sua URL
> pode simular notificações.

---

## 8. URLs de download do XML

O payload do webhook **não embute o XML** — em vez disso, carrega uma URL
para um endpoint público da API NFE.io. **Onde** essa URL fica depende do
tipo de payload, porque o shape compartilhado expõe dois campos
diferentes para essa finalidade:

| Webhook | Campo com a URL do XML |
|---|---|
| §4.1 NF-e completa | `links.xml` |
| §4.2 evento NF-e (cancelamento, CC-e, EPEC, etc.) | `links.xml` |
| §4.3 manifestação | `links.xml` |
| §4.4.1 resumo NF-e | `links.xml` |
| §4.4.2 resumo de evento NF-e | `xmlUrl` (top-level) |
| §5.1 CT-e completo | `xmlUrl` (top-level) |
| §5.2 evento CT-e | `xmlUrl` (top-level) |

> Para NF-e existe também o campo `links.pdf` com a URL do DANFE
> (PDF) — só em webhooks de NF-e completa (§4.1). Em todos os webhooks
> de evento NF-e, `links.pdf` vem como string vazia (`""`); em resumos,
> vem `null`.

> Os campos `xmlUrl` em NF-e completa/evento/manifestação/resumo-NF-e e
> `links` em CT-e/resumo-de-evento-NF-e **nunca** vêm populados. Esta é
> uma vestígio de polimorfismo no shape `NFeMetadataResource`, compartilhado
> entre vários consumidores REST e webhook — não há duplicação real no
> payload.

### Comportamento do endpoint apontado pela URL

Independentemente de qual campo carregue a URL (`links.xml` ou `xmlUrl`),
ela aponta para um destes endpoints públicos:

- **NF-e (completa)**: `GET /v2/companies/{companyId}/inbound/{accessKey}/xml`
- **NF-e (evento)**: `GET /v2/companies/{companyId}/inbound/{accessKey}/events/{eventId}/xml`
- **CT-e (completo)**: `GET /v2/companies/{companyId}/inbound/{accessKey}/xml`
- **CT-e (evento)**: `GET /v2/companies/{companyId}/inbound/{accessKey}/events/{eventId}/xml`

Roteamento por modelo é feito pelos dígitos 21–22 da chave (modelo do
documento), via `accessKey.slice(20, 22)`: `55` ⇒ NF-e, demais ⇒ CT-e.
Autenticação via header `Authorization: <API_KEY>`.

### Comportamento da resposta

A resposta NÃO é um redirect HTTP. O endpoint retorna:

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "publicTemporaryUri": "https://<storage-host>/<path>?<query-de-acesso-temporário>"
}
```

A `publicTemporaryUri` é uma **URL assinada de acesso direto ao blob**
(armazenamento de objetos da NFE.io), com **TTL de ~10 minutos** por
default. Cliente faz um segundo `GET` nessa URL para baixar o XML
diretamente — sem precisar do header `Authorization` (a assinatura na
query string autoriza o acesso).

**Fluxo cliente típico:**

```python
import requests

# Passo 1 — pedir o link temporário (autenticado)
r1 = requests.get(
    f"https://api.nfse.io/v2/companies/{company_id}/inbound/{access_key}/xml",
    headers={"Authorization": API_KEY},
)
temp_uri = r1.json()["publicTemporaryUri"]

# Passo 2 — baixar o XML pelo link temporário (sem autenticação)
r2 = requests.get(temp_uri)
xml_bytes = r2.content
```

### PDF

CT-e **não tem PDF** — o endpoint
`GET .../inbound/{accessKey}/pdf` retorna `204 No Content` para
chaves CT-e (modelo `57`).

NF-e tem PDF (DANFE) gerado pela API: mesmo padrão de resposta
(`200 OK` com `publicTemporaryUri`). Acesse via
`GET /v2/companies/{companyId}/inbound/{accessKey}/pdf`.

### Após expiração da URL temporária

Quando a `publicTemporaryUri` expira (~10 min), o blob storage retorna
erro HTTP no segundo GET. O endpoint público da API permanece válido —
basta requisitar `/xml` novamente para obter nova `publicTemporaryUri`
fresca.

> **Recomendação:** baixe e armazene XML logo após receber o webhook.
> Para acesso posterior, sempre chame `/xml` para obter URL temporária
> nova — não cacheie a `publicTemporaryUri`.

---

## 9. Reprocessamento de webhook

Se você precisar **receber novamente** um webhook (porque seu endpoint
estava fora do ar, ou houve bug no consumer), use os endpoints:

**NF-e:**

```http
POST /v2/companies/{companyId}/inbound/productinvoices/{accessKey}/processwebhook
Authorization: {api_key}
```

**CT-e:**

```http
POST /v2/companies/{companyId}/inbound/transportationinvoices/{accessKey}/processwebhook
Authorization: {api_key}
```

Ambos retornam `200 OK` e disparam novamente o webhook para a URL
configurada da empresa.

---

## 10. Idempotência

Webhooks **podem ser entregues mais de uma vez** em caso de retry após
falha temporária. Seu consumer deve ser idempotente:

- **Use `accessKey` como chave única** (NF-e e CT-e completos). Se já
  processou, ignore.
- **Use `(parentAccessKey, accessKey)` como chave única para eventos** —
  o `accessKey` do evento inclui o `tpEvento` no prefixo, garantindo
  unicidade.
- **Não use `nsu`** como chave — o NSU pertence ao registro DFe, não ao
  documento; reprocessamento pode gerar novo NSU.

---

## 11. Boas práticas de integração

1. **Responda rápido**: retorne HTTP 200 em menos de 5 segundos e
   processe assincronamente. O timeout da NFE.io é 30 segundos.
2. **Persista primeiro**: salve o payload no seu banco antes de
   processar, para não perder dados em crash do consumer.
3. **Baixe os arquivos cedo**: chame `/xml` (e `/pdf` quando aplicável)
   logo após receber o webhook e persista o conteúdo localmente —
   `publicTemporaryUri` expira em ~10 minutos.
4. **Implemente idempotência por `accessKey`** — webhooks podem ser
   reentregues após retry. Ver §10.
5. **Roteie por `(body.type, body.action)`** — a combinação dos 2 é o
   discriminador estável. Não filtre apenas por um deles.
6. **Trate `productInvoices: []` em CT-e como normal** — alguns CT-es
   declaram só a operação de transporte sem listar NF-es individuais.
7. **Não cacheie URLs temporárias** — `publicTemporaryUri` expira;
   sempre re-chame `/xml` quando precisar de acesso novo.
8. **Trate o split `event_raised_successfully` vs `input_event_raised_successfully`**
   no consumer — manifestações do destinatário (§4.3) têm semântica
   distinta de eventos do emissor (§4.2).
9. **Configure alertas** para HTTP 5xx no seu endpoint de webhook —
   detecte problemas antes de esgotar o orçamento de retries (50x em 24h).

---

## 12. Troubleshooting

### Recebi um payload com vários campos ausentes ou objetos vazios. É bug?

Não. Veja §3 "Serialização: campos `null` são omitidos por padrão". O
serializador da API está configurado para omitir campos `null` no JSON.
Resultado prático:

- Em `product_invoice_inbound_summary`, muitos campos do shape vêm
  ausentes (porque o resumo da SEFAZ não os preenche).
- Em `product_invoice_inbound` / `event_raised_successfully`, campos de
  enrichment da NF-e pai podem estar ausentes quando a NF-e ainda não foi
  indexada.
- Em `transportation_invoice_inbound` / `issued_successfully`,
  containers como `recipient` ou `sender` podem estar ausentes ou chegar
  como `{}` quando o CT-e não declara o participante.

Codifique seu parser para tolerar tanto ausência da chave quanto valor
`null`.

### `productInvoices` veio vazio no CT-e — está certo?

Sim, é possível. Alguns CT-es declaram apenas a operação de transporte
sem listar NF-es individuais (raro mas válido pela SEFAZ). Trate
`productInvoices: []` como caso normal — não como erro.

### Estou recebendo `input_event_raised_successfully` para uma operação minha. Por quê?

Significa que **o destinatário** (não você) registrou uma manifestação
sobre a operação. Se você é o destinatário das NF-es recebidas via
Inbound, isso reflete suas próprias manifestações sendo replicadas no
webhook (ou de seu sistema, ou via painel nfe.io). Ver §4.3.

### Não recebo webhooks. Checklist:

1. URL configurada no painel nfe.io → Empresas → Webhooks? Pode levar
   alguns minutos para propagar após mudança.
2. Inbound ativo para a empresa? Ver `02-doc-tecnica-clientes-nfe-cte-dev-pt.md`
   §6 "Ativando o Serviço de Inbound".
3. `WebhookVersion: 2` configurado na ativação? V1 usa formato diferente
   e está deprecado.
4. Endpoint retornando 200 em até 30s? Status 4xx (exceto 408/429) marca
   falha definitiva e **não** reenvia.
5. NSU pendente? Existe gap de NSUs na fila? Verifique via
   `GET .../inbound/productinvoices?nsuInicial=...` (ver doc API).

### Chamei `/xml` mas o response não tem o XML — só uma URL. É bug?

Não. Diferente do NFS-e (que faz `302 Found` redirect), o endpoint
`/xml` de NF-e/CT-e retorna `200 OK` com JSON `{ "publicTemporaryUri":
"<URL temporária do blob>" }`. Faça um segundo `GET` na
`publicTemporaryUri` (sem header `Authorization`) para baixar o XML.
TTL ~10 min — não cacheie. Ver §8.

### Como diferencio resumo vs documento completo?

Pelo par `(body.action, body.type)` no envelope. `body.action` é o
`eventAction` da rota interna; `body.type` é o campo do payload
(ver §3 e §4/§5):

| `body.action` | `body.type` | Significado |
|---|---|---|
| `issued_successfully` | `productInvoice` | NF-e completa |
| `event_raised_successfully` | `productInvoiceEvent` | Evento NF-e completo |
| `input_event_raised_successfully` | `productInvoiceEvent` | Manifestação do destinatário |
| `issued_successfully` | `productInvoiceSummary` | Resumo NF-e |
| `event_raised_successfully` | `productInvoiceEventSummary` | Resumo evento NF-e |
| `issued_successfully` | `transportationInvoice` | CT-e completo |
| `event_raised_successfully` | `transportationInvoiceEvent` | Evento CT-e |

Use **`body.action`** para diferenciar a **ação** (emissão, evento,
manifestação) e **`body.type`** para diferenciar a **variante** do
documento (NF-e/CT-e, completa/resumo, documento/evento).

> O `eventType` da rota interna (`product_invoice_inbound`,
> `product_invoice_inbound_summary`, `transportation_invoice_inbound`)
> determina qual webhook do painel é disparado, mas **não é necessariamente
> propagado** dentro de `body`. Não dependa dele para parsing — use
> `body.type`.

---

## 13. Anatomia da chave de acesso (NF-e/NFC-e e CT-e)

A `accessKey` que aparece nos payloads de webhook é uma identificação
única atribuída pela SEFAZ a cada documento fiscal e a cada evento.
Esta seção descreve a composição posicional para você decodificar
campos diretamente da chave (sem precisar parsear o XML).

> 📚 **Fonte oficial.** As regras abaixo seguem o Manual de Orientação do
> Contribuinte (MOC) **NF-e 7.0**, item 5.4, e o MOC **CT-e 4.00**, item
> 2.1.4. Para NFS-e Nacional, ver o §11 do webhook NFS-e
> `02-doc-tecnica-clientes-dev-nfse-inbound-webhook.md`.

### 13.1. NF-e (modelo 55) e NFC-e (modelo 65) — 44 dígitos

```
35 2605 57622466000146 55 001 001132098 1 99999999 3
└─┬┘└─┬─┘└─────┬──────┘└┬┘└┬┘└────┬────┘└┬┘└───┬────┘└┬┘
  │   │       │        │  │      │      │     │      │
 cUF AAMM   CNPJ      mod sér   nNF   tpEmis cNF    cDV
```

| Pos. | Tam. | Campo | Descrição |
|---|---|---|---|
| 1–2 | 2 | `cUF` | Código IBGE da UF do emitente. Ex.: `35` = SP, `33` = RJ, `41` = PR. |
| 3–6 | 4 | `AAMM` | Ano (2 dígitos) + mês (2 dígitos) de emissão. Ex.: `2605` = maio/2026. |
| 7–20 | 14 | `CNPJ` do emitente | CNPJ com 14 dígitos (sem máscara). |
| 21–22 | 2 | `mod` | Modelo do documento: `55` = NF-e, `65` = NFC-e. |
| 23–25 | 3 | `serie` | Série do documento (0–999, com zeros à esquerda). |
| 26–34 | 9 | `nNF` | Número sequencial da NF-e/NFC-e. |
| 35 | 1 | `tpEmis` | Forma de emissão: `1` Normal, `2` Contingência FS-IA, `3` SCAN, `4` EPEC, `5` FS-DA, `6` SVC-AN, `7` SVC-RS, `9` Contingência off-line NFC-e. |
| 36–43 | 8 | `cNF` | Código numérico aleatório (8 dígitos). |
| 44 | 1 | `cDV` | Dígito verificador (módulo 11). |

**Exemplo decodificado** (chave `35260557622466000146550010011320981999999993`,
extraída do exemplo da §4.1):

| Campo | Valor | Leitura |
|---|---|---|
| `cUF` | `35` | São Paulo |
| `AAMM` | `2605` | Maio/2026 |
| `CNPJ` | `57622466000146` | Emitente |
| `mod` | `55` | NF-e (modelo 55) |
| `serie` | `001` | Série 1 |
| `nNF` | `001132098` | Número 1.132.098 |
| `tpEmis` | `1` | Emissão normal |
| `cNF` | `99999999` | Código aleatório |
| `cDV` | `3` | DV |

### 13.2. Chave do evento NF-e — 51 dígitos (sem prefixo `ID`)

Para eventos de NF-e/NFC-e (cancelamento, CC-e, EPEC, registros do
fisco, manifestações do destinatário), o NFE.io entrega no campo
`accessKey` uma chave de **51 dígitos**, gerada como:

```
{tpEvento}{chaveNFe}{nSeqEvento}
```

| Pos. | Tam. | Campo | Descrição |
|---|---|---|---|
| 1–6 | 6 | `tpEvento` | Código do evento SEFAZ (6 dígitos). Tabela em §6.1. Ex.: `110110` (CC-e), `110111` (cancelamento), `210210` (ciência). |
| 7–50 | 44 | `chaveNFe` | Chave de acesso da NF-e referenciada (§13.1). |
| 51 | 1 | `nSeqEvento` | Sequencial do evento para a mesma NF-e (1–99, normalmente `1`). |

> ⚠️ **Sem o prefixo `ID`.** No XML SEFAZ o atributo `infEvento/@Id` traz
> `"ID" + tpEvento + chNFe + nSeqEvento` (53 caracteres). O NFE.io
> **remove** o prefixo `ID` ao gravar o `EventId` na base e ao serializar
> o webhook (ver `NFeService.cs` linhas 1798–1799 — `nfeEventMetadata.EventId = $"{chNfe}{nfeEventMetadata.Sequence}"`).
> O `parentAccessKey` no mesmo payload contém apenas a `chaveNFe`
> (44 dígitos). Para o CT-e o prefixo `ID` é preservado — ver §13.4.

**Exemplo decodificado**
(chave `110111412605999999999999995500200059985119999999941`, extraída do
exemplo de cancelamento da §4.2):

| Campo | Valor | Leitura |
|---|---|---|
| `tpEvento` | `110111` | Cancelamento de NF-e |
| `chaveNFe` | `41260599999999999999550020005998511999999994` | NF-e referenciada (PR/maio/2026/...) |
| `nSeqEvento` | `1` | Primeiro evento de cancelamento |

### 13.3. CT-e (modelo 57) — 44 dígitos

A composição é idêntica à da NF-e, com `mod=57`:

```
35 2605 42584754000267 57 002 319939022 1 99999999 6
└─┬┘└─┬─┘└─────┬──────┘└┬┘└┬┘└────┬────┘└┬┘└───┬────┘└┬┘
  │   │       │        │  │      │      │     │      │
 cUF AAMM   CNPJ      mod sér   nCT   tpEmis cCT    cDV
```

| Pos. | Tam. | Campo | Descrição |
|---|---|---|---|
| 1–2 | 2 | `cUF` | Código IBGE da UF do emitente. |
| 3–6 | 4 | `AAMM` | Ano + mês de emissão. |
| 7–20 | 14 | `CNPJ` do emitente | CNPJ do prestador do serviço de transporte. |
| 21–22 | 2 | `mod` | Sempre `57` para CT-e. (`67` = CT-e OS, `63` = CT-e GTV — não tratados por este webhook.) |
| 23–25 | 3 | `serie` | Série do documento. |
| 26–34 | 9 | `nCT` | Número sequencial do CT-e. |
| 35 | 1 | `tpEmis` | Forma de emissão: `1` Normal, `4` EPEC, `5` FS-DA, `7` SVC-RS, `8` SVC-SP. |
| 36–43 | 8 | `cCT` | Código numérico aleatório. |
| 44 | 1 | `cDV` | Dígito verificador (módulo 11). |

**Exemplo decodificado**
(chave `35260542584754000267570023199390221999999996`, extraída do
exemplo da §5.1):

| Campo | Valor | Leitura |
|---|---|---|
| `cUF` | `35` | São Paulo |
| `AAMM` | `2605` | Maio/2026 |
| `CNPJ` | `42584754000267` | Prestador do transporte |
| `mod` | `57` | CT-e |
| `serie` | `002` | Série 2 |
| `nCT` | `319939022` | Número 319.939.022 |
| `tpEmis` | `1` | Normal |

### 13.4. Chave do evento CT-e — 55 caracteres (com prefixo `ID`)

```
ID{tpEvento}{chaveCTe}{nSeqEvento}
```

| Pos. | Tam. | Campo | Descrição |
|---|---|---|---|
| 1–2 | 2 | Prefixo literal | `ID` (preservado do XML SEFAZ). |
| 3–8 | 6 | `tpEvento` | Código do evento (ver §6.2). Ex.: `110111` (cancelamento), `110110` (CC-e CT-e), `610110` (prestação em desacordo). |
| 9–52 | 44 | `chaveCTe` | Chave de acesso do CT-e referenciado (§13.3). |
| 53–55 | 3 | `nSeqEvento` | Sequencial do evento (1–999), com zeros à esquerda. |

> ⚠️ **Diferença em relação ao evento NF-e**: o CT-e **preserva** o
> prefixo `ID` e usa 3 dígitos para o sequencial; o evento NF-e remove o
> prefixo e usa 1 dígito (ver §13.2).

**Exemplo decodificado**
(chave `ID11011135260555442952000157570010168676041999999990001`,
extraída do exemplo de cancelamento da §5.2):

| Campo | Valor | Leitura |
|---|---|---|
| Prefixo | `ID` | Literal |
| `tpEvento` | `110111` | Cancelamento de CT-e |
| `chaveCTe` | `35260555442952000157570010168676041999999990` | CT-e referenciado |
| `nSeqEvento` | `001` | Primeiro evento |

### 13.5. Validação do DV (módulo 11)

O último dígito (`cDV`) é calculado com módulo 11 base 2-9 sobre os
43 dígitos anteriores. Algoritmo de referência (MOC NF-e 7.0 §5.4 / MOC
CT-e 4.00 §7.3):

```python
def calc_dv(chave43: str) -> str:
    weights = (2, 3, 4, 5, 6, 7, 8, 9)
    total = sum(int(d) * weights[i % 8] for i, d in enumerate(reversed(chave43)))
    dv = 11 - (total % 11)
    return "0" if dv >= 10 else str(dv)

# Uso:
chave = "35260557622466000146550010011320981999999993"
assert calc_dv(chave[:-1]) == chave[-1]
```

Use esse cálculo para validar integridade da chave antes de persistir no
seu sistema. Se o DV não bater, o payload provavelmente sofreu corrupção
no transporte — rejeite e force reprocessamento via §9.

---

## API de Certificados Digitais ICP-Brasil | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/gerenciamento-empresas/api-certificados/index.md

# API de Certificados (Certificates)

## Gerencie certificados digitais ICP-Brasil das empresas

> **Navegação**
> - [← Voltar para Visão Geral](./gerenciamento-empresas-resumo.md)
> - [Empresas →](./gerenciamento-empresas.md)
> - [Inscrições Estaduais →](./gerenciamento-inscricao-estadual.md)
> - [Inscrições Municipais →](./gerenciamento-inscricao-municipal.md)

---

## Visão Geral

O **Certificado Digital ICP-Brasil** funciona como uma identidade eletrônica para empresas, permitindo a identificação segura e inequívoca do autor de uma transação feita em meios eletrônicos.

Para emitir Documentos Fiscais Eletrônicos (NF-e, NFC-e, NFS-e), é **obrigatório** vincular um certificado digital válido à empresa emissora.

---

## Anatomia de um Certificado

### Conceitos Fundamentais

Ao fazer upload de um certificado, você precisa fornecer:

| Conceito | Campos na API | Descrição |
|----------|---------------|-----------|
| **Arquivo** | `File` | Certificado em formato `.pfx` ou `.p12` |
| **Credencial** | `Password` | Senha do certificado para validação |

### Requisitos do Certificado

| Requisito | Descrição |
|-----------|-----------|
| **Tipo** | e-CNPJ A1 ou NF-e A1 (certificados A3 não são suportados) |
| **Formato** | Arquivo `.pfx` ou `.p12` |
| **CNPJ** | Deve corresponder ao `FederalTaxNumber` da empresa |
| **Validade** | Não pode estar expirado |
| **Senha** | Obrigatória para upload e validação |

### Tipos de Certificado

| Tipo | Descrição | Suporte |
|------|-----------|---------|
| **e-CNPJ A1** | Certificado de pessoa jurídica em arquivo | ✅ Suportado |
| **NF-e A1** | Certificado específico para NF-e em arquivo | ✅ Suportado |
| **e-CPF A1** | Certificado de pessoa física | ❌ Não suportado |
| **A3** | Certificado em hardware (token/cartão) | ❌ Não suportado |

### Campos Gerenciados pelo Sistema

Após o upload, o sistema extrai e mantém automaticamente:

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `TaxPayerId` | string | ID da empresa vinculada |
| `Thumbprint` | string | Impressão digital única do certificado |
| `TaxId` | string | CNPJ extraído do certificado |
| `Subject` | string | Nome do certificado (Distinguished Name) |
| `ValidUntil` | datetime | Data de expiração |
| `Status` | enum | Status atual do certificado |
| `ModifiedOn` | datetime | Data da última modificação |

### Referência Completa de Propriedades

### 📋 Expandir tabela completa

| Propriedade | Tipo | Descrição |
|-------------|------|-----------|
| `TaxPayerId` | string | Identificador da empresa (company_id) |
| `Thumbprint` | string | Impressão digital única (hash SHA-1) |
| `TaxId` | string | CNPJ do certificado (somente dígitos) |
| `Subject` | string | Distinguished Name completo do certificado |
| `ValidUntil` | datetime | Data e hora de expiração (UTC) |
| `ModifiedOn` | datetime | Data e hora da última modificação (UTC) |
| `Status` | enum | Status atual: `Active`, `Overdue`, `Inactive`, `Pending`, `None` |

---

## Endpoints

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/v2/companies/{company_id}/certificates` | Upload de certificado |
| `GET` | `/v2/companies/{company_id}/certificates` | Listar certificados |
| `GET` | `/v2/companies/{company_id}/certificates/{thumbprint}` | Consultar certificado |
| `DELETE` | `/v2/companies/{company_id}/certificates/{thumbprint}` | Excluir certificado |

:::info[Autenticação]
Todos os endpoints exigem autenticação via API Key: `Authorization: <sua_api_key>`

→ **[Saiba como obter sua API Key](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/)**
:::

---

## Upload de Certificado

Faz upload de um certificado ICP-Brasil e vincula à empresa.

```http
POST /v2/companies/{company_id}/certificates
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `multipart/form-data` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição (Form Data)

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `File` | file | ✅ | Arquivo do certificado (.pfx ou .p12) |
| `Password` | string | ✅ | Senha do certificado |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Certificate": {
    "TaxPayerId": "company_abc123",
    "Thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
    "TaxId": "12345678000199",
    "Subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=Secretaria da Receita Federal do Brasil - RFB, O=ICP-Brasil, C=BR",
    "ValidUntil": "2025-06-15T23:59:59Z",
    "ModifiedOn": "2024-01-15T10:30:00Z",
    "Status": "Active"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Empresa não encontrada |
| `422 Unprocessable Entity` | Certificado expirado |

```json
{
  "Errors": [
    {
      "Code": 40034,
      "Message": "password is null or empty"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X POST https://api.nfse.io/v2/companies/company_abc123/certificates \
  -H "Authorization: sk_live_xxx" \
  -F "File=@certificado.pfx" \
  -F "Password=senha123"
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }
$form = @{
    File = Get-Item -Path ".\certificado.pfx"
    Password = "senha123"
}

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies/company_abc123/certificates" `
    -Method Post -Headers $headers -Form $form
```

---

## Listar Certificados

Lista os certificados vinculados à empresa.

```http
GET /v2/companies/{company_id}/certificates
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Certificates": [
    {
      "TaxPayerId": "company_abc123",
      "Thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
      "TaxId": "12345678000199",
      "Subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=RFB, O=ICP-Brasil, C=BR",
      "ValidUntil": "2025-06-15T23:59:59Z",
      "ModifiedOn": "2024-01-15T10:30:00Z",
      "Status": "Active"
    }
  ]
}
```

### Resposta Quando Não Há Certificado

**Status:** `200 OK`

```json
{
  "Certificates": []
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | company_id inválido |

```json
{
  "Errors": [
    {
      "Message": "company_id is null or empty"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123/certificates \
  -H "Authorization: sk_live_xxx"
```

---

## Consultar Certificado por Thumbprint

Retorna os detalhes de um certificado específico.

```http
GET /v2/companies/{company_id}/certificates/{certificate_thumbprint}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `certificate_thumbprint` | string | Impressão digital do certificado |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Certificate": {
    "TaxPayerId": "company_abc123",
    "Thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
    "TaxId": "12345678000199",
    "Subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=RFB, O=ICP-Brasil, C=BR",
    "ValidUntil": "2025-06-15T23:59:59Z",
    "ModifiedOn": "2024-01-15T10:30:00Z",
    "Status": "Active"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Certificado não encontrado |

```json
{
  "Errors": [
    {
      "Message": "Certificate not found"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123/certificates/A1B2C3D4E5F6789012345678901234567890ABCD \
  -H "Authorization: sk_live_xxx"
```

---

## Excluir Certificado

Exclui um certificado e desvincula da empresa.

:::warning[Atenção]
Este processo é **irreversível**. A empresa não poderá emitir documentos fiscais até que um novo certificado seja vinculado.
:::

```http
DELETE /v2/companies/{company_id}/certificates/{certificate_thumbprint}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `certificate_thumbprint` | string | Impressão digital do certificado |

### Headers

| Header | Valor |
|--------|-------|
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `204 No Content`

(Sem corpo na resposta)

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Certificado não encontrado |

### Exemplo cURL

```bash
curl -X DELETE https://api.nfse.io/v2/companies/company_abc123/certificates/A1B2C3D4E5F6789012345678901234567890ABCD \
  -H "Authorization: sk_live_xxx"
```

---

## Regras de Validação

O sistema aplica as seguintes regras de validação ao fazer upload de um certificado:

### Validação do Arquivo

| Campo | Regra | Mensagem de Erro |
|-------|-------|------------------|
| `File` | Obrigatório | File is null |
| `File` | Extensão deve ser .pfx ou .p12 | File extension is not valid (.pfx or .p12) |
| `Password` | Obrigatória | password is null or empty |
| `Password` | Deve ser válida para o certificado | Certificate password is invalid |

### Validação do Certificado

| Regra | Mensagem de Erro |
|-------|------------------|
| Dados devem ser válidos | Certificate data is invalid |
| Tipo deve ser e-CNPJ (não e-CPF) | Certificate type is invalid |
| Não pode estar expirado | Certificate expired |
| CNPJ deve corresponder ao da empresa | Certificate or company federal tax number is invalid |

### Validação da Empresa

| Regra | Código | Mensagem de Erro |
|-------|--------|------------------|
| Empresa deve existir | — | companyId not found |
| Empresa deve estar ativa | 40019 | company is not active |
| Empresa deve ter CNPJ cadastrado | 40031 | FederalTaxNumber is null |

---

## Códigos de Erro

### Validação de Arquivo e Certificado

| Mensagem | Descrição |
|----------|-----------|
| File is null | Arquivo não enviado |
| File extension is not valid (.pfx or .p12) | Extensão de arquivo inválida |
| Certificate password is invalid | Senha do certificado incorreta |
| Certificate data is invalid | Dados do certificado inválidos |
| Certificate type is invalid | Tipo não suportado (deve ser e-CNPJ) |
| Certificate expired | Certificado expirado |
| Certificate not found | Certificado não encontrado |
| Certificate or company federal tax number is invalid | CNPJ não corresponde |

### Validação de Empresa

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| — | company_id is null or empty | ID da empresa não informado |
| — | companyId not found | Empresa não encontrada |
| 40019 | company is not active | Empresa inativa |
| 40031 | FederalTaxNumber is null | Empresa sem CNPJ cadastrado |
| 40034 | password is null or empty | Senha não informada |

---

## Enums

### CertificateStatus (Status do Certificado)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -3 | Certificado inativo/excluído |
| `Overdue` | -2 | Certificado vencido |
| `Pending` | -1 | Certificado pendente de validação |
| `None` | 0 | Status não definido |
| `Active` | 1 | Certificado ativo e válido |

### IcpBrasilCertificateType (Tipo de Certificado)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `None` | 0 | Tipo não identificado |
| `eCPF` | 1 | Certificado de Pessoa Física (não suportado) |
| `eCNPJ` | 2 | Certificado de Pessoa Jurídica |

---

## Boas Práticas

### Preparação do Certificado

- Verifique se o tipo é **e-CNPJ A1** ou **NF-e A1**
- Verifique se a validade não está expirada
- Confirme que o CNPJ do certificado corresponde ao da empresa
- Mantenha a senha original em local seguro

### Renovação de Certificado

- Monitore a data de expiração (`ValidUntil`)
- Faça o upload do novo certificado **antes** do vencimento
- O sistema sobrescreve automaticamente o certificado anterior

### Segurança

- Nunca exponha a senha do certificado em logs ou URLs
- Use HTTPS em todas as requisições
- Armazene certificados em local seguro antes do upload
- Não compartilhe o arquivo do certificado

### Monitoramento

Verifique periodicamente o status do certificado:

| Status | Ação Recomendada |
|--------|------------------|
| `Active` | Nenhuma ação necessária |
| `Overdue` | Renovar imediatamente - emissões bloqueadas |
| `Inactive` | Fazer upload de novo certificado |
| `Pending` | Aguardar processamento |

---

## Próximos Passos

Após configurar o certificado:

1. **Crie uma Inscrição Estadual** para emitir NF-e/NFC-e → [Ver documentação](./gerenciamento-inscricao-estadual.md)
2. **Crie uma Inscrição Municipal** para emitir NFS-e → [Ver documentação](./gerenciamento-inscricao-municipal.md)

---

## Veja também:

- [API de Empresas](./gerenciamento-empresas.md) - Gerenciamento de empresas
- [Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) - Configuração para NF-e/NFC-e
- [Inscrições Municipais](./gerenciamento-inscricao-municipal.md) - Configuração para NFS-e

---

## API de Empresas (Companies) - Gerenciamento | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/gerenciamento-empresas/api-empresas/index.md

# API de Empresas (Companies)

## Gerencie empresas emissoras de documentos fiscais

> **Navegação**
> - [← Voltar para Visão Geral](./gerenciamento-empresas-resumo.md)
> - [Certificados →](./gerenciamento-certificado.md)
> - [Inscrições Estaduais →](./gerenciamento-inscricao-estadual.md)
> - [Inscrições Municipais →](./gerenciamento-inscricao-municipal.md)

---

## Visão Geral

A Empresa é a entidade central do sistema que representa a personalidade jurídica do negócio. Ela atua como um **"Hub de Identidade"**, concentrando todos os dados que são universais e imutáveis, independentemente do tipo de tributação ou esfera governamental.

---

## Anatomia de uma Empresa

### Conceitos Fundamentais

Ao criar uma empresa, você define **quem ela é**. Esses dados servem de base para qualquer emissão fiscal:

| Conceito | Campos na API | Descrição |
|----------|---------------|-----------|
| **Identificação Fiscal** | `FederalTaxNumber` | CNPJ - identificador único perante a Receita Federal |
| **Nomes Formais** | `Name`, `TradeName` | Razão Social (obrigatório) e Nome Fantasia |
| **Localização Base** | `Address` | Endereço fiscal de referência para todos os contextos |
| **Regime Tributário** | `TaxRegime` | Simples Nacional, Lucro Presumido, etc. |

### Campos Gerenciados pelo Sistema

Além dos dados que você informa, o sistema gera e mantém automaticamente:

| Campo | Tipo | Quando é definido |
|-------|------|-------------------|
| `Id` | string | Gerado na criação |
| `AccountId` | string | Vinculado à sua conta/tenant |
| `Status` | enum | Inicia como `Active` |
| `Type` | enum | Tipo de pessoa (PersonType) |
| `MunicipalTaxNumber` | Inscrição Municipal (legado) | Vinculado a Inscrição Municipal utilizada para emissão de notas fiscais de serviço |
| `CreatedOn` | datetime | Data/hora da criação |
| `ModifiedOn` | datetime | Atualizado a cada alteração |

### Campos de Contexto Tributário

Estes campos conectam a empresa às suas obrigações fiscais específicas:

| Campo | Descrição | Como é preenchido |
|-------|-----------|-------------------|
| `StateTaxes` | IDs das Inscrições Estaduais | Vinculado ao criar IE → [Ver StateTax API](./gerenciamento-inscricao-estadual.md) |
| `MunicipalTaxes` | IDs das Inscrições Municipais | Vinculado ao criar IM → [Ver MunicipalTax API](./gerenciamento-inscricao-municipal.md) |
| `STStateTaxNumber` | IE Substituto Tributário | Opcional na criação |
| `SuframaTaxNumber` | Inscrição SUFRAMA | Opcional na criação |
| `Certificate` | Certificado Digital A1 | Vinculado ao adicionar certificado → [Ver Certificate API](./gerenciamento-certificado.md) |

### Referência Completa de Propriedades

### 📋 Expandir tabela completa

| Propriedade | Tipo | Obrigatório | Descrição |
|-------------|------|:-----------:|-----------|
| `Id` | string | — | Identificador único (gerado) |
| `AccountId` | string | ✅ | Conta/tenant proprietária |
| `Name` | string | ✅ | Razão social (2-60 caracteres) |
| `TradeName` | string | — | Nome fantasia |
| `FederalTaxNumber` | long | ✅ | CNPJ (somente dígitos) |
| `MunicipalTaxNumber` | string | — | Inscrição Municipal |
| `STStateTaxNumber` | string | — | IE Substituto Tributário |
| `SuframaTaxNumber` | long | — | Inscrição SUFRAMA |
| `TaxRegime` | enum | ✅ | Regime tributário |
| `Status` | enum | — | Status operacional |
| `Type` | enum | — | Tipo de pessoa |
| `Address` | object | ✅ | Endereço completo |
| `StateTaxes` | array | — | IDs de IEs vinculadas |
| `MunicipalTaxes` | array | — | IDs de IMs vinculadas |
| `Certificate` | object | — | Metadados do certificado |
| `CreatedOn` | datetime | — | Data de criação |
| `ModifiedOn` | datetime | — | Última modificação |

---

## Endpoints

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/v2/companies` | Criar empresa |
| `GET` | `/v2/companies` | Listar empresas |
| `GET` | `/v2/companies/{company_id}` | Consultar empresa |
| `HEAD` | `/v2/companies/{company_id}` | Verificar existência |
| `PUT` | `/v2/companies/{company_id}` | Alterar empresa |
| `DELETE` | `/v2/companies/{company_id}` | Excluir empresa |

:::info[Autenticação]
Todos os endpoints exigem autenticação via API Key: `Authorization: <sua_api_key>`

→ **[Saiba como obter sua API Key](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/)**
:::

---

## Criar uma Empresa

Cria uma nova empresa na plataforma.

:::tip[Criar pela Plataforma]
Você também pode criar empresas diretamente pela interface da plataforma NFE.io. Veja o passo a passo em: [Criar Empresa](https://nfe.io/docs/documentacao/nossa-plataforma/criar-empresa/)
:::

```http
POST /v2/companies
```

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição

```json
{
  "Company": {
    "Name": "ACME Tecnologia LTDA",
    "TradeName": "ACME Tech",
    "FederalTaxNumber": "12345678000199",
    "TaxRegime": "SimplesNacional",
    "Address": {
      "State": "SP",
      "City": {
        "Code": "3550308",
        "Name": "São Paulo"
      },
      "District": "Centro",
      "Street": "Rua Exemplo",
      "Number": "100",
      "AdditionalInformation": "Sala 501",
      "PostalCode": "01001000",
      "Country": "BRA"
    }
  }
}
```

### Parâmetros do Corpo

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `Name` | string | ✅ | Razão social |
| `AccountId` | string | ✅ | ID da conta proprietária |
| `TradeName` | string | | Nome fantasia |
| `FederalTaxNumber` | long | ✅ | CNPJ como número (somente dígitos) |
| `TaxRegime` | enum | ✅ | Regime tributário |
| `Address` | object | ✅ | Endereço completo |

#### Objeto Address

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `State` | string | ✅ | UF (2 letras, ex: SP, RJ) |
| `City.Code` | string | ✅ | Código IBGE da cidade (7 dígitos) |
| `City.Name` | string | ✅ | Nome da cidade |
| `District` | string | ✅ | Bairro (mínimo 2 caracteres) |
| `StreetPrefix` | string | | Prefixo do logradouro (Rua, Av., etc.) |
| `Street` | string | ✅ | Logradouro (mínimo 5 caracteres, com prefixo válido) |
| `Number` | string | ✅ | Número |
| `AdditionalInformation` | string | | Complemento |
| `PostalCode` | string | ✅ | CEP (8 dígitos, somente números) |
| `Country` | string | ✅ | País (código ISO 3, ex: BRA) |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Company": {
    "Id": "company_abc123",
    "AccountId": "acct_12345",
    "Name": "ACME Tecnologia LTDA",
    "TradeName": "ACME Tech",
    "FederalTaxNumber": 12345678000199,
    "MunicipalTaxNumber": null,
    "TaxRegime": "SimplesNacional",
    "Status": "Active",
    "StateTaxes": [],
    "MunicipalTaxes": [],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": null,
    "Address": {
      "State": "SP",
      "City": {
        "Code": "3550308",
        "Name": "São Paulo"
      },
      "District": "Centro",
      "StreetPrefix": "Rua",
      "Street": "Rua Exemplo",
      "Number": "100",
      "AdditionalInformation": "Sala 501",
      "PostalCode": "01001000",
      "Country": "BRA"
    }
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |

```json
{
  "Errors": [
    {
      "Code": 40045,
      "Message": "city code is null or empty"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X POST https://api.nfse.io/v2/companies \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "Company": {
      "Name": "ACME Tecnologia LTDA",
      "FederalTaxNumber": "12345678000199",
      "TaxRegime": "SimplesNacional",
      "Address": {
        "State": "SP",
        "City": { "Code": "3550308", "Name": "São Paulo" },
        "District": "Centro",
        "Street": "Rua Exemplo",
        "Number": "100",
        "PostalCode": "01001000",
        "Country": "BRA"
      }
    }
  }'
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }
$body = @{
  Company = @{
    Name = "ACME Tecnologia LTDA"
    FederalTaxNumber = "12345678000199"
    TaxRegime = "SimplesNacional"
    Address = @{
      State = "SP"
      City = @{ Code = "3550308"; Name = "São Paulo" }
      District = "Centro"
      Street = "Rua Exemplo"
      Number = "100"
      PostalCode = "01001000"
      Country = "BRA"
    }
  }
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies" `
  -Method Post -Headers $headers -Body $body -ContentType "application/json"
```

---

## Listar Empresas

Lista todas as empresas da conta com paginação.

```http
GET /v2/companies
```

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Parâmetros de Query

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|--------|-----------|
| `limit` | int | 10 | Limite de resultados (1-50) |
| `startingAfter` | string | | ID do cursor para próxima página |
| `endingBefore` | string | | ID do cursor para página anterior |

### Ordenação

- Primária: `Name` (ascendente)
- Secundária: `Id` (ascendente)

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "hasMore": true,
  "companies": [
    {
      "Id": "company_abc123",
      "AccountId": "acct_12345",
      "Name": "ACME Tecnologia",
      "TradeName": "ACME",
      "FederalTaxNumber": 12345678000199,
      "MunicipalTaxNumber": null,
      "TaxRegime": "SimplesNacional",
      "Status": "Active",
      "StateTaxes": ["statetax_xyz789"],
      "MunicipalTaxes": [],
      "CreatedOn": "2024-01-15T10:30:00Z",
      "ModifiedOn": "2024-02-20T14:45:00Z",
      "Address": {
        "State": "SP",
        "City": { "Code": "3550308", "Name": "São Paulo" },
        "District": "Centro",
        "StreetPrefix": "Rua",
        "Street": "Rua Exemplo",
        "Number": "100",
        "PostalCode": "01001000",
        "Country": "BRA"
      }
    },
    {
      "Id": "company_def456",
      "AccountId": "acct_12345",
      "Name": "Beta Serviços",
      "TradeName": "Beta",
      "FederalTaxNumber": 98765432000188,
      "MunicipalTaxNumber": null,
      "TaxRegime": "LucroPresumido",
      "Status": "Active",
      "StateTaxes": [],
      "MunicipalTaxes": ["municipaltax_abc123"],
      "CreatedOn": "2024-01-20T08:00:00Z",
      "ModifiedOn": null,
      "Address": {
        "State": "RJ",
        "City": { "Code": "3304557", "Name": "Rio de Janeiro" },
        "District": "Centro",
        "StreetPrefix": "Avenida",
        "Street": "Av. Rio Branco",
        "Number": "200",
        "PostalCode": "20040020",
        "Country": "BRA"
      }
    }
  ]
}
```

### Paginação

Use o `Id` do último item como `startingAfter` para obter a próxima página:

```http
GET /v2/companies?limit=20&startingAfter=company_def456
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Cursor não encontrado |

### Exemplo cURL

```bash
curl -X GET "https://api.nfse.io/v2/companies?limit=20" \
  -H "Authorization: sk_live_xxx"
```

---

## Consultar Empresa por ID

Retorna os detalhes de uma empresa específica.

```http
GET /v2/companies/{company_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Company": {
    "Id": "company_abc123",
    "AccountId": "acct_12345",
    "Name": "ACME Tecnologia LTDA",
    "TradeName": "ACME Tech",
    "FederalTaxNumber": 12345678000199,
    "MunicipalTaxNumber": null,
    "TaxRegime": "SimplesNacional",
    "Status": "Active",
    "StateTaxes": ["statetax_xyz789"],
    "MunicipalTaxes": [],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-02-20T14:45:00Z",
    "Address": {
      "State": "SP",
      "City": { "Code": "3550308", "Name": "São Paulo" },
      "District": "Centro",
      "StreetPrefix": "Rua",
      "Street": "Rua Exemplo",
      "Number": "100",
      "PostalCode": "01001000",
      "Country": "BRA"
    }
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Empresa não encontrada |

```json
{
  "Errors": [
    {
      "Code": 40041,
      "Message": "company not found"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123 \
  -H "Authorization: sk_live_xxx"
```

---

## Verificar Existência (HEAD)

Verifica se uma empresa existe sem retornar o corpo.

```http
HEAD /v2/companies/{company_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Respostas

| Status | Descrição |
|--------|-----------|
| `204 No Content` | Empresa existe |
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Empresa não encontrada |

### Exemplo cURL

```bash
curl -I https://api.nfse.io/v2/companies/company_abc123 \
  -H "Authorization: sk_live_xxx"
```

---

## Alterar Empresa

Atualiza os dados de uma empresa existente.

```http
PUT /v2/companies/{company_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição

```json
{
  "Company": {
    "Name": "ACME Tecnologia LTDA - Atualizado",
    "TradeName": "ACME Tech",
    "TaxRegime": "LucroPresumido",
    "Address": {
      "State": "SP",
      "City": { "Code": "3550308", "Name": "São Paulo" },
      "District": "Jardins",
      "Street": "Av. Paulista",
      "Number": "1000",
      "AdditionalInformation": "Andar 10",
      "PostalCode": "01310100",
      "Country": "BRA"
    }
  }
}
```

### Campos Atualizáveis
    
| Campo | Tipo | Descrição |
|-------|------|-----------|
| `Name` | string | Razão social (2-60 caracteres) |
| `TradeName` | string | Nome fantasia |
| `TaxRegime` | enum | Regime tributário |
| `MunicipalTaxNumber` | string | Inscrição Municipal (legado) |
| `STStateTaxNumber` | string | IE Substituto Tributário |
| `SuframaTaxNumber` | long | Inscrição SUFRAMA |
| `Address` | object | Endereço completo |
| `Address.State` | string | UF (2 letras) |
| `Address.City` | object | Cidade (Code e Name) |
| `Address.District` | string | Bairro |
| `Address.Street` | string | Logradouro |
| `Address.Number` | string | Número |
| `Address.AdditionalInformation` | string | Complemento |
| `Address.PostalCode` | string | CEP (8 dígitos) |
| `Address.Country` | string | País (código ISO 3) |

:::note
O campo `FederalTaxNumber` (CNPJ) **não pode** ser alterado após a criação da empresa.
:::

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Company": {
    "Id": "company_abc123",
    "AccountId": "acct_12345",
    "Name": "ACME Tecnologia LTDA - Atualizado",
    "TradeName": "ACME Tech",
    "FederalTaxNumber": 12345678000199,
    "MunicipalTaxNumber": null,
    "TaxRegime": "LucroPresumido",
    "Status": "Active",
    "StateTaxes": ["statetax_xyz789"],
    "MunicipalTaxes": [],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-03-10T16:20:00Z",
    "Address": {
      "State": "SP",
      "City": { "Code": "3550308", "Name": "São Paulo" },
      "District": "Jardins",
      "StreetPrefix": "Avenida",
      "Street": "Av. Paulista",
      "Number": "1000",
      "AdditionalInformation": "Andar 10",
      "PostalCode": "01310100",
      "Country": "BRA"
    }
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Empresa não encontrada |

### Exemplo cURL

```bash
curl -X PUT https://api.nfse.io/v2/companies/company_abc123 \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "Company": {
      "Name": "ACME Tecnologia LTDA - Atualizado",
      "TaxRegime": "LucroPresumido",
      "Address": {
        "State": "SP",
        "City": { "Code": "3550308", "Name": "São Paulo" },
        "District": "Jardins",
        "Street": "Av. Paulista",
        "Number": "1000",
        "PostalCode": "01310100",
        "Country": "BRA"
      }
    }
  }'
```

---

## Excluir Empresa

Exclui uma empresa da plataforma.

:::warning[Atenção]
Este processo é **irreversível**. Todas as inscrições vinculadas também serão afetadas.
:::

```http
DELETE /v2/companies/{company_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `204 No Content`

(Sem corpo na resposta)

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Empresa não encontrada |

### Exemplo cURL

```bash
curl -X DELETE https://api.nfse.io/v2/companies/company_abc123 \
  -H "Authorization: sk_live_xxx"
```

---

## Regras de Validação

O sistema aplica as seguintes regras de validação ao criar ou alterar uma empresa:

### Dados da Empresa

| Campo | Regra | Código Erro |
|-------|-------|--------------|
| `Name` | Obrigatório, 2-60 caracteres | 40017, 40020 |
| `FederalTaxNumber` | CNPJ válido (dígito verificador) | 40031, 40032 |
| `Status` | Empresa deve estar ativa para alterações | 40019 |

### Endereço

| Campo | Regra | Código Erro |
|-------|-------|--------------|
| `Street` | Mínimo 5 caracteres, prefixo válido obrigatório | 40022 |
| `Number` | Obrigatório | 40023 |
| `District` | Mínimo 2 caracteres | 40024 |
| `Country` | Mínimo 3 caracteres (código ISO) | 40025 |
| `State` | Exatamente 2 caracteres, UF válida para Brasil | 40027 |
| `City.Code` | 7 dígitos, primeiros 2 devem corresponder ao código da UF | 40028 |
| `City.Name` | Obrigatório | 40029 |
| `PostalCode` | 8 dígitos, CEP válido | 40030 |

---

## Certificado Digital

A empresa pode ter um certificado digital ICP-Brasil (e-CNPJ A1 ou NF-e A1) vinculado para emissão de documentos fiscais eletrônicos.

### Metadados do Certificado

Quando um certificado está vinculado, os seguintes metadados são retornados:

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `Certificate.TaxPayerId` | string | ID da empresa vinculada |
| `Certificate.Thumbprint` | string | Impressão digital única do certificado |
| `Certificate.TaxId` | string | CNPJ do certificado |
| `Certificate.Subject` | string | Nome do certificado (Distinguished Name) |
| `Certificate.ValidUntil` | datetime | Data de expiração |
| `Certificate.Status` | enum | Status do certificado |
| `Certificate.ModifiedOn` | datetime | Data da última modificação |

### Status do Certificado (CertificateStatus)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -3 | Certificado inativo/excluído |
| `Overdue` | -2 | Certificado vencido |
| `Pending` | -1 | Certificado pendente de validação |
| `None` | 0 | Status não definido |
| `Active` | 1 | Certificado ativo e válido |

### Endpoints de Certificado

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/v2/companies/{company_id}/certificates` | Upload de certificado |
| `GET` | `/v2/companies/{company_id}/certificates` | Listar certificados |
| `GET` | `/v2/companies/{company_id}/certificates/{thumbprint}` | Consultar por thumbprint |
| `DELETE` | `/v2/companies/{company_id}/certificates/{thumbprint}` | Excluir certificado |

### Requisitos do Certificado

| Requisito | Descrição |
|-----------|-----------|
| **Tipo** | e-CNPJ A1 ou NF-e A1 (certificados A3 não são suportados) |
| **Formato** | Arquivo `.pfx` ou `.p12` |
| **CNPJ** | Deve corresponder ao `FederalTaxNumber` da empresa |
| **Validade** | Não pode estar expirado |
| **Senha** | Obrigatória para upload |

### Exemplo de Upload

```bash
curl -X POST https://api.nfse.io/v2/companies/company_abc123/certificates \
  -H "Authorization: sk_live_xxx" \
  -F "File=@certificado.pfx" \
  -F "Password=senha123"
```

### Resposta de Upload

```json
{
  "Certificate": {
    "TaxPayerId": "company_abc123",
    "Thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
    "TaxId": "12345678000199",
    "Subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=RFB, O=ICP-Brasil, C=BR",
    "ValidUntil": "2025-06-15T23:59:59Z",
    "ModifiedOn": "2024-01-15T10:30:00Z",
    "Status": "Active"
  }
}
```

:::info[Documentação Completa]
Para informações detalhadas sobre gerenciamento de certificados, consulte a [API de Certificados](./gerenciamento-certificado.md).
:::

---

## Códigos de Erro

### Validação de Dados da Empresa

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40016 | id is null or empty | ID não informado |
| 40017 | name is null or empty | Razão social não informada |
| 40018 | account id is null or empty | AccountId não informado na criação |
| 40019 | company is not active | Empresa inativa não permite alterações |
| 40020 | name must be between 2 to 60 characters | Nome fora do limite permitido |

### Validação de Endereço

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40022 | street is null or empty | Logradouro inválido ou sem prefixo válido |
| 40023 | number is null or empty | Número não informado |
| 40024 | district is null or empty | Bairro inválido (mínimo 2 caracteres) |
| 40025 | country is not valid | País inválido (mínimo 3 caracteres) |
| 40026 | city is null or empty | Cidade não informada |
| 40027 | state is not valid | UF inválida (deve ser 2 caracteres e válida para Brasil) |
| 40028 | city code is not valid | Código IBGE inválido (7 dígitos, primeiros 2 devem corresponder à UF) |
| 40029 | city name is null or empty | Nome da cidade não informado |
| 40030 | postal code is not valid | CEP inválido (deve ter 8 dígitos e ser válido) |

### Validação de CNPJ

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40031 | federal tax number is null | CNPJ não informado |
| 40032 | federal tax number is not valid | CNPJ com dígito verificador inválido |

### Operações de Empresa

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40035 | account id is null or empty | AccountId não informado na operação |
| 40036 | company is null | Payload da empresa nulo |
| 40037 | company id is null or empty | CompanyId não informado |
| 40038 | company id not found | Empresa não encontrada |
| 40039 | account id is not valid to this company | AccountId não corresponde à empresa |

---

## Enums

### TaxRegime (Regime Tributário)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `None` | 0 | Não definido |
| `LucroReal` | 2 | Lucro Real |
| `LucroPresumido` | 4 | Lucro Presumido |
| `SimplesNacional` | 8 | Simples Nacional |
| `SimplesNacionalExcessoSublimite` | 12 | Simples Nacional - Excesso Sublimite |
| `MicroempreendedorIndividual` | 16 | MEI |
| `Isento` | 32 | Isento |

### Status

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -1 | Inativa (empresa excluída/desativada) |
| `None` | 0 | Não definido |
| `Active` | 1 | Ativa (permite operações) |

### PersonType (Tipo de Pessoa)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `None` | 0 | Não definido |
| `LegalEntity` | 1 | Pessoa Jurídica (CNPJ) |
| `Individual` | 2 | Pessoa Física (CPF) |

---

## Boas Práticas

### Validação de CNPJ

- Envie **somente dígitos** (sem pontos, barras ou traços)
- Valide o dígito verificador antes de enviar
- O tipo deve ser `long` (numérico)
- Exemplo válido: `12345678000199`
- Exemplo inválido: `12.345.678/0001-99`

### Código IBGE

- Use códigos IBGE válidos de 7 dígitos
- Os primeiros 2 dígitos devem corresponder ao código da UF
- Consulte a tabela oficial do IBGE
- Exemplos:
  - São Paulo/SP: `3550308` (35 = SP)
  - Rio de Janeiro/RJ: `3304557` (33 = RJ)
  - Belo Horizonte/MG: `3106200` (31 = MG)

### Endereço

- Preencha todos os campos obrigatórios
- Use CEP válido e formatado (somente dígitos, 8 caracteres)
- O sistema normaliza/valida automaticamente (ver abaixo)

### Normalização Automática

O sistema realiza as seguintes normalizações automaticamente:

| Comportamento | Descrição |
|---------------|------------|
| **País padrão** | Se não informado, assume `BRA` (Brasil) |
| **Números no início** | Remove números do início do logradouro |
| **Prefixo "R "** | Converte "R " para "Rua " |
| **Sem prefixo** | Adiciona "Rua" se não houver prefixo válido |

### Prefixos de Logradouro Válidos

O sistema valida se o logradouro possui um prefixo reconhecido. Exemplos aceitos:

| Prefixo | Variações |
|---------|----------|
| Rua | R., Rua |
| Avenida | Av., Av, Avenida |
| Alameda | Al., Alameda |
| Travessa | Tv., Travessa |
| Praça | Pç., Praça |
| Rodovia | Rod., Rodovia |
| Estrada | Est., Estrada |

:::note
Caso o logradouro não tenha prefixo válido, o sistema adicionará "Rua" automaticamente.
:::

---

## Próximos Passos

Após criar a empresa:

1. **Configure o certificado digital** correspondente ao CNPJ → [Ver documentação](./gerenciamento-certificado.md)
2. **Crie uma Inscrição Estadual** para emitir NF-e/NFC-e → [Ver documentação](./gerenciamento-inscricao-estadual.md)
3. **Crie uma Inscrição Municipal** para emitir NFS-e → [Ver documentação](./gerenciamento-inscricao-municipal.md)

---

## Veja também:

- [API de Certificados](./gerenciamento-certificado.md) - Gerenciamento de certificados digitais
- [Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) - Configuração para NF-e/NFC-e
- [Inscrições Municipais](./gerenciamento-inscricao-municipal.md) - Configuração para NFS-e

---

## API de Contribuintes / API Gerenciamento de Empresas - Visão Geral | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/gerenciamento-empresas/visao-geral/index.md

# Contribuintes / Gerenciamento de Empresas (TaxPayers)

## Visão geral da API de Contribuintes / API Gerenciamento de Empresas da plataforma NFE.io

> **Documentação Detalhada**
> - [API de Empresas](./gerenciamento-empresas.md) - CRUD completo de empresas
> - [API de Certificados](./gerenciamento-certificado.md) - Gerenciamento de certificados digitais
> - [API de Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) - Gestão de IE para NF-e/NFC-e
> - [API de Inscrições Municipais](./gerenciamento-inscricao-municipal.md) - Gestão de IM para NFS-e

:::info[Migração da API legada]
Esta API substitui o antigo grupo `/v1/companies` da [Nota Fiscal de Serviço v1](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1), que está em descontinuação. Consulte o [guia de migração na release-note 2026.1](/docs/release-notes/2026-1-unificacao-api-contribuintes).
:::

---

## O que é o Gerenciamento de Empresas?

O **Gerenciamento de Empresas** (API de Contribuintes / API Gerenciamento de Empresas / TaxPayers) é o módulo da plataforma NFE.io responsável por centralizar todo o cadastro e a configuração das empresas que emitem documentos fiscais eletrônicos.

Antes de emitir qualquer nota fiscal — seja NF-e, NFC-e ou NFS-e — é necessário que a empresa esteja devidamente cadastrada na plataforma, com seu certificado digital vinculado e suas inscrições fiscais configuradas. Este módulo cuida exatamente disso: ele é o **pré-requisito** para toda a operação de emissão fiscal.

### Por que isso é importante?

No Brasil, a emissão de documentos fiscais eletrônicos exige o cumprimento de requisitos junto a diferentes órgãos:

- **SEFAZ (Secretaria da Fazenda estadual)** — para NF-e e NFC-e, exigindo Inscrição Estadual (IE) e certificado digital
- **Prefeituras municipais** — para NFS-e, exigindo Inscrição Municipal (IM), e frequentemente credenciais de acesso ao webservice da prefeitura

Cada órgão tem suas regras, formatos e requisitos. A NFE.io abstrai essa complexidade, oferecendo uma **interface unificada** para cadastrar e gerenciar todos esses dados em um único lugar.

:::warning[Conceito fundamental]
Esta API **não cadastra sua empresa** diretamente na SEFAZ, nas prefeituras ou na Receita Federal. Ela apenas **registra na NFE.io os dados** que você já possui — como CNPJ, inscrições estaduais, inscrições municipais e certificados digitais.

Em outras palavras: você precisa primeiro obter esses dados junto aos órgãos governamentais. Depois, você usa esta API para informar esses dados à NFE.io, que os armazena e utiliza como base para emitir suas notas fiscais (NF-e, NFC-e e NFS-e).
:::

### O que este módulo possibilita?

Com a API de Contribuintes / API Gerenciamento de Empresas, você pode:

- **Cadastrar e gerenciar empresas emissoras** — registrar internamente empresas (pessoas jurídicas identificadas por CNPJ) que emitirão documentos fiscais
- **Vincular certificados digitais** — fazer upload de certificados ICP-Brasil (e-CNPJ A1 ou NF-e A1) necessários para assinar digitalmente os documentos fiscais
- **Espelhar inscrições estaduais** — registrar os dados de IE já obtidos junto à SEFAZ, definir séries de numeração e gerenciar contingência (EPEC) para emissão de NF-e e NFC-e
- **Espelhar inscrições municipais** — registrar os dados de IM já obtidos junto à prefeitura, credenciais, séries RPS e verificar se a NFE.io possui integração homologada com a prefeitura da cidade
- **Gerenciar múltiplas empresas** — uma única conta na NFE.io pode gerenciar dezenas ou centenas de empresas, cada uma com suas próprias inscrições e certificados
- **Controlar séries e numeração** — definir e acompanhar as séries de numeração para NF-e, NFC-e e RPS (NFS-e), evitando conflitos e garantindo sequência correta

:::info[Em resumo]
Este módulo é o **ponto de partida** de toda integração com a NFE.io. Sem uma empresa cadastrada, com certificado e inscrição fiscal configurados, não é possível emitir nenhum documento fiscal pela plataforma.
:::

---

## Conceitos Essenciais

### Empresa (Company)

A **Empresa** é a entidade central do sistema, representando a pessoa jurídica emissora de documentos fiscais. Ela atua como um "Hub de Identidade", concentrando:

- **Identificação fiscal**: CNPJ, Razão Social, Nome Fantasia
- **Localização**: Endereço fiscal com código IBGE
- **Regime tributário**: Simples Nacional, Lucro Presumido, etc.
- **Certificado digital**: Para assinatura de documentos
- **Inscrições fiscais**: Estaduais e Municipais vinculadas

→ [Documentação completa da API de Empresas](./gerenciamento-empresas.md)

### Certificado Digital (Certificate)

O **Certificado Digital ICP-Brasil** é obrigatório para emissão de documentos fiscais eletrônicos:

- **Tipos aceitos**: e-CNPJ A1 ou NF-e A1 (certificados A3 não são suportados)
- **Formatos**: Arquivo `.pfx` ou `.p12`
- **Requisitos**: CNPJ deve corresponder ao da empresa, não pode estar expirado
- **Função**: Assinatura digital de NF-e, NFC-e e NFS-e

| Status | Descrição |
|--------|-----------|
| `Active` | Certificado válido e pronto para uso |
| `Overdue` | Certificado vencido - emissões bloqueadas |
| `Inactive` | Certificado excluído |
| `Pending` | Aguardando processamento |

→ [Documentação completa da API de Certificados](./gerenciamento-certificado.md)

### Inscrição Estadual (StateTax)

Representa o cadastro da empresa junto à **SEFAZ estadual**, necessário para:

- Emissão de **NF-e** (Nota Fiscal Eletrônica)
- Emissão de **NFC-e** (Nota Fiscal de Consumidor Eletrônica)
- Controle de **séries e numeração**
- Gestão de **contingência** (EPEC)

:::warning[Importante]
Esta API **não cadastra** sua empresa na SEFAZ estadual. Ela apenas registra na NFE.io os dados de Inscrição Estadual que você já obteve junto à SEFAZ, para utilizá-los como base nas emissões de NF-e e NFC-e.
:::

→ [Documentação completa da API de Inscrições Estaduais](./gerenciamento-inscricao-estadual.md)

### Inscrição Municipal (MunicipalTax)

Representa o cadastro da empresa junto à **Prefeitura municipal**, necessário para:

- Emissão de **NFS-e** (Nota Fiscal de Serviços Eletrônica)
- Controle de **séries RPS e numeração**
- Gerenciamento de **credenciais da prefeitura**

:::warning[Importante]
Esta API **não cadastra** sua empresa na prefeitura municipal. Ela apenas registra na NFE.io os dados de Inscrição Municipal que você já obteve junto à prefeitura, para utilizá-los como base nas emissões de NFS-e.
:::

→ [Documentação completa da API de Inscrições Municipais](./gerenciamento-inscricao-municipal.md)

---

## Introdução

A API de Contribuintes / API Gerenciamento de Empresas da NFE.io permite gerenciar empresas emissoras de documentos fiscais eletrônicos. A plataforma consolida o gerenciamento em uma única estrutura, diferenciando o tipo de emissão através das inscrições fiscais associadas:

| Tipo de Documento | Cadastro Necessário | Órgão |
|-------------------|---------------------|-------|
| **NF-e / NFC-e** | Inscrição Estadual | SEFAZ |
| **NFS-e** | Inscrição Municipal | Prefeitura |

---

## Arquitetura

```
Account (Conta)
    └── Company (Empresa)
            ├── Certificate (Certificado Digital A1)
            │
            ├── StateTax (Inscrição Estadual) → NF-e / NFC-e
            │       └── Series (Séries de numeração)
            │
            └── MunicipalTax (Inscrição Municipal) → NFS-e
                    └── RPS Series (Séries de RPS)
```

### Hierarquia de Recursos

| Recurso | Descrição | Documentação |
|---------|-----------|--------------|
| **Company** | Pessoa jurídica (CNPJ) emissora de documentos fiscais | [API de Empresas](./gerenciamento-empresas.md) |
| **Certificate** | Certificado digital A1 ICP-Brasil para assinatura | [API de Certificados](./gerenciamento-certificado.md) |
| **StateTax** | Cadastro estadual (ICMS) para NF-e/NFC-e | [API de Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) |
| **MunicipalTax** | Cadastro municipal (ISS) para NFS-e | [API de Inscrições Municipais](./gerenciamento-inscricao-municipal.md) |

---

## Fluxos de Configuração

### Habilitar empresa para NF-e/NFC-e

```
1. Criar Empresa
   POST /v2/companies
       ↓
2. Configurar Certificado A1
   POST /v2/companies/{id}/certificates
       ↓
3. Criar Inscrição Estadual
   POST /v2/companies/{id}/statetaxes
       ↓
✅ Pronta para emitir NF-e/NFC-e
```

→ Documentação completa: [API de Empresas](./gerenciamento-empresas.md) | [API de Inscrições Estaduais](./gerenciamento-inscricao-estadual.md)  
→ Para criar empresas pela plataforma: [Criar Empresa](/docs/documentacao/nossa-plataforma/criar-empresa)

### Habilitar empresa para NFS-e

```
1. Criar Empresa
   POST /v2/companies
       ↓
2. Configurar Certificado A1
   POST /v2/companies/{id}/certificates
       ↓
3. Criar Inscrição Municipal
   POST /v2/companies/{id}/municipaltaxes
       ↓
4. Verificar FiscalStatus da prefeitura
       ↓
✅ Pronta para emitir NFS-e
```

→ Documentação completa: [API de Empresas](./gerenciamento-empresas.md) | [API de Inscrições Municipais](./gerenciamento-inscricao-municipal.md)  
→ Para criar empresas pela plataforma: [Criar Empresa](/docs/documentacao/nossa-plataforma/criar-empresa)

---

## URLs Base

| Ambiente | URL |
|----------|-----|
| Produção | `https://api.nfse.io` |

### Endpoints Principais

| Recurso | Endpoint Base | Documentação |
|---------|---------------|--------------|
| Empresas | `/v2/companies` | [Ver detalhes](./gerenciamento-empresas.md) |
| Certificados | `/v2/companies/{company_id}/certificates` | [Ver detalhes](./gerenciamento-certificado.md) |
| Inscrições Estaduais | `/v2/companies/{company_id}/statetaxes` | [Ver detalhes](./gerenciamento-inscricao-estadual.md) |
| Inscrições Municipais | `/v2/companies/{company_id}/municipaltaxes` | [Ver detalhes](./gerenciamento-inscricao-municipal.md) |

---

## Autenticação

Todos os endpoints exigem autenticação via API Key.

→ **[Saiba como obter sua API Key](/docs/documentacao/nossa-plataforma/chaves-de-autenticacao)**

```http
Authorization: <sua_api_key>
```

### Exemplo cURL

```bash
curl -H "Authorization: sk_live_xxx" \
     https://api.nfse.io/v2/companies
```

### Respostas de Autenticação

| Código | Descrição |
|--------|-----------|
| `401 Unauthorized` | API Key inválida ou expirada |
| `403 Forbidden` | API Key sem permissão para o recurso |

---

## Enums Principais

### Status

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -1 | Inativo (excluído/desativado) |
| `None` | 0 | Não definido |
| `Active` | 1 | Ativo (permite operações) |

### TaxRegime (Regime Tributário)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `None` | 0 | Não definido |
| `LucroReal` | 2 | Lucro Real |
| `LucroPresumido` | 4 | Lucro Presumido |
| `SimplesNacional` | 8 | Simples Nacional |
| `SimplesNacionalExcessoSublimite` | 12 | Simples Nacional - Excesso Sublimite |
| `MicroempreendedorIndividual` | 16 | MEI |
| `Isento` | 32 | Isento |

### Environment (Ambiente)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Development` / `Test` | 0 | Homologação/Sandbox |
| `Production` | 1 | Produção (emissão real) |

---

## Contrato de Erros

Todas as respostas de erro seguem o formato:

```json
{
  "Errors": [
    {
      "Code": 40041,
      "Message": "company not found"
    }
  ]
}
```

### Códigos de Erro Comuns

| Código | Mensagem | Recurso |
|--------|----------|---------|
| 40017 | name is null or empty | Company |
| 40031 | federal tax number is null | Company |
| 40032 | federal tax number is not valid | Company |
| 40041 | company not found | Company |
| 40042 | company is not available to issue | Company |
| 40044 | city is null | MunicipalTax |
| 40045 | city code is null or empty | MunicipalTax |

→ Códigos completos: [Empresas](./gerenciamento-empresas.md#códigos-de-erro) | [IE](./gerenciamento-inscricao-estadual.md#códigos-de-erro) | [IM](./gerenciamento-inscricao-municipal.md#códigos-de-erro)

---

## Boas Práticas

### Dados Cadastrais

- Envie `FederalTaxNumber` (CNPJ) **somente com dígitos** (sem pontuação)
- Use códigos IBGE válidos de 7 dígitos para `City.Code`
- Mantenha endereços reais; a API valida e pode rejeitar dados inconsistentes

### Numeração

- Comece com séries simples (ex.: `1`, `IO`, `A1`)
- Inicialize numeração de forma clara (ex.: começar em `1`)
- Mantenha controle local do último número usado
- Não reutilize números dentro da mesma série

### Tratamento de Erros

- Sempre leia o array `Errors` nas respostas de erro
- Implemente retry com backoff exponencial para erros 5xx
- Valide dados localmente antes de enviar à API

### Paginação

- Use `startingAfter` com o ID do último item para avançar
- Respeite o limite máximo de 50 itens por página
- Ordenação varia por recurso:
  - Empresas: `Name` (ascendente)
  - Inscrições: `CreatedOn` (descendente)

---

## Documentação Detalhada

| Recurso | Descrição | Link |
|---------|-----------|------|
| **Empresas** | CRUD completo, endereço, regime tributário | [api-empresas](./gerenciamento-empresas.md) |
| **Certificados** | Upload, consulta e exclusão de certificados A1 | [api-certificados](./gerenciamento-certificado.md) |
| **Inscrições Estaduais** | IE, séries, numeração, contingência EPEC | [api-inscricoes-estaduais](./gerenciamento-inscricao-estadual.md) |
| **Inscrições Municipais** | IM, RPS, credenciais, FiscalStatus | [api-inscricoes-municipais](./gerenciamento-inscricao-municipal.md) |

---

## API de Inscrições Estaduais - Gestão de IE | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/gerenciamento-empresas/api-inscricoes-estaduais/index.md

# API de Inscrições Estaduais (StateTax)

## Gerencie inscrições estaduais para emissão de NF-e e NFC-e

> **Navegação**
> - [← Voltar para Visão Geral](./gerenciamento-empresas-resumo.md)
> - [Empresas →](./gerenciamento-empresas.md)
> - [Certificados →](./gerenciamento-certificado.md)
> - [Inscrições Municipais →](./gerenciamento-inscricao-municipal.md)

---

## Visão Geral

O recurso **StateTax** (Inscrição Estadual) representa o cadastro da empresa junto à SEFAZ estadual, necessário para emissão de:

- **NF-e** - Nota Fiscal Eletrônica
- **NFC-e** - Nota Fiscal de Consumidor Eletrônica

:::warning[Importante]
Esta API **não cadastra** sua empresa na SEFAZ estadual. Ela apenas **registra na NFE.io os dados** de Inscrição Estadual que você já obteve junto à SEFAZ, para utilizá-los como base nas emissões de NF-e e NFC-e.

O cadastro junto à SEFAZ, obtenção da Inscrição Estadual e habilitação para emissão de documentos fiscais devem ser feitos **diretamente por você** junto ao órgão estadual competente.
:::

---

## Anatomia de uma Inscrição Estadual

### Conceitos Fundamentais

Ao criar uma inscrição estadual, você define os dados necessários para emissão de documentos fiscais na SEFAZ:

| Conceito | Campos na API | Descrição |
|----------|---------------|-----------|
| **Localização** | `Code` | Código do Estado (UF) |
| **Identificação Estadual** | `TaxNumber` | Número da Inscrição Estadual |
| **Tipo de Emissão** | `Type` | NF-e ou NFC-e |
| **Numeração** | `Serie`, `Number` | Série e número atual da numeração |
| **Ambiente** | `EnvironmentType` | Produção ou Homologação |
| **Processamento** | `ProcessingDetails` | Detalhes de autorização e contingência |

### Campos Gerenciados pelo Sistema

Além dos dados que você informa, o sistema gera e mantém automaticamente:

| Campo | Tipo | Quando é definido |
|-------|------|-------------------|
| `Id` | string | Gerado na criação |
| `CompanyId` | string | Vinculado à empresa da URL |
| `AccountId` | string | Vinculado à sua conta/tenant |
| `Status` | enum | Inicia como `Active` |
| `Series` | array | Lista de séries utilizadas, atualizada automaticamente |
| `ProcessingDetails.AuthorityStatus` | enum | Status da SEFAZ em tempo real |
| `ProcessingDetails.StatusOn` | datetime | Data/hora da última atualização do status |
| `CreatedOn` | datetime | Data/hora da criação |
| `ModifiedOn` | datetime | Atualizado a cada alteração |

### Referência Completa de Propriedades

### 📋 Expandir tabela completa

| Propriedade | Tipo | Obrigatório | Descrição |
|-------------|------|:-----------:|-----------|
| `Id` | string | — | Identificador único (gerado) |
| `CompanyId` | string | — | ID da empresa proprietária |
| `AccountId` | string | — | Conta/tenant proprietária |
| `Status` | enum | — | Status operacional |
| `Code` | enum | ✅ | Código do Estado (UF) |
| `TaxNumber` | string | ✅ | Número da Inscrição Estadual |
| `EnvironmentType` | enum | | Ambiente de processamento (`Production` ou `Test`) |
| `SpecialTaxRegime` | enum | | Regime especial de tributação |
| `Type` | enum | ✅ | Tipo de emissão (`NFe` ou `NFCe`) |
| `Serie` | int | | Série atual |
| `Number` | long | | Próximo número da série |
| `Series` | array | — | Lista de séries utilizadas (gerado) |
| `SecurityCredential` | object | | Credenciais de segurança (obrigatório para NFC-e) |
| `SecurityCredential.Id` | int | | ID do CSC |
| `SecurityCredential.Code` | string | | Código CSC |
| `ProcessingDetails` | object | — | Detalhes de processamento |
| `ProcessingDetails.SwitchAuthorizerStrategy` | enum | | Estratégia de troca de autorizador |
| `ProcessingDetails.AuthorityStatus` | enum | — | Status da SEFAZ |
| `ProcessingDetails.StatusOn` | datetime | — | Data do status |
| `ProcessingDetails.LastSwitchAuthorizerDetails` | object | — | Última troca de autorizador |
| `CreatedOn` | datetime | — | Data de criação |
| `ModifiedOn` | datetime | — | Última modificação |

---

## Endpoints

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/v2/companies/{company_id}/statetaxes` | Criar inscrição |
| `GET` | `/v2/companies/{company_id}/statetaxes` | Listar inscrições |
| `GET` | `/v2/companies/{company_id}/statetaxes/{state_tax_id}` | Consultar inscrição |
| `PUT` | `/v2/companies/{company_id}/statetaxes/{state_tax_id}` | Alterar inscrição |
| `DELETE` | `/v2/companies/{company_id}/statetaxes/{state_tax_id}` | Excluir inscrição |
| `POST` | `/v2/companies/{company_id}/statetaxes/{state_tax_id}/switch-authorizer` | Trocar autorizador |

:::info[Autenticação]
Todos os endpoints exigem autenticação via API Key: `Authorization: <sua_api_key>`

→ **[Saiba como obter sua API Key](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/)**
:::

---

## Criar uma Inscrição Estadual

Cria uma nova inscrição estadual para a empresa.

```http
POST /v2/companies/{company_id}/statetaxes
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição

```json
{
  "StateTax": {
    "Code": "SP",
    "TaxNumber": "123456789",
    "EnvironmentType": "Production",
    "SpecialTaxRegime": "Nenhum",
    "Type": "NFe",
    "Serie": 1,
    "Number": 1,
    "ProcessingDetails": {
      "SwitchAuthorizerStrategy": "Manual"
    }
  }
}
```

### Parâmetros do Corpo

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `Code` | enum | ✅ | Código do Estado (UF) |
| `TaxNumber` | string | ✅ | Número da Inscrição Estadual |
| `Type` | enum | ✅ | Tipo de emissão (`NFe` ou `NFCe`) |
| `EnvironmentType` | enum | | `Production` ou `Test` (padrão: `Test`) |
| `SpecialTaxRegime` | enum | | Regime especial de tributação |
| `Serie` | int | | Série inicial (padrão: 1) |
| `Number` | long | | Número inicial da série |
| `SecurityCredential` | object | | Obrigatório para NFC-e |
| `ProcessingDetails` | object | | Configurações de processamento |

#### Objeto SecurityCredential (obrigatório para NFC-e)

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `Id` | int | ✅ | ID do CSC (Código de Segurança do Contribuinte) |
| `Code` | string | ✅ | Código CSC |

#### Objeto ProcessingDetails

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `SwitchAuthorizerStrategy` | enum | `Manual` ou `StateTaxAuthorityStatusUnavailable` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "StateTax": {
    "Id": "stx_001",
    "CompanyId": "company_abc123",
    "AccountId": "acct_12345",
    "Status": "Active",
    "Code": "SP",
    "TaxNumber": "123456789",
    "EnvironmentType": "Production",
    "SpecialTaxRegime": "Nenhum",
    "Type": "NFe",
    "Serie": 1,
    "Number": 1,
    "Series": [1],
    "SecurityCredential": null,
    "ProcessingDetails": {
      "SwitchAuthorizerStrategy": "Manual",
      "AuthorityStatus": "Unknown",
      "StatusOn": "2024-01-15T10:30:00Z",
      "LastSwitchAuthorizerDetails": null
    },
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": null
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Empresa não encontrada |

```json
{
  "Errors": [
    {
      "Code": 40041,
      "Message": "company not found"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X POST https://api.nfse.io/v2/companies/company_abc123/statetaxes \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "StateTax": {
      "Code": "SP",
      "TaxNumber": "123456789",
      "EnvironmentType": "Production",
      "Type": "NFe",
      "Serie": 1,
      "Number": 1
    }
  }'
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }
$body = @{
  StateTax = @{
    Code = "SP"
    TaxNumber = "123456789"
    EnvironmentType = "Production"
    Type = "NFe"
    Serie = 1
    Number = 1
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies/company_abc123/statetaxes" `
  -Method Post -Headers $headers -Body $body -ContentType "application/json"
```

---

## Listar Inscrições Estaduais

Lista todas as inscrições estaduais de uma empresa com paginação.

```http
GET /v2/companies/{company_id}/statetaxes
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Parâmetros de Query

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|--------|-----------|
| `limit` | int | 10 | Limite de resultados (1-50) |
| `startingAfter` | string | | ID do cursor para próxima página |
| `endingBefore` | string | | ID do cursor para página anterior |

### Ordenação

- Primária: `CreatedOn` (descendente - mais recentes primeiro)
- Secundária: `Id` (ascendente)

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "hasMore": false,
  "stateTaxes": [
    {
      "Id": "stx_001",
      "CompanyId": "company_abc123",
      "AccountId": "acct_12345",
      "Status": "Active",
      "Code": "SP",
      "TaxNumber": "123456789",
      "EnvironmentType": "Production",
      "SpecialTaxRegime": "Nenhum",
      "Type": "NFe",
      "Serie": 1,
      "Number": 1500,
      "Series": [1],
      "CreatedOn": "2024-01-15T10:30:00Z",
      "ModifiedOn": "2024-02-20T14:45:00Z"
    },
    {
      "Id": "stx_002",
      "CompanyId": "company_abc123",
      "AccountId": "acct_12345",
      "Status": "Active",
      "Code": "RJ",
      "TaxNumber": "987654321",
      "EnvironmentType": "Production",
      "SpecialTaxRegime": "Nenhum",
      "Type": "NFCe",
      "Serie": 1,
      "Number": 200,
      "Series": [1],
      "SecurityCredential": {
        "Id": 1,
        "Code": "ABC123..."
      },
      "CreatedOn": "2024-01-10T14:00:00Z",
      "ModifiedOn": null
    }
  ]
}
```

### Paginação

Use o `Id` do último item como `startingAfter` para obter a próxima página:

```http
GET /v2/companies/{company_id}/statetaxes?limit=20&startingAfter=stx_002
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Empresa ou cursor não encontrado |

### Exemplo cURL

```bash
curl -X GET "https://api.nfse.io/v2/companies/company_abc123/statetaxes?limit=20" \
  -H "Authorization: sk_live_xxx"
```

---

## Consultar Inscrição Estadual por ID

Retorna os detalhes de uma inscrição estadual específica.

```http
GET /v2/companies/{company_id}/statetaxes/{state_tax_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `state_tax_id` | string | ID da inscrição estadual |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "StateTax": {
    "Id": "stx_001",
    "CompanyId": "company_abc123",
    "AccountId": "acct_12345",
    "Status": "Active",
    "Code": "SP",
    "TaxNumber": "123456789",
    "EnvironmentType": "Production",
    "SpecialTaxRegime": "Nenhum",
    "Type": "NFe",
    "Serie": 1,
    "Number": 1500,
    "Series": [1, 2],
    "SecurityCredential": null,
    "ProcessingDetails": {
      "SwitchAuthorizerStrategy": "Manual",
      "AuthorityStatus": "Available",
      "StatusOn": "2024-02-20T14:45:00Z",
      "LastSwitchAuthorizerDetails": {
        "FromAuthorizer": "EPEC",
        "ToAuthorizer": "Normal",
        "Reason": "Retorno à operação normal",
        "ModifiedOn": "2024-02-20T14:45:00Z"
      }
    },
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-02-20T14:45:00Z"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Inscrição não encontrada |

```json
{
  "Errors": [
    {
      "Code": 40041,
      "Message": "state tax not found"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123/statetaxes/stx_001 \
  -H "Authorization: sk_live_xxx"
```

---

## Alterar Inscrição Estadual

Atualiza os dados de uma inscrição estadual existente.

```http
PUT /v2/companies/{company_id}/statetaxes/{state_tax_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `state_tax_id` | string | ID da inscrição estadual |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição

```json
{
  "StateTax": {
    "TaxNumber": "123456789",
    "EnvironmentType": "Production",
    "Serie": 2,
    "Number": 1
  }
}
```

### Campos Atualizáveis

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `Code` | enum | Código do Estado (UF) |
| `TaxNumber` | string | Número da Inscrição Estadual |
| `EnvironmentType` | enum | Ambiente de processamento |
| `SpecialTaxRegime` | enum | Regime especial de tributação |
| `Type` | enum | Tipo de emissão |
| `Serie` | int | Série atual |
| `Number` | long | Próximo número da série |
| `SecurityCredential` | object | Credenciais de segurança (NFC-e) |
| `ProcessingDetails.SwitchAuthorizerStrategy` | enum | Estratégia de troca de autorizador |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "StateTax": {
    "Id": "stx_001",
    "CompanyId": "company_abc123",
    "AccountId": "acct_12345",
    "Status": "Active",
    "Code": "SP",
    "TaxNumber": "123456789",
    "EnvironmentType": "Production",
    "SpecialTaxRegime": "Nenhum",
    "Type": "NFe",
    "Serie": 2,
    "Number": 1,
    "Series": [1, 2],
    "SecurityCredential": null,
    "ProcessingDetails": {
      "SwitchAuthorizerStrategy": "Manual",
      "AuthorityStatus": "Available",
      "StatusOn": "2024-02-20T14:45:00Z",
      "LastSwitchAuthorizerDetails": null
    },
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-03-10T16:20:00Z"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Inscrição não encontrada |

### Exemplo cURL

```bash
curl -X PUT https://api.nfse.io/v2/companies/company_abc123/statetaxes/stx_001 \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "StateTax": {
      "Serie": 2,
      "Number": 1
    }
  }'
```

---

## Excluir Inscrição Estadual

Exclui uma inscrição estadual da empresa.

:::warning[Atenção]
Este processo é **irreversível**. Histórico de numeração será perdido.
:::

```http
DELETE /v2/companies/{company_id}/statetaxes/{state_tax_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `state_tax_id` | string | ID da inscrição estadual |

### Headers

| Header | Valor |
|--------|-------|
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `204 No Content`

(Sem corpo na resposta)

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Inscrição não encontrada |

### Exemplo cURL

```bash
curl -X DELETE https://api.nfse.io/v2/companies/company_abc123/statetaxes/stx_001 \
  -H "Authorization: sk_live_xxx"
```

---

## Trocar Autorizador (Switch Authorizer)

Altera o autorizador da inscrição estadual, útil para operações de contingência.

```http
POST /v2/companies/{company_id}/statetaxes/{state_tax_id}/switch-authorizer
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `state_tax_id` | string | ID da inscrição estadual |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição

```json
{
  "Authorizer": "EPEC",
  "Reason": "SEFAZ indisponível - ativando contingência EPEC"
}
```

### Parâmetros do Corpo

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `Authorizer` | enum | ✅ | Novo autorizador (`Normal` ou `EPEC`) |
| `Reason` | string | ✅* | Motivo da troca (obrigatório para EPEC, 15-256 caracteres) |

:::note
O campo `Reason` é obrigatório quando `Authorizer` = `EPEC` e deve ter entre 15 e 256 caracteres.
:::

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "FromAuthorizer": "Normal",
  "ToAuthorizer": "EPEC",
  "Reason": "SEFAZ indisponível - ativando contingência EPEC",
  "ModifiedOn": "2024-01-20T15:30:00Z"
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Inscrição não encontrada |

### Exemplo cURL

```bash
curl -X POST https://api.nfse.io/v2/companies/company_abc123/statetaxes/stx_001/switch-authorizer \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "Authorizer": "EPEC",
    "Reason": "SEFAZ indisponível - ativando contingência EPEC"
  }'
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }
$body = @{
  Authorizer = "EPEC"
  Reason = "SEFAZ indisponível - ativando contingência EPEC"
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies/company_abc123/statetaxes/stx_001/switch-authorizer" `
  -Method Post -Headers $headers -Body $body -ContentType "application/json"
```

---

## Fluxo de Contingência

### Ativar Contingência EPEC

Quando a SEFAZ está indisponível:

```
1. Detectar indisponibilidade da SEFAZ
       ↓
2. POST /switch-authorizer com Authorizer="EPEC"
       ↓
3. Emitir NF-e em contingência EPEC
       ↓
4. Quando SEFAZ voltar: POST /switch-authorizer com Authorizer="Normal"
```

### Consultar Histórico de Trocas

O histórico da última troca está disponível em `ProcessingDetails.LastSwitchAuthorizerDetails`:

```json
{
  "ProcessingDetails": {
    "SwitchAuthorizerStrategy": "Manual",
    "AuthorityStatus": "Available",
    "StatusOn": "2024-02-20T14:45:00Z",
    "LastSwitchAuthorizerDetails": {
      "FromAuthorizer": "EPEC",
      "ToAuthorizer": "Normal",
      "Reason": "Retorno à operação normal",
      "ModifiedOn": "2024-01-20T08:00:00Z"
    }
  }
}
```

### Estratégia Automática

Configure `ProcessingDetails.SwitchAuthorizerStrategy` como `StateTaxAuthorityStatusUnavailable` para que o sistema troque automaticamente para contingência quando a SEFAZ estiver indisponível.

---

## Regras de Validação

O sistema aplica as seguintes regras de validação ao criar ou alterar uma inscrição estadual:

### Dados da Inscrição Estadual

| Campo | Regra | Mensagem de Erro |
|-------|-------|------------------|
| `Status` | Inscrição deve estar ativa para alterações | state tax is not active |
| `Code` | Obrigatório, deve ser UF válida (exceto EX e NA) | state code is not valid |
| `TaxNumber` | Obrigatório, deve ser IE válida para o estado | tax number is not valid |
| `Serie` | Deve ser entre 1 e 999 | serie is not valid |

### Validação de NFC-e

| Campo | Regra | Mensagem de Erro |
|-------|-------|------------------|
| `SecurityCredential` | Obrigatório quando `Type` = `NFCe` | Security credential is not valid |
| `SecurityCredential.Id` | Deve ser maior que 0 | Security credential is not valid |
| `SecurityCredential.Code` | Não pode ser vazio | Security credential is not valid |

### Validação de Contingência

| Campo | Regra | Mensagem de Erro |
|-------|-------|------------------|
| `Reason` | Obrigatório para EPEC, 15-256 caracteres | reason must be between 15 and 256 characters for contingency authorizer |

---

## Códigos de Erro

### Validação de Dados

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40002 | state tax is not active | Inscrição inativa não permite alterações |
| 40003 | tax number is not valid | Inscrição Estadual inválida para o estado |

### Validação de Empresa

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40035 | account id is null or empty | AccountId não informado |
| 40037 | company id is null or empty | CompanyId não informado |
| 40040 | request state is null | Payload da inscrição estadual nulo |
| 40041 | company not found | Empresa não encontrada |
| 40042 | company is not available to issue | Empresa inativa |
| 40043 | account id is not valid to this company | AccountId não corresponde à empresa |

### Validação de Inscrição Estadual

| Mensagem | Descrição |
|----------|-----------|
| state tax id is null or empty | StateTaxId não informado |
| state tax not found | Inscrição estadual não encontrada |
| account id is not valid to this state tax | AccountId não corresponde à inscrição |
| company id is not valid to this state tax | CompanyId não corresponde à inscrição |
| state code is not valid | Código do estado inválido |
| serie is not valid | Série fora do intervalo permitido |
| Security credential is not valid | Credencial de segurança inválida |

---

## Enums

### StateCode (Código do Estado)

| Nome | Descrição |
|------|-----------|
| `AC` | Acre |
| `AL` | Alagoas |
| `AP` | Amapá |
| `AM` | Amazonas |
| `BA` | Bahia |
| `CE` | Ceará |
| `DF` | Distrito Federal |
| `ES` | Espírito Santo |
| `GO` | Goiás |
| `MA` | Maranhão |
| `MT` | Mato Grosso |
| `MS` | Mato Grosso do Sul |
| `MG` | Minas Gerais |
| `PA` | Pará |
| `PB` | Paraíba |
| `PR` | Paraná |
| `PE` | Pernambuco |
| `PI` | Piauí |
| `RJ` | Rio de Janeiro |
| `RN` | Rio Grande do Norte |
| `RS` | Rio Grande do Sul |
| `RO` | Rondônia |
| `RR` | Roraima |
| `SC` | Santa Catarina |
| `SP` | São Paulo |
| `SE` | Sergipe |
| `TO` | Tocantins |

### EnvironmentType (Ambiente)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Test` | 0 | Homologação (padrão) |
| `Production` | 1 | Produção (emissão real) |

### Status

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -1 | Inativa (excluída/desativada) |
| `None` | 0 | Não definido |
| `Active` | 1 | Ativa (permite operações) |

### StateTaxType (Tipo de Emissão)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Default` | 0 | Padrão |
| `NFe` | 1 | NF-e - Nota Fiscal Eletrônica |
| `NFCe` | 2 | NFC-e - Nota Fiscal de Consumidor Eletrônica |

### SpecialTaxRegime (Regime Especial de Tributação)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Automatico` | -1 | Automático |
| `Nenhum` | 0 | Sem regime especial |
| `MicroempresaMunicipal` | 1 | Microempresa municipal |
| `Estimativa` | 2 | Regime de estimativa |
| `SociedadeDeProfissionais` | 3 | Sociedade de profissionais |
| `Cooperativa` | 4 | Cooperativa |
| `MicroempreendedorIndividual` | 5 | MEI |
| `MicroempresarioEmpresaPequenoPorte` | 6 | ME/EPP |

### StateTaxProcessingAuthorizer (Autorizador)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Normal` | 1 | SEFAZ normal |
| `EPEC` | 4 | Contingência EPEC (Evento Prévio de Emissão em Contingência) |

### StateTaxProcessingSwitchAuthorizerStrategy (Estratégia de Troca)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Manual` | 0 | Troca manual |
| `StateTaxAuthorityStatusUnavailable` | 1 | Troca automática quando SEFAZ indisponível |

### StateTaxAuthorityStatus (Status da SEFAZ)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Paused` | -2 | Pausada |
| `Unavailable` | -1 | Indisponível |
| `Unknown` | 0 | Desconhecido |
| `Available` | 1 | Disponível |

---

## Boas Práticas

### Numeração de Séries

- Use séries sequenciais simples (`1`, `2`, `3`)
- Mantenha controle do último número usado
- Não reutilize números dentro da mesma série
- Ao mudar de série, inicie a numeração em 1

### Validação de Inscrição Estadual

- Valide o formato da IE antes de enviar
- O sistema valida automaticamente a IE para a maioria dos estados
- Alguns estados (GO, PA) têm validação simplificada

### Contingência

- Monitore a disponibilidade da SEFAZ
- Tenha um plano de contingência documentado
- O motivo da contingência deve ter entre 15 e 256 caracteres
- Registre o motivo de cada troca de autorizador
- Retorne ao modo normal assim que possível

### Múltiplas Inscrições

- Uma empresa pode ter inscrições em diferentes estados
- Cada inscrição possui séries independentes
- Gerencie a numeração de cada estado separadamente

### NFC-e

- O CSC (Código de Segurança do Contribuinte) é obrigatório
- Obtenha o CSC junto à SEFAZ do estado
- Mantenha o CSC seguro e não compartilhe

---

## Próximos Passos

Após criar a inscrição estadual:

1. **Configure o certificado digital** correspondente ao CNPJ → [Ver documentação](./gerenciamento-certificado.md)
2. **Inicialize a numeração** da série conforme necessário
3. **Configure a estratégia de contingência** se desejar troca automática
4. **Comece a emitir** NF-e ou NFC-e

Para emissão de NFS-e, crie uma [Inscrição Municipal](./gerenciamento-inscricao-municipal.md).

---

## Veja também:

- [API de Empresas](./gerenciamento-empresas.md) - Gerenciamento de empresas
- [API de Certificados](./gerenciamento-certificado.md) - Gerenciamento de certificados digitais
- [Inscrições Municipais](./gerenciamento-inscricao-municipal.md) - Configuração para NFS-e

---

## API de Inscrições Municipais - Gestão de IM | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/gerenciamento-empresas/api-inscricoes-municipais/index.md

# API de Inscrições Municipais (MunicipalTax)

## Cadastre os dados de inscrição municipal para emissão de NFS-e

> **Navegação**
> - [← Voltar para Visão Geral](./gerenciamento-empresas-resumo.md)
> - [Empresas →](./gerenciamento-empresas.md)
> - [Certificados →](./gerenciamento-certificado.md)
> - [Inscrições Estaduais →](./gerenciamento-inscricao-estadual.md)

---

## Visão Geral

O recurso **MunicipalTax** (Inscrição Municipal) **registra na NFE.io** os dados cadastrais da empresa, necessários para emissão de NFS-e (Nota Fiscal de Serviços Eletrônica).

:::warning[Importante]
Esta API **não cadastra** sua empresa na prefeitura municipal. Ela apenas **registra na NFE.io os dados** de Inscrição Municipal que você já obteve junto à prefeitura, para utilizá-los como base nas emissões de NFS-e.

O cadastro junto à prefeitura, obtenção de credenciais (login/senha ou token) e habilitação para emissão de NFS-e devem ser feitos **diretamente por você** no portal da respectiva prefeitura.
:::

---

## Anatomia de uma Inscrição Municipal

### Conceitos Fundamentais

Ao cadastrar uma inscrição municipal, você informa os dados **já obtidos** junto à prefeitura:

| Conceito | Campos na API | Descrição |
|----------|---------------|-----------|
| **Localização** | `City` | Cidade da inscrição (código IBGE, nome, UF) |
| **Identificação Municipal** | `TaxNumber` | Número da Inscrição Municipal obtido na prefeitura |
| **Numeração RPS** | `RpsSerialNumber`, `RpsNumber` | Controle de numeração de RPS |
| **Ambiente** | `Environment` | Produção ou Desenvolvimento para emissão da nota|
| **Credenciais** | `LoginName`, `LoginPassword`, `AuthIssueValue` | Dados de acesso à prefeitura (usados na emissão) |

### Campos Gerenciados pelo Sistema

Além dos dados que você informa, o sistema gera e mantém automaticamente:

| Campo | Tipo | Quando é definido |
|-------|------|-------------------|
| `Id` | string | Gerado na criação |
| `CompanyId` | string | Vinculado à empresa da URL |
| `AccountId` | string | Vinculado à sua conta/tenant |
| `Status` | enum | Inicia como `Active` |
| `LastRpsSent` | long | Último RPS enviado (controle interno de numeração utilizado para emissões em prefeituras onde o RPS é sequencial) |
| `FiscalStatus` | enum | Verificado automaticamente (suporte da NFE.io para a cidade) |
| `RpsSerialNumbers` | array | Lista de séries utilizadas, atualizada automaticamente |
| `City.Country` | string | Definido automaticamente como `"BRA"` |
| `CreatedOn` | datetime | Data/hora da criação |
| `ModifiedOn` | datetime | Atualizado a cada alteração |

### O que o contribuinte faz **fora** do sistema NFE.io

1. Obtém sua Inscrição Municipal diretamente na prefeitura
2. Consegue credenciais de acesso (login/senha ou token) junto à prefeitura (se exigido)
3. Habilita a emissão de NFS-e no portal da prefeitura
4. Verifica com qual série e número de RPS ele deve utilizar na plataforma da NFE.io 
5. Cadastra esses dados no sistema NFE.io através desta API

### Referência Completa de Propriedades

### 📋 Expandir tabela completa

| Propriedade | Tipo | Obrigatório | Descrição |
|-------------|------|:-----------:|-----------|
| `Id` | string | — | Identificador único (gerado) |
| `CompanyId` | string | — | ID da empresa proprietária |
| `AccountId` | string | — | Conta/tenant proprietária |
| `Status` | enum | — | Status operacional |
| `City` | object | ✅ | Cidade da inscrição |
| `City.Code` | string | ✅ | Código IBGE (7 dígitos) |
| `City.Name` | string | ✅ | Nome da cidade |
| `City.State` | string | ✅ | UF (2 letras) |
| `City.Country` | string | — | País (sempre "BRA") |
| `TaxNumber` | string | — | Número da Inscrição Municipal |
| `SpecialTaxRegime` | enum | — | Regime especial de tributação |
| `Email` | string | — | E-mail para notificações |
| `LegalNature` | enum | — | Natureza jurídica |
| `CompanyRegistryNumber` | long | — | Registro na Junta Comercial |
| `RegionalTaxNumber` | long | — | Número do cadastro regional |
| `RpsSerialNumber` | string | ✅ | Série de RPS atual |
| `RpsNumber` | long | ✅ | Próximo número de RPS |
| `LastRpsSent` | long | - | Último RPS enviado |
| `RpsSerialNumbers` | array | — | Lista de séries (gerado) |
| `IssRate` | decimal | — | Alíquota do ISS (%) |
| `Environment` | enum | ✅ | Ambiente de processamento |
| `FiscalStatus` | enum | — | Suporte da NFE.io para a cidade |
| `FederalTaxDetermination` | enum | — | Determinação fiscal federal |
| `MunicipalTaxDetermination` | enum | — | Determinação fiscal municipal |
| `LoginName` | string | — | Usuário para acesso à prefeitura |
| `LoginPassword` | string | — | Senha para acesso à prefeitura |
| `AuthIssueValue` | string | — | Token de autorização |
| `CreatedOn` | datetime | — | Data de criação |
| `ModifiedOn` | datetime | — | Última modificação |

---

## Endpoints

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/v2/companies/{company_id}/municipaltaxes` | Criar inscrição |
| `GET` | `/v2/companies/{company_id}/municipaltaxes` | Listar inscrições |
| `GET` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}` | Consultar inscrição |
| `PUT` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}` | Alterar inscrição |
| `DELETE` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}` | Excluir inscrição |
| `PATCH` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}/updateprefecture` | Verificar suporte da cidade |
| `GET` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}/series/{serie}` | Consultar série RPS |

:::info[Autenticação]
Todos os endpoints exigem autenticação via API Key: `Authorization: <sua_api_key>`

→ **[Saiba como obter sua API Key](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/)**
:::

---

## Criar uma Inscrição Municipal

Cadastra os dados de uma inscrição municipal no sistema NFE.io.

:::note
Este endpoint apenas cadastra os dados no sistema NFE.io. A inscrição municipal deve ter sido previamente obtida junto à prefeitura.
:::

```http
POST /v2/companies/{company_id}/municipaltaxes
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

:::warning Ambiente padrão de criação
Toda Inscrição Municipal é criada no ambiente **`Development`**, independentemente do valor enviado no campo `Environment`. Isso evita emissões acidentais em produção durante a configuração e os testes.

Para emitir notas em **produção**, é necessário **alterar a IM após a criação**, definindo `Environment` como `Production` — veja [Alterar Inscrição Municipal](#alterar-inscrição-municipal).
:::

### Corpo da Requisição

```json
{
  "MunicipalTax": {
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP"
    },
    "TaxNumber": "876543",
    "Environment": "Development",
    "RpsSerialNumber": "IO",
    "RpsNumber": 1000,
    "LastRpsSent": 999
  }
}
```

### Parâmetros do Corpo

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `City` | object | ✅ | Cidade da inscrição |
| `City.Code` | string | ✅ | Código IBGE (7 dígitos) |
| `City.Name` | string | ✅ | Nome da cidade |
| `City.State` | string | ✅ | UF (2 letras) |
| `TaxNumber` | string | | Número da Inscrição Municipal |
| `Environment` | enum |  | Ambiente. **A IM é sempre criada em `Development`**, mesmo que outro valor seja enviado. Para emitir em produção, [altere a IM após a criação](#alterar-inscrição-municipal). Valores: `Development` (padrão), `Production`, `Staging` |
| `RpsSerialNumber` | string | ✅ | Série do RPS |
| `RpsNumber` | long | ✅ | Próximo número de RPS |
| `LastRpsSent` | long | ✅ | Último RPS enviado |

#### Parâmetros Opcionais

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `SpecialTaxRegime` | enum | Regime especial de tributação (padrão: `Nenhum`) |
| `Email` | string | E-mail para notificações |
| `LegalNature` | enum | Natureza jurídica |
| `CompanyRegistryNumber` | long | Número do registro na Junta Comercial |
| `RegionalTaxNumber` | long | Número do cadastro regional |
| `IssRate` | decimal | Alíquota de ISS (%) |
| `FederalTaxDetermination` | enum | Determinação fiscal federal (padrão: `Default`) |
| `MunicipalTaxDetermination` | enum | Determinação fiscal municipal (padrão: `Default`) |
| `LoginName` | string | Usuário para acesso à prefeitura |
| `LoginPassword` | string | Senha para acesso à prefeitura |
| `AuthIssueValue` | string | Token de autorização |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "MunicipalTax": {
    "Id": "mtx_001",
    "CompanyId": "company_abc123",
    "AccountId": "acct_12345",
    "Status": "Active",
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    },
    "TaxNumber": "876543",
    "SpecialTaxRegime": "Nenhum",
    "Email": null,
    "LegalNature": "None",
    "CompanyRegistryNumber": null,
    "RegionalTaxNumber": null,
    "RpsSerialNumber": "IO",
    "RpsNumber": 1000,
    "LastRpsSent": 999,
    "IssRate": null,
    "Environment": "Development",
    "FiscalStatus": "Active",
    "FederalTaxDetermination": "Default",
    "MunicipalTaxDetermination": "Default",
    "LoginName": null,
    "LoginPassword": null,
    "AuthIssueValue": null,
    "RpsSerialNumbers": ["IO"],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": null
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Empresa não encontrada |

```json
{
  "Errors": [
    {
      "Code": 40044,
      "Message": "city is null"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X POST https://api.nfse.io/v2/companies/company_abc123/municipaltaxes \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "MunicipalTax": {
      "City": { "Code": "3550308", "Name": "São Paulo", "State": "SP" },
      "Environment": "Development",
      "RpsSerialNumber": "IO",
      "RpsNumber": 1000,
      "LastRpsSent": 999
    }
  }'
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }
$body = @{
  MunicipalTax = @{
    City = @{ Code = "3550308"; Name = "São Paulo"; State = "SP" }
    TaxNumber = "876543"
    Environment = "Development"
    RpsSerialNumber = "IO"
    RpsNumber = 1000
    LastRpsSent = 999
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies/company_abc123/municipaltaxes" `
  -Method Post -Headers $headers -Body $body -ContentType "application/json"
```

---

## Listar Inscrições Municipais

Lista todas as inscrições municipais de uma empresa com paginação.

```http
GET /v2/companies/{company_id}/municipaltaxes
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Parâmetros de Query

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|--------|-----------|
| `limit` | int | 10 | Limite de resultados (1-50) |
| `startingAfter` | string | | ID do cursor para próxima página |
| `endingBefore` | string | | ID do cursor para página anterior |

### Ordenação

- Primária: `CreatedOn` (descendente - mais recentes primeiro)
- Secundária: `Id` (ascendente)

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "hasMore": true,
  "municipalTaxes": [
    {
      "Id": "mtx_001",
      "CompanyId": "company_abc123",
      "AccountId": "acct_12345",
      "Status": "Active",
      "City": {
        "Code": "3550308",
        "Name": "São Paulo",
        "State": "SP",
        "Country": "BRA"
      },
      "TaxNumber": "876543",
      "SpecialTaxRegime": "Nenhum",
      "Email": "contato@acme.com.br",
      "LegalNature": "SociedadeEmpresariaLimitada",
      "CompanyRegistryNumber": 1234567,
      "RegionalTaxNumber": null,
      "RpsSerialNumber": "IO",
      "RpsNumber": 1000,
      "LastRpsSent": 999,
      "IssRate": 2.0,
      "Environment": "Production",
      "FiscalStatus": "Active",
      "FederalTaxDetermination": "Default",
      "MunicipalTaxDetermination": "Default",
      "LoginName": "pref_user",
      "AuthIssueValue": null,
      "RpsSerialNumbers": ["IO"],
      "CreatedOn": "2024-01-15T10:30:00Z",
      "ModifiedOn": "2024-02-20T14:45:00Z"
    },
    {
      "Id": "mtx_002",
      "CompanyId": "company_abc123",
      "AccountId": "acct_12345",
      "Status": "Active",
      "City": {
        "Code": "3304557",
        "Name": "Rio de Janeiro",
        "State": "RJ",
        "Country": "BRA"
      },
      "TaxNumber": "112233",
      "SpecialTaxRegime": "Nenhum",
      "Email": null,
      "LegalNature": "None",
      "CompanyRegistryNumber": null,
      "RegionalTaxNumber": null,
      "RpsSerialNumber": "A1",
      "RpsNumber": 200,
      "LastRpsSent": 199,
      "IssRate": null,
      "Environment": "Production",
      "FiscalStatus": "Active",
      "FederalTaxDetermination": "Default",
      "MunicipalTaxDetermination": "Default",
      "LoginName": null,
      "AuthIssueValue": null,
      "RpsSerialNumbers": ["A1"],
      "CreatedOn": "2024-01-10T14:00:00Z",
      "ModifiedOn": null
    }
  ]
}
```

### Paginação

Use o `Id` do último item como `startingAfter` para obter a próxima página:

```http
GET /v2/companies/{company_id}/municipaltaxes?limit=20&startingAfter=mtx_002
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Empresa ou cursor não encontrado |

### Exemplo cURL

```bash
curl -X GET "https://api.nfse.io/v2/companies/company_abc123/municipaltaxes?limit=20" \
  -H "Authorization: sk_live_xxx"
```

---

## Consultar Inscrição Municipal por ID

Retorna os detalhes de uma inscrição municipal específica.

```http
GET /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "MunicipalTax": {
    "Id": "mtx_001",
    "CompanyId": "company_abc123",
    "AccountId": "acct_12345",
    "Status": "Active",
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    },
    "TaxNumber": "876543",
    "SpecialTaxRegime": "Nenhum",
    "Email": "contato@acme.com.br",
    "LegalNature": "SociedadeEmpresariaLimitada",
    "CompanyRegistryNumber": 1234567,
    "RegionalTaxNumber": 98765,
    "RpsSerialNumber": "IO",
    "RpsNumber": 1000,
    "LastRpsSent": 999,
    "IssRate": 2.0,
    "Environment": "Production",
    "FiscalStatus": "Active",
    "FederalTaxDetermination": "Default",
    "MunicipalTaxDetermination": "Default",
    "LoginName": "pref_user",
    "LoginPassword": null,
    "AuthIssueValue": "ABC-XYZ",
    "RpsSerialNumbers": ["IO", "A1"],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-02-20T14:45:00Z"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Inscrição não encontrada |

```json
{
  "Errors": [
    {
      "Code": 40041,
      "Message": "municipal tax not found"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001 \
  -H "Authorization: sk_live_xxx"
```

---

## Alterar Inscrição Municipal

Atualiza os dados de uma inscrição municipal existente.

```http
PUT /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição

:::tip Promover a IM para produção
Como a IM nasce em `Development`, este é o endpoint usado para movê-la para produção: basta enviar `"Environment": "Production"` no corpo da requisição. Confirme que a integração com a prefeitura está validada (`FiscalStatus: Active`) antes de promover.
:::

```json
{
  "MunicipalTax": {
    "TaxNumber": "876544",
    "Email": "novo-email@acme.com.br",
    "IssRate": 3.0,
    "Environment": "Production",
    "LoginName": "novo_usuario",
    "LoginPassword": "nova_senha"
  }
}
```

### Campos Atualizáveis

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `City` | object | Cidade da inscrição |
| `TaxNumber` | string | Número da Inscrição Municipal |
| `Email` | string | E-mail para notificações |
| `SpecialTaxRegime` | enum | Regime especial de tributação |
| `LegalNature` | enum | Natureza jurídica |
| `CompanyRegistryNumber` | long | Número do registro na Junta Comercial |
| `RegionalTaxNumber` | long | Número do cadastro regional |
| `IssRate` | decimal | Alíquota de ISS (%) |
| `RpsSerialNumber` | string | Série do RPS |
| `RpsNumber` | long | Próximo número de RPS |
| `LastRpsSent` | long | Último RPS enviado |
| `Environment` | enum | Ambiente de processamento |
| `LoginName` | string | Usuário da prefeitura |
| `LoginPassword` | string | Senha da prefeitura |
| `AuthIssueValue` | string | Token de autorização |
| `FederalTaxDetermination` | enum | Determinação fiscal federal |
| `MunicipalTaxDetermination` | enum | Determinação fiscal municipal |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "MunicipalTax": {
    "Id": "mtx_001",
    "CompanyId": "company_abc123",
    "AccountId": "acct_12345",
    "Status": "Active",
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    },
    "TaxNumber": "876544",
    "SpecialTaxRegime": "Nenhum",
    "Email": "novo-email@acme.com.br",
    "LegalNature": "SociedadeEmpresariaLimitada",
    "CompanyRegistryNumber": 1234567,
    "RegionalTaxNumber": null,
    "RpsSerialNumber": "IO",
    "RpsNumber": 1000,
    "LastRpsSent": 999,
    "IssRate": 3.0,
    "Environment": "Production",
    "FiscalStatus": "Active",
    "FederalTaxDetermination": "Default",
    "MunicipalTaxDetermination": "Default",
    "LoginName": "novo_usuario",
    "LoginPassword": null,
    "AuthIssueValue": null,
    "RpsSerialNumbers": ["IO"],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-03-10T16:20:00Z"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Inscrição não encontrada |

### Exemplo cURL

```bash
curl -X PUT https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001 \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "MunicipalTax": {
      "Email": "novo-email@acme.com.br",
      "IssRate": 3.0
    }
  }'
```

---

## Excluir Inscrição Municipal

Exclui uma inscrição municipal da empresa.

:::warning[Atenção]
Este processo é **irreversível**. Histórico de numeração RPS será perdido.
:::

```http
DELETE /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |

### Headers

| Header | Valor |
|--------|-------|
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `204 No Content`

(Sem corpo na resposta)

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Inscrição não encontrada |

### Exemplo cURL

```bash
curl -X DELETE https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001 \
  -H "Authorization: sk_live_xxx"
```

---

## Verificar Suporte da Cidade

Força uma verificação se a NFE.io possui suporte/homologação para emissão de NFS-e na cidade cadastrada.

:::warning[Importante]
Este endpoint **não** verifica o status da prefeitura em si. Ele verifica internamente se o sistema NFE.io tem integração homologada com a prefeitura daquela cidade.
:::

```http
PATCH /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}/updateprefecture
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |

### Headers

| Header | Valor |
|--------|-------|
| `Authorization` | `<sua_api_key>` |

### Uso

Este endpoint é útil quando:
- Você quer verificar se a NFE.io adicionou suporte para uma cidade que antes não era suportada
- Houve atualização na lista de cidades homologadas
- Você quer atualizar o `FiscalStatus` após mudanças internas no sistema

### Resposta de Sucesso

**Status:** `204 No Content`

(Sem corpo na resposta - o FiscalStatus é atualizado internamente)

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Inscrição não encontrada |

### Exemplo cURL

```bash
curl -X PATCH https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001/updateprefecture \
  -H "Authorization: sk_live_xxx"
```

---

## Consultar Série RPS

Consulta informações de numeração de uma série específica de RPS.

```http
GET /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}/series/{serie}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |
| `serie` | string | Identificador da série RPS |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Serie": {
    "RpsNumber": 1500,
    "LastRpsSent": 1499
  }
}
```

### Campos da Resposta

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `RpsNumber` | long | Próximo número de RPS disponível |
| `LastRpsSent` | long | Último número de RPS enviado/utilizado |

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Inscrição ou série não encontrada |

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001/series/IO \
  -H "Authorization: sk_live_xxx"
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001/series/IO" `
  -Method Get -Headers $headers
```

---

## Regras de Validação

O sistema aplica as seguintes regras de validação ao criar ou alterar uma inscrição municipal:

### Dados da Inscrição Municipal

| Campo | Regra | Mensagem de Erro |
|-------|-------|------------------|
| `Status` | Inscrição deve estar ativa para alterações | municipal tax is not active |
| `City` | Obrigatório | city is null |
| `City.Code` | 7 dígitos, primeiros 2 devem corresponder ao código da UF | city code does not match the state code |
| `City.Name` | Obrigatório | city name is null or empty |
| `City.State` | Obrigatório, deve ser UF válida | state is null or empty / state is not valid |
| `RpsSerialNumber` | Obrigatório | rps serial number is null or empty |
| `Email` | Se informado, não pode ser vazio | email is null or empty |

### Validação de Cidade

O código IBGE da cidade deve corresponder ao estado informado (exemplos):

| UF | Código IBGE (primeiros 2 dígitos) |
|----|-----------------------------------|
| SP | 35 |
| RJ | 33 |
| MG | 31 |
| PR | 41 |
| RS | 43 |

---

## Códigos de Erro

### Validação de Dados

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40035 | account id is null or empty | AccountId não informado |
| 40037 | company id is null or empty | CompanyId não informado |
| 40040 | request municipal tax is null | Payload da inscrição municipal nulo |
| 40044 | city is null | Cidade não informada |
| 40045 | city code is null or empty | Código IBGE não informado |

### Validação de Empresa

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40041 | company not found | Empresa não encontrada |
| 40042 | company is not available to issue | Empresa inativa |
| 40043 | account id is not valid to this company | AccountId não corresponde à empresa |

### Validação de Inscrição Municipal

| Mensagem | Descrição |
|----------|-----------|
| municipal tax is not active | Inscrição inativa não permite alterações |
| municipal tax not found | Inscrição municipal não encontrada |
| city name is null or empty | Nome da cidade não informado |
| state is null or empty | UF não informada |
| state is not valid | UF inválida |
| city code does not match the state code | Código IBGE não corresponde à UF |
| rps serial number is null or empty | Série RPS não informada |
| series not found | Série não encontrada |
| serial number not found | Série especificada não existe |
| account id is not valid to this municipal tax | AccountId não corresponde à inscrição |
| company id is not valid to this municipal tax | CompanyId não corresponde à inscrição |

---

## Enums

### ApiEnvironment (Ambiente)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Development` | 0 | Desenvolvimento (padrão) |
| `Production` | 1 | Produção (emissão real) |
| `Staging` | 2 | Homologação |

> **Importante:** ao criar uma IM, o ambiente é sempre `Development`, mesmo que outro valor seja enviado no `POST`. Para mudar para `Production` ou `Staging`, [altere a IM](#alterar-inscrição-municipal) após a criação.

:::note
Nem todas as prefeituras suportam ambiente de teste/homologação.
:::

### Status

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -1 | Inativa (excluída/desativada) |
| `None` | 0 | Não definido |
| `Active` | 1 | Ativa (permite operações) |

### MunicipalTaxFiscalStatus (Suporte da Cidade)

Indica se a NFE.io possui integração homologada com a prefeitura da cidade.

| Nome | Valor | Descrição | NFE.io pode emitir? |
|------|-------|-----------|---------------------|
| `CityNotSupported` | -3 | NFE.io não possui integração com esta cidade | ❌ Não |
| `Pending` | -2 | Integração em desenvolvimento | ❌ Não |
| `Inactive` | -1 | Integração temporariamente indisponível | ❌ Não |
| `None` | 0 | Status não determinado | ❌ Não |
| `Active` | 1 | NFE.io tem integração homologada | ✅ Sim |

### SpecialTaxRegime (Regime Especial de Tributação)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Automatico` | -1 | Automático (detectado pelo sistema) |
| `Nenhum` | 0 | Sem regime especial |
| `MicroempresaMunicipal` | 1 | Microempresa municipal |
| `Estimativa` | 2 | Regime de estimativa |
| `SociedadeDeProfissionais` | 3 | Sociedade de profissionais |
| `Cooperativa` | 4 | Cooperativa |
| `MicroempreendedorIndividual` | 5 | MEI |
| `MicroempresarioEmpresaPequenoPorte` | 6 | ME/EPP |

### FederalTaxDeterminationBy (Determinação Fiscal Federal)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `NotInformed` | 0 | Não informado |
| `Default` | 2 | Padrão |
| `SimplesNacional` | 4 | Simples Nacional |

### MunicipalTaxDeterminationBy (Determinação Fiscal Municipal)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `NotInformed` | 0 | Não informado |
| `Default` | 2 | Padrão |
| `SimplesNacional` | 4 | Simples Nacional |

### LegalNature (Natureza Jurídica)

Código de acordo com a Tabela de Natureza Jurídica (Resolução Concla). Exemplos mais comuns:

| Nome | Código | Descrição |
|------|--------|-----------|
| `None` | 0 | Não definido |
| `EmpresaPublica` | 2011 | 201-1 Empresa Pública |
| `SociedadeAnonimaAberta` | 2046 | 204-6 S.A. Aberta |
| `SociedadeAnonimaFechada` | 2054 | 205-4 S.A. Fechada |
| `SociedadeEmpresariaLimitada` | 2062 | 206-2 Sociedade Empresária Limitada |
| `SociedadeEmpresariaEmNomeColetivo` | 2070 | 207-0 Sociedade em Nome Coletivo |
| `SociedadeEmpresariaEmComanditaSimples` | 2089 | 208-9 Sociedade em Comandita Simples |
| `Empresario` | 2135 | 213-5 Empresário Individual |
| `Cooperativa` | 2143 | 214-3 Cooperativa |
| `SociedadeSimplesPura` | 2232 | 223-2 Sociedade Simples Pura |
| `SociedadeSimplesLimitada` | 2240 | 224-0 Sociedade Simples Limitada |
| `EireliNaturezaEmpresaria` | 2305 | 230-5 EIRELI (Natureza Empresária) |
| `EireliNaturezaSimples` | 2313 | 231-3 EIRELI (Natureza Simples) |
| `EmpresaSimplesDeInovacao` | 2348 | 234-8 Inova Simples |
| `AssociacaoPrivada` | 3999 | 399-9 Associação Privada |

:::info
Consulte a tabela completa de Natureza Jurídica no [site do IBGE/Concla](http://concla.ibge.gov.br/estrutura/natjur-estrutura/natureza-juridica-2009-1).
:::

---

## Valores Padrão

O sistema aplica os seguintes valores padrão quando não informados:

| Campo | Valor Padrão | Descrição |
|-------|--------------|-----------|
| `RpsSerialNumber` | `"IO"` | Série padrão de RPS |
| `SpecialTaxRegime` | `Nenhum` | Sem regime especial |
| `FederalTaxDetermination` | `Default` | Determinação padrão |
| `MunicipalTaxDetermination` | `Default` | Determinação padrão |
| `LegalNature` | `None` | Não definido |
| `Environment` | `Development` | Ambiente de desenvolvimento |
| `City.Country` | `"BRA"` | Brasil (aplicado automaticamente) |

---

## Boas Práticas

### Numeração RPS

- **Inicie a numeração corretamente**: Defina `RpsNumber` como o próximo número a ser usado
- **Sincronize `LastRpsSent`**: Deve ser `RpsNumber - 1` na criação
- **Use séries simples**: `IO`, `A1`, `1` são exemplos comuns
- **Não reutilize números**: Cada RPS deve ter número único na série

### Códigos IBGE

Use códigos IBGE válidos de 7 dígitos. Exemplos:

| Cidade | Código IBGE |
|--------|-------------|
| São Paulo/SP | 3550308 |
| Rio de Janeiro/RJ | 3304557 |
| Belo Horizonte/MG | 3106200 |
| Curitiba/PR | 4106902 |
| Porto Alegre/RS | 4314902 |

### Credenciais da Prefeitura

As credenciais são **armazenadas** no sistema NFE.io e utilizadas automaticamente **no momento da emissão** de cada NFS-e:

- Algumas prefeituras exigem `LoginName` e `LoginPassword`
- Outras exigem `AuthIssueValue` (token)
- Consulte os requisitos específicos da prefeitura no portal dela
- As credenciais devem ser obtidas **diretamente na prefeitura** pelo contribuinte
- **Nunca** compartilhe credenciais em logs ou mensagens de erro

### Monitoramento

- Verifique `FiscalStatus` para confirmar que a NFE.io tem suporte para a cidade
- Use `updateprefecture` para verificar se houve atualização no suporte da cidade
- Se `FiscalStatus != Active`, a cidade pode não ser suportada pela NFE.io ainda

---

## Próximos Passos

Após cadastrar a inscrição municipal no sistema NFE.io:

1. **Verifique o FiscalStatus** - Confirme que a NFE.io tem suporte para a cidade (`Active`)
2. **Configure o certificado digital** se ainda não tiver → [Ver documentação](./gerenciamento-certificado.md)
3. **Confirme as credenciais** - Se a prefeitura exige login/senha ou token, verifique se foram cadastradas corretamente
4. **Valide a numeração RPS** - Confirme que `RpsNumber` e `LastRpsSent` estão sincronizados com a prefeitura
5. **Teste a emissão** - Se possível, use ambiente de desenvolvimento para validar a configuração

:::tip[Lembre-se]
A NFE.io apenas registra os dados que você já possui. O cadastro na prefeitura (obtenção da Inscrição Municipal, credenciais e habilitação para emissão) deve ser feito diretamente por você no portal da prefeitura.
:::

---

## Veja também:

- [API de Empresas](./gerenciamento-empresas.md) - Gerenciamento de empresas
- [API de Certificados](./gerenciamento-certificado.md) - Gerenciamento de certificados digitais
- [Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) - Configuração para NF-e/NFC-e

---

## Conceitos - Inteligência Tributária

Source: https://nfe.io/docs/inteligencia-tributaria/conceitos/index.md

# Motor de Cálculo de Tributos - Conceitos

O Motor de Cálculo Tributário (Taxes) é uma ferramenta automatizada desenvolvida para simplificar e garantir a conformidade na gestão de tributos da sua empresa. A legislação brasileira exige extrema precisão no cálculo de impostos como ICMS, PIS, COFINS, IPI e DIFAL na emissão da Nota Fiscal Eletrônica (NF-e). Nosso motor realiza todo esse processamento para você.

## 1. O que é e como funciona?

O cálculo de impostos no Brasil varia de acordo com inúmeros fatores, tais como a localização do remetente e do destinatário, o regime tributário de ambos, a classificação fiscal (NCM/CEST) do produto e o tipo da operação (venda, revenda, devolução, etc.).

O **Motor de Cálculo Tributário da NFE.io** analisa todos esses cenários em tempo real. Você informa os dados básicos da operação comercial e da mercadoria, e o nosso motor processa as regras fiscais vigentes e retorna os valores, alíquotas, códigos (como CFOP, CST/CSOSN) e bases de cálculo prontos para a emissão da NF-e.

## 2. Modelos de Utilização

Nosso motor adapta-se à complexidade do seu negócio através de dois cenários principais de uso:

### 2.1. Regras Padrão (Standard)
Neste modelo, o sistema utiliza a inteligência tributária nativa em tempo real.
* **Como funciona:** Você envia os parâmetros da operação (emitente, destinatário, produto e valores) no momento de solicitar o cálculo.
* **Vantagem:** Não é necessário cadastrar os produtos previamente. O motor se encarrega de aplicar a regra geral com máxima precisão.

### 2.2. Regras Customizadas (Cadastro de Produtos)
Ideal para empresas que possuem particularidades fiscais, benefícios específicos (como redução de base de cálculo, isenções) ou regimes especiais que divergem da tributação padrão.
* **Como funciona:** Você realiza o cadastro dos seus produtos em nossa plataforma configurando os cenários tributários customizados (`customTax`).
* **Vantagem:** Quando o cálculo for acionado para um produto cadastrado e as condições da operação baterem com a sua regra, o motor prioriza a sua customização, substituindo o cálculo padrão.

## 3. Os Pilares do Cálculo Tributário

Para garantir que o cálculo seja correto e aplicável à operação, o motor baseia-se em quatro pilares de dados:

1. **Emitente:** O seu estado (UF), perfil fiscal (ex: varejista, indústria, atacadista) e regime tributário (Lucro Real, Presumido, Simples Nacional). O regime dita regras cruciais, determinando se será usado CST (2 dígitos) ou CSOSN (3 dígitos) no ICMS.
2. **Destinatário:** A UF de destino, regime e, principalmente, o perfil (consumidor final, contribuinte de ICMS, etc.). Isso afeta diretamente a formação da partilha do DIFAL, por exemplo.
3. **Produto:** Informações detalhadas do item que está sendo negociado, destacando-se a NCM (classificação fiscal), CEST (para casos de substituição tributária) e a Origem (nacional, importada, etc.).
4. **Operação:** Qual a natureza do movimento? (ex: Venda de produto próprio, transferência entre filiais, entrada por devolução). A inteligência do motor mapeia internamente os códigos de operação.

## 4. O Que o Motor Retorna?

O retorno do motor consiste em todo o pacote de informações exigido pelo layout da NF-e em relação à tributação:
* **CFOP:** O Código Fiscal de Operações e Prestações correto para a operação faturada.
* **ICMS:** Modalidade de determinação da base de cálculo, CST/CSOSN, valor da base, alíquota aplicável e valor do imposto.
* **ICMS ST:** Cálculos completos para Substituição Tributária (incluindo ICMS ST retido).
* **DIFAL:** Diferencial de Alíquota e partilha entre os estados remetente e destinatário (aplicável a consumidor final em operações interestaduais).
* **FCP:** Valores referentes ao Fundo de Combate à Pobreza.
* **PIS, COFINS, IPI e II:** Respectivos cálculos de base, alíquota e valores finais para impostos federais.

## 5. Visão Geral do Fluxo

O Motor de Cálculo de Tributos pode ser acionado **diretamente via API** antes da emissão da nota fiscal, para simulações e validações do carrinho de compras (checkout), ou pode ser configurado para atuar **automaticamente** no momento emisão da nota fiscal, gerando o documento já com todos os tributos devidamente preenchidos.

![](https://nfe.io/docs/app/uploads/2025/02/TAxes-Diagram.drawio-4.png)

> **Dica para Desenvolvedores:**
> Para visualizar exemplos técnicos e payloads completos do motor de cálculo, acesse nossa collection no Postman:
> `https://api.postman.com/collections/13456751-85dce505-ec19-4086-b2ed-fd6adfa49b41?access_key=PMAT-01JKE6X6T47G7JGRYDNV5XRD1S`

---

## Guia do usuário - Inteligência Tributária

Source: https://nfe.io/docs/inteligencia-tributaria/guia-do-usuario/index.md

# Guia do Usuário — Motor de Cálculo Tributário e Cadastro de Produtos NFE.io

**Produto:** NFE.io — Motor de Cálculo Tributário
**Versão:** 1.0
**Data:** 2026-03-19
**Audiência:** Usuários e clientes do sistema NFE.io

---

## O que é o Motor de Cálculo Tributário da NFE.io?

Quando você emite uma Nota Fiscal Eletrônica (NF-e), a legislação brasileira exige que você informe corretamente os tributos de cada produto: ICMS, PIS, COFINS, IPI e, em alguns casos, o DIFAL (diferencial de alíquota interestadual). Calcular esses tributos manualmente é extremamente complexo, pois as regras variam conforme:

- O estado de origem e destino da mercadoria
- O regime tributário do emitente (Lucro Real, Presumido, Simples Nacional, MEI…)
- O tipo de destinatário (consumidor final, revendedor, indústria…)
- A classificação fiscal do produto (NCM, CEST, origem)
- O tipo de operação (venda, devolução, transferência…)

O **Motor de Cálculo Tributário da NFE.io** faz tudo isso por você. Você informa os dados da operação e da mercadoria, e o sistema retorna automaticamente todos os tributos calculados e prontos para compor o XML da NF-e.

---

## Modelo de Utilização do Motor de Cálculo

Para garantir o sucesso da sua integração e na utilização da nossa API, é importante alinhar o modelo de utilização do motor de cálculo. Atualmente, oferecemos dois cenários principais:

### 1. Utilização de Regras Padrão (Standard)

Neste cenário, você utiliza a inteligência tributária nativa do nosso motor.

- **Ação:** Não é necessário realizar o cadastro prévio de produtos.
- **Integração:** Basta enviar as propriedades perfeitamente preenchidas no grupo `TaxDetermination` via API. Com base nesses dados, o sistema processa e monta automaticamente o grupo Tax com os impostos do item.

### 2. Regras Customizadas

Indicado caso a sua operação possua particularidades fiscais ou benefícios específicos que fogem à regra geral.

- **Ação:** É necessário realizar o cadastro do produto e a configuração de cenários customizados.
- **Análise Necessária:** Nossa equipe de atendimento precisará validar se a customização desejada já existe em nossa base ou se será necessário desenvolver um novo cenário.

**Informações necessárias para o Onboarding:**

Para definir quais campos serão utilizados na configuração de regras customizadas, é fundamental mapear as seguintes variáveis do seu negócio:

- **Natureza das Operações:** Venda, transferência, entrada, simples remessa, etc.
- **Perfil dos Envolvidos:** Regime tributário, localização do emitente e do destinatário, entre outras características.
- **Especificidades do Produto:** NCM, tipo de item e a definição exata da regra que se deseja customizar.

Para garantir agilidade na configuração e na análise do seu cenário, pedimos que encaminhe ao nosso suporte as respostas do questionário de onboarding abaixo. Ele está dividido no contexto geral da sua operação e nas especificidades da regra customizada:

#### Parte 1: Perfil da Empresa (Contexto Geral)
Este mapeamento é feito apenas uma vez para entendermos o seu negócio.
1. **Atuação:** Possui operação e venda no território nacional de produtos/mercadorias? Realiza operações com múltiplos produtos?
2. **Segmento e Perfil:** Qual seu segmento de atuação (ex: Bebidas, eCommerce) e perfil do emitente (ex: Indústria, Varejista, Atacadista)?
3. **Regime Tributário:** Qual o regime de operação da empresa emitente? *(Lucro Real, Lucro Presumido ou Simples Nacional)*
4. **Volume e Abrangência:**
   - Qual a volumetria mensal de NF-es e média de itens por nota?
   - Em quais estados (UFs) sua empresa possui matriz/filiais e quais os principais estados de destino das vendas?
   - Quantos NCMs diferentes costuma operar e quais os principais capítulos?
5. **Operações Frequentes:** No seu dia a dia, quais operações são mais comuns? *(Ex: Venda, Revenda, Devolução, Transferência, etc.)*
6. **Automação e Particularidades:** Existe algum processo automatizado para os cálculos hoje? Sua empresa possui operações com regimes especiais (benefícios, isenções específicas do Estado)?

#### Parte 2: Mapeamento da Regra Customizada (Cenário Específico)
Para **cada regra customizada** que você precisar criar no nosso motor (para atender os regimes especiais ou particularidades citadas no item 6 da Parte 1), precisaremos das informações pontuais abaixo:
1. **Operação Alvo:** Dentre as operações que sua empresa realiza, para qual delas esta regra específica será aplicada? *(Ex: Somente para Transferência entre filiais)*
2. **CFOP Esperado:** Qual é o CFOP de saída exato que deseja para esta regra?
3. **CST de ICMS Esperado:** Qual o CST do ICMS que deve ser forçado/aplicado?
4. **UF Origem vs. UF Destino da Regra:** Em qual cruzamento de estados essa regra deve ser disparada? *(Ex: Somente saídas de SP para RJ)*
5. **Origem da Mercadoria:** Essa regra se aplica a produtos com qual origem? *(Ex: Somente Importados)*
6. **Classificação Fiscal (NCMs Afetados):** Quais são os NCMs exatos que devem obedecer a esta regra específica?
7. **Escopo da Customização:** A intenção é customizar apenas os valores de ICMS ou também outros impostos (PIS, COFINS)?

---

## 1. Visão Geral dos Dois Recursos Principais

### 1.1 Motor de Cálculo

O motor de cálculo é o coração do sistema. Você envia:
- Quem está emitindo (regime tributário, perfil fiscal, estado)
- Para quem está enviando (estado do destinatário, tipo de destinatário)
- Quais produtos (NCM, origem, quantidade, valor)

E recebe de volta:
- CFOP correto para cada produto
- CST ou CSOSN do ICMS
- Valores de base de cálculo, alíquotas e tributos calculados
- DIFAL (quando aplicável em operações interestaduais para consumidor final)
- PIS, COFINS, IPI

### 1.2 Cadastro de Produto

O cadastro de produto é um recurso **opcional** que permite "pré-configurar" produtos com regras tributárias específicas. Quando um produto cadastrado é identificado em uma operação de cálculo, suas regras customizadas substituem (total ou parcialmente) o resultado padrão do motor.

**Por que cadastrar um produto?**
- Seu produto tem tributação especial que o motor padrão não conhece (ex: benefício fiscal estadual, código de redução de base)
- Você trabalha no regime de Substituição Tributária e precisa informar valores de ICMS ST retido
- Você quer garantir que sempre seja utilizado o CST correto para um produto específico
- Sua empresa tem acordos ou regimes diferenciados que precisam ser refletidos na NF-e

**Sem cadastro de produto:** o sistema calcula normalmente — você só não terá as customizações aplicadas.

---

## 2. O Motor de Cálculo em Detalhes

### 2.1 O Que Você Precisa Informar

Para calcular os tributos de uma operação, você precisa fornecer:

**Sobre o Emitente:**
- Estado (ex: São Paulo → SP)
- Regime tributário (Lucro Real, Lucro Presumido, Simples Nacional, MEI...)
- Perfil fiscal (indústria, comércio, atacado, importador)

**Sobre o Destinatário:**
- Estado (ex: Rio de Janeiro → RJ)
- Regime tributário (opcional, se conhecido)
- Tipo de destinatário (consumidor final, filial, revendedor...)

**Sobre a Operação:**
- Tipo: saída (venda) ou entrada (compra/devolução)
- Código de operação (define a natureza: venda, devolução, transferência, etc.)

**Sobre cada Produto:**
- NCM (Nomenclatura Comum do Mercosul — 8 dígitos)
- Origem da mercadoria (nacional ou estrangeira e em qual grau)
- CEST (quando o produto está sujeito à Substituição Tributária)
- Quantidade e valor unitário
- Valor de frete, seguro e desconto (quando aplicável)

### 2.2 O Que Você Recebe

Para cada produto informado, o sistema retorna:

**CFOP:** Código Fiscal de Operações — define a natureza da operação para fins fiscais (ex: 5102 para venda de mercadoria adquirida de terceiros no estado)

**ICMS:** Todos os campos necessários para o XML da NF-e:
- CST (Código de Situação Tributária) ou CSOSN (para Simples Nacional)
- Modalidade de cálculo da base (modBC)
- Base de cálculo (vBC) e alíquota (pICMS)
- Valor do ICMS (vICMS)
- Campos de ST quando aplicável (vBCST, pICMSST, vICMSST, etc.)
- Campos de ST retido anteriormente (vBCSTRet, vICMSSTRet, pST, etc.)
- Fundo de Combate à Pobreza (FCP) quando aplicável
- Desoneração (quando aplicável)

**DIFAL (Diferencial de Alíquota):** Calculado automaticamente em operações interestaduais para consumidor final (EC 87/2015 e LC 190/2022)
- Base de cálculo na UF de destino
- Alíquota interna e interestadual
- Partilha entre UF remetente e destinatário
- FCP da UF de destino

**PIS e COFINS:**
- CST
- Base de cálculo e alíquota
- Valor calculado
- Suporte a cálculo por quantidade (alíquota específica)

**IPI:**
- CST e código de enquadramento
- Base de cálculo (por dentro — gross-up)
- Alíquota e valor

**Imposto de Importação (II):** quando aplicável a produtos estrangeiros

**Informações Adicionais:** texto informativo sobre tributos para a NF-e

### 2.3 Como os Regimes Tributários Influenciam o Cálculo

O regime tributário do emitente é um dos fatores mais importantes:

**Simples Nacional / MEI / Simples Nacional sublimite:**
- ICMS: usa CSOSN (3 dígitos) em vez de CST (2 dígitos)
- ICMS: pode gerar crédito para o destinatário (pCredSN, vCredICMSSN)
- Cache: o resultado é reutilizável por ser determinístico pelo NCM
- Cálculo é simplificado em relação ao regime normal

**Lucro Real / Lucro Presumido:**
- ICMS: usa CST (2 dígitos)
- PIS/COFINS: calculados normalmente
- DIFAL: aplicável em vendas interestaduais para consumidor final não contribuinte
- Benefícios como redução de base de cálculo são considerados

### 2.4 Diferencial de Alíquota (DIFAL)

O DIFAL é calculado automaticamente quando:
- A operação é interestadual (estados emitente e destinatário diferentes)
- O destinatário é consumidor final não contribuinte do ICMS

O sistema implementa a **base dupla** prevista na LC 190/2022 para produtos com redução de base de cálculo (CST 20), garantindo conformidade com a legislação vigente.

---

## 3. Cadastro de Produto em Detalhes

### 3.1 Dados Cadastrais do Produto

Além das regras tributárias, você pode registrar informações complementares do produto:

**Identificação:**
- **SKU:** código interno do produto na sua empresa (obrigatório)
- **Descrição:** nome/descrição do produto (mínimo 3 caracteres, obrigatório)
- **GTIN:** código de barras EAN/GTIN (quando disponível)
- **Categoria, Unidade de Medida, Preço Unitário**

**Classificação Fiscal:**
- **NCM:** Nomenclatura Comum do Mercosul — 8 dígitos numéricos (obrigatório)
- **CEST:** Código Especificador da Substituição Tributária — 7 dígitos (quando o produto é sujeito à ST)
- **ExTipi:** código EX da TIPI para produtos industrializados com tributação diferenciada
- **Origem:** código de origem da mercadoria (nacional ou estrangeira)

**Detalhes Físicos (opcionais):**
- Peso líquido e bruto
- Dimensões (altura, largura, profundidade)
- Unidade de medida das dimensões

### 3.2 O Que São as Regras Customizadas (`customTax`)

As regras customizadas permitem que você defina, para cada combinação específica de:
- Regime tributário do emitente
- Perfil fiscal do emitente (indústria, comércio, atacado, importador)
- Tipo de destinatário
- Código de operação

...quais valores de ICMS, PIS, COFINS e IPI devem ser usados ao invés do retorno padrão do motor.

**Exemplo de situações onde customTax é útil:**
- Produto com benefício fiscal estadual (ex: redução de base com isenção parcial)
- Produto sujeito a ST onde você precisa informar o ICMS já recolhido anteriormente
- Produto com CST específico acordado com a SEFAZ do seu estado
- Produto com informações adicionais obrigatórias na NF-e

### 3.3 Operações Intraestadual e Interestadual

Para cada regra customizada, você pode definir configurações diferentes para:

- **Intrastate (Intraestadual):** operações onde emitente e destinatário estão no **mesmo estado**. É aqui que geralmente se configura o CST 60 para produtos com ST, por exemplo.
- **Interstate (Interestadual):** operações onde emitente e destinatário estão em **estados diferentes**. As alíquotas e CFOPs interestaduais são diferentes das internas.

É possível informar apenas um dos dois (intraestadual OU interestadual) ou ambos.

### 3.4 Campos ICMS Disponíveis nas Regras Customizadas

| Campo | Descrição |
|---|---|
| `cst` | Código de Situação Tributária (ex: "00", "20", "40", "60") |
| `pICMS` | Alíquota do ICMS (%) |
| `modBC` | Modalidade de determinação da BC |
| `pRedBC` | Percentual de redução da base de cálculo |
| `pFCP` | Percentual do Fundo de Combate à Pobreza |
| `motDesICMS` | Motivo da desoneração do ICMS |
| `indDeduzDeson` | Indica se ICMS desonerado deduz do valor do produto |
| `vBCSTRet` | Valor da BC do ICMS ST retido anteriormente |
| `pST` | Alíquota suportada pelo consumidor final |
| `vICMSSubstituto` | Valor do ICMS próprio do substituto |
| `vICMSSTRet` | Valor do ICMS ST retido anteriormente |
| `vBCFCPSTRet` | Base de cálculo do FCP ST retido anteriormente |
| `pFCPSTRet` | Percentual do FCP ST retido anteriormente |
| `vFCPSTRet` | Valor do FCP ST retido anteriormente |

### 3.5 Campos PIS, COFINS e IPI nas Regras Customizadas

**PIS:**
- `cst` — Código de Situação Tributária do PIS
- `pPIS` — Alíquota do PIS

**COFINS:**
- `cst` — Código de Situação Tributária do COFINS
- `pCOFINS` — Alíquota do COFINS

**IPI:**
- `cst` — Código de Situação Tributária do IPI
- `pIPI` — Alíquota do IPI

---

## 4. Ciclo de Vida do Cadastro de Produto

Após criar ou atualizar um produto, ele passa por um processo automático de validação. Acompanhe o status pelo campo `status` na consulta do produto:

### Status e Significados

| Status | Descrição | O que acontece |
|---|---|---|
| **Pendente de Criação** (`Created`) | Produto recém-criado, aguardando processamento | O sistema inicia automaticamente a validação em segundos |
| **Regras Pendentes** (`CustomTaxPending`) | Regras customizadas sendo validadas | O motor tributário está verificando se as regras fazem sentido para cada cenário fiscal possível. Isso pode levar até 5 horas |
| **Ativo** (`Active`) | Produto validado e pronto para uso | As regras serão aplicadas automaticamente em todas as operações de cálculo |
| **Erro** (`Error`) | Falha na validação | Verifique o campo `errorMessage` para entender o problema. Corrija e recadastre |
| **Inativo** (`Inactive`) | Produto desativado | Não participa do cálculo automático |

### Por Que Demora até 5 Horas?

Quando um produto tem regras customizadas (`customTax`), o sistema precisa:

1. **Identificar todos os cenários fiscais** onde esse produto pode ser vendido (diferentes estados de origem e destino, tipos de destinatários)
2. **Validar cada cenário** consultando o motor tributário — garante que as regras informadas são consistentes com a legislação
3. **Registrar o produto no motor Systax** — cria um vínculo entre o produto e as regras no sistema de cálculo da Systax (parceira tributária)
4. **Aguardar o Systax processar as regras** — o processamento interno do Systax leva aproximadamente 3 horas
5. **Ativar o produto** — após confirmação do Systax, o produto é marcado como Ativo

---

## 5. Notificações via Webhook

Configure um webhook para receber notificações automáticas quando o status de um produto muda:

| Evento | Quando ocorre |
|---|---|
| `product_tax.created_successfully` | Produto foi validado e ativado com sucesso |
| `product_tax.custom_rules_requested` | Regras customizadas identificadas, aguardando processamento Systax |
| `product_tax.creation_failed` | Falha na validação — verifique o errorMessage |

O payload do webhook contém todos os dados do produto, incluindo o status atual e as regras tributárias configuradas.

---

## 6. Regras e Restrições Importantes

### 6.1 Unicidade do Produto

Não podem existir dois produtos com o mesmo **SKU + Origem** dentro da mesma conta. Se tentar criar um produto duplicado, o sistema retorna o ID do produto já existente.

### 6.2 Regras Customizadas Únicas por Cenário

Dentro do `customTax`, cada combinação de `regime do emitente + perfil do emitente + regime do destinatário + perfil do destinatário + código de operação` deve ser única. O sistema valida isso na criação e atualização.

### 6.3 Atualização Completa vs. Parcial

Ao atualizar um produto (`PUT`), você deve enviar **todos os campos** do produto — o sistema substitui o cadastro inteiro. Campos não enviados serão apagados.

Para atualizações pontuais de status ou de vínculos internos, use o `PATCH`.

### 6.4 Impacto de Mudanças Tributárias

Se você atualizar um produto e modificar qualquer informação tributária (NCM, CEST, origem, GTIN ou qualquer campo do `customTax`), o sistema:
1. Invalida automaticamente o registro existente na Systax
2. Reinicia o ciclo de validação do zero
3. O produto voltará ao status `Created` e precisará passar pelo processo de ativação novamente

Atualizações em campos não tributários (descrição, preço, dimensões, etc.) **não** reiniciam o ciclo.

---

## 7. Cálculo de Impostos — Exemplos Práticos

### 7.1 Venda de produto nacional para consumidor final — mesmo estado

**Situação:** Loja em SP vende produto doméstico para consumidor final em SP

**Dados da operação:**
- Emitente: regime Lucro Real, perfil "comércio", estado SP
- Destinatário: consumidor final (não contribuinte), estado SP
- Produto: NCM 64021200 (calçados), origem 0 (nacional), valor R$ 120,00

**O sistema calcula e retorna:**
- CFOP: 5102 (venda de mercadoria adquirida de terceiros — intraestadual)
- ICMS: CST "00", alíquota 12%, vBC R$ 120,00, vICMS R$ 14,40
- PIS: CST "01", alíquota 1,65%, vPIS R$ 1,98
- COFINS: CST "01", alíquota 7,6%, vCOFINS R$ 9,12

### 7.2 Venda interestadual para consumidor final — com DIFAL

**Situação:** Loja em SP vende para consumidor final no RJ

**O sistema calcula e retorna:**
- CFOP: 6102 (venda interestadual)
- ICMS: CST "00", alíquota 12% (interestadual SP→RJ), vICMS R$ 14,40
- DIFAL: pICMSUFDest 20% (interna RJ), pICMSInter 12%, diferença partilhada entre SP e RJ
- PIS/COFINS: calculados normalmente

### 7.3 Venda de produto com Substituição Tributária (produto já com ST retida)

**Situação:** Supermercado em SP vende refrigerante com ICMS-ST já pago pelo distribuidor

**Configuração do produto (customTax):**
- CST intraestadual: "60" (ST cobrado anteriormente)
- vBCSTRet: valor da base usada pelo distribuidor
- vICMSSTRet: ICMS-ST que o distribuidor recolheu

**O sistema retorna:**
- CFOP: 5405 (venda de produto adquirido com ST)
- ICMS: CST "60" com os campos de ST retido preenchidos conforme cadastro do produto
- Nenhum novo ICMS é calculado sobre a venda (já foi recolhido)

### 7.4 Emitente no Simples Nacional

**Situação:** MEI vende produto artesanal para consumidor final

**O sistema retorna:**
- ICMS com CSOSN em vez de CST
- Possível crédito de ICMS para o destinatário (pCredSN, vCredICMSSN)
- PIS/COFINS: CST de isenção (07 ou 08, conforme o produto)

---

## 8. Perfis Fiscais — O Que São e Como Usar

O **perfil fiscal** classifica o tipo de contribuinte dentro do sistema tributário brasileiro, influenciando quais alíquotas e regras se aplicam.

### Perfis do Emitente

| Perfil | Quando usar |
|---|---|
| `trade` (comércio) | Empresas que compram e revendem mercadorias (varejistas, atacadistas) |
| `wholesale` (atacado) | Distribuidores e atacadistas |
| `industry` (indústria) | Fabricantes que produzem mercadorias próprias |
| `wholesale_industry` (atacado + indústria) | Empresas que tanto fabricam quanto distribuem |
| `importer` (importador) | Empresas que importam diretamente do exterior |

> **Atenção:** o perfil deve ser compatível com a origem do produto. Por exemplo, `industry` só é aceito para produtos nacionais (origem 0, 3, 4, 5 ou 8). `importer` é exclusivo para importação direta (origem 1 ou 6).

### Perfis do Destinatário

| Perfil | Quando usar |
|---|---|
| `final_consumer_non_icms_contributor` | Consumidor final que não é contribuinte do ICMS (pessoa física ou empresa não contribuinte) |
| `retail_branch` | Filial varejista da mesma empresa |
| `closed_warehouse` | Depósito fechado (armazém próprio) |

---

## 9. Códigos de Operação — O Que São

O código de operação (`operationCode`) define a **natureza** da operação fiscal. Os mais comuns são:

| Código | Descrição |
|---|---|
| `120` | Venda de produção do próprio estabelecimento (indústria) |
| `121` | Venda de mercadoria adquirida ou recebida de terceiros (comércio) |
| `466` | Devolução de venda |
| `727` | RI — Remessa para industrialização |
| `784` | SRI — Saída de retorno de industrialização |
| `802` | BSRI — Baixa de saída para retorno de industrialização |
| `1108` | Transferência de mercadoria com crédito ICMS (mesmo estado) |
| `2108` | Transferência de mercadoria com crédito ICMS (2 estados) |
| `3108` | Transferência de mercadoria com crédito ICMS (3 ou mais estados) |

Use `/tax-codes/operation-code` para consultar a lista completa com descrições.

---

## 10. Perguntas Frequentes (FAQ)

**Preciso cadastrar todos os produtos para usar o motor de cálculo?**
Não. O motor de cálculo funciona sem cadastro de produto. O cadastro é necessário apenas quando você precisa de regras tributárias customizadas que divergem do padrão calculado pela Systax.

**O que acontece se o produto não for encontrado no cadastro durante o cálculo?**
O sistema calcula normalmente usando apenas o NCM, a origem e os dados da operação — sem aplicar nenhuma customização. O resultado é o retorno padrão da Systax.

**Posso ter regras diferentes para clientes do Simples Nacional e Lucro Real?**
Sim. É exatamente para isso que serve o array `customTax`. Você pode ter várias entradas, cada uma com `issuer.taxRegime` diferente, e o sistema aplica automaticamente a regra correta conforme o regime informado na chamada de cálculo.

**Qual a diferença entre CST e CSOSN?**
- **CST** (2 dígitos): usado por contribuintes fora do Simples Nacional (Lucro Real, Lucro Presumido, MEI em alguns casos)
- **CSOSN** (3 dígitos): Código de Situação da Operação no Simples Nacional — usado por empresas optantes do Simples Nacional

O motor determina automaticamente qual usar com base no `taxRegime` do emitente.

**Meu produto tem benefício fiscal com redução de base de cálculo. Como configurar?**
Use o campo `pRedBC` no `customTax.intrastate.icms` e/ou `customTax.interstate.icms`. Informe o percentual de redução (ex: `"40.00"` para 40% de redução). O sistema recalcula a base e o valor do ICMS automaticamente.

**O DIFAL é calculado automaticamente?**
Sim. Para operações interestaduais destinadas a consumidor final não contribuinte, o DIFAL é calculado automaticamente e retornado no campo `icmsUfDest` do response. Você não precisa configurar nada extra.

**Quanto tempo demora para ativar um produto com regras customizadas?**
O processo completo leva entre 3 e 5 horas. Isso ocorre porque o sistema precisa registrar o produto na Systax e aguardar o processamento das regras. Você receberá um webhook quando o produto for ativado.

**Posso usar os campos de ICMS ST retido (`vBCSTRet`, `vICMSSTRet`, etc.) sem ser CST 60?**
Tecnicamente sim — o sistema aceita os campos em qualquer configuração. Porém, eles são semanticamente aplicáveis ao CST 60 (ICMS cobrado anteriormente por ST) e ao CSOSN 500 (Simples Nacional com ST). Para outros CSTs, consulte sua assessoria fiscal.

**O que é a Systax?**
A Systax é a parceira da NFE.io para o motor de cálculo tributário. É uma empresa especializada em dados e regras tributárias brasileiras que mantém uma base de dados atualizada com todas as legislações estaduais e federais. A NFE.io orquestra a comunicação com a Systax e aplica as customizações do seu cadastro de produto sobre o resultado dela.

**Se a Systax ficar indisponível, minha emissão de NF-e para?**
Não. O sistema mantém um cache dos últimos cálculos realizados. Em caso de indisponibilidade temporária da Systax, o cache é utilizado como fallback para garantir continuidade operacional. O cache é automaticamente revalidado quando a Systax volta ao ar.

**Posso atualizar o `customTax` sem reiniciar o ciclo de validação?**
Não. Qualquer alteração em `customTax` (ou nos campos tributários `ncm`, `cest`, `origin`, `gtin`) reinicia o ciclo completo de validação. Isso é necessário para garantir que as novas regras sejam devidamente registradas e validadas na Systax.

---

## 11. Glossário

| Termo | Significado |
|---|---|
| **NCM** | Nomenclatura Comum do Mercosul — código de 8 dígitos que classifica todos os produtos para fins fiscais e aduaneiros |
| **CEST** | Código Especificador da Substituição Tributária — código de 7 dígitos que identifica mercadorias sujeitas à ST |
| **CST** | Código de Situação Tributária do ICMS — 2 dígitos para empresas fora do Simples Nacional |
| **CSOSN** | Código de Situação da Operação no Simples Nacional — 3 dígitos para optantes do Simples |
| **CFOP** | Código Fiscal de Operações e Prestações — código de 4 dígitos que define a natureza da operação (venda, devolução, transferência...) |
| **DIFAL** | Diferencial de Alíquota — imposto sobre a diferença entre a alíquota interna do estado de destino e a alíquota interestadual, em operações para consumidor final |
| **FCP** | Fundo de Combate à Pobreza — adicional de até 2% do ICMS cobrado em alguns estados para determinados produtos |
| **Substituição Tributária (ST)** | Regime onde um contribuinte anterior na cadeia (substituto) recolhe o ICMS por todos os que virão depois |
| **CustomTax** | Regra tributária customizada cadastrada no produto, que sobrepõe o resultado padrão do motor |
| **Systax** | Motor de cálculo tributário parceiro da NFE.io, especializado em dados fiscais brasileiros |
| **TaxRegime** | Regime tributário do contribuinte (Simples Nacional, Lucro Real, Lucro Presumido, MEI...) |
| **TaxProfile** | Perfil fiscal do contribuinte (comércio, indústria, atacado, importador...) |
| **OperationCode** | Código interno da NFE.io que define a natureza da operação fiscal |
| **SKU** | Stock Keeping Unit — código interno do produto na empresa |
| **CollectionId** | Identificador de uma coleção/empresa dentro de uma conta NFE.io — usado para organizar e separar produtos de diferentes CNPJs |

---

## Cadastro de produtos - Inteligência Tributária

Source: https://nfe.io/docs/inteligencia-tributaria/cadastro-de-produto/index.md

# Documentação Funcional: API de Cadastro de Produtos e Customização Tributária

## Visão Geral
Esta API permite o cadastro e atualização de produtos, incluindo suas classificações fiscais básicas (NCM, CEST) e, principalmente, a definição de cenários tributários customizados (`customTax`).

O recurso de `customTax` é fundamental para flexibilidade fiscal: ele permite que o usuário defina regras específicas que **sobrescrevem** o cálculo automático do motor de impostos. Se um campo for informado dentro de um cenário de `customTax`, esse valor será utilizado prioritariamente na emissão da nota fiscal para aquele produto, naquele cenário específico, atuando como um valor "default" ou forçado.

## Modelo de Utilização do Motor de Cálculo

Para garantir o sucesso da sua integração e na utilização da nossa API, é importante alinhar o modelo de utilização do motor de cálculo. Atualmente, oferecemos dois cenários principais:

### 1. Utilização de Regras Padrão (Standard)

Neste cenário, você utiliza a inteligência tributária nativa do nosso motor.

- **Ação:** Não é necessário realizar o cadastro prévio de produtos.
- **Integração:** Basta enviar as propriedades perfeitamente preenchidas no grupo `TaxDetermination` via API. Com base nesses dados, o sistema processa e monta automaticamente o grupo Tax com os impostos do item.

### 2. Regras Customizadas

Indicado caso a sua operação possua particularidades fiscais ou benefícios específicos que fogem à regra geral.

- **Ação:** É necessário realizar o cadastro do produto e a configuração de cenários customizados.
- **Análise Necessária:** Nossa equipe de atendimento precisará validar se a customização desejada já existe em nossa base ou se será necessário desenvolver um novo cenário.

**Informações necessárias para o Onboarding:**

Para definir quais campos serão utilizados na configuração de regras customizadas, é fundamental mapear as seguintes variáveis do seu negócio:

- **Natureza das Operações:** Venda, transferência, entrada, simples remessa, etc.
- **Perfil dos Envolvidos:** Regime tributário, localização do emitente e do destinatário, entre outras características.
- **Especificidades do Produto:** NCM, tipo de item e a definição exata da regra que se deseja customizar.

Para garantir agilidade na configuração e na análise do seu cenário, pedimos que encaminhe ao nosso suporte as respostas do questionário de onboarding abaixo. Ele está dividido no contexto geral da sua operação e nas especificidades da regra customizada:

#### Parte 1: Perfil da Empresa (Contexto Geral)
Este mapeamento é feito apenas uma vez para entendermos o seu negócio.
1. **Atuação:** Possui operação e venda no território nacional de produtos/mercadorias? Realiza operações com múltiplos produtos?
2. **Segmento e Perfil:** Qual seu segmento de atuação (ex: Bebidas, eCommerce) e perfil do emitente (ex: Indústria, Varejista, Atacadista)?
3. **Regime Tributário:** Qual o regime de operação da empresa emitente? *(Lucro Real, Lucro Presumido ou Simples Nacional)*
4. **Volume e Abrangência:**
   - Qual a volumetria mensal de NF-es e média de itens por nota?
   - Em quais estados (UFs) sua empresa possui matriz/filiais e quais os principais estados de destino das vendas?
   - Quantos NCMs diferentes costuma operar e quais os principais capítulos?
5. **Operações Frequentes:** No seu dia a dia, quais operações são mais comuns? *(Ex: Venda, Revenda, Devolução, Transferência, etc.)*
6. **Automação e Particularidades:** Existe algum processo automatizado para os cálculos hoje? Sua empresa possui operações com regimes especiais (benefícios, isenções específicas do Estado)?

#### Parte 2: Mapeamento da Regra Customizada (Cenário Específico)
Para **cada regra customizada** que você precisar criar no nosso motor (para atender os regimes especiais ou particularidades citadas no item 6 da Parte 1), precisaremos das informações pontuais abaixo:
1. **Operação Alvo:** Dentre as operações que sua empresa realiza, para qual delas esta regra específica será aplicada? *(Ex: Somente para Transferência entre filiais)*
2. **CFOP Esperado:** Qual é o CFOP de saída exato que deseja para esta regra?
3. **CST de ICMS Esperado:** Qual o CST do ICMS que deve ser forçado/aplicado?
4. **UF Origem vs. UF Destino da Regra:** Em qual cruzamento de estados essa regra deve ser disparada? *(Ex: Somente saídas de SP para RJ)*
5. **Origem da Mercadoria:** Essa regra se aplica a produtos com qual origem? *(Ex: Somente Importados)*
6. **Classificação Fiscal (NCMs Afetados):** Quais são os NCMs exatos que devem obedecer a esta regra específica?
7. **Escopo da Customização:** A intenção é customizar apenas os valores de ICMS ou também outros impostos (PIS, COFINS)?

## Estrutura do Produto (`ProductInput`)

O objeto principal de entrada para cadastro/atualização contém os seguintes campos:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `tenantId` | String | Sim | Identificador do Tenant (AccountId do Marketplace). |
| `collectionId` | String | Sim | Identificador da coleção (CompanyId do Seller) para isolar o produto. |
| `sku` | String | Sim | Código único de identificação do produto (SKU). |
| `origin` | Enum | Sim | Origem da mercadoria (ex: `national`, `foreignDirectImport`). Ver tabela de Origem. |
| `description` | String | Sim | Descrição detalhada do produto. |
| `gtin` | String | Não | GTIN (EAN) do produto. |
| `taxGtin` | String | Não | GTIN da unidade tributável. |
| `tax.ncm` | String | Sim | Código NCM (8 dígitos) ou Gênero (2 dígitos). |
| `tax.cest` | String | Não | Código CEST. |
| `customTax` | Array | Sim | Lista de cenários tributários customizados. |

### Valores de Origem (`origin`)
- `national`: Nacional
- `foreignDirectImport`: Estrangeira - Importação direta
- `foreignInternalMarket`: Estrangeira - Adquirida no mercado interno
- `nationalWith40To70Import`: Nacional, mercadoria ou bem com Conteúdo de Importação superior a 40% e inferior ou igual a 70%
- `nationalPpb`: Nacional, cuja produção tenha sido feita em conformidade com os processos produtivos básicos
- `nationalWithLess40Import`: Nacional, mercadoria ou bem com Conteúdo de Importação inferior ou igual a 40%
- `foreignDirectImportWithoutNationalSimilar`: Estrangeira - Importação direta, sem similar nacional
- `foreignInternalMarketWithoutNationalSimilar`: Estrangeira - Adquirida no mercado interno, sem similar nacional
- `nationalWithGreater70Import`: Nacional, mercadoria ou bem com Conteúdo de Importação superior a 70%

## Customização de Regras Tributárias (`customTax`)

O array `customTax` permite definir regras específicas baseadas no perfil do emitente (`issuer`) e do destinatário (`recipient`).

### Como funciona o "Match" do Cenário
Para que uma regra customizada seja aplicada, o sistema verifica se a operação sendo realizada corresponde aos critérios definidos no cenário:
1.  **Emitente (`issuer`)**: O Regime Tributário (`taxRegime`) e o Perfil Tributário (`taxProfile`) do emitente da nota correspondem à lista fornecida?
2.  **Destinatário (`recipient`)**: O Perfil Tributário (`taxProfile`) do destinatário corresponde à lista fornecida?
3.  **Operação (`OperationCode`)**: O código da operação corresponde?
4.  **Origem (`origin`)**: A origem da mercadoria corresponde?

Se houver correspondência, os valores definidos em `intraState` (operações internas/estaduais) ou `interState` (operações interestaduais) serão utilizados para preencher a nota fiscal.

### Grupos de Impostos (`intraState` / `interState`)
Dentro de cada grupo (interno ou interestadual), é possível customizar:
-   `cfop`: Código Fiscal de Operações e Prestações.
-   `icms`: Grupo de ICMS.
-   `pis`: Grupo de PIS.
-   `cofins`: Grupo de COFINS.

## Interação com a Emissão da Nota (`taxDetermination`)

Para que o motor de cálculo utilize as regras definidas no `customTax` do produto, é necessário enviar o grupo `taxDetermination` na requisição de emissão da nota fiscal (endpoint de emissão).

Este grupo fornece os parâmetros de contexto que o sistema utiliza para buscar a regra correspondente no cadastro do produto:

*   **`operationCode`**: Corresponde ao `OperationCode` cadastrado na regra.
*   **`issuerTaxProfile`**: Corresponde ao `taxProfile` do emitente (`issuer`) na regra.
*   **`buyerTaxProfile`**: Corresponde ao `taxProfile` do destinatário (`recipient`) na regra.
*   **`origin`**: Corresponde à origem da mercadoria.

**Exemplo de `taxDetermination` na emissão:**

```json
"taxDetermination": {
  "operationCode": 1,
  "origin": "0",
  "issuerTaxProfile": "retail",
  "buyerTaxProfile": "final_consumer_non_icms_contributor"
}
```

---

## Customização do ICMS (`customTax.intraState.icms`)

Este grupo é utilizado para definir valores fixos ou regras específicas para o ICMS. **Qualquer valor informado aqui terá precedência sobre o cálculo automático.** Isso permite, por exemplo, fixar uma alíquota reduzida ou uma base de cálculo específica que o motor genérico não contemplaria.

### Campos Disponíveis

| Campo | Descrição | Tag SEFAZ |
|---|---|---|
| `cst` | Código da Situação Tributária do ICMS (ex: 00, 20, 60). | CST |
| `modBC` | Modalidade de determinação da Base de Cálculo do ICMS. | modBC |
| `pICMS` | Alíquota do ICMS (%). | pICMS |
| `pRedBC` | Percentual de redução da Base de Cálculo do ICMS. | pRedBC |
| `modBCST` | Modalidade de determinação da BC do ICMS ST. | modBCST |
| `pMVAST` | Percentual da Margem de Valor Adicionado ICMS ST. | pMVAST |
| `pRedBCST` | Percentual de redução da BC do ICMS ST. | pRedBCST |
| `pICMSST` | Alíquota do ICMS ST (%). | pICMSST |
| `motDesICMS` | Motivo da desoneração do ICMS. | motDesICMS |
| `pFCP` | Percentual do Fundo de Combate à Pobreza (FCP). | pFCP |
| `pDif` | Percentual de Diferimento. | pDif |
| ... | (Outros campos conforme schema) | |

### Guia de Preenchimento: Customizando CST 20 (Redução de Base de Cálculo)

O CST 20 ("Com redução de base de cálculo") é utilizado quando a operação é tributada, mas existe um benefício fiscal que reduz a base sobre a qual o imposto é calculado.

Para configurar este cenário corretamente no grupo `customTax.intraState.icms` (ou `interState`), preencha os seguintes campos obrigatórios para a regra:

1.  **`cst`**: Deve ser preenchido com o valor **"20"**.
2.  **`modBC`**: Informe a modalidade de determinação da base. Geralmente utiliza-se **"3"** (Valor da operação).
3.  **`pRedBC`**: Informe o **percentual de redução** que deve ser aplicado à base.
    *   *Exemplo:* Se a base deve ser reduzida em 20%, informe "20.00".
4.  **`pICMS`**: Informe a **alíquota do ICMS** aplicável à operação (alíquota cheia, antes da redução da base).
5.  **`pFCP`**: Informe o **percentual do FCP** (Fundo de Combate à Pobreza) aplicável à operação.

**Exemplo de objeto `icms` para CST 20:**
```json
"icms": {
  "cst": "20",
  "modBC": "3",
  "pRedBC": "41.67",  // Exemplo: Redução de 41.67% na base
  "pICMS": "18.00",   // Alíquota de 18%
  "pFCP": "2.00"      // Alíquota de 2% do FCP
}
```

---

## Exemplo Completo de Requisição (JSON)

Abaixo, um exemplo de cadastro de produto com uma regra customizada para CST 20 em operações estaduais (Intrastate) para um emitente do Lucro Real vendendo para Consumidor Final.

```json
{
  "tenantId": "ACCOUNT-123",
  "collectionId": "COMPANY-456",
  "sku": "PROD-001",
  "origin": "national",
  "description": "Produto Exemplo com Redução de Base",
  "gtin": "7891234567890",
  "tax": {
    "ncm": "94036000",
    "cest": "2806100"
  },
  "customTax": [
    {
      "OperationCode": 1,
      "issuer": [
        {
          "taxRegime": "RealProfit",
          "taxProfile": "retail"
        }
      ],
      "recipient": [
        {
          "taxProfile": "final_consumer_non_icms_contributor"
        }
      ],
      "intraState": {
        "cfop": 5102,
        "icms": {
          "cst": "20",
          "modBC": "3",
          "pRedBC": "33.33",
          "pICMS": "18.00"
        },
        "pis": {
          "cst": "01",
          "pPIS": "1.65"
        },
        "cofins": {
          "cst": "01",
          "pCOFINS": "7.60"
        }
      }
    }
  ]
}
```

### Nota Importante: CST 60 (ICMS Cobrado Anteriormente por Substituição Tributária) 

Para operações com CST 60, existem informações referentes à retenção do imposto na fase anterior (pelo substituto tributário) que são variáveis a cada lote de compra e, portanto, não devem ser cadastradas no produto (via customTax). 

Esses dados são específicos da transação e devem ser enviados diretamente na integração da Nota Fiscal (endpoint de emissão), dentro do objeto items[].tax.icms. 

Campos que devem ser enviados na emissão da NF-e (e não no cadastro): 

* **baseSTRetentionAmount (vBCSTRet):** Valor da BC do ICMS ST retido na operação anterior.
* **stRetentionAmount (vICMSSTRet):** Valor do ICMS ST retido na operação anterior.
* **substituteAmount (vICMSSubstituto):** Valor do ICMS próprio do substituto.
* **stFinalConsumerRate (pST):** Alíquota suportada pelo consumidor final.
* **fcpstRetAmount (vFCPSTRet):** Valor do FCP retido anteriormente por ST.
* **fcpstRetRate (pFCPSTRet):** Percentual do FCP retido anteriormente por ST.

Exemplo de JSON na emissão da NF-e (CST 60):
```json
  ...
  "taxDetermination": {
      "operationCode": 121,
      "origin": "0",
      "issuerTaxProfile": "retail",
      "buyerTaxProfile": "final_consumer_non_icms_contributor",
      "acquisitionPurpose": null
  },
  "tax": {
      "icms": {
          "BaseSTRetentionAmount": "10.00",
          "STFinalConsumerRate": 18.00,
          "SubstituteAmount": 10.00,
          "STRetentionAmount": "10.00"
      }
  }
  ...
```

---

## Introdução

Source: https://nfe.io/docs/documentacao/index.md

# Introdução

Seja bem vindo à nossa documentação. Criamos este conteúdo para que você consiga aprender tudo o que é necessário para utilizar qualquer uma de nossas API’s.

Nossa ideia com essa seção de nosso site é oferecer algo dinâmico. Por isso, se tiver sugestões, entre em contato conosco pelo: suporte@nfe.io.

A partir de agora, apresentaremos conceitos básicos sobre Notas Fiscais, CPF, CNPJ, entre outros. Por meio desses conceitos você poderá decidir qual das nossas API’s se encaixa com o seu negócio.

## O que é uma API?

API é uma sigla em inglês para Aplication Program Interface, que traduzido seria “Interface de Programação de Aplicações”. Mas o que isso significa?

Basicamente, API é um conjunto de padrões de programação estabelecidos por um software para a utilização das suas funcionalidades por outros aplicativos que pretendem usar seus serviços. Com isso, torna-se possível que dois aplicativos conversem entre si.

Um exemplo muito comum é a integração de e-commerce com meios de pagamento (PagSeguro, por exemplo). Você já deve ter efetuado uma compra em um site e no momento da compra ser direcionado para um ambiente diferente para deixar os dados do cartão de crédito, por exemplo, e efetuar seu pagamento. Essa integração entre o site que vendeu o produto e a plataforma onde ocorreu o pagamento funcona através de API´s.

Nossas API’s foram criadas utilizando o padrão REST, o que possibilita a integração de seu sistema ao nosso.

## Conheça nossas APIs

### Consultar dados de Pessoa Jurídica

Nessa consulta nossa API retornará os dados de uma Pessoas Jurídica através de um CNPJ, confira os dados que a gente pega. Possuímos diversas fontes de busca para puxar os dados e retorná-los de maneira bem organizada, acesse nossa documentação para conhecer melhor.

### Consultar dados de Pessoa Física

Essa API retornará os dados de uma Pessoa Física a partir de um CPF. Assim você pode ter acesso a situação cadastral de uma pessoa física, clique aqui para acessar nossa documentação.

### Consultar dados de endereços

Nossa API de endereços retornará os dados de endereço a partir de um CEP. Nós também disponibilizamos outras formas de fazer essa consulta, clique aqui para acessar nossa documentação.

### Consultar de Notas Fiscais Eletrônicas (NF-e)

Nessa consulta nossa API retorna os dados de uma NF-e (em diferentes formatos de arquivos) a partir da chave de acesso da nota. Conheça a documentação da API.

### Emissão Automática de Nota Fiscal de Serviço (NFS-e)

Com a nossa API é possivel emitir notas fiscais de serviço de forma automatizada. Além do calculo automático de impostos, nosso sistema possui diversas funcionalidades como, envio automático de email com a nota emitida para o seu cliente, cancelamento de notas, consulta de pdf ou xml, dentre outros. Clique aqui e confira nossa documentação.

Nós possuímos integração com as principais plataformas de pagamento, caso tenha interesse clique aqui e veja qual a melhor solução para você. Além disso, é possível integrar nossa API com outros sistemas através de plugins, clique aqui e saiba mais sobre nossos plugins.

### Emissão Automática de Nota Fiscal de Produtos (NF-e)

Temos também uma API para emitir NFe de Produtos, que nesse momento está em BETA e estamos disponibilizando nossa API para quem deseja integrar em seu sistema. Como ela está em BETA, o uso dela é sem custos, por tempo indeterminado, e quem tem interesse em desenvolver uma integração pode começar agora, olhando nossa documentação.

## Contato
Possui alguma dúvida ou sugestão? Entre contato conosco através do email suporte@nfe.io., ou por telefone (11) 4063-8091 se preferir. Estaremos a disposição para melhor atendê-lo.

---

## Como alterar uma empresa no painel da NFE.io

Source: https://nfe.io/docs/documentacao/nossa-plataforma/alterar-empresa/index.md

# Alterar Empresa

Ao final desse tutorial você será capaz de **alterar os dados de uma empresa** pelo painel centralizado da NFE.io.

**Requisitos**

- [Criar uma conta](./criar-conta.md)
- [Criar uma empresa](./criar-empresa.md)

:::info
Desde o release **2026.2**, todas as configurações da empresa ficam reunidas em um único painel acessível por [app.nfe.io/companies](https://app.nfe.io/companies). O endereço antigo `/companies-v2` foi descontinuado e redireciona automaticamente para o novo. Não é necessária nenhuma ação da sua parte.
:::

## 1. Abrir o painel da empresa

No menu lateral, clique em **Empresas** e selecione a empresa que deseja alterar. Você será levado para a tela **Gerenciamento da empresa**, que reúne todos os cards de configuração em um único lugar:

- **Informações da empresa** — dados cadastrais (CNPJ, Razão Social, endereço)
- **Certificado Digital** — status, validade e ação de upload/substituição
- **Inscrições Estaduais (IE)** — para emissão de NF-e e NFC-e
- **Inscrição Municipal (IM)** — para emissão de NFS-e
- **Lista de serviços cadastrados** e **CT-e distribuição** (quando aplicável)

![Painel de Gerenciamento da empresa](https://nfe.io/docs/static/docs/plataforma/criar-empresa/7-empresa-criada.png)

:::tip
Cada card pode ser aberto diretamente para edição, sem passar pelo menu **Ações** no topo. O menu Ações concentra atalhos para operações além do cadastro (emissão em lote, listagem de notas, etc.).
:::

## 2. Alterar dados cadastrais

Clique no card **Informações da empresa** (ou em **Ações → Alterar Empresa**, no topo da página). Os campos editáveis são os mesmos da [Etapa 1 do wizard de criação](./criar-empresa.md#etapa-1-dados-básicos-da-empresa):

**Dados da Empresa**

- **Razão Social** e **Nome Fantasia**
- **Regime Tributário** (Simples Nacional, Lucro Presumido, Lucro Real, MEI ou Isento)

**Dados do Endereço**

- **CEP**, **Logradouro**, **Número**, **Complemento** (opcional), **Bairro**, **Estado**, **Cidade**

> O **CNPJ** não pode ser alterado após a criação — para trocar o CNPJ é necessário cadastrar uma nova empresa.

![Formulário de Alterar Empresa — dados básicos](https://nfe.io/docs/static/docs/plataforma/criar-empresa/2-dados-basicos-empresa.png)

:::info Ambiente é por inscrição, não da empresa
A definição de **Produção** ou **Homologação/Testes** é feita em cada Inscrição (IE ou IM) individualmente, não no nível da empresa. Veja as seções abaixo.
:::

## 3. Certificado Digital

O card **Certificado Digital** mostra o estado atual do certificado vinculado à empresa: **Status**, **Válido até** e **Atualizado há**. Clique nele para abrir o painel de upload e fazer envio ou substituição do certificado A1 (`.pfx` ou `.p12`).

O CNPJ do certificado precisa coincidir com o CNPJ da empresa. Em ambiente de **homologação**, o certificado é opcional; em **produção** é necessário para emissão de notas reais.

![Painel de upload do Certificado Digital](https://nfe.io/docs/static/docs/plataforma/criar-empresa/5-incluir-certificado.png)

Para o passo a passo completo, consulte [Fazer upload do certificado digital](./upload-do-certificado-digital.md).

## 4. Inscrição Estadual (IE)

O card de **Inscrição Estadual** mostra a IE ativa da empresa. O comportamento ao clicar depende de quantas inscrições estão cadastradas:

- Com **apenas uma IE**, o clique leva direto à edição daquela inscrição.
- Com **mais de uma IE**, o clique abre a **lista completa**, com botão **Nova Inscrição Estadual** para cadastrar uma nova.

![Card de Inscrição Estadual no painel da empresa](https://nfe.io/docs/static/docs/release-2026-2/card-inscricao-estadual.png)

**Campos editáveis em cada IE:**

- **Tipo** — NF-e ou NFC-e
- **UF** — estado da inscrição
- **Inscrição Estadual** — número junto à SEFAZ
- **Série** — série padrão usada na emissão
- **Credenciais** — quando exigidas pelo estado (por exemplo, **CSC** para NFC-e)
- **Ambiente** — Produção ou Homologação

Para o passo a passo completo, consulte [Alterar Inscrição Estadual](./alterar-inscricao-estadual.md) ou [Criar Inscrição Estadual](./criar-inscricao-estadual.md) para uma nova UF.

## 5. Inscrição Municipal (IM)

O card de **Inscrição Municipal** mostra a IM cadastrada para a empresa. O clique abre o formulário de cadastro (quando ainda não há IM) ou a edição (quando já existe uma).

![Card de Inscrição Municipal no painel da empresa](https://nfe.io/docs/static/docs/release-2026-2/card-inscricao-municipal.png)

**Campos editáveis na IM:**

- **UF** e **Cidade**
- **Inscrição Municipal** — número junto à prefeitura
- **Regime Especial de Tributação**
- **E-mail** — para notificações da prefeitura
- **Série do RPS**, **Número do RPS** e **Último RPS Enviado** (somente leitura)
- **Credenciais** — login e senha exigidos por algumas prefeituras
- **Alíquota de ISS** — apenas para Simples Nacional
- **Ambiente** — Produção ou Testes

Para o passo a passo completo, consulte [Cadastrar a Inscrição Municipal](./criar-inscricao-municipal.md) ou [Alterar a Inscrição Municipal](./alterar-inscricao-municipal.md).

## Próximos passos

- [Fazer upload do certificado digital](./upload-do-certificado-digital.md)
- [Alterar Inscrição Estadual](./alterar-inscricao-estadual.md) | [Criar Inscrição Estadual](./criar-inscricao-estadual.md)
- [Alterar Inscrição Municipal](./alterar-inscricao-municipal.md) | [Criar Inscrição Municipal](./criar-inscricao-municipal.md)
- [Emitir NFS-e em lote](./nota-fiscal-servico/emitir-nota-fiscal-de-servico-em-lote.md)
- [Listar notas fiscais de serviço](./nota-fiscal-servico/listar-notas-fiscais-de-servico.md)

---

## Alterar Inscrição Estadual no painel da empresa | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/alterar-inscricao-estadual/index.md

# Alterar Inscrição Estadual

Esta página descreve como **editar** uma Inscrição Estadual já cadastrada — atualizar credenciais, mudar série/numeração ou trocar o ambiente entre Produção e Homologação.

**Requisitos**

- [Criar uma conta](./criar-conta.md)
- [Criar uma empresa](./criar-empresa.md)
- [Cadastrar uma Inscrição Estadual](./criar-inscricao-estadual.md)

## Abrir o card de Inscrição Estadual

No painel da empresa em [app.nfe.io/companies](https://app.nfe.io/companies), localize o card **Inscrição Estadual**:

- Com **uma IE cadastrada**, o clique leva direto para a edição daquela inscrição
- Com **mais de uma IE**, o clique abre a lista completa

![Card de Inscrição Estadual no painel da empresa](https://nfe.io/docs/static/docs/release-2026-2/card-inscricao-estadual.png)

## Listar Inscrições Estaduais

A lista mostra todas as IEs cadastradas para a empresa, com as colunas:

- **Tipo** — NF-e ou NFC-e
- **UF** — estado da inscrição
- **Inscrição** — número da IE
- **Série** — série padrão usada na emissão
- **Ambiente** — Produção ou Homologação
- **Status** — situação atual da inscrição

Clique em qualquer linha para abrir a edição. Para cadastrar uma nova IE, clique em **Nova Inscrição Estadual** (veja [Criar Inscrição Estadual](./criar-inscricao-estadual.md)).

## Editar uma Inscrição Estadual

Abra a IE pela lista (ou pelo card, quando houver apenas uma) e ajuste os campos necessários:

- **Atualizar credenciais** — por exemplo, ao gerar novo CSC para NFC-e
- **Série ou próximo número** — quando precisar reajustar a numeração
- **Regime Especial de Tributação**
- **Ambiente** — alternar entre Produção e Homologação

:::tip Troca de ambiente
A troca entre **Produção** e **Homologação** é confirmada por uma caixa de diálogo. Notas emitidas em Homologação **não têm validade fiscal**. Use esse ambiente apenas para testes.
:::

## Próximos passos

- [Cadastrar Inscrição Estadual](./criar-inscricao-estadual.md) — adicionar uma IE em outra UF
- [Alterar Inscrição Municipal](./alterar-inscricao-municipal.md)
- [Alterar dados da empresa](./alterar-empresa.md)
- [API de Inscrições Estaduais (referência técnica)](../gerenciamento-empresas/gerenciamento-inscricao-estadual.md)

---

## Alterar Inscrição Municipal no painel da empresa | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/alterar-inscricao-municipal/index.md

# Alterar Inscrição Municipal

Esta página descreve como **editar** a Inscrição Municipal já cadastrada — atualizar credenciais da prefeitura, corrigir série/numeração do RPS, trocar regime especial ou alternar entre Produção e Testes.

**Requisitos**

- [Criar uma conta](./criar-conta.md)
- [Criar uma empresa](./criar-empresa.md)
- [Cadastrar uma Inscrição Municipal](./criar-inscricao-municipal.md)

## Abrir o card de Inscrição Municipal

No painel da empresa em [app.nfe.io/companies](https://app.nfe.io/companies), localize o card **Inscrição Municipal**. O clique abre direto a edição da IM cadastrada.

![Card de Inscrição Municipal no painel da empresa](https://nfe.io/docs/static/docs/release-2026-2/card-inscricao-municipal.png)

## Editar a Inscrição Municipal

Abra o card **Inscrição Municipal** e ajuste os campos necessários:

- **Credenciais da Prefeitura** — quando a prefeitura exigir nova senha
- **Série do RPS ou próximo número** — quando precisar reajustar a numeração
- **Regime Especial de Tributação** ou **Alíquota ISS**
- **Ambiente** — alternar entre Produção e Testes

:::tip Troca de ambiente
A troca entre **Produção** e **Testes** pede confirmação adicional. Notas emitidas em Testes **não têm validade fiscal**.
:::

## Próximos passos

- [Cadastrar Inscrição Municipal](./criar-inscricao-municipal.md) — cadastrar a IM da empresa
- [Alterar Inscrição Estadual](./alterar-inscricao-estadual.md)
- [Alterar dados da empresa](./alterar-empresa.md)
- [API de Inscrições Municipais (referência técnica)](../gerenciamento-empresas/gerenciamento-inscricao-municipal.md)

---

## Chaves de autenticação (API Keys)

Source: https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/index.md

# Acessar chave de autenticação na plataforma

Para utilizar as APIs oferecidas pela [NFE.io][4] você precisará usar as chaves de autenticação disponibilizadas no momento da criação da conta.

:::tip Resumo Rápido

**Existem DUAS chaves diferentes com propósitos específicos:**

- **Chave de Dados** → Para **consultar** informações (CNPJ, CPF, CEP, notas emitidas)
- **Chave de Nota Fiscal** → Para **emitir** notas fiscais e gerenciar empresas

**Regra simples:** Precisa consultar dados? Use a Chave de Dados. Precisa emitir nota fiscal? Use a Chave de Nota Fiscal.

:::

**Ao final desse tutorial, você será capaz de:**

* [Identificar as chaves de acesso disponíveis](#1-menu-conta)
* [Entender a diferença entre as chaves](#3-entendendo-as-duas-chaves)
* [Saber quando usar cada chave](#4-quando-usar-cada-chave)
* [Evitar erros comuns de autenticação](#6-erros-comuns-e-soluções)

**Requisitos**  
[Criar uma conta][7]

## 1) Menu conta

1- Clique no menu **CONTA** e aparecerá todas as chaves disponíveis.

![](https://nfe.io/docs/static/docs/plataforma/account-page.png)

2- Clique na opção **CHAVE DE ACESSO**

![](https://nfe.io/docs/static/docs/plataforma/access-key-option.png)

## 2) Chaves disponíveis

Nesta tela, você verá **duas chaves diferentes**:

![](https://nfe.io/docs/static/docs/plataforma/access-key.png)

:::warning Atenção

**Cada chave tem uma finalidade específica.** Usar a chave errada resultará em erro 401 (Não autorizado). Continue lendo para entender quando usar cada uma.

:::

## 3) Entendendo as duas chaves

### 🔍 Chave de Dados (Data Key)

**Propósito:** Consultar informações e dados cadastrais.

Esta chave permite que você faça **consultas** (somente leitura) de:

- ✅ **CNPJ** - Dados cadastrais de empresas na Receita Federal
- ✅ **CPF** - Status e validação de CPF
- ✅ **CEP** - Consulta de endereços
- ✅ **Simples Nacional** - Regime tributário de empresas
- ✅ **Notas Fiscais já emitidas** - Consultar NFe/NFCe por chave de acesso

**Base URLs que usam esta chave:**
- `legalentity.api.nfe.io` - Consultas de CNPJ
- `naturalperson.api.nfe.io` - Consultas de CPF
- `address.api.nfe.io` - Consultas de CEP
- `nfe.api.nfe.io` - Consultas de notas fiscais

**Exemplo de uso:**
```bash
curl -X GET "https://legalentity.api.nfe.io/v1/legalentities/basicInfo/12345678000195" \
  -H "Authorization: SUA_CHAVE_DE_DADOS"
```

### 📝 Chave de Nota Fiscal (Invoice Key)

**Propósito:** Emitir e gerenciar notas fiscais.

Esta chave permite que você **emita notas e gerencie** sua operação fiscal:

- ✅ **Emitir NFS-e** - Nota Fiscal de Serviço Eletrônica
- ✅ **Emitir NF-e** - Nota Fiscal de Produto Eletrônica (modelo 55)
- ✅ **Emitir NFC-e** - Nota Fiscal de Consumidor Eletrônica (modelo 65)
- ✅ **Criar empresas** - Cadastrar empresas na plataforma
- ✅ **Gerenciar certificados** - Upload de certificados digitais
- ✅ **Cancelar notas** - Cancelamento de documentos fiscais
- ✅ **Enviar emails** - Envio de PDF/XML para clientes
- ✅ **Webhooks** - Configurar notificações de eventos

**Base URLs que usam esta chave:**
- `api.nfe.io` - NFS-e (Nota de Serviço)
- `api.nfse.io` - NF-e e NFC-e (Produto e Consumidor)

**Exemplo de uso:**
```bash
curl -X POST "https://api.nfe.io/v2/companies/ID_EMPRESA/serviceinvoices" \
  -H "Authorization: SUA_CHAVE_DE_NOTA_FISCAL" \
  -H "Content-Type: application/json" \
  -d '{"borrower": {...}, "services": [...]}'
```

## 4) Quando usar cada chave

### Tabela Comparativa

| Característica | 🔍 Chave de Dados | 📝 Chave de Nota Fiscal |
|---|---|---|
| **Propósito** | Consultas (somente leitura) | Emissão e gestão fiscal |
| **Operações** | Consultar CNPJ, CPF, CEP, notas | Emitir notas, criar empresas, cancelar |
| **Padrão de URL** | `*.api.nfe.io` (subdomínio) | `api.nfe.io/*` ou `api.nfse.io/*` (caminho) |
| **Tipo de acesso** | Read-only (GET) | Read + Write (GET, POST, PUT, DELETE) |
| **Requer certificado** | ❌ Não | ✅ Sim (para emissão de notas) |
| **Exemplo de endpoint** | `GET legalentity.api.nfe.io/v1/...` | `POST api.nfe.io/v2/companies/.../serviceinvoices` |

### Fluxograma de Decisão

```mermaid
graph TD
    A[O que você precisa fazer?] --> B{Consultar dados?}
    B -->|Sim| C{Que tipo de consulta?}
    C -->|CNPJ| D[🔍 Use Chave de Dados<br/>legalentity.api.nfe.io]
    C -->|CPF| E[🔍 Use Chave de Dados<br/>naturalperson.api.nfe.io]
    C -->|CEP/Endereço| F[🔍 Use Chave de Dados<br/>address.api.nfe.io]
    C -->|Nota já emitida| G[🔍 Use Chave de Dados<br/>nfe.api.nfe.io]
    
    B -->|Não| H{Emitir ou gerenciar?}
    H -->|Emitir NFS-e| I[📝 Use Chave de Nota Fiscal<br/>api.nfe.io]
    H -->|Emitir NF-e/NFC-e| J[📝 Use Chave de Nota Fiscal<br/>api.nfse.io]
    H -->|Criar empresa| K[📝 Use Chave de Nota Fiscal<br/>api.nfe.io ou api.nfse.io]
    H -->|Cancelar nota| L[📝 Use Chave de Nota Fiscal<br/>api.nfe.io ou api.nfse.io]
    H -->|Upload certificado| M[📝 Use Chave de Nota Fiscal<br/>api.nfe.io ou api.nfse.io]
    
    style D fill:#e3f2fd
    style E fill:#e3f2fd
    style F fill:#e3f2fd
    style G fill:#e3f2fd
    style I fill:#fff3e0
    style J fill:#fff3e0
    style K fill:#fff3e0
    style L fill:#fff3e0
    style M fill:#fff3e0
```

## 5) Mapeamento completo de endpoints

### Endpoints que usam 🔍 Chave de Dados

| Operação | Endpoint | Documentação |
|---|---|---|
| Consultar CNPJ | `GET legalentity.api.nfe.io/v1/legalentities/basicInfo/{cnpj}` | [Consulta CNPJ](/desenvolvedores/rest-api/consulta-de-cnpj-v1) |
| Consultar CPF | `GET naturalperson.api.nfe.io/v1/naturalperson/status/{cpf}/{birthDate}` | [Consulta CPF](/desenvolvedores/rest-api/consulta-de-cpf-v1) |
| Consultar CEP | `GET address.api.nfe.io/v2/addresses/{postalCode}` | [Consulta Endereços](/desenvolvedores/rest-api/consulta-de-enderecos-v1) |
| Consultar NF-e por chave | `GET nfe.api.nfe.io/v2/productinvoices/{accessKey}` | [Consulta NF-e](/desenvolvedores/rest-api/consulta-de-nota-fiscal/v2) |

### Endpoints que usam 📝 Chave de Nota Fiscal

| Operação | Endpoint | Documentação |
|---|---|---|
| Criar empresa | `POST api.nfe.io/v2/companies` ou `POST api.nfse.io/v2/companies` | [Criar Empresa](/documentacao/nossa-plataforma/criar-empresa) |
| Upload certificado | `POST api.nfe.io/v2/companies/{id}/certificate` | [Upload Certificado](/documentacao/nossa-plataforma/upload-do-certificado-digital) |
| Emitir NFS-e | `POST api.nfe.io/v2/companies/{id}/serviceinvoices` | [NFS-e v1](/desenvolvedores/rest-api/nota-fiscal-de-servico-v1) |
| Emitir NF-e | `POST api.nfse.io/v2/companies/{id}/productinvoices` | [NF-e v2](/desenvolvedores/rest-api/nota-fiscal-de-produto-v2) |
| Emitir NFC-e | `POST api.nfse.io/v2/companies/{id}/consumerinvoices` | [NFC-e v2](/desenvolvedores/rest-api/nota-fiscal-de-consumidor-v2) |
| Listar NFS-e | `GET api.nfe.io/v2/companies/{id}/serviceinvoices` | [NFS-e v1](/desenvolvedores/rest-api/nota-fiscal-de-servico-v1) |
| Cancelar NFS-e | `DELETE api.nfe.io/v2/companies/{id}/serviceinvoices/{invoiceId}` | [NFS-e v1](/desenvolvedores/rest-api/nota-fiscal-de-servico-v1) |
| Criar webhook | `POST api.nfse.io/v2/webhooks` | [Webhooks](/documentacao/conceitos/webhook) |

## 6) Erros comuns e soluções

### ❌ Erro 401: "API Key da conta não é válida"

**Causa mais comum:** Você está usando a chave errada para o endpoint.

**Como identificar qual chave usar:**

1. **Olhe para a URL base:**
   - Se for `*.api.nfe.io` (com subdomínio) → 🔍 **Chave de Dados**
   - Se for `api.nfe.io/*` ou `api.nfse.io/*` → 📝 **Chave de Nota Fiscal**

2. **Pergunte-se:**
   - "Estou consultando dados?" → 🔍 **Chave de Dados**
   - "Estou emitindo/criando algo?" → 📝 **Chave de Nota Fiscal**

**Exemplos de erros e soluções:**

| ❌ Erro | ✅ Solução |
|---|---|
| Tentando emitir NFS-e com Chave de Dados | Use a **Chave de Nota Fiscal** |
| Tentando consultar CNPJ com Chave de Nota Fiscal | Use a **Chave de Dados** |
| Tentando criar empresa com Chave de Dados | Use a **Chave de Nota Fiscal** |
| Tentando consultar nota emitida com Chave de Nota Fiscal | Use a **Chave de Dados** (se for consulta por chave de acesso) |

### Outras verificações de segurança

- ✅ Certifique-se de que está usando o cabeçalho correto: `Authorization: SUA_CHAVE`
- ✅ Não adicione prefixos como "Bearer" na Chave de API (use apenas para JWT)
- ✅ Verifique se não há espaços antes ou depois da chave
- ✅ Confirme que a chave está ativa na plataforma

## 7) Boas práticas de segurança

:::danger Segurança crítica

**NUNCA faça isso:**
- ❌ Commitar chaves no Git/GitHub
- ❌ Expor chaves em código-fonte público
- ❌ Compartilhar chaves por email ou chat sem criptografia
- ❌ Usar a mesma chave em produção e testes (quando possível)
- ❌ Armazenar chaves em texto plano no frontend

**SEMPRE faça isso:**
- ✅ Armazene chaves em variáveis de ambiente (`process.env`, `.env` no `.gitignore`)
- ✅ Use gerenciadores de secrets (AWS Secrets Manager, Azure Key Vault, etc.)
- ✅ Rotacione chaves periodicamente ou se suspeitar de vazamento
- ✅ Use HTTPS em todas as requisições
- ✅ Limite o acesso às chaves apenas para quem precisa
- ✅ Monitore o uso das chaves para detectar comportamentos anômalos

:::

**Exemplo de uso seguro em Node.js:**

```javascript
// ✅ CORRETO - Usando variável de ambiente
const DATA_API_KEY = process.env.NFEIO_DATA_KEY;
const INVOICE_API_KEY = process.env.NFEIO_INVOICE_KEY;

// Consultar CNPJ
const cnpjResponse = await fetch(
  'https://legalentity.api.nfe.io/v1/legalentities/basicInfo/12345678000195',
  { headers: { 'Authorization': DATA_API_KEY } }
);

// Emitir nota
const invoiceResponse = await fetch(
  'https://api.nfe.io/v2/companies/ID/serviceinvoices',
  {
    method: 'POST',
    headers: {
      'Authorization': INVOICE_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({...})
  }
);
```

**Exemplo de arquivo `.env`:**

```bash
# Chaves NFE.io (NÃO commitar este arquivo!)
NFEIO_DATA_KEY=sua-chave-de-dados-aqui
NFEIO_INVOICE_KEY=sua-chave-de-nota-fiscal-aqui
```

**Adicione ao `.gitignore`:**

```
.env
.env.local
.env.*.local
```

## 8) Próximos passos

### Se você vai usar a Chave de Dados:

1. **Comece com consultas simples:**
   - [Consultar CNPJ](/desenvolvedores/rest-api/consulta-de-cnpj-v1) - Ideal para começar
   - [Consultar CPF](/desenvolvedores/rest-api/consulta-de-cpf-v1)
   - [Consultar CEP](/desenvolvedores/rest-api/consulta-de-enderecos-v1)

2. **Consultas avançadas:**
   - [Consultar notas fiscais](/desenvolvedores/rest-api/consulta-de-nota-fiscal/v2)
   - [Distribuição de NF-e](/desenvolvedores/rest-api/consulta-nf-e-distribuicao)

### Se você vai usar a Chave de Nota Fiscal:

1. **Configure sua estrutura primeiro:**
   - [Criar uma empresa][8]
   - [Fazer upload do certificado digital][9]

2. **Emita sua primeira nota:**
   - [Emitir NFS-e (Nota de Serviço)][10]
   - [Emitir NF-e (Nota de Produto)](/desenvolvedores/rest-api/nota-fiscal-de-produto-v2)
   - [Emitir NFC-e (Nota de Consumidor)](/desenvolvedores/rest-api/nota-fiscal-de-consumidor-v2)

3. **Gerencie suas notas:**
   - [Listar notas fiscais de serviço][11]
   - [Cancelar uma nota fiscal de serviço][12]
   - [Configurar Webhooks](/documentacao/conceitos/webhook)

### Documentação complementar:

- [Introdução à REST API](/rest-api) - Guia completo da API
- [Conceitos da plataforma](/documentacao/conceitos/introducao) - Entenda melhor a NFE.io
- [Cálculo de impostos](/desenvolvedores/rest-api/calculo-de-impostos-v1) - Motor tributário

---

:::info Dica final

Guarde este marcador! Sempre que tiver dúvida sobre qual chave usar, volte à [tabela comparativa](#4-quando-usar-cada-chave) ou ao [fluxograma de decisão](#fluxograma-de-decisão).

:::

[1]: #1-menu-conta
[2]: #1-menu-conta
[3]: #2-chaves-disponíveis
[4]: https://nfe.io
[5]: #1-menu-conta
[6]: #2-chaves-disponíveis
[7]: /docs/documentacao/nossa-plataforma/criar-conta
[8]: /docs/documentacao/nossa-plataforma/criar-empresa
[9]: /docs/documentacao/nossa-plataforma/upload-do-certificado-digital
[10]: /docs/documentacao/nossa-plataforma/nota-fiscal-servico/emitir-em-lote
[11]: /docs/documentacao/nossa-plataforma/nota-fiscal-servico/listar-notas-servico
[12]: /docs/documentacao/nossa-plataforma/nota-fiscal-servico/cancelar-nota-servico

---

## Como Criar Conta em nossa plataforma?

Source: https://nfe.io/docs/documentacao/nossa-plataforma/criar-conta/index.md

# Criar Conta

Mostraremos aqui, como criar conta na plataforma da NFE.io e como escolher os serviços que melhor lhe atende.

## Ao final desse tutorial, você será capaz de:

* [Criar conta na plataforma NFE.io][6]
* [Escolher quais serviços melhor lhe atende][7]

## 1\. Cadastrar uma conta ou realizar login

Você deverá criar uma conta na nossa plataforma, ou realizar o login.

1. [Clique aqui][8] para criar uma conta em nossa plataforma.  
![criar conta](https://nfe.io/docs/static/docs/plataforma/create-a-new-account.png)

Ao clicar em **CRIAR UMA NOVA CONTA**, a tela de criação abaixo aparecerá, agora é só preencher suas informações corretamente, Nome completo, email, telefone e uma senha forte!  
**Clique em 'Criar conta'**

![MELHOR EMAIL](https://nfe.io/docs/static/docs/plataforma/create-a-new-account-3.png)

## 2\. Escolher quais serviços utilizar

Após a criação da conta, você será direcionado para a tela de onboarding, abaixo.

![tela de onboarding](https://nfe.io/docs/static/docs/plataforma/create-a-new-account-4-e1603997839899.png)

> Selecione os serviços que você quer testar e clique em avançar. É possível selecionar mais de um serviço, fique à vontade para testar todos!

[_Lembre-se você está no ambiente de teste_][9]

## Próximos passos

* [Criar uma empresa][10]
* [Fazer upload do certificado digital][11]
* [ Emitir uma nota fiscal de serviço][12]
* [Listar notas fiscais de serviço][13]
* [Cancelar uma nota fiscal de serviço][14]

[1]: #Criar%5FConta
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #1%5FCadastrar%5Fuma%5Fconta%5Fou%5Frealizar%5Flogin
[4]: #2%5FEscolher%5Fquais%5Fservicos%5Futilizar
[5]: #Proximos%5Fpassos
[6]: https://nfe.io/docs/nossa-plataforma/criar-conta/#1-cadastrar-uma-conta-ou-realizar-login
[7]: https://nfe.io/docs/documentacao/nossa-plataforma/criar-conta/#2%5FEscolher%5Fquais%5Fservicos%5Futilizar
[8]: https://app.nfe.io/
[9]: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/primeiros-passos/#Utilizando%5Fo%5FAmbiente%5Fde%5FTestes
[10]: https://nfe.io/docs/nossa-plataforma/criar-empresa/
[11]: https://nfe.io/docs/nossa-plataforma/upload-certificado/
[12]: https://nfe.io/docs/nossa-plataforma/nota-fiscal-servico/emitir-nota-servico/
[13]: https://nfe.io/docs/nossa-plataforma/nota-fiscal-servico/listar-notas-servico/
[14]: https://nfe.io/docs/nossa-plataforma/nota-fiscal-servico/cancelar-nota-servico/

---

## Como criar empresa na plataforma - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/criar-empresa/index.md

# Criar Empresa

Ao final desse tutorial você será capaz de cadastrar uma empresa pelo **painel da NFE.io** e deixá-la pronta para emitir notas fiscais.

**Requisitos**

- [Criar uma conta](./criar-conta.md)

:::info Painel centralizado
Todas as configurações da empresa estão reunidas em um único painel, acessível por [app.nfe.io/companies](https://app.nfe.io/companies). O endereço antigo `/companies-v2` foi descontinuado e redireciona automaticamente para o novo.
:::

:::tip Procurando a cadência completa até emitir a nota?
Esta página foca em **criar a empresa**. Para o fluxo de ponta a ponta até a emissão, veja a cadência por tipo de documento:

- [Primeiros Passos — NFS-e](../nota-fiscal-servico-eletronica/primeiros-passos.md) (criar empresa → IM → certificado opcional em testes → emitir NFS-e)
- [Primeiros Passos — NF-e / NFC-e](../nota-fiscal-produto-eletronica/integracao-api/primeiros-passos.md) (criar empresa → IE → certificado obrigatório → emitir NF-e/NFC-e)
:::

## 1. Acessar o painel de empresas

No menu lateral, clique em **Empresas**. Você será levado para a listagem em `app.nfe.io/companies`, com todas as empresas vinculadas à sua conta. Em seguida, clique no botão **+ Criar Empresa** no topo da listagem.

![Listagem de empresas com o botão Criar Empresa em destaque](https://nfe.io/docs/static/docs/plataforma/criar-empresa/1-inicio-criar-empresa.png)

## 2. Preencher o cadastro

O cadastro abre como um wizard de **cinco etapas** numeradas na lateral esquerda. A cada etapa preenchida, o item recebe um check verde e a próxima fica disponível.

Este guia descreve em detalhe a **Etapa 1 (Dados básicos)** e a **Etapa 5 (Confirmar)** — ou seja, o que é específico de **criar a empresa**. As etapas de IE, IM e Certificado têm guias dedicados linkados em cada seção.

### Etapa 1: Dados básicos da empresa

Preencha duas seções:

**Dados da Empresa**

- **CNPJ** (obrigatório)
- **Razão Social** (obrigatório)
- **Nome Fantasia** (opcional)
- **Regime Tributário** — Simples Nacional, Lucro Presumido, Lucro Real, MEI ou Isento

**Dados do Endereço**

- **CEP**, **Logradouro**, **Número**, **Complemento** (opcional), **Bairro**, **Estado** e **Cidade**

Se a cidade da empresa for atendida pela NFE.io, aparece o selo **Prefeitura integrada** ao lado do campo.

![Etapa 1 — Dados básicos da empresa](https://nfe.io/docs/static/docs/plataforma/criar-empresa/2-dados-basicos-empresa.png)

### Etapa 2: Inscrição Estadual

A **Inscrição Estadual (IE)** é o registro da empresa na SEFAZ. Necessária para emissão de **NF-e** ou **NFC-e**.

**Quando preencher?**

- Empresa emite **NF-e** ou **NFC-e** → preencha os dados da IE
- Empresa só emite **NFS-e** → marque **"É isento"** e avance

![Etapa 2 — Inscrição Estadual (opção "É isento" marcada)](https://nfe.io/docs/static/docs/plataforma/criar-empresa/3-pular-ie.png)

→ **Detalhes do formulário e campos:** [Criar Inscrição Estadual](./criar-inscricao-estadual.md)

### Etapa 3: Inscrição Municipal

A **Inscrição Municipal (IM)** é o registro da empresa na prefeitura. Obrigatória para emissão de **NFS-e**.

**Quando preencher?**

- Empresa emite **NFS-e** → preencha os dados da IM
- Empresa só emite **NF-e** ou **NFC-e** → marque **"É isento"** e avance

![Etapa 3 — Inscrição Municipal](https://nfe.io/docs/static/docs/plataforma/criar-empresa/4-criar-im.png)

→ **Detalhes do formulário e campos:** [Criar Inscrição Municipal](./criar-inscricao-municipal.md)

### Etapa 4: Certificado digital (Opcional no wizard)

Faça upload do **certificado digital A1** ICP-Brasil.

**Quando preencher?**

- Vai emitir notas em **produção** (qualquer tipo) → necessário (pode pular aqui e fazer depois)
- Vai testar **NFS-e** em ambiente de homologação NFE.io → **opcional**, pode clicar em **Pular** (os servidores da NFE.io simulam a prefeitura)
- Vai testar **NF-e/NFC-e** em homologação SEFAZ → **obrigatório mesmo em homologação** (a SEFAZ é o ambiente real do órgão e exige assinatura digital)

![Etapa 4 — Upload do certificado digital](https://nfe.io/docs/static/docs/plataforma/criar-empresa/5-incluir-certificado.png)

→ **Detalhes e como enviar depois:** [Upload do Certificado Digital](./upload-do-certificado-digital.md)

### Etapa 5: Confirmar criação

Revise o resumo das etapas anteriores. Cada item aparece com check verde e um resumo dos dados informados — por exemplo, "Inscrição Municipal: Brasília/DF · 1111111".

Clique em **"Criar empresa"** para finalizar. Para ajustar algum dado, clique em **"Voltar"** ou navegue para a etapa correspondente na barra à esquerda.

![Etapa 5 — Confirmação e criação da empresa](https://nfe.io/docs/static/docs/plataforma/criar-empresa/6-confirmar-criar-empresa.png)

## 3. Empresa criada

Após confirmar, você é direcionado para a página de **Gerenciamento da empresa** com a notificação "Empresa criada com sucesso!". A página reúne os cards de:

- **Informações da empresa** — dados básicos
- **Certificado Digital** — status e validade
- **Inscrições Estaduais**
- **Inscrição Municipal**
- **Lista de serviços cadastrados**
- **CT-e distribuição**

A empresa também já aparece na listagem em `app.nfe.io/companies`.

![Página de Gerenciamento da empresa após criação](https://nfe.io/docs/static/docs/plataforma/criar-empresa/7-empresa-criada.png)

## Próximos passos

- [Primeiros Passos — NFS-e](../nota-fiscal-servico-eletronica/primeiros-passos.md) — cadência completa até emitir
- [Primeiros Passos — NF-e / NFC-e](../nota-fiscal-produto-eletronica/integracao-api/primeiros-passos.md) — cadência completa até emitir
- [Criar Inscrição Estadual](./criar-inscricao-estadual.md) — adicionar uma IE depois
- [Criar Inscrição Municipal](./criar-inscricao-municipal.md) — cadastrar a IM depois
- [Upload do certificado digital](./upload-do-certificado-digital.md)
- [Alterar dados da empresa](./alterar-empresa.md)

---

## Criar Inscrição Estadual no painel da empresa | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/criar-inscricao-estadual/index.md

# Criar Inscrição Estadual

A **Inscrição Estadual (IE)** é o registro da empresa na **SEFAZ** do seu estado. É obrigatória para emitir **NF-e** e **NFC-e**. Esta página descreve como cadastrar uma nova IE pelo painel da NFE.io.

**Requisitos**

- [Criar uma conta](./criar-conta.md)
- [Criar uma empresa](./criar-empresa.md)
- IE habilitada na SEFAZ do seu estado, com credenciais de acesso quando aplicável

:::info
A NFE.io **não cadastra** sua Inscrição Estadual na SEFAZ. O cadastro junto ao órgão estadual continua sendo responsabilidade da empresa e do contador. O painel apenas registra os dados para que a NFE.io consiga transmitir e assinar as notas em seu nome.
:::

## Quando cadastrar uma IE

- A empresa emite (ou pretende emitir) **NF-e** ou **NFC-e**
- A empresa opera em uma **nova UF** — uma mesma empresa pode ter várias IEs, uma por estado

Se a empresa só emite **NFS-e**, a IE não é necessária — marque "É isento" no wizard ou pule esta etapa.

## Caminhos para cadastrar

A IE pode ser cadastrada por dois caminhos. O formulário é o mesmo nos dois.

### Caminho A — Durante a criação da empresa (wizard)

Na **Etapa 2 do wizard de criar empresa**, preencha os dados da IE. Veja [Criar Empresa](./criar-empresa.md) para o fluxo completo.

![Etapa 2 do wizard — Inscrição Estadual](https://nfe.io/docs/static/docs/plataforma/criar-empresa/3-pular-ie.png)

### Caminho B — Depois, pelo card no painel da empresa

No painel da empresa em [app.nfe.io/companies](https://app.nfe.io/companies), localize o card **Inscrição Estadual**:

- Se ainda não há nenhuma IE, o clique abre direto o formulário de cadastro
- Se já existe pelo menos uma IE, o clique abre a lista — clique em **Nova Inscrição Estadual**

![Card de Inscrição Estadual no painel da empresa](https://nfe.io/docs/static/docs/release-2026-2/card-inscricao-estadual.png)

## Formulário

O formulário pede:

- **Estado (UF)** — o estado da inscrição
- **Tipo** — **NF-e** ou **NFC-e**
- **Inscrição Estadual** — número da IE junto à SEFAZ
- **Série** — série usada na emissão
- **Credenciais** — quando exigidas pelo estado (por exemplo, **CSC** para NFC-e)
- **Ambiente** — **Produção** ou **Homologação**

:::warning Certificado obrigatório
Diferente da NFS-e, em NF-e e NFC-e o certificado digital A1 é **obrigatório mesmo em Homologação** — a SEFAZ exige assinatura ICP-Brasil em todas as transmissões. Veja [Upload do certificado digital](./upload-do-certificado-digital.md).
:::

Confira os dados com seu contador e clique em **Salvar**. A inscrição passa a aparecer no card da empresa e fica disponível para emissão.

## Próximos passos

- [Alterar Inscrição Estadual](./alterar-inscricao-estadual.md) — editar uma IE existente
- [Cadastrar uma Inscrição Municipal](./criar-inscricao-municipal.md) — para emitir NFS-e
- [Fazer upload do certificado digital](./upload-do-certificado-digital.md)
- [Primeiros Passos — NF-e](../nota-fiscal-produto-eletronica/integracao-api/primeiros-passos.md) — cadência completa até a emissão
- [API de Inscrições Estaduais (referência técnica)](../gerenciamento-empresas/gerenciamento-inscricao-estadual.md)

---

## Criar Inscrição Municipal no painel da empresa | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/criar-inscricao-municipal/index.md

# Criar Inscrição Municipal

A **Inscrição Municipal (IM)** é o registro da empresa na **prefeitura** de uma cidade. É obrigatória para emitir **NFS-e** naquele município. Esta página descreve como cadastrar a IM pelo painel da NFE.io.

**Requisitos**

- [Criar uma conta](./criar-conta.md)
- [Criar uma empresa](./criar-empresa.md)
- IM habilitada na prefeitura da cidade, com credenciais de acesso quando exigidas

:::info
A NFE.io **não cadastra** sua Inscrição Municipal na prefeitura. O credenciamento junto ao município continua sendo responsabilidade da empresa e do contador. O painel apenas registra os dados (inclusive login, senha e série do RPS) para que a NFE.io consiga transmitir as NFS-e em seu nome.
:::

## Quando cadastrar uma IM

- A empresa emite (ou pretende emitir) **NFS-e**
- A empresa ainda não tem uma IM cadastrada no painel

Se a empresa só emite **NF-e/NFC-e**, a IM não é necessária — marque "É isento" no wizard ou pule esta etapa.

## Caminhos para cadastrar

A IM pode ser cadastrada por dois caminhos. O formulário é o mesmo nos dois.

### Caminho A — Durante a criação da empresa (wizard)

Na **Etapa 3 do wizard de criar empresa**, preencha os dados da IM. Veja [Criar Empresa](./criar-empresa.md) para o fluxo completo.

![Etapa 3 do wizard — Inscrição Municipal](https://nfe.io/docs/static/docs/plataforma/criar-empresa/4-criar-im.png)

### Caminho B — Depois, pelo card no painel da empresa

No painel da empresa em [app.nfe.io/companies](https://app.nfe.io/companies), localize o card **Inscrição Municipal**. Quando ainda não há IM cadastrada, o clique abre direto o formulário de cadastro.

![Card de Inscrição Municipal no painel da empresa](https://nfe.io/docs/static/docs/release-2026-2/card-inscricao-municipal.png)

## Formulário

O formulário é dividido em quatro blocos.

### Dados da Inscrição Municipal

- **UF** e **Cidade** — selecione o estado e a cidade (o sistema preenche automaticamente o código IBGE). Se a cidade tem suporte da NFE.io, aparece o selo **Prefeitura integrada**
- **Inscrição Municipal** — número da IM junto à prefeitura
- **Regime Especial de Tributação** — conforme legislação municipal
- **Email** — para notificações da prefeitura

### Dados de Impostos

- **Determinação dos impostos pela federação** — incidência conforme legislação federal
- **Determinação dos impostos pelo município** — incidência conforme legislação municipal
- **Alíquota ISS para Simples Nacional** — apenas para empresas optantes pelo Simples Nacional

### RPS (Recibo Provisório de Serviços)

- **Série do RPS** — série utilizada na emissão
- **Número do RPS** — próximo número a ser utilizado
- **Último RPS Enviado** — somente leitura, referência de controle

:::tip
Confirme com a prefeitura qual é o próximo RPS disponível antes de cadastrar. Iniciar com um número já utilizado costuma resultar em rejeição da NFS-e.
:::

### Credenciais da Prefeitura

- **Login da Prefeitura**
- **Senha da Prefeitura**

As credenciais são exigidas apenas para prefeituras que demandam autenticação direta. Cada município tem regras próprias. Em caso de dúvida, consulte a documentação específica da cidade.

### Ambiente

Selecione **Produção** ou **Testes**:

- **Produção** — as NFS-e são processadas pelo sistema da Prefeitura; impostos passam a ser devidos
- **Testes** — as NFS-e são processadas por servidores que imitam o comportamento da prefeitura; sem validade fiscal

:::tip Certificado é opcional em Testes
Para emitir NFS-e em ambiente de **Testes**, o certificado digital **não é obrigatório** — os servidores da NFE.io simulam a prefeitura, sem trânsito real. Em **Produção**, o certificado é obrigatório. Veja a cadência completa em [Primeiros Passos — NFS-e](../nota-fiscal-servico-eletronica/primeiros-passos.md).
:::

Ao final, clique em **Salvar**. A inscrição aparece no card da empresa e fica disponível para emissão.

## Próximos passos

- [Alterar Inscrição Municipal](./alterar-inscricao-municipal.md) — editar a IM existente
- [Cadastrar uma Inscrição Estadual](./criar-inscricao-estadual.md) — se também emite NF-e/NFC-e
- [Fazer upload do certificado digital](./upload-do-certificado-digital.md)
- [Primeiros Passos — NFS-e](../nota-fiscal-servico-eletronica/primeiros-passos.md) — cadência completa até a emissão
- [API de Inscrições Municipais (referência técnica)](../gerenciamento-empresas/gerenciamento-inscricao-municipal.md)

---

## Inscrição Estadual no painel da empresa | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/inscricao-estadual/index.md

# Inscrição Estadual

A **Inscrição Estadual (IE)** é o registro da empresa na **SEFAZ** do seu estado e é obrigatória para emitir **NF-e** e **NFC-e**. No painel da NFE.io, a IE fica acessível em um card dedicado dentro do **Gerenciamento da empresa**.

Uma mesma empresa pode ter **várias IEs**, uma por estado em que opera.

:::info
A NFE.io **não cadastra** sua Inscrição Estadual na SEFAZ. O cadastro junto ao órgão estadual continua sendo responsabilidade da empresa e do contador. O painel apenas registra os dados para que a NFE.io consiga transmitir e assinar as notas em seu nome.
:::

## Operações disponíveis

- **[Criar Inscrição Estadual](./criar-inscricao-estadual.md)** — cadastrar uma nova IE, durante o wizard de criação da empresa ou pelo card no painel
- **[Alterar Inscrição Estadual](./alterar-inscricao-estadual.md)** — listar, editar credenciais/série/ambiente de uma IE existente

## Conceitos relacionados

- [Criar Empresa](./criar-empresa.md) — wizard que inclui a etapa de cadastrar IE
- [Upload do certificado digital](./upload-do-certificado-digital.md) — obrigatório para emitir NF-e/NFC-e mesmo em homologação
- [Primeiros Passos — NF-e](../nota-fiscal-produto-eletronica/integracao-api/primeiros-passos.md) — cadência completa até a emissão
- [API de Inscrições Estaduais (referência técnica)](../gerenciamento-empresas/gerenciamento-inscricao-estadual.md)

---

## Inscrição Municipal no painel da empresa | NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/inscricao-municipal/index.md

# Inscrição Municipal

A **Inscrição Municipal (IM)** é o registro da empresa na **prefeitura** de uma cidade e é obrigatória para emitir **NFS-e** naquele município. No painel da NFE.io, a IM da empresa fica em um card dedicado dentro do **Gerenciamento da empresa**.

:::info
A NFE.io **não cadastra** sua Inscrição Municipal na prefeitura. O credenciamento junto ao município continua sendo responsabilidade da empresa e do contador. O painel apenas registra os dados (inclusive login, senha e série do RPS) para que a NFE.io consiga transmitir as NFS-e em seu nome.
:::

## Operações disponíveis

- **[Criar Inscrição Municipal](./criar-inscricao-municipal.md)** — cadastrar a IM, durante o wizard de criação da empresa ou pelo card no painel
- **[Alterar Inscrição Municipal](./alterar-inscricao-municipal.md)** — editar ou trocar o ambiente da IM cadastrada

## Conceitos relacionados

- [Criar Empresa](./criar-empresa.md) — wizard que inclui a etapa de cadastrar IM
- [Upload do certificado digital](./upload-do-certificado-digital.md) — obrigatório em produção; opcional em testes na NFS-e
- [Primeiros Passos — NFS-e](../nota-fiscal-servico-eletronica/primeiros-passos.md) — cadência completa até a emissão
- [API de Inscrições Municipais (referência técnica)](../gerenciamento-empresas/gerenciamento-inscricao-municipal.md)

---

## Como Emitir Nota Fiscal de Produto em Lote - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/nota-fiscal-produto/emitir-em-lote/index.md

# Como emitir Nota Fiscal Eletrônica de Produto em Lote

:::info
Para emitir em lote notas fiscais de produto, é necessário habilitar a funcionalidade **Emissão de Notas Fiscais de Produto (NF-e) em Lote** pela plataforma. Entre em contato com nosso suporte através do chat ou e-mail.
:::

> 📚 **Novo na emissão de NF-e?** Recomendamos ler os [conceitos sobre Nota Fiscal de Produto](/docs/documentacao/nota-fiscal-produto-eletronica/conceitos) antes de continuar.

## Ao final desse tutorial, você será capaz de:

* Emitir notas fiscais eletrônicas de produto (NF-e) em lote

## Requisitos

1. [Criar uma conta](/docs/documentacao/nossa-plataforma/criar-conta)
2. [Criar uma empresa](/docs/documentacao/nossa-plataforma/criar-empresa)
3. [Ter Certificado Digital](/docs/documentacao/certificado-digital/conceitos) - [Fazer upload na plataforma](/docs/documentacao/nossa-plataforma/upload-do-certificado-digital)

## 1\. Como emitir

1.1 Clique na aba **EMPRESAS**  
![pagina emitir nota fiscal em lote](https://nfe.io/docs/static/docs/plataforma/company-page-4.png)

1.2 Clique no botão **EMITIR** em frente à sua empresa. Se o **certificado digital estiver corretamente instalado** e a **inscrição estadual estiver válida**, você verá a tela de emissão de notas fiscais.

![passo a passo nfs-e](https://nfe.io/docs/static/docs/plataforma/issue-service-invoice.png)

1.2.1 Ou, na visualização da empresa, clique no menu **Ações** e depois no botão **Emitir Notas Fiscais em Lote**.

![](https://nfe.io/docs/static/docs/plataforma/nfe-batch-company-view-action.png)

1.3 Caso a aplicação não identifique o seu login, será solicitado que você informe sua senha novamente para prosseguir com a emissão.

1.4 Neste passo a passo você encontrará as instruções necessárias para emitir suas notas fiscais utilizando o Excel e preencher os campos da planilha.

![problemas emitir nota](https://nfe.io/docs/static/docs/plataforma/nfe-batch-setup.png)

## 2\. Passo a passo para enviar a planilha

2.1 Nessa etapa você pode baixar o template da planilha ou fazer o upload da planilha preenchida.

![](https://nfe.io/docs/static/docs/plataforma/nfe-batch-first-upload.png)

2.2 Aguarde um momento enquanto realizamos a validação dos dados. Se estiver tudo correto, você verá a tela "Notas Fiscais". Caso contrário, aparecerá uma tela de erros para corrigir na planilha.

![](https://nfe.io/docs/static/docs/plataforma/nfe-batch-ready-to-send.png)

## 3\. Emitir em lote

Nessa tela temos uma listagem com as notas fiscais de sua planilha. Aqui você poderá revisar as informações das notas, por meio do botão **Pré-visualizar** em cada linha da tabela, selecionar quais serão enviadas para emissão e acompanhar o status da sua emissão.

![](https://nfe.io/docs/static/docs/plataforma/nfe-batch-ready-to-send.png)

3.1 Para selecionar, clique na caixa de seleção na primeira coluna. Você poderá selecionar todas de uma vez clicando na primeira caixa de seleção ou selecionar manualmente as que desejar.

3.2 Para emitir, clique no botão verde **Enviar Notas** e aguarde até que todas sejam enviadas.

3.2.1 Se o envio ocorreu com sucesso, você verá um botão chamado **Ver nota** em cada linha da tabela. Clicando nele, você será redirecionado para a página da nota fiscal emitida.

3.2.2 Caso alguma nota tenha apresentado erro, você verá um botão chamado **Ver erro** em cada linha da tabela. Clicando nele, você verá o motivo do erro e poderá corrigir na planilha para reenviar.


## 4\. Como preencher os campos da planilha

Para uma relação completa de preenchimento dos campos da planilha de produto, consulte o nosso guia: [Template Planilha Completa](/docs/documentacao/nota-fiscal-produto-eletronica/template-de-planilha-para-processamento-de-notas-fiscais).

---

## Como cancelar Nota Fiscal de Serviço na nossa plataforma - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/nota-fiscal-servico/cancelar-nota-servico/index.md

# Cancelar Nota Fiscal de Serviço (NFS-e)

Mostraremos como cancelar a Nota Fiscal de Serviço (NFS-e) emitida dentro de nossa plataforma. Caso fique dúvidas entre em contato, ficaremos felizes em ajudar e responder suas dúvidas.

## Ao final desse tutorial, você será capaz de:

* Cancelar Nota Fiscal de Serviço

## Requisitos

* [Criar uma conta][6]
* [Criar uma empresa][7]
* [Emitir uma nota fiscal de serviço][8]
* [Listar Notas Fiscais de Serviço][9]

## 1\. Cancelar Nota Fiscal de Serviço Eletrônica

1. Clique no Menu **EMPRESAS**  
![empresas](https://nfe.io/docs/static/docs/plataforma/company-page-6.png)
2. Clique no botão **LISTAR NOTAS FISCAIS**  
![listar nota fiscal](https://nfe.io/docs/static/docs/plataforma/list-service-invoice-1.png)
3. Clique no botão em frente a nota que deseja cancelar
4. Clique no botão **CANCELAR**

![cancelar nota fiscal](https://nfe.io/docs/static/docs/plataforma/cancel-invoice.png)

## Próximos passos

* [Fazer upload do certificado digital][10]
* [Emitir uma nota fiscal de serviço][8]
* [Listar notas fiscais de serviço][9]

[1]: #Cancelar%5FNota%5FFiscal%5Fde%5FServico%5FNFS-e
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Requisitos
[4]: #1%5FCancelar%5FNota%5FFiscal%5Fde%5FServico%5FEletronica
[5]: #Proximos%5Fpassos
[6]: https://nfe.io/docs/nossa-plataforma/criar-conta/
[7]: https://nfe.io/docs/nossa-plataforma/criar-empresa/
[8]: https://nfe.io/docs/nossa-plataforma/nota-fiscal-servico/emitir-nota-servico/
[9]: https://nfe.io/docs/nossa-plataforma/nota-fiscal-servico/listar-notas-servico/
[10]: https://nfe.io/docs/nossa-plataforma/upload-certificado

---

## Como Emitir Nota Fiscal de Serviço em Lote - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/nota-fiscal-servico/emitir-em-lote/index.md

# Como emitir Nota Fiscal Eletrônica de Serviço em Lote

Aqui você entenderá melhor como emitir [nota fiscal eletrônica de serviço](/docs/documentacao/nota-fiscal-servico-eletronica/conceitos) (NFS-e) em Lote na nossa plataforma, explicado passo-a-passo.

> 📚 **Novo na emissão de NFS-e?** Recomendamos ler os [conceitos sobre Nota Fiscal de Serviço](/docs/documentacao/nota-fiscal-servico-eletronica/conceitos) antes de continuar.

## Ao final desse tutorial, você será capaz de:

* Emitir notas fiscais de serviço eletrônica (NFS-e) em lote

## Requisitos

1. [Criar uma conta](/docs/documentacao/nossa-plataforma/criar-conta)
2. [Criar uma empresa](/docs/documentacao/nossa-plataforma/criar-empresa)
3. [Ter Certificado Digital](/docs/documentacao/certificado-digital/conceitos) - [Fazer upload na plataforma](/docs/documentacao/nossa-plataforma/upload-do-certificado-digital)

> Emissão limitada a 50 linhas por vez, para aumentar o volume para 500 linhas por planilha, por favor vá até conta > funcionalidades > ativar 500 linhas ou solicitar via email para suporte@nfe.io  
> Não há custo para essa solicitação.

## 1\. Como emitir

1.1 Clique na aba **EMPRESAS**  
![pagina emitir nota fiscal em lote](https://nfe.io/docs/static/docs/plataforma/company-page-4.png)

1.2 Clique no botão **EMITIR** em frente a sua empresa

![passo a passo nfs-e](https://nfe.io/docs/static/docs/plataforma/issue-service-invoice.png)

1.3 Nesse passo a passo você encontrará as instruções necessárias para emitir suas notas fiscais utilizando o excel e como preencher os campos da planilha.

![problemas emitir nota](https://nfe.io/docs/static/docs/plataforma/step-by-step-issue-service-invoice.png)

Passo a passo para emitir notas fiscais em lote

## 2\. Passo a passo para montar sua planilha

2.1 Você pode pular caso já saiba como emitir em lote, ou pode clicar em sim e dar continuidade.

![](https://nfe.io/docs/static/docs/plataforma/etapa1.png)

2.2 Nessa etapa você deve escolher um dos modelos de planilha que disponibilizamos para realizar as emissões em lote. No modelo **básico**, os **impostos são calculados automaticamente** pelo nosso sistema e contém apenas os campos excênciais para a emissão das notas. No modelo **avançado**, você pode informar os dados de impostos retidos, alíquota de [ISS](/docs/documentacao/nota-fiscal-servico-eletronica/conceitos#quais-são-os-impostos-retidos-na-emissão-de-nota-fiscal-de-serviço-nfs-e) entre outros campos. Os impostos serão calculados de acordo com as alíquotas que você informou.

> 💡 **Dica:** Se você não sabe qual código de serviço utilizar, consulte nosso guia [Qual código de serviço devo utilizar?](/docs/duvidas-frequentes/qual-codigo-servico-utilizar)

![](https://nfe.io/docs/static/docs/plataforma/tela-passo-2-da-planilha.png)

2.3 Aqui você poderá baixar e aprender como preencher o modelo de planilha selecionado anteriormente.

![](https://nfe.io/docs/static/docs/plataforma/etapa3.png)

2.4 Nessa etapa você já deve estar com a sua planilha corretamente preenchida. Para importá-la, clique no botão **ESCOLHER ARQUIVO**, selecione sua planilha e clique em **IMPORTAR.** Nós iremos validar todas as informações nela contidas.

![](https://nfe.io/docs/static/docs/plataforma/etapa4-1.png)

2.5 Aguarde um momento enquanto realizamos a validação dos dados. Se estiver tudo correto, você irá ver a seguinte mensagem "Planilha importada com sucesso!". Clique no botão **IR PARA EMISSÃO** para continuar com a emissão das suas notas.

![](https://nfe.io/docs/static/docs/plataforma/etapa5.png)

## 3\. Emitir em lote

Nessa tela temos uma listagem com as notas fiscais de sua planilha. Aqui você poderá revisar as informações das notas, selecionar quais serão enviadas para emissão e acompanhar o status da sua emissão.

![](https://nfe.io/docs/static/docs/plataforma/issue-list.png)

3.1 Para selecionar, clique na caixa de seleção na primeira coluna. Você poderá selecionar todas de uma vez clicando na primeira caixa de seleção ou poderá selecionar manualmente quais deseja.

![](https://nfe.io/docs/static/docs/plataforma/issue-list-checkbox.png)

3.2 Para emitir, clique no botão em verde **EMITIR EM LOTE** e aguarde até que todas sejam emitidas.

> Veja esse tutorial que montamos para você!

## 4\. Planilha básica

Veja abaixo algumas regras importantes para alguns campos específicos.

* **Codigo\_Servico**: código do serviço no município (`cityServiceCode`). Cada prefeitura possui sua própria tabela de códigos de serviço.
* **Codigo\_Servico\_Federal**: código federal do serviço (`federalServiceCode`) conforme Lei Complementar 116 (máx. 5 caracteres). [Saiba mais](/docs/duvidas-frequentes/qual-codigo-servico-utilizar).
* **Descricao**: descrição detalhada do serviço prestado (máx. 2000 caracteres).
* **NBS**: código da Nomenclatura Brasileira de Serviços (máx. 9 dígitos). Campo obrigatório na API. [Consulte a tabela de códigos NBS aqui](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-correlacao-nbs-lc116/).
* **CPF\_CNPJ**: pode ser preenchido no formato padrão ou somente números.
* **Email:** caso queira enviar para mais de um email, basta separá-los com vírgula. (Ex: email@teste.com, email2@teste.com).
* **Valor:** pode ser preenchido no padrão brasileiro ou americano. (Ex: 1.000,50 ou 1000.50).
* **Endereco\_Pais:** Sigla do País no padrão ISO 3166-1\. (Ex: BRA, USA, ARG). Mais em [Wikipedia - ISO 3166-1](https://pt.wikipedia.org/wiki/ISO_3166-1).
* **Endereco\_Cep:** pode ser preenchido no formato padrão ou somente números.
* **Data\_competencia:** a data de competência deve ser preenchida apenas para notas retroativas e deve seguir o seguinte formato: YYYY-MM-DD (ano-mês-dia).

> ⚠️ **Importante**:
> O nome de cada coluna na planilha **deve ser exatamente igual** ao descrito na coluna "Campo/Coluna" das tabelas abaixo. Qualquer diferença (espaços, acentos, maiúsculas/minúsculas diferentes) fará com que o sistema não reconheça o campo.

> 🎨 **Convenção de cores dos cabeçalhos**: na planilha, cabeçalhos em **vermelho** indicam campos obrigatórios em toda linha. Cabeçalhos em cinza indicam campos opcionais no nível da nota; alguns desses campos podem se tornar condicionalmente obrigatórios quando o grupo ao qual pertencem é utilizado (ex: `Obra_Endereco_*`, `Deducao_Documento_*`, `Reembolso_Terceiros_Documento_*`). Consulte as regras de cada grupo nas seções abaixo.

### Campos Obrigatórios (Planilha Básica)

> ⚠️ **Atenção**: A obrigatoriedade das informações pode variar de prefeitura para prefeitura.

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Codigo_Servico` | Texto livre | Código do serviço no município. Cada prefeitura possui sua própria tabela de códigos. |
| `Descricao` | Texto livre | Descrição detalhada do serviço prestado (máx. 2000 caracteres) |
| `Valor` | Numérico | Valor total do serviço. Ex: 1000.50 ou 1.000,50 |
| `NBS` | Código NBS | Código da Nomenclatura Brasileira de Serviços (máx. 9 dígitos). Obrigatório em algumas cidades. [Consulte a tabela de códigos NBS aqui](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-correlacao-nbs-lc116/). |
| `CPF_CNPJ` | CPF ou CNPJ | CPF ou CNPJ do tomador. Pode ser com ou sem formatação |
| `Nome` | Texto livre | Nome ou Razão Social do tomador |
| `Endereco_Pais` | Código ISO 3166-1 | Sigla do país (ex: BRA, USA, ARG) |
| `Endereco_Cep` | CEP | CEP do endereço. Com ou sem formatação |
| `Endereco_Logradouro` | Texto livre | Nome da rua, avenida, etc. |
| `Endereco_Numero` | Texto livre | Número do endereço |
| `Endereco_Bairro` | Texto livre | Bairro do endereço |
| `Endereco_Cidade_Codigo` | Código IBGE | Código IBGE da cidade (7 dígitos) |
| `Endereco_Cidade_Nome` | Texto livre | Nome da cidade |
| `Endereco_Estado` | UF | Sigla do estado (ex: SP, RJ, MG) |

### Campos Opcionais (Planilha Básica)

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `NCM` | Código NCM | Código NCM (Nomenclatura Comum do Mercosul) (máx. 8 caracteres). Usado para identificação de produtos/mercadorias. |
| `Email` | Email(s) | Email do tomador. Para múltiplos, separar com vírgula |
| `Endereco_Complemento` | Texto livre | Complemento do endereço (sala, andar, etc.) |
| `Data_Competencia` | YYYY-MM-DD | Data de competência para notas retroativas |
| `Data_Emissao` | YYYY-MM-DD | Data de emissão: se não informada, assume-se a data atual. |
| `Regime_Tributario_Tomador` | `Isento`, `MicroempreendedorIndividual`, `SimplesNacional`, `LucroPresumido`, `LucroReal` | Regime tributário do tomador do serviço |
| `Tomador_Telefone` | Texto livre | Telefone do tomador do serviço |
| `Tomador_Inscricao_Estadual` | Texto livre | Inscrição estadual do tomador do serviço |

### Campos IBS/CBS - Reforma Tributária (Planilha Básica)

> ⚠️ **Regra de Obrigatoriedade Condicional**:
> Se **qualquer um** dos campos `NBS`, `IBSCBS_Indicador_Operacao` ou `IBSCBS_Codigo_Classificacao` for preenchido, **todos os três devem ser preenchidos**. Esses campos são utilizados para operações que seguem o novo modelo tributário brasileiro (Reforma Tributária).
>
> **Consulte a documentação completa:**
> - [Tabela de CST e Classificação Tributária (IBS/CBS)](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-cst-classificacao-tributaria-ibs-cbs/) - Lista completa de códigos CST e cClassTrib
> - [Tabela de Indicador da Operação](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-indicador-operacao/) - Códigos de operação (indOp)
> - [Documentação do Layout de Emissão de NFS-e (RTC)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/) - Documentação completa

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `NBS` | Código NBS | Código da Nomenclatura Brasileira de Serviços (máx. 9 dígitos). [Consulte a tabela de códigos NBS aqui](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-correlacao-nbs-lc116/). |
| `IBSCBS_Indicador_Operacao` | Código `indOp` (ex: `020101`, `030101`, `100301`) | Indicador da operação que determina o local de incidência do IBS/CBS. [Consulte a tabela de referência](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-indicador-operacao/) |
| `IBSCBS_Codigo_Classificacao` | Código `cClassTrib` (ex: `000001`, `200028`, `200052`) | Código de Classificação Tributária que define o regime e alíquotas aplicáveis. [Consulte a tabela de CST/cClassTrib](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-cst-classificacao-tributaria-ibs-cbs/) |

## 5\. Planilha avançada

A planilha avançada possui os mesmos campos da planilha básica e mais os campos adicionais listados abaixo.

> ⚠️ **Importante**:
> O nome de cada coluna na planilha **deve ser exatamente igual** ao descrito na coluna "Campo/Coluna" das tabelas abaixo. Qualquer diferença (espaços, acentos, maiúsculas/minúsculas diferentes) fará com que o sistema não reconheça o campo.

### Campos Tributários Básicos

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `CNAE` | Código CNAE | Código CNAE da atividade |
| `Codigo_Servico_Federal` | Código LC 116 | Código federal do serviço conforme Lei Complementar 116. [Saiba mais sobre códigos de serviço](/docs/duvidas-frequentes/qual-codigo-servico-utilizar) |
| `NBS` | Código NBS | Código da Nomenclatura Brasileira de Serviços. [Consulte a tabela de códigos NBS aqui](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-correlacao-nbs-lc116/). |
| `NCM` | Código NCM | Código NCM (Nomenclatura Comum do Mercosul) (máx. 8 caracteres) |
| `Inscricao_Municipal` | Texto livre | Inscrição municipal do tomador |
| `Informacoes_Adicionais` | Texto livre | Informações complementares para a nota |
| `CAEPF_Tomador` | Numérico | Cadastro de Atividade Econômica da Pessoa Física do tomador (máx. 14 dígitos) |
| `Motivo_Sem_NIF_Tomador` | `NotInformedOriginal`, `Exempted`, `NotRequired` | Justificativa para ausência de NIF do tomador |
| `Pagamento_Parcelado_Antecipado` | `true`, `false` | Indica se é pagamento parcelado antecipado |
| `Tipo_Tributacao` | `None`, `WithinCity`, `OutsideCity`, `Export`, `Free`, `Immune`, `SuspendedCourtDecision`, `SuspendedAdministrativeProcedure`, `OutsideCityFree`, `OutsideCityImmune`, `OutsideCitySuspended`, `OutsideCitySuspendedAdministrativeProcedure`, `ObjectiveImune`, `ObjectiveOutsideCityImune` | Tipo de tributação do serviço |
| `Aliquota_ISS` | Numérico (%) | Alíquota do ISS em percentual |
| `Valor_ISS` | Numérico | Valor do ISS calculado |
| `CST_PIS_COFINS` | `00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09` | Código de Situação Tributária do PIS/COFINS |
| `Base_Calculo_PIS_COFINS` | Numérico | Base de cálculo para PIS e COFINS |
| `Aliquota_PIS` | Numérico (%) | Alíquota do PIS |
| `Valor_PIS` | Numérico | Valor do PIS (sem retenção) |
| `Aliquota_COFINS` | Numérico (%) | Alíquota do COFINS |
| `Valor_COFINS` | Numérico | Valor do COFINS (sem retenção) |
| `Retencao_IR` | Numérico | Valor da retenção de IR |
| `Retencao_PIS` | Numérico | Valor da retenção de PIS |
| `Retencao_COFINS` | Numérico | Valor da retenção de COFINS |
| `Retencao_CSLL` | Numérico | Valor da retenção de CSLL |
| `Retencao_INSS` | Numérico | Valor da retenção de INSS |
| `Retencao_ISS` | Numérico | Valor da retenção de ISS |
| `Aliquota_IR` | Numérico (%) | Alíquota do IR |
| `Aliquota_CSLL` | Numérico (%) | Alíquota do CSLL |
| `Aliquota_INSS` | Numérico (%) | Alíquota do INSS |
| `Aliquota_IPI` | Numérico (%) | Alíquota do IPI |
| `Valor_IPI` | Numérico | Valor do IPI calculado |
| `Retencao_OUTROS` | Numérico | Valor de outras retenções |
| `Valor_Deducoes` | Numérico | Valor das deduções legais |
| `Valor_Desconto_Incondicionado` | Numérico | Valor do desconto incondicionado |
| `Valor_Desconto_Condicionado` | Numérico | Valor do desconto condicionado |
| `Valor_Recebido` | Numérico | Valor efetivamente recebido |
| `Tipo_Tomador` | Texto | Tipo do tomador do serviço |
| `Estado_Prestacao_Servico` | UF | Estado onde o serviço foi prestado |
| `Cidade_Prestacao_Servico` | Texto livre | Nome da cidade onde o serviço foi prestado |
| `Codigo_Cidade_Prestacao_Servico` | Código IBGE | Código IBGE da cidade de prestação |
| `ID_Externo` | Texto livre | Identificador externo para integração |
| `RPS_Serie` | Texto livre | Série do RPS (máx. 5 caracteres). Se não informado, usa o valor do cadastro da empresa |
| `RPS_Numero` | Numérico | Número do RPS. Se não informado, usa o próximo da sequência automática |

### Local de Prestação do Serviço

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Pais_Prestacao_Servico` | Código ISO 3166-1 | País de prestação do serviço (ex: BRA) |
| `Cep_Prestacao_Servico` | CEP | CEP do local de prestação do serviço |
| `Logradouro_Prestacao_Servico` | Texto livre | Logradouro do local de prestação |
| `Numero_Prestacao_Servico` | Texto livre | Número do local de prestação |
| `Bairro_Prestacao_Servico` | Texto livre | Bairro do local de prestação |
| `Complemento_Prestacao_Servico` | Texto livre | Complemento do endereço de prestação |

### Atividade/Evento

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Nome_Atividade_Evento` | Texto livre | Nome da atividade ou evento |
| `Data_Inicio_Evento` | YYYY-MM-DD | Data de início do evento |
| `Data_Fim_Evento` | YYYY-MM-DD | Data de término do evento |
| `Codigo_Atividade_Evento` | Texto livre | Código identificador da atividade/evento |

### Endereço do Evento

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Evento_Endereco_Pais` | Código ISO 3166-1 | País do evento (ex: BRA) |
| `Evento_Endereco_Cep` | CEP | CEP do local do evento |
| `Evento_Endereco_Logradouro` | Texto livre | Logradouro do evento |
| `Evento_Endereco_Numero` | Texto livre | Número do endereço do evento |
| `Evento_Endereco_Complemento` | Texto livre | Complemento do endereço do evento |
| `Evento_Endereco_Bairro` | Texto livre | Bairro do evento |
| `Evento_Endereco_Cidade_Codigo` | Código IBGE | Código IBGE da cidade do evento |
| `Evento_Endereco_Cidade_Nome` | Texto livre | Nome da cidade do evento |
| `Evento_Endereco_Estado` | UF | Estado do evento (ex: SP) |

### Imóvel

> Campos para serviços relacionados a imóveis (ex: serviços de manutenção, limpeza, administração de imóveis).

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Imovel_Inscricao_Imobiliaria` | Texto livre | Inscrição imobiliária do imóvel (número de cadastro municipal) |
| `Imovel_CIB` | Texto livre | Código de Identificação de Bens (imóvel) |
| `Imovel_Endereco_Pais` | Código ISO 3166-1 | País do imóvel (ex: BRA) |
| `Imovel_Endereco_Cep` | CEP | CEP do imóvel |
| `Imovel_Endereco_Logradouro` | Texto livre | Logradouro do imóvel |
| `Imovel_Endereco_Numero` | Texto livre | Número do endereço do imóvel |
| `Imovel_Endereco_Complemento` | Texto livre | Complemento do endereço do imóvel |
| `Imovel_Endereco_Bairro` | Texto livre | Bairro do imóvel |
| `Imovel_Endereco_Cidade_Codigo` | Código IBGE | Código IBGE da cidade do imóvel |
| `Imovel_Endereco_Cidade_Nome` | Texto livre | Nome da cidade do imóvel |
| `Imovel_Endereco_Estado` | UF | Estado do imóvel (ex: SP) |

### Obra/Construção Civil

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Obra_CNO` | Texto livre | Cadastro Nacional de Obras |
| `Obra_CEI` | Texto livre | Cadastro Específico do INSS |
| `Obra_CIB` | Texto livre | Código de Identificação de Bens |
| `Obra_Endereco_Pais` | Código ISO 3166-1 | País da obra (ex: BRA) |
| `Obra_Endereco_Cep` | CEP | CEP da obra |
| `Obra_Endereco_Logradouro` | Texto livre | Logradouro da obra |
| `Obra_Endereco_Numero` | Texto livre | Número do endereço da obra |
| `Obra_Endereco_Complemento` | Texto livre | Complemento do endereço da obra |
| `Obra_Endereco_Bairro` | Texto livre | Bairro da obra |
| `Obra_Endereco_Cidade_Codigo` | Código IBGE | Código IBGE da cidade da obra |
| `Obra_Endereco_Cidade_Nome` | Texto livre | Nome da cidade da obra |
| `Obra_Endereco_Estado` | UF | Estado da obra (ex: SP) |

### Comércio Exterior

> Consulte a [Tabela de Referência de Comércio Exterior](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-comercio-exterior /) para todos os códigos, vínculos, modos de prestação, moedas e mecanismos de fomento utilizados nos campos abaixo.

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Comercio_Exterior_Modo_Prestacao` | `Unknown`, `CrossBorder`, `ConsumptionInBrazil`, `TemporaryPersonnel`, `ConsumptionAbroad` | Modo de prestação do serviço internacional. Veja a tabela de referência para todos os códigos. |
| `Comercio_Exterior_Vinculo` | `NoLink`, `Controlled`, `Controller`, `Affiliate`, `HeadOffice`, `Branch`, `OtherLink` | Vínculo entre prestador e tomador. Veja a tabela de referência para todos os códigos. |
| `Comercio_Exterior_Moeda` | Código Siscomex/BACEN | Moeda da operação (ex: 220, 756, etc). Veja a [tabela oficial de moedas do Banco Central do Brasil](https://www.bcb.gov.br/estabilidadefinanceira/todasmoedas) para todos os códigos. |
| `Comercio_Exterior_Valor_Servico_Moeda` | Numérico | Valor do serviço na moeda estrangeira |
| `Comercio_Exterior_Fomento_Prestador` | `Unknown`, `None`, `Acc`, `Ace`, `BndesEximPostShipServices`, `BndesEximPreShipServices`, `Fge`, `ProexEqualization`, `ProexFinancing` | Mecanismo de fomento do prestador. Veja a tabela de referência para todos os códigos. |
| `Comercio_Exterior_Fomento_Tomador` | `Unknown`, `None`, `PublicAdminAndInternationalRep`, `LeasesMachineryShipsAircraft`, `AircraftLeaseAirTransportPublic`, `ExportAgentsCommission`, `StorageHandlingTransportAbroad`, `FifaEventsSubsidiary`, `FifaEvents`, `FreightsVesselAircraftRentalsOthers`, `AeronauticalMaterial`, `PromotionGoodsAbroad`, `PromotionBrazilianTourism`, `PromotionBrazilAbroad`, `PromotionServicesAbroad`, `Recine`, `Recopa`, `TrademarksPatentsCultivars`, `Reicomp`, `Reidi`, `Repenec`, `Repes`, `Retaero`, `Retid`, `RoyaltiesTechnicalAssistance`, `ConformityAssessmentWto`, `Zpe` | Mecanismo de fomento do tomador. Veja a tabela de referência para todos os códigos. |
| `Comercio_Exterior_Movimentacao_Temporaria_Bens` | `Unknown`, `No`, `LinkedImportDeclaration`, `LinkedExportDeclaration` | Movimentação temporária de bens. Veja a tabela de referência para todos os códigos. |
| `Comercio_Exterior_Declaracao_Importacao` | Texto livre | Número da declaração de importação |
| `Comercio_Exterior_Registro_Exportacao` | Texto livre | Número do registro de exportação |
| `Comercio_Exterior_Envio_MDIC` | `true`, `false` | Indicador de envio ao MDIC |

### Intermediário

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Intermediario_Tipo` | `Undefined`, `NaturalPerson`, `LegalEntity` | Tipo do intermediário (Pessoa Física ou Jurídica) |
| `Intermediario_Nome` | Texto livre | Nome ou Razão Social do intermediário |
| `Intermediario_CPF_CNPJ` | CPF ou CNPJ | CPF ou CNPJ do intermediário |
| `Intermediario_Inscricao_Municipal` | Texto livre | Inscrição municipal do intermediário |
| `Intermediario_Inscricao_Estadual` | Texto livre | Inscrição estadual do intermediário |
| `Intermediario_Regime_Tributario` | `Isento`, `MicroempreendedorIndividual`, `SimplesNacional`, `LucroPresumido`, `LucroReal` | Regime tributário do intermediário |
| `Intermediario_CAEPF` | Numérico | Cadastro de Atividade Econômica da Pessoa Física do intermediário (máx. 14 dígitos) |
| `Intermediario_Motivo_Sem_NIF` | `NotInformedOriginal`, `Exempted`, `NotRequired` | Justificativa para ausência de NIF do intermediário |
| `Intermediario_Telefone` | Texto livre | Telefone do intermediário |
| `Intermediario_Email` | Email | Email do intermediário |
| `Intermediario_Endereco_Pais` | Código ISO 3166-1 | País do intermediário |
| `Intermediario_Endereco_Cep` | CEP | CEP do intermediário |
| `Intermediario_Endereco_Logradouro` | Texto livre | Logradouro do intermediário |
| `Intermediario_Endereco_Numero` | Texto livre | Número do endereço do intermediário |
| `Intermediario_Endereco_Complemento` | Texto livre | Complemento do endereço do intermediário |
| `Intermediario_Endereco_Bairro` | Texto livre | Bairro do intermediário |
| `Intermediario_Endereco_Cidade_Codigo` | Código IBGE | Código IBGE da cidade do intermediário |
| `Intermediario_Endereco_Cidade_Nome` | Texto livre | Nome da cidade do intermediário |
| `Intermediario_Endereco_Estado` | UF | Estado do intermediário |

### Destinatário (quando diferente do tomador)

> Quando o destinatário for preenchido, é obrigatório informar o valor `DifferentFromBuyer` no campo `IBSCBS_Indicador_Destino` dentro do grupo IBS/CBS.

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Destinatario_Tipo` | `Undefined`, `NaturalPerson`, `LegalEntity` | Tipo do destinatário (Pessoa Física ou Jurídica) |
| `Destinatario_Nome` | Texto livre | Nome ou Razão Social do destinatário |
| `Destinatario_CPF_CNPJ` | CPF ou CNPJ | CPF ou CNPJ do destinatário |
| `Destinatario_Inscricao_Municipal` | Texto livre | Inscrição municipal do destinatário |
| `Destinatario_Inscricao_Estadual` | Texto livre | Inscrição estadual do destinatário |
| `Destinatario_Regime_Tributario` | `Isento`, `MicroempreendedorIndividual`, `SimplesNacional`, `LucroPresumido`, `LucroReal` | Regime tributário do destinatário |
| `Destinatario_CAEPF` | Numérico | Cadastro de Atividade Econômica da Pessoa Física do destinatário (máx. 14 dígitos) |
| `Destinatario_Motivo_Sem_NIF` | `NotInformedOriginal`, `Exempted`, `NotRequired` | Justificativa para ausência de NIF do destinatário |
| `Destinatario_Telefone` | Texto livre | Telefone do destinatário |
| `Destinatario_Email` | Email | Email do destinatário |
| `Destinatario_Endereco_Pais` | Código ISO 3166-1 | País do destinatário |
| `Destinatario_Endereco_Cep` | CEP | CEP do destinatário |
| `Destinatario_Endereco_Logradouro` | Texto livre | Logradouro do destinatário |
| `Destinatario_Endereco_Numero` | Texto livre | Número do endereço do destinatário |
| `Destinatario_Endereco_Complemento` | Texto livre | Complemento do endereço do destinatário |
| `Destinatario_Endereco_Bairro` | Texto livre | Bairro do destinatário |
| `Destinatario_Endereco_Cidade_Codigo` | Código IBGE | Código IBGE da cidade do destinatário |
| `Destinatario_Endereco_Cidade_Nome` | Texto livre | Nome da cidade do destinatário |
| `Destinatario_Endereco_Estado` | UF | Estado do destinatário |

### Locação de Bens

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Locacao_Categoria` | `Lease`, `Sublease`, `Leasehold`, `RightOfWay`, `UsePermission` | Categoria da locação (Locação, Sublocação, Arrendamento, Direito de Passagem, Permissão de Uso) |
| `Locacao_Objeto` | `Railway`, `Road`, `Poles`, `Cables`, `Pipelines`, `Conduits` | Objeto da locação (Ferrovia, Rodovia, Postes, Cabos, Dutos, Condutos) |
| `Locacao_Extensao` | Numérico | Extensão em metros |
| `Locacao_Numero_Postes` | Numérico inteiro | Quantidade de postes |

### Benefício Municipal

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Beneficio_ID` | Texto livre | Identificador do benefício fiscal municipal |
| `Beneficio_Valor` | Numérico | Valor do benefício |
| `Beneficio_Percentual` | Numérico (%) | Percentual do benefício |

### Suspensão de Exigibilidade

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Suspensao_Motivo` | `Judicial`, `Administrative` | Motivo da suspensão da exigibilidade (Decisão Judicial ou Procedimento Administrativo) |
| `Suspensao_Numero_Processo` | Texto livre | Número do processo judicial ou administrativo |

### Tipo de Imunidade

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Tipo_Imunidade` | `Unspecified`, `PublicEntitiesMutual`, `Temples`, `PartiesUnionsEducationSocialNonprofit`, `BooksPressPaper`, `BrazilianMusicPhonograms` | Tipo de imunidade tributária (CF88, Art 150, VI) |

### Tipo de Retenção

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Tipo_Retencao` | `NotWithheld`, `WithheldByBuyer`, `WithheldByIntermediary` | Tipo de retenção do ISSQN (Não Retido, Retido pelo Tomador, Retido pelo Intermediário) |

### Tributos Aproximados (Lei 12.741/2012)

> Os campos de tributos aproximados atendem à Lei 12.741/2012 ("Lei De Olho no Imposto"). Você pode usar a **estrutura simplificada** (totais consolidados) ou a **estrutura detalhada** (por esfera governamental).

#### Estrutura Simplificada

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Tributos_Aproximados_Fonte` | Texto livre | Fonte da informação (ex: IBPT) |
| `Tributos_Aproximados_Versao` | Texto livre | Versão da tabela (ex: 24.1.A) |
| `Tributos_Aproximados_Percentual_Total` | Numérico (%) | Percentual total da carga tributária |
| `Tributos_Aproximados_Valor_Total` | Numérico | Valor total aproximado dos tributos |

#### Estrutura Detalhada

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Tributos_Aproximados_Federal_Percentual` | Numérico (%) | Percentual de tributos federais |
| `Tributos_Aproximados_Federal_Valor` | Numérico | Valor de tributos federais |
| `Tributos_Aproximados_Estadual_Percentual` | Numérico (%) | Percentual de tributos estaduais |
| `Tributos_Aproximados_Estadual_Valor` | Numérico | Valor de tributos estaduais |
| `Tributos_Aproximados_Municipal_Percentual` | Numérico (%) | Percentual de tributos municipais |
| `Tributos_Aproximados_Municipal_Valor` | Numérico | Valor de tributos municipais |
| `Tributos_Aproximados_Detalhado_Percentual_Total` | Numérico (%) | Percentual total agregado dos tributos aproximados detalhados |
| `Tributos_Aproximados_Detalhado_Valor_Total` | Numérico | Valor total agregado dos tributos aproximados detalhados |
| `Tributos_Aproximados_SN_Valor` | Numérico | **Obsoleto.** Substituído por `Tributos_Aproximados_Detalhado_Percentual_Total`/`Tributos_Aproximados_Detalhado_Valor_Total`. Valor do Simples Nacional |
| `Tributos_Aproximados_Total` | Numérico | **Obsoleto.** Substituído por `Tributos_Aproximados_Detalhado_Valor_Total`. Valor total dos tributos |
| `Tributos_Aproximados_Indicador` | `None`, `OptOut` | **Obsoleto.** Indicador se deve informar os totais |

### Substituição de NFS-e

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Substituicao_Chave_NFSe` | Texto livre | Chave da NFS-e a ser substituída (44 dígitos) |
| `Substituicao_Motivo` | `SnOut`, `SnIn`, `ImmunityAddRetro`, `ImmunityRemoveRetro`, `RejectionBuyerOrIntermediary`, `Other` | Motivo da substituição |
| `Substituicao_Motivo_Texto` | Texto livre | Descrição do motivo (obrigatório quando motivo = Other) |

### Informações Adicionais Estruturadas

> Além do campo `Informacoes_Adicionais` (texto livre), você pode estruturar informações específicas:

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Info_Adicional_ART_RRT` | Texto livre | Documento de responsabilidade técnica (ART/RRT) |
| `Info_Adicional_Documento_Referencia` | Texto livre | Documento referenciado |
| `Info_Adicional_Pedido` | Texto livre | Número do pedido/ordem de compra |
| `Info_Adicional_Itens_Pedido` | Texto livre | Itens do pedido separados por vírgula ou ponto e vírgula (ex: Item A, Item B ou Item A; Item B; Item C) |
| `Info_Adicional_Outras` | Texto livre | Outras informações complementares |

### Documento de Dedução (grupo `deduction.documents`)

> Use este grupo para detalhar **um documento fiscal** que justifique uma dedução/redução da base de cálculo do ISSQN, alinhado ao padrão da NFS-e Nacional. É a forma mais completa e recomendada quando você possui os dados do documento que embasa a dedução, e o sistema de emissão prioriza estes campos em relação ao `Valor_Deducoes`.
>
> ⚠️ **Um documento por nota**: como a planilha prevê apenas uma nota por linha, é permitido preencher **apenas um** documento de dedução por NFS-e. Para enviar múltiplos documentos por nota, utilize a [API REST](/docs/documentacao/nota-fiscal-servico-eletronica/primeiros-passos).
>
> **Regras de preenchimento**:
> - Pelo menos **um** dos campos identificadores (`Deducao_Documento_Chave_NFSe_Nacional`, `Deducao_Documento_Chave_NFe`, o bloco `Deducao_Documento_NFSe_Municipal_*`, `Deducao_Documento_Numero_Documento_Fiscal` ou `Deducao_Documento_Numero_Documento_Nao_Fiscal`) é obrigatório quando o grupo é utilizado. Se mais de um identificador for enviado, o backend aplica a precedência nessa ordem.
> - Quando qualquer campo do grupo é preenchido, os campos `Deducao_Documento_Tipo`, `Deducao_Documento_Data_Emissao`, `Deducao_Documento_Valor_Dedutivel` e `Deducao_Documento_Valor_Utilizado` **passam a ser obrigatórios**.
> - Quando `Deducao_Documento_Tipo = Other`, o campo `Deducao_Documento_Outra_Descricao` **passa a ser obrigatório**.
> - Quando qualquer um dos campos do bloco `Deducao_Documento_NFSe_Municipal_*` é preenchido, **os três** (`Codigo_Cidade`, `Numero`, `Codigo_Verificacao`) devem ser preenchidos.
> - `Deducao_Documento_Valor_Utilizado` deve ser **menor ou igual** a `Deducao_Documento_Valor_Dedutivel`.

#### Identificadores do documento (ao menos um é obrigatório)

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Deducao_Documento_Chave_NFSe_Nacional` | 50 dígitos | Chave de acesso da NFS-e nacional (`chNFSe`). |
| `Deducao_Documento_Chave_NFe` | 44 dígitos | Chave de acesso da NF-e de produto (`chNFe`). |
| `Deducao_Documento_NFSe_Municipal_Codigo_Cidade` | Código IBGE | Código IBGE do município emissor (`cMunNFSeMun`). |
| `Deducao_Documento_NFSe_Municipal_Numero` | Texto (máx. 15) | Número da NFS-e municipal (`nNFSeMun`). |
| `Deducao_Documento_NFSe_Municipal_Codigo_Verificacao` | Texto (máx. 9) | Código de verificação da NFS-e municipal (`cVerifNFSeMun`). |
| `Deducao_Documento_Numero_Documento_Fiscal` | Texto (máx. 255) | Identificador de outro documento fiscal não eletrônico (`nDocFisc`). |
| `Deducao_Documento_Numero_Documento_Nao_Fiscal` | Texto (máx. 255) | Identificador de documento não fiscal, ex: nota de débito interna (`nDoc`). |

#### Dados obrigatórios do documento

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Deducao_Documento_Tipo` | `FoodAndBeverages`, `Materials`, `ConsortiumPassThrough`, `HealthPlanPassThrough`, `Services`, `Subcontracting`, `Other` | Tipo da dedução/redução (`tpDedRed`). Valores: Alimentação/bebidas, Materiais, Repasse consorciado, Repasse plano de saúde, Serviços, Subempreitada de mão de obra, Outras. |
| `Deducao_Documento_Outra_Descricao` | Texto livre (máx. 150) | Descrição livre da dedução (`xDescOutDed`). Obrigatório quando `Deducao_Documento_Tipo = Other`. |
| `Deducao_Documento_Data_Emissao` | YYYY-MM-DD | Data de emissão do documento de origem (`dtEmiDoc`). |
| `Deducao_Documento_Valor_Dedutivel` | Numérico | Valor total dedutível/redutível no documento de origem (`vDedutivelRedutivel`). |
| `Deducao_Documento_Valor_Utilizado` | Numérico | Valor efetivamente utilizado como dedução nesta NFS-e (`vDeducaoReducao`). Deve ser ≤ `Deducao_Documento_Valor_Dedutivel`. |

#### Fornecedor do documento (opcional)

> Dados do emitente do documento que embasa a dedução (`fornec`). Baseado em `partyDefinition`.

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Deducao_Documento_Fornecedor_Tipo` | `Undefined`, `NaturalPerson`, `LegalEntity` | Tipo do fornecedor (Pessoa Física ou Jurídica). |
| `Deducao_Documento_Fornecedor_Nome` | Texto livre (máx. 115) | Nome ou Razão Social do fornecedor. |
| `Deducao_Documento_Fornecedor_CPF_CNPJ` | CPF ou CNPJ | CPF ou CNPJ do fornecedor. Pode ser com ou sem formatação. |
| `Deducao_Documento_Fornecedor_Endereco_Pais` | Código ISO 3166-1 | País do fornecedor (ex: BRA). |
| `Deducao_Documento_Fornecedor_Endereco_Cep` | CEP | CEP do endereço do fornecedor. |
| `Deducao_Documento_Fornecedor_Endereco_Logradouro` | Texto livre | Logradouro do fornecedor. |
| `Deducao_Documento_Fornecedor_Endereco_Numero` | Texto livre | Número do endereço do fornecedor. |
| `Deducao_Documento_Fornecedor_Endereco_Complemento` | Texto livre | Complemento do endereço do fornecedor. |
| `Deducao_Documento_Fornecedor_Endereco_Bairro` | Texto livre | Bairro do fornecedor. |
| `Deducao_Documento_Fornecedor_Endereco_Cidade_Codigo` | Código IBGE | Código IBGE da cidade do fornecedor (7 dígitos). |
| `Deducao_Documento_Fornecedor_Endereco_Cidade_Nome` | Texto livre | Nome da cidade do fornecedor. |
| `Deducao_Documento_Fornecedor_Endereco_Estado` | UF | Sigla do estado do fornecedor (ex: SP). |

### Documento de Reembolso a Terceiros (grupo `ibsCbs.thirdPartyReimbursements.documents`)

> Use este grupo para detalhar **um documento** que justifique um valor de **reembolso ou repasse a terceiros** no contexto da Reforma Tributária (IBS/CBS). Exemplos típicos: corretagem imobiliária com repasse, agência de viagens repassando ao fornecedor, agência de publicidade reembolsando produção externa ou mídia.
>
> ⚠️ **Um documento por nota**: como a planilha prevê apenas uma nota por linha, é permitido preencher **apenas um** documento de reembolso a terceiros por NFS-e. Para enviar múltiplos documentos por nota, utilize a [API REST](/docs/documentacao/nota-fiscal-servico-eletronica/primeiros-passos).
>
> **Regras de preenchimento**:
> - Pelo menos **um** dos identificadores (`Reembolso_Terceiros_Documento_Chave_NFSe_Nacional`, `Reembolso_Terceiros_Documento_Chave_NFe`, `Reembolso_Terceiros_Documento_Chave_CTe`, o bloco `Reembolso_Terceiros_Documento_Outro_DFe_Nacional_*`, o bloco `Reembolso_Terceiros_Documento_Outro_Doc_Fiscal_*` ou o bloco `Reembolso_Terceiros_Documento_Outro_Doc_Nao_Fiscal_*`) é obrigatório quando o grupo é utilizado. Se mais de um identificador for enviado, o backend aplica a precedência nessa ordem.
> - Quando qualquer campo do grupo é preenchido, os campos `Reembolso_Terceiros_Documento_Data_Emissao`, `Reembolso_Terceiros_Documento_Data_Competencia`, `Reembolso_Terceiros_Documento_Tipo` e `Reembolso_Terceiros_Documento_Valor` **passam a ser obrigatórios**.
> - Quando `Reembolso_Terceiros_Documento_Tipo = OtherReimbursement`, o campo `Reembolso_Terceiros_Documento_Tipo_Descricao` **passa a ser obrigatório**.
> - Quando o bloco `Reembolso_Terceiros_Documento_Outro_DFe_Nacional_*` é utilizado, o campo `Outro_DFe_Nacional_Tipo_Texto` **passa a ser obrigatório** (`Outro_DFe_Nacional_Chave` é opcional).
> - Quando o bloco `Reembolso_Terceiros_Documento_Outro_Doc_Fiscal_*` é utilizado, os campos `Outro_Doc_Fiscal_Codigo_Cidade_Emissor` e `Outro_Doc_Fiscal_Numero` **são obrigatórios**.
> - Quando o bloco `Reembolso_Terceiros_Documento_Outro_Doc_Nao_Fiscal_*` é utilizado, os campos `Outro_Doc_Nao_Fiscal_Numero` e `Outro_Doc_Nao_Fiscal_Descricao` **são obrigatórios**.

#### Identificador do documento (`anyOf` — escolha exatamente um caminho)

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Reembolso_Terceiros_Documento_Chave_NFSe_Nacional` | Texto (máx. 50) | Chave de acesso da NFS-e Nacional (`chNFSe`). |
| `Reembolso_Terceiros_Documento_Chave_NFe` | 44 dígitos | Chave de acesso da NF-e (`chNFe`). |
| `Reembolso_Terceiros_Documento_Chave_CTe` | 44 dígitos | Chave de acesso do CT-e (`chCTe`). |
| `Reembolso_Terceiros_Documento_Outro_DFe_Nacional_Chave` | Texto livre | Chave de outro DF-e nacional (`chDFE`). **Obrigatório quando o bloco `Outro_DFe_Nacional_*` é utilizado.** |
| `Reembolso_Terceiros_Documento_Outro_DFe_Nacional_Tipo_Texto` | Texto livre | Descrição textual do tipo de DF-e (`xTpDFE`), ex: `NFS-e`, `NF-e`, `CT-e`. **Obrigatório quando o bloco `Outro_DFe_Nacional_*` é utilizado.** |
| `Reembolso_Terceiros_Documento_Outro_DFe_Nacional_Tipo` | Texto (1 caractere) | Código numérico do tipo de DF-e (`tipoChaveDFE`). Validação fraca no backend — sem enum oficial. |
| `Reembolso_Terceiros_Documento_Outro_Doc_Fiscal_Codigo_Cidade_Emissor` | Código IBGE | Código IBGE do município emissor do documento fiscal (`cMunEmiDocFisc`). **Obrigatório quando o bloco `Outro_Doc_Fiscal_*` é utilizado.** |
| `Reembolso_Terceiros_Documento_Outro_Doc_Fiscal_Numero` | Texto livre | Número do documento fiscal (`nDocFisc`). **Obrigatório quando o bloco `Outro_Doc_Fiscal_*` é utilizado.** |
| `Reembolso_Terceiros_Documento_Outro_Doc_Fiscal_Descricao` | Texto livre | Descrição complementar do documento fiscal (`xDocFisc`). |
| `Reembolso_Terceiros_Documento_Outro_Doc_Nao_Fiscal_Numero` | Texto livre | Número do documento não fiscal (`nDoc`). **Obrigatório quando o bloco `Outro_Doc_Nao_Fiscal_*` é utilizado.** |
| `Reembolso_Terceiros_Documento_Outro_Doc_Nao_Fiscal_Descricao` | Texto livre | Descrição do documento não fiscal (`xDoc`). **Obrigatório quando o bloco `Outro_Doc_Nao_Fiscal_*` é utilizado.** |

#### Dados obrigatórios do documento

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Reembolso_Terceiros_Documento_Data_Emissao` | YYYY-MM-DD | Data de emissão do documento que originou o reembolso/repasse (`dtEmiDoc`). |
| `Reembolso_Terceiros_Documento_Data_Competencia` | YYYY-MM-DD | Data de competência do reembolso/repasse (`dtCompDoc`). |
| `Reembolso_Terceiros_Documento_Tipo` | `RealEstateBrokerPassThrough`, `TravelAgencySupplierPassThrough`, `AdAgencyExternalProductionReimbursement`, `AdAgencyMediaReimbursement`, `OtherReimbursement` | Tipo do reembolso/repasse (`tpReemb`). Valores: Repasse de corretagem imobiliária, Repasse de fornecedor de agência de viagens, Reembolso de produção externa de agência de publicidade, Reembolso de mídia de agência de publicidade, Outro reembolso. |
| `Reembolso_Terceiros_Documento_Tipo_Descricao` | Texto livre (máx. 150) | Descrição livre do reembolso (`xReembOutros`). Obrigatório quando `Reembolso_Terceiros_Documento_Tipo = OtherReimbursement`. |
| `Reembolso_Terceiros_Documento_Valor` | Numérico | Valor do reembolso/repasse a terceiros (`vReemb`). |

#### Fornecedor do documento (opcional)

> Dados do fornecedor (terceiro) que recebeu o repasse/reembolso (`fornec`). Baseado em `partyDefinition`.

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Reembolso_Terceiros_Documento_Fornecedor_Tipo` | `Undefined`, `NaturalPerson`, `LegalEntity` | Tipo do fornecedor (Pessoa Física ou Jurídica). |
| `Reembolso_Terceiros_Documento_Fornecedor_Nome` | Texto livre (máx. 115) | Nome ou Razão Social do fornecedor. |
| `Reembolso_Terceiros_Documento_Fornecedor_CPF_CNPJ` | CPF ou CNPJ | CPF ou CNPJ do fornecedor. Pode ser com ou sem formatação. |
| `Reembolso_Terceiros_Documento_Fornecedor_Endereco_Pais` | Código ISO 3166-1 | País do fornecedor (ex: BRA). |
| `Reembolso_Terceiros_Documento_Fornecedor_Endereco_Cep` | CEP | CEP do endereço do fornecedor. |
| `Reembolso_Terceiros_Documento_Fornecedor_Endereco_Logradouro` | Texto livre | Logradouro do fornecedor. |
| `Reembolso_Terceiros_Documento_Fornecedor_Endereco_Numero` | Texto livre | Número do endereço do fornecedor. |
| `Reembolso_Terceiros_Documento_Fornecedor_Endereco_Complemento` | Texto livre | Complemento do endereço do fornecedor. |
| `Reembolso_Terceiros_Documento_Fornecedor_Endereco_Bairro` | Texto livre | Bairro do fornecedor. |
| `Reembolso_Terceiros_Documento_Fornecedor_Endereco_Cidade_Codigo` | Código IBGE | Código IBGE da cidade do fornecedor (7 dígitos). |
| `Reembolso_Terceiros_Documento_Fornecedor_Endereco_Cidade_Nome` | Texto livre | Nome da cidade do fornecedor. |
| `Reembolso_Terceiros_Documento_Fornecedor_Endereco_Estado` | UF | Sigla do estado do fornecedor (ex: SP). |

### Detalhes de Valores do Serviço

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `Valor_Inicial_Cobrado` | Numérico | Valor inicial cobrado pelo serviço (antes de tributos, multa e juros) |
| `Valor_Final_Cobrado` | Numérico | Valor final cobrado pelo serviço (incluindo todos os tributos) |
| `Valor_Multa` | Numérico | Valor de multa aplicada |
| `Valor_Juros` | Numérico | Valor de juros aplicados |

### IBS/CBS (Reforma Tributária)

> **Nota sobre a Reforma Tributária**:
> Os campos de IBS/CBS são utilizados para operações que seguem o novo modelo tributário brasileiro (Reforma Tributária). Esses campos são **opcionais** e devem ser preenchidos apenas quando aplicável à operação.
>
> ⚠️ **Regra de Obrigatoriedade Condicional**:
> Se **qualquer um** dos campos `IBSCBS_Indicador_Operacao` ou `IBSCBS_Codigo_Classificacao` for preenchido, **ambos se tornam obrigatórios**.
>
> **Saiba mais sobre a Reforma Tributária:**
> - [Documentação do Layout de Emissão de NFS-e (RTC)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/) - Documentação funcional completa
> - [Mudanças no Layout de Integração da NFS-e (v4)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/mudancas-layout-integracao-nfse-v4/) - Mudanças entre versões
> - [Tabela de CST e Classificação Tributária (IBS/CBS)](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-cst-classificacao-tributaria-ibs-cbs/) - Lista completa de códigos CST e cClassTrib
> - [Tabela de Indicador da Operação](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-indicador-operacao/) - Códigos de operação (indOp)

#### Dados Gerais do IBS/CBS

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `IBSCBS_Indicador_Operacao` | Código `indOp` (ex: `020101`, `030101`, `100301`) | **Condicionalmente obrigatório.** Indicador da operação que determina o local de incidência do IBS/CBS, conforme Art. 11 da LC nº 214/2025. [Consulte a tabela completa](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-indicador-operacao/) |
| `IBSCBS_Codigo_Classificacao` | Código `cClassTrib` (ex: `000001`, `200028`) | **Condicionalmente obrigatório.** Código de Classificação Tributária que define o regime e alíquotas aplicáveis (ex: tributação integral, alíquota reduzida). [Consulte a tabela de CST/cClassTrib](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-cst-classificacao-tributaria-ibs-cbs/) |
| `IBSCBS_Codigo_Situacao` | Código CST (ex: `000`, `200`, `400`) | Código da Situação Tributária do IBS/CBS. O CST indica o tratamento tributário da operação (tributação integral, alíquota zero, imunidade, etc.). [Consulte a tabela de CST](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-cst-classificacao-tributaria-ibs-cbs/) |
| `IBSCBS_Finalidade` | `regular` | Finalidade da operação (atualmente apenas `regular` é aceito) |
| `IBSCBS_Indicador_Destino` | `SameAsBuyer`, `DifferentFromBuyer` | Indicador de destino (mesmo que o tomador ou diferente do tomador) |
| `IBSCBS_Tipo_Operacao` | Texto livre | Tipo de operação do IBS/CBS |
| `IBSCBS_Uso_Consumo_Pessoal` | `true`, `false` | Indica se é para uso/consumo pessoal do adquirente |
| `IBSCBS_Base_Calculo` | Numérico | Base de cálculo do IBS/CBS |
| `IBSCBS_Valor_Reembolso_Repasse` | Numérico | Valor de reembolso ou repasse |
| `IBSCBS_Valor_Deducao_Reducao` | Numérico | Valor de dedução ou redução |
| `IBSCBS_Doacao` | `true`, `false` | Indicador de doação |

#### IBS Estadual

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `IBS_Estadual_Aliquota` | Numérico (%) | Alíquota do IBS estadual |
| `IBS_Estadual_Reducao_Aliquota` | Numérico (%) | Percentual de redução da alíquota |
| `IBS_Estadual_Aliquota_Efetiva` | Numérico (%) | Alíquota efetiva após reduções |
| `IBS_Estadual_Valor` | Numérico | Valor calculado do IBS estadual |
| `IBS_Estadual_Diferimento_Percentual` | Numérico (%) | Percentual de diferimento |
| `IBS_Estadual_Diferimento_Valor` | Numérico | Valor diferido |
| `IBS_Estadual_Valor_Devolvido` | Numérico | Valor devolvido (cashback) |

#### IBS Municipal

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `IBS_Municipal_Aliquota` | Numérico (%) | Alíquota do IBS municipal |
| `IBS_Municipal_Reducao_Aliquota` | Numérico (%) | Percentual de redução da alíquota |
| `IBS_Municipal_Aliquota_Efetiva` | Numérico (%) | Alíquota efetiva após reduções |
| `IBS_Municipal_Valor` | Numérico | Valor calculado do IBS municipal |
| `IBS_Municipal_Diferimento_Percentual` | Numérico (%) | Percentual de diferimento |
| `IBS_Municipal_Diferimento_Valor` | Numérico | Valor diferido |
| `IBS_Municipal_Valor_Devolvido` | Numérico | Valor devolvido (cashback) |

#### IBS Total

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `IBS_Total` | Numérico | Valor total do IBS (estadual + municipal) |

#### CBS (Contribuição sobre Bens e Serviços)

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `CBS_Aliquota` | Numérico (%) | Alíquota da CBS |
| `CBS_Reducao_Aliquota` | Numérico (%) | Percentual de redução da alíquota |
| `CBS_Aliquota_Efetiva` | Numérico (%) | Alíquota efetiva após reduções |
| `CBS_Valor` | Numérico | Valor calculado da CBS |
| `CBS_Diferimento_Percentual` | Numérico (%) | Percentual de diferimento |
| `CBS_Diferimento_Valor` | Numérico | Valor diferido |
| `CBS_Valor_Devolvido` | Numérico | Valor devolvido (cashback) |

#### Imóvel vinculado ao IBS/CBS

> Campos para informar dados de imóvel especificamente vinculados à apuração do IBS/CBS. Diferente da seção "Imóvel" acima, que trata do imóvel no contexto geral da NFS-e.

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `IBSCBS_Imovel_Inscricao_Imobiliaria` | Texto livre | Inscrição imobiliária do imóvel vinculado ao IBS/CBS |
| `IBSCBS_Imovel_CIB` | Texto livre | Código de Identificação de Bens do imóvel vinculado ao IBS/CBS |
| `IBSCBS_Imovel_Endereco_Pais` | Código ISO 3166-1 | País do imóvel (ex: BRA) |
| `IBSCBS_Imovel_Endereco_Cep` | CEP | CEP do imóvel |
| `IBSCBS_Imovel_Endereco_Logradouro` | Texto livre | Logradouro do imóvel |
| `IBSCBS_Imovel_Endereco_Numero` | Texto livre | Número do endereço do imóvel |
| `IBSCBS_Imovel_Endereco_Complemento` | Texto livre | Complemento do endereço do imóvel |
| `IBSCBS_Imovel_Endereco_Bairro` | Texto livre | Bairro do imóvel |
| `IBSCBS_Imovel_Endereco_Cidade_Codigo` | Código IBGE | Código IBGE da cidade do imóvel |
| `IBSCBS_Imovel_Endereco_Cidade_Nome` | Texto livre | Nome da cidade do imóvel |
| `IBSCBS_Imovel_Endereco_Estado` | UF | Estado do imóvel (ex: SP) |

#### Transferência de Crédito (IBS/CBS)

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `IBSCBS_Transferencia_Credito_IBS` | Numérico | Valor da transferência de crédito de IBS |
| `IBSCBS_Transferencia_Credito_CBS` | Numérico | Valor da transferência de crédito de CBS |

#### Tributação Regular (IBS/CBS)

> Campos para informar dados da tributação pelo regime regular, quando a operação possui tratamento diferenciado no grupo principal de IBS/CBS (ex: imunidade, isenção) mas também precisa informar os valores que seriam devidos na tributação regular.

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `IBSCBS_Trib_Regular_Codigo_Situacao` | Código CST | Código da Situação Tributária da tributação regular |
| `IBSCBS_Trib_Regular_Codigo_Classificacao` | Código cClassTrib | Código de Classificação Tributária da tributação regular |
| `IBSCBS_Trib_Regular_IBS_Total` | Numérico | Valor total do IBS na tributação regular |
| `IBSCBS_Trib_Regular_IBS_Estadual_Aliquota_Efetiva` | Numérico (%) | Alíquota efetiva do IBS estadual na tributação regular |
| `IBSCBS_Trib_Regular_IBS_Estadual_Valor` | Numérico | Valor do IBS estadual na tributação regular |
| `IBSCBS_Trib_Regular_IBS_Municipal_Aliquota_Efetiva` | Numérico (%) | Alíquota efetiva do IBS municipal na tributação regular |
| `IBSCBS_Trib_Regular_IBS_Municipal_Valor` | Numérico | Valor do IBS municipal na tributação regular |
| `IBSCBS_Trib_Regular_CBS_Aliquota_Efetiva` | Numérico (%) | Alíquota efetiva da CBS na tributação regular |
| `IBSCBS_Trib_Regular_CBS_Valor` | Numérico | Valor da CBS na tributação regular |

#### Crédito Presumido (IBS/CBS)

> Campos para informar dados de crédito presumido do IBS e CBS, quando aplicável à operação.

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `IBSCBS_Credito_Presumido_IBS_Codigo` | Texto livre | Código do crédito presumido de IBS |
| `IBSCBS_Credito_Presumido_IBS_Aliquota` | Numérico (%) | Alíquota do crédito presumido de IBS |
| `IBSCBS_Credito_Presumido_IBS_Valor` | Numérico | Valor do crédito presumido de IBS |
| `IBSCBS_Credito_Presumido_IBS_Valor_Condicional` | Numérico | Valor condicional do crédito presumido de IBS |
| `IBSCBS_Credito_Presumido_CBS_Codigo` | Texto livre | Código do crédito presumido de CBS |
| `IBSCBS_Credito_Presumido_CBS_Aliquota` | Numérico (%) | Alíquota do crédito presumido de CBS |
| `IBSCBS_Credito_Presumido_CBS_Valor` | Numérico | Valor do crédito presumido de CBS |
| `IBSCBS_Credito_Presumido_CBS_Valor_Condicional` | Numérico | Valor condicional do crédito presumido de CBS |

#### Compra Governamental (IBS/CBS)

> Campos para operações de venda de serviços para órgãos governamentais, com tratamento tributário específico.

| Campo/Coluna | Possíveis Valores | Descrição |
|--------------|-------------------|-----------|
| `IBSCBS_Compra_Gov_Tipo_Entidade` | `federal`, `state`, `municipal` | Tipo de entidade governamental compradora |
| `IBSCBS_Compra_Gov_IBS_Total` | Numérico | Valor total do IBS na compra governamental |
| `IBSCBS_Compra_Gov_IBS_Estadual_Aliquota` | Numérico (%) | Alíquota do IBS estadual na compra governamental |
| `IBSCBS_Compra_Gov_IBS_Estadual_Valor` | Numérico | Valor do IBS estadual na compra governamental |
| `IBSCBS_Compra_Gov_IBS_Municipal_Aliquota` | Numérico (%) | Alíquota do IBS municipal na compra governamental |
| `IBSCBS_Compra_Gov_IBS_Municipal_Valor` | Numérico | Valor do IBS municipal na compra governamental |
| `IBSCBS_Compra_Gov_CBS_Aliquota` | Numérico (%) | Alíquota da CBS na compra governamental |
| `IBSCBS_Compra_Gov_CBS_Valor` | Numérico | Valor da CBS na compra governamental |

---

> ⚠️ **Atenção:** Evite adicionar fórmulas, índices ou qualquer tipo de alteração no excel. Isso pode gerar problemas ao capturar os dados do excel.

## Próximos passos

* [Listar notas fiscais de serviço](/docs/documentacao/nossa-plataforma/nota-fiscal-servico/listar-notas-servico)
* [Cancelar uma nota fiscal de serviço](/docs/documentacao/nossa-plataforma/nota-fiscal-servico/cancelar-nota-servico)

## Documentação relacionada

* [Conceitos sobre NFS-e](/docs/documentacao/nota-fiscal-servico-eletronica/conceitos) - Entenda o que é NFS-e, CNAE, Código de Serviço e Inscrição Municipal
* [Primeiros passos para integração via API](/docs/documentacao/nota-fiscal-servico-eletronica/primeiros-passos) - Para quem deseja integrar via API REST
* [Motor de Cálculo de Tributos](/docs/documentacao/nota-fiscal-eletronica/motor-de-calculo-de-imposto) - Calcule impostos automaticamente
* [Qual código de serviço utilizar?](/docs/duvidas-frequentes/qual-codigo-servico-utilizar) - Dúvidas sobre códigos de serviço

### Reforma Tributária (IBS/CBS)

* [Documentação do Layout de Emissão de NFS-e (RTC)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/) - Documentação funcional completa do novo layout
* [Mudanças no Layout de Integração da NFS-e (v4)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/mudancas-layout-integracao-nfse-v4/) - Comparativo entre layouts antigo e novo
* [Tabela de CST e Classificação Tributária](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-cst-classificacao-tributaria-ibs-cbs/) - Códigos CST e cClassTrib (obrigatório para preencher `IBSCBS_Codigo_Classificacao` e `IBSCBS_Codigo_Situacao`)
* [Tabela de Indicador da Operação](/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-indicador-operacao/) - Códigos indOp (obrigatório para preencher `IBSCBS_Indicador_Operacao`)

---

## Como Listar Notas Fiscais de Serviço em nossa plataforma - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/nota-fiscal-servico/listar-notas-servico/index.md

# Listar Notas Fiscais de Serviço

Aqui você entenderá como listar as notas fiscais de serviço usando nossa plataforma, bem como os próximos passos e materias relacionados.

## Ao final desse tutorial, você será capaz de:

* [Listar Notas Fiscais de Serviço][6]

## Requisitos

* [Criar uma conta][6]
* [Criar uma empresa][7]
* [Emitir uma nota fiscal de serviço][8]

## 1\. Listar Notas Fiscais de Serviço

1. Clique no Menu **EMPRESA**  
![plataforma nfe.io](https://nfe.io/docs/static/docs/plataforma/company-page-5.png)
2. Clique no botão **LISTAR NOTAS FISCAIS**  
![nota fiscal na plataforma](https://nfe.io/docs/static/docs/plataforma/list-service-invoice.png)
3. Você verá uma tela parecida com essa  
![](https://nfe.io/docs/static/docs/plataforma/list-service-invoice-items.png)

## Próximos passos

* [Emitir uma nota fiscal de serviço][8]
* [Cancelar uma nota fiscal de serviço][9]

[1]: #Listar%5FNotas%5FFiscais%5Fde%5FServico
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Requisitos
[4]: #1%5FListar%5FNotas%5FFiscais%5Fde%5FServico
[5]: #Proximos%5Fpassos
[6]: https://nfe.io/docs/nossa-plataforma/criar-conta/
[7]: https://nfe.io/docs/nossa-plataforma/criar-empresa/
[8]: https://nfe.io/docs/nossa-plataforma/nota-fiscal-servico/emitir-nota-servico/
[9]: https://nfe.io/docs/nossa-plataforma/nota-fiscal-servico/cancelar-nota-servico/

---

## Upload do Certificado Digital na plataforma da NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nossa-plataforma/upload-do-certificado-digital/index.md

# Upload do Certificado Digital

O upload do **certificado digital A1** é obrigatório para emitir notas no ambiente de **produção**. Em **sandbox**, o envio é opcional e pode ser feito a qualquer momento pelo painel da empresa.

## Ao final desse tutorial você será capaz de:

- Enviar um certificado digital A1 pelo painel da empresa
- Substituir um certificado vencido ou prestes a vencer

## Requisitos

- [Criar uma conta](./criar-conta.md)
- [Criar uma empresa](./criar-empresa.md)
- Certificado digital **A1** válido em arquivo `.pfx` ou `.p12`, com o CNPJ correspondente ao da empresa

:::info
A NFE.io aceita somente certificados **A1**. Certificados A3 (em token ou cartão) não são suportados, pois exigem hardware físico para assinar cada documento.
:::

## 1. Abrir o painel da empresa

No menu lateral, clique em **Empresas** e selecione a empresa para a qual deseja enviar o certificado. Você será levado para a tela **Gerenciamento da empresa** em `app.nfe.io/companies/<id>`.

![Painel da empresa](https://nfe.io/docs/static/docs/release-2026-2/painel-centralizado-companies.png)

## 2. Abrir a edição da empresa

No topo da página, clique no menu **Ações** e selecione **Alterar Empresa**. Em seguida, abra a seção **Certificado Digital**.

## 3. Enviar o arquivo do certificado

Na seção **Certificado Digital**, siga os passos:

1. Clique em **Escolher arquivo** e selecione o `.pfx` ou `.p12` do certificado.
2. Informe a **senha** do certificado.
3. Clique em **Enviar Certificado Digital**.

![Envio do certificado digital A1](https://nfe.io/docs/static/docs/plataforma/upload-certificate.png)

Após o envio, a plataforma valida o certificado e atualiza:

- **Thumbprint** (impressão digital SHA-1)
- **Validade** (data de expiração)
- **Status** (Active, Overdue, Pending ou Inactive)

:::tip
Acompanhe a data de validade do certificado direto pelo card no painel da empresa. O status muda para **Overdue** quando o certificado vence, e a emissão de notas é bloqueada até que um novo seja enviado.
:::

## Próximos passos

- [Cadastrar uma Inscrição Estadual](./criar-inscricao-estadual.md)
- [Cadastrar uma Inscrição Municipal](./criar-inscricao-municipal.md)
- [Emitir NFS-e em lote](./nota-fiscal-servico/emitir-nota-fiscal-de-servico-em-lote.md)
- [Listar notas fiscais de serviço](./nota-fiscal-servico/listar-notas-fiscais-de-servico.md)

---

## Conceitos

Source: https://nfe.io/docs/documentacao/nota-fiscal-consumidor/conceitos/index.md

## Tudo sobre Nota Fiscal de Consumidor

### O que é Nota Fiscal de Consumidor (NFC-e)?

A Nota Fiscal de Consumidor Eletrônica (NFC-e) é um documento de existência apenas digital, emitido e armazenado eletronicamente, com o intuito de documentar as operações comerciais de venda presencial ou venda para entrega em domicilio feitas ao consumidor final, seja ele pessoa física ou jurídica, em operação interna sem geração de crédito de ICMS ao adquirente.

A NFC-e substitui a nota fiscal de venda a consumidor, modelo 2, e o cupom fiscal emitido por Emissor de Cupom Fiscal (ECF).

O motivo para a migração da tecnologia do ECF para a NFCe, é a possibilidade de maior automatização do processo de emissão de notas, maior agilidade no repasse de informações fiscais e facilitar a fiscalização e o combate à sonegação.

A NFC-e possui um documento auxiliar, chamado DANFE-NFC-e, que contém as informações simplificadas sobre o conteúdo da nota de maneira legível e que deve ser entregue ao consumidor no momento da compra.

### O que é o DANFE-NFC-e?

O Documento Auxiliar da Nota Fiscal de Consumidor Eletrônica, é um comprovante que representa de forma resumida as informações que estão inseridas na NFCe. A DANFE também contém uma chave de acesso e um código de barras QR-Code para que se consulte a regularidade da mesma através de um dispositivo com internet.

O DANFE NFC-e deve ser impresso pelo emitente da NFC-e antes da circulação da mercadoria, na venda presencial ou entrega em domicílio. Vale ressaltar que o destinatário pode dispensar a sua impressão nas vendas presenciais, e pode optar pelo recebimento via e-mail ou SMS.

## Como emitir a NFC-e?

Em alguns estados a emissão da NFC-e já é obrigatória, em outros, ainda está sendo implementada. Para começar a emitir NFC-e, primeiro é preciso certificar-se que você possui os requisitos básicos para a emissão, que são:

* Possuir certificado digital no padrão ICP-Brasil, contendo o CNPJ da empresa;
* Utilizar um software emissor de NFC-e, que pode ser gratuito fornecido por empresas, adquirido ou desenvolvido pela empresa;
* Solicitar o Código de Segurança do Contribuinte - CSC em ambiente de produção disponível no sítio da SEFAZ;
* Estar com a Inscrição Estadual regular;
* Efetuar o credenciamento no site da SEFAZ.

[1]: #Tudo%5Fsobre%5FNota%5FFiscal%5Fde%5FConsumidor
[2]: #O%5Fque%5Fe%5FNota%5FFiscal%5Fde%5FConsumidor%5FNFC-e
[3]: #O%5Fque%5Fe%5Fo%5FDANFE-NFC-e
[4]: #Como%5Femitir%5Fa%5FNFC-e

---

## Credenciamento de nota fiscal de consumidor eletrônica

Source: https://nfe.io/docs/documentacao/nota-fiscal-consumidor/credenciamento/index.md

# Como fazer o credenciamento da nota fiscal de consumidor na SEFAZ?

> Todos os procedimentos para credenciamento de nota fiscal de consumidor citados abaixo servem como um guia, podendo ou não estar faltando tópicos importantes. Por favor, sempre consultar o seu contador de confiança antes de realizar esses procedimentos.

O primeiro passo para se emitir Nota Fiscal de Consumidor eletrônica (NFC-e) é realizar o credenciamento junto à Secretaria da Fazenda (SEFAZ) do estado onde está inserida sua empresa. Com isto o contribuinte está apto para emitir nota fiscal eletrônica, em substituição à nota fiscal em papel modelo 1 ou 1A.

Os requisitos básicos para uma empresa se cadastrar e emitir Nota Fiscal Eletrônica são:

* Possuir certificado Digital do padrão ICP-brasil;
* Ter acesso à internet;
* Possuir programa emissor de NF-e ou utilizar o “Emissor de NF-e” gratuito disponibilizado pela SEFAZ;
* Solicitar o credenciamento junto à SEFAZ.

Leia com atenção as seguintes instruções para solicitação de credenciamento de emissão de NFC-e:

1. O acesso ao sistema é efetuado por meio do mesmo usuário e senha do **contribuinte** utilizado para acessar os serviços do Posto Fiscal Eletrônico - PFE; Atenção: a senha do PFE obtida junto ao Posto Fiscal somente será reconhecido no sistema de credenciamento após um dia útil.
2. Ao acessar o sistema, selecione um estabelecimento e complete ou corrija as informações pré-cadastradas;
3. Ao processar as informações, o estabelecimento já estará autorizado, automaticamente, a realizar os testes de sua solução tecnológica de emissão de NFC-e no ambiente de teste/homologação da SEFAZ-SP. Os testes realizados neste ambiente não serão avaliados pela SEFAZ-SP;
4. Apesar dos testes no ambiente de testes/homologação da SEFAZ-SP não serem obrigatórios, recomendamos fortemente que o contribuinte efetue seus testes antes de solicitar seu credenciamento no ambiente de produção. Para entrar em produção, após realizados todos os testes que julgar necessário, clique no botão "Credenciamento para emitir NF-e em produção".
5. Ao credenciar-se no ambiente de produção, o estabelecimento continuará a ter acesso ao ambiente de testes da SEFAZ-SP para realizar os testes que julgar necessário.

## Consulte também

[Tudo sobre Nota Fiscal de Consumidor][3]  
[Tudo sobre Nota Fiscal de Produto Eletrônica][4]  
[Tudo sobre Nota Fiscal de Serviço][5]


[1]: #Como%5Ffazer%5Fo%5Fcredenciamento%5Fda%5Fnota%5Ffiscal%5Fde%5Fconsumidor%5Fna%5FSEFAZ
[2]: #Consulte%5Ftambem
[3]: https://nfe.io/docs/documentacao/nota-fiscal-consumidor/conceitos/
[4]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/conceitos/
[5]: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/conceitos/

---

## NFC-e - Primeiros passos sobre a integração de Nota Fiscal de Consumidor NFC-e

Source: https://nfe.io/docs/documentacao/nota-fiscal-consumidor/integracao-api/nfc-primeiros-passos/index.md

# Integração Nota Fiscal de Consumidor - NFC-e

Nesse documento você entenderá sobre os primeiros passos para fazer a integração da nota fiscal de consumidor eletrônica.

> A Nota fiscal de consumidor eletrônica é o documento digital fiscal usada para a documentação de operaçóes de circulação de mercadorias ou prestação de serviço do consumidor final, em transações presenciais, dentro do mesmo estado.

**Saiba mais:** [O que é nota fiscal eletrônica?][14]

### Ao final desse tutorial, você será capaz de:

[1\. Cadastrar uma empresa][15]  
[2\. Fazer upload de um certificado na plataforma][16]  
[3\. Cadastrar uma inscrição estadual][17]  
[4\. Emitir uma nota fiscal de consumidor][18]

## Requisitos

* Qual tipo de nota fiscal devo emitir?
* Como fazer o credenciamento da minha empresa para emissão de nota?
* Quer saber mais sobre certificado digital?
* [Desconto para adquirir seu certificado digital A1?][22]

## Tutorial

A partir desse momento faremos uma breve explicação de como realizar a integração de Nota fiscal de Consumidor com a API oferecida pela [NFE.io][23].

**Veja mais sobre a** [Documentação da API][24]

> Essa coleção é exclusiva para NFC-e e você pode realizar a importação da url no Postman para ter todos os seguintes exemplos através do link:

```json
https://www.postman.com/nfe-io/workspace/nfe-io-public-api-demos/collection/29654924-bbda8082-c5fe-4dec-b51c-ff3618402957?action=share&creator=29654924
```

Tutorial de como importar a url no postman [Clique aqui][25]

## Primeiros passos

Antes de tudo, você precisará realizar um cadastro na nossa plataforma [app.nfe.io][26]. Depois, você terá que pegar a chave de autorização do nosso sistema.

> Devemos atentar para copiar a autorização referente 'Nota fiscal'

**Veja como pegar a chave de autorização na plataforma:** [Autenticação][27]

> **Lembre-se:** Após importar a url do postman e copiar a chave de autenticação para nota fiscal eletrônica, você deverá adicionar em cada requisição na aba "Headers" (cabeçalhos) a chave em "Authorization" (autorização).  
> ![integração api](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/authentication-key-modified.png)

## 1\. Criar uma empresa

Para emitir as notas fiscais, é necessário criar uma empresa. Neste momento será obrigatório a identificação do CNPJ, endereço e tipo de regime tributário.

Ao sucesso da requisição, será gerada um chave de identificação (ID), e você deve copiá-la para os passos seguintes.

Abaixo, a url e um json de exemplo contendo os dados para a criação de uma empresa.

> O método HTTP utilizada na criação da empresa é o "POST", portanto, verifique no seu postman se está preenchido corretamente.  
> (Utilize o Create Company na coleção)

`POST: https://api.nfse.io/v2/companies`

```json
 {  
  "company": {
    "name":"RAZAO SOCIAL DA EMPRESA",
    "federalTaxNumber": 58065968000186,
    "taxRegime": "SimplesNacional",
        "address": {  
            "state":"SP",
            "city": {   
                "code":"3550308",
                "name":"São Paulo"
            },
            "district":"BAIRRO",
            "additionalInformation":" INFORMAÇÃO ADICIONAL",
            "street":"AV NOME DA RUA",
            "number":"1111",
            "postalCode":"14940001",
            "country":"BRA"
        }
  } 
```

1.Você deverá enviar os dados preenchidos corretamente com as informações da sua empresa e clicar no botão "Send" (Enviar).

![api integração postman enviar](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/create-company-2.png)

2.Você receberá uma ID de empresa após o envio e sucesso da requisição.

> **Será necerrário copiá-la para dar continuidade nos passos seguintes.**

![integration api](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/company-id3-modified.png)

> **Atenção:** Em todas as requisições na API, deverá ser informado a ID da empresa fornecida no sucesso de requisição.

## 2\. Fazer upload do certificado na plataforma

### O que é um certificado digital?

Para entender mais sobre o que é um certificado digital, escrevemos um resumo em: [Tudo sobre Certificado Digital][28].

Na nota fiscal eletrônica de consumidor devemos realizar uma requisição para o envio do certificado digital que será utilizado como autenticador com o Governo, onde deverá ser enviado o arquivo `.pfx` e a senha.

> **Atenção:** Não se preocupe, após a inserção do certificado na nossa plataforma, todos os dados são criptografados para maior segurança.

Abaixo, a url e um json de exemplo contendo os dados para realizar o envio do certificado.

> Observação: Substitua \{companyId\} pela ID gerada no passo de criação da empresa.
> 
> O método HTTP utilizada no envio do certificado é o "POST", portanto verifique no seu postman se está preenchido corretamente.  
> (Utilize o Create Certificate na coleção)

`` `POST: https://api.nfse.io/v2/companies/{companyId}/certificates` ``

![criacao do certificado](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/create-certificate.png)

1. Você deverá selecionar o arquivo .pfx em seus arquivos juntamente com a senha e clicar no botão "Send" (Enviar).

![Envio da requisição do certificado](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/create-certificate-send-modified.png)

Após o sucesso da requisição, será informado alguns dados sobre o certificado, tais como:

* A validade do certificado
* Status se está ativou ou inativo na plataforma
* Thumbprint
* Dados sobre o emissor do certificado
1. Você deverá enviar os dados preenchidos corretamente com as informações da sua inscrição estadual e clicar no botão "Send" (Enviar).

![Certificado inserido com sucesso](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/certificate-created-modified.png)

## 3\. Criar inscrição estadual

O terceiro passo será criar o "State Tax", que identifica na nossa plataforma a Inscrição Estadual usada pela empresa.

Saiba mais sobre [Inscrição Estadual][24].

A inscrição estadual tem possibilidade de ser uma ou mais por estado para o mesmo CNPJ. Portanto, separamos a requisição para melhor identificação e organização das sequências númericas.

> **Múltiplas Inscrições Estaduais:** Caso a empresa possua mais de uma Inscrição Estadual (StateTax) ativa, é possível informar explicitamente qual delas deve ser utilizada na emissão. Veja o passo [4.1 Emitir informando a Inscrição Estadual (StateTax)](#41-emitir-informando-a-inscricao-estadual-statetax).

Ela também é responsável por identificar o ambiente em que a nota fiscal será emitida, sendo disponível como "EnvironmentType" (tipo de ambiente), com os valores "_Test_" (_desenvolvimento_) e "Production" (_produção_).

> Por padrão o ambiente criado na plataforma é "Test" (desenvolvimento).

Abaixo, a url e um json de exemplo contendo os dados básicos para a criação de uma inscrição estadual.

> Observação: Substitua \{companyId\} pela ID gerada no passo anterior.
> 
> **O método HTTP utilizada na criação da inscrição estadual é o "POST", portanto, verifique no seu postman se está preenchido corretamente.** 
> (Utilize o `Create StateTaxes` na coleção)

`` `POST: https://api.nfse.io/v2/companies/{companyId}/stateTaxes` ``

```Json
    {
  "stateTax": {
    "code": "SP",
    "taxNumber": "344104773111",
    "SpecialTaxRegime": "automatico",
    "serie": 1,
    "number": 1,
    "type": "NFCe",
    "securityCredential": {
        "code": "d41492a9-4d10-4454-b19b-dddddddddd",
        "id": 1 }
        }
    }
```

Devemos atentar para os valores de Série e Número (_serie e number_), que são utilizados pela SEFAZ para sequenciar as notas emitidas por uma empresa.

Caso você já emita nota, precisará identificar qual a série e o último número emitido, com isso podemos continuar a emissão de onde parou.

Se preferir, poderá identificar com seu contador, uma nova série e número para emissão de nota com a nossa plataforma.

1. Você deverá enviar os dados preenchidos corretamente com as informações da sua inscrição estadual e clicar no botão "Send" (Enviar).

![Envio da requisição da inscricao estadual](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/create-state-tax-modified.png)

1. Você receberá uma ID da inscrição estadual após o envio e sucesso da requisição.  
![Inscrição estadual criada com sucesso](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/state-tax-created-modified.png)

## 4\. Emitir primeira nota fiscal

Pronto, todos os passos antecessores de emissão de suas notas fiscais eletrônicas estão concluídos.

Colocamos um exemplo do mínimo de dados para serem informados à nossa API, caso precise ou queira verificar o restante da documentação, estará disponível em: [Documentação completa.][24]

Os campos mínimos para serem enviados são os dados do comprador (buyer) e os produtos (items).

> Observação: Neste momento, caso você não tenha os dados de impostos:
> 
> * NCM
> * CST/CSOSN - ICMS/PIS/COFINS
> * CFOP
> * CEST
> * GTIN  
> Sugerimos que você avalie com seu contador como deverão ser preenchidos no contexto da sua empresa.
> 
> Caso você já tenha as informaçôes, preenchê-las corretamente e realizar a requisição de emissão de nota.
> 
> **Atenção: Nosso processamento é realizado de forma assíncrona, portanto, o sucesso da requisição não significa que a nota fiscal já foi emitida. Realizamos uma breve validação no momento do envio e outras verificações no decorrer do processamento.**

Abaixo, a url e um json de exemplo contendo os dados mínimos para a emissão de uma nota fiscal.

> **Observação:** Substitua \{companyId\} pela ID gerada no passo de criação da empresa.
> 
> **O método HTTP utilizada no envio da nota fiscal é o "POST", então verifique no seu postman se está preenchido corretamente.**  
> (Utilize o _Issue Invoice_ na coleção)

`POST: https://api.nfse.io/v2/companies/{companyId}/consumerinvoices`

```json
{
    "items": [{
        "unitAmount": 499.00,
        "quantity": 1.0000,
        "cfop": 5102,
        "ncm": "21069030",
        "codeGTIN": "SEM GTIN",
        "CodeTaxGTIN": "SEM GTIN",
        "tax": {
            "totalTax": 156.94,
            "icms": {
                "origin": "0",
                "csosn": "102"
            },
            "pis": {
                "amount": 0.00,
                "rate": 0.6500,
                "baseTax": 0.00,
                "cst": "01"
            },
            "cofins": {
                "amount": 14.97,
                "rate": 3.0000,
                "baseTax": 499.00,
                "cst": "01"
            }
        },
        "cest": "0301100",
        "description": "NOTA FISCAL EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL",
        "code": "K0003-3"
    }]
}
```

1. Você deverá enviar os dados preenchidos corretamente com as informações da sua nota fiscal e clicar no botão "Send" (Enviar).

![Enviar nota fiscal](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/create-invoice-modified.png)

1. Ao sucesso da requisição, será fornecido uma ID da nota fiscal utilizada no processamento da emissão.

![Nota fiscal enviada com sucesso](https://nfe.io/docs/static/docs/nota-fiscal-consumidor/invoice-created-modified-300x72.png)

> **Reforma Tributária (IBS/CBS/IS):** O corpo da emissão também aceita os novos grupos de tributos da Reforma Tributária do Consumo (RTC) — Imposto Seletivo (`items[].tax.IS`), IBS e CBS (`items[].tax.IBSCBS`), além dos totais correspondentes (`totals.isTotals`, `totals.ibsCbsTotals`). O detalhamento completo de cada campo está na [Documentação funcional do layout NF-e/NFC-e (RTC)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/documentacao-layout-nfe-rtc/) e na [Documentação completa da API][24].

## 4.1\. Emitir informando a Inscrição Estadual (StateTax) {#41-emitir-informando-a-inscricao-estadual-statetax}

Quando a empresa possui **mais de uma Inscrição Estadual (StateTax) ativa**, recomendamos utilizar o endpoint que recebe o `statetaxId` diretamente na rota. Assim, você informa explicitamente qual IE deve ser usada na emissão, evitando a seleção automática da primeira IE cadastrada (mesmo comportamento já disponível na NF-e).

> **Observação:** Substitua `{companyId}` pela ID da empresa e `{statetaxId}` pela ID da Inscrição Estadual obtida no passo 3.

`POST: https://api.nfse.io/v2/companies/{companyId}/statetaxes/{statetaxId}/consumerinvoices`

O corpo (`body`) da requisição é **idêntico** ao do endpoint padrão de emissão (`/v2/companies/{companyId}/consumerinvoices`). A diferença está apenas na rota, que passa a identificar a Inscrição Estadual a ser utilizada.

Respostas possíveis:

* **200** — Nota enfileirada para emissão com sucesso.
* **400** — Algum parâmetro informado não é válido (verifique a resposta).
* **404** — A Inscrição Estadual (StateTax) informada não pertence à empresa, ou a empresa não possui Inscrição Estadual configurada.

> **Atenção:** A Inscrição Estadual informada deve ser do tipo **NFCe** e estar **ativa**. Caso contrário, a requisição será rejeitada.

## Importação da url do postman

Novamente, fornecemos uma URL de importação no **POSTMAN** com todas essas requisiçôes já inclusas. Basta inserir sua Autorização em cada requisição e alterar os dados fornecidos.

```json
https://www.getpostman.com/collections/ac619eadd8e51fb33e95
```

[1]: #Integracao%5FNota%5FFiscal%5Fde%5FConsumidor%5F-%5FNFC-e
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Proximos%5Fpassos
[4]: #Requisitos
[5]: #Tutorial
[6]: #Primeiros%5Fpassos
[7]: #1%5FCriar%5Fuma%5Fempresa
[8]: #2%5FFazer%5Fupload%5Fdo%5Fcertificado%5Fna%5Fplataforma
[9]: #O%5Fque%5Fe%5Fum%5Fcertificado%5Fdigital
[10]: #3%5FCriar%5Finscricao%5Festadual
[11]: #4%5FEmitir%5Fprimeira%5Fnota%5Ffiscal
[12]: #Importacao%5Fda%5Furl%5Fdo%5Fpostman
[13]: #Proximos%5Fpassos-2
[14]: https://nfe.io/docs/documentacao/conceitos/notas-fiscais/
[15]: https://nfe.io/docs/documentacao/nota-fiscal-consumidor/integracao-api-nfc/primeiros-passos/#1%5FCriar%5Fuma%5Fempresa
[16]: https://nfe.io/docs/documentacao/nota-fiscal-consumidor/integracao-api-nfc/primeiros-passos/#2%5FFazer%5Fupload%5Fdo%5Fcertificado%5Fna%5Fplataforma
[17]: https://nfe.io/docs/documentacao/nota-fiscal-consumidor/integracao-api-nfc/primeiros-passos/#3%5FCriar%5Finscricao%5Festadual
[18]: https://nfe.io/docs/documentacao/nota-fiscal-consumidor/integracao-api-nfc/primeiros-passos/#4%5FEmitir%5Fprimeira%5Fnota%5Ffiscal
[22]: https://p.nfe.io/pt-br/certificado-digital-20off
[23]: https://nfe.io/
[24]: https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-consumidor-v2/
[25]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/importar-colecao-postman/
[26]: https://app.nfe.io/
[27]: https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/
[28]: https://nfe.io/docs/documentacao/certificado-digital/conceitos/

---

## Como habilitar o fornecedor e emissor de nota fiscal (NFe - mercadoria) estado do Paraná - NFE.io | Docs

Source: https://nfe.io/docs/como-habilitar-o-fornecedor-e-emissor-de-nota-fiscal-nfe-mercadoria/index.md

# Habilitação para emissão de NFe (mercadoria) – Estado do Paraná

O Estado do Paraná optou por ser autorizador de NF-e, ao contrário de algumas unidades da federação que aderiram ao conceito da “SEFAZ VIRTUAL”.  
Para emitir nota no estado do Paraná é necessário realizar o credenciamento do sistema emissor de NF-e adquirido fora do estado.

1. Acessar o link [https://receita.pr.gov.br/login][1]  
![receita_paraná](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/receita_pr-300x225.jpg)
2. Após realizar o login, clique no menu UPD > Autorização de Uso > Cadastro de Autorização de Uso.  
![autorização_de_uso](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/autorizacao_de_uso.jpg)
3. Em seguida, informe os dados e clique em 'Continuar'.  
CNPJ: 18.792.479/0001-01  
Código da NFE.io no SEFAZ/PR: 77369  
![código_sefaz](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/codigo_sefaz-300x80.jpg)
4. Informe o CAD/ICMS (Inscrição Estadual) ou CNPJ da sua empresa e clique em 'Continuar'.  
![informe_o_cad](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/informar_cad-300x86.jpg)
5. Selecione as opções de documentos fiscais a emitir (Ex: modelo 55) e clique em 'Continuar'.  
![seleção_documento_fiscal](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/selecao_docfiscal-300x105.jpg)

[1]: https://receita.pr.gov.br/login

---

## Conceitos sobre Nota Fiscal de Produto Eletrônica (NF-e) - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/conceitos/index.md

# Tudo sobre Nota Fiscal de Produto Eletrônica

A Nota Fiscal Eletrônica (NF-e) é a nota que tem como um dos objetivos fiscalizar as operações e prestações tributadas pelo Imposto sobre Circulação de Mercadorias e Serviços (ICMS) e pelo Imposto sobre Produtos Industrializados (IPI), através do registro de transações referentes à circulação de **produtos físicos**.

> **Lojas físicas ou sites de e-commerce que vendem produtos como eletrodomésticos, aparelhos eletrônicos, móveis ou qualquer outra mercadoria tangível, por exemplo, se enquadram na obrigatoriedade de emissão de notas fiscais.**

Além de ajudar o fisco na fiscalização das atividades citadas acima, a Nota Fiscal Eletrônica também facilita a vida do contribuinte, ao substituir os modelos em papel, reduzindo custos de armazenamento e erros de escrituração.

## Quem precisa emitir NF-e?

A legislação prevê que todas as trocas comerciais de produtos e serviços que envolvem contribuintes do Imposto sobre Circulação de Mercadorias e Serviços (ICMS) e/ou do Imposto sobre Produtos Industrializados (IPI) sejam regulamentadas por meio de notas fiscais, mas existem situações específicas nas quais a empresa fica isenta da emissão.

Assim, resumidamente, quem deve [emitir a NFe][12]:

* MEI (Microempreendedor Individual);
* ME (Microempresa);
* EPP (Empresa de Pequeno Porte);
* Empresa de Lucro Presumido;
* Empresa de Lucro Real;
* Pessoa física (em alguns casos);
* Qualquer empresa que comercializa produtos ou serviços.

## Quando é preciso emitir NF-e?

Na SEFAZ de seu estado, é preciso emitir a NF-e todas as vezes que trocas comerciais de produtos que envolvem contribuintes do ICMS e/ou IPI forem feitas. Isso acontece para que as prefeituras estejam a par de todas as trocas comerciais advindas de prestação de serviços que acontecem na cidade.

## Quais são os impostos retidos na emissão de NF-e?

Ao [emitir uma nota fiscal eletrônica][13], alguns impostos deverão ser calculados e retidos no momento da emissão.

Os impostos são:

* IRRF;
* CSLL;
* PIS/PASEP
* COFINS;
* IPI;
* ICMS;
* ISS;
* INSS;

## Como começar a emitir NF-e?

### Credenciamento

Para começar a emitir NF-e é necessário:

* Obter [certificado digital][14] do padrão ICP-Brasil, necessário para validar a identidade da empresa
* Realizar o [credenciamento][15] no SEFAZ
* Obter acesso a algum programa emissor de nota fiscal. Existe a versão gratuita, do governo, assim como existem emissores automáticos, como o da NFe.io

## Quais as informações necessárias para emitir uma nota fiscal?

Para realizar a emissão de uma [Nota Fiscal eletrônica de Produto][16], você deverá fornecer algumas informações importantes, listadas abaixo:

* Razão Social da empresa;
* Número do Cadastro Nacional de Pessoa Jurídica (CNPJ) da empresa;
* Número telefônico com DDD;
* Endereço completo;
* Email da empresa;
* Número de Inscrição Estadual da empresa (caso a empresa possua).

## O que é Inscrição Estadual?

A [inscrição estadual][17] (IE) é o registro do contribuinte junto à Receita Estadual ou Secretaria de Estado da Fazenda para o recolhimento do ICMS (Imposto sobre Circulação de Mercadorias e Serviços).

O número de inscrição estadual identifica a empresa como um estabelecimento apto a realizar operações de venda de produtos no território nacional.

Em alguns estados, o registro é solicitado com o preenchimento da Ficha Cadastral (FC). Essa ficha deve ser preenchida toda vez que o contribuinte fizer qualquer alteração cadastral. Em outros estados, as fichas de Inscrição Estadual podem possuir outro nome, como Documento Único de Cadastro (DUC).

## O que é Nomeclatura Comum do Mercosul (NCM)?

A sigla [NCM][18] significa _"Nomenclatura Comum Mercosul"_ que é o nome dado para um código utilizado para designar as mercadorias que circulam no Brasil e nos demais países que fazem parte do Mercosul. Esse código passou a ser utilizado em janeiro de 1995 e se baseia no método internacional de classificação de mercadoria SH (Sistema Harmonizado de Designação e de Codificação de Mercadorias).

Todas as notas fiscais de mercadorias importadas ou exportadas devem ter o NCM dos produtos descritos na nota.

## Como cancelar uma NF-e?

Muitas vezes, o responsável por emitir o documento pode cometer erros, como digitar um número errado, inserir produtos desnecessários, errar algum cálculo, entre outros. Quando ocorre algum tipo de erro, é necessário o [cancelamento da nota][19].

Para efetuar o cancelamento, compilamos alguns passos:

1. Acesse o site da SEFAZ.
2. Em seguida, clique em Gerenciar Emissão (botão azul da página).
3. Será necessária a nota fiscal que você deseja cancelar, impressa ou em arquivo digital, para verificar alguns dados.
4. Verifique na nota o número da NF-e e ainda a chamada “Chave de Acesso”.
5. Será requisitado um desses códigos para prosseguir e acessar a nota fiscal eletrônica.
6. Preencha os campos seguintes desta forma:
7. Em remetente, escolha o tipo (entre CPF e CNPJ).
8. Depois, insira o número do documento correspondente.
9. Em seguida, coloque o número da nota fiscal ou os dígitos da Chave de Acesso exibidos na nota.
10. Preencha o captcha (escreva no campo de texto as letras exibidas na tela).
11. Clique em Consultar.

Pronto: A nota fiscal eletrônica estará aberta na tela. Essa é exatamente a nota que deverá ser cancelada. Confira o documento com atenção.  
Agora, vá até a opção do menu “Cancelar” que fica no topo da página  
Clique sobre ela para cancelar a nota fiscal eletrônica  
O responsável poderá realizar o cancelamento da nota em até 24 horas por recomendação do Conselho Nacional de Política Fazendária. O prazo, porém, não diz respeito a todos os estados brasileiros. Após esse período, a empresa responsável deverá pagar uma multa com valor que varia entre os municípios.

> Observação: Cada estado tem sua legislação e regulamento, portanto, não deixe de pesquisar a legislação do seu estado sobre o cancelamento de nota fiscal eletrônica.

### Mais informações

[Certificado digital com desconto][14]  
[Crie uma conta e teste nossa plataforma gratuitamente][20]


[1]: #Tudo%5Fsobre%5FNota%5FFiscal%5Fde%5FProduto%5FEletronica
[2]: #Quem%5Fprecisa%5Femitir%5FNF-e
[3]: #Quando%5Fe%5Fpreciso%5Femitir%5FNF-e
[4]: #Quais%5Fsao%5Fos%5Fimpostos%5Fretidos%5Fna%5Femissao%5Fde%5FNF-e
[5]: #Como%5Fcomecar%5Fa%5Femitir%5FNF-e
[6]: #Credenciamento
[7]: #Quais%5Fas%5Finformacoes%5Fnecessarias%5Fpara%5Femitir%5Fuma%5Fnota%5Ffiscal
[8]: #O%5Fque%5Fe%5FInscricao%5FEstadual
[9]: #O%5Fque%5Fe%5FNomeclatura%5FComum%5Fdo%5FMercosul%5FNCM
[10]: #Como%5Fcancelar%5Fuma%5FNF-e
[11]: #Mais%5Finformacoes
[12]: https://nfe.io/nota-fiscal-de-produto-eletronica/
[13]: https://nfe.io/blog/nota-fiscal/tudo-sobre-emissao-nota-fiscal-eletronica/
[14]: https://p.nfe.io/pt-br/certificado-digital-20off
[15]: /documentacao/nota-fiscal-produto-eletronica/credenciamento
[16]: https://nfe.io/blog/nota-fiscal/o-que-e-nota-fiscal-produto/
[17]: https://nfe.io/blog/gestao-empresarial/o-que-e-inscricao-estadual/
[18]: https://nfe.io/blog/nota-fiscal/o-que-e-ncm-nota-fiscal/
[19]: https://nfe.io/blog/nota-fiscal/como-cancelar-nota-fiscal-ja-emitida/
[20]: https://id.nfe.io/signup?returnUrl=%2Flogout%3FlogoutId%3DCfDJ8KGjv5x5Q6lMi2BB4X2DIf1-IF%5FHuff4L-tg32LR9%5FTivqZl6WKpGA4HGNBnbXjpTrWYM7spj54Fi3S%5F1R2n-8ZkNkXyeLVDHyMrPEM-fluAMwNYeJ7wSqAYL-RTWnNMRsX2COo2x9z9ZVQVyRL1IWqZWOJ4gxi-jOMj05eW3ITsdxirELxKUg11cmZ2zRCKXif5GEzbF8JzMI9EGHHKOLIoSTeBA4V0HXo170%5FKDvgjFWmNRbpZyj7Wcq9P2ct643g0DKw9wPPO9PmrmGjO9G4B9-xQ2cgs5Cs5RDZN9hTfZ%5F6325h0%5Fy8Xfb2W6V2ICf7v-GNWj7lVdjdqqlANIwQ

---

## Guia para usar a SEFAZ e emitir a Nota Fiscal Eletrônica

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/credenciamento/index.md

# Credenciamento na SEFAZ: como emitir a Nota Fiscal Eletrônica

Muitas empresas usam o sistema da **Secretaria da Fazenda (SEFAZ) para emitir a Nota Fiscal Eletrônica (NF-e)**. Trata-se de uma **etapa obrigatória para alcançar a conformidade fiscal** com a legislação vigente e também para promover uma gestão ágil e segura.

Além disso, o processo oferece benefícios para o trabalho de qualquer gestor, como **transparência, organização e suporte à escalabilidade** da organização.

Portanto, se você vai lidar com atividades desse tipo, ou mesmo se deseja otimizar o processo, preparamos este guia para te ensinar como usar a SEFAZ e emitir a Nota Fiscal Eletrônica.

Continue a leitura e aprenda, inclusive, como fazer uma **consulta sobre o credenciamento de NFe**. Confira!

## O que é o credenciamento na SEFAZ estadual e por que é importante?

O credenciamento na SEFAZ (seja ela municipal ou estadual) é o procedimento que **habilita empresas a emitir Nota Fiscal Eletrônica (NF-e)**, uma solução para a **substituição do documento em papel modelo 1 ou 1A**.

Trata-se de um **processo focado em atender às obrigações tributárias**, evitar penalidades fiscais e garantir a validade jurídica das notas emitidas.

Dessa maneira, sua empresa, ao realizar o **credenciamento na SEFAZ**, passa a operar no ambiente digital, simplifica a gestão fiscal e promove benefícios como eficiência operacional e transparência na realização das tarefas.

Para além da obrigatoriedade de usar a **SEFAZ como [emissor de nota fiscal][24]**, trata-se de uma evolução natural para o crescimento sustentável de qualquer organização. Afinal de contas, aproxima-as da transformação digital e é um passo estratégico capaz de fortalecer a sua competitividade no mercado.

**Veja também**: [Não emitir nota fiscal é crime? Sim! Veja riscos e penalidades][25]

## Existe mais de um tipo de credenciamento na SEFAZ?

O credenciamento se divide em duas categorias principais, que atendem a diferentes etapas do processo de emissão de notas fiscais. Abaixo, explicamos cada tipo.

### Homologação (ambiente de testes)

O ambiente de testes serve para **testar as soluções tecnológicas que serão empregadas na emissão de uma NF-e**.

Assim, empresas verificam se o software emissor funciona corretamente e ajustam possíveis inconsistências antes de migrar para a produção.

**Atenção**: embora seja opcional em alguns estados, realizar os testes é altamente recomendado para evitar erros futuros.

### Produção (ambiente real)

Após concluir os testes no ambiente de homologação, sua empresa **pode se credenciar no ambiente de produção** e, dessa maneira, **começar a emitir NF-e com validade fiscal**.

Ou seja: é uma etapa indispensável para iniciar operações formais e **garantir que as notas fiscais estejam conforme as normas legais**.

## Passo a passo: como se cadastrar na SEFAZ?

Vai usar a SEFAZ para emitir a Nota Fiscal Eletrônica? Então, atente-se ao seguinte: embora o processo possa variar entre os estados, segue uma estrutura em comum.

Abaixo, detalhamos cada uma dessas etapas gerais.

### 1\. Obtenha o Certificado Digital

**Adquira um Certificado Digital [ICP-Brasil][26]**. O documento é necessário para autenticar sua empresa no sistema da SEFAZ e assegurar a segurança das informações. Caso ainda não tenha, pode obter seu [Certificado Digital com desconto aqui][27].

### 2\. Acesse o Posto Fiscal Eletrônico (PFE)

Certifique-se de que sua empresa tem login e senha válidos no [Posto Fiscal Eletrônico (PFE)][28] da SEFAZ.

Caso não tenha acesso, solicite o cadastro no portal fiscal correspondente ao seu estado.

### 3\. Escolha o software emissor de NF-e

**Decida entre o emissor gratuito da SEFAZ e sistemas pagos**. Caso opte pelo investimento em soluções desse tipo, vale a dica: busque por soluções personalizadas. É o tipo de diferencial capaz de **agregar eficiência e integração com outras ferramentas de gestão**.

[Aproveite, e conheça as soluções da NFE.io!][29]

### 4\. Solicite o credenciamento na SEFAZ

Preencha o formulário de credenciamento no sistema da SEFAZ e **confirme que todas as informações cadastrais estão corretas**.

### 5\. Realize testes no ambiente de homologação

Mesmo quando não for obrigatório, **é aconselhável validar o software emissor** no ambiente de homologação para identificar e **corrigir problemas antes de iniciar as operações reais**.

### 6\. Habilite o ambiente de produção

Após a aprovação, conclua o credenciamento para operar no ambiente de produção e comece a emitir NF-e com validade jurídica.

## Como consultar o status do credenciamento na SEFAZ?

Confirmar o status do credenciamento vai te ajudar a evitar imprevistos e garantir que sua empresa esteja apta a usar a SEFAZ como emissor de nota fiscal. Siga os passos a seguir:

1. acesse o [portal da SEFAZ][30] do seu estado com o login e senha do PFE;
2. navegue até a seção de consulta de credenciamento;
3. verifique informações sobre o ambiente habilitado (homologação ou produção) e possíveis pendências.

**Dica**: manter essas informações atualizadas é muito importante porque evita interrupções nas operações fiscais.

## O que é o emissor de nota fiscal da SEFAZ?

**A SEFAZ disponibiliza um emissor gratuito de Nota Fiscal Eletrônica**, ideal para pequenas empresas com baixo volume de emissão.

É necessário reforçar, contudo, que negócios de grande porte podem optar por sistemas pagos, que permitem automação e integração com outras ferramentas.

E independentemente do porte da sua empresa, conte com as [soluções da NFE.io][31], que são pensadas para se adaptarem às suas necessidades e à demanda da sua gestão fiscal.

### Vantagens do emissor gratuito da SEFAZ

Se você vai usar a SEFAZ para emitir Nota fiscal eletrônica, fique por dentro das vantagens desse sistema gratuito:

* **fácil acesso** e implementação;
* **sem custos** adicionais para a sua organização;
* **atualizações constantes** com base nas normas fiscais vigentes.

**Aprenda também**: [Como rejeitar nota fiscal na SEFAZ? Passo a passo!][32]

## Quais cuidados tomar ao realizar o credenciamento na SEFAZ?

Siga as recomendações abaixo e previna-se contra problemas durante o credenciamento na SEFAZ:

* **revise as informações cadastrais** e certifique-se de que os dados estão corretos no sistema;
* **acompanhe os prazos** — pode levar até 24 horas para o reconhecimento no sistema;
* **valide o software emissor** e realize testes para evitar erros na produção;
* **Consulte um contador** caso tenha qualquer dúvida, pois especialistas podem garantir conformidade com os requisitos legais.

## Perguntas Frequentes (FAQ)

Confira as dúvidas mais comuns sobre a SEFAZ para emitir a Nota Fiscal Eletrônica.

### Quem deve se credenciar na SEFAZ para emitir NF-e?

Todas as empresas que têm obrigação legal de emitir Nota Fiscal Eletrônica precisam realizar o credenciamento na SEFAZ do estado em que operam.

### Posso emitir NF-e sem credenciamento na SEFAZ?

Não, o credenciamento é obrigatório para garantir a validade jurídica e fiscal das notas emitidas, além de atender às exigências do [Fisco][33].

### O credenciamento na SEFAZ é gratuito?

Sim, em quase todos os estados, o credenciamento na SEFAZ não gera custos adicionais, mas é importante verificar eventuais requisitos específicos.

### Como saber se minha empresa está credenciada?

É possível consultar o status no portal da SEFAZ por meio dos dados de login e senha cadastrados no Posto Fiscal Eletrônico (PFE) da sua empresa.

### Quais estados têm regras específicas para credenciamento?

Alguns estados exigem documentos ou procedimentos adicionais. Consulte o site da SEFAZ do seu estado de atuação para entender as regras aplicáveis à região.

### É necessário habilitar ou indicar um emissor de notas em todos os estados?

Em algumas SEFAZ estaduais, é necessário habilitar ou indicar um emissor de notas para poder emitir a NF-e. Esse procedimento pode ser restritivo e varia conforme o estado. Verifique as orientações específicas na SEFAZ de sua localidade.


[1]: #Credenciamento%5Fna%5FSEFAZ%5Fcomo%5Femitir%5Fa%5FNota%5FFiscal%5FEletronica
[2]: #O%5Fque%5Fe%5Fo%5Fcredenciamento%5Fna%5FSEFAZ%5Festadual%5Fe%5Fpor%5Fque%5Fe%5Fimportante
[3]: #Existe%5Fmais%5Fde%5Fum%5Ftipo%5Fde%5Fcredenciamento%5Fna%5FSEFAZ
[4]: #Homologacao%5Fambiente%5Fde%5Ftestes
[5]: #Producao%5Fambiente%5Freal
[6]: #Passo%5Fa%5Fpasso%5Fcomo%5Fse%5Fcadastrar%5Fna%5FSEFAZ
[7]: #1%5FObtenha%5Fo%5FCertificado%5FDigital
[8]: #2%5FAcesse%5Fo%5FPosto%5FFiscal%5FEletronico%5FPFE
[9]: #3%5FEscolha%5Fo%5Fsoftware%5Femissor%5Fde%5FNF-e
[10]: #4%5FSolicite%5Fo%5Fcredenciamento%5Fna%5FSEFAZ
[11]: #5%5FRealize%5Ftestes%5Fno%5Fambiente%5Fde%5Fhomologacao
[12]: #6%5FHabilite%5Fo%5Fambiente%5Fde%5Fproducao
[13]: #Como%5Fconsultar%5Fo%5Fstatus%5Fdo%5Fcredenciamento%5Fna%5FSEFAZ
[14]: #O%5Fque%5Fe%5Fo%5Femissor%5Fde%5Fnota%5Ffiscal%5Fda%5FSEFAZ
[15]: #Vantagens%5Fdo%5Femissor%5Fgratuito%5Fda%5FSEFAZ
[16]: #Quais%5Fcuidados%5Ftomar%5Fao%5Frealizar%5Fo%5Fcredenciamento%5Fna%5FSEFAZ
[17]: #Perguntas%5FFrequentes%5FFAQ
[18]: #Quem%5Fdeve%5Fse%5Fcredenciar%5Fna%5FSEFAZ%5Fpara%5Femitir%5FNF-e
[19]: #Posso%5Femitir%5FNF-e%5Fsem%5Fcredenciamento%5Fna%5FSEFAZ
[20]: #O%5Fcredenciamento%5Fna%5FSEFAZ%5Fe%5Fgratuito
[21]: #Como%5Fsaber%5Fse%5Fminha%5Fempresa%5Festa%5Fcredenciada
[22]: #Quais%5Festados%5Ftem%5Fregras%5Fespecificas%5Fpara%5Fcredenciamento
[23]: #E%5Fnecessario%5Fhabilitar%5Fou%5Findicar%5Fum%5Femissor%5Fde%5Fnotas%5Fem%5Ftodos%5Fos%5Festados
[24]: https://nfe.io/blog/nota-fiscal/regras-emissao-nota-fiscal/
[25]: https://nfe.io/blog/nota-fiscal/nao-emitir-nota-fiscal-e-crime/
[26]: https://arprime.com/
[27]: https://p.nfe.io/pt-br/certificado-digital-20off
[28]: http://pfe.fazenda.sp.gov.br/
[29]: https://nfe.io/
[30]: https://www.nfe.fazenda.gov.br/
[31]: http://nfe.io
[32]: https://nfe.io/blog/nota-fiscal/como-rejeitar-nota-fiscal-sefaz/
[33]: https://nfe.io/blog/nota-fiscal/como-identificar-notas-frias/

---

## Importar Coleção Postman - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/importar-colecao-postman/index.md

# Importar url no Postman

Postman é um ambiente de desenvolvimento de APIs, usada para testar as mesmas sem necessidade de criação de códigos adicionais.

## 1\. Instalação

Faça download pelo link: [https://www.postman.com/downloads/][4]

## 2\. Importar

Colocamos essa url de exemplo para importação:

```json
https://api.postman.com/collections/13456751-f3769b82-5291-445b-b7bf-8fc0ffcab9b2?access_key=PMAT-01JKDTXTXB7DN8645BWG6K7C7K
```

1. Copie a url acima para continuar os passos.
2. Você pode importar pela tela inicial conforme abaixo ou pelo seu Workspace.

![nfe_io_postman_import](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/nfe_io_postman_import.png)

1. Agora basta clicar quem "Import" (importar) no canto superior esquerdo da tela.

![nfe_io_postman_import_2](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/nfe_io_postman_import_2.png)

1. Clique em "Import from Link" (importar do link) e cole a url copiada anteriormente clique em "continue" (continuar).

![nfe_io_postman_import_link](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/nfe_io_postman_import_link.png)

1. Clique "Import" (importar) e aparecerá no canto esquerdo as coleções disponíveis.

![nfe_io_postman_import_botaoimport](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/nfe_io_postman_import_botaoimport.png)

1. Ao final aparecerá uma coleção chamada "DEFAULT", onde estará disponível todas as opções de requisição.

![nfe_io_postman_collection_default](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/nfe_io_postman_collection_default.png)


[1]: #Importar%5Furl%5Fno%5FPostman
[2]: #1%5FInstalacao
[3]: #2%5FImportar
[4]: https://www.postman.com/downloads/

---

## Como consultar nota fiscal eletrônica

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica/index.md

# Como consultar a nota fiscal eletrônica emitida

A consulta de nota fiscal eletrônica é um processo importante para verificar o status e os detalhes das notas fiscais emitidas. Neste tutorial, você aprenderá como consultar uma nota fiscal eletrônica (NF-e) utilizando a API da NFE.io.

## Outros passos

1. [Pegar chave de autorização na plataforma][11]
2. [Instalar e importar url no postman][12]
3. [Emitir nota fiscal de produto][13]

## 1\. Consultar nota fiscal

Precisamos [consultar a nota fiscal][14] para verificar o status da mesma.

> **Observação:** Substitua \{companyId\} pela ID da empresa e a \{producInvoiceId\} pela ID da nota fiscal gerada na emissão.
> 
> **O método HTTP utilizada para consultar a nota fiscal é o "GET", portanto, verifique no seu postman se está preenchido corretamente.**

`GET: https://api.nfse.io/v2/companies/{companyId}/productinvoices/{productInvoiceId}`

1. Clicar no botão "Send" (Enviar) para completar a requisição.

![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/get-product-invoice-modified.png)

1. Será retornado os dados completos da nota fiscal.

![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/get-product-invoice-result.png)

> **Observação:** A consulta de XML e consulta de PDF geram uma nova url temporária (válida por 15 minutos) e necessitará uma nova requisição para receber o dado válido.

## 2\. Consultar XML

Para [consultar o XML][15] é utilizado a mesma URL de requisição de consulta de nota fiscal adicionado de /xml

> **Observação:** Substitua \{companyId\} pela ID da empresa e a \{producInvoiceId\} pela ID da nota fiscal gerada na emissão.
> 
> **O método HTTP utilizado para consultar o XML da nota fiscal é o "GET", portanto, verifique no seu postman se está preenchido corretamente.**

![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/get-xml-product-invoice-modified.png)

`GET: https://api.nfse.io/v2/companies/{companyId}/productinvoices/{productInvoiceId}/xml`

1. Clicar no botão "Send" (Enviar) para completar a requisição.  
![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/get-xml-product-invoice-modified-1.png)
2. Será retornado uma URL temporária para consulta do xml.

![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/get-xml-product-invoice-link.png)

1. Resultado da requisição da url temporária.  
![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/get-xml-product-invoice-result.png)

## 3\. Consultar PDF (Danfe)

Para consultar o PDF é utilizado a mesma URL de requisição de consulta de nota fiscal adicionado de `/pdf`

> **Observação:** Substitua \{companyId\} pela ID da empresa e a \{producInvoiceId\} pela ID da nota fiscal gerada na emissão.
> 
> **O método HTTP utilizado para consultar o PDF da nota fiscal é o "GET", portanto, verifique no seu postman se está preenchido corretamente.**

`GET: https://api.nfse.io/v2/companies/{companyId}/productinvoices/{productInvoiceId}/pdf`

1. Clicar no botão "Send" (Enviar) para completar a requisição.

![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/get-pdf-product-invoice-modified.png)

1. Será retornado uma URL temporária para consulta do pdf.  
![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/get-pdf-product-invoice-link.png)
2. Resultado da requisição da url temporária.  
![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/get-pdf-product-invoice-result.png)

## Outros passos

1. [Pegar chave de autorização na plataforma][11]
2. [Instalar e importar url no postman][16]
3. [Emitir nota fiscal de produto][13]

[1]: #Como%5Fconsultar%5Fa%5Fnota%5Ffiscal%5Feletronica%5Femitida
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Outros%5Fpassos
[4]: #1%5FConsultar%5Fnota%5Ffiscal
[5]: #2%5FConsultar%5FXML
[6]: #3%5FConsultar%5FPDF%5FDanfe
[7]: #Outros%5Fpassos-2
[8]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica/#1%5FConsultar%5Fnota%5Ffiscal
[9]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica/#2%5FConsultar%5FXML
[10]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica/#3%5FConsultar%5FPDF%5FDanfe
[11]: https://nfe.io/docs/nossa-plataforma/pegar-chave-acesso/
[12]: https://nfe.io/docs/comum/postman/
[13]: https://nfe.io/docs/nota-fiscal-eletronica/integracao-api/integracao/
[14]: https://nfe.io/blog/financeiro/consultar-nota-fiscal-por-cpf/
[15]: https://nfe.io/consulta-nota-fiscal/
[16]: https://nfe.io/docs/comum/postman/

---

## Como consultar nota fiscal por parâmetro

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-por-parametro/index.md

# Como consultar nota fiscal por parâmetro

A consulta de notas fiscais por parâmetro é uma funcionalidade que permite buscar notas fiscais eletrônicas (NF-e) com base em critérios específicos, como CNPJ do destinatário, status da nota, entre outros. Isso facilita a localização de notas fiscais específicas sem a necessidade de consultar uma a uma.

## Outros passos

[1\. Pegar chave de autorização na plataforma.][12]  
[2\. Instalar e importar url no postman][13]  
[3\. Emitir nota fiscal de produto][14]

## 1\. Consultar notas fiscais de uma empresa

Para consultar as notas fiscais de uma empresa, utilizaremos a url abaixo.

`GET: https://api.nfse.io/v2/companies/{companyId}/productinvoices?environment=test`

> **Obs:** Substitua \{companyId\} pela ID de sua empresa. O parâmetro \{environment\} não pode ser nulo, preencha-o com production ou test. Nesse tutorial usaremos o ambiente de teste.
> 
> **Utilizaremos o método HTTP do tipo "GET"**, portanto, verifique no seu postman se está selecionado a opção corretamente.

1. Clicar no botão "Send" (Enviar) para completar a requisição.
2. Será retornado alguns dados e uma lista com as notas fiscais dessa empresa.

## 2\. Consultar notas fiscais via elasticsearch

O Elasticsearch é um mecanismo de busca e análise de dados distribuído e open source para todos os tipos de dados, incluindo textuais, numéricos, geoespaciais, estruturados e não estruturados. Através dele, conseguiremos fazer buscas de notas fiscais por diversos tipos de parâmetros e dados.

Veja abaixo um exemplo simples de uma busca por notas fiscais pelo CNPJ do destinatário.

`GET: https://api.nfse.io/v2/companies/{companyId}/productinvoices?environment=test&q=buyer.federalTaxNumber:8662968678`

O parâmetro `q`, é onde passaremos a query string do elasticsearch.

Nesse caso, a query `q=buyer.federalTaxNumber:8662968678` corresponde ao campo do JSON da nota fiscal que temos da API, como no exemplo abaixo.

```json
{
    "buyer": {
        "name": "João",
        "address": {
            "city": {
                "code": "3550308",
                "name": "jundiai"
            },
            "state": "SP",
            "district": "centro",
            "street": "rua petronilha antunes",
            "postalCode": "13207760",
            "number": "204",
            "country": "BRA"
        },
        "federalTaxNumber": 8662968678
    },
    "items": [{
        "code": "2617",
        "unitAmount": 9.98,
        "quantity": 5,
        "cfop": 5102,
        "ncm": "47079000",
        "codeGTIN": "SEM GTIN",
        "codeTaxGTIN": "SEM GTIN",
        "tax": {
            "totalTax": 6,
            "icms": {
                "amount": 6,
                "rate": 18,
                "baseTax": 33.25,
                "baseTaxSTReduction": "33.33",
                "baseTaxModality": "3",
                "cst": "20",
                "origin": "0"
            },
            "pis": {
                "amount": 0,
                "rate": 0,
                "baseTax": 0,
                "cst": "06"
            },
            "cofins": {
                "amount": 0,
                "rate": 0,
                "baseTax": 0,
                "cst": "06"
            }
        },
        "cest": "",
        "description": "FEIJAO CAMIL 500G NF ENTRADA 1030099 14\/05\/2018"
    }]
}
```

Se quiséssemos consultar as notas fiscais pelo nome do destinatário, faríamos a seguinte query:

`q=buyer.name:"João"`

Perceba que temos um leque bem amplo de possibilidades e com certeza você poderá implementar os filtros ideais para o seu negócio.

## 3\. Sintaxe da string de consulta

A string de consulta é analisada em uma série de termos e operadores. Um termo pode ser uma única palavra - `João` ou `Pedro `\- ou uma frase, entre aspas duplas - `"João Pedro"` \- que procura todas as palavras na frase, na mesma ordem.

Os operadores permitem que você personalize a pesquisa. Veja abaixo as opções disponíveis.

## Nomes dos campos

Você pode especificar campos para pesquisar na sintaxe da consulta:

* onde o campo `status` contém `Issued`

`q=status:Issued`

* onde o campo `buyer.name` contém `João` ou `Pedro`

`q=buyer.name:(João OR Pedro)`

* onde o campo `buyer.name` contém exatamente a frase `"João Pedro"`

`q=buyer.name:"João Pedro"`

## Intervalos

Intervalos podem ser especificados para compos do tipo date, numeric ou string.

* Todos os dias de 2019

`q=createdOn:[2019-01-01 TO 2019-12-31]`

* Números 1...5

`q=number:[1 TO 5]`

* Números de 10 em diante

`q=number:[10 TO *]`

## Combinações

Os operadores booleanos AND, OR e NOT (&&, || e !) também são suportados, mas cuidado, nesses casos os parênteses devem ser usados sempre que múltiplos operadores são usados juntos. Por exemplo:

`q=status:(Issued OR Cancelled) AND buyer.name:(João OR Pedro) AND createdOn:[2020-01-01 TO 2020-01-31]`

Esta consulta irá trazer todas as notas fiscais que foram emitidas ou canceladas, em que o campo do nome do destinatário contém o nome "João" ou "Pedro", no dia 01/01/2020 até 31/01/2020.

Para saber mais sobre "Query String", [acesse a documentação do elasticsearch.][15]


[1]: #Como%5Fconsultar%5Fnota%5Ffiscal%5Fpor%5Fparametro
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Outros%5Fpassos
[4]: #1%5FConsultar%5Fnotas%5Ffiscais%5Fde%5Fuma%5Fempresa
[5]: #2%5FConsultar%5Fnotas%5Ffiscais%5Fvia%5Felasticsearch
[6]: #3%5FSintaxe%5Fda%5Fstring%5Fde%5Fconsulta
[7]: #Nomes%5Fdos%5Fcampos
[8]: #Intervalos
[9]: #Combinacoes
[10]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-por-parametro/#1%5FConsultar%5Fnotas%5Ffiscais%5Fde%5Fuma%5Fempresa
[11]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-por-parametro/#2%5FConsultar%5Fnotas%5Ffiscais%5Fvia%5Felasticsearch
[12]: https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/
[13]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/importar-colecao-postman/
[14]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/primeiros-passos/#4%5FEmitir%5Fprimeira%5Fnota%5Ffiscal
[15]: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html

---

## Emitir uma nota fiscal de Produto

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/emitir-uma-nota-fiscal-de-produto/index.md

# Integração da Nota Fiscal Eletronica (NF-e / NFC-e)

A Nota fiscal eletrônica é o documento digital fiscal usada para a documentação de operaçóes de circulação de mercadorias ou prestação de serviço, seja transporte no mesmo estado, quanto entre estados.

**Saiba mais:** [O que é nota fiscal eletrônica?][11]

## Ao final desse tutorial, você será capaz de:

[1\. Emitir uma nota fiscal de produto][12]

## Próximos passos

1. [Emitir uma nota fiscal eletrônica (NF-e/NFC-e) utilizando Motor de Cálculo de Tributos][13]
2. [Consultar uma nota fiscal][14]
3. [Consultar o XML de uma nota fiscal emitida][15]
4. [Consultar o PDF (danfe) de uma nota fiscal emitida][16]

## Requisitos

* [Qual tipo de nota fiscal devo emitir?][17]
* [Como fazer o **credenciamento** da minha empresa para emissão de nota?][18]
* [Quer saber mais sobre certificado digital?][19]
* [Desconto para adquirir seu certificado digital **A1?**][20]

## Tutorial

A partir desse momento faremos uma breve explicação de como realizar a integração de Nota fiscal de Produto com a API oferecida pela NFE.io.

**Veja mais sobre a** [Documentação da API][21]

> Você pode realizar a importação da url no Postman para ter todos os seguintes exemplos através do link:

```json
https://api.postman.com/collections/13456751-f3769b82-5291-445b-b7bf-8fc0ffcab9b2?access_key=SEU_ACCESS_KEY_DO_POSTMAN
```

Tutorial de como importar a url no postman [Clique aqui][22]

## Primeiros passos

## 1\. Emitir primeira nota fiscal

Pronto, todos os passos antecessores de emissão de suas notas fiscais eletrônicas estão concluídos.

Colocamos um exemplo do mínimo de dados para serem informados à nossa API, caso precise ou queira verificar o restante da documentação, estará disponível em: [Documentação completa.][23]

Os campos mínimos para serem enviados são os dados do comprador (buyer) e os produtos (items).

> **Observação:** Neste momento, caso você não tenha os dados de impostos:
> 
> * NCM
> * CST/CSOSN - ICMS/PIS/COFINS
> * CFOP
> * CEST
> * GTIN  
> Sugerimos que você avalie com seu contador como deverão ser preenchidos no contexto da sua empresa.  
> Outra opção seria utilizar o motor de cálculo de imposto da NFE.io que preenche automaticamente o grupo "tax".
> 
> Caso você já tenha as informaçôes, preenchê-las corretamente e realizar a requisição de emissão de nota.
> 
> **Atenção: Nosso processamento é realizado de forma assíncrona, portanto, o sucesso da requisição não significa que a nota fiscal já foi emitida. Realizamos uma breve validação no momento do envio e outras verificações no decorrer do processamento.**

Abaixo, a url e um json de exemplo contendo os dados mínimos para a emissão de uma nota fiscal **sem** a utilização do motor de cálculo de imposto.

> **Observação:** Substitua \{companyId\} pela ID gerada no passo de criação da empresa.
> 
> **O método HTTP utilizada no envio da nota fiscal é o "POST", então verifique no seu postman se está preenchido corretamente.**

`POST: https://api.nfse.io/v2/companies/{companyId}/productinvoices`

```json
{
    "buyer": {
        "name": "teste",
        "address": {
            "city": {
                "code": "3550308",
                "name": "jundiai"
            },
            "state": "SP",
            "district": "centro",
            "street": "rua petronilha antunes",
            "postalCode": "13207760",
            "number": "204",
            "country": "BRA"
        },
        "federalTaxNumber": 8662968678
    },
    "items": [{
        "code": "2617",
        "unitAmount": 9.98,
        "quantity": 5,
        "cfop": 5102,
        "ncm": "47079000",
        "codeGTIN": "SEM GTIN",
        "codeTaxGTIN": "SEM GTIN",
        "tax": {
            "totalTax": 6,
            "icms": {
                "amount": 6,
                "rate": 18,
                "baseTax": 33.25,
                "baseTaxSTReduction": "33.33",
                "baseTaxModality": "3",
                "cst": "20",
                "origin": "0"
            },
            "pis": {
                "amount": 0,
                "rate": 0,
                "baseTax": 0,
                "cst": "06"
            },
            "cofins": {
                "amount": 0,
                "rate": 0,
                "baseTax": 0,
                "cst": "06"
            }
        },
        "cest": "",
        "description": "FEIJAO BOLINHA CAMIL 500G NF ENTRADA 1030099 14\/05\/2018"
    }]
}
```

1. Você deverá enviar os dados preenchidos corretamente com as informações da sua nota fiscal e clicar no botão "Send" (Enviar).

![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/create-invoice-modified.png)

1. Ao sucesso da requisição, será fornecido uma ID da nota fiscal utilizada no processamento da emissão.

![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/invoice-created-modified.png)

## Importação da url do postman

Novamente, fornecemos uma URL de importação no POSTMAN com todas essas requisiçôes já inclusas. Basta inserir sua Autorização em cada requisição e alterar os dados fornecidos.

```json
https://api.postman.com/collections/13456751-f3769b82-5291-445b-b7bf-8fc0ffcab9b2?access_key=SEU_ACCESS_KEY_DO_POSTMAN
```

## Próximos passos

1. [Emitir uma nota fiscal de produto utilizando o Motor de Cálculo de Triutos][13]
2. [Consultar o XML de uma nota fiscal emitida][15]
3. [Consultar o PDF (danfe) de uma nota fiscal emitida][16]

## Veja também:

* [Nossos segmentos][24]
* [Sobre a NFE.io][25]
* [Junte-se ao nosso time][26]

[1]: #Integracao%5Fda%5FNota%5FFiscal%5FEletronica%5FNF-e%5FNFC-e
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Proximos%5Fpassos
[4]: #Requisitos
[5]: #Tutorial
[6]: #Primeiros%5Fpassos
[7]: #1%5FEmitir%5Fprimeira%5Fnota%5Ffiscal
[8]: #Importacao%5Fda%5Furl%5Fdo%5Fpostman
[9]: #Proximos%5Fpassos-2
[10]: #Veja%5Ftambem
[11]: /documentacao/conceitos/notas-fiscais
[12]: /documentacao/nota-fiscal-produto-eletronica/integracao-api/primeiros-passos#4%5FEmitir%5Fprimeira%5Fnota%5Ffiscal
[13]: /documentacao/motor-de-calculo-de-tributos
[14]: /documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica#1%5FConsultar%5Fnota%5Ffiscal
[15]: /documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica#2%5FConsultar%5FXML
[16]: /documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica#3%5FConsultar%5FPDF%5FDanfe
[17]: /documentacao/conceitos/notas-fiscais
[18]: /documentacao/nota-fiscal-produto-eletronica/credenciamento
[19]: /documentacao/certificado-digital/conceitos
[20]: https://p.nfe.io/pt-br/certificado-digital-20off
[21]: /desenvolvedores/rest-api/nota-fiscal-de-produto-v2/nota-fiscal-de-produto
[22]: /documentacao/nota-fiscal-produto-eletronica/importar-colecao-postman
[23]: /desenvolvedores/rest-api/nota-fiscal-de-produto-v2/nota-fiscal-de-produto
[24]: https://nfe.io/segmentos/
[25]: https://nfe.io/sobre/
[26]: https://nfe.io/carreira/

---

## Emitir uma nota fiscal de produto utilizando Motor de Cálculo de Tributos

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/emitir-uma-nota-fiscal-de-produto-utilizando-o-motor-de-calculo-de-tributos/index.md

# Integração da Nota Fiscal Eletrônica utilizando o Motor de Cálculo de Tributos (NF-e / NFC-e)

A Nota fiscal eletrônica é o documento digital fiscal usada para a documentação de operaçóes de circulação de mercadorias ou prestação de serviço, seja transporte no mesmo estado, quanto entre estados.

**Saiba mais:** [O que é nota fiscal eletrônica?][20]

## Ao final desse tutorial, você será capaz de:

Emitir uma nota fiscal eletrônica utilizando o motor de cálculo de tributos.

## Próximos passos

1. [Consultar uma nota fiscal][21]
2. [Consultar o XML de uma nota fiscal emitida][22]
3. [Consultar o PDF (danfe) de uma nota fiscal emitida][23]
4. [Motor de Cálculo de Tributos][24]

## Requisitos

* [Qual tipo de nota fiscal devo emitir?][25]
* [Como fazer o **credenciamento** da minha empresa para emissão de nota?][26]
* [Quer saber mais sobre certificado digital?][27]
* [Desconto para adquirir seu certificado digital **A1?**][28]
* [Cadastrar uma empresa][29]
* [Fazer upload de um certificado na plataforma][30]
* [Cadastrar uma inscrição estadual][31]

## Tutorial

A partir desse momento faremos uma breve explicação de como realizar a integração de Nota fiscal Eletrônica (NF-e / NFC-e) com a API oferecida pela NFE.io utilizando o Taxes (motor de cálculo de imposto).

**Veja mais sobre a** [Documentação da API][32]

> Você pode realizar a importação da url no Postman para ter todos os seguintes exemplos através do link:

```json
https://api.postman.com/collections/13456751-f3769b82-5291-445b-b7bf-8fc0ffcab9b2?access_key=PMAT-01JKDTXTXB7DN8645BWG6K7C7K
```

Tutorial de como importar a url no postman [Clique aqui][33]

### 1\. Introdução

Utilizamos uma API REST (Representational State Transfer), que é um padrão amplamente adotado para a integração entre sistemas.

* Aqui estão os pontos principais sobre a forma de comunicação com a API NFE.io:  
   * Protocolo HTTPS: HTTPS é uma combinação do protocolo HTTP com uma camada adicional de segurança chamada SSL/TLS (Secure Sockets Layer/Transport Layer Security). A comunicação é feita através do protocolo HTTP, o mesmo utilizado para navegar na web. Isso facilita a integração, pois é um protocolo bem conhecido e suportado por diversas plataformas.  
   * Métodos HTTP: Utilizamos métodos HTTP para realizar diferentes operações:  
         * GET: Para obter informações.  
         * POST: Para enviar novas informações.  
         * PUT: Para atualizar informações existentes.  
         * DELETE: Para remover informações.  
   * Formato de Dados: As requisições e respostas são geralmente em formato JSON, que é leve e fácil de interpretar. Isso torna a troca de dados eficiente e simples de manipular.  
   * Códigos de Status: Cada resposta da API inclui um código de status HTTP que indica o resultado da operação, como:  
         * 200: Sucesso.  
         * 400: (BadRequest) Erros nos dados enviados.  
         * 404: Recurso não encontrado.  
         * 500: Erro no servidor.
* A API NFE.io permitie que você escolha entre duas opções para emitir uma nota fiscal, são elas:  
   * **Sem cálculo do imposto** \- As informações tributárias serão fornecidas por você, ou seja, a nota fiscal será emitida sem a utilização do motor de cálculo tributário.  
   Clique aqui para mais informações  
   * **Com cálculo do imposto** \- As informações tributárias serão fornecidas pela NFE.io, de acordo com os parâmetros informados no grupo "taxDetermination".  
   Veja o detalhamento mais abaixo.

### 2\. Visão Geral do fluxo de emissão de nota fiscal.

![](https://nfe.io/docs/app/uploads/2025/02/NFe-Taxes-Diagram.drawio-5.png)

## Primeiros passos

### 1\. Emitir primeira nota fiscal

Pronto, todos os passos antecessores de emissão de suas notas fiscais eletrônicas estão concluídos.

Colocamos um exemplo do mínimo de dados para serem informados à nossa API, caso precise ou queira verificar o restante da documentação, estará disponível em: [Documentação completa.][34]

Os campos mínimos para serem enviados são os dados do comprador (buyer) e os produtos (items).  
**Obs.1: O grupo "taxDetermination" substituí o grupo "tax" (dados dos impostos da nota fiscal) para que o sistema acione automaticamente o Motor de Cálculo de Tributos. Desta forma o grupo "tax" será preenchido com o resultado da consulta no motor de cálculo de tributos de forma automática.**

**Saiba mais:** [O que é motor de cálculo de tributos][35]

Abaixo, a url e um json de exemplo contendo os dados mínimos para a emissão de uma nota fiscal **com a utilização do motor de cálculo de tributos.**  
**Saiba mais:** [Entendendo a estrutura do json (layout de integração)][36]  

> **Observação:** Substitua \{companyId\} pela ID gerada no passo de criação da Empresa e a \{statetaxId\} pela ID gerada no passo de criação da Inscrição Estadual.
> 
> **O método HTTP utilizada no envio da nota fiscal é o "POST", então verifique no seu postman se está preenchido corretamente.**

`POST: https://api.nfse.io/v2/companies/{companyId}/statetaxes/{statetaxId}/productinvoices`

```json
{
    "buyer": {
        "name": "NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL",
        "federalTaxNumber": 8662968678,
        "address": {
            "city": {
                "code": "3550308",
                "name": "jundiai"
            },
            "state": "SP",
            "district": "centro",
            "street": "rua petronilha antunes",
            "postalCode": "13207760",
            "number": "204",
            "country": "BRA"
        }
    },
    "items": [
        {
            "code": "2617",
            "unitAmount": 9.98,
            "quantity": 5,
            "ncm": "47079000",
            "cest": null,
            "description": "FEIJAO BOLINHA CAMIL 500G NF ENTRADA 1030099 14/05/2018",
            "codeGTIN": "9999999999999",
            "taxDetermination": {
                "BuyerTaxProfile": "<string>",
                "IssuerTaxProfile": "<string>",
                "acquisitionPurpose": "<string>",
                "OperationCode": "<number>",
                "Origin": "<string>"
            }
        }
    ]
}
```

### 2\. Detalhamento dos campos do grupo "taxDetermination":

O grupo "taxDetermination" define o cenário que representa a operação tributária realizada e é identificada por, basicamente, quatro códigos: natureza da operação, perfil do remetente, o perfil do destinatário e a finalidade da aquisição. Os quatro códigos combinados dão o significado para a operação realizada, exemplo: Industria rementendo para o varejo material de sua produção.  

#### **BuyerTaxProfile**

* Para obter os valores disponíveis para preenchimento do campo "BuyerTaxProfile", faça uma chamada na API de listagem dos perfis fiscais do destinatário confome exemplo abaixo  
**Veja a documentação da API:** [BuyerTaxProfile][37]

**Destinatário/Perfil Destino**  
Tabela parcial com os perfis mais comuns.

| Código                                  | Descrição                                 |
| --------------------------------------- | ----------------------------------------- |
| closed\_warehouse                       | Depósito temporário (Fullfilment)         |
| wholesale                               | Atacadista                                |
| company\_abroad                         | Comercial exportadora (inclusive trading) |
| final\_consumer\_icms\_contributor      | Consumidor final contribuinte do ICMS     |
| final\_consumer\_non\_icms\_contributor | Consumidor final não contribuinte do ICMS |
| importer                                | Importador                                |
| industry                                | Indústria                                 |
| NationalSimple                          | Optante pelo Simples Nacional             |
| retail                                  | Varejista                                 |

---

#### **IssuerTaxProfile**

* Para obter os valores disponíveis para preenchimento do campo "IssuerTaxProfile", faça uma chamada na API de listagem dos perfis fiscais do emissor confome exemplo abaixo:  
**Veja a documentação da API:** [IssuerTaxProfile][38]

**Remetente/Perfil Origem**  
Tabela parcial com os perfis mais comuns.

| Código    | Descrição  |
| --------- | ---------- |
| wholesale | Atacadista |
| importer  | Importador |
| industry  | Indústria  |
| retail    | Varejista  |

---

#### **AcquisitionPurpose**

* Para obter os valores disponíveis para preenchimento do campo "AcquisitionPurpose", faça uma chamada na API de listagem de finalidades de aquisição confome exemplo abaixo:  
**Veja a documentação da API:** [AcquisitionPurpose][39]

**Finalidade de aquisição**  
Tabela parcial com as finalidades de aquisição mais comuns.

| Código | Descrição                                                            |
| ------ | -------------------------------------------------------------------- |
| 220    | Compra de bem para o ativo imobilizado                               |
| 569    | Compra para comercialização                                          |
| 202    | Compra para insumo                                                   |
| 43     | Compra de material para uso ou consumo                               |
| 197    | Entrada de amostra grátis                                            |
| 353    | Entrada de bonificação                                               |
| 198    | Entrada de mercadoria em demonstração                                |
| 201    | Entrada de mercadoria ou bem recebido para conserto ou reparo        |
| 205    | Entrada de mercadoria recebida em consignação industrial             |
| 204    | Entrada de mercadoria recebida em consignação mercantil              |
| 189    | Entrada de mercadoria recebida para depósito em armazém geral        |
| 188    | Entrada de mercadoria recebida para depósito em depósito fechado     |
| 325    | Recebimento em transferência de material para uso ou consumo         |
| 175    | Recebimento em transferência para comercialização                    |
| 174    | Recebimento em transferência para industrialização ou produção rural |
| 200    | Retorno de mercadoria remetida em exposição ou feira                 |
| 320    | Transferência de bem do ativo imobilizado                            |

---

#### **OperationCode**

* Para obter os valores disponíveis para preenchimento do campo "OperationCode", faça uma chamada na API de listagem de códigos da operação confome exemplo abaixo:  
**Veja a documentação da API:** [OperationCode][40]

**Natureza de Operação**  
Tabela parcial com as operações mais comuns.

| Código | Descrição                                                                                                                                                                          |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 159    | Remessa de amostra grátis                                                                                                                                                          |
| 549    | Remessa de mercadoria em consignação industrial                                                                                                                                    |
| 547    | Remessa de mercadoria em consignação mercantil                                                                                                                                     |
| 160    | Remessa de mercadoria em demonstração                                                                                                                                              |
| 162    | Remessa de mercadoria ou bem para conserto ou reparo                                                                                                                               |
| 101    | Remessa de mercadoria ou bem para exposição ou feira                                                                                                                               |
| 537    | Remessa de mercadoria recebida de terceiros em bonificação                                                                                                                         |
| 105    | Remessa de mercadoria para armazém geral                                                                                                                                           |
| 104    | Remessa de mercadoria para depósito fechado                                                                                                                                        |
| 145    | Saída em transferência de bem do ativo imobilizado                                                                                                                                 |
| 148    | Saída em transferência de material de uso ou consumo                                                                                                                               |
| 108    | Saída em transferência de mercadoria adquirida ou recebida de terceiros                                                                                                            |
| 107    | Saída em transferência de produção do estabelecimento                                                                                                                              |
| 147    | Venda de bem do ativo imobilizado                                                                                                                                                  |
| 121    | Venda de mercadoria adquirida ou recebida de terceiros                                                                                                                             |
| 120    | Venda de produção do estabelecimento                                                                                                                                               |
| 72     | Compra de mercadoria arrematada em leilão.                                                                                                                                         |
| 569    | Compra para comercialização.                                                                                                                                                       |
| 630    | Compra pelo sistema de marketing direto para revendedores que operem na modalidade de venda porta-a-porta exclusivamente a consumidores finais ou em bancas de jornais e revistas. |

---

#### **Origin**

* Códigos do campo origem do material  
   * O código de origem do material é um código oficial e representa o conteúdo de importação do material. Segue a lista de todos os códigos disponíveis:

| Código | Descrição                                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------------------------- |
| 0      | Nacional, exceto as indicadas nos códigos 3, 4, 5 e 8                                                                |
| 1      | Estrangeira - Importação direta, exceto a indicada no código 6                                                       |
| 2      | Estrangeira - Adquirida no mercado interno, exceto a indicada no código 7                                            |
| 3      | Nacional, mercadoria ou bem com Conteúdo de Importação superior a 40% e inferior ou igual a 70%                      |
| 4      | Nacional, cuja produção tenha sido feita em conformidade com os PPB de que tratam as legislações citadas nos Ajustes |
| 5      | Nacional, mercadoria ou bem com Conteúdo de Importação inferior ou igual a 40%                                       |
| 6      | Estrangeira - Importação direta, sem similar nacional, constante em lista da CAMEX e gás natural                     |
| 7      | Estrangeira - Adquirida no mercado interno, sem similar nacional, constante em lista da CAMEX e gás natural          |
| 8      | Nacional, mercadoria ou bem com Conteúdo de Importação superior a 70%                                                |

---

### 3\. Integração da nota fiscal no padrão "json".

1. Você deverá enviar os dados preenchidos corretamente com as informações da sua nota fiscal e clicar no botão "Send" (Enviar).  
![](https://nfe.io/docs/app/uploads/2025/02/Issue-invoice-2.png)
2. Ao sucesso da requisição, será fornecido uma ID da nota fiscal utilizada no processamento da emissão.  
![](https://nfe.io/docs/app/uploads/2025/02/Issue-invoice-response.png)

### 4\. Importação da url do postman

Novamente, fornecemos uma URL de importação no POSTMAN com todas essas requisiçôes já inclusas. Basta inserir sua Autorização em cada requisição e alterar os dados fornecidos.

```json
https://api.postman.com/collections/13456751-f3769b82-5291-445b-b7bf-8fc0ffcab9b2?access_key=PMAT-01JKDTXTXB7DN8645BWG6K7C7K
```

## Próximos passos

1. [Consultar uma nota fiscal][21]
2. [Consultar o XML de uma nota fiscal emitida][22]
3. [Consultar o PDF (danfe) de uma nota fiscal emitida][23]
4. [Motor de Cálculo de Tributos][24]

## Veja também:

* [Nossos segmentos][41]
* [Sobre a NFE.io][42]
* [Junte-se ao nosso time][43]

[1]: #Integracao%5Fda%5FNota%5FFiscal%5FEletronica%5Futilizando%5Fo%5FMotor%5Fde%5FCalculo%5Fde%5FTributos%5FNF-e%5FNFC-e
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Proximos%5Fpassos
[4]: #Requisitos
[5]: #Tutorial
[6]: #1%5FIntroducao
[7]: #2%5FVisao%5FGeral%5Fdo%5Ffluxo%5Fde%5Femissao%5Fde%5Fnota%5Ffiscal
[8]: #Primeiros%5Fpassos
[9]: #1%5FEmitir%5Fprimeira%5Fnota%5Ffiscal
[10]: #2%5FDetalhamento%5Fdos%5Fcampos%5Fdo%5Fgrupo%5FquottaxDeterminationquot
[11]: #BuyerTaxProfile
[12]: #IssuerTaxProfile
[13]: #AcquisitionPurpose
[14]: #OperationCode
[15]: #Origin
[16]: #3%5FIntegracao%5Fda%5Fnota%5Ffiscal%5Fno%5Fpadrao%5Fquotjsonquot
[17]: #4%5FImportacao%5Fda%5Furl%5Fdo%5Fpostman
[18]: #Proximos%5Fpassos-2
[19]: #Veja%5Ftambem
[20]: https://nfe.io/docs/documentacao/conceitos/notas-fiscais/
[21]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica/#1%5FConsultar%5Fnota%5Ffiscal
[22]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica/#2%5FConsultar%5FXML
[23]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica/#3%5FConsultar%5FPDF%5FDanfe
[24]: https://nfe.io/docs/documentacao/nota-fiscal-eletronica/motor-de-calculo-de-imposto/
[25]: https://nfe.io/docs/conceitos/notas-fiscais/
[26]: https://nfe.io/docs/nota-fiscal-eletronica/credenciamento-nf-e/
[27]: https://nfe.io/docs/certificado-digital/conceitos/
[28]: https://p.nfe.io/pt-br/certificado-digital-20off
[29]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/primeiros-passos/#1%5FCriar%5Fuma%5Fempresa
[30]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/primeiros-passos/#2%5FFazer%5Fupload%5Fdo%5Fcertificado%5Fna%5Fplataforma
[31]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/primeiros-passos/#3%5FCriar%5Finscricao%5Festadual
[32]: https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-produto-v2/
[33]: https://nfe.io/docs/comum/postman/
[34]: https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-produto-v2/
[35]: https://nfe.io/docs/sem-categoria/motor-de-calculo-de-imposto/
[36]: https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-produto-v2/#/Product%20Invoices/post%5Fv2%5Fcompanies%5F%5FcompanyId%5F%5Fstatetaxes%5F%5FstatetaxId%5F%5Fproductinvoices
[37]: https://nfe.io/docs/desenvolvedores/rest-api/calculo-de-impostos-v1/#/C%C3%B3digos%20Auxiliares/get%5Ftax%5Fcodes%5Frecipient%5Ftax%5Fprofile
[38]: https://nfe.io/docs/desenvolvedores/rest-api/calculo-de-impostos-v1/#/C%C3%B3digos%20Auxiliares/get%5Ftax%5Fcodes%5Fissuer%5Ftax%5Fprofile
[39]: https://nfe.io/docs/desenvolvedores/rest-api/calculo-de-impostos-v1/#/C%C3%B3digos%20Auxiliares/get%5Ftax%5Fcodes%5Facquisition%5Fpurpose
[40]: https://nfe.io/docs/desenvolvedores/rest-api/calculo-de-impostos-v1/#/C%C3%B3digos%20Auxiliares/get%5Ftax%5Fcodes%5Foperation%5Fcode
[41]: https://nfe.io/segmentos/
[42]: https://nfe.io/sobre/
[43]: https://nfe.io/carreira/

---

## Estratégia de Contingência

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/estrategia-de-contingencia/index.md

## Definição da estratégia para emissão de nota fiscal (NF-e) em contingência.

#### 1\. Entenda o parâmetro "SwitchAuthorizerStrategy"

O parâmetro "SwitchAuthorizerStrategy" é utilizado para definir a regra a ser utilizada na emissão de notas fiscais em contingência.

* O valor do parâmetro "SwitchAuthorizerStrategy" deve ser definido no cadastro da empresa, mas também pode ser atualizado posteriormente.  
   * Segue abaixo os possíveis valores para o parâmetro "SwitchAuthorizerStrategy":  
         * StateTaxAuthorityStatusUnavailable  
         * Manual

#### 2\. Entenda como funciona a estratégia de contingência.

Detalharemos a seguir como deverá funcionar a estratégia de contingência de acordo com o valor definido para o campo "SwitchAuthorizerStrategy" no cadastro da "State Tax":

* **StateTaxAuthorityStatusUnavailable** \- A decisão do momento em que se inicia a emissão das notas fiscais em contingência é da NFE.io, ou seja, ao identificar que uma SEFAZ está com instabilidade, nosso time vai alterar o parâmetro da SEFAZ para que todas as empresas desta UF que estiverem com o parâmetro "SwitchAuthorizerStrategy" definido com o valor "StateTaxAuthorityStatusUnavailable", iniciem as emissões no ambiente de contingência EPEC.
* **Manual** \- A decisão da data e hora em que se inicia a emissão das notas fiscais em contingência é do cliente e nesse caso o cliente deverá enviar uma requisição de alteração "PUT" para o StateTax no momento em que se deseja que as notas sejam enviadas para o ambiente nacional EPEC, conforme exemplo abaixo:  

```json  
{  
"authorizer": "EPEC",  //[EPEC, Normal]  
"reason": "SEFAZ autorizadora indisponível"  
}  
```  

![](https://nfe.io/docs/app/uploads/2025/02/Change-a-statetax.png)  

**Obs.1**: Nesta situação, quando o parâmetro "SwitchAuthorizerStrategy" estiver definido como "Manual" e o parâmetro "authorizer" for alterado para "EPEC", todas as novas notas fiscais recepcionadas pela API NFE.io serão encaminhadas para o ambiente nacional EPEC.  
**Obs.2**: As notas fiscais que já estavam sendo processadas quando a estratégia de comunicação foi alterada para EPEC, não serão encaminhadas para o ambiente nacional EPEC e permanecerão represadas até que a comunicação com a SEFAZ de origem seja reestabelecida.  

![](https://nfe.io/docs/app/uploads/2025/02/Change-a-statetax-Normal.png)

:::danger
**IMPORTANTE:** Todas as notas fiscais emitidas no ambiente nacional EPEC serão encaminhadas para a autorização na SEFAZ de origem, logo que a estratégia de comunicação for alterada de "EPEC" para "Normal".  
:::


[1]: #Definicao%5Fda%5Festrategia%5Fpara%5Femissao%5Fde%5Fnota%5Ffiscal%5FNF-e%5Fem%5Fcontingencia
[2]: #1%5FEntenda%5Fo%5Fparametro%5FquotSwitchAuthorizerStrategyquot
[3]: #2%5FEntenda%5Fcomo%5Ffunciona%5Fa%5Festrategia%5Fde%5Fcontingencia
[4]: https://nfe.io/docs/documentacao/nota-fiscal-eletronica/emitir-uma-nota-fiscal-de-produto/

---

## Primeiros passos - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/primeiros-passos/index.md

# Primeiros Passos para Integração da Nota Fiscal Eletrônica.

A Nota fiscal eletrônica é o documento digital fiscal usada para a documentação de operaçóes de circulação de mercadorias ou prestação de serviço, seja transporte no mesmo estado, quanto entre estados.

**Saiba mais:** [O que é nota fiscal eletrônica?][15]

## Ao final desse tutorial, você será capaz de:

[1\. Cadastrar uma empresa][16]  
[2\. Fazer upload de um certificado na plataforma][17]  
[3\. Cadastrar uma inscrição estadual][18]

## Próximos passos

1. [Emitir uma nota fiscal de produto][19]
2. [Emitir uma nota fiscal de produto utilizando o Motor de Cálculo de Tributos][20]
3. [Consultar uma nota fiscal][21]
4. [Consultar o XML de uma nota fiscal emitida][22]
5. [Consultar o PDF (danfe) de uma nota fiscal emitida][23]

## Requisitos

* [Qual tipo de nota fiscal devo emitir?][24]
* [Como fazer o **credenciamento** da minha empresa para emissão de nota?][25]
* [Quer saber mais sobre certificado digital?][26]
* [Desconto para adquirir seu certificado digital **A1?**][27]

## Tutorial

A partir desse momento faremos uma breve explicação de como realizar cadastros necessários para possibilitar a integração de Nota fiscal de Produto com a API oferecida pela NFE.io.

**Veja mais sobre a** [Documentação da API][28]

> Você pode realizar a importação da url no Postman para ter todos os seguintes exemplos através do link:

```json
https://api.postman.com/collections/13456751-f3769b82-5291-445b-b7bf-8fc0ffcab9b2?access_key=PMAT-01JKDTXTXB7DN8645BWG6K7C7K
```

Tutorial de como importar a url no postman [Clique aqui][29]

## Primeiros passos

Antes de tudo, você precisará realizar um cadastro na nossa plataforma [app.nfe.io][30]. Depois, você terá que pegar a chave de autorização do nosso sistema.

> Devemos atentar para copiar a autorização referente 'Nota fiscal'

## Ambiente: Homologação ou Produção

A NFE.io oferece dois ambientes para emissão de NF-e e NFC-e. O ambiente é configurado **na Inscrição Estadual** (campo `environmentType`), não na empresa — uma mesma empresa pode ter IEs em estados diferentes, cada uma com seu próprio ambiente.

| Recurso | Homologação (`Test`) | Produção (`Production`) |
|---|---|---|
| **Inscrição Estadual** | Obrigatória, com `environmentType: "Test"` | Obrigatória, com `environmentType: "Production"` |
| **Certificado Digital** | ⚠️ **Obrigatório** | ⚠️ **Obrigatório** |
| **Trânsito da nota** | SEFAZ de homologação (ambiente real do órgão) | SEFAZ de produção (ambiente real do órgão) |
| **Validade fiscal** | Sem validade fiscal | Com validade fiscal |
| **NFC-e (`nFCe`)** | CSC obrigatório (Código de Segurança do Contribuinte) | CSC obrigatório |

### Por que o certificado é obrigatório mesmo em homologação?

Diferente da NFS-e (que roda em servidores NFE.io simulando prefeituras), o ambiente de **Homologação da SEFAZ é o ambiente real do órgão estadual** — apenas marcado como teste. A SEFAZ valida e responde a cada requisição assim como em produção, e por isso **exige assinatura digital ICP-Brasil em todas as transmissões**, inclusive em homologação.

Você precisa do certificado A1 vinculado à empresa **antes** de qualquer tentativa de emissão, mesmo só para testes.

:::info[Diferente de NFS-e]
Para **NFS-e**, o certificado digital é **opcional em ambiente de testes**, porque o ambiente de testes da NFE.io para NFS-e usa servidores próprios simulando prefeituras (sem trânsito real ao órgão municipal). Veja a cadência para NFS-e em [Primeiros Passos — NFS-e](/docs/documentacao/nota-fiscal-servico-eletronica/primeiros-passos).
:::

:::tip Inscrição Municipal não se aplica
NF-e e NFC-e não usam **Inscrição Municipal (IM)**. Se você está usando o wizard de criar empresa pelo painel, marque a Etapa de IM como **"É isento"** e prossiga. A IM só é exigida para empresas que emitem NFS-e.
:::

- - -

## 1\. Obter a chave de autorização (apikey).

**Veja como pegar a chave de autorização na plataforma:** [Autenticação][31]

> **Lembre-se:** Após importar a url do postman e copiar a chave de autenticação para nota fiscal eletrônica, você deverá adicionar em cada requisição na aba "Auth", Auth Type "API Key", Key "Authorization", Value "inserir a chave" ou na aba "Headers" (cabeçalhos) a chave em "Authorization" (autorização).  
> 
> * Como configurar a chave de autorização no Postman.  
> ![](https://nfe.io/docs/app/uploads/2025/02/Auth.png)  
> ![](https://nfe.io/docs/app/uploads/2025/02/Headers-Auth.png)

## 2\. Criar uma empresa

Para emitir as notas fiscais, é necessário criar uma empresa. Neste momento será obrigatório a identificação do CNPJ, endereço e tipo de regime tributário.

Ao sucesso da requisição, será gerada um chave de identificação (ID), e você deve copiá-la para os passos seguintes.

Abaixo, a url e um json de exemplo contendo os dados para a criação de uma empresa.

**Saiba mais:** [Entendendo a estrutura do json (layout de integração)][32]

> O método HTTP utilizada na criação da empresa é o "POST", portanto, verifique no seu postman se está preenchido corretamente.

```
POST: https://api.nfse.io/v2/companies/
```

```json
 {  
  "company": {
    "name":"RAZAO SOCIAL DA EMPRESA",
    "federalTaxNumber": 99999999000199,
    "taxRegime": "SimplesNacional",
    "address":{  
     "state":"SP",
     "city":{   
        "code":"3550308",
        "name":"São Paulo"
     },
     "district":"BAIRRO",
     "additionalInformation":" INFORMAÇÃO ADICIONAL",
     "street":"AV NOME DA RUA",
     "number":"1111",
     "postalCode":"14940001",
     "country":"BRA"
    }
  }
}
```

1. Você deverá enviar os dados preenchidos corretamente com as informações da sua empresa e clicar no botão "Send" (Enviar).  
>   * Create a Company  
>   ![](https://nfe.io/docs/app/uploads/2025/02/Create-a-comapny-2.png)
2. Você receberá uma ID de empresa após o envio e sucesso da requisição.  
Será necerrário copiá-la para dar continuidade nos passos seguintes.  
>   * Company Id  
>   ![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/company-id3-modified.png)

> Atenção: Em todas as requisições na API, deverá ser informado a ID da empresa fornecida no sucesso de requisição.

## 3\. Fazer upload do certificado na plataforma

### O que é um certificado digital?

Para entender mais sobre o que é um certificado digital, escrevemos um resumo em: [Tudo sobre Certificado Digital.][26]

Na nota fiscal eletrônica de produto devemos realizar uma requisição para o envio do certificado digital que será utilizado como autenticador com o Governo, onde deverá ser enviado o arquivo .pfx e a senha.

> **Atenção:** Não se preocupe, após a inserção do certificado na nossa plataforma, todos os dados são criptografados para maior segurança.

Abaixo, a url e um json de exemplo contendo os dados para realizar o envio do certificado.

> **Observação:** Substitua \{companyId\} pela ID gerada no passo de criação da empresa.  
> **O método HTTP utilizada no envio do certificado é o "POST", portanto verifique no seu postman se está preenchido corretamente.**

`POST: https://api.nfse.io/v2/companies/{companyId}/certificates`

1. Você deverá selecionar o arquivo .pfx em seus arquivos juntamente com a senha e clicar no botão "Send" (Enviar).  
>   * Uploading a Certificate  
>   ![](https://nfe.io/docs/app/uploads/2025/02/Upload-certificate-1.png)
2. Após o sucesso da requisição, será informado alguns dados sobre o certificado, tais como:  
   * A validade do certificado  
   * Status se está ativou ou inativo na plataforma  
   * Thumbprint  
   * Dados sobre o emissor do certificado  
![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/certificate-created-modified.png)

## 4\. Criar inscrição estadual

O terceiro passo será criar o "State Tax", que identifica na nossa plataforma a[ Inscrição Estadual][33] usada pela empresa.

Saiba mais sobre [ Inscrição Estadual][33].

1. No cadastro da Inscrição Estadual você vai definir as seguintes informações:  
   * "processingDetails" - Estratégia para emissão de nota fiscal em contingência.  
   (clique [aqui][34] para mais informações).  
   * "type" - Tipo de nota fiscal (NF-e \[nFe\] ou NFC-e \[nFCe\]).  
   * "environmentType" -Ambiente da SEFAZ (Produção \[production\] ou Homologação \[test\]).  
   * "serie" - Série da nota fiscal.  
   * "number" - Número inicial da nota fiscal.  
   * "code" - UF (define qual é a SEFAZ que vai recepcionar as notas fiscais).  
   * "specialTaxRegime" - Regime especial de tributação (specialTaxRegime).  
   * "taxNumber" - Número da Inscrição Estadual.  
   * "securityCredential" - Código de segurança do contribuinte **(necessário para emissão de NFCe)**.

A inscrição estadual tem possibilidade de ser uma ou mais por estado para o mesmo CNPJ. Portanto, separamos a requisição para melhor identificação e organização das sequências númericas.

Ela também é responsável por identificar o ambiente em que a nota fiscal será emitida, sendo disponível como "EnvironmentType" (tipo de ambiente), com os valores "Test" (desenvolvimento) e "Production" (produção).

> Por padrão o ambiente criado na plataforma é **"Test"** (desenvolvimento).

---

> O grupo de parâmetros "processingDetails" se refere ao detalhamento da estratégia de contingência que será adotada. Clique [aqui][34] para obter mais informações.

---

Abaixo, a url e um json de exemplo contendo os dados básicos para a criação de uma inscrição estadual.

> **Observação:** Substitua \{companyId\} pela ID gerada no passo anterior.

---

> **O método HTTP utilizada na criação da inscrição estadual é o "POST", portanto, verifique no seu postman se está preenchido corretamente.**

---

`POST: https://api.nfse.io/v2/companies/{companyId}/stateTaxes`

```json
{
  "stateTax": {
    "code": "SP",
    "taxNumber": "99999999999",
    "specialTaxRegime": "automatico",
    "environmentType": "Test",
    "type": "nFe",
    "serie": 1,
    "number": 1,
    "processingDetails": {
        "SwitchAuthorizerStrategy" : "StateTaxAuthorityStatusUnavailable"
        // "SwitchAuthorizerStrategy" : "Manual"
    },
    //O grupo abaixo deve ser informado somente se o 'type' for 'nFCe'
    "securityCredential": {
        "id": 1,
        "code": "999999999999999"
    }
  }
}
```

Devemos atentar para os valores de Série e Número (serie e number), que são utilizados pela SEFAZ para sequenciar as notas emitidas por uma empresa.

Caso você já emita nota, precisará identificar qual a série e o último número emitido, com isso podemos continuar a emissão de onde parou.

Se preferir, poderá identificar com seu contador, uma nova série e número para emissão de nota com a nossa plataforma.

1. Você deverá enviar os dados preenchidos corretamente com as informações da sua inscrição estadual e clicar no botão "Send" (Enviar).  
>   * Create a StateTax  
>   ![](https://nfe.io/docs/app/uploads/2025/02/Create-a-statetax.png)
2. Você receberá uma ID da inscrição estadual após o envio e sucesso da requisição.  
>   * StateTax Id  
>   ![](https://nfe.io/docs/static/docs/nota-fiscal-eletronica/state-tax-created-modified.png)

## Importação da url do postman

Novamente, fornecemos uma URL de importação no POSTMAN com todas essas requisiçôes já inclusas. Basta inserir sua Autorização em cada requisição e alterar os dados fornecidos.

```json
https://api.postman.com/collections/13456751-f3769b82-5291-445b-b7bf-8fc0ffcab9b2?access_key=PMAT-01JKDTXTXB7DN8645BWG6K7C7K
```

## Próximos passos

1. [Emitir uma nota fiscal de produto][19]
2. [Emitir uma nota fiscal de produto utilizando o Motor de Cálculo de Tributos][20]
3. [Consultar uma nota fiscal][21]
4. [Consultar o XML de uma nota fiscal emitida][22]
5. [Consultar o PDF (danfe) de uma nota fiscal emitida][23]

## Veja também:

* [Nossos segmentos][35]
* [Sobre a NFE.io][36]
* [Junte-se ao nosso time][37]

[15]: /docs/documentacao/conceitos/notas-fiscais
[19]: /docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/emitir-uma-nota-fiscal-de-produto
[20]: /docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/emitir-uma-nota-fiscal-de-produto-utilizando-o-motor-de-calculo-de-tributos
[21]: /docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica#1-consultar-nota-fiscal
[22]: /docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica#2-consultar-xml
[23]: /docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/como-consultar-nota-fiscal-eletronica#3-consultar-pdf-danfe
[24]: /docs/documentacao/conceitos/notas-fiscais
[25]: /docs/documentacao/nota-fiscal-produto-eletronica/credenciamento
[26]: /docs/documentacao/certificado-digital/conceitos
[27]: https://p.nfe.io/pt-br/certificado-digital-20off
[28]: /docs/desenvolvedores/rest-api/nota-fiscal-de-produto-v2
[29]: /docs/documentacao/nota-fiscal-produto-eletronica/importar-colecao-postman
[30]: https://app.nfe.io/
[31]: /docs/documentacao/nossa-plataforma/chaves-de-autenticacao
[32]: /docs/desenvolvedores/rest-api/nota-fiscal-de-produto-v2
[33]: /docs/documentacao/nota-fiscal-produto-eletronica/conceitos
[34]: /docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/estrategia-de-contingencia
[35]: https://nfe.io/segmentos/
[36]: https://nfe.io/sobre/
[37]: https://nfe.io/carreira/

---

## Template Planilha Completa

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/template-de-planilha-para-processamento-de-notas-fiscais/index.md

# Planilha para Processamento de Notas Fiscais em Lote

> ⚠️ **Documento em fase de homologação**

Esta planilha foi desenvolvida para apoiar clientes da NFE.io na emissão de Notas Fiscais Eletrônicas de Produtos (NF-e).

A planilha é composta por várias abas de cadastro, cada uma com campos obrigatórios e opcionais que seguem os requisitos da SEFAZ e da plataforma NFE.io.

**Premissa:** Toda informação cadastral, tributária e fiscal é de responsabilidade do usuário. Os cenários existentes são exemplos fictícios não representado uma situação real.

### Passos:
1. Respeite os formatos esperados para cada campo.
2. Mantenha os códigos consistentes entre as abas.
3. Verifique a validade das informações fiscais e tributárias com seu contador.
4. Não é permitida a duplicidade de códigos nos cadastros.
5. Observe a consistência de datas nos campos DataInicio e DataFim.
6. Cada Produto precisa estar associado a um Grupo de Produtos
7. Cada Grupo de Produtos precisa ter uma Determinação Fiscal
8. Para emitir uma Nota Fiscal a tabela NotasFiscais e ItensNF necessariamente precisam estar preenchidas de forma correta (Codigo corretamente relacionado nas duas tabelas)
9. Deverá haver a correta correspondência da Determinação Fiscal com o Grupo Produto e com os Produtos da Nota Fiscal. Esse é um pré-requisito para emitir a Nota Fiscal.

### Boas Práticas:
- Valide os dados antes de enviar à NFE.io para evitar rejeições da SEFAZ.
- Atualize os cadastros sempre que houver alterações fiscais, de produto ou de cliente.
- Salve versões de backup da planilha para controle e auditoria.
- Consulte seu contador sempre que tiver dúvidas sobre alíquotas, CFOPs e enquadramentos fiscais.
- Mantenha consistência entre os dados fiscais e comerciais apresentados.

---

Este arquivo descreve a estrutura esperada do arquivo XLSX para processamento de notas fiscais na API NFE.io.

## Abas do Arquivo XLSX

O arquivo deve conter as seguintes abas (sheets):

### GrupoProdutos
| Coluna | Descrição | Obrigatório |
|--------|-----------|-------------|
| Codigo | Código único do grupo | Sim |
| DescricaoGrupo | Descrição do grupo de produtos | Sim |
| Origem | Código de origem da mercadoria (0-8) | Sim |
| UnidadeMedida | Unidade de medida padrão do grupo | Sim |
| BeneficioFiscal | Código do benefício fiscal aplicado | Não |
| MVA | Margem de Valor Agregado (%) | Não |
| SubstituicaoTributaria | Indicador de substituição tributária (S/N) | Não |
| DataInicio | Data de início de vigência (DD/MM/AAAA) | Não |
| DataFim | Data de fim de vigência (DD/MM/AAAA) | Não |

### Produto
| Coluna | Descrição | Obrigatório |
|--------|-----------|-------------|
| Codigo | Código único do produto | Sim |
| Descricao | Descrição do produto | Sim |
| CodigoGrupoProdutos | Referência ao código do grupo de produtos | Sim |
| GTIN | Código GTIN/EAN do produto | Não |
| NCM | Código NCM (Nomenclatura Comum do Mercosul) | Sim |
| CEST | Código CEST (Código Especificador da Substituição Tributária) | Não |
| PesoBruto | Peso bruto do produto em kg | Não |
| PesoLiquido | Peso líquido do produto em kg | Não |
| DataInicio | Data de início de vigência (DD/MM/AAAA) | Não |
| DataFim | Data de fim de vigência (DD/MM/AAAA) | Não |

### DeterminacaoFiscal
| Coluna | Descrição | Obrigatório |
|--------|-----------|-------------|
| Codigo | Código único da determinação fiscal | Sim |
| TipoOperacao | Tipo de operação (0=Entrada, 1=Saída) | Sim |
| Finalidade | Finalidade da operação (1=Normal, 2=Complementar, 3=Ajuste, 4=Devolução) | Sim |
| NaturezaOperacao | Descrição da natureza da operação | Sim |
| RegimeEmitente | Regime tributário do emitente (1-6, veja tabela de referência) | Sim |
| UFEmitente | UF do emitente (sigla do estado) | Sim |
| CodigoMunicipioEmitente | Código IBGE do município do emitente | Sim |
| RegimeDestinatario | Regime do destinatário (1=Consumidor Final, 2=Normal) | Sim |
| UFDestinatario | UF do destinatário (sigla do estado) | Sim |
| CodigoMunicipioDestinatario | Código IBGE do município do destinatário | Sim |
| CodigoGrupoProdutos | Referência ao código do grupo de produtos | Sim |
| SubstituicaoTributaria | Indicador de substituição tributária (S/N) | Não |
| CFOP | Código Fiscal de Operações e Prestações | Sim |
| OrigemICMS | Origem da mercadoria para ICMS (0-8, veja tabela OrigemICMS) | Sim |
| CSTICMS | CST do ICMS (Código de Situação Tributária) | Sim |
| CSOSN | CSOSN para Simples Nacional | Não |
| AliquotaICMS | Alíquota do ICMS em percentual | Não |
| AliquotaICMSST | Alíquota do ICMS ST em percentual | Não |
| ValorDesoneracaoICMS | Valor do ICMS desonerado em reais (mapeado para vICMSDeson) | Não |
| MotivoDesoneracaoICMS | Motivo da desoneração do ICMS. Valores aceitos: 3=Uso na agropecuária, 9=Outros, 12=Órgão de fomento | Não |
| DeduzDesoneracaoICMS | Indica se o ICMS desonerado deduz do total da nota (indDeduzDeson). Sim/Nao (ou 1/0). Padrão Nao | Não |
| BaseCalculoICMS | Valor da base de cálculo do ICMS em reais (vBC) | Não |
| ModalidadeBaseCalculoICMS | Modalidade da BC do ICMS (modBC): 0=MVA, 1=Pauta, 2=Preço Tabelado, 3=Valor da Operação. Padrão 3 quando há base | Não |
| PercentualReducaoBCICMS | Percentual de redução da base de cálculo do ICMS (pRedBC) | Não |
| ValorICMS | Valor do ICMS em reais (vICMS) | Não |
| CSTPIS | CST do PIS (Código de Situação Tributária, veja tabela CST PIS/COFINS) | Sim |
| AliquotaPIS | Alíquota do PIS em percentual | Não |
| CSTCOFINS | CST do COFINS (Código de Situação Tributária, veja tabela CST PIS/COFINS) | Sim |
| AliquotaCOFINS | Alíquota do COFINS em percentual | Não |
| AliquotaIPI | Alíquota do IPI em percentual | Não |
| AliquotaFCP | Alíquota do Fundo de Combate à Pobreza em percentual | Não |
| IncentivoFiscal | Código do incentivo fiscal aplicado | Não |
| IBSCBS_Codigo_Situacao | CST do IBS/CBS - Código de Situação Tributária (3 dígitos, ex: 101) | Não |
| IBSCBS_Codigo_Classificacao | Código de Classificação Tributária do IBS/CBS (6 dígitos, ex: RT0001) | Não |
| IBSCBS_Modo_Calculo | Modo de cálculo: Manual ou OfficialService | Não |
| IBSCBS_Base_Calculo | Base de cálculo do IBS/CBS em Reais. Se não informado, usa o valor do item. | Não |
| DataInicio | Data de início de vigência (DD/MM/AAAA) | Não |
| DataFim | Data de fim de vigência (DD/MM/AAAA) | Não |

### NotasFiscais - Principal
| Coluna | Descrição | Obrigatório |
|--------|-----------|-------------|
| Codigo | Código único da nota fiscal | Sim |
| Numero | Número sequencial da nota fiscal | Sim |
| Serie | Série da nota fiscal | Sim |
| DataEmissao | Data de emissão da nota fiscal (DD/MM/AAAA) | Sim |
| DataSaida | Data de saída/entrada da mercadoria (DD/MM/AAAA). Se vazio, usa a data de emissão | Não |
| CodigoDestinatario | Código do destinatário (referência à aba Destinatario) | Sim |
| CodigoTransportadora | Código da transportadora (referência à aba Transportadora) | Não |
| CodigoDeterminacaoFiscal | Código da determinação fiscal (referência à aba DeterminacaoFiscal) | Sim |
| InformacoesAdicionais | Informações complementares da nota fiscal | Não |
| InformacoesFisco | Informações de interesse do Fisco (mapeado para infAdFisco) | Não |
| ValorTotalNF | Valor total da nota fiscal em reais | Sim |

### ItensNF
| Coluna | Descrição | Obrigatório |
|--------|-----------|-------------|
| CodigoNF | Código da nota fiscal (referência à aba NotasFiscais) | Sim |
| CodigoProduto | Código do produto (referência à aba Produto) | Sim |
| Quantidade | Quantidade do item na nota fiscal | Sim |
| ValorUnitario | Valor unitário do item em reais | Sim |
| InformacoesAdicionais | Informações complementares do item | Não |
| ValorItens | Valor total do item (Quantidade × ValorUnitario) | Sim |

### Destinatario
| Coluna | Descrição | Obrigatório | Valores Aceitos |
|--------|-----------|-------------|-----------------|
| Codigo | Código único do destinatário | Sim | - |
| NomeRazaoSocial | Nome/Razão social do destinatário | Sim | - |
| CPFCNPJ | CPF ou CNPJ do destinatário | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos) |
| IndicadorIE | Indicador de inscrição estadual | Não | None, TaxPayer, Exempt, NonTaxPayer |
| IE | Número da inscrição estadual | Não | - |
| Endereco | Logradouro do endereço | Sim | - |
| Numero | Número do endereço | Sim | - |
| Bairro | Bairro do endereço | Sim | - |
| Municipio | Nome do município | Sim | - |
| CodigoMunicipio | Código IBGE do município | Sim | Código IBGE do município ([consulte aqui](https://www.ibge.gov.br/explica/codigos-dos-municipios.php)) |
| UF | Sigla da UF | Sim | Sigla da UF (ex: SP, RJ, MG) |
| CEP | CEP do endereço | Sim | Formato: 12345-678 (9 dígitos) |
| RegimeTributario | Regime tributário do destinatário | Sim | 1=Consumidor Final, 2=Normal |
| ContribuinteICMS | Indicador se é contribuinte do ICMS | Sim | S=Sim, N=Não |
| NomeContato | Nome da pessoa de contato | Não | - |
| Telefone | Telefone de contato | Não | - |
| Email | Email de contato | Não | - |

### Transportadora
| Coluna | Descrição | Obrigatório | Valores Aceitos |
|--------|-----------|-------------|-----------------|
| Codigo | Código único da transportadora | Sim | - |
| RazaoSocial | Razão social da transportadora | Sim | - |
| CNPJ | CNPJ da transportadora | Sim | CNPJ (14 dígitos) |
| IE | Número da inscrição estadual | Não | - |
| Endereco | Logradouro do endereço | Sim | - |
| Numero | Número do endereço | Sim | - |
| Bairro | Bairro do endereço | Sim | - |
| Municipio | Nome do município | Sim | - |
| CodigoMunicipio | Código IBGE do município | Sim | Código IBGE do município ([consulte aqui](https://www.ibge.gov.br/explica/codigos-dos-municipios.php)) |
| UF | Sigla da UF | Sim | Sigla da UF (ex: SP, RJ, MG) |
| CEP | CEP do endereço | Sim | Formato: 12345-678 (9 dígitos) |
| ModalidadeFrete | Modalidade do frete | Sim | Sistema usa "ByThirdParties" automaticamente |
| CodigoANTT | Código ANTT da transportadora | Não | - |
| PlacaVeiculo | Placa do veículo de transporte | Não | Formato: ABC1234 ou ABC1D23 |

## Tabelas de Referência - Valores Específicos

### TipoOperacao
| Valor | Descrição | Resultado no Sistema |
|--------|-----------|---------------------|
| 0 | Entrada | Incoming |
| 1 | Saída | Outgoing |

### Finalidade
| Valor | Descrição | Resultado no Sistema |
|--------|-----------|---------------------|
| 1 | Normal | Normal |
| 2 | Complementar | Complement |
| 3 | Ajuste | Adjustment |
| 4 | Devolução | Devolution |

### RegimeEmitente
| Valor | Descrição | Resultado no Sistema |
|--------|-----------|---------------------|
| 1 | Simples Nacional | SimplesNacional |
| 2 | Lucro Real | LucroReal |
| 3 | Lucro Presumido | LucroPresumido |
| 4 | Simples Nacional - Excesso Sublimite | SimplesNacionalExcessoSublimite |
| 5 | Microempreendedor Individual | MicroempreendedorIndividual |
| 6 | Isento | Isento |

### RegimeDestinatario (Tipo de Consumidor)
| Valor | Descrição | Resultado no Sistema |
|--------|-----------|---------------------|
| 1 | Consumidor Final | FinalConsumer |
| 2 | Normal | Normal |

### IndicadorIE (Indicador de Inscrição Estadual)
| Valor | Descrição | Resultado no Sistema |
|-------------------|-----------|---------------------|
| None | Sem inscrição estadual | None |
| TaxPayer | Contribuinte | TaxPayer |
| Exempt | Isento | Exempt |
| NonTaxPayer | Não contribuinte | NonTaxPayer |

### OrigemICMS (Origem da Mercadoria)
| Valor | Descrição |
|--------|-----------|
| 0 | Nacional, exceto as indicadas nos códigos 3, 4, 5 e 8 |
| 1 | Estrangeira - Importação direta, exceto a indicada no código 6 |
| 2 | Estrangeira - Adquirida no mercado interno, exceto a indicada no código 7 |
| 3 | Nacional, mercadoria ou bem com Conteúdo de Importação superior a 40% e inferior ou igual a 70% |
| 4 | Nacional, cuja produção tenha sido feita em conformidade com os processos produtivos básicos |
| 5 | Nacional, mercadoria ou bem com Conteúdo de Importação inferior ou igual a 40% |
| 6 | Estrangeira - Importação direta, sem similar nacional, constante em lista da CAMEX |
| 7 | Estrangeira - Adquirida no mercado interno, sem similar nacional, constante em lista da CAMEX |
| 8 | Nacional, mercadoria ou bem com Conteúdo de Importação superior a 70% |

### CST ICMS
| Valor | Descrição |
|--------|-----------|
| 00 | Tributada integralmente |
| 10 | Tributada e com cobrança do ICMS por substituição tributária |
| 20 | Com redução de base de cálculo |
| 30 | Isenta ou não tributada e com cobrança do ICMS por substituição tributária |
| 40 | Isenta |
| 41 | Não tributada |
| 50 | Suspensão |
| 51 | Diferimento |
| 60 | ICMS cobrado anteriormente por substituição tributária |
| 70 | Com redução de base de cálculo e cobrança do ICMS por substituição tributária |
| 90 | Outras |

### CST IPI
| Valor | Descrição |
|--------|-----------|
| 01 | Entrada tributável com alíquota zero |
| 02 | Entrada isenta |
| 03 | Entrada não-tributada |
| 04 | Entrada imune |
| 05 | Entrada com suspensão |
| 49 | Outras entradas |
| 50 | Saída tributável |
| 51 | Saída tributável com alíquota zero |
| 52 | Saída isenta |
| 53 | Saída não-tributada |
| 54 | Saída imune |
| 55 | Saída com suspensão |
| 99 | Outras saídas |

### CST PIS/COFINS
| Valor | Descrição |
|--------|-----------|
| 01 | Operação tributável com alíquota básica |
| 02 | Operação tributável com alíquota por unidade de medida de produto |
| 03 | Operação tributável com alíquota por unidade de medida de produto |
| 04 | Operação tributável monofásica - revenda a alíquota zero |
| 05 | Operação tributável por substituição tributária |
| 06 | Operação tributável a alíquota zero |
| 07 | Operação isenta da contribuição |
| 08 | Operação sem incidência da contribuição |
| 09 | Operação com suspensão da contribuição |
| 99 | Outras operações |

### CST IBS/CBS (Reforma Tributária)
| Valor | Descrição |
|--------|-----------|
| 101 | Tributação regular |
| 102 | Tributação com redução de alíquota |
| 103 | Diferimento |
| 200 | Imunidade |
| 201 | Isenção |
| 300 | Não incidência |
| 400 | Suspensão |


## Observações Importantes

1. **Relacionamentos**: As abas estão relacionadas através dos códigos:
   - ItensNF.CodigoNF → NotasFiscais.Codigo
   - ItensNF.CodigoProduto → Produto.Codigo
   - Produto.CodigoGrupoProdutos → GrupoProdutos.Codigo
   - NotasFiscais.CodigoDeterminacaoFiscal → DeterminacaoFiscal.Codigo
   - NotasFiscais.CodigoDestinatario → Destinatario.Codigo
   - NotasFiscais.CodigoTransportadora → Transportadora.Codigo (opcional)

2. **Formato de Dados**:
   - **Datas**: DD/MM/AAAA
   - **Valores monetários**: Use ponto como separador decimal (ex: 1000.50)
   - **Percentuais**: Use valores decimais (ex: 18 para 18%)
   - **Quantidades**: Use números inteiros ou decimais (ex: 10 ou 10.5)
   - **CPF/CNPJ**: Apenas números (ex: 12345678901 para CPF, 12345678000195 para CNPJ)
   - **CEP**: 00000-000
   - **Campos de texto**: Todos os outros campos são tratados como texto

3. **Campos Calculados Automaticamente**:
   - Valor total dos itens (Quantidade × Valor Unitário)
   - Valores de impostos baseados nas alíquotas informadas
   - Origem da mercadoria baseada no código informado
   - Tipo de operação baseado no código da determinação fiscal

---

## Template Planilha Simplificada

Source: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/template-de-planilha-simplificada-para-processamento-de-notas-fiscais/index.md

# Planilha Simplificada para Processamento de Notas Fiscais em Lote

> ⚠️ **Documento em fase de homologação** 

Esta planilha simplificada foi desenvolvida para facilitar a emissão de Notas Fiscais Eletrônicas de Produtos (NF-e) na plataforma NFE.io.

## Formato Ultra-Simplificado (Recomendado)

O formato mais simples consiste em uma única aba chamada **"Simplificada"** contendo todos os dados necessários para emissão das notas fiscais.

### Aba: Simplificada

Cada linha representa um **item de produto**. Itens com o mesmo CPF/CNPJ serão agrupados automaticamente em uma única nota fiscal.

| Coluna | Descrição | Obrigatório | Exemplo |
|--------|-----------|-------------|---------|
| **CPF_CNPJ** | CPF ou CNPJ do destinatário | Sim | 12345678901 ou 12345678000190 |
| **Nome** | Nome/Razão social do destinatário | Sim | João da Silva ou Empresa LTDA |
| **Email** | Email do destinatário | Não | contato@empresa.com.br |
| **Pagamento_Valor** | Valor total do pagamento | Não | 1000.00 |
| **Pagamento_Tipo** | Tipo de pagamento (código) | Não | 01 (Dinheiro), 03 (Cartão de Crédito), 15 (PIX) |
| **Endereco_Pais** | País do destinatário | Não | Brasil (padrão) |
| **Endereco_CEP** | CEP do endereço | Sim | 12345-678 |
| **Endereco_Logradouro** | Logradouro (rua, avenida, etc) | Sim | Rua das Flores |
| **Endereco_Numero** | Número do endereço | Sim | 123 |
| **Endereco_Complemento** | Complemento | Não | Apto 45 |
| **Endereco_Bairro** | Bairro | Sim | Centro |
| **Endereco_Cidade_Codigo** | Código IBGE do município | Sim | 3550308 (São Paulo) |
| **Endereco_Cidade_Nome** | Nome do município | Sim | São Paulo |
| **Endereco_Estado** | Sigla da UF | Sim | SP |
| **InformacoesComplementares** | Informações adicionais da nota | Não | Observações gerais |
| **Produto_Codigo** | Código do produto | Não | PROD001 (gerado automaticamente se vazio) |
| **Produto_Descricao** | Descrição do produto | Sim | Notebook Dell Inspiron |
| **Produto_InformacaoAdicional** | Informação adicional do item | Não | Garantia de 12 meses |
| **Produto_Unidade** | Unidade de medida | Não | UN (padrão) |
| **Produto_Quantidade** | Quantidade | Sim | 2 |
| **Produto_ValorUnitario** | Valor unitário | Sim | 2500.00 |
| **Produto_ValorDesconto** | Valor de desconto | Não | 100.00 |
| **Produto_GTIN** | Código GTIN/EAN | Não | 7891234567890 |
| **Produto_NCM** | Código NCM | Sim | 8471.30.12 |
| **Produto_CFOP** | Código CFOP | Sim | 5102 |
| **Tipo_Operacao** | Tipo de operação | Não | Saida (padrão) ou Entrada |
| **Produto_Imposto_ICMS_CST** | CST do ICMS | Sim | 00, 10, 20, etc |
| **Produto_Imposto_ICMS_Origem** | Origem da mercadoria | Sim | 0 (Nacional) |
| **Produto_Imposto_PIS_CST** | CST do PIS | Não | 01, 02, etc |
| **Produto_Imposto_COFINS_CST** | CST do COFINS | Não | 01, 02, etc |
| **Produto_Imposto_IPI_CST** | CST do IPI | Não | 00, 49, etc |
| **Produto_IPI_CENQ** | Código CENQ do IPI | Não | 999 |

### Exemplo de Planilha Simplificada

```
CPF_CNPJ        | Nome           | Email              | Produto_Descricao | Produto_Quantidade | Produto_ValorUnitario | Produto_NCM | Produto_CFOP | ...
12345678901     | João Silva     | joao@email.com     | Notebook          | 1                  | 2500.00              | 8471.30.12  | 5102         | ...
12345678901     | João Silva     | joao@email.com     | Mouse             | 2                  | 50.00                | 8471.60.52  | 5102         | ...
98765432000100  | Empresa XYZ    | contato@xyz.com    | Teclado           | 5                  | 150.00               | 8471.60.52  | 5102         | ...
```

Neste exemplo:
- **João Silva** receberá 1 nota fiscal com 2 itens (Notebook e Mouse)
- **Empresa XYZ** receberá 1 nota fiscal com 1 item (Teclado)

### Códigos de Tipo de Pagamento

| Código | Descrição |
|--------|-----------|
| 01 | Dinheiro |
| 02 | Cheque |
| 03 | Cartão de Crédito |
| 04 | Cartão de Débito |
| 05 | Crédito Loja |
| 10 | Vale Alimentação |
| 11 | Vale Refeição |
| 12 | Vale Presente |
| 13 | Vale Combustível |
| 14 | Duplicata Mercantil |
| 15 | Boleto Bancário |
| 16 | Depósito Bancário |
| 17 | PIX |
| 18 | Transferência Bancária |
| 19 | Cashback |
| 90 | Sem Pagamento |
| 99 | Outros |

---

## Formato Legado (Com Múltiplas Abas)

Para compatibilidade com versões anteriores, ainda é possível utilizar o formato com múltiplas abas.

### Abas do Arquivo XLSX

O arquivo deve conter as seguintes abas (sheets):

### Destinatario

| Coluna | Descrição | Obrigatório | Valores Aceitos |
|--------|-----------|-------------|-----------------|
| Codigo | Código único do destinatário | Sim | - |
| NomeRazaoSocial | Nome/Razão social do destinatário | Sim | - |
| CPFCNPJ | CPF ou CNPJ do destinatário | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos) |
| IndicadorIE | Indicador de inscrição estadual | Não | None, TaxPayer, Exempt, NonTaxPayer |
| IE | Número da inscrição estadual | Não | - |
| Endereco | Logradouro do endereço | Sim | - |
| Numero | Número do endereço | Sim | - |
| Bairro | Bairro do endereço | Sim | - |
| Municipio | Nome do município | Sim | - |
| CodigoMunicipio | Código IBGE do município | Sim | Código IBGE do município ([consulte aqui](https://www.ibge.gov.br/explica/codigos-dos-municipios.php)) |
| UF | Sigla da UF | Sim | Sigla da UF (ex: SP, RJ, MG) |
| CEP | CEP do endereço | Sim | Formato: 12345-678 (9 dígitos) |
| RegimeTributario | Regime tributário do destinatário | Sim | 1=Consumidor Final, 2=Normal |
| ContribuinteICMS | Indicador se é contribuinte do ICMS | Sim | S=Sim, N=Não |
| NomeContato | Nome da pessoa de contato | Não | - |
| Telefone | Telefone de contato | Não | - |
| Email | Email de contato | Não | - |

### Transportadora

| Coluna | Descrição | Obrigatório | Valores Aceitos |
|--------|-----------|-------------|-----------------|
| Codigo | Código único da transportadora | Sim | - |
| RazaoSocial | Razão social da transportadora | Sim | - |
| CNPJ | CNPJ da transportadora | Sim | CNPJ (14 dígitos) |
| IE | Número da inscrição estadual | Não | - |
| Endereco | Logradouro do endereço | Sim | - |
| Numero | Número do endereço | Sim | - |
| Bairro | Bairro do endereço | Sim | - |
| Municipio | Nome do município | Sim | - |
| CodigoMunicipio | Código IBGE do município | Sim | Código IBGE do município ([consulte aqui](https://www.ibge.gov.br/explica/codigos-dos-municipios.php)) |
| UF | Sigla da UF | Sim | Sigla da UF (ex: SP, RJ, MG) |
| CEP | CEP do endereço | Sim | Formato: 12345-678 (9 dígitos) |
| ModalidadeFrete | Modalidade do frete | Sim | Sistema usa "ByThirdParties" automaticamente |
| CodigoANTT | Código ANTT da transportadora | Não | - |
| PlacaVeiculo | Placa do veículo de transporte | Não | Formato: ABC1234 ou ABC1D23 |

### NotasFiscais (com Itens Inline)

**IMPORTANTE:** Na planilha simplificada, **cada linha representa UMA nota fiscal completa com UM item**. 

Se você deseja criar uma nota fiscal com múltiplos itens, você precisará usar a planilha completa (com agrupamento por CodigoNF) ou criar múltiplas notas fiscais de item único.

**Estrutura:** 1 linha = 1 nota fiscal + 1 item

#### Colunas da Aba NotasFiscais

| Coluna | Descrição | Obrigatório | Valores Aceitos |
|--------|-----------|-------------|-----------------|
| Codigo | Código único da nota fiscal | Sim | Identificador único para esta nota |
| Numero | Número da nota fiscal | Não | Deixe em branco (será configurado na plataforma) |
| Serie | Série da nota fiscal | Não | Deixe em branco (será configurado na plataforma) |
| DataEmissao | Data de emissão da nota fiscal | Sim | DD/MM/AAAA |
| CodigoDestinatario | Código do destinatário (referência à aba Destinatario) | Sim | - |
| CodigoTransportadora | Código da transportadora (referência à aba Transportadora) | Não | - |
| PerfilEmitente | Perfil fiscal do emitente para cálculo automático | Não | Ver tabela de perfis fiscais abaixo |
| PerfilComprador | Perfil fiscal do comprador para cálculo automático | Sim | Ver tabela de perfis fiscais abaixo |
| CodigoOperacao | Código interno para determinação de CFOP | Sim | Código numérico (flexível conforme necessidade) |
| Origem | Origem da mercadoria | Sim | 0-8 (ver tabela OrigemICMS) |
| InformacoesAdicionais | Informações complementares da nota fiscal | Não | - |
| NCM | Código NCM (Nomenclatura Comum do Mercosul) | Sim | 8 dígitos |
| GTIN | Código GTIN/EAN do produto | Não | - |
| CEST | Código CEST | Não | 7 dígitos |
| SituacaoTributaria | CST/CSOSN do ICMS | Sim | Ex: "00", "101", etc |
| CodigoProduto | Código do produto | Sim | - |
| DescricaoProduto | Descrição do produto | Não | Se vazio, usa CodigoProduto |
| Quantidade | Quantidade do item | Sim | Número com até 4 casas decimais |
| ValorUnitario | Valor unitário do item | Sim | Valor em reais |
| InformacoesAdicionaisItem | Informações adicionais do item | Não | - |

#### Dados da Reforma Tributária (IBS/CBS)

| Coluna | Descrição | Obrigatório | Valores Aceitos |
|--------|-----------|-------------|-----------------|
| Reforma_CodigoSituacaoTributariaIBSCBS | Código de Situação Tributária do IBS/CBS | Não | 3 dígitos. Ex: "101" |
| Reforma_ClassificacaoTributariaIBSCBS | Código de Classificação Tributária do IBS/CBS | Não | 6 dígitos. Ex: "RT0001" |
| Reforma_BaseCalculoEspecificoIBSCBS | Base de Cálculo Específica do IBS/CBS antes de reduções para cálculo do tributo bruto | Não | Valor numérico (ex: 1500.00) |

**Observação:** Os campos da Reforma Tributária são opcionais. Quando informados, recomenda-se preencher ao menos `Reforma_CodigoSituacaoTributariaIBSCBS` e `Reforma_ClassificacaoTributariaIBSCBS`. O campo `Reforma_BaseCalculoEspecificoIBSCBS` é opcional e, se enviado, será considerado pela API; caso contrário, a API calculará automaticamente. Estes campos são enviados independentemente do uso do motor de cálculo automático (taxDetermination).

**Nota sobre campos removidos:**
- `NaturezaOperacao`: Não está na planilha atual (valor padrão: "Venda de mercadoria")
- `ValorTotalNF`: Não está na planilha atual (calculado automaticamente a partir dos itens)
- `UnidadeMedida`: Não está na planilha atual (valor padrão: "UN")

## Tabelas de Referência

### Perfis Fiscais

#### PerfilEmitente (Perfil do Emitente)

Valores possíveis para o campo `PerfilEmitente`:

| Valor | Descrição |
|-------|-----------|
| simples_nacional | Simples Nacional ou MEI |
| lucro_real | Lucro Real |
| lucro_presumido | Lucro Presumido |
| retail | Varejo |
| industry | Indústria |
| wholesaler | Atacadista |
| rural_producer | Produtor rural |

**Observação:** Se não informado, o sistema determina automaticamente baseado no regime tributário da empresa cadastrada.

#### PerfilComprador (Perfil do Comprador)

Valores possíveis para o campo `PerfilComprador`:

| Valor | Descrição |
|-------|-----------|
| final_consumer_non_icms_contributor | Consumidor final não contribuinte do ICMS |
| final_consumer_icms_contributor | Consumidor final contribuinte do ICMS |
| industry | Indústria |
| retail | Varejo |
| wholesaler | Atacadista |
| rural_producer | Produtor rural |

### OrigemICMS (Origem da Mercadoria)

| Valor | Descrição |
|--------|-----------|
| 0 | Nacional, exceto as indicadas nos códigos 3, 4, 5 e 8 |
| 1 | Estrangeira - Importação direta, exceto a indicada no código 6 |
| 2 | Estrangeira - Adquirida no mercado interno, exceto a indicada no código 7 |
| 3 | Nacional, mercadoria ou bem com Conteúdo de Importação superior a 40% e inferior ou igual a 70% |
| 4 | Nacional, cuja produção tenha sido feita em conformidade com os processos produtivos básicos |
| 5 | Nacional, mercadoria ou bem com Conteúdo de Importação inferior ou igual a 40% |
| 6 | Estrangeira - Importação direta, sem similar nacional, constante em lista da CAMEX |
| 7 | Estrangeira - Adquirida no mercado interno, sem similar nacional, constante em lista da CAMEX |
| 8 | Nacional, mercadoria ou bem com Conteúdo de Importação superior a 70% |

## Observações Importantes

1. **Relacionamentos**: 
   - NotasFiscais.CodigoDestinatario → Destinatario.Codigo
   - NotasFiscais.CodigoTransportadora → Transportadora.Codigo (opcional)

2. **Múltiplos Itens por Nota**: 
   - Para adicionar múltiplos itens a uma mesma nota, repita as linhas com o mesmo `Codigo`, alterando apenas os dados do item
   - Os dados da nota (DataEmissao, CodigoDestinatario, etc.) devem ser iguais em todas as linhas da mesma nota

3. **Motor de Cálculo Automático**:
   - Os impostos são calculados automaticamente pela plataforma NFE.io
   - É necessário informar: `CodigoOperacao`, `Origem`, `SituacaoTributaria`, `PerfilComprador`
   - Opcionalmente pode informar: `PerfilEmitente` (se não informado, será determinado pelo regime tributário da empresa)
   - Campos `Numero` e `Serie` são opcionais (configurados diretamente na plataforma)

4. **Reforma Tributária**:
   - Os campos `Reforma_CodigoSituacaoTributariaCBSIBS` e `Reforma_ClassificacaoTributariaCBSIBS` são **opcionais**
   - Quando informados, **ambos os campos** devem ser preenchidos
   - Estes campos são enviados para a API independentemente do uso do motor de cálculo automático (taxDetermination)
   - Consulte as tabelas oficiais da Receita Federal para os códigos corretos

5. **Formato de Dados**:
   - **Datas**: DD/MM/AAAA
   - **Valores monetários**: Use ponto como separador decimal (ex: 1000.50)
   - **Quantidades**: Use números inteiros ou decimais (ex: 10 ou 10.5)
   - **CPF/CNPJ**: Apenas números
   - **CEP**: 00000-000

**Importante**: Os dados da nota (Codigo, DataEmissao, CodigoDestinatario, etc.) são repetidos em ambas as linhas.

---

## Conceitos sobre Nota Fiscal de Serviço Eletronica (NFs-e) - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/conceitos/index.md

# Tudo sobre Nota Fiscal de Serviço (NFS-e)

A [Nota Fiscal de Serviços][11] Eletrônica (NFS-e) é um documento inteiramente eletrônico e de responsabilidade municipal. Sendo assim, cabe às prefeituras fazer a implantação e a fiscalização das emissões realizadas em sua área de coordenação.

O objetivo desse documento é justamente facilitar a comunicação entre os prestadores de serviço e a prefeitura, para que seja possível ter um controle maior sobre as suas responsabilidades fiscais.

A NFS-e é um projeto que faz parte do[ Sistema Público de Escrituração Digital (Sped)][12] e que está sendo implantado nos municípios de forma integrada entre a Associação Brasileira das Secretarias de Finanças das Capitais (Abrasf) e a Receita Federal do Brasil (RFB).

E antes de entrarmos em mais detalhes sobre a emissão desse tipo de nota, vamos abordar alguns conceitos relevantes para empresas que tenham que emití-la.

## O que é CNAE?

O **CNAE** (Classificação Nacional de Atividades Econômicas) é uma numeração dada pelo governo para definir as atividades econômicas de uma empresa ativa. Uma empresa pode ter vários CNAEs cadastrados, porém, deverá ter um CNAE principal, que define a atividade principal da empresa, tornando os outros, atividades secundárias.

Através do CNAE é possível saber algumas coisas como:

* Enquadramento tributário da empresa, e com isso entender se é possível saber se ela pode optar pelo Simples Nacional.
* Definir qual o sindicato da empresa.

## O que é Código de Serviço?

O Código de Serviço é um número que define o tipo de serviço prestado pela sua empresa ao seu cliente. A alíquota de imposto municipal é definida com base no código do serviço que a empresa fornece.

A diferença para o CNAE, é que o CNAE diz em relação ao enquadramento de uma empresa, enquanto o código de serviço diz em relação a um serviço prestado por uma empresa e servirá para determinar que alíquota de imposto será virá de base de cálculo para o recolhimento do imposto municipal para esse serviço.

## O que é Inscrição Municipal?

A **Inscrição Municipal (IM)** é o número de registro do contribuinte no Cadastro Tributário Municipal e possui vínculo com o **ISS (Imposto Sobre Serviço)**. Este cadastro é obrigatório para empresas prestadoras de serviços.

Você precisará do número de registro da Inscrição Municipal para:

* Emitir notas fiscais de prestação de serviços (NFS-e);
* Ser enquadrado no Simples Nacional em até 30 dias após registro da IM;
* Solicitar alvará de funcionamento, vistorias, etc.

A diferença para a inscrição estadual é que a inscrição municipal está vinculada a prefeitura e é destinada às empresas que prestam serviços.

Caso você não saiba como realizar o credenciamento na prefeitura de sua cidade, [clique aqui][13].

> Observação: Você deverá possuir ao menos um código de serviço atrelado à sua Inscrição Municipal.

## Quem precisa emitir NFS-e?

A emissão de NFS-e é obrigatória para todas as empresas que prestam serviços aos contribuintes e que estão em municípios homologados nesse sistema. No entanto, a emissão automática, instantânea e online da NFS-e não é obrigatória na maioria das cidades.

A emissão online da NFS-e pode ser feita pelos empreendimentos que já tenham conectividade com o serviço de emissão, mas, para os que não tiverem, basta que a empresa faça a emissão de um RPS:

> **RPS:** Quando uma empresa presta um determinado serviço, nos municípios cadastrados para emissão de NFS-e, ela precisa fazer o Recibo Provisório de Serviços (RPS), que fica de posse do contribuinte. Esse documento é emitido manualmente ou por sistema próprio e deve conter um código numérico.  
> **Conversão do RPS:**o RPS é de total responsabilidade do contribuinte, que deve consultar o prazo de conversão do município e apresentar no local municipal de conversão o documento. Assim, ele será convertido na NFS-e propriamente dita.

## Quando é preciso emitir Nota Fiscal de Serviço (NFS-e)?

Nos municípios homologados, é preciso emitir a NFS-e ou o RPS todas as vezes que uma empresa prestar seus serviços para um contribuinte. Isso acontece para que as prefeituras estejam a par de todas as trocas comerciais advindas de prestação de serviços que acontecem na cidade.

## Quais são os impostos retidos na emissão de Nota Fiscal de Serviço (NFS-e)?

Ao emitir uma nota fiscal de serviço, alguns impostos deverão ser calculados e retidos no momento da emissão.

Os impostos são:

* **ISS;**
* **INSS;**
* **IRRF;**
* **COFINS;**
* **CSLL;**
* **ICMS;**
* **PIS/PASEP**

## Como emitir Nota Fiscal de Serviço (NFs-e)?

Para fazer a emissão da NFS-e, existem alguns passos que devem ser seguidos, que deixamos bem resumidos abaixo:

**Credenciamento:** através do site da prefeitura da sua cidade você deve efetuar um cadastro e seguir os passos que a prefeitura indicar para, então, ter acesso ao sistema de emissão de notas.

**Acesso ao sistema:** Uma vez com o acesso ao sistema, você fará o seu cadastro no mesmo, registrando dados como inscrição municipal, CNPJ, razão social, regime de tributação da empresa e atividades

**Emissão de notas:** agora você pode começar a emitir notas pelo sistema da prefeitura, indicando o tomador de serviços, a atividade exercida, dedução (se houver) e o detalhamento, como na nota convencional, com horas de trabalho,valores, entre outros.  
Também existe a opção de contar com a NFE.io e não ter que se preocupar em fazer esse processo, que pode ser demorado, trabalhoso e sujeito a muitos erros manuais.

A NFe.io oferece diversas facilidades para quem precisa emitir notas fiscais em sua empresa, como a conta Multi Empresas, um quadro de controle com dados e estatísticas para acompanhar o os resultados do seu negócio, além de um cupom de desconto para comprar [certificado digital e-CNPJ-A1.][14]

Caso você tenha dúvidas sobre o que é um certificado digital, você pode acessar este link.

Com os nossos serviços, a emissão pode ser feita:

* via excel pela nossa plataforma.
* [via Google Sheets usando o Microsoft Flow.][15]
* [utilizando nossos plugins em outros sistemas.][16]
* [através das principais plataformas de pagamento][16].
* [via desenvolvimento para integração com nossas APIs.][17]

## Como cancelar uma Nota Fiscal de Serviço (NFs-e)?

É permitido o cancelamento de Nota Fiscal de Serviços pelo emitente por meio do sistema de consulta de NFS-e emitidas. No entanto se faz necessário observar algumas condições.

Caso o ISS não tenha sido recolhido, o prestador poderá cancelar a NFS-e, desde que não tenha ultrapassado o prazo de seis meses contados da data de emissão da nota. Entretanto, se a NFS-e estiver incluída em uma guia de recolhimento, o link para cancelamento não será exibido, sendo necessário o cancelamento da guia para que seja possível o cancelamento da NFS-e. Caso o recolhimento do ISS seja de responsabilidade do tomador dos serviços (ISS retido), o cancelamento da guia deverá ser realizado pelo tomador.

Caso o ISS já tenha sido recolhido, a NFS-e somente poderá ser cancelada por meio de processo administrativo. No entanto, as notas fiscais com ISS recolhido poderão ser substituídas, desde que obedecido o prazo limite.

> Observação: Cada prefeitura tem sua legislação e regulamento, portanto, não deixe de pesquisar a legislação do seu município sobre o cancelamento de nota fiscal de serviços.

Para cancelar suas notas fiscais de forma simples e rápida, utilize nossos serviços. Através da nossa plataforma, o cancelamento pode ser feito com apenas um clique. Caso necessite realiazar o cancelamento em lote, utilize o [fluxo do Microsoft Flow.][18]

### Veja também:

* [Nossos segmentos][19]
* [Sobre a NFE.io][20]
* [Junte-se ao nosso time][21]

[1]: #Tudo%5Fsobre%5FNota%5FFiscal%5Fde%5FServico%5FNFS-e
[2]: #O%5Fque%5Fe%5FCNAE
[3]: #O%5Fque%5Fe%5FCodigo%5Fde%5FServico
[4]: #O%5Fque%5Fe%5FInscricao%5FMunicipal
[5]: #Quem%5Fprecisa%5Femitir%5FNFS-e
[6]: #Quando%5Fe%5Fpreciso%5Femitir%5FNota%5FFiscal%5Fde%5FServico%5FNFS-e
[7]: #Quais%5Fsao%5Fos%5Fimpostos%5Fretidos%5Fna%5Femissao%5Fde%5FNota%5FFiscal%5Fde%5FServico%5FNFS-e
[8]: #Como%5Femitir%5FNota%5FFiscal%5Fde%5FServico%5FNFs-e
[9]: #Como%5Fcancelar%5Fuma%5FNota%5FFiscal%5Fde%5FServico%5FNFs-e
[10]: #Veja%5Ftambem
[11]: https://nfe.io/blog/nota-fiscal/o-que-e-nota-fiscal-servico/
[12]: https://nfe.io/blog/nota-fiscal/sped-nota-fiscal-eletronica/
[13]: /documentacao/nota-fiscal-servico-eletronica/credenciamento-na-prefeitura
[14]: https://p.nfe.io/certificado-digital-20off/
[15]: /integracoes/plugins/microsoft-flow
[16]: /integracoes
[17]: /documentacao/nota-fiscal-servico-eletronica/integracao-api/primeiros-passos
[18]: /integracoes/plugins/microsoft-flow#cancelando-uma-nfe
[19]: https://nfe.io/segmentos/
[20]: https://nfe.io/sobre/
[21]: https://nfe.io/carreira/

---

## Como fazer o Credenciamento na Prefeitura - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/documentacao-nota-fiscal-servico-eletronica-credenciamento-prefeitura/index.md

## Credenciamento na Prefeitura

Nesta seção, você encontrará informações sobre o credenciamento da sua empresa junto à prefeitura para emitir notas fiscais de serviço. Algumas prefeituras possuem sistemas que permitem você verificar se sua empresa está cadastrada para emissão de notas. [Clique aqui][4] e veja quais prefeituras disponibilizam essa consulta.

### Como fazer o Credenciamento na Prefeitura?

> Todos os procedimentos citados abaixo servem como um guia, trazendo as informações mais importantes, mas certos detalhes podem variar de acordo com a prefeitura. Consulte seu contador antes de realizar os procedimentos.

Para realizar o credenciamento, você precisará comparecer ao órgão responsável de seu município, com os documentos necessários para a solicitação da Inscrição Municipal, bem como:

* Cartão do CNPJ;
* Contrato Social;
* Cartão de CPF (caso sua empresa tenha sócios, será necessário estar munido dos documentos de cada sócio);
* RG (caso sua empresa tenha sócios, será necessário estar munido dos documentos de cada um deles);
* Comprovante de residência (caso sua empresa tenha sócios, será necessário estar munido dos documentos de cada sócio);
* Inscrição Estadual (caso haja necessidade);
* Planta do Imóvel;
* Alvará Sanitário e Laudo do Corpo de bombeiros da sua cidade (caso haja necessidade);

> **Observação:** Você poderá preencher um requerimento pelo site do órgão responsável de seu município, caso o mesmo disponibilize esse serviço online. Aconselhamos consultar seu contador para realizar o processo de credenciamento.  
> **Nota:** Em alguns municípios, o credenciamento para obter a Inscrição Municipal e para emissão de notas é o mesmo. Em alguns casos, será necessário realizar dois credenciamentos.

### Veja também esses materiais adicionais 

Caso você continue com dúvidas, recomendamos a leitura dos tópicos abaixo, aqui em nossa documentação e;

[Conceitos sobre nota fiscal de serviço][5]  
[Primeiros passos para integrar a nota fiscal de serviço][6]  
[Dúvidas frequentes][7]

Esse artigo no blog está relacionado a esse assunto, pode ser que você goste!

[Como implementar nota fiscal eletronica em sua empresa][8]


[1]: #Credenciamento%5Fna%5FPrefeitura
[2]: #Como%5Ffazer%5Fo%5FCredenciamento%5Fna%5FPrefeitura
[3]: #Veja%5Ftambem%5Fesses%5Fmateriais%5Fadicionais
[4]: /prefeituras-integradas
[5]: /documentacao/nota-fiscal-servico-eletronica/conceitos
[6]: /documentacao/nota-fiscal-servico-eletronica/primeiros-passos
[7]: /documentacao/nota-fiscal-servico-eletronica/duvidas
[8]: https://nfe.io/blog/nota-fiscal/como-implantar-nota-fiscal-eletronica-empresa/

---

## Campos de autorização NFSe - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/campos-de-autorizacao-nfse/index.md

# Campos de Autenticação para Empresas que Emitem Nota Fiscal de Serviço

Para algumas prefeituras, pode ser necessário informar campos extras de autenticação para que a emissão seja possível. Abaixo segue uma descrição desses campos e como eles devem ser preenchidos.

**Requisitos**

* Ter uma empresa cadastrada (acesse [Cadastrar uma empresa][4])
* Prefeituras que exijam algum tipo de informação além do certificado para autenticação no webservice de emissão de nota (acesse [lista de prefeituras][5] para averiguar se sua prefeitura não é atendida por certificado digital)

## Tipos de Autenticação para Emissão de Nota Fiscal

Normalmente, quando uma empresa emite uma nota fiscal, a autenticação é feita por meio de um certificado digital válido. Para atender esse cenário, por padrão, é definida na NFE.io essa opção de autenticação, descrita em [Upload do Certificado Digital][6].

Contudo, algumas prefeituras exigem informações adicionais além do certificado digital para a emissão de notas via Webservice. Isso pode incluir:

* Uma senha
* Uma combinação de usuário e senha
* Uma chave de autorização

Para atender cenários onde esse tipo de autenticação é necessária, a NFE.io disponibiliza alguns campos para que a emissão consiga ser feita. Eles são as seguintes opções:

* "Usuário de acesso ao Webservice"
* "Senha de acesso ao Webservice"
* "Identificação de autorização fiscal"

Pela definição do nome, a descrição desses campos é autoexplicativa na forma como devem ser preenchidos. Contudo, para algumas particularidades de prefeituras, esses campos podem possuir outros significados.

Por fim, como ressaltado nos Requisitos no início do documento, essa opção só estará disponível para preenchimento quando a sua prefeitura requer esse tipo de dado. Caso a autenticação seja feita por meio de certificado, não é preciso se preocupar com esse tipo de informação.

No [link][5] já disponibilizado, é possível visualizar todas as prefeituras que estão integradas com a NFE.io e os tipos de autenticação necessários para cada prefeitura. Para aquelas em que esse tipo de informação é necessária, verifique todas aquelas prefeituras cuja coluna **_Column1.webService.authenticationMethod_** está preenchida com a informação **_UserAndPassword_**.

## Como Preencher os Campos de Autenticação

Nos casos em que a prefeitura exija os campos extras de autenticação, na plataforma da NFE.io essas opções estarão disponíveis para preenchimento na opção de **_Dados Fiscais_**, como mostrado abaixo:

![Campos de autenticação](https://nfepub.blob.core.windows.net/kita/msedge_qq1NC0uv4D.png "Campos de autenticação")

Essas opções estarão disponíveis após serem preenchidas as opções descritas como **_Dados básicos da empresa_** no cadastro de uma nova empresa para emissão.

No caso do uso da API, abaixo segue o trecho de JSON de como esses campos estão disponíveis:

```json
{ 
  "fiscalStatus": "Active",
  "loginName": "string", // Usuário de acesso ao Webservice
  "loginPassword": "string", // Senha de acesso ao Webservice
  "authIssueValue": "string", // Identificação de autorização fiscal
  "certificate": { ... }
}```

No json comples eles estão disponíveis da seguinte forma:

```json
{
  "companies": {
    "id": "string",
    "name": "string",
    "tradeName": "string",
    "federalTaxNumber": 0,
    "email": "string",
    "address": {
      "country": "string",
      "postalCode": "string",
      "street": "string",
      "number": "string",
      "additionalInformation": "string",
      "district": "string",
      "city": {
        "code": "string",
        "name": "string"
      },
      "state": "string"
    },
    "openningDate": "2024-10-28T16:31:41.583Z",
    "taxRegime": "Isento",
    "specialTaxRegime": "Automatico",
    "legalNature": "EmpresaPublica",
    "economicActivities": [
      {
        "type": "Main",
        "code": 0
      }
    ],
    "companyRegistryNumber": 0,
    "regionalTaxNumber": 0,
    "municipalTaxNumber": "string",
    "rpsSerialNumber": "string",
    "rpsNumber": 0,
    "issRate": 0,
    "environment": "Development",
    "fiscalStatus": "CityNotSupported",
    "federalTaxDetermination": "NotInformed",
    "municipalTaxDetermination": "NotInformed",
    "loginName": "string",
    "loginPassword": "string",
    "authIssueValue": "string",
    "certificate": {
      "thumbprint": "string",
      "modifiedOn": "2024-10-28T16:31:41.583Z",
      "expiresOn": "2024-10-28T16:31:41.583Z",
      "status": "Overdue"
    },
    "createdOn": "2024-10-28T16:31:41.583Z",
    "modifiedOn": "2024-10-28T16:31:41.583Z"
  }
}
```

Caso tenha alguma dúvida, entre em contato consco em suporte@nfe.io.


[1]: #Campos%5Fde%5FAutenticacao%5Fpara%5FEmpresas%5Fque%5FEmitem%5FNota%5FFiscal%5Fde%5FServico
[2]: #Tipos%5Fde%5FAutenticacao%5Fpara%5FEmissao%5Fde%5FNota%5FFiscal
[3]: #Como%5FPreencher%5Fos%5FCampos%5Fde%5FAutenticacao
[4]: https://nfe.io/docs/documentacao/nossa-plataforma/criar-empresa/
[5]: https://nfeio-my.sharepoint.com/:x:/g/personal/gabriel%5Fnfe%5Fio/EfHrnj4ygVRKhPdsY1n%5FlGcBe0-dfbTe8pwq0ctp7G4BhQ?rtime=AZHuIK3z3Eg&isSPOFile=1&clickparams=eyJBcHBOYW1lIjoiVGVhbXMtRGVza3RvcCIsIkFwcFZlcnNpb24iOiI0OS8yNDA5MTIyMTMxOCIsIkhhc0ZlZGVyYXRlZFVzZXIiOmZhbHNlfQ%3D%3D
[6]: https://nfe.io/docs/documentacao/nossa-plataforma/upload-do-certificado-digital/

---

## Emissão de NFS-e com Cálculo Automático de Impostos - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/calculo-automatico-impostos/index.md

# Emissão de NFS-e com Cálculo Automático de Impostos

Nesta seção, iremos explicar como emitir uma **Nota Fiscal de Serviço Eletrônica (NFS-e)** utilizando o **cálculo automático de impostos** da plataforma NFE.io. Caso não encontre uma resposta para sua dúvida, fique à vontade para [entrar em contato](https://nfe.io/#contato) e enviar sua pergunta.

## O que é o Cálculo Automático de Impostos?

O **cálculo automático de impostos** é uma funcionalidade da plataforma NFE.io que realiza o cálculo dos tributos automaticamente com base no **código de serviço** informado. Isso significa que você não precisa preencher os campos de impostos manualmente — como valor da alíquota de ISS, por exemplo — pois a plataforma identifica os detalhes tributários e calcula os valores a serem enviados para a prefeitura.

Além disso, é possível **customizar o cálculo de impostos** para uma empresa específica utilizando o **CNPJ da empresa emissora**. Dessa forma, o cálculo automático pode ser ajustado de acordo com as particularidades tributárias de cada empresa.

### Quando utilizar este cenário?

- **Simplicidade na integração**: Quando você deseja emitir notas fiscais sem se preocupar com o preenchimento dos campos de impostos.

## Campos obrigatórios para emissão

Para emitir uma **nota fiscal com cálculo automático de impostos**, você deve informar apenas os campos básicos:

| Campo | Descrição | Obrigatório |
|-------|-----------|-------------|
| `borrower.type` | Tipo do tomador de serviço (`Undefined`, `NaturalPerson`, `LegalEntity`) | Sim |
| `borrower.name` | Nome ou Razão Social do tomador | Sim |
| `borrower.federalTaxNumber` | CPF ou CNPJ do tomador (somente números) | Sim |
| `borrower.email` | Email do tomador | Não |
| `borrower.address` | Endereço completo do tomador | Sim |
| `cityServiceCode` | Código do serviço no município | Sim |
| `description` | Descrição do serviço prestado | Sim |
| `servicesAmount` | Valor total do serviço | Sim |

:::info

**Nota:** Os campos de impostos (`issRate`, `issAmount`, retenções, etc.) **não devem ser informados** neste cenário. A plataforma calculará todos os valores automaticamente com base no código de serviço.

:::

---

## Emissão via API

Para emitir uma nota fiscal com cálculo automático de impostos via API, não informe nenhum campo de imposto na requisição. A plataforma calculará automaticamente com base no código de serviço.

### Exemplo de JSON

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "Banco do Brasil SA",
    "federalTaxNumber": 191,
    "municipalTaxNumber": null,
    "email": "joao.silva@emaildobancodobrasil.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01430-000",
      "street": "Avenida Brasil",
      "number": "418",
      "additionalInformation": "ANDAR 1",
      "district": "Jardins",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "0101",
  "description": "Descrição do serviço prestado",
  "servicesAmount": 1000.00
}
```

### Observações importantes

- O campo `federalTaxNumber` deve conter **somente números** (sem pontos, traços ou barras).
- O campo `municipalTaxNumber` é opcional e deve ser informado somente quando exigido pela prefeitura da empresa emissora.
- O campo `borrower.address.city.code` deve conter o **código IBGE** do município (7 dígitos).

---

## Emissão via Planilha

Também é possível emitir notas fiscais com cálculo automático de impostos utilizando a **planilha básica** de importação. Neste cenário, utilize o modelo de planilha básica — nele, os impostos são calculados automaticamente pelo sistema.

### Campos da Planilha

| Coluna da Planilha | API | Descrição | Obrigatório |
|--------------------|-----|-----------|-------------|
| `Codigo_Servico` | `cityServiceCode` | Código do serviço no município | Sim |
| `Descricao` | `description` | Descrição do serviço prestado (máx. 2000 caracteres) | Sim |
| `Valor` | `servicesAmount` | Valor total do serviço (ex: 1000.50 ou 1.000,50) | Sim |
| `CPF_CNPJ` | `borrower.federalTaxNumber` | CPF ou CNPJ do tomador | Sim |
| `Nome` | `borrower.name` | Nome ou Razão Social do tomador | Sim |
| `Email` | `borrower.email` | Email do tomador (múltiplos separados por vírgula) | Não |
| `Endereco_Pais` | `borrower.address.country` | Sigla do país (ISO 3166-1, ex: BRA) | Sim |
| `Endereco_Cep` | `borrower.address.postalCode` | CEP do endereço | Sim |
| `Endereco_Logradouro` | `borrower.address.street` | Nome da rua, avenida, etc. | Sim |
| `Endereco_Numero` | `borrower.address.number` | Número do endereço | Sim |
| `Endereco_Bairro` | `borrower.address.district` | Bairro | Sim |
| `Endereco_Cidade_Codigo` | `borrower.address.city.code` | Código IBGE da cidade (7 dígitos) | Sim |
| `Endereco_Cidade_Nome` | `borrower.address.city.name` | Nome da cidade | Sim |
| `Endereco_Estado` | `borrower.address.state` | Sigla do estado (ex: SP) | Sim |

### Exemplo de preenchimento

| Codigo_Servico | Descricao | Valor | CPF_CNPJ | Nome | Email | Endereco_Pais | Endereco_Cep | Endereco_Logradouro | Endereco_Numero | Endereco_Bairro | Endereco_Cidade_Codigo | Endereco_Cidade_Nome | Endereco_Estado |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0101 | Descrição do serviço prestado | 1000.00 | 00000000000191 | Banco do Brasil SA | joao.silva@email.com.br | BRA | 01430-000 | Avenida Brasil | 418 | Jardins | 3550308 | São Paulo | SP |

### Observações

- Para utilizar o cálculo automático, utilize o modelo de **planilha básica**. Nela, nenhum campo de imposto precisa ser preenchido.
- O campo `CPF_CNPJ` pode ser preenchido com ou sem formatação (pontos, traços, barras).
- O campo `Valor` aceita tanto o formato brasileiro (1.000,50) quanto o americano (1000.50).

---

## Perguntas Frequentes (FAQ)

### Como a plataforma sabe qual alíquota aplicar?

A plataforma utiliza o **código de serviço** (`cityServiceCode`) informado para identificar as alíquotas de impostos configuradas na prefeitura do município da empresa emissora.

### Posso customizar o cálculo automático para minha empresa?

Sim. É possível customizar o cálculo de impostos utilizando o **CNPJ da empresa emissora**, permitindo que o cálculo automático seja ajustado de acordo com as particularidades tributárias de cada empresa.

### Como cadastrar, atualizar ou customizar um imposto?

Para **cadastro de imposto**, **atualização de imposto** ou **cadastro de imposto customizado** para sua empresa, [entre em contato com nosso suporte](https://nfe.io/#contato). A equipe de suporte será responsável por realizar essas configurações na plataforma.

### Posso informar campos de impostos mesmo usando cálculo automático?

Não é recomendado. Se você informar qualquer campo de imposto (como `issRate`), a plataforma entenderá que você deseja controlar os valores manualmente e passará a utilizar os valores informados. Para cálculo manual, consulte o cenário [Cálculo Manual de Impostos](./calculo-manual-impostos).

### O cálculo automático funciona para todas as prefeituras?

Sim, o cálculo automático de impostos funciona para todas as prefeituras integradas à plataforma NFE.io.

### E se o valor calculado automaticamente estiver diferente do esperado?

Recomendamos verificar o código de serviço informado e consultar a tabela de alíquotas da prefeitura. Caso o problema persista, [entre em contato com nosso suporte](https://nfe.io/#contato).

---

## Dúvidas adicionais

Caso tenha dúvidas específicas sobre a emissão de notas fiscais com cálculo automático de impostos, [entre em contato com nosso suporte](https://nfe.io/contato) ou consulte seu contador para orientações sobre o enquadramento correto da sua empresa.

---

**Relacionados:**
- [Dúvidas na Integração da NFS-e](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/)
- [Cálculo de Impostos na NFE.io](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/calculo-de-impostos)
- [Emitir NFS-e em Lote via Planilha](/docs/documentacao/nossa-plataforma/nota-fiscal-servico/emitir-em-lote)

---

## Emissão de NFS-e com Cálculo Manual de Impostos - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/calculo-manual-impostos/index.md

# Emissão de NFS-e com Cálculo Manual de Impostos

Nesta seção, iremos explicar como emitir uma **Nota Fiscal de Serviço Eletrônica (NFS-e)** informando **manualmente os valores de impostos e alíquotas**. Caso não encontre uma resposta para sua dúvida, fique à vontade para [entrar em contato](https://nfe.io/#contato) e enviar sua pergunta.

## O que é o Cálculo Manual de Impostos?

O **cálculo manual de impostos** é o cenário em que você tem **total controle** sobre os detalhes tributários e valores dos impostos a serem enviados para a prefeitura no processamento da nota fiscal. Ao informar qualquer campo de imposto na requisição, a plataforma entende que você deseja controlar os valores manualmente e não realizará o cálculo automático.

### Quando utilizar este cenário?

- **Controle total sobre os impostos**: Quando você precisa definir manualmente os valores de alíquotas e impostos retidos.
- **Alíquotas específicas**: Quando a alíquota de ISS ou outros impostos aplicáveis ao serviço diferem do padrão cadastrado na plataforma.
- **Retenções de impostos**: Quando há necessidade de informar valores de retenção de IR, PIS, COFINS, CSLL, INSS ou ISS.

## Campos para emissão

Para emitir uma **nota fiscal com cálculo manual de impostos**, além dos campos básicos, você deve informar os campos de alíquotas e retenções conforme as regras abaixo:

| Campo | Descrição | Obrigatório |
|-------|-----------|-------------|
| `borrower.type` | Tipo do tomador de serviço (`Undefined`, `NaturalPerson`, `LegalEntity`) | Sim |
| `borrower.name` | Nome ou Razão Social do tomador | Sim |
| `borrower.federalTaxNumber` | CPF ou CNPJ do tomador (somente números) | Sim |
| `borrower.email` | Email do tomador | Não |
| `borrower.address` | Endereço completo do tomador | Sim |
| `cityServiceCode` | Código do serviço no município | Sim |
| `description` | Descrição do serviço prestado | Sim |
| `servicesAmount` | Valor total do serviço | Sim |
| `issRate` | Alíquota do ISS (valor em decimal, ex: 2% = 0.02) | Sim |
| `issAmount` | Valor do ISS calculado (`servicesAmount` x `issRate`) | Condicional* |
| `deductions` | Valor das deduções | Condicional** |
| `unconditionalDiscount` | Valor do desconto incondicionado | Condicional** |
| `conditionalDiscount` | Valor do desconto condicionado | Condicional** |
| `irWithheld` | Valor da retenção de IR | Condicional** |
| `pisWithheld` | Valor da retenção de PIS | Condicional** |
| `cofinsWithheld` | Valor da retenção de COFINS | Condicional** |
| `csllWithheld` | Valor da retenção de CSLL | Condicional** |
| `inssWithheld` | Valor da retenção de INSS | Condicional** |
| `issWithheld` | Valor da retenção de ISS | Condicional** |
| `othersWithheld` | Valor de outras retenções | Condicional** |

:::info

**Regras de obrigatoriedade:**

- **\*ISS**: Você pode informar somente o `issRate` (alíquota do ISS). Porém, se informar o `issAmount` (valor do ISS), é obrigatório informar também o `issRate`, pois são correlatos (`servicesAmount` x `issRate` = `issAmount`).
- **\*\*Impostos retidos**: Se qualquer campo de retenção for informado, **todos os campos de retenção devem ser informados**, definindo `0` para os que não se aplicam.

:::

---

## Emissão via API

Para emitir uma nota fiscal com cálculo manual de impostos via API, informe os campos de alíquotas e retenções na requisição.

### Cenário 1: Informando apenas a alíquota do ISS

Quando você precisa apenas definir a alíquota do ISS, sem informar retenções.

#### Exemplo de JSON

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "Banco do Brasil SA",
    "federalTaxNumber": 191,
    "municipalTaxNumber": null,
    "email": "joao.silva@emaildobancodobrasil.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01430-000",
      "street": "Avenida Brasil",
      "number": "418",
      "additionalInformation": "ANDAR 1",
      "district": "Jardins",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "0101",
  "description": "Descrição do serviço prestado",
  "servicesAmount": 1000.00,
  "issRate": 0.02
}
```

---

### Cenário 2: Informando alíquota, valor do ISS e retenções

Quando você precisa definir todos os valores de impostos e retenções.

#### Exemplo de JSON

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "Banco do Brasil SA",
    "federalTaxNumber": 191,
    "municipalTaxNumber": null,
    "email": "joao.silva@emaildobancodobrasil.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01430-000",
      "street": "Avenida Brasil",
      "number": "418",
      "additionalInformation": "ANDAR 1",
      "district": "Jardins",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "0101",
  "description": "Descrição do serviço prestado",
  "servicesAmount": 1000.00,
  "issRate": 0.02,
  "issAmount": 20.00,
  "deductions": 0.00,
  "unconditionalDiscount": 0.00,
  "conditionalDiscount": 0.00,
  "irWithheld": 0.00,
  "pisWithheld": 0.00,
  "cofinsWithheld": 0.00,
  "csllWithheld": 0.00,
  "inssWithheld": 0.00,
  "issWithheld": 0.00,
  "othersWithheld": 0.00
}
```

### Observações importantes

- O campo `issRate` deve ser informado em **valor decimal** (ex: 2% = 0.02, ou seja, 2 / 100).
- Se o `issAmount` for informado, ele deve ser consistente com a fórmula: `servicesAmount` x `issRate` = `issAmount`.
- Todos os campos de retenção que não se aplicam devem ser preenchidos com `0.00`.
- O campo `federalTaxNumber` deve conter **somente números** (sem pontos, traços ou barras).
- O campo `borrower.address.city.code` deve conter o **código IBGE** do município (7 dígitos).

---

## Emissão via Planilha

Também é possível emitir notas fiscais com cálculo manual de impostos utilizando a **planilha avançada** de importação. Neste cenário, utilize o modelo de planilha avançada — nele, você tem controle total sobre os campos de impostos.

### Campos da Planilha

Além dos campos básicos do tomador e serviço, preencha os seguintes campos tributários:

| Coluna da Planilha | API | Descrição |
|--------------------|-----|-----------|
| `Aliquota_ISS` | `issRate` | Alíquota do ISS em percentual |
| `Valor_ISS` | `issAmount` | Valor do ISS calculado |
| `Retencao_IR` | `irWithheld` | Valor da retenção de IR |
| `Retencao_PIS` | `pisWithheld` | Valor da retenção de PIS |
| `Retencao_COFINS` | `cofinsWithheld` | Valor da retenção de COFINS |
| `Retencao_CSLL` | `csllWithheld` | Valor da retenção de CSLL |
| `Retencao_INSS` | `inssWithheld` | Valor da retenção de INSS |
| `Retencao_ISS` | `issWithheld` | Valor da retenção de ISS |
| `Retencao_OUTROS` | `othersWithheld` | Valor de outras retenções |
| `Valor_Deducoes` | `deductions` | Valor das deduções legais |
| `Valor_Desconto_Incondicionado` | `unconditionalDiscount` | Valor do desconto incondicionado |
| `Valor_Desconto_Condicionado` | `conditionalDiscount` | Valor do desconto condicionado |

### Exemplo de preenchimento

| Codigo_Servico | Descricao | Valor | CPF_CNPJ | Nome | Aliquota_ISS | Valor_ISS | Retencao_IR | Retencao_PIS | Retencao_COFINS | Retencao_CSLL | Retencao_INSS | Retencao_ISS | Retencao_OUTROS | Valor_Deducoes | Valor_Desconto_Incondicionado | Valor_Desconto_Condicionado |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0101 | Descrição do serviço prestado | 1000.00 | 00000000000191 | Banco do Brasil SA | 2 | 20.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 |

### Observações

- Para utilizar o cálculo manual, utilize o modelo de **planilha avançada**.
- Na planilha, a alíquota do ISS (`Aliquota_ISS`) é informada em **percentual** (ex: 2 para 2%), diferente da API onde o valor é em decimal (0.02).
- As mesmas regras de obrigatoriedade da API se aplicam à planilha: se um campo de retenção for preenchido, todos devem ser preenchidos.

---

## Perguntas Frequentes (FAQ)

### Qual a diferença entre a alíquota na API e na planilha?

Na **API**, a alíquota do ISS (`issRate`) deve ser informada em **valor decimal** (ex: 2% = 0.02). Na **planilha**, o campo `Aliquota_ISS` é informado em **percentual** (ex: 2% = 2).

### O que acontece se eu não informar todos os campos de impostos?

Os campos de impostos seguem regras específicas:

- **ISS**: Você pode informar somente o campo `issRate` (alíquota do ISS). Porém, se informar o campo `issAmount` (valor do ISS), é obrigatório informar também o `issRate`, pois eles são correlatos (`servicesAmount` x `issRate` = `issAmount`).
- **Impostos retidos**: Se qualquer campo de retenção for informado (`irWithheld`, `pisWithheld`, `cofinsWithheld`, `csllWithheld`, `inssWithheld`, `issWithheld`, `othersWithheld`), **todos os campos de retenção devem ser informados**, definindo `0` para os que não se aplicam.

### Posso misturar cálculo automático e manual?

Não. Ao informar qualquer campo de imposto na requisição, a plataforma entende que você deseja controlar os valores manualmente. Se você quer que a plataforma calcule automaticamente, não informe nenhum campo de imposto. Consulte o cenário [Cálculo Automático de Impostos](./calculo-automatico-impostos).

### Como sei quais alíquotas aplicar para o meu serviço?

Recomendamos consultar a **tabela de alíquotas da prefeitura** do município da empresa emissora ou seu **contador** para identificar as alíquotas corretas para cada tipo de serviço.

### Como cadastrar, atualizar ou customizar um imposto?

Para **cadastro de imposto**, **atualização de imposto** ou **cadastro de imposto customizado** para sua empresa, [entre em contato com nosso suporte](https://nfe.io/#contato). A equipe de suporte será responsável por realizar essas configurações na plataforma.

---

## Dúvidas adicionais

Caso tenha dúvidas específicas sobre a emissão de notas fiscais com cálculo manual de impostos, [entre em contato com nosso suporte](https://nfe.io/contato) ou consulte seu contador para orientações sobre o enquadramento correto da sua empresa.

---

**Relacionados:**
- [Cálculo Automático de Impostos](./calculo-automatico-impostos)
- [Dúvidas na Integração da NFS-e](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/)
- [Cálculo de Impostos na NFE.io](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/calculo-de-impostos)
- [Emitir NFS-e em Lote via Planilha](/docs/documentacao/nossa-plataforma/nota-fiscal-servico/emitir-em-lote)

---

## Emissão de NFS-e com Cliente Domiciliado no Exterior - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/cliente-exterior/index.md

# Emissão de NFS-e com Cliente Domiciliado no Exterior

Nesta seção, iremos explicar como emitir uma **Nota Fiscal de Serviço Eletrônica (NFS-e)** quando o **tomador do serviço (cliente) está domiciliado fora do Brasil**. Caso não encontre uma resposta para sua dúvida, fique à vontade para [entrar em contato](https://nfe.io/#contato) e enviar sua pergunta.

## O que é a emissão para cliente no exterior?

A emissão para **cliente domiciliado no exterior** ocorre quando a empresa prestadora de serviço (emissora da nota fiscal) realiza um serviço para um cliente que está localizado **fora do Brasil**. Neste cenário, alguns campos do tomador que normalmente são obrigatórios passam a ser **opcionais**, pois não se aplicam a endereços internacionais.

### Quando utilizar este cenário?

- **Exportação de serviços**: Quando a empresa brasileira presta serviços para um cliente no exterior.
- **Cliente pessoa jurídica estrangeira**: Quando o tomador é uma empresa registrada fora do Brasil.
- **Cliente pessoa física no exterior**: Quando o tomador é uma pessoa física domiciliada fora do Brasil.

## Como a plataforma identifica um cliente no exterior?

Nossa plataforma utiliza o campo **`borrower.address.country`** como referência para identificar se o cliente está fora do Brasil. Os valores aceitos seguem o padrão [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) (código de 3 letras).

- Se o valor for **`BRA`**, o cliente é considerado nacional.
- Se o valor for **diferente de `BRA`** (ex: `USA`, `ARG`, `DEU`), o cliente é considerado no exterior e a plataforma ajusta automaticamente os campos obrigatórios.

## Campos para emissão

Para emitir uma **nota fiscal com cliente no exterior**, os campos obrigatórios são reduzidos em relação a uma emissão nacional:

| Campo | Descrição | Obrigatório |
|-------|-----------|-------------|
| `borrower.type` | Tipo do tomador de serviço (`Undefined`, `NaturalPerson`, `LegalEntity`) | Sim |
| `borrower.name` | Nome ou Razão Social do tomador | Sim |
| `borrower.federalTaxNumber` | CPF ou CNPJ do tomador (opcional para exterior, informar `0` quando não aplicável) | Não |
| `borrower.email` | Email do tomador | Não |
| `borrower.address.country` | Sigla do país no padrão ISO 3166-1 (ex: `USA`, `ARG`) | Sim |
| `borrower.address.postalCode` | Código postal do endereço no exterior | Não |
| `borrower.address.street` | Logradouro | Sim |
| `borrower.address.number` | Número do endereço | Sim |
| `borrower.address.district` | Bairro | Sim |
| `borrower.address.city.name` | Nome da cidade | Sim |
| `borrower.address.city.code` | Código IBGE da cidade (não se aplica para exterior) | Não |
| `borrower.address.state` | Estado, Província ou Região no exterior | Não |
| `cityServiceCode` | Código do serviço no município | Sim |
| `description` | Descrição do serviço prestado | Sim |
| `servicesAmount` | Valor total do serviço | Sim |

:::info

**Nota:** Para clientes no exterior, os campos `federalTaxNumber`, `postalCode`, `city.code` e `state` são **opcionais**. O campo `federalTaxNumber` pode ser informado como `0` quando o cliente não possui CPF ou CNPJ brasileiro.

:::

---

## Emissão via API

Para emitir uma nota fiscal com cliente domiciliado no exterior via API, envie uma requisição informando o campo `borrower.address.country` com um código ISO 3166-1 diferente de `BRA`.

### Exemplo de JSON

```json
{
  "borrower": {
    "type": "Undefined",
    "name": "Google LLC",
    "federalTaxNumber": 0,
    "email": "joao.silva@emaildogoogle.com.br",
    "address": {
      "country": "USA",
      "postalCode": "02142",
      "street": "Main Street",
      "number": "355",
      "additionalInformation": "",
      "district": "Downtown",
      "city": {
        "name": "Cambridge"
      },
      "state": "MA"
    }
  },
  "cityServiceCode": "0101",
  "description": "Descrição do serviço prestado",
  "servicesAmount": 1000.00
}
```

### Observações importantes

- O campo `borrower.type` pode ser `"Undefined"` quando o tipo do tomador não se aplica ao contexto internacional.
- O campo `borrower.address.city.code` (código IBGE) **não deve ser informado** para endereços no exterior, pois não existe código IBGE para cidades internacionais.
- O campo `borrower.address.state` aceita valores com até 60 caracteres para estados, províncias ou regiões no exterior (diferente do padrão nacional de 2 caracteres).

---

## Emissão via Planilha

Também é possível emitir notas fiscais com cliente no exterior utilizando a planilha de importação. O campo principal que determina o cenário é o `endereco_pais`.

### Campos da Planilha

| Coluna da Planilha | API | Descrição | Obrigatório |
|--------------------|-----|-----------|-------------|
| `cpf_cnpj` | `borrower.federalTaxNumber` | CPF ou CNPJ do tomador (informar `0` para exterior) | Não |
| `nome` | `borrower.name` | Nome ou Razão Social do tomador | Sim |
| `email` | `borrower.email` | Email do tomador | Não |
| `endereco_pais` | `borrower.address.country` | Sigla do país ISO 3166-1 (ex: USA, ARG, DEU) | Sim |
| `endereco_cep` | `borrower.address.postalCode` | Código postal no exterior | Não |
| `endereco_logradouro` | `borrower.address.street` | Logradouro | Sim |
| `endereco_numero` | `borrower.address.number` | Número do endereço | Sim |
| `endereco_bairro` | `borrower.address.district` | Bairro | Sim |
| `endereco_cidade_nome` | `borrower.address.city.name` | Nome da cidade | Sim |
| `endereco_cidade_codigo` | `borrower.address.city.code` | Código IBGE (não preencher para exterior) | Não |
| `endereco_estado` | `borrower.address.state` | Estado, Província ou Região | Não |
| `codigo_servico` | `cityServiceCode` | Código do serviço no município | Sim |
| `descricao` | `description` | Descrição do serviço prestado | Sim |
| `valor` | `servicesAmount` | Valor total do serviço | Sim |

### Exemplo de preenchimento

| cpf_cnpj | nome | email | endereco_pais | endereco_cep | endereco_logradouro | endereco_numero | endereco_bairro | endereco_cidade_nome | endereco_estado | codigo_servico | descricao | valor |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Google LLC | contato@google.com | USA | 02142 | Main Street | 355 | Downtown | Cambridge | MA | 0101 | Descrição do serviço prestado | 1000.00 |

### Observações

- O campo `endereco_pais` deve conter a sigla do país no padrão **ISO 3166-1** (3 letras). Exemplos: `USA`, `ARG`, `DEU`, `GBR`, `JPN`.
- O campo `endereco_cidade_codigo` (código IBGE) **não deve ser preenchido** para clientes no exterior.
- O campo `cpf_cnpj` pode ser preenchido com `0` para clientes que não possuem documento brasileiro.

---

## Perguntas Frequentes (FAQ)

### Preciso informar o CPF/CNPJ do cliente no exterior?

Não. O campo `federalTaxNumber` (ou `cpf_cnpj` na planilha) é **opcional** para clientes no exterior. Informe `0` quando o cliente não possuir documento brasileiro.

### Como sei qual código ISO 3166-1 usar para o país do cliente?

Os códigos seguem o padrão [ISO 3166-1 alfa-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). Alguns exemplos comuns:

| País | Código |
|------|--------|
| Estados Unidos | `USA` |
| Argentina | `ARG` |
| Alemanha | `DEU` |
| Reino Unido | `GBR` |
| Japão | `JPN` |
| Portugal | `PRT` |
| Canadá | `CAN` |

### Posso usar cálculo automático de impostos para clientes no exterior?

Sim. O cálculo automático de impostos funciona normalmente para clientes no exterior. A plataforma identificará automaticamente os detalhes tributários com base no código de serviço.

### O que acontece com o ISS para serviços prestados ao exterior?

A tributação de serviços prestados ao exterior pode variar. Recomendamos consultar seu contador para verificar se o serviço se enquadra como **exportação de serviço** (com possível isenção de ISS) e configurar o campo `taxationType` adequadamente (ex: `Export`).

### Como cadastrar, atualizar ou customizar um imposto?

Para **cadastro de imposto**, **atualização de imposto** ou **cadastro de imposto customizado** para sua empresa, [entre em contato com nosso suporte](https://nfe.io/#contato). A equipe de suporte será responsável por realizar essas configurações na plataforma.

---

## Dúvidas adicionais

Caso tenha dúvidas específicas sobre a emissão de notas fiscais com cliente domiciliado no exterior, [entre em contato com nosso suporte](https://nfe.io/contato) ou consulte seu contador para orientações sobre o enquadramento correto da sua empresa.

---

**Relacionados:**
- [Cálculo Automático de Impostos](./calculo-automatico-impostos)
- [Cálculo Manual de Impostos](./calculo-manual-impostos)
- [Dúvidas na Integração da NFS-e](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/)
- [Cálculo de Impostos na NFE.io](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/calculo-de-impostos)

---

## Emissão de NFS-e com Cliente Não Identificado - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/cliente-nao-identificado/index.md

# Emissão de NFS-e com Cliente Não Identificado

Nesta seção, iremos explicar como emitir uma **Nota Fiscal de Serviço Eletrônica (NFS-e)** quando o **tomador do serviço (cliente) não foi identificado** no momento da venda. Caso não encontre uma resposta para sua dúvida, fique à vontade para [entrar em contato](https://nfe.io/#contato) e enviar sua pergunta.

## O que é a emissão para cliente não identificado?

A emissão para **cliente não identificado** ocorre quando a empresa prestadora de serviço precisa emitir uma nota fiscal, mas **não possui os dados do cliente** — como CPF/CNPJ, nome ou endereço. Isso pode acontecer em vendas de balcão, atendimentos esporádicos ou situações onde a identificação do tomador não foi possível.

### Quando utilizar este cenário?

- **Vendas de balcão**: Quando o serviço é prestado a um cliente que não forneceu seus dados.
- **Atendimentos esporádicos**: Quando não há necessidade ou possibilidade de identificar o tomador.
- **Cliente sem CPF/CNPJ**: Quando o tomador não possui ou não informou um documento de identificação.

## Campos para emissão

Embora o cliente não tenha sido identificado, muitas prefeituras **exigem o envio de alguns campos do tomador**. Por isso, recomendamos a abordagem abaixo, que funciona em todas as prefeituras e pró-fisco.

| Campo | Descrição | Valor Recomendado |
|-------|-----------|-------------------|
| `borrower.type` | Tipo do tomador de serviço | `Undefined` |
| `borrower.name` | Nome do tomador | `CLIENTE NAO IDENTIFICADO` |
| `borrower.federalTaxNumber` | CPF ou CNPJ | `0` |
| `borrower.email` | Email do tomador | `null` |
| `borrower.address.country` | Sigla do país | `BRA` |
| `borrower.address.postalCode` | CEP | `00000-000` |
| `borrower.address.street` | Logradouro | `RUA NAO IDENTIFICADO` |
| `borrower.address.number` | Número | `S/N` |
| `borrower.address.additionalInformation` | Complemento | (vazio) |
| `borrower.address.district` | Bairro | `NAO IDENTIFICADO` |
| `borrower.address.city.name` | Nome da cidade | **Cidade da sua empresa** |
| `borrower.address.city.code` | Código IBGE da cidade | **Código IBGE da cidade da sua empresa** |
| `borrower.address.state` | Estado | **Estado da sua empresa** |
| `cityServiceCode` | Código do serviço no município | Sim (obrigatório) |
| `description` | Descrição do serviço prestado | Sim (obrigatório) |
| `servicesAmount` | Valor total do serviço | Sim (obrigatório) |

:::warning

**Atenção:** Os campos `borrower.address.city.name`, `borrower.address.city.code` e `borrower.address.state` devem ser preenchidos com os **dados da sua empresa** (emissora da nota fiscal). Dessa forma, estamos declarando ao fisco que a empresa deve os tributos para a cidade em que está registrada. Recomendamos que avalie com seu contador antes de utilizar essa abordagem.

:::

---

## Emissão via API

Para emitir uma nota fiscal com cliente não identificado via API, envie uma requisição com os campos do tomador preenchidos com valores de placeholder.

### Exemplo de JSON

```json
{
  "borrower": {
    "type": "Undefined",
    "name": "CLIENTE NAO IDENTIFICADO",
    "federalTaxNumber": 0,
    "email": null,
    "address": {
      "country": "BRA",
      "postalCode": "00000-000",
      "street": "RUA NAO IDENTIFICADO",
      "number": "S/N",
      "additionalInformation": "",
      "district": "NAO IDENTIFICADO",
      "city": {
        "name": "São Paulo",
        "code": "3550308"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "0101",
  "description": "Descrição do serviço prestado",
  "servicesAmount": 1000.00
}
```

### Observações importantes

- Substitua `"São Paulo"`, `"3550308"` e `"SP"` pelos dados reais da **cidade, código IBGE e estado da sua empresa emissora**.
- O campo `federalTaxNumber` deve ser informado como `0` para indicar que o cliente não possui documento.
- O campo `email` deve ser informado como `null` ou omitido.

---

## Emissão via Planilha

Também é possível emitir notas fiscais com cliente não identificado utilizando a planilha de importação. Preencha os campos do tomador com os valores de placeholder recomendados.

### Campos da Planilha

| Coluna da Planilha | API | Valor Recomendado |
|--------------------|-----|-------------------|
| `cpf_cnpj` | `borrower.federalTaxNumber` | `0` |
| `nome` | `borrower.name` | `CLIENTE NAO IDENTIFICADO` |
| `email` | `borrower.email` | (vazio) |
| `endereco_pais` | `borrower.address.country` | `BRA` |
| `endereco_cep` | `borrower.address.postalCode` | `00000-000` |
| `endereco_logradouro` | `borrower.address.street` | `RUA NAO IDENTIFICADO` |
| `endereco_numero` | `borrower.address.number` | `S/N` |
| `endereco_bairro` | `borrower.address.district` | `NAO IDENTIFICADO` |
| `endereco_cidade_nome` | `borrower.address.city.name` | Cidade da sua empresa |
| `endereco_cidade_codigo` | `borrower.address.city.code` | Código IBGE da sua empresa |
| `endereco_estado` | `borrower.address.state` | Estado da sua empresa |
| `codigo_servico` | `cityServiceCode` | Código do serviço |
| `descricao` | `description` | Descrição do serviço |
| `valor` | `servicesAmount` | Valor do serviço |

### Exemplo de preenchimento

| cpf_cnpj | nome | email | endereco_pais | endereco_cep | endereco_logradouro | endereco_numero | endereco_bairro | endereco_cidade_nome | endereco_cidade_codigo | endereco_estado | codigo_servico | descricao | valor |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | CLIENTE NAO IDENTIFICADO | | BRA | 00000-000 | RUA NAO IDENTIFICADO | S/N | NAO IDENTIFICADO | São Paulo | 3550308 | SP | 0101 | Descrição do serviço prestado | 1000.00 |

### Observações

- Substitua os campos de cidade, código IBGE e estado pelos dados da **sua empresa emissora**.
- O campo `email` deve ser deixado **em branco**.
- O campo `cpf_cnpj` deve ser preenchido com `0`.

---

## Perguntas Frequentes (FAQ)

### Posso deixar os campos do tomador completamente vazios?

Não é recomendado. Muitas prefeituras exigem o envio de dados mínimos do tomador. A abordagem com valores de placeholder (como `CLIENTE NAO IDENTIFICADO`) garante compatibilidade com todas as prefeituras integradas.

### Por que usar os dados da minha empresa nos campos de cidade e estado?

Ao informar a cidade e estado da empresa emissora, estamos declarando ao fisco que os tributos devidos são para o município onde a empresa está registrada. Isso evita rejeições por parte das prefeituras que exigem esses campos.

### Posso usar cálculo automático de impostos neste cenário?

Sim. O cálculo automático de impostos funciona normalmente para o cenário de cliente não identificado. A plataforma calculará os impostos com base no código de serviço informado.

### Essa abordagem é aceita por todas as prefeituras?

Sim. A abordagem recomendada com valores de placeholder funciona em **todas as prefeituras** integradas à plataforma NFE.io e é compatível com o pró-fisco.

### Como cadastrar, atualizar ou customizar um imposto?

Para **cadastro de imposto**, **atualização de imposto** ou **cadastro de imposto customizado** para sua empresa, [entre em contato com nosso suporte](https://nfe.io/#contato). A equipe de suporte será responsável por realizar essas configurações na plataforma.

---

## Dúvidas adicionais

Caso tenha dúvidas específicas sobre a emissão de notas fiscais com cliente não identificado, [entre em contato com nosso suporte](https://nfe.io/contato) ou consulte seu contador para orientações sobre o enquadramento correto da sua empresa.

---

**Relacionados:**
- [Cálculo Automático de Impostos](./calculo-automatico-impostos)
- [Cálculo Manual de Impostos](./calculo-manual-impostos)
- [Cliente Domiciliado no Exterior](./cliente-exterior)
- [Dúvidas na Integração da NFS-e](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/)
- [Cálculo de Impostos na NFE.io](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/calculo-de-impostos)

---

## Emissão de NFS-e com externalId e RPS - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/cenarios-externalid-e-rps/index.md

# Emissão de NFS-e com externalId e RPS

Campos de integração: `externalId` (idempotência) e `RPS` (número + série).

### Com externalId

`externalId` garante idempotência — reenvio com o mesmo valor retorna 400 (já existe).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "externalId": "NFSE-EXEMPLO-0001"
}
```

### Com RPS (número + série)

`rpsNumber` + `rpsSerialNumber` identificam o recibo provisório.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "rpsSerialNumber": "A",
  "rpsNumber": 1001
}
```

## Veja também

- [Matriz de cenários de emissão](./matriz-de-cenarios.md)

---

## Emissão de NFS-e: ISS e local de prestação - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/cenarios-iss-e-local/index.md

# Emissão de NFS-e: ISS e local de prestação

Tributação do ISS e local de prestação. Por padrão a plataforma calcula o ISS automaticamente — `issRate`/`taxationType` são opcionais.

### Cálculo manual do ISS (issRate)

**`issRate` é opcional.** Por padrão a plataforma calcula o ISS automaticamente; informe-o apenas para cálculo manual. Veja [Cálculo manual de impostos](./calculo-manual-impostos.md).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "issRate": 0.05,
  "taxationType": "WithinCity"
}
```

### ISS isento

`taxationType=Free` para serviços isentos do ISS.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "taxationType": "Free"
}
```

### ISS imune

`taxationType=Immune` + `immunityType` (imunidade constitucional).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "taxationType": "Immune",
  "immunityType": "Temples"
}
```

### ISS com exigibilidade suspensa

`taxationType=SuspendedCourtDecision` + grupo `suspension`.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "taxationType": "SuspendedCourtDecision",
  "suspension": {
    "reason": "1",
    "processNumber": "0012345-67.2026"
  }
}
```

### Informar local de prestação

Grupo `location` indica onde o serviço foi prestado.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "location": {
    "country": "BRA",
    "postalCode": "01311-000",
    "street": "Avenida Exemplo",
    "number": "1000",
    "district": "Centro",
    "city": {
      "code": "3550308",
      "name": "São Paulo"
    },
    "state": "SP"
  }
}
```

### Serviço prestado fora do município

`taxationType=OutsideCity` + `location` no município da prestação (ISS devido fora).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "taxationType": "OutsideCity",
  "location": {
    "country": "BRA",
    "postalCode": "01311-000",
    "street": "Avenida Exemplo",
    "number": "1000",
    "district": "Centro",
    "city": {
      "code": "3509502",
      "name": "Campinas"
    },
    "state": "SP"
  }
}
```

### Três municípios

Prestador, tomador e prestação em municípios distintos.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Exemplo",
      "number": "1000",
      "district": "Centro",
      "city": {
        "code": "3304557",
        "name": "Rio de Janeiro"
      },
      "state": "RJ"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "taxationType": "OutsideCity",
  "location": {
    "country": "BRA",
    "postalCode": "01311-000",
    "street": "Avenida Exemplo",
    "number": "1000",
    "district": "Centro",
    "city": {
      "code": "3106200",
      "name": "Belo Horizonte"
    },
    "state": "MG"
  }
}
```

## Veja também

- [Matriz de cenários de emissão](./matriz-de-cenarios.md)

---

## Matriz de cenários de emissão de NFS-e - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/matriz-de-cenarios/index.md

# Matriz de cenários de emissão de NFS-e

Índice dos **26 cenários** de emissão. Cada um é o **payload base** abaixo + os campos do seu eixo.

## Payload base (tomador completo)

Padrão recomendado: os obrigatórios + o **tomador completo com endereço** (a plataforma calcula os impostos automaticamente, mas **não** completa o endereço do tomador):

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0
}
```

:::note
CNPJ/CPF dos exemplos têm dígito verificador válido e os códigos de cidade são IBGE reais. Substitua pelos dados reais da sua operação. `issRate`/`taxationType` são **opcionais** (padrão: cálculo automático).
:::

## Os 26 cenários

| Cenário | Guia |
|---|---|
| Emissão padrão (tomador completo) | [Por regime e tomador](./por-regime-tributario.md) |
| Tomador pessoa física (CPF) | [Por regime e tomador](./por-regime-tributario.md) |
| Tomador pessoa jurídica (CNPJ) | [Por regime e tomador](./por-regime-tributario.md) |
| IBS/CBS com cálculo automático (payload mínimo) | [Reforma Tributária (IBS/CBS)](./reforma-tributaria-ibs-cbs.md) |
| IBS/CBS regime geral (com valores) | [Reforma Tributária (IBS/CBS)](./reforma-tributaria-ibs-cbs.md) |
| IBS/CBS compra governamental | [Reforma Tributária (IBS/CBS)](./reforma-tributaria-ibs-cbs.md) |
| Cálculo manual do ISS (issRate) | [ISS e local de prestação](./local-de-prestacao.md) |
| ISS isento | [ISS e local de prestação](./local-de-prestacao.md) |
| ISS imune | [ISS e local de prestação](./local-de-prestacao.md) |
| ISS com exigibilidade suspensa | [ISS e local de prestação](./local-de-prestacao.md) |
| Informar local de prestação | [ISS e local de prestação](./local-de-prestacao.md) |
| Serviço prestado fora do município | [ISS e local de prestação](./local-de-prestacao.md) |
| Três municípios | [ISS e local de prestação](./local-de-prestacao.md) |
| Retenção de IRRF | [Retenções](./retencoes.md) |
| ISS retido pelo tomador | [Retenções](./retencoes.md) |
| Retenção de PIS/COFINS/CSLL | [Retenções](./retencoes.md) |
| Retenção de INSS | [Retenções](./retencoes.md) |
| Retenção plena (ISS + federais) | [Retenções](./retencoes.md) |
| Evento | [Tipos de atividade](./tipos-de-atividade.md) |
| Construção civil | [Tipos de atividade](./tipos-de-atividade.md) |
| Locação | [Tipos de atividade](./tipos-de-atividade.md) |
| Comércio exterior | [Tipos de atividade](./tipos-de-atividade.md) |
| Substituição / nota referenciada | [Tipos de atividade](./tipos-de-atividade.md) |
| Intermediário | [Tipos de atividade](./tipos-de-atividade.md) |
| Com externalId | [externalId e RPS](./externalid-e-rps.md) |
| Com RPS (número + série) | [externalId e RPS](./externalid-e-rps.md) |

## Cenários já documentados (guias dedicados)

- [Cálculo automático de impostos](./calculo-automatico-impostos.md) — padrão da plataforma
- [Cálculo manual de impostos](./calculo-manual-impostos.md)
- [Cliente no exterior](./cliente-exterior.md)
- [Cliente não identificado](./cliente-nao-identificado.md)

## Veja também

- [Cenários de erro 400 na emissão](../erros-e-status/cenarios-de-badrequest-na-emissao.md)

---

## Emissão de NFS-e por regime tributário e tomador - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/cenarios-regime-tributario/index.md

# Emissão de NFS-e por regime tributário e tomador

Esta página cobre o **regime tributário do prestador** e o **tipo de tomador**. O regime é configuração da empresa emissora; o tomador vai no payload (recomendado enviá-lo completo, com endereço).

## Por regime tributário do prestador

O **regime tributário** (MEI, Simples Nacional, Lucro Presumido, Lucro Real) é configuração da **empresa emissora** (prestador), definida no cadastro da empresa — **não é um campo do payload de emissão**. O regime define quais campos fiscais fazem sentido na nota:

- **MEI** — ISS normalmente fixo (recolhido em valor fixo pela prefeitura); emissão simples, sem retenções federais e geralmente sem alíquota de ISS variável.
- **Simples Nacional** — ISS recolhido dentro do DAS; pode informar a alíquota do ISS; normalmente sem retenção de tributos federais pelo prestador.
- **Lucro Presumido** — regime normal; podem ocorrer retenções de tributos federais (IR, PIS/COFINS/CSLL, INSS) em operações entre empresas.
- **Lucro Real** — regime normal; base para as retenções federais mais completas.

> O regime é definido no cadastro da empresa (não na nota). Para os campos que variam por regime, veja [Retenções](./retencoes.md) e [ISS e local de prestação](./local-de-prestacao.md).

## Por tipo de tomador

### Emissão padrão (tomador completo)

Padrão recomendado: os obrigatórios + **tomador completo com endereço**. A plataforma calcula os impostos automaticamente, mas **não** completa o endereço do tomador — por isso envie-o completo.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0
}
```

### Tomador pessoa física (CPF)

Tomador PF: `type=NaturalPerson` e `federalTaxNumber` com CPF.

```json
{
  "borrower": {
    "type": "NaturalPerson",
    "name": "MARIA DA SILVA",
    "federalTaxNumber": 11144477735,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0
}
```

### Tomador pessoa jurídica (CNPJ)

Tomador PJ: `federalTaxNumber` com CNPJ.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0
}
```

## O endereço do tomador é preenchido automaticamente?

**Não.** Se você enviar o tomador apenas com `name` e `federalTaxNumber` (sem o grupo `address`), a NFS-e é emitida assim mesmo — a plataforma **não consulta o CNPJ/CPF para completar o endereço**. Onde o endereço do tomador é exibido (ex.: no DANFSE/PDF), ele aparece como **"Endereço Não Informado"**.

Na prática, a **maioria das emissões já envia o endereço do tomador** — é o padrão do mercado. Por isso, o **recomendado é enviar o tomador completo** (com endereço), como nos exemplos acima. O que a plataforma faz nos bastidores ao receber `federalTaxNumber`:

- **Registra o tomador** na lista de Pessoas (Físicas/Jurídicas) da sua conta, reutilizando o cadastro por CPF/CNPJ. Isso vincula o tomador ao seu cadastro, mas **não** preenche o endereço da nota.
- Quando você **envia** `borrower.address` (país `BRA`), a plataforma normaliza o nome da cidade e a UF — mas não cria dados que você não enviou.

:::tip
Se a sua prefeitura exigir o endereço do tomador (ou se você quiser que ele conste no DANFSE), **envie o grupo `borrower.address`** — veja os campos em [Referência completa de campos](./referencia-completa-de-campos.md).
:::

## Veja também

- [Matriz de cenários de emissão](./matriz-de-cenarios.md)

---

## Referência completa de campos de emissão de NFS-e - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/cenarios-referencia-completa-campos/index.md

# Referência completa de campos de emissão de NFS-e

Lista de **todos os campos** aceitos no corpo (`POST`) de emissão de NFS-e. Apenas `cityServiceCode`, `description`, `servicesAmount` e `borrower` são **obrigatórios** — todo o restante é opcional e deve ser enviado apenas quando aplicável.

:::note
Por padrão a plataforma faz o **cálculo automático** dos impostos — os campos de alíquota/valor (`issRate`, `pisRate`, etc.) são opcionais e usados apenas no cálculo manual. Veja [Cálculo automático](./calculo-automatico-impostos.md) e [Cálculo manual](./calculo-manual-impostos.md).
:::

## Obrigatórios

| Campo | Tipo | Descrição |
|---|---|---|
| `cityServiceCode` | string | Código do serviço no município. |
| `description` | string | Descrição dos serviços. |
| `servicesAmount` | número | Valor dos serviços. |
| `borrower` | objeto | Tomador dos serviços (ver [Por regime e tomador](./por-regime-tributario.md)). |

## Identificação e datas

| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
| `externalId` | string | Identificação externa (idempotência). | [externalId e RPS](./externalid-e-rps.md) |
| `issuedOn` | data/hora | Data da emissão. | — |
| `accrualOn` | data (AAAA-MM-DD) | Data da competência da prestação. | — |
| `rpsSerialNumber` | string | Número de série da RPS. | [externalId e RPS](./externalid-e-rps.md) |
| `rpsNumber` | inteiro | Número da RPS. | [externalId e RPS](./externalid-e-rps.md) |

## Classificação do serviço

| Campo | Tipo | Descrição |
|---|---|---|
| `federalServiceCode` | string | Código federal do serviço (item da lista LC 116). |
| `cnaeCode` | string | Código CNAE (quando exigido pela cidade). |
| `nbsCode` | string | Código NBS (quando exigido pela cidade). |
| `ncmCode` | string | Código NCM (Nomenclatura Comum do Mercosul). |

:::tip
Sobre a validação de **CNAE × item da LC116** (algumas prefeituras exigem compatibilidade), veja [CNAE e item da LC116](../impostos-e-classificacao/cnae-e-item-da-lc116.md).
:::

## Valores e pagamento

| Campo | Tipo | Descrição |
|---|---|---|
| `paidAmount` | número | Valor dos serviços pago. |
| `paymentMethod` | enum | Forma de pagamento. |
| `deductionsAmount` | número | Valor de deduções. |
| `discountUnconditionedAmount` | número | Valor do desconto incondicionado. |
| `discountConditionedAmount` | número | Valor do desconto condicionado. |
| `isEarlyInstallmentPayment` | booleano | Indica pagamento antecipado de parcela. |

## ISS e tributação

| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
| `taxationType` | enum | Tipo da tributação (`WithinCity`, `OutsideCity`, `Free`, `Immune`, `SuspendedCourtDecision`, `FixedISSQN`, …). | [ISS e local](./local-de-prestacao.md) |
| `issRate` | número | Alíquota do ISS (cálculo manual; opcional). | [ISS e local](./local-de-prestacao.md) |
| `issTaxAmount` | número | Valor do ISS. | — |
| `issAmountWithheld` | número | Valor retido do ISS. | [Retenções](./retencoes.md) |
| `retentionType` | enum | Tipo de retenção do ISSQN (`withheldByBuyer`, `withheldByIntermediary`, `notWithheld`). | [Retenções](./retencoes.md) |
| `immunityType` | enum | Tipo de imunidade (apenas com `taxationType=Immune`). | [ISS e local](./local-de-prestacao.md) |

## Retenções federais

| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
| `irAmountWithheld` | número | Valor retido do IR. | [Retenções](./retencoes.md) |
| `cstPisCofins` | enum | Código de Situação Tributária PIS/COFINS. | — |
| `pisCofinsBaseTax` | número | Base de cálculo de PIS/COFINS. | — |
| `pisAmount` / `pisRate` / `pisAmountWithheld` | número | Valor / alíquota / valor retido do PIS. | [Retenções](./retencoes.md) |
| `cofinsAmount` / `cofinsRate` / `cofinsAmountWithheld` | número | Valor / alíquota / valor retido do COFINS. | [Retenções](./retencoes.md) |
| `csllAmount` / `csllRate` / `csllAmountWithheld` | número | Valor / alíquota / valor retido do CSLL. | [Retenções](./retencoes.md) |
| `inssRate` / `inssAmountWithheld` | número | Alíquota / valor retido do INSS. | [Retenções](./retencoes.md) |
| `ipiRate` / `ipiAmount` | número | Alíquota / valor do IPI (SP). | — |
| `othersAmountWithheld` | número | Valor de outras retenções. | — |

:::note
Clientes às vezes enviam `irRate` (alíquota do IR), mas **o contrato não tem esse campo** — para o IR, use `irAmountWithheld` (valor retido).
:::

## Reforma Tributária (IBS/CBS)

| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
| `ibsCbs` | objeto | Grupo de IBS/CBS (`operationIndicator`, `classCode`, `situationCode`, `ibs`, `cbs`, `governmentPurchase`, …). | [Reforma Tributária](./reforma-tributaria-ibs-cbs.md) |

## Local e grupos de atividade

| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
| `location` | objeto | Local da prestação do serviço. | [ISS e local](./local-de-prestacao.md) |
| `activityEvent` | objeto | Atividade de evento (nome, datas, endereço). | [Tipos de atividade](./tipos-de-atividade.md) |
| `realEstate` | objeto | Operações com bens imóveis (exceto obras). | — |
| `construction` | objeto | Obras de construção civil. | [Tipos de atividade](./tipos-de-atividade.md) |
| `lease` | objeto | Locação/sublocação/arrendamento/direito de passagem. | [Tipos de atividade](./tipos-de-atividade.md) |
| `foreignTrade` | objeto | Transações com residentes/domiciliados no exterior. | [Tipos de atividade](./tipos-de-atividade.md) |
| `referenceSubstitution` | objeto | NFS-e a ser substituída. | [Tipos de atividade](./tipos-de-atividade.md) |
| `deduction` | objeto | Deduções/reduções da base de cálculo do ISSQN. | — |
| `benefit` | objeto | Benefício municipal aplicado à base do ISSQN. | — |
| `suspension` | objeto | Suspensão da exigibilidade do ISSQN. | [ISS e local](./local-de-prestacao.md) |

## Partes adicionais

| Campo | Tipo | Descrição |
|---|---|---|
| `intermediary` | objeto | Intermediário do serviço. |
| `recipient` | objeto | Destinatário (quando diferente do tomador). |

## Tributos aproximados e informações adicionais

| Campo | Tipo | Descrição |
|---|---|---|
| `approximateTax` | objeto | Tributos aproximados (fonte + alíquota). |
| `approximateTotals` | objeto | Totais aproximados dos tributos (Lei 12.741/2012). |
| `additionalInformation` | string | Informações adicionais (texto, máx. 500 caracteres). |
| `additionalInformationGroup` | objeto | Grupo de informações adicionais. |
| `serviceAmountDetails` | objeto | Informações adicionais de tributação do serviço. |

## Veja também

- [Matriz de cenários de emissão](./matriz-de-cenarios.md)
- [Cenários de erro 400 na emissão](../erros-e-status/cenarios-de-badrequest-na-emissao.md)

---

## Emissão de NFS-e com IBS/CBS (Reforma Tributária) - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/cenarios-reforma-tributaria-ibs-cbs/index.md

# Emissão de NFS-e com IBS/CBS (Reforma Tributária)

O grupo `ibsCbs` carrega os tributos da Reforma Tributária. `classCode` e `operationIndicator` têm exatamente 6 dígitos.

Há **duas formas** de emitir com IBS/CBS: enviar apenas a **classificação da operação** e deixar a plataforma calcular base e valores (cálculo automático), ou enviar o **grupo completo com valores** calculados no seu sistema.

:::warning Envie o grupo completo ou apenas a classificação — nunca meio-termo
Se o grupo `ibsCbs` vier **sem os valores** (`amount`), a plataforma calcula e preenche base, alíquotas e valores — inclusive **sobrescrevendo alíquotas** que você tenha enviado. Para que os seus valores prevaleçam, envie o grupo **completo** (base, alíquotas e valores). Envios parciais têm os campos de valor recalculados.
:::

### IBS/CBS com cálculo automático (payload mínimo)

Nas prefeituras em que a plataforma opera o **cálculo automático de IBS/CBS**, basta classificar a operação: `classCode` e `operationIndicator` (com o `nbsCode` do serviço). A base de cálculo, as alíquotas, os valores e as alíquotas efetivas são calculados e preenchidos automaticamente na nota. `situationCode` (CST) é opcional — quando omitido, é derivado do `classCode`. É o padrão adotado pela maioria dos emissores.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "nbsCode": "101010100",
  "ibsCbs": {
    "operationIndicator": "050101",
    "classCode": "000001"
  }
}
```

:::note
A disponibilidade do cálculo automático depende do provedor da prefeitura. Se a nota for rejeitada com erro de base de cálculo do IBS/CBS (ex.: E1530), a prefeitura ainda exige os valores no payload — use o cenário completo abaixo.
:::

### IBS/CBS regime geral (com valores)

Grupo `ibsCbs` completo com `ibs` (estadual+municipal) e `cbs`. Use quando os tributos são calculados no **seu** sistema e devem prevalecer, ou quando a prefeitura não opera com o cálculo automático.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "nbsCode": "101010100",
  "ibsCbs": {
    "purpose": "regular",
    "operationIndicator": "050101",
    "situationCode": "000",
    "classCode": "000001",
    "basis": 1000.0,
    "ibs": {
      "totalAmount": 20.0,
      "state": {
        "rate": 0.1,
        "effectiveRate": 0.1,
        "amount": 10.0
      },
      "municipal": {
        "rate": 0.1,
        "effectiveRate": 0.1,
        "amount": 10.0
      }
    },
    "cbs": {
      "rate": 0.088,
      "effectiveRate": 0.088,
      "amount": 88.0
    }
  }
}
```

### IBS/CBS compra governamental

Grupo `governmentPurchase` para operações com entes públicos.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "nbsCode": "101010100",
  "ibsCbs": {
    "operationIndicator": "050101",
    "classCode": "000001",
    "basis": 1000.0,
    "governmentPurchase": {
      "entityType": "State",
      "ibs": {
        "totalAmount": 20.0,
        "state": {
          "rate": 0.1,
          "amount": 10.0
        },
        "municipal": {
          "rate": 0.1,
          "amount": 10.0
        }
      },
      "cbs": {
        "rate": 0.088,
        "amount": 88.0
      }
    }
  }
}
```

## Veja também

- [Matriz de cenários de emissão](./matriz-de-cenarios.md)

---

## Emissão de NFS-e com retenções - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/cenarios-retencoes/index.md

# Emissão de NFS-e com retenções

Retenções via campos `*AmountWithheld` (sempre ≥ 0).

### Retenção de IRRF

`irAmountWithheld` — IR retido na fonte pelo tomador.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "irAmountWithheld": 15.0
}
```

### ISS retido pelo tomador

`issAmountWithheld` + `retentionType=withheldByBuyer`.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "issAmountWithheld": 50.0,
  "retentionType": "withheldByBuyer"
}
```

### Retenção de PIS/COFINS/CSLL

Retenção conjunta dos três tributos federais.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "pisAmountWithheld": 6.5,
  "cofinsAmountWithheld": 30.0,
  "csllAmountWithheld": 10.0
}
```

### Retenção de INSS

`inssAmountWithheld` — cessão de mão de obra/empreitada.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "inssAmountWithheld": 110.0
}
```

### Retenção plena (ISS + federais)

Todas as retenções juntas — tomador grande / órgão público.

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "issAmountWithheld": 50.0,
  "retentionType": "withheldByBuyer",
  "irAmountWithheld": 15.0,
  "pisAmountWithheld": 6.5,
  "cofinsAmountWithheld": 30.0,
  "csllAmountWithheld": 10.0,
  "inssAmountWithheld": 110.0
}
```

## Veja também

- [Matriz de cenários de emissão](./matriz-de-cenarios.md)

---

## Emissão de NFS-e por tipo de atividade - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/cenarios-tipos-de-atividade/index.md

# Emissão de NFS-e por tipo de atividade

Grupos específicos por tipo de serviço — inclua apenas quando aplicável.

### Evento

Grupo `activityEvent` (nome, datas, endereço do evento).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "taxationType": "Free",
  "activityEvent": {
    "name": "Show Musical 2026",
    "code": "EVT2026",
    "beginOn": "2026-06-01",
    "endOn": "2026-06-02",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Exemplo",
      "number": "1000",
      "district": "Centro",
      "city": {
        "code": "3304557",
        "name": "Rio de Janeiro"
      },
      "state": "RJ"
    }
  }
}
```

### Construção civil

Grupo `construction` (inscrição imobiliária, `workId` CNO, `encapsulationNumber`, endereço da obra).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "construction": {
    "propertyFiscalRegistration": "123456789",
    "workId": {
      "scheme": "CNO",
      "value": "12345678901234"
    },
    "encapsulationNumber": "123456789012",
    "siteAddress": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Exemplo",
      "number": "1000",
      "district": "Centro",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  }
}
```

### Locação

Grupo `lease` (categoria, objeto, extensão).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "lease": {
    "category": "Lease",
    "objectType": "Road",
    "totalLength": 15.5
  }
}
```

### Comércio exterior

Grupo `foreignTrade` (tomador no exterior). Veja também [Cliente no exterior](./cliente-exterior.md).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "GLOBAL TECH CONSULTING INC",
    "federalTaxNumber": 0,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "USA",
      "postalCode": "10001",
      "street": "5th Avenue",
      "number": "100",
      "district": "Manhattan",
      "city": {
        "name": "New York"
      },
      "state": "NY"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "taxationType": "Export",
  "foreignTrade": {
    "serviceMode": "CrossBorder",
    "relationShip": "NoLink",
    "currency": "USD",
    "serviceAmountInCurrency": 200.0,
    "supportMechanismProvider": "None",
    "supportMechanismReceiver": "None",
    "temporaryGoods": "None",
    "mdicDelivery": false
  }
}
```

### Substituição / nota referenciada

Grupo `referenceSubstitution` (chave da NFS-e substituída + motivo).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "referenceSubstitution": {
    "id": "NFSE11112222333344445555666677778888999900001111",
    "reason": "Correção de preenchimento"
  }
}
```

### Intermediário

Grupo `intermediary` + `retentionType=withheldByIntermediary` (responsabilidade do intermediário).

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "contato@exemplo.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "intermediary": {
    "name": "INTERMEDIARIO EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181
  },
  "retentionType": "withheldByIntermediary",
  "issAmountWithheld": 50.0
}
```

## Veja também

- [Matriz de cenários de emissão](./matriz-de-cenarios.md)

---

## Como saber se sua nota fiscal de serviço foi emitida pela API - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/como-saber-se-sua-nota-fiscal-de-servico-foi-emitida-pela-api/index.md

# Como avaliar se a sua nota fisca de serviço foi emitida a partir dos retornos da API

### Os campos do json da nota que se relacionam com a condição de nota fiscal de serviço emitida

O json de uma nota que já foi processada na NFE.io possui alguns campos que combinados expressam ou não a emissão de uma nota fiscal.

Na tabela abaixo são descritos quais são os campos do json que contém os dados da nota, bem como o significado de cada um desses campos.

| Campo na API | Significado do campo                                                                       |
| ------------ | ------------------------------------------------------------------------------------------ |
| status       | Status final da nota. Ele representa em qual etapa final a nota se encontra                |
| flowStatus   | Indica em qual estágio do processamento da nota se encontra.                               |
| flowMessage  | Mensagem que indica o motivo pelo qual a nota se encontra no status definido no flowStatus |

Dos três campos apresentados acima, existem dois que possuem valores pré estabelecidos para eles. Ou seja, ambos possuem como parâmetros de retorno um item de uma lista que possui valores já determinados. O `status` e o `flowStatus` são esses campos.

O campo `flowMessage` é uma string com uma mensagem de reporte do evento final da nota.

#### Campo `status`

O campo `status` é uma lista no formato de `Enum` e possui cinco possibilidades de retorno. Abaixo segue uma tabela que indica quais são os retornos no formato de string. Como se trata de um `Enum`, há um número correspondente ao valor da string. Esse último valor é apresentado na segunda coluna. Já a última coluna indica com detalhes o que significa cada um dos tipos de retorno da API.  

| Retorno do campo | Número correspondente ao retorno (formato Enum) | Descrição do campo                                                          |
| ---------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
| _Error_          | \-1                                             | Nota não conseguiu concluir com sucesso todos os estágios de processamento. |
| _None_           | 0                                               | Nota não iniciou o processo de emissão da nota.                             |
| _Created_        | 1                                               | Nota em processo de emissão.                                                |
| _Issued_         | 2                                               | Nota conseguiu concluir com sucesso todos os estágios de processamento.     |
| _Cancelled_      | 3                                               | Nota cancelada.                                                             |

#### Campo `flowStatus`

O campo `flowStatus` também é uma lista no formato de `Enum` e possui onze possibilidades de retorno. Como na tabela acima, são identificados na primeira coluna o valor em string, na segunda coluna o número correspondente ao campo de string e na terceira coluna um detalhamento do que o retorno significa.

| Retorno do campo         | Número correspondente ao retorno (formato Enum) | Descrição do campo                                                                            |
| ------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
| _CancelFailed_           | \-2                                             | Nota não foi cancelada com sucesso                                                            |
| _IssueFailed_            | \-1                                             | Emissão da nota sem sucesso                                                                   |
| _Issued_                 | 1                                               | Nota emitida                                                                                  |
| _Cancelled_              | 2                                               | Nota cancelada                                                                                |
| _PullFromCityHall_       | 3                                               |                                                                                               |
| _WaitingCalculateTaxes_  | 10                                              | Calculando impostos da nota                                                                   |
| _WaitingDefineRpsNumber_ | 11                                              | Definindo número de RPS da nota                                                               |
| _WaitingSend_            | 12                                              | Nota enviada para emissão na prefeitura e aguardando confirmação de recebimento da mesma      |
| _WaitingSendCancel_      | 13                                              | Nota enviada para cancelamento na prefeitura e aguardando confirmação de recebimento da mesma |
| _WaitingReturn_          | 14                                              | Aguardando retorno da prefeitura com confirmação de nota emitida                              |
| _WaitingDownload_        | 15                                              | Aguardando download do PDF da nota                                                            |

#### Campo `flowMessage`

Caso a nota não consiga concluir todos os estágios de processamento (ou seja, passar com sucesso por todas as etapas definidas no `flowStatus`), o campo `flowMessage` é preenchido com uma mensagem com detalhes sobre a falha na conclusão das etapas de processamento.

### Como saber se uma nota foi efetivamente emitida.

Somente o campo `status` não indica a emissão de nota. Esse campo expressa que houve falha em alguma das etapas do processamento da nota. E dependendo de qual estágio do `flowStatus`, a nota pode estar emitida. Dessa forma, para se considerar a emissão de uma nota, deve ser feita a análise de ambos os campos em conjunto.

Abaixo segue uma tabela que descreve alguns cenários onde há a combinação dos valores dos campos `status` e `flowStatus`. A partir do cruzamento desses dois dados, é possível inferir como a nota se encontra.

| status    | flowStatus   | Situação da nota            |
| --------- | ------------ | --------------------------- |
| Issued    | Issued       | Nota emitida com sucesso.   |
| Cancelled | Cancelled    | Nota cancelada com sucesso. |
| Issued    | CancelFailed | Nota com falha ao cancelar  |

Existe ainda um cenário que necessita de uma avaliação especial quanto a situção final da nota. Em raros os casos, é possível que a nota tenha sido emitida, contudo a disponibilização do PDF da mesma não é concluído. Por conta dessa situação, o processamento da nota não é completo, e consequentemente o status da nota está com a informação de "falha". Esse é um contexto onde é necessário utilizar a informação do campo `flowMessage`, além dos campos já apresentados acima para interpretar o estágio da nota.

Abaixo segue uma tabela expressando a combinação dos campos e a interpretação da combinação de todos eles.

| status | flowStatus  | flowMessage                           | Situação da nota                                       |
| ------ | ----------- | ------------------------------------- | ------------------------------------------------------ |
| Issued | IssueFailed | "max retry reached on download stage" | Nota emitida. Porém o PDF da nota não está disponivel. |

Como é possível observar, apesar do `flowStatus` representar a informação de falha em uma etapa do processamento, a nota foi emitida. Para esse caso, o perigo de se interpretar a falha na nota é o de induzir o prestador de serviço a emitir uma nova nota. Ou seja, gerar duplicação de uma informação fiscal. Caso esse cenário seja vislumbrado, você pode entrar em contato com a NFE.io que nós reprocessamos a etapa de disponibilização do PDF da nota.


[1]: #Como%5Favaliar%5Fse%5Fa%5Fsua%5Fnota%5Ffisca%5Fde%5Fservico%5Ffoi%5Femitida%5Fa%5Fpartir%5Fdos%5Fretornos%5Fda%5FAPI
[2]: #Os%5Fcampos%5Fdo%5Fjson%5Fda%5Fnota%5Fque%5Fse%5Frelacionam%5Fcom%5Fa%5Fcondicao%5Fde%5Fnota%5Ffiscal%5Fde%5Fservico%5Femitida
[3]: #Campo%5Fstatus
[4]: #Campo%5FflowStatus
[5]: #Campo%5FflowMessage
[6]: #Como%5Fsaber%5Fse%5Fuma%5Fnota%5Ffoi%5Fefetivamente%5Femitida

---

## Dúvidas na Integração da Nota Fiscal de Serviço - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/index.md

# Dúvidas na Integração da Nota Fiscal de Serviço (NFS-e)

Nesta seção, iremos responder algumas perguntas frequentes em relação às **dúvidas** no momento da integração com nossa API de Notas Fiscais de Serviço. Caso não encontre uma resposta para sua dúvida, fique à vontade para [entrar em contato](https://nfe.io/#contato) e enviar sua pergunta.

## Quais os campos obrigatórios para emissão das notas fiscais?

Essa é uma das dúvidas recorrentes em nossa plataforma, pois existem alguns casos de uso no momento de realizar a emissão de uma Nota Fiscal de Serviço, que dependendo do cenário os campos a serem informados podem variar. Abaixo estão listados os cenários mais comuns:

* **[Cenário 1: Com cálculo automático de impostos](./cenarios-de-emissao/calculo-automatico-impostos)** — Nossa plataforma será responsável por identificar os detalhes tributários e calcular os valores dos impostos a serem enviados para a prefeitura no processamento da nota fiscal.
* **[Cenário 2: Com cálculo manual de impostos](./cenarios-de-emissao/calculo-manual-impostos)** — Você tem todo o controle sobre os detalhes tributários e valores dos impostos a serem enviados para a prefeitura no processamento da nota fiscal.
* **[Cenário 3: Com cliente domiciliado fora do Brasil](./cenarios-de-emissao/cliente-exterior)** — Quando a empresa que vai emitir a nota fiscal (prestador do serviço) está vendendo algum serviço/produto para um cliente que está domiciliado fora do Brasil.
* **[Cenário 4: Com cliente não identificado](./cenarios-de-emissao/cliente-nao-identificado)** — Quando a empresa que vai emitir a nota fiscal (prestador do serviço) está vendendo algum serviço/produto para um cliente que não foi possível ser identificado no momento da venda.
* **[Cenário 5: Empresa com tipo de tributação diferenciada](#cenário-5-empresa-com-tipo-de-tributação-diferenciada)** — Quando a empresa que vai emitir a nota fiscal (prestador do serviço) e o tipo da tributação não segue o padrão "Dentro do Município".

---

## Cenário 5: Empresa com tipo de tributação diferenciada

Em alguns cenários as empresas que emitem as notas fiscais de serviços e o tipo da tributação não segue o padrão "Dentro do Município", essa diferenciação aparece junto com a necessidade de informar para a prefeitura que ela possui alguma isenção, imunidade, seja por uma lei ou por um processo judicial.

Para qualquer um desses casos nossa plataforma, conta com o campo Tipo da tributação (`taxationType`) e com ele é possível informar qualquer uma das opções:

| Valor | Descrição |
|-------|-----------|
| `None` | Nenhum |
| `WithinCity` | Dentro do município |
| `OutsideCity` | Fora do município |
| `Export` | Exportação |
| `Free` | Livre |
| `Immune` | Imune |
| `SuspendedCourtDecision` | Suspenso por decisão judicial |
| `SuspendedAdministrativeProcedure` | Suspenso por processo administrativo |
| `OutsideCityFree` | Livre e Fora do município |
| `OutsideCityImmune` | Imune e Fora do município |
| `OutsideCitySuspended` | Suspenso por decisão judicial e Fora do município |
| `OutsideCitySuspendedAdministrativeProcedure` | Suspenso por processo administrativo e Fora do município |

Segue abaixo um exemplo de JSON para emissão com imunidade:

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "Banco do Brasil SA",
    "federalTaxNumber": 191,
    "municipalTaxNumber": null,
    "email": "joao.silva@emaildobancodobrasil.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01430-000",
      "street": "Avenida Brasil",
      "number": "418",
      "additionalInformation": "ANDAR 1",
      "district": "Jardins",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "taxationType": "Immune",
  "cityServiceCode": "0101",
  "description": "Descrição do serviço prestado",
  "servicesAmount": 1000.00
}
```

:::info

Para detalhes sobre a emissão com **exigibilidade do ISS suspensa** (tipos `SuspendedCourtDecision` e `SuspendedAdministrativeProcedure`), consulte a documentação específica: [Exigibilidade do ISS Suspensa](/docs/documentacao/nota-fiscal-servico-eletronica/emissor-nacional/exemplos-de-emissao/exigibilidade-iss-suspensa).

:::

---

## Cenários de erro 400 (BadRequest) na emissão de NFS-e

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/erros-e-status/cenarios-de-badrequest-na-emissao/index.md

# Cenários de erro 400 (BadRequest) na emissão de NFS-e

Esta página lista os cenários em que a API de NFS-e responde **HTTP 400 (BadRequest)** ao emitir uma nota ou ao cancelá-la. Um 400 significa que a requisição foi rejeitada por **validação de payload** ou por **regra de negócio** — antes de a nota ser enviada à prefeitura.

Para a visão geral de todos os status HTTP (401, 408, 500, 503, 504), consulte [Tipos de retorno de status das requisições HTTPS](./tipos-de-retorno-de-status-das-requisicoes-https.md). Para diagnóstico passo a passo por sintoma, consulte [Solução de erros 400 na emissão de NFS-e](./solucao-de-erros-400-na-emissao.md).

## Como interpretar o corpo do erro 400

Existem **dois tipos** de erro 400, com corpos diferentes:

### Validação de formato (desserialização do JSON)

Quando o corpo enviado não pode ser interpretado — JSON malformado ou tipo incompatível (por exemplo, enviar `federalTaxNumber` ou `servicesAmount` como texto não numérico) — a API responde 400 com um corpo **ProblemDetails** (JSON estruturado), antes de qualquer regra de negócio. As chaves de `errors` são o caminho do campo no JSON (`$.campo`):

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "$.borrower.federalTaxNumber": [
      "The JSON value could not be converted to System.Int64. Path: $.borrower.federalTaxNumber | LineNumber: 0 | BytePositionInLine: 736."
    ]
  },
  "traceId": "00-<trace-id>-<span-id>-00"
}
```

### Regras de negócio (validação e estado)

Os cenários das tabelas abaixo retornam um corpo de **texto simples**, em uma destas formas:

- **Mensagem única** — uma frase descrevendo a regra violada. Exemplo: `Municipal tax is not allowed to issue invoice`.
- **Lista de mensagens** — quando vários campos falham na mesma requisição, as mensagens vêm concatenadas (uma por regra violada).
- **Sem corpo** — alguns cenários retornam 400 com corpo vazio. Nesses casos, identifique a causa pela operação e pelo contexto da requisição (ver coluna "Mensagem retornada" marcada como _sem corpo_).

:::note
As mensagens de negócio são retornadas em inglês, exatamente como nas tabelas abaixo. Trate-as como literais ao exibir para o usuário final ou ao casar por texto em automações.
:::

## Validação do payload de emissão

Disparados ao validar o corpo do `POST /v1/companies/{companyId}/serviceinvoices`. Quando mais de uma regra falha, as mensagens são agregadas em uma única resposta.

| Campo / regra | Condição que dispara o 400 | Mensagem retornada | Como evitar |
|---|---|---|---|
| `Body` | corpo da requisição nulo | `Body can not be null` | Envie um corpo JSON válido |
| `cityServiceCode` | nulo ou vazio | `cityServiceCode can not be null or empty` | Informe o código de serviço municipal |
| `description` | nula ou vazia | `description can not be null or empty` | Informe a descrição do serviço |
| `servicesAmount` | `< 0` | `servicesAmount can not be less than 0.00` | Use valor de serviço `>= 0` |
| `rpsSerialNumber` | informado com comprimento 0 | `rpsSerialNumber can not be less than zero` | Omita o campo ou informe uma série não vazia |
| `rpsNumber` | informado `<= 0` | `rpsNumber can not be less than or equal zero` | Use número de RPS `> 0` |
| `issRate` | `< 0` | `issRate can not be less than 0.00 (0%)` | Use alíquota entre 0% e 5% |
| `issRate` | `> 0,05` | `issRate can not be more than 0.05 (5%)` | Use alíquota `<= 0.05` (5%) |
| `deductionsAmount` | `< 0` | `deductionsAmount can not be less than zero` | Use valor `>= 0` |
| `discountConditionedAmount` | `< 0` | `discountConditionedAmount can not be less than zero` | Use valor `>= 0` |
| `discountUnconditionedAmount` | `< 0` | `discountUnconditionedAmount can not be less than zero` | Use valor `>= 0` |
| `irAmountWithheld` | `< 0` | `irAmountWithheld can not be less than zero` | Use valor `>= 0` |
| `pisAmountWithheld` | `< 0` | `pisAmountWithheld can not be less than zero` | Use valor `>= 0` |
| `cofinsAmountWithheld` | `< 0` | `cofinsAmountWithheld can not be less than zero` | Use valor `>= 0` |
| `csllAmountWithheld` | `< 0` | `csllAmountWithheld can not be less than zero` | Use valor `>= 0` |
| `inssAmountWithheld` | `< 0` | `inssAmountWithheld can not be less than zero` | Use valor `>= 0` |
| `issAmountWithheld` | `< 0` | `issAmountWithheld can not be less than zero` | Use valor `>= 0` |
| `othersAmountWithheld` | `< 0` | `othersAmountWithheld can not be less than zero` | Use valor `>= 0` |
| `approximateTax.totalRate` | `< 0` | `approximateTax.TotalRate can not be less than 0.00 (0%)` | Use percentual `>= 0` |
| `approximateTax.totalRate` | `> 99,99` | `approximateTax.TotalRate can not be more than 99.99 (99.99%)` | Use percentual `<= 99.99` |
| `ibsCbs.classCode` | informado e diferente de 6 dígitos | `ibsCbs.classCode must be exactly 6 digits` | Informe exatamente 6 dígitos |
| `ibsCbs.operationIndicator` | informado e diferente de 6 dígitos | `ibsCbs.operationIndicator must be exactly 6 digits` | Informe exatamente 6 dígitos |
| `construction.encapsulationNumber` | informado fora de 1 a 12 dígitos | `construction.encapsulationNumber must contain from 1 to 12 digits` | Informe de 1 a 12 dígitos |
| `additionalInformation` | comprimento `> 500` | `additionalInformation length must be less than 500 characters` | Limite o texto a 500 caracteres |
| `location.city` | `location` presente com `city` nulo | `location.city can not be null` | Informe a cidade do local da prestação |
| `location.city.code` | nulo ou vazio | `location.city.code can not be null or empty` | Informe o código IBGE da cidade |
| `location.city.code` | diferente de 7 dígitos | `location.city.code must be a valid IBGE city code` | Use o código IBGE de 7 dígitos |
| `location.city.name` | nula ou vazia | `location.city.name can not be null or empty` | Informe o nome da cidade |
| `location.state` | nula ou vazia | `location.state can not be null or empty` | Informe a UF |
| `location.state` | diferente de 2 caracteres | `location.state must be a valid ISO 3166-2 code, samples (SP, RJ, AC)` | Use a sigla da UF com 2 letras |
| `borrower.name` | comprimento `> 115` | `borrower.name length must be less than 115 characters` | Limite o nome a 115 caracteres |
| `borrower.federalTaxNumber` | tomador no Brasil sem CPF nem CNPJ válido | `borrower.federalTaxNumber borrower federal tax number is not valid` | Informe CPF ou CNPJ válido |
| `borrower.federalTaxNumber` | tipo `NaturalPerson` com CPF inválido | `borrower.federalTaxNumber is not valid for natural person` | Use CPF válido para pessoa física |
| `borrower.federalTaxNumber` | tipo `LegalEntity` com CNPJ inválido | `borrower.federalTaxNumber is not valid for legal person` | Use CNPJ válido para pessoa jurídica |
| `borrower.phoneNumber` | informado com menos de 7 dígitos | `borrower.phoneNumber can not be less than 7 digits` | Use telefone com 7 a 19 dígitos |
| `borrower.phoneNumber` | informado com 20 dígitos ou mais | `borrower.phoneNumber can not be longer than 20 digits` | Use telefone com no máximo 19 dígitos |

:::tip
Tomador estrangeiro (`borrower.address.country` diferente de `BRA`) pula a validação de CPF/CNPJ. Use o `country` correto para evitar rejeição indevida do documento fiscal.
:::

:::note
A ausência do bloco `borrower` **não** retorna 400 na emissão. Ainda assim, informe o tomador: ele é necessário para a nota ser concluída — sem ele, a validação ocorre apenas adiante (consulta da nota/prefeitura).
:::

### Endereço do tomador (quando `country` = `BRA`)

Disparados por `ValidateAddress`. Um endereço totalmente vazio é aceito; ao informar qualquer campo, os demais passam a ser exigidos.

| Campo / regra | Condição que dispara o 400 | Mensagem retornada | Como evitar |
|---|---|---|---|
| `borrower.address.country` | código fora da tabela ISO 3166-1 | `borrower.address.country must be a valid ISO 3166-1 code, samples (BRA, ARG, COL)` | Use o código de país de 3 letras |
| `borrower.address.postalCode` | nulo ou vazio | `borrower.address.postalCode can not be null or empty` | Informe o CEP |
| `borrower.address.street` | nulo ou vazio | `borrower.address.street can not be null or empty` | Informe o logradouro |
| `borrower.address.city` | nula | `borrower.address.city can not be null` | Informe a cidade |
| `borrower.address.state` | nula ou vazia | `borrower.address.state can not be null or empty` | Informe a UF |
| `borrower.address.state` | diferente de 2 caracteres ou com espaço | `borrower.address.state must be a valid ISO 3166-2 code, samples (SP, RJ, AC)` | Use a sigla da UF com 2 letras |
| `borrower.address.city.code/name` | código **ou** nome da cidade vazio | `borrower.address.city.code or borrower.address.city.name can not be null or empty` | Informe código IBGE e nome |
| `borrower.address.city.code` | diferente de 7 dígitos | `borrower.address.city.code must be a valid IBGE city code` | Use o código IBGE de 7 dígitos |
| `borrower.address.state` | UF inexistente na base | `borrower.address.state is not a valid state code` | Use uma UF válida |
| `borrower.address.city.code` | cidade inexistente na base | `borrower.address.city.code is not a valid city code or city` | Use um código IBGE existente |
| `borrower.address.city.code` + `state` | UF não corresponde ao prefixo do código IBGE | `borrower.address.city.code and borrower.address.state aren't related. inform the correct state associated with correct city code` | Garanta que cidade e UF sejam coerentes |
| `borrower.address.state` | UF da base difere da informada | `borrower.address.state from DB differs of city state informed` | Garanta que cidade e UF sejam coerentes |

### Comércio exterior (`foreignTrade`)

Validados apenas quando o bloco `foreignTrade` é informado.

| Campo / regra | Condição que dispara o 400 | Mensagem retornada | Como evitar |
|---|---|---|---|
| `foreignTrade.serviceMode` | valor fora do enum | `foreignTrade.serviceMode is invalid` | Use um valor de enum válido |
| `foreignTrade.relationShip` | valor fora do enum | `foreignTrade.relationShip is invalid` | Use um valor de enum válido |
| `foreignTrade.currency` | nula ou vazia | `foreignTrade.currency can not be null or empty` | Informe a moeda |
| `foreignTrade.serviceAmountInCurrency` | nulo | `foreignTrade.serviceAmountInCurrency can not be null` | Informe o valor em moeda estrangeira |
| `foreignTrade.serviceAmountInCurrency` | `< 0` | `foreignTrade.serviceAmountInCurrency can not be less than zero` | Use valor `>= 0` |
| `foreignTrade.supportMechanismProvider` | valor fora do enum | `foreignTrade.supportMechanismProvider is invalid` | Use um valor de enum válido |
| `foreignTrade.supportMechanismReceiver` | valor fora do enum | `foreignTrade.supportMechanismReceiver is invalid` | Use um valor de enum válido |
| `foreignTrade.temporaryGoods` | valor fora do enum | `foreignTrade.temporaryGoods is invalid` | Use um valor de enum válido |
| `foreignTrade.mdicDelivery` | nulo | `foreignTrade.mdicDelivery can not be null` | Informe o indicador de entrega ao MDIC |

## Regras de emissão

Disparados de forma **síncrona** depois da validação do payload, no `POST /v1/companies/{companyId}/serviceinvoices`. Quando a mensagem é _sem corpo_, identifique a causa pelo contexto da empresa.

| Cenário | Condição que dispara o 400 | Mensagem retornada |
|---|---|---|
| Imposto municipal inativo | habilitação fiscal da empresa diferente de "ativa" (em produção) | `Municipal tax is not allowed to issue invoice` |
| Empresa inativa | empresa com status diferente de "ativa" | `company is not active` |
| RPS duplicado | já existe nota com o mesmo número de RPS | `service invoice with rps number ({rpsNumber}) already exists` |
| `externalId` duplicado | já existe nota com o mesmo `externalId` | `service invoice with external id ({externalId}) already exists` |
| Corpo da nota nulo | requisição sem dados da nota | _sem corpo_ |

:::warning
RPS ou `externalId` duplicado pode retornar **400** (e não 409). Não trate duplicidade assumindo um código de status fixo; verifique a mensagem retornada.
:::

:::note
Outras validações (certificado digital, habilitação por código de serviço, regravação) ocorrem **após o enfileiramento**, no processamento assíncrono da nota. Elas **não** retornam 400 na chamada de emissão — o resultado é entregue na consulta da nota, no `status` e na mensagem de fluxo.
:::

## Cancelamento da nota

| Operação | Condição que dispara o 400 | Mensagem retornada |
|---|---|---|
| Cancelamento (`DELETE /{id}`) | imposto municipal inativo (em produção) | `Municipal tax is not allowed to issue invoice` |

## Veja também

- [Tipos de retorno de status das requisições HTTPS](./tipos-de-retorno-de-status-das-requisicoes-https.md)
- [Solução de erros 400 na emissão de NFS-e](./solucao-de-erros-400-na-emissao.md)
- [Campos de autorização NFSe](../campos-de-autorizacao-nfse.md)

## Para IA / LLMs

- **Cobertura:** cenários que fazem a API de NFS-e responder HTTP 400 (BadRequest) na emissão e no cancelamento da nota.
- **Versão aplicável:** API de NFS-e v1. Regras de validação são da plataforma NFE.io; a rejeição da prefeitura é posterior e não gera 400.
- **Não parafrasear:** a coluna "Mensagem retornada" é **literal** (retornada em inglês pela API). Reproduza a mensagem original ao responder; a coluna "Como evitar" pode ser interpretada.
- **Corpo do erro:** dois tipos. Validação de formato/desserialização → ProblemDetails JSON (`{ "errors": {...}, "status": 400 }`). Regras de negócio → texto simples (mensagem única ou lista concatenada) ou **vazio**.
- **Síncrono vs assíncrono:** só os cenários listados retornam 400 na chamada. Certificado, código de serviço e regravação ocorrem no processamento assíncrono e não viram 400 — chegam na consulta da nota.
- **Pré-requisitos:** [Tipos de retorno de status das requisições HTTPS](./tipos-de-retorno-de-status-das-requisicoes-https.md).
- **Atualizado:** 2026-06-27 por revisão humana.

---

## Solução de erros 400 na emissão de NFS-e

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/erros-e-status/solucao-de-erros-400-na-emissao/index.md

# Solução de erros 400 na emissão de NFS-e

Este guia diagnostica os erros **HTTP 400 (BadRequest)** mais comuns ao emitir uma NFS-e ou operar sobre ela. Cada seção parte do sintoma e indica causa e ação. Para o catálogo completo com as mensagens literais, consulte [Cenários de erro 400 (BadRequest) na emissão de NFS-e](./cenarios-de-badrequest-na-emissao.md).

## Erros de validação do payload

### Mensagens sobre o tomador (`borrower`)

O tomador está ausente ou com dados inválidos — por exemplo `borrower can not be null` ou `borrower.federalTaxNumber borrower federal tax number is not valid`.

1. Garanta que o objeto `borrower` está presente no corpo.
2. Para tomador no Brasil, informe CPF ou CNPJ válido em `federalTaxNumber`.
3. Confira a coerência entre `type` (`NaturalPerson`/`LegalEntity`) e o documento.
4. Para tomador estrangeiro, use `borrower.address.country` diferente de `BRA` — a validação de CPF/CNPJ é dispensada.

### Mensagens sobre endereço ou cidade

Um campo de endereço foi informado de forma incompleta ou incoerente — por exemplo `borrower.address.city.code must be a valid IBGE city code`.

1. Use o código IBGE de 7 dígitos para a cidade.
2. Garanta que a UF (`state`) corresponde ao prefixo do código IBGE.
3. Ao preencher qualquer campo de endereço, preencha também CEP, logradouro, cidade e UF.

Para prevenir, valide CPF/CNPJ e mantenha uma base de cidades e UFs consistente com a tabela do IBGE.

## Erros de regra de emissão

### Empresa não habilitada

A mensagem `Municipal tax is not allowed to issue invoice` ou `company is not active` indica que a empresa não está apta a emitir.

1. Verifique se a empresa está ativa e habilitada na prefeitura.
2. Conclua o credenciamento municipal, se pendente.
3. Confirme que o ambiente da requisição corresponde à habilitação.

### RPS ou `externalId` duplicado

Já existe uma nota com o mesmo número de RPS ou `externalId`. Esse cenário pode retornar **400** (não apenas 409).

1. Consulte a nota existente antes de emitir novamente.
2. Use um novo número de RPS sequencial ou um `externalId` único por nota.

Para prevenir, controle o contador de RPS internamente e gere `externalId` idempotente por documento.

## Erros no cancelamento

O cancelamento (`DELETE /{id}`) pode retornar 400 quando a empresa não está habilitada a operar no município (mesma causa de `Municipal tax is not allowed to issue invoice`).

1. Verifique se a empresa está ativa e habilitada na prefeitura.
2. Conclua o credenciamento municipal, se ainda pendente.

## Veja também

- [Cenários de erro 400 (BadRequest) na emissão de NFS-e](./cenarios-de-badrequest-na-emissao.md)
- [Tipos de retorno de status das requisições HTTPS](./tipos-de-retorno-de-status-das-requisicoes-https.md)

---

## Tipos de retorno de status das requisições HTTPS

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/erros-e-status/tipos-de-retorno-de-status-das-requisicoes-https/index.md

# Tipos de retorno de status das requisições HTTPS

Durante o seu processo de emissão via API de nota fiscal de serviço, é possível que você se depare com uma série de tipos de retorno de status HTTP. 

Esses retornos são definidos por padrão, mas para cada um deles, talvez seja necessário algum tipo de ação com relação às emissões das suas notas.

Na tabela abaixo estão expressos alguns status com o seu respectivo significado, bem como um possível plano de ação.

| **Código status** | **Significado status**                                | **Significado do status para a NFE.io**                              | **Ação para solucionar possível pendência**                                                                                                                                                                                      |
| ----------------- | ----------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 202               | Requisição aceita                                     | Nota Fiscal de Serviços foi enviada com sucesso para fila de emissão | Nada a ser feito.                                                                                                                                                                                                                |
| 400               | Requisição errada                                     | Algum parametro informado não é válido                               | Verificar no seu json de envio se há algum dado que está sendo enviado está em desacordo com os padrões definidos na nossa [documentação][1].                                                                                    |
| 401               | Requisição não autorizada                             | API Key da conta não é valida                                        | Verificar se está utilizando a autenticação correta, bem como se você está apto para emissões de nota.                                                                                                                           |
| 408               | Requisição excedeu tempo limite                       | Tempo de reposta do servidor excedeu o limite (60s)                  | Buscar na [listagem de notas fiscais][2] se há o registro da nota que houve tentativa de emissão (buscar pelo CPF/CNPJ do tomador da nota).                                                                                      |
| 500               | Erro no processamento                                 | Serviço indisponível                                                 | Reenviar a requisição de emissão da nota que recebeu de retorno o erro.                                                                                                                                                          |
| 503               | Serviço indisponível                                  | Serviço da NFE.io está indisponível                                  | Entrar em contato com a NFE.io para confirmar o motivo da indisponibilidade.                                                                                                                                                     |
| 504               | Requisição excedeu o tempo na comunicação com Gateway | Não foi possível concluir a comunicação com o serviço da NFE.io      | Não há certeza se a nota foi ou não enviada para emissão. Nesse caso, recomenda-se que seja realizada a consulta da nota no portal da NFE.io através do CPF do tomador da nota para que seja constatado se houve ou não emissão. |

Após a avaliação da suituação encontrada por você, caso seja necessário, pode nos contatar pelo email suporte@nfe.io.


[1]: https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/
[2]: https://nfe.io/docs/documentacao/nossa-plataforma/nota-fiscal-servico/listar-notas-servico/

---

## Cálculo de impostos na NFE.io - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/impostos-e-classificacao/calculo-de-impostos/index.md

# Impostos incidentes na nota fiscal (NFS-e)

Nesta seção, será serão descritos os impostos que incidem na nota e como ele é calculado quando a nota é emitida na NFE.io.

Caso não encontre uma resposta para sua dúvida, fique à vontade para [entrar em contato][12] e enviar sua pergunta.

## Impostos Incidentes em Notas Fiscais de Serviços

Quando você lida com **notas fiscais de serviços**, existem vários impostos que podem incidir, dependendo do tipo de serviço, da localização e do porte da empresa. Aqui está um resumo dos impostos mais comuns:

### 1\. **ISS (Imposto sobre Serviços de Qualquer Natureza)**

* **O que é?** Um imposto municipal que se aplica à maioria dos serviços. A alíquota varia de 2% a 5%, dependendo da cidade e do tipo de serviço.
* **Quem paga?** Geralmente, o prestador de serviços, mas o custo pode ser repassado ao cliente.

### 2\. **PIS (Programa de Integração Social)**

* **O que é?** Um imposto federal que financia programas sociais para trabalhadores.
* **Alíquota:** Em geral, é 0,65% no **Regime Cumulativo** ou 1,65% no **Regime Não Cumulativo** (depende do regime tributário da empresa).
* **Quem paga?** O prestador de serviços.

### 3\. **COFINS (Contribuição para o Financiamento da Seguridade Social)**

* **O que é?** Um imposto federal que financia a seguridade social, saúde e assistência social.
* **Alíquota:** 3% no **Regime Cumulativo** ou 7,6% no **Regime Não Cumulativo**.
* **Quem paga?** O prestador de serviços.

### 4\. **CSLL (Contribuição Social sobre o Lucro Líquido)**

* **O que é?** Um tributo sobre o lucro da empresa para financiar a seguridade social.
* **Alíquota:** Geralmente 9% para a maioria das empresas e 20% para instituições financeiras.
* **Quem paga?** O prestador de serviços (especificamente sobre o lucro da empresa).

### 5\. **IRPJ (Imposto de Renda Pessoa Jurídica)**

* **O que é?** Imposto de renda sobre o lucro das empresas.
* **Alíquota:** Depende do regime tributário:  
   * **Lucro Presumido:** Tributado com base em um percentual do lucro presumido, geralmente em torno de 15% sobre a margem de lucro fixa.  
   * **Lucro Real:** Tributado sobre o lucro real, com alíquota base de 15%, mais um adicional de 10% sobre lucros acima de R$ 240.000 anuais.
* **Quem paga?** O prestador de serviços.

### 6\. **INSS (Instituto Nacional do Seguro Social)**

* **O que é?** Contribuição para a seguridade social, paga pelas empresas sobre os salários.
* **Alíquota:** Geralmente 20% sobre a folha de pagamento, mas para prestadores de serviço, existe a **Retenção de INSS**, onde 11% pode ser retido diretamente na nota fiscal.
* **Quem paga?** O empregador (prestador de serviços), mas parte pode ser retida na nota fiscal (se aplicável).

### 7\. **Retenção de IR (Imposto de Renda Retido na Fonte)**

* **O que é?** Imposto de renda que pode ser retido pelo cliente em determinados serviços, geralmente para pessoas físicas ou pequenos prestadores de serviços.
* **Alíquota:** Pode variar, mas geralmente é em torno de 1,5%.
* **Quem paga?** O imposto é retido pelo cliente e repassado ao governo em nome do prestador de serviços.

### Resumo em Tabela:

| **Imposto**        | **Tipo**  | **Quem Paga?**        | **Alíquota**                    |
| ------------------ | --------- | --------------------- | ------------------------------- |
| **ISS**            | Municipal | Prestador de Serviços | 2% - 5%                         |
| **PIS**            | Federal   | Prestador de Serviços | 0,65% ou 1,65%                  |
| **COFINS**         | Federal   | Prestador de Serviços | 3% ou 7,6%                      |
| **CSLL**           | Federal   | Prestador de Serviços | 9% (sobre o lucro)              |
| **IRPJ**           | Federal   | Prestador de Serviços | 15% (sobre o lucro)             |
| **INSS**           | Federal   | Empregador            | 20% sobre a folha ou 11% retido |
| **Retenção de IR** | Federal   | Retido pelo Cliente   | \~1,5%                          |

Esses impostos podem ser um pouco confusos, então é importante saber qual é o regime tributário da sua empresa (**Simples Nacional**, **Lucro Presumido** ou **Lucro Real**) para identificar quais impostos se aplicam. Se precisar de mais detalhes sobre algum imposto específico, é só avisar!

## Cálculo de impostos na NFe.io

O cálculo de impostos é feito a partir da combinação da informação da cidade onde o prestador de serviços está registrado com a informação do tipo de serviço prestado.

Com esses dois dados, uma base de dados é consultada e dela são trazidas as informações das alíquotas dos impostos relacionados às informações utilizadas na busca. Os dados retornados nessa busca são os seguintes:

* Código de Serviço da Cidade
* Código Federal
* Cnae Nacional
* ISS
* Descrição do serviço
* IR (Imposto a ser retido)
* PIS (Imposto a ser retido)
* COFINS (Imposto a ser retido)
* CSLL (Imposto a ser retido)
* INSS (Imposto a ser retido)
* ISS (Imposto a ser retido)

A partir desse conjunto de informações retornado, os impostos que incidem na nota fiscal são calculados.

Para o cálculo de impostos de uma nota o tipo de regime tributário da empresa e a sua cidade de registro são fatores de definirão como o imposto é calculado. Dessa forma, com a combinação do retorno das alíquotas com o tipo de regime da sua empresa, regras no nosso processamento são aplicadas para a definição dos impostos que incidem na nota. 

Como regras gerais na aplicação de impostos para cenários em que o cliente é do regime do Lucro Real ou Lucro Presumido, os impostos retidos incidem na nota fiscal. Para os demais cenários, esses tipos de impostos não são aplicados. Com relação ao município onde a empresa reside, cenários específicos são aplicados para as empresas que retêm impostos.

Caso tenha alguma dúvida de como o imposto é aplicado para o seu cenário, entre em contato conosco para que possamos esclarecer.


[1]: #Impostos%5Fincidentes%5Fna%5Fnota%5Ffiscal%5FNFS-e
[2]: #Impostos%5FIncidentes%5Fem%5FNotas%5FFiscais%5Fde%5FServicos
[3]: #1%5FISS%5FImposto%5Fsobre%5FServicos%5Fde%5FQualquer%5FNatureza
[4]: #2%5FPIS%5FPrograma%5Fde%5FIntegracao%5FSocial
[5]: #3%5FCOFINS%5FContribuicao%5Fpara%5Fo%5FFinanciamento%5Fda%5FSeguridade%5FSocial
[6]: #4%5FCSLL%5FContribuicao%5FSocial%5Fsobre%5Fo%5FLucro%5FLiquido
[7]: #5%5FIRPJ%5FImposto%5Fde%5FRenda%5FPessoa%5FJuridica
[8]: #6%5FINSS%5FInstituto%5FNacional%5Fdo%5FSeguro%5FSocial
[9]: #7%5FRetencao%5Fde%5FIR%5FImposto%5Fde%5FRenda%5FRetido%5Fna%5FFonte
[10]: #Resumo%5Fem%5FTabela
[11]: #Calculo%5Fde%5Fimpostos%5Fna%5FNFeio
[12]: https://nfe.io/#contato

---

## CNAE e item da LC116 (código de serviço) - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/impostos-e-classificacao/cnae-e-item-da-lc116/index.md

# CNAE e item da LC116 (código de serviço)

Algumas prefeituras validam o **código CNAE** contra o **item da Lista de Serviços da LC 116/2003** (o código de serviço). Esta página explica como esse vínculo é tratado no NFE.io.

## O NFE.io mapeia esse vínculo?

**Sim.** O NFE.io mantém um **catálogo de serviços e tributos por município** que correlaciona:

- o **código de serviço municipal** (`cityServiceCode`),
- o **item da LC 116** (`federalServiceCode`),
- o **CNAE** (`cnaeCode`), e
- as **alíquotas** de ISS e retenções.

Esse catálogo é a base do **cálculo automático de impostos**: ao emitir informando o município e o código de serviço, o NFE.io usa esse vínculo para determinar as alíquotas.

## Como isso funciona na emissão

Na emissão, o NFE.io **envia os códigos como você informar** (`cityServiceCode`, `federalServiceCode`, `cnaeCode`) — ele **não bloqueia** uma eventual divergência entre o CNAE e o item da LC 116.

**Quem valida o vínculo CNAE × LC 116 é a prefeitura**, no processamento da nota. Se os códigos forem incompatíveis para aquele município, a nota é **rejeitada pela prefeitura** — não é um erro do NFE.io.

## Recomendação

Para evitar rejeição:

- Use os códigos **conforme o catálogo do município** — o caminho mais simples é deixar o [cálculo automático de impostos](../cenarios-de-emissao/calculo-automatico-impostos.md) resolver as alíquotas a partir do `cityServiceCode`.
- Confira os campos de classificação na [Referência completa de campos](../cenarios-de-emissao/referencia-completa-de-campos.md).

## Veja também

- [Cálculo de impostos na NFE.io](./calculo-de-impostos-na-nfe.io.md)
- [Cenários de emissão de NFS-e](../cenarios-de-emissao/matriz-de-cenarios.md)

---

## Tipos de apuração de impostos federais e municipal

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/impostos-e-classificacao/tipos-de-apuracao-de-impostos-federais-e-municipal/index.md

# Definição na forma de Apuração dos Impostos Federais e Municipais

**Requisito**

* Caso queira definir a forma de apuração pela plataforma, é necessário [cadastrar uma empresa][7]

### Contexto

Na composição da nota fiscal de serviço, há a incidência de impostos federais (IRRF, COFINS, PIS e CSLL) e de um imposto municipal (ISS).

A forma de incidência dos impostos, tanto federais quanto municipal, pode variar conforme o regime tributário da empresa. Em termos gerais, o regime Simples Nacional simplifica e unifica a apuração dos tributos, o que impacta a forma de cálculo e pagamento tanto dos impostos federais quanto do ISS municipal. Dependendo do enquadramento da empresa, o Simples Nacional pode influenciar apenas os impostos federais, apenas o ISS, ambos os grupos de impostos ou, em alguns casos, nenhum deles.

Dentro do cenário onde pode haver algum tipo de influência nos impostos federais e/ou municipal, na NFE.io foram criados dois campos para que se defina qual o tipo de influência em cada um desses tipos de impostos.

### Como definir os campos de incidência dos impostos federais e municipal

Existem duas formas de definir os campos que irão definir o tipo de influência nos impostos federais e municipal.

Pela plataforma, os campos são descritos como "**_Determinação dos impostos pelo município_**" e "**_Determinação dos impostos pela federação_**". Para ambos os casos, as opções são: "**_Definido pelo Simples Nacional_**", "**_Padrão_**" e "**_Não informado_**".

* Definido pelo Simples Nacional: Os impostos serão calculados de acordo com as regras específicas do regime Simples Nacional.
* Padrão: Os impostos são calculados sem qualquer influência diferenciada, utilizando a forma de apuração padrão.
* Não informado: Nenhuma configuração foi especificada para o cálculo dos impostos.

Pela API, os campos para definição da forma de apuração dos impostos federais e municipal são "**_FederalTaxDetermination_**" e "**_MunicipalTaxDetermination_**". Para ambos os campos, a definição é a partir de uma propriedade do tipo _enum_ com as seguintes opções: **_NotInformed_**, **_Default_** e **_SimplesNacional_**.

#### Como definir os campos pela plataforma

1. Antes de conseguir definir a forma de apuração, é necessário [cadastrar uma empresa][7], como informado no requisito.
2. Após o cadastro, a primeira ação é alterar a empresa.

![](https://nfe.io/docs/static/docs/nota-fiscal-servico-e/Alterar-empresa.jpg)

1. Depois, selecione a opção do box "Dados Fiscais".

![](https://nfe.io/docs/static/docs/nota-fiscal-servico-e/Selecao-dados-fiscais-2.jpg)

1. Dentro do box de "Dados Fiscais", as opções para definir a forma do regime de apuração estão descritas no box "Dados de Impostos".

![](https://nfe.io/docs/static/docs/nota-fiscal-servico-e/Dados-de-impostos.jpg)

Nesse box, as opções "Determinação dos impostos pelo município" e "Determinação dos impostos pela federação" são as formas para definir como o regime de apuração da empresa irá influenciar na definição dos impostos federais e municipal.

1. Em ambos os boxes, as opções são as demonstradas abaixo.

![](https://nfe.io/docs/static/docs/nota-fiscal-servico-e/TIpos-de-preenchimento.jpg)

Como demonstrado, as três opções são "Não informado", "Padrão" e "Definido pelo Simples Nacional".

#### Como definir os campos pela API

Na API, ambos os campos estão dentro do objeto "**_Company_**"

```
{
  "companies": {
    "id": "xxx",
    "name": "XXX S.A.",
    "tradeName": "asdas",
    "federalTaxNumber": 11111111111111,
    "address": {
      "country": "",
      "postalCode": "11111-111",
      "street": "Avenida XXX",
      "number": "111",
      "district": "Barra XXX",
      "city": {
        "code": "4314902",
        "name": "Porto Alegre"
      },
      "state": "RS"
    },
    "taxRegime": "LucroReal",
    "specialTaxRegime": "Nenhum",
    "legalNature": "SociedadeAnonimaFechada",
    "economicActivities": [],
    "regionalTaxNumber": 11111111,
    "municipalTaxNumber": "11111111",
    "rpsSerialNumber": "IO",
    "rpsNumber": 10,
    "issRate": 0.0439,
    "environment": "Development",
    "fiscalStatus": "Active",
    "federalTaxDetermination": "NotInformed",
    "municipalTaxDetermination": "NotInformed",
    "certificate": {
      "thumbprint": "1111",
      "modifiedOn": "2022-04-20T17:11:31.940047+00:00",
      "expiresOn": "2022-12-03T13:05:23+00:00",
      "status": "Overdue"
    },
    "createdOn": "2019-03-01T14:14:41.5031368+00:00",
    "modifiedOn": "2024-06-27T14:52:04.4986016-03:00"
  }
}
```

Para alterar qualquer um dos campos, basta [criar uma empresa][8] ou [alterar uma empresa][9] como demonstrado no swagger utilizando o modelo do json descrito acima.

### Informações adicionais

Esses campos são definidos para atender, principalmente, o Emissor de NFSe Nacional. Caso sua prefeitura não exija a definição diferenciada dos impostos federais e municipal, não é preciso considerar o uso desses campos.

Caso tenha alguma dúvida, entre em contato por suporte@nfe.io.


[1]: #Definicao%5Fna%5Fforma%5Fde%5FApuracao%5Fdos%5FImpostos%5FFederais%5Fe%5FMunicipais
[2]: #Contexto
[3]: #Como%5Fdefinir%5Fos%5Fcampos%5Fde%5Fincidencia%5Fdos%5Fimpostos%5Ffederais%5Fe%5Fmunicipal
[4]: #Como%5Fdefinir%5Fos%5Fcampos%5Fpela%5Fplataforma
[5]: #Como%5Fdefinir%5Fos%5Fcampos%5Fpela%5FAPI
[6]: #Informacoes%5Fadicionais
[7]: https://nfe.io/docs/documentacao/nossa-plataforma/criar-empresa/
[8]: https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/#/Companies/Companies%5FPost
[9]: https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/#/Companies/Companies%5FPut

---

## Evento de cancelamento da NFS-e Nacional

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/emissor-nacional/evento-cancelamento/index.md

# Evento de cancelamento da NFS-e Nacional

No **Ambiente Nacional (ADN)** da NFS-e, cancelar uma nota não apaga o documento: gera um **novo documento fiscal**, o **evento de cancelamento `e110001`**. Esse evento tem XML próprio, vinculado à nota original pela chave de acesso, e comprova oficialmente que a nota foi cancelada.

<!-- ai-canonical: NFS-e: Nota Fiscal de Serviços eletronica municipal. Ambiente Nacional (ADN) e o padrao da Reforma Tributaria. NAO confundir com NF-e (produto) nem com provedores legados (ABRASF/Paulistana). -->

## Contexto

O cancelamento funciona de forma diferente conforme o padrão da prefeitura emissora.

Nos **provedores legados** (ABRASF, Paulistana, Curitiba e similares), o cancelamento devolve apenas uma **confirmação** da prefeitura — protocolo e data. Não existe um documento de cancelamento separado; a própria nota passa a constar como cancelada.

No **Ambiente Nacional**, o modelo segue o padrão da NF-e modelo 55: o cancelamento é um **evento fiscal autônomo**. Ele é registrado, autorizado e devolvido como um XML independente da emissão. A LC 214/2025 trata esse evento como o documento fiscal que dá validade jurídica ao cancelamento.

## Como funciona

O evento de cancelamento é um XML separado, com identidade própria, que aponta para a NFS-e original.

```mermaid
flowchart LR
    A[NFS-e emitida<br/>XML de emissão] -->|solicitação de cancelamento| B[Evento e110001<br/>XML de cancelamento]
    B -->|vinculado pela<br/>chave de acesso| A
    B --> C[Nota fica<br/>Cancelada]
```

Dois XMLs passam a existir para a mesma nota, sem que um sobrescreva o outro:

- **XML de emissão** — o documento original da nota (disponível assim que a nota é emitida).
- **XML do evento de cancelamento** — o comprovante fiscal do cancelamento (disponível só depois da nota ficar **Cancelada**).

Quando o Ambiente Nacional devolve o **retorno autorizado** do evento (`procEventoNFSe`), esse retorno é a versão de maior valor fiscal e tem prioridade sobre o request enviado.

## Disponibilidade

O XML do evento de cancelamento existe **apenas para notas do Ambiente Nacional**.

| Padrão da prefeitura | Gera XML de evento de cancelamento? |
|---|---|
| Ambiente Nacional (ADN) | Sim — evento `e110001` com XML próprio |
| Legados (ABRASF, Paulistana, etc.) | Não — apenas confirmação (protocolo + data) |

Além do padrão, vale o **momento**: o XML do evento só fica disponível depois que o cancelamento é concluído e a nota assume o status **Cancelada**. Antes disso — ou para provedores legados — o documento não existe.

## O XML do evento na prática

O XML do evento de cancelamento é um documento fiscal e deve ser guardado como tal.

- É **separado** do XML de emissão — um não substitui o outro. Guarde os dois.
- Tem o mesmo valor de comprovação fiscal que o XML de emissão e deve ser mantido pelo prazo legal mínimo de **5 anos**.
- Para integrações, ele é obtido por um **endpoint dedicado** da API — não vem no corpo da consulta da nota. Veja [Como obter o XML do evento de cancelamento](/docs/duvidas-frequentes/como-obter-xml-do-evento-de-cancelamento/).

## Para IA / LLMs

- **Cobertura:** evento de cancelamento `e110001` da NFS-e no Ambiente Nacional (ADN). Para o cancelamento em provedores legados (ABRASF/Paulistana), não há evento próprio — apenas confirmação.
- **Versão aplicável:** NFS-e API v1, Ambiente Nacional. Provedores legados têm comportamento diferente (sem XML de evento).
- **Não parafrasear:** o código do evento `e110001`; a regra de disponibilidade (somente Nacional e somente após status `Cancelled`).
- **Pré-requisitos:** [Tudo sobre Nota Fiscal Eletrônica](/docs/documentacao/conceitos/notas-fiscais/).
- **Fontes oficiais:** [Schemas oficiais NFS-e (gov.br)](https://www.gov.br/nfse/pt-br/documentacao/schemas).
- **Atualizado:** 2026-06-05 por revisão humana.

## Leituras relacionadas

- [Como obter o XML do evento de cancelamento](/docs/duvidas-frequentes/como-obter-xml-do-evento-de-cancelamento/)
- [Layout RTC da NFS-e — XML do Evento de Cancelamento](/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/#xml-do-evento-de-cancelamento-ambiente-nacional)
- [Referência da API REST — cancellation-xml](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-get-cancellation-xml)
- [Tudo sobre Nota Fiscal Eletrônica](/docs/documentacao/conceitos/notas-fiscais/)

---

## Emissão de NFS-e com Exigibilidade do ISS Suspensa - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/emissor-nacional/exemplos-de-emissao/exigibilidade-iss-suspensa/index.md

# Emissão de NFS-e com Exigibilidade do ISS Suspensa

Nesta seção, iremos explicar como emitir uma **Nota Fiscal de Serviço Eletrônica (NFS-e)** informando o cenário de **exigibilidade do ISS suspensa**. Caso não encontre uma resposta para sua dúvida, fique à vontade para [entrar em contato](https://nfe.io/#contato) e enviar sua pergunta.

## O que é a Exigibilidade do ISS Suspensa?

A **exigibilidade do ISS suspensa** ocorre quando há uma **decisão judicial** ou um **processo administrativo** que suspende temporariamente a cobrança do **Imposto Sobre Serviços (ISS)**. Isso significa que, enquanto a suspensão estiver vigente, o prestador de serviço não é obrigado a recolher o ISS, mesmo que o serviço seja tributável.

### Quando utilizar este cenário?

- **Decisão Judicial**: Quando existe uma **liminar** ou **decisão judicial** que suspende a cobrança do ISS para determinado serviço ou empresa.
- **Processo Administrativo**: Quando há um **processo administrativo** em andamento que resulta na suspensão da exigibilidade do imposto.

## Campos obrigatórios para emissão

Para emitir uma **nota fiscal com exigibilidade do ISS suspensa**, além dos campos básicos obrigatórios, você deve informar:

| Campo | Descrição | Obrigatório |
|-------|-----------|-------------|
| `taxationType` | Tipo de tributação indicando a suspensão | Sim |
| `suspension.processNumber` | Número do processo judicial ou administrativo (somente números) | Não* |

:::info

**Nota:** O campo `suspension.processNumber` é opcional na API, porém algumas prefeituras podem exigir o número do processo para validar a suspensão. Recomendamos informar sempre que disponível.

:::

## Valores disponíveis para Tipo de Tributação (taxationType)

| Valor | Código enviado à prefeitura | Descrição |
|-------|:---------------------------:|-----------|
| `SuspendedCourtDecision` | 1 | Suspenso por decisão judicial |
| `SuspendedAdministrativeProcedure` | 2 | Suspenso por processo administrativo |

---

## Cenário 1: ISS Suspenso por Decisão Judicial

Este cenário é utilizado quando existe uma decisão judicial (liminar, tutela antecipada, etc.) que determina a suspensão da cobrança do ISS.

### Exemplo de JSON

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "Empresa Cliente Ltda",
    "federalTaxNumber": 12345678000199,
    "municipalTaxNumber": null,
    "email": "contato@empresacliente.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01430-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "additionalInformation": "Sala 101",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "0101",
  "description": "Descrição do serviço prestado",
  "servicesAmount": 1000.00,
  "taxationType": "SuspendedCourtDecision",
  "suspension": {
    "processNumber": "12345678920248260100"
  }
}
```

### Observações importantes

- O campo `suspension.processNumber` deve conter **somente números** (caracteres não numéricos serão removidos automaticamente).
- Algumas prefeituras podem exigir o número do processo para validar a suspensão.

---

## Cenário 2: ISS Suspenso por Processo Administrativo

Este cenário é utilizado quando existe um processo administrativo que resulta na suspensão da exigibilidade do ISS.

### Exemplo de JSON

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "Empresa Cliente Ltda",
    "federalTaxNumber": 12345678000199,
    "municipalTaxNumber": null,
    "email": "contato@empresacliente.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01430-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "additionalInformation": "Sala 101",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "0101",
  "description": "Descrição do serviço prestado",
  "servicesAmount": 1000.00,
  "taxationType": "SuspendedAdministrativeProcedure",
  "suspension": {
    "processNumber": "2024001234"
  }
}
```

---

## Cenário 3: ISS Suspenso sem número de processo

Caso não possua o número do processo, é possível emitir a nota fiscal apenas com o tipo de tributação informado. Neste caso, o objeto `suspension` pode ser omitido ou enviado sem o `processNumber`.

### Exemplo de JSON

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "Empresa Cliente Ltda",
    "federalTaxNumber": 12345678000199,
    "municipalTaxNumber": null,
    "email": "contato@empresacliente.com.br",
    "address": {
      "country": "BRA",
      "postalCode": "01430-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "additionalInformation": "Sala 101",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "0101",
  "description": "Descrição do serviço prestado",
  "servicesAmount": 1000.00,
  "taxationType": "SuspendedCourtDecision"
}
```
:::warning

**Atenção:** Verifique com a prefeitura de destino se o número do processo é obrigatório antes de utilizar este cenário.

:::

---

## Emissão via Planilha

Também é possível emitir notas fiscais com exigibilidade do ISS suspensa utilizando nossa planilha de importação. Para isso, preencha os seguintes campos específicos para este cenário:

### Campos da Planilha para Suspensão do ISS

| Coluna da Planilha | Descrição | Valores Aceitos |
|--------------------|-----------|-----------------|
| `Tipo_Tributacao` | Tipo de tributação da nota fiscal | `SuspendedCourtDecision` ou `SuspendedAdministrativeProcedure` |
| `Suspensao_Motivo` | Motivo da suspensão do ISS | `Judicial` ou `Administrativo` |
| `Suspensao_Numero_Processo` | Número do processo (somente números) | Ex: `000000000002437346320108190001` |

### Exemplo de preenchimento

| Tipo_Tributacao | Suspensao_Motivo | Suspensao_Numero_Processo |
|-----------------|------------------|---------------------------|
| SuspendedCourtDecision | Judicial | 000000000002437346320108190001 |
| SuspendedAdministrativeProcedure | Administrativo | 2024001234 |

### Exemplo completo de linha na planilha

```
CPF_CNPJ: 9375025000144
Nome: Empresa Cliente Ltda
Email: contato@empresa.com.br
Valor: 1000,00
Codigo_Servico: 010501.001
... (demais campos do tomador e serviço)
Tipo_Tributacao: SuspendedCourtDecision
Suspensao_Motivo: Judicial
Suspensao_Numero_Processo: 000000000002437346320108190001
```

### Observações

- O campo `Suspensao_Numero_Processo` é opcional, mas recomendamos preencher sempre que disponível.
- Informe o número do processo **somente com números** (sem pontos, traços ou barras).
- O campo `Suspensao_Motivo` deve ser consistente com o `Tipo_Tributacao`:
  - `SuspendedCourtDecision` → `Suspensao_Motivo` = `Judicial`
  - `SuspendedAdministrativeProcedure` → `Suspensao_Motivo` = `Administrativo`

---

## Perguntas Frequentes (FAQ)

### É obrigatório informar o número do processo?

Não é obrigatório na API. O campo `suspension.processNumber` só será enviado à prefeitura se for preenchido. Porém, algumas prefeituras podem exigir o número do processo para validar a suspensão. Recomendamos sempre informar quando disponível.

### O número do processo pode conter caracteres especiais?

Você pode informar o número do processo com ou sem formatação (pontos, traços, barras). Nossa plataforma **remove automaticamente** todos os caracteres não numéricos antes de enviar para a prefeitura.

**Exemplos:**
- `1234567-89.2024.8.26.0100` → enviado como `12345678920248260100`
- `PA-2024/001234` → enviado como `2024001234`

### Posso usar cálculo automático de impostos com ISS suspenso?

Sim, porém o valor do ISS será calculado como **R$ 0,00** devido à suspensão da exigibilidade.

### O que acontece se eu não informar o campo `taxationType` corretamente?

A nota fiscal pode ser rejeitada pela prefeitura ou processada com tributação normal, gerando a cobrança do ISS indevidamente.

### Preciso enviar documentação comprobatória para a prefeitura?

Nossa plataforma realiza apenas o envio eletrônico da nota fiscal. A documentação comprobatória (decisão judicial, processo administrativo) deve ser mantida pela empresa para eventuais fiscalizações.

---

## Dúvidas adicionais

Caso tenha dúvidas específicas sobre a emissão de notas fiscais com exigibilidade do ISS suspensa, [entre em contato com nosso suporte](https://nfe.io/contato) ou consulte seu contador para orientações sobre o enquadramento correto da sua empresa.

---

**Relacionados:**
- [Dúvidas na Integração da NFS-e](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/)
- [Cálculo de Impostos na NFE.io](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/calculo-de-impostos)
- [Tipos de Tributação](/docs/documentacao/nota-fiscal-servico-eletronica/emissor-nacional/exemplos-de-emissao/)

---

## Primeiros Passos para integração de nota fiscal de serviço - NFE.io | Docs

Source: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/primeiros-passos/index.md

# Integração Nota Fiscal de Serviço - NFSe

Nesse documento você entenderá os primeiros passos para fazer a integração da **Nota Fiscal de Serviço Eletrônica (NFSe)**.

:::info[Estrutura nova de gerenciamento de empresa]
A partir da [unificação da API de Contribuintes (2026.1)](/docs/release-notes/2026-1-unificacao-api-contribuintes), habilitar uma empresa para emitir NFS-e exige **três recursos** combinados: a própria **Empresa** (`/v2/companies`), o **Certificado Digital** (`/v2/companies/{id}/certificates`) e a **Inscrição Municipal** (`/v2/companies/{id}/municipaltaxes`). Veja a [visão geral do Gerenciamento de Empresas](/docs/documentacao/gerenciamento-empresas/visao-geral) para entender a estrutura completa.
:::

> A Nota Fiscal de Serviço Eletrônica é um documento digital fiscal utilizado para registrar a prestação de serviços de uma empresa, conforme as regras da prefeitura do município onde o serviço foi prestado.

**Saiba mais:** [O que é nota fiscal eletrônica?](/docs/documentacao/conceitos/notas-fiscais)

### Ao final desse tutorial, você será capaz de:

[1. Cadastrar uma empresa](#1-criar-uma-empresa)\
[2. Fazer upload de um certificado digital](#2-enviar-certificado-digital)\
[3. Criar uma inscrição municipal](#3-criar-uma-inscrição-municipal)\
[4. Emitir uma nota fiscal de serviço](#4-emitir-uma-nota-fiscal-de-serviço)

### Próximos passos

[1. Consultar uma nota fiscal de serviço emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-id-get)\
[2. Consultar o XML de uma nota fiscal emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-get-document-xml)\
[3. Consultar o PDF da nota fiscal emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-get-document-pdf)

## Requisitos

* Empresa com CNPJ e CNAE de prestação de serviços
* Certificado digital A1 (arquivo .pfx)
* Integração via API REST, via Meio de Pagamento ou Planilha
* Verificar se a prefeitura é **atendida** pela NFE.io ([lista de prefeituras](/docs/prefeituras-integradas/))

## Tutorial

A partir deste momento, faremos uma explicação de como realizar a integração da Nota Fiscal de Serviço com a API da [NFE.io](https://nfe.io/).

**Veja mais sobre a** [Documentação da API de NFSe](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1)

Você pode realizar a importação da URL no Postman para ter todos os exemplos de requisição:

```json
https://www.postman.com/nfe-io/workspace/nfe-io-public-api-demos/collection/29654924-09b8c724-7d9a-4735-93a3-518cc135989d?action=share&creator=29654924&active-environment=29463388-d0c59007-e68a-45c8-8fb8-16b53cb58c11
```

Tutorial de como importar a URL no Postman [Clique aqui](/docs/documentacao/nota-fiscal-produto-eletronica/importar-colecao-postman)

- - -

## Primeiros passos

Antes de tudo, você precisará realizar um cadastro na nossa plataforma [app.nfe.io](https://app.nfe.io/) e pegar a chave de autorização da API.

> Devemos atentar para copiar a autorização referente a "Nota Fiscal"

**Veja como pegar a chave de autorização:** [Autenticação](/docs/documentacao/nossa-plataforma/chaves-de-autenticacao)

> **Lembre-se:** A chave deve ser adicionada em cada requisição na aba "Headers" com o campo `Authorization`.

- - -

## Ambiente: Testes ou Produção

A NFE.io oferece dois ambientes para emissão de NFS-e. O ambiente é configurado **na Inscrição Municipal** (campo `Environment`), não na empresa — uma mesma empresa pode ter IMs de cidades diferentes, cada uma com seu próprio ambiente.

| Recurso | Testes (`Development`) | Produção (`Production`) |
|---|---|---|
| **Inscrição Municipal** | Obrigatória, com `Environment: "Development"` | Obrigatória, com `Environment: "Production"` |
| **Certificado Digital** | ✅ **Opcional** | ⚠️ **Obrigatório** |
| **Trânsito da nota** | Servidores NFE.io que simulam a prefeitura | Prefeitura real |
| **Validade fiscal** | Sem validade fiscal | Com validade fiscal |

### Por que o certificado é opcional em testes na NFS-e?

O ambiente de **Testes** da NFE.io para NFS-e roda em servidores que **simulam o comportamento das prefeituras** — a nota não trafega para a prefeitura real, então não há transmissão que exija assinatura digital ICP-Brasil. Isso permite testar a integração de ponta a ponta antes mesmo de adquirir um certificado.

Em **Produção**, a nota é enviada para a prefeitura real, que exige assinatura digital. Por isso o certificado vira obrigatório.

:::info[Diferente de NF-e e NFC-e]
Para **NF-e e NFC-e**, o certificado digital é **obrigatório mesmo em homologação**, porque o ambiente de homologação da SEFAZ é o ambiente real do órgão (apenas marcado como teste) e exige assinatura digital. Veja a cadência para esses documentos em [Primeiros Passos — NF-e](/docs/documentacao/nota-fiscal-produto-eletronica/integracao-api/primeiros-passos).
:::

- - -

## 1. Criar uma empresa

Cadastra a empresa emissora na plataforma NFE.io. A empresa é o recurso central: o certificado e a inscrição municipal serão vinculados a ela nas próximas etapas.

**Endpoint:**\
`POST: https://api.nfse.io/v2/companies`

**Exemplo de JSON:**

```json
{
  "Company": {
    "Name": "RAZAO SOCIAL DA EMPRESA",
    "FederalTaxNumber": "12345678000199",
    "TaxRegime": "SimplesNacional",
    "Address": {
      "State": "SP",
      "City": {
        "Code": "3550308",
        "Name": "São Paulo"
      },
      "District": "Centro",
      "Street": "Av. Exemplo",
      "Number": "100",
      "PostalCode": "01001000",
      "Country": "BRA"
    }
  }
}
```

> Será retornado o `Id` que representa o `companyId`, usado nas próximas requisições.

> Referência completa: [API de Empresas (v2)](/docs/documentacao/gerenciamento-empresas/api-empresas).

- - -

## 2. Enviar certificado digital

:::tip Pular se estiver testando
Esta etapa é **opcional em ambiente de Testes** (veja [Ambiente: Testes ou Produção](#ambiente-testes-ou-produção)). Se você só quer validar a integração antes de ir para produção, pode seguir para a Etapa 3 sem enviar o certificado e voltar aqui depois.
:::

Faz o upload do certificado A1 ICP-Brasil que será usado para assinar digitalmente as notas em **Produção**.

**Endpoint:**\
`POST: https://api.nfse.io/v2/companies/{companyId}/certificates`

Você deve enviar o arquivo `.pfx` e a senha no corpo da requisição. Após o envio, o sistema informará a validade, status e dados do certificado.

> **Segurança:** Os dados são criptografados e armazenados com segurança na plataforma da NFE.io.

> Referência completa: [API de Certificados (v2)](/docs/documentacao/gerenciamento-empresas/api-certificados).

- - -

## 3. Criar uma inscrição municipal

Vincula à empresa os dados de **Inscrição Municipal** que você obteve junto à prefeitura. Sem essa inscrição, a NFE.io não tem como emitir a NFS-e em nome da empresa.

**Endpoint:**\
`POST: https://api.nfse.io/v2/companies/{companyId}/municipaltaxes`

**Exemplo de JSON:**

```json
{
  "MunicipalTax": {
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP"
    },
    "TaxNumber": "876543",
    "Environment": "Production",
    "RpsSerialNumber": "IO"
  }
}
```

**Campos obrigatórios:**

- `City.Code` — código IBGE de 7 dígitos
- `City.Name` / `City.State` — nome e UF da cidade
- `Environment` — **`Development`** para testes (servidor NFE.io simulando prefeitura, sem validade fiscal) ou **`Production`** para emitir notas válidas
- `RpsSerialNumber` — série do RPS (ex.: `IO`, `A1`, `1`)

:::tip Comece pelo ambiente de testes
Use `Environment: "Development"` enquanto valida a integração — não é preciso certificado digital nesse ambiente. Quando estiver pronto para emitir notas reais, atualize a IM para `Environment: "Production"` e faça o upload do certificado.
:::

> Se a sua prefeitura exige credenciais de acesso ao webservice (login/senha ou token), envie também `LoginName`, `LoginPassword` e/ou `AuthIssueValue`.

> A resposta inclui o campo `FiscalStatus`, que indica se a NFE.io tem integração homologada com a prefeitura daquela cidade.

> Referência completa: [API de Inscrições Municipais (v2)](/docs/documentacao/gerenciamento-empresas/api-inscricoes-municipais).

- - -

## 4. Emitir uma nota fiscal de serviço

**Endpoint:**\
`POST: https://api.nfe.io/v1/companies/{companyId}/serviceinvoices`

:::info[Emissão segue na API v1]
A emissão de NFS-e ainda é servida pela API v1 (`api.nfe.io/v1/...`) e continuará funcionando normalmente durante a transição. O gerenciamento de empresa (etapas 1–3 acima) já é feito pela API v2 de Contribuintes (`api.nfse.io/v2/...`).
:::

**Campos principais:**

* Descrição do serviço (`description`)
* Código do serviço (`cityServiceCode`)
* Valor total do serviço (`servicesAmount`)
* Dados do tomador (`borrower`: CNPJ ou CPF, nome, endereço)

> Consulte a prefeitura para confirmar o código de serviço correto.

:::tip Cálculo automático de impostos
Por padrão, a NFE.io faz o **cálculo automático dos impostos** com base no `cityServiceCode` informado — você não precisa enviar `issRate`, `issAmount` ou outras retenções. Veja [Cálculo Automático de Impostos](/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/cenarios-de-emissao/calculo-automatico-impostos) para detalhes e para entender quando o cálculo manual se aplica.
:::

**Exemplo mínimo de payload:**

```json
{
  "borrower": {
    "type": "LegalEntity",
    "name": "Cliente Exemplo",
    "federalTaxNumber": "12345678000199",
    "email": "cliente@exemplo.com",
    "address": {
      "country": "BRA",
      "postalCode": "01001000",
      "street": "Rua Cliente",
      "number": "200",
      "district": "Centro",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "0101",
  "description": "Consultoria em tecnologia",
  "servicesAmount": 1000.00
}
```

> O processamento é assíncrono. Após envio bem-sucedido, você receberá um `id` que representa o id único da nota atribuído pela NFE.io. Acompanhe o status por consulta de nota.

- - -

## Próximos passos

[Consultar uma nota fiscal de serviço emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-id-get)\
[Consultar o XML de uma nota fiscal emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-get-document-xml)\
[Consultar o PDF da nota fiscal emitida](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/service-invoices-get-document-pdf)

## Informações adicionais

### Primeiros passos para integrar com nossa API de forma simples

Integre seu sistema com a nossa API para começar a emitir notas fiscais de forma automatizada. Em caso de dúvida em algum conceito utilizado aqui, visite nossa [Página de Conceitos](/docs/documentacao/nota-fiscal-servico-eletronica/conceitos) e saiba tudo que você precisa para emitir Nota Fiscal de Serviço Eletrônica (NFS-e).

Recomendamos que você use nosso **[Ambiente de Testes](#utilizando-o-ambiente-de-testes)** para fazer a integração e só depois mudar para o **[Ambiente de Produção](#mudando-para-o-ambiente-de-produção)**. Assim você pode tirar suas dúvidas e evitar equívocos quando mudar para produção.

Caso você não seja um desenvolvedor ou sua empresa não possua uma equipe de TI, nós disponibilizamos outras formas de automatizar suas emissões, [clique aqui](/docs/documentacao/nota-fiscal-servico-eletronica/conceitos#como-emitir-nota-fiscal-de-serviço-nfs-e) e veja as outras possibilidades disponíveis.

### Integração a partir de um meio de pagamento

A emissão automatizada de NFS-e depende da integração com o meio de pagamento usado por você. O meio de pagamento deve ter uma API por onde serão disponibilizadas as informações sobre os pagamentos que foram realizados.

Alguns meios de pagamento disponibilizam Webhooks para monitoramento dos pagamentos. Uma das opções de integrar com a nossa API é através desses [Webhooks](/docs/documentacao/webhooks/conceitos), que informarão sempre que um pagamento for realizado.

Outra opção é, de tempos em tempos, consultar a API do seu meio de pagamento para coletar os dados dos pagamentos que foram realizados.

Tendo os dados do pagamento, é só adicionar as informações pertinentes ao serviço prestado e enviar para nossa API, que emitirá a nota calculando os impostos automaticamente.

> Observação: A maioria dos meios de pagamento não disponibilizam todas as informações necessárias para que a nota seja emitida. Ou seja, sua solução terá que agregar as informações faltantes com as informações cedidas pelo seu meio de pagamento.

### Utilizando o Ambiente de Testes

Uma das vantagens da nossa API é que você pode testá-la gratuitamente, assim você pode garantir que a nossa solução atenda às suas demandas.

Abaixo temos um passo a passo para utilização do nosso Ambiente de Testes:

> Observação: Para testar a API de NFS-e você precisa apenas de uma **Inscrição Municipal** configurada com `Environment: "Development"`. **Certificado Digital** e **Inscrição Estadual** não são necessários no ambiente de testes da NFS-e (Inscrição Estadual nunca é exigida para NFS-e). Veja a matriz completa em [Ambiente: Testes ou Produção](#ambiente-testes-ou-produção).

### Módulos disponíveis

1. **Escolha da linguagem**: Oferecemos bibliotecas em:  

   * [Node.js](/docs/desenvolvedores/bibliotecas/nodejs)  
   * [PHP](/docs/desenvolvedores/bibliotecas/php)  
   * [Ruby](/docs/desenvolvedores/bibliotecas/ruby)

Para outras linguagens, use nossa [Referência da API](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1).

### Mudando para o ambiente de produção

Após testar com sucesso, siga os passos abaixo:

1. Verifique os dados ao [criar sua empresa](/docs/documentacao/nossa-plataforma/criar-empresa)
2. Certifique-se de que está credenciado na prefeitura para emissão de nota fiscal ([como credenciar](/docs/documentacao/nota-fiscal-servico-eletronica/documentacao-nota-fiscal-servico-eletronica-credenciamento-prefeitura))
3. Faça o [upload do certificado digital](/docs/documentacao/nossa-plataforma/upload-do-certificado-digital)
4. Entre em contato com a equipe comercial para gerar sua fatura.
5. Após o pagamento, vá até a aba **"EMPRESAS"**, clique em **"ALTERAR EMPRESA"**.
6. Mude o ambiente de testes para produção na seção **"Ambiente"**.

---

## Documentação Funcional: API de Emissão de NF-e/NFC-e (v3)

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/documentacao-layout-nfe-rtc/index.md

# Documentação Funcional: API de Emissão de NF-e/NFC-e (v3)

**Versão do Documento:** 1.0
**Data da Última Revisão:** 24 de Outubro de 2025

---

## 1. Introdução

### 1.1. Objetivo

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

Este documento serve como um guia funcional completo para a utilização da API de emissão de Nota Fiscal de Produto (NF-e, modelo 55) e Nota Fiscal de Consumidor (NFC-e, modelo 65). O objetivo é detalhar a estrutura do corpo da requisição (`payload`), a finalidade de cada grupo e propriedade, as regras de negócio, validações e o contexto de preenchimento de cada campo.

Esta documentação é destinada a desenvolvedores, analistas de sistemas e qualquer profissional que necessite integrar sistemas de terceiros com a plataforma de emissão de documentos fiscais.

### 1.2. Documentos de Referência

A estrutura desta API foi desenvolvida com base nos seguintes documentos oficiais:

*   **Manual de Orientação do Contribuinte (MOC):** Principalmente o "ANEXO I - Leiaute e Regra de Validação - NF-e e NFC-e".
*   **Nota Técnica 2025.002 (v1.31):** Detalha as adequações para a Reforma Tributária do Consumo (RTC), incluindo os novos tributos IBS, CBS e IS.
*   **Schemas XSD Oficiais:** Como `tiposBasico_v4.00.xsd` e o leiaute da NF-e.

Ao longo do documento, os campos da API são mapeados para seus respectivos campos no XML da SEFAZ (ex: `(natOp)`), facilitando a associação para quem já tem familiaridade com o leiaute oficial.

### 1.3. Conceitos Gerais

*   **Ambiente de Emissão:** A API opera em dois ambientes distintos:
    *   `Test` (Homologação): Para testes de integração, sem validade fiscal.
    *   `Production` (Produção): Para emissão de documentos com validade fiscal.
*   **Modelos de Documento:**
    *   **NF-e (modelo 55):** Nota Fiscal Eletrônica, utilizada para documentar operações de circulação de mercadorias entre pessoas jurídicas ou entre pessoa jurídica e física.
    *   **NFC-e (modelo 65):** Nota Fiscal de Consumidor Eletrônica, utilizada em operações de venda presencial ou para entrega a domicílio ao consumidor final.

---

## 2. Estrutura Geral da Requisição

A emissão de uma nota fiscal é realizada através de uma requisição `POST` para o endpoint `/v2/companies/:companyId/productinvoices`. O corpo da requisição é um objeto JSON que representa a totalidade da nota fiscal. A seguir, detalhamos cada grupo principal deste objeto.

:::info NFC-e (modelo 65)

Para a **NFC-e (modelo 65)**, a estrutura do corpo (`payload`) e os grupos de tributos da Reforma Tributária (IBS, CBS e IS) são **os mesmos** descritos neste documento — muda apenas o endpoint de emissão:

* `POST /v2/companies/{companyId}/consumerinvoices` — emissão padrão da NFC-e.
* `POST /v2/companies/{companyId}/statetaxes/{statetaxId}/consumerinvoices` — emissão informando explicitamente a Inscrição Estadual (StateTax) a ser utilizada. Recomendado quando a empresa possui **mais de uma IE ativa**. A IE informada deve ser do tipo `NFCe` e estar `Active`; caso contrário a requisição é rejeitada (`400`/`404`).

Ao longo do texto, os campos **não aplicáveis à NFC-e** (ex.: `operationOn`, `expectedDeliveryOn`) e as regras específicas do modelo 65 (ex.: valores permitidos de `presenceType`, séries de contingência) estão destacados nos respectivos grupos.

:::

### 2.1. Grupo de Identificação da Nota Fiscal

Este grupo contém as informações que identificam unicamente a nota fiscal e definem suas características principais, como natureza da operação, datas e finalidade.

*   `serie` (integer): **Série do Documento Fiscal (serie)**. Número que controla a sequência de numeração.
    *   **Validações:** Valor entre 0 e 999. Para NFC-e, as séries 890-899 são de uso exclusivo para emissão em contingência (SCAN).
*   `number` (integer): **Número do Documento Fiscal (nNF)**. Número sequencial da nota dentro da série.
    *   **Validações:** Não pode ser duplicado para o mesmo emitente, modelo e série.
*   `operationOn` (string): **Data e Hora de Saída/Entrada (dhSaiEnt)**. Data e hora em que a mercadoria saiu do estabelecimento (em notas de saída) ou entrou (em notas de entrada). Formato `AAAA-MM-DDThh:mm:ssTZD`. **Não deve ser preenchido para NFC-e (modelo 65)**.
    *   **Validações:** Não pode ser maior que a data de processamento. Para NF-e de entrada, não pode ser menor que a data de emissão.
*   `expectedDeliveryOn` (string): **Data da Previsão de Entrega (dPrevEntrega)**. Data prevista para a entrega do bem. Formato `AAAA-MM-DD`. **Não aplicável à NFC-e**.
    *   **Validações:** Não pode ser anterior à data de emissão, nem superior a 3 meses da data de saída. Não é permitida para finalidades de ajuste (`finNFe=3`) ou complementar (`finNFe=2`), nem para fretes por conta do destinatário (`modFrete=1`, FOB) ou sem frete (`modFrete=9`).
*   `operationNature` (string): **Descrição da Natureza da Operação (natOp)**. Texto que descreve a operação (ex: "Venda de mercadoria", "Remessa para conserto"). Este campo deve ser consistente com o CFOP utilizado nos itens.
    *   **Validações:** Mínimo de 2 caracteres.
*   `operationType` (enum): **Tipo do Documento Fiscal (tpNF)**. Define se a nota é de `Incoming` (Entrada) ou `Outgoing` (Saída).
    *   **Validações:** Uma nota de devolução (`purposeType` = `Devolution`) deve ser do tipo `Incoming`. Uma nota de crédito (`finNFe=5`) deve ser do tipo `Incoming`.
*   `destination` (enum): **Identificador de Local de Destino (idDest)**. Indica se a operação é `Internal_Operation` (dentro do mesmo estado), `Interstate_Operation` (entre estados) ou `International_Operation` (com o exterior).
    *   **Validações:** Se a UF do destinatário for igual à do emitente, deve ser `Internal_Operation`. Se for diferente, `Interstate_Operation`. Se o país for diferente de Brasil, `International_Operation`.
*   `consumptionCityCode` (integer): **Código do Município de Ocorrência do Fato Gerador (cMunFG)**. Código IBGE do município onde o imposto (ICMS) é devido. Geralmente, é o município do emitente, mas pode variar em casos específicos.
    *   **Validações:** Obrigatório se a UF do local de entrega for diferente da UF do emitente (para NF-e) ou se a venda for presencial fora do estabelecimento (para NFC-e).
*   `ibsConsumptionCityCode` (integer): **Município do Fato Gerador do IBS/CBS (cMunFGIBS)**. Código IBGE do município onde ocorre o fato gerador dos novos tributos (IBS/CBS). Relevante para operações presenciais fora do estabelecimento, onde o consumo ocorre em município diferente.
    *   **Validações:** Obrigatório apenas se `presenceType` for `5` (Operação presencial, fora do estabelecimento) e o endereço do destinatário ou de entrega não for informado.
*   `printType` (enum): **Formato de Impressão do DANFE (tpImp)**. Define o layout de impressão do Documento Auxiliar da Nota Fiscal Eletrônica.
*   `purposeType` (enum): **Finalidade da Emissão (finNFe)**. Indica a finalidade da nota: `Normal`, `Complement` (complementar), `Adjustment` (ajuste) ou `Devolution` (devolução).
    *   **Validações:** Uma nota complementar (`finNFe=2`), de ajuste (`finNFe=3`), de devolução (`finNFe=4`) ou de crédito (`finNFe=5`) deve, obrigatoriamente, referenciar um documento fiscal.
*   `debitType` (enum): **Tipo de Nota de Débito (tpNFDebito)**. Usado em notas de débito (finNFe=6) para cenários específicos da Reforma Tributária, como `finesAndInterest` (multas e juros).
    *   **Validações:** Só pode ser informado se a finalidade da nota (`purposeType`) for `Debit` (finalidade 6).
*   `creditType` (enum): **Tipo de Nota de Crédito (tpNFCredito)**. Usado em notas de crédito (finNFe=5) para cenários como `valueReduction` (redução de valor) ou apropriação de créditos.
    *   **Validações:** Só pode ser informado se a finalidade da nota (`purposeType`) for `Credit` (finalidade 5).
*   `consumerType` (enum): **Indicador de Operação com Consumidor Final (indFinal)**.
    *   `FinalConsumer`: A venda é para um consumidor final.
    *   `Normal`: A venda não é para consumidor final.
    *   **Regra de Padrão:** Se este campo não for informado, o valor será definido com base no `federalTaxNumber` do comprador (`buyer`): "Normal" para CNPJ e "FinalConsumer" para CPF/NIF.
*   `presenceType` (enum): **Indicador de Presença do Comprador (indPres)**. Indica como a operação comercial ocorreu (ex: `Presence` para presencial, `Internet` para não presencial via internet). Essencial para diferenciar vendas em loja física de e-commerce.
    *   **Validações:** Para NFC-e, os valores permitidos são `Presence` (presencial) ou `Delivery` (entrega a domicílio).
*   `contingencyOn` (string) e `contingencyJustification` (string): **Entrada em Contingência (dhCont, xJust)**. Usados para emissão em modo de contingência, quando o ambiente da SEFAZ está indisponível.
    *   **Validações:** A justificativa deve ter no mínimo 15 caracteres.
*   `governmentPurchase` (object): **Grupo de Compras Governamentais (gCompraGov)**. Detalha operações de venda para órgãos públicos, que podem ter regras de tributação específicas.

### 2.2. Grupo do Comprador (`buyer`)

Contém todas as informações do destinatário da mercadoria. **Grupo obrigatório para NF-e (modelo 55)**.
*   `name` (string): **Nome ou Razão Social (xNome)**. (Obrigatório)
*   `federalTaxNumber` (integer): **CNPJ ou CPF (CNPJ/CPF)**. (Obrigatório) Para operações com o exterior, pode ser o NIF (Número de Identificação Fiscal).
    *   **Validações:** Para operações internas ou interestaduais, deve ser um CNPJ ou CPF válido. Se for informado CNPJ, a Inscrição Estadual (`stateTaxNumber`) pode ser obrigatória dependendo da UF.
*   `tradeName` (string): **Nome Fantasia (xFant)**.
*   `stateTaxNumber` (string): **Inscrição Estadual (IE)**.
    *   **Validações:** Se `stateTaxNumberIndicator` for `TaxPayer`, a IE deve ser informada e válida para a UF do destinatário. Se for `NonTaxPayer`, não deve ser informada.
*   `stateTaxNumberIndicator` (enum): **Indicador da IE do Destinatário (indIEDest)**. Define a relação do destinatário com o ICMS. Este campo é crucial para o cálculo correto de impostos como o DIFAL.
    *   `TaxPayer`: Contribuinte de ICMS.
    *   `Exempt`: Contribuinte isento de Inscrição Estadual.
    *   `NonTaxPayer`: Não Contribuinte de ICMS.
*   `address` (object): **Endereço do Destinatário (enderDest)**. (Obrigatório) Objeto contendo os dados completos do endereço.
*   `email` (string): **Email (email)**. (Obrigatório)
    *   **Validações:** O código do município (`city.code`) deve corresponder à UF (`state`).

### 2.3. Grupos de Locais de Entrega e Retirada

*   `delivery` (object): **Identificação do Local de Entrega (entrega)**. Usado **apenas** quando o local de entrega é diferente do endereço do destinatário. Se for o mesmo, este grupo não deve ser preenchido.
    *   **Validações:** O CNPJ/CPF do local de entrega não pode ser igual ao do emitente.
*   `withdrawal` (object): **Identificação do Local de Retirada (retirada)**. Usado **apenas** quando a mercadoria é retirada em local diferente do endereço do emitente.

### 2.4. Grupo de Itens (`items`)

Este é um array de objetos, onde cada objeto representa um produto ou serviço da nota. É a seção mais importante e complexa do documento fiscal.

#### 2.4.1. Propriedades do Item

*   `code` (string): **Código do Produto ou Serviço (cProd)**. (Obrigatório) Código interno do produto no sistema do emitente.
*   `codeGTIN` (string): **GTIN (cEAN)**. Código de barras do produto, se houver.
*   `description` (string): **Descrição do Produto ou Serviço (xProd)**. (Obrigatório)
    *   **Validações:** Não pode ser preenchido com termos genéricos como "DIVERSOS".
*   `ncm` (string): **Código NCM (NCM)**. (Obrigatório) Nomenclatura Comum do Mercosul. Campo fundamental para a correta tributação.
    *   **Validações:** Deve ser um código NCM válido, existente na tabela oficial. Para alguns produtos, o NCM completo de 8 dígitos é obrigatório.
*   `cest` (string): **Código CEST (CEST)**. Código Especificador da Substituição Tributária. Obrigatório para produtos listados em convênios de ICMS-ST.
    *   **Validações:** Obrigatório se o produto estiver sujeito à substituição tributária, conforme convênios ICMS.
*   `cfop` (integer): **Código Fiscal de Operações e Prestações (CFOP)**. (Obrigatório se não enviado taxDetermination) Código numérico que define a natureza da operação do item (venda, remessa, devolução, etc.) e sua tributação.
    *   **Validações:** Deve ser um código válido. O primeiro dígito deve ser compatível com o tipo de operação (ex: 5 ou 6 para saídas, 1 ou 2 para entradas).
*   `quantity` (number): **Quantidade Comercial (qCom)**. (Obrigatório)
*   `unit` (string): **Unidade Comercial (uCom)** (ex: "UN", "CX", "KG"). (Obrigatório)
*   `unitAmount` (number): **Valor Unitário de Comercialização (vUnCom)**. (Obrigatório)
*   `totalAmount` (number): **Valor Total Bruto do Produto (vProd)**. (Obrigatório) Resultado de `quantity * unitAmount`.
    *   **Validações:** O valor deve ser o resultado da multiplicação da quantidade pelo valor unitário, com uma pequena tolerância para arredondamento.
*   `freightAmount`, `insuranceAmount`, `othersAmount` (number): Valores de frete, seguro e outras despesas acessórias que são rateados e compõem o valor total do item.
*   `totalIndicator` (boolean): **Indicador de Totalização (indTot)**. Indica se o valor do item (`vProd`) entra no cálculo do valor total da NF-e.
    *   **Validações:** Para NF-e de ajuste (`purposeType` = `Adjustment`), este campo deve ser `false`.
*   `numberOrderBuy` (string): **Número do Pedido de Compra (xPed)**.
*   `unitTax` (string): **Unidade Tributável (uTrib)**. (Obrigatório)

#### 2.4.2. Grupo de Tributos do Item (`tax`)

Dentro de cada item, o objeto `tax` detalha todos os tributos incidentes sobre o produto ou serviço.
**Obrigatório somente se não for enviado o grupo taxDetermination.**

*   `totalTax` (number): **Valor Aproximado dos Tributos (vTotTrib)**. (Obrigatório) Valor estimado de tributos conforme Lei da Transparência.

*   **Tributos do Regime Antigo:**
    *   `icms` (object): **Grupo do ICMS**. (Obrigatório) Contém a tributação do ICMS, com campos como `origin`, `cst`, `baseTax`, `rate` e `amount`. A estrutura interna varia conforme o CST.
        *   **Validações:** Apenas um dos grupos de tributação do ICMS (ICMS00, ICMS10, ICMS20, etc.) pode ser preenchido, de acordo com o CST informado.
    *   `ipi` (object): **Grupo do IPI**. Detalha a tributação do Imposto sobre Produtos Industrializados.
    *   `pis` (object): **Grupo do PIS**. (Obrigatório)
    *   `cofins` (object): **Grupo do COFINS**. (Obrigatório)

*   **Tributos da Reforma Tributária (RTC):**
    *   `IS` (object): **Imposto Seletivo**. Preenchido para produtos sujeitos a este imposto (ex: cigarros, bebidas açucaradas). Contém `situationCode`, `basis`, `rate` e `amount`.
        *   **Validações:** O uso deste grupo é obrigatório se o `cClassTribIS` do item indicar incidência do Imposto Seletivo. O valor do imposto (`amount`) deve ser o resultado da base de cálculo (`basis`) pela alíquota (`rate`).
    *   `IBSCBS` (object): **Grupo do IBS e CBS**. Grupo central da RTC, obrigatório para operações no novo regime a partir de 05/01/2026.
        *   `situationCode` (string): Código de Situação Tributária para IBS/CBS.
        *   `classCode` (string): Código de Classificação Tributária, que define o regime específico do item (ex: tributação geral, isenção, alíquota reduzida).
            *   **Validações:** O `classCode` deve ser um código válido da tabela oficial e compatível com o `situationCode` informado.
        *   `basis` (number): Base de cálculo unificada.
        *   `calculationMode` (enum): Modo de cálculo do imposto. Permite escolher entre o preenchimento manual (`Manual`, valor padrão) ou o cálculo automático via serviço oficial (`OfficialService`). Quando `OfficialService` é usado, apenas `situationCode` e `classCode` são necessários, e os demais campos de tributo são preenchidos pelo serviço.
        *   `state` (object): Detalha o cálculo do **IBS Estadual** (`rate`, `amount`, `deferment`, `reduction`).
        *   `municipal` (object): Detalha o cálculo do **IBS Municipal**.
        *   `cbs` (object): Detalha o cálculo da **CBS**.
            *   **Validações:** Os valores de `amount` em cada subgrupo devem ser calculados corretamente com base na `basis` e nas respectivas alíquotas e benefícios.
            *   **Validações (RTC):** Para notas de débito ou crédito (`finNFe` = 5 ou 6), é vedado informar os grupos de tributos do regime antigo (ICMS, IPI, PIS, COFINS, etc.).
        *   Subgrupos opcionais como `monophase` (tributação monofásica), `operationalPresumedCredit` (crédito presumido), `governmentPurchase` (compras governamentais), etc.

*   `taxDetermination` (object): **Grupo para Determinação Automática de Impostos**. Se preenchido, o sistema pode calcular automaticamente os tributos do grupo `IBSCBS` com base em informações como `operationCode`, `issuerTaxProfile` e `buyerTaxProfile`.

### 2.5. Grupo de Transporte (`transport`)

Contém as informações sobre o transporte da mercadoria.

*   `freightModality` (enum): **Modalidade do Frete (modFrete)**. Define o responsável pelo frete (ex: `ByIssuer` - CIF, `ByReceiver` - FOB, `Free` - Sem frete).
    *   **Validações:** Se a modalidade for `Free` (sem frete), os grupos de transportador, veículo e volumes não devem ser preenchidos.
*   `transportGroup` (object): **Dados do Transportador (transporta)**. Informações como `name`, `federalTaxNumber`, `stateTaxNumber` e `address`.
*   `transportVehicle` (object): **Dados do Veículo (veicTransp)**. Placa (`plate`) e UF do veículo.
*   `reboque` (object): **Dados do Reboque**.
*   `volume` (object): **Dados dos Volumes Transportados (vol)**. Informações como quantidade (`volumeQuantity`), espécie (`species`), peso líquido (`netWeight`) e peso bruto (`grossWeight`).

### 2.6. Grupo de Pagamento (`payment`)

Array de objetos que detalha as formas de pagamento.

*   `paymentDetail` (array): Detalhes do pagamento.
    *   `method` (enum): **Forma de Pagamento (tPag)** (ex: `Cash`, `CreditCard`, `InstantPayment` para PIX).
    *   `amount` (number): **Valor do Pagamento (vPag)**.
        *   **Validações:** A soma dos valores de todos os pagamentos deve ser igual ao valor total da nota.
    *   `paymentType` (enum): **Indicador da Forma de Pagamento (indPag)**: `InCash` (à vista) ou `Term` (a prazo).
    *   `card` (object): Se o pagamento for com cartão, este grupo contém dados da transação, como a bandeira (`flag`), o CNPJ da credenciadora e o número de autorização.
        *   **Validações:** Obrigatório se o método de pagamento for `CreditCard` ou `DebitCard`.
*   `payBack` (number): **Valor do Troco (vTroco)**.

### 2.7. Grupo de Cobrança (`billing`)

Usado para detalhar a cobrança comercial da operação.

*   `bill` (object): **Fatura (fat)**. Contém número (`number`), valor original (`originalAmount`), desconto (`discountAmount`) e valor líquido (`netAmount`).
*   `duplicates` (array): **Duplicatas (dup)**. Array com as parcelas da fatura, cada uma com número (`number`), data de vencimento (`expirationOn`) e valor (`amount`).

### 2.8. Grupo de Totais (`totals`)

Resume os valores totais da nota fiscal. A maioria desses campos é calculada pelo sistema com base nos itens, mas é importante que o sistema de origem também os calcule para validação.

*   `icms` (object): **Totais do ICMS (ICMSTot)**. Contém a somatória de bases de cálculo, valores de ICMS, ICMS-ST, valor total dos produtos, frete, seguro, desconto, e o valor total da nota (`invoiceAmount`) segundo o regime antigo.
    *   **Validações:** Cada campo deste grupo deve corresponder à somatória do campo respectivo de todos os itens da nota.
*   `issqn` (object): **Totais do ISSQN (ISSQNtot)**. Somatórias relativas ao Imposto Sobre Serviços.
*   `withheldTaxes` (object): **Retenções de Tributos (retTrib)**. Valores retidos de PIS, COFINS, CSLL, IRRF e Previdência Social.
*   `isTotals` (object): **Totais do Imposto Seletivo (ISTot)**. Somatória do valor do Imposto Seletivo de todos os itens.
    *   **Validações:** O valor total (`amount`) deve ser a soma dos valores de `IS.amount` de todos os itens.
*   `ibsCbsTotals` (object): **Totais de IBS e CBS (IBSCBSTot)**. Consolida os totais de base de cálculo, valores de IBS (estadual e municipal), CBS, diferimentos, devoluções, etc.
    *   **Validações:** Os valores neste grupo devem ser a somatória dos valores correspondentes do grupo `IBSCBS` de cada item.
*   `totalInvoiceAmount` (number): **Valor Total da NF-e com RTC (vNFTot)**. Representa o valor total final da nota, considerando a soma dos produtos e todos os impostos, incluindo os novos (IBS, CBS, IS).
    *   **Validações:** Deve ser a soma do `totals.icms.invoiceAmount` com os totais de `isTotals` e `ibsCbsTotals`.

### 2.9. Grupo de Informações Adicionais (`additionalInformation`)

Campos de texto livre e referências para informações complementares.

*   `fisco` (string): **Informações Adicionais de Interesse do Fisco (infAdFisco)**.
*   `taxpayer` (string): **Informações Complementares de Interesse do Contribuinte (infCpl)**.
*   `xmlAuthorized` (array): **Autorizados a Baixar o XML (autXML)**. Lista de CNPJs ou CPFs de terceiros (ex: contador) autorizados a acessar o XML do documento.
    *   **Validações:** Devem ser CNPJs ou CPFs válidos. **Máximo de 10 autorizações.**
*   `taxDocumentsReference` (array): **Documentos Fiscais Referenciados (NFref)**. Usado para referenciar chaves de acesso de outras notas (ex: em uma devolução). Cada item pode conter um de três tipos:
    *   `documentElectronicInvoice`: NF-e/NFC-e referenciada (chave de acesso de 44 dígitos em `accessKey`).
    *   `documentInvoiceReference`: Nota fiscal modelo 1/1A referenciada (campos `state`, `yearMonth`, `federalTaxNumber`, `model`, `series`, `number`).
    *   `taxCouponInformation`: Cupom fiscal referenciado (campos `modelDocumentFiscal`, `orderECF`, `orderCountOperation`).
    *   **Validações:** A chave de acesso referenciada deve ser válida e existir na base de dados da SEFAZ.
*   `advancePayment` (array): **Notas de Antecipação de Pagamento (gPagAntecipado)**. Usado para abater parcelas de antecipação conforme art. 10 § 4º. Cada item contém apenas `accessKey`.
*   `taxpayerComments` (array): **Observações Fiscais (obsCont)**. Lista de pares `field`/`text` para observações livres do contribuinte.
*   `referencedProcess` (array): **Processos Referenciados (procRef)**. Para informar números de processos judiciais ou administrativos que amparam a operação. Cada item contém:
    *   `identifierConcessory` (string): Identificador do ato concessório.
    *   `identifierOrigin` (integer): Indicador da origem do processo (1=SEFAZ, 2=Justiça Federal, 3=Justiça Estadual, 9=Outros).
    *   `concessionActType` (integer): Tipo do ato concessório.

### 2.10. Grupo do Emitente (`issuer`) — Resposta

> **Observação:** Diferente da maioria dos grupos, `issuer` **não é enviado na requisição** de emissão. Ele é determinado automaticamente pelo cadastro da empresa (`companyId` na URL) e populado pela API na resposta. Este grupo é detalhado aqui para referência ao consumir os endpoints de consulta.

Identifica o emitente da NF-e (`emit` no XML).

*   `name` (string): **Nome ou Razão Social (xNome)**.
*   `federalTaxNumber` (integer): **CNPJ do emitente**.
*   `tradeName` (string): **Nome Fantasia (xFant)**.
*   `regionalTaxNumber` (integer): **Inscrição Estadual (IE)** na SEFAZ da UF do emitente.
*   `regionalSTTaxNumber` (integer): **IE do Substituto Tributário (IEST)** quando o emitente é substituto tributário.
*   `municipalTaxNumber` (string): **Inscrição Municipal (IM/CCM)**.
*   `companyRegistryNumber` (integer): **Número de Inscrição na Junta Comercial (nIRE)**.
*   `address` (AddressResource): Endereço do emitente (`enderEmit`).
*   `taxRegime` (enum `TaxRegime`): Código de Regime Tributário (CRT). Ver §11.3.1.
*   `specialTaxRegime` (enum `SpecialTaxRegime`): Regime especial de tributação (`indRegTrib`). Ver §11.3.2.
*   `legalNature` (enum `LegalNature`): Natureza jurídica da empresa. Ver §11.10.
*   `economicActivities` (array): Lista de **CNAEs** da empresa, cada item com `type` (`Main`/`Secondary`) e `code` (código numérico).
*   `openningDate` (string): Data de abertura da empresa (`dIniAtiv`).
*   `stStateTaxNumber` (string): **IE do Substituto Tributário (IEST)** — também exposta no payload de requisição via `issuerTaxSubstitute` quando relevante para a operação específica.

### 2.11. Grupo de Compras (`purchaseInformation`)

Detalha referências comerciais da operação. Aplicável principalmente a vendas para órgãos públicos.

*   `commitmentNote` (string): **Nota de Empenho (xNEmp)**. Identificação do empenho quando se trata de compra pública. Mín. 1, máx. 22 caracteres.
*   `purchaseOrder` (string): **Pedido (xPed)**. Identificação do pedido de compra. Mín. 1, máx. 60 caracteres.
*   `contractNumber` (string): **Contrato (xCont)**. Identificação do contrato. Mín. 1, máx. 60 caracteres.

> **Diferença para `additionalInformation.order` / `contract`:** Os campos em `additionalInformation` são genéricos de texto livre. O grupo `purchaseInformation` é estruturado e mapeado diretamente ao grupo `compra` do XML — preferível em compras governamentais.

### 2.12. Grupo de Exportação (`export`)

Aplicável apenas a operações com `destination = InternationalOperation`.

*   `state` (enum `StateCode`): Sigla da UF de embarque ou de transposição de fronteira.
*   `office` (string): **Local de Embarque (xLocExporta)**. Descrição do local físico de saída do bem (ex: "Porto de Santos", "Aeroporto de Guarulhos").
*   `local` (string): **Local de Despacho (xLocDespacho)**. Local de despacho aduaneiro.

### 2.13. Grupo do Intermediador da Transação (`transactionIntermediate`)

Aplicável quando a venda é feita por meio de **marketplace, plataforma de delivery ou agenciador**.

*   `federalTaxNumber` (integer): **CNPJ do Intermediador (CNPJ)**. CNPJ da plataforma intermediadora.
*   `identifier` (string): **Identificador no Intermediador (idCadIntTran)**. ID interno do vendedor/loja na plataforma intermediadora.

> **Quando preencher:** Sempre que a transação foi originada/processada por um terceiro (Marketplace), mesmo que o pagamento tenha sido feito diretamente ao emitente. A SEFAZ usa este grupo para conciliação fiscal entre emitente e plataforma.

### 2.14. Grupo de Contingência (`contingencyOn` / `contingencyJustification`)

Quando a SEFAZ está indisponível (timeout, erro 5xx, status do serviço degradado), a NF-e pode ser emitida em **modo contingência**:

*   `contingencyOn` (string, ISO 8601): Data e hora de entrada em contingência (`dhCont`).
*   `contingencyJustification` (string): Justificativa textual da entrada em contingência (`xJust`). **Mínimo 15 caracteres**, máximo 1.000.

A nota é processada localmente e posteriormente sincronizada com a SEFAZ. O status da NF-e fica em `IssuedContingency` até a sincronização ser bem-sucedida.

> **Recomendação:** Configure o emissor para gerenciar contingência automaticamente via cadastro da Inscrição Estadual em vez de preencher manualmente — ver §9.4.

### 2.15. Subgrupos Especiais de Item

Além dos campos básicos descritos em §2.4.1 e §2.4.2, cada item pode conter subgrupos específicos para tipos de produto/operação:

#### 2.15.1. `vehicleDetail` — Veículos Novos

Aplicável quando o item é um **veículo 0 km**. Detalhamento completo em §6.22 (todos os campos J02–J26 do leiaute oficial).

```json
"vehicleDetail": {
  "operationType": 1,
  "chassis": "9BWZZZ377VT004251",
  "colorCode": "001",
  "colorDescription": "PRETO",
  "enginePower": "150",
  "engineDisplacement": "1998",
  "netWeight": "1250.000",
  "grossWeight": "1500.000",
  "serialNumber": "123456789",
  "fuelType": "16",
  "engineNumber": "MOTOR123456789",
  "maximumTractionCapacity": "0.0000",
  "wheelBase": "2649",
  "modelYear": 2026,
  "manufactureYear": 2025,
  "paintType": "S",
  "vehicleType": "06",
  "vehicleSpecies": 1,
  "vinCondition": "N",
  "vehicleCondition": 1,
  "brandModelCode": "025104",
  "denatranColorCode": "11",
  "seatingCapacity": 5,
  "restrictionType": 0
}
```

*   **`operationType`:** Tipo da operação (0-Outros, 1-Venda concessionária, 2-Faturamento direto, 3-Venda direta a grandes consumidores).
*   **`chassis`:** Chassi/VIN do veículo (17 caracteres alfanuméricos).
*   **`colorCode` / `colorDescription`:** Código (montadora) e descrição da cor.
*   **`enginePower` / `engineDisplacement`:** Potência (CV) e cilindrada (CC).
*   **`netWeight` / `grossWeight`:** Pesos líquido (`pesoL`) e bruto (`pesoB`).
*   **`serialNumber`:** Número de série (`nSerie`).
*   **`fuelType`:** Tipo de combustível pela Tabela RENAVAM (ex: `16` Álcool/Gasolina flex).
*   **`engineNumber`:** Número do motor (`nMotor`).
*   **`maximumTractionCapacity` / `wheelBase`:** CMT em toneladas e distância entre eixos (mm).
*   **`modelYear` / `manufactureYear`:** Ano modelo e ano de fabricação.
*   **`paintType` / `vehicleType` / `vehicleSpecies`:** Tipo de pintura, tipo (RENAVAM) e espécie do veículo.
*   **`vinCondition`:** Condição do chassi (`R`-Remarcado, `N`-Normal).
*   **`vehicleCondition`:** Condição do veículo (1-Acabado, 2-Inacabado, 3-Semi-acabado).
*   **`brandModelCode` / `denatranColorCode`:** Código marca/modelo e código da cor DENATRAN.
*   **`seatingCapacity`:** Lotação máxima (passageiros + motorista).
*   **`restrictionType`:** Restrição (0-Não há, 1-Alienação Fiduciária, 2-Arrendamento, 3-Reserva de Domínio, 4-Penhor, 9-Outras).

#### 2.15.2. `fuelDetail` — Combustíveis

Aplicável quando o item é um **combustível** sujeito a controle ANP.

```json
"fuelDetail": {
  "codeANP": "210203001",
  "percentageNG": 50.0,
  "descriptionANP": "GLP",
  "percentageGLP": 40.0,
  "percentageNGn": 30.0,
  "percentageGNi": 20.0,
  "startingAmount": 100.0,
  "codif": "CODIF-123",
  "amountTemp": 10.0,
  "stateBuyer": "RJ",
  "cide": { "bc": 10.0, "rate": 5.0, "cideAmount": 0.5 },
  "pump": { "spoutNumber": 1, "number": 1, "tankNumber": 1, "beginningAmount": 1000.0, "endAmount": 1010.0, "percentageBio": 10.0 },
  "fuelOrigin": { "indImport": 1, "cUFOrig": 35, "pOrig": 10.0 }
}
```

*   **`codeANP`:** Código de produto da ANP (`cProdANP`).
*   **`descriptionANP`:** Descrição do produto conforme ANP (`descANP`).
*   **`percentageNG`, `percentageGLP`, `percentageNGn`, `percentageGNi`:** Percentuais de mistura para o produto GLP (`cProdANP=210203001`).
*   **`startingAmount`:** Valor de partida (`vPart`).
*   **`codif`:** Código de autorização do CODIF.
*   **`amountTemp`:** Quantidade faturada à temperatura ambiente (`qTemp`).
*   **`stateBuyer`:** Sigla da UF de consumo (`UFCons`).
*   **`cide`:** Grupo CIDE (Contribuição de Intervenção no Domínio Econômico) com `bc` (BC), `rate` (alíquota), `cideAmount` (valor).
*   **`pump`:** Dados da bomba de combustível para postos:
    *   `spoutNumber`/`number`/`tankNumber`: Identificação física (bico, bomba, tanque).
    *   `beginningAmount`/`endAmount`: Encerrante inicial e final do abastecimento.
    *   `percentageBio`: Percentual do índice de mistura do Biodiesel B100 no Óleo Diesel.
*   **`fuelOrigin`:** Origem do combustível:
    *   `indImport`: Indicador de importação.
    *   `cUFOrig`: Código da UF de origem.
    *   `pOrig`: Percentual originário para a UF.

> **Mútua exclusão:** `vehicleDetail`, `fuelDetail` (e `medicineDetail` quando aplicável) são mutuamente exclusivos. Se mais de um for enviado, prevalece a ordem: medicamento > veículo > combustível.

#### 2.15.3. `presumedCredit` — Crédito Presumido por Item (regime ICMS)

Crédito presumido específico do regime antigo, conforme exigência da UF (NT 2019.001).

```json
"presumedCredit": {
  "code": "BENEF-001",   // Código do benefício na UF (cCredPresumido). Tamanho 8 ou 10
  "rate": 4.0,           // Percentual (pCredPresumido) — usar fração, ex: 0.04 = 4%
  "amount": 80.08        // Valor (vCredPresumido)
}
```

> **Diferente do `operationalPresumedCredit` do `IBSCBS`:** este é específico de ICMS e usa códigos de benefício da UF. O `operationalPresumedCredit` é da Reforma Tributária (RTC).

#### 2.15.4. `importDeclarations` — Declarações de Importação (DI)

Array de DIs vinculadas ao item. Cada DI contém:

*   `code`: Número do Documento de Importação (`nDI`).
*   `registeredOn`: Data de registro da DI/DSI/DA (`dDI`).
*   `customsClearanceName`: Local de desembaraço (`xLocDesemb`).
*   `customsClearanceState` (enum `StateCode`): UF do desembaraço (`UFDesemb`).
*   `customsClearancedOn`: Data do desembaraço (`dDesemb`).
*   `additions`: Array de adições com `code` (nº), `manufacturer` (cód. fabricante), `amount` (vDescDI), `drawback` (nº ato concessório).
*   `exporter`: Código do exportador (`cExportador`).
*   `internationalTransport` (enum `InternationalTransportType`): Via de transporte da DI. Ver §11.6.3.
*   `intermediation` (enum `IntermediationType`): Forma de intermediação. Ver §11.6.2.
*   `acquirerFederalTaxNumber`: CNPJ/CPF do adquirente/encomendante.
*   `stateThird`: UF do adquirente/encomendante.

#### 2.15.5. `exportDetails` — Detalhamento de Exportação por Item

Vínculo do item a um Registro de Exportação (RE) ou DEC (Declaração de Exportação Comum).

*   `drawback`: Número do ato concessório (`nDraw`).
*   `hintInformation`:
    *   `registryId`: Número do RE (`nRE`).
    *   `accessKey`: Chave da NF-e recebida para exportação (`chNFe`).
    *   `quantity`: Quantidade efetivamente exportada (`qExport`).

#### 2.15.6. `referencedDFe` — Documento Fiscal Eletrônico Referenciado

Referência item-a-item a um item específico de outro DF-e (uso típico: nota de devolução referenciando a NF-e original).

*   `accessKey` (string, 44 chars): Chave de acesso do DF-e referenciado.
*   `itemNumber` (integer 1–999): Número do item no DF-e original (`nItem`).

#### 2.15.7. `taxDetermination` — Cálculo Automático de Impostos

Quando preenchido, **substitui o preenchimento manual de `tax`** e dispara o cálculo automático via Tax Engine interno:

*   `operationCode` (integer): Código interno para determinação da natureza de operação.
*   `issuerTaxProfile` (string): Perfil fiscal do vendedor (origem) — ex: `industry`, `retail`, `wholesale`.
*   `buyerTaxProfile` (string): Perfil fiscal do comprador (destino) — ex: `final_consumer_non_icms_contributor`, `industry_icms_contributor`.
*   `origin` (string): Origem da mercadoria (mesmo enum do `tax.icms.origin`).
*   `acquisitionPurpose` (string): Finalidade da aquisição.

> **Ordem de precedência:**
> 1. Se `taxDetermination` preenchido → cálculo automático.
> 2. Caso contrário, `tax.IBSCBS` com `calculationMode = OfficialService` → cálculo automático apenas do IBS/CBS.
> 3. Caso contrário, todos os campos de `tax` devem ser preenchidos manualmente.

---

## 3. Apêndice A: Mapeamento de Grupos Principais

A tabela abaixo resume o mapeamento dos principais grupos do JSON da API para os grupos do XML da SEFAZ.

| Grupo na API (JSON) | Grupo no XML da SEFAZ | Descrição |
|---|---|---|
| (raiz do objeto) | `ide` | Identificação da NF-e |
| `issuer` | `emit` | Dados do Emitente |
| `buyer` | `dest` | Dados do Destinatário |
| `delivery` | `entrega` | Local de Entrega |
| `withdrawal` | `retirada` | Local de Retirada |
| `items` | `det` | Detalhamento de Produtos e Serviços (Itens) |
| `items.tax` | `imposto` | Tributos incidentes no item |
| `items.tax.icms` | `ICMS` | Grupo de ICMS |
| `items.tax.ipi` | `IPI` | Grupo de IPI |
| `items.tax.pis` | `PIS` | Grupo de PIS |
| `items.tax.cofins` | `COFINS` | Grupo de COFINS |
| `items.tax.IS` | `IS` | Grupo do Imposto Seletivo (RTC) |
| `items.tax.IBSCBS` | `IBSCBS` | Grupo de IBS e CBS (RTC) |
| `totals` | `total` | Grupo de Valores Totais |
| `totals.icms` | `ICMSTot` | Totais de ICMS |
| `totals.issqn` | `ISSQNtot` | Totais de ISSQN |
| `totals.isTotals` | `ISTot` | Totais do Imposto Seletivo (RTC) |
| `totals.ibsCbsTotals` | `IBSCBSTot` | Totais de IBS e CBS (RTC) |
| `transport` | `transp` | Dados do Transporte |
| `billing` | `cobr` | Dados da Cobrança (Fatura e Duplicatas) |
| `payment` | `pag` | Dados do Pagamento |
| `additionalInformation` | `infAdic` | Informações Adicionais |
| `purchaseInformation` | `compra` | Informações de Compra (empenho, pedido) |
| `export` | `exporta` | Informações de Exportação |
| `transactionIntermediate` | `infIntermed` | Informações do Intermediador da Transação |

---

## 4. Apêndice B: Estrutura Detalhada dos Novos Grupos da Reforma Tributária

### 4.1. `items.tax.IS`

```json
"IS": {
  "situationCode": "101",
  "classificationCode": "IS0001",
  "basis": 2002.0,
  "rate": 5.0,
  "amount": 100.1
}
```

*   **Finalidade:** Declarar o Imposto Seletivo.
*   **`situationCode`:** Define a tributação do IS para o item.
*   **`classificationCode`:** Classifica o item em uma das categorias do Imposto Seletivo.
*   **`basis`:** Valor sobre o qual a alíquota (`rate`) será aplicada.
*   **`amount`:** Valor final do imposto (`basis * rate / 100`).

### 4.2. `items.tax.IBSCBS`

```json
"IBSCBS": {
  "situationCode": "101",
  "classCode": "RT0001",
  "basis": 2002.0,
  "state": {
    "rate": 10.0,
    "deferment": { "rate": 1.0, "amount": 20.02 },
    "reduction": { "rateReduction": 0.5, "effectiveRate": 9.5 },
    "amount": 190.19
  },
  "municipal": {
    "rate": 5.0,
    "amount": 96.1
  },
  "cbs": {
    "rate": 12.0,
    "amount": 216.22
  },
  "ibsTotalAmount": 286.29
}
```

*   **Finalidade:** Declarar os novos tributos sobre o consumo, IBS e CBS.
*   **`situationCode` e `classCode`:** Chaves para determinar o regime de tributação do item.
*   **`basis`:** Base de cálculo comum para os tributos.
*   **`state` e `municipal`:** Detalham o IBS, que é um imposto dual. Contêm a alíquota nominal (`rate`), o valor final (`amount`) e podem conter subgrupos para benefícios como diferimento (`deferment`) ou redução de alíquota (`reduction`).
*   **`cbs`:** Detalha a CBS, que é um tributo federal único.
*   **`ibsTotalAmount`:** Soma dos valores de `state.amount` e `municipal.amount`.

### 4.3. `totals.isTotals` e `totals.ibsCbsTotals`

```json
"totals": {
  // ... outros totais
  "isTotals": {
    "amount": 100.1
  },
  "ibsCbsTotals": {
    "basis": 2002.0,
    "ibs": {
      "state": { "defermentAmount": 20.02, "amount": 190.19 },
      "municipal": { "amount": 96.1 },
      "totalAmount": 286.29
    },
    "cbs": {
      "amount": 216.22
    }
  },
  "totalInvoiceAmount": 2675.04
}
```

*   **Finalidade:** Consolidar os valores totais dos novos tributos para toda a nota fiscal.
*   **`isTotals.amount`:** Soma do campo `amount` de todos os grupos `IS` dos itens.
*   **`ibsCbsTotals`:** Agrega as bases de cálculo e os valores de IBS e CBS de todos os itens, separando os totais por esfera (estadual, municipal, federal) e por tipo de benefício (diferimento, devolução).
*   **`totalInvoiceAmount`:** O novo valor total da nota, calculado como: `totals.icms.invoiceAmount` (valor antigo) + `totals.isTotals.amount` + `totals.ibsCbsTotals.ibs.totalAmount` + `totals.ibsCbsTotals.cbs.amount`.

### 4.4. Subgrupos de Benefícios Fiscais do IBS/CBS

Tanto `state` quanto `municipal` (IBS) e `cbs` (CBS) compartilham a mesma estrutura interna para representar **benefícios fiscais** que reduzem o tributo devido. Cada um pode conter, opcionalmente, três subgrupos:

#### 4.4.1. `deferment` — Diferimento (`gDif`)

Representa **diferimento tributário**: o tributo é apurado mas seu pagamento é postergado para uma etapa posterior da cadeia.

```json
"deferment": {
  "rate": 1.0,        // Percentual do diferimento (pDif)
  "amount": 20.02     // Valor diferido (vICMSDif)
}
```

*   **`rate`:** Percentual da alíquota que está sendo diferido.
*   **`amount`:** Valor monetário do diferimento, calculado como `(basis * rate.diferida) / 100`.
*   **Quando aparece no XML:** Apenas quando o `cClassTrib` indica diferimento (CST `510`).

#### 4.4.2. `reduction` — Redução de Alíquota (`gRed`)

Representa **redução de alíquota** (não da base de cálculo). A alíquota efetiva aplicada é menor que a nominal.

```json
"reduction": {
  "rateReduction": 40.0,    // Percentual da redução (pRedAliq)
  "effectiveRate": 0.06     // Alíquota efetiva pós-redução (pAliqEfet)
}
```

*   **`rateReduction`:** Percentual da redução aplicada sobre a alíquota nominal (ex: 40 significa redução de 40%).
*   **`effectiveRate`:** Alíquota efetiva resultante após a redução (`rate * (1 - rateReduction/100)`).
*   **Invariante crítico:** O campo `rate` no nível superior (`state.rate`, `municipal.rate`, `cbs.rate`) **deve ser sempre a alíquota nominal**, nunca a efetiva. A alíquota efetiva fica exclusivamente em `reduction.effectiveRate`. Esta separação é garantida pela API.

#### 4.4.3. `returnedAmount` — Devolução de Tributos (`gDevTrib`)

Representa **devolução de tributos** ao adquirente em casos como devolução de mercadoria ou ajuste contábil.

```json
"returnedAmount": {
  "amount": 10.0    // Valor a devolver (vDevTrib)
}
```

### 4.5. Subgrupos Especiais do IBS/CBS

Além dos benefícios fiscais por jurisdição, o `IBSCBS` aceita subgrupos especiais para regimes tributários específicos.

#### 4.5.1. `monophase` — Tributação Monofásica (`gMonofasicoIBSCBS`)

Aplicável a **combustíveis** e outros produtos sujeitos à tributação monofásica (alíquota ad rem por unidade tributável, art. 172-180 LC 214/2025).

```json
"monophase": {
  "standart": {
    "quantityBasis": 10.0,
    "ibsAdRemRate": 15.0,
    "cbsAdRemRate": 25.0,
    "ibsAmount": 150.0,
    "cbsAmount": 250.0
  },
  "withholding": { /* tributação monofásica sujeita à retenção */ },
  "previouslyWithheld": { /* monofásica retida anteriormente */ },
  "deferment": { /* diferimento monofásico (biocombustíveis) */ },
  "ibsAmount": 140.0,    // Total IBS monofásico do item (vTotIBSMonoItem)
  "cbsAmount": 255.0     // Total CBS monofásico do item (vTotCBSMonoItem)
}
```

*   **`standart` (gMonofasicoPadrao):** Tributação monofásica aplicada na cadeia em uma única etapa.
    *   `quantityBasis`: Quantidade base tributada (qBCMono).
    *   `ibsAdRemRate` / `cbsAdRemRate`: Alíquota ad rem em R$ por unidade tributável.
    *   `ibsAmount` / `cbsAmount`: `quantityBasis * adRemRate`.
*   **`withholding` (gMonofasicoRetido):** Tributação monofásica em que o emitente é responsável pela retenção.
*   **`previouslyWithheld` (gMonofasicoRetidoAnt):** Tributação monofásica que foi retida em etapa anterior da cadeia (informativo, sem efeito no valor final).
*   **`deferment` (gMonofasicoDif):** Diferimento aplicável especificamente a biocombustíveis na monofásica.
*   **`ibsAmount` / `cbsAmount`:** Totais consolidados do item para o IBS e CBS monofásicos.

#### 4.5.2. `operationalPresumedCredit` — Crédito Presumido Operacional (`gCredPresOper`)

Crédito presumido sobre operações específicas (produtor rural não contribuinte, reciclagem de PF, bens usados de PF para revenda, etc.).

```json
"operationalPresumedCredit": {
  "basis": 1000.0,
  "classificationCode": "RuralProducerNonTaxpayer",
  "ibs": {
    "rate": 10.0,
    "amount": 100.0,
    "suspensiveConditionAmount": 10.0
  },
  "cbs": {
    "rate": 5.0,
    "amount": 50.0,
    "suspensiveConditionAmount": 5.0
  }
}
```

*   **`basis`:** Base de cálculo do crédito presumido (vBC).
*   **`classificationCode`:** Tipo do crédito presumido (ver enum `PresumedCreditClassificationCode` no Apêndice H).
*   **`ibs` / `cbs`:**
    *   `rate`: Percentual do crédito presumido (pCredPres).
    *   `amount`: Valor do crédito presumido (vCredPres).
    *   `suspensiveConditionAmount`: Parcela do crédito sujeita a condição suspensiva (vCredPresCondSus). Só se concretiza quando a condição for cumprida.

#### 4.5.3. `creditTransfer` — Transferência de Crédito (`gTransfCred`)

Aplicável em **fusão, cisão, incorporação ou transferência entre cooperativas e associados** (CST `800`).

```json
"creditTransfer": {
  "ibsAmount": 50.0,    // IBS a transferir (vIBS)
  "cbsAmount": 30.0     // CBS a transferir (vCBS)
}
```

#### 4.5.4. `creditReversal` — Estorno de Crédito (`gEstornoCred`)

Aplicável quando há vedação ou obrigatoriedade de estorno de crédito conforme o `cClassTrib` (campo `ind_gEstornoCred` da tabela).

```json
"creditReversal": {
  "ibsReversalAmount": 2.0,    // IBS a estornar (vIBSEstCred)
  "cbsReversalAmount": 1.0     // CBS a estornar (vCBSEstCred)
}
```

#### 4.5.5. `governmentPurchase` — Composição em Compras Governamentais (`gCompraGov`)

Detalha como IBS e CBS são compostos em vendas para órgãos da administração pública direta, autarquias e fundações (art. 472/370 LC 214/2025). Aplicável quando o grupo `governmentPurchase` (raiz) está preenchido.

```json
"governmentPurchase": {
  "stateRate": 8.0,       "stateAmount": 160.16,
  "municipalRate": 4.0,   "municipalAmount": 80.08,
  "cbsRate": 10.0,        "cbsAmount": 200.2
}
```

*   Repete a estrutura `rate`/`amount` para as três jurisdições (UF, Município, CBS), mas considerando a redução `pRedutor` aplicada à compra governamental.

#### 4.5.6. `regularTaxation` — Tributação Regular Hipotética

Quando há **condição resolutória ou suspensiva** (ex: alíquota zero condicionada a destinação específica), declara-se aqui qual seria a tributação caso a condição não se cumpra. Importante para apuração e fiscalização.

```json
"regularTaxation": {
  "situationCode": "101",
  "classCode": "RT0001",
  "stateEffectiveRate": 10.0,    "amount": 200.2,
  "municipalEffectiveRate": 5.0, "municipalAmount": 100.1,
  "cbsEffectiveRate": 12.0,      "cbsAmount": 240.24
}
```

*   **`situationCode` (CSTReg):** CST que aplicaria se a condição resolutória/suspensiva caísse.
*   **`classCode` (cClassTribReg):** Classificação tributária regular.
*   **Pares `stateEffectiveRate`/`amount`, `municipalEffectiveRate`/`municipalAmount`, `cbsEffectiveRate`/`cbsAmount`:** Alíquota efetiva e valor que seriam apurados.

#### 4.5.7. `zfmPresumedCredit` — Crédito Presumido ZFM (`gCredPresIBSZFM`)

Crédito presumido específico para fornecimentos a partir da Zona Franca de Manaus (art. 450 LC 214/2025).

```json
"zfmPresumedCredit": {
  "classificationCode": "IntermediateGoods",   // tpCredPresIBSZFM
  "amount": 123.45                              // vCredPresIBSZFM
}
```

*   **`classificationCode`:** Determina o percentual aplicável (55%, 75%, 90,25%, 100% — ver enum `IbsZfmPresumedCreditClassification` no Apêndice H).
*   **`amount`:** Valor do crédito presumido. Obrigatório quando `creditType = 02`.

### 4.6. `donationIndicator` e `competenceAdjustment`

#### 4.6.1. `donationIndicator` — Indicador de Doação (`indDoacao`)

Quando a operação é uma **doação** (ex: doação a entidade beneficente, transferência sem contraprestação), informe este campo no `IBSCBS` para que a apuração trate corretamente débitos/estornos. Valores: `"0"` (não doação) / `"1"` (doação). Campo de 1 caractere; informar apenas quando aplicável.

#### 4.6.2. `competenceAdjustment` — Ajuste de Competência (`gAjusteCompet`)

Reabre uma competência fiscal anterior para incluir um ajuste de IBS/CBS:

```json
"competenceAdjustment": {
  "assessmentPeriod": "2025-09",   // AAAA-MM (competApur)
  "ibsAmount": 5.0,                 // vIBS do ajuste
  "cbsAmount": 3.0                  // vCBS do ajuste
}
```

Aplicável tipicamente em notas com `purposeType = Credit` ou `Debit`.

---

## 5. Considerações Finais

A estrutura da API foi projetada para ser flexível e acomodar tanto o sistema tributário atual quanto o novo modelo da Reforma Tributária. Durante o período de transição, os grupos de tributos antigos (ICMS, PIS, COFINS) e novos (IS, IBSCBS) coexistirão.

É fundamental que os sistemas emissores consultem as tabelas oficiais (CST, cClassTrib, etc.) e sigam as regras de validação descritas no Manual do Contribuinte e nas Notas Técnicas para garantir a correta emissão e autorização dos documentos fiscais.

Para mais detalhes sobre regras de validação específicas, consulte a documentação da SEFAZ e as Notas Técnicas vigentes.

---

## 6. Apêndice C: Detalhamento dos Objetos de Recurso

Este apêndice detalha a estrutura dos principais objetos e sub-objetos referenciados no corpo da requisição da API.

### 6.1. AddressResource

Define a estrutura de um endereço, utilizada nos grupos `buyer`, `delivery`, `withdrawal` e `transportGroup`.

*   `street` (string): Logradouro do Endereço (xLgr). (Obrigatório)
*   `number` (string): Número do Endereço (nro). (Obrigatório)
*   `additionalInformation` (string): Complemento do Endereço (xCpl).
*   `district` (string): Bairro do Endereço (xBairro). (Obrigatório)
*   `city` (CityResource): Objeto contendo o código (`code`) e nome (`name`) do município. (Obrigatório)
*   `state` (string): Sigla da UF. (Obrigatório)
*   `postalCode` (string): Código de Endereçamento Postal (CEP).
*   `country` (string): Código ou nome do país. (Obrigatório)
*   `phone` (string): Telefone.

### 6.2. BuyerResource

Contém as informações cadastrais do destinatário da nota.

*   `name` (string): Nome ou Razão Social (xNome). (Obrigatório)
*   `federalTaxNumber` (integer): CNPJ ou CPF. (Obrigatório)
*   `tradeName` (string): Nome Fantasia (xFant).
*   `stateTaxNumber` (string): Inscrição Estadual (IE).
*   `stateTaxNumberIndicator` (enum): Indicador da IE do Destinatário (`TaxPayer`, `Exempt`, `NonTaxPayer`).
*   `address` (AddressResource): Objeto com os dados de endereço do destinatário. (Obrigatório)
*   `email` (string): E-mail do destinatário. (Obrigatório)
*   `type` (enum): Tipo de pessoa (`NaturalPerson`, `LegalEntity`).
*   `taxRegime` (enum): Regime de tributação.

### 6.3. DeliveryInformationResource

Define o local de entrega, **se e somente se** for diferente do endereço do destinatário.

*   `federalTaxNumber` (integer): CNPJ ou CPF do local de entrega.
*   `name` (string): Nome ou Razão Social.
*   `stateTaxNumber` (string): Inscrição Estadual.
*   `address` (AddressResource): Objeto com os dados completos do endereço de entrega.

### 6.4. WithdrawalInformationResource

Define o local de retirada, **se e somente se** for diferente do endereço do emitente.

*   `federalTaxNumber` (integer): CNPJ ou CPF do local de retirada.
*   `name` (string): Nome ou Razão Social.
*   `address` (AddressResource): Objeto com os dados completos do endereço de retirada.

### 6.5. GovernmentPurchaseResource

Detalha uma operação de compra por um órgão governamental. (gCompraGov)

*   `entityType` (enum): Tipo de ente governamental (`Union`, `State`, `Municipality`).
*   `rateReduction` (number): Percentual de redução de alíquota. (pRedutor)
*   `operationType` (enum): Tipo de operação com o governo (`Supply`, `Payment`, etc.). (tpOperGov)

### 6.6. TransportInformationResource

Agrupa todas as informações relacionadas ao transporte da mercadoria.

*   `freightModality` (enum): Modalidade do frete (`ByIssuer`, `ByReceiver`, etc.). (modFrete)
*   `transportGroup` (TransportGroupResource): Dados do transportador. (transporta)
*   `transportVehicle` (TransportVehicleResource): Dados do veículo principal. (veicTransp)
*   `reboque` (ReboqueResource): Dados do veículo reboque. (reboque)
*   `volume` (VolumeResource): Informações sobre os volumes transportados. (vol)
*   `transpRate` (TransportRateResource): Dados da retenção de ICMS do transporte. (retTransp)
*   `sealNumber` (string): Número dos lacres.

#### 6.6.1. TransportGroupResource

*   `name` (string): Nome/Razão Social do transportador.
*   `federalTaxNumber` (integer): CNPJ/CPF do transportador.
*   `stateTaxNumber` (string): Inscrição Estadual do transportador.
*   `address` (AddressResource): Endereço completo do transportador.

#### 6.6.2. TransportVehicleResource

*   `plate` (string): Placa do veículo. (placa)
*   `state` (string): UF de registro do veículo.
*   `rntc` (string): Registro Nacional de Transportadores Rodoviários de Carga.

#### 6.6.3. ReboqueResource

*   `plate` (string): Placa do reboque.
*   `state` (string): UF de registro do reboque.
*   `rntc` (string): RNTRC do reboque.

#### 6.6.4. VolumeResource

*   `volumeQuantity` (integer): Quantidade de volumes. (qVol)
*   `species` (string): Espécie dos volumes. (esp)
*   `brand` (string): Marca dos volumes. (marca)
*   `netWeight` (number): Peso líquido total (em Kg). (pesoL)
*   `grossWeight` (number): Peso bruto total (em Kg). (pesoB)

### 6.7. PaymentResource e PaymentDetailResource

Estrutura para detalhar as formas e os valores de pagamento da operação.

*   **PaymentResource**:
    *   `paymentDetail` (array[PaymentDetailResource]): Lista dos detalhes de pagamento.
    *   `payBack` (number): Valor do troco.
*   **PaymentDetailResource**:
    *   `method` (enum): Forma de pagamento (`Cash`, `CreditCard`, `InstantPayment`).
    *   `amount` (number): Valor do pagamento.
    *   `paymentType` (enum): Indicador da forma de pagamento (`InCash`, `Term`).
    *   `card` (CardResource): Detalhes da transação com cartão.

#### 6.7.1. CardResource

*   `federalTaxNumber` (string): CNPJ da credenciadora do cartão.
*   `flag` (enum): Bandeira do cartão (ex: `Visa`, `Mastercard`). (tBand)
*   `authorization` (string): Número de autorização da operação com cartões, PIX, boletos e outros pagamentos eletrônicos. (cAut)
*   `integrationPaymentType` (enum): Tipo de integração (`Integrated`, `NotIntegrated`). (tpIntegra)

### 6.8. BillingResource

Contém os dados de cobrança comercial, como fatura e duplicatas.

*   `bill` (BillResource): Dados da fatura.
*   `duplicates` (array[DuplicateResource]): Lista de duplicatas (parcelas).

#### 6.8.1. BillResource

*   `number` (string): Número da fatura. (nFat)
*   `originalAmount` (number): Valor original da fatura. (vOrig)
*   `discountAmount` (number): Valor do desconto. (vDesc)
*   `netAmount` (number): Valor líquido da fatura. (vLiq)

#### 6.8.2. DuplicateResource

*   `number` (string): Número da duplicata. (nDup)
*   `expirationOn` (string): Data de vencimento. (dVenc)
*   `amount` (number): Valor da duplicata. (vDup)


### 6.9. AdditionalInformationResource

Agrupa informações complementares, como observações para o fisco, documentos referenciados e processos.

*   `fisco` (string): Informações para o Fisco.
*   `taxpayer` (string): Informações para o contribuinte.
*   `xmlAuthorized` (array[integer]): Lista de CNPJs/CPFs autorizados a baixar o XML.
*   `taxDocumentsReference` (array[TaxDocumentsReferenceResource]): Documentos fiscais referenciados.
*   `referencedProcess` (array[ReferencedProcessResource]): Processos judiciais/administrativos referenciados.

#### 6.9.1. TaxDocumentsReferenceResource

*   `documentElectronicInvoice` (object): Contém a chave de acesso (`accessKey`) de uma NF-e/NFC-e referenciada.
*   `documentInvoiceReference` (object): Contém dados de uma nota fiscal modelo 1/1A referenciada.
*   `taxCouponInformation` (object): Contém dados de um cupom fiscal referenciado.

#### 6.9.2. ReferencedProcessResource

*   `identifierConcessory` (string): Identificador do processo.
*   `identifierOrigin` (integer): Indicador da origem do processo (ex: SEFAZ, Justiça Federal).

### 6.10. InvoiceItemResource

Detalha um item da nota fiscal.

*   `code` (string): Código do produto.
*   `description` (string): Descrição do produto.
*   `ncm` (string): Código NCM.
*   `cfop` (integer): Código CFOP.
*   `quantity` (number): Quantidade.
*   `unit` (string): Unidade de medida.
*   `unitAmount` (number): Valor unitário.
*   `totalAmount` (number): Valor total bruto.
*   `tax` (InvoiceItemTaxResource): Objeto com todos os tributos do item.
*   `vehicleDetail` (VehicleDetailResource): Detalhes específicos para itens que representam veículos novos. Consulte a seção **6.22. VehicleDetailResource** para o detalhamento completo de todos os campos.
*   `fuelDetail` (FuelResource): Detalhes se o item for um combustível.
*   `importDeclarations` (array[ImportDeclarationResource]): Detalhes de importação.
*   `taxDetermination` (TaxDeterminationResource): Grupo para cálculo automático de impostos.

### 6.11. InvoiceItemTaxResource

Agrupa todos os tributos incidentes sobre um item.

*   `totalTax` (number): Valor aproximado total de tributos (Lei da Transparência).
*   `icms` (IcmsTaxResource): Tributação do ICMS.
*   `ipi` (IPITaxResource): Tributação do IPI.
*   `pis` (PISTaxResource): Tributação do PIS.
*   `cofins` (CofinsTaxResource): Tributação do COFINS.
*   `IS` (ISTaxResource): Tributação do Imposto Seletivo.
*   `IBSCBS` (IBSCBSTaxResource): Tributação do IBS e CBS.

#### 6.11.1. IcmsTaxResource

*   `origin` (string): Origem da mercadoria.
*   `cst` (string): Código de Situação Tributária do ICMS.
*   `baseTax` (number): Base de cálculo do ICMS.
*   `rate` (number): Alíquota do ICMS (%).
*   `amount` (number): Valor do ICMS.
*   *...outros campos para ST, redução, diferimento, etc.*

#### 6.11.2. IPITaxResource

*   `cst` (string): Código de Situação Tributária do IPI.
*   `base` (number): Base de cálculo do IPI.
*   `rate` (number): Alíquota do IPI (%).
*   `amount` (number): Valor do IPI.

#### 6.11.3. PISTaxResource e CofinsTaxResource

*   `cst` (string): Código de Situação Tributária do PIS/COFINS.
*   `baseTax` (number): Base de cálculo.
*   `rate` (number): Alíquota (%).
*   `amount` (number): Valor do tributo.

### 6.12. ISTaxResource

Detalha a tributação do Imposto Seletivo para um item.

*   `situationCode` (string): Código de Situação Tributária do IS.
*   `classificationCode` (string): Código de Classificação Tributária do IS.
*   `basis` (number): Base de cálculo.
*   `rate` (number): Alíquota (%).
*   `amount` (number): Valor do imposto.

### 6.13. IBSCBSTaxResource

Detalha a tributação do IBS e da CBS para um item, conforme a Reforma Tributária.

*   `situationCode` (string): Código de Situação Tributária do IBS/CBS.
*   `classCode` (string): Código de Classificação Tributária.
*   `basis` (number): Base de cálculo.
*   `state` (IBSStateTaxResource): Detalhes do IBS Estadual.
*   `municipal` (IBSMunicipalTaxResource): Detalhes do IBS Municipal.
*   `cbs` (CBSTaxResource): Detalhes da CBS.
*   `monophase` (MonophaseIBSCBSTaxResource): Detalhes para tributação monofásica.
*   `operationalPresumedCredit` (OperationalPresumedCreditResource): Detalhes de crédito presumido.

#### 6.13.1. IBSStateTaxResource e IBSMunicipalTaxResource

*   `rate` (number): Alíquota do IBS (%).
*   `amount` (number): Valor do IBS.
*   `deferment` (object): Contém `rate` e `amount` do diferimento.
*   `reduction` (object): Contém `rateReduction` e `effectiveRate` da redução.

#### 6.13.2. CBSTaxResource

*   `rate` (number): Alíquota da CBS (%).
*   `amount` (number): Valor da CBS.
*   `deferment` (object): Contém `rate` e `amount` do diferimento.
*   `reduction` (object): Contém `rateReduction` e `effectiveRate` da redução.

### 6.14. Total (Schema de Totais)

Agrupa os valores totais consolidados de toda a nota fiscal.

*   `icms` (ICMSTotal): Totais do ICMS.
*   `issqn` (ISSQNTotal): Totais do ISSQN.
*   `withheldTaxes` (TotalsWithholdings): Totais de tributos retidos.
*   `isTotals` (ISTotalsResource): Totais do Imposto Seletivo.
*   `ibsCbsTotals` (IBSCBSTotalsResource): Totais de IBS e CBS.
*   `totalInvoiceAmount` (number): Valor total final da NF-e.

#### 6.14.1. ICMSTotal

*   `baseTax` (number): Somatório da base de cálculo do ICMS.
*   `icmsAmount` (number): Somatório do valor do ICMS.
*   `stCalculationBasisAmount` (number): Somatório da base de cálculo do ICMS-ST.
*   `stAmount` (number): Somatório do valor do ICMS-ST.
*   `productAmount` (number): Somatório do valor dos produtos.
*   `invoiceAmount` (number): Valor total da nota (regime antigo).

#### 6.14.2. TotalsWithholdings

*   `pisAmount` (number): Valor retido de PIS.
*   `cofinsAmount` (number): Valor retido de COFINS.
*   *...outros campos para CSLL, IRRF, etc.*

### 6.15. ISTotalsResource

Consolida o valor total do Imposto Seletivo da nota.

*   `amount` (number): Soma do valor do Imposto Seletivo de todos os itens.

### 6.16. IBSCBSTotalsResource


*   `basis` (number): Somatório da base de cálculo do IBS/CBS.
*   `ibs` (IBSTotalsResource): Objeto com os totais do IBS.
*   `cbs` (CBSTotalsResource): Objeto com os totais da CBS.
*   `monophase` (MonophaseTotalsResource): Objeto com os totais da tributação monofásica.

### 6.17. IBSTotalsResource

Agrega os totais do IBS.

*   `state` (IBSStateTotalsResource): Totais do IBS estadual.
*   `municipal` (IBSMunicipalTotalsResource): Totais do IBS municipal.
*   `totalAmount` (number): Valor total do IBS.
*   `presumedCreditAmount` (number): Valor total do crédito presumido.

### 6.18. CBSTotalsResource

Agrega os totais da CBS.

*   `defermentAmount` (number): Valor total do diferimento.
*   `returnedAmount` (number): Valor total de devolução.
*   `amount` (number): Valor total da CBS.
*   `presumedCreditAmount` (number): Valor total do crédito presumido.

### 6.19. PurchaseInformationResource

Agrupa informações de compra.

*   `commitmentNote` (string): Nota de Empenho.
*   `purchaseOrder` (string): Pedido de compra.
*   `contractNumber` (string): Número do contrato.

### 6.20. ExportResource

Contém informações sobre a exportação de mercadorias.
*   `state` (string): Sigla da UF de embarque.
*   `office` (string): Local de embarque.
*   `local` (string): Local de despacho.

### 6.21. IntermediateResource

Contém informações do intermediador da transação (marketplace, plataforma de delivery, etc.).
*   `federalTaxNumber` (integer): CNPJ do intermediador.
*   `identifier` (string): Identificador cadastrado no intermediador.

### 6.22. VehicleDetailResource

Este grupo contém as informações específicas para itens que representam **veículos novos** na nota fiscal. Corresponde ao grupo **`veicProd`** (campos J01 a J26) do leiaute oficial da NF-e, conforme definido no XSD `leiauteNFe_v4.00.xsd`.

**Quando utilizar:** Este grupo deve ser preenchido exclusivamente quando o item da nota fiscal é um veículo novo (0 km). É obrigatório para operações de venda realizadas por concessionárias, montadoras e revendedores de veículos novos. Cada item da nota pode conter apenas um grupo de produto específico (`vehicleDetail`, `fuelDetail` ou `medicineDetail`). Se mais de um for preenchido, apenas o primeiro encontrado será considerado, seguindo a ordem de precedência: medicamento, veículo, combustível.

**Campos:**

*   `operationType` (integer): **Tipo da Operação (`tpOp` — campo J02)**. Define o contexto comercial da venda do veículo. Este campo indica como a operação de venda está sendo realizada e influencia regras de faturamento e tributação.
    *   `0` = Outros (operações que não se enquadram nas demais categorias)
    *   `1` = Venda concessionária (venda realizada por uma concessionária autorizada)
    *   `2` = Faturamento direto para consumidor final (venda direta da montadora ao consumidor)
    *   `3` = Venda direta para grandes consumidores (ex: frotistas, governo, locadoras)
    *   **Validações:** Opcional no contrato da API. Quando informado, deve ser um dos valores acima (0, 1, 2 ou 3). A obrigatoriedade do preenchimento pode depender da regra de negócio aplicável à operação.

*   `chassis` (string): **Chassi do Veículo — VIN (`chassi` — campo J03)**. O número de identificação do veículo (Vehicle Identification Number), gravado no chassi. É o identificador único e universal do veículo, utilizado para rastreamento, registro e documentação em todo o mundo.
    *   **Validações:** Obrigatório. Deve conter exatamente **17 caracteres alfanuméricos** (letras maiúsculas de A a Z e dígitos de 0 a 9). Padrão: `[A-Z0-9]{17}`.
    *   **Exemplo:** `9BWZZZ377VT004251`

*   `colorCode` (string): **Código da Cor do Veículo (`cCor` — campo J04)**. Código interno utilizado pela montadora para identificar a cor do veículo. Cada fabricante possui sua própria tabela de códigos de cores.
    *   **Validações:** Obrigatório. Máximo de **4 caracteres**.
    *   **Exemplo:** `A1B2`

*   `colorDescription` (string): **Descrição da Cor (`xCor` — campo J05)**. Nome por extenso da cor do veículo, em linguagem compreensível. Deve corresponder ao código informado em `colorCode`.
    *   **Validações:** Obrigatório. Máximo de **40 caracteres**.
    *   **Exemplo:** `Prata Lunar Metálico`

*   `enginePower` (string): **Potência do Motor (`pot` — campo J06)**. Potência máxima do motor do veículo, expressa em cavalos-vapor (CV). Este valor consta no certificado de registro do veículo.
    *   **Validações:** Obrigatório. Máximo de **4 caracteres**.
    *   **Exemplo:** `150` (equivale a 150 CV)

*   `engineDisplacement` (string): **Cilindradas (`cilin` — campo J07)**. Capacidade volumétrica do motor, expressa em centímetros cúbicos (CC). Indica o volume total dos cilindros do motor.
    *   **Validações:** Obrigatório. Máximo de **4 caracteres**.
    *   **Exemplo:** `1998` (equivale a 2.0 litros)

*   `netWeight` (string): **Peso Líquido (`pesoL` — campo J08)**. Peso do veículo sem carga, passageiros ou acessórios opcionais, expresso em quilogramas.
    *   **Validações:** Obrigatório. Máximo de **9 caracteres**.
    *   **Exemplo:** `1250`

*   `grossWeight` (string): **Peso Bruto (`pesoB` — campo J09)**. Peso total do veículo incluindo a capacidade máxima de carga permitida, expresso em quilogramas.
    *   **Validações:** Obrigatório. Máximo de **9 caracteres**.
    *   **Exemplo:** `1650`

*   `serialNumber` (string): **Número de Série (`nSerie` — campo J10)**. Número de série do veículo atribuído pelo fabricante. Serve como identificador adicional de produção.
    *   **Validações:** Obrigatório. Máximo de **9 caracteres**.
    *   **Exemplo:** `ABC123456`

*   `fuelType` (string): **Tipo de Combustível (`tpComb` — campo J11)**. Código numérico que identifica o tipo de combustível utilizado pelo veículo, conforme a **Tabela RENAVAM**. Os códigos mais comuns são:
    *   `01` = Álcool
    *   `02` = Gasolina
    *   `03` = Diesel
    *   `08` = Elétrico
    *   `16` = Álcool/Gasolina (flex)
    *   `17` = Gasolina/Álcool/GNV (flex + GNV)
    *   `18` = Gasolina/Elétrico (híbrido)
    *   **Validações:** Obrigatório. Máximo de **2 caracteres**. Deve corresponder a um código válido da Tabela RENAVAM.

*   `engineNumber` (string): **Número do Motor (`nMotor` — campo J12)**. Número de identificação do motor do veículo, gravado no bloco do motor pelo fabricante.
    *   **Validações:** Obrigatório. Máximo de **21 caracteres**.
    *   **Exemplo:** `MOT123456789012`

*   `maximumTractionCapacity` (string): **Capacidade Máxima de Tração — CMT (`CMT` — campo J13)**. Peso máximo que o veículo pode tracionar, incluindo seu próprio peso e a carga do reboque, expresso em toneladas com até 4 casas decimais.
    *   **Validações:** Obrigatório. Máximo de **9 caracteres**.
    *   **Exemplo:** `1.5000` (equivale a 1,5 toneladas)

*   `wheelBase` (string): **Distância entre Eixos (`dist` — campo J14)**. Distância medida entre o centro do eixo dianteiro e o centro do eixo traseiro do veículo, expressa em milímetros.
    *   **Validações:** Obrigatório. Máximo de **4 caracteres**.
    *   **Exemplo:** `2620` (equivale a 2.620 mm)

*   `modelYear` (integer): **Ano Modelo de Fabricação (`anoMod` — campo J16)**. Ano do modelo do veículo, conforme definido pelo fabricante. O ano modelo pode ser diferente do ano de fabricação (ex: veículo fabricado em 2025 com ano modelo 2026).
    *   **Validações:** Obrigatório. Deve conter exatamente **4 dígitos**.
    *   **Exemplo:** `2026`

*   `manufactureYear` (integer): **Ano de Fabricação (`anoFab` — campo J17)**. Ano em que o veículo foi efetivamente produzido na linha de montagem.
    *   **Validações:** Obrigatório. Deve conter exatamente **4 dígitos**.
    *   **Exemplo:** `2025`

*   `paintType` (string): **Tipo de Pintura (`tpPint` — campo J18)**. Código que identifica o tipo de acabamento da pintura do veículo (ex: sólida, metálica, perolizada).
    *   **Validações:** Obrigatório. Exatamente **1 caractere**.
    *   **Exemplo:** `M` (Metálica)

*   `vehicleType` (string): **Tipo de Veículo (`tpVeic` — campo J19)**. Código numérico que classifica o tipo do veículo conforme a **Tabela RENAVAM** (ex: automóvel, caminhão, motocicleta). Os códigos mais comuns são:
    *   `02` = Ciclomotor
    *   `03` = Motoneta
    *   `04` = Motocicleta
    *   `05` = Triciclo
    *   `06` = Automóvel
    *   `13` = Camioneta
    *   `14` = Caminhão
    *   `17` = Micro-ônibus
    *   `22` = Caminhão-trator
    *   **Validações:** Obrigatório. Máximo de **2 caracteres**. Deve corresponder a um código válido da Tabela RENAVAM.

*   `vehicleSpecies` (integer): **Espécie de Veículo (`espVeic` — campo J20)**. Código numérico que classifica a finalidade de uso do veículo conforme a **Tabela RENAVAM**:
    *   `1` = Passageiro
    *   `2` = Carga
    *   `3` = Misto (passageiro e carga)
    *   `4` = Corrida
    *   `5` = Tração
    *   `6` = Especial
    *   **Validações:** Obrigatório. Deve ser um dígito válido conforme a tabela.

*   `vinCondition` (string): **Condição do VIN — Chassi (`VIN` — campo J21)**. Indica se o número do chassi (VIN) do veículo foi remarcado ou se encontra em condição original de fábrica. A remarcação ocorre quando o chassi original foi danificado e precisou ser regravado pelo DETRAN.
    *   `R` = Remarcado (chassi regravado)
    *   `N` = Normal (chassi original de fábrica)
    *   **Validações:** Obrigatório. Deve ser `R` ou `N`.

*   `vehicleCondition` (integer): **Condição do Veículo (`condVeic` — campo J22)**. Indica o estado de acabamento do veículo no momento da venda. Veículos inacabados ou semi-acabados geralmente são comercializados entre montadoras e encarroçadoras para finalização.
    *   `1` = Acabado (veículo pronto para uso, com todos os componentes)
    *   `2` = Inacabado (veículo sem algum componente essencial, necessitando acabamento)
    *   `3` = Semi-acabado (veículo parcialmente montado, como chassis-cabina)
    *   **Validações:** Obrigatório. Deve ser 1, 2 ou 3.

*   `brandModelCode` (string): **Código Marca Modelo (`cMod` — campo J23)**. Código numérico que identifica a combinação de marca e modelo do veículo na **Tabela RENAVAM**. Cada veículo possui um código único que identifica, por exemplo, "Volkswagen Gol 1.0" ou "Toyota Corolla 2.0".
    *   **Validações:** Obrigatório. Máximo de **6 caracteres** numéricos.
    *   **Exemplo:** `123456`

*   `denatranColorCode` (string): **Código da Cor DENATRAN (`cCorDENATRAN` — campo J24)**. Código padronizado de cores definido pelo DENATRAN (Departamento Nacional de Trânsito). Diferente do `colorCode` (que é do fabricante), este código é a classificação oficial de cores para registro e documentação veicular:
    *   `01` = Amarelo | `02` = Azul | `03` = Bege | `04` = Branca
    *   `05` = Cinza | `06` = Dourada | `07` = Grená | `08` = Laranja
    *   `09` = Marrom | `10` = Prata | `11` = Preta | `12` = Rosa
    *   `13` = Roxa | `14` = Verde | `15` = Vermelha | `16` = Fantasia
    *   **Validações:** Obrigatório. Máximo de **2 caracteres** numéricos. Deve ser um dos códigos acima.

*   `seatingCapacity` (integer): **Lotação — Capacidade de Passageiros (`lota` — campo J25)**. Quantidade máxima de passageiros que o veículo pode transportar sentados, **incluindo o motorista**. Este valor consta no certificado de registro do veículo.
    *   **Validações:** Obrigatório. Máximo de **3 dígitos**.
    *   **Exemplo:** `5` (automóvel padrão com 5 lugares)

*   `restrictionType` (integer): **Tipo de Restrição (`tpRest` — campo J26)**. Indica se existe alguma restrição legal ou financeira sobre o veículo que limita sua comercialização ou transferência de propriedade:
    *   `0` = Não há restrição (veículo livre para venda e transferência)
    *   `1` = Alienação Fiduciária (veículo dado como garantia em financiamento)
    *   `2` = Arrendamento Mercantil (veículo em contrato de leasing)
    *   `3` = Reserva de Domínio (vendedor mantém a propriedade até quitação total)
    *   `4` = Penhor de Veículos (veículo dado como garantia em empréstimo)
    *   `9` = Outras restrições
    *   **Validações:** Obrigatório. Deve ser um dos valores acima (0, 1, 2, 3, 4 ou 9).

> **Nota Importante:** O grupo `vehicleDetail` é mutuamente exclusivo com `fuelDetail` (combustível) e `medicineDetail` (medicamento). Cada item da nota fiscal pode conter no máximo **um** desses grupos de produto específico. Se mais de um for preenchido por engano, a API seguirá a ordem de precedência: medicamento > veículo > combustível.

---

## 7. Apêndice D: Erros Comuns e Suas Soluções

Esta seção descreve as rejeições mais comuns durante o processo de emissão da NF-e/NFC-e e fornece orientações sobre como corrigi-las.

### 7.1. Rejeições Gerais

**Rejeição 204: Duplicidade de NF-e**
*   **O que significa:** Já existe uma nota fiscal com o mesmo número, série e CNPJ do emitente na base de dados da SEFAZ.
*   **Causa Comum:** Tentativa de reenviar uma nota que já foi autorizada ou está em processamento, ou erro no controle de numeração sequencial.
*   **Como Corrigir:** Verifique o status da nota fiscal original. Se ela já foi autorizada, não a reenvie. Se precisa emitir uma nova nota, incremente o campo `number` para o próximo valor disponível na sequência da `serie`.

**Rejeição 225: Falha no Schema XML**
*   **O que significa:** A estrutura do JSON enviado não corresponde ao leiaute esperado pela API.
*   **Causa Comum:** Campos com tipos de dados incorretos (ex: enviar um texto onde se espera um número), nomes de propriedades errados, ou estrutura de objetos aninhados incorreta.
*   **Como Corrigir:** Revise o corpo da requisição e compare-o com a especificação OpenAPI e os exemplos fornecidos nesta documentação. Preste atenção especial aos tipos de dados e à hierarquia dos objetos.

**Rejeição 210: IE do destinatário inválida**
*   **O que significa:** A Inscrição Estadual (`stateTaxNumber`) informada para o comprador (`buyer`) não é válida para a UF de destino.
*   **Causa Comum:** Erro de digitação, IE inexistente ou IE de uma UF diferente da informada no endereço do comprador.
*   **Como Corrigir:** Confirme a Inscrição Estadual correta do destinatário. Se o destinatário for isento ou não contribuinte, ajuste o campo `stateTaxNumberIndicator` para `Exempt` ou `NonTaxPayer` e não envie o campo `stateTaxNumber`.

**Rejeição 610: Valor total da NF-e difere do somatório dos valores que compõem o valor total**
*   **O que significa:** O campo `totals.icms.invoiceAmount` não bate com a soma dos valores dos itens e outros campos que compõem o total.
*   **Causa Comum:** Erro de cálculo na somatória de `items.totalAmount` mais frete, seguro, despesas acessórias, impostos, e subtraindo os descontos.
*   **Como Corrigir:** Recalcule o valor total da nota. A fórmula básica é: `vProd` (soma de `totalAmount` dos itens) - `vDesc` + `vST` + `vFrete` + `vSeg` + `vOutro` + `vIPI` + `vIPIDevol`. Com a RTC, o campo `totalInvoiceAmount` também deve ser validado, incluindo os novos impostos.

**Rejeição 321: NF-e de devolução de mercadoria não possui documento fiscal referenciado**
*   **O que significa:** A nota foi emitida com `purposeType` = `Devolution`, mas não foi informada a chave de acesso da nota original que está sendo devolvida.
*   **Causa Comum:** Esquecer de preencher o grupo `additionalInformation.taxDocumentsReference`.
*   **Como Corrigir:** Adicione o grupo `taxDocumentsReference` dentro de `additionalInformation`, contendo um objeto `documentElectronicInvoice` com a `accessKey` da NF-e que originou a devolução.

### 7.2. Rejeições da Reforma Tributária (RTC)

**Rejeição 1115: IBS/CBS não informado**
*   **O que significa:** Para uma operação sob o novo regime, o grupo `IBSCBS` não foi informado em um ou mais itens.
*   **Causa Comum:** A operação já se enquadra nas regras da RTC, mas o sistema emissor ainda não está enviando o grupo `items.tax.IBSCBS`.
*   **Como Corrigir:** Para cada item da nota, adicione o objeto `IBSCBS` dentro de `tax`, preenchendo os campos obrigatórios como `situationCode`, `classCode`, `basis` e os subgrupos `state`, `municipal` e `cbs`.

**Rejeição 1023: Classificação Tributária do IBS/CBS informada inexistente**
*   **O que significa:** O código informado em `items.tax.IBSCBS.classCode` não existe na tabela oficial `cClassTrib` da SEFAZ.
*   **Causa Comum:** Erro de digitação ou uso de um código desatualizado.
*   **Como Corrigir:** Consulte a tabela `cClassTrib` mais recente, disponível no Portal Nacional da NF-e, e utilize um código válido que corresponda à tributação do item.

**Rejeição 1024: Classificação Tributária do IBS e da CBS incompatível com o CST informado**
*   **O que significa:** A combinação entre o `situationCode` (CST) e o `classCode` (Classificação Tributária) não é permitida.
*   **Causa Comum:** Um `classCode` que representa uma isenção foi combinado com um `situationCode` de tributação integral, por exemplo.
*   **Como Corrigir:** Verifique a tabela `cClassTrib`. Ela contém as combinações válidas entre CST e Classificação Tributária. Ajuste um dos dois campos para que a combinação seja válida.

**Rejeição 1104: Valor da Base de cálculo do IBS e CBS difere do somatório dos valores que a compõem**
*   **O que significa:** O valor informado em `items.tax.IBSCBS.basis` não corresponde à soma dos valores que formam a base de cálculo do item.
*   **Causa Comum:** Erro no cálculo da base de cálculo, que geralmente é `vProd` - `vDesc` + `vFrete` + `vSeg` + `vOutro` + `vII` + `vIPI`.
*   **Como Corrigir:** Recalcule o campo `basis` para cada item, garantindo que ele reflita a soma correta dos valores que compõem a base de cálculo dos novos tributos.

**Rejeição 1026: Alíquota do IBS da UF inválida**
*   **O que significa:** A alíquota do IBS estadual (`items.tax.IBSCBS.state.rate`) não corresponde à alíquota vigente para o período de emissão.
*   **Causa Comum:** Utilização de uma alíquota incorreta. Durante o período de transição, as alíquotas são fixas (ex: 0,1% para 2025/2026).
*   **Como Corrigir:** Ajuste a alíquota para o valor correto definido na legislação da Reforma Tributária para o ano de emissão da nota. Consulte a documentação para os valores vigentes.

**Rejeição 1001: NF-e com finalidade de débito ou crédito somente para IBS/CBS**
*   **O que significa:** Uma nota com finalidade de Débito (`finNFe=6`) ou Crédito (`finNFe=5`) continha grupos de tributos do regime antigo (ICMS, IPI, PIS, COFINS).
*   **Causa Comum:** Envio de uma nota de ajuste fiscal da RTC contendo, indevidamente, tributos do modelo antigo.
*   **Como Corrigir:** Remova completamente os grupos `icms`, `ipi`, `pis`, `cofins` e `icmsDestination` do objeto `tax` de todos os itens da nota. Notas de débito e crédito são exclusivas para ajustes de IBS e CBS.
*   **Exemplo Incorreto:**
    ```json
    {
      "purposeType": "Credit",
      "creditType": "valueReduction",
      // ... outros dados da nota
      "items": [
        {
          // ... dados do item
          "tax": {
            // INCORRETO: Grupos do regime antigo não são permitidos
            "icms": { "origin": "0", "cst": "90" },
            "pis": { "cst": "99" },
            "cofins": { "cst": "99" },
            // CORRETO: Apenas o grupo IBSCBS deve ser usado
            "IBSCBS": {
              "situationCode": "910",
              "classCode": "RT0001",
              "basis": 100.00,
              "cbs": { "amount": -12.00 } // Valor negativo para ajuste
            }
          }
        }
      ]
    }
    ```
*   **Exemplo Corrigido:**
    ```json
    {
      "purposeType": "Credit",
      "creditType": "valueReduction",
      // ... outros dados da nota
      "items": [
        {
          // ... dados do item
          "tax": {
            // CORRETO: Apenas o grupo IBSCBS é informado
            "IBSCBS": {
              "situationCode": "910",
              "classCode": "RT0001",
              "basis": 100.00,
              "cbs": { "amount": -12.00 } // Valor negativo para ajuste
            }
          }
        }
      ]
    }
    ```


---

## 9. Apêndice F: Boas Práticas para Integração

Para garantir uma integração mais eficiente, robusta e resiliente com a API de emissão de NF-e, recomendamos seguir as práticas listadas abaixo.

### 9.1. Controle de Numeração e Série

*   O controle da numeração sequencial (`number`) para cada série (`serie`) pode ser realizado tanto pelo sistema cliente quanto pelo nosso sistema. Independentemente de quem realiza o controle, é fundamental evitar a "Rejeição 204: Duplicidade de NF-e". Além disso, o sistema cliente deve sempre verificar a ocorrência de pulos na sequência numérica. Caso um número não seja utilizado, é necessário solicitar a sua **inutilização** para evitar problemas com o Fisco.
*   **Alteração de Série:** Sempre que for necessário alterar ou iniciar o uso de uma nova série fiscal, é um requisito mandatório que o cadastro da Inscrição Estadual do emitente seja previamente atualizado no sistema NFE.io para o uso desta nova série. Essa obrigação existe independentemente de qual sistema realiza o controle da numeração.

### 9.2. Validação de Dados Pré-Envio

*   **Reduza Chamadas Desnecessárias:** Antes de enviar os dados para a API, realize o máximo de validações possível no seu sistema. Isso inclui:
    *   **Validação de Dados Cadastrais e Endereço:** Para garantir a validade dos dados cadastrais do emitente e do destinatário, recomendamos o uso de nossas APIs de consulta. Elas permitem verificar se CNPJs e CPFs são válidos, se a Inscrição Estadual está ativa e vinculada ao CNPJ correto, e também consultar endereços a partir do CEP. A utilização dessas APIs evita rejeições por dados cadastrais ou de endereço incorretos.
    *   Garantir que campos obrigatórios estão preenchidos de acordo com a operação (ex: CFOP, NCM).

### 9.3. Tratamento de Erros e Rejeições

*   **Logs Detalhados:** Nosso sistema mantém um histórico completo e detalhado de todas as requisições (JSON enviado) e respostas (JSON recebido) por um longo período. Em caso de erros, esses logs são uma ferramenta poderosa para análise e depuração, facilitando a identificação da causa raiz do problema e agilizando o suporte técnico.
*   **Mecanismo de Retentativa:** Para erros de rede ou instabilidade momentânea da SEFAZ (ex: timeouts, erros 5xx), nosso sistema já possui um mecanismo de retentativa com *exponential backoff*. Isso evita que o cliente precise se preocupar em implementar essa lógica, pois gerenciamos as tentativas de reenvio automaticamente em caso de falhas temporárias.

### 9.4. Gerenciamento do Ciclo de Vida da NF-e

*   **Consulta de Status (Webhooks):** Após o envio de uma nota, o status inicial pode ser "Processando". Para obter o status final (como "Emitida" ou "Erro"), nosso sistema trabalha com o conceito de **webhooks**. Em vez de implementar uma rotina de consulta periódica, você deve configurar um endpoint no seu sistema para receber nossas notificações automáticas assim que o processamento for concluído. Isso torna a comunicação mais eficiente e em tempo real.
*   **Armazenamento Local:** Embora a responsabilidade legal pelo armazenamento seja do emitente, nosso sistema armazena todos os dados e o arquivo XML de cada NF-e autorizada pelo período mínimo de 5 anos. Você pode fazer o download do XML e do DANFE em PDF a qualquer momento através de nossa plataforma, garantindo a conformidade fiscal.
*   **Esteja Preparado para a Contingência:** Sistemas da SEFAZ podem ficar indisponíveis. Para simplificar sua integração, o modo de emissão em contingência pode ser configurado diretamente no cadastro da sua Inscrição Estadual em nossa plataforma. Com essa configuração, nosso sistema gerencia automaticamente a entrada e saída do modo de contingência quando necessário, permitindo que sua operação comercial continue sem interrupções. Caso prefira, você ainda pode gerenciar a contingência manualmente.

### 9.5. Performance e Eficiência

*   **Mantenha Tabelas Auxiliares Atualizadas:** Mantenha uma cópia local e atualizada das tabelas de referência publicadas pelo governo, como as de NCM, CEST, CFOP e, especialmente, as novas tabelas da Reforma Tributária (`cClassTrib`, `cCredPres`). Isso evita a necessidade de consultas externas a cada emissão.
*   **Evite Dados Desnecessários:** Envie apenas os campos e grupos necessários para a sua operação. Omitir grupos opcionais que não se aplicam (como `delivery` se a entrega for no endereço do comprador) torna o payload mais limpo e a validação mais rápida.

### 9.6. Segurança

*   **Proteja suas Credenciais:** Trate as chaves de acesso à API (API Keys) e os certificados digitais como informações altamente sensíveis. Não as exponha no código-fonte do lado do cliente (frontend) e armazene-as de forma segura no seu backend.

## 8. Apêndice E: Cancelamento, Inutilização e Devolução

É comum haver dúvidas sobre qual procedimento adotar para corrigir ou anular uma operação fiscal. Este apêndice esclarece a diferença entre os três principais mecanismos.

### 8.1. Cancelamento

*   **O que é:** É o ato de invalidar uma NF-e **autorizada**, tornando-a sem efeito fiscal.
*   **Quando usar:** Quando a operação comercial não se concretizou (ex: desistência da compra) e, crucialmente, **a mercadoria ainda não circulou**.
*   **Regras Principais:**
    *   Deve ser solicitado dentro de um prazo legal, geralmente 24 horas após a autorização.
    *   A mercadoria não pode ter saído do estabelecimento emitente.
    *   O destinatário não pode ter realizado a "Ciência da Emissão".

### 8.2. Inutilização de Numeração

*   **O que é:** É o processo de comunicar à SEFAZ que uma faixa de números de NF-e não foi e não será utilizada.
*   **Quando usar:** Quando ocorre uma **quebra na sequência da numeração** das notas. Por exemplo, a nota 100 foi emitida e a próxima a ser emitida é a 102, deixando o número 101 vago.
*   **Regras Principais:**
    *   A inutilização se aplica apenas a números que não foram usados em nenhuma NF-e (nem mesmo em uma nota rejeitada ou denegada).
    *   Serve para o Fisco saber que aquele "buraco" na sequência não é uma sonegação, mas sim uma falha técnica ou operacional.

### 8.3. Nota Fiscal de Devolução

*   **O que é:** É a emissão de uma nova NF-e (com `purposeType` = `Devolution`) para anular os efeitos de uma operação anterior.
*   **Quando usar:** Quando a mercadoria circulou e o destinatário a está devolvendo, seja por recusa no recebimento ou por devolução após a entrega. É a única forma de anular uma operação após a circulação do bem.
*   **Regras Principais:**
    *   É uma nota de entrada (`operationType` = `Incoming`) para o emitente original.
    *   Deve obrigatoriamente referenciar a chave de acesso da NF-e original que está sendo devolvida.
    *   Os impostos são "espelhados" para anular o débito da nota de saída.

:::note NFC-e (modelo 65)

Os mesmos mecanismos valem para a NFC-e, alterando apenas o recurso de endpoint (`consumerinvoices` no lugar de `productinvoices`):

*   **Cancelamento:** `DELETE /v2/companies/{companyId}/consumerinvoices/{invoiceId}`. Observe que, por ser uma operação **presencial com consumidor final**, o prazo legal de cancelamento da NFC-e costuma ser mais curto que o da NF-e (em diversas UFs, até 30 minutos após a autorização).
*   **Inutilização de numeração:** `POST /v2/companies/{companyId}/consumerinvoices/disablement`.

:::

---

## 10. Apêndice G: Tabela de Referência - CST e Classificação Tributária (IBS/CBS)

A tabela a seguir detalha os códigos de Situação Tributária (`situationCode`) e de Classificação Tributária (`classCode`) para o IBS e a CBS, conforme a Reforma Tributária. A combinação correta desses códigos é essencial para a validação da NF-e no novo regime.

| SituationCode (CST) | Descrição do CST | ClassCode (cClassTrib) | Descrição do ClassCode |
|:---|:---|:---|:---|
|000|Tributação integral|000001|Situações tributadas integralmente pelo IBS e CBS.|
|000|Tributação integral|000002|Exploração de via, observado o art. 11 da Lei Complementar nº 214, de 2025.|
|000|Tributação integral|000003|Regime automotivo - projetos incentivados, observado o art. 311 da Lei Complementar nº 214, de 2025.|
|000|Tributação integral|000004|Regime automotivo - projetos incentivados, observado o art. 312 da Lei Complementar nº 214, de 2025.|
|010|Tributação com alíquotas uniformes - operações do FGTS|010001|Operações do FGTS não realizadas pela Caixa Econômica Federal, observado o art. 212 da Lei Complementar nº 214, de 2025.|
|011|Tributação com alíquotas uniformes reduzidas em 60%|011001|Planos de assistência funerária, observado o art. 236 da Lei Complementar nº 214, de 2025.|
|011|Tributação com alíquotas uniformes reduzidas em 60%|011002|Planos de assistência à saúde, observado o art. 237 da Lei Complementar nº 214, de 2025.|
|011|Tributação com alíquotas uniformes reduzidas em 60%|011003|Intermediação de planos de assistência à saúde, observado o art. 240 da Lei Complementar nº 214, de 2025.|
|011|Tributação com alíquotas uniformes|011004|Concursos e prognósticos, observado o art. 246 da Lei Complementar nº 214, de 2025.|
|011|Tributação com alíquotas uniformes reduzidas em 30%|011005|Planos de assistência à saúde de animais domésticos, observado o art. 243 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200001|Aquisições de máquinas, de aparelhos, de instrumentos, de equipamentos, de matérias-primas, de produtos intermediários e de materiais de embalagem realizadas entre empresas autorizadas a operar em zonas de processamento de exportação, observado o art. 103 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200002|Fornecimento ou importação de tratores, máquinas e implementos agrícolas, destinados a produtor rural não contribuinte, e de veículos de transporte de carga destinados a transportador autônomo de carga pessoa física não contribuinte, observado o art. 110 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200003|Vendas de produtos destinados à alimentação humana relacionados no Anexo I da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, que compõem a Cesta Básica Nacional de Alimentos, criada nos termos do art. 8º da Emenda Constitucional nº 132, de 20 de dezembro de 2023, observado o art. 125 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200004|Venda de dispositivos médicos com a especificação das respectivas classificações da NCM/SH previstas no Anexo XII da Lei Complementar nº 214, de 2025, observado o art. 144 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200005|Venda de dispositivos médicos com a especificação das respectivas classificações da NCM/SH previstas no Anexo IV da Lei Complementar nº 214, de 2025, quando adquiridos por órgãos da administração pública direta, autarquias e fundações públicas, observado o art. 144 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200006|Situação de emergência de saúde pública reconhecida pelo Poder Legislativo federal, estadual, distrital ou municipal competente, ato conjunto do Ministro da Fazenda e do Comitê Gestor do IBS poderá ser editado, a qualquer momento, para incluir dispositivos não listados no Anexo XIII da Lei Complementar nº 214, de 2025, limitada a vigência do benefício ao período e à localidade da emergência de saúde pública, observado o art. 144 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200007|Fornecimento dos dispositivos de acessibilidade próprios para pessoas com deficiência relacionados no Anexo XIV da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 145 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200008|Fornecimento dos dispositivos de acessibilidade próprios para pessoas com deficiência relacionados no Anexo V da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, quando adquiridos por órgãos da administração pública direta, autarquias, fundações públicas e entidades imunes, observado o art. 145 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200009|Fornecimento dos medicamentos relacionados no Anexo XIV da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 146 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200010|Fornecimento dos medicamentos registrados na Anvisa, quando adquiridos por órgãos da administração pública direta, autarquias, fundações públicas e entidades imunes, observado o art. 146 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200011|Fornecimento das composições para nutrição enteral e parenteral, composições especiais e fórmulas nutricionais destinadas às pessoas com erros inatos do metabolismo relacionadas no Anexo VI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, quando adquiridas por órgãos da administração pública direta, autarquias e fundações públicas, observado o art. 146 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200012|Situação de emergência de saúde pública reconhecida pelo Poder Legislativo federal, estadual, distrital ou municipal competente, ato conjunto do Ministro da Fazenda e do Comitê Gestor do IBS poderá ser editado, a qualquer momento, para incluir dispositivos não listados no Anexo XIV da Lei Complementar nº 214, de 2025, limitada a vigência do benefício ao período e à localidade da emergência de saúde pública, observado o art. 146 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200013|Fornecimento de tampões higiênicos, absorventes higiênicos internos ou externos, descartáveis ou reutilizáveis, calcinhas absorventes e coletores menstruais, observado o art. 147 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200014|Fornecimento dos produtos hortícolas, frutas e ovos, relacionados no Anexo XV da Lei Complementar nº 214 , de 2025, com a especificação das respectivas classificações da NCM/SH e desde que não cozidos, observado o art. 148 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200015|Venda de automóveis de passageiros de fabricação nacional de, no mínimo, 4 (quatro) portas, inclusive a de acesso ao bagageiro, quando adquiridos por motoristas profissionais que exerçam, comprovadamente, em automóvel de sua propriedade, atividade de condutor autônomo de passageiros, na condição de titular de autorização, permissão ou concessão do poder público, e que destinem o automóvel à utilização na categoria de aluguel (táxi), ou por pessoas com deficiência física, visual, auditiva, deficiência mental severa ou profunda, transtorno do espectro autista, com prejuízos na comunicação social e em padrões restritos ou repetitivos de comportamento de nível moderado ou grave, nos termos da legislação relativa à matéria, observado o disposto no art. 149 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200016|Prestação de serviços de pesquisa e desenvolvimento por Instituição Científica, Tecnológica e de Inovação (ICT) sem fins lucrativos para a administração pública direta, autarquias e fundações públicas ou para o contribuinte sujeito ao regime regular do IBS e da CBS, observado o disposto no art. 156 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200017|Operações relacionadas ao FGTS, considerando aquelas necessárias à aplicação da Lei nº 8.036, de 1990, realizadas pelo Conselho Curador ou Secretaria Executiva do FGTS, observado o art. 212 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200018|Operações de resseguro e retrocessão ficam sujeitas à incidência à alíquota zero, inclusive quando os prêmios de resseguro e retrocessão forem cedidos ao exterior, observado o art. 223 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200019|Importador dos serviços financeiros seja contribuinte que realize as operações de que tratam os incisos I a V do caput do art. 182, será aplicada alíquota zero na importação, sem prejuízo da manutenção do direito de dedução dessas despesas da base de cálculo do IBS e da CBS, segundo, observado o art. 231 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200020|Operação praticada por sociedades cooperativas optantes por regime específico do IBS e CBS, quando o associado destinar bem ou serviço à cooperativa de que participa, e a cooperativa fornecer bem ou serviço ao associado sujeito ao regime regular do IBS e da CBS, observado o art. 271 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200021|Serviços de transporte público coletivo de passageiros ferroviário e hidroviário urbanos, semiurbanos e metropolitanos, observado o art. 285 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200022|Operação originada fora da Zona Franca de Manaus que destine bem material industrializado de origem nacional a contribuinte estabelecido na Zona Franca de Manaus que seja habilitado nos termos do art. 442 da Lei Complementar nº 214, de 2025, e sujeito ao regime regular do IBS e da CBS ou optante pelo regime do Simples Nacional de que trata o art. 12 da Lei Complementar nº 123, de 2006, observado o art. 445 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200023|Operação realizada por indústria incentivada que destine bem material intermediário para outra indústria incentivada na Zona Franca de Manaus, desde que a entrega ou disponibilização dos bens ocorra dentro da referida área, observado o art. 448 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero|200024|Operação originada fora das Áreas de Livre Comércio que destine bem material industrializado de origem nacional a contribuinte estabelecido nas Áreas de Livre Comércio que seja habilitado nos termos do art. 456 da Lei Complementar nº 214, de 2025, e sujeito ao regime regular do IBS e da CBS ou optante pelo regime do Simples Nacional de que trata o art. 12 da Lei Complementar nº 123, de 2006, observado o art. 463 da Lei Complementar nº 214, de 2025.|
|200|Alíquota zero apenas CBS e reduzida em 60% para IBS|200025|Fornecimento dos serviços de educação relacionados ao Programa Universidade para Todos (Prouni), instituído pela Lei nº 11.096, de 13 de janeiro de 2005, observado o art. 308 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 80%|200026|Locação de imóveis localizados nas zonas reabilitadas, pelo prazo de 5 (cinco) anos, contado da data de expedição do habite-se, e relacionados a projetos de reabilitação urbana de zonas históricas e de áreas críticas de recuperação e reconversão urbanística dos Municípios ou do Distrito Federal, a serem delimitadas por lei municipal ou distrital, observado o art. 158 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 70%|200027|Operações de locação, cessão onerosa e arrendamento de bens imóveis, observado o art. 261 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200028|Fornecimento dos serviços de educação relacionados no Anexo II da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da Nomenclatura Brasileira de Serviços, Intangíveis e Outras Operações que Produzam Variações no Patrimônio (NBS), observado o art. 129 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200029|Fornecimento dos serviços de saúde humana relacionados no Anexo III da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS, observado o art. 130 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200030|Venda dos dispositivos médicos relacionados no Anexo IV da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 131 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200031|Fornecimento dos dispositivos de acessibilidade próprios para pessoas com deficiência relacionados no Anexo V da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 132 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200032|Fornecimento dos medicamentos registrados na Anvisa ou produzidos por farmácias de manipulação, ressalvados os medicamentos sujeitos à alíquota zero de que trata o art. 141 da Lei Complementar nº 214, de 2025, observado o art. 133 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200033|Fornecimento das composições para nutrição enteral e parenteral, composições especiais e fórmulas nutricionais destinadas às pessoas com erros inatos do metabolismo relacionadas no Anexo VI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 133 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200034|Fornecimento dos alimentos destinados ao consumo humano relacionados no Anexo VII da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 135 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200035|Fornecimento dos produtos de higiene pessoal e limpeza relacionados no Anexo VIII da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 136 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200036|Fornecimento de produtos agropecuários, aquícolas, pesqueiros, florestais e extrativistas vegetais in natura, observado o art. 137 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200037|Fornecimento de serviços ambientais de conservação ou recuperação da vegetação nativa, mesmo que fornecidos sob a forma de manejo sustentável de sistemas agrícolas, agroflorestais e agrossilvopastoris, em conformidade com as definições e requisitos da legislação específica, observado o art. 137 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200038|Fornecimento dos insumos agropecuários e aquícolas relacionados no Anexo IX da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH e da NBS, observado o art. 138 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200039|Fornecimento dos serviços e o licenciamento ou cessão dos direitos relacionados no Anexo X da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS, quando destinados às seguintes produções nacionais artísticas, culturais, de eventos, jornalísticas e audiovisuais: espetáculos teatrais, circenses e de dança, shows musicais, desfiles carnavalescos ou folclóricos, eventos acadêmicos e científicos, como congressos, conferências e simpósios, feiras de negócios, exposições, feiras e mostras culturais, artísticas e literárias; programas de auditório ou jornalísticos, filmes, documentários, séries, novelas, entrevistas e clipes musicais, observado o art. 139 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200040|Fornecimento dos seguintes serviços de comunicação institucional à administração pública direta, autarquias e fundações públicas: serviços direcionados ao planejamento, criação, programação e manutenção de páginas eletrônicas da administração pública, ao monitoramento e gestão de suas redes sociais e à otimização de páginas e canais digitais para mecanismos de buscas e produção de mensagens, infográficos, painéis interativos e conteúdo institucional, serviços de relações com a imprensa, que reúnem estratégias organizacionais para promover e reforçar a comunicação dos órgãos e das entidades contratantes com seus públicos de interesse, por meio da interação com profissionais da imprensa, e serviços de relações públicas, que compreendem o esforço de comunicação planejado, coeso e contínuo que tem por objetivo estabelecer adequada percepção da atuação e dos objetivos institucionais, a partir do estímulo à compreensão mútua e da manutenção de padrões de relacionamento e fluxos de informação entre os órgãos e as entidades contratantes e seus públicos de interesse, no País e no exterior, observado o art. 140 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200041|Operações relacionadas às seguintes atividades desportivas: fornecimento de serviço de educação desportiva, classificado no código 1.2205.12.00 da NBS, e gestão e exploração do desporto por associações e clubes esportivos filiados ao órgão estadual ou federal responsável pela coordenação dos desportos, inclusive por meio de venda de ingressos para eventos desportivos, fornecimento oneroso ou não de bens e serviços, inclusive ingressos, por meio de programas de sócio-torcedor, cessão dos direitos desportivos dos atletas e transferência de atletas para outra entidade desportiva ou seu retorno à atividade em outra entidade desportiva, observado o art. 141 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200042|Operações relacionadas ao fornecimento de serviço de educação desportiva, classificado no código 1.2205.12.00 da NBS, observado o art. 141 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200043|Fornecimento à administração pública direta, autarquias e fundações púbicas dos serviços e dos bens relativos à soberania e à segurança nacional, à segurança da informação e à segurança cibernética relacionados no Anexo XI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS e da NCM/SH, observado o art. 142 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200044|Operações e prestações de serviços de segurança da informação e segurança cibernética desenvolvidos por sociedade que tenha sócio brasileiro com o mínimo de 20% (vinte por cento) do seu capital social, relacionados no Anexo XI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS e da NCM/SH, observado o art. 142 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 60%|200045|Operações relacionadas a projetos de reabilitação urbana de zonas históricas e de áreas críticas de recuperação e reconversão urbanística dos Municípios ou do Distrito Federal, a serem delimitadas por lei municipal ou distrital, observado o art. 158 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 50%|200046|Operações com bens imóveis, observado o art. 261 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 40%|200047|Bares e Restaurantes, observado o art. 275 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 40%|200048|Hotelaria, Parques de Diversão e Parques Temáticos, observado o art. 281 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 40%|200049|Transporte coletivo de passageiros rodoviário, ferroviário e hidroviário intermunicipais e interestaduais, observado o art. 286 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 40%|200450|Serviços de transporte aéreo regional coletivo de passageiros ou de carga, observado o art. 287 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 40%|200051|Agências de Turismo, observado o art. 289 da Lei Complementar nº 214, de 2025.|
|200|Alíquota reduzida em 30%|200052|Prestação de serviços das seguintes profissões intelectuais de natureza científica, literária ou artística, submetidas à fiscalização por conselho profissional: administradores, advogados, arquitetos e urbanistas, assistentes sociais, bibliotecários, biólogos, contabilistas, economistas, economistas domésticos, profissionais de educação física, engenheiros e agrônomos, estatísticos, médicos veterinários e zootecnistas, museólogos, químicos, profissionais de relações públicas, técnicos industriais e técnicos agrícolas, observado o art. 127 da Lei Complementar nº 214, de 2025.|
|210|Alíquota reduzida em 50% com redutor de base de cálculo|210001|Redutor social aplicado uma única vez na alienação de bem imóvel residencial novo, observado o art. 259 da Lei Complementar nº 214, de 2025.|
|210|Alíquota reduzida em 50% com redutor de base de cálculo|210002|Redutor social aplicado uma única vez na alienação de lote residencial, observado o art. 259 da Lei Complementar nº 214, de 2025.|
|210|Alíquota reduzida em 70% com redutor de base de cálculo|210003|Redutor social em operações de locação, cessão onerosa e arrendamento de bens imóveis de uso residencial, observado o art. 260 da Lei Complementar nº 214, de 2025.|
|220|Alíquota fixa|220001|Incorporação imobiliária submetida ao regime especial de tributação, observado o art. 485 da Lei Complementar nº 214, de 2025.|
|220|Alíquota fixa|220002|Incorporação imobiliária submetida ao regime especial de tributação, observado o art. 485 da Lei Complementar nº 214, de 2025.|
|220|Alíquota fixa|220003|Alienação de imóvel decorrente de parcelamento do solo, observado o art. 486 da Lei Complementar nº 214, de 2025.|
|221|Alíquota fixa proporcional|221001|Locação, cessão onerosa ou arrendamento de bem imóvel com alíquota sobre a receita bruta, observado o art. 487 da Lei Complementar nº 214, de 2025.|
|400|Isenção|400001|Fornecimento de serviços de transporte público coletivo de passageiros rodoviário e metroviário de caráter urbano, semiurbano e metropolitano, sob regime de autorização, permissão ou concessão pública, observado o art. 157 da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410001|Fornecimento de bonificações quando constem do respectivo documento fiscal e que não dependam de evento posterior, observado o art. 5º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410002|Transferências entre estabelecimentos pertencentes ao mesmo contribuinte, observado o art. 6º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410003|Doações, observado o art. 6º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410004|Exportações de bens e serviços, observado o art. 8º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410005|Fornecimentos realizados pela União, pelos Estados, pelo Distrito Federal e pelos Municípios, observado o art. 9º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410006|Fornecimentos realizados por entidades religiosas e templos de qualquer culto, inclusive suas organizações assistenciais e beneficentes, observado o art. 9º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410007|Fornecimentos realizados por partidos políticos, inclusive suas fundações, entidades sindicais dos trabalhadores e instituições de educação e de assistência social, sem fins lucrativos, observado o art. 9º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410008|Fornecimentos de livros, jornais, periódicos e do papel destinado a sua impressão, observado o art. 9º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410009|Fornecimentos de fonogramas e videofonogramas musicais produzidos no Brasil contendo obras musicais ou literomusicais de autores brasileiros e/ou obras em geral interpretadas por artistas brasileiros, bem como os suportes materiais ou arquivos digitais que os contenham, salvo na etapa de replicação industrial de mídias ópticas de leitura a laser, observado o art. 9º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410010|Fornecimentos de serviço de comunicação nas modalidades de radiodifusão sonora e de sons e imagens de recepção livre e gratuita, observado o art. 9º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410011|Fornecimentos de ouro, quando definido em lei como ativo financeiro ou instrumento cambial, observado o art. 9º da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410012|Fornecimento de condomínio edilício não optante pelo regime regular, observado o art. 26 da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410013|Exportações de combustíveis, observado o art. 98 da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410014|Fornecimento de produtor rural não contribuinte, observado o art. 164 da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410015|Fornecimento por transportador autônomo não contribuinte, observado o art. 169 da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410016|Fornecimento ou aquisição de resíduos sólidos, observado o art. 170 da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410017|Aquisição de bem móvel com crédito presumido sob condição de revenda realizada, observado o art. 171 da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410018|Operações relacionadas aos fundos garantidores e executores de políticas públicas, inclusive de habitação, previstos em lei, assim entendidas os serviços prestados ao fundo pelo seu agente operador e por entidade encarregada da sua administração, observado o art. 213 da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410019|Exclusão da gorjeta na base de cálculo no fornecimento de alimentação, observado o art. 274 da Lei Complementar nº 214, de 2025.|
|410|Imunidade e não incidência|410020|Exclusão do valor de intermediação na base de cálculo no fornecimento de alimentação, observado o art. 274 da Lei Complementar nº 214, de 2025.|
|510|Diferimento|510001|Operações, sujeitas a diferimento, com energia elétrica ou com direitos a ela relacionados, relativas à geração, comercialização, distribuição e transmissão, observado o art. 28 da Lei Complementar nº 214, de 2025.|
|510|Diferimento|510002|Operações, sujeitas a diferimento, com insumos agropecuários e aquícolas destinados a produtor rural contribuinte, observado o art. 138 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550001|Exportações de bens materiais, observado o art. 82 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550002|Regime de Trânsito, observado o art. 84 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550003|Regimes de Depósito, observado o art. 85 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550004|Regimes de Depósito, observado o art. 87 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550005|Regimes de Depósito, observado o art. 87 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550006|Regimes de Permanência Temporária, observado o art. 88 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550007|Regimes de Aperfeiçoamento, observado o art. 90 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550008|Importação de bens para o Regime de Repetro-Temporário, de que tratam o inciso I do art. 93 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550009|GNL-Temporário, de que trata o inciso II do art. 93 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550010|Repetro-Permanente, de que trata o inciso III do art. 93 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550011|Repetro-Industrialização, de que trata o inciso IV do art. 93 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550012|Repetro-Nacional, de que trata o inciso V do art. 93 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550013|Repetro-Entreposto, de que trata o inciso VI do art. 93 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550014|Zona de Processamento de Exportação, observado os arts. 99, 100 e 102 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550015|Regime Tributário para Incentivo à Modernização e à Ampliação da Estrutura Portuária - Reporto, observado o art. 105 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550016|Regime Especial de Incentivos para o Desenvolvimento da Infraestrutura - Reidi, observado o art. 106 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550017|Regime Tributário para Incentivo à Atividade Econômica Naval – Renaval, observado o art. 107 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550018|Desoneração da aquisição de bens de capital, , observado o art. 109 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550019|Importação de bem material por indústria incentivada para utilização na Zona Franca de Manaus, observado o art. 443 da Lei Complementar nº 214, de 2025.|
|550|Suspensão|550020|Áreas de livre comércio, observado o art. 461 da Lei Complementar nº 214, de 2025.|
|620|Tributação monofásica|620001|Tributação monofásica sobre combustíveis, observados os art. 172 e art. 179 I da Lei Complementar nº 214, de 2025.|
|620|Tributação monofásica|620002|Tributação monofásica com responsabilidade pela retenção sobre combustíveis, observado o art. 178 da Lei Complementar nº 214, de 2025.|
|620|Tributação monofásica|620003|Tributação monofásica com tributos retidos por responsabilidade sobre combustíveis, observado o art. 178 da Lei Complementar nº 214, de 2025.|
|620|Tributação monofásica|620004|Tributação monofásica sobre mistura de EAC com gasolina A em percentual superior ou inferior ao obrigatório, observado o art. 179 da Lei Complementar nº 214, de 2025.|
|620|Tributação monofásica|620005|Tributação monofásica sobre combustíveis cobrada anteriormente, observador o art. 180 da Lei Complementar nº 214, de 2025.|
|800|Transferência de crédito|800001|Fusão, cisão ou incorporação, observado o art. 55 da Lei Complementar nº 214, de 2025.|
|800|Transferência de crédito|800002|Transferência de crédito do associado, inclusive as cooperativas singulares, para cooperativa de que participa das operações antecedentes às operações em que fornece bens e serviços e os créditos presumidos, observado o art. 272 da Lei Complementar nº 214, de 2025.|
|810|Ajustes|810001|Crédito presumido sobre o valor apurado nos fornecimentos a partir da Zona Franca de Manaus, observado o art. 450 da Lei Complementar nº 214, de 2025.|
|820|Tributação em declaração de regime específico|820001|Documento com informações de fornecimento de serviços de planos de assinstência à saúde, mas com tributação realizada por outro meio, observado o art. 235 da Lei Complementar nº 214, de 2025.|
|820|Tributação em declaração de regime específico|820002|Documento com informações de fornecimento de serviços de planos de assinstência funerária, mas com tributação realizada por outro meio, observado o art. 236 da Lei Complementar nº 214, de 2025.|
|820|Tributação em declaração de regime específico|820003|Documento com informações de fornecimento de serviços de planos de assinstência à saúde de animais domésticos, mas com tributação realizada por outro meio, observado o art. 243 da Lei Complementar nº 214, de 2025.|
|820|Tributação em declaração de regime específico|820004|Documento com informações de prestação de serviços de consursos de prognósticos, mas com tributação realizada por outro meio, observado o art. 248 da Lei Complementar nº 214, de 2025.|
|820|Tributação em declaração de regime específico|820005|Documento com informações de alienação de bens imóveis, mas com tributação realizada por outro meio,, observado o art. 254 da Lei Complementar nº 214, de 2025.|

---

## 11. Apêndice H: Referência Completa de Enumerações (Enums)

Este apêndice documenta **todas** as enumerações utilizadas pela API, com o mapeamento entre o valor recebido no JSON, o valor correspondente no XML da SEFAZ (quando aplicável) e a descrição do significado de cada valor.

### 11.1. Enums de Identificação da Operação

#### 11.1.1. `OperationType` — Tipo de Operação (`tpNF`)

Identifica se a NF-e/NFC-e representa uma entrada ou saída de mercadoria do estabelecimento emitente.

| Valor JSON | Valor SEFAZ | Descrição | Quando usar |
|---|:---:|---|---|
| `Outgoing` | `1` | Saída | Vendas, remessas, transferências de saída, exportações. **Default**. |
| `Incoming` | `0` | Entrada | Devoluções recebidas, retornos, NF-e complementar de entrada, NF-e de crédito. |

> **Regra:** Notas com `purposeType = Devolution` ou `creditType` informado devem ser obrigatoriamente `Incoming`.

#### 11.1.2. `Destination` — Identificador de Local de Destino (`idDest`)

Indica onde a mercadoria é destinada para fins de tributação interestadual e cálculo do DIFAL/IBS-CBS.

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `None` | — | Não definido (não use em produção). |
| `InternalOperation` | `1` | Operação interna — UF do destinatário **igual** à UF do emitente. **Default**. |
| `InterstateOperation` | `2` | Operação interestadual — UF do destinatário **diferente** da UF do emitente. |
| `InternationalOperation` | `3` | Operação com o exterior — destinatário em país diferente do Brasil. |

> **Aliases legados:** `Internal_Operation`, `Interstate_Operation`, `International_Operation` (com underline) são aceitos por compatibilidade, mas a forma sem underline é a preferida.

#### 11.1.3. `PurposeType` — Finalidade da Emissão (`finNFe`)

Define a natureza fiscal da NF-e/NFC-e e governa quais grupos podem/devem ser preenchidos.

| Valor JSON | Valor SEFAZ | Descrição | Restrições |
|---|:---:|---|---|
| `None` | `0` | Não definido | Não usar. |
| `Normal` | `1` | NF-e normal | **Default.** Operação fiscal padrão. |
| `Complement` | `2` | NF-e complementar | Deve referenciar uma NF-e original em `additionalInformation.taxDocumentsReference`. |
| `Adjustment` | `3` | NF-e de ajuste | Deve referenciar NF-e original. `totalIndicator` dos itens deve ser `false`. |
| `Devolution` | `4` | Devolução de mercadoria | Deve ser `operationType = Incoming` e referenciar a NF-e original. |

> **RTC:** A partir de 05/01/2026, os valores `5` (Crédito) e `6` (Débito) também são válidos via campos `creditType` e `debitType` (atualmente expostos como enums separados).

#### 11.1.4. `DebitType` — Tipo de Nota de Débito (`tpNFDebito`)

Aplicável apenas quando `purposeType = 6` (Débito). Detalha o motivo do débito segundo a Reforma Tributária.

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `TransferCreditsToCooperatives` | `01` | Transferência de créditos para cooperativas |
| `CancelCreditsExemptImmuneSales` | `02` | Cancelamento de créditos por vendas isentas/imunes |
| `UnprocessedInvoicesDebits` | `03` | Débitos de faturas não processadas no cálculo |
| `FinesAndInterest` | `04` | Multa e juros |
| `TransferInheritanceCredit` | `05` | Transferência de crédito na sucessão |
| `AdvancePayment` | `06` | Pagamento antecipado |
| `InventoryLoss` | `07` | Perda de estoque |
| `SnDisqualification` | `08` | Desenquadramento do Simples Nacional |

#### 11.1.5. `CreditType` — Tipo de Nota de Crédito (`tpNFCredito`)

Aplicável apenas quando `purposeType = 5` (Crédito).

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `FinesAndInterest` | `01` | Multa e juros |
| `IbsPresumedCreditAppropriationZfm` | `02` | Apropriação de crédito presumido de IBS sobre saldo devedor na ZFM |
| `ReturnDeliveryRefusedOrNotFound` | `03` | Retorno por recusa na entrega ou não localização do destinatário |
| `ValueReduction` | `04` | Redução de valores |
| `TransferCreditSuccession` | `05` | Transferência de crédito na sucessão |

> **NT 2025.002:** O Ajuste SINIEF 8/26 (vigência 04/05/2026) introduziu o código `06` — *Retorno por recusa parcial na entrega*, que desmembra o antigo `03` (recusa total/não localização) e exige referenciamento dos itens recusados na NF-e original. Ainda não exposto como valor de enum nesta versão da API.

### 11.2. Enums do Consumidor / Comprador

#### 11.2.1. `ConsumerType` — Indicador de Operação com Consumidor Final (`indFinal`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `Normal` | `0` | Operação **não** destinada a consumidor final (revenda, industrialização, etc.). **Default para CNPJ**. |
| `FinalConsumer` | `1` | Operação destinada a consumidor final. **Default para CPF/NIF**. |

> **Regra de inferência:** Se omitido, o sistema usa o `federalTaxNumber` do `buyer`: CNPJ → `Normal`; CPF/NIF → `FinalConsumer`.

#### 11.2.2. `ConsumerPresenceType` — Indicador de Presença (`indPres`)

Caracteriza o canal/modalidade da operação comercial.

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `None` | `0` | Não se aplica (NF-e complementar ou ajuste). |
| `Presence` | `1` | Operação presencial (PDV físico). |
| `Internet` | `2` | Operação não presencial via Internet (e-commerce). **Default**. |
| `Telephone` | `3` | Operação não presencial via teleatendimento. |
| `Delivery` | `4` | NFC-e em operação com entrega a domicílio. |
| `OthersNonPresenceOperation` | `9` | Outros, operação não presencial. |

> **NFC-e:** Apenas `Presence` e `Delivery` são aceitos.

#### 11.2.3. `PersonType` — Tipo da Pessoa

| Valor JSON | Valor numérico | Descrição |
|---|:---:|---|
| `Undefined` | `0` | Indefinido. |
| `NaturalPerson` | `2` | Pessoa Física (PF). |
| `LegalEntity` | `4` | Pessoa Jurídica (PJ). |
| `Company` | `8` | (obsoleto, uso interno) Prestador de serviço. |
| `Customer` | `16` | (obsoleto, uso interno) Cliente. |

> **Decimal flags:** Este enum usa `[Flags]`, mas na prática só são usados `NaturalPerson` e `LegalEntity` no payload externo.

#### 11.2.4. `ReceiverStateTaxIndicator` — Indicador da IE do Destinatário (`indIEDest`)

Define a relação do destinatário com o ICMS — campo crítico para cálculo de DIFAL e validação da IE.

| Valor JSON | Valor SEFAZ | Descrição | Comportamento da IE |
|---|:---:|---|---|
| `None` | — | Não definido | Não usar. |
| `TaxPayer` | `1` | Contribuinte ICMS | `stateTaxNumber` **deve** ser informado e válido. |
| `Exempt` | `2` | Contribuinte isento de inscrição | `stateTaxNumber` não deve ser informado. |
| `NonTaxPayer` | `9` | Não Contribuinte | `stateTaxNumber` opcional (pode ou não possuir IE). |

### 11.3. Enums Tributários e de Regime

#### 11.3.1. `TaxRegime` — Código de Regime Tributário (`CRT`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `None` | — | Não definido. |
| `LucroReal` | `3` | Lucro Real. |
| `LucroPresumido` | `3` | Lucro Presumido (mesmo CRT que Lucro Real — categorizado como "Regime Normal"). |
| `SimplesNacional` | `1` | Simples Nacional. |
| `SimplesNacionalExcessoSublimite` | `2` | Simples Nacional — excesso de sublimite de receita bruta. |
| `MicroempreendedorIndividual` | `4` | Microempreendedor Individual (MEI). |
| `Isento` | — | Isento. |

#### 11.3.2. `SpecialTaxRegime` — Regime Especial de Tributação (`indRegTrib`)

| Valor JSON | Descrição |
|---|---|
| `Nenhum` | Nenhum |
| `MicroempresaMunicipal` | Microempresa Municipal |
| `Estimativa` | Estimativa |
| `SociedadeDeProfissionais` | Sociedade de Profissionais |
| `MicroempreendedorIndividual` | Microempreendedor Individual (MEI) |
| `MicroempresarioEmpresaPequenoPorte` | Microempresário e Empresa de Pequeno Porte (ME/EPP) |
| `Automatico` | Automático |

#### 11.3.3. `ExemptReason` — Motivo da Desoneração ICMS (`motDesICMS`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `Agriculture` | `3` | Uso na agropecuária |
| `Others` | `9` | Outros |
| `DevelopmentEntities` | `12` | Órgão de fomento e desenvolvimento agropecuário |

#### 11.3.4. `DuductionIndicator` — Indicador de Dedução do ICMS Desonerado (`indDeducao`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `NotDeduct` | `0` | O valor do ICMS desonerado **não** deduz do valor total da NF-e. |
| `Deduce` | `1` | O valor do ICMS desonerado deduz do valor total da NF-e. |

### 11.4. Enums de IBS/CBS (Reforma Tributária)

#### 11.4.1. `TaxCalculationMode` — Modo de Cálculo IBS/CBS

Define como os campos de IBS/CBS são preenchidos.

| Valor JSON | Valor numérico | Descrição |
|---|:---:|---|
| `Manual` | `0` | Preenchimento manual de todos os campos de tributo. **Default**. |
| `OfficialService` | `1` | Cálculo automático via serviço oficial. Apenas `situationCode` e `classCode` são necessários; demais campos são ignorados na entrada e preenchidos pelo serviço de cálculo. |

#### 11.4.2. `IbsZfmPresumedCreditClassification` — Classificação do Crédito Presumido ZFM (`tpCredPresIBSZFM`)

Para cálculo do crédito presumido de IBS em fornecimentos da Zona Franca de Manaus (art. 450 LC 214/2025).

| Valor JSON | Percentual | Descrição |
|---|:---:|---|
| `NoPresumedCredit` | 0% | Sem crédito presumido. |
| `FinalConsumptionGoods` | 55% | Bens de consumo final. |
| `CapitalGoods` | 75% | Bens de capital. |
| `IntermediateGoods` | 90,25% | Bens intermediários. |
| `ItAndOtherGoods` | 100% | Bens de informática e outros definidos em legislação. |

#### 11.4.3. `PresumedCreditClassificationCode` — Crédito Presumido Operacional (`cCredPres`)

Classifica a operação que dá direito ao crédito presumido operacional.

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `RuralProducerNonTaxpayer` | `01` | Produtor rural não contribuinte (art. 168 LC 214/2025) |
| `TacPfTransportServiceNonTaxpayer` | `02` | TAC PF não contribuinte do serviço de transporte (art. 169) |
| `RecyclingFromIndividual` | `03` | Reciclagem de pessoa física (art. 170) |
| `UsedMovableGoodsFromIndividualForResale` | `04` | Bens móveis usados de PF para revenda (art. 171) |
| `OptionalRegimeForCooperative` | — | Regime opcional para cooperativa |

> **Tabela `cCredPres`:** A tabela oficial (NT 2025.002) possui **13 códigos** (`01`–`13`), incluindo regime automotivo (`05`–`06`) e Zona Franca de Manaus / Áreas de Livre Comércio (`07`–`13`). O valor `OptionalRegimeForCooperative` não corresponde a um código `cCredPres` direto e é tratado pelo regime específico das cooperativas.

#### 11.4.4. `GovernmentPurchaseEntityType` — Tipo de Ente Governamental (`tpEnteGov`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `Union` | `1` | União |
| `State` | `2` | Estado |
| `FederalDistrict` | `3` | Distrito Federal |
| `Municipality` | `4` | Município |

#### 11.4.5. `GovernmentPurchaseOperationType` — Tipo de Operação com Ente Governamental (`tpOperGov`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `Supply` | `1` | Fornecimento |
| `Payment` | `2` | Recebimento do pagamento |
| `SupplyThenPay` | — | Fornecimento e pagamento simultâneo |
| `PayForPastSupply` | — | Pagamento por fornecimento passado |
| `SupplyAfterPay` | — | Fornecimento após pagamento |
| `PayNowSupplyLater` | — | Pagamento agora, fornecimento depois |
| `SupplyAndPayNow` | — | Fornecimento e pagamento agora |

> **Campo `tpOperGov`:** Na NT 2025.002 (inclusive v1.40), o campo da SEFAZ admite apenas `1` (Fornecimento) e `2` (Recebimento do pagamento). Os demais valores são abstrações da API NFe.io, resolvidas para `1` ou `2` conforme o fato gerador do IBS/CBS — os cenários combinados são tratados por regras de validação e pelo campo `refDFeAnt`, não por novos códigos.

### 11.5. Enums de Pagamento

#### 11.5.1. `PaymentMethod` — Forma de Pagamento (`tPag`)

Lista completa das formas de pagamento aceitas pela SEFAZ.

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `Cash` | `01` | Dinheiro |
| `Cheque` | `02` | Cheque |
| `CreditCard` | `03` | Cartão de Crédito |
| `DebitCard` | `04` | Cartão de Débito |
| `StoreCredict` | `05` | Crédito Loja |
| `FoodVouchers` | `10` | Vale Alimentação |
| `MealVouchers` | `11` | Vale Refeição |
| `GiftVouchers` | `12` | Vale Presente |
| `FuelVouchers` | `13` | Vale Combustível |
| `MercantileDuplicate` | `14` | Duplicata Mercantil |
| `BankBill` | `15` | Boleto Bancário |
| `BankDeposit` | `16` | Depósito Bancário |
| `InstantPayment` | `17` | Pagamento Instantâneo (PIX) — dinâmico |
| `WireTransfer` | `18` | Transferência bancária / Carteira Digital |
| `Cashback` | `19` | Programa de fidelidade / Cashback / Crédito Virtual |
| `StaticInstantPayment` | `20` | PIX Estático |
| `StoreCredit` | `21` | Crédito em Loja |
| `ElectronicPaymentNotInformed` | `22` | Pagamento Eletrônico Não Informado |
| `WithoutPayment` | `90` | Sem Pagamento (ex: remessa, bonificação) |
| `Others` | `99` | Outros |

> **Validação:** Quando `method = CreditCard` ou `DebitCard`, o grupo `card` é **obrigatório**.

#### 11.5.2. `PaymentType` — Indicador da Forma de Pagamento (`indPag`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `InCash` | `0` | Pagamento à vista |
| `Term` | `1` | Pagamento a prazo |

#### 11.5.3. `IntegrationPaymentType` — Tipo de Integração (`tpIntegra`)

Aplicável dentro do grupo `card`.

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `Integrated` | `1` | Pagamento integrado com o sistema de automação da empresa (Ex.: TEF, Comércio Eletrônico). |
| `NotIntegrated` | `2` | Pagamento não integrado (Ex.: equipamento POS independente). |

#### 11.5.4. `FlagCard` — Bandeira do Cartão (`tBand`)

| Valor JSON | Valor SEFAZ | Bandeira |
|---|:---:|---|
| `None` | `00` | Não definido |
| `Visa` | `01` | Visa |
| `Mastercard` | `02` | Mastercard |
| `AmericanExpress` | `03` | American Express |
| `Sorocred` | `04` | Sorocred |
| `DinersClub` | `05` | Diners Club |
| `Elo` | `06` | Elo |
| `Hipercard` | `07` | Hipercard |
| `Aura` | `08` | Aura |
| `Cabal` | `09` | Cabal |
| `Alelo` | `10` | Alelo |
| `BanesCard` | `11` | Banescard |
| `CalCard` | `12` | Calcard |
| `Credz` | `13` | Credz |
| `Discover` | `14` | Discover |
| `GoodCard` | `15` | Good Card |
| `GreenCard` | `16` | Green Card |
| `Hiper` | `17` | Hiper |
| `JCB` | `18` | JCB |
| `Mais` | `19` | Mais |
| `MaxVan` | `20` | Maxvan |
| `Policard` | `21` | Policard |
| `RedeCompras` | `22` | Rede Compras |
| `Sodexo` | `23` | Sodexo |
| `ValeCard` | `24` | ValeCard |
| `Verocheque` | `25` | Verocheque |
| `VR` | `26` | VR |
| `Ticket` | `27` | Ticket |
| `Other` | `99` | Outros |

### 11.6. Enums de Transporte e Importação

#### 11.6.1. `ShippingModality` — Modalidade do Frete (`modFrete`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `ByIssuer` | `0` | Contratação do frete por conta do Remetente (CIF) |
| `ByReceiver` | `1` | Contratação do frete por conta do Destinatário (FOB) |
| `ByThirdParties` | `2` | Contratação do frete por conta de terceiros |
| `OwnBySender` | `3` | Transporte próprio por conta do remetente |
| `OwnByBuyer` | `4` | Transporte próprio por conta do destinatário |
| `Free` | `9` | Sem ocorrência de transporte. **Default**. |

> **Validação:** Se `Free`, os grupos `transportGroup`, `transportVehicle`, `reboque` e `volume` não devem ser preenchidos.

#### 11.6.2. `IntermediationType` — Forma de Importação quanto a Intermediação (`tpIntermedio`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `None` | `0` | Não definido |
| `ByOwn` | `1` | Importação por conta própria |
| `ImportOnBehalf` | `2` | Importação por conta e ordem de terceiro |
| `ByOrder` | `3` | Importação por encomenda |

#### 11.6.3. `InternationalTransportType` — Via de Transporte Internacional (`tpViaTransp`)

Informada na Declaração de Importação (DI).

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `None` | `0` | Não definido |
| `Maritime` | `1` | Marítima |
| `River` | `2` | Fluvial |
| `Lake` | `3` | Lacustre |
| `Airline` | `4` | Aérea |
| `Postal` | `5` | Postal |
| `Railway` | `6` | Ferroviária |
| `Highway` | `7` | Rodoviária |
| `Network` | `8` | Conduto / Rede de transmissão |
| `Own` | `9` | Meios próprios |
| `Ficta` | `10` | Entrada / Saída ficta |
| `Courier` | `11` | Serviço de Courier |
| `Handcarry` | `12` | Em mãos |

### 11.7. Enums de Impressão e Ambiente

#### 11.7.1. `PrintType` — Formato de Impressão do DANFE (`tpImp`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `None` | `0` | Sem geração de DANFE |
| `NFeNormalPortrait` | `1` | DANFE normal — Retrato |
| `NFeNormalLandscape` | `2` | DANFE normal — Paisagem |
| `NFeSimplified` | `3` | DANFE simplificado |
| `DANFE_NFC_E` | `4` | DANFE NFC-e |
| `DANFE_NFC_E_MSG_ELETRONICA` | `5` | DANFE NFC-e em mensagem eletrônica |

#### 11.7.2. `EnvironmentType` — Tipo de Ambiente (`tpAmb`)

| Valor JSON | Valor SEFAZ | Descrição |
|---|:---:|---|
| `None` | — | Não definido |
| `Production` | `1` | Produção (validade fiscal) |
| `Test` | `2` | Homologação (sem validade fiscal) |

#### 11.7.3. `StateTaxProcessingAuthorizer`

Identifica o autorizador SEFAZ que processou (ou está processando) o documento.

| Valor JSON | Descrição |
|---|---|
| `Normal` | Autorizador Normal (SEFAZ da UF do emitente ou autorizador alternativo) |
| `EPEC` | Autorizador de Evento Prévio de Emissão em Contingência |

### 11.8. Enums de Status e Eventos

#### 11.8.1. `InvoiceStatus` — Status da NF-e

| Valor JSON | Valor numérico interno | Descrição |
|---|:---:|---|
| `None` | `0` | Estado inicial / não definido |
| `Created` | `1` | Criada (recebida pela API, ainda não enviada à SEFAZ) |
| `Processing` | `2` | Em processamento (envio em andamento) |
| `Issued` | `3` | Emitida e autorizada pela SEFAZ |
| `IssuedContingency` | `4` | Emitida em contingência |
| `Cancelled` | `5` | Cancelada |
| `Disabled` | `6` | Inutilizada (numeração) |
| `IssueDenied` | `-2` | Emissão denegada pela SEFAZ |
| `Error` | `-1` | Erro no processamento |

#### 11.8.2. `EconomicActivityType` — Tipo de Atividade Econômica

| Valor JSON | Descrição |
|---|---|
| `Main` | Principal |
| `Secondary` | Secundária |

### 11.9. Enums de Estados Brasileiros (`StateCode`)

Lista das siglas das UFs brasileiras + indicador de exterior (`EX`). Aplicável em campos como `state` (endereço), `customsClearanceState`, etc.

| Sigla | Descrição |
|---|---|
| `NA` | Não Aplicável |
| `RO`, `AC`, `AM`, `RR`, `PA`, `AP`, `TO` | Região Norte |
| `MA`, `PI`, `CE`, `RN`, `PB`, `PE`, `AL`, `SE`, `BA` | Região Nordeste |
| `MG`, `ES`, `RJ`, `SP` | Região Sudeste |
| `PR`, `SC`, `RS` | Região Sul |
| `MS`, `MT`, `GO`, `DF` | Região Centro-Oeste |
| `EX` | Exterior |

### 11.10. Enum de Natureza Jurídica (`LegalNature`)

Aplicável ao emitente (`issuer.legalNature`).

| Valor JSON | Descrição |
|---|---|
| `EmpresaPublica` | Empresa Pública |
| `SociedadeEconomiaMista` | Sociedade de Economia Mista |
| `SociedadeAnonimaAberta` | Sociedade Anônima Aberta |
| `SociedadeAnonimaFechada` | Sociedade Anônima Fechada |
| `SociedadeEmpresariaLimitada` | Sociedade Empresária Limitada |
| `SociedadeEmpresariaEmNomeColetivo` | Sociedade Empresária em Nome Coletivo |
| `SociedadeEmpresariaEmComanditaSimples` | Sociedade Empresária em Comandita Simples |
| `SociedadeEmpresariaEmComanditaporAcoes` | Sociedade Empresária em Comandita por Ações |
| `SociedadeemContaParticipacao` | Sociedade em Conta de Participação |
| `Empresario` | Empresário Individual |
| `Cooperativa` | Cooperativa |
| `ConsorcioSociedades` | Consórcio de Sociedades |
| `GrupoSociedades` | Grupo de Sociedades |
| `EmpresaDomiciliadaExterior` | Empresa Domiciliada no Exterior |
| `ClubeFundoInvestimento` | Clube/Fundo de Investimento |
| `SociedadeSimplesPura` | Sociedade Simples Pura |
| `SociedadeSimplesLimitada` | Sociedade Simples Limitada |
| `SociedadeSimplesEmNomeColetivo` | Sociedade Simples em Nome Coletivo |
| `SociedadeSimplesEmComanditaSimples` | Sociedade Simples em Comandita Simples |
| `EmpresaBinacional` | Empresa Binacional |
| `ConsorcioEmpregadores` | Consórcio de Empregadores |
| `ConsorcioSimples` | Consórcio Simples |
| `EireliNaturezaEmpresaria` | EIRELI de Natureza Empresária |
| `EireliNaturezaSimples` | EIRELI de Natureza Simples |
| `ServicoNotarial` | Serviço Notarial e de Registro |
| `FundacaoPrivada` | Fundação Privada |
| `ServicoSocialAutonomo` | Serviço Social Autônomo |
| `CondominioEdilicio` | Condomínio Edilício |
| `ComissaoConciliacaoPrevia` | Comissão de Conciliação Prévia |
| `EntidadeMediacaoArbitragem` | Entidade de Mediação e Arbitragem |
| `PartidoPolitico` | Partido Político |
| `EntidadeSindical` | Entidade Sindical |
| `EstabelecimentoBrasilFundacaoAssociacaoEstrangeiras` | Estabelecimento no Brasil de Fundação ou Associação Estrangeiras |
| `FundacaoAssociacaoDomiciliadaExterior` | Fundação ou Associação Domiciliada no Exterior |
| `OrganizacaoReligiosa` | Organização Religiosa |
| `ComunidadeIndigena` | Comunidade Indígena |
| `FundoPrivado` | Fundo Privado |
| `AssociacaoPrivada` | Associação Privada |

---

## 12. Apêndice I: Mapeamento Propriedade-a-Propriedade (JSON ↔ XML SEFAZ)

Esta seção complementa o **Apêndice A (§3)** descendo ao nível de cada propriedade individual. Para cada campo do JSON, indicamos o **caminho completo**, o **tag XML correspondente** no leiaute oficial (NT 2025.002), o **tipo** e observações de preenchimento.

> **Convenção:** O caminho JSON usa notação por ponto (ex: `buyer.address.state`). O tag XML usa o nome exato do elemento no schema oficial. Quando um campo JSON encapsula múltiplos tags ou estruturas auxiliares, o "Tag XML" lista o tag principal.

### 12.1. Identificação da Nota (`ide`)

Estes campos ficam no **nível raiz** do JSON da requisição.

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `serie` | `serie` | int | Série do documento (0–999). |
| `number` | `nNF` | int | Número sequencial. |
| `operationOn` | `dhSaiEnt` | datetime | Data/hora de saída ou entrada. **Não enviar para NFC-e.** |
| `expectedDeliveryOn` | `dPrevEntrega` | date | Data prevista de entrega. **Não aplicável a NFC-e.** |
| `operationNature` | `natOp` | string | Descrição da operação. |
| `operationType` | `tpNF` | enum | `Outgoing=1`, `Incoming=0`. Ver §11.1.1. |
| `destination` | `idDest` | enum | Ver §11.1.2. |
| `consumptionCityCode` | `cMunFG` | int | Código IBGE do município. |
| `ibsConsumptionCityCode` | `cMunFGIBS` | int | Aplicável a operações presenciais fora do estabelecimento. |
| `printType` | `tpImp` | enum | Ver §11.7.1. |
| `purposeType` | `finNFe` | enum | Ver §11.1.3. |
| `debitType` | `tpNFDebito` | enum | Apenas para `purposeType=6`. Ver §11.1.4. |
| `creditType` | `tpNFCredito` | enum | Apenas para `purposeType=5`. Ver §11.1.5. |
| `consumerType` | `indFinal` | enum | Ver §11.2.1. |
| `presenceType` | `indPres` | enum | Ver §11.2.2. |
| `contingencyOn` | `dhCont` | datetime | Entrada em contingência. |
| `contingencyJustification` | `xJust` | string | Justificativa (mín. 15 chars). |

### 12.2. Compras Governamentais (`gCompraGov`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `governmentPurchase.entityType` | `tpEnteGov` | enum | Ver §11.4.4. |
| `governmentPurchase.rateReduction` | `pRedutor` | decimal | Percentual de redução de alíquota (art. 472/370 LC 214/2025). |
| `governmentPurchase.operationType` | `tpOperGov` | enum | Ver §11.4.5. |

### 12.3. Comprador / Destinatário (`dest`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `buyer.name` | `xNome` | string | **Obrigatório.** |
| `buyer.federalTaxNumber` | `CNPJ` ou `CPF` | int | **Obrigatório.** Ou `idEstrangeiro` para exterior. |
| `buyer.email` | `email` | string | **Obrigatório.** |
| `buyer.tradeName` | `xFant` | string | Nome fantasia. |
| `buyer.taxRegime` | `CRT` | enum | Ver §11.3.1. |
| `buyer.stateTaxNumber` | `IE` | string | Inscrição estadual. |
| `buyer.stateTaxNumberIndicator` | `indIEDest` | enum | Ver §11.2.4. |
| `buyer.type` | (lógico) | enum | Tipo da pessoa (NaturalPerson/LegalEntity). |
| `buyer.address.state` | `UF` | string | Sigla ISO 3166-2 (2 chars). |
| `buyer.address.city.code` | `cMun` | string | Código IBGE. |
| `buyer.address.city.name` | `xMun` | string | Nome do município. |
| `buyer.address.district` | `xBairro` | string | Bairro. |
| `buyer.address.additionalInformation` | `xCpl` | string | Complemento. |
| `buyer.address.street` | `xLgr` | string | Logradouro. |
| `buyer.address.number` | `nro` | string | "S/N" se sem número. |
| `buyer.address.postalCode` | `CEP` | string | CEP (somente dígitos). |
| `buyer.address.country` | `xPais` | string | ISO 3166-1 alfa-3. **Default `BRA`.** |
| `buyer.address.phone` | `fone` | string | Telefone (DDD + número). |

### 12.4. Local de Entrega e Retirada

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `delivery.federalTaxNumber` | `CNPJ`/`CPF` (de `entrega`) | int | Apenas se diferente do `buyer`. |
| `delivery.address.*` | `entrega/...` | object | Mesma estrutura de `buyer.address`. |
| `withdrawal.federalTaxNumber` | `CNPJ`/`CPF` (de `retirada`) | int | Apenas se diferente do emitente. |
| `withdrawal.address.*` | `retirada/...` | object | Mesma estrutura de `buyer.address`. |

### 12.5. Item — Identificação e Valores

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `items[].code` | `cProd` | string | **Obrigatório.** |
| `items[].codeGTIN` | `cEAN` | string | "SEM GTIN" se inexistente. |
| `items[].description` | `xProd` | string | **Obrigatório.** |
| `items[].ncm` | `NCM` | string | 2 ou 8 dígitos. |
| `items[].nve[]` | `NVE` | string array | Nomenclatura de Valor Aduaneiro. |
| `items[].extipi` | `EXTIPI` | string | Exceção da TIPI. |
| `items[].cfop` | `CFOP` | int | **Obrigatório se sem `taxDetermination`.** |
| `items[].unit` | `uCom` | string | Unidade comercial. |
| `items[].quantity` | `qCom` | decimal | Quantidade comercial. |
| `items[].unitAmount` | `vUnCom` | decimal | Valor unitário de comercialização. |
| `items[].totalAmount` | `vProd` | decimal | `quantity * unitAmount`. |
| `items[].codeTaxGTIN` | `cEANTrib` | string | GTIN da unidade tributável; "SEM GTIN" se inexistente. |
| `items[].unitTax` | `uTrib` | string | Unidade tributável. |
| `items[].quantityTax` | `qTrib` | decimal | Quantidade tributável. |
| `items[].taxUnitAmount` | `vUnTrib` | decimal | Valor unitário de tributação. |
| `items[].freightAmount` | `vFrete` | decimal | Valor do frete rateado para o item. |
| `items[].insuranceAmount` | `vSeg` | decimal | Valor do seguro rateado para o item. |
| `items[].discountAmount` | `vDesc` | decimal | Valor do desconto do item. |
| `items[].othersAmount` | `vOutro` | decimal | Outras despesas acessórias do item. |
| `items[].totalIndicator` | `indTot` | bool | `0` ou `1`. **Default `true`.** |
| `items[].usedMovableAssetIndicator` | `indBemMovelUsado` | bool | Indicador de bem móvel usado (regime específico de IBS/CBS para revenda). |
| `items[].cest` | `CEST` | string | 7 dígitos. |
| `items[].itemAmount` | `vItem` | decimal | Valor total do item (vProd + acréscimos − descontos). |
| `items[].numberOrderBuy` | `xPed` | string | Número do pedido de compra. |
| `items[].itemNumberOrderBuy` | `nItemPed` | int | Número do item no pedido de compra. |
| `items[].importControlSheetNumber` | `nFCI` | string | Ficha de Conteúdo de Importação. |
| `items[].benefit` | `cBenef` | string | Código de benefício fiscal na UF. |
| `items[].additionalInformation` | `infAdProd` | string | Informações adicionais do produto. |

### 12.6. Item — ICMS (`tax.icms`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `items[].tax.icms.origin` | `orig` | string | Origem da mercadoria (`0`–`8`): nacional, estrangeira (importação direta ou mercado interno) etc. |
| `items[].tax.icms.cst` | `CST` | string | Código de Situação Tributária do ICMS (regime normal). |
| `items[].tax.icms.csosn` | `CSOSN` | string | Código de Situação da Operação no Simples Nacional (substitui o CST para `CRT=1`). |
| `items[].tax.icms.baseTaxModality` | `modBC` | string | Modalidade de determinação da BC do ICMS: `0`=Margem Valor Agregado (%); `1`=Pauta (valor); `2`=Preço Tabelado Máx. (valor); `3`=Valor da operação. |
| `items[].tax.icms.baseTax` | `vBC` | decimal | Valor da base de cálculo do ICMS. |
| `items[].tax.icms.rate` | `pICMS` | decimal | Alíquota do ICMS (%). |
| `items[].tax.icms.amount` | `vICMS` | decimal | Valor do ICMS. |
| `items[].tax.icms.baseTaxReduction` | `pRedBC` | decimal | Percentual de redução da base de cálculo. |
| `items[].tax.icms.baseTaxSTModality` | `modBCST` | string | Modalidade de determinação da BC do ICMS ST: `0`=Preço tabelado/máx. sugerido; `1`=Lista Negativa; `2`=Lista Positiva; `3`=Lista Neutra; `4`=Margem Valor Agregado (%); `5`=Pauta. |
| `items[].tax.icms.baseTaxSTReduction` | `pRedBCST` | decimal | Percentual de redução da BC do ICMS ST. |
| `items[].tax.icms.baseTaxST` | `vBCST` | decimal | Valor da BC do ICMS ST. |
| `items[].tax.icms.stRate` | `pICMSST` | decimal | Alíquota do ICMS ST (%). |
| `items[].tax.icms.stAmount` | `vICMSST` | decimal | Valor do ICMS ST. |
| `items[].tax.icms.stMarginAmount` | `pMVAST` | decimal | Percentual da margem de valor adicionado do ICMS ST. |
| `items[].tax.icms.stRetentionAmount` | `vICMSSTRet` | decimal | Valor do ICMS ST retido anteriormente. |
| `items[].tax.icms.baseSTRetentionAmount` | `vBCSTRet` | decimal | Valor da BC do ICMS ST retido anteriormente. |
| `items[].tax.icms.snCreditRate` | `pCredSN` | decimal | Alíquota aplicável de cálculo do crédito (Simples Nacional). |
| `items[].tax.icms.snCreditAmount` | `vCredICMSSN` | decimal | Valor do crédito de ICMS que pode ser aproveitado (Simples Nacional). |
| `items[].tax.icms.fcpRate` | `pFCP` | decimal | Percentual do Fundo de Combate à Pobreza (FCP). |
| `items[].tax.icms.fcpAmount` | `vFCP` | decimal | Valor do FCP. |
| `items[].tax.icms.fcpstRate` | `pFCPST` | decimal | Percentual do FCP retido por ST. |
| `items[].tax.icms.fcpstAmount` | `vFCPST` | decimal | Valor do FCP retido por ST. |
| `items[].tax.icms.fcpstRetRate` | `pFCPSTRet` | decimal | Percentual do FCP retido anteriormente por ST. |
| `items[].tax.icms.fcpstRetAmount` | `vFCPSTRet` | decimal | Valor do FCP retido anteriormente por ST. |
| `items[].tax.icms.baseTaxFCPSTAmount` | `vBCFCPST` | decimal | Valor da BC do FCP retido por ST. |
| `items[].tax.icms.exemptAmount` | `vICMSDeson` | decimal | Valor do ICMS desonerado. |
| `items[].tax.icms.exemptReason` | `motDesICMS` | enum | Motivo da desoneração do ICMS. Ver §11.3.3. |
| `items[].tax.icms.deductionIndicator` | `indDeducao` | enum | Indicador de dedução do ICMS desonerado do valor do item. Ver §11.3.4. |
| `items[].tax.icms.ufst` | `UFST` | string | UF para a qual é devido o ICMS ST. |
| `items[].tax.icms.percentualDeferment` | `pDif` | decimal | Percentual do diferimento do ICMS. |
| `items[].tax.icms.baseDeferred` | `vICMSDif` | decimal | Valor do ICMS diferido. |
| `items[].tax.icms.basisBenefitCode` | `cBenefRBC` | string | Código de benefício fiscal na UF aplicado ao item quando houver redução da BC. |
| `items[].tax.icms.stFinalConsumerRate` | `pST` | decimal | Alíquota suportada pelo consumidor final (ST com retenção). |
| `items[].tax.icms.effectiveBaseTaxReductionRate` | `pRedBCEfet` | decimal | Percentual de redução da BC efetiva. |
| `items[].tax.icms.effectiveBaseTaxAmount` | `vBCEfet` | decimal | Valor da BC efetiva. |
| `items[].tax.icms.effectiveRate` | `pICMSEFET` | decimal | Alíquota do ICMS efetiva (%). |
| `items[].tax.icms.effectiveAmount` | `vICMSEFET` | decimal | Valor do ICMS efetivo. |

### 12.7. Item — IPI / II / PIS / COFINS

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `items[].tax.ipi.cst` | `CST` (em `IPI`) | string | Código de Situação Tributária do IPI. |
| `items[].tax.ipi.classificationCode` | `cEnq` | string | Código de enquadramento legal do IPI. |
| `items[].tax.ipi.classification` | `clEnq` | string | Classe de enquadramento do IPI (cigarros e bebidas). |
| `items[].tax.ipi.producerCNPJ` | `CNPJProd` | string | CNPJ do produtor da mercadoria, quando diferente do emitente. |
| `items[].tax.ipi.stampCode` | `cSelo` | string | Código do selo de controle do IPI. |
| `items[].tax.ipi.stampQuantity` | `qSelo` | decimal | Quantidade de selos de controle do IPI. |
| `items[].tax.ipi.base` | `vBC` (em `IPI`) | decimal | Base de cálculo do IPI (tributação por valor). |
| `items[].tax.ipi.rate` | `pIPI` | decimal | Alíquota do IPI (%). |
| `items[].tax.ipi.unitQuantity` | `qUnid` | decimal | Quantidade total na unidade padrão (tributação do IPI por unidade). |
| `items[].tax.ipi.unitAmount` | `vUnid` | decimal | Valor por unidade tributável (tributação do IPI por unidade). |
| `items[].tax.ipi.amount` | `vIPI` | decimal | Valor do IPI. |
| `items[].tax.ii.baseTax` | `vBC` (em `II`) | decimal | Base de cálculo do Imposto de Importação. |
| `items[].tax.ii.customsExpenditureAmount` | `vDespAdu` | decimal | Valor das despesas aduaneiras. |
| `items[].tax.ii.amount` | `vII` | decimal | Valor do Imposto de Importação. |
| `items[].tax.ii.iofAmount` | `vIOF` | decimal | Valor do IOF (Imposto sobre Operações Financeiras). |
| `items[].tax.pis.cst` | `CST` (em `PIS`) | string | Código de Situação Tributária do PIS. |
| `items[].tax.pis.baseTax` | `vBC` (em `PIS`) | decimal | Base de cálculo do PIS (tributação por percentual). |
| `items[].tax.pis.rate` | `pPIS` | decimal | Alíquota do PIS (%). |
| `items[].tax.pis.amount` | `vPIS` | decimal | Valor do PIS. |
| `items[].tax.pis.baseTaxProductQuantity` | `qBCProd` | decimal | Quantidade vendida (tributação do PIS por alíquota específica/unidade). |
| `items[].tax.pis.productRate` | `vAliqProd` | decimal | Alíquota do PIS em valor por unidade (R$). |
| `items[].tax.cofins.cst` | `CST` (em `COFINS`) | string | Código de Situação Tributária do COFINS. |
| `items[].tax.cofins.baseTax` | `vBC` (em `COFINS`) | decimal | Base de cálculo do COFINS (tributação por percentual). |
| `items[].tax.cofins.rate` | `pCOFINS` | decimal | Alíquota do COFINS (%). |
| `items[].tax.cofins.amount` | `vCOFINS` | decimal | Valor do COFINS. |
| `items[].tax.cofins.baseTaxProductQuantity` | `qBCProd` | decimal | Quantidade vendida (tributação do COFINS por alíquota específica/unidade). |
| `items[].tax.cofins.productRate` | `vAliqProd` | decimal | Alíquota do COFINS em valor por unidade (R$). |

### 12.8. Item — ICMS Destino UF (`ICMSUFDest`)

Aplicável a operações interestaduais com consumidor final não contribuinte (DIFAL).

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `items[].tax.icmsDestination.vBCUFDest` | `vBCUFDest` | decimal | Valor da BC do ICMS na UF de destino. |
| `items[].tax.icmsDestination.pFCPUFDest` | `pFCPUFDest` | decimal | Percentual do FCP devido à UF de destino. |
| `items[].tax.icmsDestination.pICMSUFDest` | `pICMSUFDest` | decimal | Alíquota interna na UF de destino. |
| `items[].tax.icmsDestination.pICMSInter` | `pICMSInter` | decimal | Alíquota interestadual aplicável entre as UF de origem e destino. |
| `items[].tax.icmsDestination.pICMSInterPart` | `pICMSInterPart` | decimal | Percentual provisório de partilha do ICMS interestadual (atualmente 100% à UF de destino). |
| `items[].tax.icmsDestination.vFCPUFDest` | `vFCPUFDest` | decimal | Valor do FCP devido à UF de destino. |
| `items[].tax.icmsDestination.vICMSUFDest` | `vICMSUFDest` | decimal | Valor do ICMS de partilha devido à UF de destino. |
| `items[].tax.icmsDestination.vICMSUFRemet` | `vICMSUFRemet` | decimal | Valor do ICMS de partilha devido à UF do remetente. |
| `items[].tax.icmsDestination.vBCFCPUFDest` | `vBCFCPUFDest` | decimal | Valor da BC do FCP na UF de destino. |

### 12.9. Item — Imposto Seletivo (`IS`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `items[].tax.IS.situationCode` | `CSTIS` | string | 3 dígitos. |
| `items[].tax.IS.classificationCode` | `cClassTribIS` | string | 6 dígitos. |
| `items[].tax.IS.basis` | `vBCIS` | decimal | 13.2. |
| `items[].tax.IS.rate` | `pIS` | decimal | Até 4 casas. |
| `items[].tax.IS.unitRate` | `pISEspec` | decimal | Alíquota específica por unidade. |
| `items[].tax.IS.unit` | `uTrib` | string | Unidade tributável. |
| `items[].tax.IS.quantity` | `qTrib` | decimal | Quantidade tributável do Imposto Seletivo. |
| `items[].tax.IS.amount` | `vIS` | decimal | Valor do Imposto Seletivo. |

### 12.10. Item — IBS/CBS (`IBSCBS`)

#### Raiz e jurisdições

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `items[].tax.IBSCBS.situationCode` | `CST` (em `IBSCBS`) | string | Código de Situação Tributária do IBS/CBS (3 dígitos). Ver §10. |
| `items[].tax.IBSCBS.classCode` | `cClassTrib` | string | Código de classificação tributária do IBS/CBS. Ver §10. |
| `items[].tax.IBSCBS.donationIndicator` | `indDoacao` | string | Indicador de doação a ente governamental. Ver §4.6.1. |
| `items[].tax.IBSCBS.basis` | `vBC` (em `IBSCBS`) | decimal | Base de cálculo do IBS/CBS. |
| `items[].tax.IBSCBS.state.rate` | `pIBSUF` | decimal | Alíquota do IBS da UF (%). |
| `items[].tax.IBSCBS.state.amount` | `vIBSUF` | decimal | Valor do IBS da UF. |
| `items[].tax.IBSCBS.municipal.rate` | `pIBSMun` | decimal | Alíquota do IBS do município (%). |
| `items[].tax.IBSCBS.municipal.amount` | `vIBSMun` | decimal | Valor do IBS do município. |
| `items[].tax.IBSCBS.cbs.rate` | `pCBS` | decimal | Alíquota da CBS (%). |
| `items[].tax.IBSCBS.cbs.amount` | `vCBS` | decimal | Valor da CBS. |
| `items[].tax.IBSCBS.ibsTotalAmount` | `vIBSTot` | decimal | Valor total do IBS (UF + município). |

#### Subgrupos por jurisdição (`state`/`municipal`/`cbs`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `*.deferment.rate` | `pDif` | decimal | Percentual do diferimento aplicado à jurisdição. Ver §4.4.1. |
| `*.deferment.amount` | `vDif` | decimal | Valor do tributo diferido. |
| `*.reduction.rateReduction` | `pRedAliq` | decimal | Percentual de redução da alíquota. Ver §4.4.2. |
| `*.reduction.effectiveRate` | `pAliqEfet` | decimal | Alíquota efetiva após a redução. |
| `*.returnedAmount.amount` | `vDevTrib` | decimal | Valor do tributo devolvido ao contribuinte. Ver §4.4.3. |

#### Subgrupos especiais (raiz `IBSCBS`)

> Cada subgrupo é um objeto com múltiplos campos; consulte a seção de referência indicada para o detalhamento de cada propriedade.

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `items[].tax.IBSCBS.regularTaxation.*` | `gTribRegular` | object | Tributação regular hipotética (informativa). Ver §4.5.6. |
| `items[].tax.IBSCBS.governmentPurchase.*` | `gIBSCBS_CompraGov` | object | Composição em compras governamentais. Ver §4.5.5. |
| `items[].tax.IBSCBS.monophase.standart.*` | `gMonofasicoPadrao` | object | Tributação monofásica padrão. Ver §4.5.1. |
| `items[].tax.IBSCBS.monophase.withholding.*` | `gMonofasicoRetido` | object | Monofásico com retenção. Ver §4.5.1. |
| `items[].tax.IBSCBS.monophase.previouslyWithheld.*` | `gMonofasicoRetidoAnt` | object | Monofásico retido anteriormente. Ver §4.5.1. |
| `items[].tax.IBSCBS.monophase.deferment.*` | `gMonofasicoDif` | object | Monofásico com diferimento. Ver §4.5.1. |
| `items[].tax.IBSCBS.creditTransfer.*` | `gTransfCred` | object | Transferência de crédito. Ver §4.5.3. |
| `items[].tax.IBSCBS.operationalPresumedCredit.*` | `gCredPresOper` | object | Crédito presumido operacional. Ver §4.5.2. |
| `items[].tax.IBSCBS.creditReversal.*` | `gEstornoCred` | object | Estorno de crédito. Ver §4.5.4. |
| `items[].tax.IBSCBS.zfmPresumedCredit.*` | `gCredPresIBSZFM` | object | Crédito presumido da Zona Franca de Manaus. Ver §4.5.7. |
| `items[].competenceAdjustment.*` | `gAjusteCompet` | object | Ajuste de competência. Ver §4.6.2. |

### 12.11. Totais (`total`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `totals.icms.baseTax` | `vBC` | decimal | Base de cálculo do ICMS (soma dos itens). |
| `totals.icms.icmsAmount` | `vICMS` | decimal | Valor total do ICMS. |
| `totals.icms.icmsExemptAmount` | `vICMSDeson` | decimal | Valor total do ICMS desonerado. |
| `totals.icms.stCalculationBasisAmount` | `vBCST` | decimal | Base de cálculo do ICMS ST. |
| `totals.icms.stAmount` | `vST` | decimal | Valor total do ICMS ST. |
| `totals.icms.productAmount` | `vProd` | decimal | Valor total dos produtos e serviços. |
| `totals.icms.freightAmount` | `vFrete` | decimal | Valor total do frete. |
| `totals.icms.insuranceAmount` | `vSeg` | decimal | Valor total do seguro. |
| `totals.icms.discountAmount` | `vDesc` | decimal | Valor total dos descontos. |
| `totals.icms.iiAmount` | `vII` | decimal | Valor total do Imposto de Importação. |
| `totals.icms.ipiAmount` | `vIPI` | decimal | Valor total do IPI. |
| `totals.icms.pisAmount` | `vPIS` | decimal | Valor total do PIS. |
| `totals.icms.cofinsAmount` | `vCOFINS` | decimal | Valor total do COFINS. |
| `totals.icms.othersAmount` | `vOutro` | decimal | Outras despesas acessórias. |
| `totals.icms.invoiceAmount` | `vNF` | decimal | Valor total da NF-e. |
| `totals.icms.fcpufDestinationAmount` | `vFCPUFDest` | decimal | Valor total do FCP devido à UF de destino. |
| `totals.icms.icmsufDestinationAmount` | `vICMSUFDest` | decimal | Valor total do ICMS de partilha para a UF de destino. |
| `totals.icms.icmsufSenderAmount` | `vICMSUFRemet` | decimal | Valor total do ICMS de partilha para a UF do remetente. |
| `totals.icms.federalTaxesAmount` | `vTotTrib` | decimal | Valor aproximado total de tributos (federais, estaduais e municipais). |
| `totals.icms.fcpAmount` | `vFCP` | decimal | Valor total do FCP. |
| `totals.icms.fcpstAmount` | `vFCPST` | decimal | Valor total do FCP retido por ST. |
| `totals.icms.fcpstRetAmount` | `vFCPSTRet` | decimal | Valor total do FCP retido anteriormente por ST. |
| `totals.icms.ipiDevolAmount` | `vIPIDevol` | decimal | Valor total do IPI devolvido. |
| `totals.issqn.baseRateISS` | `vBC` (em `ISSQNtot`) | decimal | Base de cálculo do ISSQN. |
| `totals.issqn.totalISS` | `vISS` | decimal | Valor total do ISSQN. |
| `totals.withheldTaxes.pisAmount` | `vRetPIS` | decimal | Valor do PIS retido por substituição. |
| `totals.withheldTaxes.cofinsAmount` | `vRetCOFINS` | decimal | Valor do COFINS retido por substituição. |
| `totals.withheldTaxes.csllAmount` | `vRetCSLL` | decimal | Valor da CSLL retida. |
| `totals.withheldTaxes.irrfBasis` | `vBCIRRF` | decimal | Base de cálculo do IRRF. |
| `totals.withheldTaxes.irrfAmount` | `vIRRF` | decimal | Valor do IRRF retido. |
| `totals.withheldTaxes.socialSecutiryBasis` | `vBCRetPrev` | decimal | Base de cálculo da retenção da Previdência Social. |
| `totals.withheldTaxes.socialSecutiryAmount` | `vRetPrev` | decimal | Valor da retenção da Previdência Social. |
| `totals.isTotals.amount` | `vIS` (em `ISTot`) | decimal | Valor total do Imposto Seletivo. |
| `totals.ibsCbsTotals.basis` | `vBCIBSCBS` | decimal | Base de cálculo total do IBS/CBS. |
| `totals.ibsCbsTotals.ibs.state.amount` | `vIBSUF` (em totais) | decimal | Valor total do IBS da UF. |
| `totals.ibsCbsTotals.ibs.municipal.amount` | `vIBSMun` (em totais) | decimal | Valor total do IBS do município. |
| `totals.ibsCbsTotals.ibs.totalAmount` | `vIBS` (em `IBSCBSTot`) | decimal | Valor total do IBS (UF + município). |
| `totals.ibsCbsTotals.cbs.amount` | `vCBS` (em totais) | decimal | Valor total da CBS. |
| `totals.totalInvoiceAmount` | `vNFTot` | decimal | Valor total da NF-e considerando IBS/CBS/IS. |

### 12.12. Transporte (`transp`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `transport.freightModality` | `modFrete` | enum | Modalidade do frete. Ver §11.6.1. |
| `transport.transportGroup.name` | `xNome` | string | Razão social ou nome do transportador. |
| `transport.transportGroup.federalTaxNumber` | `CNPJ`/`CPF` | int | CNPJ ou CPF do transportador. |
| `transport.transportGroup.stateTaxNumber` | `IE` | string | Inscrição estadual do transportador. |
| `transport.transportGroup.address.*` | (subcampos `transporta`) | object | Endereço do transportador (`xEnder`, `xMun`, `UF`). |
| `transport.transportVehicle.plate` | `placa` | string | Placa do veículo de transporte. |
| `transport.transportVehicle.state` | `UF` | string | UF de registro do veículo. |
| `transport.transportVehicle.rntc` | `RNTC` | string | Registro Nacional de Transportador de Carga (ANTT). |
| `transport.reboque.plate` | `placa` (em `reboque`) | string | Placa do reboque. |
| `transport.reboque.uf` | `UF` (em `reboque`) | string | UF de registro do reboque. |
| `transport.reboque.rntc` | `RNTC` (em `reboque`) | string | RNTC do reboque. |
| `transport.reboque.wagon` | `vagao` | string | Identificação do vagão (transporte ferroviário). |
| `transport.reboque.ferry` | `balsa` | string | Identificação da balsa. |
| `transport.volume.volumeQuantity` | `qVol` | int | Quantidade de volumes transportados. |
| `transport.volume.species` | `esp` | string | Espécie dos volumes transportados. |
| `transport.volume.brand` | `marca` | string | Marca dos volumes transportados. |
| `transport.volume.volumeNumeration` | `nVol` | string | Numeração dos volumes transportados. |
| `transport.volume.netWeight` | `pesoL` | decimal | Peso líquido (kg). |
| `transport.volume.grossWeight` | `pesoB` | decimal | Peso bruto (kg). |
| `transport.sealNumber` | `nLacre` | string | Número dos lacres. |
| `transport.transpRate.serviceAmount` | `vServ` | decimal | Valor do serviço de transporte (retenção do ICMS do transporte). |
| `transport.transpRate.bcRetentionAmount` | `vBCRet` | decimal | Base de cálculo da retenção do ICMS do transporte. |
| `transport.transpRate.icmsRetentionRate` | `pICMSRet` | decimal | Alíquota da retenção do ICMS do transporte. |
| `transport.transpRate.icmsRetentionAmount` | `vICMSRet` | decimal | Valor do ICMS retido do transporte. |
| `transport.transpRate.cfop` | `CFOP` (em `retTransp`) | int | CFOP do serviço de transporte. |
| `transport.transpRate.cityGeneratorFactCode` | `cMunFG` (em `retTransp`) | int | Código IBGE do município de ocorrência do fato gerador do ICMS do transporte. |

### 12.13. Pagamento (`pag`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `payment[].paymentDetail[].method` | `tPag` | enum | Forma de pagamento. Ver §11.5.1. |
| `payment[].paymentDetail[].methodDescription` | `xPag` | string | Descrição da forma de pagamento (obrigatória quando `tPag=99`/outros). |
| `payment[].paymentDetail[].paymentType` | `indPag` | enum | Indicador da forma de pagamento (à vista/a prazo). Ver §11.5.2. |
| `payment[].paymentDetail[].amount` | `vPag` | decimal | Valor do pagamento. |
| `payment[].paymentDetail[].paymentDate` | `dPag` | datetime | Data do pagamento. |
| `payment[].paymentDetail[].federalTaxNumberPag` | `CNPJPag` | string | CNPJ do estabelecimento beneficiário do pagamento. |
| `payment[].paymentDetail[].statePag` | `UFPag` | string | UF do beneficiário do pagamento. |
| `payment[].paymentDetail[].card.federalTaxNumber` | `CNPJ` (em `card`) | string | CNPJ da credenciadora de cartão de crédito/débito. |
| `payment[].paymentDetail[].card.flag` | `tBand` | enum | Bandeira do cartão. Ver §11.5.4. |
| `payment[].paymentDetail[].card.authorization` | `cAut` | string | Número de autorização da operação com cartão. |
| `payment[].paymentDetail[].card.integrationPaymentType` | `tpIntegra` | enum | Tipo de integração do pagamento com o sistema de automação. Ver §11.5.3. |
| `payment[].payBack` | `vTroco` | decimal | Valor do troco. |

### 12.14. Cobrança (`cobr`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `billing.bill.number` | `nFat` | string | Número da fatura. |
| `billing.bill.originalAmount` | `vOrig` | decimal | Valor original da fatura. |
| `billing.bill.discountAmount` | `vDesc` | decimal | Valor do desconto da fatura. |
| `billing.bill.netAmount` | `vLiq` | decimal | Valor líquido da fatura. |
| `billing.duplicates[].number` | `nDup` | string | Número da duplicata/parcela. |
| `billing.duplicates[].expirationOn` | `dVenc` | datetime | Data de vencimento da duplicata. |
| `billing.duplicates[].amount` | `vDup` | decimal | Valor da duplicata. |

### 12.15. Informações Adicionais (`infAdic`)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `additionalInformation.fisco` | `infAdFisco` | string | Informações adicionais de interesse do Fisco. |
| `additionalInformation.taxpayer` | `infCpl` | string | Informações complementares de interesse do contribuinte. |
| `additionalInformation.xmlAuthorized[]` | `autXML/CNPJ`/`CPF` | int array | CNPJ/CPF autorizados a acessar o XML da NF-e. |
| `additionalInformation.taxDocumentsReference[].documentElectronicInvoice.accessKey` | `refNFe` | string | Chave de acesso da NF-e referenciada. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.federalTaxNumber` | `refNF/CNPJ` | string | CNPJ do emitente da NF (modelo 1/1A) referenciada. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.state` | `refNF/cUF` | int | Código da UF do emitente da NF referenciada. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.yearMonth` | `refNF/AAMM` | string | Ano e mês (AAMM) de emissão da NF referenciada. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.model` | `refNF/mod` | string | Modelo do documento fiscal referenciado. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.series` | `refNF/serie` | string | Série da NF referenciada. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.number` | `refNF/nNF` | string | Número da NF referenciada. |
| `additionalInformation.taxDocumentsReference[].taxCouponInformation.modelDocumentFiscal` | `refECF/mod` | string | Modelo do Cupom Fiscal (ECF) referenciado. |
| `additionalInformation.taxDocumentsReference[].taxCouponInformation.orderECF` | `refECF/nECF` | string | Número de ordem sequencial do ECF. |
| `additionalInformation.taxDocumentsReference[].taxCouponInformation.orderCountOperation` | `refECF/nCOO` | int | Número do Contador de Ordem de Operação (COO). |
| `additionalInformation.advancePayment[].accessKey` | `gPagAntecipado/refNFe` | string | Chave de acesso de NF-e de pagamento antecipado. |
| `additionalInformation.taxpayerComments[].field` | `obsCont/xCampo` | string | Identificação do campo livre do contribuinte. |
| `additionalInformation.taxpayerComments[].text` | `obsCont/xTexto` | string | Conteúdo do campo livre do contribuinte. |
| `additionalInformation.referencedProcess[].identifierConcessory` | `nProc` | string | Identificador do processo ou ato concessório. |
| `additionalInformation.referencedProcess[].identifierOrigin` | `indProc` | int | Origem do processo (SEFAZ, Justiça Federal/Estadual, Secex/RFB, outros). |
| `additionalInformation.referencedProcess[].concessionActType` | `tpAto` | int | Tipo de ato concessório. |

### 12.16. Compra, Exportação e Intermediário

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `purchaseInformation.commitmentNote` | `xNEmp` | string | Nota de empenho (compras públicas). |
| `purchaseInformation.purchaseOrder` | `xPed` (em `compra`) | string | Número do pedido de compra. |
| `purchaseInformation.contractNumber` | `xCont` | string | Número do contrato. |
| `export.state` | `UFSaidaPais` | enum | UF de embarque ou de transposição de fronteira. |
| `export.office` | `xLocExporta` | string | Local de embarque ou de despacho da exportação. |
| `export.local` | `xLocDespacho` | string | Descrição do local de despacho. |
| `transactionIntermediate.federalTaxNumber` | `CNPJ` (em `infIntermed`) | int | CNPJ do intermediador da transação (ex.: marketplace). |
| `transactionIntermediate.identifier` | `idCadIntTran` | string | Identificador do intermediador no portal do marketplace. |
| `issuerTaxSubstitute.stStateTaxNumber` | `IEST` | string | Inscrição estadual do substituto tributário na UF de destino. |

### 12.17. Item — Subgrupos Especiais (DI, Combustível, Veículo)

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `items[].importDeclarations[].code` | `nDI` | string | Número da Declaração de Importação (DI/DSI/DA). |
| `items[].importDeclarations[].registeredOn` | `dDI` | datetime | Data de registro da DI. |
| `items[].importDeclarations[].customsClearanceName` | `xLocDesemb` | string | Local de desembaraço aduaneiro. |
| `items[].importDeclarations[].customsClearanceState` | `UFDesemb` | enum | UF onde ocorreu o desembaraço aduaneiro. |
| `items[].importDeclarations[].customsClearancedOn` | `dDesemb` | datetime | Data do desembaraço aduaneiro. |
| `items[].importDeclarations[].afrmmAmount` | `vAFRMM` | decimal | Valor do AFRMM (Adicional ao Frete para Renovação da Marinha Mercante). |
| `items[].importDeclarations[].internationalTransport` | `tpViaTransp` | enum | Via de transporte internacional. Ver §11.6.3. |
| `items[].importDeclarations[].intermediation` | `tpIntermedio` | enum | Forma de importação quanto à intermediação. Ver §11.6.2. |
| `items[].importDeclarations[].acquirerFederalTaxNumber` | `CNPJ`/`CPF` | string | CNPJ/CPF do adquirente ou encomendante. |
| `items[].importDeclarations[].stateThird` | `UFTerceiro` | string | UF do adquirente ou encomendante. |
| `items[].importDeclarations[].exporter` | `cExportador` | string | Código do exportador (usado pelo importador nos seus controles). |
| `items[].importDeclarations[].additions[].code` | `nAdicao` | int | Número sequencial da adição. |
| `items[].importDeclarations[].additions[].manufacturer` | `cFabricante` | string | Código do fabricante estrangeiro (controle do importador). |
| `items[].importDeclarations[].additions[].amount` | `vDescDI` | decimal | Valor do desconto da adição. |
| `items[].importDeclarations[].additions[].drawback` | `nDraw` | int | Número do ato concessório de Drawback. |
| `items[].fuelDetail.codeANP` | `cProdANP` | string | Código do produto conforme tabela da ANP. |
| `items[].fuelDetail.descriptionANP` | `descANP` | string | Descrição do produto conforme a ANP. |
| `items[].fuelDetail.percentageNG` | `pMixGN` | decimal | Percentual de gás natural no produto GLP (mistura). |
| `items[].fuelDetail.percentageGLP` | `pGLP` | decimal | Percentual do GLP derivado do petróleo. |
| `items[].fuelDetail.percentageNGn` | `pGNn` | decimal | Percentual de gás natural nacional. |
| `items[].fuelDetail.percentageGNi` | `pGNi` | decimal | Percentual de gás natural importado. |
| `items[].fuelDetail.startingAmount` | `vPart` | decimal | Valor de partida (`pGLP` × valor de venda). |
| `items[].fuelDetail.codif` | `CODIF` | string | Código de autorização/registro no CODIF. |
| `items[].fuelDetail.amountTemp` | `qTemp` | decimal | Quantidade de combustível faturada à temperatura ambiente. |
| `items[].fuelDetail.stateBuyer` | `UFCons` | string | UF de consumo do combustível. |
| `items[].fuelDetail.cide.bc` | `qBCProd` | decimal | Base de cálculo da CIDE (quantidade comercializada). |
| `items[].fuelDetail.cide.rate` | `vAliqProd` | decimal | Alíquota da CIDE em valor por unidade (R$). |
| `items[].fuelDetail.cide.cideAmount` | `vCIDE` | decimal | Valor da CIDE. |
| `items[].fuelDetail.pump.spoutNumber` | `nBico` | int | Número do bico utilizado no abastecimento. |
| `items[].fuelDetail.pump.number` | `nBomba` | int | Número da bomba ao qual o bico está interligado. |
| `items[].fuelDetail.pump.tankNumber` | `nTanque` | int | Número do tanque ao qual o bico está interligado. |
| `items[].fuelDetail.pump.beginningAmount` | `vEncIni` | decimal | Valor do encerrante no início do abastecimento. |
| `items[].fuelDetail.pump.endAmount` | `vEncFin` | decimal | Valor do encerrante no final do abastecimento. |
| `items[].vehicleDetail.*` | `veicProd/*` (campos J02–J26) | object | Dados do veículo novo (chassi, cor, potência, etc.). Ver §6.22. |

### 12.18. Resposta — Identificadores e Status

Os campos a seguir são preenchidos pelo **servidor** e retornados nos endpoints de consulta. Não devem ser enviados na requisição.

| Caminho JSON | Tag XML | Tipo | Observações |
|---|---|---|---|
| `id` | (interno) | string | Identificador interno do recurso na NFe.io. |
| `status` | `cStat` | enum | Status da NF-e. Ver §11.8.1. |
| `authorization.receiptOn` | `dhRecbto` | datetime | Data/hora do processamento pela SEFAZ. |
| `authorization.accessKey` | `chNFe` | string | Chave de acesso da NF-e (44 dígitos). |
| `authorization.message` | `xMsg` | string | Mensagem complementar retornada pela SEFAZ. |
| `authorization.description` | `xMotivo` | string | Descrição do motivo do status (`cStat`). |
| `contingencyDetails.authorizer` | (interno) | enum | Autorizador utilizado em contingência. |
| `contingencyDetails.startedOn` | (interno) | datetime | Data/hora de início da contingência. |
| `contingencyDetails.reason` | (interno) | string | Justificativa da entrada em contingência. |
| `lastEvents.events[]` | (interno) | array | Lista de eventos vinculados (cancelamento, CC-e, etc.). |

> **Notas finais:**
>
> 1. Os caminhos com `*` indicam que o subgrupo possui múltiplos campos com mesma estrutura — consulte a documentação específica do subgrupo (referenciada em §4.5 e §11).
> 2. Tags XML entre parênteses do tipo `(em X)` indicam que o tag tem o mesmo nome em vários grupos; o sufixo desambigua o grupo pai.
> 3. Para a relação completa entre `cClassTrib` (codClassTrib) e CST do IBS/CBS, consulte o Apêndice G (§10).

---

## Functional Documentation: NF-e/NFC-e Issuance API (v3)

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/documentation-nfe-layout-rtc/index.md

# Functional Documentation: NF-e/NFC-e Issuance API (v3)

**Document Version:** 1.0
**Last Revision Date:** October 24, 2025

---

## 1. Introduction

### 1.1. Objective

This document serves as a complete functional guide for using the API for issuing Product Invoices (NF-e, model 55) and Consumer Invoices (NFC-e, model 65). The objective is to detail the structure of the request body (`payload`), the purpose of each group and property, business rules, validations, and the context for filling out each field.

This documentation is intended for developers, system analysts, and any professional who needs to integrate third-party systems with the tax document issuance platform.

### 1.2. Reference Documents

The structure of this API was developed based on the following official documents:

*   **Taxpayer Orientation Manual (MOC):** Mainly "ANNEX I - Layout and Validation Rule - NF-e and NFC-e".
*   **Technical Note 2025.002 (v1.31):** Details the adjustments for the Consumption Tax Reform (RTC), including the new taxes IBS, CBS, and IS.
*   **Official XSD Schemas:** Such as `tiposBasico_v4.00.xsd` and the NF-e layout.

Throughout the document, the API fields are mapped to their respective fields in the SEFAZ XML (e.g., `(natOp)`), facilitating association for those already familiar with the official layout.

### 1.3. General Concepts

*   **Issuance Environment:** The API operates in two distinct environments:
    *   `Test` (Homologation): For integration testing, with no fiscal validity.
    *   `Production`: For issuing documents with fiscal validity.
*   **Document Models:**
    *   **NF-e (model 55):** Electronic Invoice, used to document operations of goods circulation between legal entities or between a legal entity and an individual.
    *   **NFC-e (model 65):** Electronic Consumer Invoice, used in in-person sales operations or for home delivery to the final consumer.

---

## 2. General Request Structure

The issuance of an invoice is performed via a `POST` request to the `/v2/companies/:companyId/productinvoices` endpoint. The request body is a JSON object that represents the entire invoice. Below, we detail each main group of this object.

### 2.1. Invoice Identification Group

This group contains the information that uniquely identifies the invoice and defines its main characteristics, such as the nature of the operation, dates, and purpose.

*   `serie` (integer): **Invoice Series (serie)**. A number that controls the numbering sequence.
    *   **Validations:** Value between 0 and 999. For NFC-e, series 890-899 are for exclusive use in contingency issuance (SCAN).
*   `number` (integer): **Invoice Number (nNF)**. Sequential number of the invoice within the series.
    *   **Validations:** Cannot be duplicated for the same issuer, model, and series.
*   `operationOn` (string): **Date and Time of Exit/Entry (dhSaiEnt)**. The date and time the goods left the establishment (for outgoing invoices) or entered (for incoming invoices). Format `YYYY-MM-DDThh:mm:ssTZD`. **Should not be filled for NFC-e (model 65)**.
    *   **Validations:** Cannot be later than the processing date. For an incoming NF-e, it cannot be earlier than the issuance date.
*   `expectedDeliveryOn` (string): **Expected Delivery Date (dPrevEntrega)**. The expected date for the delivery of the goods. Format `YYYY-MM-DD`. **Not applicable to NFC-e**.
    *   **Validations:** Cannot be earlier than the issuance date, nor more than 3 months after the exit date. Not allowed for adjustment (`finNFe=3`) or complementary (`finNFe=2`) purposes, nor for freight paid by the recipient (`modFrete=1`, FOB) or without freight (`modFrete=9`).
*   `operationNature` (string): **Description of the Nature of the Operation (natOp)**. Text describing the operation (e.g., "Sale of goods", "Shipment for repair"). This field must be consistent with the CFOP used in the items.
    *   **Validations:** Minimum of 2 characters.
*   `operationType` (enum): **Type of Fiscal Document (tpNF)**. Defines whether the invoice is `Incoming` or `Outgoing`.
    *   **Validations:** A return invoice (`purposeType` = `Devolution`) must be of type `Incoming`. A credit note (`finNFe=5`) must be of type `Incoming`.
*   `destination` (enum): **Destination Location Identifier (idDest)**. Indicates whether the operation is `Internal_Operation` (within the same state), `Interstate_Operation` (between states), or `International_Operation` (with a foreign country).
    *   **Validations:** If the recipient's state is the same as the issuer's, it must be `Internal_Operation`. If different, `Interstate_Operation`. If the country is not Brazil, `International_Operation`.
*   `consumptionCityCode` (integer): **Municipality Code of Taxable Event (cMunFG)**. IBGE code of the municipality where the tax (ICMS) is due. Usually, it is the issuer's municipality but may vary in specific cases.
    *   **Validations:** Mandatory if the delivery location's state is different from the issuer's state (for NF-e) or if the sale is in-person outside the establishment (for NFC-e).
*   `ibsConsumptionCityCode` (integer): **Municipality of IBS/CBS Taxable Event (cMunFGIBS)**. IBGE code of the municipality where the taxable event for the new taxes (IBS/CBS) occurs. Relevant for in-person operations outside the establishment, where consumption occurs in a different municipality.
    *   **Validations:** Mandatory only if `presenceType` is `5` (In-person operation, outside the establishment) and the recipient's or delivery address is not provided.
*   `printType` (enum): **DANFE Print Format (tpImp)**. Defines the print layout of the Auxiliary Document of the Electronic Invoice.
*   `purposeType` (enum): **Purpose of Issuance (finNFe)**. Indicates the purpose of the invoice: `Normal`, `Complement` (complementary), `Adjustment`, or `Devolution` (return).
    *   **Validations:** A complementary (`finNFe=2`), adjustment (`finNFe=3`), return (`finNFe=4`), or credit (`finNFe=5`) invoice must reference a fiscal document.
*   `debitType` (enum): **Type of Debit Note (tpNFDebito)**. Used in debit notes (finNFe=6) for specific Tax Reform scenarios, such as `finesAndInterest`.
    *   **Validations:** Can only be informed if the invoice purpose (`purposeType`) is `Debit` (purpose 6).
*   `creditType` (enum): **Type of Credit Note (tpNFCredito)**. Used in credit notes (finNFe=5) for scenarios like `valueReduction` or credit appropriation.
    *   **Validations:** Can only be informed if the invoice purpose (`purposeType`) is `Credit` (purpose 5).
*   `consumerType` (enum): **Final Consumer Operation Indicator (indFinal)**.
    *   `FinalConsumer`: The sale is to a final consumer.
    *   `Normal`: The sale is not to a final consumer.
    *   **Default Rule:** If this field is not provided, the value will be set based on the buyer's `federalTaxNumber`: "Normal" for CNPJ and "FinalConsumer" for CPF/NIF.
*   `presenceType` (enum): **Buyer Presence Indicator (indPres)**. Indicates how the commercial operation occurred (e.g., `Presence` for in-person, `Internet` for non-presential via the internet). Essential for differentiating in-store sales from e-commerce.
    *   **Validations:** For NFC-e, the allowed values are `Presence` or `Delivery` (home delivery).
*   `contingencyOn` (string) and `contingencyJustification` (string): **Contingency Entry (dhCont, xJust)**. Used for issuance in contingency mode when the SEFAZ environment is unavailable.
    *   **Validations:** The justification must have at least 15 characters.
*   `governmentPurchase` (object): **Government Purchases Group (gCompraGov)**. Details sales operations to public bodies, which may have specific taxation rules.

### 2.2. Buyer Group (`buyer`)

Contains all information about the recipient of the goods. **Mandatory group for NF-e (model 55)**.

*   `name` (string): **Name or Corporate Name (xNome)**.
*   `federalTaxNumber` (integer): **CNPJ or CPF**. For foreign operations, it can be the NIF (Tax Identification Number).
    *   **Validations:** For internal or interstate operations, it must be a valid CNPJ or CPF. If a CNPJ is provided, the State Tax Number (`stateTaxNumber`) may be mandatory depending on the state.
*   `tradeName` (string): **Trade Name (xFant)**.
*   `stateTaxNumber` (string): **State Tax Number (IE)**.
    *   **Validations:** If `stateTaxNumberIndicator` is `TaxPayer`, the IE must be provided and valid for the recipient's state. If `NonTaxPayer`, it should not be provided.
*   `stateTaxNumberIndicator` (enum): **Recipient's IE Indicator (indIEDest)**. Defines the recipient's relationship with ICMS. This field is crucial for the correct calculation of taxes like DIFAL.
    *   `TaxPayer`: ICMS taxpayer.
    *   `Exempt`: Taxpayer exempt from State Tax Number.
    *   `NonTaxPayer`: Not an ICMS taxpayer.
*   `address` (object): **Recipient's Address (enderDest)**. Object containing the complete address data.
    *   **Validations:** The municipality code (`city.code`) must correspond to the state (`state`).

### 2.3. Delivery and Withdrawal Location Groups

*   `delivery` (object): **Delivery Location Identification (entrega)**. Used **only** when the delivery location is different from the recipient's address. If it is the same, this group should not be filled.
    *   **Validations:** The CNPJ/CPF of the delivery location cannot be the same as the issuer's.
*   `withdrawal` (object): **Withdrawal Location Identification (retirada)**. Used **only** when the goods are picked up at a location different from the issuer's address.

### 2.4. Items Group (`items`)

This is an array of objects, where each object represents a product or service on the invoice. It is the most important and complex section of the fiscal document.

#### 2.4.1. Item Properties

*   `code` (string): **Product or Service Code (cProd)**. Internal product code in the issuer's system.
*   `codeGTIN` (string): **GTIN (cEAN)**. Barcode of the product, if any.
*   `description` (string): **Product or Service Description (xProd)**.
    *   **Validations:** Cannot be filled with generic terms like "MISCELLANEOUS".
*   `ncm` (string): **NCM Code (NCM)**. Mercosur Common Nomenclature. A fundamental field for correct taxation.
    *   **Validations:** Must be a valid NCM code from the official table. For some products, the full 8-digit NCM is mandatory.
*   `cest` (string): **CEST Code (CEST)**. Specifier Code for Tax Substitution. Mandatory for products listed in ICMS-ST agreements.
    *   **Validations:** Mandatory if the product is subject to tax substitution, according to ICMS agreements.
*   `cfop` (integer): **Fiscal Code of Operations and Services (CFOP)**. A numeric code that defines the nature of the item's operation (sale, shipment, return, etc.) and its taxation.
    *   **Validations:** Must be a valid code. The first digit must be compatible with the operation type (e.g., 5 or 6 for outgoing, 1 or 2 for incoming).
*   `quantity` (number): **Commercial Quantity (qCom)**.
*   `unit` (string): **Commercial Unit (uCom)** (e.g., "UN", "BOX", "KG").
*   `unitAmount` (number): **Commercial Unit Price (vUnCom)**.
*   `totalAmount` (number): **Gross Total Product Value (vProd)**. Result of `quantity * unitAmount`.
    *   **Validations:** The value must be the result of multiplying the quantity by the unit price, with a small tolerance for rounding.
*   `freightAmount`, `insuranceAmount`, `othersAmount` (number): Values for freight, insurance, and other ancillary expenses that are prorated and make up the total item value.
*   `totalIndicator` (boolean): **Totalization Indicator (indTot)**. Indicates if the item's value (`vProd`) is included in the calculation of the total NF-e value.
    *   **Validations:** For an adjustment NF-e (`purposeType` = `Adjustment`), this field must be `false`.
*   `numberOrderBuy` (string): **Purchase Order Number (xPed)**.

#### 2.4.2. Item Tax Group (`tax`)

Within each item, the `tax` object details all taxes levied on the product or service.

*   `totalTax` (number): **Approximate Total Taxes (vTotTrib)**. Estimated tax value according to the Transparency Law.

*   **Old Regime Taxes:**
    *   `icms` (object): **ICMS Group**. Contains ICMS taxation, with fields like `origin`, `cst`, `baseTax`, `rate`, and `amount`. The internal structure varies according to the CST.
        *   **Validations:** Only one of the ICMS taxation groups (ICMS00, ICMS10, ICMS20, etc.) can be filled, according to the informed CST.
    *   `ipi` (object): **IPI Group**. Details the taxation of the Tax on Industrialized Products.
    *   `pis` (object): **PIS Group**.
    *   `cofins` (object): **COFINS Group**.

*   **Tax Reform (RTC) Taxes:**
    *   `IS` (object): **Selective Tax**. Filled for products subject to this tax (e.g., cigarettes, sugary drinks). Contains `situationCode`, `basis`, `rate`, and `amount`.
        *   **Validations:** The use of this group is mandatory if the item's `cClassTribIS` indicates the incidence of the Selective Tax. The tax value (`amount`) must be the result of the tax base (`basis`) multiplied by the rate (`rate`).
    *   `IBSCBS` (object): **IBS and CBS Group**. The central group of the RTC, mandatory for operations under the new regime from 01/05/2026.
        *   `situationCode` (string): Tax Situation Code for IBS/CBS.
        *   `classCode` (string): Tax Classification Code, which defines the specific regime of the item (e.g., general taxation, exemption, reduced rate).
            *   **Validations:** The `classCode` must be a valid code from the official table and compatible with the informed `situationCode`.
        *   `basis` (number): Unified tax base.
        *   `calculationMode` (enum): Tax calculation mode. Allows choosing between manual filling (`Manual`, default value) or automatic calculation via an official service (`OfficialService`). When `OfficialService` is used, only `situationCode` and `classCode` are necessary, and the other tax fields are filled by the service.
        *   `state` (object): Details the calculation of **State IBS** (`rate`, `amount`, `deferment`, `reduction`).
        *   `municipal` (object): Details the calculation of **Municipal IBS**.
        *   `cbs` (object): Details the calculation of **CBS**.
            *   **Validations:** The `amount` values in each subgroup must be calculated correctly based on the `basis` and the respective rates and benefits.
            *   **Validations (RTC):** For debit or credit notes (`finNFe` = 5 or 6), it is forbidden to inform the tax groups of the old regime (ICMS, IPI, PIS, COFINS, etc.).
        *   Optional subgroups like `monophase` (monophasic taxation), `operationalPresumedCredit`, `governmentPurchase`, etc.

*   `taxDetermination` (object): **Group for Automatic Tax Determination**. If filled, the system can automatically calculate the taxes for the `IBSCBS` group based on information like `operationCode`, `issuerTaxProfile`, and `buyerTaxProfile`.

### 2.5. Transport Group (`transport`)

Contains information about the transportation of the goods.

*   `freightModality` (enum): **Freight Modality (modFrete)**. Defines who is responsible for the freight (e.g., `ByIssuer` - CIF, `ByReceiver` - FOB, `Free`).
    *   **Validations:** If the modality is `Free`, the carrier, vehicle, and volume groups should not be filled.
*   `transportGroup` (object): **Carrier Data (transporta)**. Information such as `name`, `federalTaxNumber`, `stateTaxNumber`, and `address`.
*   `transportVehicle` (object): **Vehicle Data (veicTransp)**. License plate (`plate`) and state of the vehicle.
*   `reboque` (object): **Trailer Data**.
*   `volume` (object): **Transported Volumes Data (vol)**. Information such as quantity (`volumeQuantity`), species (`species`), net weight (`netWeight`), and gross weight (`grossWeight`).

### 2.6. Payment Group (`payment`)

Array of objects detailing the payment methods.

*   `paymentDetail` (array): Payment details.
    *   `method` (enum): **Payment Method (tPag)** (e.g., `Cash`, `CreditCard`, `InstantPayment` for PIX).
    *   `amount` (number): **Payment Amount (vPag)**.
        *   **Validations:** The sum of the values of all payments must be equal to the total value of the invoice.
    *   `paymentType` (enum): **Payment Form Indicator (indPag)**: `InCash` (cash/upfront) or `Term` (installments).
    *   `card` (object): If payment is by card, this group contains transaction data, such as the flag (`flag`), the acquirer's CNPJ, and the authorization number.
        *   **Validations:** Mandatory if the payment method is `CreditCard` or `DebitCard`.
*   `payBack` (number): **Change Amount (vTroco)**.

### 2.7. Billing Group (`billing`)

Used to detail the commercial billing of the operation.

*   `bill` (object): **Invoice (fat)**. Contains number (`number`), original amount (`originalAmount`), discount (`discountAmount`), and net amount (`netAmount`).
*   `duplicates` (array): **Installments (dup)**. Array with the invoice installments, each with a number (`number`), due date (`expirationOn`), and amount (`amount`).

### 2.8. Totals Group (`totals`)

Summarizes the total values of the invoice. Most of these fields are calculated by the system based on the items, but it is important that the source system also calculates them for validation.

*   `icms` (object): **ICMS Totals (ICMSTot)**. Contains the sum of tax bases, ICMS values, ICMS-ST, total value of products, freight, insurance, discount, and the total invoice amount (`invoiceAmount`) according to the old regime.
    *   **Validations:** Each field in this group must correspond to the sum of the respective field from all items on the invoice.
*   `issqn` (object): **ISSQN Totals (ISSQNtot)**. Sums related to the Tax on Services.
*   `withheldTaxes` (object): **Withheld Taxes (retTrib)**. Withheld amounts of PIS, COFINS, CSLL, IRRF, and Social Security.
*   `isTotals` (object): **Selective Tax Totals (ISTot)**. Sum of the Selective Tax value from all items.
    *   **Validations:** The total amount (`amount`) must be the sum of the `IS.amount` values from all items.
*   `ibsCbsTotals` (object): **IBS and CBS Totals (IBSCBSTot)**. Consolidates the totals of the tax base, IBS values (state and municipal), CBS, deferrals, returns, etc.
    *   **Validations:** The values in this group must be the sum of the corresponding values from the `IBSCBS` group of each item.
*   `totalInvoiceAmount` (number): **Total NF-e Amount with RTC (vNFTot)**. Represents the final total value of the invoice, considering the sum of products and all taxes, including the new ones (IBS, CBS, IS).
    *   **Validations:** Must be the sum of `totals.icms.invoiceAmount` with the totals from `isTotals` and `ibsCbsTotals`.

### 2.9. Additional Information Group (`additionalInformation`)

Free text fields and references for complementary information.

*   `fisco` (string): **Additional Information for the Tax Authority (infAdFisco)**.
*   `taxpayer` (string): **Complementary Information for the Taxpayer (infCpl)**.
*   `xmlAuthorized` (array): **Authorized to Download XML (autXML)**. List of CNPJs or CPFs of third parties (e.g., accountant) authorized to access the document's XML.
    *   **Validations:** Must be valid CNPJs or CPFs. **Maximum of 10 authorizations.**
*   `taxDocumentsReference` (array): **Referenced Fiscal Documents (NFref)**. Used to reference access keys of other invoices (e.g., in a return). Each item may contain one of three types:
    *   `documentElectronicInvoice`: Referenced NF-e/NFC-e (44-digit access key in `accessKey`).
    *   `documentInvoiceReference`: Referenced model 1/1A invoice (fields `state`, `yearMonth`, `federalTaxNumber`, `model`, `series`, `number`).
    *   `taxCouponInformation`: Referenced fiscal coupon (fields `modelDocumentFiscal`, `orderECF`, `orderCountOperation`).
    *   **Validations:** The referenced access key must be valid and exist in the SEFAZ database.
*   `advancePayment` (array): **Advance Payment Notes (gPagAntecipado)**. Used to offset advance payment installments according to art. 10 § 4. Each item contains only `accessKey`.
*   `taxpayerComments` (array): **Fiscal Observations (obsCont)**. List of `field`/`text` pairs for free-form taxpayer observations.
*   `referencedProcess` (array): **Referenced Processes (procRef)**. To inform numbers of judicial or administrative processes that support the operation. Each item contains:
    *   `identifierConcessory` (string): Identifier of the concession act.
    *   `identifierOrigin` (integer): Process origin indicator (1=SEFAZ, 2=Federal Justice, 3=State Justice, 9=Others).
    *   `concessionActType` (integer): Type of the concession act.

### 2.10. Issuer Group (`issuer`) — Response Only

> **Note:** Unlike most groups, `issuer` is **not sent in the issuance request**. It is determined automatically from the company registry (`companyId` in the URL) and populated by the API in responses. This group is detailed here for reference when consuming query endpoints.

Identifies the NF-e issuer (`emit` in XML).

*   `name` (string): **Name or Corporate Name (xNome)**.
*   `federalTaxNumber` (integer): **Issuer's CNPJ**.
*   `tradeName` (string): **Trade Name (xFant)**.
*   `regionalTaxNumber` (integer): **State Registration (IE)** at the SEFAZ of the issuer's UF.
*   `regionalSTTaxNumber` (integer): **Tax Substitute IE (IEST)** when the issuer is a tax substitute.
*   `municipalTaxNumber` (string): **Municipal Registration (IM/CCM)**.
*   `companyRegistryNumber` (integer): **Commercial Board Registration Number (nIRE)**.
*   `address` (AddressResource): Issuer's address (`enderEmit`).
*   `taxRegime` (enum `TaxRegime`): Tax Regime Code (CRT). See §11.3.1.
*   `specialTaxRegime` (enum `SpecialTaxRegime`): Special tax regime (`indRegTrib`). See §11.3.2.
*   `legalNature` (enum `LegalNature`): Company's legal nature. See §11.10.
*   `economicActivities` (array): List of company **CNAEs**, each item with `type` (`Main`/`Secondary`) and `code` (numeric code).
*   `openningDate` (string): Company opening date (`dIniAtiv`).
*   `stStateTaxNumber` (string): **Tax Substitute IE (IEST)** — also exposed in the request payload via `issuerTaxSubstitute` when relevant for the specific operation.

### 2.11. Purchase Information Group (`purchaseInformation`)

Details commercial references of the operation. Mainly applicable to sales to public agencies.

*   `commitmentNote` (string): **Commitment Note (xNEmp)**. Identification of the commitment when dealing with public purchases. Min. 1, max. 22 characters.
*   `purchaseOrder` (string): **Purchase Order (xPed)**. Purchase order identification. Min. 1, max. 60 characters.
*   `contractNumber` (string): **Contract (xCont)**. Contract identification. Min. 1, max. 60 characters.

> **Difference vs. `additionalInformation.order` / `contract`:** Fields in `additionalInformation` are generic free text. The `purchaseInformation` group is structured and maps directly to the `compra` group in XML — preferable for government purchases.

### 2.12. Export Group (`export`)

Applicable only to operations with `destination = InternationalOperation`.

*   `state` (enum `StateCode`): UF abbreviation of embarkation or border crossing.
*   `office` (string): **Embarkation Place (xLocExporta)**. Description of the physical exit location of the goods (e.g., "Port of Santos", "Guarulhos Airport").
*   `local` (string): **Customs Clearance Place (xLocDespacho)**. Customs clearance location.

### 2.13. Transaction Intermediate Group (`transactionIntermediate`)

Applicable when the sale is made through a **marketplace, delivery platform, or broker**.

*   `federalTaxNumber` (integer): **Intermediator CNPJ (CNPJ)**. CNPJ of the intermediating platform.
*   `identifier` (string): **Identifier in the Intermediator (idCadIntTran)**. Internal seller/store ID on the intermediating platform.

> **When to fill:** Whenever the transaction was originated/processed by a third party (Marketplace), even if the payment was made directly to the issuer. SEFAZ uses this group for fiscal reconciliation between the issuer and the platform.

### 2.14. Contingency Group (`contingencyOn` / `contingencyJustification`)

When SEFAZ is unavailable (timeout, 5xx error, degraded service status), the NF-e can be issued in **contingency mode**:

*   `contingencyOn` (string, ISO 8601): Date and time of entry into contingency (`dhCont`).
*   `contingencyJustification` (string): Textual justification of entry into contingency (`xJust`). **Minimum 15 characters**, maximum 1,000.

The invoice is processed locally and later synchronized with SEFAZ. The NF-e status is `IssuedContingency` until synchronization is successful.

> **Recommendation:** Configure the issuer to manage contingency automatically via the State Registration registry instead of filling manually — see §9.4.

### 2.15. Special Item Subgroups

In addition to the basic fields described in §2.4.1 and §2.4.2, each item may contain specific subgroups for product/operation types:

#### 2.15.1. `vehicleDetail` — New Vehicles

Applicable when the item is a **brand-new (0 km) vehicle**. Full detail in §6.22 (all fields J02–J26 of the official layout).

#### 2.15.2. `fuelDetail` — Fuels

Applicable when the item is a **fuel** subject to ANP control.

```json
"fuelDetail": {
  "codeANP": "210203001",
  "percentageNG": 50.0,
  "descriptionANP": "GLP",
  "percentageGLP": 40.0,
  "percentageNGn": 30.0,
  "percentageGNi": 20.0,
  "startingAmount": 100.0,
  "codif": "CODIF-123",
  "amountTemp": 10.0,
  "stateBuyer": "RJ",
  "cide": { "bc": 10.0, "rate": 5.0, "cideAmount": 0.5 },
  "pump": { "spoutNumber": 1, "number": 1, "tankNumber": 1, "beginningAmount": 1000.0, "endAmount": 1010.0, "percentageBio": 10.0 },
  "fuelOrigin": { "indImport": 1, "cUFOrig": 35, "pOrig": 10.0 }
}
```

*   **`codeANP`:** ANP product code (`cProdANP`).
*   **`descriptionANP`:** Product description per ANP (`descANP`).
*   **`percentageNG`, `percentageGLP`, `percentageNGn`, `percentageGNi`:** Mixture percentages for the GLP product (`cProdANP=210203001`).
*   **`startingAmount`:** Starting value (`vPart`).
*   **`codif`:** CODIF authorization code.
*   **`amountTemp`:** Quantity invoiced at ambient temperature (`qTemp`).
*   **`stateBuyer`:** Consumption UF abbreviation (`UFCons`).
*   **`cide`:** CIDE (Contribution for Intervention in the Economic Domain) group with `bc` (BC), `rate` (rate), `cideAmount` (amount).
*   **`pump`:** Fuel pump data for stations:
    *   `spoutNumber`/`number`/`tankNumber`: Physical identification (spout, pump, tank).
    *   `beginningAmount`/`endAmount`: Initial and final pump reading of the supply.
    *   `percentageBio`: Biodiesel B100 mixture percentage in B Diesel.
*   **`fuelOrigin`:** Fuel origin:
    *   `indImport`: Import indicator.
    *   `cUFOrig`: Origin UF code.
    *   `pOrig`: Originating percentage for the UF.

> **Mutual exclusion:** `vehicleDetail`, `fuelDetail` (and `medicineDetail` when applicable) are mutually exclusive. If more than one is sent, the order of precedence prevails: medicine > vehicle > fuel.

#### 2.15.3. `presumedCredit` — Per-Item Presumed Credit (ICMS regime)

Presumed credit specific to the old regime, as required by the UF (NT 2019.001).

```json
"presumedCredit": {
  "code": "BENEF-001",   // Benefit code in the UF (cCredPresumido). Length 8 or 10
  "rate": 4.0,           // Percentage (pCredPresumido) — use fraction, e.g.: 0.04 = 4%
  "amount": 80.08        // Value (vCredPresumido)
}
```

> **Different from `operationalPresumedCredit` of `IBSCBS`:** this one is specific to ICMS and uses UF benefit codes. The `operationalPresumedCredit` is from the Tax Reform (RTC).

#### 2.15.4. `importDeclarations` — Import Declarations (DI)

Array of DIs linked to the item. Each DI contains:

*   `code`: Import Document Number (`nDI`).
*   `registeredOn`: DI/DSI/DA registration date (`dDI`).
*   `customsClearanceName`: Customs clearance location (`xLocDesemb`).
*   `customsClearanceState` (enum `StateCode`): Clearance UF (`UFDesemb`).
*   `customsClearancedOn`: Clearance date (`dDesemb`).
*   `additions`: Array of additions with `code` (no.), `manufacturer` (manuf. code), `amount` (vDescDI), `drawback` (concession act no.).
*   `exporter`: Exporter code (`cExportador`).
*   `internationalTransport` (enum `InternationalTransportType`): DI transport mode. See §11.6.3.
*   `intermediation` (enum `IntermediationType`): Intermediation form. See §11.6.2.
*   `acquirerFederalTaxNumber`: Acquirer/orderer's CNPJ/CPF.
*   `stateThird`: Acquirer/orderer's UF.

#### 2.15.5. `exportDetails` — Per-Item Export Detail

Item linkage to an Export Registry (RE) or DEC (Common Export Declaration).

*   `drawback`: Concession act number (`nDraw`).
*   `hintInformation`:
    *   `registryId`: RE number (`nRE`).
    *   `accessKey`: Access key of the NF-e received for export (`chNFe`).
    *   `quantity`: Quantity actually exported (`qExport`).

#### 2.15.6. `referencedDFe` — Referenced Electronic Fiscal Document

Item-by-item reference to a specific item of another DF-e (typical use: return invoice referencing the original NF-e).

*   `accessKey` (string, 44 chars): Access key of the referenced DF-e.
*   `itemNumber` (integer 1–999): Item number in the original DF-e (`nItem`).

#### 2.15.7. `taxDetermination` — Automatic Tax Calculation

When filled, **replaces the manual fill of `tax`** and triggers automatic calculation via the internal Tax Engine:

*   `operationCode` (integer): Internal code for determining the operation nature.
*   `issuerTaxProfile` (string): Seller (origin) tax profile — e.g., `industry`, `retail`, `wholesale`.
*   `buyerTaxProfile` (string): Buyer (destination) tax profile — e.g., `final_consumer_non_icms_contributor`, `industry_icms_contributor`.
*   `origin` (string): Goods origin (same enum as `tax.icms.origin`).
*   `acquisitionPurpose` (string): Acquisition purpose.

> **Order of precedence:**
> 1. If `taxDetermination` is filled → automatic calculation.
> 2. Otherwise, `tax.IBSCBS` with `calculationMode = OfficialService` → automatic calculation only of IBS/CBS.
> 3. Otherwise, all `tax` fields must be filled manually.

---

## 3. Appendix A: Main Group Mapping

The table below summarizes the mapping of the main groups from the API's JSON to the SEFAZ XML groups.

| API Group (JSON) | SEFAZ XML Group | Description |
|---|---|---|
| (root of object) | `ide` | NF-e Identification |
| `issuer` | `emit` | Issuer Data |
| `buyer` | `dest` | Recipient Data |
| `delivery` | `entrega` | Delivery Location |
| `withdrawal` | `retirada` | Withdrawal Location |
| `items` | `det` | Detail of Products and Services (Items) |
| `items.tax` | `imposto` | Taxes incident on the item |
| `items.tax.icms` | `ICMS` | ICMS Group |
| `items.tax.ipi` | `IPI` | IPI Group |
| `items.tax.pis` | `PIS` | PIS Group |
| `items.tax.cofins` | `COFINS` | COFINS Group |
| `items.tax.IS` | `IS` | Selective Tax Group (RTC) |
| `items.tax.IBSCBS` | `IBSCBS` | IBS and CBS Group (RTC) |
| `totals` | `total` | Total Values Group |
| `totals.icms` | `ICMSTot` | ICMS Totals |
| `totals.issqn` | `ISSQNtot` | ISSQN Totals |
| `totals.isTotals` | `ISTot` | Selective Tax Totals (RTC) |
| `totals.ibsCbsTotals` | `IBSCBSTot` | IBS and CBS Totals (RTC) |
| `transport` | `transp` | Transport Data |
| `billing` | `cobr` | Billing Data (Invoice and Installments) |
| `payment` | `pag` | Payment Data |
| `additionalInformation` | `infAdic` | Additional Information |
| `purchaseInformation` | `compra` | Purchase Information (commitment, order) |
| `export` | `exporta` | Export Information |
| `transactionIntermediate` | `infIntermed` | Transaction Intermediary Information |

---

## 4. Appendix B: Detailed Structure of New Tax Reform Groups

### 4.1. `items.tax.IS`

```json
"IS": {
  "situationCode": "101",
  "classificationCode": "IS0001",
  "basis": 2002.0,
  "rate": 5.0,
  "amount": 100.1
}
```

*   **Purpose:** To declare the Selective Tax.
*   **`situationCode`:** Defines the IS taxation for the item.
*   **`classificationCode`:** Classifies the item into one of the Selective Tax categories.
*   **`basis`:** Value on which the rate (`rate`) will be applied.
*   **`amount`:** Final tax amount (`basis * rate / 100`).

### 4.2. `items.tax.IBSCBS`

```json
"IBSCBS": {
  "situationCode": "101",
  "classCode": "RT0001",
  "basis": 2002.0,
  "state": {
    "rate": 10.0,
    "deferment": { "rate": 1.0, "amount": 20.02 },
    "reduction": { "rateReduction": 0.5, "effectiveRate": 9.5 },
    "amount": 190.19
  },
  "municipal": {
    "rate": 5.0,
    "amount": 96.1
  },
  "cbs": {
    "rate": 12.0,
    "amount": 216.22
  },
  "ibsTotalAmount": 286.29
}
```

*   **Purpose:** To declare the new consumption taxes, IBS and CBS.
*   **`situationCode` and `classCode`:** Keys to determine the item's tax regime.
*   **`basis`:** Common tax base for the taxes.
*   **`state` and `municipal`:** Detail the IBS, which is a dual tax. They contain the nominal rate (`rate`), the final amount (`amount`), and may contain subgroups for benefits like deferment (`deferment`) or rate reduction (`reduction`).
*   **`cbs`:** Details the CBS, which is a single federal tax.
*   **`ibsTotalAmount`:** Sum of the values of `state.amount` and `municipal.amount`.

### 4.3. `totals.isTotals` and `totals.ibsCbsTotals`

```json
"totals": {
  // ... other totals
  "isTotals": {
    "amount": 100.1
  },
  "ibsCbsTotals": {
    "basis": 2002.0,
    "ibs": {
      "state": { "defermentAmount": 20.02, "amount": 190.19 },
      "municipal": { "amount": 96.1 },
      "totalAmount": 286.29
    },
    "cbs": {
      "amount": 216.22
    }
  },
  "totalInvoiceAmount": 2675.04
}
```

*   **Purpose:** To consolidate the total values of the new taxes for the entire invoice.
*   **`isTotals.amount`:** Sum of the `amount` field from all `IS` groups of the items.
*   **`ibsCbsTotals`:** Aggregates the tax bases and values of IBS and CBS from all items, separating totals by sphere (state, municipal, federal) and by benefit type (deferment, return).
*   **`totalInvoiceAmount`:** The new total invoice amount, calculated as: `totals.icms.invoiceAmount` (old value) + `totals.isTotals.amount` + `totals.ibsCbsTotals.ibs.totalAmount` + `totals.ibsCbsTotals.cbs.amount`.

### 4.4. IBS/CBS Tax Benefit Subgroups

Both `state` and `municipal` (IBS) and `cbs` (CBS) share the same internal structure to represent **tax benefits** that reduce the tax due. Each may optionally contain three subgroups:

#### 4.4.1. `deferment` — Deferment (`gDif`)

Represents **tax deferment**: the tax is calculated but its payment is postponed to a later stage in the chain.

```json
"deferment": {
  "rate": 1.0,        // Deferment percentage (pDif)
  "amount": 20.02     // Deferred value (vICMSDif)
}
```

*   **`rate`:** Percentage of the rate being deferred.
*   **`amount`:** Monetary value of the deferment, calculated as `(basis * rate.deferred) / 100`.
*   **When it appears in XML:** Only when `cClassTrib` indicates deferment (CST `510`).

#### 4.4.2. `reduction` — Rate Reduction (`gRed`)

Represents **rate reduction** (not of the calculation base). The effective rate applied is lower than the nominal one.

```json
"reduction": {
  "rateReduction": 40.0,    // Reduction percentage (pRedAliq)
  "effectiveRate": 0.06     // Effective rate after reduction (pAliqEfet)
}
```

*   **`rateReduction`:** Percentage of the reduction applied to the nominal rate (e.g., 40 means 40% reduction).
*   **`effectiveRate`:** Effective rate resulting after the reduction (`rate * (1 - rateReduction/100)`).
*   **Critical invariant:** The `rate` field at the top level (`state.rate`, `municipal.rate`, `cbs.rate`) **must always be the nominal rate**, never the effective one. The effective rate stays exclusively in `reduction.effectiveRate`. This separation is enforced by the API.

#### 4.4.3. `returnedAmount` — Tax Return (`gDevTrib`)

Represents **tax return** to the acquirer in cases such as goods return or accounting adjustment.

```json
"returnedAmount": {
  "amount": 10.0    // Amount to return (vDevTrib)
}
```

### 4.5. Special IBS/CBS Subgroups

In addition to per-jurisdiction tax benefits, `IBSCBS` accepts special subgroups for specific tax regimes.

#### 4.5.1. `monophase` — Monophasic Taxation (`gMonofasicoIBSCBS`)

Applicable to **fuels** and other products subject to monophasic taxation (ad rem rate per taxable unit, art. 172-180 LC 214/2025).

```json
"monophase": {
  "standart": {
    "quantityBasis": 10.0,
    "ibsAdRemRate": 15.0,
    "cbsAdRemRate": 25.0,
    "ibsAmount": 150.0,
    "cbsAmount": 250.0
  },
  "withholding": { /* monophasic taxation subject to withholding */ },
  "previouslyWithheld": { /* monophasic previously withheld */ },
  "deferment": { /* monophasic deferment (biofuels) */ },
  "ibsAmount": 140.0,    // Total monophasic IBS for the item (vTotIBSMonoItem)
  "cbsAmount": 255.0     // Total monophasic CBS for the item (vTotCBSMonoItem)
}
```

*   **`standart` (gMonofasicoPadrao):** Monophasic taxation applied in the chain in a single stage.
    *   `quantityBasis`: Taxed base quantity (qBCMono).
    *   `ibsAdRemRate` / `cbsAdRemRate`: Ad rem rate in BRL per taxable unit.
    *   `ibsAmount` / `cbsAmount`: `quantityBasis * adRemRate`.
*   **`withholding` (gMonofasicoRetido):** Monophasic taxation in which the issuer is responsible for withholding.
*   **`previouslyWithheld` (gMonofasicoRetidoAnt):** Monophasic taxation that was withheld in a previous stage of the chain (informational, no effect on the final value).
*   **`deferment` (gMonofasicoDif):** Deferment specifically applicable to biofuels in monophasic taxation.
*   **`ibsAmount` / `cbsAmount`:** Consolidated item totals for monophasic IBS and CBS.

#### 4.5.2. `operationalPresumedCredit` — Operational Presumed Credit (`gCredPresOper`)

Presumed credit on specific operations (non-taxpayer rural producer, recycling from individuals, used goods from individuals for resale, etc.).

```json
"operationalPresumedCredit": {
  "basis": 1000.0,
  "classificationCode": "RuralProducerNonTaxpayer",
  "ibs": {
    "rate": 10.0,
    "amount": 100.0,
    "suspensiveConditionAmount": 10.0
  },
  "cbs": {
    "rate": 5.0,
    "amount": 50.0,
    "suspensiveConditionAmount": 5.0
  }
}
```

*   **`basis`:** Calculation base of the presumed credit (vBC).
*   **`classificationCode`:** Type of presumed credit (see enum `PresumedCreditClassificationCode` in Appendix H).
*   **`ibs` / `cbs`:**
    *   `rate`: Presumed credit percentage (pCredPres).
    *   `amount`: Presumed credit value (vCredPres).
    *   `suspensiveConditionAmount`: Portion of the credit subject to suspensive condition (vCredPresCondSus). Materializes only when the condition is met.

#### 4.5.3. `creditTransfer` — Credit Transfer (`gTransfCred`)

Applicable in **merger, spin-off, incorporation, or transfer between cooperatives and members** (CST `800`).

```json
"creditTransfer": {
  "ibsAmount": 50.0,    // IBS to transfer (vIBS)
  "cbsAmount": 30.0     // CBS to transfer (vCBS)
}
```

#### 4.5.4. `creditReversal` — Credit Reversal (`gEstornoCred`)

Applicable when there is prohibition or obligation of credit reversal as per `cClassTrib` (`ind_gEstornoCred` field in the table).

```json
"creditReversal": {
  "ibsReversalAmount": 2.0,    // IBS to reverse (vIBSEstCred)
  "cbsReversalAmount": 1.0     // CBS to reverse (vCBSEstCred)
}
```

#### 4.5.5. `governmentPurchase` — Government Purchase Composition (`gCompraGov`)

Details how IBS and CBS are composed in sales to direct public administration agencies, autarchies, and foundations (art. 472/370 LC 214/2025). Applicable when the (root) `governmentPurchase` group is filled.

```json
"governmentPurchase": {
  "stateRate": 8.0,       "stateAmount": 160.16,
  "municipalRate": 4.0,   "municipalAmount": 80.08,
  "cbsRate": 10.0,        "cbsAmount": 200.2
}
```

*   Repeats the `rate`/`amount` structure for the three jurisdictions (UF, Municipality, CBS), but considering the `pRedutor` reduction applied to the government purchase.

#### 4.5.6. `regularTaxation` — Hypothetical Regular Taxation

When there is a **resolutive or suspensive condition** (e.g., zero rate conditioned to specific destination), declare here what the taxation would be if the condition is not met. Important for assessment and audit.

```json
"regularTaxation": {
  "situationCode": "101",
  "classCode": "RT0001",
  "stateEffectiveRate": 10.0,    "amount": 200.2,
  "municipalEffectiveRate": 5.0, "municipalAmount": 100.1,
  "cbsEffectiveRate": 12.0,      "cbsAmount": 240.24
}
```

*   **`situationCode` (CSTReg):** CST that would apply if the resolutive/suspensive condition fell.
*   **`classCode` (cClassTribReg):** Regular tax classification.
*   **Pairs `stateEffectiveRate`/`amount`, `municipalEffectiveRate`/`municipalAmount`, `cbsEffectiveRate`/`cbsAmount`:** Effective rate and value that would be assessed.

#### 4.5.7. `zfmPresumedCredit` — ZFM Presumed Credit (`gCredPresIBSZFM`)

Presumed credit specific to supplies from the Manaus Free Trade Zone (art. 450 LC 214/2025).

```json
"zfmPresumedCredit": {
  "classificationCode": "IntermediateGoods",   // tpCredPresIBSZFM
  "amount": 123.45                              // vCredPresIBSZFM
}
```

*   **`classificationCode`:** Determines the applicable percentage (55%, 75%, 90.25%, 100% — see enum `IbsZfmPresumedCreditClassification` in Appendix H).
*   **`amount`:** Value of the presumed credit. Mandatory when `creditType = 02`.

### 4.6. `donationIndicator` and `competenceAdjustment`

#### 4.6.1. `donationIndicator` — Donation Indicator (`indDoacao`)

When the operation is a **donation** (e.g., donation to a charitable entity, transfer without consideration), inform this field in `IBSCBS` so that the assessment correctly handles debits/reversals. Values: `"0"` (not a donation) / `"1"` (donation). 1-character field; inform only when applicable.

#### 4.6.2. `competenceAdjustment` — Competence Adjustment (`gAjusteCompet`)

Reopens a previous fiscal competence period to include an IBS/CBS adjustment:

```json
"competenceAdjustment": {
  "assessmentPeriod": "2025-09",   // YYYY-MM (competApur)
  "ibsAmount": 5.0,                 // adjustment vIBS
  "cbsAmount": 3.0                  // adjustment vCBS
}
```

Typically applicable to invoices with `purposeType = Credit` or `Debit`.

---

## 5. Final Considerations

The API structure was designed to be flexible and accommodate both the current tax system and the new model of the Tax Reform. During the transition period, the old tax groups (ICMS, PIS, COFINS) and the new ones (IS, IBSCBS) will coexist.

It is crucial that issuing systems consult the official tables (CST, cClassTrib, etc.) and follow the validation rules described in the Taxpayer Manual and Technical Notes to ensure the correct issuance and authorization of fiscal documents.

For more details on specific validation rules, consult the SEFAZ documentation and current Technical Notes.

---

## 6. Appendix C: Detailed Resource Objects

This appendix details the structure of the main objects and sub-objects referenced in the API request body.

### 6.1. AddressResource

Defines the structure of an address, used in the `buyer`, `delivery`, `withdrawal`, and `transportGroup` groups.

*   `street` (string): Street Address (xLgr).
*   `number` (string): Address Number (nro).
*   `additionalInformation` (string): Address Complement (xCpl).
*   `district` (string): Neighborhood (xBairro).
*   `city` (CityResource): Object containing the municipality code (`code`) and name (`name`).
*   `state` (string): State abbreviation.
*   `postalCode` (string): Postal Code (CEP).
*   `country` (string): Country code or name.
*   `phone` (string): Phone number.

### 6.2. BuyerResource

Contains the registration information of the invoice recipient.

*   `name` (string): Name or Corporate Name (xNome).
*   `federalTaxNumber` (integer): CNPJ or CPF.
*   `tradeName` (string): Trade Name (xFant).
*   `stateTaxNumber` (string): State Tax Number (IE).
*   `stateTaxNumberIndicator` (enum): Recipient's IE Indicator (`TaxPayer`, `Exempt`, `NonTaxPayer`).
*   `address` (AddressResource): Object with the recipient's address data.
*   `email` (string): Recipient's email.
*   `type` (enum): Person type (`NaturalPerson`, `LegalEntity`).
*   `taxRegime` (enum): Tax regime.

### 6.3. DeliveryInformationResource

Defines the delivery location, **if and only if** it is different from the recipient's address.

*   `federalTaxNumber` (integer): CNPJ or CPF of the delivery location.
*   `name` (string): Name or Corporate Name.
*   `stateTaxNumber` (string): State Tax Number.
*   `address` (AddressResource): Object with the complete delivery address data.

### 6.4. WithdrawalInformationResource

Defines the withdrawal location, **if and only if** it is different from the issuer's address.

*   `federalTaxNumber` (integer): CNPJ or CPF of the withdrawal location.
*   `name` (string): Name or Corporate Name.
*   `address` (AddressResource): Object with the complete withdrawal address data.

### 6.5. GovernmentPurchaseResource

Details a purchase operation by a government body.

*   `entityType` (enum): Type of government entity (`union`, `state`, `municipality`).
*   `rateReduction` (number): Rate reduction percentage.
*   `operationType` (enum): Type of operation with the government (`supply`, `payment`, etc.).

### 6.6. TransportInformationResource

Groups all information related to the transportation of the goods.

*   `freightModality` (enum): Freight modality (`ByIssuer`, `ByReceiver`, etc.). (modFrete)
*   `transportGroup` (TransportGroupResource): Carrier data. (transporta)
*   `transportVehicle` (TransportVehicleResource): Main vehicle data. (veicTransp)
*   `reboque` (ReboqueResource): Trailer vehicle data. (reboque)
*   `volume` (VolumeResource): Information about transported volumes. (vol)
*   `transpRate` (TransportRateResource): Transport ICMS retention data. (retTransp)
*   `sealNumber` (string): Seal numbers.

#### 6.6.1. TransportGroupResource

*   `name` (string): Carrier's Name/Corporate Name.
*   `federalTaxNumber` (integer): Carrier's CNPJ/CPF.
*   `stateTaxNumber` (string): Carrier's State Tax Number.
*   `address` (AddressResource): Carrier's full address.

#### 6.6.2. TransportVehicleResource

*   `plate` (string): Vehicle license plate. (placa)
*   `state` (string): Vehicle registration state.
*   `rntc` (string): National Registry of Road Freight Carriers.

#### 6.6.3. ReboqueResource

*   `plate` (string): Trailer license plate.
*   `state` (string): Trailer registration state.
*   `rntc` (string): Trailer's RNTRC.

#### 6.6.4. VolumeResource

*   `volumeQuantity` (integer): Quantity of volumes. (qVol)
*   `species` (string): Species of volumes. (esp)
*   `brand` (string): Brand of volumes. (marca)
*   `netWeight` (number): Total net weight (in Kg). (pesoL)
*   `grossWeight` (number): Total gross weight (in Kg). (pesoB)

### 6.7. PaymentResource and PaymentDetailResource

Structure for detailing the forms and amounts of payment for the operation.

*   **PaymentResource**:
    *   `paymentDetail` (array[PaymentDetailResource]): List of payment details.
    *   `payBack` (number): Change amount.
*   **PaymentDetailResource**:
    *   `method` (enum): Payment method (`Cash`, `CreditCard`, `InstantPayment`).
    *   `amount` (number): Payment amount.
    *   `paymentType` (enum): Payment form indicator (`InCash`, `Term`).
    *   `card` (CardResource): Card transaction details.

#### 6.7.1. CardResource

*   `federalTaxNumber` (string): CNPJ of the card acquirer.
*   `flag` (enum): Card brand (e.g., `Visa`, `Mastercard`). (tBand)
*   `authorization` (string): Transaction authorization number for cards, PIX, bank slips, and other electronic payments. (cAut)
*   `integrationPaymentType` (enum): Integration type (`Integrated`, `NotIntegrated`). (tpIntegra)

### 6.8. BillingResource

Contains commercial billing data, such as invoice and installments.

*   `bill` (BillResource): Invoice data.
*   `duplicates` (array[DuplicateResource]): List of installments.

#### 6.8.1. BillResource

*   `number` (string): Invoice number. (nFat)
*   `originalAmount` (number): Original invoice amount. (vOrig)
*   `discountAmount` (number): Discount amount. (vDesc)
*   `netAmount` (number): Net invoice amount. (vLiq)

#### 6.8.2. DuplicateResource

*   `number` (string): Installment number. (nDup)
*   `expirationOn` (string): Due date. (dVenc)
*   `amount` (number): Installment amount. (vDup)


### 6.9. AdditionalInformationResource

Groups complementary information, such as notes for the tax authority, referenced documents, and processes.

*   `fisco` (string): Information for the Tax Authority.
*   `taxpayer` (string): Information for the taxpayer.
*   `xmlAuthorized` (array[integer]): List of CNPJs/CPFs authorized to download the XML.
*   `taxDocumentsReference` (array[TaxDocumentsReferenceResource]): Referenced fiscal documents.
*   `referencedProcess` (array[ReferencedProcessResource]): Referenced judicial/administrative processes.

#### 6.9.1. TaxDocumentsReferenceResource

*   `documentElectronicInvoice` (object): Contains the access key (`accessKey`) of a referenced NF-e/NFC-e.
*   `documentInvoiceReference` (object): Contains data from a referenced model 1/1A invoice.
*   `taxCouponInformation` (object): Contains data from a referenced fiscal coupon.

#### 6.9.2. ReferencedProcessResource

*   `identifierConcessory` (string): Process identifier.
*   `identifierOrigin` (integer): Indicator of the process origin (e.g., SEFAZ, Federal Justice).

### 6.10. InvoiceItemResource

Details an item on the invoice.

*   `code` (string): Product code.
*   `description` (string): Product description.
*   `ncm` (string): NCM code.
*   `cfop` (integer): CFOP code.
*   `quantity` (number): Quantity.
*   `unit` (string): Unit of measure.
*   `unitAmount` (number): Unit price.
*   `totalAmount` (number): Gross total amount.
*   `tax` (InvoiceItemTaxResource): Object with all item taxes.
*   `vehicleDetail` (VehicleDetailResource): Specific details for items representing new vehicles. See section **6.22. VehicleDetailResource** for the complete field reference.
*   `fuelDetail` (FuelResource): Details if the item is a fuel.
*   `importDeclarations` (array[ImportDeclarationResource]): Import details.
*   `taxDetermination` (TaxDeterminationResource): Group for automatic tax calculation.

### 6.11. InvoiceItemTaxResource

Groups all taxes incident on an item.

*   `totalTax` (number): Approximate total tax amount (Transparency Law).
*   `icms` (IcmsTaxResource): ICMS taxation.
*   `ipi` (IPITaxResource): IPI taxation.
*   `pis` (PISTaxResource): PIS taxation.
*   `cofins` (CofinsTaxResource): COFINS taxation.
*   `IS` (ISTaxResource): Selective Tax taxation.
*   `IBSCBS` (IBSCBSTaxResource): IBS and CBS taxation.

#### 6.11.1. IcmsTaxResource

*   `origin` (string): Origin of the goods.
*   `cst` (string): ICMS Tax Situation Code.
*   `baseTax` (number): ICMS tax base.
*   `rate` (number): ICMS rate (%).
*   `amount` (number): ICMS amount.
*   *...other fields for ST, reduction, deferment, etc.*

#### 6.11.2. IPITaxResource

*   `cst` (string): IPI Tax Situation Code.
*   `base` (number): IPI tax base.
*   `rate` (number): IPI rate (%).
*   `amount` (number): IPI amount.

#### 6.11.3. PISTaxResource and CofinsTaxResource

*   `cst` (string): PIS/COFINS Tax Situation Code.
*   `baseTax` (number): Tax base.
*   `rate` (number): Rate (%).
*   `amount` (number): Tax amount.

### 6.12. ISTaxResource

Details the Selective Tax taxation for an item.

*   `situationCode` (string): IS Tax Situation Code.
*   `classificationCode` (string): IS Tax Classification Code.
*   `basis` (number): Tax base.
*   `rate` (number): Rate (%).
*   `amount` (number): Tax amount.

### 6.13. IBSCBSTaxResource

Details the IBS and CBS taxation for an item, according to the Tax Reform.

*   `situationCode` (string): IBS/CBS Tax Situation Code.
*   `classCode` (string): Tax Classification Code.
*   `basis` (number): Tax base.
*   `state` (IBSStateTaxResource): State IBS details.
*   `municipal` (IBSMunicipalTaxResource): Municipal IBS details.
*   `cbs` (CBSTaxResource): CBS details.
*   `monophase` (MonophaseIBSCBSTaxResource): Details for monophasic taxation.
*   `operationalPresumedCredit` (OperationalPresumedCreditResource): Presumed credit details.

#### 6.13.1. IBSStateTaxResource and IBSMunicipalTaxResource

*   `rate` (number): IBS rate (%).
*   `amount` (number): IBS amount.
*   `deferment` (object): Contains `rate` and `amount` of the deferment.
*   `reduction` (object): Contains `rateReduction` and `effectiveRate` of the reduction.

#### 6.13.2. CBSTaxResource

*   `rate` (number): CBS rate (%).
*   `amount` (number): CBS amount.
*   `deferment` (object): Contains `rate` and `amount` of the deferment.
*   `reduction` (object): Contains `rateReduction` and `effectiveRate` of the reduction.

### 6.14. Total (Totals Schema)

Groups the consolidated total values of the entire invoice.

*   `icms` (ICMSTotal): ICMS totals.
*   `issqn` (ISSQNTotal): ISSQN totals.
*   `withheldTaxes` (TotalsWithholdings): Totals of withheld taxes.
*   `isTotals` (ISTotalsResource): Selective Tax totals.
*   `ibsCbsTotals` (IBSCBSTotalsResource): IBS and CBS totals.
*   `totalInvoiceAmount` (number): Final total amount of the NF-e.

#### 6.14.1. ICMSTotal

*   `baseTax` (number): Sum of the ICMS tax base.
*   `icmsAmount` (number): Sum of the ICMS amount.
*   `stCalculationBasisAmount` (number): Sum of the ICMS-ST tax base.
*   `stAmount` (number): Sum of the ICMS-ST amount.
*   `productAmount` (number): Sum of the product amounts.
*   `invoiceAmount` (number): Total invoice amount (old regime).

#### 6.14.2. TotalsWithholdings

*   `pisAmount` (number): Withheld PIS amount.
*   `cofinsAmount` (number): Withheld COFINS amount.
*   *...other fields for CSLL, IRRF, etc.*

### 6.15. ISTotalsResource

Consolidates the total amount of the Selective Tax for the invoice.

*   `amount` (number): Sum of the Selective Tax amount from all items.

### 6.16. IBSCBSTotalsResource


*   `basis` (number): Sum of the IBS/CBS tax base.
*   `ibs` (IBSTotalsResource): Object with IBS totals.
*   `cbs` (CBSTotalsResource): Object with CBS totals.
*   `monophase` (MonophaseTotalsResource): Object with monophasic taxation totals.

### 6.17. IBSTotalsResource

Aggregates IBS totals.

*   `state` (IBSStateTotalsResource): State IBS totals.
*   `municipal` (IBSMunicipalTotalsResource): Municipal IBS totals.
*   `totalAmount` (number): Total IBS amount.
*   `presumedCreditAmount` (number): Total presumed credit amount.

### 6.18. CBSTotalsResource

Aggregates CBS totals.

*   `defermentAmount` (number): Total deferment amount.
*   `returnedAmount` (number): Total return amount.
*   `amount` (number): Total CBS amount.
*   `presumedCreditAmount` (number): Total presumed credit amount.

### 6.19. PurchaseInformationResource

Groups purchase information.

*   `commitmentNote` (string): Commitment Note.
*   `purchaseOrder` (string): Purchase Order.
*   `contractNumber` (string): Contract Number.

### 6.20. ExportResource

Contains information about the export of goods.
*   `state` (string): Abbreviation of the shipping state.
*   `office` (string): Shipping location.
*   `local` (string): Dispatch location.

### 6.21. IntermediateResource

Contains information of the transaction intermediary (marketplace, delivery platform, etc.).
*   `federalTaxNumber` (integer): Intermediary's CNPJ.
*   `identifier` (string): Identifier registered with the intermediary.

### 6.22. VehicleDetailResource

This group contains specific information for items representing **new vehicles** on the invoice. It corresponds to the **`veicProd`** group (fields J01 through J26) from the official NF-e layout, as defined in the XSD `leiauteNFe_v4.00.xsd`.

**When to use:** This group must be filled in exclusively when the invoice item is a brand-new vehicle (0 km). It is mandatory for sales operations conducted by dealerships, manufacturers, and authorized resellers of new vehicles. Each invoice item may contain only one product-specific group (`vehicleDetail`, `fuelDetail`, or `medicineDetail`). If more than one is provided, only the first one found will be used, following the order of precedence: medicine, vehicle, fuel.

**Fields:**

*   `operationType` (integer): **Operation Type (`tpOp` — field J02)**. Defines the commercial context of the vehicle sale. This field indicates how the sale transaction is being carried out and affects billing and tax rules.
    *   `0` = Others (operations that do not fit the other categories)
    *   `1` = Dealership sale (sale made by an authorized dealership)
    *   `2` = Direct billing to end consumer (direct sale from the manufacturer to the consumer)
    *   `3` = Direct sale to large consumers (e.g., fleet operators, government, car rental companies)
    *   **Validations:** Required. Must be one of the values above (0, 1, 2, or 3).

*   `chassis` (string): **Vehicle Chassis — VIN (`chassi` — field J03)**. The Vehicle Identification Number, stamped on the chassis. This is the unique and universal identifier for the vehicle, used for tracking, registration, and documentation worldwide.
    *   **Validations:** Required. Must contain exactly **17 alphanumeric characters** (uppercase letters A to Z and digits 0 to 9). Pattern: `[A-Z0-9]{17}`.
    *   **Example:** `9BWZZZ377VT004251`

*   `colorCode` (string): **Vehicle Color Code (`cCor` — field J04)**. Internal code used by the manufacturer to identify the vehicle's color. Each manufacturer has its own color code table.
    *   **Validations:** Required. Maximum of **4 characters**.
    *   **Example:** `A1B2`

*   `colorDescription` (string): **Color Description (`xCor` — field J05)**. Full name of the vehicle's color in plain language. Must match the code provided in `colorCode`.
    *   **Validations:** Required. Maximum of **40 characters**.
    *   **Example:** `Lunar Silver Metallic`

*   `enginePower` (string): **Engine Power (`pot` — field J06)**. Maximum engine power expressed in horsepower (HP/CV). This value is listed on the vehicle's registration certificate.
    *   **Validations:** Required. Maximum of **4 characters**.
    *   **Example:** `150` (equals 150 HP)

*   `engineDisplacement` (string): **Engine Displacement (`cilin` — field J07)**. Engine displacement expressed in cubic centimeters (CC). Indicates the total volume of the engine's cylinders.
    *   **Validations:** Required. Maximum of **4 characters**.
    *   **Example:** `1998` (equals a 2.0-liter engine)

*   `netWeight` (string): **Net Weight (`pesoL` — field J08)**. Vehicle weight without cargo, passengers, or optional accessories, expressed in kilograms.
    *   **Validations:** Required. Maximum of **9 characters**.
    *   **Example:** `1250`

*   `grossWeight` (string): **Gross Weight (`pesoB` — field J09)**. Total vehicle weight including maximum permitted cargo capacity, expressed in kilograms.
    *   **Validations:** Required. Maximum of **9 characters**.
    *   **Example:** `1650`

*   `serialNumber` (string): **Serial Number (`nSerie` — field J10)**. Vehicle serial number assigned by the manufacturer. Serves as an additional production identifier.
    *   **Validations:** Required. Maximum of **9 characters**.
    *   **Example:** `ABC123456`

*   `fuelType` (string): **Fuel Type (`tpComb` — field J11)**. Numeric code identifying the type of fuel used by the vehicle, as defined in the **RENAVAM Table**. The most common codes are:
    *   `01` = Alcohol (Ethanol)
    *   `02` = Gasoline
    *   `03` = Diesel
    *   `08` = Electric
    *   `16` = Alcohol/Gasoline (flex-fuel)
    *   `17` = Gasoline/Alcohol/CNG (flex-fuel + compressed natural gas)
    *   `18` = Gasoline/Electric (hybrid)
    *   **Validations:** Required. Maximum of **2 characters**. Must match a valid code from the RENAVAM Table.

*   `engineNumber` (string): **Engine Number (`nMotor` — field J12)**. Engine identification number stamped on the engine block by the manufacturer.
    *   **Validations:** Required. Maximum of **21 characters**.
    *   **Example:** `MOT123456789012`

*   `maximumTractionCapacity` (string): **Maximum Traction Capacity — CMT (`CMT` — field J13)**. Maximum weight the vehicle can tow, including its own weight and the trailer's load, expressed in metric tons with up to 4 decimal places.
    *   **Validations:** Required. Maximum of **9 characters**.
    *   **Example:** `1.5000` (equals 1.5 metric tons)

*   `wheelBase` (string): **Wheelbase (`dist` — field J14)**. Distance measured between the center of the front axle and the center of the rear axle, expressed in millimeters.
    *   **Validations:** Required. Maximum of **4 characters**.
    *   **Example:** `2620` (equals 2,620 mm)

*   `modelYear` (integer): **Model Year (`anoMod` — field J16)**. The model year of the vehicle, as defined by the manufacturer. The model year may differ from the manufacture year (e.g., a vehicle manufactured in 2025 with a 2026 model year).
    *   **Validations:** Required. Must contain exactly **4 digits**.
    *   **Example:** `2026`

*   `manufactureYear` (integer): **Manufacture Year (`anoFab` — field J17)**. The year in which the vehicle was actually produced on the assembly line.
    *   **Validations:** Required. Must contain exactly **4 digits**.
    *   **Example:** `2025`

*   `paintType` (string): **Paint Type (`tpPint` — field J18)**. Code identifying the paint finish type (e.g., solid, metallic, pearlescent).
    *   **Validations:** Required. Exactly **1 character**.
    *   **Example:** `M` (Metallic)

*   `vehicleType` (string): **Vehicle Type (`tpVeic` — field J19)**. Numeric code classifying the vehicle type according to the **RENAVAM Table** (e.g., automobile, truck, motorcycle). The most common codes are:
    *   `02` = Moped
    *   `03` = Motor scooter
    *   `04` = Motorcycle
    *   `05` = Tricycle
    *   `06` = Automobile
    *   `13` = Pickup truck
    *   `14` = Truck
    *   `17` = Minibus
    *   `22` = Truck-tractor
    *   **Validations:** Required. Maximum of **2 characters**. Must match a valid code from the RENAVAM Table.

*   `vehicleSpecies` (integer): **Vehicle Species (`espVeic` — field J20)**. Numeric code classifying the vehicle's intended purpose according to the **RENAVAM Table**:
    *   `1` = Passenger
    *   `2` = Cargo
    *   `3` = Mixed (passenger and cargo)
    *   `4` = Racing
    *   `5` = Traction
    *   `6` = Special purpose
    *   **Validations:** Required. Must be a valid digit from the table above.

*   `vinCondition` (string): **VIN Condition (`VIN` — field J21)**. Indicates whether the vehicle's chassis number (VIN) has been re-stamped or is in its original factory condition. Re-stamping occurs when the original chassis was damaged and needed to be re-engraved by the vehicle registration authority (DETRAN).
    *   `R` = Re-stamped (re-engraved chassis)
    *   `N` = Normal (original factory chassis)
    *   **Validations:** Required. Must be `R` or `N`.

*   `vehicleCondition` (integer): **Vehicle Condition (`condVeic` — field J22)**. Indicates the vehicle's state of completion at the time of sale. Unfinished or semi-finished vehicles are typically sold between manufacturers and body builders for completion.
    *   `1` = Finished (vehicle ready for use, with all components)
    *   `2` = Unfinished (vehicle missing an essential component, requiring completion)
    *   `3` = Semi-finished (partially assembled vehicle, such as chassis-cabin)
    *   **Validations:** Required. Must be 1, 2, or 3.

*   `brandModelCode` (string): **Brand/Model Code (`cMod` — field J23)**. Numeric code identifying the vehicle's brand and model combination in the **RENAVAM Table**. Each vehicle has a unique code that identifies, for example, "Volkswagen Gol 1.0" or "Toyota Corolla 2.0".
    *   **Validations:** Required. Maximum of **6 numeric characters**.
    *   **Example:** `123456`

*   `denatranColorCode` (string): **DENATRAN Color Code (`cCorDENATRAN` — field J24)**. Standardized color code defined by DENATRAN (National Traffic Department). Unlike `colorCode` (which is manufacturer-specific), this code is the official color classification for vehicle registration and documentation:
    *   `01` = Yellow | `02` = Blue | `03` = Beige | `04` = White
    *   `05` = Gray | `06` = Gold | `07` = Maroon | `08` = Orange
    *   `09` = Brown | `10` = Silver | `11` = Black | `12` = Pink
    *   `13` = Purple | `14` = Green | `15` = Red | `16` = Fantasy
    *   **Validations:** Required. Maximum of **2 numeric characters**. Must be one of the codes above.

*   `seatingCapacity` (integer): **Seating Capacity (`lota` — field J25)**. Maximum number of seated passengers the vehicle can carry, **including the driver**. This value is listed on the vehicle's registration certificate.
    *   **Validations:** Required. Maximum of **3 digits**.
    *   **Example:** `5` (standard automobile with 5 seats)

*   `restrictionType` (integer): **Restriction Type (`tpRest` — field J26)**. Indicates whether there is any legal or financial restriction on the vehicle that limits its sale or ownership transfer:
    *   `0` = No restriction (vehicle is free for sale and transfer)
    *   `1` = Fiduciary alienation (vehicle used as collateral in financing)
    *   `2` = Financial lease (vehicle under a leasing contract)
    *   `3` = Ownership reserve (seller retains ownership until full payment)
    *   `4` = Vehicle pledge (vehicle used as collateral for a loan)
    *   `9` = Other restrictions
    *   **Validations:** Required. Must be one of the values above (0, 1, 2, 3, 4, or 9).

> **Important Note:** The `vehicleDetail` group is mutually exclusive with `fuelDetail` (fuel) and `medicineDetail` (medicine). Each invoice item may contain at most **one** of these product-specific groups. If more than one is provided by mistake, the API will follow the order of precedence: medicine > vehicle > fuel.

---

## 7. Appendix D: Common Errors and Their Solutions

This section describes the most common rejections during the NF-e/NFC-e issuance process and provides guidance on how to correct them.

### 7.1. General Rejections

**Rejection 204: Duplicate NF-e**
*   **What it means:** An invoice with the same number, series, and issuer's CNPJ already exists in the SEFAZ database.
*   **Common Cause:** Attempting to resend an invoice that has already been authorized or is being processed, or an error in sequential numbering control.
*   **How to Fix:** Check the status of the original invoice. If it has already been authorized, do not resend it. If you need to issue a new invoice, increment the `number` field to the next available value in the `serie` sequence.

**Rejection 225: XML Schema Failure**
*   **What it means:** The structure of the sent JSON does not match the layout expected by the API.
*   **Common Cause:** Fields with incorrect data types (e.g., sending text where a number is expected), incorrect property names, or incorrect nested object structure.
*   **How to Fix:** Review the request body and compare it with the OpenAPI specification and the examples provided in this documentation. Pay special attention to data types and object hierarchy.

**Rejection 210: Invalid recipient's IE**
*   **What it means:** The State Tax Number (`stateTaxNumber`) provided for the buyer (`buyer`) is not valid for the destination state.
*   **Common Cause:** Typo, non-existent IE, or an IE from a different state than the one in the buyer's address.
*   **How to Fix:** Confirm the correct State Tax Number of the recipient. If the recipient is exempt or not a taxpayer, adjust the `stateTaxNumberIndicator` field to `Exempt` or `NonTaxPayer` and do not send the `stateTaxNumber` field.

**Rejection 610: Total NF-e value differs from the sum of the values that compose the total value**
*   **What it means:** The `totals.icms.invoiceAmount` field does not match the sum of the item values and other fields that make up the total.
*   **Common Cause:** Calculation error in the sum of `items.totalAmount` plus freight, insurance, ancillary expenses, taxes, and subtracting discounts.
*   **How to Fix:** Recalculate the total invoice amount. The basic formula is: `vProd` (sum of `totalAmount` of items) - `vDesc` + `vST` + `vFrete` + `vSeg` + `vOutro` + `vIPI` + `vIPIDevol`. With RTC, the `totalInvoiceAmount` field must also be validated, including the new taxes.

**Rejection 321: Goods return NF-e does not have a referenced fiscal document**
*   **What it means:** The invoice was issued with `purposeType` = `Devolution`, but the access key of the original invoice being returned was not provided.
*   **Common Cause:** Forgetting to fill in the `additionalInformation.taxDocumentsReference` group.
*   **How to Fix:** Add the `taxDocumentsReference` group within `additionalInformation`, containing a `documentElectronicInvoice` object with the `accessKey` of the NF-e that originated the return.

### 7.2. Tax Reform (RTC) Rejections

**Rejection 1115: IBS/CBS not informed**
*   **What it means:** For an operation under the new regime, the `IBSCBS` group was not informed in one or more items.
*   **Common Cause:** The operation already falls under the RTC rules, but the issuing system is not yet sending the `items.tax.IBSCBS` group.
*   **How to Fix:** For each item on the invoice, add the `IBSCBS` object within `tax`, filling in the mandatory fields such as `situationCode`, `classCode`, `basis`, and the subgroups `state`, `municipal`, and `cbs`.

**Rejection 1023: Informed IBS/CBS Tax Classification does not exist**
*   **What it means:** The code provided in `items.tax.IBSCBS.classCode` does not exist in the official `cClassTrib` table of SEFAZ.
*   **Common Cause:** Typo or use of an outdated code.
*   **How to Fix:** Consult the latest `cClassTrib` table, available on the National NF-e Portal, and use a valid code that corresponds to the item's taxation.

**Rejection 1024: IBS and CBS Tax Classification incompatible with the informed CST**
*   **What it means:** The combination between `situationCode` (CST) and `classCode` (Tax Classification) is not allowed.
*   **Common Cause:** A `classCode` representing an exemption was combined with a `situationCode` for full taxation, for example.
*   **How to Fix:** Check the `cClassTrib` table. It contains the valid combinations between CST and Tax Classification. Adjust one of the two fields so that the combination is valid.

**Rejection 1104: IBS and CBS tax base value differs from the sum of the values that compose it**
*   **What it means:** The value provided in `items.tax.IBSCBS.basis` does not correspond to the sum of the values that form the item's tax base.
*   **Common Cause:** Error in calculating the tax base, which is usually `vProd` - `vDesc` + `vFrete` + `vSeg` + `vOutro` + `vII` + `vIPI`.
*   **How to Fix:** Recalculate the `basis` field for each item, ensuring it reflects the correct sum of the values that compose the tax base for the new taxes.

**Rejection 1026: Invalid State IBS rate**
*   **What it means:** The state IBS rate (`items.tax.IBSCBS.state.rate`) does not correspond to the rate in effect for the issuance period.
*   **Common Cause:** Use of an incorrect rate. During the transition period, the rates are fixed (e.g., 0.1% for 2025/2026).
*   **How to Fix:** Adjust the rate to the correct value defined in the Tax Reform legislation for the year of invoice issuance. Consult the documentation for the current values.

**Rejection 1001: NF-e with debit or credit purpose only for IBS/CBS**
*   **What it means:** An invoice with a Debit (`finNFe=6`) or Credit (`finNFe=5`) purpose contained tax groups from the old regime (ICMS, IPI, PIS, COFINS).
*   **Common Cause:** Sending an RTC tax adjustment note that improperly contains taxes from the old model.
*   **How to Fix:** Completely remove the `icms`, `ipi`, `pis`, `cofins`, and `icmsDestination` groups from the `tax` object of all items on the invoice. Debit and credit notes are exclusively for IBS and CBS adjustments.
*   **Incorrect Example:**
    ```json
    {
      "purposeType": "Credit",
      "creditType": "valueReduction",
      // ... other invoice data
      "items": [
        {
          // ... item data
          "tax": {
            // INCORRECT: Old regime groups are not allowed
            "icms": { "origin": "0", "cst": "90" },
            "pis": { "cst": "99" },
            "cofins": { "cst": "99" },
            // CORRECT: Only the IBSCBS group should be used
            "IBSCBS": {
              "situationCode": "910",
              "classCode": "RT0001",
              "basis": 100.00,
              "cbs": { "amount": -12.00 } // Negative value for adjustment
            }
          }
        }
      ]
    }
    ```
*   **Corrected Example:**
    ```json
    {
      "purposeType": "Credit",
      "creditType": "valueReduction",
      // ... other invoice data
      "items": [
        {
          // ... item data
          "tax": {
            // CORRECT: Only the IBSCBS group is informed
            "IBSCBS": {
              "situationCode": "910",
              "classCode": "RT0001",
              "basis": 100.00,
              "cbs": { "amount": -12.00 } // Negative value for adjustment
            }
          }
        }
      ]
    }
    ```

---

## 9. Appendix F: Best Practices for Integration

To ensure a more efficient, robust, and resilient integration with the NF-e issuance API, we recommend following the practices listed below.

### 9.1. Numbering and Series Control

*   The control of the sequential numbering (`number`) for each series (`serie`) can be handled by either the client system or our system. Regardless of who handles the control, it is essential to avoid "Rejection 204: Duplicate NF-e". Additionally, the client system must always check for gaps in the numerical sequence. If a number is not used, it is necessary to request its **invalidation** to avoid problems with the Tax Authority.
*   **Changing Series:** Whenever it is necessary to change or start using a new fiscal series, it is a mandatory requirement that the issuer's State Tax Number registration be previously updated in the NFE.io system for the use of this new series. This obligation exists regardless of which system controls the numbering.

### 9.2. Pre-Submission Data Validation

*   **Reduce Unnecessary Calls:** Before sending data to the API, perform as many validations as possible in your system. This includes:
    *   **Validation of Registration and Address Data:** To ensure the validity of the issuer's and recipient's registration data, we recommend using our query APIs. They allow you to check if CNPJs and CPFs are valid, if the State Tax Number is active and linked to the correct CNPJ, and also to query addresses from the CEP. Using these APIs avoids rejections due to incorrect registration or address data.
    *   Ensuring that mandatory fields are filled according to the operation (e.g., CFOP, NCM).

### 9.3. Error and Rejection Handling

*   **Detailed Logs:** Our system maintains a complete and detailed history of all requests (sent JSON) and responses (received JSON) for a long period. In case of errors, these logs are a powerful tool for analysis and debugging, facilitating the identification of the root cause of the problem and speeding up technical support.
*   **Retry Mechanism:** For network errors or momentary SEFAZ instability (e.g., timeouts, 5xx errors), our system already has a retry mechanism with *exponential backoff*. This prevents the client from having to worry about implementing this logic, as we automatically manage retry attempts in case of temporary failures.

### 9.4. NF-e Lifecycle Management

*   **Status Query (Webhooks):** After sending an invoice, the initial status may be "Processing". To get the final status (such as "Issued" or "Error"), our system works with the concept of **webhooks**. Instead of implementing a periodic query routine, you should configure an endpoint in your system to receive our automatic notifications as soon as the processing is complete. This makes communication more efficient and real-time.
*   **Local Storage:** Although the legal responsibility for storage lies with the issuer, our system stores all data and the XML file of each authorized NF-e for a minimum period of 5 years. You can download the XML and DANFE in PDF at any time through our platform, ensuring fiscal compliance.
*   **Be Prepared for Contingency:** SEFAZ systems can become unavailable. To simplify your integration, the contingency issuance mode can be configured directly in your State Tax Number registration on our platform. With this configuration, our system automatically manages entering and exiting contingency mode when necessary, allowing your business operation to continue without interruption. If you prefer, you can still manage contingency manually.

### 9.5. Performance and Efficiency

*   **Keep Auxiliary Tables Updated:** Maintain a local and updated copy of the reference tables published by the government, such as NCM, CEST, CFOP, and especially the new Tax Reform tables (`cClassTrib`, `cCredPres`). This avoids the need for external queries for each issuance.
*   **Avoid Unnecessary Data:** Send only the fields and groups necessary for your operation. Omitting optional groups that do not apply (like `delivery` if the delivery is at the buyer's address) makes the payload cleaner and validation faster.

### 9.6. Security

*   **Protect Your Credentials:** Treat API access keys and digital certificates as highly sensitive information. Do not expose them in the client-side source code (frontend) and store them securely in your backend.

## 8. Appendix E: Cancellation, Invalidation, and Return

It is common to have doubts about which procedure to adopt to correct or annul a fiscal operation. This appendix clarifies the difference between the three main mechanisms.

### 8.1. Cancellation

*   **What it is:** It is the act of invalidating an **authorized** NF-e, making it fiscally void.
*   **When to use:** When the commercial operation did not materialize (e.g., purchase cancellation) and, crucially, **the goods have not yet circulated**.
*   **Main Rules:**
    *   Must be requested within a legal deadline, usually 24 hours after authorization.
    *   The goods must not have left the issuing establishment.
    *   The recipient must not have performed the "Acknowledgment of Issuance".

### 8.2. Number Invalidation

*   **What it is:** It is the process of communicating to SEFAZ that a range of NF-e numbers was not and will not be used.
*   **When to use:** When there is a **gap in the sequence of invoice numbering**. For example, invoice 100 was issued and the next to be issued is 102, leaving number 101 vacant.
*   **Main Rules:**
    *   Invalidation applies only to numbers that have not been used in any NF-e (not even in a rejected or denied invoice).
    *   It serves for the Tax Authority to know that the "gap" in the sequence is not tax evasion, but a technical or operational failure.

### 8.3. Return Invoice

*   **What it is:** It is the issuance of a new NF-e (with `purposeType` = `Devolution`) to nullify the effects of a previous operation.
*   **When to use:** When the goods have circulated and the recipient is returning them, either due to refusal upon receipt or return after delivery. It is the only way to annul an operation after the goods have circulated.
*   **Main Rules:**
    *   It is an incoming invoice (`operationType` = `Incoming`) for the original issuer.
    *   It must reference the access key of the original NF-e being returned.
    *   The taxes are "mirrored" to nullify the debit of the outgoing invoice.

---

## 10. Appendix G: Reference Table - CST and Tax Classification (IBS/CBS)

The following table details the Tax Situation Codes (`situationCode`) and Tax Classification Codes (`classCode`) for IBS and CBS, according to the Tax Reform. The correct combination of these codes is essential for the validation of the NF-e in the new regime.

| SituationCode (CST) | CST Description | ClassCode (cClassTrib) | ClassCode Description |
|:---|:---|:---|:---|
|000|Full taxation|000001|Situations fully taxed by IBS and CBS.|
|000|Full taxation|000002|Road exploration, observing art. 11 of Complementary Law No. 214, of 2025.|
|000|Full taxation|000003|Automotive regime - incentivized projects, observing art. 311 of Complementary Law No. 214, of 2025.|
|000|Full taxation|000004|Automotive regime - incentivized projects, observing art. 312 of Complementary Law No. 214, of 2025.|
|010|Taxation with uniform rates - FGTS operations|010001|FGTS operations not carried out by Caixa Econômica Federal, observing art. 212 of Complementary Law No. 214, of 2025.|
|011|Taxation with uniform rates reduced by 60%|011001|Funeral assistance plans, observing art. 236 of Complementary Law No. 214, of 2025.|
|011|Taxation with uniform rates reduced by 60%|011002|Health assistance plans, observing art. 237 of Complementary Law No. 214, of 2025.|
|011|Taxation with uniform rates reduced by 60%|011003|Intermediation of health assistance plans, observing art. 240 of Complementary Law No. 214, of 2025.|
|011|Taxation with uniform rates|011004|Contests and lotteries, observing art. 246 of Complementary Law No. 214, of 2025.|
|011|Taxation with uniform rates reduced by 30%|011005|Pet health assistance plans, observing art. 243 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200001|Acquisitions of machinery, apparatus, instruments, equipment, raw materials, intermediate products, and packaging materials between companies authorized to operate in export processing zones, observing art. 103 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200002|Supply or import of tractors, agricultural machinery and implements, intended for non-taxpayer rural producers, and cargo transport vehicles intended for non-taxpayer individual autonomous cargo transporters, observing art. 110 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200003|Sales of products for human consumption listed in Annex I of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, which make up the National Basic Food Basket, created under art. 8 of Constitutional Amendment No. 132, of December 20, 2023, observing art. 125 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200004|Sale of medical devices with the specification of the respective NCM/SH classifications provided for in Annex XII of Complementary Law No. 214, of 2025, observing art. 144 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200005|Sale of medical devices with the specification of the respective NCM/SH classifications provided for in Annex IV of Complementary Law No. 214, of 2025, when acquired by direct public administration bodies, autarchies, and public foundations, observing art. 144 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200006|In a public health emergency situation recognized by the competent federal, state, district, or municipal legislative power, a joint act of the Minister of Finance and the IBS Management Committee may be issued at any time to include devices not listed in Annex XIII of Complementary Law No. 214, of 2025, with the benefit's validity limited to the period and locality of the public health emergency, observing art. 144 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200007|Supply of accessibility devices for people with disabilities listed in Annex XIV of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 145 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200008|Supply of accessibility devices for people with disabilities listed in Annex V of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, when acquired by direct public administration bodies, autarchies, public foundations, and immune entities, observing art. 145 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200009|Supply of medicines listed in Annex XIV of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 146 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200010|Supply of medicines registered with Anvisa, when acquired by direct public administration bodies, autarchies, public foundations, and immune entities, observing art. 146 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200011|Supply of compositions for enteral and parenteral nutrition, special compositions, and nutritional formulas for people with inborn errors of metabolism listed in Annex VI of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, when acquired by direct public administration bodies, autarchies, and public foundations, observing art. 146 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200012|In a public health emergency situation recognized by the competent federal, state, district, or municipal legislative power, a joint act of the Minister of Finance and the IBS Management Committee may be issued at any time to include devices not listed in Annex XIV of Complementary Law No. 214, of 2025, with the benefit's validity limited to the period and locality of the public health emergency, observing art. 146 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200013|Supply of tampons, internal or external sanitary napkins, disposable or reusable, absorbent panties, and menstrual cups, observing art. 147 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200014|Supply of horticultural products, fruits, and eggs, listed in Annex XV of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications and provided they are not cooked, observing art. 148 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200015|Sale of nationally manufactured passenger cars with at least 4 (four) doors, including the trunk access door, when acquired by professional drivers who demonstrably exercise, in a car they own, the activity of an autonomous passenger driver, as a holder of an authorization, permission, or concession from the public authority, and who destine the car for use in the rental category (taxi), or by people with physical, visual, auditory disabilities, severe or profound mental disability, autism spectrum disorder, with impairments in social communication and in restricted or repetitive patterns of behavior of moderate or severe level, under the terms of the relevant legislation, observing the provisions of art. 149 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200016|Provision of research and development services by a non-profit Scientific, Technological, and Innovation Institution (ICT) to the direct public administration, autarchies, and public foundations or to a taxpayer subject to the regular IBS and CBS regime, observing the provisions of art. 156 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200017|Operations related to the FGTS, considering those necessary for the application of Law No. 8,036, of 1990, carried out by the Board of Trustees or Executive Secretariat of the FGTS, observing art. 212 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200018|Reinsurance and retrocession operations are subject to a zero rate, including when reinsurance and retrocession premiums are ceded abroad, observing art. 223 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200019|If the importer of financial services is a taxpayer who carries out the operations referred to in items I to V of the caput of art. 182, a zero rate will be applied on importation, without prejudice to the maintenance of the right to deduct these expenses from the IBS and CBS tax base, observing art. 231 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200020|Operation carried out by cooperative societies opting for a specific IBS and CBS regime, when the member assigns a good or service to the cooperative they participate in, and the cooperative supplies a good or service to the member subject to the regular IBS and CBS regime, observing art. 271 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200021|Urban, semi-urban, and metropolitan public collective passenger rail and waterway transport services, observing art. 285 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200022|Operation originating outside the Manaus Free Trade Zone that destines a nationally produced industrialized tangible good to a taxpayer established in the Manaus Free Trade Zone who is qualified under art. 442 of Complementary Law No. 214, of 2025, and subject to the regular IBS and CBS regime or opting for the Simples Nacional regime under art. 12 of Complementary Law No. 123, of 2006, observing art. 445 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200023|Operation carried out by an incentivized industry that destines an intermediate tangible good to another incentivized industry in the Manaus Free Trade Zone, provided that the delivery or availability of the goods occurs within said area, observing art. 448 of Complementary Law No. 214, of 2025.|
|200|Zero rate|200024|Operation originating outside the Free Trade Areas that destines a nationally produced industrialized tangible good to a taxpayer established in the Free Trade Areas who is qualified under art. 456 of Complementary Law No. 214, of 2025, and subject to the regular IBS and CBS regime or opting for the Simples Nacional regime under art. 12 of Complementary Law No. 123, of 2006, observing art. 463 of Complementary Law No. 214, of 2025.|
|200|Zero rate for CBS only and reduced by 60% for IBS|200025|Supply of education services related to the University for All Program (Prouni), established by Law No. 11,096, of January 13, 2005, observing art. 308 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 80%|200026|Leasing of properties located in rehabilitated zones, for a period of 5 (five) years, counted from the date of issuance of the occupancy permit, and related to urban rehabilitation projects of historic zones and critical areas for recovery and urban reconversion of Municipalities or the Federal District, to be delimited by municipal or district law, observing art. 158 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 70%|200027|Operations of leasing, onerous assignment, and rental of real estate, observing art. 261 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200028|Supply of education services listed in Annex II of Complementary Law No. 214, of 2025, with the specification of the respective classifications of the Brazilian Nomenclature of Services, Intangibles, and Other Operations that Produce Variations in Equity (NBS), observing art. 129 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200029|Supply of human health services listed in Annex III of Complementary Law No. 214, of 2025, with the specification of the respective NBS classifications, observing art. 130 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200030|Sale of medical devices listed in Annex IV of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 131 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200031|Supply of accessibility devices for people with disabilities listed in Annex V of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 132 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200032|Supply of medicines registered with Anvisa or produced by compounding pharmacies, except for medicines subject to the zero rate under art. 141 of Complementary Law No. 214, of 2025, observing art. 133 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200033|Supply of compositions for enteral and parenteral nutrition, special compositions, and nutritional formulas for people with inborn errors of metabolism listed in Annex VI of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 133 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200034|Supply of food for human consumption listed in Annex VII of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 135 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200035|Supply of personal hygiene and cleaning products listed in Annex VIII of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 136 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200036|Supply of agricultural, aquaculture, fishery, forestry, and plant extractive products in natura, observing art. 137 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200037|Supply of environmental services for the conservation or recovery of native vegetation, even if provided in the form of sustainable management of agricultural, agroforestry, and agrosilvopastoral systems, in accordance with the definitions and requirements of specific legislation, observing art. 137 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200038|Supply of agricultural and aquaculture inputs listed in Annex IX of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH and NBS classifications, observing art. 138 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200039|Supply of services and the licensing or assignment of rights listed in Annex X of Complementary Law No. 214, of 2025, with the specification of the respective NBS classifications, when intended for the following national artistic, cultural, event, journalistic, and audiovisual productions: theatrical, circus, and dance shows, musical concerts, carnival or folkloric parades, academic and scientific events, such as congresses, conferences, and symposiums, business fairs, exhibitions, cultural, artistic, and literary fairs and shows; auditorium or journalistic programs, films, documentaries, series, soap operas, interviews, and music videos, observing art. 139 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200040|Supply of the following institutional communication services to the direct public administration, autarchies, and public foundations: services aimed at the planning, creation, programming, and maintenance of electronic pages of the public administration, monitoring and management of their social networks, and optimization of pages and digital channels for search engines and production of messages, infographics, interactive panels, and institutional content, press relations services, which bring together organizational strategies to promote and reinforce the communication of the contracting bodies and entities with their stakeholders, through interaction with press professionals, and public relations services, which comprise the planned, cohesive, and continuous communication effort aimed at establishing an adequate perception of the institutional performance and objectives, from the stimulus to mutual understanding and the maintenance of relationship patterns and information flows between the contracting bodies and entities and their stakeholders, in the country and abroad, observing art. 140 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200041|Operations related to the following sports activities: provision of sports education service, classified under code 1.2205.12.00 of the NBS, and management and exploitation of sports by associations and sports clubs affiliated with the state or federal body responsible for coordinating sports, including through the sale of tickets for sports events, onerous or non-onerous supply of goods and services, including tickets, through supporter programs, assignment of athletes' sports rights, and transfer of athletes to another sports entity or their return to activity in another sports entity, observing art. 141 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200042|Operations related to the provision of sports education service, classified under code 1.2205.12.00 of the NBS, observing art. 141 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200043|Supply to the direct public administration, autarchies, and public foundations of services and goods related to sovereignty and national security, information security, and cybersecurity listed in Annex XI of Complementary Law No. 214, of 2025, with the specification of the respective NBS and NCM/SH classifications, observing art. 142 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200044|Operations and provision of information security and cybersecurity services developed by a company that has a Brazilian partner with a minimum of 20% (twenty percent) of its capital stock, listed in Annex XI of Complementary Law No. 214, of 2025, with the specification of the respective NBS and NCM/SH classifications, observing art. 142 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 60%|200045|Operations related to urban rehabilitation projects of historic zones and critical areas for recovery and urban reconversion of Municipalities or the Federal District, to be delimited by municipal or district law, observing art. 158 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 50%|200046|Operations with real estate, observing art. 261 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 40%|200047|Bars and Restaurants, observing art. 275 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 40%|200048|Hospitality, Amusement Parks, and Theme Parks, observing art. 281 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 40%|200049|Intermunicipal and interstate collective passenger road, rail, and waterway transport, observing art. 286 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 40%|200450|Regional collective passenger or cargo air transport services, observing art. 287 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 40%|200051|Tourism Agencies, observing art. 289 of Complementary Law No. 214, of 2025.|
|200|Rate reduced by 30%|200052|Provision of services of the following intellectual professions of a scientific, literary, or artistic nature, subject to supervision by a professional council: administrators, lawyers, architects and urban planners, social workers, librarians, biologists, accountants, economists, home economists, physical education professionals, engineers and agronomists, statisticians, veterinarians and zootechnicians, museologists, chemists, public relations professionals, industrial technicians, and agricultural technicians, observing art. 127 of Complementary Law No. 214, of 2025.|
|210|Rate reduced by 50% with tax base reducer|210001|Social reducer applied once in the sale of a new residential property, observing art. 259 of Complementary Law No. 214, of 2025.|
|210|Rate reduced by 50% with tax base reducer|210002|Social reducer applied once in the sale of a residential lot, observing art. 259 of Complementary Law No. 214, of 2025.|
|210|Rate reduced by 70% with tax base reducer|210003|Social reducer in operations of leasing, onerous assignment, and rental of residential real estate, observing art. 260 of Complementary Law No. 214, of 2025.|
|220|Fixed rate|220001|Real estate development subject to the special taxation regime, observing art. 485 of Complementary Law No. 214, of 2025.|
|220|Fixed rate|220002|Real estate development subject to the special taxation regime, observing art. 485 of Complementary Law No. 214, of 2025.|
|220|Fixed rate|220003|Sale of property resulting from land subdivision, observing art. 486 of Complementary Law No. 214, of 2025.|
|221|Proportional fixed rate|221001|Leasing, onerous assignment, or rental of real estate with a rate on gross revenue, observing art. 487 of Complementary Law No. 214, of 2025.|
|400|Exemption|400001|Provision of urban, semi-urban, and metropolitan public collective passenger road and metro transport services, under a public authorization, permission, or concession regime, observing art. 157 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410001|Provision of bonuses when they are included in the respective fiscal document and do not depend on a subsequent event, observing art. 5 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410002|Transfers between establishments belonging to the same taxpayer, observing art. 6 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410003|Donations, observing art. 6 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410004|Exports of goods and services, observing art. 8 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410005|Supplies made by the Union, States, Federal District, and Municipalities, observing art. 9 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410006|Supplies made by religious entities and temples of any cult, including their assistance and charitable organizations, observing art. 9 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410007|Supplies made by political parties, including their foundations, workers' trade union entities, and non-profit education and social assistance institutions, observing art. 9 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410008|Supplies of books, newspapers, periodicals, and the paper intended for their printing, observing art. 9 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410009|Supplies of phonograms and musical videograms produced in Brazil containing musical or literary-musical works by Brazilian authors and/or works in general interpreted by Brazilian artists, as well as the material supports or digital files that contain them, except in the industrial replication stage of laser-read optical media, observing art. 9 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410010|Supplies of communication services in the modalities of sound broadcasting and free and open reception of sound and images, observing art. 9 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410011|Supplies of gold, when defined in law as a financial asset or exchange instrument, observing art. 9 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410012|Supply by a condominium not opting for the regular regime, observing art. 26 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410013|Exports of fuels, observing art. 98 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410014|Supply by a non-taxpayer rural producer, observing art. 164 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410015|Supply by a non-taxpayer autonomous transporter, observing art. 169 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410016|Supply or acquisition of solid waste, observing art. 170 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410017|Acquisition of movable property with presumed credit subject to the condition of resale, observing art. 171 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410018|Operations related to guarantor and executor funds of public policies, including housing, provided for by law, understood as services provided to the fund by its operating agent and by the entity in charge of its administration, observing art. 213 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410019|Exclusion of tips from the tax base in the supply of food, observing art. 274 of Complementary Law No. 214, of 2025.|
|410|Immunity and non-incidence|410020|Exclusion of the intermediation value from the tax base in the supply of food, observing art. 274 of Complementary Law No. 214, of 2025.|
|510|Deferment|510001|Operations, subject to deferment, with electricity or related rights, concerning generation, commercialization, distribution, and transmission, observing art. 28 of Complementary Law No. 214, of 2025.|
|510|Deferment|510002|Operations, subject to deferment, with agricultural and aquaculture inputs intended for a taxpayer rural producer, observing art. 138 of Complementary Law No. 214, of 2025.|
|550|Suspension|550001|Exports of tangible goods, observing art. 82 of Complementary Law No. 214, of 2025.|
|550|Suspension|550002|Transit Regime, observing art. 84 of Complementary Law No. 214, of 2025.|
|550|Suspension|550003|Deposit Regimes, observing art. 85 of Complementary Law No. 214, of 2025.|
|550|Suspension|550004|Deposit Regimes, observing art. 87 of Complementary Law No. 214, of 2025.|
|550|Suspension|550005|Deposit Regimes, observing art. 87 of Complementary Law No. 214, of 2025.|
|550|Suspension|550006|Temporary Stay Regimes, observing art. 88 of Complementary Law No. 214, of 2025.|
|550|Suspension|550007|Improvement Regimes, observing art. 90 of Complementary Law No. 214, of 2025.|
|550|Suspension|550008|Import of goods for the Temporary Repetro Regime, as per item I of art. 93 of Complementary Law No. 214, of 2025.|
|550|Suspension|550009|Temporary GNL, as per item II of art. 93 of Complementary Law No. 214, of 2025.|
|550|Suspension|550010|Permanent Repetro, as per item III of art. 93 of Complementary Law No. 214, of 2025.|
|550|Suspension|550011|Repetro-Industrialization, as per item IV of art. 93 of Complementary Law No. 214, of 2025.|
|550|Suspension|550012|Repetro-National, as per item V of art. 93 of Complementary Law No. 214, of 2025.|
|550|Suspension|550013|Repetro-Warehouse, as per item VI of art. 93 of Complementary Law No. 214, of 2025.|
|550|Suspension|550014|Export Processing Zone, observing arts. 99, 100, and 102 of Complementary Law No. 214, of 2025.|
|550|Suspension|550015|Tax Regime for Incentive to Modernization and Expansion of Port Structure - Reporto, observing art. 105 of Complementary Law No. 214, of 2025.|
|550|Suspension|550016|Special Incentive Regime for Infrastructure Development - Reidi, observing art. 106 of Complementary Law No. 214, of 2025.|
|550|Suspension|550017|Tax Regime for Incentive to Naval Economic Activity – Renaval, observing art. 107 of Complementary Law No. 214, of 2025.|
|550|Suspension|550018|Exemption from the acquisition of capital goods, observing art. 109 of Complementary Law No. 214, of 2025.|
|550|Suspension|550019|Import of tangible goods by an incentivized industry for use in the Manaus Free Trade Zone, observing art. 443 of Complementary Law No. 214, of 2025.|
|550|Suspension|550020|Free trade areas, observing art. 461 of Complementary Law No. 214, of 2025.|
|620|Monophasic taxation|620001|Monophasic taxation on fuels, observing art. 172 and art. 179 I of Complementary Law No. 214, of 2025.|
|620|Monophasic taxation|620002|Monophasic taxation with responsibility for withholding on fuels, observing art. 178 of Complementary Law No. 214, of 2025.|
|620|Monophasic taxation|620003|Monophasic taxation with taxes withheld by responsibility on fuels, observing art. 178 of Complementary Law No. 214, of 2025.|
|620|Monophasic taxation|620004|Monophasic taxation on a mixture of EAC with gasoline A in a percentage higher or lower than the mandatory one, observing art. 179 of Complementary Law No. 214, of 2025.|
|620|Monophasic taxation|620005|Monophasic taxation on fuels previously charged, observing art. 180 of Complementary Law No. 214, of 2025.|
|800|Credit transfer|800001|Merger, spin-off, or incorporation, observing art. 55 of Complementary Law No. 214, of 2025.|
|800|Credit transfer|800002|Transfer of credit from the member, including single cooperatives, to the cooperative they participate in from operations preceding the operations in which they supply goods and services and the presumed credits, observing art. 272 of Complementary Law No. 214, of 2025.|
|810|Adjustments|810001|Presumed credit on the value calculated in supplies from the Manaus Free Trade Zone, observing art. 450 of Complementary Law No. 214, of 2025.|
|820|Taxation in a specific regime declaration|820001|Document with information on the provision of health assistance plan services, but with taxation carried out by other means, observing art. 235 of Complementary Law No. 214, of 2025.|
|820|Taxation in a specific regime declaration|820002|Document with information on the provision of funeral assistance plan services, but with taxation carried out by other means, observing art. 236 of Complementary Law No. 214, of 2025.|
|820|Taxation in a specific regime declaration|820003|Document with information on the provision of pet health assistance plan services, but with taxation carried out by other means, observing art. 243 of Complementary Law No. 214, of 2025.|
|820|Taxation in a specific regime declaration|820004|Document with information on the provision of lottery contest services, but with taxation carried out by other means, observing art. 248 of Complementary Law No. 214, of 2025.|
|820|Taxation in a specific regime declaration|820005|Document with information on the sale of real estate, but with taxation carried out by other means, observing art. 254 of Complementary Law No. 214, of 2025.|

---

## 11. Appendix H: Complete Enumeration (Enum) Reference

This appendix documents **all** enumerations used by the API, with the mapping between the JSON value, the corresponding SEFAZ XML value (when applicable), and the description of each value's meaning.

### 11.1. Operation Identification Enums

#### 11.1.1. `OperationType` — Operation Type (`tpNF`)

Identifies whether the NF-e/NFC-e represents an inflow or outflow of goods from the issuer's establishment.

| JSON Value | SEFAZ Value | Description | When to use |
|---|:---:|---|---|
| `Outgoing` | `1` | Outflow | Sales, shipments, outgoing transfers, exports. **Default**. |
| `Incoming` | `0` | Inflow | Received returns, returns, complementary inflow NF-e, credit NF-e. |

> **Rule:** Invoices with `purposeType = Devolution` or `creditType` informed must mandatorily be `Incoming`.

#### 11.1.2. `Destination` — Destination Location Identifier (`idDest`)

Indicates where the goods are destined for purposes of interstate taxation and DIFAL/IBS-CBS calculation.

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `None` | — | Not defined (do not use in production). |
| `InternalOperation` | `1` | Internal operation — recipient's UF **equal** to issuer's UF. **Default**. |
| `InterstateOperation` | `2` | Interstate operation — recipient's UF **different** from issuer's UF. |
| `InternationalOperation` | `3` | Operation with foreign country — recipient in country other than Brazil. |

> **Legacy aliases:** `Internal_Operation`, `Interstate_Operation`, `International_Operation` (with underscore) are accepted for compatibility, but the form without underscore is preferred.

#### 11.1.3. `PurposeType` — Issuance Purpose (`finNFe`)

Defines the fiscal nature of the NF-e/NFC-e and governs which groups can/must be filled.

| JSON Value | SEFAZ Value | Description | Restrictions |
|---|:---:|---|---|
| `None` | `0` | Not defined | Do not use. |
| `Normal` | `1` | Normal NF-e | **Default.** Standard fiscal operation. |
| `Complement` | `2` | Complementary NF-e | Must reference an original NF-e in `additionalInformation.taxDocumentsReference`. |
| `Adjustment` | `3` | Adjustment NF-e | Must reference original NF-e. Items' `totalIndicator` must be `false`. |
| `Devolution` | `4` | Goods return | Must be `operationType = Incoming` and reference the original NF-e. |

> **RTC:** As of 2026-01-05, values `5` (Credit) and `6` (Debit) are also valid via `creditType` and `debitType` fields (currently exposed as separate enums).

#### 11.1.4. `DebitType` — Debit Note Type (`tpNFDebito`)

Applicable only when `purposeType = 6` (Debit). Details the debit reason according to the Tax Reform.

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `TransferCreditsToCooperatives` | `01` | Credit transfer to cooperatives |
| `CancelCreditsExemptImmuneSales` | `02` | Credit cancellation for exempt/immune sales |
| `UnprocessedInvoicesDebits` | `03` | Debits of invoices not processed in the calculation |
| `FinesAndInterest` | `04` | Fines and interest |
| `TransferInheritanceCredit` | `05` | Credit transfer in succession |
| `AdvancePayment` | `06` | Advance payment |
| `InventoryLoss` | `07` | Inventory loss |
| `SnDisqualification` | `08` | Simples Nacional disqualification |

#### 11.1.5. `CreditType` — Credit Note Type (`tpNFCredito`)

Applicable only when `purposeType = 5` (Credit).

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `FinesAndInterest` | `01` | Fines and interest |
| `IbsPresumedCreditAppropriationZfm` | `02` | Appropriation of presumed IBS credit on debit balance in ZFM |
| `ReturnDeliveryRefusedOrNotFound` | `03` | Return for delivery refusal or recipient not found |
| `ValueReduction` | `04` | Value reduction |
| `TransferCreditSuccession` | `05` | Credit transfer in succession |

> **NT 2025.002:** Adjustment SINIEF 8/26 (effective 2026-05-04) introduced code `06` — *Return for partial delivery refusal*, which splits the former `03` (full refusal / recipient not found) and requires referencing the refused items in the original NF-e. Not yet exposed as an enum value in this API version.

### 11.2. Consumer / Buyer Enums

#### 11.2.1. `ConsumerType` — Final Consumer Indicator (`indFinal`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `Normal` | `0` | Operation **not** intended for final consumer (resale, industrialization, etc.). **Default for CNPJ**. |
| `FinalConsumer` | `1` | Operation intended for final consumer. **Default for CPF/NIF**. |

> **Inference rule:** If omitted, the system uses `buyer.federalTaxNumber`: CNPJ → `Normal`; CPF/NIF → `FinalConsumer`.

#### 11.2.2. `ConsumerPresenceType` — Presence Indicator (`indPres`)

Characterizes the channel/modality of the commercial operation.

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `None` | `0` | Not applicable (complementary or adjustment NF-e). |
| `Presence` | `1` | In-person operation (physical POS). |
| `Internet` | `2` | Non-presence operation via Internet (e-commerce). **Default**. |
| `Telephone` | `3` | Non-presence operation via telesales. |
| `Delivery` | `4` | NFC-e in operation with home delivery. |
| `OthersNonPresenceOperation` | `9` | Others, non-presence operation. |

> **NFC-e:** Only `Presence` and `Delivery` are accepted.

#### 11.2.3. `PersonType` — Person Type

| JSON Value | Numeric Value | Description |
|---|:---:|---|
| `Undefined` | `0` | Undefined. |
| `NaturalPerson` | `2` | Natural Person (PF). |
| `LegalEntity` | `4` | Legal Entity (PJ). |
| `Company` | `8` | (obsolete, internal use) Service provider. |
| `Customer` | `16` | (obsolete, internal use) Customer. |

> **Decimal flags:** This enum uses `[Flags]`, but in practice only `NaturalPerson` and `LegalEntity` are used in the external payload.

#### 11.2.4. `ReceiverStateTaxIndicator` — Recipient IE Indicator (`indIEDest`)

Defines the recipient's relationship with ICMS — critical field for DIFAL calculation and IE validation.

| JSON Value | SEFAZ Value | Description | IE Behavior |
|---|:---:|---|---|
| `None` | — | Not defined | Do not use. |
| `TaxPayer` | `1` | ICMS Taxpayer | `stateTaxNumber` **must** be informed and valid. |
| `Exempt` | `2` | Taxpayer exempt from registration | `stateTaxNumber` must not be informed. |
| `NonTaxPayer` | `9` | Non-Taxpayer | `stateTaxNumber` optional (may or may not have IE). |

### 11.3. Tax and Regime Enums

#### 11.3.1. `TaxRegime` — Tax Regime Code (`CRT`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `None` | — | Not defined. |
| `LucroReal` | `3` | Real Profit. |
| `LucroPresumido` | `3` | Presumed Profit (same CRT as Real Profit — categorized as "Normal Regime"). |
| `SimplesNacional` | `1` | Simples Nacional. |
| `SimplesNacionalExcessoSublimite` | `2` | Simples Nacional — gross revenue sublimit excess. |
| `MicroempreendedorIndividual` | `4` | Individual Microentrepreneur (MEI). |
| `Isento` | — | Exempt. |

#### 11.3.2. `SpecialTaxRegime` — Special Tax Regime (`indRegTrib`)

| JSON Value | Description |
|---|---|
| `Nenhum` | None |
| `MicroempresaMunicipal` | Municipal Microenterprise |
| `Estimativa` | Estimative |
| `SociedadeDeProfissionais` | Society of Professionals |
| `MicroempreendedorIndividual` | Individual Microentrepreneur (MEI) |
| `MicroempresarioEmpresaPequenoPorte` | Microentrepreneur and Small Business (ME/EPP) |
| `Automatico` | Automatic |

#### 11.3.3. `ExemptReason` — ICMS Exemption Reason (`motDesICMS`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `Agriculture` | `3` | Use in agriculture |
| `Others` | `9` | Others |
| `DevelopmentEntities` | `12` | Agricultural development and promotion entity |

#### 11.3.4. `DuductionIndicator` — Exempted ICMS Deduction Indicator (`indDeducao`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `NotDeduct` | `0` | The exempted ICMS amount **does not** deduct from the NF-e total. |
| `Deduce` | `1` | The exempted ICMS amount deducts from the NF-e total. |

### 11.4. IBS/CBS Enums (Tax Reform)

#### 11.4.1. `TaxCalculationMode` — IBS/CBS Calculation Mode

Defines how IBS/CBS fields are filled.

| JSON Value | Numeric Value | Description |
|---|:---:|---|
| `Manual` | `0` | Manual fill of all tax fields. **Default**. |
| `OfficialService` | `1` | Automatic calculation via official service. Only `situationCode` and `classCode` are needed; other tax fields are ignored on input and filled by the calculation service. |

#### 11.4.2. `IbsZfmPresumedCreditClassification` — ZFM Presumed Credit Classification (`tpCredPresIBSZFM`)

For calculating IBS presumed credit on supplies from the Manaus Free Trade Zone (art. 450 LC 214/2025).

| JSON Value | Percentage | Description |
|---|:---:|---|
| `NoPresumedCredit` | 0% | No presumed credit. |
| `FinalConsumptionGoods` | 55% | Final consumption goods. |
| `CapitalGoods` | 75% | Capital goods. |
| `IntermediateGoods` | 90.25% | Intermediate goods. |
| `ItAndOtherGoods` | 100% | IT and other goods defined in legislation. |

#### 11.4.3. `PresumedCreditClassificationCode` — Operational Presumed Credit (`cCredPres`)

Classifies the operation that grants the operational presumed credit.

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `RuralProducerNonTaxpayer` | `01` | Non-taxpayer rural producer (art. 168 LC 214/2025) |
| `TacPfTransportServiceNonTaxpayer` | `02` | Non-taxpayer PF transport service TAC (art. 169) |
| `RecyclingFromIndividual` | `03` | Recycling from individual (art. 170) |
| `UsedMovableGoodsFromIndividualForResale` | `04` | Used movable goods from PF for resale (art. 171) |
| `OptionalRegimeForCooperative` | — | Optional regime for cooperative |

> **`cCredPres` table:** The official table (Technical Note 2025.002) has **13 codes** (`01`–`13`), including the automotive regime (`05`–`06`) and the Manaus Free Trade Zone / Free Trade Areas (`07`–`13`). The `OptionalRegimeForCooperative` value does not map to a direct `cCredPres` code and is handled by the cooperatives' specific regime.

#### 11.4.4. `GovernmentPurchaseEntityType` — Government Entity Type (`tpEnteGov`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `Union` | `1` | Union |
| `State` | `2` | State |
| `FederalDistrict` | `3` | Federal District |
| `Municipality` | `4` | Municipality |

#### 11.4.5. `GovernmentPurchaseOperationType` — Government Operation Type (`tpOperGov`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `Supply` | `1` | Supply |
| `Payment` | `2` | Payment receipt |
| `SupplyThenPay` | — | Simultaneous supply and payment |
| `PayForPastSupply` | — | Payment for past supply |
| `SupplyAfterPay` | — | Supply after payment |
| `PayNowSupplyLater` | — | Pay now, supply later |
| `SupplyAndPayNow` | — | Supply and pay now |

> **`tpOperGov` field:** In NT 2025.002 (including v1.40), the SEFAZ field accepts only `1` (Supply) and `2` (Payment receipt). The other values are NFe.io API abstractions, resolved to `1` or `2` according to the IBS/CBS taxable event — combined scenarios are handled by validation rules and the `refDFeAnt` field, not by new codes.

### 11.5. Payment Enums

#### 11.5.1. `PaymentMethod` — Payment Method (`tPag`)

Complete list of payment methods accepted by SEFAZ.

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `Cash` | `01` | Cash |
| `Cheque` | `02` | Check |
| `CreditCard` | `03` | Credit Card |
| `DebitCard` | `04` | Debit Card |
| `StoreCredict` | `05` | Store Credit |
| `FoodVouchers` | `10` | Food Vouchers |
| `MealVouchers` | `11` | Meal Vouchers |
| `GiftVouchers` | `12` | Gift Vouchers |
| `FuelVouchers` | `13` | Fuel Vouchers |
| `MercantileDuplicate` | `14` | Mercantile Duplicate |
| `BankBill` | `15` | Bank Slip |
| `BankDeposit` | `16` | Bank Deposit |
| `InstantPayment` | `17` | Instant Payment (PIX) — dynamic |
| `WireTransfer` | `18` | Bank Transfer / Digital Wallet |
| `Cashback` | `19` | Loyalty Program / Cashback / Virtual Credit |
| `StaticInstantPayment` | `20` | Static PIX |
| `StoreCredit` | `21` | Store Credit |
| `ElectronicPaymentNotInformed` | `22` | Electronic Payment Not Informed |
| `WithoutPayment` | `90` | No Payment (e.g., shipment, bonification) |
| `Others` | `99` | Others |

> **Validation:** When `method = CreditCard` or `DebitCard`, the `card` group is **mandatory**.

#### 11.5.2. `PaymentType` — Payment Form Indicator (`indPag`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `InCash` | `0` | Cash payment (upfront) |
| `Term` | `1` | Term payment (installments) |

#### 11.5.3. `IntegrationPaymentType` — Integration Type (`tpIntegra`)

Applicable inside the `card` group.

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `Integrated` | `1` | Payment integrated with the company's automation system (e.g., TEF, E-commerce). |
| `NotIntegrated` | `2` | Payment not integrated (e.g., independent POS equipment). |

#### 11.5.4. `FlagCard` — Card Flag (`tBand`)

| JSON Value | SEFAZ Value | Flag |
|---|:---:|---|
| `None` | `00` | Not defined |
| `Visa` | `01` | Visa |
| `Mastercard` | `02` | Mastercard |
| `AmericanExpress` | `03` | American Express |
| `Sorocred` | `04` | Sorocred |
| `DinersClub` | `05` | Diners Club |
| `Elo` | `06` | Elo |
| `Hipercard` | `07` | Hipercard |
| `Aura` | `08` | Aura |
| `Cabal` | `09` | Cabal |
| `Alelo` | `10` | Alelo |
| `BanesCard` | `11` | Banescard |
| `CalCard` | `12` | Calcard |
| `Credz` | `13` | Credz |
| `Discover` | `14` | Discover |
| `GoodCard` | `15` | Good Card |
| `GreenCard` | `16` | Green Card |
| `Hiper` | `17` | Hiper |
| `JCB` | `18` | JCB |
| `Mais` | `19` | Mais |
| `MaxVan` | `20` | Maxvan |
| `Policard` | `21` | Policard |
| `RedeCompras` | `22` | Rede Compras |
| `Sodexo` | `23` | Sodexo |
| `ValeCard` | `24` | ValeCard |
| `Verocheque` | `25` | Verocheque |
| `VR` | `26` | VR |
| `Ticket` | `27` | Ticket |
| `Other` | `99` | Others |

### 11.6. Transport and Import Enums

#### 11.6.1. `ShippingModality` — Freight Modality (`modFrete`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `ByIssuer` | `0` | Freight contracted by the Sender (CIF) |
| `ByReceiver` | `1` | Freight contracted by the Recipient (FOB) |
| `ByThirdParties` | `2` | Freight contracted by third parties |
| `OwnBySender` | `3` | Own transport by sender |
| `OwnByBuyer` | `4` | Own transport by recipient |
| `Free` | `9` | No transport occurrence. **Default**. |

> **Validation:** If `Free`, the `transportGroup`, `transportVehicle`, `reboque` and `volume` groups must not be filled.

#### 11.6.2. `IntermediationType` — Import Intermediation Form (`tpIntermedio`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `None` | `0` | Not defined |
| `ByOwn` | `1` | Import on own account |
| `ImportOnBehalf` | `2` | Import on account and order of third party |
| `ByOrder` | `3` | Import by order |

#### 11.6.3. `InternationalTransportType` — International Transport Mode (`tpViaTransp`)

Informed in the Import Declaration (DI).

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `None` | `0` | Not defined |
| `Maritime` | `1` | Maritime |
| `River` | `2` | River |
| `Lake` | `3` | Lake |
| `Airline` | `4` | Air |
| `Postal` | `5` | Postal |
| `Railway` | `6` | Railway |
| `Highway` | `7` | Highway |
| `Network` | `8` | Pipeline / Transmission Network |
| `Own` | `9` | Own means |
| `Ficta` | `10` | Fictional inflow / outflow |
| `Courier` | `11` | Courier service |
| `Handcarry` | `12` | Hand-carry |

### 11.7. Print and Environment Enums

#### 11.7.1. `PrintType` — DANFE Print Format (`tpImp`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `None` | `0` | No DANFE generation |
| `NFeNormalPortrait` | `1` | DANFE normal — Portrait |
| `NFeNormalLandscape` | `2` | DANFE normal — Landscape |
| `NFeSimplified` | `3` | Simplified DANFE |
| `DANFE_NFC_E` | `4` | DANFE NFC-e |
| `DANFE_NFC_E_MSG_ELETRONICA` | `5` | DANFE NFC-e in electronic message |

#### 11.7.2. `EnvironmentType` — Environment Type (`tpAmb`)

| JSON Value | SEFAZ Value | Description |
|---|:---:|---|
| `None` | — | Not defined |
| `Production` | `1` | Production (fiscal validity) |
| `Test` | `2` | Homologation (no fiscal validity) |

#### 11.7.3. `StateTaxProcessingAuthorizer`

Identifies the SEFAZ authorizer that processed (or is processing) the document.

| JSON Value | Description |
|---|---|
| `Normal` | Normal Authorizer (issuer's UF SEFAZ or alternative authorizer) |
| `EPEC` | Authorizer for Prior Issuance Event in Contingency |

### 11.8. Status and Event Enums

#### 11.8.1. `InvoiceStatus` — NF-e Status

| JSON Value | Internal Numeric | Description |
|---|:---:|---|
| `None` | `0` | Initial state / not defined |
| `Created` | `1` | Created (received by API, not yet sent to SEFAZ) |
| `Processing` | `2` | In processing (submission in progress) |
| `Issued` | `3` | Issued and authorized by SEFAZ |
| `IssuedContingency` | `4` | Issued in contingency |
| `Cancelled` | `5` | Cancelled |
| `Disabled` | `6` | Invalidated (numbering) |
| `IssueDenied` | `-2` | Issuance denied by SEFAZ |
| `Error` | `-1` | Processing error |

#### 11.8.2. `EconomicActivityType` — Economic Activity Type

| JSON Value | Description |
|---|---|
| `Main` | Main |
| `Secondary` | Secondary |

### 11.9. Brazilian States Enum (`StateCode`)

List of Brazilian UF abbreviations + foreign indicator (`EX`). Applicable to fields like `state` (address), `customsClearanceState`, etc.

| Abbreviation | Description |
|---|---|
| `NA` | Not Applicable |
| `RO`, `AC`, `AM`, `RR`, `PA`, `AP`, `TO` | North Region |
| `MA`, `PI`, `CE`, `RN`, `PB`, `PE`, `AL`, `SE`, `BA` | Northeast Region |
| `MG`, `ES`, `RJ`, `SP` | Southeast Region |
| `PR`, `SC`, `RS` | South Region |
| `MS`, `MT`, `GO`, `DF` | Center-West Region |
| `EX` | Foreign country |

### 11.10. Legal Nature Enum (`LegalNature`)

Applicable to the issuer (`issuer.legalNature`).

| JSON Value | Description |
|---|---|
| `EmpresaPublica` | Public Company |
| `SociedadeEconomiaMista` | Mixed Economy Society |
| `SociedadeAnonimaAberta` | Open Joint-Stock Company |
| `SociedadeAnonimaFechada` | Closed Joint-Stock Company |
| `SociedadeEmpresariaLimitada` | Limited Business Society |
| `SociedadeEmpresariaEmNomeColetivo` | Business Society in Collective Name |
| `SociedadeEmpresariaEmComanditaSimples` | Business Society in Simple Limited Partnership |
| `SociedadeEmpresariaEmComanditaporAcoes` | Business Society in Limited Partnership by Shares |
| `SociedadeemContaParticipacao` | Society in Participation Account |
| `Empresario` | Individual Entrepreneur |
| `Cooperativa` | Cooperative |
| `ConsorcioSociedades` | Consortium of Societies |
| `GrupoSociedades` | Group of Societies |
| `EmpresaDomiciliadaExterior` | Company Domiciled Abroad |
| `ClubeFundoInvestimento` | Investment Club/Fund |
| `SociedadeSimplesPura` | Pure Simple Society |
| `SociedadeSimplesLimitada` | Limited Simple Society |
| `SociedadeSimplesEmNomeColetivo` | Simple Society in Collective Name |
| `SociedadeSimplesEmComanditaSimples` | Simple Society in Simple Limited Partnership |
| `EmpresaBinacional` | Binational Company |
| `ConsorcioEmpregadores` | Consortium of Employers |
| `ConsorcioSimples` | Simple Consortium |
| `EireliNaturezaEmpresaria` | EIRELI of Business Nature |
| `EireliNaturezaSimples` | EIRELI of Simple Nature |
| `ServicoNotarial` | Notarial and Registration Service |
| `FundacaoPrivada` | Private Foundation |
| `ServicoSocialAutonomo` | Autonomous Social Service |
| `CondominioEdilicio` | Building Condominium |
| `ComissaoConciliacaoPrevia` | Prior Conciliation Commission |
| `EntidadeMediacaoArbitragem` | Mediation and Arbitration Entity |
| `PartidoPolitico` | Political Party |
| `EntidadeSindical` | Trade Union Entity |
| `EstabelecimentoBrasilFundacaoAssociacaoEstrangeiras` | Brazilian Establishment of Foreign Foundation or Association |
| `FundacaoAssociacaoDomiciliadaExterior` | Foundation or Association Domiciled Abroad |
| `OrganizacaoReligiosa` | Religious Organization |
| `ComunidadeIndigena` | Indigenous Community |
| `FundoPrivado` | Private Fund |
| `AssociacaoPrivada` | Private Association |

---

## 12. Appendix I: Property-by-Property Mapping (JSON ↔ SEFAZ XML)

This section complements **Appendix A (§3)** going down to the level of each individual property. For each JSON field, we indicate the **full path**, the **corresponding XML tag** in the official layout (NT 2025.002), the **type**, and filling notes.

> **Convention:** The JSON path uses dot notation (e.g., `buyer.address.state`). The XML tag uses the exact element name in the official schema. When a JSON field encapsulates multiple tags or auxiliary structures, the "XML Tag" lists the principal tag.

### 12.1. Invoice Identification (`ide`)

These fields live at the **root level** of the request JSON.

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `serie` | `serie` | int | Document series (0–999). |
| `number` | `nNF` | int | Sequential number. |
| `operationOn` | `dhSaiEnt` | datetime | Exit/entry date and time. **Do not send for NFC-e.** |
| `expectedDeliveryOn` | `dPrevEntrega` | date | Expected delivery date. **Not applicable to NFC-e.** |
| `operationNature` | `natOp` | string | Operation description. |
| `operationType` | `tpNF` | enum | `Outgoing=1`, `Incoming=0`. See §11.1.1. |
| `destination` | `idDest` | enum | See §11.1.2. |
| `consumptionCityCode` | `cMunFG` | int | IBGE municipality code. |
| `ibsConsumptionCityCode` | `cMunFGIBS` | int | Applicable to in-person operations outside the establishment. |
| `printType` | `tpImp` | enum | See §11.7.1. |
| `purposeType` | `finNFe` | enum | See §11.1.3. |
| `debitType` | `tpNFDebito` | enum | Only for `purposeType=6`. See §11.1.4. |
| `creditType` | `tpNFCredito` | enum | Only for `purposeType=5`. See §11.1.5. |
| `consumerType` | `indFinal` | enum | See §11.2.1. |
| `presenceType` | `indPres` | enum | See §11.2.2. |
| `contingencyOn` | `dhCont` | datetime | Entry into contingency. |
| `contingencyJustification` | `xJust` | string | Justification (min. 15 chars). |

### 12.2. Government Purchases (`gCompraGov`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `governmentPurchase.entityType` | `tpEnteGov` | enum | See §11.4.4. |
| `governmentPurchase.rateReduction` | `pRedutor` | decimal | Rate reduction percentage (art. 472/370 LC 214/2025). |
| `governmentPurchase.operationType` | `tpOperGov` | enum | See §11.4.5. |

### 12.3. Buyer / Recipient (`dest`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `buyer.name` | `xNome` | string | **Mandatory.** |
| `buyer.federalTaxNumber` | `CNPJ` or `CPF` | int | **Mandatory.** Or `idEstrangeiro` for foreign. |
| `buyer.email` | `email` | string | **Mandatory.** |
| `buyer.tradeName` | `xFant` | string | Trade name. |
| `buyer.taxRegime` | `CRT` | enum | See §11.3.1. |
| `buyer.stateTaxNumber` | `IE` | string | State registration. |
| `buyer.stateTaxNumberIndicator` | `indIEDest` | enum | See §11.2.4. |
| `buyer.type` | (logical) | enum | Person type (NaturalPerson/LegalEntity). |
| `buyer.address.state` | `UF` | string | ISO 3166-2 abbreviation (2 chars). |
| `buyer.address.city.code` | `cMun` | string | IBGE code. |
| `buyer.address.city.name` | `xMun` | string | Municipality name. |
| `buyer.address.district` | `xBairro` | string | District. |
| `buyer.address.additionalInformation` | `xCpl` | string | Address complement. |
| `buyer.address.street` | `xLgr` | string | Street. |
| `buyer.address.number` | `nro` | string | "S/N" if no number. |
| `buyer.address.postalCode` | `CEP` | string | Postal code (digits only). |
| `buyer.address.country` | `xPais` | string | ISO 3166-1 alpha-3. **Default `BRA`.** |
| `buyer.address.phone` | `fone` | string | Phone (area code + number). |

### 12.4. Delivery and Withdrawal Locations

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `delivery.federalTaxNumber` | `CNPJ`/`CPF` (in `entrega`) | int | Only if different from `buyer`. |
| `delivery.address.*` | `entrega/...` | object | Same structure as `buyer.address`. |
| `withdrawal.federalTaxNumber` | `CNPJ`/`CPF` (in `retirada`) | int | Only if different from issuer. |
| `withdrawal.address.*` | `retirada/...` | object | Same structure as `buyer.address`. |

### 12.5. Item — Identification and Values

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `items[].code` | `cProd` | string | **Mandatory.** |
| `items[].codeGTIN` | `cEAN` | string | "SEM GTIN" if non-existent. |
| `items[].description` | `xProd` | string | **Mandatory.** |
| `items[].ncm` | `NCM` | string | 2 or 8 digits. |
| `items[].nve[]` | `NVE` | string array | Customs and Statistical Value Nomenclature. |
| `items[].extipi` | `EXTIPI` | string | TIPI exception. |
| `items[].cfop` | `CFOP` | int | **Mandatory if no `taxDetermination`.** |
| `items[].unit` | `uCom` | string | Commercial unit. |
| `items[].quantity` | `qCom` | decimal | Commercial quantity. |
| `items[].unitAmount` | `vUnCom` | decimal | Commercial unit price. |
| `items[].totalAmount` | `vProd` | decimal | `quantity * unitAmount`. |
| `items[].codeTaxGTIN` | `cEANTrib` | string | Taxable unit GTIN; "SEM GTIN" if none. |
| `items[].unitTax` | `uTrib` | string | Taxable unit. |
| `items[].quantityTax` | `qTrib` | decimal | Taxable quantity. |
| `items[].taxUnitAmount` | `vUnTrib` | decimal | Taxable unit price. |
| `items[].freightAmount` | `vFrete` | decimal | Freight amount apportioned to the item. |
| `items[].insuranceAmount` | `vSeg` | decimal | Insurance amount apportioned to the item. |
| `items[].discountAmount` | `vDesc` | decimal | Item discount amount. |
| `items[].othersAmount` | `vOutro` | decimal | Other accessory expenses of the item. |
| `items[].totalIndicator` | `indTot` | bool | `0` or `1`. **Default `true`.** |
| `items[].usedMovableAssetIndicator` | `indBemMovelUsado` | bool | Used movable asset indicator (IBS/CBS specific regime for resale). |
| `items[].cest` | `CEST` | string | 7 digits. |
| `items[].itemAmount` | `vItem` | decimal | Total item value (vProd + additions − discounts). |
| `items[].numberOrderBuy` | `xPed` | string | Purchase order number. |
| `items[].itemNumberOrderBuy` | `nItemPed` | int | Item number in the purchase order. |
| `items[].importControlSheetNumber` | `nFCI` | string | Import Content Sheet. |
| `items[].benefit` | `cBenef` | string | Tax benefit code in the UF. |
| `items[].additionalInformation` | `infAdProd` | string | Product additional information. |

### 12.6. Item — ICMS (`tax.icms`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `items[].tax.icms.origin` | `orig` | string | Goods origin (`0`–`8`): domestic, imported (direct or domestic market), etc. |
| `items[].tax.icms.cst` | `CST` | string | ICMS Tax Situation Code (normal regime). |
| `items[].tax.icms.csosn` | `CSOSN` | string | Operation Situation Code under Simples Nacional (replaces CST for `CRT=1`). |
| `items[].tax.icms.baseTaxModality` | `modBC` | string | ICMS calculation basis modality: `0`=Value Added Margin (%); `1`=List (value); `2`=Max. Tabled Price (value); `3`=Operation value. |
| `items[].tax.icms.baseTax` | `vBC` | decimal | ICMS calculation basis amount. |
| `items[].tax.icms.rate` | `pICMS` | decimal | ICMS rate (%). |
| `items[].tax.icms.amount` | `vICMS` | decimal | ICMS amount. |
| `items[].tax.icms.baseTaxReduction` | `pRedBC` | decimal | Calculation basis reduction percentage. |
| `items[].tax.icms.baseTaxSTModality` | `modBCST` | string | ICMS ST basis modality: `0`=Tabled/max. suggested price; `1`=Negative List; `2`=Positive List; `3`=Neutral List; `4`=Value Added Margin (%); `5`=List. |
| `items[].tax.icms.baseTaxSTReduction` | `pRedBCST` | decimal | ICMS ST basis reduction percentage. |
| `items[].tax.icms.baseTaxST` | `vBCST` | decimal | ICMS ST calculation basis amount. |
| `items[].tax.icms.stRate` | `pICMSST` | decimal | ICMS ST rate (%). |
| `items[].tax.icms.stAmount` | `vICMSST` | decimal | ICMS ST amount. |
| `items[].tax.icms.stMarginAmount` | `pMVAST` | decimal | ICMS ST value added margin percentage. |
| `items[].tax.icms.stRetentionAmount` | `vICMSSTRet` | decimal | ICMS ST previously withheld amount. |
| `items[].tax.icms.baseSTRetentionAmount` | `vBCSTRet` | decimal | ICMS ST previously withheld basis amount. |
| `items[].tax.icms.snCreditRate` | `pCredSN` | decimal | Applicable credit calculation rate (Simples Nacional). |
| `items[].tax.icms.snCreditAmount` | `vCredICMSSN` | decimal | ICMS credit amount available for use (Simples Nacional). |
| `items[].tax.icms.fcpRate` | `pFCP` | decimal | Poverty Combat Fund (FCP) percentage. |
| `items[].tax.icms.fcpAmount` | `vFCP` | decimal | FCP amount. |
| `items[].tax.icms.fcpstRate` | `pFCPST` | decimal | FCP percentage withheld by ST. |
| `items[].tax.icms.fcpstAmount` | `vFCPST` | decimal | FCP amount withheld by ST. |
| `items[].tax.icms.fcpstRetRate` | `pFCPSTRet` | decimal | FCP percentage previously withheld by ST. |
| `items[].tax.icms.fcpstRetAmount` | `vFCPSTRet` | decimal | FCP amount previously withheld by ST. |
| `items[].tax.icms.baseTaxFCPSTAmount` | `vBCFCPST` | decimal | FCP-ST calculation basis amount. |
| `items[].tax.icms.exemptAmount` | `vICMSDeson` | decimal | Exempted ICMS amount. |
| `items[].tax.icms.exemptReason` | `motDesICMS` | enum | ICMS exemption reason. See §11.3.3. |
| `items[].tax.icms.deductionIndicator` | `indDeducao` | enum | Indicator for deducting the exempted ICMS from the item amount. See §11.3.4. |
| `items[].tax.icms.ufst` | `UFST` | string | UF to which the ICMS ST is due. |
| `items[].tax.icms.percentualDeferment` | `pDif` | decimal | ICMS deferment percentage. |
| `items[].tax.icms.baseDeferred` | `vICMSDif` | decimal | Deferred ICMS amount. |
| `items[].tax.icms.basisBenefitCode` | `cBenefRBC` | string | UF tax benefit code applied to the item when there is a basis reduction. |
| `items[].tax.icms.stFinalConsumerRate` | `pST` | decimal | Rate borne by the final consumer (ST with withholding). |
| `items[].tax.icms.effectiveBaseTaxReductionRate` | `pRedBCEfet` | decimal | Effective basis reduction percentage. |
| `items[].tax.icms.effectiveBaseTaxAmount` | `vBCEfet` | decimal | Effective calculation basis amount. |
| `items[].tax.icms.effectiveRate` | `pICMSEFET` | decimal | Effective ICMS rate (%). |
| `items[].tax.icms.effectiveAmount` | `vICMSEFET` | decimal | Effective ICMS amount. |

### 12.7. Item — IPI / II / PIS / COFINS

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `items[].tax.ipi.cst` | `CST` (in `IPI`) | string | IPI Tax Situation Code. |
| `items[].tax.ipi.classificationCode` | `cEnq` | string | IPI legal classification code. |
| `items[].tax.ipi.classification` | `clEnq` | string | IPI classification class (cigarettes and beverages). |
| `items[].tax.ipi.producerCNPJ` | `CNPJProd` | string | CNPJ of the goods producer, when different from the issuer. |
| `items[].tax.ipi.stampCode` | `cSelo` | string | IPI control stamp code. |
| `items[].tax.ipi.stampQuantity` | `qSelo` | decimal | IPI control stamp quantity. |
| `items[].tax.ipi.base` | `vBC` (in `IPI`) | decimal | IPI calculation basis (taxation by value). |
| `items[].tax.ipi.rate` | `pIPI` | decimal | IPI rate (%). |
| `items[].tax.ipi.unitQuantity` | `qUnid` | decimal | Total quantity in the standard unit (IPI taxation per unit). |
| `items[].tax.ipi.unitAmount` | `vUnid` | decimal | Value per taxable unit (IPI taxation per unit). |
| `items[].tax.ipi.amount` | `vIPI` | decimal | IPI amount. |
| `items[].tax.ii.baseTax` | `vBC` (in `II`) | decimal | Import Tax calculation basis. |
| `items[].tax.ii.customsExpenditureAmount` | `vDespAdu` | decimal | Customs expenditure amount. |
| `items[].tax.ii.amount` | `vII` | decimal | Import Tax amount. |
| `items[].tax.ii.iofAmount` | `vIOF` | decimal | IOF (Tax on Financial Operations) amount. |
| `items[].tax.pis.cst` | `CST` (in `PIS`) | string | PIS Tax Situation Code. |
| `items[].tax.pis.baseTax` | `vBC` (in `PIS`) | decimal | PIS calculation basis (taxation by percentage). |
| `items[].tax.pis.rate` | `pPIS` | decimal | PIS rate (%). |
| `items[].tax.pis.amount` | `vPIS` | decimal | PIS amount. |
| `items[].tax.pis.baseTaxProductQuantity` | `qBCProd` | decimal | Quantity sold (PIS taxation by specific rate/unit). |
| `items[].tax.pis.productRate` | `vAliqProd` | decimal | PIS rate as value per unit (R$). |
| `items[].tax.cofins.cst` | `CST` (in `COFINS`) | string | COFINS Tax Situation Code. |
| `items[].tax.cofins.baseTax` | `vBC` (in `COFINS`) | decimal | COFINS calculation basis (taxation by percentage). |
| `items[].tax.cofins.rate` | `pCOFINS` | decimal | COFINS rate (%). |
| `items[].tax.cofins.amount` | `vCOFINS` | decimal | COFINS amount. |
| `items[].tax.cofins.baseTaxProductQuantity` | `qBCProd` | decimal | Quantity sold (COFINS taxation by specific rate/unit). |
| `items[].tax.cofins.productRate` | `vAliqProd` | decimal | COFINS rate as value per unit (R$). |

### 12.8. Item — ICMS Destination UF (`ICMSUFDest`)

Applicable to interstate operations with non-taxpayer final consumers (DIFAL).

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `items[].tax.icmsDestination.vBCUFDest` | `vBCUFDest` | decimal | ICMS calculation basis amount in the destination UF. |
| `items[].tax.icmsDestination.pFCPUFDest` | `pFCPUFDest` | decimal | FCP percentage due to the destination UF. |
| `items[].tax.icmsDestination.pICMSUFDest` | `pICMSUFDest` | decimal | Internal rate in the destination UF. |
| `items[].tax.icmsDestination.pICMSInter` | `pICMSInter` | decimal | Interstate rate applicable between origin and destination UF. |
| `items[].tax.icmsDestination.pICMSInterPart` | `pICMSInterPart` | decimal | Provisional sharing percentage of interstate ICMS (currently 100% to the destination UF). |
| `items[].tax.icmsDestination.vFCPUFDest` | `vFCPUFDest` | decimal | FCP amount due to the destination UF. |
| `items[].tax.icmsDestination.vICMSUFDest` | `vICMSUFDest` | decimal | ICMS sharing amount due to the destination UF. |
| `items[].tax.icmsDestination.vICMSUFRemet` | `vICMSUFRemet` | decimal | ICMS sharing amount due to the sender UF. |
| `items[].tax.icmsDestination.vBCFCPUFDest` | `vBCFCPUFDest` | decimal | FCP calculation basis amount in the destination UF. |

### 12.9. Item — Selective Tax (`IS`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `items[].tax.IS.situationCode` | `CSTIS` | string | 3 digits. |
| `items[].tax.IS.classificationCode` | `cClassTribIS` | string | 6 digits. |
| `items[].tax.IS.basis` | `vBCIS` | decimal | 13.2. |
| `items[].tax.IS.rate` | `pIS` | decimal | Up to 4 decimals. |
| `items[].tax.IS.unitRate` | `pISEspec` | decimal | Specific rate per unit. |
| `items[].tax.IS.unit` | `uTrib` | string | Taxable unit. |
| `items[].tax.IS.quantity` | `qTrib` | decimal | Taxable quantity for the Selective Tax. |
| `items[].tax.IS.amount` | `vIS` | decimal | Selective Tax amount. |

### 12.10. Item — IBS/CBS (`IBSCBS`)

#### Root and jurisdictions

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `items[].tax.IBSCBS.situationCode` | `CST` (in `IBSCBS`) | string | IBS/CBS Tax Situation Code (3 digits). See §10. |
| `items[].tax.IBSCBS.classCode` | `cClassTrib` | string | IBS/CBS tax classification code. See §10. |
| `items[].tax.IBSCBS.donationIndicator` | `indDoacao` | string | Indicator of donation to a government entity. See §4.6.1. |
| `items[].tax.IBSCBS.basis` | `vBC` (in `IBSCBS`) | decimal | IBS/CBS calculation basis. |
| `items[].tax.IBSCBS.state.rate` | `pIBSUF` | decimal | State IBS rate (%). |
| `items[].tax.IBSCBS.state.amount` | `vIBSUF` | decimal | State IBS amount. |
| `items[].tax.IBSCBS.municipal.rate` | `pIBSMun` | decimal | Municipal IBS rate (%). |
| `items[].tax.IBSCBS.municipal.amount` | `vIBSMun` | decimal | Municipal IBS amount. |
| `items[].tax.IBSCBS.cbs.rate` | `pCBS` | decimal | CBS rate (%). |
| `items[].tax.IBSCBS.cbs.amount` | `vCBS` | decimal | CBS amount. |
| `items[].tax.IBSCBS.ibsTotalAmount` | `vIBSTot` | decimal | Total IBS amount (state + municipal). |

#### Per-jurisdiction subgroups (`state`/`municipal`/`cbs`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `*.deferment.rate` | `pDif` | decimal | Deferment percentage applied to the jurisdiction. See §4.4.1. |
| `*.deferment.amount` | `vDif` | decimal | Deferred tax amount. |
| `*.reduction.rateReduction` | `pRedAliq` | decimal | Rate reduction percentage. See §4.4.2. |
| `*.reduction.effectiveRate` | `pAliqEfet` | decimal | Effective rate after reduction. |
| `*.returnedAmount.amount` | `vDevTrib` | decimal | Tax amount returned to the taxpayer. See §4.4.3. |

#### Special subgroups (root `IBSCBS`)

> Each subgroup is an object with multiple fields; refer to the indicated reference section for the detail of each property.

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `items[].tax.IBSCBS.regularTaxation.*` | `gTribRegular` | object | Hypothetical regular taxation (informational). See §4.5.6. |
| `items[].tax.IBSCBS.governmentPurchase.*` | `gIBSCBS_CompraGov` | object | Government purchase composition. See §4.5.5. |
| `items[].tax.IBSCBS.monophase.standart.*` | `gMonofasicoPadrao` | object | Standard monophasic taxation. See §4.5.1. |
| `items[].tax.IBSCBS.monophase.withholding.*` | `gMonofasicoRetido` | object | Monophasic with withholding. See §4.5.1. |
| `items[].tax.IBSCBS.monophase.previouslyWithheld.*` | `gMonofasicoRetidoAnt` | object | Monophasic previously withheld. See §4.5.1. |
| `items[].tax.IBSCBS.monophase.deferment.*` | `gMonofasicoDif` | object | Monophasic with deferment. See §4.5.1. |
| `items[].tax.IBSCBS.creditTransfer.*` | `gTransfCred` | object | Credit transfer. See §4.5.3. |
| `items[].tax.IBSCBS.operationalPresumedCredit.*` | `gCredPresOper` | object | Operational presumed credit. See §4.5.2. |
| `items[].tax.IBSCBS.creditReversal.*` | `gEstornoCred` | object | Credit reversal. See §4.5.4. |
| `items[].tax.IBSCBS.zfmPresumedCredit.*` | `gCredPresIBSZFM` | object | Manaus Free Trade Zone presumed credit. See §4.5.7. |
| `items[].competenceAdjustment.*` | `gAjusteCompet` | object | Competence adjustment. See §4.6.2. |

### 12.11. Totals (`total`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `totals.icms.baseTax` | `vBC` | decimal | ICMS calculation basis (sum of items). |
| `totals.icms.icmsAmount` | `vICMS` | decimal | Total ICMS amount. |
| `totals.icms.icmsExemptAmount` | `vICMSDeson` | decimal | Total exempted ICMS amount. |
| `totals.icms.stCalculationBasisAmount` | `vBCST` | decimal | ICMS ST calculation basis. |
| `totals.icms.stAmount` | `vST` | decimal | Total ICMS ST amount. |
| `totals.icms.productAmount` | `vProd` | decimal | Total amount of products and services. |
| `totals.icms.freightAmount` | `vFrete` | decimal | Total freight amount. |
| `totals.icms.insuranceAmount` | `vSeg` | decimal | Total insurance amount. |
| `totals.icms.discountAmount` | `vDesc` | decimal | Total discount amount. |
| `totals.icms.iiAmount` | `vII` | decimal | Total Import Tax amount. |
| `totals.icms.ipiAmount` | `vIPI` | decimal | Total IPI amount. |
| `totals.icms.pisAmount` | `vPIS` | decimal | Total PIS amount. |
| `totals.icms.cofinsAmount` | `vCOFINS` | decimal | Total COFINS amount. |
| `totals.icms.othersAmount` | `vOutro` | decimal | Other accessory expenses. |
| `totals.icms.invoiceAmount` | `vNF` | decimal | Total NF-e amount. |
| `totals.icms.fcpufDestinationAmount` | `vFCPUFDest` | decimal | Total FCP amount due to the destination UF. |
| `totals.icms.icmsufDestinationAmount` | `vICMSUFDest` | decimal | Total ICMS sharing amount for the destination UF. |
| `totals.icms.icmsufSenderAmount` | `vICMSUFRemet` | decimal | Total ICMS sharing amount for the sender UF. |
| `totals.icms.federalTaxesAmount` | `vTotTrib` | decimal | Approximate total amount of taxes (federal, state, and municipal). |
| `totals.icms.fcpAmount` | `vFCP` | decimal | Total FCP amount. |
| `totals.icms.fcpstAmount` | `vFCPST` | decimal | Total FCP amount withheld by ST. |
| `totals.icms.fcpstRetAmount` | `vFCPSTRet` | decimal | Total FCP amount previously withheld by ST. |
| `totals.icms.ipiDevolAmount` | `vIPIDevol` | decimal | Total returned IPI amount. |
| `totals.issqn.baseRateISS` | `vBC` (in `ISSQNtot`) | decimal | ISSQN calculation basis. |
| `totals.issqn.totalISS` | `vISS` | decimal | Total ISSQN amount. |
| `totals.withheldTaxes.pisAmount` | `vRetPIS` | decimal | PIS amount withheld by substitution. |
| `totals.withheldTaxes.cofinsAmount` | `vRetCOFINS` | decimal | COFINS amount withheld by substitution. |
| `totals.withheldTaxes.csllAmount` | `vRetCSLL` | decimal | Withheld CSLL amount. |
| `totals.withheldTaxes.irrfBasis` | `vBCIRRF` | decimal | IRRF calculation basis. |
| `totals.withheldTaxes.irrfAmount` | `vIRRF` | decimal | Withheld IRRF amount. |
| `totals.withheldTaxes.socialSecutiryBasis` | `vBCRetPrev` | decimal | Social Security withholding calculation basis. |
| `totals.withheldTaxes.socialSecutiryAmount` | `vRetPrev` | decimal | Social Security withholding amount. |
| `totals.isTotals.amount` | `vIS` (in `ISTot`) | decimal | Total Selective Tax amount. |
| `totals.ibsCbsTotals.basis` | `vBCIBSCBS` | decimal | Total IBS/CBS calculation basis. |
| `totals.ibsCbsTotals.ibs.state.amount` | `vIBSUF` (in totals) | decimal | Total state IBS amount. |
| `totals.ibsCbsTotals.ibs.municipal.amount` | `vIBSMun` (in totals) | decimal | Total municipal IBS amount. |
| `totals.ibsCbsTotals.ibs.totalAmount` | `vIBS` (in `IBSCBSTot`) | decimal | Total IBS amount (state + municipal). |
| `totals.ibsCbsTotals.cbs.amount` | `vCBS` (in totals) | decimal | Total CBS amount. |
| `totals.totalInvoiceAmount` | `vNFTot` | decimal | Total NF-e amount considering IBS/CBS/IS. |

### 12.12. Transport (`transp`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `transport.freightModality` | `modFrete` | enum | Freight modality. See §11.6.1. |
| `transport.transportGroup.name` | `xNome` | string | Carrier company name or name. |
| `transport.transportGroup.federalTaxNumber` | `CNPJ`/`CPF` | int | Carrier CNPJ or CPF. |
| `transport.transportGroup.stateTaxNumber` | `IE` | string | Carrier state tax registration. |
| `transport.transportGroup.address.*` | (subfields of `transporta`) | object | Carrier address (`xEnder`, `xMun`, `UF`). |
| `transport.transportVehicle.plate` | `placa` | string | Transport vehicle license plate. |
| `transport.transportVehicle.state` | `UF` | string | Vehicle registration UF. |
| `transport.transportVehicle.rntc` | `RNTC` | string | National Cargo Carrier Registry (ANTT). |
| `transport.reboque.plate` | `placa` (in `reboque`) | string | Trailer license plate. |
| `transport.reboque.uf` | `UF` (in `reboque`) | string | Trailer registration UF. |
| `transport.reboque.rntc` | `RNTC` (in `reboque`) | string | Trailer RNTC. |
| `transport.reboque.wagon` | `vagao` | string | Wagon identification (rail transport). |
| `transport.reboque.ferry` | `balsa` | string | Ferry identification. |
| `transport.volume.volumeQuantity` | `qVol` | int | Quantity of transported volumes. |
| `transport.volume.species` | `esp` | string | Species of the transported volumes. |
| `transport.volume.brand` | `marca` | string | Brand of the transported volumes. |
| `transport.volume.volumeNumeration` | `nVol` | string | Numbering of the transported volumes. |
| `transport.volume.netWeight` | `pesoL` | decimal | Net weight (kg). |
| `transport.volume.grossWeight` | `pesoB` | decimal | Gross weight (kg). |
| `transport.sealNumber` | `nLacre` | string | Seal numbers. |
| `transport.transpRate.serviceAmount` | `vServ` | decimal | Transport service amount (transport ICMS withholding). |
| `transport.transpRate.bcRetentionAmount` | `vBCRet` | decimal | Transport ICMS withholding calculation basis. |
| `transport.transpRate.icmsRetentionRate` | `pICMSRet` | decimal | Transport ICMS withholding rate. |
| `transport.transpRate.icmsRetentionAmount` | `vICMSRet` | decimal | Withheld transport ICMS amount. |
| `transport.transpRate.cfop` | `CFOP` (in `retTransp`) | int | Transport service CFOP. |
| `transport.transpRate.cityGeneratorFactCode` | `cMunFG` (in `retTransp`) | int | IBGE code of the city where the transport ICMS taxable event occurred. |

### 12.13. Payment (`pag`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `payment[].paymentDetail[].method` | `tPag` | enum | Payment method. See §11.5.1. |
| `payment[].paymentDetail[].methodDescription` | `xPag` | string | Payment method description (required when `tPag=99`/others). |
| `payment[].paymentDetail[].paymentType` | `indPag` | enum | Payment form indicator (cash/installment). See §11.5.2. |
| `payment[].paymentDetail[].amount` | `vPag` | decimal | Payment amount. |
| `payment[].paymentDetail[].paymentDate` | `dPag` | datetime | Payment date. |
| `payment[].paymentDetail[].federalTaxNumberPag` | `CNPJPag` | string | CNPJ of the establishment receiving the payment. |
| `payment[].paymentDetail[].statePag` | `UFPag` | string | UF of the payment beneficiary. |
| `payment[].paymentDetail[].card.federalTaxNumber` | `CNPJ` (in `card`) | string | CNPJ of the credit/debit card acquirer. |
| `payment[].paymentDetail[].card.flag` | `tBand` | enum | Card flag. See §11.5.4. |
| `payment[].paymentDetail[].card.authorization` | `cAut` | string | Card operation authorization number. |
| `payment[].paymentDetail[].card.integrationPaymentType` | `tpIntegra` | enum | Payment integration type with the automation system. See §11.5.3. |
| `payment[].payBack` | `vTroco` | decimal | Change amount. |

### 12.14. Billing (`cobr`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `billing.bill.number` | `nFat` | string | Invoice (fatura) number. |
| `billing.bill.originalAmount` | `vOrig` | decimal | Original invoice amount. |
| `billing.bill.discountAmount` | `vDesc` | decimal | Invoice discount amount. |
| `billing.bill.netAmount` | `vLiq` | decimal | Net invoice amount. |
| `billing.duplicates[].number` | `nDup` | string | Installment (duplicata) number. |
| `billing.duplicates[].expirationOn` | `dVenc` | datetime | Installment due date. |
| `billing.duplicates[].amount` | `vDup` | decimal | Installment amount. |

### 12.15. Additional Information (`infAdic`)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `additionalInformation.fisco` | `infAdFisco` | string | Additional information of interest to the tax authority. |
| `additionalInformation.taxpayer` | `infCpl` | string | Complementary information of interest to the taxpayer. |
| `additionalInformation.xmlAuthorized[]` | `autXML/CNPJ`/`CPF` | int array | CNPJ/CPF authorized to access the NF-e XML. |
| `additionalInformation.taxDocumentsReference[].documentElectronicInvoice.accessKey` | `refNFe` | string | Access key of the referenced NF-e. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.federalTaxNumber` | `refNF/CNPJ` | string | CNPJ of the issuer of the referenced NF (model 1/1A). |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.state` | `refNF/cUF` | int | UF code of the referenced NF issuer. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.yearMonth` | `refNF/AAMM` | string | Year and month (AAMM) of issuance of the referenced NF. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.model` | `refNF/mod` | string | Model of the referenced fiscal document. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.series` | `refNF/serie` | string | Series of the referenced NF. |
| `additionalInformation.taxDocumentsReference[].documentInvoiceReference.number` | `refNF/nNF` | string | Number of the referenced NF. |
| `additionalInformation.taxDocumentsReference[].taxCouponInformation.modelDocumentFiscal` | `refECF/mod` | string | Model of the referenced Tax Coupon (ECF). |
| `additionalInformation.taxDocumentsReference[].taxCouponInformation.orderECF` | `refECF/nECF` | string | Sequential order number of the ECF. |
| `additionalInformation.taxDocumentsReference[].taxCouponInformation.orderCountOperation` | `refECF/nCOO` | int | Operation Order Counter number (COO). |
| `additionalInformation.advancePayment[].accessKey` | `gPagAntecipado/refNFe` | string | Access key of an advance-payment NF-e. |
| `additionalInformation.taxpayerComments[].field` | `obsCont/xCampo` | string | Identification of the taxpayer free field. |
| `additionalInformation.taxpayerComments[].text` | `obsCont/xTexto` | string | Content of the taxpayer free field. |
| `additionalInformation.referencedProcess[].identifierConcessory` | `nProc` | string | Identifier of the process or granting act. |
| `additionalInformation.referencedProcess[].identifierOrigin` | `indProc` | int | Process origin (SEFAZ, Federal/State Justice, Secex/RFB, others). |
| `additionalInformation.referencedProcess[].concessionActType` | `tpAto` | int | Granting act type. |

### 12.16. Purchase, Export, and Intermediate

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `purchaseInformation.commitmentNote` | `xNEmp` | string | Commitment note (public procurement). |
| `purchaseInformation.purchaseOrder` | `xPed` (in `compra`) | string | Purchase order number. |
| `purchaseInformation.contractNumber` | `xCont` | string | Contract number. |
| `export.state` | `UFSaidaPais` | enum | UF of embarkation or border crossing. |
| `export.office` | `xLocExporta` | string | Place of embarkation or dispatch of the export. |
| `export.local` | `xLocDespacho` | string | Description of the dispatch location. |
| `transactionIntermediate.federalTaxNumber` | `CNPJ` (in `infIntermed`) | int | CNPJ of the transaction intermediary (e.g., marketplace). |
| `transactionIntermediate.identifier` | `idCadIntTran` | string | Identifier of the intermediary in the marketplace portal. |
| `issuerTaxSubstitute.stStateTaxNumber` | `IEST` | string | State tax registration of the tax substitute in the destination UF. |

### 12.17. Item — Special Subgroups (DI, Fuel, Vehicle)

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `items[].importDeclarations[].code` | `nDI` | string | Import Declaration number (DI/DSI/DA). |
| `items[].importDeclarations[].registeredOn` | `dDI` | datetime | DI registration date. |
| `items[].importDeclarations[].customsClearanceName` | `xLocDesemb` | string | Customs clearance location. |
| `items[].importDeclarations[].customsClearanceState` | `UFDesemb` | enum | UF where customs clearance took place. |
| `items[].importDeclarations[].customsClearancedOn` | `dDesemb` | datetime | Customs clearance date. |
| `items[].importDeclarations[].afrmmAmount` | `vAFRMM` | decimal | AFRMM amount (Merchant Marine Renewal Freight Surcharge). |
| `items[].importDeclarations[].internationalTransport` | `tpViaTransp` | enum | International transport mode. See §11.6.3. |
| `items[].importDeclarations[].intermediation` | `tpIntermedio` | enum | Import intermediation form. See §11.6.2. |
| `items[].importDeclarations[].acquirerFederalTaxNumber` | `CNPJ`/`CPF` | string | CNPJ/CPF of the acquirer or orderer. |
| `items[].importDeclarations[].stateThird` | `UFTerceiro` | string | UF of the acquirer or orderer. |
| `items[].importDeclarations[].exporter` | `cExportador` | string | Exporter code (used by the importer in its records). |
| `items[].importDeclarations[].additions[].code` | `nAdicao` | int | Sequential addition number. |
| `items[].importDeclarations[].additions[].manufacturer` | `cFabricante` | string | Foreign manufacturer code (importer record). |
| `items[].importDeclarations[].additions[].amount` | `vDescDI` | decimal | Addition discount amount. |
| `items[].importDeclarations[].additions[].drawback` | `nDraw` | int | Drawback granting act number. |
| `items[].fuelDetail.codeANP` | `cProdANP` | string | Product code per the ANP table. |
| `items[].fuelDetail.descriptionANP` | `descANP` | string | Product description per the ANP. |
| `items[].fuelDetail.percentageNG` | `pMixGN` | decimal | Percentage of natural gas in the GLP product (mixture). |
| `items[].fuelDetail.percentageGLP` | `pGLP` | decimal | Percentage of GLP derived from petroleum. |
| `items[].fuelDetail.percentageNGn` | `pGNn` | decimal | Percentage of domestic natural gas. |
| `items[].fuelDetail.percentageGNi` | `pGNi` | decimal | Percentage of imported natural gas. |
| `items[].fuelDetail.startingAmount` | `vPart` | decimal | Starting value (`pGLP` × sale value). |
| `items[].fuelDetail.codif` | `CODIF` | string | Authorization/registration code in CODIF. |
| `items[].fuelDetail.amountTemp` | `qTemp` | decimal | Quantity of fuel billed at ambient temperature. |
| `items[].fuelDetail.stateBuyer` | `UFCons` | string | Fuel consumption UF. |
| `items[].fuelDetail.cide.bc` | `qBCProd` | decimal | CIDE calculation basis (quantity sold). |
| `items[].fuelDetail.cide.rate` | `vAliqProd` | decimal | CIDE rate as value per unit (R$). |
| `items[].fuelDetail.cide.cideAmount` | `vCIDE` | decimal | CIDE amount. |
| `items[].fuelDetail.pump.spoutNumber` | `nBico` | int | Nozzle number used in the refueling. |
| `items[].fuelDetail.pump.number` | `nBomba` | int | Number of the pump the nozzle is connected to. |
| `items[].fuelDetail.pump.tankNumber` | `nTanque` | int | Number of the tank the nozzle is connected to. |
| `items[].fuelDetail.pump.beginningAmount` | `vEncIni` | decimal | Encerrante value at the start of the refueling. |
| `items[].fuelDetail.pump.endAmount` | `vEncFin` | decimal | Encerrante value at the end of the refueling. |
| `items[].vehicleDetail.*` | `veicProd/*` (fields J02–J26) | object | New vehicle data (chassis, color, power, etc.). See §6.22. |

### 12.18. Response — Identifiers and Status

The fields below are filled by the **server** and returned in query endpoints. They should not be sent in the request.

| JSON Path | XML Tag | Type | Notes |
|---|---|---|---|
| `id` | (internal) | string | Internal identifier of the resource in NFe.io. |
| `status` | `cStat` | enum | NF-e status. See §11.8.1. |
| `authorization.receiptOn` | `dhRecbto` | datetime | Date/time of processing by SEFAZ. |
| `authorization.accessKey` | `chNFe` | string | NF-e access key (44 digits). |
| `authorization.message` | `xMsg` | string | Complementary message returned by SEFAZ. |
| `authorization.description` | `xMotivo` | string | Description of the status reason (`cStat`). |
| `contingencyDetails.authorizer` | (internal) | enum | Authorizer used in contingency. |
| `contingencyDetails.startedOn` | (internal) | datetime | Date/time the contingency started. |
| `contingencyDetails.reason` | (internal) | string | Justification for entering contingency. |
| `lastEvents.events[]` | (internal) | array | List of linked events (cancellation, CC-e, etc.). |

> **Final notes:**
>
> 1. Paths with `*` indicate the subgroup has multiple fields with the same structure — refer to the specific subgroup documentation (referenced in §4.5 and §11).
> 2. XML tags in parentheses of the form `(in X)` indicate the tag has the same name in multiple groups; the suffix disambiguates the parent group.
> 3. For the complete relation between `cClassTrib` (codClassTrib) and IBS/CBS CST, refer to Appendix G (§10).

---

## Fluxograma do Ciclo de Vida da NF-e

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/fluxograma-ciclo-vida-nfe/index.md

# Fluxograma: Ciclo de Vida da NF-e

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

Este documento ilustra o ciclo de vida completo de uma Nota Fiscal Eletrônica (NF-e), desde sua criação até os possíveis desfechos como autorização, cancelamento, inutilização e os novos eventos da Reforma Tributária.

```mermaid
graph TD
    subgraph "Fase de Emissão"
        A["1. Início: Criação dos Dados da NF-e"] --> B{2. Envio para API};
        B --> C{3. API Valida e Assina o XML};
        C -- Dados Inválidos --> A;
        C -- Dados Válidos --> D["4. Transmissão para SEFAZ"];
        D --> E{5. Processamento SEFAZ};
    end

    subgraph "Resposta da SEFAZ"
        E -- Autorizada --> F["6. Status: Autorizada"];
        E -- Rejeitada --> G["Status: Rejeitada"];
        E -- Denegada --> H["Status: Denegada"];
    end

    subgraph "Ações Pós-Autorização (Tradicionais)"
        F --> K{7. O que fazer agora?};
        K -- Seguir fluxo normal --> K_DANFE["Imprimir DANFE / Enviar XML"];
        K_DANFE --> J[Fim];
        K -- Corrigir erro simples --> P["Emitir Carta de Correção (CC-e)"];
        P --> Q["NF-e Corrigida"];
        K -- Desistir da operação --> M["Solicitar Cancelamento"];
        M --> N{SEFAZ Processa};
        N -- Aprovado --> O["Status: Cancelada"];
        N -- Rejeitado --> F;
    end
    
    subgraph "Correção de Dados"
      G -- Corrigir Dados e Reenviar --> A;
    end

    subgraph "Eventos da Reforma Tributária (Pós-Autorização)"
        F --> EV_RTC{8. Registrar Evento Específico?};
        EV_RTC -- Destinatário --> EV_DEST["Ações do Destinatário"];
        EV_DEST --> EV_CRED["Solicitação de Apropriação<br>de Crédito Presumido"];
        EV_DEST --> EV_IMOB["Imobilização de Item"];
        EV_DEST --> EV_CONSUMO["Destinação para<br>Consumo Pessoal"];
        
        EV_RTC -- Emitente --> EV_EMIT["Ações do Emitente"];
        EV_EMIT --> EV_PAG["Informação de<br>Pagamento Integral"];
        EV_EMIT --> EV_PERDA["Perecimento/Perda/Roubo<br>no Transporte (CIF)"];
        EV_EMIT --> EV_ENTREGA["Atualização da Data<br>de Previsão de Entrega"];

        EV_CRED --> FIM_EV["NF-e com Evento Registrado"];
        EV_IMOB --> FIM_EV;
        EV_CONSUMO --> FIM_EV;
        EV_PAG --> FIM_EV;
        EV_PERDA --> FIM_EV;
        EV_ENTREGA --> FIM_EV;
    end

    subgraph "Fim do Processo (Numeração Perdida)"
      H --> J_FIM["Fim: Numeração Denegada"];
      O --> J_FIM;
    end

    subgraph "Processo de Inutilização"
        R{Houve quebra de sequência<br>na numeração?};
        R -- Sim --> S["Solicitar Inutilização de Numeração"];
        S --> T{SEFAZ Processa Inutilização};
        T --> U["Status: Numeração Inutilizada"];
        R -- Não --> V[Fim];
    end

    style F fill:#d4edda,stroke:#155724
    style O fill:#f8d7da,stroke:#721c24
    style H fill:#f8d7da,stroke:#721c24
    style G fill:#fff3cd,stroke:#856404    
    style U fill:#cce5ff,stroke:#004085
    style FIM_EV fill:#e2e3e5,stroke:#383d41
```

### Explicação do Fluxograma:

1.  **Fase de Emissão:** Começa com a criação dos dados da nota, que são enviados para a API. A API valida, assina o XML e transmite para a SEFAZ. Se houver um erro de validação inicial, o processo retorna para correção.
2.  **Resposta da SEFAZ:** A SEFAZ pode:
    *   **Autorizar:** A NF-e é válida.
    *   **Rejeitar:** A NF-e contém erros de negócio (ex: cálculo de imposto errado). Os dados devem ser corrigidos e a nota reenviada.
    *   **Denegar:** Ocorre quando o emitente ou o destinatário possui irregularidades fiscais. A nota é invalidada e a numeração **não pode ser reutilizada**.
3.  **Ações Pós-Autorização:** Após a autorização, o emitente pode:
    *   **Cancelar a NF-e:** Se a mercadoria ainda não circulou e o prazo legal (geralmente 24 horas) não expirou.
    *   **Emitir uma Carta de Correção (CC-e):** Para corrigir erros simples que não alteram valores, impostos ou as partes envolvidas.
4.  **Processo de Inutilização:** Se, por algum motivo, houver um salto na numeração sequencial das notas (ex: a nota 10 foi emitida e a 12 também, mas a 11 não), o número "pulado" deve ser inutilizado junto à SEFAZ para evitar problemas fiscais.

---

## Mudanças no Layout de Integração da NF-e/NFC-e (v3)

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/mudancas-layout-integracao-nfe-v3/index.md

## Objetivo

Este documento detalha as principais mudanças introduzidas na versão 3 do layout de integração da nota fiscal de produto (NF-e) e consumidor (NFC-e). A atualização incorpora os novos campos exigidos pela Reforma Tributária (IBS, CBS, IS) e adiciona outros grupos e campos para maior detalhamento das operações, alinhando-se aos padrões mais recentes.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

## Público-Alvo

Desenvolvedores e usuários já familiarizados com o layout de integração anterior (v2).

## 1. Principais Mudanças: Novos Grupos de Tributos nos Itens

A mudança mais significativa ocorre dentro de cada item da nota (`items`). A estrutura de tributos (`tax`) foi expandida para acomodar os novos impostos. Enquanto os grupos `icms`, `ipi`, `pis` e `cofins` permanecem para operações no regime antigo, dois novos grupos principais foram adicionados para o novo modelo: `IS` e `IBSCBS`.

### 1.1. Grupo: IS (Imposto Seletivo)

Este grupo é opcional e deve ser preenchido apenas para produtos sujeitos ao Imposto Seletivo.

#### Motivo da Inclusão

O Imposto Seletivo foi criado pela Reforma Tributária para incidir sobre a produção, comercialização ou importação de bens e serviços prejudiciais à saúde ou ao meio ambiente. Este grupo permite a sua correta declaração.

#### Campos-chave

* `situationCode`: Código de Situação Tributária (CST) específico para o IS.

* `basis`: Base de cálculo do imposto.

* `rate`: Alíquota do imposto (em percentual).

* `amount`: Valor final do Imposto Seletivo.


### 1.2. Grupo: IBSCBS (IBS e CBS)

Este é o principal grupo adicionado e será **obrigatório** para as operações sob o novo regime tributário. Ele centraliza as informações do IBS (que unifica ICMS e ISS) e da CBS (que unifica PIS e COFINS).

#### Motivo da Inclusão

Alinhar a emissão de documentos fiscais ao novo modelo de tributação sobre o consumo, detalhando o cálculo e a distribuição dos novos impostos.

#### Campos-chave

- `situationCode`: Código de Situação Tributária unificado para IBS/CBS.
- `classCode`: Código de Classificação Tributária, que define o regime de tributação do item.
- `basis`: Base de cálculo unificada para os novos tributos.

#### Subgrupos de Cálculo (dentro de `IBSCBS`)

- `state` e `municipal`: Detalham o cálculo do IBS, que é um imposto de competência compartilhada. A estrutura é similar para ambos e contém campos como `rate`, `amount`, `deferment` e `reduction`.
- `cbs`: Detalha o cálculo da CBS (tributo federal), com campos como `rate` e `amount`.

#### Outros Subgrupos Opcionais em `IBSCBS`

- `regularTaxation`: Usado para informar a tributação que seria aplicável caso uma condição especial (suspensiva/resolutória) não fosse atendida.
- `governmentPurchase`: Detalha a composição do IBS/CBS em operações de compra por entidades governamentais.
- `monophase`: Contém informações específicas para produtos com tributação monofásica sob o novo regime.
- `creditTransfer`: Para casos de transferência de créditos de IBS/CBS.
- `operationalPresumedCredit`: Detalha créditos presumidos da operação (`basis`, `classificationCode`, `ibs`, `cbs`).
- `creditReversal`: Para informar o estorno de créditos de IBS/CBS.
- `zfmPresumedCredit`: Crédito presumido aplicável à Zona Franca de Manaus (ZFM).

> Além desses, o grupo `IBSCBS` possui os campos `calculationMode` (modo de cálculo) e `donationIndicator` (indicador de doação), e o subgrupo `ibsTotalAmount`.

## 2. Outras Mudanças Relevantes

Além dos novos grupos de tributos, outros campos foram adicionados para dar suporte ao novo sistema.

### 2.1. Novos Campos e Grupos na Raiz do Documento

- `purposeType` (enum): Finalidade da emissão (`Normal`, `Complement`, `Adjustment`, `Devolution`). Para notas de débito/crédito da Reforma Tributária, utilize os campos `debitType`/`creditType`.
- `consumptionCityCode` (integer): Código do município de ocorrência do fato gerador do ICMS (`cMunFG`).
- `ibsConsumptionCityCode` (integer): Código do município onde ocorreu o fato gerador do IBS/CBS, para operações presenciais fora do estabelecimento (`cMunFGIBS`).
- `debitType` / `creditType` (enum): Tipos específicos para NF-e de débito (`tpNFDebito`) ou crédito (`tpNFCredito`), cenários previstos na nova legislação.
- `governmentPurchase`: Grupo de compras governamentais (`gCompraGov`) na raiz do documento.
- `purchaseInformation`: Grupo para informar dados da nota de empenho, pedido de compra e contrato.

> **Documentos e processos referenciados:** o processo judicial/administrativo que ampara a operação é informado em `additionalInformation.referencedProcess`; documentos fiscais referenciados são informados por item em `items[].referencedDFe` (e, quando aplicável, em `additionalInformation.taxDocumentsReference`). Informações do comprador estrangeiro são tratadas em `buyer` (endereço no exterior) e no grupo `export`.

### 2.2. Novos Campos nos Itens (`items`)

- `usedMovableAssetIndicator`: Indica fornecimento de bem móvel usado (`indBemMovelUsado`).
- `itemAmount`: Valor total do item (`vItem`).
- `presumedCredit`: Informações de crédito presumido por item (`gCred`).
- `ibsZfmPresumedCreditClassification`: Classificação para o cálculo do crédito presumido na Zona Franca de Manaus (`tpCredPresIBSZFM`).
- `referencedDFe`: Documento Fiscal Eletrônico referenciado no item.

> O crédito presumido **operacional** (com sua alíquota) é informado dentro de `items[].tax.IBSCBS.operationalPresumedCredit`, e não como um campo de alíquota na raiz do item.

### 2.3. Novos Grupos de Totais (`totals`)

No grupo `totals`, foram adicionados novos objetos para consolidar os valores totais dos novos impostos:
- `isTotals`: Contém o valor total do Imposto Seletivo (`amount`).
- `ibsCbsTotals`: Agrupa os totais de IBS e CBS da nota, incluindo valores de base de cálculo, diferimento, devolução e créditos presumidos.
- `totalInvoiceAmount`: Novo campo para o valor total da NF-e considerando os novos impostos (IBS/CBS/IS).

## 3. Resumo das Principais Diferenças


| Característica                | Layout Antigo (v2)                                       | Novo Layout (v3)                                                                                              |
|-------------------------------|----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| **Estrutura Tributária**      | Grupos separados para ICMS, IPI, PIS, COFINS.            | Mantém os grupos antigos e adiciona os novos grupos **`IS`** e **`IBSCBS`** dentro de cada item.              |
| **Novos Impostos**            | Não aplicável.                                           | Suporte completo ao Imposto Seletivo (`IS`) e à dupla IBS/CBS.                                                |
| **Finalidade da NF-e**        | Não explícito no layout.                                 | Campo **`purposeType`** para indicar a finalidade da emissão.                                                 |
| **Cálculo de Impostos**       | Baseado nas regras individuais de cada tributo antigo.   | Cálculo mais complexo e interligado, com alíquotas efetivas, diferimentos e reduções dentro dos novos grupos. |
| **Totalizadores**             | Grupo `icms` dentro de `totals`.                         | Adiciona os grupos **`isTotals`** e **`ibsCbsTotals`** para os novos impostos.                                |
| **Cenários Específicos**      | Tratados com CFOPs e CSTs.                               | Novos grupos no item (`tax.IBSCBS.governmentPurchase`, `monophase`, `creditTransfer`, etc.) e referências em `additionalInformation.referencedProcess` / `items[].referencedDFe`. |


## Conclusão

A transição para o layout v3 é focada na adaptação ao novo sistema tributário nacional. O principal esforço de integração será mapear as operações para os novos `situationCode` e `classCode`, e preencher corretamente os grupos `IS` e `IBSCBS` quando aplicável. A estrutura para o regime antigo de tributação foi mantida para garantir a coexistência dos dois modelos durante o período de transição.

---

## Guia Rápido: Sua Primeira Emissão de NF-e

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/quickstart-nfe-api/index.md

# Guia Rápido (Quickstart): Sua Primeira Emissão de NF-e

Este guia mostra o passo a passo para emitir sua primeira Nota Fiscal Eletrônica (NF-e) em **ambiente de testes (Homologação)** usando nossa API. O objetivo é realizar uma operação simples de venda para validar a comunicação e entender o fluxo básico.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

## Pré-requisitos

Antes de começar, você vai precisar de:

1.  **API Key:** Sua chave de acesso à API. Você pode obtê-la no painel da sua conta.
2.  **ID da Empresa (`companyId`):** O identificador único da empresa emitente.
3.  **Certificado Digital:** Um certificado A1 válido, já configurado e associado à empresa na nossa plataforma.
4.  **`cURL`:** Uma ferramenta de linha de comando para fazer requisições HTTP. Você pode usar outras ferramentas como Postman ou Insomnia, se preferir.

---

## Passo 1: Entendendo o Ambiente de Testes

Todas as operações neste guia serão realizadas no ambiente de **Homologação (Testes)**. As notas emitidas aqui **não possuem validade jurídica** e servem apenas para validar sua integração.

Para emitir notas fiscais reais, você precisará usar o ambiente de **Produção**.

---

## Passo 2: Preparando o Payload (JSON)

Vamos criar um arquivo chamado `payload.json` com os dados mínimos para uma NF-e de venda simples. Note que usamos "NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO" na descrição para deixar claro que é um teste.

**Arquivo `payload.json`:**
```json
{
  "operationType": "Outgoing",
  "purposeType": "Normal",
  "destination": "Internal_Operation",
  "consumerType": "FinalConsumer",
  "presenceType": "Internet",
  "buyer": {
    "name": "NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL",
    "federalTaxNumber": "01234567890",
    "type": "NaturalPerson",
    "stateTaxNumberIndicator": "NonTaxPayer",
    "address": {
      "street": "Av. Teste",
      "number": "123",
      "district": "Centro",
      "city": {
        "code": "3550308",
        "name": "Sao Paulo"
      },
      "state": "SP",
      "postalCode": "01000000",
      "country": "BRA"
    }
  },
  "items": [
    {
      "code": "P001",
      "description": "PRODUTO TESTE - NOTA FISCAL EMITIDA EM AMBIENTE DE HOMOLOGACAO",
      "ncm": "85171300",
      "cfop": 5102,
      "quantity": 1,
      "unit": "UN",
      "unitAmount": 10.00,
      "totalAmount": 10.00,
      "totalIndicator": true,
      "tax": {
        "icms": {
          "origin": "0",
          "cst": "00",
          "baseTax": 10.00,
          "rate": 18.00,
          "amount": 1.80
        },
        "pis": {
          "cst": "07"
        },
        "cofins": {
          "cst": "07"
        }
      }
    }
  ],
  "payment": [
    {
      "paymentDetail": [
        {
          "method": "InstantPayment",
          "paymentType": "InCash",
          "amount": 10.00
        }
      ]
    }
  ]
}
```

---

## Passo 3: Enviando a Requisição de Emissão

Agora, vamos enviar o `payload.json` para a API usando `cURL`. Substitua `YOUR_COMPANY_ID` e `YOUR_API_KEY` pelos seus dados.

```bash
curl --location --request POST 'https://api.nfse.io/v2/companies/YOUR_COMPANY_ID/productinvoices' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_KEY' \
--data-raw '@payload.json'
```

A API processa as emissões de forma **assíncrona**. Se sua requisição for válida, você receberá uma resposta `HTTP 202 Accepted`, indicando que a nota foi enfileirada para processamento.

**Resposta Esperada (HTTP 202):**
```json
{
  "id": "xxxxxxxxxxxxxxxx"
  ...
}
```
Guarde o `id` retornado. Ele será usado para consultar o status final da nota.

---

## Passo 4: Consultando o Status Final da Nota

Após alguns segundos, consulte o status da nota usando o `id` obtido no passo anterior.

```bash
curl --location --request GET \
  https://api.nfse.io/v2/companies/YOUR_COMPANY_ID/productinvoices/xxxxxxxxxxxxxxxx \
  --header "Authorization: YOUR_API_KEY"
```

### Cenário de Sucesso

Se tudo correu bem, o status da nota será `Issued` (Emitida) e a resposta incluirá a chave de acesso e os links para download do XML e do DANFE (PDF).

**Resposta de Sucesso:**
```json
{
  "id": "xxxxxxxxxxxxxxxx",
  "status": "Issued",
  "authorization": {
    "accessKey": "35240811223344000155550010000001231000001234",
    "message": "Autorizado o uso da NF-e",
    ...
  },
  "xml": { "uri": "https://..." },
  "pdf": { "uri": "https://..." }
}
```

### Cenário de Erro (Rejeição)

Se a SEFAZ rejeitar a nota por alguma regra de negócio (ex: NCM inválido), o status será `Error` e a resposta conterá o código e a mensagem da rejeição.

**Resposta de Erro:**
```json
{
  "id": "xxxxxxxxxxxxxxxx",
  "status": "Error",
  "errors": [
    {
      "code": 778,
      "message": "Rejeicao: Informado NCM inexistente"
    }
  ]
}
```
Neste caso, você deve corrigir o dado no `payload.json` e reenviar a nota (preferencialmente com um novo número para evitar duplicidade).

---

## Próximos Passos

Parabéns! Você emitiu sua primeira NF-e de teste. Agora você pode:

*   **Explorar a Documentação Completa:** Consulte o Guia de Solução de Problemas e a Documentação Funcional para entender todos os campos e cenários.
*   **Testar Cenários da Reforma Tributária:** Adicione o grupo `IBSCBS` aos itens para testar as novas regras.
*   **Configurar Webhooks:** Em vez de consultar o status, configure um webhook para ser notificado automaticamente quando a nota for autorizada ou rejeitada.

---

## Guia de Solução de Problemas e Boas Práticas: Emissão de NF-e/NFC-e (RTC)

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/guia-solucao-problemas-nfe-nfce-rtc/index.md

# Guia de Solução de Problemas e Boas Práticas: Emissão de NF-e/NFC-e (RTC)

Este guia é um recurso completo para desenvolvedores e usuários que estão integrando seus sistemas com nossa API de emissão de NF-e/NFC-e. Ele aborda desde os erros mais comuns até as especificidades da Reforma Tributária (RTC), além de fornecer boas práticas e tabelas de referência para garantir uma integração suave e eficiente.

Se você está começando, recomendamos ler a seção de **Boas Práticas de Integração** antes de iniciar o desenvolvimento.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

---

## 1. Rejeições Comuns (Gerais)

Esta seção cobre os erros mais frequentes que não estão diretamente ligados à Reforma Tributária.

### Rejeição 204: Duplicidade de NF-e
*   **O que significa:** Já existe uma nota com o mesmo número, série e CNPJ do emitente na base da SEFAZ.
*   **Causa Comum:** Tentativa de reenvio de uma nota já autorizada ou em processamento, ou erro no controle de numeração sequencial.
*   **Como Resolver:** Verifique o status da nota original. Se já estiver autorizada, não reenvie. Se precisar emitir uma nova nota, incremente o campo `number` para o próximo valor disponível na sequência da `serie`.

### Rejeição 225: Falha no Schema XML
*   **O que significa:** A estrutura do JSON enviado não corresponde ao layout esperado pela API, resultando em um XML inválido para a SEFAZ.
*   **Causa Comum:** Campos com tipos de dados incorretos (ex: enviar texto onde se espera número), nomes de propriedades errados ou estrutura de objetos aninhados incorreta.
*   **Como Resolver:** Revise o corpo da requisição e compare com a especificação OpenAPI e os exemplos da documentação funcional. Dê atenção especial aos tipos de dados e à hierarquia dos objetos.

### Rejeição 210: IE do destinatário inválida
*   **O que significa:** A Inscrição Estadual (`stateTaxNumber`) informada para o comprador (`buyer`) não é válida para o estado de destino.
*   **Causa Comum:** Erro de digitação, IE inexistente ou IE de outro estado diferente do endereço do comprador.
*   **Como Resolver:** Confirme a Inscrição Estadual correta do destinatário. Se o destinatário for isento ou não contribuinte, ajuste o campo `stateTaxNumberIndicator` para `Exempt` (Isento) ou `NonTaxPayer` (Não Contribuinte) e não envie o campo `stateTaxNumber`.

### Rejeição 539: Duplicidade de NF-e com diferença na Chave de Acesso
*   **O que significa:** Você tentou emitir uma nota com o mesmo `number` e `serie` de uma nota anterior, mas com algum dado diferente (data, valor, cliente), o que gerou uma chave de acesso nova.
*   **Como Resolver:** A numeração é única. Se a nota anterior foi autorizada, você deve usar o próximo número sequencial. Se a nota anterior não serve, ela deve ser cancelada (se estiver no prazo) ou você deve emitir uma nova nota com um novo número.

### Rejeição 610: Total da NF-e difere do somatório dos valores que compõem o valor total
*   **O que significa:** O campo `totals.icms.invoiceAmount` não corresponde à soma dos valores dos itens e demais campos que compõem o total.
*   **Causa Comum:** Erro de cálculo no somatório de `items.totalAmount` mais frete, seguro, despesas acessórias, impostos e subtração de descontos.
*   **Como Resolver:** Recalcule o valor total da nota. A fórmula básica é: `vProd` (soma de `totalAmount` dos itens) - `vDesc` + `vST` + `vFrete` + `vSeg` + `vOutro` + `vIPI` + `vIPIDevol`. Com a RTC, o campo `totalInvoiceAmount` também deve ser validado, incluindo os novos impostos.

### Rejeição 321: NF-e de devolução de mercadoria não possui documento fiscal referenciado
*   **O que significa:** A nota foi emitida com finalidade de Devolução (`purposeType` = `Devolution`), mas não foi informada a chave de acesso da nota original que está sendo devolvida.
*   **Causa Comum:** Esquecimento de preencher o grupo `additionalInformation.taxDocumentsReference`.
*   **Como Resolver:** Adicione o grupo `taxDocumentsReference` dentro de `additionalInformation`, contendo um objeto `documentElectronicInvoice` com a `accessKey` da NF-e que originou a devolução.

### Rejeição 703: Data-Hora de Emissão posterior ao horário de recebimento
*   **O que significa:** A data/hora enviada no campo `operationOn` está no futuro em relação ao relógio da SEFAZ.
*   **Causa:** Relógio do servidor adiantado ou configuração incorreta de Fuso Horário (Timezone).
*   **Solução:** Verifique o relógio do servidor e certifique-se de enviar o offset do fuso horário correto (ex: `-03:00`) no formato da data.

### Rejeição 520: CFOP de Operação com Exterior e UF destinatária diferente de "EX"
*   **O que significa:** Foi usado um CFOP iniciado em 7 (exportação), mas o endereço do destinatário é no Brasil.
*   **Solução:** Se é uma operação de exportação, o estado (`state`) do destinatário deve ser "EX". Se for uma venda interna, corrija o CFOP para um código iniciado em 5 (operação estadual) ou 6 (operação interestadual).

### Rejeição 778: NCM Inexistente
*   **O que significa:** O código NCM informado no produto não existe mais na tabela oficial do governo.
*   **Causa:** A Receita Federal atualiza periodicamente a tabela TIPI, extinguindo códigos antigos e criando novos.
*   **Solução:** Atualize o cadastro do produto com um NCM válido e vigente. Consulte a tabela TIPI mais recente.

### Situação Comum: Confusão de Ambientes (Homologação vs. Produção)
*   **Sintoma:** "A API retornou que a nota foi autorizada, mas não consigo consultá-la no Portal da SEFAZ."
*   **Causa:** A nota foi emitida no ambiente de **Homologação** (Teste), mas a consulta está sendo feita no portal de **Produção**.
*   **Solução:** Notas emitidas em homologação não têm validade jurídica e não aparecem na consulta pública principal. Certifique-se de que está consultando no ambiente correto ou mude a configuração da API para `Production` se desejar emitir uma nota real.

---

## 2. Rejeições da Reforma Tributária (RTC)

Erros específicos do novo modelo de tributação (IBS, CBS, IS).

### Rejeição 1115: IBS/CBS não informado
*   **O que significa:** Para uma operação no novo regime, o grupo `IBSCBS` não foi informado em um ou mais itens.
*   **Causa Comum:** A operação já se enquadra nas regras da RTC, mas o sistema emissor ainda não está enviando o grupo `items.tax.IBSCBS`.
*   **Como Resolver:** Para cada item da nota, adicione o objeto `IBSCBS` dentro de `tax`, preenchendo os campos obrigatórios como `situationCode`, `classCode`, `basis` e os subgrupos `state`, `municipal` e `cbs`.

### Rejeição 1023: Classificação Tributária IBS/CBS informada inexistente
*   **O que significa:** O código informado em `items.tax.IBSCBS.classCode` não existe na tabela oficial `cClassTrib` da SEFAZ.
*   **Causa Comum:** Erro de digitação ou uso de código desatualizado.
*   **Como Resolver:** Consulte o **Apêndice B** deste guia ou a tabela `cClassTrib` mais recente no Portal Nacional da NF-e e utilize um código válido.

### Rejeição 1024: Classificação Tributária IBS e CBS incompatível com o CST informado
*   **O que significa:** A combinação entre `situationCode` (CST) e `classCode` (Classificação Tributária) não é permitida.
*   **Causa Comum:** Um `classCode` que representa isenção foi combinado com um `situationCode` de tributação integral, por exemplo.
*   **Como Resolver:** Verifique o **Apêndice B** deste guia. Ele contém as combinações válidas entre CST e Classificação Tributária. Ajuste um dos dois campos para que a combinação seja válida.

### Rejeição 1104: Valor da base de cálculo do IBS e CBS difere do somatório dos valores que a compõem
*   **O que significa:** O valor informado em `items.tax.IBSCBS.basis` não corresponde à soma dos valores que formam a base de cálculo do item.
*   **Causa Comum:** Erro no cálculo da base, que geralmente é `vProd` - `vDesc` + `vFrete` + `vSeg` + `vOutro` + `vII` + `vIPI`.
*   **Como Resolver:** Recalcule o campo `basis` de cada item, garantindo que ele reflita o somatório correto dos valores que compõem a base de cálculo para os novos impostos.

### Rejeição 1026: Alíquota do IBS Estadual inválida
*   **O que significa:** A alíquota do IBS estadual (`items.tax.IBSCBS.state.rate`) não corresponde à alíquota vigente para o período de emissão.
*   **Causa Comum:** Uso de alíquota incorreta. No período de transição, as alíquotas são fixas (ex: 0,1% para 2025/2026).
*   **Como Resolver:** Ajuste a alíquota para o valor correto definido na legislação da Reforma Tributária para o ano de emissão da nota. Consulte a documentação para os valores vigentes.

### Rejeição 1027: Alíquota do IBS Municipal inválida
*   **O que significa:** A alíquota do IBS municipal (`items.tax.IBSCBS.municipal.rate`) não corresponde à alíquota vigente para o período de emissão.
*   **Causa Comum:** Uso de alíquota incorreta. No período de transição, as alíquotas são fixas (ex: 0,8% para 2025/2026).
*   **Como Resolver:** Ajuste a alíquota para o valor correto definido na legislação da Reforma Tributária para o ano de emissão da nota.

### Rejeição 1001: NF-e com finalidade de débito ou crédito apenas para IBS/CBS
*   **O que significa:** Uma nota de **débito** (com o campo `debitType` preenchido) ou de **crédito** (com o campo `creditType` preenchido) da Reforma Tributária continha grupos de impostos do regime antigo (ICMS, IPI, PIS, COFINS).
    > Observação: a finalidade débito/crédito é indicada pelos campos `debitType` (`tpNFDebito`) / `creditType` (`tpNFCredito`) na raiz do documento — o campo `purposeType` (`finNFe`) aceita apenas `None`, `Normal`, `Complement`, `Adjustment` e `Devolution`.
*   **Causa Comum:** Envio de nota de ajuste de impostos da RTC contendo indevidamente impostos do modelo antigo.
*   **Como Resolver:** Remova completamente os grupos `icms`, `ipi`, `pis`, `cofins` e `icmsDestination` do objeto `tax` de todos os itens da nota. Notas de débito e crédito são exclusivamente para ajustes de IBS e CBS.

### Rejeição 1200: Total da NF-e (RTC) difere do somatório dos valores
*   **O que significa:** O campo `totals.totalInvoiceAmount` não corresponde à soma do valor total do regime antigo (`totals.icms.invoiceAmount`) com os novos impostos (`totals.isTotals.amount` e os totais de `totals.ibsCbsTotals`).
*   **Causa Comum:** Erro de cálculo no valor total final da nota, que deve considerar tanto os tributos do regime antigo (se houver) quanto os do novo regime.
*   **Como Resolver:** Recalcule o valor total da nota. A fórmula é: `vNF` (regime antigo) + `vIS` + `vIBS` + `vCBS`. Garanta que o campo `totalInvoiceAmount` reflita essa soma.

### Rejeição 1116: Modo de cálculo automático do IBS/CBS com preenchimento indevido
*   **O que significa:** O campo `calculationMode` foi definido como `OfficialService`, mas outros campos de tributo do grupo `IBSCBS` (como `basis`, `rate` ou `amount`) também foram preenchidos.
*   **Causa Comum:** Envio de dados desnecessários ao optar pelo cálculo automático.
*   **Como Resolver:** Ao usar `calculationMode: "OfficialService"`, envie apenas os campos `situationCode` e `classCode` dentro do grupo `IBSCBS`. Remova todos os outros campos de valores e alíquotas (`basis`, `state`, `municipal`, `cbs`, etc.), pois eles serão calculados e preenchidos pelo serviço oficial.

**Exemplo Incorreto:**
```json
{
  "creditType": "ValueReduction",
  "items": [
    {
      "tax": {
        "icms": { "origin": "0", "cst": "90" }, // INCORRETO: Grupos do regime antigo não permitidos
        "IBSCBS": { ... }
      }
    }
  ]
}
```

**Exemplo Correto:**
```json
{
  "creditType": "ValueReduction",
  "items": [
    {
      "tax": {
        "IBSCBS": { ... } // CORRETO: Apenas o grupo IBSCBS é informado
      }
    }
  ]
}
```

---

## 3. Guia Passo a Passo: Tratando Erros Comuns

### 3.1. Rejeição 204: Duplicidade de NF-e

A rejeição 204 é uma das mais comuns e indica que a SEFAZ já recebeu uma nota com a mesma chave de acesso ou com o mesmo número e série para o emitente. Siga este fluxo para resolver:

#### Passo 1: Verificar o Status da Nota Original

Antes de tentar emitir uma nova nota ou incrementar a numeração, descubra o status da nota que causou a duplicidade.

1.  **Consulte a nota:** Consulte o webhook encaminhado pelo nosso sistema ou utilize o endpoint de consulta da API para buscar a nota pelo ID.
2.  **Analise o Retorno:**
    *   **Autorizada:** Se a nota já consta como `Issued`, o envio anterior teve sucesso. **Ação:** Atualize o status no seu sistema e capture o XML/DANFE. Não reenvie.
    *   **Cancelada:** A nota existe, mas foi cancelada. **Ação:** O número não pode ser reutilizado. Emita uma nova nota com um novo número (`number`).
    *   **Denegada:** A nota existe e foi denegada por irregularidade fiscal. **Ação:** O número não pode ser reutilizado. Resolva a pendência fiscal e emita uma nova nota com novo número.

#### Passo 2: Decidir sobre a Numeração

Se a consulta não retornar uma nota autorizada, mas a rejeição 204 persistir ao tentar enviar:

*   **Cenário A (Correção):** Se a nota original foi rejeitada (não autorizada), teoricamente o número poderia ser reutilizado. Se a SEFAZ acusa duplicidade, pode haver uma nota autorizada que seu sistema desconhece. Consulte a chave diretamente no Portal da SEFAZ para ter certeza.
*   **Cenário B (Nova Emissão):** Se você precisa emitir com urgência ou não consegue recuperar o status da anterior, a solução é **usar um novo número**.
    *   **Ação:** Incremente o campo `number` para o próximo sequencial disponível e envie a requisição novamente.

#### Passo 3: Inutilizar a Numeração (Se necessário)

Se você optou por pular a numeração (Cenário B) e emitiu a nota com número seguinte (ex: pulou a 100 e emitiu a 101), criou-se uma quebra na sequência.

1.  **Identifique o número pulado:** No exemplo, o número 100.
2.  **Confirme o não-uso:** Certifique-se de que a nota 100 realmente não foi autorizada, cancelada ou denegada.
3.  **Solicite a Inutilização:** Envie uma requisição de inutilização para a API informando:
    *   `serie`: A série da nota.
    *   `beginNumber` e `lastNumber`: O número ou faixa a ser inutilizada (ex: 100).
    *   `reason`: Justificativa (ex: "Ocorrência de erro técnico na emissão").

---

## 4. Procedimentos Fiscais: Cancelamento, Inutilização e Devolução

É comum haver dúvidas sobre qual procedimento adotar para corrigir ou anular uma operação fiscal. Abaixo esclarecemos a diferença entre os três principais mecanismos.

### 4.1. Cancelamento

*   **O que é:** Ato de invalidar uma NF-e **autorizada**, tornando-a sem efeito fiscal.
*   **Quando usar:** Quando a operação comercial não se concretizou (ex: desistência da compra) e, crucialmente, **a mercadoria ainda não circulou**.
*   **Regras Principais:**
    *   Deve ser solicitado dentro do prazo legal, geralmente 24 horas após a autorização.
    *   A mercadoria não pode ter saído do estabelecimento emitente.
    *   O destinatário não pode ter realizado a "Ciência da Emissão".

### 4.2. Inutilização de Numeração

*   **O que é:** Processo de comunicar à SEFAZ que uma faixa de números de NF-e não foi e não será utilizada.
*   **Quando usar:** Quando há um **salto na sequência da numeração** das notas. Exemplo: a nota 100 foi emitida e a próxima a ser emitida é a 102, ficando o número 101 vago.
*   **Regras Principais:**
    *   A inutilização aplica-se apenas a números que não foram usados em nenhuma NF-e (nem mesmo em nota rejeitada ou denegada).
    *   Serve para o Fisco saber que o "buraco" na sequência não é sonegação, mas uma falha técnica ou operacional.

### 4.3. Nota de Devolução

*   **O que é:** Emissão de uma nova NF-e (com `purposeType` = `Devolution`) para anular os efeitos de uma operação anterior.
*   **Quando usar:** Quando a mercadoria circulou e o destinatário a está devolvendo, seja por recusa no recebimento ou devolução após entrega. É a única forma de anular uma operação após a circulação da mercadoria.
*   **Regras Principais:**
    *   É uma nota de entrada (`operationType` = `Incoming`) para o emitente original.
    *   Deve referenciar a chave de acesso da NF-e original que está sendo devolvida.
    *   Os impostos são "espelhados" para anular o débito da nota de saída.

---

## 5. Boas Práticas de Integração e Checklist

Esta seção detalha as recomendações para garantir uma integração mais eficiente, robusta e resiliente com a API.

### 5.1. Boas Práticas Detalhadas

#### Controle de Numeração e Série
*   O controle da numeração sequencial (`number`) para cada série (`serie`) é fundamental para evitar a "Rejeição 204: Duplicidade de NF-e".
*   O controle pode ser realizado de duas formas: pelo cliente, enviando os campos `serie` e `number` na requisição, ou automaticamente pelo nosso sistema.
*   Para o controle automático, o usuário pode definir o valor inicial da série e do número no cadastro da Inscrição Estadual. Se os campos `serie` e `number` não forem enviados na requisição, nosso sistema gerenciará a sequência.
*   **Atenção:** Se o controle for realizado pelo nosso sistema, o número de uma nota fiscal que resultar em erro não será reaproveitado. Nesse caso, o cliente deverá gerenciar a quebra de numeração para inutilizar os números pulados posteriormente.
*   O sistema cliente deve sempre verificar a ocorrência de pulos na sequência numérica. Caso um número não seja utilizado, é necessário solicitar a sua inutilização para evitar problemas com o Fisco.
*   Sempre que for necessário alterar ou iniciar o uso de uma nova série fiscal, é mandatório que o cadastro da Inscrição Estadual do emitente seja previamente atualizado no sistema.

#### Validação de Dados Pré-Envio
*   **Reduza chamadas desnecessárias:** Antes de enviar os dados para a API, realize o máximo de validações possível no seu sistema.
*   **Valide dados cadastrais e de endereço:** Use APIs de consulta para verificar CNPJs, CPFs, Inscrições Estaduais e CEPs, evitando rejeições por dados incorretos.
*   **Garanta que campos obrigatórios estão preenchidos** de acordo com a operação (ex: CFOP, NCM).

#### Tratamento de Erros e Rejeições
*   Utilize os logs detalhados de requisições (JSON enviado) e respostas (JSON recebido) para análise e depuração em caso de erros.
*   Para erros de rede ou instabilidade momentânea da SEFAZ (ex: timeouts, erros 5xx), nosso sistema já possui um mecanismo de retentativa com *exponential backoff*, não sendo necessário implementar essa lógica no cliente.

#### Gerenciamento do Ciclo de Vida da NF-e
*   Utilize **webhooks** para receber notificações automáticas sobre o status final da nota ('Emitida', 'Erro'), em vez de realizar consultas periódicas.
*   Nosso sistema armazena o XML de cada NF-e autorizada por no mínimo 5 anos. O download do XML e DANFE está disponível a qualquer momento.
*   Esteja preparado para a **contingência**. O modo de emissão em contingência pode ser configurado em nossa plataforma para gerenciamento automático, permitindo que sua operação continue sem interrupções.

#### Performance e Eficiência
*   Mantenha uma cópia local e atualizada das tabelas de referência (NCM, CEST, CFOP, cClassTrib, etc.).
*   Envie apenas os campos e grupos necessários para a sua operação, omitindo grupos opcionais não aplicáveis para um payload mais limpo e validação mais rápida.

#### Segurança
*   Trate as chaves de acesso à API (API Keys) e os certificados digitais como informações altamente sensíveis. Não as exponha no código-fonte do lado do cliente (frontend) e armazene-as de forma segura no seu backend.

### 5.2. Checklist Rápido de Integração

- [ ] **Validação Pré-Envio:** Implementar validações no seu sistema para campos obrigatórios (CFOP, NCM, etc.) antes de enviar a requisição para a API.
- [ ] **Consulta de Cadastros:** Utilizar APIs de consulta para validar dados de CNPJ, CPF, Inscrição Estadual e endereços (via CEP).
- [ ] **Cache de Tabelas Auxiliares:** Manter uma cópia local e atualizada das tabelas de referência (NCM, CEST, CFOP, e as novas tabelas da RTC como `cClassTrib`).
- [ ] **Controle de Numeração:** Definir a estratégia de controle de numeração sequencial (`number`) e série (`serie`) para evitar a Rejeição 204.
- [ ] **Tratamento de "Pulos" na Numeração:** Implementar um processo para solicitar a **inutilização** de números que não foram utilizados.
- [ ] **Gerenciamento de Status com Webhooks:** Configurar um endpoint (webhook) para receber notificações de status em tempo real (`Emitida`, `Erro`, `Cancelada`).
- [ ] **Estratégia de Contingência:** Configurar o modo de contingência automático na plataforma ou preparar o sistema para gerenciá-lo.
- [ ] **Payloads Otimizados:** Enviar na requisição apenas os campos e grupos necessários para a operação.
- [ ] **Proteção de Credenciais:** Armazenar as chaves de acesso da API e os certificados digitais de forma segura no backend.
- [ ] **Implementar Fluxos de Correção:** Preparar o sistema para os eventos pós-emissão, como **Cancelamento**, **Carta de Correção (CC-e)** e emissão de **Nota de Devolução**.

---

## 6. Apêndices

### 6.1. Apêndice A: Mapeamento de Grupos (JSON para XML)

Para desenvolvedores familiarizados com o layout XML da SEFAZ, a tabela abaixo resume o mapeamento dos principais grupos do JSON da API.

| Grupo na API (JSON) | Grupo no XML (SEFAZ) | Descrição |
|---|---|---|
| (raiz do objeto) | `ide` | Identificação da NF-e |
| `issuer` | `emit` | Dados do Emitente |
| `buyer` | `dest` | Dados do Destinatário |
| `delivery` | `entrega` | Local de Entrega |
| `withdrawal` | `retirada` | Local de Retirada |
| `items` | `det` | Detalhamento de Produtos e Serviços (Itens) |
| `items.tax` | `imposto` | Tributos incidentes no item |
| `items.tax.icms` | `ICMS` | Grupo de ICMS |
| `items.tax.ipi` | `IPI` | Grupo de IPI |
| `items.tax.pis` | `PIS` | Grupo de PIS |
| `items.tax.cofins` | `COFINS` | Grupo de COFINS |
| `items.tax.IS` | `IS` | Grupo do Imposto Seletivo (RTC) |
| `items.tax.IBSCBS` | `IBSCBS` | Grupo de IBS e CBS (RTC) |
| `totals` | `total` | Grupo de Valores Totais |
| `totals.icms` | `ICMSTot` | Totais de ICMS |
| `totals.issqn` | `ISSQNtot` | Totais de ISSQN |
| `totals.isTotals` | `ISTot` | Totais do Imposto Seletivo (RTC) |
| `totals.ibsCbsTotals` | `IBSCBSTot` | Totais de IBS e CBS (RTC) |
| `transport` | `transp` | Dados do Transporte |
| `billing` | `cobr` | Dados da Cobrança (Fatura e Duplicatas) |
| `payment` | `pag` | Dados do Pagamento |
| `additionalInformation` | `infAdic` | Informações Adicionais |
| `purchaseInformation` | `compra` | Informações de Compra (empenho, pedido) |
| `export` | `exporta` | Informações de Exportação |
| `transactionIntermediate` | `infIntermed` | Informações do Intermediador da Transação |

### 6.2. Apêndice B: Tabela de Referência - CST e Classificação Tributária (IBS/CBS)

A combinação correta do Código de Situação Tributária (`situationCode`) e do Código de Classificação Tributária (`classCode`) é essencial para a validação da NF-e no novo regime.

| Código CST | Descrição CST | Código Class. | Descrição da Classificação Tributária |
| :--- | :--- | :--- | :--- |
| 000 | Tributação integral | 000001 | Situações tributadas integralmente pelo IBS e CBS. |
| 000 | Tributação integral | 000002 | Exploração de via, observado o art. 11 da Lei Complementar nº 214, de 2025. |
| 010 | Tributação com alíquotas uniformes - operações do FGTS | 010001 | Operações do FGTS não realizadas pela Caixa Econômica Federal... |
| 011 | Tributação com alíquotas uniformes reduzidas em 60% | 011001 | Planos de assistência funerária... |
| 011 | Tributação com alíquotas uniformes reduzidas em 60% | 011002 | Planos de assistência à saúde... |
| 200 | Alíquota zero | 200001 | Aquisições de máquinas, aparelhos, instrumentos... em zonas de processamento de exportação. |
| 200 | Alíquota zero | 200003 | Vendas de produtos da Cesta Básica Nacional de Alimentos. |
| 200 | Alíquota reduzida em 60% | 200028 | Fornecimento dos serviços de educação... |
| 200 | Alíquota reduzida em 30% | 200052 | Prestação de serviços de profissões intelectuais (advogados, arquitetos, etc.). |
| 400 | Isenção | 400001 | Fornecimento de serviços de transporte público coletivo... |
| 410 | Imunidade e não incidência | 410002 | Transferências entre estabelecimentos do mesmo contribuinte. |
| 410 | Imunidade e não incidência | 410004 | Exportações de bens e serviços. |
| 510 | Diferimento | 510001 | Operações com energia elétrica... |
| 550 | Suspensão | 550001 | Exportações de bens materiais. |
| 620 | Tributação monofásica | 620001 | Tributação monofásica sobre combustíveis. |
| 800 | Transferência de crédito | 800001 | Fusão, cisão ou incorporação. |

*Nota: A tabela acima é um extrato simplificado. Para a lista completa e detalhada, consulte a documentação oficial no Portal Nacional da NF-e.*

---

## Adequação ao Emissor em Ambiente Nacional de NFS-e

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/adequacao-ao-emissor-ambiente-nacional-nfse/index.md

## Municípios aderentes ao Ambiente Nacional da Reforma Tributária

Seu município (ex.: Rio de Janeiro, Curitiba, entre outros) **aderiu ao Emissor Nacional de NFS-e?** Siga o passo a passo abaixo para garantir que sua empresa esteja em conformidade.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

## 1º passo — Ativar o Emissor Nacional na Inscrição Municipal da empresa

Para direcionar a emissão de NFS-e ao **Ambiente Nacional**, é necessário ativar a opção **Emissor Nacional** no cadastro da Inscrição Municipal (IM) da empresa emissora na plataforma da NFE.io.

**Caminho:**

Conta → Empresas → Selecionar empresa → Inscrição Municipal → marcar a opção **"Emitir via Emissor Nacional de NFS-e"** → Salvar

Após salvar, a empresa fica vinculada ao **Ambiente Nacional** e pronta para emitir conforme as novas regras da Reforma Tributária. Esse vínculo passa a ser exibido como **"Emissor Nacional de NFS-e: Ativo"** no card de Inscrição Municipal da empresa.

:::note Integração via API
Internamente, o checkbox grava o valor **530000** no campo `regionalTaxNumber` do objeto da Inscrição Municipal — esse é o sinalizador esperado pelo Ambiente Nacional. Se você atualiza a IM diretamente via API, envie `regionalTaxNumber: 530000` para ativar e `0` para desativar.
:::

## 2º passo — Ajustar Série e Número do RPS

O Ambiente Nacional **não aceita letras** nos campos de Série e Número do RPS.

* **Série:** deve ser numérica (ex.: 1\)  
* **Número do RPS:** deve ser numérico (ex.: 1\)

Caso utilize séries alfanuméricas atualmente, será necessário alterá-las antes da emissão.

## 3º passo — Atualizar o Código de Serviço (como esperado pelo ambiente nacional) e NBS

No Ambiente Nacional, os **códigos de serviço seguem um novo padrão**:

* Mínimo de **6 dígitos**  
* O município pode **adicionar mais 3 dígitos**  
* Cada município pode ter variações específicas

### Como obter o código correto via ambiente nacional, em que o município já configurou os códigos para emissão de nota fiscal

Recomendamos que você:

1. Acesse o **Ambiente Nacional**  
2. Realize a **emissão de uma NFS-e de teste**  
3. Utilize o código de serviço retornado para sua operação

### Como acessar o Ambiente Nacional

Antes de emitir, é obrigatório realizar o **cadastro do CNPJ emissor no Portal Nacional**.

Siga os guias oficiais da NFE.io:

* [https://nfe.io/docs/duvidas-frequentes/credenciamento-emissor-nacional/](https://nfe.io/docs/duvidas-frequentes/credenciamento-emissor-nacional/)  
* [https://nfe.io/docs/duvidas-frequentes/como-cadastrar-uma-empresa-no-emissor-nacional/](https://nfe.io/docs/duvidas-frequentes/como-cadastrar-uma-empresa-no-emissor-nacional/)

### Emissão via API

Se a emissão for feita via API, será necessário enviar:

* **NBS (Nomenclatura Brasileira de Serviços)**  
* **Novo código de serviço do Ambiente Nacional**

**Tabela de referência oficial:**

[Tabela de Correlação – LC 116, NBS, Indicador de Operação e Classificação Tributária](https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-correlacao-nbs-lc116/)

## 4º passo — Informações adicionais (Lucro Real ou Presumido)

Se sua empresa é do **Lucro Real ou Lucro Presumido**, e portanto se enquadra nas novas regras da Reforma Tributária, será necessário informar **dados adicionais**:

* **Código de Operação** ([conforme tabela de referência](https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-correlacao-nbs-lc116/))  
* **Classificação Tributária**

### Envio via API

Consulte a documentação técnica:

* Envio de dados para emissão de NFS-e (RPS/DPS) – Documentação NFE.io

**Emissão via meio de pagamento / integração**

Caso utilize um intermediador (ex.: **Vindi**), será necessário:

* Ajustar a **camada de integração**  
* Garantir que os novos campos estejam sendo enviados corretamente pela interface

**Emissão via planilha \- Baixar novo template da planilha básica ou planilha avançada que já utiliza, que já terá informações adicionais para Reforma Tributária.**

![](https://nfe.io/docs/static/docs/adequacao-ao-emissor-ambiente-nacional-nfse.jpg)

Como Emitir Nota Fiscal de Serviço em Lote \- NFE.io | Docs | NFE.io : Documentação

## 5º passo — Emitir a NFS-e via plataforma NFE.io

Após todas as configurações:

* Realize a emissão da nota fiscal com as **novas informações exigidas**  
* Valide se a nota foi autorizada corretamente 

### Em caso de rejeição

Caso ocorra qualquer rejeição na emissão:

1. Entre em contato com o **suporte da NFE.io**  
2. Envie:  
   * Evidências do erro (mensagens de rejeição)  
   * Se possível, uma **NFS-e emitida diretamente no Ambiente Nacional**, para comparação e validação dos dados

---

## Layout RTC - Documentação Funcional

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/index.md

# Documentação Funcional do Layout de Emissão de NFS-e (RTC)

## Introdução

Esta documentação descreve de forma funcional todos os campos disponíveis para a emissão de uma Nota Fiscal de Serviço Eletrônica (NFS-e) através da nossa API. O layout RTC foi desenvolvido para ser compatível com o **padrão nacional da NFS-e** e já incorpora as mudanças da **Reforma Tributária**, como os novos tributos IBS e CBS.

O objetivo é fornecer um guia claro para usuários e desenvolvedores sobre a finalidade de cada campo, as regras de preenchimento e o impacto de cada informação na nota fiscal gerada.

---

## Estrutura Geral da Requisição

A emissão de uma nota é realizada através de uma requisição JSON que contém todas as informações necessárias. Os campos podem ser divididos nos seguintes grupos principais:

1.  **Informações Gerais da Nota**: Dados essenciais que identificam a operação.
2.  **Participantes**: Informações sobre o tomador, intermediário e outros envolvidos.
3.  **Valores e Tributos (Legado)**: Campos relacionados ao cálculo de impostos do sistema antigo (ISS, PIS, COFINS, etc.).
4.  **Grupo da Reforma Tributária (`ibsCbs`)**: O grupo central e obrigatório para os novos tributos (IBS e CBS).
5.  **Regras de Validação e Comportamentos**: Detalhes sobre as validações aplicadas aos dados.
5.  **Grupos para Cenários Específicos**: Estruturas opcionais para detalhar operações como construção civil, locação, comércio exterior, etc.

A seguir, detalhamos cada campo.

---

## 1. Informações Gerais da Nota

Estes são os campos que definem os dados básicos do serviço prestado.

`externalId` (string, opcional)
> Identificador único definido pelo seu sistema para associar a nota fiscal a um registro interno (ex: ID do pedido, contrato). Facilita a conciliação e a busca.

`cityServiceCode` (string, **obrigatório**)
> Código do serviço conforme a tabela do município do prestador.

`federalServiceCode` (string, **obrigatório**)
> Código do serviço conforme a Lista de Serviços da Lei Complementar 116. É um código federal padronizado.

`description` (string, **obrigatório**)
> Descrição detalhada dos serviços prestados. Este texto aparecerá no corpo da nota fiscal. Máximo de 2000 caracteres.

`servicesAmount` (número, **obrigatório**)
> Valor total dos serviços prestados, antes de descontos ou impostos.

`nbsCode` (string, **opcional**)
> Código da **Nomenclatura Brasileira de Serviços (NBS)**. Esta é uma nova classificação obrigatória para padronização nacional dos serviços.

`cnaeCode` (string, opcional)
> Código CNAE (Classificação Nacional de Atividades Econômicas) relacionado ao serviço, se exigido pelo município.

`ncmCode` (string, opcional)
> Código NCM (Nomenclatura Comum do Mercosul), utilizado quando o serviço está atrelado a um bem ou mercadoria.

`paidAmount` (número, opcional)
> Valor total efetivamente pago pelo serviço.

`issuedOn` (data-hora, opcional)
> Data e hora de emissão da nota no formato `YYYY-MM-DDTHH:MM:SS-03:00`. Se não for informado, o sistema usará a data e hora do processamento.

`accrualOn` (data, opcional)
> Data de competência do serviço (quando o serviço foi efetivamente prestado) no formato `AAAA-MM-DD`. Se não for informada, será considerada a data de `issuedOn`.

`rpsSerialNumber` (string, opcional)
> Série do Recibo Provisório de Serviços (RPS). Se não informado, o sistema usará o valor padrão cadastrado para a empresa.

`rpsNumber` (número, opcional)
> Número do RPS. Se não informado, o sistema gerará o próximo número da sequência automática.

`location` (objeto, opcional)
> Endereço onde o serviço foi prestado. É crucial para determinar o município onde o ISSQN é devido. Contém os campos do `addressDefinition`.

`additionalInformation` (string, opcional)
> **Informações Adicionais: Simples vs. Estruturado (`additionalInformation` vs. `additionalInformationGroup`)**
>
> O layout oferece duas formas de enviar informações complementares, visando flexibilidade e completude.
>
> *   **`additionalInformation` (Texto Simples):**
>     Um campo de `string` para adicionar qualquer observação em formato de texto livre. É ideal para anotações rápidas e genéricas.
>
> *   **`additionalInformationGroup` (Objeto Estruturado):**
>     Um objeto que organiza dados complementares em campos específicos, como `responsibilityDocumentIdentifier` (ART/RRT), `order` (Pedido), etc. É a forma mais completa e padronizada de enviar esses dados.
>
> **Comportamento e Relação:**
> Para facilitar a integração, o campo `additionalInformation` funciona como um atalho. Se você preencher apenas este campo, seu conteúdo será automaticamente copiado para `additionalInformationGroup.otherInformation`. Isso garante que todas as informações adicionais fiquem consolidadas na estrutura mais completa, mantendo a consistência interna dos dados.
>
> **Recomendação:**
> *   Para observações simples, use `additionalInformation`.
> *   Para dados específicos como ART, Pedido, etc., use os campos dedicados dentro de `additionalInformationGroup`.

`additionalInformationGroup` (objeto, opcional)
> Grupo estruturado para organizar dados complementares em campos específicos, como `responsibilityDocumentIdentifier` (ART/RRT), `order` (Pedido), etc. É a forma mais completa e padronizada de enviar esses dados.

`isEarlyInstallmentPayment` (booleano, opcional)
> Indique `true` se a nota se refere a um pagamento de parcela antecipada, ou seja, um pagamento realizado antes da prestação do serviço.

---

## 2. Participantes da Operação

Define as pessoas ou empresas envolvidas na prestação de serviço.

`borrower` (objeto, **obrigatório**)
> Representa o **Tomador do Serviço** (cliente). Utiliza a estrutura `partyDefinition`.

`intermediary` (objeto, opcional)
> Representa o **Intermediário do Serviço** (ex: um marketplace, agência). Utiliza a estrutura `partyDefinition`.

`recipient` (objeto, opcional)
> Representa o **Destinatário Final do Serviço**, quando ele é diferente do tomador. Utiliza a estrutura `partyDefinition`. Este campo só deve ser informado quando `ibsCbs.destinationIndicator` estiver definido como `DifferentFromBuyer`. Nessa situação, o preenchimento de `recipient` passa a ser **obrigatório**.

### Estrutura `partyDefinition` (Tomador, Intermediário, Destinatário)

Esta estrutura é usada para identificar qualquer participante.

* `type` (string, opcional): Tipo de pessoa (`NaturalPerson` para Física, `LegalEntity` para Jurídica).
* `name` (string, **obrigatório**): Nome completo ou Razão Social.
* `federalTaxNumber` (número, **obrigatório**): CPF ou CNPJ.
* `municipalTaxNumber` (string, opcional): Inscrição Municipal.
* `stateTaxNumber` (string, opcional): Inscrição Estadual.
* `taxRegime` (string, opcional): Regime tributário do participante (ex: `SimplesNacional`, `LucroReal`).
* `caepf` (string, opcional): Cadastro de Atividade Econômica da Pessoa Física.
* `phoneNumber` (string, opcional): Telefone de contato.
* `email` (string, opcional): E-mail para contato e envio da nota.
* `address` (objeto, **obrigatório**): Endereço do participante, utilizando a estrutura `addressDefinition`.

### Estrutura `addressDefinition` (Endereço)

* `country` (string, **obrigatório**): Sigla do país (padrão: `BRA`).
* `postalCode` (string, **obrigatório**): CEP.
* `street` (string, **obrigatório**): Logradouro.
* `number` (string, **obrigatório**): Número.
* `additionalInformation` (string, opcional): Complemento.
* `district` (string, **obrigatório**): Bairro.
* `city` (objeto, **obrigatório**): Contém `code` (código IBGE) e `name` (nome da cidade, para exterior).
* `state` (string, **obrigatório**): Sigla do estado (UF).

---

## 3. Valores e Tributos (Sistema Legado - ISSQN e Retenções)

Estes campos são usados para o cálculo do ISSQN e das retenções federais (IR, PIS, COFINS, CSLL, INSS), que coexistem com o novo modelo durante a transição.

`taxationType` (string, opcional)
> **Tipo de Tributação (taxationType)**
>
> O campo `taxationType` define o regime de tributação do **ISSQN (Imposto Sobre Serviços de Qualquer Natureza)**. Ele é um campo legado, mantido para compatibilidade com os layouts municipais existentes e continua sendo fundamental para o cálculo do ISS durante o período de transição da Reforma Tributária.
>
> **Finalidade Principal (Contexto do ISSQN):**
> Este campo indica ao sistema como o ISSQN deve ser tratado na operação. Com base no valor selecionado (ex: `WithinCity`, `OutsideCity`, `Immune`), o sistema determina se o ISSQN é devido, se a tributação ocorrerá dentro ou fora do município, ou se a operação é isenta ou imune a este imposto específico.
>
> **Relação com a Reforma Tributária (IBS/CBS):**
> É crucial entender que o `taxationType` **não se aplica aos novos tributos (IBS e CBS)**. Para a apuração do IBS e da CBS, as regras de tributação e o local de incidência são definidos exclusivamente pelos campos dentro do grupo `ibsCbs`, como o `operationIndicator` e o `classCode`.
>
> **Em resumo:**
> *   **`taxationType`**: Governa o comportamento do **ISSQN**.
> *   **`ibsCbs`**: Governa o comportamento do **IBS e da CBS**.
>
> Durante o período de transição, ambos os sistemas de tributação coexistirão, tornando o preenchimento correto de todos esses campos essencial para a conformidade fiscal da nota.

`immunityType` (string, opcional)
> **Tipo de Imunidade (immunityType)**
>
> O campo `immunityType` é condicional e deve ser utilizado **exclusivamente quando o campo `taxationType` for definido como `Immune`**.
>
> Sua finalidade é especificar a base legal que fundamenta a imunidade tributária do **ISSQN (Imposto Sobre Serviços de Qualquer Natureza)** para a operação. Cada valor disponível no campo corresponde a uma alínea específica do Artigo 150, Inciso VI, da Constituição Federal, que trata das limitações ao poder de tributar.
>
> **Relação com a Reforma Tributária (IBS/CBS):**
> É fundamental destacar que este campo se refere **apenas à imunidade do ISSQN**. As regras de imunidade para os novos tributos (IBS e CBS) são tratadas de forma separada, dentro do grupo `ibsCbs`, através de códigos específicos no campo `classCode` (ex: códigos iniciados com `41xxxx`).
>
> A correta especificação do `immunityType` é essencial para validar a justificativa legal da não incidência do ISSQN na nota fiscal, garantindo a conformidade perante as autoridades fiscais municipais.

`retentionType` (string, opcional)
> **Tipo de Retenção do ISSQN (retentionType)**
>
> O campo `retentionType` determina quem é o responsável pelo recolhimento do **ISSQN (Imposto Sobre Serviços de Qualquer Natureza)**. Ele define a transferência da responsabilidade de pagamento do imposto do prestador para outra parte na operação.
>
> **Finalidade e Opções:**
> *   **`NotWithheld` (Não Retido):** Esta é a situação padrão. O **prestador** do serviço é o responsável por calcular e recolher o ISSQN devido.
> *   **`WithheldByBuyer` (Retido pelo Tomador):** A responsabilidade pelo recolhimento do ISSQN é transferida para o **tomador** (cliente) do serviço.
> *   **`WithheldByIntermediary` (Retido pelo Intermediário):** Em operações com um intermediário (como marketplaces), a responsabilidade pelo recolhimento do ISSQN é transferida para este **intermediário**.
>
> **Comportamento Automático vs. Manual:**
> Se um valor for explicitamente enviado na requisição, ele será utilizado. Se o campo não for enviado, o sistema aplicará as regras de cálculo automáticas (baseadas na legislação, local da prestação e cadastro dos envolvidos) para definir se a retenção é aplicável e quem é o responsável.
>
> **Relação com a Reforma Tributária (IBS/CBS):**
> Assim como outros campos legados, o `retentionType` aplica-se **exclusivamente ao ISSQN**. As regras de retenção para os novos tributos (IBS e CBS) serão definidas por legislação complementar específica e tratadas em outros campos do layout.

`issRate` (número, opcional)
> Alíquota do ISSQN (pAliq, tpAliquota). Se não informada, o sistema usa a alíquota cadastrada para o serviço.

`issTaxAmount` (número, opcional)
> Valor do ISSQN. Se não informado, é calculado automaticamente.

`issAmountWithheld` (número, opcional)
> Valor do ISSQN retido (vISSQN). Calculado automaticamente se houver retenção.

`deductionsAmount` (número, opcional)
> **Deduções: Simples vs. Estruturado (`deductionsAmount` vs. `deduction`)**
>
> O layout oferece duas formas de registrar deduções da base de cálculo do ISSQN, visando flexibilidade e conformidade com os diferentes padrões (municipal legado vs. nacional).
>
> *   **`deductionsAmount` (Valor Simples):**
>     Um campo numérico para informar o **valor total consolidado** das deduções (vDR, tpValor). É uma abordagem direta, compatível com layouts mais antigos que não exigem o detalhamento dos documentos que comprovam a dedução.
>
> *   **`deduction` (Grupo Estruturado):**
>     Um objeto complexo que permite justificar cada dedução com base em documentos fiscais, alinhando-se ao **padrão da NFS-e Nacional**. Ele detalha a origem de cada valor (chave do documento, tipo, valor, fornecedor).
>
> **Relação e Recomendação:**
> A coexistência dos campos oferece compatibilidade. `deductionsAmount` é uma opção simplificada, enquanto o grupo `deduction` é a forma mais completa e recomendada para garantir rastreabilidade e conformidade fiscal com o padrão nacional. O sistema de emissão priorizará os dados detalhados do grupo `deduction`, se fornecidos.
>
> **Recomendação de Uso:**
> *   Use `deductionsAmount` para integrações simples ou quando não há detalhamento dos documentos.
> *   Use o grupo `deduction` sempre que a informação detalhada dos documentos estiver disponível para garantir a máxima conformidade.

`deduction` (objeto, opcional)
> **Finalidade**: Justificar deduções da base de cálculo do **ISSQN** com base em documentos fiscais (ex: subempreitadas). É a versão estruturada e mais completa do campo `deductionsAmount`.

`discountUnconditionedAmount` (número, opcional)
> Valor do desconto incondicionado (que não depende de evento futuro) (vDescIncond, tpValor).

`discountConditionedAmount` (número, opcional)
> Valor do desconto condicionado (ex: desconto por pagamento antecipado) (vDescCond, tpValor).

### Campos de Retenções Federais e Valores Destacados

Para cada tributo federal (IR, PIS, COFINS, CSLL, INSS), existem campos para o valor retido (`...AmountWithheld`).

*   `irAmountWithheld` (vRetIRRF, tpValor)
*   `pisAmountWithheld` (vPis, tpValor)
*   `cofinsAmountWithheld` (vCofins, tpValor)
*   `csllAmountWithheld` (vRetCSLL, tpValor)
*   `inssAmountWithheld` (vRetCP, tpValor)

**Nota:** Os campos de alíquota (`pisRate`, `cofinsRate` e `csllRate`) são utilizados apenas para cálculos automáticos internos do sistema quando os valores retidos não são informados.

Além dos campos de retenção, existem campos específicos para informar os valores de PIS e COFINS quando **não há retenção**, mas o valor deve ser destacado na nota:

*   `pisAmount`: Valor do PIS (sem retenção) (vPis, tpValor).
*   `cofinsAmount`: Valor do COFINS (sem retenção) (vCofins, tpValor).
*   `csllAmount`: Valor do CSLL (sem retenção) (vCSLL, tpValor).
*   `pisCofinsBaseTax`: Base de cálculo para o Pis e Cofins (vBCPisCofins, tpValor).
*   `ipiRate`: SP - Alíquota IPI (pAliqIPI, tpAliquota).
*   `ipiAmount`: SP - Valor IPI (vIPI, tpValor).

`othersAmountWithheld` (número, opcional)
> Valor de outras retenções não especificadas (vOutrasRet, tpValor).

---

## 4. Grupo Principal: `ibsCbs` (Reforma Tributária)

Este é o grupo **obrigatório** mais importante do novo layout. Ele centraliza todas as informações para o cálculo dos novos tributos: **IBS** (Imposto sobre Bens e Serviços) e **CBS** (Contribuição sobre Bens e Serviços).

`purpose` (string, opcional, padrão: `regular`)
> **Finalidade**: Indica a finalidade da emissão da NFS-e. Atualmente, o único valor suportado é para uma emissão regular.
>
>| Valor     | Descrição      |
>|:----------|:---------------|
>| `regular` | Emissão Regular |

`personalUse` (booleano, opcional)
> **Finalidade**: Indique `true` se o serviço for destinado a uso ou consumo pessoal do tomador. Este campo é relevante para regras específicas da Reforma Tributária, como o *cashback*.

`operationIndicator` (string, **obrigatório**)
> **Finalidade**: Código que define a natureza da operação e determina o **local de incidência** (onde o imposto é devido) para o IBS e a CBS. A escolha correta é fundamental para o recolhimento do imposto no município/estado correto.
> **Exemplo**: Um serviço de construção (`020201`) terá o imposto devido no local do imóvel. Um serviço de consultoria (`100301`) terá o imposto devido no domicílio do adquirente.
> * A lista completa de valores possíveis está disponível na **Tabela de `operationIndicator`** no Apêndice.

`operationType` (string, opcional)
> **Finalidade**: Tipo de Operação com Entes Governamentais ou outros serviços sobre bens imóveis.
>
> * `SupplyFirstPayLater`: Fornecimento com pagamento posterior.
> * `PayForPastSupply`: Recebimento do pagamento com fornecimento já realizado.
> * `SupplyForPastPay`: Fornecimento com pagamento já realizado.
> * `PayFirstSupplyLater`: Recebimento do pagamento com fornecimento posterior.
> * `SupplyPayTogether`: Fornecimento e recebimento do pagamento concomitantes.

`situationCode` (string, opcional)
> **Finalidade**: Código de Situação Tributária (CST) do IBS/CBS. Este campo é opcional, pois se não for preenchido, o sistema o derivará automaticamente dos 3 primeiros dígitos do `classCode`.
> **Exemplo**: Se o `classCode` for `200028` (serviços de educação com alíquota reduzida), o `situationCode` derivado será `200` (Alíquota zero ou com redução de alíquota).
> * A lista completa de valores possíveis está disponível na **Tabela de `situationCode`** no Apêndice.

`classCode` (string, **obrigatório**)
> **Finalidade**: Código de Classificação Tributária que define o tratamento fiscal da operação para IBS/CBS (ex: tributação integral, alíquota zero, isenção, etc.). Este código determina as alíquotas e regimes aplicáveis.
> **Exemplo**: `000001` para tributação integral, `410004` para exportação (imunidade).
> * A lista completa de valores possíveis está disponível na **Tabela de `classCode`** no Apêndice.

`isDonation` (booleano, opcional)
> Indique `true` se a operação for uma doação.

`destinationIndicator` (string, opcional)
> Indica se o destinatário do serviço é o mesmo que o tomador (`SameAsBuyer`) ou diferente (`DifferentFromBuyer`). Se for diferente, o grupo `recipient` se torna obrigatório.

`basis` (número, opcional)
> Base de cálculo para o IBS/CBS, antes de quaisquer reduções.

`reimbursedResuppliedAmount` (número, opcional)
> Valor de reembolsos ou repasses que não compõem a base de cálculo. Para detalhar a origem, use o subgrupo `thirdPartyReimbursements`.

`ibscbsDeductionReductionAmount` (número, opcional)
> Valor total de deduções e reduções específicas da base de cálculo do IBS/CBS, aplicáveis a operações como locação de imóveis e serviços médicos, conforme legislação.

### 4.1. Subgrupo `ibs` (Opcional)

Detalha o cálculo do **IBS**, o imposto subnacional (estadual e municipal).

`totalAmount` (número): Valor total do IBS na operação.
`state` (objeto): Detalhes da parcela **estadual** do IBS.
  - `rate`: Alíquota de referência do estado.
  - `effectiveRate`: Alíquota efetiva após reduções.
  - `amount`: Valor do IBS devido ao estado.
`municipal` (objeto): Detalhes da parcela **municipal** do IBS, com estrutura similar à estadual.

### 4.2. Subgrupo `cbs` (Opcional)

Detalha o cálculo da **CBS**, o tributo federal.

`rate` (número): Alíquota de referência da CBS.
`effectiveRate` (número): Alíquota efetiva após reduções.
`amount` (número): Valor da CBS devida.

### 4.3. Outros Subgrupos Opcionais no `ibsCbs`

Estes grupos tratam de cenários fiscais mais complexos.

* `relatedDocs` (objeto): Permite referenciar até 99 chaves de outras NFS-e.
* `leasedMovableAssets` (array): Para detalhar bens móveis em uma operação de locação.
* `regularTaxation` (objeto): Para informar o cálculo hipotético do imposto no regime padrão.
* `presumedCredits` (objeto): Para detalhar créditos presumidos de IBS e CBS.
* `governmentPurchase` (objeto): Para especificar detalhes de operações com entidades governamentais.
* `creditTransfer` (objeto): Para casos de transferência de créditos de IBS/CBS.
* `thirdPartyReimbursements` (objeto): Para declarar e justificar valores de reembolso que não compõem a base de cálculo, com detalhamento dos documentos de origem.
> O detalhamento completo de cada Subgrupo está disponível no **Apêndice**.

---

## Regras de Validação e Comportamentos

Para garantir a integridade e a conformidade das notas fiscais emitidas, diversas validações são aplicadas. Abaixo estão as principais regras de negócio e comportamentos do sistema.

### Validações Gerais

*   **Geração da NFS-e**: Uma vez gerada, uma NFS-e não pode ser alterada. As únicas ações permitidas são o **cancelamento** ou a **substituição**, mantendo-se o vínculo entre a nota original e a nova.
*   **Identificação do Serviço**: O serviço prestado deve ser identificado em conformidade com a **Lista de Serviços anexa à Lei Complementar n°116/03**.
*   **Identificação do Prestador**: A identificação do prestador de serviços é realizada através do CNPJ ou CPF. O uso da Inscrição Municipal é opcional.
*   **Identificação do Tomador**: A informação do CNPJ do tomador do serviço é obrigatória para pessoas jurídicas, exceto quando se tratar de um tomador no exterior.
*   **Competência**: A competência da NFS-e corresponde à data da ocorrência do fato gerador e deve ser informada pelo contribuinte.

### Validações do ISSQN

*   **Código do Município de Incidência**: Este campo deve ser informado quando a exigibilidade do ISS for "Exigível", "Isenção", "Imunidade", "Exigibilidade Suspensa por Decisão Judicial" ou "Exigibilidade Suspensa por Processo Administrativo". Nos demais casos, se informado, será considerado um erro.
*   **Número do Processo**: Deve ser informado quando a exigibilidade do ISS for "Suspensa por Decisão Judicial" ou "Suspensa por Processo Administrativo".
*   **Base de Cálculo**: A base de cálculo da NFS-e é o `Valor Total de Serviços`, subtraindo-se o `Valor de Deduções` previstas em lei e o `Desconto Incondicionado`.
*   **Valor do ISS Devido**: O cálculo é realizado com base na exigibilidade do ISS, no código do município de incidência, na opção pelo Simples Nacional, no regime especial de tributação e se o ISS foi retido. O valor será sempre calculado, exceto em cenários específicos, como para microempresas municipais ou quando a tributação ocorre fora do município (nesse caso, o prestador deve indicar a alíquota e o valor).
*   **Alíquota do ISS**: A alíquota é definida pela legislação municipal. Se for informada pelo contribuinte fora das exceções permitidas (como tributação fora do município ou retenção para optantes do Simples Nacional), será considerada um erro.

### Processos Síncronos e Assíncronos

**Nota Importante sobre a Comunicação com a Nossa API:**
Do ponto de vista do sistema do cliente, **toda comunicação com a nossa API é assíncrona**. Isso significa que, ao enviar uma requisição (como uma emissão de nota), o cliente recebe uma confirmação imediata de que a solicitação foi aceita e enfileirada. O resultado final do processamento (sucesso ou erro) será informado posteriormente através de um **webhook**.

A distinção abaixo entre "síncrono" e "assíncrono" descreve o **mecanismo interno** de comunicação entre o **nosso sistema e o sistema da prefeitura**, e não a comunicação entre o cliente e a nossa API.

---

*   **Serviços Síncronos**:
    *   **O que são (Comunicação API ↔ Prefeitura)**: Solicitações que nosso sistema envia para a prefeitura e que são processadas imediatamente, com o resultado retornado na mesma conexão.
    *   **Exemplos**: `Geração de NFS-e`, `Cancelamento de NFS-e`, `Substituição de NFS-e`, `Consulta de Lote de RPS`, `Consulta de NFS-e por RPS`, `Consulta de NFS-e – Serviços Prestados` e `Consulta de NFS-e por Faixa`.
    *   **Ideal para**: Operações que exigem uma resposta rápida e processamento de baixo volume.

*   **Serviços Assíncronos**:
    *   **O que são (Comunicação API ↔ Prefeitura)**: Solicitações que nosso sistema envia para a prefeitura e que envolvem um processamento mais intenso. O resultado é obtido em uma segunda conexão, através de uma consulta posterior que nosso sistema realiza automaticamente.
    *   **Exemplo**: `Recepção e Processamento de Lote de RPS`.
    *   **Ideal para**: Processamento de grandes volumes de informação, como o envio de lotes de RPS, para não sobrecarregar o sistema e garantir a estabilidade.

### XML do Evento de Cancelamento (Ambiente Nacional)

No **Ambiente Nacional (ADN)**, o cancelamento de uma NFS-e é registrado como o **evento `e110001`**, que possui um XML próprio (distinto do XML de emissão da nota). Após o cancelamento, esse XML fica disponível para download:

`GET /v1/companies/{company_id}/serviceinvoices/{id}/cancellation-xml`

*   **Disponibilidade**: apenas para notas emitidas no **Ambiente Nacional** e que estejam efetivamente **canceladas** (`status = Cancelled`). Provedores de layout municipal/ABRASF **não** geram evento de cancelamento próprio e, portanto, o endpoint retorna **`404`**.
*   **Priorização**: quando existem o XML enviado (request do `e110001`) e o XML do **evento autorizado** retornado pelo ADN (`procEventoNFSe`), o **retorno autorizado é priorizado** na resposta.
*   **Diferença em relação ao `/xml`**: o endpoint `/{id}/xml` retorna o XML de **emissão** da nota; o `/{id}/cancellation-xml` retorna o XML do **evento de cancelamento**. São documentos distintos e armazenados separadamente.

> **Observação**: assim como nos demais downloads, a resposta é um redirecionamento para uma URL assinada e temporária do arquivo.

### Testes de Integração (Ambiente de Homologação)

Para facilitar a integração, é importante entender a distinção entre os ambientes e as responsabilidades:

*   **Responsabilidade do Cliente**: A única configuração necessária é definir se a empresa está operando em ambiente de **Produção** ou **Homologação** no cadastro da empresa em nosso sistema.

*   **Responsabilidade da Nossa API**: Com base no ambiente configurado, nosso sistema gerencia internamente o fluxo de testes. O controle sobre o envio para o ambiente real da prefeitura ou para um *mockup* interno de validação é feito por nós.

Dentro do ambiente de **Homologação**, nosso sistema oferece dois comportamentos distintos, gerenciados internamente pela nossa API:

*   **Fluxo de Validação (Mockup)**: Para validar a estrutura da requisição sem gerar um documento fiscal, a API realiza todas as validações de regras de negócio e da estrutura dos dados. Se a requisição for válida, o sistema retorna sucesso; caso contrário, retorna uma lista de erros. Neste fluxo, a nota **não é emitida** e não é enviada à prefeitura, o que é ideal para testes de integração iniciais.

*   **Fluxo de Emissão em Homologação**: Para testar o fluxo completo de ponta a ponta, a requisição é enviada para o ambiente de homologação da prefeitura. Neste caso, a nota fiscal é efetivamente emitida no ambiente de testes do município.

*   **Importante**: Contribuintes optantes pelo Simples Nacional/MEI, em um primeiro momento, não poderão realizar testes utilizando as novas tags da Reforma Tributária.

---

## 5. Detalhamento de Valores Cobrados

* `serviceAmountDetails` (objeto, opcional)
> **Finalidade**: Fornecer uma decomposição clara dos valores cobrados, separando o valor original do serviço de multas e juros. Garante maior precisão na base de cálculo.
>
> * `initialChargedAmount` (número): Valor original do serviço, antes de acréscimos.
> * `finalChargedAmount` (número): Valor final total, incluindo impostos, multas e juros.
> * `fineAmount` (número): Valor específico de multas.
> * `interestAmount` (número): Valor específico de juros.

---

## 6. Grupos para Cenários Específicos (Opcionais)

Estes grupos foram adicionados para acomodar casos de uso específicos previstos no padrão nacional.

`ReferenceSubstitution` (objeto)
> Usado quando uma nota está sendo emitida para **substituir** uma nota anterior. Requer o `id` (chave da nota a ser substituída) e o `reason` (motivo).

`lease` (objeto)
> Para serviços de locação, sublocação ou direito de passagem de infraestrutura (ferrovias, postes, cabos, etc.).

`construction` (objeto)
> Para serviços de construção civil. Exige a identificação da obra (CNO/CEI), o código CIB ou o endereço do local da obra. (obra)

`realEstate` (objeto)
> Para operações relacionadas a bens imóveis, exceto obras. (imovel)

> **Diferença entre `construction` e `realEstate`**:
> A estrutura `realEstate` não possui o campo `workId` (identificação da obra), pois se refere a operações em imóveis que não são obras de construção civil.
> *   Use **`construction`** para serviços que envolvem efetivamente uma **obra de construção civil** (ex: construção, reforma, demolição).
> *   Use **`realEstate`** para outras operações relacionadas a imóveis que **não são obras** (ex: administração de imóveis, limpeza, vigilância, quando o local da prestação é o imóvel).

`foreignTrade` (objeto)
> Para operações de importação/exportação de serviços. Detalha o modo de prestação, moeda, mecanismos de fomento, etc.

`benefit` (objeto)
> Para aplicar um benefício fiscal municipal que reduz a base de cálculo do **ISSQN**.

`suspension` (objeto)
> Para indicar que a exigibilidade do **ISSQN** está suspensa por processo judicial ou administrativo.

`activityEvent` (objeto)
> Para detalhar informações sobre eventos (shows, feiras, congressos), como nome, datas e local.

`approximateTax` (objeto, opcional)
> **Finalidade**: Atender à "Lei De Olho no Imposto", informando a carga tributária aproximada.
>
> **Estrutura Simplificada vs. Detalhada (`approximateTax` vs. `approximateTotals`)**
>
> *   **`approximateTax` (Estrutura Simplificada):**
>     Permite informar a carga tributária de forma consolidada, através de um percentual (`totalRate`) ou valor monetário (`totalAmount`) totais. É ideal para sistemas que não possuem a decomposição dos tributos por esfera governamental.
>
> *   **`approximateTotals` (Estrutura Detalhada):**
>     Permite um detalhamento completo, separando os valores por esfera: `federal`, `state` e `municipal`. É a escolha ideal quando o sistema possui essa informação decomposta, oferecendo maior transparência.
>
> **Importante:** Se nenhum dos grupos for preenchido, o sistema realizará o cálculo automático e preencherá o grupo `approximateTax`.

`approximateTotals` (objeto, opcional)
> Versão detalhada para atender à "Lei De Olho no Imposto", permitindo informar a carga tributária aproximada com valores separados por esfera (federal, estadual, municipal).
> O detalhamento completo está disponível no **Apêndice**.

---

## Boas Práticas de Integração

Para garantir uma integração eficiente, segura e escalável com a nossa API, recomendamos que os desenvolvedores sigam as seguintes boas práticas:

### 1. Utilize Chaves de Idempotência

Para evitar a emissão de notas fiscais em duplicidade devido a falhas de rede ou timeouts, sempre utilize o campo `externalId`.

*   **Como funciona**: Envie um identificador único gerado pelo seu sistema (como um UUID ou o ID do seu registro interno) no campo `externalId`. Se recebermos uma nova requisição com um `externalId` que já foi processado com sucesso, em vez de criarmos uma nova nota, retornaremos os dados da nota fiscal original.
*   **Benefício**: Garante que uma mesma operação não seja processada mais de uma vez, trazendo segurança e consistência para a sua aplicação.

### 2. Deixe os Cálculos Complexos para a API

Nosso sistema é projetado para simplificar a sua vida. Campos como `rpsNumber`, `issTaxAmount`, `irAmountWithheld`, e os valores dentro dos grupos `ibs` e `cbs` podem ser calculados automaticamente.

*   **Recomendação**: Envie apenas as informações essenciais da operação (valores, serviços, participantes) e deixe que a API realize os cálculos de impostos e preencha os campos automáticos.
*   **Benefício**: Reduz a complexidade do seu lado, garante que os cálculos estarão sempre em conformidade com a legislação vigente e diminui a chance de erros por arredondamento ou regras de negócio incorretas.

### 3. Prefira Campos Estruturados

O layout oferece campos simples (como `deductionsAmount`) e grupos estruturados (como `deduction`).

*   **Recomendação**: Sempre que possível, utilize os grupos estruturados (`deduction`, `additionalInformationGroup`, `approximateTotals`). Eles permitem um detalhamento maior das informações, alinhado ao padrão nacional.
*   **Benefício**: Garante maior conformidade fiscal, melhora a rastreabilidade dos dados e prepara sua integração para futuras exigências do fisco sem a necessidade de grandes refatorações.

### 4. Entenda o Grupo `ibsCbs`

O grupo `ibsCbs` é o coração da Reforma Tributária. O preenchimento incorreto dos seus campos pode levar a apurações de impostos erradas.

*   **Foco principal**: Dedique atenção especial aos campos `operationIndicator` (que define o local de incidência do imposto) e `classCode` (que define o regime e as alíquotas).
*   **Recomendação**: Não fixe esses valores no código. Crie um mecanismo (ou utilize um motor fiscal) que determine os códigos corretos com base na natureza do serviço, no local da prestação e nos regimes tributários dos participantes.

### 5. Utilize o Ambiente de Homologação de Forma Inteligente

O ambiente de homologação é seu aliado para garantir que tudo funcione antes de ir para produção.

*   **Validação sem Emissão**: Utilize o fluxo de emissão no ambiente de testes para validar a estrutura e as regras da sua requisição sem gerar um documento fiscal. A API retornará sucesso se estiver tudo certo ou uma lista de erros a corrigir.
*   **Benefício**: Permite realizar testes completos de validação de forma rápida e segura, sem poluir o ambiente de homologação com notas fiscais de teste.

### 6. Tratamento de Erros e Rejeições

A API retornará mensagens de erro claras e estruturadas.

*   **Recomendação**: Configure seu sistema para registrar (logar) a resposta completa da API em caso de erro. Isso inclui códigos de erro, mensagens e o campo específico que causou a falha.

*   **Benefício**: Facilita enormemente a depuração e a resolução de problemas, tanto para sua equipe de desenvolvimento quanto para o nosso time de suporte.

*   **Logs Detalhados:** Nosso sistema mantém um histórico completo e detalhado de todas as requisições (JSON enviado) e respostas (JSON recebido) por um longo período. Em caso de erros, esses logs são uma ferramenta poderosa para análise e depuração, facilitando a identificação da causa raiz do problema e agilizando o suporte técnico.

*   **Mecanismo de Retentativa:** Para erros de rede ou instabilidade momentânea da SEFAZ (ex: timeouts, erros 5xx), nosso sistema já possui um mecanismo de retentativa com *exponential backoff*. Isso evita que o cliente precise se preocupar em implementar essa lógica, pois gerenciamos as tentativas de reenvio automaticamente em caso de falhas temporárias.

### 7. Validação de Dados Pré-Envio

*   **Reduza Chamadas Desnecessárias:** Antes de enviar os dados para a API, realize o máximo de validações possível no seu sistema. Isso inclui:
    *   **Validação de Dados Cadastrais e Endereço:** Para garantir a validade dos dados cadastrais do emitente e do destinatário, recomendamos o uso de nossas APIs de consulta. Elas permitem verificar se CNPJs e CPFs são válidos, se a Inscrição Estadual está ativa e vinculada ao CNPJ correto, e também consultar endereços a partir do CEP. A utilização dessas APIs evita rejeições por dados cadastrais ou de endereço incorretos.
    *   Garantir que campos obrigatórios estão preenchidos de acordo com a operação (ex: CFOP, NCM).

---

## Conclusão

A transição para o layout RTC é impulsionada pela Reforma Tributária. O principal esforço de implementação está no preenchimento correto do grupo `ibsCbs`, que exige um entendimento das novas regras fiscais. Os demais campos garantem a compatibilidade com os sistemas legados e acomodam uma vasta gama de cenários de negócio, alinhando a emissão da NFS-e ao padrão nacional.

Recomendamos revisar cuidadosamente esta documentação e os exemplos na especificação OpenAPI para garantir uma integração bem-sucedida.

---

## Apêndice: Tabelas de Referência

### Tabela de Referência - Indicador da Operação (indOp)

Para detalhes sobre os códigos, consulte o documento Apêndice: [Tabela de Referência - Indicador da Operação (indOp)](https://nfe.io/docs/documentacao/reforma-tributaria/tabelas-de-referencia/doc-ref-operation-indicator-table/)

### Tabela de Referência - CST e Classificação Tributária (IBS/CBS)

Para detalhes sobre os códigos, consulte o documento Apêndice: [Tabela de Referência - CST e Classificação Tributária (IBS/CBS)](https://nfe.io/docs/documentacao/reforma-tributaria/Tabelas%20de%20referencia/doc-ref-classcode-situationcode-table-pt-br/)

### Tabela de Correlação: LC 116, NBS, Indicador de Operação e Classificação Tributária

Para detalhes sobre a correlação sugerida entre o Item da Lista de Serviço (LC 116), o código NBS, o Indicador de Operação (indOp) e a Classificação Tributária (cClassTrib) para diversos serviços, consulte o documento Apêndice: [Tabela de Correlação: LC 116, NBS, Indicador de Operação e Classificação Tributária](https://nfe.io/docs/documentacao/reforma-tributaria/Tabelas%20de%20referencia/lc116-nbs-correlation-table-pt-br/)

### Tabela de Referência - Comércio Exterior (`foreignTrade`)

Para detalhes sobre os códigos, consulte o documento Apêndice: [Tabela de Referência - Comércio Exterior (`foreignTrade`)](https://nfe.io/docs/documentacao/reforma-tributaria/Tabelas%20de%20referencia/doc_ref_foreign_trade_table_pt-br/)

### Tabela de `destinationIndicator`

| Valor                  | Descrição                                       |
|:-----------------------|:------------------------------------------------|
| `SameAsBuyer`          | O destinatário é o mesmo que o tomador (padrão). |
| `DifferentFromBuyer`   | O destinatário é diferente do tomador.          |

## Apêndice: Estruturas de Dados Detalhadas

### `deduction`

Permite detalhar os documentos que justificam uma dedução/redução da base de cálculo do **ISSQN** (`vDedRed`, tipo `TCInfoDedRed` do layout nacional). Deve ser enviada **apenas uma** das três alternativas: `rate`, `amount` ou `documents`. O envio de mais de uma dessas propriedades no mesmo objeto `deduction` não é suportado.

**Propriedades Principais:**
- `rate` (número): Percentual padrão de dedução/redução (`pDR`, %).
- `amount` (número): Valor monetário padrão de dedução/redução (`vDR`, R$).
- `documents` (array de objetos, até 1000 itens): Lista de documentos que comprovam a dedução. Cada item segue o tipo `TCDocDedRed` do XSD nacional.

**Campos de cada `document`:**

Cada item exige **pelo menos um** identificador do documento de origem — `nfseKey`, `nfeKey`, `municipalNfse`, `fiscalDocumentNumber` ou `nonFiscalDocumentNumber`. Quando mais de um é enviado, a precedência aplicada é nessa ordem.

- `nfseKey` (string, 50 dígitos): Chave de acesso de uma NFS-e padrão nacional (`chNFSe`).
- `nfeKey` (string, 44 dígitos): Chave de acesso de uma NF-e produto (`chNFe`).
- `municipalNfse` (objeto): Referência a uma NFS-e municipal no padrão legado (`NFSeMun`). Os três campos internos são obrigatórios.
  - `cityCode` (string): Código IBGE do município emissor (`cMunNFSeMun`).
  - `number` (string): Número da NFS-e municipal (`nNFSeMun`).
  - `verificationCode` (string): Código de verificação da NFS-e municipal (`cVerifNFSeMun`).
- `fiscalDocumentNumber` (string): Identificador de outro documento fiscal não eletrônico (`nDocFisc`).
- `nonFiscalDocumentNumber` (string): Identificador de um documento não fiscal, ex: nota de débito interna (`nDoc`).
- `deductionType` (string, obrigatório): Tipo da dedução/redução (`tpDedRed`). Valores aceitos (nome — código — descrição):
  - `FoodAndBeverages` (1) — Alimentação e bebidas/frigobar
  - `Materials` (2) — Materiais
  - `ConsortiumPassThrough` (5) — Repasse consorciado
  - `HealthPlanPassThrough` (6) — Repasse plano de saúde
  - `Services` (7) — Serviços
  - `Subcontracting` (8) — Subempreitada de mão de obra
  - `Other` (99) — Outras deduções (exige `otherDeductionDescription`)
- `otherDeductionDescription` (string): Descrição obrigatória quando `deductionType = "Other"` (`xDescOutDed`).
- `issueDate` (data, obrigatório): Data de emissão do documento de origem (`dtEmiDoc`, `AAAA-MM-DD`).
- `deductibleTotal` (número, obrigatório): Valor total dedutível/redutível no documento de origem (`vDedutivelRedutivel`, R$).
- `usedAmount` (número, obrigatório): Valor efetivamente utilizado como dedução nesta NFS-e (`vDeducaoReducao`, R$). Deve ser ≤ `deductibleTotal`.
- `supplier` (objeto, opcional): Fornecedor do documento (`fornec`), usando a estrutura `partyDefinition`.

### `thirdPartyReimbursements` (dentro de `ibsCbs`)

Permite detalhar os documentos que justificam um reembolso/repasse que não integra a base de cálculo do IBS/CBS.

**Propriedades Principais:**
- `documents` (array de objetos): Lista de documentos comprobatórios.
  - `nfseKey` (string): Chave de uma NFS-e padrão nacional.
  - `nfeKey` (string): Chave de uma NF-e.
  - `cteKey` (string): Chave de um CT-e.
  - `otherNationalDfe` (objeto): Para outros Documentos Fiscais Eletrônicos (DF-e) do repositório nacional.
    - `dfeKey` (string): Chave do DF-e.
    - `dfeTypeText` (string): Descrição do tipo de DF-e.
  - `otherFiscalDoc` (objeto): Para documentos fiscais que não estão no repositório nacional.
    - `issuerCityCode` (string): Código IBGE do município emissor.
    - `fiscalDocNumber` (string): Número do documento.
    - `fiscalDocDescription` (string): Descrição do documento.
  - `otherDoc` (objeto): Para documentos não fiscais.
    - `docNumber` (string): Número do documento.
    - `docDescription` (string): Descrição do documento.
  - `supplier` (objeto): Identificação do fornecedor (estrutura `partyDefinition`).
  - `issueDate` (data): Data de emissão do documento (`AAAA-MM-DD`).
  - `accrualOn` (data): Data de competência do documento (`AAAA-MM-DD`).
  - `reimbursementType` (string): Motivo do reembolso (ex: `TravelAgencySupplierPassThrough`, `OtherReimbursement`).
  - `reimbursementTypeText` (string): Descrição obrigatória se `reimbursementType` for `OtherReimbursement`.
  - `amount` (número): Valor do reembolso/repasse.

### `governmentPurchase` (dentro de `ibsCbs`)

Detalha a composição dos tributos em operações com o governo.

**Propriedades Principais:**
- `entityType` (string): Tipo de entidade governamental (`Union`, `State`, `Municipality`).
- `ibs` (objeto): Detalhes do IBS para a compra governamental.
  - `totalAmount` (número): Valor total do IBS.
  - `state` (objeto): Parcela estadual.
    - `rate` (número): Alíquota do estado.
    - `amount` (número): Valor do IBS estadual.
  - `municipal` (objeto): Parcela municipal.
    - `rate` (número): Alíquota do município.
    - `amount` (número): Valor do IBS municipal.
- `cbs` (objeto): Detalhes da CBS para a compra governamental.
  - `rate` (número): Alíquota da CBS.
  - `amount` (número): Valor da CBS.

### `regularTaxation` (dentro de `ibsCbs`)

Informa como seria a tributação se a operação não estivesse em um regime especial (suspensivo, etc.).

**Propriedades Principais:**
- `situationCode` (string): Código de Situação Tributária (CST) que seria aplicado.
- `classCode` (string): Código de Classificação Tributária que seria aplicado.
- `ibs` (objeto): Detalhes do IBS no regime regular.
  - `totalAmount` (número): Valor total do IBS.
  - `state` (objeto): Parcela estadual.
    - `effectiveRate` (número): Alíquota efetiva do estado.
    - `amount` (número): Valor do IBS estadual.
  - `municipal` (objeto): Parcela municipal.
    - `effectiveRate` (número): Alíquota efetiva do município.
    - `amount` (número): Valor do IBS municipal.
- `cbs` (objeto): Detalhes da CBS no regime regular.
  - `effectiveRate` (número): Alíquota efetiva da CBS.
  - `amount` (número): Valor da CBS.

### `presumedCredits` (dentro de `ibsCbs`)

Detalha os créditos presumidos de IBS e CBS que o adquirente pode ter direito.

**Propriedades Principais:**
- `ibs` (objeto):
  - `code` (string): Código do crédito presumido.
  - `rate` (número): Percentual do crédito.
  - `amount` (número): Valor do crédito.
  - `conditionalAmount` (número): Valor do crédito sob condição suspensiva.
- `cbs` (objeto): Estrutura similar para a CBS.
  - `code` (string): Código do crédito presumido.
  - `rate` (número): Percentual do crédito.
  - `amount` (número): Valor do crédito.
  - `conditionalAmount` (número): Valor do crédito sob condição suspensiva.

### `creditTransfer` (dentro de `ibsCbs`)

Usado em operações específicas que envolvem a transferência de saldo credor de IBS/CBS.

**Propriedades Principais:**
- `ibsAmount` (número): Valor do crédito de IBS a ser transferido.
- `cbsAmount` (número): Valor do crédito de CBS a ser transferido.

### `foreignTrade`

Detalha operações de comércio exterior de serviços.

**Propriedades Principais:**
- `serviceMode` (string): Modo de prestação (ex: `CrossBorder`, `ConsumptionInBrazil`).
- `relationShip` (string): Vínculo entre as partes (ex: `HeadOffice`, `Branch`).
- `currency` (string): Moeda da transação (tabela de moedas do Banco Central do Brasil) (ex: `220`).
- `serviceAmountInCurrency` (número): Valor do serviço na moeda estrangeira.
- `supportMechanismProvider` (string): Mecanismo de fomento usado pelo prestador.
- `supportMechanismReceiver` (string): Mecanismo de fomento usado pelo tomador.
- `temporaryGoods` (string): Vínculo com movimentação temporária de bens.
- `importDeclaration` (string): Número da Declaração de Importação (DI).
- `exportRegistration` (string): Número do Registro de Exportação (RE).
- `mdicDelivery` (booleano): Indicador de envio da NFS-e ao MDIC.

### `lease`

Para serviços de locação de infraestrutura.

**Propriedades Principais:**
- `category` (string): Categoria (`lease`, `sublease`, etc.).
- `objectType` (string): Objeto (`Railway`, `Poles`, `Cables`, etc.).
- `totalLength` (número): Comprimento total (para ferrovias, cabos, etc.).
- `polesCount` (número): Número total de postes.

### `construction`

Para serviços de construção civil.

**Propriedades Principais:**
- `workId` (objeto): Identificação da obra via CNO ou CEI.
  - `scheme` (string): Tipo de cadastro (`bra.cno` ou `bra.cei`).
  - `value` (string): Número da obra no cadastro.
- `cibCode` (string): Código do Cadastro Imobiliário Brasileiro.
- `siteAddress` (objeto): Endereço da obra.
- `encapsulationNumber` (string, 1–12 dígitos): Número do encapsulamento da obra (`NumeroEncapsulamento`). Atualmente utilizado apenas pelo serializador do município de São Paulo (Paulistana); emitido como `<NumeroEncapsulamento>` nos blocos `<tpRPS>` e `<tpNFe>` do XML. Zeros à esquerda são preservados.

### `realEstate`

Para operações relacionadas a bens imóveis, exceto obras.

**Propriedades Principais:**
- `propertyFiscalRegistration` (string): Inscrição imobiliária fiscal.
- `cibCode` (string): Código do Cadastro Imobiliário Brasileiro.
- `siteAddress` (objeto): Endereço do imóvel.

### `ReferenceSubstitution`

Para substituir uma nota fiscal emitida anteriormente.

**Propriedades Principais:**
- `id` (string): Chave da NFS-e que será substituída.
- `reason` (string): Motivo da substituição (ex: `RejectionBuyerOrIntermediary`).
- `reasonText` (string): Descrição do motivo, se `reason` for `other`.

### `benefit`

Para aplicar benefícios fiscais municipais ao ISSQN.

**Propriedades Principais:**
- `id` (string): Identificador do benefício.
- `amount` ou `rate`: Valor ou percentual da redução na base de cálculo.

### `suspension`

Para suspender a exigibilidade do ISSQN.

**Propriedades Principais:**
- `reason` (string): Motivo (`Judicial` ou `Administrative`).
- `processNumber` (string): Número do processo.

### `activityEvent`

Para serviços relacionados a eventos.

**Propriedades Principais:**
- `name` (string): Nome do evento.
- `beginOn` / `endOn` (data-hora): Início e fim do evento.
- `Code` (string): Código da atividade do evento (se aplicável).
- `address` (objeto): Endereço do evento.

### `approximateTotals`

Estrutura detalhada para informar a carga tributária aproximada.

**Propriedades Principais:**
- `federal` (objeto): Tributos federais (`rate`, `amount`).
- `state` (objeto): Tributos estaduais (`rate`, `amount`).
- `municipal` (objeto): Tributos municipais (`rate`, `amount`).
- `rate` (número): Valor percentual total aproximado dos tributos.
- `amount` (número): Valor monetário total aproximado dos tributos.

---

## Mudanças Funcionais no Layout de Integração da Nota Fiscal de Serviço (v4)

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/mudancas-layout-integracao-nfse-v4/index.md

# Mudanças Funcionais no Layout de Integração da Nota Fiscal de Serviço (antigo vs. novo)

:::warning
Recomendamos revisar cuidadosamente a documentação de cada campo no novo JSON Schema e os exemplos fornecidos para garantir uma transição tranquila.
:::

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

## Objetivo

Este documento detalha todas as mudanças funcionais introduzidas na versão "novo" do layout de integração da nota fiscal de serviço. A atualização incorpora primariamente os novos campos exigidos pela Reforma Tributária (IBS/CBS), mas também adiciona outros campos para melhorar a completude dos dados e alinhar-se aos novos padrões nacionais.

## Público-Alvo

Desenvolvedores e usuários já familiarizados com o layout de integração anterior (antigo).

## Visão Geral das Mudanças

Para alinhamento com a nova legislação tributária e os padrões nacionais, diversos campos e grupos foram adicionados. Embora a maioria dos campos existentes permaneça inalterada, a inclusão de novos campos obrigatórios é crucial para a emissão de notas no modelo novo.

As principais mudanças são a adição dos grupos `ibsCbs` e `serviceAmountDetails`. No entanto, outros campos individuais e grupos opcionais mais complexos também foram introduzidos.

## 1. Grupo Principal: ibsCbs (Reforma Tributária)

Este é o principal grupo adicionado ao layout e é **obrigatório**. Ele centraliza todas as informações relacionadas aos novos tributos, IBS (Imposto sobre Bens e Serviços) e CBS (Contribuição sobre Bens e Serviços), que substituirão o ICMS, ISS, PIS e COFINS.

O objetivo deste grupo é fornecer ao fisco todos os detalhes necessários para o cálculo, apuração e fiscalização dos novos impostos, permitindo a correta distribuição da arrecadação entre os níveis federal, estadual e municipal.

:::note ISSQN x IBS/CBS

Os campos `taxationType` e `immunityType` na raiz da requisição referem-se **exclusivamente ao ISSQN** (período de transição). A tributação do **IBS e da CBS** é governada apenas pelos campos do grupo `ibsCbs` — principalmente `operationIndicator` e `classCode`. As regras de imunidade/redução dos novos tributos são expressas via `classCode` (ex.: códigos iniciados em `41xxxx`), e não pelo `immunityType`.

:::

**Campos-chave dentro do grupo `ibsCbs`:**

Dentro do grupo, os únicos campos **obrigatórios** são `operationIndicator` e `classCode`.

- `operationIndicator` (string, **obrigatório**): Um código que especifica o tipo de operação de fornecimento, de acordo com uma nova tabela definida pelo fisco.
- `classCode` (string, **obrigatório**): O Código de Classificação Tributária para o IBS/CBS, que determina as alíquotas e regimes aplicáveis. É uma **string** (ex.: `"000001"`), não um número.
- `situationCode` (string, opcional): Código de Situação Tributária (CST) do IBS/CBS. Se não informado, é derivado automaticamente dos 3 primeiros dígitos do `classCode`.
- `personalUse` (booleano, opcional): Indica se o serviço é para uso ou consumo pessoal. Relevante para a aplicação de regras tributárias específicas.
- `destinationIndicator` (string, opcional): Indica o destinatário do serviço. Quando definido como `DifferentFromBuyer`, o grupo `recipient` na raiz passa a ser **obrigatório**.

> **Preenchimento automático:** Em geral, você **não precisa** informar os subgrupos `ibs` e `cbs` com alíquotas e valores. Quando omitidos, o motor de cálculo da NFE.io os calcula automaticamente a partir do `operationIndicator`, do `classCode` e do `servicesAmount`. Informe-os apenas quando precisar sobrepor o cálculo automático.

### 1.1. Subgrupo: `ibs` (Opcional)

Este subgrupo detalha o cálculo do IBS, que é um imposto subnacional (estadual e municipal).

- `totalAmount`: O valor total do IBS para a operação (soma das parcelas estadual e municipal).
- `state`: Detalhes da parcela **estadual** do IBS.
- `municipal`: Detalhes da parcela **municipal** do IBS (mesma estrutura do subgrupo estadual).

Tanto `state` quanto `municipal` (e também o `cbs`) compartilham a mesma estrutura de campos:

| Campo            | Descrição                                                                 |
|------------------|---------------------------------------------------------------------------|
| `rate`           | Alíquota de referência.                                                   |
| `rateReduction`  | Percentual de redução aplicado sobre a alíquota de referência.            |
| `effectiveRate`  | Alíquota efetiva, após a redução.                                         |
| `deferment`      | Informações de diferimento do tributo, quando aplicável.                  |
| `returnedAmount` | Valor de tributo devolvido (cashback), quando aplicável.                  |
| `amount`         | Valor do tributo devido.                                                  |

### 1.2. Subgrupo: `cbs` (Opcional)

Este subgrupo detalha o cálculo da CBS, que é um tributo federal. Possui a **mesma estrutura** dos subgrupos `ibs.state`/`ibs.municipal` (`rate`, `rateReduction`, `effectiveRate`, `deferment`, `returnedAmount`, `amount`).

### 1.3. Outros Subgrupos Opcionais no `ibsCbs`:

O grupo `ibsCbs` também inclui outros subgrupos opcionais para tratar de cenários fiscais mais complexos, como:

- `regularTaxation`: Para informar o cálculo hipotético do imposto no regime padrão.
- `presumedCredits`: Para detalhar quaisquer créditos presumidos de IBS e CBS.
- `governmentPurchase`: Para especificar detalhes fiscais para operações envolvendo entidades governamentais.
- `creditTransfer`: Para casos que envolvem a transferência de créditos de IBS/CBS.
- `thirdPartyReimbursements`: Para declarar valores relacionados a reembolsos ou repasses que não compõem a base de cálculo.
- `relatedDocs`: Para referenciar outras NFS-e, permitindo vincular as chaves dos documentos relacionados.

## 2. Grupo: serviceAmountDetails (Opcional)

Este grupo foi adicionado para fornecer uma decomposição mais clara dos valores cobrados, especialmente em cenários com multas e juros, comuns em contratos de serviço.

Motivo da Inclusão:
Para diferenciar o valor original do serviço de outros encargos, garantindo um cálculo mais preciso da base de cálculo. No layout anterior, esses valores eram frequentemente incluídos em `servicesAmount`.

**Campos-chave:**

- `initialChargedAmount`: O valor original cobrado pelo serviço, antes de quaisquer acréscimos.
- `finalChargedAmount`: O valor final total cobrado, incluindo todos os impostos, multas e juros.
- `fineAmount`: O valor específico referente a multas.
- `interestAmount`: O valor específico referente a juros.

## 3. Outros Novos Campos e Grupos

Além dos grupos principais acima, vários outros campos foram adicionados na raiz da requisição para acomodar o padrão nacional e fornecer mais detalhes.

- `nbsCode` (string, obrigatório): Código da Nomenclatura Brasileira de Serviços. Esta é uma nova classificação obrigatória para serviços em nível nacional.
- `ncmCode` (string, opcional): Código da Nomenclatura Comum do Mercosul, usado quando o serviço está relacionado a um bem físico.
- `cnaeCode` (string, opcional): Código CNAE, exigido apenas quando o município o requer.
- `paidAmount` (número, opcional): Valor total pago pelo serviço.
- `accrualOn` (data, opcional): Data de competência da prestação do serviço. Se não for fornecida, será assumida a data de `issuedOn`.
- `isEarlyInstallmentPayment` (booleano, opcional): Indica se a nota é para um pagamento de parcela antecipada.
- `immunityType` (string, opcional): Especifica o tipo de imunidade tributária, se aplicável.
- `retentionType` (string, opcional): Define quem é o responsável pela retenção do ISSQN (`NotWithheld`, `WithheldByBuyer`, `WithheldByIntermediary`).

**Novos Campos de Alíquotas (Opcional):**

O layout antigo possuía apenas campos (opcionais) para os valores finais dos impostos retidos. O novo layout inclui campos (opcionais) para as alíquotas, permitindo que o sistema utilize a alíquota informada pelo usuário no cálculo automático.

- `pisRate`
- `cofinsRate`

**Novos Grupos Opcionais para Cenários Complexos:**

Estes grupos foram adicionados para lidar com casos de negócio específicos previstos no padrão nacional.

- `ReferenceSubstitution`: Usado quando uma nota está sendo emitida para substituir uma anterior.
- `lease`: Para serviços envolvendo locação, sublocação ou direito de passagem de infraestrutura como ferrovias, postes e cabos.
- `construction`: Para serviços de construção civil, exigindo a identificação da obra (CNO/CEI) ou o endereço do imóvel.
- `foreignTrade`: Para operações de importação/exportação de serviços, detalhando aspectos como modo do serviço, moeda e mecanismos de fomento.
- `intermediary`: Para identificar um intermediário na prestação do serviço, além do prestador e do tomador.
- `recipient`: Para identificar o destinatário final do serviço quando ele é diferente do tomador.
- `realEstate`: Para operações relacionadas a bens imóveis, exceto obras.
- `deduction`: Para detalhar documentos que justificam deduções da base de cálculo (ex: subempreitadas).
- `benefit`: Para aplicar um benefício fiscal municipal que reduz a base de cálculo do ISSQN.
- `suspension`: Para indicar que a exigibilidade do ISSQN está suspensa por processo judicial ou administrativo.
- `approximateTotals`: Uma versão mais detalhada do antigo `approximateTax`, decompondo a carga tributária aproximada nas esferas federal, estadual e municipal.

## Resumo das Principais Diferenças

| Característica                | Layout Antigo (antigo)                                    | Novo Layout (novo)                                                                                             |
|-------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| **Estrutura Tributária**      | Baseada no ISS, com campos para retenções federais.      | Centrada em **IBS** e **CBS**, com um grupo dedicado `ibsCbs`.                                               |
| **Grupo Principal de Imposto**| Não aplicável. Campos estavam no nível raiz.             | **`ibsCbs`** (obrigatório), que contém todas as informações para os novos tributos.                          |
| **Classificação do Serviço**  | `cityServiceCode`, `federalServiceCode`.                 | Adiciona `nbsCode` (obrigatório) e `ncmCode` (opcional) para padronização nacional.                           |
| **Cálculo de Impostos**       | Mais simples, baseado em uma única alíquota de ISS.       | Mais complexo, com cálculos separados para IBS estadual/municipal e CBS federal, incluindo alíquotas efetivas. |
| **Cenários Especiais**        | Tratados através de campos genéricos ou descrições.      | Grupos específicos para `lease`, `construction`, `foreignTrade`, `ReferenceSubstitution`, etc.               |
| **Detalhamento de Valores**   | Geralmente consolidado em `servicesAmount`.              | O grupo `serviceAmountDetails` separa o valor original de multas e juros.                                  |
| **Participantes**             | Apenas `borrower`.                                       | Adiciona objetos opcionais `intermediary` e `recipient` para operações mais complexas.                       |


## Exemplo Mínimo (novo layout)

O exemplo abaixo contém **apenas os campos obrigatórios** para emissão no novo layout — incluindo o grupo `ibsCbs` com `operationIndicator` e `classCode`. Os valores de IBS/CBS são calculados automaticamente pela plataforma.

```json
{
  "borrower": {
    "name": "CONSUMIDOR MINIMO LTDA",
    "federalTaxNumber": 191
  },
  "cityServiceCode": "4444",
  "federalServiceCode": "01.01",
  "description": "Serviço de Consultoria e Assessoria.",
  "servicesAmount": 1000.00,
  "nbsCode": "101010100",
  "ibsCbs": {
    "operationIndicator": "1005011",
    "classCode": "000001"
  }
}
```

`POST https://api.nfe.io/v1/companies/{company_id}/serviceinvoices`

## Referências

- [Documentação Funcional do Layout de Emissão de NFS-e (RTC)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc) — detalhamento completo de todos os grupos e campos, tabelas de `operationIndicator` e `classCode`, e regras de validação.
- [Referência da API — Emissão de NFS-e (RTC)](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-servico-rtc/api-de-emissao-de-nota-fiscal-de-servicos-eletronica-nfs-e-rtc/) — schema completo e exemplos (mínimo, intermediário e completo) diretamente no contrato OpenAPI.
- [Envio de dados para emissão de NFS-e (RPS/DPS)](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-servico-rtc/envio-de-dados-para-emissao-de-nfs-e-rps-dps/) — endpoint de emissão.

## Conclusão

A transição para o layout novo é impulsionada principalmente pela necessidade de adaptação ao novo modelo tributário da Reforma Tributária. O principal esforço de integração será o preenchimento correto do grupo `ibsCbs`, que exige um entendimento detalhado das novas regras fiscais aplicáveis a cada prestação de serviço. O restante do layout permanece em grande parte consistente com a versão anterior.

---

## Municípios que não utilizam o Ambiente Nacional de Nota Fiscal de Serviço

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/municipios-que-nao-utilizam-ambiente-nacional/index.md

Para municípios que continuam utilizando **provedores próprios de emissão de NFS-e**, siga as orientações abaixo para manter a conformidade com as regras atuais e com as mudanças decorrentes da Reforma Tributária.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

## 1º passo — Verificar o regime tributário da empresa

### Simples Nacional e MEI

Para empresas enquadradas no **Simples Nacional** ou **MEI**, **não há mudanças obrigatórias no fluxo de emissão** neste momento.

**Pontos de atenção:**

* Alguns municípios já estão exigindo o envio do **NBS (Nomenclatura Brasileira de Serviços)**, mesmo fora do Ambiente Nacional  
  * Exemplo: **Fortaleza**

:::warning

Recomendamos verificar as exigências específicas do município emissor.

:::

### Lucro Real e Lucro Presumido

Para empresas enquadradas no **Lucro Real** ou **Lucro Presumido**, que já precisam atender às novas diretrizes da Reforma Tributária, será necessário enviar **informações adicionais** na emissão da NFS-e:

* **Código de Operação** (conforme tabela de referência)  
* **Classificação Tributária**

### Emissão via API

Consulte a documentação técnica:

* **Envio de dados para emissão de NFS-e (RPS/DPS)** — Documentação NFE.io

**Emissão via meio de pagamento / integração**

Caso utilize um intermediador ou meio de pagamento (ex.: **Vindi**), será necessário:

* Ajustar a **camada de integração**  
* Garantir que os novos campos estejam sendo corretamente informados pela interface

## 2º passo — Emitir a NFS-e

Após realizar os ajustes necessários:

* Efetue a emissão da nota fiscal com as **novas informações exigidas**  
* Verifique se a autorização ocorreu corretamente no provedor municipal

### Em caso de rejeição

Caso ocorra rejeição na emissão:

1. Entre em contato com o **suporte da NFE.io**  
2. Envie:  
   * Evidências do erro ou mensagens de rejeição  
   * Se possível, uma **nota fiscal válida emitida no ambiente do município**, para apoio na validação dos dados

---

## Guia de Solução de Problemas - Erros Comuns da API (RTC)

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/guia-solucao-problemas-nfse-rtc/index.md

# Guia de Solução de Problemas: Erros Comuns da API (Layout RTC)

## Introdução

Este guia foi projetado para ajudar desenvolvedores a diagnosticar e resolver erros comuns encontrados ao integrar com a API de emissão de NFS-e. Ele abrange erros de validação, rejeições de regras de negócio e problemas de fluxo de integração, fornecendo passos práticos para que sua integração funcione sem problemas.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

## Passos Gerais para Depuração

Antes de mergulhar em tipos de erro específicos, sempre siga estes passos iniciais:

1.  **Verifique a Resposta Completa da API:** Nossa API retorna mensagens de erro estruturadas na resposta JSON. Essas mensagens frequentemente incluem um código de erro, uma descrição e o campo específico que causou o problema. **Sempre registre (log) o corpo completo da resposta**, pois é a informação mais crítica para a depuração.

2.  **Valide Contra o Schema:** Muitos erros ocorrem porque o payload JSON não está em conformidade com a estrutura exigida. Antes de enviar uma requisição, valide seu payload contra a especificação OpenAPI da API de NFS-e (RTC) para identificar problemas estruturais, tipos de dados incorretos ou formatos inválidos antecipadamente.

3.  **Utilize o Ambiente de Homologação:** O **Fluxo de Validação (Mockup)** do ambiente de homologação é seu melhor amigo. Ele permite testar a estrutura e as regras de negócio da sua requisição sem de fato emitir um documento fiscal, fornecendo feedback instantâneo sobre o que precisa ser corrigido.

4.  **Aproveite os Logs Detalhados:** Lembre-se de que nosso sistema mantém um histórico detalhado de todas as requisições e respostas. Se precisar contatar o suporte, ter o `externalId` ou o timestamp exato da sua requisição permitirá que nossa equipe encontre rapidamente os logs e diagnostique o problema.

---

## Cenários de Erros Comuns e Soluções

### 1. Erros de Validação (HTTP 400 - Bad Request)

Estes são os erros mais comuns durante a integração inicial. Eles ocorrem quando o payload da requisição está malformado ou faltam informações obrigatórias.

#### Sintoma:
Uma resposta imediata da API com um status HTTP `400`. O corpo da resposta conterá detalhes sobre a falha de validação.

#### Causas Comuns e Soluções:

*   **Campos Obrigatórios Ausentes:**
    *   **Problema:** Um campo ou objeto obrigatório está faltando. Por exemplo, deixar de enviar o objeto `borrower`, o `servicesAmount` ou todo o grupo `ibsCbs`.
    *   **Solução:** Revise a especificação OpenAPI da API de NFS-e (RTC) e a documentação funcional para garantir que todos os campos marcados como **obrigatórios** (ou `required` no schema) estejam presentes no seu payload JSON. Preste atenção especial ao grupo `ibsCbs`, que é sempre obrigatório.

*   **Formatos de Dados Inválidos:**
    *   **Problema:** Um campo é enviado no formato errado. Exemplos comuns incluem enviar uma data como `DD/MM/AAAA` em vez de `YYYY-MM-DD`, ou um número como string (ex: `"100.00"` em vez de `100.00`).
    *   **Solução:** Verifique os requisitos de tipo de dado e formato para cada campo na documentação. Datas e data-horas devem seguir os padrões ISO 8601 (`YYYY-MM-DD` e `YYYY-MM-DDTHH:MM:SS-03:00`).

*   **Valores de Enum/Código Inválidos:**
    *   **Problema:** Um campo que espera um conjunto específico de valores recebe um valor inválido. Por exemplo, enviar um `taxationType` incorreto ou um `operationIndicator` desatualizado.
    *   **Solução:** Consulte as tabelas de referência na documentação funcional para os valores corretos de campos como `taxationType`, `operationIndicator` e `classCode`. Não fixe esses valores no código (hardcode) se eles puderem mudar com base na operação.

### 2. Erros de Regra de Negócio e Lógica

Esses erros ocorrem após a validação inicial ser aprovada, mas os dados violam uma regra de negócio específica aplicada pelo nosso sistema ou pelas autoridades fiscais.

#### Sintoma:
A requisição é aceita (HTTP 200/202), mas o status final recebido via webhook indica uma falha. A mensagem de erro descreverá a regra de negócio que foi violada.

#### Causas Comuns e Soluções:

*   **Códigos de Tributação Incorretos para a Operação:**
    *   **Problema:** A combinação de `operationIndicator` e `classCode` no grupo `ibsCbs` é inválida ou não corresponde ao serviço prestado. Esta é a parte mais crítica do novo layout.
    *   **Solução:** Revise cuidadosamente a finalidade do `operationIndicator` (define o local de incidência do imposto) e do `classCode` (define o tratamento tributário). Garanta que você está usando os códigos corretos para o serviço, local e regimes tributários dos participantes específicos.

*   **Dados de Participantes Inválidos (CNPJ/CPF/Endereço):**
    *   **Problema:** O `federalTaxNumber` (CNPJ/CPF) do prestador ou tomador é inválido, inativo ou não corresponde aos seus dados cadastrais. Da mesma forma, um endereço incorreto (especialmente CEP ou código da cidade) pode causar rejeição.
    *   **Solução:** Conforme recomendado nas boas práticas, utilize nossas **APIs de consulta** para validar dados cadastrais (`CNPJ/CPF`, Inscrição Estadual) e endereços (`CEP`) *antes* de enviar a requisição de emissão. Este passo de pré-validação reduz significativamente as rejeições.

*   **Erros de Campos Condicionais:**
    *   **Problema:** Um campo que é obrigatório apenas sob certas condições está ausente. Por exemplo, enviar `taxationType: "Immune"` sem fornecer o `immunityType` correspondente.
    *   **Solução:** Leia a documentação para campos que possuem lógica condicional. O campo `immunityType`, por exemplo, só é obrigatório quando `taxationType` é `Immune`. Outro exemplo é o objeto `recipient`, que se torna obrigatório se `destinationIndicator` for `DifferentFromBuyer`.

### 3. Erros de Fluxo de Integração e Processamento Assíncrono

Esses problemas estão relacionados ao fluxo geral de comunicação com a API, em vez do payload de dados em si.

#### Sintoma:
Comportamento inesperado, como notas fiscais duplicadas ou nunca receber uma atualização de status final.

#### Causas Comuns e Soluções:

*   **Emissão de Nota Fiscal Duplicada:**
    *   **Problema:** Seu sistema envia a mesma requisição de emissão várias vezes, muitas vezes devido a timeouts de rede ou falta de confirmação de resposta, resultando em notas duplicadas.
    *   **Solução:** **Sempre utilize o campo `externalId`.** Forneça um identificador único do seu sistema para cada requisição. Se nossa API receber uma requisição com um `externalId` que já foi processado com sucesso, ela não criará uma nova nota e, em vez disso, retornará os dados da original, garantindo a idempotência.

*   **Não Recebimento do Status Final (Problemas de Webhook):**
    *   **Problema:** Você envia uma requisição com sucesso, mas nunca recebe a notificação final de sucesso ou falha na sua URL de webhook.
    *   **Solução:**
        1.  **Verifique sua URL de Webhook:** Garanta que a URL de webhook configurada em nosso sistema está correta, acessível publicamente e pode receber requisições `POST`.
        2.  **Verifique seu Firewall/Rede:** Certifique-se de que nossos servidores não estão sendo bloqueados pelo seu firewall.
        3.  **Inspecione os Logs do Servidor:** Verifique os logs do seu servidor no momento da requisição para ver se a chamada do webhook foi recebida e se resultou em um erro do seu lado (ex: `500 Internal Server Error`).

*   **Mecanismo de Retentativa Automático:**
    *   **Informação:** Para erros temporários de rede ou instabilidade por parte da autoridade fiscal (como timeouts ou erros 5xx), nosso sistema possui um **mecanismo de retentativa com *exponential backoff*** integrado. Você não precisa implementar sua própria lógica de retentativa para esses casos; nossa API gerencia isso automaticamente.

---

Seguindo este guia, você pode identificar e corrigir eficientemente os problemas mais comuns, levando a uma integração mais rápida e confiável.

---

## Tabela de Referência - Comércio Exterior (`foreignTrade`)

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-comercio-exterior/index.md

# Tabela de Referência - Comércio Exterior (`foreignTrade`)

A tabela a seguir detalha os códigos e descrições para os campos enumerados dentro do grupo `foreignTrade`, que contém informações sobre transações entre residentes ou domiciliados no Brasil com residentes ou domiciliados no exterior.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

---

## Modo de Prestação (`serviceMode`)

| Código (`serviceMode`) | Descrição |
| :--------------------- | :-------- |
| `Unknown`              | Desconhecido (tipo não informado na nota de origem) |
| `CrossBorder`          | Transfronteiriço |
| `ConsumptionInBrazil`  | Consumo no Brasil |
| `TemporaryPersonnel`   | Movimento Temporário de Pessoas Físicas |
| `ConsumptionAbroad`    | Consumo no Exterior |

---

## Vínculo entre as Partes (`relationShip`)

| Código (`relationShip`) | Descrição |
| :---------------------- | :-------- |
| `NoLink`                | Sem Vínculo com o Tomador/Prestador |
| `Controlled`            | Controlada |
| `Controller`            | Controladora |
| `Affiliate`             | Coligada |
| `HeadOffice`            | Matriz |
| `Branch`                | Filial ou Sucursal |
| `OtherLink`             | Outro Vínculo |

---

## Mecanismo de Apoio/Fomento do Prestador (`supportMechanismProvider`)

| Código (`supportMechanismProvider`) | Descrição |
| :---------------------------------- | :-------- |
| `Unknown`                           | Desconhecido (tipo não informado na nota de origem) |
| `None`                              | Nenhum |
| `Acc`                               | ACC - Adiantamento sobre Contrato de Câmbio – Redução a Zero do IR e do IOF |
| `Ace`                               | ACE – Adiantamento sobre Cambiais Entregues - Redução a Zero do IR e do IOF |
| `BndesEximPostShipServices`         | BNDES-Exim Pós-Embarque – Serviços |
| `BndesEximPreShipServices`          | BNDES-Exim Pré-Embarque - Serviços |
| `Fge`                               | FGE - Fundo de Garantia à Exportação |
| `ProexEqualization`                 | PROEX - Equalização |
| `ProexFinancing`                    | PROEX - Financiamento |

---

## Mecanismo de Apoio/Fomento do Tomador (`supportMechanismReceiver`)

| Código (`supportMechanismReceiver`) | Descrição |
| :---------------------------------- | :-------- |
| `Unknown`                           | Desconhecido |
| `None`                              | Nenhum |
| `PublicAdminAndInternationalRep`    | Adm. Pública e Repr. Internacional |
| `LeasesMachineryShipsAircraft`      | Aluguéis e Arrend. Mercantil de máquinas, equip., embarc. e aeronaves |
| `AircraftLeaseAirTransportPublic`   | Arrendamento Mercantil de aeronave para empresa de transporte aéreo público |
| `ExportAgentsCommission`            | Comissão a agentes externos na exportação |
| `StorageHandlingTransportAbroad`    | Despesas de armazenagem, mov. e transporte de carga no exterior |
| `FifaEventsSubsidiary`              | Eventos FIFA (subsidiária) |
| `FifaEvents`                        | Eventos FIFA |
| `FreightsVesselAircraftRentalsOthers` | Fretes, arrendamentos de embarcações ou aeronaves e outros |
| `AeronauticalMaterial`              | Material Aeronáutico |
| `PromotionGoodsAbroad`              | Promoção de Bens no Exterior |
| `PromotionBrazilianTourism`         | Promoção de Dest. Turísticos Brasileiros |
| `PromotionBrazilAbroad`             | Promoção do Brasil no Exterior |
| `PromotionServicesAbroad`           | Promoção Serviços no Exterior |
| `Recine`                            | RECINE |
| `Recopa`                            | RECOPA |
| `TrademarksPatentsCultivars`        | Registro e Manutenção de marcas, patentes e cultivares |
| `Reicomp`                           | REICOMP |
| `Reidi`                             | REIDI |
| `Repenec`                           | REPENEC |
| `Repes`                             | REPES |
| `Retaero`                           | RETAERO |
| `Retid`                             | RETID |
| `RoyaltiesTechnicalAssistance`      | Royalties, Assistência Técnica, Científica e Assemelhados |
| `ConformityAssessmentWto`           | Serviços de avaliação da conformidade vinculados aos Acordos da OMC |
| `Zpe`                               | ZPE |

---

## Vínculo à Movimentação Temporária de Bens (`temporaryGoods`)

| Código (`temporaryGoods`) | Descrição |
| :------------------------ | :-------- |
| `Unknown`                 | Desconhecido (tipo não informado na nota de origem) |
| `No`                      | Não |
| `LinkedImportDeclaration` | Vinculada - Declaração de Importação |
| `LinkedExportDeclaration` | Vinculada - Declaração de Exportação |

---

## Tabela de Referência - CST e Classificação Tributária (IBS/CBS)

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-cst-classificacao-tributaria-ibs-cbs/index.md

# Tabela de Referência - CST e Classificação Tributária (IBS/CBS)

A tabela a seguir detalha os códigos de Situação Tributária (CST) e de Classificação Tributária (cClassTrib) para o IBS e a CBS, conforme a Reforma Tributária. A combinação correta desses códigos é essencial para a validação da NF-e no novo regime.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

## CST 000 - Tributação integral

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `000001` | Situações tributadas integralmente pelo IBS e CBS. |
| `000002` | Exploração de via, observado o art. 11 da Lei Complementar nº 214, de 2025. |
| `000003` | Regime automotivo - projetos incentivados, observado o art. 311 da Lei Complementar nº 214, de 2025. |
| `000004` | Regime automotivo - projetos incentivados, observado o art. 312 da Lei Complementar nº 214, de 2025. |

---

## CST 010 - Tributação com alíquotas uniformes - operações do FGTS

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `010001` | Operações do FGTS não realizadas pela Caixa Econômica Federal, observado o art. 212 da Lei Complementar nº 214, de 2025. |

---

## CST 011 - Tributação com alíquotas uniformes

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `011001` | **(Redução de 60%)** Planos de assistência funerária, observado o art. 236 da Lei Complementar nº 214, de 2025. |
| `011002` | **(Redução de 60%)** Planos de assistência à saúde, observado o art. 237 da Lei Complementar nº 214, de 2025. |
| `011003` | **(Redução de 60%)** Intermediação de planos de assistência à saúde, observado o art. 240 da Lei Complementar nº 214, de 2025. |
| `011004` | Concursos e prognósticos, observado o art. 246 da Lei Complementar nº 214, de 2025. |
| `011005` | **(Redução de 30%)** Planos de assistência à saúde de animais domésticos, observado o art. 243 da Lei Complementar nº 214, de 2025. |

---

## CST 200 - Alíquota zero ou reduzida

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `200001` | **(Alíquota zero)** Aquisições de máquinas, de aparelhos, de instrumentos, de equipamentos, de matérias-primas, de produtos intermediários e de materiais de embalagem realizadas entre empresas autorizadas a operar em zonas de processamento de exportação, observado o art. 103 da Lei Complementar nº 214, de 2025. |
| `200002` | **(Alíquota zero)** Fornecimento ou importação de tratores, máquinas e implementos agrícolas, destinados a produtor rural não contribuinte, e de veículos de transporte de carga destinados a transportador autônomo de carga pessoa física não contribuinte, observado o art. 110 da Lei Complementar nº 214, de 2025. |
| `200003` | **(Alíquota zero)** Vendas de produtos destinados à alimentação humana relacionados no Anexo I da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, que compõem a Cesta Básica Nacional de Alimentos, criada nos termos do art. 8º da Emenda Constitucional nº 132, de 20 de dezembro de 2023, observado o art. 125 da Lei Complementar nº 214, de 2025. |
| `200004` | **(Alíquota zero)** Venda de dispositivos médicos com a especificação das respectivas classificações da NCM/SH previstas no Anexo XII da Lei Complementar nº 214, de 2025, observado o art. 144 da Lei Complementar nº 214, de 2025. |
| `200005` | **(Alíquota zero)** Venda de dispositivos médicos com a especificação das respectivas classificações da NCM/SH previstas no Anexo IV da Lei Complementar nº 214, de 2025, quando adquiridos por órgãos da administração pública direta, autarquias e fundações públicas, observado o art. 144 da Lei Complementar nº 214, de 2025. |
| `200006` | **(Alíquota zero)** Situação de emergência de saúde pública reconhecida pelo Poder Legislativo federal, estadual, distrital ou municipal competente, ato conjunto do Ministro da Fazenda e do Comitê Gestor do IBS poderá ser editado, a qualquer momento, para incluir dispositivos não listados no Anexo XIII da Lei Complementar nº 214, de 2025, limitada a vigência do benefício ao período e à localidade da emergência de saúde pública, observado o art. 144 da Lei Complementar nº 214, de 2025. |
| `200007` | **(Alíquota zero)** Fornecimento dos dispositivos de acessibilidade próprios para pessoas com deficiência relacionados no Anexo XIV da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 145 da Lei Complementar nº 214, de 2025. |
| `200008` | **(Alíquota zero)** Fornecimento dos dispositivos de acessibilidade próprios para pessoas com deficiência relacionados no Anexo V da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, quando adquiridos por órgãos da administração pública direta, autarquias, fundações públicas e entidades imunes, observado o art. 145 da Lei Complementar nº 214, de 2025. |
| `200009` | **(Alíquota zero)** Fornecimento dos medicamentos relacionados no Anexo XIV da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 146 da Lei Complementar nº 214, de 2025. |
| `200010` | **(Alíquota zero)** Fornecimento dos medicamentos registrados na Anvisa, quando adquiridos por órgãos da administração pública direta, autarquias, fundações públicas e entidades imunes, observado o art. 146 da Lei Complementar nº 214, de 2025. |
| `200011` | **(Alíquota zero)** Fornecimento das composições para nutrição enteral e parenteral, composições especiais e fórmulas nutricionais destinadas às pessoas com erros inatos do metabolismo relacionadas no Anexo VI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, quando adquiridas por órgãos da administração pública direta, autarquias e fundações públicas, observado o art. 146 da Lei Complementar nº 214, de 2025. |
| `200012` | **(Alíquota zero)** Situação de emergência de saúde pública reconhecida pelo Poder Legislativo federal, estadual, distrital ou municipal competente, ato conjunto do Ministro da Fazenda e do Comitê Gestor do IBS poderá ser editado, a qualquer momento, para incluir dispositivos não listados no Anexo XIV da Lei Complementar nº 214, de 2025, limitada a vigência do benefício ao período e à localidade da emergência de saúde pública, observado o art. 146 da Lei Complementar nº 214, de 2025. |
| `200013` | **(Alíquota zero)** Fornecimento de tampões higiênicos, absorventes higiênicos internos ou externos, descartáveis ou reutilizáveis, calcinhas absorventes e coletores menstruais, observado o art. 147 da Lei Complementar nº 214, de 2025. |
| `200014` | **(Alíquota zero)** Fornecimento dos produtos hortícolas, frutas e ovos, relacionados no Anexo XV da Lei Complementar nº 214 , de 2025, com a especificação das respectivas classificações da NCM/SH e desde que não cozidos, observado o art. 148 da Lei Complementar nº 214, de 2025. |
| `200015` | **(Alíquota zero)** Venda de automóveis de passageiros de fabricação nacional de, no mínimo, 4 (quatro) portas, inclusive a de acesso ao bagageiro, quando adquiridos por motoristas profissionais que exerçam, comprovadamente, em automóvel de sua propriedade, atividade de condutor autônomo de passageiros, na condição de titular de autorização, permissão ou concessão do poder público, e que destinem o automóvel à utilização na categoria de aluguel (táxi), ou por pessoas com deficiência física, visual, auditiva, deficiência mental severa ou profunda, transtorno do espectro autista, com prejuízos na comunicação social e em padrões restritos ou repetitivos de comportamento de nível moderado ou grave, nos termos da legislação relativa à matéria, observado o disposto no art. 149 da Lei Complementar nº 214, de 2025. |
| `200016` | **(Alíquota zero)** Prestação de serviços de pesquisa e desenvolvimento por Instituição Científica, Tecnológica e de Inovação (ICT) sem fins lucrativos para a administração pública direta, autarquias e fundações públicas ou para o contribuinte sujeito ao regime regular do IBS e da CBS, observado o disposto no art. 156 da Lei Complementar nº 214, de 2025. |
| `200017` | **(Alíquota zero)** Operações relacionadas ao FGTS, considerando aquelas necessárias à aplicação da Lei nº 8.036, de 1990, realizadas pelo Conselho Curador ou Secretaria Executiva do FGTS, observado o art. 212 da Lei Complementar nº 214, de 2025. |
| `200018` | **(Alíquota zero)** Operações de resseguro e retrocessão ficam sujeitas à incidência à alíquota zero, inclusive quando os prêmios de resseguro e retrocessão forem cedidos ao exterior, observado o art. 223 da Lei Complementar nº 214, de 2025. |
| `200019` | **(Alíquota zero)** Importador dos serviços financeiros seja contribuinte que realize as operações de que tratam os incisos I a V do caput do art. 182, será aplicada alíquota zero na importação, sem prejuízo da manutenção do direito de dedução dessas despesas da base de cálculo do IBS e da CBS, segundo, observado o art. 231 da Lei Complementar nº 214, de 2025. |
| `200020` | **(Alíquota zero)** Operação praticada por sociedades cooperativas optantes por regime específico do IBS e CBS, quando o associado destinar bem ou serviço à cooperativa de que participa, e a cooperativa fornecer bem ou serviço ao associado sujeito ao regime regular do IBS e da CBS, observado o art. 271 da Lei Complementar nº 214, de 2025. |
| `200021` | **(Alíquota zero)** Serviços de transporte público coletivo de passageiros ferroviário e hidroviário urbanos, semiurbanos e metropolitanos, observado o art. 285 da Lei Complementar nº 214, de 2025. |
| `200022` | **(Alíquota zero)** Operação originada fora da Zona Franca de Manaus que destine bem material industrializado de origem nacional a contribuinte estabelecido na Zona Franca de Manaus que seja habilitado nos termos do art. 442 da Lei Complementar nº 214, de 2025, e sujeito ao regime regular do IBS e da CBS ou optante pelo regime do Simples Nacional de que trata o art. 12 da Lei Complementar nº 123, de 2006, observado o art. 445 da Lei Complementar nº 214, de 2025. |
| `200023` | **(Alíquota zero)** Operação realizada por indústria incentivada que destine bem material intermediário para outra indústria incentivada na Zona Franca de Manaus, desde que a entrega ou disponibilização dos bens ocorra dentro da referida área, observado o art. 448 da Lei Complementar nº 214, de 2025. |
| `200024` | **(Alíquota zero)** Operação originada fora das Áreas de Livre Comércio que destine bem material industrializado de origem nacional a contribuinte estabelecido nas Áreas de Livre Comércio que seja habilitado nos termos do art. 456 da Lei Complementar nº 214, de 2025, e sujeito ao regime regular do IBS e da CBS ou optante pelo regime do Simples Nacional de que trata o art. 12 da Lei Complementar nº 123, de 2006, observado o art. 463 da Lei Complementar nº 214, de 2025. |
| `200025` | **(Alíquota zero apenas CBS e reduzida em 60% para IBS)** Fornecimento dos serviços de educação relacionados ao Programa Universidade para Todos (Prouni), instituído pela Lei nº 11.096, de 13 de janeiro de 2005, observado o art. 308 da Lei Complementar nº 214, de 2025. |
| `200026` | **(Alíquota reduzida em 80%)** Locação de imóveis localizados nas zonas reabilitadas, pelo prazo de 5 (cinco) anos, contado da data de expedição do habite-se, e relacionados a projetos de reabilitação urbana de zonas históricas e de áreas críticas de recuperação e reconversão urbanística dos Municípios ou do Distrito Federal, a serem delimitadas por lei municipal ou distrital, observado o art. 158 da Lei Complementar nº 214, de 2025. |
| `200027` | **(Alíquota reduzida em 70%)** Operações de locação, cessão onerosa e arrendamento de bens imóveis, observado o art. 261 da Lei Complementar nº 214, de 2025. |
| `200028` | **(Alíquota reduzida em 60%)** Fornecimento dos serviços de educação relacionados no Anexo II da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da Nomenclatura Brasileira de Serviços, Intangíveis e Outras Operações que Produzam Variações no Patrimônio (NBS), observado o art. 129 da Lei Complementar nº 214, de 2025. |
| `200029` | **(Alíquota reduzida em 60%)** Fornecimento dos serviços de saúde humana relacionados no Anexo III da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS, observado o art. 130 da Lei Complementar nº 214, de 2025. |
| `200030` | **(Alíquota reduzida em 60%)** Venda dos dispositivos médicos relacionados no Anexo IV da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 131 da Lei Complementar nº 214, de 2025. |
| `200031` | **(Alíquota reduzida em 60%)** Fornecimento dos dispositivos de acessibilidade próprios para pessoas com deficiência relacionados no Anexo V da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 132 da Lei Complementar nº 214, de 2025. |
| `200032` | **(Alíquota reduzida em 60%)** Fornecimento dos medicamentos registrados na Anvisa ou produzidos por farmácias de manipulação, ressalvados os medicamentos sujeitos à alíquota zero de que trata o art. 141 da Lei Complementar nº 214, de 2025, observado o art. 133 da Lei Complementar nº 214, de 2025. |
| `200033` | **(Alíquota reduzida em 60%)** Fornecimento das composições para nutrição enteral e parenteral, composições especiais e fórmulas nutricionais destinadas às pessoas com erros inatos do metabolismo relacionadas no Anexo VI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 133 da Lei Complementar nº 214, de 2025. |
| `200034` | **(Alíquota reduzida em 60%)** Fornecimento dos alimentos destinados ao consumo humano relacionados no Anexo VII da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 135 da Lei Complementar nº 214, de 2025. |
| `200035` | **(Alíquota reduzida em 60%)** Fornecimento dos produtos de higiene pessoal e limpeza relacionados no Anexo VIII da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 136 da Lei Complementar nº 214, de 2025. |
| `200036` | **(Alíquota reduzida em 60%)** Fornecimento de produtos agropecuários, aquícolas, pesqueiros, florestais e extrativistas vegetais in natura, observado o art. 137 da Lei Complementar nº 214, de 2025. |
| `200037` | **(Alíquota reduzida em 60%)** Fornecimento de serviços ambientais de conservação ou recuperação da vegetação nativa, mesmo que fornecidos sob a forma de manejo sustentável de sistemas agrícolas, agroflorestais e agrossilvopastoris, em conformidade com as definições e requisitos da legislação específica, observado o art. 137 da Lei Complementar nº 214, de 2025. |
| `200038` | **(Alíquota reduzida em 60%)** Fornecimento dos insumos agropecuários e aquícolas relacionados no Anexo IX da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH e da NBS, observado o art. 138 da Lei Complementar nº 214, de 2025. |
| `200039` | **(Alíquota reduzida em 60%)** Fornecimento dos serviços e o licenciamento ou cessão dos direitos relacionados no Anexo X da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS, quando destinados às seguintes produções nacionais artísticas, culturais, de eventos, jornalísticas e audiovisuais: espetáculos teatrais, circenses e de dança, shows musicais, desfiles carnavalescos ou folclóricos, eventos acadêmicos e científicos, como congressos, conferências e simpósios, feiras de negócios, exposições, feiras e mostras culturais, artísticas e literárias; programas de auditório ou jornalísticos, filmes, documentários, séries, novelas, entrevistas e clipes musicais, observado o art. 139 da Lei Complementar nº 214, de 2025. |
| `200040` | **(Alíquota reduzida em 60%)** Fornecimento dos seguintes serviços de comunicação institucional à administração pública direta, autarquias e fundações públicas: serviços direcionados ao planejamento, criação, programação e manutenção de páginas eletrônicas da administração pública, ao monitoramento e gestão de suas redes sociais e à otimização de páginas e canais digitais para mecanismos de buscas e produção de mensagens, infográficos, painéis interativos e conteúdo institucional, serviços de relações com a imprensa, que reúnem estratégias organizacionais para promover e reforçar a comunicação dos órgãos e das entidades contratantes com seus públicos de interesse, por meio da interação com profissionais da imprensa, e serviços de relações públicas, que compreendem o esforço de comunicação planejado, coeso e contínuo que tem por objetivo estabelecer adequada percepção da atuação e dos objetivos institucionais, a partir do estímulo à compreensão mútua e da manutenção de padrões de relacionamento e fluxos de informação entre os órgãos e as entidades contratantes e seus públicos de interesse, no País e no exterior, observado o art. 140 da Lei Complementar nº 214, de 2025. |
| `200041` | **(Alíquota reduzida em 60%)** Operações relacionadas às seguintes atividades desportivas: fornecimento de serviço de educação desportiva, classificado no código 1.2205.12.00 da NBS, e gestão e exploração do desporto por associações e clubes esportivos filiados ao órgão estadual ou federal responsável pela coordenação dos desportos, inclusive por meio de venda de ingressos para eventos desportivos, fornecimento oneroso ou não de bens e serviços, inclusive ingressos, por meio de programas de sócio-torcedor, cessão dos direitos desportivos dos atletas e transferência de atletas para outra entidade desportiva ou seu retorno à atividade em outra entidade desportiva, observado o art. 141 da Lei Complementar nº 214, de 2025. |
| `200042` | **(Alíquota reduzida em 60%)** Operações relacionadas ao fornecimento de serviço de educação desportiva, classificado no código 1.2205.12.00 da NBS, observado o art. 141 da Lei Complementar nº 214, de 2025. |
| `200043` | **(Alíquota reduzida em 60%)** Fornecimento à administração pública direta, autarquias e fundações púbicas dos serviços e dos bens relativos à soberania e à segurança nacional, à segurança da informação e à segurança cibernética relacionados no Anexo XI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS e da NCM/SH, observado o art. 142 da Lei Complementar nº 214, de 2025. |
| `200044` | **(Alíquota reduzida em 60%)** Operações e prestações de serviços de segurança da informação e segurança cibernética desenvolvidos por sociedade que tenha sócio brasileiro com o mínimo de 20% (vinte por cento) do seu capital social, relacionados no Anexo XI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS e da NCM/SH, observado o art. 142 da Lei Complementar nº 214, de 2025. |
| `200045` | **(Alíquota reduzida em 60%)** Operações relacionadas a projetos de reabilitação urbana de zonas históricas e de áreas críticas de recuperação e reconversão urbanística dos Municípios ou do Distrito Federal, a serem delimitadas por lei municipal ou distrital, observado o art. 158 da Lei Complementar nº 214, de 2025. |
| `200046` | **(Alíquota reduzida em 50%)** Operações com bens imóveis, observado o art. 261 da Lei Complementar nº 214, de 2025. |
| `200047` | **(Alíquota reduzida em 40%)** Bares e Restaurantes, observado o art. 275 da Lei Complementar nº 214, de 2025. |
| `200048` | **(Alíquota reduzida em 40%)** Hotelaria, Parques de Diversão e Parques Temáticos, observado o art. 281 da Lei Complementar nº 214, de 2025. |
| `200049` | **(Alíquota reduzida em 40%)** Transporte coletivo de passageiros rodoviário, ferroviário e hidroviário intermunicipais e interestaduais, observado o art. 286 da Lei Complementar nº 214, de 2025. |
| `200050` | **(Alíquota reduzida em 40%)** Serviços de transporte aéreo regional coletivo de passageiros ou de carga, observado o art. 287 da Lei Complementar nº 214, de 2025. |
| `200051` | **(Alíquota reduzida em 40%)** Agências de Turismo, observado o art. 289 da Lei Complementar nº 214, de 2025. |
| `200052` | **(Alíquota reduzida em 30%)** Prestação de serviços das seguintes profissões intelectuais de natureza científica, literária ou artística, submetidas à fiscalização por conselho profissional: administradores, advogados, arquitetos e urbanistas, assistentes sociais, bibliotecários, biólogos, contabilistas, economistas, economistas domésticos, profissionais de educação física, engenheiros e agrônomos, estatísticos, médicos veterinários e zootecnistas, museólogos, químicos, profissionais de relações públicas, técnicos industriais e técnicos agrícolas, observado o art. 127 da Lei Complementar nº 214, de 2025. |

---

## CST 210 - Alíquota reduzida com redutor de base de cálculo

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `210001` | **(Redução de 50%)** Redutor social aplicado uma única vez na alienação de bem imóvel residencial novo, observado o art. 259 da Lei Complementar nº 214, de 2025. |
| `210002` | **(Redução de 50%)** Redutor social aplicado uma única vez na alienação de lote residencial, observado o art. 259 da Lei Complementar nº 214, de 2025. |
| `210003` | **(Redução de 70%)** Redutor social em operações de locação, cessão onerosa e arrendamento de bens imóveis de uso residencial, observado o art. 260 da Lei Complementar nº 214, de 2025. |

---

## CST 220 - Alíquota fixa

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `220001` | Incorporação imobiliária submetida ao regime especial de tributação, observado o art. 485 da Lei Complementar nº 214, de 2025. |
| `220002` | Incorporação imobiliária submetida ao regime especial de tributação, observado o art. 485 da Lei Complementar nº 214, de 2025. |
| `220003` | Alienação de imóvel decorrente de parcelamento do solo, observado o art. 486 da Lei Complementar nº 214, de 2025. |

---

## CST 221 - Alíquota fixa proporcional

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `221001` | Locação, cessão onerosa ou arrendamento de bem imóvel com alíquota sobre a receita bruta, observado o art. 487 da Lei Complementar nº 214, de 2025. |

---

## CST 400 - Isenção

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `400001` | Fornecimento de serviços de transporte público coletivo de passageiros rodoviário e metroviário de caráter urbano, semiurbano e metropolitano, sob regime de autorização, permissão ou concessão pública, observado o art. 157 da Lei Complementar nº 214, de 2025. |

---

## CST 410 - Imunidade e não incidência

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `410001` | Fornecimento de bonificações quando constem do respectivo documento fiscal e que não dependam de evento posterior, observado o art. 5º da Lei Complementar nº 214, de 2025. |
| `410002` | Transferências entre estabelecimentos pertencentes ao mesmo contribuinte, observado o art. 6º da Lei Complementar nº 214, de 2025. |
| `410003` | Doações, observado o art. 6º da Lei Complementar nº 214, de 2025. |
| `410004` | Exportações de bens e serviços, observado o art. 8º da Lei Complementar nº 214, de 2025. |
| `410005` | Fornecimentos realizados pela União, pelos Estados, pelo Distrito Federal e pelos Municípios, observado o art. 9º da Lei Complementar nº 214, de 2025. |
| `410006` | Fornecimentos realizados por entidades religiosas e templos de qualquer culto, inclusive suas organizações assistenciais e beneficentes, observado o art. 9º da Lei Complementar nº 214, de 2025. |
| `410007` | Fornecimentos realizados por partidos políticos, inclusive suas fundações, entidades sindicais dos trabalhadores e instituições de educação e de assistência social, sem fins lucrativos, observado o art. 9º da Lei Complementar nº 214, de 2025. |
| `410008` | Fornecimentos de livros, jornais, periódicos e do papel destinado a sua impressão, observado o art. 9º da Lei Complementar nº 214, de 2025. |
| `410009` | Fornecimentos de fonogramas e videofonogramas musicais produzidos no Brasil contendo obras musicais ou literomusicais de autores brasileiros e/ou obras em geral interpretadas por artistas brasileiros, bem como os suportes materiais ou arquivos digitais que os contenham, salvo na etapa de replicação industrial de mídias ópticas de leitura a laser, observado o art. 9º da Lei Complementar nº 214, de 2025. |
| `410010` | Fornecimentos de serviço de comunicação nas modalidades de radiodifusão sonora e de sons e imagens de recepção livre e gratuita, observado o art. 9º da Lei Complementar nº 214, de 2025. |
| `410011` | Fornecimentos de ouro, quando definido em lei como ativo financeiro ou instrumento cambial, observado o art. 9º da Lei Complementar nº 214, de 2025. |
| `410012` | Fornecimento de condomínio edilício não optante pelo regime regular, observado o art. 26 da Lei Complementar nº 214, de 2025. |
| `410013` | Exportações de combustíveis, observado o art. 98 da Lei Complementar nº 214, de 2025. |
| `410014` | Fornecimento de produtor rural não contribuinte, observado o art. 164 da Lei Complementar nº 214, de 2025. |
| `410015` | Fornecimento por transportador autônomo não contribuinte, observado o art. 169 da Lei Complementar nº 214, de 2025. |
| `410016` | Fornecimento ou aquisição de resíduos sólidos, observado o art. 170 da Lei Complementar nº 214, de 2025. |
| `410017` | Aquisição de bem móvel com crédito presumido sob condição de revenda realizada, observado o art. 171 da Lei Complementar nº 214, de 2025. |
| `410018` | Operações relacionadas aos fundos garantidores e executores de políticas públicas, inclusive de habitação, previstos em lei, assim entendidas os serviços prestados ao fundo pelo seu agente operador e por entidade encarregada da sua administração, observado o art. 213 da Lei Complementar nº 214, de 2025. |
| `410019` | Exclusão da gorjeta na base de cálculo no fornecimento de alimentação, observado o art. 274 da Lei Complementar nº 214, de 2025. |
| `410020` | Exclusão do valor de intermediação na base de cálculo no fornecimento de alimentação, observado o art. 274 da Lei Complementar nº 214, de 2025. |

---

## CST 510 - Diferimento

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `510001` | Operações, sujeitas a diferimento, com energia elétrica ou com direitos a ela relacionados, relativas à geração, comercialização, distribuição e transmissão, observado o art. 28 da Lei Complementar nº 214, de 2025. |
| `510002` | Operações, sujeitas a diferimento, com insumos agropecuários e aquícolas destinados a produtor rural contribuinte, observado o art. 138 da Lei Complementar nº 214, de 2025. |

---

## CST 550 - Suspensão

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `550001` | Exportações de bens materiais, observado o art. 82 da Lei Complementar nº 214, de 2025. |
| `550002` | Regime de Trânsito, observado o art. 84 da Lei Complementar nº 214, de 2025. |
| `550003` | Regimes de Depósito, observado o art. 85 da Lei Complementar nº 214, de 2025. |
| `550004` | Regimes de Depósito, observado o art. 87 da Lei Complementar nº 214, de 2025. |
| `550005` | Regimes de Depósito, observado o art. 87 da Lei Complementar nº 214, de 2025. |
| `550006` | Regimes de Permanência Temporária, observado o art. 88 da Lei Complementar nº 214, de 2025. |
| `550007` | Regimes de Aperfeiçoamento, observado o art. 90 da Lei Complementar nº 214, de 2025. |
| `550008` | Importação de bens para o Regime de Repetro-Temporário, de que tratam o inciso I do art. 93 da Lei Complementar nº 214, de 2025. |
| `550009` | GNL-Temporário, de que trata o inciso II do art. 93 da Lei Complementar nº 214, de 2025. |
| `550010` | Repetro-Permanente, de que trata o inciso III do art. 93 da Lei Complementar nº 214, de 2025. |
| `550011` | Repetro-Industrialização, de que trata o inciso IV do art. 93 da Lei Complementar nº 214, de 2025. |
| `550012` | Repetro-Nacional, de que trata o inciso V do art. 93 da Lei Complementar nº 214, de 2025. |
| `550013` | Repetro-Entreposto, de que trata o inciso VI do art. 93 da Lei Complementar nº 214, de 2025. |
| `550014` | Zona de Processamento de Exportação, observado os arts. 99, 100 e 102 da Lei Complementar nº 214, de 2025. |
| `550015` | Regime Tributário para Incentivo à Modernização e à Ampliação da Estrutura Portuária - Reporto, observado o art. 105 da Lei Complementar nº 214, de 2025. |
| `550016` | Regime Especial de Incentivos para o Desenvolvimento da Infraestrutura - Reidi, observado o art. 106 da Lei Complementar nº 214, de 2025. |
| `550017` | Regime Tributário para Incentivo à Atividade Econômica Naval – Renaval, observado o art. 107 da Lei Complementar nº 214, de 2025. |
| `550018` | Desoneração da aquisição de bens de capital, , observado o art. 109 da Lei Complementar nº 214, de 2025. |
| `550019` | Importação de bem material por indústria incentivada para utilização na Zona Franca de Manaus, observado o art. 443 da Lei Complementar nº 214, de 2025. |
| `550020` | Áreas de livre comércio, observado o art. 461 da Lei Complementar nº 214, de 2025. |

---

## CST 620 - Tributação monofásica

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `620001` | Tributação monofásica sobre combustíveis, observados os art. 172 e art. 179 I da Lei Complementar nº 214, de 2025. |
| `620002` | Tributação monofásica com responsabilidade pela retenção sobre combustíveis, observado o art. 178 da Lei Complementar nº 214, de 2025. |
| `620003` | Tributação monofásica com tributos retidos por responsabilidade sobre combustíveis, observado o art. 178 da Lei Complementar nº 214, de 2025. |
| `620004` | Tributação monofásica sobre mistura de EAC com gasolina A em percentual superior ou inferior ao obrigatório, observado o art. 179 da Lei Complementar nº 214, de 2025. |
| `620005` | Tributação monofásica sobre combustíveis cobrada anteriormente, observador o art. 180 da Lei Complementar nº 214, de 2025. |

---

## CST 800 - Transferência de crédito

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `800001` | Fusão, cisão ou incorporação, observado o art. 55 da Lei Complementar nº 214, de 2025. |
| `800002` | Transferência de crédito do associado, inclusive as cooperativas singulares, para cooperativa de que participa das operações antecedentes às operações em que fornece bens e serviços e os créditos presumidos, observado o art. 272 da Lei Complementar nº 214, de 2025. |

---

## CST 810 - Ajustes

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `810001` | Crédito presumido sobre o valor apurado nos fornecimentos a partir da Zona Franca de Manaus, observado o art. 450 da Lei Complementar nº 214, de 2025. |

---

## CST 820 - Tributação em declaração de regime específico

| Código de Classificação (cClassTrib) | Descrição da Classificação |
| :--- | :--- |
| `820001` | Documento com informações de fornecimento de serviços de planos de assinstência à saúde, mas com tributação realizada por outro meio, observado o art. 235 da Lei Complementar nº 214, de 2025. |
| `820002` | Documento com informações de fornecimento de serviços de planos de assinstência funerária, mas com tributação realizada por outro meio, observado o art. 236 da Lei Complementar nº 214, de 2025. |
| `820003` | Documento com informações de fornecimento de serviços de planos de assinstência à saúde de animais domésticos, mas com tributação realizada por outro meio, observado o art. 243 da Lei Complementar nº 214, de 2025. |
| `820004` | Documento com informações de prestação de serviços de consursos de prognósticos, mas com tributação realizada por outro meio, observado o art. 248 da Lei Complementar nº 214, de 2025. |
| `820005` | Documento com informações de alienação de bens imóveis, mas com tributação realizada por outro meio,, observado o art. 254 da Lei Complementar nº 214, de 2025. |

---

## Tabela de Referência - Indicador da Operação (indOp)

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-indicador-operacao/index.md

# Tabela de Referência - Indicador da Operação (indOp)

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

**Pontos de Atenção (Lei Complementar nº 214, de 2025):**

1.  **Imóvel em Múltiplos Municípios:** Caso o bem imóvel esteja situado em mais de um Município, considera-se local do imóvel o Município onde está situada a maior parte da sua área (Art. 11, §2º).
2.  **Serviços à Distância:** Aos serviços do inc. III, se parcialmente prestados à distância, aplica-se o disposto no inciso X (Art. 11, §4º).
3.  **Aquisições Centralizadas:** Nas aquisições centralizadas por contribuinte com mais de um estabelecimento, os serviços do inc. IX do art. 11 serão considerados prestados no domicílio principal do adquirente; para o inc. X do art. 11 e o inc. I do §4º do art. 11, considera-se como domicílio principal do adquirente o local de seu estabelecimento matriz (Art. 11, §4º, II).
4.  **Cessão de Espaço Publicitário:** Aplica-se o disposto no inciso X do artigo 11 às operações de cessão de espaço para prestação de serviços publicitários (Art. 11, §11).
5.  **Adquirente no Exterior:** Na hipótese do inc. X do caput do art. 11, caso o adquirente seja residente ou domiciliado no exterior e o destinatário seja residente ou domiciliado no País, considera-se como local da operação o domicílio do destinatário (Art. 11, §8).
6.  **Domicílio do Destinatário:** Vide §3º do art. 11 a respeito da caracterização do domicílio.

A tabela a seguir reproduz o **Anexo VII (`cIndOp`) v1.02.00** do Ambiente de Dados Nacional (ADN), detalhando os códigos do Indicador da Operação (`operationIndicator` / `indOp`), que determinam o local de incidência do IBS e da CBS, com base no Art. 11 da Lei Complementar nº 214, de 2025. As colunas **NF-e** e **NFS-e** indicam em quais documentos fiscais cada código é aplicável.

| Código (`indOp`) | Tipo de Operação | Característica do Fornecimento | Local a ser Identificado no DF-e | Dispositivo Legal (LC 214/2025) | Observação | NF-e | NFS-e |
| :--- | :--- | :--- | :--- | :--- | :--- | :---: | :---: |
| `010101` | Bem Móvel Material | Presencial, com retirada no estabelecimento do fornecedor | Estabelecimento do fornecedor como o local da entrega ou disponibilização do bem ao destinatário | Art. 11, I | A locação, o arrendamento e a cessão temporária do bem incluem-se como operações com bens, conforme art. 3º, § 3º, da LC 214/2025 | — | Sim |
| `010102` | Bem Móvel Material | Presencial, com retirada fora do estabelecimento do fornecedor | Local da realização da operação e sua retirada | Art. 11, I | A locação, o arrendamento e a cessão temporária do bem incluem-se como operações com bens, conforme art. 3º, § 3º, da LC 214/2025 | — | Sim |
| `010103` | Bem Móvel Material | Não presencial, com entrega ou disponibilização em endereço fornecido | Endereço do destinatário fornecido para entrega ou disponibilização (assim considerado o destino final indicado pelo adquirente) | Art. 11, I e §1º, I | A locação, o arrendamento e a cessão temporária do bem incluem-se como operações com bens, conforme art. 3º, § 3º, da LC 214/2025 | — | Sim |
| `010104` | Bem Móvel Material | Licitação promovida pelo poder público de bem apreendido ou abandonado ou leilão judicial | Local onde se encontra o bem móvel material | Art. 11, I e §1º, III, "a" | — | Sim | — |
| `010105` | Bem Móvel Material | Constatação de irregularidade pela falta de documentação fiscal ou pelo acobertamento por documentação inidônea | Local onde se encontra o bem móvel material (Local da retirada) | Art. 11, I e §1º, III, "b" | — | Sim | — |
| `010106` | Bem Móvel Material | Locação de bem móvel material em aquisições realizadas de forma centralizada por contribuinte sujeito ao regime regular do IBS e da CBS que possui mais de um estabelecimento e que não estejam sujeitas a vedação à apropriação de créditos | Local do domicílio principal do adquirente (estabelecimento matriz) | Art. 11, I e §4º | — | — | Sim |
| `010201` | Aquisição de veículo automotor terrestre, aquático ou aéreo | Entrega ou disponibilização do bem | Domicílio principal do destinatário | Art. 11, I e §1º, II | — | — | — |
| `010202` | Aquisição de veículo automotor em licitação promovida pelo poder público de bem apreendido ou abandonado ou leilão judicial | Entrega ou disponibilização do bem | Domicílio principal do destinatário | Art. 11, I e §1º, II | Na aquisição de veículo automotor em licitação promovida pelo poder público de bem apreendido ou abandonado ou leilão judicial considera-se ocorrida a operação no local do domicílio principal do destinatário, conforme art. 12, § 15, do Decreto 12.955/2026 e art. 12, § 15, da Resolução CGIBS 6/2026 | — | — |
| `020101` | Operação com bem imóvel, bem imaterial, inclusive direito, relacionada a bem imóvel | Realização de operações com bem imóvel, bem imaterial, inclusive direito, relacionado a bem imóvel | Localidade do imóvel | Art. 11, II e §2º | — | — | Sim |
| `020201` | Serviço prestado fisicamente sobre bem imóvel | Execução de serviços diversos prestados fisicamente sobre bem imóvel | Localidade do imóvel | Art. 11, II e §2º | — | — | Sim |
| `020202` | Serviço prestado fisicamente sobre bem imóvel | Execução de serviços sobre Bens Imóveis de Características Especiais (BICE) | Localidade do imóvel | Art. 11, II e §2º | — | — | Sim |
| `020301` | Serviço de administração e intermediação de bem imóvel | Execução dos serviços de administração e intermediação de bens imóveis | Localidade do imóvel | Art. 11, II e §2º | — | — | Sim |
| `020401` | Serviços de locação, sublocação, arrendamento, direito de passagem ou permissão de uso, compartilhado ou não, de ferrovia, rodovia, postes, cabos, dutos e condutos de qualquer natureza | Execução de serviços sobre Bens Imóveis de Características Especiais (BICE) | Localidade do imóvel | Art. 11, II e §2º | — | — | Sim |
| `030101` | Serviço prestado fisicamente sobre a pessoa ou fruído presencialmente por pessoa física | Execução de serviços diversos exclusivamente prestados fisicamente sobre a pessoa ou integralmente fruídos presencialmente por pessoa física | Estabelecimento do fornecedor como local da prestação | Art. 11, III | Na operação de serviço notarial e de registro relativo a bem imóvel ou a bem móvel imaterial, inclusive direito, relacionado a bem imóvel, considera-se ocorrida a operação no local da prestação caso seja fruído presencialmente, conforme art. 12, § 11 do Decreto 12.955/2026 e art. 12, § 11, da Resolução CGIBS 6/2026 | — | Sim |
| `030102` | Serviço prestado fisicamente sobre a pessoa ou fruído presencialmente por pessoa física | Execução de serviços diversos exclusivamente prestados fisicamente sobre a pessoa ou integralmente fruídos presencialmente por pessoa física | Local da prestação do serviço diverso do estabelecimento do fornecedor | Art. 11, III | Na operação de serviço notarial e de registro relativo a bem imóvel ou a bem móvel imaterial, inclusive direito, relacionado a bem imóvel, considera-se ocorrida a operação no local da prestação caso seja fruído presencialmente, conforme art. 12, § 11 do Decreto 12.955/2026 e art. 12, § 11, da Resolução CGIBS 6/2026 | — | Sim |
| `040101` | Serviço de planejamento, organização e administração de feiras, exposições, congressos, espetáculos, exibições e congêneres | Execução de serviços de planejamento, organização e administração de feiras, exposições, congressos, espetáculos, exibições e congêneres | Local do evento a que se refere o serviço | Art. 11, IV | — | — | Sim |
| `050101` | Serviço prestado fisicamente sobre bem móvel material | Execução de serviços diversos prestados fisicamente sobre bem móvel material | Estabelecimento do fornecedor como local da prestação | Art. 11, V | No serviço prestado em porto seco e aeroporto, considera-se ocorrida a operação no local da prestação do serviço, conforme art. 12, § 12, do Decreto 12.955/2026 e art. 12, § 12, da Resolução CGIBS 6/2026 | — | Sim |
| `050102` | Serviço prestado fisicamente sobre bem móvel material | Execução de serviços diversos prestados fisicamente sobre bem móvel material | Local da prestação do serviço diverso do estabelecimento do fornecedor | Art. 11, V | No serviço prestado em porto seco e aeroporto, considera-se ocorrida a operação no local da prestação do serviço, conforme art. 12, § 12, do Decreto 12.955/2026 e art. 12, § 12, da Resolução CGIBS 6/2026 | — | Sim |
| `050201` | Serviços portuários | Execução de serviços portuários | Local do porto como local da prestação | Art. 11, V | — | — | Sim |
| `060101` | Serviço de transporte de passageiros | Execução de serviços de transporte de passageiros | Local de início do transporte | Art. 11, VI | — | — | Sim |
| `070101` | Serviço de transporte de carga | Execução de serviço de transporte de carga | Endereço fornecido para entrega do bem | Art. 11, VII | — | — | Sim |
| `070102` | Serviço de transporte de carga | Execução de serviço de transporte de carga | Local da retirada do bem | Art. 11, VII | — | — | Sim |
| `080101` | Serviço de exploração de via | Execução de serviços de exploração de via | Local da prestação correspondente à extensão da via explorada, proporcionalmente ao território dos entes tributantes | Art. 11, VIII | — | — | — |
| `090101` | Serviço de telefonia fixa e demais serviços de comunicação prestados por meio de cabos, fios, fibras e meios similares | Execução de serviços de telefonia fixa e demais serviços de comunicação prestados por meio de cabos, fios, fibras e meios similares | Local de instalação do terminal | Art. 11, IX | — | — | — |
| `090102` | Serviço de telefonia fixa e demais serviços de comunicação prestados por meio de cabos, fios, fibras e meios similares | Execução de serviços de telefonia fixa e demais serviços de comunicação prestados por meio de cabos, fios, fibras e meios similares | Local do domicílio principal do adquirente (assim considerada a matriz), nas aquisições realizadas de forma centralizada por contribuinte sujeito ao regime regular do IBS e da CBS que possui mais de um estabelecimento e que não estejam sujeitas a vedação à apropriação de créditos | Art. 11, IX e §4º, I e II | — | — | — |
| `100101` | Cessão de espaço para prestação de serviços publicitários, em operações onerosas | Realização de operações de cessão de espaço para prestação de serviços publicitários | Local do domicílio principal do adquirente residente ou domiciliado no País. Nas aquisições indicadas no art. 11, §4º, II, considera-se domicílio principal do adquirente o estabelecimento matriz | Art. 11, X, "a", 1 e § 11 | — | — | Sim |
| `100102` | Cessão de espaço para prestação de serviços publicitários, em operações onerosas | Realização de operações de cessão de espaço para prestação de serviços publicitários | Local do domicílio principal do destinatário residente ou domiciliado no País, caso o adquirente não seja residente ou domiciliado no País | Art. 11, X, "a", 2 e § 11 | — | — | Sim |
| `100201` | Cessão de espaço para prestação de serviços publicitários, em operações não onerosas | Realização de operações de cessão de espaço para prestação de serviços publicitários | local do domicílio principal do destinatário residente ou domiciliado no País | Art. 11, X, "b" e § 11 | — | — | Sim |
| `100301` | Demais serviços, em operações onerosas | Execução dos demais serviços em operações não especificadas em outros indicadores ou, nos serviços de que trata o inc. III do art. 11, esses sejam, ainda que parcialmente, prestados à distância | Local do domicílio principal do adquirente residente ou domiciliado no País. Nas aquisições indicadas no art. 11, §4º, II, considera-se domicílio principal do adquirente o estabelecimento matriz | Art. 11, X, "a", 1 e §§ 4º, II e 5º | Na operação de serviço notarial e de registro relativo a bem imóvel ou a bem móvel imaterial, inclusive direito, relacionado a bem imóvel, considera-se ocorrida a operação no local do inciso X, caso não seja fruído presencialmente, conforme art. 12, § 11, do Decreto 12.955/2026 e art. 12, § 11, da Resolução CGIBS 6/2026 | — | Sim |
| `100302` | Demais serviços, em operações onerosas | Execução dos demais serviços em operações não especificadas em outros indicadores ou, nos serviços de que trata o inc. III do art. 11, esses sejam, ainda que parcialmente, prestados à distância | Local do domicílio principal do destinatário residente ou domiciliado no País, caso o adquirente não seja residente ou domiciliado no País | Art. 11, X, "a", 2 e § 5º | Na operação de serviço notarial e de registro relativo a bem imóvel ou a bem móvel imaterial, inclusive direito, relacionado a bem imóvel, considera-se ocorrida a operação no local do inciso X, caso não seja fruído presencialmente, conforme art. 12, § 11, do Decreto 12.955/2026 e art. 12, § 11, da Resolução CGIBS 6/2026 | — | Sim |
| `100401` | Demais serviços, em operações não onerosas | Execução dos demais serviços em operações não especificadas em outros indicadores ou, nos serviços de que tratam o inc. III, estes sejam, ainda que parcialmente, prestados à distância | local do domicílio principal do destinatário residente ou domiciliado no País | Art. 11, X, "b" e § 5º | Na operação de serviço notarial e de registro relativo a bem imóvel ou a bem móvel imaterial, inclusive direito, relacionado a bem imóvel, considera-se ocorrida a operação no local do inciso X, caso não seja fruído presencialmente, conforme art. 12, § 11, do Decreto 12.955/2026 e art. 12, § 11, da Resolução CGIBS 6/2026 | — | Sim |
| `100501` | Demais bens, em operações onerosas | Realização de demais operações com bens não especificadas em outros indicadores | Local do domicílio principal do adquirente residente ou domiciliado no País. Nas aquisições indicadas no art. 11, §4º, II, considera-se domicílio principal do adquirente o estabelecimento matriz | Art. 11, X, "a", 1 e §4º, II | — | — | — |
| `100502` | Demais bens, em operações onerosas | Realização de demais operações com bens não especificadas em outros indicadores | Local do domicílio principal do destinatário residente ou domiciliado no País, caso o adquirente não seja residente ou domiciliado no País | Art. 11, X, "a", 2 | — | — | — |
| `100601` | Demais bens, em operações não onerosas | Realização de demais operações com bens não especificadas em outros indicadores | local do domicílio principal do destinatário residente ou domiciliado no País | Art. 11, X, "b" | — | — | — |
| `110101` | Operações com abastecimento de água, gás canalizado e energia elétrica | Operações destinadas a consumo | Local da entrega ou disponibilização | Art. 11, §7º, I | — | — | — |
| `110201` | Operações com abastecimento de água, gás canalizado e energia elétrica | Operações que não envolvam efetivo consumo: a) no fornecimento de serviços de transmissão de energia elétrica; e b) nas demais operações, inclusive nas hipóteses de geração, distribuição ou comercialização de energia elétrica. | Local do estabelecimento principal do adquirente (assim considerada a matriz), conforme §4º do art. 11 | Art. 11, §7º, II | — | — | — |
| `120101` | Nas aquisições de energia elétrica realizadas de forma multilateral | Disponibilização de energia elétrica | Local do estabelecimento do agente ou de seus representados que figurem na posição devedora da liquidação financeira apurada pela Câmara de Comercialização de Energia Elétrica | Art. 11, §9º | — | — | — |
| `130101` | Operações de transporte dutoviário de gás natural | Execução do transporte dutoviário de gás natural, na contratação de capacidade de entrada de gás natural do duto, nos termos da legislação aplicável | Local do estabelecimento principal do fornecedor | Art. 11, §10, I | — | — | — |
| `130201` | Operações de transporte dutoviário de gás natural | Execução do transporte dutoviário de gás natural, na contratação de capacidade de saída do gás natural do duto | Local do estabelecimento principal do adquirente | Art. 11, §10, II | — | — | — |

---

## Tabelas de Referência

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/index.md

# Tabelas de Referência

Uma lista das tabelas de referência disponíveis para a seção "Reforma Tributária":

- [Tabela de Correlação - LC 116, NBS, Indicador de Operação e Classificação Tributária](/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-correlacao-nbs-lc116/)
- [Tabela de Referência - CST e Classificação Tributária (IBS/CBS)](/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-cst-classificacao-tributaria-ibs-cbs/)
- [Tabela de Referência - Indicador da Operação (indOp)](/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-indicador-operacao/)
- [Tabela de Referência - Comércio Exterior (`foreignTrade`)](/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-referencia-comercio-exterior/)

---

## Tabela de Correlação - LC 116, NBS, Indicador de Operação e Classificação Tributária

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/tabela-correlacao-nbs-lc116/index.md

# Tabela de Correlação - LC 116, NBS, Indicador de Operação e Classificação Tributária

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

Esta tabela detalha a correlação sugerida entre o Item da Lista de Serviço (LC 116), o código NBS, o Indicador de Operação (`indOp`) e a Classificação Tributária (`cClassTrib`) para diversos serviços. Os dados reproduzem o **Anexo VIII (Correlação Item NBS / `indOp` / `cClassTrib`) v1.01.00** do Ambiente de Dados Nacional (ADN).

### Definição dos Campos
*   **Item LC 116:** Código do serviço conforme a Lei Complementar 116/2003.
*   **Código NBS:** Nomenclatura Brasileira de Serviços.
*   **Indicador da Operação:** Define a natureza da operação e determina o local de incidência do IBS/CBS (ex: `020201` para serviços sobre bens imóveis).
*   **Classificação Tributária:** Define o tratamento tributário específico da operação para o IBS/CBS (ex: `000001` para tributação integral).

:::warning

**Nota Técnica:** A combinação do *Item LC 116* com um *NBS* incorreto resultará na Rejeição 345 (Código NBS inválido para o item de serviço).

:::

| Item LC 116 | Descrição LC 116 | Código NBS | Descrição NBS | Indicador da Operação (`indOp`) | Classificação Tributária (`cClassTrib`) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1502.10.00 | Serviços de projeto, desenvolvimento e instalação de aplicativos e programas não customizáveis | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1502.20.00 | Serviços de projeto, desenvolvimento, adaptação e instalação de aplicativos e programas customizáveis | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1502.40.00 | Serviços de projeto e desenvolvimento de estruturas e conteúdo de bancos de dados | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1502.50.00 | Serviços de integração de sistemas de tecnologia da informação (TI) | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1502.90.00 | Serviços de projeto e desenvolvimento de aplicativos e programas de TI não classificados em outras subposições | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1502.90.00 | Serviços de projeto e desenvolvimento de aplicativos e programas de TI não classificados em outras subposições | 100301 | 200043 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1502.90.00 | Serviços de projeto e desenvolvimento de aplicativos e programas de TI não classificados em outras subposições | 100301 | 200044 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1503.00.00 | Serviços de projeto e desenvolvimento de redes de TI | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1504.00.00 | Serviços de projeto e desenvolvimento de topografias de circuitos integrados | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1505.00.00 | Serviços de projeto de circuitos integrados | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1507.10.00 | Serviços de gerenciamento de redes de TI | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1507.20.00 | Serviços de gerenciamento de sistemas de computadores | 100301 | 000001 |
| 01.01 | Análise e desenvolvimento de sistemas. | 1.1507.90.00 | Serviços de gerenciamento de infraestrutura de TI não classificados em outras subposições | 100301 | 000001 |
| 01.02 | Programação. | 1.1502.10.00 | Serviços de projeto, desenvolvimento e instalação de aplicativos e programas não customizáveis | 100301 | 000001 |
| 01.02 | Programação. | 1.1502.20.00 | Serviços de projeto, desenvolvimento, adaptação e instalação de aplicativos e programas customizáveis | 100301 | 000001 |
| 01.02 | Programação. | 1.1502.90.00 | Serviços de projeto e desenvolvimento de aplicativos e programas de TI não classificados em outras subposições | 100301 | 000001 |
| 01.02 | Programação. | 1.1502.90.00 | Serviços de projeto e desenvolvimento de aplicativos e programas de TI não classificados em outras subposições | 100301 | 200043 |
| 01.02 | Programação. | 1.1502.90.00 | Serviços de projeto e desenvolvimento de aplicativos e programas de TI não classificados em outras subposições | 100301 | 200044 |
| 01.03 | Processamento, armazenamento ou hospedagem... | 1.1506.10.00 | Serviços de hospedagem de páginas na rede mundial de computadores (World Wide Web) | 100301 | 000001 |
| 01.03 | Processamento, armazenamento ou hospedagem... | 1.1506.21.00 | Serviços de hospedagem de aplicativos e software como serviço (SaaS) | 100301 | 000001 |
| 01.03 | Processamento, armazenamento ou hospedagem... | 1.1506.22.00 | Serviços de provimento de infraestrutura como serviço (IaaS) | 100301 | 000001 |
| 01.03 | Processamento, armazenamento ou hospedagem... | 1.1506.23.00 | Serviços de provimento de plataforma como serviço (PaaS) | 100301 | 000001 |
| 01.03 | Processamento, armazenamento ou hospedagem... | 1.1506.29.00 | Serviços de hospedagem de aplicativos e programas não classificados em outras subposições | 100301 | 000001 |
| 01.03 | Processamento, armazenamento ou hospedagem... | 1.1506.90.00 | Serviços de hospedagem e provimento de infraestrutura de TI não classificados em outras subposições | 100301 | 000001 |
| 01.03 | Processamento, armazenamento ou hospedagem... | 1.1509.00.00 | Serviços de processamento de dados | 100301 | 000001 |
| 01.04 | Elaboração de programas de computadores... | 1.1502.10.00 | Serviços de projeto, desenvolvimento e instalação de aplicativos e programas não customizáveis | 100301 | 000001 |
| 01.04 | Elaboração de programas de computadores... | 1.1502.20.00 | Serviços de projeto, desenvolvimento, adaptação e instalação de aplicativos e programas customizáveis | 100301 | 000001 |
| 01.04 | Elaboração de programas de computadores... | 1.1502.90.00 | Serviços de projeto e desenvolvimento de aplicativos e programas de TI não classificados em outras subposições | 100301 | 000001 |
| 01.04 | Elaboração de programas de computadores... | 1.1502.90.00 | Serviços de projeto e desenvolvimento de aplicativos e programas de TI não classificados em outras subposições | 100301 | 200043 |
| 01.04 | Elaboração de programas de computadores... | 1.1502.90.00 | Serviços de projeto e desenvolvimento de aplicativos e programas de TI não classificados em outras subposições | 100301 | 200044 |
| 01.05 | Licenciamento ou cessão de direito... | 1.1103.21.00 | Licenciamento de direitos para a produção, distribuição ou comercialização de programas de computador (software) | 100501 | 000001 |
| 01.05 | Licenciamento ou cessão de direito... | 1.1103.22.00 | Licenciamento de direitos de uso de programas de computador (software) | 100501 | 000001 |
| 01.05 | Licenciamento ou cessão de direito... | 1.1103.23.00 | Licenciamento de direitos sobre bancos de dados | 100501 | 000001 |
| 01.05 | Licenciamento ou cessão de direito... | 1.1103.29.00 | Licenciamento de direitos sobre programas de computador (software) e bancos de dados não classificados em outras subposições | 100501 | 000001 |
| 01.05 | Licenciamento ou cessão de direito... | 1.1106.20.00 | Cessão temporária de direitos sobre programas de computador (software) | 100501 | 000001 |
| 01.05 | Licenciamento ou cessão de direito... | 1.1107.20.00 | Cessão permanente de direitos sobre programas de computador (software) | 100501 | 000001 |
| 01.05 | Licenciamento ou cessão de direito... | 1.1506.21.00 | Serviços de hospedagem de aplicativos e software como serviço (SaaS) | 100501 | 000001 |
| 01.06 | Assessoria e consultoria em informática. | 1.1501.10.00 | Serviços de consultoria em tecnologia da informação (TI) | 100301 | 000001 |
| 01.06 | Assessoria e consultoria em informática. | 1.1501.20.00 | Serviços de segurança em tecnologia da informação (TI) | 100301 | 000001 |
| 01.06 | Assessoria e consultoria em informática. | 1.1501.20.00 | Serviços de segurança em tecnologia da informação (TI) | 100301 | 200043 |
| 01.06 | Assessoria e consultoria em informática. | 1.1501.20.00 | Serviços de segurança em tecnologia da informação (TI) | 100301 | 200044 |
| 01.06 | Assessoria e consultoria em informática. | 1.1507.10.00 | Serviços de gerenciamento de redes de TI | 100301 | 000001 |
| 01.06 | Assessoria e consultoria em informática. | 1.1507.20.00 | Serviços de gerenciamento de sistemas de computadores | 100301 | 000001 |
| 01.06 | Assessoria e consultoria em informática. | 1.1507.90.00 | Serviços de gerenciamento de infraestrutura de TI não classificados em outras subposições | 100301 | 000001 |
| 01.06 | Assessoria e consultoria em informática. | 1.1510.00.00 | Serviços de tecnologia da informação (TI) não classificados em outras subposições | 100301 | 000001 |
| 01.06 | Assessoria e consultoria em informática. | 1.1510.00.00 | Serviços de tecnologia da informação (TI) não classificados em outras subposições | 100301 | 200043 |
| 01.06 | Assessoria e consultoria em informática. | 1.1510.00.00 | Serviços de tecnologia da informação (TI) não classificados em outras subposições | 100301 | 200044 |
| 01.07 | Suporte técnico em informática... | 1.1501.30.00 | Serviços de suporte em tecnologia da informação (TI) | 050101 | 000001 |
| 01.07 | Suporte técnico em informática... | 1.1501.30.00 | Serviços de suporte em tecnologia da informação (TI) | 050102 | 000001 |
| 01.07 | Suporte técnico em informática... | 1.1501.30.00 | Serviços de suporte em tecnologia da informação (TI) | 100301 | 000001 |
| 01.07 | Suporte técnico em informática... | 1.1508.00.00 | Serviços de manutenção de aplicativos e programas | 100301 | 000001 |
| 01.07 | Suporte técnico em informática... | 1.1502.10.00 | Serviços de projeto, desenvolvimento e instalação de aplicativos e programas não customizáveis | 100301 | 000001 |
| 01.07 | Suporte técnico em informática... | 1.1502.20.00 | Serviços de projeto, desenvolvimento, adaptação e instalação de aplicativos e programas customizáveis | 100301 | 000001 |
| 01.08 | Planejamento, confecção, manutenção... | 1.1502.30.00 | Serviços de projeto e desenvolvimento de estruturas e conteúdo de páginas da Internet | 100301 | 000001 |
| 01.08 | Planejamento, confecção, manutenção... | 1.1502.30.00 | Serviços de projeto e desenvolvimento de estruturas e conteúdo de páginas da Internet | 100301 | 200040 |
| 01.09 | Disponibilização, sem cessão definitiva... | 1.1703.10.00 | Serviços de oferta de livros, jornais, periódicos, diretórios e mala direta online | 100301 | 000001 |
| 01.09 | Disponibilização, sem cessão definitiva... | 1.1703.21.00 | Serviços de oferta de áudio para download | 100301 | 000001 |
| 01.09 | Disponibilização, sem cessão definitiva... | 1.1703.22.00 | Serviços de oferta de conteúdo de áudio por streaming | 100301 | 000001 |
| 01.09 | Disponibilização, sem cessão definitiva... | 1.1703.31.00 | Serviços de oferta de arquivos contendo filmes e vídeos para download | 100301 | 000001 |
| 01.09 | Disponibilização, sem cessão definitiva... | 1.1703.32.00 | Serviços de oferta de filmes e vídeos por streaming | 100301 | 000001 |
| 01.09 | Disponibilização, sem cessão definitiva... | 1.1703.91.00 | Serviços de oferta de jogos online | 100301 | 000001 |
| 01.09 | Disponibilização, sem cessão definitiva... | 1.1703.92.00 | Serviços de oferta de conteúdo de portais de busca na rede mundial de computadores | 100301 | 000001 |
| 01.09 | Disponibilização, sem cessão definitiva... | 1.1703.99.00 | Serviços de oferta de outros conteúdos online não classificados em outras subposições | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.11.00 | Serviços de pesquisa e desenvolvimento em ciências físicas | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.11.00 | Serviços de pesquisa e desenvolvimento em ciências físicas | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.12.00 | Serviços de pesquisa e desenvolvimento em química e biologia | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.12.00 | Serviços de pesquisa e desenvolvimento em química e biologia | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.19.00 | Serviços de pesquisa e desenvolvimento em ciências não classificados em outras subposições | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.19.00 | Serviços de pesquisa e desenvolvimento em ciências não classificados em outras subposições | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.20.00 | Serviços de pesquisa e desenvolvimento em biotecnologia | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.20.00 | Serviços de pesquisa e desenvolvimento em biotecnologia | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.31.00 | Serviços de pesquisa e desenvolvimento em Tecnologia da Informação e Comunicação (TIC) | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.31.00 | Serviços de pesquisa e desenvolvimento em Tecnologia da Informação e Comunicação (TIC) | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.32.00 | Serviços de pesquisa e desenvolvimento em nanotecnologia | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.32.00 | Serviços de pesquisa e desenvolvimento em nanotecnologia | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.33.00 | Serviços de pesquisa e desenvolvimento em engenharia e tecnologia nuclear | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.33.00 | Serviços de pesquisa e desenvolvimento em engenharia e tecnologia nuclear | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.34.00 | Serviços de pesquisa e desenvolvimento em engenharia e tecnologia de micro-ondas de potência | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.34.00 | Serviços de pesquisa e desenvolvimento em engenharia e tecnologia de micro-ondas de potência | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.39.00 | Serviços de pesquisa e desenvolvimento em engenharia e tecnologia não classificados em outras subposições | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.39.00 | Serviços de pesquisa e desenvolvimento em engenharia e tecnologia não classificados em outras subposições | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.40.00 | Serviços de pesquisa e desenvolvimento em ciências médicas, odontológicas e farmacêuticas | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.40.00 | Serviços de pesquisa e desenvolvimento em ciências médicas, odontológicas e farmacêuticas | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.50.00 | Serviços de pesquisa e desenvolvimento em ciências agrícolas | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.50.00 | Serviços de pesquisa e desenvolvimento em ciências agrícolas | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.90.00 | Serviços de pesquisa e desenvolvimento em ciências, engenharia e tecnologia não classificados em outras subposições | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1201.90.00 | Serviços de pesquisa e desenvolvimento em ciências, engenharia e tecnologia não classificados em outras subposições | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.10.00 | Serviços de pesquisa e desenvolvimento em psicologia | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.10.00 | Serviços de pesquisa e desenvolvimento em psicologia | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.20.00 | Serviços de pesquisa e desenvolvimento em ciências econômicas | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.20.00 | Serviços de pesquisa e desenvolvimento em ciências econômicas | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.30.00 | Serviços de pesquisa e desenvolvimento em direito | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.30.00 | Serviços de pesquisa e desenvolvimento em direito | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.40.00 | Serviços de pesquisa e desenvolvimento em línguas e literatura | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.40.00 | Serviços de pesquisa e desenvolvimento em línguas e literatura | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.90.00 | Serviços de pesquisa e desenvolvimento em ciências sociais e humanas não classificados em outras subposições | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1202.90.00 | Serviços de pesquisa e desenvolvimento em ciências sociais e humanas não classificados em outras subposições | 100301 | 200016 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1203.00.00 | Serviços de pesquisa e desenvolvimento interdisciplinares | 100301 | 000001 |
| 02.01 | Pesquisa e desenvolvimento... | 1.1203.00.00 | Serviços de pesquisa e desenvolvimento interdisciplinares | 100301 | 200016 |
| 03.02 | Cessão de direito de uso... | 1.1103.33.00 | Licenciamento de direitos autorais de obras publicitárias | 100501 | 000001 |
| 03.02 | Cessão de direito de uso... | 1.1104.20.00 | Licenciamento de direitos sobre marcas | 100501 | 000001 |
| 03.02 | Cessão de direito de uso... | 1.1106.33.00 | Cessão temporária de direitos autorais de obras publicitárias | 100501 | 000001 |
| 03.02 | Cessão de direito de uso... | 1.1107.33.00 | Cessão permanente de direitos de obras publicitárias | 100501 | 000001 |
| 03.02 | Cessão de direito de uso... | 1.1108.20.00 | Cessão permanente de direitos sobre marcas | 100501 | 000001 |
| 03.03 | Exploração de salões de festas... | 1.1805.31.00 | Serviços de reserva para centros de convenções, auditórios e salões de exposição | 020101 | 200027 |
| 03.03 | Exploração de salões de festas... | 1.1806.61.00 | Serviços de assistência e organização de convenções | 020101 | 200027 |
| 03.03 | Exploração de salões de festas... | 1.1806.62.00 | Serviços de assistência e organização de feiras comerciais | 020101 | 200027 |
| 03.03 | Exploração de salões de festas... | 1.1806.63.00 | Serviços de assistência e organização de exposições e outros eventos | 020101 | 200027 |
| 03.03 | Exploração de salões de festas... | 1.2508.00.00 | Serviços recreativos, culturais e desportivos não classificados em outras posições | 020101 | 200027 |
| 03.04 | Locação, sublocação, arrendamento... | 1.1001.12.10 | Administração e locação, sublocação, arrendamento, direito de passagem ou permissão de uso, compartilhado ou não, de ferrovia, rodovia, postes, cabos, dutos e condutos de qualquer natureza | 020201 | 200027 |
| 03.05 | Cessão de andaimes... | 1.0105.70.00 | Serviços de andaimes | 050101 | 000001 |
| 03.05 | Cessão de andaimes... | 1.0105.70.00 | Serviços de andaimes | 050102 | 000001 |
| 03.05 | Cessão de andaimes... | 1.0105.50.00 | Serviços de montagem de estruturas de aço | 050101 | 000001 |
| 03.05 | Cessão de andaimes... | 1.0105.50.00 | Serviços de montagem de estruturas de aço | 050102 | 000001 |
| 03.05 | Cessão de andaimes... | 1.0105.50.00 | Serviços de montagem de estruturas de aço | 050101 | 200039 |
| 03.05 | Cessão de andaimes... | 1.0105.50.00 | Serviços de montagem de estruturas de aço | 050102 | 200039 |
| 04.01 | Medicina e biomedicina. | 1.2301.22.00 | Serviços médicos especializados | 030101 | 200029 |
| 04.01 | Medicina e biomedicina. | 1.2301.22.00 | Serviços médicos especializados | 030102 | 200029 |
| 04.01 | Medicina e biomedicina. | 1.2301.22.00 | Serviços médicos especializados | 100301 | 200029 |
| 04.02 | Análises clínicas, patologia... | 1.2301.93.00 | Serviços de laboratório | 030101 | 200029 |
| 04.02 | Análises clínicas, patologia... | 1.2301.93.00 | Serviços de laboratório | 030102 | 200029 |
| 04.02 | Análises clínicas, patologia... | 1.2301.93.00 | Serviços de laboratório | 100301 | 200029 |
| 04.02 | Análises clínicas, patologia... | 1.2301.94.00 | Serviços de diagnóstico por imagem | 030101 | 200029 |
| 04.02 | Análises clínicas, patologia... | 1.2301.94.00 | Serviços de diagnóstico por imagem | 030102 | 200029 |
| 04.02 | Análises clínicas, patologia... | 1.2301.94.00 | Serviços de diagnóstico por imagem | 100301 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.11.00 | Serviços cirúrgicos | 030101 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.11.00 | Serviços cirúrgicos | 030102 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.12.00 | Serviços ginecológicos e obstétricos | 030101 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.12.00 | Serviços ginecológicos e obstétricos | 030102 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.13.00 | Serviços psiquiátricos | 030101 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.13.00 | Serviços psiquiátricos | 030102 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.14.00 | Serviços prestados em Unidades de Terapia Intensiva | 030101 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.14.00 | Serviços prestados em Unidades de Terapia Intensiva | 030102 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.15.00 | Serviços de atendimento de emergência | 030101 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.15.00 | Serviços de atendimento de emergência | 030102 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.19.00 | Serviços hospitalares não classificados em outras subposições | 030101 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.19.00 | Serviços hospitalares não classificados em outras subposições | 030102 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.21.00 | Serviços de clínica médica | 030101 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.21.00 | Serviços de clínica médica | 030102 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.93.00 | Serviços de laboratório | 030101 | 200029 |
| 04.03 | Hospitais, clínicas, laboratórios... | 1.2301.93.00 | Serviços de laboratório | 030102 | 200029 |
| 04.04 | Instrumentação cirúrgica. | 1.2301.11.00 | Serviços cirúrgicos | 030101 | 200029 |
| 04.04 | Instrumentação cirúrgica. | 1.2301.11.00 | Serviços cirúrgicos | 030102 | 200029 |
| 04.05 | Acupuntura. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030101 | 200029 |
| 04.05 | Acupuntura. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030102 | 200029 |
| 04.06 | Enfermagem, inclusive auxiliar... | 1.2301.91.00 | Serviços de enfermagem | 030101 | 200029 |
| 04.06 | Enfermagem, inclusive auxiliar... | 1.2301.91.00 | Serviços de enfermagem | 030102 | 200029 |
| 04.06 | Enfermagem, inclusive auxiliar... | 1.2301.97.00 | Serviços de assistência ao parto e pós-parto | 030101 | 200029 |
| 04.06 | Enfermagem, inclusive auxiliar... | 1.2301.97.00 | Serviços de assistência ao parto e pós-parto | 030102 | 200029 |
| 04.07 | Serviços farmacêuticos. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030101 | 200029 |
| 04.07 | Serviços farmacêuticos. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030102 | 200029 |
| 04.07 | Serviços farmacêuticos. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 100301 | 200029 |
| 04.08 | Terapia ocupacional, fisioterapia... | 1.2301.92.00 | Serviços de fisioterapia | 030101 | 200029 |
| 04.08 | Terapia ocupacional, fisioterapia... | 1.2301.92.00 | Serviços de fisioterapia | 030102 | 200029 |
| 04.08 | Terapia ocupacional, fisioterapia... | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030101 | 200029 |
| 04.08 | Terapia ocupacional, fisioterapia... | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030102 | 200029 |
| 04.09 | Terapias de qualquer espécie... | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030101 | 200029 |
| 04.09 | Terapias de qualquer espécie... | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030102 | 200029 |
| 04.09 | Terapias de qualquer espécie... | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 100301 | 200029 |
| 04.10 | Nutrição. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030101 | 200029 |
| 04.10 | Nutrição. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030102 | 200029 |
| 04.10 | Nutrição. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 100301 | 200029 |
| 04.11 | Obstetrícia. | 1.2301.12.00 | Serviços ginecológicos e obstétricos | 030101 | 200029 |
| 04.11 | Obstetrícia. | 1.2301.12.00 | Serviços ginecológicos e obstétricos | 030102 | 200029 |
| 04.11 | Obstetrícia. | 1.2301.97.00 | Serviços de assistência ao parto e pós-parto | 030101 | 200029 |
| 04.11 | Obstetrícia. | 1.2301.97.00 | Serviços de assistência ao parto e pós-parto | 030102 | 200029 |
| 04.12 | Odontologia. | 1.2301.23.00 | Serviços odontológicos | 030101 | 200029 |
| 04.12 | Odontologia. | 1.2301.23.00 | Serviços odontológicos | 030102 | 200029 |
| 04.13 | Ortóptica. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030101 | 200029 |
| 04.13 | Ortóptica. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030102 | 200029 |
| 04.14 | Próteses sob encomenda. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 100301 | 200029 |
| 04.15 | Psicanálise. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030101 | 200029 |
| 04.15 | Psicanálise. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 030102 | 200029 |
| 04.15 | Psicanálise. | 1.2301.99.00 | Outros serviços de saúde humana não classificados em outras subposições | 100301 | 200029 |
| 04.16 | Psicologia. | 1.2301.98.00 | Serviços de psicologia | 030101 | 200029 |
| 04.16 | Psicologia. | 1.2301.98.00 | Serviços de psicologia | 030102 | 200029 |
| 04.16 | Psicologia. | 1.2301.98.00 | Serviços de psicologia | 100301 | 200029 |
| 04.17 | Casas de repouso e de recuperação... | 1.2201.11.00 | Serviços de creche ou entidade equivalente | 030101 | 200029 |
| 04.17 | Casas de repouso e de recuperação... | 1.2302.10.00 | Serviços de cuidados de saúde em instalações de cuidados residenciais | 030101 | 200029 |
| 04.17 | Casas de repouso e de recuperação... | 1.2302.21.00 | Serviços de assistência a idosos em instalações de cuidados residenciais | 030101 | 200029 |
| 04.17 | Casas de repouso e de recuperação... | 1.2302.22.00 | Serviços de assistência a crianças e adolescentes com deficiência... | 030101 | 200029 |
| 04.17 | Casas de repouso e de recuperação... | 1.2302.23.00 | Serviços de assistência a adultos com deficiência em instalações de cuidados residenciais | 030101 | 200029 |
| 04.17 | Casas de repouso e de recuperação... | 1.2303.00.00 | Serviços de assistência social com alojamento | 030101 | 200029 |
| 04.18 | Inseminação artificial... | 1.2301.21.00 | Serviços de clínica médica | 030101 | 200029 |
| 04.18 | Inseminação artificial... | 1.2301.21.00 | Serviços de clínica médica | 030102 | 200029 |
| 04.19 | Bancos de sangue, leite, pele, olhos... | 1.2301.95.00 | Serviços de banco de material biológico humano | 050101 | 200029 |
| 04.20 | Coleta de sangue, leite, tecidos... | 1.2301.95.00 | Serviços de banco de material biológico humano | 030101 | 200029 |
| 04.20 | Coleta de sangue, leite, tecidos... | 1.2301.95.00 | Serviços de banco de material biológico humano | 030102 | 200029 |
| 04.21 | Unidade de atendimento, assistência ou... | 1.2301.96.00 | Serviços de ambulância | 030101 | 200029 |
| 04.21 | Unidade de atendimento, assistência ou... | 1.2301.96.00 | Serviços de ambulância | 030102 | 200029 |
| 04.22 | Planos de medicina de grupo ou individual... | 1.0910.10.00 | Serviços de planos privados de assistência à saúde | 100301 | 820001 |
| 04.22 | Planos de medicina de grupo ou individual... | 1.0910.90.00 | Serviços de planos privados de assistência à saúde e serviços relacionados não classificados... | 100301 | 820001 |
| 04.23 | Outros planos de saúde... | 1.0910.10.00 | Serviços de planos privados de assistência à saúde | 100301 | 820001 |
| 04.23 | Outros planos de saúde... | 1.0910.90.00 | Serviços de planos privados de assistência à saúde e serviços relacionados não classificados... | 100301 | 820001 |
| 05.01 | Medicina veterinária e zootecnia. | 1.1405.12.00 | Serviços de cuidado, assistência ou tratamento de animais domésticos | 050101 | 200052 |
| 05.01 | Medicina veterinária e zootecnia. | 1.1405.12.00 | Serviços de cuidado, assistência ou tratamento de animais domésticos | 050102 | 200052 |
| 05.01 | Medicina veterinária e zootecnia. | 1.1405.22.00 | Serviços de cuidado, assistência ou tratamento de animais de produção | 050101 | 200038 |
| 05.01 | Medicina veterinária e zootecnia. | 1.1405.22.00 | Serviços de cuidado, assistência ou tratamento de animais de produção | 050102 | 200038 |
| 05.01 | Medicina veterinária e zootecnia. | 1.1405.90.00 | Serviços veterinários não classificados em outras subposições | 050101 | 200052 |
| 05.01 | Medicina veterinária e zootecnia. | 1.1405.90.00 | Serviços veterinários não classificados em outras subposições | 050102 | 200052 |
| 05.02 | Hospitais, clínicas, ambulatórios... | 1.1405.11.00 | Serviços hospitalares, com ou sem internação, para animais domésticos | 050101 | 000001 |
| 05.02 | Hospitais, clínicas, ambulatórios... | 1.1405.12.00 | Serviços de cuidado, assistência ou tratamento de animais domésticos | 050101 | 000001 |
| 05.02 | Hospitais, clínicas, ambulatórios... | 1.1405.21.00 | Serviços hospitalares, com ou sem internação, para animais de produção | 050101 | 200038 |
| 05.02 | Hospitais, clínicas, ambulatórios... | 1.1405.22.00 | Serviços de cuidado, assistência ou tratamento de animais de produção | 050101 | 200038 |
| 05.03 | Laboratórios de análise na área... | 1.1405.90.00 | Serviços veterinários não classificados em outras subposições | 050101 | 000001 |
| 05.03 | Laboratórios de análise na área... | 1.1405.90.00 | Serviços veterinários não classificados em outras subposições | 050101 | 200038 |
| 05.04 | Inseminação artificial... | 1.1405.90.00 | Serviços veterinários não classificados em outras subposições | 050101 | 000001 |
| 05.04 | Inseminação artificial... | 1.1405.90.00 | Serviços veterinários não classificados em outras subposições | 050102 | 000001 |
| 05.04 | Inseminação artificial... | 1.1405.90.00 | Serviços veterinários não classificados em outras subposições | 050101 | 200038 |
| 05.04 | Inseminação artificial... | 1.1405.90.00 | Serviços veterinários não classificados em outras subposições | 050102 | 200038 |
| 05.05 | Bancos de sangue e de órgãos... | 1.1405.40.00 | Serviços de banco de órgãos, sangue, sêmen, tecidos, óvulos e outros materiais biológicos | 050101 | 000001 |
| 05.06 | Coleta de sangue, leite... | 1.1405.40.00 | Serviços de banco de órgãos, sangue, sêmen, tecidos, óvulos e outros materiais biológicos | 050101 | 000001 |
| 05.06 | Coleta de sangue, leite... | 1.1405.40.00 | Serviços de banco de órgãos, sangue, sêmen, tecidos, óvulos e outros materiais biológicos | 050102 | 000001 |
| 05.07 | Unidade de atendimento, assistência ou... | 1.1405.12.00 | Serviços de cuidado, assistência ou tratamento de animais domésticos | 050101 | 000001 |
| 05.07 | Unidade de atendimento, assistência ou... | 1.1405.12.00 | Serviços de cuidado, assistência ou tratamento de animais domésticos | 050102 | 000001 |
| 05.07 | Unidade de atendimento, assistência ou... | 1.1405.22.00 | Serviços de cuidado, assistência ou tratamento de animais de produção | 050101 | 200038 |
| 05.07 | Unidade de atendimento, assistência ou... | 1.1405.22.00 | Serviços de cuidado, assistência ou tratamento de animais de produção | 050102 | 200038 |
| 05.08 | Guarda, tratamento, amestramento... | 1.1405.60.00 | Serviços de guarda, treinamento, embelezamento e alojamento | 050101 | 000001 |
| 05.08 | Guarda, tratamento, amestramento... | 1.1405.60.00 | Serviços de guarda, treinamento, embelezamento e alojamento | 050102 | 000001 |
| 05.09 | Planos de atendimento e assistência... | 1.1405.50.00 | Planos de atendimento e assistência médico-veterinária | 100301 | 820003 |
| 06.01 | Barbearias, cabeleireiros... | 1.2602.10.00 | Serviços de cabeleireiro e barbeiro | 030101 | 000001 |
| 06.01 | Barbearias, cabeleireiros... | 1.2602.10.00 | Serviços de cabeleireiro e barbeiro | 030102 | 000001 |
| 06.01 | Barbearias, cabeleireiros... | 1.2602.20.00 | Serviços de manicure, pedicure e tratamento cosmético | 030101 | 000001 |
| 06.01 | Barbearias, cabeleireiros... | 1.2602.20.00 | Serviços de manicure, pedicure e tratamento cosmético | 030102 | 000001 |
| 06.02 | Esteticistas, tratamento de pele... | 1.2602.20.00 | Serviços de manicure, pedicure e tratamento cosmético | 030101 | 000001 |
| 06.02 | Esteticistas, tratamento de pele... | 1.2602.20.00 | Serviços de manicure, pedicure e tratamento cosmético | 030102 | 000001 |
| 06.02 | Esteticistas, tratamento de pele... | 1.2602.30.00 | Serviços de bem-estar físico | 030101 | 000001 |
| 06.02 | Esteticistas, tratamento de pele... | 1.2602.30.00 | Serviços de bem-estar físico | 030102 | 000001 |
| 06.02 | Esteticistas, tratamento de pele... | 1.2602.90.00 | Serviços de tratamento de beleza e bem-estar físico não classificados... | 030101 | 000001 |
| 06.02 | Esteticistas, tratamento de pele... | 1.2602.90.00 | Serviços de tratamento de beleza e bem-estar físico não classificados... | 030102 | 000001 |
| 06.03 | Banhos, duchas, sauna, massagens... | 1.2602.30.00 | Serviços de bem-estar físico | 030101 | 000001 |
| 06.03 | Banhos, duchas, sauna, massagens... | 1.2602.30.00 | Serviços de bem-estar físico | 030102 | 000001 |
| 06.04 | Ginástica, dança, esportes... | 1.2205.12.00 | Serviços de educação desportiva e recreacional | 030101 | 200041 |
| 06.04 | Ginástica, dança, esportes... | 1.2205.12.00 | Serviços de educação desportiva e recreacional | 030102 | 200041 |
| 06.04 | Ginástica, dança, esportes... | 1.2505.90.00 | Serviços desportivos e recreacionais desportivos não classificados em outras subposições | 030101 | 000001 |
| 06.04 | Ginástica, dança, esportes... | 1.2505.90.00 | Serviços desportivos e recreacionais desportivos não classificados em outras subposições | 030102 | 000001 |
| 06.04 | Ginástica, dança, esportes... | 1.2505.90.00 | Serviços desportivos e recreacionais desportivos não classificados em outras subposições | 100301 | 000001 |
| 06.04 | Ginástica, dança, esportes... | 1.2602.30.00 | Serviços de bem-estar físico | 030101 | 000001 |
| 06.04 | Ginástica, dança, esportes... | 1.2602.30.00 | Serviços de bem-estar físico | 030102 | 000001 |
| 06.05 | Centros de emagrecimento, spas... | 1.2602.30.00 | Serviços de bem-estar físico | 030101 | 000001 |
| 06.05 | Centros de emagrecimento, spas... | 1.2602.30.00 | Serviços de bem-estar físico | 030102 | 000001 |
| 06.05 | Centros de emagrecimento, spas... | 1.2602.90.00 | Serviços de tratamento de beleza e bem-estar físico não classificados... | 030101 | 000001 |
| 06.05 | Centros de emagrecimento, spas... | 1.2602.90.00 | Serviços de tratamento de beleza e bem-estar físico não classificados... | 030102 | 000001 |
| 06.06 | Aplicação de tatuagens, piercings... | 1.2602.90.00 | Serviços de tratamento de beleza e bem-estar físico não classificados... | 030101 | 000001 |
| 06.06 | Aplicação de tatuagens, piercings... | 1.2602.90.00 | Serviços de tratamento de beleza e bem-estar físico não classificados... | 030102 | 000001 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1402.11.00 | Serviços de consultoria em arquitetura | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1402.12.00 | Serviços de arquitetura para projetos de construções residenciais | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1402.13.00 | Serviços de arquitetura para projetos de construções não residenciais | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1402.14.00 | Serviços de arquitetura para restauração de prédios históricos | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1402.21.00 | Serviços de planejamento urbano | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1402.22.00 | Serviços de planejamento de áreas rurais | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1402.31.00 | Serviços de consultoria em paisagismo | 100301 | 000001 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1402.32.00 | Serviços de paisagismo, exceto consultoria | 100301 | 000001 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1402.90.00 | Serviços de arquitetura, de planejamento urbano e de áreas rurais e de paisagismo não classificados... | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.10.00 | Serviços de consultoria em engenharia | 100301 | 200038 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.10.00 | Serviços de consultoria em engenharia | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.21.10 | Serviços de engenharia para projetos de construção residencial | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.21.20 | Serviços de engenharia para projetos de construção não residencial | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.22.11 | Serviços de engenharia para projetos de exploração de minerais | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.22.12 | Serviços de engenharia para projetos de exploração de petróleo e gás | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.22.13 | Serviços de engenharia para projetos de refino de petróleo e petroquímica | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.22.14 | Serviços de engenharia para projetos de unidades de produção de biocombustíveis | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.22.21 | Serviços de engenharia para projetos de veículos terrestres | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.22.22 | Serviços de engenharia para projetos de embarcações | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.22.23 | Serviços de engenharia para projetos de veículos aéreos e aeroespaciais | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.22.90 | Serviços de engenharia para outros projetos industriais e de fabricação... | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.23.00 | Serviços de engenharia para projetos de infraestrutura de transportes | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.24.00 | Serviços de engenharia para projetos de energia | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.25.00 | Serviços de engenharia para projetos de telecomunicações, radiodifusão e televisão | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.26.00 | Serviços de engenharia para projetos de gerenciamento de resíduos (perigosos e não perigosos) | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.27.00 | Serviços de engenharia para projetos de distribuição de água e rede de esgoto | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.29.00 | Serviços de engenharia para outros projetos | 100301 | 200038 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.29.00 | Serviços de engenharia para outros projetos | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.30.00 | Serviços de gerenciamento de projetos de construção | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1403.90.00 | Serviços de engenharia não classificados em outras subposições | 100301 | 200052 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1404.11.00 | Serviços de consultoria geológica e geofísica | 100301 | 000001 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1404.12.00 | Serviços geofísicos | 100301 | 000001 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1404.13.00 | Serviços geoquímicos | 100301 | 000001 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1404.14.00 | Serviços de informações para avaliação e exploração de recursos naturais | 100301 | 000001 |
| 07.01 | Engenharia, agronomia, agrimensura... | 1.1404.19.00 | Serviços geológicos, geofísicos e outros de prospecção não classificados... | 100301 | 000001 |
| 07.02 | Execução, por administração... | 1.0101.11.00 | Serviços de construção de edificações residenciais de um e dois pavimentos | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0101.11.00 | Serviços de construção de edificações residenciais de um e dois pavimentos | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0101.12.00 | Serviços de construção de edificações residenciais com mais de dois pavimentos | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0101.12.00 | Serviços de construção de edificações residenciais com mais de dois pavimentos | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0101.21.00 | Serviços de construção de edificações industriais | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0101.21.00 | Serviços de construção de edificações industriais | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0101.22.00 | Serviços de construção de edificações comerciais | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0101.22.00 | Serviços de construção de edificações comerciais | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0101.29.00 | Serviços de construção de edificações não residenciais não classificados... | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0101.29.00 | Serviços de construção de edificações não residenciais não classificados... | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0101.30.00 | Serviços de construção de edificações de uso misto (residencial e não residencial) | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0101.30.00 | Serviços de construção de edificações de uso misto (residencial e não residencial) | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.11.00 | Serviços de construção de autoestradas (exceto elevadas), ruas e estradas | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.11.00 | Serviços de construção de autoestradas (exceto elevadas), ruas e estradas | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.12.00 | Serviços de construção de ferrovias | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.13.00 | Serviços de construção de pistas de aeroportos e infraestrutura aeroportuária | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.20.00 | Serviços de construção de pontes, autoestradas elevadas e túneis | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.20.00 | Serviços de construção de pontes, autoestradas elevadas e túneis | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.31.00 | Serviços de construção de infraestrutura de proteção e acesso aquaviário | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.31.00 | Serviços de construção de infraestrutura de proteção e acesso aquaviário | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.32.00 | Serviços de construção de infraestrutura de acostagem aquaviária | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.32.00 | Serviços de construção de infraestrutura de acostagem aquaviária | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.33.00 | Serviços de construção de infraestrutura terrestre e obras de engenharia afins em portos | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.34.00 | Serviços de construção de barragens | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.35.10 | Serviços de construção de adutoras em canal aberto | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.35.10 | Serviços de construção de adutoras em canal aberto | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.35.20 | Serviços de construção de sistemas de irrigação | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.35.20 | Serviços de construção de sistemas de irrigação | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.35.20 | Serviços de construção de sistemas de irrigação | 020201 | 200038 |
| 07.02 | Execução, por administração... | 1.0102.35.30 | Serviços de construção relacionados ao controle de cursos d'água, incluindo canalização | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.35.30 | Serviços de construção relacionados ao controle de cursos d'água, incluindo canalização | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.41.10 | Serviços de construção de dutos de longa distância para transporte de petróleo... | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.41.20 | Serviços de construção de dutos de longa distância para transporte e drenagem de água | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.41.90 | Serviços de construção de dutos de longa distância não classificados... | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.42.10 | Serviços de construção de linhas de comunicação de longa distância | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.42.20 | Serviços de construção de linhas de transmissão de alta tensão | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.51.00 | Serviços de construção de dutos locais | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.51.00 | Serviços de construção de dutos locais | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.52.10 | Serviços de construção de linhas de comunicação locais | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.52.10 | Serviços de construção de linhas de comunicação locais | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.52.20 | Serviços de construção de linhas de transmissão locais de baixa e média tensão | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.52.20 | Serviços de construção de linhas de transmissão locais de baixa e média tensão | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.53.10 | Serviços de construção de sistemas de esgoto | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.53.10 | Serviços de construção de sistemas de esgoto | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.53.20 | Serviços de construção de sistemas de estações de elevação, tratamento e purificação de água | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.53.20 | Serviços de construção de sistemas de estações de elevação, tratamento e purificação de água | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.61.00 | Serviços de construção de usinas de geração de energia | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.69.00 | Serviços de construção de instalações industriais não classificados... | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.69.00 | Serviços de construção de instalações industriais não classificados... | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.70.00 | Serviços de construção de minas e suas unidades industriais | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.80.00 | Serviços de construção de instalações para recreação e esportes ao ar livre | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.80.00 | Serviços de construção de instalações para recreação e esportes ao ar livre | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0102.90.00 | Serviços de construção de obras de engenharia civil não classificados... | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0102.90.00 | Serviços de construção de obras de engenharia civil não classificados... | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0103.20.00 | Serviços de preparação de terrenos e canteiros de obras | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0103.20.00 | Serviços de preparação de terrenos e canteiros de obras | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0103.30.00 | Serviços de escavação e terraplenagem | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0103.30.00 | Serviços de escavação e terraplenagem | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0103.41.00 | Serviços de perfuração de poços de água | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0103.41.00 | Serviços de perfuração de poços de água | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0103.42.00 | Serviços de instalação de sistemas sépticos | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0103.42.00 | Serviços de instalação de sistemas sépticos | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0104.00.00 | Serviços de montagem e edificação de construções pré-fabricadas | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0104.00.00 | Serviços de montagem e edificação de construções pré-fabricadas | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0105.11.00 | Serviços de estaqueamento | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0105.11.00 | Serviços de estaqueamento | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0105.12.00 | Serviços de fundação | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0105.12.00 | Serviços de fundação | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0105.21.00 | Serviços de construção de estruturas de edificações | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0105.21.00 | Serviços de construção de estruturas de edificações | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0105.22.00 | Serviços de construção de estruturas de telhados e coberturas | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0105.22.00 | Serviços de construção de estruturas de telhados e coberturas | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0105.30.00 | Serviços de construção de telhados e coberturas e serviços de impermeabilização | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0105.30.00 | Serviços de construção de telhados e coberturas e serviços de impermeabilização | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0105.40.00 | Serviços de concretagem | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0105.40.00 | Serviços de concretagem | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0105.50.00 | Serviços de montagem de estruturas de aço | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0105.50.00 | Serviços de montagem de estruturas de aço | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0105.60.00 | Serviços de alvenaria | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0105.60.00 | Serviços de alvenaria | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0105.90.00 | Serviços especializados de construção não classificados em outras subposições | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0105.90.00 | Serviços especializados de construção não classificados em outras subposições | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0106.11.00 | Serviços de instalação de fiação e componentes elétricos | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0106.11.00 | Serviços de instalação de fiação e componentes elétricos | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0106.19.00 | Serviços de instalação elétrica não classificados em outras subposições | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0106.19.00 | Serviços de instalação elétrica não classificados em outras subposições | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0106.21.00 | Serviços de instalação de tubulação para fornecimento de água | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0106.21.00 | Serviços de instalação de tubulação para fornecimento de água | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0106.22.00 | Serviços de instalação de tubulação para drenagem de água | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0106.22.00 | Serviços de instalação de tubulação para drenagem de água | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0106.60.00 | Serviços de instalação de elevadores, transportadores e escadas rolantes | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0106.60.00 | Serviços de instalação de elevadores, transportadores e escadas rolantes | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0107.30.00 | Serviços de pintura | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0107.30.00 | Serviços de pintura | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0107.40.00 | Serviços de revestimento de pisos e paredes | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0107.40.00 | Serviços de revestimento de pisos e paredes | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0106.32.00 | Serviços de instalação de equipamentos de ventilação e ar condicionado | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0106.32.00 | Serviços de instalação de equipamentos de ventilação e ar condicionado | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0106.40.00 | Serviços de instalação de gás | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0106.40.00 | Serviços de instalação de gás | 020201 | 200045 |
| 07.02 | Execução, por administração... | 1.0107.90.00 | Serviços de acabamento não classificados em outras subposições | 020201 | 200046 |
| 07.02 | Execução, por administração... | 1.0107.90.00 | Serviços de acabamento não classificados em outras subposições | 020201 | 200045 |
| 07.03 | Elaboração de planos diretores... | 1.1402.11.00 | Serviços de consultoria em arquitetura | 100301 | 000001 |
| 07.03 | Elaboração de planos diretores... | 1.1402.11.00 | Serviços de consultoria em arquitetura | 100301 | 200045 |
| 07.03 | Elaboração de planos diretores... | 1.1402.11.00 | Serviços de consultoria em arquitetura | 100301 | 200052 |
| 07.03 | Elaboração de planos diretores... | 1.1403.10.00 | Serviços de consultoria em engenharia | 100301 | 000001 |
| 07.03 | Elaboração de planos diretores... | 1.1403.10.00 | Serviços de consultoria em engenharia | 100301 | 200045 |
| 07.03 | Elaboração de planos diretores... | 1.1403.10.00 | Serviços de consultoria em engenharia | 100301 | 200052 |
| 07.03 | Elaboração de planos diretores... | 1.1402.21.00 | Serviços de planejamento urbano | 100301 | 000001 |
| 07.03 | Elaboração de planos diretores... | 1.1402.21.00 | Serviços de planejamento urbano | 100301 | 200045 |
| 07.03 | Elaboração de planos diretores... | 1.1402.21.00 | Serviços de planejamento urbano | 100301 | 200052 |
| 07.03 | Elaboração de planos diretores... | 1.1402.22.00 | Serviços de planejamento de áreas rurais | 100301 | 000001 |
| 07.03 | Elaboração de planos diretores... | 1.1402.22.00 | Serviços de planejamento de áreas rurais | 100301 | 200052 |
| 07.04 | Demolição. | 1.0103.10.00 | Serviços de demolição | 020201 | 200046 |
| 07.04 | Demolição. | 1.0103.10.00 | Serviços de demolição | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.11.00 | Serviços de construção de edificações residenciais de um e dois pavimentos | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.11.00 | Serviços de construção de edificações residenciais de um e dois pavimentos | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.12.00 | Serviços de construção de edificações residenciais com mais de dois pavimentos | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.12.00 | Serviços de construção de edificações residenciais com mais de dois pavimentos | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.21.00 | Serviços de construção de edificações industriais | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.21.00 | Serviços de construção de edificações industriais | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.22.00 | Serviços de construção de edificações comerciais | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.22.00 | Serviços de construção de edificações comerciais | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.29.00 | Serviços de construção de edificações não residenciais não classificados... | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.29.00 | Serviços de construção de edificações não residenciais não classificados... | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.30.00 | Serviços de construção de edificações de uso misto (residencial e não residencial) | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0101.30.00 | Serviços de construção de edificações de uso misto (residencial e não residencial) | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.11.00 | Serviços de construção de autoestradas (exceto elevadas), ruas e estradas | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.11.00 | Serviços de construção de autoestradas (exceto elevadas), ruas e estradas | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.12.00 | Serviços de construção de ferrovias | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.13.00 | Serviços de construção de pistas de aeroportos e infraestrutura aeroportuária | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.20.00 | Serviços de construção de pontes, autoestradas elevadas e túneis | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.20.00 | Serviços de construção de pontes, autoestradas elevadas e túneis | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.31.00 | Serviços de construção de infraestrutura de proteção e acesso aquaviário | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.31.00 | Serviços de construção de infraestrutura de proteção e acesso aquaviário | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.32.00 | Serviços de construção de infraestrutura de acostagem aquaviária | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.32.00 | Serviços de construção de infraestrutura de acostagem aquaviária | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.33.00 | Serviços de construção de infraestrutura terrestre e obras de engenharia afins em portos | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.34.00 | Serviços de construção de barragens | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.35.10 | Serviços de construção de adutoras em canal aberto | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.35.10 | Serviços de construção de adutoras em canal aberto | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.35.20 | Serviços de construção de sistemas de irrigação | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.35.20 | Serviços de construção de sistemas de irrigação | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.35.20 | Serviços de construção de sistemas de irrigação | 020201 | 200038 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.35.30 | Serviços de construção relacionados ao controle de cursos d'água, incluindo canalização | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.35.30 | Serviços de construção relacionados ao controle de cursos d'água, incluindo canalização | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.41.10 | Serviços de construção de dutos de longa distância para transporte de petróleo... | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.41.20 | Serviços de construção de dutos de longa distância para transporte e drenagem de água | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.41.90 | Serviços de construção de dutos de longa distância não classificados... | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.42.10 | Serviços de construção de linhas de comunicação de longa distância | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.42.20 | Serviços de construção de linhas de transmissão de alta tensão | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.51.00 | Serviços de construção de dutos locais | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.51.00 | Serviços de construção de dutos locais | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.52.10 | Serviços de construção de linhas de comunicação locais | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.52.10 | Serviços de construção de linhas de comunicação locais | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.52.20 | Serviços de construção de linhas de transmissão locais de baixa e média tensão | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.52.20 | Serviços de construção de linhas de transmissão locais de baixa e média tensão | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.53.10 | Serviços de construção de sistemas de esgoto | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.53.10 | Serviços de construção de sistemas de esgoto | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.53.20 | Serviços de construção de sistemas de estações de elevação, tratamento e purificação de água | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.53.20 | Serviços de construção de sistemas de estações de elevação, tratamento e purificação de água | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.61.00 | Serviços de construção de usinas de geração de energia | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.69.00 | Serviços de construção de instalações industriais não classificados... | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.69.00 | Serviços de construção de instalações industriais não classificados... | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.70.00 | Serviços de construção de minas e suas unidades industriais | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.80.00 | Serviços de construção de instalações para recreação e esportes ao ar livre | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.80.00 | Serviços de construção de instalações para recreação e esportes ao ar livre | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.90.00 | Serviços de construção de obras de engenharia civil não classificados... | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0102.90.00 | Serviços de construção de obras de engenharia civil não classificados... | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0107.30.00 | Serviços de pintura | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0107.30.00 | Serviços de pintura | 020201 | 200045 |
| 07.05 | Reparação, conservação e reforma... | 1.0107.90.00 | Serviços de acabamento não classificados em outras subposições | 020201 | 200046 |
| 07.05 | Reparação, conservação e reforma... | 1.0107.90.00 | Serviços de acabamento não classificados em outras subposições | 020201 | 200045 |
| 07.06 | Instalação de tapetes, carpetes... | 1.0106.50.00 | Serviços de instalação de isolamento | 020201 | 200046 |
| 07.06 | Instalação de tapetes, carpetes... | 1.0106.50.00 | Serviços de instalação de isolamento | 020201 | 200045 |
| 07.06 | Instalação de tapetes, carpetes... | 1.0107.10.00 | Serviços de vidraçaria | 020201 | 200046 |
| 07.06 | Instalação de tapetes, carpetes... | 1.0107.10.00 | Serviços de vidraçaria | 020201 | 200045 |
| 07.06 | Instalação de tapetes, carpetes... | 1.0107.20.00 | Serviços de gesso e estuque | 020201 | 200046 |
| 07.06 | Instalação de tapetes, carpetes... | 1.0107.20.00 | Serviços de gesso e estuque | 020201 | 200045 |
| 07.06 | Instalação de tapetes, carpetes... | 1.0107.40.00 | Serviços de revestimento de pisos e paredes | 020201 | 200046 |
| 07.06 | Instalação de tapetes, carpetes... | 1.0107.40.00 | Serviços de revestimento de pisos e paredes | 020201 | 200045 |
| 07.07 | Recuperação, raspagem, polimento... | 1.0107.40.00 | Serviços de revestimento de pisos e paredes | 020201 | 200046 |
| 07.07 | Recuperação, raspagem, polimento... | 1.0107.40.00 | Serviços de revestimento de pisos e paredes | 020201 | 200045 |
| 07.08 | Calafetação. | 1.0107.90.00 | Serviços de acabamento não classificados em outras subposições | 020201 | 200046 |
| 07.08 | Calafetação. | 1.0107.90.00 | Serviços de acabamento não classificados em outras subposições | 020201 | 200045 |
| 07.09 | Varrição, coleta, remoção... | 1.2406.10.00 | Serviços de varrição de ruas e áreas públicas | 020201 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2402.20.00 | Serviços de esvaziamento e limpeza de fossas sépticas | 020201 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.11.00 | Serviços de coleta de resíduos de serviços de saúde e outros resíduos biológicos | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.11.00 | Serviços de coleta de resíduos de serviços de saúde e outros resíduos biológicos | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.12.00 | Serviços de coleta de resíduos industriais perigosos... | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.12.00 | Serviços de coleta de resíduos industriais perigosos... | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.19.00 | Serviços de coleta de outros resíduos perigosos não classificados... | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.19.00 | Serviços de coleta de outros resíduos perigosos não classificados... | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.21.00 | Serviços de coleta de resíduos recicláveis, não perigosos, de origem doméstica | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.21.00 | Serviços de coleta de resíduos recicláveis, não perigosos, de origem doméstica | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.22.00 | Serviços de coleta de resíduos recicláveis, não perigosos, exceto de origem doméstica | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.22.00 | Serviços de coleta de resíduos recicláveis, não perigosos, exceto de origem doméstica | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.31.00 | Serviços de coleta de resíduos gerais de origem doméstica | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.31.00 | Serviços de coleta de resíduos gerais de origem doméstica | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.32.00 | Serviços de coleta de resíduos gerais, exceto de origem doméstica | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2403.32.00 | Serviços de coleta de resíduos gerais, exceto de origem doméstica | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.11.00 | Serviços de triagem, preparação, consolidação e armazenamento de resíduos perigosos | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.11.00 | Serviços de triagem, preparação, consolidação e armazenamento de resíduos perigosos | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.12.00 | Serviços de demolição e desmantelamento de embarcações, veículos e outros bens | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.12.00 | Serviços de demolição e desmantelamento de embarcações, veículos e outros bens | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.13.00 | Serviços de triagem, preparação, consolidação e armazenamento de resíduos recicláveis não perigosos | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.13.00 | Serviços de triagem, preparação, consolidação e armazenamento de resíduos recicláveis não perigosos | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.19.00 | Serviços de triagem, preparação, consolidação e armazenamento de resíduos não perigosos, exceto recicláveis | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.19.00 | Serviços de triagem, preparação, consolidação e armazenamento de resíduos não perigosos, exceto recicláveis | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.21.00 | Serviços de tratamento de resíduos perigosos | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.21.00 | Serviços de tratamento de resíduos perigosos | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.22.00 | Serviços de eliminação de resíduos perigosos | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.22.00 | Serviços de eliminação de resíduos perigosos | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.31.00 | Serviços de tratamento e eliminação de resíduos não perigosos em aterros sanitários | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.31.00 | Serviços de tratamento e eliminação de resíduos não perigosos em aterros sanitários | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.32.00 | Serviços de tratamento e eliminação de resíduos não perigosos em aterros, exceto sanitários | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.32.00 | Serviços de tratamento e eliminação de resíduos não perigosos em aterros, exceto sanitários | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.39.00 | Serviços de tratamento e eliminação de resíduos não perigosos não classificados... | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.39.00 | Serviços de tratamento e eliminação de resíduos não perigosos não classificados... | 050102 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.33.00 | Serviços de incineração de resíduos não perigosos | 050101 | 000001 |
| 07.09 | Varrição, coleta, remoção... | 1.2404.33.00 | Serviços de incineração de resíduos não perigosos | 050102 | 000001 |
| 07.10 | Limpeza, manutenção e conservação... | 1.1803.10.00 | Serviços gerais de limpeza | 020201 | 000001 |
| 07.10 | Limpeza, manutenção e conservação... | 1.1803.10.00 | Serviços gerais de limpeza | 020201 | 200045 |
| 07.10 | Limpeza, manutenção e conservação... | 1.1803.22.00 | Serviços de limpeza de janelas | 020201 | 000001 |
| 07.10 | Limpeza, manutenção e conservação... | 1.1803.22.00 | Serviços de limpeza de janelas | 020201 | 200045 |
| 07.10 | Limpeza, manutenção e conservação... | 1.1803.29.00 | Serviços especializados de limpeza não classificados em outras subposições | 020201 | 000001 |
| 07.10 | Limpeza, manutenção e conservação... | 1.1803.29.00 | Serviços especializados de limpeza não classificados em outras subposições | 020201 | 200045 |
| 07.10 | Limpeza, manutenção e conservação... | 1.2405.14.00 | Serviços de remediação em edificações | 020201 | 000001 |
| 07.10 | Limpeza, manutenção e conservação... | 1.2405.14.00 | Serviços de remediação em edificações | 020201 | 200045 |
| 07.10 | Limpeza, manutenção e conservação... | 1.2406.90.00 | Serviços de limpeza urbana e similares não classificados em outras subposições | 020201 | 000001 |
| 07.10 | Limpeza, manutenção e conservação... | 1.2406.90.00 | Serviços de limpeza urbana e similares não classificados em outras subposições | 020201 | 200045 |
| 07.10 | Limpeza, manutenção e conservação... | 1.2407.00.00 | Serviços de proteção ambiental não classificados em outras posições | 020201 | 000001 |
| 07.10 | Limpeza, manutenção e conservação... | 1.2407.00.00 | Serviços de proteção ambiental não classificados em outras posições | 020201 | 200045 |
| 07.11 | Decoração e jardinagem... | 1.1409.11.00 | Serviços de design de interiores para espaços comerciais e públicos | 020201 | 000001 |
| 07.11 | Decoração e jardinagem... | 1.1409.12.00 | Serviços de design de interiores para espaços residenciais | 020201 | 000001 |
| 07.11 | Decoração e jardinagem... | 1.1806.70.00 | Serviços de jardinagem | 020201 | 000001 |
| 07.12 | Controle e tratamento de efluentes... | 1.2405.11.00 | Serviços de remediação e limpeza do ar | 100301 | 000001 |
| 07.12 | Controle e tratamento de efluentes... | 1.2405.12.00 | Serviços de remediação e limpeza de águas de superfície | 100301 | 000001 |
| 07.12 | Controle e tratamento de efluentes... | 1.2405.13.00 | Serviços de remediação e limpeza do solo e de águas subterrâneas | 100301 | 000001 |
| 07.12 | Controle e tratamento de efluentes... | 1.2405.20.00 | Serviços de contenção, controle e monitoramento de áreas contaminadas | 100301 | 000001 |
| 07.12 | Controle e tratamento de efluentes... | 1.2405.90.00 | Serviços de remediação não classificados em outras subposições | 100301 | 000001 |
| 07.13 | Controle de pragas, desinfecção... | 1.1803.21.00 | Serviços de desinfecção e extermínio de pragas | 020201 | 000001 |
| 07.16 | Florestamento, reflorestamento... | 1.1105.41.00 | Exploração de recursos vegetais, incluindo florestais | 020201 | 000001 |
| 07.16 | Florestamento, reflorestamento... | 1.1901.10.00 | Serviços de apoio à agricultura | 020201 | 200038 |
| 07.16 | Florestamento, reflorestamento... | 1.1901.10.00 | Serviços de apoio à agricultura | 100301 | 000001 |
| 07.16 | Florestamento, reflorestamento... | 1.1901.30.00 | Serviços de apoio à produção florestal (silvicultura) | 020201 | 000001 |
| 07.16 | Florestamento, reflorestamento... | 1.0602.31.00 | Serviços de armazenamento de granéis sólidos | 050101 | 000001 |
| 07.16 | Florestamento, reflorestamento... | 1.0602.31.00 | Serviços de armazenamento de granéis sólidos | 050102 | 000001 |
| 07.17 | Escoramento, contenção de encostas... | 1.0105.11.00 | Serviços de estaqueamento | 020201 | 200046 |
| 07.17 | Escoramento, contenção de encostas... | 1.0105.11.00 | Serviços de estaqueamento | 020201 | 200045 |
| 07.18 | Limpeza e dragagem de rios... | 1.2406.90.00 | Serviços de limpeza urbana e similares não classificados em outras subposições | 020201 | 000001 |
| 07.18 | Limpeza e dragagem de rios... | 1.2406.90.00 | Serviços de limpeza urbana e similares não classificados em outras subposições | 020201 | 200045 |
| 07.19 | Acompanhamento e fiscalização de... | 1.1402.15.00 | Serviços de arquitetura relacionados ao acompanhamento e fiscalização... | 020201 | 200052 |
| 07.19 | Acompanhamento e fiscalização de... | 1.1402.15.00 | Serviços de arquitetura relacionados ao acompanhamento e fiscalização... | 020201 | 200045 |
| 07.19 | Acompanhamento e fiscalização de... | 1.1403.21.10 | Serviços de engenharia para projetos de construção residencial | 020201 | 200052 |
| 07.19 | Acompanhamento e fiscalização de... | 1.1403.21.10 | Serviços de engenharia para projetos de construção residencial | 020201 | 200045 |
| 07.19 | Acompanhamento e fiscalização de... | 1.1403.21.20 | Serviços de engenharia para projetos de construção não residencial | 020201 | 200052 |
| 07.19 | Acompanhamento e fiscalização de... | 1.1403.21.20 | Serviços de engenharia para projetos de construção não residencial | 020201 | 200045 |
| 07.19 | Acompanhamento e fiscalização de... | 1.1403.30.00 | Serviços de gerenciamento de projetos de construção | 020201 | 200052 |
| 07.19 | Acompanhamento e fiscalização de... | 1.1403.30.00 | Serviços de gerenciamento de projetos de construção | 020201 | 200045 |
| 07.20 | Aerofotogrametria... | 1.1404.21.00 | Serviços topográficos | 100301 | 000001 |
| 07.20 | Aerofotogrametria... | 1.1404.21.00 | Serviços topográficos | 100301 | 200045 |
| 07.20 | Aerofotogrametria... | 1.1404.22.00 | Serviços cartográficos | 100301 | 000001 |
| 07.20 | Aerofotogrametria... | 1.1404.22.00 | Serviços cartográficos | 100301 | 200045 |
| 07.20 | Aerofotogrametria... | 1.1404.19.00 | Serviços geológicos, geofísicos e outros de prospecção não classificados... | 100301 | 000001 |
| 07.20 | Aerofotogrametria... | 1.1404.19.00 | Serviços geológicos, geofísicos e outros de prospecção não classificados... | 100301 | 200045 |
| 07.21 | Pesquisa, perfuração, cimentação... | 1.1404.19.00 | Serviços geológicos, geofísicos e outros de prospecção não classificados... | 020201 | 000001 |
| 07.21 | Pesquisa, perfuração, cimentação... | 1.1902.10.00 | Serviços de apoio à extração de petróleo e gás | 020201 | 000001 |
| 07.21 | Pesquisa, perfuração, cimentação... | 1.1902.90.00 | Serviços de apoio à mineração não classificados em outras subposições | 020201 | 000001 |
| 07.22 | Semeadura de nuvens e similares. | 1.1901.10.00 | Serviços de apoio à agricultura | 100301 | 000001 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.11.00 | Serviços de creche ou entidade equivalente | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.11.00 | Serviços de creche ou entidade equivalente | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.12.00 | Serviços de pré-escola | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.12.00 | Serviços de pré-escola | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.19.00 | Serviços de educação infantil não classificados em outras subposições | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.19.00 | Serviços de educação infantil não classificados em outras subposições | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.20.00 | Serviços de ensino fundamental | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.20.00 | Serviços de ensino fundamental | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.30.00 | Serviços de ensino médio | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2201.30.00 | Serviços de ensino médio | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2202.00.00 | Serviços de educação técnica de nível médio | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2202.00.00 | Serviços de educação técnica de nível médio | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2202.00.00 | Serviços de educação técnica de nível médio | 100301 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2203.10.00 | Serviços de ensino fundamental para jovens e adultos | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2203.10.00 | Serviços de ensino fundamental para jovens e adultos | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2203.10.00 | Serviços de ensino fundamental para jovens e adultos | 100301 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2203.20.00 | Serviços de ensino médio para jovens e adultos | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2203.20.00 | Serviços de ensino médio para jovens e adultos | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2203.20.00 | Serviços de ensino médio para jovens e adultos | 100301 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.10.00 | Serviços educacionais de graduação | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.10.00 | Serviços educacionais de graduação | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.10.00 | Serviços educacionais de graduação | 100301 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.10.00 | Serviços educacionais de graduação | 100301 | 200025 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.10.00 | Serviços educacionais de graduação | 030101 | 200025 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.10.00 | Serviços educacionais de graduação | 030102 | 200025 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.20.00 | Serviços educacionais de pós-graduação | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.20.00 | Serviços educacionais de pós-graduação | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.20.00 | Serviços educacionais de pós-graduação | 100301 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.30.00 | Serviços educacionais de extensão | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.30.00 | Serviços educacionais de extensão | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.30.00 | Serviços educacionais de extensão | 100301 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.40.00 | Serviços educacionais de cursos sequenciais | 030101 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.40.00 | Serviços educacionais de cursos sequenciais | 030102 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.40.00 | Serviços educacionais de cursos sequenciais | 100301 | 200028 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.40.00 | Serviços educacionais de cursos sequenciais | 100301 | 200025 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.40.00 | Serviços educacionais de cursos sequenciais | 030101 | 200025 |
| 08.01 | Ensino regular pré-escolar... | 1.2204.40.00 | Serviços educacionais de cursos sequenciais | 030102 | 200025 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.11.00 | Serviços de educação com foco cultural | 030101 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.11.00 | Serviços de educação com foco cultural | 030102 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.11.00 | Serviços de educação com foco cultural | 100301 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.13.00 | Serviços de educação em línguas estrangeiras e de sinais | 030101 | 200028 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.13.00 | Serviços de educação em línguas estrangeiras e de sinais | 030102 | 200028 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.13.00 | Serviços de educação em línguas estrangeiras e de sinais | 100301 | 200028 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.13.00 | Serviços de educação em línguas estrangeiras e de sinais | 030101 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.13.00 | Serviços de educação em línguas estrangeiras e de sinais | 030102 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.13.00 | Serviços de educação em línguas estrangeiras e de sinais | 100301 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.19.00 | Serviços de educação, incluindo treinamento não classificado em outras subposições | 030101 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.19.00 | Serviços de educação, incluindo treinamento não classificado em outras subposições | 030102 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.19.00 | Serviços de educação, incluindo treinamento não classificado em outras subposições | 100301 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.20.00 | Serviços de apoio aos serviços educacionais | 030101 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.20.00 | Serviços de apoio aos serviços educacionais | 030102 | 000001 |
| 08.02 | Instrução, treinamento, orientação... | 1.2205.20.00 | Serviços de apoio aos serviços educacionais | 100301 | 000001 |
| 09.01 | Hospedagem de qualquer natureza... | 1.0303.11.00 | Serviços de hospedagem em quartos ou unidades de alojamento para visitantes, com serviços diários de limpeza | 030101 | 200048 |
| 09.01 | Hospedagem de qualquer natureza... | 1.0303.12.00 | Serviços de hospedagem em quartos ou unidades de alojamento para visitantes, sem serviços diários de limpeza | 030101 | 200048 |
| 09.01 | Hospedagem de qualquer natureza... | 1.0303.13.00 | Serviços de hospedagem em quartos ou unidades de alojamento para visitantes, em propriedades compartilhadas | 030101 | 200048 |
| 09.01 | Hospedagem de qualquer natureza... | 1.0303.14.00 | Serviços de hospedagem em quartos ou unidades de alojamento para visitantes, em quartos de ocupação múltipla | 030101 | 200048 |
| 09.01 | Hospedagem de qualquer natureza... | 1.0303.20.00 | Serviços de acampamento turístico | 030101 | 200048 |
| 09.01 | Hospedagem de qualquer natureza... | 1.0303.90.00 | Serviços de hospedagem para visitantes não classificados em outras subposições | 030101 | 200048 |
| 09.01 | Hospedagem de qualquer natureza... | 1.0304.10.00 | Serviços de hospedagem em quartos ou unidades de alojamento para estudantes em residências estudantis | 030101 | 200048 |
| 09.01 | Hospedagem de qualquer natureza... | 1.0304.20.00 | Serviços de hospedagem em quartos ou unidades de alojamento para trabalhadores em hotéis ou acampamentos | 030101 | 200048 |
| 09.01 | Hospedagem de qualquer natureza... | 1.0304.90.00 | Serviços de hospedagem, exceto para visitantes não classificados em outras subposições | 030101 | 200048 |
| 09.02 | Agenciamento, organização, promoção... | 1.0401.17.10 | Serviços de transporte rodoviário para passeios turísticos | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.0401.17.20 | Serviços de transporte ferroviário para passeios turísticos | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.0401.17.90 | Serviços de transporte terrestre para passeios turísticos não classificados em itens anteriores | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.0401.23.00 | Serviços de transporte aquaviário para passeios turísticos | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.0401.43.00 | Serviços de transporte aéreo para passeios turísticos | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.0402.13.20 | Serviços de fretamento ocasional ou turístico, nacional, exceto local | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.40.00 | Serviços de operadora de turismo | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.11.00 | Serviços de reserva para transporte aéreo de passageiros | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.12.00 | Serviços de reserva para transporte ferroviário de passageiros | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.13.00 | Serviços de reserva para transporte rodoviário de passageiros | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.14.00 | Serviços de reserva para aluguel de carros | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.19.00 | Serviços de reserva para transporte de passageiros não classificados em outras subposições | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.21.00 | Serviços de reserva de acomodação, exceto em unidades compartilhadas | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.22.00 | Serviços de reserva e intercâmbio para unidades compartilhadas (time-share) | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.23.00 | Serviços de reserva de cruzeiros | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.24.00 | Serviços de reserva de pacotes turísticos | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.31.00 | Serviços de reserva para centros de convenções, auditórios e salões de exposição | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.32.00 | Serviços de reserva de ingressos para eventos de entretenimento e recreativos | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.39.00 | Serviços de reserva não classificados em outras subposições | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.61.00 | Serviços de promoção de turismo | 100301 | 200051 |
| 09.02 | Agenciamento, organização, promoção... | 1.1805.62.00 | Serviços de informação ao visitante | 100301 | 200051 |
| 09.03 | Guias de turismo. | 1.1805.50.00 | Serviços de guia de turismo | 030101 | 200051 |
| 09.03 | Guias de turismo. | 1.1805.50.00 | Serviços de guia de turismo | 030102 | 200051 |
| 09.03 | Guias de turismo. | 1.1805.50.00 | Serviços de guia de turismo | 100301 | 200051 |
| 10.01 | Agenciamento, corretagem ou intermediação... | 1.0906.11.00 | Serviços de agenciamento e corretagem de seguros, resseguros e previdência complementar, exceto seguro saúde | 100301 | 000001 |
| 10.01 | Agenciamento, corretagem ou intermediação... | 1.0906.12.00 | Serviços de corretagem de seguros de saúde | 100301 | 011003 |
| 10.01 | Agenciamento, corretagem ou intermediação... | 1.0910.20.00 | Serviços de corretagem para planos privados de assistência à saúde | 100301 | 011003 |
| 10.01 | Agenciamento, corretagem ou intermediação... | 1.0905.90.00 | Serviços auxiliares a serviços financeiros não classificados em outras subposições | 100301 | 000001 |
| 10.02 | Agenciamento, corretagem ou intermediação... | 1.0607.00.00 | Serviços de agência de transporte de cargas | 100301 | 000001 |
| 10.02 | Agenciamento, corretagem ou intermediação... | 1.0905.11.00 | Serviços de corretagem de valores mobiliários | 100301 | 000001 |
| 10.02 | Agenciamento, corretagem ou intermediação... | 1.0905.12.00 | Serviços de corretagem de derivativos e commodities | 100301 | 000001 |
| 10.03 | Agenciamento, corretagem ou intermediação... | 1.2501.40.00 | Serviços de agência para a comercialização de obras audiovisuais | 100301 | 000001 |
| 10.03 | Agenciamento, corretagem ou intermediação... | 1.0905.11.00 | Serviços de corretagem de valores mobiliários | 100301 | 000001 |
| 10.04 | Agenciamento, corretagem ou intermediação... | 1.0905.90.00 | Serviços auxiliares a serviços financeiros não classificados em outras subposições | 100301 | 000001 |
| 10.05 | Agenciamento, corretagem ou intermediação... | 1.1001.21.00 | Serviços de intermediação na compra e venda de imóveis residenciais | 020301 | 200046 |
| 10.05 | Agenciamento, corretagem ou intermediação... | 1.1001.22.00 | Serviços de intermediação na compra e venda de imóveis não residenciais | 020301 | 200046 |
| 10.05 | Agenciamento, corretagem ou intermediação... | 1.0201.00.00 | Serviços de intermediação na distribuição de mercadorias | 100301 | 000001 |
| 10.05 | Agenciamento, corretagem ou intermediação... | 1.0205.00.00 | Serviços de intermediação na comercialização de energia elétrica | 100301 | 000001 |
| 10.05 | Agenciamento, corretagem ou intermediação... | 1.0905.12.00 | Serviços de corretagem de derivativos e commodities | 100301 | 000001 |
| 10.06 | Agenciamento marítimo. | 1.0502.29.00 | Serviços de transporte aquaviário costeiro de cargas não classificados em outras subposições | 100301 | 000001 |
| 10.06 | Agenciamento marítimo. | 1.0607.00.00 | Serviços de agência de transporte de cargas | 100301 | 000001 |
| 10.07 | Agência de notícias. | 1.1704.10.00 | Serviços de agência de notícias para jornais e periódicos | 100301 | 000001 |
| 10.07 | Agência de notícias. | 1.1704.20.00 | Serviços de agência de notícias para mídias audiovisuais | 100301 | 000001 |
| 10.08 | Agência de publicidade e propaganda... | 1.1406.20.00 | Aquisição ou venda de espaço ou tempo publicitário, sob comissão | 100301 | 000001 |
| 10.09 | Representação de qualquer natureza... | 1.0201.00.00 | Serviços de intermediação na distribuição de mercadorias | 100301 | 000001 |
| 10.10 | Distribuição de bens de terceiros. | 1.0201.00.00 | Serviços de intermediação na distribuição de mercadorias | 100301 | 000001 |
| 11.01 | Guarda e estacionamento de veículos... | 1.0604.30.00 | Serviços de estacionamento | 050101 | 000001 |
| 11.01 | Guarda e estacionamento de veículos... | 1.0604.30.00 | Serviços de estacionamento | 050102 | 000001 |
| 11.01 | Guarda e estacionamento de veículos... | 1.0605.90.00 | Serviços de apoio ao transporte aquaviário não classificados em outras subposições | 050101 | 000001 |
| 11.01 | Guarda e estacionamento de veículos... | 1.0605.90.00 | Serviços de apoio ao transporte aquaviário não classificados em outras subposições | 050102 | 000001 |
| 11.01 | Guarda e estacionamento de veículos... | 1.0606.19.00 | Serviços de apoio ao transporte aéreo não classificados em outras subposições | 050101 | 000001 |
| 11.01 | Guarda e estacionamento de veículos... | 1.0606.19.00 | Serviços de apoio ao transporte aéreo não classificados em outras subposições | 050102 | 000001 |
| 11.02 | Vigilância, segurança ou monitoramento... | 1.1802.50.00 | Serviços de guarda e escolta armada | 030101 | 000001 |
| 11.02 | Vigilância, segurança ou monitoramento... | 1.1802.50.00 | Serviços de guarda e escolta armada | 030102 | 000001 |
| 11.02 | Vigilância, segurança ou monitoramento... | 1.1802.50.00 | Serviços de guarda e escolta armada | 100301 | 000001 |
| 11.02 | Vigilância, segurança ou monitoramento... | 1.1802.20.00 | Serviços de consultoria em segurança | 100301 | 000001 |
| 11.02 | Vigilância, segurança ou monitoramento... | 1.1802.30.00 | Serviços de sistemas de segurança | 100301 | 000001 |
| 11.02 | Vigilância, segurança ou monitoramento... | 1.1802.90.00 | Serviços de segurança não classificados em outras subposições | 100301 | 000001 |
| 11.03 | Escolta, inclusive de veículos... | 1.1802.50.00 | Serviços de guarda e escolta armada | 030101 | 000001 |
| 11.03 | Escolta, inclusive de veículos... | 1.1802.50.00 | Serviços de guarda e escolta armada | 030102 | 000001 |
| 11.03 | Escolta, inclusive de veículos... | 1.1802.50.00 | Serviços de guarda e escolta armada | 100301 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0601.10.00 | Serviços de manuseio de contêineres | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0601.10.00 | Serviços de manuseio de contêineres | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0601.90.00 | Serviços de manuseio de cargas não classificados em outras subposições | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0601.90.00 | Serviços de manuseio de cargas não classificados em outras subposições | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.10.00 | Serviços de armazenagem frigorificada | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.10.00 | Serviços de armazenagem frigorificada | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.21.00 | Serviços de armazenagem de petróleo e seus derivados | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.21.00 | Serviços de armazenagem de petróleo e seus derivados | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.22.00 | Serviços de armazenagem de combustíveis, lubrificantes e GLP, inclusive em botijões metálicos | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.22.00 | Serviços de armazenagem de combustíveis, lubrificantes e GLP, inclusive em botijões metálicos | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.23.00 | Serviços de armazenagem de produtos químicos perigosos | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.23.00 | Serviços de armazenagem de produtos químicos perigosos | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.29.00 | Serviços de armazenagem de produtos perigosos não classificados em outras subposições | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.29.00 | Serviços de armazenagem de produtos perigosos não classificados em outras subposições | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.31.00 | Serviços de armazenamento de granéis sólidos | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.31.00 | Serviços de armazenamento de granéis sólidos | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.32.00 | Serviços de armazenagem de granéis líquidos ou liquefeitos | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.32.00 | Serviços de armazenagem de granéis líquidos ou liquefeitos | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.33.00 | Serviços de armazenagem de granéis gasosos | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.33.00 | Serviços de armazenagem de granéis gasosos | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.90.00 | Serviços de armazenagem não classificados em outras subposições | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0602.90.00 | Serviços de armazenagem não classificados em outras subposições | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0608.20.00 | Serviços de unitização ou desunitização de cargas no transporte multimodal | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0608.20.00 | Serviços de unitização ou desunitização de cargas no transporte multimodal | 050102 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0608.30.00 | Serviços de movimentação de cargas no transporte multimodal | 050101 | 000001 |
| 11.04 | Armazenamento, depósito, carga... | 1.0608.30.00 | Serviços de movimentação de cargas no transporte multimodal | 050102 | 000001 |
| 11.05 | Vigilância, segurança ou monitoramento... | 1.1802.30.00 | Serviços de sistemas de segurança | 100301 | 000001 |
| 12.01 | Espetáculos teatrais. | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 200039 |
| 12.01 | Espetáculos teatrais. | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 000001 |
| 12.02 | Exibições cinematográficas. | 1.2501.50.00 | Serviços de projeção de filmes | 030101 | 200039 |
| 12.02 | Exibições cinematográficas. | 1.2501.50.00 | Serviços de projeção de filmes | 030102 | 200039 |
| 12.02 | Exibições cinematográficas. | 1.2501.50.00 | Serviços de projeção de filmes | 030101 | 000001 |
| 12.02 | Exibições cinematográficas. | 1.2501.50.00 | Serviços de projeção de filmes | 030102 | 000001 |
| 12.03 | Espetáculos circenses. | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 200039 |
| 12.03 | Espetáculos circenses. | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 000001 |
| 12.04 | Programas de auditório. | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 040101 | 200039 |
| 12.04 | Programas de auditório. | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 040101 | 000001 |
| 12.05 | Parques de diversões, centros de lazer... | 1.2504.21.00 | Serviços de jardins botânico e zoológico | 030101 | 200048 |
| 12.05 | Parques de diversões, centros de lazer... | 1.2504.22.00 | Serviços de reserva natural, incluindo preservação de vida selvagem | 030101 | 200048 |
| 12.05 | Parques de diversões, centros de lazer... | 1.2507.10.00 | Serviços de parques temáticos de diversão | 030101 | 200048 |
| 12.05 | Parques de diversões, centros de lazer... | 1.2507.90.00 | Serviços de parques de diversão e atrações similares não classificados em subposições anteriores | 030101 | 200048 |
| 12.06 | Boates, taxi-dancing... | 1.2508.00.00 | Serviços recreativos, culturais e desportivos não classificados em outras posições | 030101 | 000001 |
| 12.06 | Boates, taxi-dancing... | 1.2508.00.00 | Serviços recreativos, culturais e desportivos não classificados em outras posições | 030102 | 000001 |
| 12.07 | Shows, ballet, danças, desfiles... | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 200039 |
| 12.07 | Shows, ballet, danças, desfiles... | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 000001 |
| 12.07 | Shows, ballet, danças, desfiles... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 040101 | 200039 |
| 12.07 | Shows, ballet, danças, desfiles... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 040101 | 000001 |
| 12.08 | Feiras, exposições, congressos... | 1.1806.61.00 | Serviços de assistência e organização de convenções | 040101 | 200039 |
| 12.08 | Feiras, exposições, congressos... | 1.1806.61.00 | Serviços de assistência e organização de convenções | 040101 | 000001 |
| 12.08 | Feiras, exposições, congressos... | 1.1806.62.00 | Serviços de assistência e organização de feiras comerciais | 040101 | 200039 |
| 12.08 | Feiras, exposições, congressos... | 1.1806.62.00 | Serviços de assistência e organização de feiras comerciais | 040101 | 000001 |
| 12.08 | Feiras, exposições, congressos... | 1.1806.63.00 | Serviços de assistência e organização de exposições e outros eventos | 040101 | 200039 |
| 12.08 | Feiras, exposições, congressos... | 1.1806.63.00 | Serviços de assistência e organização de exposições e outros eventos | 040101 | 000001 |
| 12.09 | Bilhares, boliches e diversões... | 1.2505.90.00 | Serviços desportivos e recreacionais desportivos não classificados em outras subposições | 030101 | 000001 |
| 12.09 | Bilhares, boliches e diversões... | 1.2505.90.00 | Serviços desportivos e recreacionais desportivos não classificados em outras subposições | 030102 | 000001 |
| 12.09 | Bilhares, boliches e diversões... | 1.2508.00.00 | Serviços recreativos, culturais e desportivos não classificados em outras posições | 030101 | 000001 |
| 12.09 | Bilhares, boliches e diversões... | 1.2508.00.00 | Serviços recreativos, culturais e desportivos não classificados em outras posições | 030102 | 000001 |
| 12.10 | Corridas e competições de animais. | 1.2508.00.00 | Serviços recreativos, culturais e desportivos não classificados em outras posições | 030101 | 000001 |
| 12.10 | Corridas e competições de animais. | 1.2508.00.00 | Serviços recreativos, culturais e desportivos não classificados em outras posições | 030102 | 000001 |
| 12.10 | Corridas e competições de animais. | 1.2505.10.00 | Serviços de organização e promoção de eventos desportivos e recreacionais desportivos | 030101 | 000001 |
| 12.10 | Corridas e competições de animais. | 1.2505.10.00 | Serviços de organização e promoção de eventos desportivos e recreacionais desportivos | 030102 | 000001 |
| 12.11 | Competições esportivas ou de... | 1.2505.20.00 | Serviços de organização de competições desportivas | 030101 | 200042 |
| 12.11 | Competições esportivas ou de... | 1.2505.20.00 | Serviços de organização de competições desportivas | 030102 | 200042 |
| 12.11 | Competições esportivas ou de... | 1.2505.20.00 | Serviços de organização de competições desportivas | 030101 | 000001 |
| 12.11 | Competições esportivas ou de... | 1.2505.20.00 | Serviços de organização de competições desportivas | 030102 | 000001 |
| 12.11 | Competições esportivas ou de... | 1.2505.90.00 | Serviços desportivos e recreacionais desportivos não classificados em outras subposições | 030101 | 000001 |
| 12.11 | Competições esportivas ou de... | 1.2505.90.00 | Serviços desportivos e recreacionais desportivos não classificados em outras subposições | 030102 | 000001 |
| 12.11 | Competições esportivas ou de... | 1.2505.10.00 | Serviços de organização e promoção de eventos desportivos e recreacionais desportivos | 030101 | 000001 |
| 12.11 | Competições esportivas ou de... | 1.2505.10.00 | Serviços de organização e promoção de eventos desportivos e recreacionais desportivos | 030102 | 000001 |
| 12.12 | Execução de música. | 1.2503.10.00 | Serviços de atuação artística | 030101 | 200039 |
| 12.12 | Execução de música. | 1.2503.10.00 | Serviços de atuação artística | 030102 | 200039 |
| 12.12 | Execução de música. | 1.2503.10.00 | Serviços de atuação artística | 100301 | 200039 |
| 12.12 | Execução de música. | 1.2503.10.00 | Serviços de atuação artística | 030101 | 000001 |
| 12.12 | Execução de música. | 1.2503.10.00 | Serviços de atuação artística | 030102 | 000001 |
| 12.12 | Execução de música. | 1.2503.10.00 | Serviços de atuação artística | 100301 | 000001 |
| 12.13 | Produção de eventos, espetáculos... | 1.2501.21.00 | Serviços de produção de programas de televisão, videoteipes e filmes | 040101 | 200039 |
| 12.13 | Produção de eventos, espetáculos... | 1.2501.21.00 | Serviços de produção de programas de televisão, videoteipes e filmes | 040101 | 000001 |
| 12.13 | Produção de eventos, espetáculos... | 1.2501.22.00 | Serviços de produção de programas de rádio | 040101 | 200039 |
| 12.13 | Produção de eventos, espetáculos... | 1.2501.22.00 | Serviços de produção de programas de rádio | 040101 | 000001 |
| 12.13 | Produção de eventos, espetáculos... | 1.2502.10.00 | Serviços de organização e promoção de atuações artísticas ao vivo | 040101 | 200039 |
| 12.13 | Produção de eventos, espetáculos... | 1.2502.10.00 | Serviços de organização e promoção de atuações artísticas ao vivo | 040101 | 000001 |
| 12.13 | Produção de eventos, espetáculos... | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 200039 |
| 12.13 | Produção de eventos, espetáculos... | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 000001 |
| 12.13 | Produção de eventos, espetáculos... | 1.2502.30.00 | Serviços de apoio para atuações artísticas ao vivo | 040101 | 200039 |
| 12.13 | Produção de eventos, espetáculos... | 1.2502.30.00 | Serviços de apoio para atuações artísticas ao vivo | 040101 | 000001 |
| 12.13 | Produção de eventos, espetáculos... | 1.2505.10.00 | Serviços de organização e promoção de eventos desportivos e recreacionais desportivos | 040101 | 000001 |
| 12.14 | Fornecimento de música para... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 030101 | 200039 |
| 12.14 | Fornecimento de música para... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 030102 | 200039 |
| 12.14 | Fornecimento de música para... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 100301 | 200039 |
| 12.14 | Fornecimento de música para... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 030101 | 000001 |
| 12.14 | Fornecimento de música para... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 030102 | 000001 |
| 12.14 | Fornecimento de música para... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 100301 | 000001 |
| 12.15 | Desfiles de blocos carnavalescos... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 040101 | 200039 |
| 12.15 | Desfiles de blocos carnavalescos... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 040101 | 000001 |
| 12.15 | Desfiles de blocos carnavalescos... | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 200039 |
| 12.15 | Desfiles de blocos carnavalescos... | 1.2502.20.00 | Serviços de produção e apresentação de atuações artísticas ao vivo | 040101 | 000001 |
| 12.16 | Exibição de fotografias... | 1.2501.50.00 | Serviços de projeção de filmes | 100301 | 200039 |
| 12.16 | Exibição de fotografias... | 1.2501.50.00 | Serviços de projeção de filmes | 100301 | 000001 |
| 12.16 | Exibição de fotografias... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 100301 | 200039 |
| 12.16 | Exibição de fotografias... | 1.2502.90.00 | Serviços de apresentação e promoção de atuações artísticas e outros serviços de entretenimento ao vivo não classificados em subposições anteriores | 100301 | 000001 |
| 12.16 | Exibição de fotografias... | 1.2505.10.00 | Serviços de organização e promoção de eventos desportivos e recreacionais desportivos | 100301 | 000001 |
| 12.17 | Recreação e animação... | 1.2508.00.00 | Serviços recreativos, culturais e desportivos não classificados em outras posições | 030101 | 000001 |
| 12.17 | Recreação e animação... | 1.2508.00.00 | Serviços recreativos, culturais e desportivos não classificados em outras posições | 030102 | 000001 |
| 13.02 | Fonografia, fotografia... | 1.2501.11.00 | Serviços de gravação de som em estúdio | 100301 | 200039 |
| 13.02 | Fonografia, fotografia... | 1.2501.11.00 | Serviços de gravação de som em estúdio | 100301 | 000001 |
| 13.02 | Fonografia, fotografia... | 1.2501.12.00 | Serviços de gravação de som ao vivo | 100301 | 200039 |
| 13.02 | Fonografia, fotografia... | 1.2501.12.00 | Serviços de gravação de som ao vivo | 100301 | 000001 |
| 13.02 | Fonografia, fotografia... | 1.2501.36.00 | Serviços de legendas, títulos e dublagem em obras audiovisuais | 100301 | 200039 |
| 13.02 | Fonografia, fotografia... | 1.2501.36.00 | Serviços de legendas, títulos e dublagem em obras audiovisuais | 100301 | 000001 |
| 13.02 | Fonografia, fotografia... | 1.2501.37.00 | Serviços de projeto e edição de som em obras audiovisuais | 100301 | 200039 |
| 13.02 | Fonografia, fotografia... | 1.2501.37.00 | Serviços de projeto e edição de som em obras audiovisuais | 100301 | 000001 |
| 13.02 | Fonografia, fotografia... | 1.2501.39.00 | Serviços de pós-produção de obras audiovisuais não classificados em subposições anteriores | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.1408.11.00 | Serviços fotográficos de retratos | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.1408.12.00 | Serviços fotográficos e videográficos para propaganda | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.1408.13.00 | Serviços fotográficos e videográficos de eventos | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.1408.14.00 | Serviços fotográficos especiais | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.1408.15.00 | Serviços de restauração e retoque de fotografias | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.1408.19.00 | Serviços fotográficos e videográficos não classificados em subposições anteriores | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.1408.20.00 | Serviços de processamento de fotografias | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.2101.23.00 | Serviços de reprodução de mídia gravada | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.2501.31.00 | Serviços de edição de obras audiovisuais | 100301 | 200039 |
| 13.03 | Fotografia e cinematografia... | 1.2501.31.00 | Serviços de edição de obras audiovisuais | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.2501.32.00 | Serviços de duplicação e transferência de obras audiovisuais | 100301 | 200039 |
| 13.03 | Fotografia e cinematografia... | 1.2501.32.00 | Serviços de duplicação e transferência de obras audiovisuais | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.2501.33.00 | Serviços de correção de cor e restauração digital de obras audiovisuais | 100301 | 200039 |
| 13.03 | Fotografia e cinematografia... | 1.2501.33.00 | Serviços de correção de cor e restauração digital de obras audiovisuais | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.2501.34.00 | Serviços de efeitos visuais em obras audiovisuais | 100301 | 200039 |
| 13.03 | Fotografia e cinematografia... | 1.2501.34.00 | Serviços de efeitos visuais em obras audiovisuais | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.2501.35.00 | Serviços de animação | 100301 | 200039 |
| 13.03 | Fotografia e cinematografia... | 1.2501.35.00 | Serviços de animação | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.2501.36.00 | Serviços de legendas, títulos e dublagem em obras audiovisuais | 100301 | 200039 |
| 13.03 | Fotografia e cinematografia... | 1.2501.36.00 | Serviços de legendas, títulos e dublagem em obras audiovisuais | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.2501.39.00 | Serviços de pós-produção de obras audiovisuais não classificados em subposições anteriores | 100301 | 000001 |
| 13.03 | Fotografia e cinematografia... | 1.2501.90.00 | Serviços de produção audiovisual, de apoio e relacionados não classificados em subposições anteriores | 100301 | 200039 |
| 13.03 | Fotografia e cinematografia... | 1.2501.90.00 | Serviços de produção audiovisual, de apoio e relacionados não classificados em subposições anteriores | 100301 | 000001 |
| 13.04 | Criação de desenhos, ilustrações... | 1.1806.51.00 | Serviços de fotocópias e outros serviços de reprodução de documentos | 100301 | 000001 |
| 13.05 | Cessão de direito de uso... | 1.2101.10.00 | Serviços de editoração | 100301 | 000001 |
| 13.05 | Cessão de direito de uso... | 1.2101.21.00 | Serviços de impressão | 100301 | 000001 |
| 13.05 | Cessão de direito de uso... | 1.2101.22.00 | Serviços relacionados à impressão | 100301 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.10.00 | Serviços de manutenção e reparo de produtos metálicos, exceto máquinas e equipamentos | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.10.00 | Serviços de manutenção e reparo de produtos metálicos, exceto máquinas e equipamentos | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.20.00 | Serviços de manutenção e reparo de computadores e seus periféricos e máquinas de escritório | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.20.00 | Serviços de manutenção e reparo de computadores e seus periféricos e máquinas de escritório | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.31.10 | Serviços de manutenção e reparo de veículos rodoviários motorizados | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.31.10 | Serviços de manutenção e reparo de veículos rodoviários motorizados | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.31.20 | Serviços de manutenção e reparo de veículos rodoviários não motorizados | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.31.20 | Serviços de manutenção e reparo de veículos rodoviários não motorizados | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.32.00 | Serviços de manutenção e reparo de veículos ferroviários | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.32.00 | Serviços de manutenção e reparo de veículos ferroviários | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.33.00 | Serviços de manutenção e reparo de embarcações | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.33.00 | Serviços de manutenção e reparo de embarcações | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.34.10 | Serviços de manutenção e reparo de aeronaves, exceto motores, turbojatos e turbopropulsores | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.34.10 | Serviços de manutenção e reparo de aeronaves, exceto motores, turbojatos e turbopropulsores | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.34.20 | Serviços de manutenção e reparo de motores de aeronaves, turbojatos e turbopropulsores | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.34.20 | Serviços de manutenção e reparo de motores de aeronaves, turbojatos e turbopropulsores | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.34.30 | Serviços de manutenção e reparo de foguetes e equipamentos aeroespaciais | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.34.30 | Serviços de manutenção e reparo de foguetes e equipamentos aeroespaciais | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.35.00 | Serviços de manutenção e reparo de veículos militares | 050101 | 200044 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.35.00 | Serviços de manutenção e reparo de veículos militares | 050102 | 200044 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.39.00 | Serviços de manutenção e reparo de máquinas e equipamentos de transporte não classificados... | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.39.00 | Serviços de manutenção e reparo de máquinas e equipamentos de transporte não classificados... | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.40.00 | Serviços de manutenção e reparo de plataformas, incluindo navios-plataforma, para extração de petróleo e gás | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.40.00 | Serviços de manutenção e reparo de plataformas, incluindo navios-plataforma, para extração de petróleo e gás | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.50.00 | Serviços de manutenção e reparo de máquinas e equipamentos industriais | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.50.00 | Serviços de manutenção e reparo de máquinas e equipamentos industriais | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.60.00 | Serviços de manutenção e reparo de máquinas e equipamentos comerciais | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.60.00 | Serviços de manutenção e reparo de máquinas e equipamentos comerciais | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.70.00 | Serviços de manutenção e reparo de equipamentos e aparelhos de telecomunicações | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.70.00 | Serviços de manutenção e reparo de equipamentos e aparelhos de telecomunicações | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.81.00 | Serviços de manutenção e reparo de eletrodomésticos eletrônicos | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.81.00 | Serviços de manutenção e reparo de eletrodomésticos eletrônicos | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.82.00 | Serviços de manutenção e reparo de instrumentos e equipamentos médico-hospitalares, odontológicos, ópticos e de precisão | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.82.00 | Serviços de manutenção e reparo de instrumentos e equipamentos médico-hospitalares, odontológicos, ópticos e de precisão | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.83.00 | Serviços de manutenção e reparo de equipamentos militares | 050101 | 200044 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.83.00 | Serviços de manutenção e reparo de equipamentos militares | 050102 | 200044 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.89.00 | Serviços de manutenção e reparo de outras máquinas e equipamentos não classificados... | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2001.89.00 | Serviços de manutenção e reparo de outras máquinas e equipamentos não classificados... | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.10.00 | Serviços de manutenção e reparo de produtos de couro, calçados, malas e bolsas | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.10.00 | Serviços de manutenção e reparo de produtos de couro, calçados, malas e bolsas | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.20.00 | Serviços de manutenção e reparo de relógios e joias | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.20.00 | Serviços de manutenção e reparo de relógios e joias | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.30.00 | Serviços de manutenção e reparo de móveis | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.30.00 | Serviços de manutenção e reparo de móveis | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.40.00 | Serviços de manutenção de roupas e outros produtos têxteis | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.40.00 | Serviços de manutenção de roupas e outros produtos têxteis | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.90.00 | Serviços de manutenção e reparo de outros bens de consumo não classificados... | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.2002.90.00 | Serviços de manutenção e reparo de outros bens de consumo não classificados... | 050102 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.1803.29.00 | Serviços especializados de limpeza não classificados em outras subposições | 050101 | 000001 |
| 14.01 | Lubrificação, limpeza, polimento... | 1.1803.29.00 | Serviços especializados de limpeza não classificados em outras subposições | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.10.00 | Serviços de manutenção e reparo de produtos metálicos, exceto máquinas e equipamentos | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.10.00 | Serviços de manutenção e reparo de produtos metálicos, exceto máquinas e equipamentos | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.20.00 | Serviços de manutenção e reparo de computadores e seus periféricos e máquinas de escritório | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.20.00 | Serviços de manutenção e reparo de computadores e seus periféricos e máquinas de escritório | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.31.10 | Serviços de manutenção e reparo de veículos rodoviários motorizados | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.31.10 | Serviços de manutenção e reparo de veículos rodoviários motorizados | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.31.20 | Serviços de manutenção e reparo de veículos rodoviários não motorizados | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.31.20 | Serviços de manutenção e reparo de veículos rodoviários não motorizados | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.32.00 | Serviços de manutenção e reparo de veículos ferroviários | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.32.00 | Serviços de manutenção e reparo de veículos ferroviários | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.33.00 | Serviços de manutenção e reparo de embarcações | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.33.00 | Serviços de manutenção e reparo de embarcações | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.34.10 | Serviços de manutenção e reparo de aeronaves, exceto motores, turbojatos e turbopropulsores | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.34.10 | Serviços de manutenção e reparo de aeronaves, exceto motores, turbojatos e turbopropulsores | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.34.20 | Serviços de manutenção e reparo de motores de aeronaves, turbojatos e turbopropulsores | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.34.20 | Serviços de manutenção e reparo de motores de aeronaves, turbojatos e turbopropulsores | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.34.30 | Serviços de manutenção e reparo de foguetes e equipamentos aeroespaciais | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.34.30 | Serviços de manutenção e reparo de foguetes e equipamentos aeroespaciais | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.35.00 | Serviços de manutenção e reparo de veículos militares | 050101 | 200044 |
| 14.02 | Assistência técnica. | 1.2001.35.00 | Serviços de manutenção e reparo de veículos militares | 050102 | 200044 |
| 14.02 | Assistência técnica. | 1.2001.39.00 | Serviços de manutenção e reparo de máquinas e equipamentos de transporte não classificados... | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.39.00 | Serviços de manutenção e reparo de máquinas e equipamentos de transporte não classificados... | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.40.00 | Serviços de manutenção e reparo de plataformas, incluindo navios-plataforma, para extração de petróleo e gás | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.40.00 | Serviços de manutenção e reparo de plataformas, incluindo navios-plataforma, para extração de petróleo e gás | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.50.00 | Serviços de manutenção e reparo de máquinas e equipamentos industriais | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.50.00 | Serviços de manutenção e reparo de máquinas e equipamentos industriais | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.60.00 | Serviços de manutenção e reparo de máquinas e equipamentos comerciais | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.60.00 | Serviços de manutenção e reparo de máquinas e equipamentos comerciais | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.70.00 | Serviços de manutenção e reparo de equipamentos e aparelhos de telecomunicações | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.70.00 | Serviços de manutenção e reparo de equipamentos e aparelhos de telecomunicações | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.81.00 | Serviços de manutenção e reparo de eletrodomésticos eletrônicos | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.81.00 | Serviços de manutenção e reparo de eletrodomésticos eletrônicos | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.82.00 | Serviços de manutenção e reparo de instrumentos e equipamentos médico-hospitalares, odontológicos, ópticos e de precisão | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.82.00 | Serviços de manutenção e reparo de instrumentos e equipamentos médico-hospitalares, odontológicos, ópticos e de precisão | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.83.00 | Serviços de manutenção e reparo de equipamentos militares | 050101 | 200044 |
| 14.02 | Assistência técnica. | 1.2001.83.00 | Serviços de manutenção e reparo de equipamentos militares | 050102 | 200044 |
| 14.02 | Assistência técnica. | 1.2001.89.00 | Serviços de manutenção e reparo de outras máquinas e equipamentos não classificados... | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2001.89.00 | Serviços de manutenção e reparo de outras máquinas e equipamentos não classificados... | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.10.00 | Serviços de manutenção e reparo de produtos de couro, calçados, malas e bolsas | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.10.00 | Serviços de manutenção e reparo de produtos de couro, calçados, malas e bolsas | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.20.00 | Serviços de manutenção e reparo de relógios e joias | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.20.00 | Serviços de manutenção e reparo de relógios e joias | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.30.00 | Serviços de manutenção e reparo de móveis | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.30.00 | Serviços de manutenção e reparo de móveis | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.40.00 | Serviços de manutenção de roupas e outros produtos têxteis | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.40.00 | Serviços de manutenção de roupas e outros produtos têxteis | 050102 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.90.00 | Serviços de manutenção e reparo de outros bens de consumo não classificados... | 050101 | 000001 |
| 14.02 | Assistência técnica. | 1.2002.90.00 | Serviços de manutenção e reparo de outros bens de consumo não classificados... | 050102 | 000001 |
| 14.03 | Recondicionamento de motores... | 1.2001.31.10 | Serviços de manutenção e reparo de veículos rodoviários motorizados | 050101 | 000001 |
| 14.03 | Recondicionamento de motores... | 1.2001.31.10 | Serviços de manutenção e reparo de veículos rodoviários motorizados | 050102 | 000001 |
| 14.03 | Recondicionamento de motores... | 1.2001.89.00 | Serviços de manutenção e reparo de outras máquinas e equipamentos não classificados... | 050101 | 000001 |
| 14.03 | Recondicionamento de motores... | 1.2001.89.00 | Serviços de manutenção e reparo de outras máquinas e equipamentos não classificados... | 050102 | 000001 |
| 14.04 | Recauchutagem ou regeneração de pneus. | 1.2002.90.00 | Serviços de manutenção e reparo de outros bens de consumo não classificados... | 050101 | 000001 |
| 14.04 | Recauchutagem ou regeneração de pneus. | 1.2002.90.00 | Serviços de manutenção e reparo de outros bens de consumo não classificados... | 050102 | 000001 |
| 14.05 | Restauração, recondicionamento... | 1.1804.00.00 | Serviços de embalagem e empacotamento | 050101 | 000001 |
| 14.05 | Restauração, recondicionamento... | 1.1804.00.00 | Serviços de embalagem e empacotamento | 050102 | 000001 |
| 14.05 | Restauração, recondicionamento... | 1.2002.90.00 | Serviços de manutenção e reparo de outros bens de consumo não classificados... | 050101 | 000001 |
| 14.05 | Restauração, recondicionamento... | 1.2002.90.00 | Serviços de manutenção e reparo de outros bens de consumo não classificados... | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.12.00 | Serviços de instalação de alarmes contra incêndio | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.12.00 | Serviços de instalação de alarmes contra incêndio | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.13.00 | Serviços de instalação de sistemas de alarmes antifurto | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.13.00 | Serviços de instalação de sistemas de alarmes antifurto | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.14.00 | Serviços de instalação de antenas residenciais | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.14.00 | Serviços de instalação de antenas residenciais | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.31.00 | Serviços de instalação de equipamentos de aquecimento | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.31.00 | Serviços de instalação de equipamentos de aquecimento | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.32.00 | Serviços de instalação de equipamentos de ventilação e ar condicionado | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.32.00 | Serviços de instalação de equipamentos de ventilação e ar condicionado | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.40.00 | Serviços de instalação de gás | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.40.00 | Serviços de instalação de gás | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.90.00 | Serviços de instalação não classificados em subposições anteriores | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.90.00 | Serviços de instalação não classificados em subposições anteriores | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0107.60.00 | Serviços de instalação de cercas e grades | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0107.60.00 | Serviços de instalação de cercas e grades | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.10.00 | Serviços de instalação de produtos metálicos, exceto maquinário e equipamentos | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.10.00 | Serviços de instalação de produtos metálicos, exceto maquinário e equipamentos | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.21.10 | Serviços de montagem sob encomenda de turbinas industriais | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.21.10 | Serviços de montagem sob encomenda de turbinas industriais | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.21.90 | Serviços de instalação de maquinários, aparelhos e equipamentos industriais não classificados em itens anteriores | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.21.90 | Serviços de instalação de maquinários, aparelhos e equipamentos industriais não classificados em itens anteriores | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.22.00 | Serviços de instalação de computadores e seus periféricos e maquinário de escritório | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.22.00 | Serviços de instalação de computadores e seus periféricos e maquinário de escritório | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.23.00 | Serviços de instalação de equipamentos e aparelhos de comunicação, incluindo de rádio e de televisão | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.23.00 | Serviços de instalação de equipamentos e aparelhos de comunicação, incluindo de rádio e de televisão | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.24.00 | Serviços de instalação de maquinários, equipamentos, instrumentos e aparelhos médico-hospitalares, óticos e de precisão | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.24.00 | Serviços de instalação de maquinários, equipamentos, instrumentos e aparelhos médico-hospitalares, óticos e de precisão | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.25.10 | Serviços de instalação de sensores e sistemas de armas | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.25.10 | Serviços de instalação de sensores e sistemas de armas | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.25.20 | Serviços de instalação de maquinários, aparelhos e equipamentos de emprego militar | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.25.20 | Serviços de instalação de maquinários, aparelhos e equipamentos de emprego militar | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.26.10 | Serviços de montagem sob encomenda de motores, turborreatores e turbopropulsores aeronáuticos | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.26.10 | Serviços de montagem sob encomenda de motores, turborreatores e turbopropulsores aeronáuticos | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.26.90 | Serviços de instalação de maquinários e equipamentos de transporte não classificados em itens anteriores | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.26.90 | Serviços de instalação de maquinários e equipamentos de transporte não classificados em itens anteriores | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.29.00 | Serviços de instalação de maquinários, aparelhos e equipamentos não classificados em subposições anteriores | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.2003.29.00 | Serviços de instalação de maquinários, aparelhos e equipamentos não classificados em subposições anteriores | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.19.00 | Serviços de instalação elétrica não classificados em outras subposições | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.19.00 | Serviços de instalação elétrica não classificados em outras subposições | 050102 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.60.00 | Serviços de instalação de elevadores, transportadores e escadas rolantes | 050101 | 000001 |
| 14.06 | Instalação E Montagem De Aparelhos, Máquinas E Equipamentos, Inclusive Montagem Industrial, Prestados Ao Usuário Final, Exclusivamente Com Material Por Ele Fornecido. | 1.0106.60.00 | Serviços de instalação de elevadores, transportadores e escadas rolantes | 050102 | 000001 |
| 14.07 | Colocação de molduras e congêneres. | 1.2606.00.00 | Serviços pessoais não classificados em outras posições | 050101 | 000001 |
| 14.07 | Colocação de molduras e congêneres. | 1.2606.00.00 | Serviços pessoais não classificados em outras posições | 050102 | 000001 |
| 14.08 | Encadernação, gravação e douração... | 1.2101.22.00 | Serviços relacionados à impressão | 050101 | 000001 |
| 14.08 | Encadernação, gravação e douração... | 1.2101.22.00 | Serviços relacionados à impressão | 050102 | 000001 |
| 14.09 | Alfaiataria e costura... | 1.2604.00.00 | Serviços de confecção de roupas e outros artigos têxteis | 050101 | 000001 |
| 14.09 | Alfaiataria e costura... | 1.2604.00.00 | Serviços de confecção de roupas e outros artigos têxteis | 050102 | 000001 |
| 14.09 | Alfaiataria e costura... | 1.2002.40.00 | Serviços de manutenção de roupas e outros produtos têxteis | 050101 | 000001 |
| 14.09 | Alfaiataria e costura... | 1.2002.40.00 | Serviços de manutenção de roupas e outros produtos têxteis | 050102 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.10.00 | Serviços de limpeza de têxteis, exceto quando lavados a seco | 050101 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.10.00 | Serviços de limpeza de têxteis, exceto quando lavados a seco | 050102 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.20.00 | Serviços de limpeza a seco | 050101 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.20.00 | Serviços de limpeza a seco | 050102 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.30.00 | Serviços de tinturaria | 050101 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.30.00 | Serviços de tinturaria | 050102 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.40.00 | Serviços de passadoria de roupas e outros artigos têxteis | 050101 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.40.00 | Serviços de passadoria de roupas e outros artigos têxteis | 050102 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.90.00 | Serviços de lavanderia não classificados em subposições anteriores | 050101 | 000001 |
| 14.10 | Tinturaria e lavanderia. | 1.2601.90.00 | Serviços de lavanderia não classificados em subposições anteriores | 050102 | 000001 |
| 14.11 | Tapeçaria e estofamento em geral... | 1.2002.40.00 | Serviços de manutenção de roupas e outros produtos têxteis | 050101 | 000001 |
| 14.11 | Tapeçaria e estofamento em geral... | 1.2002.40.00 | Serviços de manutenção de roupas e outros produtos têxteis | 050102 | 000001 |
| 14.12 | Funilaria e lanternagem. | 1.2001.31.10 | Serviços de manutenção e reparo de veículos rodoviários motorizados | 050101 | 000001 |
| 14.12 | Funilaria e lanternagem. | 1.2001.31.10 | Serviços de manutenção e reparo de veículos rodoviários motorizados | 050102 | 000001 |
| 14.13 | Carpintaria e serralheria. | 1.0107.50.00 | Serviços de carpintaria e serralheria | 050101 | 000001 |
| 14.13 | Carpintaria e serralheria. | 1.0107.50.00 | Serviços de carpintaria e serralheria | 050102 | 000001 |
| 14.14 | Reboque intramunicipal, guindaste... | 1.0604.40.00 | Serviços de reboque para veículos particulares e comerciais | 050101 | 000001 |
| 14.14 | Reboque intramunicipal, guindaste... | 1.0604.40.00 | Serviços de reboque para veículos particulares e comerciais | 050102 | 000001 |
| 14.14 | Reboque intramunicipal, guindaste... | 1.0601.90.00 | Serviços de manuseio de cargas não classificados em outras subposições | 050101 | 000001 |
| 14.14 | Reboque intramunicipal, guindaste... | 1.0601.90.00 | Serviços de manuseio de cargas não classificados em outras subposições | 050102 | 000001 |
| 15.01 | Administração de quaisquer fundos... | 1.0901.40.00 | Serviços de cartão de crédito | 100301 | 820007 |
| 15.01 | Administração de quaisquer fundos... | 1.0905.21.00 | Serviços de gestão e administração de carteiras de ativos, exceto fundos de pensão | 100301 | 820007 |
| 15.01 | Administração de quaisquer fundos... | 1.0905.22.00 | Serviços de administração de fundos de investimento e fundos de pensão | 100301 | 820007 |
| 15.01 | Administração de quaisquer fundos... | 1.0905.23.00 | Serviços de gestão e administração de trustes | 100301 | 820007 |
| 15.01 | Administração de quaisquer fundos... | 1.0905.40.00 | Serviços relacionados à administração de mercados financeiros | 100301 | 820007 |
| 15.01 | Administração de quaisquer fundos... | 1.0906.40.00 | Serviços de gestão de fundos de previdência complementar | 100301 | 820007 |
| 15.02 | Abertura de contas em geral... | 1.0901.21.00 | Serviços de depósito para pessoas jurídicas | 100301 | 820007 |
| 15.02 | Abertura de contas em geral... | 1.0901.22.00 | Serviços de depósito para pessoas físicas | 100301 | 820007 |
| 15.02 | Abertura de contas em geral... | 1.0901.29.00 | Serviços de depósito para outros depositantes | 100301 | 820007 |
| 15.03 | Locação e manutenção de... | 1.1101.90.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos, sem operador, não classificados... | 010101 | 820007 |
| 15.03 | Locação e manutenção de... | 1.2001.89.00 | Serviços de manutenção e reparo de outras máquinas e equipamentos não classificados... | 050101 | 820007 |
| 15.03 | Locação e manutenção de... | 1.2001.89.00 | Serviços de manutenção e reparo de outras máquinas e equipamentos não classificados... | 050102 | 820007 |
| 15.04 | Fornecimento ou emissão de... | 1.1301.30.00 | Serviços de documentação e certificação, exceto serviços notariais e de registro | 100301 | 820007 |
| 15.04 | Fornecimento ou emissão de... | 1.1806.10.00 | Serviços de informação e análise de crédito | 100301 | 820007 |
| 15.05 | Cadastro, elaboração de... | 1.1806.10.00 | Serviços de informação e análise de crédito | 100301 | 820007 |
| 15.06 | Emissão, reemissão e... | 1.1301.30.00 | Serviços de documentação e certificação, exceto serviços notariais e de registro | 100301 | 820007 |
| 15.06 | Emissão, reemissão e... | 1.0702.00.00 | Serviços de coleta, transporte, remessa ou entrega de documentos ou pacotes, exceto remessas expressas | 100301 | 820007 |
| 15.07 | Acesso, movimentação, serviço e... | 1.0901.90.00 | Serviços financeiros, exceto serviços de banco de investimento, seguros e previdência complementar... | 100301 | 820007 |
| 15.07 | Acesso, movimentação, serviço e... | 1.1806.31.00 | Serviços de call center | 100301 | 820007 |
| 15.08 | Emissão, reemissão, alteração... | 1.0901.33.00 | Serviços de empréstimo e financiamento pessoal | 100301 | 820007 |
| 15.08 | Emissão, reemissão, alteração... | 1.0901.34.00 | Serviços de empréstimo e financiamento comercial | 100301 | 820007 |
| 15.08 | Emissão, reemissão, alteração... | 1.0901.35.00 | Serviços de empréstimo e financiamento industrial | 100301 | 820007 |
| 15.08 | Emissão, reemissão, alteração... | 1.0901.36.00 | Serviços de empréstimo e financiamento agrícola | 100301 | 820007 |
| 15.08 | Emissão, reemissão, alteração... | 1.0901.39.00 | Serviços de concessão de crédito não classificados em outras subposições | 100301 | 820007 |
| 15.08 | Emissão, reemissão, alteração... | 1.0905.50.00 | Serviços de consultoria financeira | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.11 | Arrendamento financeiro de veículos rodoviários para transporte de passageiros | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.12 | Arrendamento financeiro de veículos rodoviários para transporte de mercadorias | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.13 | Arrendamento financeiro de veículos e equipamentos ferroviários | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.14 | Arrendamento financeiro de outros equipamentos de transporte terrestre, incluindo veículos de uso misto | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.15 | Arrendamento financeiro de navios e outras embarcações | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.16 | Arrendamento financeiro de aeronaves | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.17 | Arrendamento financeiro de contêineres | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.21 | Arrendamento financeiro de máquinas e equipamentos agrícolas | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.22 | Arrendamento financeiro de máquinas e equipamentos de construção | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.23 | Arrendamento financeiro de máquinas e equipamentos de escritório, exceto computadores | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.24 | Arrendamento financeiro de computadores | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.25 | Arrendamento financeiro de equipamentos de telecomunicação | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.51.29 | Arrendamento financeiro de outras máquinas e equipamentos não classificados... | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.52.10 | Arrendamento financeiro de televisores e outros eletrodomésticos, bem como seus acessórios | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.52.20 | Arrendamento financeiro de mídias gravadas | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.52.30 | Arrendamento financeiro de móveis e eletrodomésticos | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.52.40 | Arrendamento financeiro de equipamentos para diversão e lazer | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.52.50 | Arrendamento financeiro de roupas de cama, mesa e banho | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.0901.52.90 | Arrendamento financeiro de outros bens não classificados em outras subposições | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.11.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de até oito passageiros, sem operador | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.12.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de carga, sem operador | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.13.00 | Arrendamento operacional ou aluguel de veículos e equipamentos ferroviários, sem operador | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.14.00 | Arrendamento operacional ou aluguel de outros equipamentos de transporte terrestre, incluindo veículos de uso misto, sem operador | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.15.00 | Arrendamento operacional ou aluguel de navios e outras embarcações, sem tripulação | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.16.00 | Arrendamento operacional ou aluguel de aeronaves, sem tripulação | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.17.00 | Arrendamento operacional ou aluguel de contêineres | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.20.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos agrícolas, sem operador | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.30.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de construção, sem operador | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.40.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de escritório, exceto computadores, sem operador | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.50.00 | Arrendamento operacional ou aluguel de computadores, sem operador | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.60.00 | Arrendamento operacional ou aluguel de equipamentos de telecomunicação, sem operador | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1101.90.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos, sem operador, não classificados... | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1102.10.00 | Arrendamento operacional ou aluguel de televisores e outros eletrodomésticos, bem como seus acessórios | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1102.20.00 | Arrendamento operacional ou aluguel de mídias gravadas | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1102.30.00 | Arrendamento operacional ou aluguel de móveis e eletrodomésticos | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1102.40.00 | Arrendamento operacional ou aluguel de equipamentos para diversão e lazer | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1102.50.00 | Arrendamento operacional ou aluguel de roupas de cama, mesa e banho | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1102.60.00 | Arrendamento operacional ou aluguel de roupas e calçados | 100301 | 820007 |
| 15.09 | Arrendamento mercantil de quaisquer bens... | 1.1102.90.00 | Arrendamento operacional ou aluguel de outros bens não classificados em outras subposições | 100301 | 820007 |
| 15.10 | Serviços relacionados a cobranças... | 1.1806.20.00 | Serviços de cobrança | 100301 | 820007 |
| 15.10 | Serviços relacionados a cobranças... | 1.0901.90.00 | Serviços financeiros, exceto serviços de banco de investimento, seguros e previdência complementar... | 100301 | 820007 |
| 15.11 | Devolução de títulos, protesto... | 1.0901.90.00 | Serviços financeiros, exceto serviços de banco de investimento, seguros e previdência complementar... | 100301 | 820007 |
| 15.12 | Custódia em geral... | 1.0905.30.00 | Serviços de custódia e guarda | 100301 | 820007 |
| 15.13 | Serviços relacionados a câmbio... | 1.0905.60.00 | Serviços de câmbio | 100301 | 820007 |
| 15.14 | Fornecimento, emissão, reemissão... | 1.0901.40.00 | Serviços de cartão de crédito | 100301 | 820007 |
| 15.14 | Fornecimento, emissão, reemissão... | 1.0901.90.00 | Serviços financeiros, exceto serviços de banco de investimento, seguros e previdência complementar... | 100301 | 820007 |
| 15.15 | Compensação de cheques e quaisquer... | 1.0901.21.00 | Serviços de depósito para pessoas jurídicas | 100301 | 820007 |
| 15.15 | Compensação de cheques e quaisquer... | 1.0901.22.00 | Serviços de depósito para pessoas físicas | 100301 | 820007 |
| 15.15 | Compensação de cheques e quaisquer... | 1.0901.29.00 | Serviços de depósito para outros depositantes | 100301 | 820007 |
| 15.15 | Compensação de cheques e quaisquer... | 1.0905.13.00 | Serviços de compensação de transações financeiras, incluindo com ativos financeiros (clearinghouse) | 100301 | 820007 |
| 15.16 | Emissão, reemissão, liquidação... | 1.0901.90.00 | Serviços financeiros, exceto serviços de banco de investimento, seguros e previdência complementar... | 100301 | 820007 |
| 15.17 | Emissão, fornecimento, devolução... | 1.0901.90.00 | Serviços financeiros, exceto serviços de banco de investimento, seguros e previdência complementar... | 100301 | 820007 |
| 15.18 | Serviços relacionados a crédito imobiliário... | 1.0901.31.00 | Serviços de financiamento imobiliário residencial | 100301 | 820007 |
| 15.18 | Serviços relacionados a crédito imobiliário... | 1.0901.32.00 | Serviços de financiamento imobiliário não residencial | 100301 | 820007 |
| 15.18 | Serviços relacionados a crédito imobiliário... | 1.1001.30.00 | Serviços de avaliação imobiliária | 100301 | 820007 |
| 16.01 | Transporte coletivo municipal rodoviário... | 1.0401.11.19 | Serviços de transporte rodoviário local regular de passageiros, exceto em áreas metropolitanas... | 060101 | 400001 |
| 16.01 | Transporte coletivo municipal rodoviário... | 1.0401.16.10 | Serviços de transporte ferroviário local de passageiros | 060101 | 200021 |
| 16.01 | Transporte coletivo municipal rodoviário... | 1.0401.16.20 | Serviços de transporte metroviário (metrô) local de passageiros | 060101 | 400001 |
| 16.01 | Transporte coletivo municipal rodoviário... | 1.0401.16.90 | Serviços de transporte local de passageiros por veículos sobre trilhos não classificados... | 060101 | 000001 |
| 16.01 | Transporte coletivo municipal rodoviário... | 1.0401.21.10 | Serviços de transporte aquaviário local de passageiros, por navegação interior, em balsas | 060101 | 200021 |
| 16.01 | Transporte coletivo municipal rodoviário... | 1.0401.21.90 | Serviços de transporte aquaviário local de passageiros, por navegação interior não classificados... | 060101 | 000001 |
| 16.01 | Transporte coletivo municipal rodoviário... | 1.0401.30.00 | Serviços de transporte integrado local de passageiros | 060101 | 400001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.21.90 | Serviços de transporte aquaviário local de passageiros, por navegação interior não classificados... | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.11.11 | Serviços de transporte rodoviário local prestados exclusivamente por ônibus | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.12.10 | Serviços de transporte escolar | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.12.20 | Serviços de transporte para aeroportos (shuttle) | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.12.90 | Serviços especiais de transporte rodoviário local regular de passageiros não classificados... | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.13.00 | Serviços de táxi | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.14.00 | Serviços de carro com motorista, exceto táxi | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.15.10 | Serviços de fretamento contínuo local | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.15.20 | Serviços de fretamento ocasional ou turístico local | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.19.00 | Serviços de transporte terrestre local de passageiros não classificados em outras subposições | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.21.20 | Serviços de transporte aquaviário local de passageiros, por navegação interior, em navios de cruzeiro | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.22.00 | Serviços de transporte aquaviário local de passageiros por fretamento | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.29.00 | Serviços de transporte aquaviário local de passageiros não classificados em outras subposições | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.41.00 | Serviços de táxi aéreo local | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.42.00 | Serviços de transporte aéreo local de passageiros por fretamento | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.49.00 | Serviços de transporte aéreo local de passageiros não classificados em outras subposições | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0401.90.00 | Serviços de transporte local de passageiros não classificados em outras subposições | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0404.10.00 | Aluguel de veículos rodoviários de passageiros com motorista | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0404.20.00 | Aluguel de embarcações de passageiros com tripulação | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0404.30.00 | Aluguel de aeronaves de passageiros com tripulação | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0405.00.00 | Afretamento por tempo de embarcações de passageiros | 060101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.11.10 | Serviços de transporte rodoviário de cargas sólidas a granel | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.11.20 | Serviços de transporte rodoviário de cargas líquidas ou liquefeitas a granel | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.11.30 | Serviços de transporte rodoviário de cargas gasosas a granel | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.12.10 | Serviços de transporte rodoviário de carga solta, não unitizada | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.12.20 | Serviços de transporte rodoviário de carga unitizada | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.12.30 | Serviços de transporte rodoviário de carga refrigerada ou climatizada | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.13.10 | Serviços de transporte rodoviário de cargas em contêineres refrigerados ou climatizados | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.13.20 | Serviços de transporte rodoviário de cargas em contêineres não refrigerados ou climatizados | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.14.10 | Serviços de transporte rodoviário de cargas vivas | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.14.20 | Serviços de transporte rodoviário de mudanças domésticas e mobília de escritório e outros objetos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.14.30 | Serviços de transporte rodoviário de cargas superdimensionadas | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.14.40 | Serviços de transporte rodoviário de veículos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.14.51 | Serviços de transporte rodoviário de combustíveis, lubrificantes e GLP, incluindo em cilindros metálicos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.14.52 | Serviços de transporte rodoviário de produtos químicos perigosos, exceto lubrificantes e GLP | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.14.59 | Serviços de transporte rodoviário de produtos perigosos não classificados em subitens anteriores | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.15.00 | Serviços de transporte rodoviário de cargas postais e malotes | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.19.00 | Serviços de transporte rodoviário de cargas não classificados em outras subposições | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0501.31.00 | Serviços de transporte de petróleo, gás natural e combustível por meio de dutos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.11.10 | Serviços de transporte aquaviário por navegação interior de cargas sólidas a granel | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.11.20 | Serviços de transporte aquaviário por navegação interior de cargas líquidas ou liquefeitas a granel | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.11.30 | Serviços de transporte aquaviário por navegação interior de cargas gasosas a granel | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.12.10 | Serviços de transporte aquaviário por navegação interior de carga solta, não unitizada | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.12.20 | Serviços de transporte aquaviário por navegação interior de carga unitizada | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.12.30 | Serviços de transporte aquaviário por navegação interior de carga refrigerada ou climatizada | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.13.10 | Serviços de transporte aquaviário por navegação interior de cargas em contêineres refrigerados ou climatizados | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.13.20 | Serviços de transporte aquaviário por navegação interior de cargas em contêineres não refrigerados ou climatizados | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.14.10 | Serviços de transporte aquaviário por navegação interior de cargas vivas | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.14.20 | Serviços de transporte aquaviário por navegação interior de mudanças domésticas e mobília de escritório e outros objetos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.14.30 | Serviços de transporte aquaviário por navegação interior de cargas superdimensionadas | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.14.40 | Serviços de transporte aquaviário por navegação interior de veículos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.14.51 | Serviços de transporte aquaviário por navegação interior de combustíveis, lubrificantes e GLP, incluindo em cilindros metálicos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.14.52 | Serviços de transporte aquaviário por navegação interior de produtos químicos perigosos, exceto lubrificantes e GLP | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.14.59 | Serviços de transporte aquaviário por navegação interior de produtos perigosos não classificados... | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.14.90 | Serviços de transporte aquaviário por navegação interior de cargas especiais não classificados... | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.19.00 | Serviços de transporte aquaviário por navegação interior de cargas não classificados... | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.21.10 | Serviços de transporte aquaviário costeiro de cargas sólidas a granel | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.21.20 | Serviços de transporte aquaviário costeiro de cargas líquidas ou liquefeitas a granel | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.21.30 | Serviços de transporte aquaviário costeiro de cargas gasosas a granel | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.22.10 | Serviços de transporte aquaviário costeiro de carga solta, não unitizada | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.22.20 | Serviços de transporte aquaviário costeiro de carga unitizada | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.22.30 | Serviços de transporte aquaviário costeiro de carga refrigerada ou climatizada | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.23.10 | Serviços de transporte aquaviário costeiro de cargas em contêineres refrigerados ou climatizados | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.23.20 | Serviços de transporte aquaviário costeiro de cargas em contêineres não classificados... | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.24.10 | Serviços de transporte aquaviário costeiro de cargas vivas | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.24.20 | Serviços de transporte aquaviário costeiro de mudanças domésticas e mobília de escritório e outros objetos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.24.30 | Serviços de transporte aquaviário costeiro de cargas superdimensionadas | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.24.40 | Serviços de transporte aquaviário costeiro de veículos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.24.51 | Serviços de transporte aquaviário costeiro de combustíveis, lubrificantes e GLP, incluindo em cilindros metálicos | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.24.52 | Serviços de transporte aquaviário costeiro de produtos químicos perigosos, exceto lubrificantes e GLP | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.24.59 | Serviços de transporte aquaviário costeiro de produtos perigosos não classificados... | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0502.29.00 | Serviços de transporte aquaviário costeiro de cargas não classificados em outras subposições | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0505.10.00 | Aluguel de veículos rodoviários de carga com operador | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0505.20.00 | Aluguel de embarcações de carga com tripulação | 070101 | 000001 |
| 16.02 | Outros serviços de transporte municipal. | 1.0505.30.00 | Aluguel de aeronaves de carga com tripulação | 070101 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.0608.40.00 | Serviços de consolidação ou desconsolidação documental de cargas no transporte multimodal | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1001.40.00 | Serviços de consultoria imobiliária | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1001.50.00 | Serviços de assessoria em gestão de condomínios | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1001.90.00 | Serviços imobiliários não classificados em outras subposições | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1301.30.00 | Serviços de documentação e certificação, exceto serviços notariais e de registro | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1303.10.00 | Serviços de consultoria tributária para pessoas jurídicas | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1303.20.00 | Serviços de consultoria tributária para pessoas físicas | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1401.11.00 | Serviços de consultoria em gestão estratégica | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1401.13.00 | Serviços de consultoria em gestão de recursos humanos | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1401.14.00 | Serviços de consultoria em gestão de marketing | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1401.15.00 | Serviços de consultoria em gestão operacional | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1401.16.00 | Serviços de consultoria em gestão de energia | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1401.17.00 | Serviços de consultoria em gestão da cadeia de suprimentos | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1401.18.00 | Serviços de consultoria em gestão hospitalar | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1401.19.00 | Serviços de consultoria em gestão de negócios não classificados em outras subposições | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1401.39.00 | Serviços de assessoria de negócios não classificados em outras subposições | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1410.10.00 | Serviços de consultoria ambiental | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1410.90.00 | Serviços de consultoria técnica e científica não classificados em outras subposições | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1412.00.00 | Serviços de registro de marcas e franquias comerciais, exceto licenças de uso de direitos | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1413.00.00 | Serviços de prospecção de clientes | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1414.00.00 | Serviços de prospecção de fornecedores | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1407.00.00 | Serviços de pesquisa de mercado e de opinião pública | 100301 | 000001 |
| 17.01 | Assessoria ou consultoria de qualquer... | 1.1806.10.00 | Serviços de informação e análise de crédito | 100301 | 000001 |
| 17.02 | Datilografia, digitação, estenografia... | 1.1411.00.00 | Serviços de tradução e interpretação | 100301 | 000001 |
| 17.02 | Datilografia, digitação, estenografia... | 1.1806.31.00 | Serviços de call center | 100301 | 000001 |
| 17.02 | Datilografia, digitação, estenografia... | 1.1806.39.00 | Serviços de apoio a negócios por telefone não classificados em outras subposições | 100301 | 000001 |
| 17.02 | Datilografia, digitação, estenografia... | 1.1806.40.00 | Serviços combinados de apoio a escritório e administrativo | 100301 | 000001 |
| 17.02 | Datilografia, digitação, estenografia... | 1.1806.52.00 | Serviços de execução e envio de mala direta e criação de listas de endereços | 100301 | 000001 |
| 17.02 | Datilografia, digitação, estenografia... | 1.1806.53.00 | Serviços de preparação de documentos | 100301 | 000001 |
| 17.02 | Datilografia, digitação, estenografia... | 1.1806.59.00 | Serviços especializados de apoio a escritório não classificados em outras subposições | 100301 | 000001 |
| 17.03 | Planejamento, coordenação, programação... | 1.1401.29.00 | Serviços de gestão não classificados em outras subposições | 100301 | 000001 |
| 17.03 | Planejamento, coordenação, programação... | 1.1401.39.00 | Serviços de assessoria de negócios não classificados em outras subposições | 100301 | 000001 |
| 17.04 | Recrutamento, agenciamento, seleção... | 1.1801.11.00 | Serviço de recrutamento e seleção de executivos | 100301 | 000001 |
| 17.04 | Recrutamento, agenciamento, seleção... | 1.1801.12.00 | Serviço de recrutamento e seleção de profissionais, exceto executivos | 100301 | 000001 |
| 17.05 | Fornecimento de mão de obra... | 1.1801.21.00 | Serviços de fornecimento de mão de obra terceirizada, exceto temporária | 100301 | 000001 |
| 17.05 | Fornecimento de mão de obra... | 1.1801.22.00 | Serviços de fornecimento de mão de obra temporária | 100301 | 000001 |
| 17.05 | Fornecimento de mão de obra... | 1.1801.29.00 | Serviços de fornecimento de mão de obra não classificados em outras subposições | 100301 | 000001 |
| 17.06 | Propaganda e publicidade... | 1.1406.11.00 | Serviços de campanhas publicitárias | 100301 | 000001 |
| 17.06 | Propaganda e publicidade... | 1.1406.12.00 | Serviços de marketing direto e mala direta | 100301 | 000001 |
| 17.06 | Propaganda e publicidade... | 1.1406.19.00 | Serviços de publicidade não classificados em outras subposições | 100301 | 000001 |
| 17.06 | Propaganda e publicidade... | 1.1407.00.00 | Serviços de pesquisa de mercado e de opinião pública | 100301 | 000001 |
| 17.08 | Franchising. | 1.1110.00.00 | Franquia | 100301 | 000001 |
| 17.09 | Perícias, laudos... | 1.1404.41.00 | Serviços de análise laboratorial de solos, sementes e outros materiais propagativos... | 100301 | 000001 |
| 17.09 | Perícias, laudos... | 1.1404.42.00 | Serviços de análise e exame técnico de propriedades físicas | 100301 | 000001 |
| 17.09 | Perícias, laudos... | 1.1404.43.00 | Serviços de análise e exame técnico de sistemas elétricos e mecânicos | 100301 | 000001 |
| 17.09 | Perícias, laudos... | 1.1404.44.00 | Serviços de inspeção técnica de veículos de transporte rodoviário | 100301 | 000001 |
| 17.09 | Perícias, laudos... | 1.1404.49.00 | Serviços de análise e exame técnico não classificados em outras subposições | 100301 | 000001 |
| 17.10 | Planejamento, organização e... | 1.1806.61.00 | Serviços de assistência e organização de convenções | 040101 | 000001 |
| 17.10 | Planejamento, organização e... | 1.1806.62.00 | Serviços de assistência e organização de feiras comerciais | 040101 | 000001 |
| 17.10 | Planejamento, organização e... | 1.1806.63.00 | Serviços de assistência e organização de exposições e outros eventos | 040101 | 000001 |
| 17.11 | Organização de festas e... | 1.1806.63.00 | Serviços de assistência e organização de exposições e outros eventos | 100301 | 000001 |
| 17.11 | Organização de festas e... | 1.0301.10.00 | Fornecimento de refeições acompanhadas de serviços de restaurante | 030101 | 000001 |
| 17.11 | Organização de festas e... | 1.0301.10.00 | Fornecimento de refeições acompanhadas de serviços de restaurante | 030102 | 000001 |
| 17.11 | Organização de festas e... | 1.0301.31.00 | Catering para eventos | 030101 | 000001 |
| 17.11 | Organização de festas e... | 1.0301.31.00 | Catering para eventos | 030102 | 000001 |
| 17.11 | Organização de festas e... | 1.0301.39.00 | Catering, incluindo refeições, sob contrato não classificado em outras subposições | 030101 | 000001 |
| 17.11 | Organização de festas e... | 1.0301.39.00 | Catering, incluindo refeições, sob contrato não classificado em outras subposições | 030102 | 000001 |
| 17.12 | Administração geral... | 1.1001.11.00 | Serviços de administração e locação de imóveis residenciais | 020301 | 200046 |
| 17.12 | Administração geral... | 1.1001.12.90 | Serviços de administração e locação de outros imóveis não residenciais | 020301 | 200046 |
| 17.12 | Administração geral... | 1.1401.21.00 | Serviços de gestão de processos de negócios | 100301 | 000001 |
| 17.12 | Administração geral... | 1.1401.22.00 | Serviços de gestão hospitalar | 100301 | 000001 |
| 17.13 | Leilão e congêneres. | 1.1806.90.00 | Serviços de apoio não classificados em outras subposições | 100301 | 000001 |
| 17.14 | Advocacia. | 1.1301.10.00 | Serviços de representação e consultoria jurídica criminal | 100301 | 200052 |
| 17.14 | Advocacia. | 1.1301.20.00 | Serviços de representação e consultoria jurídica em outras áreas do direito, exceto consultoria tributária | 100301 | 200052 |
| 17.14 | Advocacia. | 1.1301.90.00 | Serviços jurídicos não classificados em outras subposições | 100301 | 200052 |
| 17.14 | Advocacia. | 1.1303.10.00 | Serviços de consultoria tributária para pessoas jurídicas | 100301 | 200052 |
| 17.14 | Advocacia. | 1.1303.20.00 | Serviços de consultoria tributária para pessoas físicas | 100301 | 200052 |
| 17.15 | Arbitragem de qualquer espécie... | 1.1301.40.00 | Serviços de arbitragem, conciliação e mediação | 100301 | 000001 |
| 17.16 | Auditoria. | 1.1302.11.00 | Serviços de auditoria contábil | 100301 | 200052 |
| 17.16 | Auditoria. | 1.1302.19.00 | Serviços de auditoria não classificados em outras subposições | 100301 | 000001 |
| 17.17 | Organização e métodos. | 1.1806.90.00 | Serviços de apoio não classificados em outras subposições | 100301 | 000001 |
| 17.18 | Atuária e cálculos técnicos... | 1.0906.30.00 | Serviços atuariais | 100301 | 000001 |
| 17.19 | Contabilidade, incluindo... | 1.1302.21.00 | Serviços de contabilidade | 100301 | 200052 |
| 17.19 | Contabilidade, incluindo... | 1.1302.22.00 | Serviços de escrituração contábil | 100301 | 200052 |
| 17.19 | Contabilidade, incluindo... | 1.1302.23.00 | Serviços de folha de pagamento | 100301 | 200052 |
| 17.20 | Consultoria econômica ou financeira... | 1.0905.50.00 | Serviços de consultoria financeira | 100301 | 200052 |
| 17.20 | Consultoria econômica ou financeira... | 1.0905.70.00 | Serviços de classificação de risco de crédito | 100301 | 200052 |
| 17.20 | Consultoria econômica ou financeira... | 1.0905.80.00 | Serviços fiduciários | 100301 | 200052 |
| 17.20 | Consultoria econômica ou financeira... | 1.1401.12.00 | Serviços de consultoria em gestão financeira | 100301 | 200052 |
| 17.21 | Estatística. | 1.1415.00.00 | Serviços profissionais, técnicos e gerenciais não classificados em outras posições | 100301 | 200052 |
| 17.22 | Cobrança geral. | 1.1806.20.00 | Serviços de cobrança | 100301 | 000001 |
| 17.23 | Assessoria, análise, avaliação... | 1.0908.00.00 | Fomento comercial (factoring) | 100301 | 000001 |
| 17.24 | Apresentação de palestras... | 1.2205.14.00 | Serviços de palestras e conferências | 030101 | 000001 |
| 17.24 | Apresentação de palestras... | 1.2205.14.00 | Serviços de palestras e conferências | 030102 | 000001 |
| 17.24 | Apresentação de palestras... | 1.2205.14.00 | Serviços de palestras e conferências | 100301 | 000001 |
| 17.25 | Inserção de textos, desenhos... | 1.1406.33.00 | Venda de espaço publicitário na internet, exceto por comissão | 100101 | 000001 |
| 17.25 | Inserção de textos, desenhos... | 1.1406.34.00 | Venda de espaço publicitário em mídia externa, exceto por comissão | 100101 | 000001 |
| 17.25 | Inserção de textos, desenhos... | 1.1406.39.00 | Venda de espaço ou tempo publicitário, exceto por comissão, não classificado em outras subposições | 100101 | 000001 |
| 18.01 | Serviços de regulação de sinistros... | 1.0906.20.00 | Serviços de perícia e avaliação de seguros e resseguros | 100301 | 000001 |
| 19.01 | Serviços de distribuição e venda... | 1.0905.11.00 | Serviços de corretagem de valores mobiliários | 100301 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0401.21.20 | Serviços de transporte aquaviário local de passageiros, por navegação interior, em navios de cruzeiro | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0601.10.00 | Serviços de manuseio de contêineres | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0601.90.00 | Serviços de manuseio de cargas não classificados em outras subposições | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0605.10.00 | Serviços de operação de portos e canais, exceto manuseio de cargas | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0605.20.00 | Serviços de praticagem e atracação | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0605.30.00 | Serviços de salvamento de embarcações | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0605.40.00 | Serviços de apoio à navegação | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0605.90.00 | Serviços de apoio ao transporte aquaviário não classificados em outras subposições | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0602.10.00 | Serviços de armazenagem frigorificada | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0602.21.00 | Serviços de armazenagem de petróleo e seus derivados | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0602.22.00 | Serviços de armazenagem de combustíveis, lubrificantes e GLP, inclusive em botijões metálicos | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0602.23.00 | Serviços de armazenagem de produtos químicos perigosos | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0602.29.00 | Serviços de armazenagem de produtos perigosos não classificados em outras subposições | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0602.31.00 | Serviços de armazenamento de granéis sólidos | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0602.32.00 | Serviços de armazenagem de granéis líquidos ou liquefeitos | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0602.33.00 | Serviços de armazenagem de granéis gasosos | 050201 | 000001 |
| 20.01 | Serviços portuários, ferroportuários... | 1.0602.90.00 | Serviços de armazenagem não classificados em outras subposições | 050201 | 000001 |
| 20.02 | Serviços aeroportuários... | 1.0601.90.00 | Serviços de manuseio de cargas não classificados em outras subposições | 050101 | 000001 |
| 20.02 | Serviços aeroportuários... | 1.0602.90.00 | Serviços de armazenagem não classificados em outras subposições | 050101 | 000001 |
| 20.02 | Serviços aeroportuários... | 1.0606.11.00 | Serviços de operação aeroportuária, exceto manuseio de cargas | 100301 | 000001 |
| 20.02 | Serviços aeroportuários... | 1.0606.12.00 | Serviços de controle de tráfego aéreo | 100301 | 000001 |
| 20.02 | Serviços aeroportuários... | 1.0606.19.00 | Serviços de apoio ao transporte aéreo não classificados em outras subposições | 100301 | 000001 |
| 20.02 | Serviços aeroportuários... | 1.0606.20.00 | Serviços de apoio ao transporte aeroespacial | 100301 | 000001 |
| 20.03 | Serviços de terminais rodoviários... | 1.0601.90.00 | Serviços de manuseio de cargas não classificados em outras subposições | 050101 | 000001 |
| 20.03 | Serviços de terminais rodoviários... | 1.0603.00.00 | Serviços de apoio ao transporte ferroviário | 100301 | 000001 |
| 20.03 | Serviços de terminais rodoviários... | 1.0604.10.00 | Serviços de estações rodoviárias | 100301 | 000001 |
| 20.03 | Serviços de terminais rodoviários... | 1.0604.90.00 | Serviços de apoio ao transporte rodoviário não classificados em outras subposições | 100301 | 000001 |
| 21.01 | Serviços de registros públicos... | 1.1304.00.00 | Serviços notariais e de registro | 100301 | 000001 |
| 22.01 | Serviços de exploração de rodovia... | 1.0604.21.00 | Serviços de operação de rodovias | 080101 | 820006 |
| 22.01 | Serviços de exploração de rodovia... | 1.0604.22.00 | Serviços de operação de pontes e túneis | 080101 | 820006 |
| 23.01 | Serviços de programação e comunicação... | 1.1409.21.00 | Serviços de desenho industrial de embalagens, expositores de loja e objetos promocionais... | 100301 | 000001 |
| 23.01 | Serviços de programação e comunicação... | 1.1409.22.00 | Serviços de desenho industrial de produtos, utensílios, equipamentos, vestuário... | 100301 | 000001 |
| 23.01 | Serviços de programação e comunicação... | 1.1409.23.00 | Serviços de desenho industrial de máquinas, equipamentos, acessórios e objetos de uso industrial... | 100301 | 000001 |
| 23.01 | Serviços de programação e comunicação... | 1.1409.24.00 | Serviços de desenho industrial de mobiliário e itens de decoração | 100301 | 000001 |
| 23.01 | Serviços de programação e comunicação... | 1.1409.25.00 | Serviços de desenho industrial de utensílios e equipamentos eletrodomésticos e eletrônicos | 100301 | 000001 |
| 23.01 | Serviços de programação e comunicação... | 1.1409.29.00 | Serviços de desenho industrial não classificados em outras subposições | 100301 | 000001 |
| 23.01 | Serviços de programação e comunicação... | 1.1409.30.00 | Serviços de design de marcas, imagens, objetos gráficos e digitais | 100301 | 000001 |
| 23.01 | Serviços de programação e comunicação... | 1.1409.90.00 | Serviços de design não classificados em outras subposições | 100301 | 000001 |
| 24.01 | Serviços de chaveiro, confecção... | 1.2606.00.00 | Serviços pessoais não classificados em outras posições | 050101 | 000001 |
| 24.01 | Serviços de chaveiro, confecção... | 1.2606.00.00 | Serviços pessoais não classificados em outras posições | 050102 | 000001 |
| 24.01 | Serviços de chaveiro, confecção... | 1.2606.00.00 | Serviços pessoais não classificados em outras posições | 100301 | 000001 |
| 25.01 | Funerais, inclusive fornecimento... | 1.1405.30.00 | Serviços funerários, de cremação e de embalsamamento de animais | 100301 | 000001 |
| 25.01 | Funerais, inclusive fornecimento... | 1.2603.00.00 | Serviços funerários, de cremação e de embalsamamento | 100301 | 200029 |
| 25.02 | Translado intramunicipal e... | 1.1405.30.00 | Serviços funerários, de cremação e de embalsamamento de animais | 100301 | 000001 |
| 25.02 | Translado intramunicipal e... | 1.2603.00.00 | Serviços funerários, de cremação e de embalsamamento | 100301 | 200029 |
| 25.03 | Planos ou convênios funerários. | 1.2603.00.00 | Serviços funerários, de cremação e de embalsamamento | 100301 | 820002 |
| 25.04 | Manutenção e conservação de... | 1.2603.00.00 | Serviços funerários, de cremação e de embalsamamento | 020201 | 000001 |
| 25.05 | Cessão de uso de espaços em... | 1.2603.00.00 | Serviços funerários, de cremação e de embalsamamento | 020101 | 000001 |
| 26.01 | Serviços de coleta, remessa... | 1.0501.15.00 | Serviços de transporte rodoviário de cargas postais e malotes | 070101 | 000001 |
| 26.01 | Serviços de coleta, remessa... | 1.0608.10.00 | Serviços de coleta e entrega de cargas no transporte multimodal | 070101 | 000001 |
| 26.01 | Serviços de coleta, remessa... | 1.0701.00.00 | Serviços postais e de telegrama | 070101 | 000001 |
| 26.01 | Serviços de coleta, remessa... | 1.0702.00.00 | Serviços de coleta, transporte, remessa ou entrega de documentos ou pacotes, exceto remessas expressas | 070101 | 000001 |
| 26.01 | Serviços de coleta, remessa... | 1.0703.00.00 | Serviços de remessas expressas | 070101 | 000001 |
| 26.01 | Serviços de coleta, remessa... | 1.1802.40.00 | Serviços de carro-forte | 070101 | 000001 |
| 27.01 | Serviços de assistência social. | 1.2304.11.00 | Serviços de reabilitação vocacional para pessoas com deficiência | 030101 | 200052 |
| 27.01 | Serviços de assistência social. | 1.2304.11.00 | Serviços de reabilitação vocacional para pessoas com deficiência | 030102 | 200052 |
| 27.01 | Serviços de assistência social. | 1.2304.12.00 | Serviços de reabilitação vocacional para desempregados | 030101 | 200052 |
| 27.01 | Serviços de assistência social. | 1.2304.12.00 | Serviços de reabilitação vocacional para desempregados | 030102 | 200052 |
| 27.01 | Serviços de assistência social. | 1.2304.19.00 | Serviço de reabilitação vocacional não classificado em subposições anteriores | 030101 | 200052 |
| 27.01 | Serviços de assistência social. | 1.2304.19.00 | Serviço de reabilitação vocacional não classificado em subposições anteriores | 030102 | 200052 |
| 27.01 | Serviços de assistência social. | 1.2304.20.00 | Serviços de orientação e aconselhamento relacionados a crianças e adolescentes | 030101 | 200052 |
| 27.01 | Serviços de assistência social. | 1.2304.20.00 | Serviços de orientação e aconselhamento relacionados a crianças e adolescentes | 030102 | 200052 |
| 27.01 | Serviços de assistência social. | 1.2304.90.00 | Serviços de assistência social sem alojamento não classificados em subposições anteriores | 100301 | 200052 |
| 28.01 | Serviços de avaliação de bens... | 1.1404.14.00 | Serviços de informações para avaliação e exploração de recursos naturais | 100301 | 000001 |
| 28.01 | Serviços de avaliação de bens... | 1.1001.30.00 | Serviços de avaliação imobiliária | 100301 | 000001 |
| 28.01 | Serviços de avaliação de bens... | 1.0902.10.00 | Serviços de valoração de ativos | 100301 | 000001 |
| 29.01 | Serviços de biblioteconomia. | 1.1705.10.00 | Serviços de biblioteca | 030101 | 000001 |
| 29.01 | Serviços de biblioteconomia. | 1.1705.10.00 | Serviços de biblioteca | 100301 | 000001 |
| 29.01 | Serviços de biblioteconomia. | 1.1705.20.00 | Serviços de arquivo | 100301 | 000001 |
| 30.01 | Biologia, biotecnologia e... | 1.1415.00.00 | Serviços profissionais, técnicos e gerenciais não classificados em outras posições | 100301 | 200052 |
| 31.01 | Serviços técnicos em edificações... | 1.1415.00.00 | Serviços profissionais, técnicos e gerenciais não classificados em outras posições | 100301 | 200052 |
| 32.01 | Serviços de desenhos técnicos. | 1.1409.90.00 | Serviços de design não classificados em outras subposições | 100301 | 000001 |
| 33.01 | Desembaraço aduaneiro, comissários... | 1.0204.00.00 | Serviços de desembaraço aduaneiro | 100301 | 000001 |
| 33.01 | Desembaraço aduaneiro, comissários... | 1.2606.00.00 | Serviços pessoais não classificados em outras posições | 100301 | 000001 |
| 34.01 | Investigação particular, detetives... | 1.1802.10.00 | Serviços de investigação | 100301 | 000001 |
| 35.01 | Reportagem, assessoria de imprensa... | 1.1401.31.00 | Serviços de assessoria de imprensa | 100301 | 000001 |
| 35.01 | Reportagem, assessoria de imprensa... | 1.1401.31.00 | Serviços de assessoria de imprensa | 100301 | 200040 |
| 35.01 | Reportagem, assessoria de imprensa... | 1.1401.32.00 | Serviços de relações públicas | 100301 | 200052 |
| 35.01 | Reportagem, assessoria de imprensa... | 1.1401.32.00 | Serviços de relações públicas | 100301 | 200040 |
| 35.01 | Reportagem, assessoria de imprensa... | 1.1704.10.00 | Serviços de agência de notícias para jornais e periódicos | 100301 | 000001 |
| 35.01 | Reportagem, assessoria de imprensa... | 1.1704.20.00 | Serviços de agência de notícias para mídias audiovisuais | 100301 | 000001 |
| 36.01 | Serviços de meteorologia. | 1.1404.30.00 | Serviços meteorológicos e de previsão do tempo | 100301 | 000001 |
| 37.01 | Serviços de artistas, atletas... | 1.1806.81.00 | Serviços de agenciamento de modelos | 100301 | 000001 |
| 37.01 | Serviços de artistas, atletas... | 1.1806.82.00 | Serviços de agenciamento de artistas | 100301 | 000001 |
| 37.01 | Serviços de artistas, atletas... | 1.1806.83.00 | Serviços de agenciamento de atletas | 100301 | 000001 |
| 37.01 | Serviços de artistas, atletas... | 1.2506.00.00 | Serviços de parques de diversão e parques temáticos | 100301 | 000001 |
| 37.01 | Serviços de artistas, atletas... | 1.2503.10.00 | Serviços de atuação artística | 100301 | 000001 |
| 37.01 | Serviços de artistas, atletas... | 1.2503.10.00 | Serviços de atuação artística | 100301 | 200039 |
| 38.01 | Serviços de museologia. | 1.2504.11.00 | Serviços de museus | 030101 | 200039 |
| 38.01 | Serviços de museologia. | 1.2504.11.00 | Serviços de museus | 030101 | 000001 |
| 38.01 | Serviços de museologia. | 1.2504.12.00 | Serviços de preservação e operação de locais e construções históricas | 030101 | 000001 |
| 38.01 | Serviços de museologia. | 1.2504.12.00 | Serviços de preservação e operação de locais e construções históricas | 020201 | 000001 |
| 39.01 | Ourivesaria e lapidação... | 1.2002.20.00 | Serviços de manutenção e reparo de relógios e joias | 050101 | 000001 |
| 40.01 | Obras de arte sob encomenda. | 1.1109.90.00 | Cessão permanente de outros direitos não classificados em subposições anteriores | 100301 | 000001 |
| 40.01 | Obras de arte sob encomenda. | 1.2503.20.00 | Serviços de autores, compositores, escultores, pintores e outros artistas... | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.10.00 | Licenciamento de direitos de obras literárias | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.10.00 | Licenciamento de direitos de obras literárias | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.31.00 | Licenciamento de direitos autorais de obras musicais | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.31.00 | Licenciamento de direitos autorais de obras musicais | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.32.00 | Licenciamento de direitos autorais de obras literárias | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.32.00 | Licenciamento de direitos autorais de obras literárias | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.34.00 | Licenciamento de direitos autorais de obras audiovisuais | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.34.00 | Licenciamento de direitos autorais de obras audiovisuais | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.35.00 | Licenciamento de direitos autorais de obras artísticas | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.35.00 | Licenciamento de direitos autorais de obras artísticas | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.36.10 | Licenciamento de direitos de obras audiovisuais sobre transmissões de eventos esportivos | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.36.10 | Licenciamento de direitos de obras audiovisuais sobre transmissões de eventos esportivos | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.36.20 | Licenciamento de direitos de obras audiovisuais sobre transmissões de programas televisivos | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.36.20 | Licenciamento de direitos de obras audiovisuais sobre transmissões de programas televisivos | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.36.90 | Licenciamento de direitos de obras audiovisuais sobre outras transmissões televisivas | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.36.90 | Licenciamento de direitos de obras audiovisuais sobre outras transmissões televisivas | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.39.00 | Licenciamento de direitos autorais de outras obras não classificadas em outras subposições | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.41.00 | Licenciamento de direitos de autor de obras musicais ou literomusicais | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.41.00 | Licenciamento de direitos de autor de obras musicais ou literomusicais | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.42.00 | Licenciamento de direitos conexos de artistas intérpretes ou executantes | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.42.00 | Licenciamento de direitos conexos de artistas intérpretes ou executantes | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.43.00 | Licenciamento de direitos conexos de produtores de fonogramas | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.43.00 | Licenciamento de direitos conexos de produtores de fonogramas | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.50.00 | Licenciamento de direitos relacionados à radiodifusão | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1103.90.00 | Licenciamento de direitos de autor e de direitos conexos não classificado em subposições anteriores | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1104.10.00 | Licenciamento de direitos sobre patentes | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1104.30.00 | Licenciamento de direitos sobre desenho industrial | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1104.90.00 | Licenciamento de direitos sobre a propriedade industrial não classificado em subposições anteriores | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.10.00 | Licenciamento de direitos sobre cultivares | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.20.00 | Licenciamento de direitos sobre topografias de circuitos integrados | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.30.00 | Licenciamento de direitos relativos à informação não divulgada | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.41.00 | Exploração de recursos vegetais, incluindo florestais | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.42.00 | Exploração de recursos minerais | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.51.00 | Licenciamento de direitos sobre conhecimento tradicional associado a recursos genéticos | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.59.00 | Licenciamento de direitos sobre conhecimento tradicional não classificado em subposições anteriores | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.60.00 | Licenciamento de direitos relativos ao acesso a recursos genéticos, exceto os decorrentes do conhecimento tradicional | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.70.00 | Licenciamento de direitos sobre informações relativas à experiência adquirida no setor industrial, comercial ou científico (know-how) | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1105.90.00 | Licenciamento de outros direitos não classificado em subposições anteriores | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.10.00 | Cessão temporária de direitos de obras literárias | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.10.00 | Cessão temporária de direitos de obras literárias | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.31.00 | Cessão temporária de direitos autorais de obras musicais | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.31.00 | Cessão temporária de direitos autorais de obras musicais | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.32.00 | Cessão temporária de direitos autorais de obras literárias | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.32.00 | Cessão temporária de direitos autorais de obras literárias | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.34.00 | Cessão temporária de direitos autorais de obras audiovisuais | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.34.00 | Cessão temporária de direitos autorais de obras audiovisuais | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.35.00 | Cessão temporária de direitos autorais de obras artísticas | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.35.00 | Cessão temporária de direitos autorais de obras artísticas | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.36.10 | Cessão temporária de direitos de obras audiovisuais sobre transmissões de eventos esportivos | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.36.10 | Cessão temporária de direitos de obras audiovisuais sobre transmissões de eventos esportivos | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.36.20 | Cessão temporária de direitos de obras audiovisuais sobre transmissões de programas televisivos | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.36.20 | Cessão temporária de direitos de obras audiovisuais sobre transmissões de programas televisivos | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.36.90 | Cessão temporária de direitos de obras audiovisuais sobre outras transmissões televisivas | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.36.90 | Cessão temporária de direitos de obras audiovisuais sobre outras transmissões televisivas | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.39.00 | Cessão temporária de direitos autorais de outras obras não classificadas... | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.41.00 | Cessão temporária de direitos de autor de obras musicais e literomusicais | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.41.00 | Cessão temporária de direitos de autor de obras musicais e literomusicais | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.42.00 | Cessão temporária de direitos conexos de artistas intérpretes ou executantes | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.42.00 | Cessão temporária de direitos conexos de artistas intérpretes ou executantes | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.43.00 | Cessão temporária de direitos conexos de produtores de fonogramas | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.43.00 | Cessão temporária de direitos conexos de produtores de fonogramas | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.50.00 | Cessão temporária de direitos relacionados à radiodifusão | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1106.90.00 | Cessão temporária de direitos de autor e de direitos conexos não classificada em subposições anteriores | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.10.00 | Cessão definitiva de direitos de obras literárias | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.10.00 | Cessão definitiva de direitos de obras literárias | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.31.00 | Cessão permanente de direitos de obras musicais | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.31.00 | Cessão permanente de direitos de obras musicais | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.32.00 | Cessão permanente de direitos de obras literárias | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.32.00 | Cessão permanente de direitos de obras literárias | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.39.00 | Cessão permanente de direitos de outras obras não classificadas... | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.40.00 | Cessão definitiva de direitos de obras musicais e fonogramas | 100301 | 200039 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.40.00 | Cessão definitiva de direitos de obras musicais e fonogramas | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.50.00 | Cessão definitiva de direitos relacionados à radiodifusão | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1107.90.00 | Cessão definitiva de direitos de autor e de direitos conexos não classificada em subposições anteriores | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1108.10.00 | Cessão definitiva de direitos sobre patentes | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1108.30.00 | Cessão definitiva de direitos sobre desenho industrial | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1108.90.00 | Cessão definitiva de direitos sobre a propriedade industrial não classificada em subposições anteriores | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1109.10.00 | Cessão definitiva de direitos sobre cultivares | 100301 | 200038 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1109.20.00 | Cessão definitiva de direitos sobre topografias de circuitos integrados | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1109.30.00 | Cessão definitiva de direitos relativos à informação não divulgada | 100301 | 000001 |
| 99.02.01 | Operação com Bens Imateriais não classificados em itens anteriores | 1.1109.90.00 | Cessão permanente de outros direitos não classificados em subposições anteriores | 100301 | 000001 |
| 99.03.01 | Locação de Bens Imóveis | 1.1002.10.00 | Locação de imóveis residenciais | 020201 | 200027 |
| 99.03.01 | Locação de Bens Imóveis | 1.1002.10.00 | Locação de imóveis residenciais | 020201 | 200026 |
| 99.03.01 | Locação de Bens Imóveis | 1.1002.10.00 | Locação de imóveis residenciais | 030101 | 200048 |
| 99.03.01 | Locação de Bens Imóveis | 1.1002.20.00 | Locação de imóveis não residenciais | 020201 | 200027 |
| 99.03.01 | Locação de Bens Imóveis | 1.1002.20.00 | Locação de imóveis não residenciais | 020201 | 200026 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.11.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de até oito passageiros, sem operador | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.11.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de até oito passageiros, sem operador | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.11.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de até oito passageiros, sem operador | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.11.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de até oito passageiros, sem operador | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.12.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de carga, sem operador | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.12.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de carga, sem operador | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.12.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de carga, sem operador | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.12.00 | Arrendamento operacional ou aluguel de veículos rodoviários para transporte de carga, sem operador | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.13.00 | Arrendamento operacional ou aluguel de veículos e equipamentos ferroviários, sem operador | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.13.00 | Arrendamento operacional ou aluguel de veículos e equipamentos ferroviários, sem operador | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.13.00 | Arrendamento operacional ou aluguel de veículos e equipamentos ferroviários, sem operador | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.13.00 | Arrendamento operacional ou aluguel de veículos e equipamentos ferroviários, sem operador | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.14.00 | Arrendamento operacional ou aluguel de outros equipamentos de transporte terrestre, incluindo veículos de uso misto, sem operador | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.14.00 | Arrendamento operacional ou aluguel de outros equipamentos de transporte terrestre, incluindo veículos de uso misto, sem operador | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.14.00 | Arrendamento operacional ou aluguel de outros equipamentos de transporte terrestre, incluindo veículos de uso misto, sem operador | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.14.00 | Arrendamento operacional ou aluguel de outros equipamentos de transporte terrestre, incluindo veículos de uso misto, sem operador | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.15.00 | Arrendamento operacional ou aluguel de navios e outras embarcações, sem tripulação | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.15.00 | Arrendamento operacional ou aluguel de navios e outras embarcações, sem tripulação | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.15.00 | Arrendamento operacional ou aluguel de navios e outras embarcações, sem tripulação | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.15.00 | Arrendamento operacional ou aluguel de navios e outras embarcações, sem tripulação | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.16.00 | Arrendamento operacional ou aluguel de aeronaves, sem tripulação | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.16.00 | Arrendamento operacional ou aluguel de aeronaves, sem tripulação | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.16.00 | Arrendamento operacional ou aluguel de aeronaves, sem tripulação | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.16.00 | Arrendamento operacional ou aluguel de aeronaves, sem tripulação | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.17.00 | Arrendamento operacional ou aluguel de contêineres | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.17.00 | Arrendamento operacional ou aluguel de contêineres | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.17.00 | Arrendamento operacional ou aluguel de contêineres | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.17.00 | Arrendamento operacional ou aluguel de contêineres | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.20.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos agrícolas, sem operador | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.20.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos agrícolas, sem operador | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.20.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos agrícolas, sem operador | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.20.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos agrícolas, sem operador | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.30.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de construção, sem operador | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.30.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de construção, sem operador | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.30.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de construção, sem operador | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.30.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de construção, sem operador | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.40.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de escritório, exceto computadores, sem operador | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.40.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de escritório, exceto computadores, sem operador | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.40.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de escritório, exceto computadores, sem operador | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.40.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos de escritório, exceto computadores, sem operador | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.50.00 | Arrendamento operacional ou aluguel de computadores, sem operador | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.50.00 | Arrendamento operacional ou aluguel de computadores, sem operador | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.50.00 | Arrendamento operacional ou aluguel de computadores, sem operador | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.50.00 | Arrendamento operacional ou aluguel de computadores, sem operador | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.60.00 | Arrendamento operacional ou aluguel de equipamentos de telecomunicação, sem operador | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.60.00 | Arrendamento operacional ou aluguel de equipamentos de telecomunicação, sem operador | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.60.00 | Arrendamento operacional ou aluguel de equipamentos de telecomunicação, sem operador | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.60.00 | Arrendamento operacional ou aluguel de equipamentos de telecomunicação, sem operador | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.90.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos, sem operador, não classificados... | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.90.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos, sem operador, não classificados... | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.90.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos, sem operador, não classificados... | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1101.90.00 | Arrendamento operacional ou aluguel de máquinas e equipamentos, sem operador, não classificados... | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.10.00 | Arrendamento operacional ou aluguel de televisores e outros eletrodomésticos, bem como seus acessórios | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.10.00 | Arrendamento operacional ou aluguel de televisores e outros eletrodomésticos, bem como seus acessórios | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.10.00 | Arrendamento operacional ou aluguel de televisores e outros eletrodomésticos, bem como seus acessórios | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.10.00 | Arrendamento operacional ou aluguel de televisores e outros eletrodomésticos, bem como seus acessórios | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.20.00 | Arrendamento operacional ou aluguel de mídias gravadas | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.20.00 | Arrendamento operacional ou aluguel de mídias gravadas | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.20.00 | Arrendamento operacional ou aluguel de mídias gravadas | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.20.00 | Arrendamento operacional ou aluguel de mídias gravadas | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.30.00 | Arrendamento operacional ou aluguel de móveis e eletrodomésticos | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.30.00 | Arrendamento operacional ou aluguel de móveis e eletrodomésticos | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.30.00 | Arrendamento operacional ou aluguel de móveis e eletrodomésticos | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.30.00 | Arrendamento operacional ou aluguel de móveis e eletrodomésticos | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.40.00 | Arrendamento operacional ou aluguel de equipamentos para diversão e lazer | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.40.00 | Arrendamento operacional ou aluguel de equipamentos para diversão e lazer | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.40.00 | Arrendamento operacional ou aluguel de equipamentos para diversão e lazer | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.40.00 | Arrendamento operacional ou aluguel de equipamentos para diversão e lazer | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.50.00 | Arrendamento operacional ou aluguel de roupas de cama, mesa e banho | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.50.00 | Arrendamento operacional ou aluguel de roupas de cama, mesa e banho | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.50.00 | Arrendamento operacional ou aluguel de roupas de cama, mesa e banho | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.50.00 | Arrendamento operacional ou aluguel de roupas de cama, mesa e banho | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.60.00 | Arrendamento operacional ou aluguel de roupas e calçados | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.60.00 | Arrendamento operacional ou aluguel de roupas e calçados | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.60.00 | Arrendamento operacional ou aluguel de roupas e calçados | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.60.00 | Arrendamento operacional ou aluguel de roupas e calçados | 010106 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.90.00 | Arrendamento operacional ou aluguel de outros bens não classificados em outras subposições | 010101 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.90.00 | Arrendamento operacional ou aluguel de outros bens não classificados em outras subposições | 010102 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.90.00 | Arrendamento operacional ou aluguel de outros bens não classificados em outras subposições | 010103 | 000001 |
| 99.04.01 | Locação de Bens Móveis | 1.1102.90.00 | Arrendamento operacional ou aluguel de outros bens não classificados em outras subposições | 010106 | 000001 |

---

## Glossário da Reforma Tributária do Consumo

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-legais/glossario-reforma-tributaria-consumo/index.md

# Glossário da Reforma Tributária do Consumo

Este glossário reúne os principais termos e conceitos relacionados à Reforma Tributária do Consumo (RTC), facilitando a compreensão dos novos tributos, processos e obrigações para contribuintes, desenvolvedores e demais interessados.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

* **Administração Tributária (AT):** Órgãos públicos responsáveis por definir e controlar as obrigações fiscais dos contribuintes. Na esfera federal, o órgão responsável pela administração tributária é a Receita Federal (RFB).
* **Adquirente:** Quem participa como “cliente” de um contribuinte de CBS. É a pessoa/empresa que compra um bem ou serviço. É o adquirente quem recebe os créditos dos tributos, se ele também for contribuinte da CBS. Art. 3º Para fins desta Lei Complementar, consideram-se: (...) IV - adquirente: a) aquele obrigado ao pagamento ou a qualquer outra forma de contraprestação pelo fornecimento de bem ou serviço;
* **API:** Application Programming Interface (Interface de Programação de Aplicativos). É uma ponte entre sistemas, um agente intermediário que facilita a integração de diversos sistemas. Ela permite que sistemas se comuniquem de uma forma segura e organizada, sem que um precise “saber” como o outro funciona por dentro. A API facilita a vida do usuário de um sistema ou aplicativo.
* **Apuração Assistida (AA):** É um sistema desenvolvido pela Receita Federal para verificar e apurar o resultado das operações de um contribuinte de forma precisa e transparente, garantindo maior confiabilidade no processo do levantamento da CBS. É um sistema que “assiste/ajuda o contribuinte”.
* **CadÚnico:** Cadastro Único para Programas Sociais do Governo Federal.
* **Calculadora:** Ferramenta que auxilia os contribuintes na emissão dos documentos fiscais e no cumprimento de suas obrigações. É a ferramenta para o cálculo automático da CBS, do IBS e do IS conforme as regras estabelecidas pela RTC.
* **Cashback:** Devolução personalizada dos valores relativos a CBS e IBS a famílias de baixa renda ou que estejam em situação de extrema pobreza cadastradas no CadÚnico.
* **CBS:** Contribuição sobre Bens e Serviços – tributo de responsabilidade federal. cClassTrib: Código da Classificação Tributária. São os códigos que definem com mais detalhes o tipo de tributação da CBS, IBS e IS envolvida em uma operação. Determina exatamente qual é a operação que está sendo realizada.
* **CIB:** Cadastro Imobiliário Brasileiro – Será obrigatório a partir de 2026. O Cadastro Imobiliário Brasileiro (CIB) faz parte do Sistema Nacional de Gestão de Informações Territoriais (Sinter). O cadastro agregará informações cadastrais de imóveis rurais e urbanas, públicos ou privados, inscritos nos respectivos cadastros de origem, como o Cadastro Nacional de Imóveis Rurais (CNIR), administrado pelo Incra, e o cadastro de imóveis urbanos administrados pelas prefeituras municipais.
* **CNPJ:** Cadastro Nacional da Pessoa Jurídica.
* **Conclusão do Período de Apuração:** É o fim do período de apuração (cálculo/conferência) dos tributos. Momento em que se encerram as possibilidades de ajuste. Pode ocorrer por um pedido de ressarcimento do saldo credor do período anterior, pela confirmação do contribuinte ou pela sua ausência de manifestação.
* **Conhecimento de Transporte Eletrônico (CT-e):** Documento fiscal eletrônico para operações de transporte de cargas.
* **Contribuinte:** Todo aquele que deve apurar a CBS.
* **CPF:** Cadastro de Pessoa Física.
* **Crédito Apropriado:** Valor recolhido que se tornou disponível para uso, podendo ser utilizado para quitação de débitos.
* **Crédito Básico:** Crédito normal obtido através de operações de compras feitas entre contribuintes da CBS/IBS.
* **Crédito não Apropriado:** Valor recolhido que ainda não está disponível para utilização porque não passou por todas as etapas formais de liberação.
* **Crédito Presumido:** Crédito sem garantia em pagamento. Representa uma exceção à regra da RTC. São usados, por exemplo, quando um produtor rural pessoa física, que não é contribuinte da CBS/IBS, vende produtos a uma empresa. Nessa situação, a empresa tem direito ao crédito de CBS/IBS. O objetivo é evitar que o produtor rural perca competitividade e clientes.
* **Crédito Utilizado:** Crédito apropriado que foi utilizado para extinguir débitos.
* **CST:** Código de Situação Tributária. São os códigos que definem o tipo de tributação da CBS, IBS e IS envolvida em uma operação. Agrupa um determinado conjunto de operações que guardam semelhança entre si.
* **DARF:** Documento de Arrecadação de Receitas Federais. É o boleto usado para pagar tributos federais.
* **DERE:** Declaração de Regimes Específicos. Declaração eletrônica instituída pela RTC para abranger fatos geradores específicos dentro do novo sistema tributário. Seu objetivo é que o contribuinte informe de forma clara e organizada os dados sobre a apuração de IBS e CBS quando forem recolhidos por regimes específicos de tributação. Os regimes específicos são tratamentos tributários diferenciados aplicados a setores que, devido à sua natureza ou modelo de negócio, não se encaixam na tributação padrão.
* **Destinatário:** Para quem foi fornecido o bem ou serviço, podendo ser ou não ser o adquirente.
* **Devoluções:** É o retorno de valores para os contribuintes. No contexto da RTC, poderão ser por restituição, ressarcimento ou transferência.
* **Documento Fiscal:** Documento eletrônico padronizado que registra as operações de venda ou prestação de serviços, permitindo que a Administração Tributária acompanhe e calcule automaticamente os tributos devidos em tempo real.
* **DPS:** Declaração de Prestação de Serviços. Informações fornecidas pelos prestadores de serviço para a autorização da NFS-e.
* **Encerramento:** Último dia do período de apuração mensal.
* **ERP:** Enterprise Resource Planning (Planejamento de Recursos Empresariais) é um sistema de software que integra e automatiza os principais processos de uma empresa, como finanças, RH, vendas, logística e emissão de documentos fiscais, em uma única plataforma centralizada.
* **Eventos:** Fatos ou ocorrências com impacto na apuração dos tributos. São essenciais para a apuração correta dos tributos.
* **Fornecedor:** Quem vende o produto ou o serviço. Nem sempre será o contribuinte, como no caso no produtor rural.
* **Fornecimento:** Entrega/disponibilização de bem material ou a prestação/ disponibilização do serviço. Art. 3º Para fins desta Lei Complementar, consideram-se:
    * (...) II - fornecimento:
      * a)	entrega ou disponibilização de bem material;
      * b)	(...)
      * c)	prestação ou disponibilização de serviço;
* **IBS:** Imposto sobre Bens e Serviços – tributo de responsabilidade dos Estados, Distrito Federal e Municípios.
* **ICMS:** Imposto sobre Operações relativas à Circulação de Mercadorias e sobre Prestações de Serviços de Transporte Interestadual e Intermunicipal e de Comunicação. É de competência dos Estados e do Distrito Federal.
* **Imposto Seletivo (IS):** Imposto de competência da União e terá alíquotas específicas ou diferenciadas para os produtos danosos ou com impactos ambientais.
* **ISS:** Imposto sobre Serviços de Qualquer Natureza. É de competência dos Municípios e do Distrito Federal.
* **IVA:** Imposto sobre Valor Agregado. Tributo que será aplicado ao consumo de bens e serviços e incidirá apenas sobre o valor agregado em cada fase de produção ou prestação de serviços. Assim, evita-se a cobrança em cascata, que ocorre quando o imposto é cobrado várias vezes ao longo da cadeia produtiva. No Brasil, a aplicação do IVA será dual, abrangendo dois tributos distintos, administrados por diferentes entes federativos (CBS e IBS).
* **NBS:** Nomenclatura Brasileira de Serviços.
* **NCM:** Nomenclatura Comum do Mercosul.
* **Nota Fiscal Eletrônica (NFe):** Documento fiscal eletrônico para operações de circulação de mercadorias entre pessoas jurídicas e vendas no eCommerce para pessoas físicas.
* **Nota Fiscal de Energia Elétrica Eletrônica (NF3e):** Documento fiscal eletrônico para serviços de fornecimento de energia elétrica, em substituição à tradicional conta de energia elétrica.
* **Nota Fiscal do Consumidor Eletrônica (NFC-e):** Conhecida como nota fiscal do varejo, é o documento fiscal eletrônico para operações comerciais que envolvem o consumidor final (pessoa física), que não é contribuinte direto dos tributos sobre o consumo.
* **Nota Fiscal de Serviço de Comunicação Eletrônica (NFCom):** Documento fiscal eletrônico para as transações de serviços de comunicação e telecomunicações, como planos de telefonia, internet, TV por assinatura.
* **Nota Fiscal de Serviço Eletrônica (NFS-e):** Documento fiscal eletrônico para operações de prestação de serviços.
* **Nota Fiscal de Serviço Eletrônica de Exploração de Via (NFS-e Via):** NFS-e com propósito específico de formalizar as operações de prestação de serviço de exploração de via.
* **Operação Onerosa:** Qualquer fornecimento com contraprestação. Exemplos: operações de compra e venda, locação ou prestação de serviços.
* **PA:** Período de Apuração.
* **Pagamento não utilizado:** Valor pago pelo contribuinte, integral ou parcialmente, que não foi aproveitado na apuração mensal.
* **PCONT:** Pagamento feito pelo Contribuinte.
* **PER/DCOMP:** Pedido Eletrônico de Restituição/Declaração de Compensação. Será gerado automaticamente quando o contribuinte fizer um pedido de restituição ou de ressarcimento de valores de CBS a partir do botão localizado na funcionalidade da Apuração Assistida (AA).
* **Período de Ajuste:** Período para possível correção de valores de créditos e débitos de um contribuinte. São os 15 (quinze) dias após o mês de apuração.
* **PIX:** O pagamento das devoluções, sejam ressarcimento ou transferência, será realizado na conta PIX do contribuinte, que deve estar ativa e ter como chave o CNPJ/CPF do contribuinte.
* **RAD:** Recolhimento realizado pelo Adquirente.
* **Recolhimento não utilizado:** Valor recolhido pelo adquirente, integral ou parcialmente, que não foi aproveitado na apuração mensal.
* **Ressarcimento:** É um conceito presente atualmente na sistemática do IPI, PIS e Cofins não cumulativos, que tem como base a não-cumulatividade dos tributos. Ele ocorre sempre a pedido do contribuinte, de forma facultativa. Em relação à CBS, é solicitado diretamente no ambiente da Apuração Assistida (AA) quando existir saldo a recuperar ao final de determinado período de apuração (quando os créditos superam os débitos). Pode ser solicitado o valor total ou parcial.
* **Restituição:** Também é um conceito já existente em relação aos tributos arrecadados pela Receita Federal e ocorre quando há pagamento indevido ou a maior. Ocorre também sempre a pedido do contribuinte, de forma facultativa. Em relação à CBS, quando a Apuração Assistida identificar saldo disponível do pagamento ou recolhimento, será apresentado ao contribuinte botão específico para permitir ao contribuinte o pedido da restituição por meio da geração automática de PER/DCOMP (Pedido Eletrônico de Restituição). Não haverá a necessidade do uso do sistema PERDCOMP Web pelo contribuinte.
* **Exemplo de pagamento indevido:** pagamento em duplicidade. Exemplo de pagamento a maior: o contribuinte devia R$100,00 e pagou R$120,00 (R$ 20,00 é crédito passível de pedido de restituição).
* **Resultado do Período:** Diferença entre os valores dos débitos e créditos apropriados no período de apuração para um contribuinte.
* **RFB:** Receita Federal do Brasil.
* **ROC:** Registro de Operações de Consumo. É uma etapa do processamento dos documentos fiscais eletrônicos pelo sistema.
* **RTC:** Reforma Tributária sobre o Consumo.
* **Saldo a pagar:** Resultado da apuração menos os valores extintos por split payment, recolhimento pelo adquirente e pagamento pelo responsável após o encerramento do período de apuração.
* **Simulador:** é um dos sistemas disponibilizados no "Portal da Reforma Tributária do Consumo" (Portal RTC). Foi criado para viabilizar os testes pelos desenvolvedores/servidores/contribuintes participantes do Projeto Piloto dos sistemas da RTC.
* **SINTER:** Sistema Nacional de Gestão de Informações Territoriais – integra as bases de dados cadastrais, geoespaciais, fiscais e jurídicas de imóveis urbanos, rurais, públicos e privados do território nacional. Seu propósito é consolidar o Cadastro Imobiliário Brasileiro (CIB).
* **Split Payment (Recolhimento na Liquidação Financeira):** É uma das modalidades de extinção do débito tributário. O termo “Split Payment” em inglês significa “pagamento repartido” ou “pagamento segregado”. Refere-se à separação automática dos valores dos tributos pelos provedores de serviços de pagamento eletrônico e instituições operadoras de sistemas de pagamentos. Isso acontecerá no exato momento da liquidação financeira de uma operação. A separação acontece com base nas informações constantes do documento fiscal eletrônico, entre o valor da operação (produto ou serviço) e o montante devido a título de tributos.
* **Tomador de Serviços:** Na NFS-e, trata-se do próprio adquirente.
* **Transferência:** É um novo conceito trazido pela RTC. Ocorre quando há pagamento a maior em razão do Split Payment, RAD ou pagamento pelo contribuinte do saldo devedor da apuração. Ela é automática e não precisa de pedido do contribuinte para acontecer. O pagamento da transferência deve ocorrer em até três dias úteis. Todo esse batimento será realizado de forma automática pela Apuração Assistida.
* **Tributo:** É um tipo de pagamento obrigatório que todas as pessoas e empresas fazem ao governo (municipal, estadual ou federal) para que ele possa funcionar e prestar serviços à população. Existem vários tipos de tributos, como os impostos, as taxas e as contribuições.

---

## Reforma Tributária: Introdução e Conceitos Legais

Source: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-legais/introducao/index.md

## O que é a Reforma Tributária?

A reforma tributária é uma transformação profunda no sistema de tributos indiretos. Ela busca simplificar, modernizar e alinhar o modelo brasileiro às melhores práticas internacionais, promovendo maior eficiência econômica, segurança jurídica e competitividade.

A Reforma Tributária foi promulgada pela **Emenda Constitucional 132/2023** em 21 de dezembro de 2023 e regulamentada pela Lei Complementar 214/2025 sancionada em de janeiro de 2025.

Em relação a LC 214/2025, a sanção incluiu vetos a trechos específicos, como a tributação de plataformas digitais e a isenção para fundos de investimento, dentre outros, justificados pelo governo para evitar conflitos judiciais. Apesar dos vetos, o Ministro da Fazenda afirmou que o núcleo da reforma foi preservado.

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

## Quais objetivos da Reforma Tributária?

Objetivos da Reforma Tributária do Consumo

* Simplificação: Unificação de diversos tributos (PIS, Cofins, IPI, ICMS e ISS) em dois grandes impostos:
* IBS (Imposto sobre Bens e Serviços) — de competência compartilhada entre estados e municípios.
* CBS (Contribuição sobre Bens e Serviços) — de competência federal.
* Neutralidade: Redução das distorções econômicas, eliminando a cumulatividade e os efeitos em cascata.
* Transparência: Maior clareza para consumidores e empresas sobre os tributos incidentes.
* Segurança Jurídica: Redução da litigiosidade, com regras mais claras e consolidadas.

## O que muda com a Reforma Tributária?

### Novos Tributos passarão a existir

* **CBS**: Contribuição sobre Bens e Serviços (Federal);
* **IBS**: Imposto sobre Bens e Serviços (Estadual e Municipal); e
* **IS**: Imposto Seletivo (Federal)

**Imposto Seletivo:**

* Criado para desestimular o consumo de bens e serviços prejudiciais à saúde ou ao meio ambiente.
* Incide sobre produção, extração, comercialização ou importação de itens definidos por lei.
* A partir de 2027, entrará em vigor.

### Tributos que deixarão de existir

* PIS/PASEP: Contribuição para o Programa de Integração Social e Programa de Formação do Patrimônio do Servidor Público (Federal);
* Cofins: Contribuição para Financiamento da Seguridade Social (Federal);
* ICMS: Imposto sobre Circulação de Mercadorias e Serviços (Estadual); e
* ISSQN: Imposto sobre Serviços de Qualquer Natureza (Municipal).

**Imposto sobre Produtos Industrializados (IPI)**

* A partir de 2027, terá alíquota reduzida a zero para quase todos os produtos; e
* Será mantido apenas para preservar a competitividade da Zona Franca de Manaus.

## Qual cronograma para execução do novo modelo x Período de transição?

![img_2.png](https://nfe.io/docs/img_2.png)

### Quais são os desafios e perspectivas?

* Transição complexa: O período de transição exige adaptação dos contribuintes e dos fiscos a partir de 2026-2032.
* Necessidade de executar em paralelo por um longo período os dois sistemas tributários em paralelo, os tributos atuais e a nova sistemática do IVA dual.
* Capacitação tecnológica: Necessidade de investimentos em infraestrutura tecnológica e treinamento de pessoal.

---

## Monitoramento da Adesão e Emissão dos Municipios a NFS-e Ambiente Nacional

Source: https://nfe.io/docs/documentacao/reforma-tributaria/monitoramento-adesao-municipios-nfse-ambiente-nacional/index.md

# Monitoramento da Adesão e Emissão dos Municipios a NFS-e Ambiente Nacional

Panorama Dos Municípios Aderentes ao ambiente do portal Nacional e emissores da NFSe. Acompanhe a evolução e posicionamento dos municípios no Brasil no link abaixo.

[Monitoramento da Adesão e Emissão dos Municípios a NFS-e Ambiente Nacional](https://app.powerbi.com/view?r=eyJrIjoiNGQ4YTcxNmMtMzdhNC00Mzc5LTllM2EtMjY1MTM3NWQyZDgyIiwidCI6IjZmNDlhYTQzLTgyMmEtNGMyMC05NjcwLWRiNzcwMGJmMWViMCJ9&pageName=608609c2e0a53d7a3c6e)

:::info

* Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
* Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

---

## Reforma Tributária: visão geral e próximos passos

Source: https://nfe.io/docs/documentacao/reforma-tributaria/index.md

# Reforma Tributária: o que muda com a NFE.io

A Reforma Tributária está mexendo em muita coisa no sistema de tributos do Brasil — e é normal ficar em dúvida sobre o que realmente muda **no seu dia a dia**. Nesta página, vamos direto ao ponto: explicar, em linguagem simples, como a NFE.io está se preparando, o que você precisa saber agora e onde encontrar os detalhes mais técnicos e legais quando quiser se aprofundar.

:::info

Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.

:::

Logo abaixo, você encontra atalhos por perfil. Escolha o card que tem mais a ver com você ou siga a leitura contínua.

## Escolha o seu perfil

> Pense nestes cards como um "atalho" dentro desta própria página. Todos os perfis compartilham a mesma base de informações, mas com ênfases diferentes.

- **Sou gestor (negócio/financeiro)**  → [Ir para visão de gestão](#para-gestores-estrategia-risco-e-governanca)
- **Sou fiscal/contábil**  → [Ir para visão fiscal](#para-times-fiscalcontabil-regras-calculos-e-legislacao)
- **Sou desenvolvedor**  → [Ir para visão técnica](#para-desenvolvedores-apis-layouts-e-integracoes)
- **Trabalho com faturamento/operação**  → [Ir para visão operacional](#para-operacaofaturamento-emissao-conferencia-e-suporte)

---

## 1. Visão geral da Reforma Tributária na NFE.io

Esta seção é para todos os perfis. A ideia é alinhar o "panorama geral" antes de entrar nos detalhes de cada área.

- A Reforma Tributária do Consumo (RTC) cria novos tributos (como IBS e CBS), convive por um tempo com os tributos atuais e muda a forma como o cálculo é feito, mas **o fluxo básico de emissão continua o mesmo** para quem usa a NFE.io.
- A NFE.io está atualizando **motor de cálculo**, **layouts de integração** e **APIs** para acompanhar cada fase, sem exigir uma "virada de chave brusca" dos clientes.
- O objetivo é que você possa ir se adaptando aos poucos, testando com antecedência e evitando surpresas na operação.

Se quiser um contexto mais completo sobre os objetivos da Reforma, bases legais e termos mais técnicos, você pode se aprofundar em:

- [Conceitos legais e objetivos da RTC](/documentacao/reforma-tributaria/conceitos-legais/introducao)
- [Glossário completo de termos da Reforma](/documentacao/reforma-tributaria/conceitos-legais/glossario-reforma-tributaria-consumo)

### 1.1 O que efetivamente muda na prática?

De forma simplificada, olhando para produtos e serviços:

- **NF-e / NFC-e (produtos)**
  - Continuam existindo como hoje, mas com novos grupos de tributos relacionados a IBS/CBS/IS.
  - A NFE.io já está adequando o **layout de integração** e o **motor de cálculo** para suportar o novo modelo.
  - Detalhes técnicos e campos novos estão em:
    - [Layout completo RTC para NF-e/NFC-e](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/documentacao-layout-nfe-rtc/)
    - [Mudanças de layout (versão 3)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/mudancas-layout-integracao-nfe-v3/)

- **NFS-e (serviços)**
  - O documento continua existindo, mas passa a conviver com as regras da RTC e, em alguns casos, com o **Ambiente Nacional de NFS-e**.
  - O layout passa a ter um grupo específico para IBS/CBS (além do ISS tradicional) e novas regras para local de incidência, créditos e cenários especiais.
  - Detalhes técnicos estão em:
    - [Layout RTC para NFS-e](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/)
    - [Mudanças de layout (versão 4)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/mudancas-layout-integracao-nfse-v4/)

### 1.2 Plano de ação (agora vs depois)

Abaixo, um resumo do que faz sentido olhar **agora** e o que pode ser planejado para **depois**, por perfil. Use como checklist rápido.

- **[Gestor] Agora**: entenda em linhas gerais o que é a Reforma e como ela pode afetar seu modelo de negócio (produtos, serviços, estados/municípios). Uma boa base é a introdução em [Introdução e conceitos legais](/documentacao/reforma-tributaria/conceitos-legais/introducao) e a página de dúvidas frequentes em [Reforma Tributária - Dúvidas Frequentes](/documentacao/reforma-tributaria/perguntas-e-respostas/).
- **[Gestor] Depois**: junto com o time fiscal e de tecnologia, defina um plano interno de transição (quando testar, quando mudar cadastros, quem é responsável por quê).

- **[Fiscal/Contábil] Agora**: revise conceitos de IBS/CBS/IS, regimes e benefícios, e como isso se conecta aos códigos de tributação. Use o glossário em [Glossário da Reforma Tributária do Consumo](/documentacao/reforma-tributaria/conceitos-legais/glossario-reforma-tributaria-consumo) e as tabelas de referência em [Tabelas de referência](/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/).
- **[Fiscal/Contábil] Depois**: aprofunde-se nas regras específicas por tipo de documento (NF-e, NFS-e), avaliando impactos em cadastros de produto/serviço, NBS/NCM, CFOP e benefícios fiscais.

- **[Desenvolvedor] Agora**: confirme quais APIs você usa hoje (NF-e, NFC-e, NFS-e) e localize a documentação RTC correspondente em [APIs RTC](/desenvolvedores/rest-api/reforma-tributaria).
- **[Desenvolvedor] Depois**: planeje ajustes nos payloads (novos grupos/objetos, como `IBSCBS` ou `IbsCbs`), testes em ambiente de homologação e monitore erros utilizando os guias de troubleshooting.

- **[Operação/Faturamento] Agora**: veja se você já utiliza planilhas ou fluxos especiais de emissão (lote NFS-e, planilha NF-e) e identifique onde os campos da Reforma aparecem.
- **[Operação/Faturamento] Depois**: junto com o time fiscal, ajuste cadastros e orientações internas para garantir que os dados enviados (como códigos de tributação) estejam corretos quando a empresa decidir começar a usar as novas regras.

Se quiser aprofundar perguntas comuns sobre "preciso mudar algo agora?", "vou parar de emitir nota?" e outras dúvidas gerais, consulte:

- [FAQ completa de Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas/)

---

## 2. Para gestores: estratégia, risco e governança {#para-gestores-estrategia-risco-e-governanca}

Esta parte é voltada para quem olha o todo: risco operacional, conformidade, custo e priorização de projetos.

- **Risco de parada de emissão**: quem usa uma plataforma preparada, como a NFE.io, não deveria ter uma "virada de chave" brusca. O risco maior está em **não acompanhar** a transição ao longo do tempo (por exemplo, não revisar cadastros, não testar, não alinhar time fiscal e tecnologia).
- **Impacto no negócio**: a Reforma muda a forma de tributar consumo, o que pode afetar margens, preços e competitividade. Entender isso com o time fiscal/contábil ajuda a antecipar ajustes em contratos e políticas comerciais.
- **Governança**: vale tratar a adaptação à Reforma como um pequeno projeto interno, com dono, cronograma e marcos de validação.

Para se aprofundar:

- Conceitos legais e objetivos da Reforma: [Reforma Tributária: Introdução e Conceitos Legais](/documentacao/reforma-tributaria/conceitos-legais/introducao)
- Glossário da Reforma do Consumo: [Glossário da Reforma Tributária do Consumo](/documentacao/reforma-tributaria/conceitos-legais/glossario-reforma-tributaria-consumo)
- Dúvidas frequentes de alto nível (cronograma, riscos, necessidade de ação imediata): [Reforma Tributária - Dúvidas Frequentes](/documentacao/reforma-tributaria/perguntas-e-respostas/)

---

## 3. Para times fiscal/contábil: regras, cálculos e legislação {#para-times-fiscalcontabil-regras-calculos-e-legislacao}

Aqui o foco é em quem cuida de enquadramento tributário, parametrização e conferência fiscal.

- **Conceitos-chave**: IBS, CBS, IS, regimes, créditos, benefícios, imunidades e regras de local de incidência passam a ser fundamentais para definir corretamente como cada operação será tributada.
- **Códigos e tabelas**: o relacionamento entre `situationCode` (CST do IBS/CBS) e `classCode` (classificação tributária) é central. Utilizar as tabelas oficiais (e as referências da NFE.io) reduz muito o risco de rejeições.
- **Convivência de modelos**: durante o período de transição, os tributos antigos e novos coexistem. Isso significa conferir tanto parâmetros "legados" (como ICMS/ISS/PIS/COFINS) quanto os novos grupos de IBS/CBS/IS.

Documentos que valem estar na sua lista de leitura:

- [Introdução e conceitos legais](/documentacao/reforma-tributaria/conceitos-legais/introducao)
- [Glossário RTC](/documentacao/reforma-tributaria/conceitos-legais/glossario-reforma-tributaria-consumo)
- [Tabelas de referência (CST, classCode, etc.)](/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/)
- Layouts detalhados por tipo de documento:
  - [NF-e/NFC-e](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/documentacao-layout-nfe-rtc/)
  - [NFS-e](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/)

---

## 4. Para desenvolvedores: APIs, layouts e integrações {#para-desenvolvedores-apis-layouts-e-integracoes}

Se você cuida das integrações com a NFE.io, esta seção é para você.

- **Visão geral técnica**: a Reforma não cria uma "API totalmente nova" para emissão — ela traz **novas versões de layout** e **novos grupos de campos**, especialmente para IBS/CBS/IS. As chamadas continuam parecidas, mas os payloads evoluem.
- **NF-e / NFC-e RTC**:
  - [Visão geral da API RTC de NF-e/NFC-e](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-produto-consumidor-rtc/api-de-emissao-de-nota-fiscal-de-produto-nfe-nfce-rtc/)
  - [Endpoint de criação de nota (exemplos completos de payload)](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-produto-consumidor-rtc/create-product-invoice/)
  - [Layout funcional RTC (campos, grupos, regras)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/documentacao-layout-nfe-rtc/)
  - [Mudanças em relação ao layout anterior](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/mudancas-layout-integracao-nfe-v3/)
  - [Ciclo de vida e eventos RTC (cancelamento, apropriação de créditos, etc.)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/fluxograma-ciclo-vida-nfe/)
  - [Guia de Solução de Problemas e Boas Práticas: Emissão de NF-e/NFC-e (RTC)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/guia-solucao-problemas-nfe-nfce-rtc/)

- **NFS-e RTC (nota fiscal de serviço)**:
  - [Visão geral da API de NFS-e RTC e explicações detalhadas de cada campo (incluindo `IbsCbs`, `operationIndicator`, `classCode`)](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-servico-rtc/api-de-emissao-de-nota-fiscal-de-servicos-eletronica-nfs-e-rtc/)
  - [Especificação do endpoint de envio de dados para emissão (RPS/DPS/NFS-e)](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-servico-rtc/envio-de-dados-para-emissao-de-nfs-e-rps-dps/)
  - [Layout funcional RTC da NFS-e (campos, grupos, cenários especiais)](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/)
  - [Mudanças de layout RTC para serviços](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/mudancas-layout-integracao-nfse-v4/)

Quando estiver planejando a migração:

- Priorize mapear onde, no seu sistema, estão os dados necessários para alimentar os novos campos (especialmente IBS/CBS/IS, `operationIndicator`, `classCode`).
- Use ambientes de homologação para testar cenários típicos (operações internas, interestaduais, serviços recorrentes, construção civil etc.).
- Consulte sempre os guias de troubleshooting e as tabelas de referência para evitar rejeições difíceis de interpretar.

---

## 5. Para operação/faturamento: emissão, conferência e suporte {#para-operacaofaturamento-emissao-conferencia-e-suporte}

Aqui, a ideia é falar com quem está na ponta emitindo, conferindo e acompanhando notas no dia a dia.

- **O fluxo continua familiar**: telas, processos de emissão e rotinas de faturamento tendem a continuar parecidos. O que muda, aos poucos, são alguns campos e validações que passam a aparecer por causa da Reforma.
- **Planilhas e emissão em lote**:
  - Para NFS-e, existe um fluxo específico de emissão em lote por planilha, com campos de IBS/CBS destacados. Veja: [Emissão em lote de NFS-e com planilha básica](/documentacao/nossa-plataforma/nota-fiscal-servico/emitir-em-lote/) (especialmente a seção "Campos IBS/CBS - Reforma Tributária").
  - Para NF-e, há um template de planilha simplificada com uma área dedicada a dados da Reforma Tributária (IBS/CBS). Veja: [Template de planilha simplificada para NF-e](/documentacao/nota-fiscal-produto-eletronica/template-de-planilha-simplificada-para-processamento-de-notas-fiscais/).
- **Conferência e resolução de erros**:
  - Para NF-e/NFC-e, o guia de troubleshooting RTC ajuda a entender mensagens de rejeição e como corrigi-las: [Guia de troubleshooting NF-e/NFC-e RTC](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/guia-solucao-problemas-nfe-nfce-rtc/).
  - Para NFS-e, as descrições dos campos na documentação de API e layout orientam em casos de erro, especialmente em campos como `taxationType`, `operationIndicator`, `classCode` e retenções.

### 5.1 Callout especial: municípios em NFS-e e APIs de serviço

Se você **emite NFS-e**, este ponto merece atenção especial.

- A adoção da NFS-e em ambiente nacional e as mudanças trazidas pela Reforma podem variar de município para município.
- A NFE.io disponibiliza um acompanhamento da adesão dos municípios, para que você saiba onde e como a NFS-e nacional está sendo utilizada.
- As APIs de NFS-e RTC já consideram essas particularidades e ajudam a manter a emissão consistente.

Para acompanhar e se aprofundar:

- [Monitoramento da adesão de municípios e NFS-e Ambiente Nacional](/documentacao/reforma-tributaria/monitoramento-adesao/)
- [Documentação da API de NFS-e RTC (explicações + spec)](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-servico-rtc/api-de-emissao-de-nota-fiscal-de-servicos-eletronica-nfs-e-rtc/)
  - [Envio de dados para emissão de NFS-e (RPS/DPS)](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-servico-rtc/envio-de-dados-para-emissao-de-nfs-e-rps-dps/)
- [Layout funcional de NFS-e RTC](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/)
---

## 6. Referências rápidas e materiais complementares

Para fechar, aqui vai uma lista rápida de "onde ir" dependendo do seu perfil.

- **Se você é gestor e quer visão de contexto**
  - [Introdução e conceitos legais](/documentacao/reforma-tributaria/conceitos-legais/introducao)
  - [Glossário da Reforma do Consumo](/documentacao/reforma-tributaria/conceitos-legais/glossario-reforma-tributaria-consumo)
  - [Dúvidas frequentes gerais](/documentacao/reforma-tributaria/perguntas-e-respostas/)

- **Se você é fiscal/contábil e cuida de parametrização**
  - [Tabelas de referência (CST, classCode, etc.)](/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/)
  - [Layout RTC NF-e/NFC-e](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/documentacao-layout-nfe-rtc/)
  - [Layout RTC NFS-e](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc/)

- **Se você é desenvolvedor**
  - [APIs RTC NF-e/NFC-e](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-produto-consumidor-rtc)
  - [APIs RTC NFS-e](/desenvolvedores/rest-api/reforma-tributaria/nota-fiscal-de-servico-rtc)
  - [Guia de troubleshooting NF-e RTC](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/guia-solucao-problemas-nfe-nfce-rtc/)

- **Se você está na operação/faturamento**
  - [Emissão em lote de NFS-e com planilha](/documentacao/nossa-plataforma/nota-fiscal-servico/emitir-em-lote/)
  - [Template de planilha NF-e simplificada](/documentacao/nota-fiscal-produto-eletronica/template-de-planilha-simplificada-para-processamento-de-notas-fiscais/)
  - [Monitoramento de adesão de municípios (NFS-e)](/documentacao/reforma-tributaria/monitoramento-adesao-municipios-nfse-ambiente-nacional/)

Sempre que uma nova fase ou regra da Reforma entrar em vigor, a NFE.io atualiza estes materiais. Vale manter esta página nos favoritos como seu ponto de partida para navegar pelas novidades da Reforma Tributária dentro da plataforma.

---

## Perguntas e Respostas sobre a Reforma Tributária

Source: https://nfe.io/docs/documentacao/reforma-tributaria/perguntas-e-respostas/index.md

# Reforma Tributária - Perguntas e Respostas

## Introdução

Esta seção reúne as dúvidas mais comuns sobre a Reforma Tributária do Consumo e seus impactos na emissão de notas fiscais com a NFE.io. As respostas são baseadas na legislação atual (Emenda Constitucional 132/2023 e regulamentações complementares) e na documentação técnica das nossas APIs.

:::info

Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

:::

## Meu Município não aderiu ao Ambiente Nacional de NFS-e. O que fazer?

Para municípios que continuam utilizando **provedores próprios de emissão de NFS-e**, siga as orientações disponíveis na seção [Municípios que não utilizam o Ambiente Nacional de Nota Fiscal de Serviço](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/municipios-que-nao-utilizam-ambiente-nacional).

## Meu Município aderiu ao Ambiente Nacional de NFS-e. O que fazer?

Para municípios que **aderiram ao Ambiente Nacional de NFS-e**, siga as orientações disponíveis na seção [Adequação ao Emissor em Ambiente Nacional de NFS-e](/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/adequacao-ao-emissor-ambiente-nacional-nfse).

## O que acontece se o portal do governo ficar instável?

Nossa infraestrutura de **retentativas automáticas** mantém a operação fluindo, sem necessidade de intervenção manual.

## Notas travadas em "Definindo número de RPS", "Enviando" ou "Baixando nota", como corrigir?

Estes status indicam etapas do processamento da nota fiscal que podem travar devido a instabilidades externas ou configurações incorretas:

*   **Definindo número de RPS:** O sistema está tentando atribuir um sequencial à nota. Travamentos aqui geralmente indicam conflito de numeração (último RPS usado na prefeitura é maior que o configurado na NFE.io).
    *   **Solução:** Consulte o último RPS no site da prefeitura. No painel da NFE.io, vá em **Empresa > Dados Fiscais**, atualize o **"Número do RPS"** para o próximo sequencial válido e salve.
*   **Enviando:** A nota foi enviada e o sistema aguarda resposta da prefeitura.
    *   **Solução:** Geralmente indica **instabilidade na prefeitura**. Aguarde alguns minutos. Se persistir, contate o suporte.
*   **Baixando nota:** A nota foi processada com sucesso (emitida), mas o PDF/XML ainda não foi baixado.
    *   **Solução:** **Não reemita a nota** para evitar duplicidade, pois ela já existe fiscalmente. Se o download falhar definitivamente, contate o suporte da NFE.io para reprocessar apenas a captura do arquivo.

## Os campos de IBS/CBS estão aparecendo em branco ou zerados no PDF. O que fazer?

O primeiro passo é verificar se os campos IBS e CBS estão sendo corretamente enviadas para a nossa API durante a emissão. Em seguida, é importante validar qual ambiente está sendo utilizado:

*  **Ambiente Nacional de NFS-e:** normalmente indica que os dados não estão sendo enviados no formato ou nos campos esperados. Verifique a documentação técnica da NFE.io para garantir que os campos do grupo `IbsCbs` estão sendo preenchidos corretamente.

*  **Ambiente Municipal próprio:** alguns municípios ainda não suportam a exibição dos novos campos IBS/CBS nos documentos fiscais. Neste caso, consulte a prefeitura para confirmar se há suporte para esses campos e quando será implementado.

## Minhas notas estão retornando o erro "XML não compatível com schema" nas emissões após janeiro de 2026. O que significa?

Esse erro indica que o XML enviado para a prefeitura não está em conformidade com o layout exigido pelo novo padrão da Reforma Tributária. Isso geralmente ocorre devido a:

* A prefeitura ainda está em processo de integração ou adequação ao novo modelo.
* Há preenchimento de informações fora do padrão exigido pelo schema vigente. 

Esse tipo de erro exige uma análise mais detalhada, pois pode haver diferentes causas associadas ao ambiente e às regras municipais. 

## Precisamos mudar algo agora para empresas do Simples Nacional ou MEI?

**Não. Nenhuma ação imediata é obrigatória.** As adequações para esses regimes acontecem ao longo do período de transição, previsto para 2027, e podem ser testadas com antecedência, sem urgência. 

## Precisamos mudar algo agora para empresas do Lucro Real ou Lucro Presumido?

É necessário apenas um ajuste mínimo, basicamente relacionado à indicação de dados da operação, como a classificação tributária. A NFE.io realiza o cálculo dos novos tributos e a geração da nota fiscal. As adequações ocorrem de forma gradual, conforme a implementação pelo fisco, e também podem ser testadas com antecedência.

## Como corrigir o status da minha nota fiscal que aparece como emitida no portal da prefeitura, mas como erro no painel da NFE.io? 

Trata-se de um ajuste interno. É necessário abrir um chamado na plataforma para que seja realizada a reconsulta do lote e a atualização do status na plataforma.

## Onde encontro os códigos NBS e indicadores de operação exigidos?

A **NBS (Nomenclatura Brasileira de Serviços)** e os novos indicadores de operação são tabelas padronizadas pelo governo. Na documentação da NFE.io, disponibilizamos links e referências para essas tabelas na seção de [Tabelas de Referência](/documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia), para que você possa mapear seus serviços internos para os códigos oficiais (similar ao que é feito hoje com a lista da LC 116).

## O que acontece com o ICMS e o ISS durante a transição?

Durante o período de transição (2026 a 2032), o ICMS e o ISS **continuam existindo**. Eles serão cobrados simultaneamente com o IBS e a CBS, mas com suas alíquotas sendo reduzidas gradualmente a partir de 2029, até serem extintos em 2033. Portanto, nos próximos anos, os documentos fiscais deverão comportar informações dos dois sistemas.

## O que muda especificamente em Belo Horizonte para a NFS-e Nacional?

Para Belo Horizonte, a obrigatoriedade do **Emissor Nacional da NFS-e** para pessoas jurídicas entrou no radar com data de **1º de fevereiro de 2026**. Prestadores de serviço desta localidade devem estar atentos à integração com o padrão nacional, embora a prefeitura possa permitir a emissão via sistema municipal com compartilhamento de dados durante a transição.

## A NFE.io realizará o cálculo automático do IBS e CBS?

Sim. A NFE.io está atualizando seu **motor de cálculo** para suportar as regras da Reforma Tributária. O objetivo é que, ao informar os parâmetros da operação (produto, valores, locais), nossa API possa calcular as alíquotas estimadas de IBS e CBS, facilitando o preenchimento dos documentos fiscais, assim como já fazemos para os tributos atuais.

## O que é o "Grupo IbsCbs" na API de serviços (NFS-e) e ele é obrigatório?

É um novo grupo de campos no layout da API de Serviços (versão 4) destinado exclusivamente aos dados da Reforma. Segundo a documentação, ele centraliza informações como alíquotas, valores e indicadores de tributação dos novos impostos. Para emissões no novo padrão nacional, o envio deste grupo torna-se **obrigatório** para validar a nota perante o ambiente nacional.

## Qual a diferença entre o município de consumo (cMunFG) e o de fato gerador do IBS (cMunFGIBS) na NF-e?

Na NF-e atual, o local de ocorrência (cMunFG) geralmente define o ICMS. Com a Reforma, o IBS é devido integralmente ao **local de destino/consumo** do bem ou serviço. Em situações específicas (como vendas presenciais fora do estabelecimento), pode haver divergência entre o local da venda e o local onde o imposto é devido. O campo `ibsConsumptionCityCode` permite indicar especificamente onde o imposto IBS deve ser alocado, garantindo o repasse correto ao município de direito.

## Como identificar operações presenciais ou à distância na nova versão da API?

A API da NFE.io (v3 para produtos) reforça o uso do campo `presenceType` (Indicador de Presença). Ele é vital para a Reforma Tributária, pois vendas presenciais e vendas online podem ter regras diferentes de alocação do imposto (origem vs. destino). Certifique-se de preencher `Presence` (presencial) ou `Internet`/`Delivery` corretamente para garantir o cálculo fiscal adequado.

## Quais são os novos impostos criados pela Reforma (IBS, CBS e IS)?

A Reforma extingue PIS, Cofins, IPI, ICMS e ISS e cria três novos tributos:
*   **CBS (Contribuição sobre Bens e Serviços):** Competência federal, substitui PIS e Cofins.
*   **IBS (Imposto sobre Bens e Serviços):** Competência compartilhada (estados e municípios), substitui ICMS e ISS.
*   **IS (Imposto Seletivo):** Incide sobre bens prejudiciais à saúde ou meio ambiente (o "imposto do pecado").

## A NFE.io acompanha as mudanças legais contínuas?

**Sim.** Monitoramos e atualizamos a plataforma conforme novas regras e fases da Reforma Tributária.

## A solução funciona para empresas de qualquer porte?

**Sim.** Atendemos desde microempresas até operações que emitem milhões de documentos fiscais.

## Existe um ambiente de homologação para testar as novas regras?

**Sim**. A API da NFE.io oferece o ambiente de `Test` (Homologação), onde você pode enviar requisições com os novos layouts (v3 para produtos, v4 para serviços) e validar a estrutura dos dados sem valor fiscal. Recomendamos fortemente que desenvolvedores utilizem este ambiente para validar o preenchimento dos grupos `IbsCbs` e a resposta do sistema antes de virar a chave para produção.

## Minha empresa será multada se não preencher os novos campos em 2026?

De acordo com o Ato Conjunto RFB/CGIBS nº 1/2025, durante a fase inicial de transição em 2026, **não haverá multas** pela ausência ou preenchimento incorreto dos campos de IBS e CBS. O foco inicial é a adaptação dos sistemas ("fase de assistida"), mas é crucial começar a adaptar seu software para evitar problemas quando a fiscalização se tornar efetiva.

## O que muda a partir de janeiro?

A partir de 1º de janeiro inicia-se o período de transição da Reforma Tributária. Na prática, **não há mudanças imediatas na operação**. Os novos tributos (IBS e CBS) passam a conviver com os tributos atuais de forma gradual ao longo do período de transição.

*Detalhe técnico:* Durante 2026, teremos a "fase de teste", onde o recolhimento será simbólico (alíquotas de 0,9% para CBS e 0,1% para IBS) e compensável com PIS/Cofins, conforme Ato Conjunto RFB/CGIBS nº 1/2025.

## O que muda na emissão das notas fiscais?

O fluxo de emissão permanece exatamente o mesmo. O que muda é a **estrutura fiscal da nota**, que passa a suportar o novo modelo tributário. Essa adaptação ocorre sem impacto no dia a dia da operação, desde que sejam fornecidas as **informações mínimas necessárias para o cálculo dos novos tributos**.

## Precisamos alterar algo na API ou nas integrações?

**Não neste momento.** As integrações atuais continuam funcionando normalmente. O que ocorre é uma evolução do modelo, e não a troca de API:
*   Novos campos passam a existir para atender à Reforma;
*   As mudanças são incrementais;
*   Não há quebra de integração nem necessidade de refazer sistemas agora.

## Existe risco de parar de emitir notas fiscais?

**Não, para empresas que utilizam sistemas preparados.** O risco existe apenas para quem não se adequar ao novo modelo ao longo do tempo.

## A emissão continua funcionando durante o período de transição?

**Sim.** Ao utilizar o motor de cálculo da NFE.io, é possível aplicar automaticamente as regras dos tributos atuais durante o período de transição, mantendo a emissão normal.

## Preciso alterar meu sistema para emitir notas no modelo da Reforma?

**Não.** A NFE.io adapta internamente os cálculos e layouts, sem exigir alterações no sistema do cliente.

---

## Como Cadastrar, Consultar, Listar, Editar e Excluir WebHook

Source: https://nfe.io/docs/documentacao/webhooks/integracao/index.md

# Como Cadastrar, Consultar, Listar, Editar e Excluir um WebHook

Nesse tutorial você entenderá como cadastrar, consultar, listar, editar e excluir WebHook de maneira fácil, simples e intuitiva.

## Ao final desse tutorial, você será capaz de:

[1\. Consultar tipos de eventos][12]  
[2\. Cadastrar um webhook][6]  
[3\. Consultar um webhook][13]  
[4\. Editar um webhook][14]  
[5\. Excluir um webhook][15]  
[6\. Listar todos webhooks][16]

## Tutorial

A partir desse momento faremos uma breve explicação de como realizar a integração de WebHooks com a API oferecida pela [NFE.io.][17]

**Veja mais sobre a**[ Documentação da API][18]

> Você pode realizar a importação da url no Postman para ter todos os seguintes exemplos através do link:

```json
https://www.getpostman.com/collections/e0ddf9363c66efd43bc8
```

Tutorial de como importar a url no postman [Clique aqui][19]

## Primeiros passos

Antes de tudo, você precisará realizar um cadastro na nossa plataforma [app.nfe.io.][20] Depois, você terá que pegar a chave de autorização do nosso sistema.

> Devemos atentar para copiar a autorização referente **'Nota fiscal'**

**Veja como pegar a chave de autorização na plataforma:** Autenticação

> **Lembre-se:** Após importar a url do postman e copiar a chave de autenticação para nota fiscal eletrônica, você deverá adicionar em cada requisição na aba "Headers" (cabeçalhos) a chave em "Authorization" (autorização).Lembre-se: Após importar a url do postman e copiar a chave de autenticação para nota fiscal eletrônica, você deverá adicionar em cada requisição na aba "Headers" (cabeçalhos) a chave em "Authorization" (autorização).

![WebHook](https://nfe.io/docs/static/docs/webhooks/authentication-key-1.png)

## 1\. Tipos de Eventos

Para começar a ser notificado pelo WebHoook precisamos identificar quais os eventos possíveis na nossa plataforma. Para isso, precisamos realizar uma chamada no `/eventTypes`

> O método HTTP utilizada na requisição é o "GET", portanto, verifique no seu postman se está preenchido corretamente.

`GET: https://api.nfse.io/v2/webhooks/eventTypes`

1. Clicar no botão "Send" (Enviar) para completar a requisição.

![WebHook_eventos](https://nfe.io/docs/static/docs/webhooks/get-event-types.png)

1. Será retornado os eventos disponíveis na plataforma.

![WebHook_result](https://nfe.io/docs/static/docs/webhooks/get-event-types-result.png)

## 2\. Cadastrar

Agora, vamos cadastrar um WebHook.

Para auxiliar nos testes, utilizaremos um gerador de webhook, neste caso, você poderá utilizar qualquer site de webhooks da sua preferência. Caso não tenha um, te indicamos: [http://webhook.site][21]

**PS: A** [NFE.io][17] **não tem nenhum vínculo com este gerador de WebHook**

> Atenção: A URI indicada na requição será validada no momento da criação e atualização.
> 
> O método HTTP utilizado para cadastrar um webhook é o "POST", portanto, verifique no seu postman se está preenchido corretamente.  
> (Utilize o Create WebHook na coleção)

`POST: https://api.nfse.io/v2/webhooks`

1. Clicar no botão "Send" (Enviar) para completar a requisição.  
![](https://nfe.io/docs/static/docs/webhooks/create-webhook.png)

> Será retornado os dados do webhook contendo o identificador deste webhook no campo id.  
> Ao final do envio, você poderá verificar no gerador de webhooks uma notificação.

![](https://nfe.io/docs/static/docs/webhooks/create-webhook-result.png)

## 3\. Consultar

No passo anterior, vimos como criar um webhook.

Faremos agora a consulta do webhook criado a partir da **id** gerada anteriormente, substituindo-o no campo `{webhookId}` da request.

> O método HTTP utilizado para a consulta de um webhook é "GET", portanto, verifique no seu postman se está preenchido corretamente.  
> (Utilize o `Get WebHook` na coleção)

`GET: https://api.nfse.io/v2/webhooks/{webhookId}`

1. Clicar no botão "Send" (Enviar) para completar a requisição.  
![](https://nfe.io/docs/static/docs/webhooks/get-webhook-1.png)
2. Será retornado os dados do webhook.

![](https://nfe.io/docs/static/docs/webhooks/get-webhook-result.png)

## 4\. Editar

Quando precisamos editar algum dado do webhook, trocar a uri por exemplo, utilizamos da seguinte forma.

Faremos agora a edição do webhook criado a partir da id gerada anteriormente, substituindo-o no campo `{webhookId}` da request.

> **O método HTTP utilizado para editar um webhook é "PUT", portanto, verifique no seu postman se está preenchido corretamente**.  
> (Utilize o Update `WebHook` na coleção)
> 
> Atenção: A URI indicada na requição será validada no momento da criação e atualização.

`PUT: https://api.nfse.io/v2/webhooks/{webhookId}`

1. Clicar no botão "Send" (Enviar) para completar a requisição.  
```javascript  
{  
"webHook": {  
    "insecureSsl": true,  
    "contentType": "json",  
    "filters": [  
        "consumer_invoice.cancelled_error"  
    ],  
    "uri": "https://nova.url.com"  
}  
}  
```

![](https://nfe.io/docs/static/docs/webhooks/update-webhook.png)

1. Será retornado os dados do webhook editado.

![](https://nfe.io/docs/static/docs/webhooks/update-webhook-result.png)

## 5\. Excluir

Para remover um webhook criado, precisamos da **id** gerada anteriormente, substituindo-o no campo `{webhookId}` da request.

> **O método HTTP utilizado para excluir um webhook é "DELETE", portanto, verifique no seu postman se está preenchido corretamente.**  
> (Utilize o `Delete WebHook` na coleção)

`DELETE: https://api.nfse.io/v2/webhooks/{webhookId}`

1. Clicar no botão "Send" (Enviar) para completar a requisição.  
![](https://nfe.io/docs/static/docs/webhooks/update-webhook-1.png)
2. Será retornado o Status "200 OK" ao sucesso do cancelamento.  
![](https://nfe.io/docs/static/docs/webhooks/update-webhook-result-1.png)

## 6\. Listar

Para listar todos os webhooks, apenas será necessário realizar a request de consulta sem passar nenhuma informação adicional na request.

> **O método HTTP utilizado para excluir um webhook é "GET", portanto, verifique no seu postman se está preenchido corretamente.**  
> (Utilize o `List All WebHooks` na coleção)

`GET: https://api.nfse.io/v2/webhooks`

1. Clicar no botão "Send" (Enviar) para completar a requisição.

![](https://nfe.io/docs/static/docs/webhooks/get-all-webhooks.png)

1. Será retornado a lista de webhoooks previamente cadastrados.

![](https://nfe.io/docs/static/docs/webhooks/get-all-webhooks-result.png)

## Veja também:

1.[ Dúvidas frequentes][22]  
2.[ WebHooks na NFE.io][23]  
3.[Faça uma conta e teste gratuitamente][24]


[1]: #Como%5FCadastrar%5FConsultar%5FListar%5FEditar%5Fe%5FExcluir%5Fum%5FWebHook
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #Tutorial
[4]: #Primeiros%5Fpassos
[5]: #1%5FTipos%5Fde%5FEventos
[6]: #2%5FCadastrar
[7]: #3%5FConsultar
[8]: #4%5FEditar
[9]: #5%5FExcluir
[10]: #6%5FListar
[11]: #Veja%5Ftambem
[12]: https://nfe.io/docs/documentacao/webhooks/integracao/#1%5FTipos%5Fde%5FEventos
[13]: https://nfe.io/docs/documentacao/webhooks/integracao/#3%5FConsultar
[14]: https://nfe.io/docs/documentacao/webhooks/integracao/#4%5FEditar
[15]: https://nfe.io/docs/documentacao/webhooks/integracao/#5%5FExcluir
[16]: https://nfe.io/docs/documentacao/webhooks/integracao/#6%5FListar
[17]: https://nfe.io/
[18]: https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-nota-fiscal/v2/
[19]: https://nfe.io/docs/documentacao/nota-fiscal-produto-eletronica/importar-colecao-postman/
[20]: https://app.nfe.io/
[21]: http://webhook.site
[22]: https://nfe.io/docs/webhooks/duvidas/
[23]: https://nfe.io/docs/webhooks/conceitos/
[24]: https://id.nfe.io/signup?returnUrl=%2Fconnect%2Fauthorize%2Fcallback%3Fclient%5Fid%3Dapp-nfe-customers-dashboard%26grant%5Ftype%3Dcode%2520implicit%26response%5Ftype%3Did%5Ftoken%2520token%26scope%3Dopenid%2520profile%2520email%2520phone%2520roles%2520aztech.platform.api%26redirect%5Furi%3Dhttps%253A%252F%252Fapp.nfe.io%252Flogin-callback%26state%3DdQvLVGoYbBfwwNScwPJE%26nonce%3DjR0TBmT1saSA5VUoozI5

---

## Conceitos sobre Webhook e seu funcionamento

Source: https://nfe.io/docs/documentacao/webhooks/conceitos/index.md

# Conceitos de WebHook

Abaixo um breve tutorial sobre o funcionamento do Webhook em: Conceitos sobre [WebHook.][8] Logo, é um ponto de encontro entre você e a sua nota.

## 1\. Como funciona na NFE.io?

Quando estamos falando de emissão de nota, vimos que nenhum sistema é perfeito, então, entendemos que sistema do Governo pode ficar fora do ar, ter instabilidades ou ter uma série de regras para emissão que pode levar a um tempo maior para o sucesso.

Você poderá enviar os dados para emissão das notas, processaremos, e através dos webhoooks poderemos te avisar o que aconteceu no processo.

O WebHook é um ponto de encontro entre você e a sua nota, ou seja, você não precisará ficar esperando todo o processamento para identificar o estado dela, e sim, te avisaremos no momento de sua conclusão. Em algumas regras de negócio, ela faz total sentido.

## 2\. Fluxo de notificação

No exemplo seguinte, faremos uma análise do fluxo de emissão e notificação.

Basicamente temos dois passos:

1. O "Sistema Cliente" que envia os dados da nota fiscal para a NFE.io.
2. Após todo o fluxo de emissão de nota, faremos as notificações devidas na nota fiscal utilizando o WebHook.

Essas notificações são enviadas para o "Sistema do Cliente" de acordo com a ação identificada (emitida, erro ou falha).

### Ilustração do fluxo

![webhook](https://nfe.io/docs/static/docs/webhooks/webhook-flow.png)

#### Passo a passo:

1. Sistema do Cliente envia os dados para emissão.
2. Sistema NFe.io recebe dados para emitir.
3. NFE.io processa a nota fiscal.
4. NFE.io entende o estado da nota, se foi emitida com sucesso, com erro ou com falha.
5. NFE.io aciona o gatilho de notificação para o Sistema do Cliente baseado no status da nota fiscal.
6. Sistema do Cliente recebe a nota fiscal na url equivalente ao status da nota.

#### Como utilizar?

Agora que você já tem uma ideia de como funcionam os WebHooks, os próximos passos são:

[1\. Tutorial de webhooks][11]  
[2\. Consultar tipos de eventos][12]  
[3\. Cadastrar um webhook][13]  
[4\. Consultar um webhook][14]  
[5\. Editar um webhook][15]  
[6\. Excluir um webhook][16]  
[7\. Listar todos webhooks][17]


[1]: #Conceitos%5Fde%5FWebHook
[2]: #O%5Fque%5Fencontrara%5Fno%5Ftexto
[3]: #1%5FComo%5Ffunciona%5Fna%5FNFEio
[4]: #2%5FFluxo%5Fde%5Fnotificacao
[5]: #Ilustracao%5Fdo%5Ffluxo
[6]: #Passo%5Fa%5Fpasso
[7]: #Como%5Futilizar
[8]: /documentacao/conceitos/webhook
[9]: #1%5FComo%5Ffunciona%5Fna%5FNFEio
[10]: #2%5FFluxo%5Fde%5Fnotificacao
[11]: /documentacao/webhooks/integracao
[12]: /documentacao/webhooks/integracao#1%5FTipos%5Fde%5FEventos
[13]: #2%5FCadastrar
[14]: /documentacao/webhooks/integracao#3%5FConsultar
[15]: /documentacao/webhooks/integracao#4%5FEditar
[16]: /documentacao/webhooks/integracao#5%5FExcluir
[17]: /documentacao/webhooks/integracao#6%5FListar

---

## Dúvidas frequentes sobre webhook

Source: https://nfe.io/docs/documentacao/webhooks/duvidas-frequentes/index.md

# Dúvidas frequentes

Essa seção de dúvidas frequentes sobre o webhook, tem o objetivo se clarificar qualquer dúvida que possa aparecer durante seu aprendizado.

## 1\. Após o cadastro de webhook, o que recebo nas notificações?

* De acordo com o webhook cadastrado, será enviado uma nota fiscal completa (os mesmos dados retornados na **consulta da nota fiscal**), adicionado dos campos do webhook informados no momento de sua criação.  
Veja como realizar a [consulta da nota fiscal][9].

## 2\. Como saber se o webhook que recebi é da NFE.io?

Disponibilizamos o campo **secret** para validar que os webhooks que recebe do host da [NFE.io][10] são legítimos.

O objetivo é calcular um hash usando seu **SECRET\_TOKEN** e garantir que o hash da NFE.io corresponda. O [NFE.io][10] usa um HMAC para calcular o hash.

Segredo, contendo de 32 até 64 caracteres que será usado gerar o valor do HMAC em hexadecimal que será enviado no cabeçalho HTTP X-Hub-Signature. O HMAC será gerado baseado no bytes do evento de notificação que será enviado.

## 3\. Como funciona os Headers?

Caso você precise passar algum campo validador do seu sistema autorizando o nosso sistema enviar notificações.

**Exemplo:**

Autenticação, disponibilizamos um campo chamado "Header" que poderá ser preenchido de acordo com a sua necessidade. Sendo enviado no momento da criação como **"Authorization"**:

**Json para análise dos Headers**

```json
{
  "webHook": {

        "insecureSsl": true,
        "contentType": "json",
        "filters": [
            "product_invoice.issued_successfully"
        ],
        "headers": [
            "Authorization": "api-key-test"
        ],
        "uri": "https://webhook.site/3483dade-39b8-445f-8928-95f0c0897c76"
    }
}
```


[1]: #Duvidas%5Ffrequentes
[2]: #O%5Fque%5Fencontrara%5Fno%5Ftexto
[3]: #1%5FApos%5Fo%5Fcadastro%5Fde%5Fwebhook%5Fo%5Fque%5Frecebo%5Fnas%5Fnotificacoes
[4]: #2%5FComo%5Fsaber%5Fse%5Fo%5Fwebhook%5Fque%5Frecebi%5Fe%5Fda%5FNFEio
[5]: #3%5FComo%5Ffunciona%5Fos%5FHeaders
[6]: #1%5FApos%5Fo%5Fcadastro%5Fde%5Fwebhook%5Fo%5Fque%5Frecebo%5Fnas%5Fnotificacoes
[7]: #2%5FComo%5Fsaber%5Fse%5Fo%5Fwebhook%5Fque%5Frecebi%5Fe%5Fda%5FNFEio
[8]: #3%5FComo%5Ffunciona%5Fos%5FHeaders
[9]: /documentacao/consultas/notas-fiscais
[10]: https://nfe.io/

---

## IPs de origem dos webhooks

Source: https://nfe.io/docs/documentacao/webhooks/ips-de-origem/index.md

# IPs de origem dos webhooks

Os webhooks da NFE.io são enviados a partir de uma lista conhecida de endereços IP. Se você restringe o tráfego de entrada por firewall, adicione **todos** os IPs abaixo à sua allowlist para garantir o recebimento das notificações.

:::warning Não dependa apenas do IP
O filtro por IP é uma camada **adicional** de segurança. A forma correta de verificar a autenticidade de um webhook é validar sua **assinatura HMAC** (cabeçalho `X-Hub-Signature`). IPs de origem podem mudar; a assinatura, não. Veja [Dúvidas frequentes — validação da assinatura](./duvidas-frequentes.md).
:::

## Endereços ativos (Produção)

| IP                | Ambiente  | Status |
|-------------------|-----------|--------|
| `34.44.243.117`   | Produção  | Ativo  |
| `40.78.80.242`    | Produção  | Ativo  |
| `20.237.231.30`   | Produção  | Ativo  |
| `104.45.219.39`   | Produção  | Ativo  |

## Como configurar a allowlist

1. Libere o tráfego de **entrada HTTPS (porta 443)** vindo de todos os IPs da tabela acima para o seu endpoint de webhook.
2. Ao incluir um novo IP, **nunca remova** os existentes — todos permanecem ativos simultaneamente.
3. Após a mudança, valide o recebimento com um evento de teste.

## Como verificar a autenticidade

Em vez de confiar apenas no IP, valide a assinatura de cada requisição:

- Cabeçalho `X-Hub-Signature`, no formato `sha1=<hash>`.
- Algoritmo **HMAC-SHA1**, usando o `SECRET_TOKEN` (32 a 64 caracteres) configurado no seu webhook.
- O hash é calculado sobre os **bytes do corpo** do evento de notificação.

Passo a passo em [Dúvidas frequentes — validação da assinatura](./duvidas-frequentes.md).

## Mudanças nos IPs

Novos IPs de origem são comunicados por meio das nossas [Release notes](/release-notes). Acompanhe esta página e as release notes para se manter atualizado.

## Para IA / LLMs

- **Cobertura:** IPs de origem usados pela NFE.io para **enviar webhooks**. Não cobre IPs de envio de e-mail ou de outros serviços.
- **Não parafrasear:** a lista de IPs e o status de cada um — usar exatamente como na tabela.
- **Autenticação:** a verificação primária é a assinatura HMAC (`X-Hub-Signature`), não o IP de origem. Não recomende confiar apenas no IP.
- **Atualizado:** 2026-06-22 por revisão humana.

---

## Adicionar Novos Usuários a Conta

Source: https://nfe.io/docs/duvidas-frequentes/adicionar-novos-usuarios-a-conta/index.md

# Adicionar novos Usuários a conta

Ao final desse tutorial, você será capaz de:

* [Adicionar novos usuários na sua conta][5]
* [Como localizar o Administrador da conta][6]
* [Como criar uma conta na plataforma da NFe.io][7]

## 1\. Adicionar novos Usuários

Primeiro acesse a [plataforma][8] com usuário administrador da conta, caso não souber qual é o usuário administrador da conta, [clique Aqui][6].

> Somente o usuário administrador da conta pode adicionar ou remover usuários.

Após fazer o login com o administrador da conta clique em > CONTA > USUARIOS > ADCIONAR USUÁRIO.

![](https://nfe.io/docs/static/docs/imagem-1.png)

Preencha o e-mail do novo usuário e clique em enviar convite.

![](https://nfe.io/docs/static/docs/WINWORD_WZEM2jFsid.png)

O novo usuário recebera um -e-mail de confirmação do cadastro, aceite o convite.  
Caso o usuário cadastrado já tenha um cadastro na plataforma da NFe.io é só fazer o login que terá acesso a conta.  
Caso usuário cadastrado não tenha conta criada [clique aqui][9].

## 2\. Localizando o Administrador da conta.

Acesse a plataforma clique em CONTA > INFORMAÇÕES DA CONTA 

![](https://nfe.io/docs/static/docs/WINWORD_hBWxrMEvZl.png)


[1]: #Adicionar%5Fnovos%5FUsuarios%5Fa%5Fconta
[2]: #Ao%5Ffinal%5Fdesse%5Ftutorial%5Fvoce%5Fsera%5Fcapaz%5Fde
[3]: #1%5FAdicionar%5Fnovos%5FUsuarios
[4]: #2%5FLocalizando%5Fo%5FAdministrador%5Fda%5Fconta
[5]: #1%5FAdicionar%5Fnovos%5FUsuarios
[6]: #2%5FLocalizando%5Fo%5FAdministrador%5Fda%5Fconta
[7]: /documentacao/nossa-plataforma/criar-conta#1-cadastrar-uma-conta-ou-realizar-login
[8]: https://id.nfe.io/v2/login?ReturnUrl=%2Fconnect%2Fauthorize%2Fcallback%3Fclient%5Fid%3Dapp-nfe-customers-dashboard%26grant%5Ftype%3Dcode%2520implicit%26response%5Ftype%3Did%5Ftoken%2520token%26scope%3Dopenid%2520profile%2520email%2520phone%2520roles%2520aztech.platform.api%26redirect%5Furi%3Dhttps%253A%252F%252Fapp.nfe.io%252Flogin-callback%26state%3Dn8x2Gxoel2Z.jszgo8DN%26nonce%3D.Zjj87.phsoIcVyVY7xe
[9]: /documentacao/nossa-plataforma/criar-conta

---

## Como fazer a ativação do SAT no Sistema de Gestão e Retaguarda

Source: https://nfe.io/docs/duvidas-frequentes/como-fazer-a-ativacao-do-sat-no-sistema-de-gestao-e-retaguarda-do-sat-cf-e-em-sao-paulo/index.md

# Como fazer a ativação do SAT no Sistema de Gestão e Retaguarda do SAT-CF-e em São Paulo

SAT é um equipamento desenvolvido em São Paulo a emissão do cupom fiscal no Estado.

Ele também faz a transmissão imediata dos dados da transacão para a Secretária da Fazenda, [automatizando todo o processo][44].

Mas você sabe como ativar o equipamento SAT nota fiscal e começar a usar em seu estabelecimento?

Veja, agora, como fazer isso!

## Preparando-se para ativar o SAT nota fiscal

Antes de fazer a ativação do SAT nota fiscal no sistema de Gestão e Retaguarda, é preciso se certificar de algumas providências.

### 1 - Você precisa ter um Aplicativo Comercial adequado

Para o SAT funcionar, é preciso contar com um AC, Aplicativo Comercial, compatível com o SAT nota fiscal.

Nesta página da SEFAZ de São Paulo [http://www.fazenda.sp.gov.br/sat/][45] você pode achar softwares compatíveis com o SAT nota fiscal.

### 2 - Conexão online

Evidentemente seu equipamento SAT nota fiscal precisa estar conectado à internet para que os dados possam ser enviados à SEFAZ de São Paulo.

### 3 - Contar com o equipamento SAT nota fiscal

Para escolher seu equipamento SAT nota fiscal, acesse esta página da SEFAZ de São Paulo: [http://www.fazenda.sp.gov.br/sat/][45]

### 4 - Um computador com entrada USB

O equipamento SAT nota fiscal não funciona sozinho, ele precisa etar conectado a um dispistivo computacional, como um PC.

### 5 - Impressora

A impressora usada pode ser de qualquer tipo, desde que seja capaz de imprimir o CF-e-SAT.

## Passo a passo para ativar o SAT nota fiscal ao Sistema de Gestão e Retaguarda do SAT-CF-e SP

### 1 - Associar seu equipamento SAT ao CNPJ da emprersa

Antes de iniciar a ativação do SAT propriamente dita, você deve vincular o SAT ao seu CNPJ.

Para isso, acesse o [SGRSAT][46] e siga as seguintes instruções:

1. Acesse o endereço: [https://satsp.fazenda.sp.gov.br/COMSAT/][47];
2. Assinale se é um contribuinte, um procurador ou um contabilista;
3. Defina como vai fazer o acesso. Como contribuiente use o e-CNPJ, como procurador use o e-CPF, para acessar como empresa existem 2 opções: se a empresa já é credenciada no DEC, acesse o certificado digital, se não for, acesse por meio de usuário e senha do Posto Fiscal Eletrônico;
4. Selecione qual dos CNPJs de eventuaias filiais de sua empresa vai usar;
5. Em seguida, no menu "equipamento", selecione "ações";
6. Depois, clique em "vincular ao SAT";
7. Na janela que vai surgir, preencha o campo "Número de Série do Equipamento" e clique no sinal "+";
8. Preencha com seu e-mail;
9. Leia o termo de aceite e, se concordar, selecione se vai usar o certificado digital da SEFAZ ou um certificado padrão ICP-Brasil;
10. No segundo caso, leia o aviso sobre custos e, se concordar, clique em "sim";
11. Verifique a tela de confirtmação e se estiver tudo correto, clique em "sim".
12. Depois de ver a mensagem de sucesso, esta etapa estea finalizada e você pode imprimir uma cópia ou gerar um PDF clicando em "imprimir".

### 2 - Ative o SAT com ajuda das instruções do fabricante

### 3 - Vincule o Aplicativo Comercial ao SAT

Para isso, consulte os fornecedores do equipamento e do software AC e veja como fazer isso.

## Com saber se tudo correu bem?

Durante a ativação do SAT no Sistema de Gestão de Retaguarda, caso algo não esteja ocorrendo adequadamente, avisos serão enviados ao usuário.

Veja alguns deles e o que fazer:

### O usuário não possui permissões de acesso para o perfil escolhido

Veja se escolheu o tipo de perfil correto correto ou o certificado digital correto.

### Usuário não tem permissão para acessar o sistema com e-CPF. Favor logar com e-CNPJ

Veja se definiu o perfil e o certificado digital correto. No caso dê acesso como contabilista, veja se a empresa o cadastrou no CADESP.

### Usuário não tem permissão para acessar o sistema com e-CNPJ. Favor logar com e-CPF

Veja se definiu o perfil e o certificado digital correto. No caso dê acesso como contabilista, veja se a empresa o cadastrou no CADESP.

### Contabilista não esta cadastrado no CADESP.

Veja se definiu o perfil e o certificado digital correto. No caso dê acesso como contabilista, veja se a empresa o cadastrou no CADESP.

### Consulta à Receita Federal temporariamente indisponível. Por favor, tente novamente mais tarde.” ou Consulta ao CADESP temporariamente indisponível. Por favor, tente novamente mais tarde

Tentar novamente em alguns minutos.

### Não existe nenhuma procuração para o usuário logado no sistema

Veja se definiu o perfil e o certificado digital correto. No caso de acesso como contabilista, veja se a empresa o cadastrou no Sistema de Gestão e Retaguarda do SAT-CF-e.

### O contribuinte não esta cadastrado no sistema

Confira se o contribuinte está mesmo cadastrado.

### Usuário não tem permissão de acesso ao sistema.

Confira se o contribuinte está mesmo cadastrado.

### Certificado digital não encontrado, inválido e suas variações

Veja se definiu o perfil e o certificado digital correto.

### Contribuinte não esta cadastrado no CADESP

Veja se está cadastrado no CADESP. Em caso de e-CNPJ de fora do SP, utilize o e-CNPJ de uma filial de SP.

### CNPJ não encontrado ou inválido

Veja se o CNPJ é existente e válido.

### Não existe procuração para o CNPJ informado

Veja se definiu o perfil e o certificado digital correto. No caso dê acesso como contabilista, veja se a empresa o cadastrou no Sistema de Gestão e Retaguarda do SAT-CF-e.

### O texto digitado não confere com a imagem de segurança

Digite novamente o texto.

### Favor efetuar o acesso ao sistema com o Certificado Digital

O usuário tem cadastro no DEC, por isso deve acessar o sistema com o Certificado Digital e não por meio de Login e Senha.

### Na hora de selecionar seu CNPJ, não aparece nenhum CNPJ

Feche as janelas abertas e tente mais uma vez.

### Erro durante a operação! Contate o suporte

Como dito acima, contate o suporte.

### Esta página não pôde ser exibida

Feche as janelas abertas e tente mais uma vez.

### Dígito verificador do número de série inválido

Veja se digitou o número corretamente, caso esteja certo, entre em contato com o fabricante do SAT.

### Este equipamento está vinculado a outro contribuinte. Deseja prosseguir?

Veja se o número de série está certo, se estiver, prossiga assim mesmo.

### Situação inválida para vinculação do equipamento

Veja se o número de série está certo.

### Número de série inexistente

Verificar o número digitado.  
Caso o número estiver certo, entrar em contato com o fabricante ou revendedor do SAT para verificar.

### O preenchimento dos seguintes campos é obrigatório

Preencha o campo informado.  
**Obs:** Se for o número de série, lembre-se de clicar no "+".

### A versão do software básico do equipamento está fora da data de vigência do software

Entre em contato com o fabricante do SAT.

### Por favor, preencha o campo e-mail com um e-mail válido

Veja se o e-mail informado está correto.

### O modelo / versão do software básico do equipamento não está autorizado para uso em São Paulo

Entre em contato com o fabricante do SAT.

### Contribuinte com ocorrência Atividade pré-operacional

Veja a situação no CADESP.

### O modelo do equipamento está fora do período de vigência

Confira o número digitado. Se estiver, entre em contato com o fabricante do SAT para verificar.

### O equipamento já está vinculado ao contribuinte logado. Deseja prosseguir?

Confira o número digitado. Se estiver, pode prosseguir.

### Contribuinte inativo no CADESP

Veja a situação no CADESP.

### O equipamento não pode ser vinculado pois já foi desativado pelo contribuinte logado

Confira o número digitado.  
Se estiver certo, lembre-se que uma vez desativado, o SAT não pode ser reativado pelo mesmo estabelecimento.

### Quer certificado digital com desconto? [Clique aqui][48]

Veja mais sobre [emissão de nota fiscal][49]  
[Crie uma conta em nossa plataforma gratuitamente][50]


[1]: #Como%5Ffazer%5Fa%5Fativacao%5Fdo%5FSAT%5Fno%5FSistema%5Fde%5FGestao%5Fe%5FRetaguarda%5Fdo%5FSAT-CF-e%5Fem%5FSao%5FPaulo
[2]: #Preparando-se%5Fpara%5Fativar%5Fo%5FSAT%5Fnota%5Ffiscal
[3]: #1%5F-%5FVoce%5Fprecisa%5Fter%5Fum%5FAplicativo%5FComercial%5Fadequado
[4]: #2%5F-%5FConexao%5Fonline
[5]: #3%5F-%5FContar%5Fcom%5Fo%5Fequipamento%5FSAT%5Fnota%5Ffiscal
[6]: #4%5F-%5FUm%5Fcomputador%5Fcom%5Fentrada%5FUSB
[7]: #5%5F-%5FImpressora
[8]: #Passo%5Fa%5Fpasso%5Fpara%5Fativar%5Fo%5FSAT%5Fnota%5Ffiscal%5Fao%5FSistema%5Fde%5FGestao%5Fe%5FRetaguarda%5Fdo%5FSAT-CF-e%5FSP
[9]: #1%5F-%5FAssociar%5Fseu%5Fequipamento%5FSAT%5Fao%5FCNPJ%5Fda%5Femprersa
[10]: #2%5F-%5FAtive%5Fo%5FSAT%5Fcom%5Fajuda%5Fdas%5Finstrucoes%5Fdo%5Ffabricante
[11]: #3%5F-%5FVincule%5Fo%5FAplicativo%5FComercial%5Fao%5FSAT
[12]: #Com%5Fsaber%5Fse%5Ftudo%5Fcorreu%5Fbem
[13]: #O%5Fusuario%5Fnao%5Fpossui%5Fpermissoes%5Fde%5Facesso%5Fpara%5Fo%5Fperfil%5Fescolhido
[14]: #Usuario%5Fnao%5Ftem%5Fpermissao%5Fpara%5Facessar%5Fo%5Fsistema%5Fcom%5Fe-CPF%5FFavor%5Flogar%5Fcom%5Fe-CNPJ
[15]: #Usuario%5Fnao%5Ftem%5Fpermissao%5Fpara%5Facessar%5Fo%5Fsistema%5Fcom%5Fe-CNPJ%5FFavor%5Flogar%5Fcom%5Fe-CPF
[16]: #Contabilista%5Fnao%5Festa%5Fcadastrado%5Fno%5FCADESP
[17]: #Consulta%5Fa%5FReceita%5FFederal%5Ftemporariamente%5Findisponivel%5FPor%5Ffavor%5Ftente%5Fnovamente%5Fmais%5Ftarde%5Fou%5FConsulta%5Fao%5FCADESP%5Ftemporariamente%5Findisponivel%5FPor%5Ffavor%5Ftente%5Fnovamente%5Fmais%5Ftarde
[18]: #Nao%5Fexiste%5Fnenhuma%5Fprocuracao%5Fpara%5Fo%5Fusuario%5Flogado%5Fno%5Fsistema
[19]: #O%5Fcontribuinte%5Fnao%5Festa%5Fcadastrado%5Fno%5Fsistema
[20]: #Usuario%5Fnao%5Ftem%5Fpermissao%5Fde%5Facesso%5Fao%5Fsistema
[21]: #Certificado%5Fdigital%5Fnao%5Fencontrado%5Finvalido%5Fe%5Fsuas%5Fvariacoes
[22]: #Contribuinte%5Fnao%5Festa%5Fcadastrado%5Fno%5FCADESP
[23]: #CNPJ%5Fnao%5Fencontrado%5Fou%5Finvalido
[24]: #Nao%5Fexiste%5Fprocuracao%5Fpara%5Fo%5FCNPJ%5Finformado
[25]: #O%5Ftexto%5Fdigitado%5Fnao%5Fconfere%5Fcom%5Fa%5Fimagem%5Fde%5Fseguranca
[26]: #Favor%5Fefetuar%5Fo%5Facesso%5Fao%5Fsistema%5Fcom%5Fo%5FCertificado%5FDigital
[27]: #Na%5Fhora%5Fde%5Fselecionar%5Fseu%5FCNPJ%5Fnao%5Faparece%5Fnenhum%5FCNPJ
[28]: #Erro%5Fdurante%5Fa%5Foperacao%5FContate%5Fo%5Fsuporte
[29]: #Esta%5Fpagina%5Fnao%5Fpode%5Fser%5Fexibida
[30]: #Digito%5Fverificador%5Fdo%5Fnumero%5Fde%5Fserie%5Finvalido
[31]: #Este%5Fequipamento%5Festa%5Fvinculado%5Fa%5Foutro%5Fcontribuinte%5FDeseja%5Fprosseguir
[32]: #Situacao%5Finvalida%5Fpara%5Fvinculacao%5Fdo%5Fequipamento
[33]: #Numero%5Fde%5Fserie%5Finexistente
[34]: #O%5Fpreenchimento%5Fdos%5Fseguintes%5Fcampos%5Fe%5Fobrigatorio
[35]: #A%5Fversao%5Fdo%5Fsoftware%5Fbasico%5Fdo%5Fequipamento%5Festa%5Ffora%5Fda%5Fdata%5Fde%5Fvigencia%5Fdo%5Fsoftware
[36]: #Por%5Ffavor%5Fpreencha%5Fo%5Fcampo%5Fe-mail%5Fcom%5Fum%5Fe-mail%5Fvalido
[37]: #O%5Fmodelo%5Fversao%5Fdo%5Fsoftware%5Fbasico%5Fdo%5Fequipamento%5Fnao%5Festa%5Fautorizado%5Fpara%5Fuso%5Fem%5FSao%5FPaulo
[38]: #Contribuinte%5Fcom%5Focorrencia%5FAtividade%5Fpre-operacional
[39]: #O%5Fmodelo%5Fdo%5Fequipamento%5Festa%5Ffora%5Fdo%5Fperiodo%5Fde%5Fvigencia
[40]: #O%5Fequipamento%5Fja%5Festa%5Fvinculado%5Fao%5Fcontribuinte%5Flogado%5FDeseja%5Fprosseguir
[41]: #Contribuinte%5Finativo%5Fno%5FCADESP
[42]: #O%5Fequipamento%5Fnao%5Fpode%5Fser%5Fvinculado%5Fpois%5Fja%5Ffoi%5Fdesativado%5Fpelo%5Fcontribuinte%5Flogado
[43]: #Quer%5Fcertificado%5Fdigital%5Fcom%5Fdesconto%5FClique%5Faqui
[44]: https://nfe.io/blog/financeiro/o-que-e-automacao-processos/
[45]: http://www.fazenda.sp.gov.br/sat/
[46]: https://satsp.fazenda.sp.gov.br/COMSAT/Account/LoginSSL.aspx?ReturnUrl=%2fCOMSAT%2f
[47]: https://satsp.fazenda.sp.gov.br/COMSAT/
[48]: https://p.nfe.io/pt-br/certificado-digital-20off
[49]: https://nfe.io/produtos/
[50]: https://nfe.io/contato/

---

## Quais são os códigos das unidades federativas do Brasil

Source: https://nfe.io/docs/duvidas-frequentes/codigos-unidades-federativas/index.md

# Quais são os códigos das unidades federativas para usar na emissão de notas fiscais e outros documentos?

Na hora de emitir documentos como CT-e, [NFC-e][3], [NF-e][3], MDF-e e CF-e e preencher outros formulários oficiais, é necessário usar o código corretos das unidades federativas do Brasil, isto é, dos estados e do Distrito Federal.

Não sabe quais são os códigos dessas unidades federativas?

Estão aqui, confira e use quando precisar:

## Códigos das Unidades Federativas do Brasil:

| Estado              | Sigla | Código |
| ------------------- | ----- | ------ |
| Rondônia            | RO    | 11     |
| Acre                | AC    | 12     |
| Amazonas            | AM    | 13     |
| Pará                | PA    | 15     |
| Amapá               | AP    | 16     |
| Tocantis            | TO    | 17     |
| Maranhão            | MA    | 21     |
| Piauí               | PI    | 22     |
| Ceará               | CE    | 23     |
| Rio Grande do Norte | RN    | 24     |
| Paraíba             | PB    | 25     |
| Pernambuco          | PE    | 26     |
| Alagoas             | AL    | 27     |
| Sergipe             | SE    | 28     |
| Bahia               | BA    | 29     |
| Minas Gerais        | MG    | 31     |
| Espírito Santo      | ES    | 32     |
| Rio de Janeiro      | RJ    | 33     |
| São Paulo           | SP    | 35     |
| Paraná              | PR    | 41     |
| Santa Catarina      | SC    | 42     |
| Rio Grande do Sul   | RS    | 43     |
| Mato Grosso do Sul  | MS    | 50     |
| Mato Grosso         | MT    | 51     |
| Goiás               | GO    | 52     |
| Distrito Federal    | DF    | 53     |

Pronto, agora vai ficar muito mais fácil preencher formulários em sites oficiais.

Leia também: [Qual código de serviço devo utilizar?][4]


[1]: #Quais%5Fsao%5Fos%5Fcodigos%5Fdas%5Funidades%5Ffederativas%5Fpara%5Fusar%5Fna%5Femissao%5Fde%5Fnotas%5Ffiscais%5Fe%5Foutros%5Fdocumentos
[2]: #Codigos%5Fdas%5FUnidades%5FFederativas%5Fdo%5FBrasil
[3]: https://nfe.io/produtos/
[4]: https://nfe.io/docs/duvidas-frequentes/qual-codigo-servico-utilizar/

---

## Como Alterar o Método de Pagamento da sua Assinatura

Source: https://nfe.io/docs/duvidas-frequentes/como-alterar-o-metodo-de-pagamento-da-sua-assinatura/index.md

# Como Alterar o Método de Pagamento da sua Assinatura

Ao acessar a sua conta da NFE.io é preciso selecionar a opção de “Conta” no menu de opções na barra superior.  
![](https://nfe.io/docs/static/docs/chrome_3UMJ2cm6e0-300x42.png)

Em seguida ao final desta tela deve ser selecionada a opção de “Métodos de Pagamento”  
![](https://nfe.io/docs/static/docs/chrome_8Xs0kfCfS2-1024x474.png)

Após selecionar a opção acima, você será direcionado para a tela onde visualiza todos os meios de pagamento salvos na sua conta. Através dessa tela é possível Adicionar ou Excluir uma forma de pagamento já existente.

![](https://nfe.io/docs/static/docs/chrome_cpU5kS3dlt-1024x185.png)

![](https://nfe.io/docs/static/docs/chrome_PUZa9K6xBo.png)

#### Veja o passo a passo no vídeo abaixo


[1]: #Como%5FAlterar%5Fo%5FMetodo%5Fde%5FPagamento%5Fda%5Fsua%5FAssinatura
[2]: #Veja%5Fo%5Fpasso%5Fa%5Fpasso%5Fno%5Fvideo%5Fabaixo

---

## Como alterar o número de RPS

Source: https://nfe.io/docs/duvidas-frequentes/como-alterar-o-numero-de-rps/index.md

# Como alterar o número de RPS
Em alguns casos é necessário alterar o número de RPS para que a nota possa ser emitida com sucesso.

Para realizar este procedimento basta seguir as instruções:

1 - Passe o cursor em cima da empresa e clique em **"Alterar"**

![](https://nfe.io/docs/app/uploads/2020/09/imagem-11.png)

2 - Na tela seguinte clique na barra de **"Dados Fiscais"**

![](https://nfe.io/docs/app/uploads/2020/09/imagem-10.png)

3 - Dentro desse campo terá a opção de alterar o **"Número do RPS"**

![](https://nfe.io/docs/app/uploads/2020/09/imagem-12.png)

4 - Após realizar a alteração é só clicar em salvar no final da tela e pedir a re-emissão da nota

---

## Como Ativar e Desativar Notificações por E-mail

Source: https://nfe.io/docs/duvidas-frequentes/como-ativar-e-desativar-notificacoes-por-e-mail/index.md

# Como Ativar e Desativar Notificações por E-mail

Primeiro demonstraremos quais são os IDs para realizar a ativação e desativação das notificações através do link abaixo, onde você será direcionado para a nossa documentação:

[https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/][1]

Após acessar o link você irá rolar a tela para baixo até localizar o botão de “Authorize”:

![](https://nfe.io/docs/static/docs/chrome_jYQMkHOyKL-1024x283.png)

Em “Authorize” você irá inserir a sua chave de apiKey para realizar o processo de autenticação da sua conta. Em seguida, após realizar a autenticação da sua conta, desça mais um pouco a tela até localizar a URL de “EventTypes” e clique em cima do endpoint para expandi-lo.

![](https://nfe.io/docs/static/docs/chrome_Dg6tNkSiYb-1024x119.png)

![](https://nfe.io/docs/static/docs/chrome_CW7cR1ckjd-1024x375.png)

Seleciona o botão de “Try it out”, depois o botão “Execute”:  
![](https://nfe.io/docs/static/docs/chrome_1oEa4BxMFs-1024x135.png)

Após selecionar o botão de “Execute” a API irá listar todos os eventos da sua conta que por regra já estarão ativos:

Para realizar a ativação ou desativação das notificações de e-mail para os seus tomadores, será necessário anotar dois IDs relacionados às notificações, e são eles:

![](https://nfe.io/docs/static/docs/chrome_gNaIDLW03V.png)

Agora que já sabemos quais são os IDs que correspondem às Notas Emitidas e Notas Canceladas, vamos ao próximo passo.

Rolando a sua tela um pouco mais para cima, iremos encontrar as URLs de “CompaniesNotifications”.

Selecione a URL de indicada como “POST” para expandi-la e em seguida selecione o botão “Try it out”:

![](https://nfe.io/docs/static/docs/chrome_dxAwuLg6cn-1024x273.png)

No campo setado como “ID da empresa”, informe o ID da sua empresa.

Em “Dados de Notificações”, você irá ativar ou desativar as notificações.

Exemplo:

Para desativar uma notificação o json ficará com o seguinte formato:

![](https://nfe.io/docs/static/docs/chrome_k3RNQwzg2h-1024x696.png)

Feito os passos acima, basta selecionar o botão “Execute” e as notificações que os tomadores recebem estarão ativadas. Para desativar a notificação é só mudar o status de “Active” para “Inactive” e selecionar o botão “Execute”.

![](https://nfe.io/docs/static/docs/chrome_9xJwxd6JKr-1024x79.png)

Caso considere necessário validar as notificações que você modificou basta listar as notificações de uma empresa utilizando a URL abaixo e informando o ID da sua Empresa:

![](https://nfe.io/docs/static/docs/chrome_rVqENgJI5P-1024x502.png)

A URL listará todas as notificações que foram ativadas, ou desativadas por você. Ressaltando que todas as notificações já estão ativadas por padrão, então na chamada acima só serão exibidas as notificações que você personalizou manualmente.


[1]: https://nfe.io/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/

---

## Como cadastrar uma empresa no Emissor Nacional?

Source: https://nfe.io/docs/duvidas-frequentes/como-cadastrar-uma-empresa-no-emissor-nacional/index.md

# Como cadastrar uma empresa no Emissor Nacional?

Após a etapa de cadastro de usuário no [Emissor Nacional][1], a próxima etapa para poder emitir uma nota fiscal por meio dessa plataforma é o cadastro da empresa que irá prestar o serviço e que irá emitir as notas.

A primeira etapa é a criação de um usuário e essa ação é demonstrada nesse [link][2]. Após essa etapa, é o momento de cadastrar uma empresa e esse segundo momento é demonstrado abaixo.

1. Acesse a [página de login do Emissor Nacional][3] e informe as credenciais que você cadastrou na etapa de [cadastro de usuário][2].

[![acesso](https://nfe.io/docs/app/uploads/2023/09/opera_2H10Nw6l5i.png "acesso")][4]

1. No seu primeiro acesso, será necessário acessar as configurações. Isso pode ser feito clicando em qualquer um dos símbolos destacados em vermelho mostrados na imagem abaixo.

[![](https://nfe.io/docs/static/docs/opera_XUIMocFEhV.png)][5]

1. Ao entrar nas configurações, preencha os campos com email e telefone que serão utilizados na geração da NFSe. Selecione também a opção de não informar valores aproximados dos tributos.

[![](https://nfe.io/docs/static/docs/opera_SsPfzk8pid.png)][6]

1. Agora é necessário você cadastrar um imposto que se relacione ao seu tipo de serviço. Na primeira imagem abaixo, clique na estrela. Na sequência, clique na opção de cadastrar o novo serviço.

[![](https://nfe.io/docs/static/docs/opera_NBF0zw89KA.png)][7]

[![](https://nfe.io/docs/static/docs/opera_XrX06D6omP.png)][8]

1. Nessa etapa selecione os dados relacionados ao seu imposto. Após a seleção, sua empresa já está habilitada para emissões na NFe.io!

[1]: https://www.gov.br/nfse/pt-br
[2]: https://nfe.io/docs/duvidas-frequentes/credenciamento-emissor-nacional/
[3]: https://www.nfse.gov.br/EmissorNacional/Login
[4]: https://nfe.io/docs/app/uploads/2023/09/opera%5F2H10Nw6l5i.png
[5]: https://nfe.io/docs/app/uploads/2023/09/opera%5FXUIMocFEhV.png
[6]: https://nfe.io/docs/app/uploads/2023/09/opera%5FSsPfzk8pid.png
[7]: https://nfe.io/docs/app/uploads/2023/09/opera%5FNBF0zw89KA.png
[8]: https://nfe.io/docs/app/uploads/2023/09/opera%5FXrX06D6omP.png

---

## Aprenda como consultar um CNPJ na Receita Federal

Source: https://nfe.io/docs/duvidas-frequentes/como-consultar-cnpj-receita-federal/index.md

# Quer consultar um CNPJ na Receita Federal? Veja o passo a passo!

Consultar um CNPJ na Receita Federal é uma **prática bastante comum para empresas que desejam verificar a situação de novos parceiros**, como clientes e fornecedores. 

A consulta **permite verificar a regularidade cadastral e fiscal** de outra empresa **antes de realizar transações comerciais**.

Então, se você não sabe como consultar a situação de um Cadastro Nacional de Pessoa Jurídica, este passo a passo vai tirar todas as suas dúvidas..

## O que é o CNPJ e qual é a sua importância?

O Cadastro Nacional de Pessoa Jurídica (CNPJ) é um **número único atribuído a todas as empresas e entidades no Brasil**. A Receita Federal o utiliza para identificar as empresas oficialmente e **acompanhar suas obrigações fiscais**.

Além disso, o CNPJ **serve para que empresas realizem transações financeiras, emitam notas fiscais, contratem funcionários** e, em muitos casos, **façam negócios com outros empreendimentos** — o que torna a ferramenta de **busca de CNPJ** ainda mais importante.

## Como funciona a consulta de CNPJ na Receita Federal?

Consultar um CNPJ na Receita Federal é muito simples. Para realizar essa busca, **você precisa ter o número da empresa** que deseja verificar. Caso não tenha o número em mãos, você pode pesquisar diretamente no [site da Receita Federal][22].

### Passo a passo para consultar um CNPJ na Receita Federal

#### 1\. Acesse o site da Receita Federal

**Acesse o site oficial do órgão** pelo link específico para a consulta de CNPJ na [Receita Federal][23].

#### 2\. Insira o número do CNPJ

**Insira o número do CNPJ** da empresa que deseja consultar no campo de pesquisa.

#### 3\. Prove que você não é um robô

Clique na opção “Não sou um robô” para confirmar que quem consulta é uma pessoa real, e depois em “Consultar”.

#### 4\. Veja as informações do CNPJ

**Você visualizará a ficha cadastral da empresa**, que inclui informações como a razão social, nome fantasia, situação cadastral e muito mais.

## Dicas para verificar informações do CNPJ

Ao consultar um CNPJ, verifique alguns dados relevantes para garantir a veracidade e regularidade da empresa:

* **razão social**: nome oficial registrado da empresa;
* **situação cadastral**: indica se a empresa está ativa, inapta, suspensa ou baixada;
* **endereço**: endereço físico da sede da empresa;
* **atividade econômica**: as atividades que a empresa está autorizada a desenvolver.

Com essas informações em mãos, **você consegue verificar (e validar) a idoneidade de novos parceiros** comerciais facilmente.

## Certidão federal CNPJ: o que é e como obter?

A Receita emite a certidão federal CNPJ para atestar a regularidade de uma empresa perante o fisco. O documento é muito importante quando você precisa comprovar a situação fiscal e cadastral de uma empresa, ou mesmo diante de processos licitatórios ou de transações financeiras em geral.

Você pode gerar uma **certidão federal negativa ou positiva** durante o processo de consulta do CNPJ, o que **indica a situação perante a Receita Federal**.

**Mas atenção**: o status da empresa no Cadastro Nacional de Pessoa Jurídica **define a certidão gerada**. Entenda o que esses resultados significam.

### Certidão positiva

Uma **certidão positiva é emitida quando a empresa tem pendências ou irregularidades fiscais**, como débitos com a Receita Federal. Por exemplo: a empresa pode ter impostos não pagos ou outras obrigações não cumpridas.

Assim, mesmo que a empresa não esteja irregular em termos de atividade, tem pendências que precisam de ajustes.

Nesse caso, a certidão pode ser chamada de “certidão positiva com efeito de negativa” — e ocorre em casos nos quais a empresa garante o pagamento ou regularização das pendências, mas continua no processo de atualização no sistema.

### Certidão negativa

Por outro lado, a **certidão negativa é emitida quando a empresa está em plena conformidade com suas obrigações fiscais**, sem pendências ou débitos registrados junto à Receita Federal.

Nestes casos, a empresa não tem nenhum tipo de dívida ativa ou irregularidade registrada, e está regularizada perante o fisco.

## Consultas de CNPJ grátis e outros serviços

Busca outras formas de consultar dados de CNPJ on-line? O [Consulta.Guru tem uma ferramenta gratuita][24]! Além disso, você pode [gerar um CNPJ][25] válido para fazer testes em aplicativos ou, ainda, [verificar se um CNPJ em uso é válido][26].

### Como consultar um CNPJ na Receita Federal?

Acesse o site da Receita Federal, insira o número do CNPJ e clique em “Consultar”.

### Quais dados são necessários para verificar um CNPJ?

Apenas o número do CNPJ é necessário para realizar a consulta.

### O que é a situação cadastral no CNPJ?

A situação cadastral indica se a empresa está ativa, inapta, suspensa ou baixada.

### Como consultar um CNPJ na Receita Federal?

1. acesse o site da Receita Federal;
2. encontre a seção “Consulta CNPJ”;
3. insira o número do CNPJ;
4. clique em “Consultar” e visualize as informações.

### Por que é importante verificar o CNPJ de uma empresa?

Verificar o CNPJ garante que a empresa esteja regularizada e apta para realizar transações.

### O que significa CNPJ inapto ou suspenso?

Significa que a empresa não está em conformidade com as obrigações fiscais e pode estar impedida de operar legalmente.

### Como emitir a certidão negativa do CNPJ?

A certidão negativa pode ser emitida no próprio site da Receita Federal após a consulta do CNPJ.

## Veja também:

[Consulta de Pessoa Jurídica][27]  
[Consulta a base da Receita Federal em massa via API][28]


[1]: #Quer%5Fconsultar%5Fum%5FCNPJ%5Fna%5FReceita%5FFederal%5FVeja%5Fo%5Fpasso%5Fa%5Fpasso
[2]: #O%5Fque%5Fe%5Fo%5FCNPJ%5Fe%5Fqual%5Fe%5Fa%5Fsua%5Fimportancia
[3]: #Como%5Ffunciona%5Fa%5Fconsulta%5Fde%5FCNPJ%5Fna%5FReceita%5FFederal
[4]: #Passo%5Fa%5Fpasso%5Fpara%5Fconsultar%5Fum%5FCNPJ%5Fna%5FReceita%5FFederal
[5]: #1%5FAcesse%5Fo%5Fsite%5Fda%5FReceita%5FFederal
[6]: #2%5FInsira%5Fo%5Fnumero%5Fdo%5FCNPJ
[7]: #3%5FProve%5Fque%5Fvoce%5Fnao%5Fe%5Fum%5Frobo
[8]: #4%5FVeja%5Fas%5Finformacoes%5Fdo%5FCNPJ
[9]: #Dicas%5Fpara%5Fverificar%5Finformacoes%5Fdo%5FCNPJ
[10]: #Certidao%5Ffederal%5FCNPJ%5Fo%5Fque%5Fe%5Fe%5Fcomo%5Fobter
[11]: #Certidao%5Fpositiva
[12]: #Certidao%5Fnegativa
[13]: #Consultas%5Fde%5FCNPJ%5Fgratis%5Fe%5Foutros%5Fservicos
[14]: #Como%5Fconsultar%5Fum%5FCNPJ%5Fna%5FReceita%5FFederal
[15]: #Quais%5Fdados%5Fsao%5Fnecessarios%5Fpara%5Fverificar%5Fum%5FCNPJ
[16]: #O%5Fque%5Fe%5Fa%5Fsituacao%5Fcadastral%5Fno%5FCNPJ
[17]: #Como%5Fconsultar%5Fum%5FCNPJ%5Fna%5FReceita%5FFederal-2
[18]: #Por%5Fque%5Fe%5Fimportante%5Fverificar%5Fo%5FCNPJ%5Fde%5Fuma%5Fempresa
[19]: #O%5Fque%5Fsignifica%5FCNPJ%5Finapto%5Fou%5Fsuspenso
[20]: #Como%5Femitir%5Fa%5Fcertidao%5Fnegativa%5Fdo%5FCNPJ
[21]: #Veja%5Ftambem
[22]: https://www.gov.br/receitafederal/pt-br
[23]: http://servicos.receita.fazenda.gov.br/Servicos/cnpjreva/cnpjreva%5Fsolicitacao.asp
[24]: https://consulta.guru/consultar-cnpj-gratis
[25]: https://consulta.guru/gerador-cnpj-gratis
[26]: https://consulta.guru/validar-cnpj
[27]: https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-cnpj-v1/
[28]: https://nfe.io/consulta-de-dados/

---

## Passo a passo: de como consultar EPECs pendentes

Source: https://nfe.io/docs/duvidas-frequentes/como-consultar-epec-pendente/index.md

# EPECs pendentes? Veja passo a paso de como consultar

Se você tem deuvidas de como consultar uma EPECs pendentes de conciliação, fique tranquilo, temos a solucão para você!

## Passo a passo de como consultar EPEC pendente

Antes de iniciar este passo a passo, é importante que você saiba que para verificar uma EPEC pendente é preciso que seu certificado digital esteja devidamente instalado em seu nevegador.

Estes posts podem ajudar você a fazer isso:

* [Guia definitivo para exportar seu certificado digital no Windows][7]
* [Guia definitivo para exportar seu certificado digital no Mac OS][8]
* [Você precisa de um certificado digital com desconto?][9]

## Passo a passo para consultar EPEC pendente

### 1 - Acesse o portal do SEFAZ nacional

Para isso, basta clicar neste link: [http://www.nfe.fazenda.gov.br/portal/principal.aspx][10]

### 2 - Selecione o serviço Consultar EPEC Pendente de Conciliação

Para isso, no menu "Serviços", selecione a opção "Conultar EPEC Pendente de conciliacão.

### 3 - Selecione seu Cerificado Digital

Em seguida, você deve confirmar se o certificado digital apresentado na tela é o seu, clicando no botão "OK".

Processo finalizado! As EPECs pendentes aparecerão para você em uma lista com CNPJ, numeração, dias de atraso e outros dados.


[1]: #EPECs%5Fpendentes%5FVeja%5Fpasso%5Fa%5Fpaso%5Fde%5Fcomo%5Fconsultar
[2]: #Passo%5Fa%5Fpasso%5Fde%5Fcomo%5Fconsultar%5FEPEC%5Fpendente
[3]: #Passo%5Fa%5Fpasso%5Fpara%5Fconsultar%5FEPEC%5Fpendente
[4]: #1%5F-%5FAcesse%5Fo%5Fportal%5Fdo%5FSEFAZ%5Fnacional
[5]: #2%5F-%5FSelecione%5Fo%5Fservico%5FConsultar%5FEPEC%5FPendente%5Fde%5FConciliacao
[6]: #3%5F-%5FSelecione%5Fseu%5FCerificado%5FDigital
[7]: /documentacao/certificado-digital/guia-para-exportar-certificado-windows#Guia%5Fde%5FExportacao%5Fdo%5FCertificado%5FDigital%5FA1
[8]: /documentacao/certificado-digital/guia-para-exportar-certificado-mac-os
[9]: https://p.nfe.io/pt-br/certificado-digital-20off
[10]: http://www.nfe.fazenda.gov.br/portal/principal.aspx

---

## Passo a passo: como consultar inscrição estadual MEI

Source: https://nfe.io/docs/duvidas-frequentes/como-consultar-inscricao-estadual-sintegra/index.md

# Você sabe como consultar uma inscrição estadual MEI?

Consultar uma inscrição estadual - IE - é mais fácil do que você imagina.

Para isso, você deve consultar o SINTEGRA, Sistema Integrado de Informações sobre Operações Interestaduais com Mercadorias e Serviços.

## Veja nosso passo a passo de como consultar inscrição estadual no SINTEGRA:

### 1 - Acessse o site SINTEGRA

O primeiro passo é acessar o endereço do site SINTEGRA: [http://www.sintegra.gov.br/][7]

### 2 - Selecione seu estado

Ao acessar o site do SINTEGRA, vai aparecer um mapa do Brasil. Você deve clicar na unidade federativa correspondente àquela em que a inscrição estadual que você procura está cadastrada.

### 3 - Defina que dado será usado para a consulta

Você será direcionado para uma página onde escolherá que dado usar na busca da inscrição estatual, o CCE (Cadastro de Contribuinte Estadual, outro nome para a inscrição estadual) , o CNPJ ou o CPF.

Selecione o que vai usar e clique no botão "consultar".

### 4 - Pronto, os dados serão exibidos!

Depois de clicar em "consultar", você verá uma ficha com todas as informações importantes sobre a inscrição estadual pesquisada.

Leia também: [Consulta de Pessoa Física][8]


[1]: #Voce%5Fsabe%5Fcomo%5Fconsultar%5Fuma%5Finscricao%5Festadual%5FMEI
[2]: #Veja%5Fnosso%5Fpasso%5Fa%5Fpasso%5Fde%5Fcomo%5Fconsultar%5Finscricao%5Festadual%5Fno%5FSINTEGRA
[3]: #1%5F-%5FAcessse%5Fo%5Fsite%5FSINTEGRA
[4]: #2%5F-%5FSelecione%5Fseu%5Festado
[5]: #3%5F-%5FDefina%5Fque%5Fdado%5Fsera%5Fusado%5Fpara%5Fa%5Fconsulta
[6]: #4%5F-%5FPronto%5Fos%5Fdados%5Fserao%5Fexibidos
[7]: http://www.sintegra.gov.br/
[8]: https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-cpf-v1/

---

## Como consultar o Regime Tributário de uma empresa?

Source: https://nfe.io/docs/duvidas-frequentes/como-consultar-regime-tributario-empresa/index.md

# Quer saber como consultar o Regime Tributário de uma empresa?

Existem duas opções: você pode usar o SINTEGRA ou o Cadastro Geral de Contribuintes para consultar o Regime Tributário.

Ambos fornecerão as informações que você precisa sobre regime tributário, também chamado de regime de recolhimento ou de regime de apuração.

## Como realizar a consulta de regime tributário usando o SINTEGRA

Isso varia de estado pra estado.  
Por meio do CNPJ da empresa, em alguns estados aparecem as informações completas do contribuinte.

Porém, no SINTEGRA de outros estados, é necessário clicar em botões específicos.

Assim, se você conseguir a informação sobre o regime tributário logo de cara, deu sorte!

Se não, terá que procurar um botão clicável, em destaque, para acessar essa informação ou dados mais completos.

Possivelmente você será encaminhado para a página com as informações completas do contribuinte, incluindo o regime tributário da empresa.

## Fazendo a consulta pelo CCC - Cadastro Centralizado de Contribuintes

Para fazer a consulta do regime tributário pelo Cadastro Centralizado de Contribuintes, ao acessar o site, você pode clicar no CNPJ ou na Inscrição Estadual da empresa.

Assim que fizer isso, você verá a tela com todas as informações desse contribuinte, incluisve o regime tributário usado por ele.

Leia também: [Lucro Real, Lucro Presumido ou Simples Nacional? Como escolher o regime tributário para sua empresa][4]


[1]: #Quer%5Fsaber%5Fcomo%5Fconsultar%5Fo%5FRegime%5FTributario%5Fde%5Fuma%5Fempresa
[2]: #Como%5Frealizar%5Fa%5Fconsulta%5Fde%5Fregime%5Ftributario%5Fusando%5Fo%5FSINTEGRA
[3]: #Fazendo%5Fa%5Fconsulta%5Fpelo%5FCCC%5F-%5FCadastro%5FCentralizado%5Fde%5FContribuintes
[4]: https://nfe.io/blog/financeiro/como-escolher-regime-tributario-empresa/

---

## Como consultar o Regime Tributário no site do SINTEGRA SP?

Source: https://nfe.io/docs/duvidas-frequentes/como-consultar-o-regime-tributario-no-site-do-sintegra/index.md

# Como consultar o Regime Tributário de uma empresa?

Nesse artigo vamos mostrar passo a passo como consultar o Regime Tributário de uma empresa.  
O Regime Tributário, Regime de Apuração, ou Regime de Recolhimento pode ser consultado tanto no SINTEGRA quanto no Cadastro Centralizado de Contribuintes. 

## Comece pela consulta do CNPJ

O primeiro passo é consultar o CNPJ ou Inscrição Estadual nesses Portais e para saber como realizar essa consulta, veja os artigos a seguir:

[Você sabe como consultar uma inscrição estadual no SINTEGRA?][11]  
[Fazendo a consulta pelo CCC - Cadastro Centralizado de Contribuintes][12]

## Como consultar no site no SINTEGRA?

### Passo 1

Acesse o site do [SINTEGRA clicando aqui][13]

Selecione o estado que a empresa se encontra:  
![pagina sintegra](https://nfe.io/docs/static/docs/pagina_sintegra.png)

### Passo 2

1. Na caixa de seleção mude para a opção CNPJ
2. Preencha com o número que deseja consultar
3. Marque não sou um robô
4. Clique em Consultar  
![selecione o estado site sintegra](https://nfe.io/docs/static/docs/sintegra-passo-2.png)

### Passo 3

Faça a análise das informações do cadastro.  
![](https://nfe.io/docs/static/docs/informacoes-de-retorno-do-sintegra.png)

### As informações na consulta são:

* Informações completas do Contribuinte,
* Regime Tributário,
* Numero da Inscrição Estadual
* Nome Empresarial
* CNAEs
* Situação Cadastral
* Dados do Endereço:

### Veja a diferença da informação para o estado de Minas Gerais

![sintegra minas gerais](https://nfe.io/docs/static/docs/informacoes-de-retorno-do-sintegra.png)

> Cada estado tem o seu formato de apresentar as informações
> 
> No Cadastro Centralizado de Contribuintes, sempre será necessário expandir as informações completas do contribuinte. 

### Erro na consulta do Regime Tributário

Caso você vá fazer a consulta do Regime Tributário e apareça a mensagem **"Não existem registros que atendem ao critério de filtro definido."** Significa que o CNPJ que você está tentando consultar não possui Inscrição Estadual.

![erro no sintegra](https://nfe.io/docs/static/docs/mensagem-de-erro.png)

### Quer automatizar a consulta do Regime Tributário?

A [NFE.io][14] tem a solução perfeita para você!  
Nossas [API's de consulta][15] de Regime Tributário faz todo o serviço para sua empresa de forma automatizada, com rapidez e baixa latência.  
[Faça o teste gratuitamente.][16]  
[Converse conosco para saber mais.][17]


[1]: #Como%5Fconsultar%5Fo%5FRegime%5FTributario%5Fde%5Fuma%5Fempresa
[2]: #Comece%5Fpela%5Fconsulta%5Fdo%5FCNPJ
[3]: #Como%5Fconsultar%5Fno%5Fsite%5Fno%5FSINTEGRA
[4]: #Passo%5F1
[5]: #Passo%5F2
[6]: #Passo%5F3
[7]: #As%5Finformacoes%5Fna%5Fconsulta%5Fsao
[8]: #Veja%5Fa%5Fdiferenca%5Fda%5Finformacao%5Fpara%5Fo%5Festado%5Fde%5FMinas%5FGerais
[9]: #Erro%5Fna%5Fconsulta%5Fdo%5FRegime%5FTributario
[10]: #Quer%5Fautomatizar%5Fa%5Fconsulta%5Fdo%5FRegime%5FTributario
[11]: https://nfe.io/docs/duvidas-frequentes/como-consultar-inscricao-estadual-sintegra/
[12]: https://nfe.io/docs/sem-categoria/como-consultar-regime-tributario-empresa/
[13]: http://www.sintegra.gov.br/
[14]: http://nfe.io
[15]: https://nfe.io/produtos/consulta-de-dados/
[16]: http://app.nfe.io
[17]: http://nfe.io/contato

---

## Baixar uma nota fiscal em XML: 5 passos práticos

Source: https://nfe.io/docs/duvidas-frequentes/como-fazer-download-do-xml-na-sefaz/index.md

# Baixar uma nota fiscal em XML: passo a passo

Você sabe como **baixar uma nota fiscal em XML** no portal da Secretaria da Fazenda (SEFAZ) do seu estado?

Independentemente de o documento se referir à nota fiscal de produto (NF-e), nota fiscal de serviço (NFS-e) ou nota fiscal do consumidor (NFC-e), aprenda aqui o passo a passo de como fazer o download desse arquivo em seu computador. Mas antes, entenda:

* O que é uma nota fiscal eletrônica?
* O que é arquivo XML?
* Qual a diferença entre o DANF-e e o XML da nota fiscal?

## O que é uma nota fiscal eletrônica?

A nota fiscal eletrônica é um documento fiscal digital que, além de substituir a versão em papel, registra operações da venda (produtos e serviços) e traz segurança, agilidade nos processos e um melhor controle fiscal por parte das autoridades tributárias. 

Tanto emissão como armazenamento da NF-e são eletrônicos, o que garante a validade jurídica por meio da assinatura digital do emitente e da autorização de uso pela SEFAZ do estado. 

## O que é arquivo XML?

O arquivo XML é a representação digital da NF-e e contém todas as informações necessárias sobre a transação, como:

* dados do emitente;
* do destinatário;
* produtos vendidos;
* impostos aplicáveis.

O XML é um formato padronizado que permite a automação e a integração de processos de negócios; por isso, é essencial para a emissão, transferência e consulta das notas fiscais.

## Qual é a diferença entre o DANF-e e o XML da Nota Fiscal?

A principal diferença entre os dois é que, enquanto o Documento Auxiliar da Nota Fiscal Eletrônica (DANF-e) é a versão impressa e resumida para uso prático, o XML é o arquivo digital completo com todas as informações detalhadas da Nota Fiscal.

Ambos são importantes para diferentes etapas do processo de emissão e registro de notas fiscais.

## Por que baixar o XML da SEFAZ?

Baixar o XML da NF-e é importante por várias razões, que incluem as listadas abaixo.

* **Auditorias**: frequentemente, o Fisco solicita o XML durante auditorias fiscais para comprovar transações.
* **Consultas**: permite que empresas consultem notas fiscais que emitiram e receberam.
* **Armazenamento**: a legislação exige que tanto o emitente quanto o destinatário mantenham esses arquivos por um período mínimo de 5 anos.
* **Compartilhamento com contadores**: facilita o trabalho contábil ao fornecer informações detalhadas sobre as transações realizadas.

Após considerar todas as motivações, veja a seguir como baixar uma nota fiscal em XML no portal da SEFAZ.

## Como baixar uma nota fiscal XML em 5 passos práticos?

Seja você um destinatário, emitente ou transportador, antes de descobrir como baixar uma nota fiscal em XML, é importante saber que é necessário ter uma autorização para essa operação. A concessão se dá por meio de um certificado digital.

Lembre-se de instalá-lo em seu navegador. Não sabe como fazer? Veja as orientações na sessão [Upload do Certificado Digital][17]. Caso não o tenha, pode obter um [Certificado Digital com desconto aqui][18]! Em seguida, siga os passos abaixo.

### 1\. Localize a chave de acesso:

Busque a chave de acesso (com 44 dígitos numéricos) na DANF-e impressa (geralmente está no topo do documento) ou no QR Code da nota. 

### 2\. Acesse o site do Portal Nacional ou SEFAZ estadual

Em seguida, entre no [Portal Nacional da NF-e][19] ou na SEFAZ estadual para baixar a NF-e de seu interesse.

### 3\. Prove que não é um robô

Digite o código numérico que aparecerá na imagem. Coloque a chave de acesso e, em seguida, clique no botão continuar.

### 4\. Clique em “download do documento”

Depois que o documento aparecer, clique no botão “download do documento”.

### 5\. Selecione seu certificado digital

Confirme a veracidade de seu certificado digital e clique em “OK” na janela que aparecerá. Pronto! Você acaba de aprender a baixar uma nota fiscal em XML em seu computador!

## Posso baixar o XML da NF-e somente com certificado digital?

Geralmente, para baixar uma nota fiscal em XML, é necessário ter tanto o certificado digital quanto a chave de acesso.

No entanto, algumas situações permitem o download do XML apenas com o certificado digital, tais como as que você conhece a seguir.

* **Plataformas de gestão fiscal**: algumas plataformas permitem a consulta e o download de notas fiscais ao utilizar apenas o certificado digital, desde que você seja o emitente ou destinatário da nota.  
Essas plataformas geralmente têm ferramentas para filtrar as notas por período, valor, entre outros critérios.
* **Consulta no portal da SEFAZ**: em alguns casos, os portais das SEFAZ dos estados liberam a consulta de notas fiscais somente com certificado digital, sem a necessidade da chave de acesso.

No entanto, as funcionalidades e informações disponíveis podem variar de um estado para outro.

* **Notas fiscais emitidas para o seu CNPJ**: se você é o destinatário da nota fiscal e tem o certificado digital, pode ser possível baixar o XML diretamente do portal da SEFAZ ou de plataformas de gestão fiscal.

Também, é possível identificar notas fiscais emitidas conta um determinado CNPJ, por meio de nosso serviço Radar de Notas Fiscais. Por meio de seu certificado digital, essa ferramenta busca no ambiente nacional de distribuição da SEFAZ as notas fiscais emitidas e que contenham seu CNPJ como um agente.

## Como realizar uma consulta do XML pela chave?

Como no processo de download, a consulta do XML da NF-e ocorre tanto pelo Portal Nacional da NF-e quanto pela SEFAZ estadual. Por meio dos dois caminhos, veja como buscar um arquivo pela chave.

### Portal Nacional da NF-e

* procure a opção “Consultar NF-e”;
* digite a chave de acesso;
* insira o código de verificação (captcha);
* clique em “consultar”.

### SEFAZ estadual

* entre no site da SEFAZ do seu estado;
* procure “Consulta de NF-e”;
* insira a chave de acesso;
* digite o código de verificação;
* faça a consulta da NF-e na Fazenda.

Já aqui na NFE.io, temos o produto **Consulta Básica**. Ao inserir a chave de acesso, você recebe tanto o XML quanto DANFE. Atente-se que, caso o destinatário da nota fiscal possua Inscrição Estadual, não conseguiremos fornecer as informações de solicitadas.

## É possível fazer o download da nota fiscal eletrônica sem a chave de acesso?

Baixar uma nota fiscal XML sem a chave de acesso é possível, mas exige um pouco mais de trabalho. A disponibilidade da funcionalidade varia conforme o estado emissor da nota, as informações que você tem e a plataforma que você utiliza para a consulta.

É importante lembrar que a consulta sem a chave de acesso pode ser mais complexa e demorada do que com a chave. Além disso, a privacidade e a segurança das informações podem ser limitadas. Se você não conseguir encontrar a nota fiscal, o ideal é entrar em contato com o emitente ou procurar um contador.

Utilizar plataformas especializadas e ter um certificado digital facilitam esse processo, mas é fundamental avaliar cada caso individualmente e buscar orientação de um profissional quando necessário.

Felizmente, na NFE.io, é possível fazer o download de NF-e sem essa alternativa de acesso. Além do serviço Radar de Notas fiscais (em que somente é necessária a Certificação Digital), temos também o produto Consulta Irrestrita.

Com esse serviço, você pode consultar qualquer nota fiscal no Brasil para qualquer destinatário, sem a necessidade de um certificado digital ou estar citado na nota. As informações são entregues em Json, DANFE e XML original.

Saiba mais sobre esse e outros produtos já citados, [clicando aqui][20]!


[1]: #Baixar%5Fuma%5Fnota%5Ffiscal%5Fem%5FXML%5Fpasso%5Fa%5Fpasso
[2]: #O%5Fque%5Fe%5Fuma%5Fnota%5Ffiscal%5Feletronica
[3]: #O%5Fque%5Fe%5Farquivo%5FXML
[4]: #Qual%5Fe%5Fa%5Fdiferenca%5Fentre%5Fo%5FDANF-e%5Fe%5Fo%5FXML%5Fda%5FNota%5FFiscal
[5]: #Por%5Fque%5Fbaixar%5Fo%5FXML%5Fda%5FSEFAZ
[6]: #Como%5Fbaixar%5Fuma%5Fnota%5Ffiscal%5FXML%5Fem%5F5%5Fpassos%5Fpraticos
[7]: #1%5FLocalize%5Fa%5Fchave%5Fde%5Facesso
[8]: #2%5FAcesse%5Fo%5Fsite%5Fdo%5FPortal%5FNacional%5Fou%5FSEFAZ%5Festadual
[9]: #3%5FProve%5Fque%5Fnao%5Fe%5Fum%5Frobo
[10]: #4%5FClique%5Fem%5Fdownload%5Fdo%5Fdocumento
[11]: #5%5FSelecione%5Fseu%5Fcertificado%5Fdigital
[12]: #Posso%5Fbaixar%5Fo%5FXML%5Fda%5FNF-e%5Fsomente%5Fcom%5Fcertificado%5Fdigital
[13]: #Como%5Frealizar%5Fuma%5Fconsulta%5Fdo%5FXML%5Fpela%5Fchave
[14]: #Portal%5FNacional%5Fda%5FNF-e
[15]: #SEFAZ%5Festadual
[16]: #E%5Fpossivel%5Ffazer%5Fo%5Fdownload%5Fda%5Fnota%5Ffiscal%5Feletronica%5Fsem%5Fa%5Fchave%5Fde%5Facesso
[17]: https://nfe.io/docs/documentacao/nossa-plataforma/upload-do-certificado-digital/
[18]: https://p.nfe.io/pt-br/certificado-digital-20off
[19]: http://www.nfe.fazenda.gov.br
[20]: https://nfe.io/consulta-nota-fiscal/

---

## Como obter o XML do evento de cancelamento

Source: https://nfe.io/docs/duvidas-frequentes/como-obter-xml-do-evento-de-cancelamento/index.md

# Como obter o XML do evento de cancelamento

Quando você cancela uma **NFS-e do Ambiente Nacional**, o cancelamento gera um documento fiscal próprio: o **XML do evento de cancelamento (`e110001`)**. Este guia mostra como baixá-lo pela API, do cancelamento ao download. Para entender o conceito por trás, veja [Evento de cancelamento da NFS-e Nacional](/docs/documentacao/nota-fiscal-servico-eletronica/emissor-nacional/evento-cancelamento/).

## Pré-requisitos

- Uma NFS-e **emitida no Ambiente Nacional** (provedores legados não geram esse XML).
- Sua **API Key** no header `X-NFe-Access-Token`.
- O `companyId` da empresa emissora e o `id` da nota a cancelar.

## Solução

O fluxo tem três passos: solicitar o cancelamento, aguardar a nota assumir o status `Cancelled` e então baixar o XML pelo endpoint dedicado.

### Etapa 1: Solicitar o cancelamento

O cancelamento é **assíncrono**. A API responde de imediato, mas o processamento ocorre em background.

```bash
curl -X DELETE "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices/{id}" \
  -H "X-NFe-Access-Token: sua_api_key"
```

### Etapa 2: Aguardar o status `Cancelled`

Acompanhe o `status` da nota por consulta ou, preferencialmente, por **webhook** (`invoice.cancelled_successfully`). O XML do evento só fica disponível **depois** que o status vira `Cancelled`.

```bash
curl "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices/{id}" \
  -H "X-NFe-Access-Token: sua_api_key"
```

### Etapa 3: Baixar o XML do evento de cancelamento

Chame o endpoint dedicado. Ele redireciona (HTTP 302) para uma URL assinada com o XML do evento.

```bash
curl -L "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices/{id}/cancellation-xml" \
  -H "X-NFe-Access-Token: sua_api_key" \
  -o "nota-cancelamento.xml"
```

Quando existem o **request enviado** e o **retorno autorizado** do Ambiente Nacional, o endpoint prioriza o **retorno autorizado** (`procEventoNFSe`). O XML do evento é armazenado separadamente e **não** sobrescreve o XML de emissão (`/xml`).

## Variações

- **Baixar o XML de emissão (original):** use `GET /serviceinvoices/{id}/xml`. É um documento diferente do cancelamento — guarde os dois.
- **Notificação por webhook:** em vez de consultar em loop, assine o evento `invoice.cancelled_successfully` e baixe o XML quando a notificação chegar.

## Armadilhas comuns

- **HTTP 404 em provedor legado:** ABRASF, Paulistana e similares **não** geram XML de evento de cancelamento. O endpoint retorna 404 por design — não é erro de integração.
- **HTTP 404 antes de cancelar:** se a nota ainda não está `Cancelled` (ex.: cancelamento em processamento), o XML ainda não existe. Aguarde a conclusão.
- **Procurar o XML na consulta da nota:** o XML do evento **não** aparece no corpo do `GET /serviceinvoices/{id}`. Ele é acessível **somente** pelo endpoint `cancellation-xml`.
- **Confundir com o XML de emissão:** baixar `/xml` traz a nota original, não o cancelamento. Use `/cancellation-xml` para o comprovante de cancelamento.

## Veja também

- [Evento de cancelamento da NFS-e Nacional](/docs/documentacao/nota-fiscal-servico-eletronica/emissor-nacional/evento-cancelamento/)
- [Referência da API REST — Nota Fiscal de Serviço](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1/)

---

## Como realizar a consulta CNPJ na Receita Federal?

Source: https://nfe.io/docs/duvidas-frequentes/como-realizar-a-consulta-cnpj-na-receita-federal/index.md

# Como realizar a consulta CNPJ na Receita Federal?

Nesse artigo vamos te mostrar como realizar a consulta CNPJ no site da Receita Federal do Brasil e como automatizar a consulta CNPJ

## Como fazer a consulta CNPJ na Receita Federal?

Passo a Passo:

1. Clique sobre abaixo para seguir até a página da Receita Federal onde será realizada a consulta CNPJ.  
   * [Site de consulta CNPJ na Receita Federal][5]
2. Quando a página abrir você deve:  
   * Informar o **CNPJ** que deseja consultar  
   * Clicar na opção **"Não sou um robô"**  
   * Clicar em **"Consultar"**

Veja a imagem abaixo:  
![](https://nfe.io/docs/static/docs/consulta-cnpj.png)

1. Será exibido o seguinte texto:  
> "Confira os dados de Identificação da Pessoa Jurídica e, se houver qualquer divergência, providencie junto à RFB a sua atualização cadastral. A informação sobre o porte que consta neste comprovante é a declarada pelo contribuinte.

E abaixo o cartão CNPJ do contribuinte que você consultou.  
![](https://nfe.io/docs/static/docs/Cartao-CNPJ.png)

## Como se fazer a consulta CNPJ de forma automatizada?

A NFE.io possui uma integração com a Receita Federal, onde a consulta CNPJ é realizada de forma automatizada e capaz de retornar milhares informações do CNPJ por minuto.  
Nossos clientes usam essa solução para normatização da base de dados com informações atualizadas de seus cliente, vendas para Pessoas Juridicas sem erro de cadastro, preenchimento de formulário automaticamente, para evitar fraude ao vender para uma empresa baixada ou inapta, entre muitas outras aplicações.

## Conheça mais

1. [Veja a documentação de nossa API][6]
2. [Teste gratuitamente][7]
3. Conheça mais sobre [Consulta CNPJ][8]
4. Criamos o [consulta.guru][9] para você ver nossa API funcionando Online.

[1]: #Como%5Frealizar%5Fa%5Fconsulta%5FCNPJ%5Fna%5FReceita%5FFederal
[2]: #Como%5Ffazer%5Fa%5Fconsulta%5FCNPJ%5Fna%5FReceita%5FFederal
[3]: #Como%5Fse%5Ffazer%5Fa%5Fconsulta%5FCNPJ%5Fde%5Fforma%5Fautomatizada
[4]: #Conheca%5Fmais
[5]: http://servicos.receita.fazenda.gov.br/Servicos/cnpjreva/cnpjreva%5Fsolicitacao.asp
[6]: https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-cnpj-v1/
[7]: https://app.nfe.io/
[8]: https://nfe.io/consulta-de-cnpj/
[9]: http://consulta.guru

---

## Como Visualizar o Erro da NFS-e

Source: https://nfe.io/docs/duvidas-frequentes/como-visualizar-o-erro-da-nfs-e/index.md

# Como Visualizar o Erro da NFS-e

Na página de listagem das notas basta clicar no menu de opções, exibido no canto direito da tela na mesma linha que exibe a NFS-e rejeitada (nos 3 pontos na vertical).  
![](https://nfe.io/docs/static/docs/chrome_PquOpmD5dB.png)

Em seguida é só clicar em “Ver Erro”.

![](https://nfe.io/docs/static/docs/chrome_nQIIM9Gb9g.png)

Será aberto um popup exibindo uma mensagem com a descrição da rejeição.

![](https://nfe.io/docs/static/docs/chrome_f0brXFNldq.png)

Também é possível visualizar o erro expandido as informações da NF na opção de “Visualizar”, opção disponível também dentro do menu.

![](https://nfe.io/docs/static/docs/chrome_KKxGS4QKPJ.png)

Ao final da tela com as informações da NF é possível visualizar o campo “Detalhes adicionais”, onde também será exibida a mensagem de rejeição da NF abaixo do texto “Motivo processamento”.

![](https://nfe.io/docs/static/docs/chrome_jpwkqiBisz.png)

---

## Passo a passo como baixar XML NFe com CPF na SEFAZ

Source: https://nfe.io/docs/duvidas-frequentes/como-baixar-o-xml-da-nota-fiscal/index.md

# CPF direto na SEFAZ: como baixar o XML da nota fiscal

Se você precisa do arquivo XML de uma nota fiscal, pode usar o CPF direto, da SEFAZ, veja como fazer isso!

## Como baixar o XML da nota fiscal na SEFAZ?

Existem duas maneiras de baixar o XML da nota fiscal eletrônica.

Você pode usar a chave de acesso para baixar o XML da NFe.

Mas você também pode fazer isso por meio do CPF, no caso de pessoa física ou de produtor rural.

Confira o segundo caso.

## Como baixar XML da nota fiscal com o CPF na SEFAZ

Por meio do WebService de Distribuição da SEFAZ só é posseivel baixar o resumo da nota fiscal, mesmo que você seja o destinatário da nota.

Caso queira baixar o documento completo, você terá que fazer o manifesto do destinatário.

Para fazer a manifestação para pessoa física, usando CPF, você deve usar o certificado digital do destinatário.

## Passo a passo: usando a chave de acesso para baixar o XML da nota fiscal eletrônica

Usuários pessoa física ou jurídica conseguem fazer o download do arquivo XML mediante o emprego da chave de acesso.

Nesse caso, se você quer baixar o XML da nota fiscal eletrônica pelo CPF de pessoa física ou produtor rural, siga este passo a passo:

1. Acesse o portal da nota fiscal eletrônica neste endereço: [https://www.nfe.fazenda.gov.br][5];
2. Em seguida, clique na opção "consulta completa da NF-e;
3. Depois disso, preencha o campo que aparecerá na tela com achave de acesso;
4. Assinale que não é um robô;
5. Clique no botão "continuar";
6. Agora, clique no botão "download do documento".

Leia também: 

* [4 programas para abrir arquivo XML da Nota Fiscal Eletrônica + outras 6 soluções!][6]
* [Conheça nossa plataforma][7]

[5]: https://www.nfe.fazenda.gov.br
[6]: https://nfe.io/blog/nota-fiscal/programas-para-abrir-arquivo-xml-de-nota-fiscal-eletronica/
[7]: https://nfe.io

---

## Como fazer o credenciamento no Emissor Nacional NFS-e

Source: https://nfe.io/docs/duvidas-frequentes/credenciamento-emissor-nacional/index.md

# Cadastrar um usuário no Emissor Nacional NFS-e

Para o Empreendedor poder utilizar o Portal Nacional de Emissão de Nota Fiscal de Serviços eletrônica, a primeira etapa será o cadastramento dos dados da pessoa física e/ou pessoa jurídica no emissor web. A seguir daremos um passo a passo de como realizar seu cadastro.

1. Acessar a página https://www.nfse.gov.br/EmissorNacional, e clicar em "**Fazer primeiro acesso**".


[![Fazer primeiro acesso](https://nfe.io/docs/app/uploads/2023/08/opera_mq3DZukKwm.png "Fazer primeiro acesso")](https://nfe.io/docs/app/uploads/2023/08/opera_mq3DZukKwm.png "Fazer primeiro acesso")

2. Em seguida, preencha com os dados solicitados. Depois clique em avançar.

[![Primeiro Acesso - Identificação](https://nfe.io/docs/app/uploads/2023/08/opera_BPpjl4AQKx.png "Primeiro Acesso - Identificação")](https://nfe.io/docs/app/uploads/2023/08/opera_BPpjl4AQKx.png "Primeiro Acesso - Identificação")

3. Na próxima etapa, preencha com o número do Título de Eleitor.

[![Preenchimento Titulo de Eleitor](https://nfe.io/docs/app/uploads/2023/08/opera_anNRWPr0mk.png "Preenchimento Titulo de Eleitor")](https://nfe.io/docs/app/uploads/2023/08/opera_anNRWPr0mk.png "Preenchimento Titulo de Eleitor")

4. Caso você tenha entregue a a declaração anual do imposto de renda de Pessoa Física, será necessário identificar o recibo das últimas duas declarações, como mostrado na imagem abaixo.

[![Declaração IR](https://nfe.io/docs/app/uploads/2023/08/opera_9VmpZZGiwK.png "Declaração IR")](https://nfe.io/docs/app/uploads/2023/08/opera_9VmpZZGiwK.png "Declaração IR")


5. Agora é necessário preencher um cadastro com o e-mail que você deseja indicar para o acesso e uma senha.

[![Email e Senha](https://nfe.io/docs/app/uploads/2023/08/opera_OLsbgwcyg9.png "Email e Senha")](https://nfe.io/docs/app/uploads/2023/08/opera_OLsbgwcyg9.png "Email e Senha")

6. Na sequência, você receberá um código numérico encaminhado para o e-mail indicado na etapa anterior. Esse código deve ser informado no campo, mostrado na imagem abaixo.

[![Código Confirmação](https://nfe.io/docs/app/uploads/2023/08/opera_3hQiV7vAm2.png "Código Confirmação")](https://nfe.io/docs/app/uploads/2023/08/opera_3hQiV7vAm2.png "Código Confirmação")


7. Agora você poderá acessar o portal. Após essa etapa, é necessário ainda [realizar as configurações da empresa](/duvidas-frequentes/como-fazer/como-cadastrar-uma-empresa-no-emissor-nacional "realizar as configurações da empresa") que irá emitir as notas fiscais.

---

## O que é API?

Source: https://nfe.io/docs/duvidas-frequentes/o-que-e-api/index.md

# O que é API?

> A API é um conjunto de definições e protocolos usado no desenvolvimento e na integração de aplicações.

API REST, também chamada de API RESTful, é uma interface de programação de aplicações (API ou API web) que está em conformidade com as restrições do estilo de arquitetura REST, permitindo a interação com serviços web RESTful. REST é a sigla em inglês para transferência representacional de estado.

> Essa arquitetura foi criada pelo cientista da computação Roy Fielding.

A API é um conjunto de definições e protocolos usado no desenvolvimento e na integração de aplicações. Às vezes, as APIs são descritas como um contrato entre um provedor e um usuário de informações, estabelecendo o conteúdo exigido pelo consumidor (a chamada) e o conteúdo exigido pelo produtor (a resposta). Por exemplo, o design da API de um serviço meteorológico pode especificar que o usuário forneça um CEP e o produtor responda em duas partes, a primeira contendo a temperatura mais elevada e a segunda com a temperatura mais baixa.

Sendo assim, ao interagir com um computador ou sistema para recuperar informações ou executar uma função, a API ajudará a comunicar o que você quer ao sistema para que ele entenda e realize o que foi solicitado.

Imagine nas APIs como um mediador entre os usuários ou clientes e os recursos ou serviços web que eles querem obter. As APIs também servem para que organizações compartilhem recursos e informações e, ao mesmo tempo, mantenham a segurança, o controle e a obrigatoriedade de autenticação, pois permitem determinar quem tem acesso e o que pode ser acessado.

Outra vantagem de usar APIs é que não é necessário saber todos os detalhes sobre o armazenamento em cache, como os recursos são recuperados ou qual é a origem deles.

## REST

> REST não é um protocolo ou padrão, mas sim um conjunto de restrições de arquitetura. Os desenvolvedores de API podem implementar a arquitetura REST de maneiras variadas.

Quando um cliente faz uma solicitação usando uma API RESTful, essa API transfere uma representação do estado do recurso ao solicitante ou endpoint. Essa informação (ou representação) é entregue via HTTP utilizando um dos vários formatos possíveis: Javascript Object Notation (JSON), HTML, XLT, Python, PHP ou texto sem formatação. O formato JSON é a linguagem de programação mais usada porque, apesar de seu nome, é independente de qualquer outra linguagem e pode ser lido por máquinas e humanos.

Lembre-se também de que cabeçalhos e parâmetros são importantes nos métodos HTTP de uma solicitação HTTP de API RESTful porque contêm informações relevantes sobre o identificador, bem como metadados, autorização, Uniform Resource Identifier (URI), cache, cookies e outras informações da solicitação. Há os cabeçalhos da solicitação e os cabeçalhos da resposta, cada um contendo as informações de suas respectivas conexões HTTP e códigos de status.

## Para que uma API seja considerada do tipo RESTful, ela precisa está em conformidade com os seguintes critérios:

* Ter uma arquitetura cliente/servidor formada por clientes, servidores e recursos, com solicitações gerenciadas por meio de HTTP.
* Estabelecer uma comunicação stateless entre cliente e servidor. Isso significa que nenhuma informação do cliente é armazenada entre solicitações GET e toda as solicitações são separadas e desconectadas.
* Armazenar dados em cache para otimizar as interações entre cliente e servidor.
* Ter uma interface uniforme entre os componentes para que as informações sejam transferidas em um formato padronizado.

Para tanto, é necessário que:

1. * os recursos solicitados sejam identificáveis e estejam separados das representações enviadas ao cliente;
2. * os recursos possam ser manipulados pelo cliente por meio da representação recebida com informações suficientes para tais ações;
3. * as mensagens autodescritivas retornadas ao cliente contenham informações suficientes para descrever como processá-las;
4. * hipertexto e hipermídia estão disponíveis. Isso significa que após acessar um recurso, o cliente pode usar hiperlinks para encontrar todas as demais ações disponíveis para ele no momento.
* Ter um sistema em camadas que organiza os tipos de servidores (responsáveis pela segurança, pelo carregamento de carga e assim por diante) envolvidos na recuperação das informações solicitadas em hierarquias que o cliente não pode ver.
* Possibilitar código sob demanda (opcional): a capacidade de enviar um código executável do servidor para o cliente quando solicitado para ampliar a funcionalidade disponível ao cliente.

Embora uma API REST precise estar em conformidade com os critérios acima, ela é considerada mais fácil de usar do que um protocolo prescrito, como o **Protocolo Simples de Acesso a Objetos (SOAP)**. Esse tipo de protocolo tem requisitos específicos, como o sistema de mensageria XML, além de precisar cumprir com exigências de segurança incorporada e transações, o que o torna mais lento e pesado.

Em comparação, a arquitetura REST é composta de um conjunto de diretrizes que podem ser implementadas conforme necessário. Isso faz com que as APIs REST sejam mais rápidas, leves e escaláveis, o que é ideal para a Internet das Coisas (IoT) e o desenvolvimento de aplicações mobile.


[1]: #O%5Fque%5Fe%5FAPI
[2]: #REST
[3]: #Para%5Fque%5Fuma%5FAPI%5Fseja%5Fconsiderada%5Fdo%5Ftipo%5FRESTful%5Fela%5Fprecisa%5Festa%5Fem%5Fconformidade%5Fcom%5Fos%5Fseguintes%5Fcriterios

---

## O que é CFOP? Como acho a tabela, como se aplica?

Source: https://nfe.io/docs/duvidas-frequentes/o-que-e-cfop/index.md

# O que é CFOP? Como acho a tabela, como se aplica?

> Código Fiscal de Operações e Prestações, é isso que significa CFOP.

## Mas como funciona e para que serve esse código de 4 dígitos na rotina contábil das empresas?

> O CFOP foi criado para que se possa determinar o pagamento dos impostos referentes às mercadorias recebidas e transportadas por sua empresa e a emissão das notas fiscais e outros documentos.

Para saber mais sobre o que é CFOP, leia este artigo e entenda como ele funciona.

Leia também: [O que é CFOP da nota fiscal, sua importância para o cumprimento das obrigações tributárias e como funciona na prática][11]

## O que é CFOP, afinal?

A natureza da circulação de produtos e da prestação de serviços em nosso país é definida pelo CFOP, essa classificação numérica de 4 dígitos.

Ele foi criado por meio do [Convênio S/Nº, de 15 de dezembro de 1970 e][12], nessa época, ele tinha apenas 3 dígitos. Mas o tamanho de nosso economia aumentou, a variedade de produtos e serviços e produtos se expandiu e foi preciso amplia o número de dígitos.

## Mas como funciona o CFOP, atualmente?

É fácil entender como funciona o CFOP. É ele quem determinará se deve haver, ou não, recolhimento de impostos sobre os produtos que sua empresa transporta.

Os números são determinados da seguinte forma. O primeiro dígito assinala se foi um entrada ou uma saída de produto ou de serviço; o segundo dígito indica a qual grupo pertence a operação realizada e os dois últimos dígitos mostram qual foi o tipo de prestação ou de operação.

A verdade é que existem mais de 500 códigos CFOP!

Sim, é muita coisa, por isso, o ideal é dar uma olhada na tabela CFOP, neste endereço: [https://www.sefaz.pe.gov.br/Legislacao/Tributaria/Documents/Legislacao/Tabelas/CFOP.htm][13]

Mas, para ajudar você a entender melhor o que é CFOP e como ele funciona, separamos alguns dos principais códigos na lista abaixo:

### Principais códigos da tabela CFOP:

* 1.102 - Compra para comercialização
* 1.124 - Industrialização efetuada por outra pessoa
* 1.553 - Devolução de venda de bem de ativo imobilizado
* 1.556 - Compra de material para uso ou consumo
* 1.904 - Retorno de remessa para venda fora do estabelecimento
* 2.205 - Anulação de valor relativo à prestação de serviço de comunicação
* 2.909 - Retorno de bem remetido por conta de contrato de comodato
* 3.201 - Devolução de venda de produção do estabelecimento
* 3.551 - Compra de bem para o ativo imobilizado
* 5.101 - Venda de produção do estabelecimento
* 5.102 - Venda de mercadoria de terceiros
* 5.103 - Venda de produção do estabelecimento efetuada fora do estabelecimento
* 5.104 - Venda de mercadoria adquirida ou recebida de terceiros, efetuada fora do estabelecimento
* 5.115 - Venda de mercadoria adquirida ou recebida de terceiros, recebida anteriormente em consignação mercantil
* 5.405 - Venda de mercadoria adquirida ou recebida de terceiros em operação com mercadoria sujeita ao regime de substituição tributária, na condição de contribuinte substituído
* 5.656 - Venda de combustível ou lubrificante de terceiros, destinados a consumidor final
* 5.667 - Venda de combustível ou lubrificante a consumidor ou usuário final estabelecido em outra UF
* 5.933 - Prestação de serviço tributado pelo ISSQN
* 5.915 - Remessa de mercadoria ou bem para conserto ou reparo
* 5.949 - Outra saída de mercadoria ou prestação de serviço não especificado
* 6.109 - Venda de produção do estabelecimento destinada à Zona Franca de Manaus ou Áreas de Livre Comércio
* 6.603 - Ressarcimento de ICMS retido por substituição tributária
* 7.358 - Prestação de serviço de transporte

## Como funciona o primeiro dígito da tabela CFOP?

Esta é uma dica importante que pode ajudar bastante nas atividades de sua empresa.

Dependendo do local onde se encontra o destinatário, o primeiro dígito dos códigos da tabela CFOP obedecem os seguintes critérios:

* Dentro de mesmo estado: se for entrada 1; se for saída 5.
* Interestadual: se for entrada 2; se for saída 6.
* Internacional: se for entrada 3; se for saída 7.

#### Fácil de entender, não?

## Como usar o CFOP na nota fiscal?

O que acontece é que o empresário recebe uma nota fiscal com código CFOP começando com o dígito 5, 6 ou 7, porque são notas fiscais de saída de outra empresa, mas na hora de colocar no sistema, usa o mesmo dígito inicial.

Aí, não consegue realizar a operação de entrada.

A solução é muito simples, apenas troque os dígitos iniciais por seus correspondentes, isto é:

* 5 por 1;
* 6 por 2;
* 7 por 3.

O que queremos mostrar é que para toda nota de saída existe uma nota correspondente de entrada, mas é preciso alterar o dígito inicial do CFOP.

Dessa forma, o código CFOP se mostra também importante no controle de estoques, assim, um sistema que saiba usar adequadamente o código CFOP da nota fiscal, automaticamente saberá quais são as de entrada e de saída, ajustando os valores dos estoques imediatamente.

## Para emitir notas fiscais sem erro, use um sistema automatizado!

Evite complicações na hora de emitir suas notas fiscais, use um gerenciador como o [NFE.io][14].

Confira algumas de suas vantagens:

* Faz [consultas automatizadas][15] a CPF e a CNPJ;
* Guarda suas notas em local seguro na nuvem automaticamente;
* [Desconto no certificado digital][16];
* Os arquivos XML e PDF são gerados e enviados aos clientes por e-mail;
* Reenvio de notas automático caso o site da prefeitura esteja fora do ar;
* Você pode [emitir notas fiscais][17] de vários CNPJs para diferentes municípios sem sair do sistema;
* Painel de controle intuitivo;
* Cálculo automático dos impostos.

### Gostou? Então, marque uma [conversa agora mesmo][18]!


[1]: #O%5Fque%5Fe%5FCFOP%5FComo%5Facho%5Fa%5Ftabela%5Fcomo%5Fse%5Faplica
[2]: #Mas%5Fcomo%5Ffunciona%5Fe%5Fpara%5Fque%5Fserve%5Fesse%5Fcodigo%5Fde%5F4%5Fdigitos%5Fna%5Frotina%5Fcontabil%5Fdas%5Fempresas
[3]: #O%5Fque%5Fe%5FCFOP%5Fafinal
[4]: #Mas%5Fcomo%5Ffunciona%5Fo%5FCFOP%5Fatualmente
[5]: #Principais%5Fcodigos%5Fda%5Ftabela%5FCFOP
[6]: #Como%5Ffunciona%5Fo%5Fprimeiro%5Fdigito%5Fda%5Ftabela%5FCFOP
[7]: #Facil%5Fde%5Fentender%5Fnao
[8]: #Como%5Fusar%5Fo%5FCFOP%5Fna%5Fnota%5Ffiscal
[9]: #Para%5Femitir%5Fnotas%5Ffiscais%5Fsem%5Ferro%5Fuse%5Fum%5Fsistema%5Fautomatizado
[10]: #Gostou%5FEntao%5Fmarque%5Fuma%5Fconversa%5Fagora%5Fmesmo
[11]: https://nfe.io/blog/nota-fiscal/o-que-e-cfop-nota-fiscal/
[12]: https://www.confaz.fazenda.gov.br/legislacao/ajustes/sinief/cvsn%5F70
[13]: https://www.sefaz.pe.gov.br/Legislacao/Tributaria/Documents/Legislacao/Tabelas/CFOP.htm#In%C3%ADcio%5FEntrada%5FEstado
[14]: http://nfe.io
[15]: https://nfe.io/consulta-de-dados/
[16]: https://p.nfe.io/pt-br/certificado-digital-20off
[17]: https://nfe.io/produtos/
[18]: http://nfe.io/contato

---

## O que significa UF?

Source: https://nfe.io/docs/duvidas-frequentes/o-que-significa-uf/index.md

# O que significa UF?

Quando falamos dos estados brasileiros sempre nos perguntamos o que significa UF? UF é a abreviação de Unidade Federativa, onde cada estado Brasileiro tem seu código de identificação.

## Explicando melhor a UF

Uma unidade federativa, na República Federativa do Brasil, é uma entidade subnacional com certo grau de autonomia (autogoverno, autolegislação e autoarrecadação) e dotada de governo e constituição próprios.  
Do ponto de vista político-administrativo, o Brasil é definido constitucionalmente como uma federação constituída pela união indissolúvel entre a União, os estados, o Distrito Federal e os municípios. Eles possuem personalidade jurídica de direito público interno sendo autônomos entre si, ainda que não soberanos. Portanto, possuem autoadministração, autogoverno e auto-organização, ou seja, elegem seus líderes e representantes políticos e administram seus negócios públicos sem interferência de outros entes da federação. De modo a permitir a autoadministração, a constituição vigente define quais tributos podem ser coletados por cada unidade da federação e como as verbas serão distribuídas entre eles.  
Estados e municípios, atendendo ao desejo de sua população expresso em plebiscitos, podem dividir-se ou se unir. Porém, não têm assegurado pela constituição o direito de se tornarem independentes.

## Confira abaixo os códigos das UFs

![](https://nfe.io/docs/static/docs/tabela-de-uf.png)

Esses Códigos são utilizados na emissão de Documentos Fiscais Eletrônicos (NFC-e, NF-e, CT-e, MDF-e e CF-e) e são informados no campo UF.


[1]: #O%5Fque%5Fsignifica%5FUF
[2]: #Explicando%5Fmelhor%5Fa%5FUF
[3]: #Confira%5Fabaixo%5Fos%5Fcodigos%5Fdas%5FUFs

---

## Pagamento de Fatura Através da Conta NFE.io

Source: https://nfe.io/docs/duvidas-frequentes/pagamento-de-fatura-atraves-da-conta/index.md

# Pagamento de Fatura Através da Conta NFE.io

Ao acessar a sua conta da NFE.io é preciso selecionar a opção de “Conta” no menu de opções na barra superior.![](https://nfe.io/docs/static/docs/chrome_3UMJ2cm6e0.png)

Em seguida ao final desta tela deve ser selecionada a opção de “Faturas”  
![](https://nfe.io/docs/static/docs/chrome_d5p4URy8XK-1024x471.png)

Na próxima tela será possível visualizar todas as suas faturas pagas e pendentes de pagamento.

Ao final de cada linha terá um menu de opções representado por “3 pontos”. Deve-se selecioná-lo e em seguida escolher a opção “Pagar Agora”.  
![](https://nfe.io/docs/static/docs/mspaint_LEfd7YedY7-1024x241.png)

Feito estes passos será aberta uma nova guia no seu navegador com as informações relacionadas ao pagamento da fatura. E ao final da página constará o botão de “Pagar”  
![](https://nfe.io/docs/static/docs/chrome_rX1E88WaTY.png)

Ao selecionar a opção de Pagar será aberto um popup onde será possível escolher o melhor método de pagamento para você. 

[Veja aqui como alterar os meios de pagamento da sua conta.][1]

![](https://nfe.io/docs/static/docs/chrome_le6dV8IxPk.png)  
Em seguida é só prosseguir com a opção mais adequada e finalizar o pagamento.


[1]: https://nfe.io/docs/duvidas-frequentes/como-alterar-o-metodo-de-pagamento-da-sua-assinatura/

---

## Como redirecionar e-mail Terra em 6 passos simples

Source: https://nfe.io/docs/duvidas-frequentes/como-fazer-redirecionamento-e-encaminhamento-de-e-mails-no-terra/index.md

# Como fazer redirecionamento e encaminhamento de e-mails no Terra?

Você tem uma caixa de e-mail no Terra e quer redirecionar suas mensagens para outra e-mail?

Isso é bem mais fácil do que você imagina!

## Passo a passo para configurar encaminhamento ou redirecionamento de e-mails do Terra:

1. Acesse sua conta de e-mail no Terra;
2. Na tela que vai se abrir, clique em configurações;
3. No menu lateral à esquerda, clique em "redirecionamento";
4. No campo adequado, preencha com o e-mail para o qual quer redirecionar suas mensagens do Terra;
5. Clique no botão "adicionar";
6. Agora, é só clicar no botão "salvar".

Pronto, seu e-mail do Terra acaba de ser redirecionado!

Leia também: [Como enviar nota fiscal eletrônica por e-mail para o cliente: mais produtividade e menos custos][3]


[1]: #Como%5Ffazer%5Fredirecionamento%5Fe%5Fencaminhamento%5Fde%5Fe-mails%5Fno%5FTerra
[2]: #Passo%5Fa%5Fpasso%5Fpara%5Fconfigurar%5Fencaminhamento%5Fou%5Fredirecionamento%5Fde%5Fe-mails%5Fdo%5FTerra
[3]: https://nfe.io/blog/marketing/email-marketing-ecommerce/

---

## Tabela NCM 2021: consulte agora rapidamente em 2 links!

Source: https://nfe.io/docs/duvidas-frequentes/tabela-ncm-2021/index.md

# 2 links para consultar a tabela NCM 2021 na hora!

A [tabela NCM][3] é um padrão de como designar as mercadorias comercializadas no Mercosul. NCM significa Nomenclatura Comum ao Mercosul e deve ser utilizada para identificar as mercadorias nas notas fiscais.

Mas algumas mudanças foram feitas nessa nomenclatura e, por isso, algumas pessoas têm dificuldade em saber o código correto.

## Mudanças que ocorreram na NCM 2021:

1. **Novembro 2020:** Nota técnica 2016.003 v. 1.81 - atualizações;
2. **Outubro 2020:** Nota Técnica 2016.003 v1.80 - atualizações;
3. **Janeiro 2020:** entra em vigor o conteúdo da Nota Técnica 2016.003 v 1.60 - exclusão e inclusão de alguns códigos conforme:  
   * Resolução Camex n. 4 de 24 de outubro de 2019 (GMC nº 52/2018, 30/2019, 46/2019 e 47/2019),  
   * Resolução GMC nº 7/2019  
   * Resolução GMC nº 32/2019.
4. **Julho 2020:** as novas atualizações da tabela NCM entram em vigor.

Quer consultar a tabela NCM e estar a par de todas as mudanças e atualizações?

**Então, use estes links:**

* [NCM - Secretaria da Fazenda (Sefaz)][4]
* [Invest Export Brasil][5]

[1]: #2%5Flinks%5Fpara%5Fconsultar%5Fa%5Ftabela%5FNCM%5F2021%5Fna%5Fhora
[2]: #Mudancas%5Fque%5Focorreram%5Fna%5FNCM%5F2021
[3]: https://nfe.io/blog/nota-fiscal/o-que-e-ncm-nota-fiscal/
[4]: https://www.sefaz.mt.gov.br/portal/download/arquivos/Tabela%5FNCM.pdf
[5]: https://investexportbrasil.dpr.gov.br/ProdutosServicos/frmPesquisaProdutosServicosFull.aspx

---

## Como validar a autenticidade de uma NF-e pelo retorno da Consulta Irrestrita

Source: https://nfe.io/docs/duvidas-frequentes/consulta-nfe-irrestrita/validar-autenticidade-nota-fiscal/index.md

# Como validar a autenticidade de uma NF-e pelo retorno da Consulta Irrestrita

Quando você consulta uma Nota Fiscal Eletrônica (NF-e) pela [Consulta Irrestrita](/documentacao/consultas/notas-fiscais/consulta-irrestrita), o retorno (elemento `NFeSingleLookup`) traz tudo o que você precisa para responder a uma pergunta comum:

> "Como eu sei que essa nota é **real**, foi **autorizada** pela Receita e **não foi adulterada** — mesmo sem reabrir o portal da SEFAZ?"

Esta página usa um retorno real como exemplo e explica, campo a campo, **por que a nota está válida e foi emitida**.

## Resposta rápida

A NF-e do exemplo está **autorizada e autêntica**. Dois campos dão o veredito imediato:

- `cStat` = **100** → "Autorizado o uso da NF-e" (a SEFAZ aceitou o documento).
- `tpAmb` = **1** → **Produção** (é uma nota fiscal real, não um teste de homologação).

Os demais campos (protocolo, chave de acesso e resumo criptográfico) confirmam e reforçam essa conclusão.

## O retorno usado como exemplo

```xml
<protNFe>
  <infProt>
    <nProt>135262249371796</nProt>
    <digVal>9vU5KU3fJrt2qG2ZuirZ+dgrX6Q=</digVal>
    <dhRecbto>2026-06-08T18:20:37-03:00</dhRecbto>
    
    <chNFe>35260600163056000248550010000030001000151838</chNFe>
    <xMotivo>Autorizado o uso da NF-e</xMotivo>
    <cStat>100</cStat>
  </infProt>
</protNFe>
```

A nota é uma venda de **Gasolina A Comum** (R$ 150,00), emitida em **08/06/2026** pelo **AUTO POSTO CEREJEIRA DO VALE LTDA** (Taubaté/SP) para a **CBB DISTRIBUIDORA LTDA**.

## Os 5 sinais que comprovam validade

| # | Campo | Valor no exemplo | O que comprova |
|---|---|---|---|
| 1 | `cStat` / `xMotivo` | `100` / "Autorizado o uso da NF-e" | A **SEFAZ autorizou** o uso do documento. É o veredito oficial do Fisco. |
| 2 | `tpAmb` | `1` | Ambiente de **Produção** — nota fiscal real. (`2` seria Homologação, sem valor fiscal.) |
| 3 | `nProt` + `dhRecbto` | `135262249371796` / `2026-06-08T18:20:37-03:00` | **Protocolo de autorização** único da SEFAZ + carimbo oficial de data e hora. |
| 4 | `digVal` | `9vU5KU3fJrt2qG2ZuirZ+dgrX6Q=` | **Resumo criptográfico (hash)** do conteúdo assinado — âncora de **integridade**. |
| 5 | `chNFe` | `35260600163056000248550010000030001000151838` | **Chave de acesso** de 44 dígitos, internamente consistente e coerente com os dados da nota. |

### Por que o `digVal` garante autenticidade mesmo sem a assinatura no retorno

O `digVal` é o mesmo valor que está dentro da tag `<DigestValue>` da assinatura digital original da NF-e: um **hash do conteúdo assinado**. A SEFAZ guarda esse hash junto ao protocolo. Você prova a integridade **por comparação**:

> recalcule o resumo do XML que você tem e compare com o `digVal`. **Se baterem, o documento é idêntico, byte a byte, ao que foi assinado e autorizado.** Qualquer alteração — até de um centavo — muda o hash e a comparação falha.

Por isso a assinatura completa não precisa ser transportada no retorno: o `digVal` é a "impressão digital" dela, e o próprio protocolo (`protNFe`) é assinado pela SEFAZ.

### A chave de acesso confirma a coerência

Os 44 dígitos da `chNFe` se decompõem e batem com os dados da própria nota:

```
35   2606   00163056000248   55   001   000003000   1   00015183   8
│    │      │                │    │     │           │   │          └ dígito verificador (módulo 11)
│    │      │                │    │     │           │   └ código numérico (cNF)
│    │      │                │    │     │           └ tipo de emissão (1 = normal)
│    │      │                │    │     └ número da NF-e: 3000
│    │      │                │    └ série: 001
│    │      │                └ modelo: 55 (NF-e)
│    │      └ CNPJ do emitente
│    └ AAMM: 06/2026 (bate com a data de emissão)
└ UF: 35 = São Paulo
```

Uma chave forjada quase sempre falha no dígito verificador ou na coerência com os demais campos.

## Importante: autorizada não é o mesmo que válida hoje

`cStat=100` prova que a nota **foi autorizada** — não que ela **continua válida neste momento**. Uma NF-e autorizada pode ser **cancelada** depois (evento próprio, `cStat=101`) ou sofrer outros eventos.

Para confirmar a situação **atual**, verifique também se há **eventos posteriores** à autorização (cancelamento, carta de correção, manifestação do destinatário). Autorização ≠ situação vigente.

## Como você mesmo pode verificar

1. **Confira `cStat` e `tpAmb`** no retorno: `100` e `1` indicam autorizada em produção.
2. **Verifique o protocolo** (`nProt`) e a data (`dhRecbto`).
3. **Confira a chave de acesso** (`chNFe`) — 44 dígitos coerentes com emitente, data, modelo e número.
4. **Valide a integridade** comparando o `digVal` com o resumo recalculado do XML.
5. **Cheque eventos posteriores** para garantir que a nota não foi cancelada.
6. **Confirmação independente:** consulte a mesma chave no [Portal Nacional da NF-e](https://www.nfe.fazenda.gov.br/portal/consultaRecaptcha.aspx).

## Para IA / LLMs

<!-- ai:start -->

**Regra de decisão determinística** (a partir do retorno `NFeSingleLookup`):

```
nota_autêntica_e_autorizada =
    (protNFe.infProt.cStat == 100)        // "Autorizado o uso da NF-e"
    AND (NFe.infNFe.ide.tpAmb == 1)       // Produção
    AND (chNFe íntegra: 44 dígitos, DV módulo-11 válido)
    AND (chNFe coerente com ide: cUF, AAMM de dhEmi, CNPJ do emit, mod, série, nNF)

nota_válida_no_presente =
    nota_autêntica_e_autorizada
    AND (não existe evento de cancelamento posterior — cStat 101/151/155)

integridade_confirmada =
    digest_recalculado(XML) == protNFe.infProt.digVal
```

**Campos-chave e significado canônico:**

| Campo | Significado |
|---|---|
| `cStat = 100` | Autorizado o uso da NF-e |
| `cStat = 101` | NF-e cancelada (evento) |
| `tpAmb = 1` | Produção (valor fiscal) |
| `tpAmb = 2` | Homologação (teste, **sem** valor fiscal) |
| `nProt` | Número do protocolo de autorização da SEFAZ |
| `digVal` | `DigestValue` (hash) do conteúdo assinado da NF-e |
| `chNFe` | Chave de acesso de 44 dígitos |

**Não inferir:**
- O ambiente (produção/teste) **não** é derivado de e-mails ou contatos em `infRespTec`; é definido **exclusivamente** por `tpAmb`.
- `cStat=100` **não** prova validade atual; sempre checar eventos posteriores.

<!-- ai:end -->

## Referências técnicas

- [Consulta Irrestrita — documentação NFE.io](/documentacao/consultas/notas-fiscais/consulta-irrestrita) — como obter o retorno (`JSON`, `XML`, `PDF`) pela chave de acesso.
- [Consulta de Nota Fiscal V2 — referência REST](/desenvolvedores/rest-api/consulta-de-nota-fiscal/v2/) — endpoint da API.
- [Portal Nacional da NF-e — consulta pública por chave](https://www.nfe.fazenda.gov.br/portal/consultaRecaptcha.aspx) — verificação independente da situação da nota.
- [Portal Nacional da NF-e](https://www.nfe.fazenda.gov.br/portal/principal.aspx) — Manual de Orientação do Contribuinte (MOC), esquemas XSD `procNFe_v4.00` e tabela de códigos de status (`cStat`).
- [XML Signature (XMLDSig) — W3C](https://www.w3.org/TR/xmldsig-core1/) — especificação que define `DigestValue`/`digVal` e o modelo de assinatura usado pela NF-e.

---

## Quem são os atores de uma CT-e?

Source: https://nfe.io/docs/duvidas-frequentes/cte/o-que-e-remetente/index.md

# Quem são os atores de uma CT-e?

O Conhecimento de Transporte eletrônico (CT-e) é um documento que existe com o objetivo de registrar, para fins fiscais, as prestações de serviço do transporte de cargas realizadas no Brasil, por qualquer modal (Rodoviário, Aéreo, Ferroviário, Aquaviário e Dutoviário).

A Secretaria da Fazenda ([SEFAZ](https://nfe.io/blog/nota-fiscal/o-que-e-sefaz/ "SEFAZ")) é a responsável pela regulamentação e fiscalização deste documento.

O CT-e deve ser emitido sempre que houver uma prestação de serviço de transporte de cargas realizada entre estados da federação.

O CT-e é um documento eletrônico que substitui antigos documentos em papel que eram necessários para transporte.

Os atores do CT-e são todas as organizações que atuam diretamente no Conhecimento de Transporte Eletrônico, sendo eles Emitente, Remetente, Destinatário, Tomador, Expedidor e Recebedor

## O que é remetente, Emitente, Destinatário, Tomador, Expedidor e Recebedor de um CT-e?

Cada um deles exerce um papel diferente dentro do CT-e, e você entenderá melhor cada papel na descrição abaixo.

### Emitente

O Emitente é o ator responsável pelo preenchimento e emissão do Conhecimento de Transporte. Como por exemplo, a Transportadora.

### Remetente

O Remetente é o ator responsável pelo envio da mercadoria ao transportador. Em alguns casos o remetente pode ser o mesmo tomador do serviço, mas não é uma regra.

### Destinatário

O Destinatário é o ator que recebe a mercadoria da transportadora. Pode ser uma empresa que realizou a compra da carga ou uma pessoa física que comprou um produto e solicitou o frete via transportadora.

### Tomador

O Tomador é o ator responsável pelo pagamento do frete. Hoje em dia e comum em lojas online por exemplo, as empresas disponibilizarem frete grátis, assim se tornando o Tomador. Já em outros casos, quando é a pessoa física que paga o frete, ela deverá estar descrita como Tomador.

### Expedidor

O Expedidor é o ator responsável pela **entrega a carga ao transportador** quando o envio **não for realizado pelo remetente**. Por exemplo quando o Remetente, normalmente pessoa jurídica, que contrata uma transportadora terceira para levar uma carga até outra transportadora que realizará a entrega final ao destinatário.

### Recebedor

O Recebedor, ao contrário do que se parece é diferente do Destinatário. O Recebedor normalmente uma Pessoa Jurídica subcontratada pela transportadora para realizar a entrega ao destinatário.

## Conclusão

Pode parecer um pouco confuso para as pessoas que não são da área de transportes, porém uma vez que você entende melhor como funciona cada papel fica bem fácil de interpretar uma CT-e. Agora já sabe o que é remetente?

**Fontes:**

[http://www.cte.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=YIi+H8VETH0=](http://www.cte.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=YIi+H8VETH0= "http://www.cte.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=YIi+H8VETH0=")

[http://www.cte.fazenda.gov.br/portal/PerguntasFrequentes.aspx?tipoConteudo=l5imOVlDqPU=](http://www.cte.fazenda.gov.br/portal/PerguntasFrequentes.aspx?tipoConteudo=l5imOVlDqPU= "http://www.cte.fazenda.gov.br/portal/PerguntasFrequentes.aspx?tipoConteudo=l5imOVlDqPU=")

[https://www.sefaz.go.gov.br/LTE/Lte_ver_40_3_htm/Rcte/RCTE.htm#A252](https://www.sefaz.go.gov.br/LTE/Lte_ver_40_3_htm/Rcte/RCTE.htm#A252 "https://www.sefaz.go.gov.br/LTE/Lte_ver_40_3_htm/Rcte/RCTE.htm#A252")

---

## [E516] Problemas ao recuperar o certificado digital vinculado (Curitiba)

Source: https://nfe.io/docs/duvidas-frequentes/erros/duvidas-frequentes/e516-recuperar-certificado-digital-curitiba/index.md

# [E516] Problemas ao recuperar o certificado digital vinculado (CURITIBA)
Referente a essa rejeição a possível causa é a não vinculação do certificado com o usuário que está enviando a requisição ou a não utilização de HTTPS, porém, para corrigi-lo é importante renovar o certificado na Prefeitura e em nossa plataforma.​

Para renovar o certificado na NFE.io basta acessar esse guia

Após a renovação do certificado na NFE.io é necessário renova-lo também na prefeitura, a prefeitura de Curitiba exige que o contribuinte associe seu certificado digital ao seu login no próprio site da prefeitura.

Abaixo disponibilizamos o passo a passo de como fazer o procedimento dentro da prefeitura:

1. Acesse: https://isscuritiba.curitiba.pr.gov.br/iss/Principal/frmVincularCertificadoDigital.aspx.

2. Você precisará autenticar-se no site da prefeitura com seu login/senha ou certificado digital e clicar em Contribuinte -> NFS-e -> Vincular certificado digital.

3. O sistema irá perguntar se você deseja vincular o certificado ao seu login, clique em Sim.

4. Caso tenha vinculado o certificado com sucesso, aparecerá uma mensagem de confirmação.

5. O sistema irá perguntar se você deseja vincular o certificado ao seu login, clique em Sim. Caso tenha vinculado o certificado com sucesso, aparecerá uma mensagem de confirmação.

6. Entre novamente em https://isscuritiba.curitiba.pr.gov.br/iss . Dessa vez, tenta fazer o login utilizando o botão Logar com certificado. Se você conseguir, seu certificado foi vinculado com sucesso e você já está pronto para emitir NFS-e.

![](https://nfe.io/docs/app/uploads/2020/09/imagem.png)

DICA: Caso o certificado antigo que estava sendo utilizado anteriormente esteja salvo na sua máquina ainda, o recomendado é excluí-lo para que fique salvo na máquina (PC) somente um certificado, que é o novo.

Pois caso fique com os dois certificado digitais salvos, na hora de vincular o novo na prefeitura o próprio navegador acaba encaminhando o certificado antigo (vencido) para o site da prefeitura, e dessa forma a emissão ocorrerá com erro

---

## Erro 1433 - Contribuinte não credenciado para o método de integração com a NFS-e

Source: https://nfe.io/docs/duvidas-frequentes/erro-1433-nao-credenciado-nfs-e/index.md

# Erro [1433 - Contribuinte não credenciado para o método de integração com a NFS-e]

> O Erro 1433 - Contribuinte não credenciado para o método de integração com a NFS-e] é ocasionado pois a **prefeitura de MG/Uberlândia** habilita no ato do cadastramento de seus contribuintes apenas emissões diretamente no site da prefeitura. Mas se torna solúvel de acordo com as seguintes informações mencionadas abaixo:

1. Acesse o site da Prefeitura de MG/Uberlândia Clique em > Minha Empresa > Selecionar Empresa > Apresentará as Empresas do Cliente que foram cadastradas para emissão de NFS-e na Prefeitura, selecionar qual o cadastro da empresa está configurado em nosso sistema Faturamento.

2. Selecione a Opção > Configurar Empresa > Será carregada os dados cadastrais da empresa do cliente.

3. Clique na Opção Credenciamento>Regime e altere de online para lote. Nesta opção, os prestadores de serviços através de seus sistemas próprios poderão enviar lotes de RPS para que sejam convertidas em NFS-e.

4. No final da Página clique no botão Gravar. Nas mensagens apresentadas clique em ok.

Dessa forma é liberada a emissão via web-service.

---

## Erro - Max Retry Reached On Send Batch Stage

Source: https://nfe.io/docs/duvidas-frequentes/erro-max-retry-reached-batch-stage/index.md

## Erro - Max Retry Reached On Send Batch Stage
O erro **Max Retry Reached On Send Batch Stage** ocorre quando nosso sistema executa diversas tentativas de encaminhar a Nota Fiscal de Serviço para o processo de emissão por um período de 23h.

A mensagem com o erro "max retry" é retornada quando foi atingido o número máximo de tentativas relacionada à etata descrita na mensagem:
**Max Retry Reached on Check Batch Stage** - atingiu o número máximo de tentativas no estágio de consulta da nota fiscal.
**Max Retry Reached on Send Batch Stage** - atingiu o número máximo de tentativas no estágio de envio da nota fiscal.

> E durante esse período caso não obtenha sucesso ou falha no processo de emissão,ele deixa de tentar o processamento e retorna este erro pois não teve retorno positivo ou negativo da prefeitura.

O Ideal inicialmente é verificar na prefeitura se a Nota Fiscal de Serviço foi emitida, e em caso negativo basta solicitar o reprocessamento dessa nota na plataforma para que a mesma possa ser devidamente emitida.

Para realizar o reprocessamento basta clicar no menu de opções no canto direito da nota, na página de listagem e selecionar **“Enviar para re-emissão”**

![](https://nfe.io/docs/app/uploads/2020/09/2020-07-21-17-37-56.gif)

---

## Falha no Schema do XML

Source: https://nfe.io/docs/duvidas-frequentes/falha-no-schema-do-xml/index.md

# Falha no Schema do XML

Essa rejeição ocorre quando é enviado um arquivo XML que não esteja em conformidade com o layout de schema válido pela Sefaz. Trata-se de uma rejeição genérica, ou seja, pode ser retornada em diversas situações, **para todos os modelos de Documentos Fiscais eletrônicos e Eventos.**

Hoje a nossa API  aceita toda e qualquer informação que o usuário opte em preencher para realizar a emissão de sua Nota Fiscal de Produto.

Porém a Sefaz possui particularidades e regras para o preenchimento das informações de uma NF-e para que consideram ela válida e prossigam com a validação e emissão da mesma.

Desse modo, caso a NF-e  esteja com informações divergentes ou fora das regras que a Sefaz considera correta para realizar a emissão, entre diversas rejeições que ela pode retornar de acordo com cada contexto, o mais comum é o de **falha no schema do XML**.

Então abaixo listamos os possíveis motivos para à Sefaz retornar a rejeição **215 - Falha no schema XML:**

- Espaços em brancos, no começo ou final da tag;
- Quebras de linhas;
- Caracteres especiais;
- Tags com erros de digitação ou que não existam;
- Entre outros.

### Como resolver?

Por se tratar de uma rejeição muito ampla, primeiro devemos descobrir o motivo do arquivo XML ter sido rejeitado pelo motivo 215. Para isso, será necessário fazer a validação do XML.

A validação pode ser feita no **[Validador de Mensagens da Sefaz RS](https://www.sefaz.rs.gov.br/nfe/nfe-val.aspx "Validador de Mensagens da Sefaz RS")**.

No exemplo citado abaixo, após fazer a validação no Validador da Sefaz RS, foi retornado a seguinte mensagem:

![](https://nfe.io/docs/app/uploads/2020/11/imagem-22.png)

Indicando que o campo **xJust** está inválido, ou seja, não está de acordo com o schema XML. Neste caso, para corrigir, foi necessário retirar a quebra de linha do arquivo.

Abaixo exemplo de XML com a correção:

![](https://nfe.io/docs/app/uploads/2020/11/imagem-22-1.png)

---

## Dúvidas Frequentes

Source: https://nfe.io/docs/duvidas-frequentes/index.md

# Dúvidas Frequentes

---

## Qual código de serviço devo utilizar?

Source: https://nfe.io/docs/duvidas-frequentes/qual-codigo-servico-utilizar/index.md

# Qual código de serviço devo utilizar?

Inicialmente é importante ressaltar que os códigos de serviços são determinados pela prefeitura, com base em suas atividades mencionadas nos CNAEs de seu CNPJ. Sobretudo não possuímos uma base de dados que pode auxiliar esta parametrização. Outro ponto importante é que esta informação deve partir de nosso cliente.

Este código normalmente está mencionado no XML de emissão de NFS-e na tag ou na menção do PDF como Código de Serviço ou Item lista de Serviço ou como dito na prefeitura.

De forma intuitiva acabamos avaliando se ele está correta ou não com base no XML encaminhado para o nosso time do Suporte.

Mencionamos também a necessidade da validação de seu/do contador para seguir com as emissões.

Abaixo mencionamos alguns exemplos:

**Prefeitura do Rio de Janeiro:**

Alguns que estão atrelados ao código 01.01 os seguintes códigos:

010101 - Análise de Sistemas

010102 - Desenvolvimento de Sistemas

010103 - Geração de Programa de Computador sob encomenda, cadastro como desenvolvido no Brasil

010104 - Geração de Programa de Computador sob encomenda

**Prefeitura de São Paulo:**

04219 - Ambulatórios e prontos socorros

Prefeitura de Brasília:

01.01 - Análise e Desenvolvimento de Sistemas.

Por Fim, basta usar os códigos de acordo com o que sua prefeitura liberou e o seu contador orientou, ou conforme mencionado no XML de emissão de uma NFS-e.

---

## Reforma Tributária - Dúvidas Frequentes

Source: https://nfe.io/docs/duvidas-frequentes/reforma-tributaria/index.md

# Reforma Tributária - Dúvidas Frequentes

## Introdução

A Reforma Tributária no Brasil é um processo complexo que visa simplificar e modernizar o sistema de tributos do país. Com a implementação gradual de novos tributos, como o IBS (Imposto sobre Bens e Serviços) e o CBS (Contribuição sobre Bens e Serviços), muitas empresas têm dúvidas sobre como essas mudanças afetarão suas operações diárias.

Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página:

- [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria)

Aqui, nas seções abaixo, reunimos as **perguntas mais frequentes** sobre a Reforma Tributária e suas respostas, fornecendo informações claras e objetivas para que você possa se preparar adequadamente para as mudanças que estão por vir.

## 1 - O que muda a partir de 1º de janeiro? 

A partir de 1º de janeiro começa o período de transição da Reforma Tributária. 
Na prática, nada muda de forma imediata na operação.  Os novos tributos (IBS e CBS) passam a conviver com os atuais, de forma gradual.

## 2 - O que muda na emissão das notas fiscais? 

O fluxo de emissão continua exatamente o mesmo.  O que muda é a estrutura fiscal da nota, que passa a suportar o novo modelo tributário, sem impacto no dia a dia da operação. 

## 3 - Precisamos mudar algo agora? 

Sim, pois o prazo é 31/12/2025.  É importante começar a se preparar o quanto antes, para evitar riscos operacionais no futuro.  A NFE.io oferece suporte e materiais para ajudar na adaptação. 

## 4 - Precisamos alterar algo na API ou nas integrações? 

Sim, **haverá ajustes**. A Reforma introduz **novos campos e regras** (ex.: grupos de IBS/CBS), e isso exige **evolução de payloads/layouts** e validações na integração.

## 5 - Existe risco de parar de emitir notas? 
Não, para empresas que utilizam sistemas preparados.  O risco existe apenas para quem não se adequar ao novo modelo ao longo do tempo. 

## 6 - Qual é o principal ponto de atenção agora? 

Acompanhar e se preparar com antecedência.  A Reforma não é uma virada brusca, mas um processo gradual.  Quem testa e se adapta antes evita riscos operacionais no futuro.

## 7 - Preciso alterar meu sistema para calcular os novos tributos para emitir no modelo da Reforma?

Não. A NFE.io adapta os cálculos e layouts internamente. 

## 8 - A emissão continua funcionando no período de transição? 
Sim. Ao utilizar nosso motor de calculo, e possivel aplicar regras de tributos atuais automaticamente.

## 9 -  A NFE.io acompanha mudanças legais contínuas? 
Sim. Monitoramos e atualizamos a plataforma conforme novas regras e fases da Reforma. 

## 10 - Funciona para empresas de qualquer porte? 
Sim — desde microempresas até operações de milhões de documentos. 

## 11 -  O que acontece se o portal do governo ficar instável? 
Nossa estrutura de retentativas mantém sua operação fluindo sem intervenção manual.

---

## Introdução às Integrações

Source: https://nfe.io/docs/integracoes/index.md

# Integrações

Bem-vindo à documentação de integrações da NFe.io. Abaixo você encontra uma listagem dinâmica de todas as integrações e plugins disponíveis. Use o campo de busca para filtrar rapidamente.

---

## O que é a GestãoDS e como integrar com a NFE.io?

Source: https://nfe.io/docs/integracoes/plataformas/gestaods/index.md

# O que é a GestãoDS?

[GestãoDS](https://gestaods.com.br/ "GestãoDS") é o melhor software para médicos e clinicas com pacientes recorrentes.
Realiza agendamento on-line, controle financeiro, telemedicina, marketing médico e mais uma série de funcionalidades criadas para facilitar a gestão da sua clínica ou consultório.

A GestãoDS é uma empresa de soluções tecnológicas que aplica metodologia através de softwares e educação continuada para profissionais que desejam melhorar a sua performance.

Tem como **visão** atuação global, integrando as áreas de saúde, educação, finanças e simplificando a relação entre as pessoas.

## Para qual tipo de negócio é indicada?
Para simplificar, vamos pegar um exemplo de negócio em que a plataforma GestãoDS pode ajudar e muito. Imagine uma clinica médica ou estética que todo os meses precisa realizar o processo de cobrança para os mais de 50 pacientes.

Para isso essa clinica precisará enviar os boletos para os pacientes mensalmente, depois será preciso acompanhar dia-a-dia no banco para conferir os pagamento que foram efetivados e então emitir as 50 notas fiscais dos clientes que pagaram seus boletos.

Com um software online, a plataforma GestãoDS resolve tudo isso de forma simples e fácil. Você cadastra os 50 pacientes, gerencia as consultas, faz as agendas dos médicos, realiza a cobração, faz a conciliação bancária e por fim emite as notas fiscais.

Resumindo, seu paciente pode te pagar de diferentes formas (cartão de crédito, débito online, boleto bancário), você vai ter mais segurança com as transações e monitorar o crescimento do seu negócio. Tudo estará centralizado em um lugar.

É a plataforma ideal não só para médicos e clinicas, como para todas as empresas da área da saúde que querem ganhar mais tempo no dia a dia, automatizando tarefas simples.

## Como fazer a Integração com a Plataforma Da GestãoDS

## **Ao final desse tutorial, você será capaz de**:
- Integrar a emissão de notas da NFE.io na plataforma da GestãoDS

## Fizemos esse vídeo para lhe auxiliar com a integração da GestãoDS e NFE.io

## Requisitos

- Ser administrador no GestãoDS
- Criar uma conta na NFE.io
- Criar uma empresa
- Fazer upload do certificado digital
- Pegar sua chave de acesso

## Para integrar Com a GestãoDS siga os passos abaixo:

Acessando a NFE.io, na barra superior você deve clicar em **Conta**

![gestaods](https://nfe.io/docs/app/uploads/2021/12/gestaods1.png)


Na sequência, você deve descer até a opção de **"Chaves de acesso".**
![gestaods](https://nfe.io/docs/app/uploads/2021/12/gestaods2.png)

Na tela de chaves de acesso, você copiará a chave que será inserida no GestãoDS.


No GestãoDS, você deve acessar o menu de configurações no canto superior direito, ir em **Integrações > NFE.IO.**

![gestaods](https://nfe.io/docs/app/uploads/2021/12/deepin-screen-recorder_brave-browser_20211203165856.gif)

Acessando a página da integração, a **chave de acesso** copiada será adicionada em **Token Geral**.


Por fim, após adicionar o **Token Geral** e ativar a integração, você irá configurar as informações do emissor. Clicando em **Continuar**, clicará nas engrenagens em laranja, para configurar a emissão.

![gestaods e nfeio](https://nfe.io/docs/app/uploads/2021/12/deepin-screen-recorder_brave-browser_20211203170226.gif)

## O que é cada campo

- **Código CNAE (Classificação Nacional de Atividades Econômicas)**: é uma numeração dada pelo governo para definir as atividades econômicas de uma empresa ativa;

- **Código de serviço municipal**: é um número que define o tipo de serviço prestado pela sua empresa ao seu cliente e segue as regras municipais;

*- **Recomendamos fortemente que você consulte sua contabilidade para saber qual Código de Serviço utilizar***

- **Descrição do serviço**: É o texto que você quer que saia na Nota Fiscal de Serviço;

- **Regime de tributário**: É um conjunto de leis que tem a função de determinar como a empresa pagará pelos seus tributos obrigatórios. Dentre os regimes tributários estão: Lucro Real, Lucro Presumido e Simples Nacional;

- **Inscrição municipal**: É o número de identificação do contribuinte no Cadastro Tributário Municipal;

- **Alíquotas**: Impostos retidos na emissão de Nota Fiscal, inseridas em % (0 - 100). Elas são definidas com base no código de serviço municipal.
a) ISS;
b) IR;
c) PIS;
d) INSS;
e) COFINS;
f) CSL;
g) Outros;


## Ainda tem dúvidas?

Acesse o site da GestãoDS e tire suas dúvidas sobre como podem te ajudar [https://gestaods.com.br/](https://gestaods.com.br/ "https://gestaods.com.br/")

Caso queira falar conosco acesso [NFE.io](http://nfe.io/contato "NFE.io")

---

## Como integrar nossa API de Consulta de CNPJ com o CRM Hubspot via Zapier

Source: https://nfe.io/docs/integracoes/plataformas/hubspot-via-zapier/index.md

# Como integrar nossa API de Consulta de CNPJ com o CRM Hubspot via Zapier

> Nesse artigo te ensinaremos Como integrar nossa API de Consulta de dados dos CNPJ's com o CRM Hubspot via Zapier.

Um dos principais problemas das empresas é uma base de dados e de clientes extremamente bagunçada e sem dados padronizados, dificultando a vida dos times de Marketing, Operações, Vendas e Desenvolvedores.

Somos inconformados com isso e nosso principal objetivo é que você consiga, sem muitos conhecimentos técnicos, integrar nossa API de consulta de dados na Receita Federal de forma fácil e rápida. Padronizando assim sua base de clientes com informações extremamente atualizadas e direto dos servidores da Receita Federal.

## Ao final desse tutorial, você será capaz de:
- Integrar nossa API de Consulta de dados dos CNPJ's ao seu CRM
- Entender melhor sobre normatização e padronização de base
- Conhecer os campos dos dados dos CNPJ's na Receita Federal

## Pré Requisitos

- Criar campos ou propriedades em sua base de dados ou CRM em nosso caso o Hubspot
- Conta no [Zapier](https://zapier.com/ "Zapier")
- Conta em nossa plataforma [criar conta](https://app.nfe.io/ "criar conta")
- Apikey da sua conta

## Passo a passo

### 1º - Criar conta na NFE.io e pegar a sua API key

Primeiro e mais importante passo é criar uma conta na plataforma da [NFE.io](https://app.nfe.io/), esse passo é fundamental para ter acesso a sua API Key.

[Veja aqui](https://nfe.io/docs/documentacao/nossa-plataforma/criar-conta/) como criar a sua conta na plataforma passo a passo, é gratuita e estará em ambiente de teste.

> Logo após a criação da conta, você deverá escolher os serviços que deseja utlizar em nossa plataforma, escolha a opção  *Consulta de Pessoa Jurídica*.

![Consulta de dados](https://nfe.io/docs/app/uploads/2020/10/create-a-new-account-4-e1603997839899.png)


Agora que você já tem uma conta, [siga esse artigo](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/ "siga esse artigo") para encontrar sua Api key ou Chave de Acesso

A figura abaixo mostra a tela onde a Api key fica, Copie a de Dados. Vamos precisar dela logo abaixo.

![API key](https://nfe.io/docs/app/uploads/2020/09/access-key.png)

### 2º - Criar campos ou propriedades em sua base de dados ou CRM em nosso caso o Hubspot

Agora que já sabemos qual é nossa Chave de Acesso ou Api key é hora de padronizarmos os campos que vamos colocar a Informação do CNPJ que queremos consulta, bem como os campos que queremos que sejam preenchidos com a informação da Receita Federal.
Como usamos o Hubspot aqui na NFE.io, precisamos criar no objeto de empresas (lembre-se onde criou pois irá usar mais tarde) apenas os campos abaixo:

- CNPJ (Tipo do Campos texto)
- Status CNPJ (Tipo do Campos texto)
- Capital Social (Tipo do Campos Número)
- CNAE Primário (Tipo do Campos texto)
- Descrição do CNAE Primário (Tipo do Campos texto)
- Inscrição Estadual (Tipo do Campos texto)
- Inscrição Municipal (Tipo do Campos texto)
- Tamanho da Empresa (Tipo do Campos texto)

> Você pode adicionar também outras informações como Nome Fantasia, Razão Social, endereço completo, telefones, emails, nome dos sócios entre outras informações, confira a API completa [aqui](https://nfe.io/docs/desenvolvedores/rest-api/consulta-de-cnpj-v1/#/LegalEntities/V1LegalentitiesBasicInfoByFederalTaxNumberGet "aqui")

No Hubspot você tem que ir em *Configurações* > *Propriedades* > *Propriedades de Empresas* > *Criar propriedade*

![](https://nfe.io/docs/app/uploads/2020/12/print-1-hubspot.png)

### 3º Criar conta no Zapier

Para criar a conta no Zapier [clique aqui](https://zapier.com/sign-up/ "clique aqui"), preencha seu email de trabalho, primeiro nome e ultimo nome. Clique em Sign Up, botão laranjado.
>Caso queira mais sobre o Zapier esse video pode te ajudar [Como Usar o ZAPIER para Automatizar Tarefas Tutorial Básico](https://youtu.be/yvj_K_RwU7s "Como Usar o ZAPIER para Automatizar Tarefas Tutorial Básico")

1. Após a conta criada, vamos conectar o Hubspot na conta do Zapier.
2. Abra o Zapier, clique em *Make a Zap*
3. De um nome ao seu Zap no canto superior esquerdo, o nosso aqui se chamará *Normatização de base do Hubspot com a API NFE*

### 4º Conectar o Hubspot em sua conta e começar a integração

1. No passo 1 Trigger selecione o Hubspot
2. Em *Trigger Event* escolha a opção *New Company Property Change* e clique em Continue

![](https://nfe.io/docs/app/uploads/2020/12/zapier-trigger-event.png)

3. Escolha sua conta da hubspot e clique em Continue
4. Em *Set up trigger*, você tem que colocar o campo CNPJ criado nas propriedades anteriormente. Lembrando que quando houver criação ou alteração dessa informação o comando será disparado.

![](https://nfe.io/docs/app/uploads/2020/12/zapier-set-up-trigger.png)

5. Clique em continuar e depois *Test Trigger* para o Zapier ir no Hubspot procurar essa informação; é muito importante ter esse campo preenchido pelo menos uma vez em sua base ou CRM para poder retornar alguma informação. Dessa forma:

![](https://nfe.io/docs/app/uploads/2020/12/zapier-test-trigger.png)

6. Tudo certo com as informações é hora de configurar a segunda ação dentro do Zapier, na caixa de busca digite *Webhooks by Zapier* e selecione essa opção.

![](https://nfe.io/docs/app/uploads/2020/12/zapier-webhook-by-zapier.png)

7. Na caixa *Action Event* Selecione > GET > Continue

8. Agora vem uma parte muito importante, preste atenção: na opção de URL copie e cole essa informação toda: https://legalentity.api.nfe.io/v2/legalentities/basicInfo/{{cnpj}}?updateaddress=true&apikey={sua apikey aqui}

9. Substitua o `{{cnpj}}` pela propriedade do Hubspot correspondente ao CNPJ e substitua também `{sua apikey aqui}` pela api key que você copiou da sua conta em nossa plataforma. O Zapier deve ficar igual essa imagem aqui.

![](https://nfe.io/docs/app/uploads/2020/12/zapier-colando-certinho-o-caminho.png)

10. Se você fez o passo 9 certinho você estará vendo a mensagem *Test was successful!!* e todos os dados da Receita Federal disponíveis em nossa api estará aparecendo para você.

![](https://nfe.io/docs/app/uploads/2020/12/zapier-teste-successful.png)

11. Agora adicionaremos a 3ª Etapa que é fazer o update com essas informações la no Hubspot, trazendo todos os dados diretos da RFB e normatizando a informação em nossos sistemas.

12. Clique no + azul, selecione o Hubspot e na opção *Action Event* escolha *Update Company* na primeira opção "Object ID" coloque o campo do primeiro passo chamado "1.Company Id:o resultado numerico", depois selecione as propriedades que você criou no Passo 2 desse tutorial. Ficará igual essa imagem

![](https://nfe.io/docs/app/uploads/2020/12/zapier-3-parte-da-integracao.png)

13. Clique em testar e continuar, logo após é só *Turn on Zap* que sua integração já estará funcionando.

> Caso queira ver esse zap é só [clicar aqui](https://zapier.com/shared/fef18b7a5b89d7a027badaa44bc87cc884db3947), Lembrando que a Chave de acesso não é mais válida, você tem que ter sua própria chave.

## Precisa de ajuda?

O que achou do nosso passo a passo? Se precisar de ajuda é só enviar um email para [Suporte](mailto:suporte@nfe.io) com a sua pergunta que ficaremos felizes de responder.

## Quer uma conta em produção?

Para transformar a sua conta em produção, entre em contato conosco pelo e-mail [Comercial](mailto:comercial@nfe.io), que lhe atenderemos com o maior prazer.

---

## O que é a iugu e como integrar com a NFE.io?

Source: https://nfe.io/docs/integracoes/plataformas/iugu/index.md

# O que é iugu
Com a promessa de fazer empresas economizarem tempo e dinheiro, a iugu é uma plataforma pioneira em oferecer uma ferramenta de automatização de operações financeiras, gestão de assinaturas e marketplace.

## Qual a intenção da iugu?
A intenção da iugu é ajudar sua empresa a simplificar os mecanismos de recebimentos e pagamentos. Outro foco é a **gestão de cobranças para reduzir a inadimplência**.

Proporcionar aos clientes uma experiência eficaz e segura de pagamento facilitará a vida do seu departamento financeiro. E o resultado da automação desse processo também terá efeitos positivos na receita da sua empresa.

A plataforma permite que você cobre seus clientes de forma avulsa ou recorrente. Gerenciar contas de pagamentos e gerir assinaturas de serviços virtuais são outros dos serviços oferecidos.

## Quem não está apto a usar a iugu e quem está?

> Se você vende seus produtos offline, a plataforma não poderá ajudar na sua gestão, não estando apto para usar a iugu. Além disso, pessoas físicas e PJs do tipo MEI não são aceitas.

A iugu é voltada para negócios digitais. As ferramentas oferecidas são personalizadas para lojas virtuais, marketplaces, fintechs e vendas por aplicativos.

Vale lembrar que a iugu tem uma lista de produtos e [serviços proibidos.](https://iugu.com/juridico/produtos-e-servicos-proibidos/ "serviços proibidos.") É importante conferir se sua empresa se enquadra nas regulações antes de se informar sobre os benefícios.

## Como fazer a emissão de nota fiscal automaticamente?

É ai que a **[NFE.io](http://nfe.io "NFE.io")** entra. Nós automatizamos toda a emissão de nota fiscal eletronica proveniente das vendas realizadas através da plataforma.
O que você precisa fazer é preencher esse [formulário](https://p.nfe.io/integracao-meios-pagamentos) e seguir os passos descritos nesse link: [click aqui](/documentacao/nossa-plataforma/criar-conta "click aqui")

---

## Como Integrar Emissão de NFE na Mundipagg com NFe.io

Source: https://nfe.io/docs/integracoes/plataformas/mundipagg/index.md

# O que é a Mundipagg?

A Mundipagg acredita que pagamentos online devem ser rápidos e simples!
Querendo sempre que seu cliente foque no que mais importa: **o negócio**. Por isso, desenvolveram sua tecnologia de pagamentos para ajudar a gerar negócios e oferecer soluções de pagamento online. Ou seja, a mundipagg é uma solução de meio de pagamento.

> Pertencente ao grupo Stone.co a Mundipagg, oferece uma gama de soluções para automatizar os processos internos e tornar a operação mais inteligente.

## Uma empresa jovem focada em entregar o melhor resultado

A Mundipagg começou como uma startup em janeiro de 2012, mas já nascendo focados em entregar a melhor experiência em pagamentos graças aos 13 anos de atuação de seus fundadores no mercado.

Criada por empreendedores e feita para quem quer empreender o futuro, a Mundipagg foi pensada para ajudar você a escalar a sua operação com facilidade. Você gerencia o seu negócio e a gente cuida de toda a tecnologia de pagamentos.

São uma empresa do Grupo Stone Co., que possui um ecossistema completo de pagamentos.

## Funcionalidades NFE.io e Mundipagg

- Emissão automática de NFS-e após um pedido pago;
- Emissão automática de NFS-e após uma fatura paga (assinatura);
- Cancelamento automático de NFS-e após um pedido cancelado;
- Cancelamento automático de NFS-e após uma fatura cancelada (assinatura);
- Cancelamento sincronizado na Mundipagg quando NFS-e é cancelada pelo painel do NFe.io;

> Obs.: atualmente o aplicativo do NFe.io disponibilizado pela Mundipagg gera apenas Notas fiscais de Serviço.

## Como integrar?

### Passo 1

Para integrar você precisa obter os dados de acesso no painel do NFe.io (código da empresa e o token de acesso). Veja como obter esses dados na seção obtendo [chaves de autenticação no NFe.io.](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/ "chaves de autenticação no NFe.io.")

### Passo 2

Instale o App do NFe.io pelo Hub para autorizar a aplicação. Durante a instalação serão solicitados alguns dados adicionais. Para ver mais sobre os dados adicionais, veja a seção dados adicionais da integração mais abaixo nesse texto.

> Durante essa etapa você pode negar a permissão de algum evento ao aplicativo, porém essa ação pode desabitar alguma funcionalidade relacionada.

**Pronto!** Sua integração está configurada e pronta para funcionar.

>Obs: Para o funcionamento da integração, não é necessário copiar o Id ou o Token da instalação para nenhum lugar.


## Obtendo chaves de acesso no NFe.io
Para obter as chaves de acesso necessárias, acesse sua conta no NFe.io, no menu empresas, clique em alterar na empresa desejada e em seguida acesse o menu chaves de acesso.

Nessa tela, será possível obter o *Empresa ID* (código da empresa) e o *Nota Fiscal (api.nfe.io)* (API Key).

![obtendo a chave de acesso](https://nfe.io/docs/app/uploads/2020/08/obtendo-a-chave-de-acesso.png)


## Dados adicionais da integração

Durante a instalação serão solicitadas algumas informações adicionais para configurar a sua integração. Você pode editar essas informações posteriormente por aqui mesmo.

É possível criar uma lista de empresas em sua instalação e identificá-las, para que você possa definir por qual empresa emitir a NFe caso seja necessário emitir por mais de um CNPJ conforme demanda. Sendo a interação feita via metadata.

**Importante:** a primeira empresa definida na instação será sempre considerada como empresa default para emissão.

- **API Key:** Chave de autenticação que será usada para comunicação com a API da Nfe.io;
- **Código de serviço na cidade:** Código específico do serviço para seu município que está habilitado em sua inscrição municipal (CCM). Consulte seu contador para saber qual código deve usar;
- **Empresa ID:** Identificação da empresa no sistema da NFe.io;
- **Identificador:** Identificação da empresa na Mundipagg (a sua escolha), para cenários que você possua mais de uma empresa no ambiente do NFe.io, você poderá criar uma lista de empresas identificá-las;
- **Sempre emitir nota fiscal:** Habilita emissão automática após um pedido/fatura paga. Caso esteja desabilitado, será necessário enviar o metadata nfeio_issuance_enabled : true para que a notificação seja enviada;
- **Sempre cancelar nota fiscal:** Habilita cancelamento automático da nota fiscal após um pedido/fatura cancelada. Caso esteja desabilitado, será necessário enviar o metadata nfeio_cancellation_enabled : true para que o cancelamento da cobrança na Mundipagg reflita na nota fiscal;
- **Sempre cancelar cobrança:** Habilita cancelamento automático da cobrança na Mundipagg após uma nota fiscal ser cancelada pela plataforma do NFe.io. Caso esteja desabilitado, será necessário enviar o metadata charge_cancellation_enabled : true para que o cancelamento da nota fiscal reflita na cobrança na Mundipagg;
- **Sempre cancelar cobrança com nota fiscal com erro:** Habilita cancelamento automático da cobrança na Mundipagg após uma nota fiscal não ter sido criada corretamente pela plataforma do NFe.io. Este caso geralmente acontece ao criar uma nota com algum dado inválido, como um CEP que não existe. Caso esteja desabilitado, será necessário enviar o metadata charge_failed_cancellation_enabled : true para que o erro da nota fiscal reflita na cobrança na Mundipagg;
- **Sempre criar nota fiscal com CPF/CNPJ inválido**: Habilita criação automática da nota fiscal mesmo que o documento (CPF ou CNPJ) do cliente estiver errado. Nessa caso, as notas fiscais serão criadas sem nenhum documento nela.
- **Descrição da Nota Fiscal**: Descrição do serviço que será exibida na nota fiscal;
- **CEP padrão**: O CEP padrão é usando quando não encontramos o código do IBGE do CEP passado no pedido. Nesse caso, criaremos a nota fiscal com o CEP que você digitou nesse campo. Caso você deixe vazio, os pedidos com CEP sem código do IBGE não criarão nota fiscal. Normalmente esse problema acontece com CEPs que foram alterados recentemente e ainda não foram atualizados no Correios.

>Se você remover permissões de evento, os recursos associados a eles não serão permitidos. Por exemplo, se a permissão de *Fatura Paga* não for habilitada, a emissão de nota fiscal para assinatura não funcionará.

## Variáveis na Descrição da Nota Fiscal

Você pode utilizar variáveis para personalizar a descrição da sua nota fiscal com dados específicos do seu pedido ou fatura. Para isso basta utilizar os campos abaixo como parte do texto da sua descrição e no momento da emissão da nota iremos substituir pelo informação correta.

`{name}` Nome do comprador;
`{code}` Código do pedido ou da assinatura;
`{items}` Exibe os itens do pedido, 1 item por linha;
`{cycle_start}` Período inicial do ciclo de cobrança da assinatura;
`{cycle_end}` Período final do ciclo de cobrança da assinatura;

## Interagindo via Metadata
Para alguns modelos de negócio mais complexos, pode ser necessário manipular mais informações durante a emissão de uma nota fiscal, como tornar o valor da nota fiscal diferente do total do pedido.

>A sua integração com a Mundipagg pode enviar alguns metadatas para sinalizar algumas ações, como:

`nfeio_increase_flat` Adiciona um valor específico ao valor final da nota fiscal, podendo ser um acréscimo ou desconto (para aplicar um desconto envie um valor negativo). O valor deve ser informado em centavos. Exemplo: -1050 aplica um desconto de R$ 10,50;

`nfeio_increase_percent` Adiciona um valor proporcional ao valor do pedido em % ao valor final da nota fiscal, podendo ser um acréscimo ou desconto (para aplicar um desconto envie um valor negativo). Exemplo: -2.6 aplica um desconto de 2.6% em relação ao valor do pedido;

`nfeio_issuance_enabled` Habilita (true) ou desabilita (false) a criação automática da nota fiscal para a assinatura/pedido criado; Quando passado, esse metadata sobreescreve o campo Sempre emitir nota fiscal;

`nfeio_cancellation_enabled` Habilita (true) ou desabilita (false) o cancelamento automático da nota fiscal para a assinatura/pedido criado; Quando passado, esse metadata sobreescreve o campo Sempre cancelar nota fiscal;

`charge_cancellation_enabled` Habilita (true) ou desabilita (false) o cancelamento automático de uma cobrança caso a nota fiscal referente seja cancelada. Quando passado, esse metadata sobreescreve o campo Sempre cancelar cobrança;

`charge_failed_cancellation_enabled` Habilita (true) ou desabilita (false) o cancelamento automático de uma cobrança caso ocorra algum erro ao criar a nota fiscal referente.

`nfeio_description` Altera a descrição da NFS-e. Caso não enviado e a emissão for baseada em um pedido ou fatura, será inserido os items como descrição. Caso seja baseado apenas em uma cobrança avulsa (sem carrinho de compras) será usado o nome da loja.

`nfeio_discover_real_amount_percent` Caso um NFe tenha um acréscimo percentual no seu valor original, esta propriedade permite que esta informação seja recebida para que o valor original da nota possa ser trabalhado posteriormente.

`nfeio_company_identification` Para casos em que seja necessário emitir NFe em empresas diferentes dentro do NFe.io, deve ser passado o Indentificador da Mundipagg neste campo, para que repassemos os dados deste caso específico para a emissão avulsa.

## Metadatas informativos

Quando nós integarimos com uma cobrança, pedido ou fatura, podemos adicionar metadatas a estes dependendo de algum fluxo e permissões específicas. As permissões necessárias são:

- Atualizar Metadata de Cobrança
- Atualizar Metadata de Pedido
- Atualizar Metadata da Fatura


**Os possíveis metadatas são:**

`nfeio_issuance_error_message` Caso ocorra algum erro no momento de ciração da nota, este campo será preenchido com o motivo do erro;

`nfeio_cancellation_error_message` Caso ocorra algum erro no momento de cancelamento da nota, este campo será preenchido com o motivo do erro;

`nfeio_invoice_id` Identificador da nota fiscal pra a NFe.io;

`nfeio_invoice_number` Número da RPS (Recibo Provisório de Serviços);

`nfeio_invoice_provider_number` Número da nota fiscal;

`nfeio_invoice_status` Status de processamento. Possíveis valores: CancelFailed, IssueFailed, Issued, Cancelled, PullFromCityHall, WaitingCalculateTaxes, WaitingDefineRpsNumber, WaitingSend, WaitingSendCancel, WaitingReturn, WaitingDownload;

`nfeio_issue_date` Data de emissão da nota fiscal;

`nfeio_provider_legal_name` Razão social da sua empresa;

`nfeio_invoice_services_amount` Valor cobrado na nota fiscal;

`nfeio_invoice_iss_amount` Valor do ISS (Imposto Sobre Serviços);

`nfeio_pdf_url` Link para PDF da nota fiscal;

`nfeio_cancel_date` Data de cancelamento da nota fiscal;

---

## O que é o Pagar.me e como integrar com a NFE.io?

Source: https://nfe.io/docs/integracoes/plataformas/pagar-me/index.md

# Pagar.me, seu meio de pagamento digital
O Pagar.me é uma plataforma de meio de pagamento digital pronto para usar. Fácil, simples e intutiva que facilita suas transações financeiras.

## O que é o Pagar.me?

O Pagar.me faz parte do grupo STONE.CO, que tem como o objetivo lhe ajudar a começar suas vendas na internet com alta conversão e a segurança que você precisa para crescer o seu negócio.

## Quais meios de pagamento o Pagar.me aceita?
O Pagar.me trabalha com as principais bandeiras de cartão de crédito —  **Visa, Mastercard, American Express, Elo, Hipercard, Diners, Discover, Aura e JCB — e boleto bancário.**

## Como fazer a emissão de nota fiscal automaticamente?
Como o Pagar.me é um meio de pagamento, eles fazem apendas a transação financeira e não emitem a nota fiscal proveniente da venda realizada.
É ai que a NFE.io entra. Nós automatizamos toda a emissão de nota fiscal eletronica proveniente das vendas realizadas através da plataforma do Pagar.me.
O que você precisa fazer é preencher esse [formulário do pagar.me](https://p.nfe.io/integracao-meios-pagamentos "formulário do pagar.me") e seguir os passos descritos nesse link: [click aqui](https://nfe.io/docs/documentacao/nossa-plataforma/criar-conta/)

## Ficou com dúvidas?
Em caso de dúvidas na integração do Pagar.me com a NFE.io entre em contato conosco que vamos te ajudar!
Contato do comercial `comercial@nfe.io`
Contato do suporte `suporte@nfe.io`

---

## Integração NFe.io + Asaas

Source: https://nfe.io/docs/integracoes/plataformas/pluga/asaas/index.md

A integração entre **NFe.io** e **Asaas** permite automatizar o processo de emissão de notas fiscais eletrônicas
(NF-e) e a gestão de cobranças, facilitando o controle financeiro do seu negócio.

## O que é Asaas?

O Asaas é uma plataforma completa para gestão de cobranças, pagamentos e recebimentos, ideal para empresas que
desejam simplificar a emissão de boletos, cobranças recorrentes e o acompanhamento dos pagamentos.

## Benefícios da integração NFe.io + Asaas

- **Automação completa:** Gere notas fiscais automaticamente a partir das cobranças criadas no Asaas.
- **Redução de erros:** Evite retrabalho e inconsistências ao sincronizar dados entre as duas plataformas.
- **Agilidade no processo:** Emita NF-e de forma rápida e integrada, sem precisar cadastrar manualmente as
informações.
- **Controle financeiro unificado:** Tenha visibilidade consolidada das cobranças e notas fiscais emitidas.

## Como funciona a integração?

1. **Criação da cobrança no Asaas:** Quando uma cobrança é gerada na plataforma Asaas, os dados são automaticamente
enviados para o NFe.io.
2. **Emissão da NF-e:** Com as informações da cobrança, o NFe.io emite a nota fiscal eletrônica correspondente.
3. **Sincronização dos dados:** As informações da nota fiscal são atualizadas no Asaas, mantendo o controle
financeiro alinhado.

## Como configurar?

Para configurar a integração entre NFe.io e Asaas, siga os passos abaixo:

1. Acesse sua conta no [Pluga.co][1] e vá até a seção de integrações.
2. Selecione a opção Asaas e conecte sua conta utilizando as credenciais da API Asaas.
3. Configure as regras de emissão automática de notas fiscais conforme sua necessidade.
4. Salve as configurações e comece a emitir NF-e automaticamente a partir das cobranças do Asaas.

[1]: https://pluga.co/ferramentas/nfe_io/integracao/asaas/

---

## Integração NFe.io + Bling

Source: https://nfe.io/docs/integracoes/plataformas/pluga/bling/index.md

A integração entre **NFe.io** e **Bling** permite automatizar a emissão de notas fiscais eletrônicas (**NF-e**)
a partir de pedidos e vendas registrados no ERP, reduzindo tarefas manuais e acelerando seu processo fiscal.

## O que é Bling?

O **Bling** é um sistema ERP que integra vendas, estoque, faturamento e financeiro, muito utilizado por pequenas e
médias empresas para organizar a operação e centralizar os dados do negócio.

## Benefícios da integração NFe.io + Bling

- **Automação fiscal:** Emita **NF-e** automaticamente a partir de pedidos e vendas do Bling.
- **Redução de erros:** Evite retrabalho com mapeamento de dados entre ERP e NFe.io.
- **Agilidade operacional:** Ganhe tempo eliminando digitação dupla e rotinas manuais.
- **Informações consistentes:** Mantenha dados sincronizados entre as plataformas.

## Como funciona a integração?

1. **Evento no Bling:** Quando um pedido/venda é criado ou atualizado conforme suas regras, os dados são enviados pela
   Pluga para o NFe.io.
2. **Emissão da nota:** O NFe.io utiliza essas informações para emitir a **NF-e** correspondente.
3. **Acompanhamento:** Você acompanha o status da automação na Pluga e a situação fiscal no NFe.io.

## Como configurar?

Para configurar a integração entre NFe.io e Bling via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a seção de integrações.
2. Selecione **Bling** e **NFe.io**, conectando suas contas (use suas chaves de API quando solicitado).
3. Escolha o gatilho no Bling (ex.: novo pedido, pedido pago, nova venda) e a ação no NFe.io (ex.: emitir **NF-e**).
4. Mapeie os campos obrigatórios (destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos).
5. Salve e ative a automação para começar a emitir notas automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/bling/

---

## Integração NFe.io + Eduzz

Source: https://nfe.io/docs/integracoes/plataformas/pluga/eduzz/index.md

A integração entre **NFe.io** e **Eduzz** permite emitir automaticamente **NFS-e** a partir de eventos de venda,
reduzindo tarefas manuais e garantindo conformidade fiscal de forma simples.

## O que é a Eduzz?

A **Eduzz** é uma plataforma de soluções para infoprodutores e negócios digitais, oferecendo ferramentas para
vendas online, gestão de assinaturas, checkout e controle de recebíveis.

## Benefícios da integração NFe.io + Eduzz

- **Emissão automática de NFS-e:** Gere suas notas de serviço sem intervenções manuais após a aprovação da venda.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre plataformas.
- **Agilidade e conformidade:** Acelere o ciclo de faturamento mantendo os requisitos fiscais atualizados.
- **Visão integrada:** Centralize os dados de vendas e notas emitidas.

## Como funciona a integração?

1. **Evento na Eduzz:** Quando uma venda é aprovada (ou outro evento configurado), a Pluga envia os dados para o NFe.io.
2. **Emissão da NFS-e:** O NFe.io utiliza as informações do pedido/cliente para emitir a **NFS-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga, e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns na Eduzz:

- Venda/fatura paga
- Fatura cancelada
- Fatura expirada

Ações no NFe.io:

- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Eduzz via Pluga, siga os passos:

1. Acesse sua conta no [Pluga][1] e vá até a integração **Eduzz + NFe.io**.
2. Conecte suas contas (utilize as credenciais e chaves de API solicitadas).
3. Selecione o gatilho na Eduzz (ex.: venda aprovada) e a ação no NFe.io (ex.: emitir **NFS-e**).
4. Mapeie os campos obrigatórios da NFS-e, como tomador, serviço, município, CNAE/código de serviço, alíquota de ISS e outras regras fiscais.
5. Salve e ative a automação para começar a emitir NFS-e automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/eduzz/

---

## Integração NFe.io + Excel

Source: https://nfe.io/docs/integracoes/plataformas/pluga/excel/index.md

Com a integração entre **NFe.io** e **Excel** via Pluga, você emite **NF-e** ou **NFS-e** automaticamente quando novas
linhas são adicionadas ou atualizadas na sua planilha — sem código e com menos trabalho manual.

## O que é o Excel?

O **Microsoft Excel** é uma ferramenta de planilhas amplamente utilizada para organizar dados, realizar cálculos e
acompanhar processos do dia a dia das empresas.

## Benefícios da integração NFe.io + Excel

- **Automação fiscal a partir da planilha:** Gere **NF-e** ou **NFS-e** com base nos dados de cada linha.
- **Menos erros:** Evite retrabalho e divergências ao aproveitar o mapeamento direto dos campos.
- **Agilidade operacional:** Elimine tarefas manuais repetitivas e ganhe produtividade.
- **Flexibilidade:** Modele sua planilha para atender às regras fiscais do seu negócio.

## Como funciona a integração?

1. **Evento no Excel:** Ao adicionar ou atualizar uma linha (conforme o gatilho configurado), a Pluga envia os dados
   para o NFe.io.
2. **Emissão da nota:** O NFe.io utiliza as informações mapeadas para emitir a **NF-e** ou **NFS-e**.
3. **Acompanhamento:** Você acompanha o status da automação na Pluga e consulta a situação da nota no NFe.io.

Gatilhos típicos no Excel:

- Nova linha adicionada
- Linha atualizada

Ações no NFe.io:

- Emitir **NF-e**
- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Excel via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e escolha a integração **Excel + NFe.io**.
2. Conecte suas contas do Excel e do NFe.io (utilize as credenciais e chaves de API quando solicitado).
3. Selecione o gatilho no Excel (ex.: nova linha em uma aba específica) e a ação no NFe.io (emitir **NF-e** ou **NFS-e**).
4. Mapeie os campos obrigatórios:
   - Para **NF-e**: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
   - Para **NFS-e**: tomador, serviço, município, CNAE/código de serviço, alíquota de ISS, regime tributário e outras regras.
5. Salve e ative a automação para começar a emitir notas automaticamente a partir da sua planilha.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/excel/

---

## Integração NFe.io + Google Forms

Source: https://nfe.io/docs/integracoes/plataformas/pluga/google-forms/index.md

Com a integração entre **NFe.io** e **Google Forms** via Pluga, você emite **NF-e** ou **NFS-e** automaticamente
sempre que uma nova resposta é recebida — sem código e com mapeamento direto dos campos do formulário.

## O que é o Google Forms?

O **Google Forms** é uma ferramenta gratuita do Google para criação de formulários e pesquisas online, amplamente
utilizada para coletar dados de clientes, inscrições, pedidos e solicitações diversas.

## Benefícios da integração NFe.io + Google Forms

- **Automação fiscal a partir das respostas:** Gere **NF-e** ou **NFS-e** com base nos dados enviados pelos respondentes.
- **Menos erros e retrabalho:** Evite digitação dupla e inconsistências aproveitando o mapeamento de campos.
- **Agilidade no processo:** Reduza tarefas manuais e acelere o faturamento.
- **Flexibilidade:** Modele o formulário conforme as regras fiscais e dados necessários do seu negócio.

## Como funciona a integração?

1. **Evento no Google Forms:** Quando uma nova resposta é enviada (conforme o gatilho configurado), a Pluga encaminha
   os dados para o NFe.io.
2. **Emissão da nota:** O NFe.io utiliza as informações mapeadas para emitir a **NF-e** ou **NFS-e**.
3. **Acompanhamento:** O status da automação é exibido na Pluga e a situação da nota pode ser consultada no NFe.io.

Gatilhos típicos no Google Forms:

- Nova resposta recebida

Ações no NFe.io:

- Emitir **NF-e**
- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Google Forms via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e selecione a integração **Google Forms + NFe.io**.
2. Conecte suas contas (autorize o Google Forms e informe a chave de API do NFe.io quando solicitado).
3. Escolha o gatilho no Google Forms (ex.: nova resposta em um formulário específico) e a ação no NFe.io (emitir **NF-e** ou **NFS-e**).
4. Mapeie os campos obrigatórios:
   - Para **NF-e**: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
   - Para **NFS-e**: tomador, serviço, município, CNAE/código de serviço, alíquota de ISS, regime tributário e outras regras.
5. Salve e ative a automação para começar a emitir notas automaticamente a partir das respostas do formulário.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/google-forms/

---

## Integração NFe.io + Google Sheets

Source: https://nfe.io/docs/integracoes/plataformas/pluga/google-sheets/index.md

Com a integração entre **NFe.io** e **Google Sheets** via Pluga, você emite **NF-e** ou **NFS-e** automaticamente quando
novas linhas são adicionadas ou atualizadas na sua planilha — sem código e com mapeamento direto dos campos.

## O que é o Google Sheets?

O **Google Sheets** é a ferramenta de planilhas em nuvem do Google, ideal para organizar dados, colaborar em tempo real
e acompanhar processos do dia a dia das empresas.

## Benefícios da integração NFe.io + Google Sheets

- **Automação fiscal a partir da planilha:** Gere **NF-e** ou **NFS-e** com base nas informações de cada linha.
- **Menos erros operacionais:** Elimine digitação duplicada e inconsistências entre sistemas.
- **Agilidade e produtividade:** Reduza tarefas manuais repetitivas e acelere o faturamento.
- **Flexibilidade:** Modele a planilha conforme as regras fiscais e dados do seu negócio.

## Como funciona a integração?

1. **Evento no Google Sheets:** Ao adicionar ou atualizar uma linha (conforme o gatilho configurado), a Pluga envia
   os dados para o NFe.io.
2. **Emissão da nota:** O NFe.io utiliza as informações mapeadas para emitir a **NF-e** ou **NFS-e**.
3. **Acompanhamento:** O status da automação é exibido na Pluga e a situação da nota pode ser consultada no NFe.io.

Gatilhos típicos no Google Sheets:

- Nova linha adicionada
- Linha atualizada

Ações no NFe.io:

- Emitir **NF-e**
- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Google Sheets via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e selecione a integração **Google Sheets + NFe.io**.
2. Conecte suas contas (autorize o Google Sheets e informe a chave de API do NFe.io quando solicitado).
3. Escolha o gatilho no Google Sheets (ex.: nova linha em uma aba específica) e a ação no NFe.io (emitir **NF-e** ou **NFS-e**).
4. Mapeie os campos obrigatórios:
   - Para **NF-e**: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
   - Para **NFS-e**: tomador, serviço, município, CNAE/código de serviço, alíquota de ISS, regime tributário e outras regras.
5. Salve e ative a automação para começar a emitir notas automaticamente a partir da sua planilha.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/google-sheets/

---

## Integração NFe.io + Hotmart

Source: https://nfe.io/docs/integracoes/plataformas/pluga/hotmart/index.md

A integração entre **NFe.io** e **Hotmart** permite emitir automaticamente **NFS-e** com base em eventos de vendas e
assinaturas, reduzindo tarefas manuais e garantindo conformidade fiscal para seu negócio digital.

## O que é a Hotmart?

A **Hotmart** é uma plataforma completa para criação, venda e distribuição de produtos digitais e assinaturas, com
recursos de pagamentos, checkout, área de membros, afiliados e gestão de recorrência.

## Benefícios da integração NFe.io + Hotmart

- **Emissão automática de NFS-e:** Gere notas de serviço sem intervenção manual após a aprovação da venda/assinatura.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre plataformas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão integrada:** Centralize os dados de vendas e notas emitidas.

## Como funciona a integração?

1. **Evento na Hotmart:** Quando uma venda/assinatura dispara um gatilho (ex.: venda aprovada), a Pluga envia os dados
   para o NFe.io.
2. **Emissão da NFS-e:** O NFe.io utiliza as informações do pedido/cliente para emitir a **NFS-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga, e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns na Hotmart:

- Venda aprovada
- Venda completa
- Assinatura paga
- Reembolso
- Chargeback

Ações no NFe.io:

- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Hotmart via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **Hotmart + NFe.io**.
2. Conecte suas contas (autorize a Hotmart e informe a chave de API do NFe.io quando solicitado).
3. Selecione o gatilho na Hotmart (ex.: venda aprovada) e a ação no NFe.io (ex.: emitir **NFS-e**).
4. Mapeie os campos obrigatórios da NFS-e: tomador, serviço, município, CNAE/código de serviço, alíquota de ISS, regime
   tributário e demais regras fiscais necessárias.
5. Salve e ative a automação para começar a emitir NFS-e automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/hotmart/

---

## Integrações NFe.io + Pluga

Source: https://nfe.io/docs/integracoes/plataformas/pluga/intro/index.md

A Pluga é uma plataforma de automações que conecta aplicações — como ERPs, planilhas, gateways de pagamento e ferramentas de assinatura —
sem a necessidade de desenvolvimento. Com a Pluga você monta fluxos ("automações") que reagenciam a eventos (gatilhos) em uma ferramenta
para executar ações em outra.

A integração entre o NFe.io e a Pluga permite automatizar a emissão de NF-e e NFS-e a partir de eventos vindos de centenas de apps
— por exemplo: quando uma linha é adicionada no Google Sheets, quando um pedido é criado no Bling, quando um pagamento é confirmado no
Stripe, ou quando um webhook personalizado chega ao Pluga.

## Por que usar NFe.io + Pluga

- Automação sem código: crie fluxos para emitir notas automaticamente sem desenvolver integrações.
- Flexibilidade: conecte sistemas que não têm integração nativa com NFe.io por meio de conectores da Pluga (Google Sheets, Bling, Stripe, Superlógica, etc.).
- Redução de erros operacionais: elimine digitação manual e garanta consistência entre vendas/cobranças e emissão fiscal.
- Conformidade e segurança: a emissão continua sendo feita pelo NFe.io, mantendo regras fiscais, validações e armazenamento conforme necessário.

## Principais gatilhos e ações

Gatilhos típicos na Pluga (exemplos):
- Nova linha adicionada (Google Sheets)
- Novo pedido/vença no ERP (Bling)
- Pagamento aprovado (Stripe)
- Cobrança liquidada / assinatura criada (Superlógica)
- Webhook recebido (Pluga Webhooks)

Ações disponíveis no NFe.io (via Pluga):
- Emitir NF-e (documento fiscal de produto)
- Emitir NFS-e (nota de serviço)

## Casos de uso comuns

- Automatizar a emissão de NF-e a partir de pedidos do seu ERP.
- Gerar NFS-e automaticamente quando um pagamento recorrente é conciliado.
- Transformar linhas de uma planilha em notas fiscais para simplificar faturamento em volume.
- Receber dados via webhooks de sistemas próprios e emitir notas sem criar integrações customizadas.

## Como configurar (resumo rápido)

1. Acesse seu painel na Pluga e escolha uma integração que envolva NFe.io (ex.: Google Sheets + NFe.io, Bling + NFe.io).
2. Conecte as contas necessárias (autorize Google/Stripe/Bling/Superlógica quando solicitado e informe a chave de API do NFe.io).
3. Configure o gatilho (quando a automação deve rodar) e a ação no NFe.io (emitir NF-e ou NFS-e).
4. Mapeie os campos obrigatórios (destinatário, itens, tributos para NF-e; tomador, serviço e município para NFS-e) de acordo com sua operação fiscal.
5. Salve, ative e faça testes com eventos reais ou simulações para validar os mapeamentos.

### Boas práticas

- Sempre teste com dados de homologação antes de ativar em produção.
- Mapeie e valide todos os campos fiscais obrigatórios; a Pluga faz a entrega dos dados, mas o NFe.io executa as validações fiscais.
- Documente os fluxos e mantenha os responsáveis informados sobre alterações que possam afetar o faturamento.

## Dúvidas e suporte

Se precisar de ajuda para configurar uma automação específica, consulte as páginas desta seção (ex.: Google Sheets, Bling, Stripe, Superlógica, Pluga Webhooks)
ou entre em contato com o suporte da Pluga e do NFe.io.

[Ver integrações no Pluga](https://pluga.co/ferramentas/nfe-io/integracao/)

---

## Integração NFe.io + Iugu

Source: https://nfe.io/docs/integracoes/plataformas/pluga/iugu/index.md

A integração entre **NFe.io** e **Iugu** permite emitir automaticamente **NFS-e** com base em eventos de cobrança e
assinaturas, reduzindo tarefas manuais e mantendo a conformidade fiscal do seu negócio.

## O que é a iugu?

A **Iugu** é uma plataforma de pagamentos focada em cobranças, faturas e assinaturas, com soluções para automação
financeira, conciliação e recebimentos recorrentes.

## Benefícios da integração NFe.io + Iugu

- **Emissão automática de NFS-e:** Gere notas de serviço sem intervenção manual após a aprovação de faturas/assinaturas.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre sistemas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais sempre atualizadas.
- **Visão integrada:** Centralize os dados de cobranças e notas emitidas.

## Como funciona a integração?

1. **Evento na iugu:** Quando uma fatura/assinatura dispara um gatilho (ex.: fatura paga), a Pluga envia os dados
   para o NFe.io.
2. **Emissão da NFS-e:** O NFe.io utiliza as informações do cliente e da cobrança para emitir a **NFS-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga, e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns na iugu:

- Fatura paga
- Fatura cancelada
- Fatura expirada
- Assinatura paga
- Assinatura cancelada

Ações no NFe.io:

- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e iugu via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **iugu + NFe.io**.
2. Conecte suas contas (autorize a iugu e informe a chave de API do NFe.io quando solicitado).
3. Selecione o gatilho na iugu (ex.: fatura paga) e a ação no NFe.io (ex.: emitir **NFS-e**).
4. Mapeie os campos obrigatórios da NFS-e: tomador, serviço, município, CNAE/código de serviço, alíquota de ISS, regime
   tributário e outras regras fiscais necessárias.
5. Salve e ative a automação para começar a emitir NFS-e automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/iugu/

---

## Integração NFe.io + Kobana (Boleto Simples)

Source: https://nfe.io/docs/integracoes/plataformas/pluga/kobana/index.md

A integração entre **NFe.io** e **Kobana (Boleto Simples)** permite emitir automaticamente **NFS-e** com base em
cobranças por boleto e assinaturas, reduzindo tarefas manuais e mantendo a conformidade fiscal.

## O que é a Kobana (Boleto Simples)?

A **Kobana** (antigo **Boleto Simples**) oferece soluções de emissão de boletos, gestão de assinaturas e automação de
cobranças, facilitando a operação financeira de empresas.

## Benefícios da integração NFe.io + Kobana

- **Emissão automática de NFS-e:** Gere notas de serviço após a confirmação de pagamento do boleto/assinatura.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre plataformas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão integrada:** Centralize os dados de cobranças e notas emitidas.

## Como funciona a integração?

1. **Evento na Kobana:** Quando um pagamento ou evento de assinatura dispara um gatilho (ex.: boleto pago), a Pluga
   envia os dados para o NFe.io.
2. **Emissão da NFS-e:** O NFe.io utiliza as informações do cliente e da cobrança para emitir a **NFS-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga, e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns na Kobana:

- Boleto pago
- Assinatura paga
- Boleto cancelado/expirado

Ações no NFe.io:

- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Kobana via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **Boleto Simples (Kobana) + NFe.io**.
2. Conecte suas contas (autorize a Kobana e informe a chave de API do NFe.io quando solicitado).
3. Selecione o gatilho na Kobana (ex.: boleto pago) e a ação no NFe.io (ex.: emitir **NFS-e**).
4. Mapeie os campos obrigatórios da NFS-e: tomador, serviço, município, código de serviço/CNAE, alíquota de ISS,
   regime tributário e outras regras fiscais necessárias.
5. Salve e ative a automação para começar a emitir NFS-e automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/boleto-simples/

---

## Integração NFe.io + Loja Integrada

Source: https://nfe.io/docs/integracoes/plataformas/pluga/loja-integrada/index.md

A integração entre **NFe.io** e **Loja Integrada** permite emitir automaticamente **NF-e** com base em eventos de
pedido e pagamento, reduzindo tarefas manuais e agilizando seu faturamento no e-commerce.

## O que é a Loja Integrada?

A **Loja Integrada** é uma plataforma de e-commerce que facilita a criação e gestão de lojas virtuais, com recursos
para pedidos, meios de pagamento, frete e integrações diversas.

## Benefícios da integração NFe.io + Loja Integrada

- **Emissão automática de NF-e:** Gere notas fiscais ao aprovar pagamentos e confirmar pedidos.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre sistemas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão integrada:** Centralize os dados de pedidos e notas emitidas.

## Como funciona a integração?

1. **Evento na Loja Integrada:** Quando um pedido é criado/pago (conforme seu gatilho), a Pluga envia os dados para o NFe.io.
2. **Emissão da NF-e:** O NFe.io utiliza as informações do pedido/cliente para emitir a **NF-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga, e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns na Loja Integrada:

- Pedido pago
- Pedido criado
- Pedido cancelado

Ações no NFe.io:

- Emitir **NF-e**

## Como configurar?

Para configurar a integração entre NFe.io e Loja Integrada via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **Loja Integrada + NFe.io**.
2. Conecte suas contas (autorize a Loja Integrada e informe a chave de API do NFe.io quando solicitado).
3. Selecione o gatilho na Loja Integrada (ex.: pedido pago) e a ação no NFe.io (ex.: emitir **NF-e**).
4. Mapeie os campos obrigatórios da NF-e: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
5. Salve e ative a automação para começar a emitir NF-e automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/loja-integrada/

---

## Integração NFe.io + Magento 1.x

Source: https://nfe.io/docs/integracoes/plataformas/pluga/magento/index.md

A integração entre **NFe.io** e **Magento 1.x** via **Pluga** permite emitir automaticamente **NF-e** com base em
eventos de pedido e pagamento, reduzindo tarefas manuais e agilizando o faturamento do seu e-commerce.

## O que é o Magento 1.x?

O **Magento 1.x** é uma plataforma de e-commerce robusta e flexível, amplamente utilizada para a criação e gestão de
lojas virtuais, com recursos para catálogo, carrinho, pagamento, entregas e integrações diversas.

## Benefícios da integração NFe.io + Magento 1.x

- **Emissão automática de NF-e:** Gere notas fiscais sempre que um pedido for criado ou um pagamento for aprovado.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre sistemas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão integrada:** Centralize os dados de pedidos e notas emitidas.

## Como funciona a integração?

1. **Evento no Magento 1.x:** Quando um pedido é criado/pago (conforme o gatilho configurado), a Pluga envia os dados para o NFe.io.
2. **Emissão da NF-e:** O NFe.io utiliza as informações do pedido/cliente para emitir a **NF-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga, e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns no Magento 1.x:

- Pedido pago
- Pedido criado
- Pedido cancelado

Ações no NFe.io:

- Emitir **NF-e**

## Como configurar?

Para configurar a integração entre NFe.io e Magento 1.x via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **Magento + NFe.io**.
2. Conecte suas contas (autorize o Magento 1.x e informe a chave de API do NFe.io quando solicitado).
3. Selecione o gatilho no Magento 1.x (ex.: pedido pago) e a ação no NFe.io (ex.: emitir **NF-e**).
4. Mapeie os campos obrigatórios da NF-e: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
5. Salve e ative a automação para começar a emitir NF-e automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/magento/

---

## Integração NFe.io + Mercado Pago

Source: https://nfe.io/docs/integracoes/plataformas/pluga/mercado-pago/index.md

A integração entre **NFe.io** e **Mercado Pago** permite automatizar o processo de emissão de **notas fiscais eletrônicas (NF-e)**
a partir de cobranças e pagamentos aprovados, reduzindo tarefas manuais e facilitando o controle fiscal do seu negócio.

## O que é o Mercado Pago?

O **Mercado Pago** é uma plataforma completa de pagamentos, que oferece soluções para recebimento online e presencial,
checkout transparente, links de pagamento, assinaturas e conciliação de transações.

## Benefícios da integração NFe.io + Mercado Pago

- **Automação completa:** Gere notas fiscais automaticamente a partir de pagamentos aprovados no Mercado Pago.
- **Redução de erros:** Evite retrabalho e inconsistências ao sincronizar dados entre as plataformas.
- **Agilidade no processo:** Emita NF-e de forma rápida e integrada, sem precisar cadastrar manualmente as informações.
- **Visão centralizada:** Tenha visibilidade consolidada das cobranças e notas fiscais emitidas.

## Como funciona a integração?

1. **Pagamento aprovado no Mercado Pago:** Quando uma cobrança é paga/confirmada, os dados são automaticamente enviados para o NFe.io via Pluga.
2. **Emissão da NF-e:** Com as informações do pagamento e do comprador, o NFe.io emite a nota fiscal eletrônica correspondente.
3. **Acompanhamento:** Consulte o status da automação na Pluga e o status fiscal da nota dentro do NFe.io.

## Como configurar?

Para configurar a integração entre NFe.io e Mercado Pago via Pluga, siga os passos abaixo:

1. Acesse sua conta no [Pluga.co][1] e vá até a seção de integrações.
2. Selecione **Mercado Pago** e conecte sua conta autorizando o acesso.
3. Conecte sua conta do **NFe.io** informando a chave de API quando solicitado.
4. Configure as regras de emissão automática de notas fiscais conforme sua necessidade (ex.: pagamento aprovado).
5. Salve as configurações e comece a emitir **NF-e** automaticamente a partir dos pagamentos do Mercado Pago.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/mercado-pago/

---

## Integração NFe.io + Pagar.me

Source: https://nfe.io/docs/integracoes/plataformas/pluga/pagar-me/index.md

A integração entre **NFe.io** e **Pagar.me** permite automatizar o processo de emissão de **notas fiscais eletrônicas (NF-e)**
a partir de cobranças e pagamentos aprovados, reduzindo tarefas manuais e facilitando o controle fiscal do seu negócio.

## O que é o Pagar.me?

O **Pagar.me** é uma plataforma completa de pagamentos, com soluções para e-commerce e negócios recorrentes, incluindo
checkout transparente, links de pagamento, split de pagamentos, assinaturas e conciliação.

## Benefícios da integração NFe.io + Pagar.me

- **Automação completa:** Gere notas fiscais automaticamente a partir de pagamentos aprovados no Pagar.me.
- **Redução de erros:** Evite retrabalho e inconsistências ao sincronizar dados entre as plataformas.
- **Agilidade no processo:** Emita **NF-e** de forma rápida e integrada, sem precisar cadastrar manualmente as informações.
- **Visão centralizada:** Tenha visibilidade consolidada das cobranças e notas fiscais emitidas.

## Como funciona a integração?

1. **Pagamento aprovado no Pagar.me:** Quando uma cobrança é paga/confirmada, os dados são enviados para o NFe.io via Pluga.
2. **Emissão da NF-e:** Com as informações do pagamento e do comprador, o NFe.io emite a nota fiscal eletrônica correspondente.
3. **Acompanhamento:** Consulte o status da automação na Pluga e o status fiscal da nota dentro do NFe.io.

Gatilhos comuns no Pagar.me:

- Pagamento aprovado
- Pagamento criado
- Assinatura criada/paga
- Pagamento reembolsado

Ações no NFe.io:

- Emitir **NF-e**

## Como configurar?

Para configurar a integração entre NFe.io e Pagar.me via Pluga, siga os passos abaixo:

1. Acesse sua conta no [Pluga.co][1] e vá até a integração **Pagar.me + NFe.io**.
2. Conecte sua conta do **Pagar.me** autorizando o acesso.
3. Conecte sua conta do **NFe.io** informando a chave de API quando solicitado.
4. Selecione o gatilho (ex.: pagamento aprovado) e a ação (emitir **NF-e**) e faça o mapeamento dos campos obrigatórios:
   - Destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
5. Salve as configurações e comece a emitir **NF-e** automaticamente a partir dos pagamentos do Pagar.me.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/pagar-me/

---

## Integração NFe.io + Pipefy

Source: https://nfe.io/docs/integracoes/plataformas/pluga/pipefy/index.md

A integração entre **NFe.io** e **Pipefy** via **Pluga** permite emitir automaticamente **NFS-e** com base em eventos do seu
processo — como criação de cards, movimentação de fase e finalização — reduzindo tarefas manuais e garantindo
conformidade fiscal.

## O que é o Pipefy?

O **Pipefy** é uma plataforma de gestão de processos (BPM/Workflow) que organiza atividades em pipes e fases, permitindo
padronizar fluxos, automatizar tarefas e centralizar informações do seu time.

## Benefícios da integração NFe.io + Pipefy

- **Emissão automática de NFS-e:** Gere notas de serviço ao criar, mover ou finalizar cards conforme suas regras.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre plataformas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão integrada:** Centralize o status das automações na Pluga e das notas no NFe.io.

## Como funciona a integração?

1. **Evento no Pipefy:** Quando um card é criado, movido para uma fase específica ou finalizado, a Pluga envia os dados
   configurados para o NFe.io.
2. **Emissão da NFS-e:** O NFe.io utiliza as informações do card (tomador/cliente, serviço, valores, município etc.)
   para emitir a **NFS-e**.
3. **Acompanhamento:** A automação pode ser monitorada na Pluga e a situação fiscal da nota é consultável no NFe.io.

Gatilhos comuns no Pipefy:

- Card criado
- Card movido de fase
- Card finalizado

Ações no NFe.io:

- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Pipefy via Pluga, siga os passos abaixo:

1. Acesse sua conta no [Pluga.co][1] e selecione a integração **Pipefy + NFe.io**.
2. Conecte sua conta do **Pipefy** e autorize o acesso solicitado.
3. Conecte sua conta do **NFe.io** informando a chave de API quando solicitado.
4. Escolha o gatilho no Pipefy (ex.: card movido para a fase "Faturar") e a ação no NFe.io (emitir **NFS-e**).
5. Mapeie os campos obrigatórios da NFS-e: tomador, serviço, município, código de serviço/CNAE, alíquota de ISS,
   regime tributário e demais regras fiscais compatíveis com sua operação.
6. Salve e ative a automação para começar a emitir NFS-e automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/pipefy/

---

## Integração NFe.io + Pluga Webhooks

Source: https://nfe.io/docs/integracoes/plataformas/pluga/pluga-webhooks/index.md

A integração entre **NFe.io** e **Pluga Webhooks** permite emitir automaticamente **NF-e** e **NFS-e** com base nas
notificações recebidas via webhook — conectando qualquer ferramenta que envie eventos HTTP ao seu fluxo fiscal,
sem escrever código.

## O que é o Pluga Webhooks?

O **Pluga Webhooks** é o conector da Pluga que recebe notificações (eventos) de outras ferramentas por meio de chamadas
HTTP e as transforma em dados utilizáveis em automações, permitindo criar fluxos sem integração direta nativa.

## Benefícios da integração NFe.io + Pluga Webhooks

- **Automação por eventos:** Emita **NF-e/NFS-e** assim que um webhook for recebido pelo Pluga.
- **Flexibilidade máxima:** Conecte sistemas próprios ou ferramentas sem integração nativa na Pluga.
- **Menos retrabalho:** Evite processos manuais e inconsistências ao mapear os campos de nota diretamente.
- **Conformidade garantida:** Mantenha as regras fiscais atualizadas no NFe.io, com emissão segura e rastreável.

## Como funciona a integração?

1. **Webhook recebido no Pluga:** Ao receber um evento HTTP (ex.: pedido pago, assinatura criada), o Pluga processa o
   payload e envia os dados mapeados para o NFe.io.
2. **Emissão da nota:** O NFe.io utiliza as informações para emitir a **NF-e** ou **NFS-e** conforme sua configuração.
3. **Acompanhamento:** Você acompanha o status da automação na Pluga e a situação fiscal da nota no NFe.io.

Gatilhos no Pluga Webhooks:

- Webhook recebido

Ações no NFe.io:

- Emitir **NF-e**
- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Pluga Webhooks, siga os passos:

1. Acesse sua conta no [Pluga][1] e selecione a integração **Pluga Webhooks + NFe.io**.
2. Gere um endpoint de **Webhook** no Pluga e configure sua ferramenta/sistema para enviar o evento HTTP para esse URL.
3. Conecte sua conta do **NFe.io** informando a chave de API quando solicitado.
4. Escolha a ação no NFe.io (emitir **NF-e** ou **NFS-e**) e faça o mapeamento dos campos obrigatórios:
   - Para **NF-e**: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
   - Para **NFS-e**: tomador, serviço, município, código de serviço/CNAE, alíquota de ISS, regime de tributação etc.
5. Salve e ative a automação. Ao enviar um evento de teste para o webhook, a emissão será executada conforme o mapeamento.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/pluga-webhooks/

---

## Integração NFe.io + Squarespace

Source: https://nfe.io/docs/integracoes/plataformas/pluga/squarespace/index.md

A integração entre **NFe.io** e **Squarespace** via **Pluga** permite emitir automaticamente **NF-e** com base em eventos
como criação de pedidos, pagamentos aprovados e entregas, reduzindo tarefas manuais e acelerando seu faturamento no e-commerce.

## O que é o Squarespace?

O **Squarespace** é uma plataforma completa para criação de sites e lojas virtuais, com recursos de catálogo, carrinho,
pagamentos, entregas e integrações para levar seu negócio do CMS ao checkout com qualidade e design profissional.

## Benefícios da integração NFe.io + Squarespace

- **Emissão automática de NF-e:** Gere notas fiscais quando um pedido é criado, pago ou finalizado.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre sistemas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão integrada:** Centralize os dados de pedidos e notas emitidas.

## Como funciona a integração?

1. **Evento no Squarespace:** Quando um pedido é criado, pago ou entregue (conforme seu gatilho), a Pluga envia os dados para o NFe.io.
2. **Emissão da NF-e:** O NFe.io utiliza as informações do pedido/cliente para emitir a **NF-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga, e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns no Squarespace:

- Pedido criado
- Pedido cancelado
- Pedido entregue

Ações no NFe.io:

- Emitir **NF-e**

## Como configurar?

Para configurar a integração entre NFe.io e Squarespace via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **Squarespace + NFe.io**.
2. Conecte sua conta do **Squarespace** e autorize o acesso quando solicitado.
3. Conecte sua conta do **NFe.io** informando a chave de API quando solicitado.
4. Selecione o gatilho no Squarespace (ex.: pedido criado ou pedido pago) e a ação no NFe.io (ex.: emitir **NF-e**).
5. Mapeie os campos obrigatórios da NF-e: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
6. Salve e ative a automação para começar a emitir **NF-e** automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/squarespace/

---

## Integração NFe.io + Stripe

Source: https://nfe.io/docs/integracoes/plataformas/pluga/stripe/index.md

A integração entre **NFe.io** e **Stripe** via **Pluga** permite emitir automaticamente **NFS-e** com base em eventos de
pagamento e assinaturas — reduzindo tarefas manuais e garantindo conformidade fiscal no seu negócio.

## O que é o Stripe?

O **Stripe** é uma plataforma global de pagamentos que oferece soluções para recebimentos online e recorrentes,
checkout, links de pagamento, gestão de assinaturas e conciliação financeira.

## Benefícios da integração NFe.io + Stripe

- **Emissão automática de NFS-e:** Gere notas de serviço assim que o pagamento/assinatura for aprovado(a).
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre sistemas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão integrada:** Centralize dados de cobranças e notas emitidas.

## Como funciona a integração?

1. **Evento no Stripe:** Quando um pagamento é aprovado, reembolsado, recusado, ou quando a assinatura é criada/ativada/cancelada,
   a Pluga envia os dados para o NFe.io.
2. **Emissão da NFS-e:** O NFe.io utiliza as informações do cliente e da cobrança para emitir a **NFS-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga, e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns no Stripe:

- Pagamento aprovado
- Pagamento recusado
- Pagamento reembolsado
- Assinatura criada
- Assinatura ativa
- Assinatura cancelada

Ações no NFe.io:

- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Stripe via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **Stripe + NFe.io**.
2. Conecte sua conta do **Stripe** e autorize o acesso quando solicitado.
3. Conecte sua conta do **NFe.io** informando a chave de API quando solicitado.
4. Selecione o gatilho no Stripe (ex.: pagamento aprovado) e a ação no NFe.io (emitir **NFS-e**).
5. Mapeie os campos obrigatórios da NFS-e: tomador, serviço, município, código de serviço/CNAE, alíquota de ISS,
   regime tributário e demais regras fiscais da sua operação.
6. Salve e ative a automação para começar a emitir **NFS-e** automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/stripe/

---

## Integração NFe.io + Superlógica Assinaturas

Source: https://nfe.io/docs/integracoes/plataformas/pluga/superlogica/index.md

A integração entre **NFe.io** e **Superlógica Assinaturas** via **Pluga** permite emitir automaticamente **NFS-e** com base
em eventos de cobranças e assinaturas — reduzindo tarefas manuais e garantindo conformidade fiscal.

## O que é a Superlógica Assinaturas?

A **Superlógica Assinaturas** é uma plataforma de gestão de recorrência, com recursos para planos, faturas, cobranças,
boletos, cartões, inadimplência e toda a operação de assinaturas.

## Benefícios da integração NFe.io + Superlógica

- **Emissão automática de NFS-e:** Gere notas de serviço assim que uma cobrança for liquidada ou uma assinatura criada.
- **Menos erros operacionais:** Evite retrabalho e inconsistências ao sincronizar dados entre as plataformas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão centralizada:** Acompanhe as automações na Pluga e as notas no NFe.io.

## Como funciona a integração?

1. **Evento na Superlógica:** Quando uma cobrança/assinatura dispara um gatilho (ex.: cobrança liquidada, assinatura criada),
   a Pluga envia os dados para o NFe.io.
2. **Emissão da NFS-e:** O NFe.io utiliza as informações do tomador e da cobrança para emitir a **NFS-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga e a situação fiscal da nota pode ser consultada no NFe.io.

Gatilhos comuns na Superlógica:

- Assinatura criada
- Cobrança liquidada
- Cobrança pendente
- Cobrança estornada
- Cobrança invalidada/cancelada

Ações no NFe.io:

- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Superlógica Assinaturas via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **Superlógica + NFe.io**.
2. Conecte sua conta da **Superlógica Assinaturas** e autorize o acesso.
3. Conecte sua conta do **NFe.io** informando a chave de API quando solicitado.
4. Selecione o gatilho na Superlógica (ex.: cobrança liquidada) e a ação no NFe.io (emitir **NFS-e**).
5. Mapeie os campos obrigatórios da NFS-e: tomador, serviço, município, código de serviço/CNAE, alíquota de ISS,
   regime tributário e demais regras fiscais necessárias.
6. Salve e ative a automação para começar a emitir **NFS-e** automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/superlogica/

---

## Integração NFe.io + Typeform

Source: https://nfe.io/docs/integracoes/plataformas/pluga/typeform/index.md

Com a integração entre **NFe.io** e **Typeform** via Pluga, você emite **NF-e** ou **NFS-e** automaticamente quando novas
respostas chegam ao seu formulário — sem código e com mapeamento direto dos campos.

## O que é o Typeform?

O **Typeform** é uma plataforma de formulários e pesquisas com foco em experiência do usuário, ideal para capturar dados
com qualidade e conversão.

## Benefícios da integração NFe.io + Typeform

- **Automação fiscal a partir das respostas:** Gere **NF-e** ou **NFS-e** com base nas informações dos respondentes.
- **Menos erros e retrabalho:** Evite digitação duplicada ao mapear os campos diretamente para a nota.
- **Agilidade no processo:** Reduza tarefas manuais e acelere o faturamento.
- **Flexibilidade:** Modele o formulário para coletar os dados fiscais necessários do seu negócio.

## Como funciona a integração?

1. **Evento no Typeform:** Ao receber uma nova resposta (ou resposta com anexos, conforme seu plano), a Pluga encaminha
   os dados para o NFe.io.
2. **Emissão da nota:** O NFe.io utiliza as informações mapeadas para emitir a **NF-e** ou **NFS-e**.
3. **Acompanhamento:** O status da automação é exibido na Pluga e a situação da nota pode ser consultada no NFe.io.

Gatilhos típicos no Typeform:

- Nova resposta recebida
- Nova resposta com anexos (premium)

Ações no NFe.io:

- Emitir **NF-e**
- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Typeform via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e selecione a integração **Typeform + NFe.io**.
2. Conecte suas contas (autorize o Typeform e informe a chave de API do NFe.io quando solicitado).
3. Escolha o gatilho no Typeform (ex.: nova resposta) e a ação no NFe.io (emitir **NF-e** ou **NFS-e**).
4. Mapeie os campos obrigatórios:
   - Para **NF-e**: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
   - Para **NFS-e**: tomador, serviço, município, código de serviço/CNAE, alíquota de ISS, regime de tributação etc.
5. Salve e ative a automação para começar a emitir notas automaticamente a partir das respostas do formulário.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/typeform/

---

## Integração NFe.io + Vindi Recorrência

Source: https://nfe.io/docs/integracoes/plataformas/pluga/vindi/index.md

A integração entre **NFe.io** e **Vindi** via **Pluga** permite emitir automaticamente **NFS-e** com base em eventos de
transações e cobranças recorrentes — reduzindo tarefas manuais e garantindo conformidade fiscal.

## O que é a Vindi?

A **Vindi** é uma plataforma de pagamentos e recorrência, com recursos para cobranças, assinaturas, cartões, boletos e
conciliação financeira.

## Benefícios da integração NFe.io + Vindi

- **Emissão automática de NFS-e:** Gere notas de serviço assim que a transação for criada/aprovada.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre sistemas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão centralizada:** Acompanhe as automações na Pluga e as notas no NFe.io.

## Como funciona a integração?

1. **Evento na Vindi:** Quando uma transação dispara um gatilho (ex.: transação criada ou aprovada), a Pluga envia os
   dados para o NFe.io.
2. **Emissão da NFS-e:** O NFe.io utiliza as informações do cliente e da cobrança para emitir a **NFS-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga e a situação fiscal da nota pode ser consultada no NFe.io.

Gatilhos comuns na Vindi:

- Transação criada
- Transação aprovada

Ações no NFe.io:

- Emitir **NFS-e**

## Como configurar?

Para configurar a integração entre NFe.io e Vindi via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **Vindi + NFe.io**.
2. Conecte sua conta da **Vindi** e autorize o acesso quando solicitado.
3. Conecte sua conta do **NFe.io** informando a chave de API quando solicitado.
4. Selecione o gatilho na Vindi (ex.: transação aprovada) e a ação no NFe.io (emitir **NFS-e**).
5. Mapeie os campos obrigatórios da NFS-e: tomador, serviço, município, código de serviço/CNAE, alíquota de ISS,
   regime tributário e demais regras fiscais da sua operação.
6. Salve e ative a automação para começar a emitir **NFS-e** automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/vindi/

---

## Integração NFe.io + Webflow

Source: https://nfe.io/docs/integracoes/plataformas/pluga/webflow/index.md

A integração entre **NFe.io** e **Webflow** via **Pluga** permite emitir automaticamente **NF-e** com base em eventos de
pedido e pagamento, reduzindo tarefas manuais e acelerando o faturamento do seu e-commerce.

## O que é o Webflow?

O **Webflow** é uma plataforma de criação de sites e lojas virtuais que combina design visual, CMS e e-commerce, com
recursos para catálogo, checkout, pagamento e automações.

## Benefícios da integração NFe.io + Webflow

- **Emissão automática de NF-e:** Gere notas fiscais quando um pedido é criado, aprovado ou atualizado.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre sistemas.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão integrada:** Centralize os dados de pedidos e notas emitidas.

## Como funciona a integração?

1. **Evento no Webflow:** Quando um pedido sofre uma mudança (ex.: criado, aprovado, reembolsado), a Pluga envia os dados para o NFe.io.
2. **Emissão da NF-e:** O NFe.io utiliza as informações do pedido/cliente para emitir a **NF-e**.
3. **Acompanhamento:** O status da automação é visível na Pluga e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns no Webflow:

- Pedido criado
- Pedido aprovado
- Pedido atualizado para pendente
- Pedido reembolsado
- Pedido contestado
- Pedido com contestação perdida
- Pedido não cumprido

Ações no NFe.io:

- Emitir **NF-e**

## Como configurar?

Para configurar a integração entre NFe.io e Webflow via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **Webflow + NFe.io**.
2. Conecte sua conta do **Webflow** e autorize o acesso quando solicitado.
3. Conecte sua conta do **NFe.io** informando a chave de API quando solicitado.
4. Selecione o gatilho no Webflow (ex.: pedido aprovado) e a ação no NFe.io (emitir **NF-e**).
5. Mapeie os campos obrigatórios da NF-e: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
6. Salve e ative a automação para começar a emitir **NF-e** automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/webflow/

---

## Integração NFe.io + WooCommerce

Source: https://nfe.io/docs/integracoes/plataformas/pluga/woocommerce/index.md

A integração entre **NFe.io** e **WooCommerce** via **Pluga** permite emitir automaticamente **NF-e** com base em
pedidos e eventos de pagamento da sua loja, reduzindo tarefas manuais e acelerando seu faturamento.

## O que é o WooCommerce?

O **WooCommerce** é um plugin de e-commerce para WordPress que transforma seu site em uma loja virtual completa,
com recursos para catálogo de produtos, carrinho, checkout, meios de pagamento, frete e extensões.

## Benefícios da integração NFe.io + WooCommerce

- **Emissão automática de NF-e:** Gere notas fiscais a partir de pedidos criados ou pagamentos aprovados.
- **Menos erros operacionais:** Evite digitação duplicada e inconsistências entre loja e sistema fiscal.
- **Agilidade e conformidade:** Acelere o faturamento mantendo as regras fiscais atualizadas.
- **Visão integrada:** Centralize os dados de pedidos e notas emitidas.

## Como funciona a integração?

1. **Evento no WooCommerce:** Quando um pedido é criado/atualizado (conforme o gatilho configurado), a Pluga envia os
   dados para o NFe.io.
2. **Emissão da NF-e:** O NFe.io utiliza as informações do pedido/cliente para emitir a **NF-e** correspondente.
3. **Acompanhamento:** O status da automação é visível na Pluga, e a situação da nota pode ser consultada no NFe.io.

Gatilhos comuns no WooCommerce:

- Pedido criado
- Pedido pago (pagamento aprovado)
- Pedido cancelado

Ações no NFe.io:

- Emitir **NF-e**

## Como configurar?

Para configurar a integração entre NFe.io e WooCommerce via Pluga, siga os passos:

1. Acesse sua conta na [Pluga][1] e vá até a integração **WooCommerce + NFe.io**.
2. Conecte suas contas (autorize o WooCommerce e informe a chave de API do NFe.io quando solicitado).
3. Selecione o gatilho no WooCommerce (ex.: pedido pago) e a ação no NFe.io (ex.: emitir **NF-e**).
4. Mapeie os campos obrigatórios da NF-e: destinatário, itens, CFOP, NCM, CST/CSOSN, alíquotas e demais tributos.
5. Salve e ative a automação para começar a emitir NF-e automaticamente.

[1]: https://pluga.co/ferramentas/nfe-io/integracao/woocommerce/

---

## O que é a Vindi e como integrar com a NFE.io?

Source: https://nfe.io/docs/integracoes/plataformas/vindi/index.md

# O que é a Vindi?
A Vindi é uma empresa de tecnologia financeira, ou mais comum Fintech, eles criaram uma plataforma SaaS para gestão de pagamentos recorrentes, que possibilita que empresas de pequeno, médio e grande porte, possam automatizar todo o processo de cobranças.

Foi fundada em 2013, focados na gestão de cobrança das vendas por assinaturas, planos e mensalidades, focada principalmente no segmento de academias, onde o percentual de sua carteira de clientes é mais relevante.

## Para qual tipo de negócio é indicada?
Para simplificar, vamos pegar um exemplo de negócio em que a plataforma da Vindi pode ajudar e muito. Imagine um dono de escola da idiomas que todo os meses precisa realizar o processo de cobrança para os mais de 500 alunos.

Para isso essa empresa precisará enviar os boletos para os alunos mensalistas, depois será preciso acompanhar dia-a-dia no banco para conferir os pagamento que foram efetivados e então emitir as 500 notas fiscais dos clientes que pagaram seus boletos.

Com um software online, a plataforma a Vindi resolve tudo isso de forma simples e fácil. Você cadastra os 500 clientes/alunos de uma só vez e todo mês a plataforma emite os boletos, faz a conciliação bancária e por fim emite as notas fiscais.

Resumindo, seu cliente pode te pagar de diferentes formas (cartão de crédito, débito online, boleto bancário), você vai ter mais segurança com as transações e monitorar o crescimento do seu negócio. Tudo estará centralizado em um lugar.

É a plataforma ideal não só para escolas, como para todas as empresas que trabalham com recorrência e querem ganhar mais tempo no dia a dia, automatizando tarefas simples.

## Como fazer a Integração com a Plataforma Vindi

## **Ao final desse tutorial, você será capaz de**:
- Integrar a emissão de notas da NFe.io na plataforma da VINDI

## Fizemos esse vídeo para lhe auxiliar com a integração da Vindi e NFE.io

[Integração Vindi e NFE.io](https://youtu.be/hwjl2WxMkSE "Integração Vindi e NFE.io")

Watch the video: [YouTube video player](https://www.youtube.com/watch?v=hwjl2WxMkSE)

## Requisitos

- Criar uma conta
- Criar uma empresa
- Fazer upload do certificado digital
- Pegar sua chave de acesso

## Para integrar Com a Vindi siga os passos abaixo:

1. Acesse e faça login na plataforma da VINDI
2. Clique no botão **Configurações** no menu esquerdo

![vindi](https://nfe.io/docs/app/uploads/2020/09/botao-configuracao.png)

3. Clique no botão Extensões & Integrações
![vindi](https://nfe.io/docs/app/uploads/2020/09/botao-extensoes.png)

4. Clique na aba Disponíveis
![vindi](https://nfe.io/docs/app/uploads/2020/09/botao-disponiveis.png)

5. Clique no botão instalar em frente ao plugin da NFe.io
![](https://nfe.io/docs/app/uploads/2020/09/botao-instalar.png)
> [Clique aqui](https://atendimento.vindi.com.br/hc/pt-br/articles/204706800 "Clique aqui") para ver o significado de cada status.

6. Defina em que momento/status da fatura será emitida a nota
>[ Clique aqui](https://nfe.io/docs/integracoes/integracao-vindi/ " Clique aqui") para ver como pegar sua chave de acesso. PS: Pegar a chave de acesso de "Nota Fiscal"

7. Informe a sua chave de acesso e clique no botão **Continuar**
![](https://nfe.io/docs/app/uploads/2020/09/definir-emissao.png)

8. Selecione qual empresa você quer usar

> Se não souber qual código de serviço informar, confirme com o seu contador.

9. Informe o código de serviço municipal do seu serviço com base no seu municipio

> Essa informação irá sair na descrição do serviço no PDF.

10. Informe a descrição do seu serviço

![](https://nfe.io/docs/app/uploads/2020/09/definir-empresa.png)

11. Clique em Instalar e você deverá ver uma mensagem que indica **Sucesso**

![](https://nfe.io/docs/app/uploads/2020/09/salvo-sucesso.png)

12. Agora é só criar uma fatura ou ir em uma já criada e simular a emissão de nota alterando o status da fatura ou emitindo manualmente

## Próximos passos
- [Listar notas fiscais de serviço](/documentacao/nossa-plataforma/nota-fiscal-servico/listar-notas-servico "Listar notas fiscais de serviço")
- [Cancelar uma nota fiscal de serviço](/documentacao/nossa-plataforma/nota-fiscal-servico/cancelar-nota-servico "Cancelar uma nota fiscal de serviço")
- [Veja o artigo na Vindi](https://blog.vindi.com.br/integracao-nota-fiscal-online-nfe-io/ "Veja o artigo na Vindi")

---

## O que é a Wirecard e como integrar com a NFE.io?

Source: https://nfe.io/docs/integracoes/plataformas/wirecard/index.md

# O que é Moip? Descubra como o Moip virou Wirecard

> A Wirecard é um serviço que trabalha para atender os lojistas virtuais de todo o Brasil, ajudando-os a receber pagamentos online e vender muito mais. Mas talvez a palavra “Wirecard” esteja na fatura do seu cartão é uma maneira inteligente de receber pagamentos online.

## O que é Wirecard?

**Wirecard** é um intermediador de pagamento para e-commerces e marketplaces, com a função de fazer com que os pagamentos de um site sejam efetuados de maneira ágil e segura. Ao fazermos isso, se melhora a experiência de compra dos clientes em uma loja virtual e, consequentemente, aumentar as taxas de conversão em vendas de um site.

Você verá que o **Moip** que virou Wirecard, partiu da ideia de 3 amigos empreendedores que amam trabalhar com tecnologia. Então, nada mais justo do que referenciar esse gosto pela tecnologia no próprio nome da empresa.

*Moip* é uma sigla para “Money over IP”, que, traduzido ao pé da letra, seria algo como *“dinheiro sobre um protocolo de Internet”*. Desde então a **Wirecard** atua ajudando no processo de recebimento de pagamentos em e-commerces e marketplaces, além de auxiliar milhares de lojistas virtuais que buscam por uma solução de pagamentos ideal.

## Mas como os pagamentos são efetuados?

Quando um comprador visita uma loja virtual, busca por um produto e decide comprá-lo, ele é direcionado para uma página própria para realizar a finalização da sua compra. Nela, ele informa seus dados pessoais e os dados do cartão de crédito. É aqui que a Wirecard atua. A nossa função é realizar o checkout da compra, ou seja, atuamos na coleta dos dados bancários do cliente que está comprando para podermos processar o pagamento de forma segura e eficiente.

## Conheça os principais produtos Wirecard

A Wirecard conta com diversos produtos para diferentes necessidades, de acordo com um modelo de negócios específico. Veja quais são os produtos:

## Wirecard para e-commerces

> Com essa solução de pagamento para e-commerce, o lojista virtual fica livre da contratação de gateways, gestão de fraude, bancos e administradoras. Com apenas 1 contrato e 1 integração você garante tudo o que precisa para receber pagamentos no e-commerce.

## Wirecard para marketplaces

> A Wirecard foi a primeira solução de pagamentos para marketplaces do Brasil. Com o produto da Wirecard para marketplaces, você pode gerenciar pagamentos, integrar os seus lojistas e receber comissões em tempo real com o Split de Pagamento.

## Wirecard in App

>Essa opção permite o lojista receber pagamentos pelo próprio smartphone. Com a Wirecard In-App, você pode gerenciar os seus pagamentos dentro do seu aplicativo a hora que quiser.

## Wirecard Assinaturas

>Com a Wirecard Assinaturas, você consegue gerenciar as mensalidades e cobranças recorrentes, além de fazer a gestão das suas assinaturas e receber pagamentos no cartão de crédito e boleto.

## Veja quem recebe pagamentos com a Wirecard

Diversas gigantes do comércio eletrônico viram na Wirecard um diferencial no mercado e então decidiram garantir uma otimização na experiência de compra dos seus clientes, utilizando as soluções de pagamento online.

Lojas virtuais como a **Elo7, Positivo, Enjoei, ConectCar e outros milhares de empreendimentos de sucesso** já otimizaram o processo de receber pagamentos online com a **Wirecard**.

### Agora que você já conheceu a **Wirecard** que tal integrar com a **emissão de nota fiscal da NFE.io** ?

Entre em contato conosco, que nosso time ficará muito feliz em ajudar a solucionar seus problemas e otimizar o tempo que você gasta com as burocracias do Governo
E para dar sequencia na integração não se esqueça de preencher esse [formulário wirecard](https://p.nfe.io/integracao-meios-pagamentos)

---

## Microsoft Flow

Source: https://nfe.io/docs/integracoes/plugins/microsoft-flow/index.md

Nesse tutorial iremos entender o que é Microsoft Flow, como usar junto ao Google Planilhas e integrá-lo à plataforma da [NFE.io](https://nfe.io "NFE.io").

### Emitindo uma nota pelo Google Sheets
#### Downloads
Antes de dar início a este tutorial, você deve realizar o download do fluxo necessário de acordo com sua necessidade. clique para fazer o download.

### Efetuando login
[Acesse o site](https://flow.microsoft.com/pt-br/ "Acesse o site"), clique no botão **“Entrar”**, preencha os campos com as informações necessárias (Para que a funcionalidade seja completa, utilize um email comercial).

![](https://nfe.io/docs/app/uploads/2020/08/msflow1.png)

Após inserir o email no campo mostrado acima, chegará um email com o código de confirmação no email informado e que precisará ser utilizado na etapa de preenchimento das informações.

![](https://nfe.io/docs/app/uploads/2020/08/msflow2.png)

Após preencher todas as informações e clicar no botão **“Iniciar”**, você será redirecionado para a página inicial do Microsoft Flow, conforme imagem a seguir:

![](https://nfe.io/docs/app/uploads/2020/08/msflow3.png)

### Configurando o ambiente
Antes de importar o fluxo, devemos fazer as configurações necessárias para que o fluxo funcione corretamente.

> No menu superior direito, clique na engrenagem e depois em “Conexões (Connections)”, conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow4.png)

Após clicar em conexões você será redirecionado para a seguinte página:

![](https://nfe.io/docs/app/uploads/2020/08/msflow5.png)

Nesta página clique em **“Criar uma conexão (New connection)”**, como destacado na imagem acima, você será redirecionado novamente.

Selecionaremos as conexões necessárias para o funcionamento do nosso fluxo. Precisaremos de uma conexão com o Google Sheets e com o Google Drive.

> Digite **“Google sheets (Planilhas Google)”** na barra de pesquisa. Após selecionar a conexão com o Google sheets, clique em **“Criar (Create)”** na opção que aparecerá conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow6.png)

Uma nova janela aparecerá solicitando que você selecione uma conta. Selecione uma conta do google conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow7.png)

Agora precisamos adicionar a conexão com o Google Drive. Faça o mesmo procedimento anterior e adicione uma conexão com o Google Drive. Esta deverá ser a tela final de conexões:

![](https://nfe.io/docs/app/uploads/2020/08/msflow8.png)]

#### Importando um Fluxo no MS Flow
Nesta etapa iremos importar nosso fluxo.

> No menu superior, clique em **“Meus fluxos (My flows)”**, logo no menu abaixo, clique na opção **“Importar (Import)”**, conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow9.png)

Clique em **“Carregar (Upload)”** e o mesmo abrirá uma nova janela para que você selecione um arquivo.

Selecione o fluxo com o nome **“Fluxo emissão padrão”** que está em formato **.zip**.

Após carregar o fluxo, a seguinte tela irá aparecer:![](https://nfe.io/docs/app/uploads/2020/08/msflow11.png)

Apenas temos que selecionar nossos Recursos relacionados. Assim como mostra na imagem acima, clique na opção **“Selecionar durante a importação (Select during import) ”**. Surgirá a seguinte janela no canto direito da sua tela:

![](https://nfe.io/docs/app/uploads/2020/08/msflow12.png)

Selecione sua conta de e-mail e clique no botão **“Salvar”**.

![](https://nfe.io/docs/app/uploads/2020/08/msflow13.png)

Sua tela ficará assim. Clique no botão **“Importar (Import)”** na parte inferior e espere até que a seguinte tela apareça com uma mensagem de sucesso na importação.

![](https://nfe.io/docs/app/uploads/2020/08/msflow14.png)

Feito isso, o fluxo já está pronto para uso. Clique em **“Meus fluxos (my flows)”** no menu principal do site na parte superior e siga os próximos passos.

### Criando um arquivo do Google Sheets
Para criar uma planilha do Google Sheets, acesse o Google Drive e faça o login com sua conta do Google.
Na página inicial, clique no botão **“New (Novo)”** ou clique com o botão direito na área onde se encontram seus arquivos e selecione a opção Google Sheets, como na imagem abaixo.

![](https://nfe.io/docs/app/uploads/2020/08/msflow15.png)

Abra a planilha que foi baixada no início deste tutorial e copie a primeira linha onde contém os campos em verde e cole em sua planilha do Google Sheets. Deverá ficar assim:

![](https://nfe.io/docs/app/uploads/2020/08/msflow16.png)

Agora precisamos inserir os valores para a emissão da Nfe. Alguns campos possuem regras a serem seguidas:

- **CPF_CNPJ:** pode ser preenchido no padrão de CPF ou CNPJ ou somente números se preferir (Ex: 123.456.789-12; 12345678912).
- **Email:** caso queira enviar para mais de um email, separá-los com vígula. Ex: teste@teste.com, teste2@teste.com, teste3@teste.com
- Valor: deve ser preenchido sem “R$” e com “.”(Ex: 10.50).
- **Endereco_Cep:** pode ser preenchido no padrão CEP (Ex: 12345-678).
- **Endereco_Complemento:** caso não haja complemento, pode-se deixar em branco.
- **Data_emissao:** a data de emissão deve ser preenchida apenas para notas retroativas (datas anteriores à data atual) e deve seguir o seguinte formato: “yyyy-MM-dd” (ano-mês-dia).
- **Aliquota_ISS:** caso necessário informar a alíquota ISS, preencher o campo sem o sinal de porcentagem “%” (Ex: 2,5). Caso não seja necessário, preencher o campo com o valor 0.

O fluxo se encarregará de preencher os campos **“status”** e **“ERRO mensagem”**, por isso não devem ser preenchidos. Caso a nota seja emitida com sucesso, o campo de status será preenchido com um **“OK”**, caso contrário, com **“ERRO”**.

> Se houver alguma falha na emissão, o campo** “ERRO mensagem”** retornará o motivo pela qual a nota não foi emitida.

Caso você se depare com um campo desconhecido como na imagem abaixo, não se preocupe, pois o fluxo o cria automaticamente para poder identificar as linhas da planilha.

![](https://nfe.io/docs/app/uploads/2020/08/msflow17.png)

### Executando o fluxo
Na página **“Meus fluxos (My flows)”** no menu principal, selecione o fluxo que foi importado e após isso, clique no ícone para editar o fluxo como na imagem abaixo.

![](https://nfe.io/docs/app/uploads/2020/08/msflow18.png)

Após isso, você será redirecionado para a página de edição do fluxo, onde devemos editar as informações necessárias para emissão. Para o fluxo funcionar corretamente, precisamos apenas que o usuário carregue o arquivo do google sheets que contém as Nfes que serão emitidas.

> Na etapa **“Obter linhas (Get rows)”** clique no ícone de busca de arquivos (ícone destacado em vermelho) e selecione a sua planilha do Google sheets e o nome da tabela logo abaixo, previamente criada em sua conta no Google Drive.

![](https://nfe.io/docs/app/uploads/2020/08/msflow19.png)

Para que o fluxo retorne o status da emissão, devemos também selecionar essa mesma planilha nas etapas destacadas abaixo.

![](https://nfe.io/docs/app/uploads/2020/08/msflow20.png)

Após selecionar sua planilha e sua tabela na etapa de status, o fluxo automaticamente irá reconhecer os campos da planilha, como mostra a imagem abaixo, porém não precisamos preencher nenhum dos campos.

![](https://nfe.io/docs/app/uploads/2020/08/msflow21.png)

> Feito isso, basta iniciar o fluxo. Na parte superior da página de edição do fluxo, clique em **Testar**.

![](https://nfe.io/docs/app/uploads/2020/08/msflow23.png)

Em seguida marque a primeira opção “Vou executar a ação de disparo **(I’ll perform the trigger action)**” e clique em **“Salvar e Testar”**, conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow24.png)

A seguinte tela aparecerá:

![](https://nfe.io/docs/app/uploads/2020/08/msflow25.png)

Os campos **“ID empresa”** e **“Chave API”** são obrigatórios e devem ser preenchidos corretamente para o funcionamento do fluxo. Essas informações podem ser encontradas em nossa plataforma.

[Acesse a nossa plataforma](https://app.nfe.io/ "Acesse a nossa plataforma"), faça o login e clique no menu **“EMPRESAS(COMPANIES)”**, procure por sua empresa e clique em editar. Na aba** “CHAVES DE ACESSO(ACCESS KEYS)”** estarão os dados necessários.
Preenchidos os campos, clique no botão** “Run flow (executar fluxo)”** que estará habilitado para a execução do fluxo.

Você receberá uma mensagem na tela dizendo que o fluxo foi iniciado com êxito, apenas clique em **“Concluído”**:

![](https://nfe.io/docs/app/uploads/2020/08/msflow26.png)

> Se todos os passos anteriores estiverem corretos, a seguinte tela irá aparecer. Note que a mensagem na parte superior nos diz que o fluxo foi executado com sucesso.

![](https://nfe.io/docs/app/uploads/2020/08/msflow27.png)

O fluxo retornará automaticamente o status da nota no campo status na mesma planilha que foi enviada, ou seja, se ela foi emitida de fato ou ocorreu algum erro. Caso a nota for emitida com sucesso, o status aparecerá como **“OK”**, se houver algum erro, o campo status aparecerá como **“ERRO”** e no campo **“ERRO mensagem“** estará descrito qual o motivo do erro, por exemplo: **“cityServiceCode can not be null or empty”**.

Veja os campos na imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow28.png)

### Salvando as notas no Google drive
Os passos citados neste tutorial para salvar as notas no Google Drive são os mesmos para o formato em PDF ou XML.

#### Download
Antes de dar início a este tutorial, você deve realizar o download do fluxo que se adequa à sua necessidade. clique para fazer o download.


**IMAGEM AQUI COM LINK******

#### Efetuando login
[Acesse o site](https://flow.microsoft.com/pt-br/ "Acesse o site"), clique no botão **“Entrar Gratuito”**, preencha os campos com as informações necessárias (Para que a funcionalidade seja completa, utilize um email comercial).

![](https://nfe.io/docs/app/uploads/2020/08/msflow1-1.png)

Após inserir o email no campo mostrado acima, chegará um email com o código de confirmação no email informado e que precisará ser utilizado na etapa de preenchimento das informações.

![](https://nfe.io/docs/app/uploads/2020/08/msflow2-1.png)

Após preencher todas as informações e clicar no botão **“Iniciar”**, você será redirecionado para a página inicial do Microsoft Flow, conforme imagem a seguir:

![](https://nfe.io/docs/app/uploads/2020/08/msflow3-1.png)

### Configurando o ambiente
Antes de importar o fluxo, devemos fazer as configurações necessárias para que o fluxo funcione corretamente.

>No menu superior direito, clique na engrenagem e depois em **“Conexões (Connections)”**, conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow4-1.png)

Após clicar em conexões você será redirecionado para a seguinte página:

Nesta página clique em **“Criar uma conexão (New connection)”**, como destacado na imagem acima, você será redirecionado novamente.

Selecionaremos as conexões necessárias para o funcionamento do nosso fluxo. Precisaremos apenas de uma conexão com o Google Drive.

> Digite **“Google Drive”** na barra de pesquisa. Após selecionar a conexão com o Google Drive, clique em “Criar (Create)” na opção que aparecerá conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/drive-connection.png)

Uma nova janela aparecerá solicitando que você selecione uma conta. Selecione uma conta do google conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/drive-account.png)

Feito isso, esta deverá ser a tela final de conexões:![](https://nfe.io/docs/app/uploads/2020/08/connections.png)

### Importando um Fluxo no MS Flow
Nesta etapa iremos importar nosso fluxo.

No menu superior, clique em **“Meus fluxos (My flows)”**, logo no menu abaixo, clique na opção **“Importar (Import)”**, conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow10.png)

Clique em **“Carregar (Upload)”** e o mesmo abrirá uma nova janela para que você selecione um arquivo.

> Selecione o fluxo com o nome Clique em “Carregar (Upload)” e o mesmo abrirá uma nova janela para que você selecione um arquivo.

Selecione o fluxo com o nome “Fluxo envio notas googledrive” que está em formato .zip.

Após carregar o fluxo, a seguinte tela irá aparecer: que está em formato .zip.

Após carregar o fluxo, a seguinte tela irá aparecer:

![](https://nfe.io/docs/app/uploads/2020/08/import.png)

Apenas temos que selecionar nossos Recursos relacionados. Assim como mostra na imagem acima, clique na opção **“Selecionar durante a importação (Select during import)”**. Surgirá a seguinte janela no canto direito da sua tela:

![](https://nfe.io/docs/app/uploads/2020/08/msflow12-1.png)

> Selecione sua conta de e-mail e clique no botão **“Salvar”**.

![](https://nfe.io/docs/app/uploads/2020/08/import2.png)

Sua tela ficará assim. Clique no botão **“Importar (Import)”** na parte inferior e espere até que a seguinte tela apareça com uma mensagem de sucesso na importação.

![](https://nfe.io/docs/app/uploads/2020/08/import3.png)

Feito isso, o fluxo já está pronto para uso. Clique em **“Meus fluxos (my flows)”** no menu principal do site na parte superior e siga os próximos passos.

### Executando o fluxo
Na página **“Meus fluxos (My flows)”** no menu principal, selecione o fluxo que foi importado e após isso, clique no ícone para editar o fluxo como na imagem abaixo.

![](https://nfe.io/docs/app/uploads/2020/08/edit.png)

Após isso, você será redirecionado para a página de edição do fluxo, onde devemos configurar o fluxo. Para o fluxo funcionar corretamente, precisamos que o usuário informe sua chave de API e selecione a pasta do Google Drive onde deseja guardar o pdf das notas.

> Na etapa “Chave de API” insira sua chave de API no campo informado.

![](https://nfe.io/docs/app/uploads/2020/08/apikey.png)

O campo **“Chave API”** é obrigatório e deve ser preenchido corretamente para o funcionamento do fluxo. A chave de API pode ser encontrada em nossa plataforma.

[Acesse a nossa plataforma](https://app.nfe.io/ "Acesse a nossa plataforma"), faça o login e clique no menu **“CONTA”**. Na aba **“CHAVES DE ACESSO”**, sua chave de API estará no campo **“Nota Fiscal (api.nfe.io)”**

Por último, na etapa **“Create file”**, devemos selecionar a pasta onde deseja armazenar as Nfes em pdf. Clique no ícone destacado em vermelho e selecione a pasta desejada como mostra a imagem.

![](https://nfe.io/docs/app/uploads/2020/08/folder.png)

Agora precisamos fazer nosso sistema conversar com o fluxo. Para isso, vá em nossa plataforma e clique no menu **"CONTA"**, logo abaixo clique na aba **"WEBHOOKS"**. O webhook será disparado sempre que uma nota fiscal for emitida. Para configurá-lo, clique em **"Criar Webhook"** como na imagem abaixo.

![](https://nfe.io/docs/app/uploads/2020/08/webhook.png)

Para preencher o primeiro campo do formulário iremos voltar para o nosso fluxo e clicar na primeira etapa chamada "Quando uma solicitação HTTP for recebida", iremos copiar esse link conforme ilustrado na imagem abaixo.

![](https://nfe.io/docs/app/uploads/2020/08/url-request.png)

Podemos agora voltar para nossa plataforma e preencher os campos corretamente. O formulário ficará como no exemplo abaixo.

![](https://nfe.io/docs/app/uploads/2020/08/webhook-form.png)

- No primeiro campo cole o link que copiamos do fluxo.
- No segundo campo deixe apenas o evento "Emitida".
- No campo de senha, preencha com a senha de acesso da plataforma.
- No campo de status, deixe como ativo.
### Cancelando uma NFe
#### Downloads
Antes de dar início a este tutorial, você deve realizar o download do fluxo. clique para fazer o download.

**IMAGEM EXCEL E PASTA*****

### Efetuando login

[Acesse o site](https://flow.microsoft.com/pt-br/ "Acesse o site"), clique no botão “Entrar Gratuito”, preencha os campos com as informações necessárias (Para que a funcionalidade seja completa, utilize um email comercial)., preencha os campos com as informações necessárias (Para que a funcionalidade seja completa, utilize um email comercial).

![](https://nfe.io/docs/app/uploads/2020/08/msflow1-2.png)

Após inserir o email no campo mostrado acima, chegará um email com o código de confirmação no email informado e que precisará ser utilizado na etapa de preenchimento das informações.

![](https://nfe.io/docs/app/uploads/2020/08/msflow2-2.png)

Após preencher todas as informações e clicar no botão **“Iniciar”**, você será redirecionado para a página inicial do Microsoft Flow, conforme imagem a seguir:

![](https://nfe.io/docs/app/uploads/2020/08/msflow3-2.png)

### Configurando o ambiente
Antes de importar o fluxo, devemos fazer as configurações necessárias para que o fluxo funcione corretamente.

> No menu superior direito, clique na engrenagem e depois em **“Conexões (Connections)”**, conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow4-2.png)

Após clicar em conexões você será redirecionado para a seguinte página:

![](https://nfe.io/docs/app/uploads/2020/08/msflow5-1.png)

Nesta página clique em **“Criar uma conexão (New connection)”**, como destacado na imagem acima, você será redirecionado novamente.

Selecionaremos as conexões necessárias para o funcionamento do nosso fluxo. Precisaremos de uma conexão com o Google Sheets e com o Google Drive.

> Digite **“Google sheets (Planilhas Google)”** na barra de pesquisa. Após selecionar a conexão com o Google sheets, clique em “Criar (Create)” na opção que aparecerá conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow6-1.png)

Uma nova janela aparecerá solicitando que você selecione uma conta. Selecione uma conta do google conforme imagem abaixo:
![](https://nfe.io/docs/app/uploads/2020/08/msflow7-1.png)

Agora precisamos adicionar a conexão com o Google Drive. Faça o mesmo procedimento anterior e adicione uma conexão com o Google Drive. Esta deverá ser a tela final de conexões:

![](https://nfe.io/docs/app/uploads/2020/08/msflow8-1.png)

### Importando um Fluxo no MS Flow
Nesta etapa iremos importar nosso fluxo.

> No menu superior, clique em **“Meus fluxos (My flows)”**, logo no menu abaixo, clique na opção “Importar (Import)”, conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow10-1.png)

Clique em **“Carregar (Upload)”** e o mesmo abrirá uma nova janela para que você selecione um arquivo.

> Selecione o fluxo com o nome **“Fluxo cancelamento nfe”** que está em formato **.zip**.

Após carregar o fluxo, a seguinte tela irá aparecer:

![](https://nfe.io/docs/app/uploads/2020/08/msflow11-1.png)

Apenas temos que selecionar nossos Recursos relacionados. Assim como mostra na imagem acima, clique na opção **“Selecionar durante a importação (Select during import) ”**. Surgirá a seguinte janela no canto direito da sua tela:

![](https://nfe.io/docs/app/uploads/2020/08/msflow12-2.png)

> Selecione sua conta de e-mail e clique no botão **“Salvar”**.

![](https://nfe.io/docs/app/uploads/2020/08/msflow13-1.png)

Sua tela ficará assim. Clique no botão **“Importar (Import)”** na parte inferior e espere até que a seguinte tela apareça com uma mensagem de sucesso na importação.

![](https://nfe.io/docs/app/uploads/2020/08/msflow14-1.png)

Feito isso, o fluxo já está pronto para uso. Clique em **“Meus fluxos (my flows) ”** no menu principal do site na parte superior e siga os próximos passos.

### Criando um arquivo do Google Sheets

Para criar uma planilha do Google Sheets, acesse o Google Drive e faça o login com sua conta do Google.
Na página inicial, clique no botão **“New (Novo)”** ou clique com o botão direito na área onde se encontram seus arquivos e selecione a opção Google Sheets, como na imagem abaixo.

![](https://nfe.io/docs/app/uploads/2020/08/msflow15-1.png)

Abra a planilha que foi baixada no início deste tutorial e copie a primeira linha onde contém os campos em verde e cole em sua planilha do Google Sheets. Deverá ficar assim:

![](https://nfe.io/docs/app/uploads/2020/08/id-nfe.png)

Agora precisamos inserir os valores para o cancelamento da Nfe.

- **ID nota:** deve ser preenchido com o ID da NFe (Ex: 5b43dac68efda7092c364bb1).

Caso você se depare com um campo desconhecido como na imagem abaixo, não se preocupe, pois o fluxo o cria automaticamente para poder identificar as linhas da planilha.

![](https://nfe.io/docs/app/uploads/2020/08/power-apps-id.png)

### Executando o fluxo
Na página **“Meus fluxos (My flows)”** no menu principal, selecione o fluxo que foi importado e após isso, clique no ícone para editar o fluxo como na imagem abaixo.

![](https://nfe.io/docs/app/uploads/2020/08/msflow18-1.png)

Após isso, você será redirecionado para a página de edição do fluxo, onde devemos editar as informações necessárias para emissão. Para o fluxo funcionar corretamente, precisamos apenas que o usuário carregue o arquivo do google sheets que contém as Nfes que serão emitidas.

> Na etapa **“Obter linhas (Get rows)”** clique no ícone de busca de arquivos (ícone destacado em vermelho) e selecione a sua planilha do Google sheets e o nome da tabela logo abaixo, previamente criada em sua conta no Google Drive.

![](https://nfe.io/docs/app/uploads/2020/08/msflow19-1.png)

Feito isso, basta iniciar o fluxo. Na parte superior da página de edição do fluxo, clique em **Testar.**

![](https://nfe.io/docs/app/uploads/2020/08/msflow23-1.png)

Em seguida marque a primeira opção **“Vou executar a ação de disparo (I’ll perform the trigger action)”** e clique em **“Salvar e Testar”**, conforme imagem abaixo:

![](https://nfe.io/docs/app/uploads/2020/08/msflow24-1.png)

A seguinte tela aparecerá:

![](https://nfe.io/docs/app/uploads/2020/08/msflow25-1.png)

Os campos **“ID empresa”** e **“Chave API”** são obrigatórios e devem ser preenchidos corretamente para o funcionamento do fluxo. Essas informações podem ser encontradas em nossa plataforma.

[Acesse a nossa plataforma](https://app.nfe.io/ "Acesse a nossa plataforma"), faça o login e clique no menu **“EMPRESAS(COMPANIES)”**, procure por sua empresa e clique em editar. Na aba **“CHAVES DE ACESSO(ACCESS KEYS)”** estarão os dados necessários.
Preenchidos os campos, clique no botão** “Run flow (executar fluxo)”** que estará habilitado para a execução do fluxo.

Você receberá uma mensagem na tela dizendo que o fluxo foi iniciado com êxito, apenas clique em **“Concluído”**:

![](https://nfe.io/docs/app/uploads/2020/08/msflow26-1.png)

Se todos os passos anteriores estiverem corretos, uma mensagem na parte superior nos dirá que o fluxo foi executado com sucesso.

### Veja também:
[Nossos segmentos](https://nfe.io/segmentos/ "Nossos segmentos")
[Sobre a NFE.io](https://nfe.io/sobre/ "Sobre a NFE.io")
[Junte-se ao nosso time](https://nfe.io/carreira/ "Junte-se ao nosso time")

---

## Associar Emissor

Source: https://nfe.io/docs/plugins/whmcs/associar-emissor/index.md

Quando múltiplos emissores estão configurados, é possível associar clientes a um emissor específico. Isso permite que um cliente utilize um emissor diferente do padrão definido na configuração global do módulo.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-13.png)

## Associar Clientes

Para associar um cliente a um emissor específico, acesse o menu **Configuracoes** e clique no botão **Associar Clientes**. Use o campo de pesquisa para localizar o cliente desejado, em seguida selecione o emissor desejado e clique no botão `Salvar`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-14.png)

## Excluir Associação

Para excluir a associação de um cliente a um emissor específico, localize o cliente desejado na tabela e clique no botão `Excluir`. A associação será excluída e o cliente voltará a utilizar o emissor padrão definido na configuração global do módulo.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-15.png)

---

## Atualização

Source: https://nfe.io/docs/plugins/whmcs/atualizacao/index.md

Este documento irá mostrar como atualizar e migrar com sucesso o [Módulo Nota Fiscal para WHMCS via NFE.io](https://github.com/nfe/whmcs-addon) para a versão 2.x. Ela irá guiar passo a passo por todo o processo de atualização e migração necessários.

> Este documento visa auxiliar no processo de atualização do módulo da versão v1.4.x para a versão v2.x

> **ATENÇÃO:** Sempre realize um backup por segurança, tanto do seu WHMCS quanto do seu banco e dados antes de realizar qualquer migração.

## Ativando as versões em paralelo

A versão 2.x do módulo possui uma nova estrutura de diretórios, o que possibilita uma ativação em paralelo a versão anterior permitindo assim uma migração rápida e transparente. Ao ativar a nova versão em paralelo, o módulo irá buscar todas as informações da versão anterior e irá importa-las automaticamente.

Então é crucial para que o processo de atualização e migração ocorra adequadamente a **ativação em paralelo das duas versões do módulo**.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-atualizacao-01.png)

**Não desative** o módulo antigo **antes de concluir** a migração/atualização. 

## Configuração

Ao ativar a nova versão, todas as configurações globais do módulo serão automaticamente migradas. Configurações como API Key e ID da empresa já poderão ser visíveis como exemplificado na imagem a seguir.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-atualizacao-02.png)

As configurações migradas automaticamente da versão anterior serão:

* API Key
* ID da Empresa
* Código de Serviço Principal
* Informações de depuragem (debug)
* RPS (legado)
* Disparar e-mail com a nota
* Quando emitir NFE
* Quando emitir NFE
* Cancelar NFE Quando Cancelar Fatura
* Informações do campo personalizado para Campo Inscrição Municipal
* Informações do campo personalizado para Campo Personalizado CPF
* Informações do campo personalizado para Campo Personalizado CNPJ
* Aplicar Impostos em todos os produtos
* Descrição da NFSe
* Exibir Link da Fatura na NFSe
* Descrição Adicional

As demais configurações migradas poderão ser verificadas acessando o módulo em `Addons -> NFE.io NFSe -> Configurações`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-atualizacao-03.png)

## Migrando as notas fiscais

Ao ativar o novo módulo, as informações das notas fiscais emitidas a partir da versão anterior serão migradas automaticamente.

Todas as notas existentes estarão visíveis ao acessar o módulo em  `Addons -> NFE.io NFSe`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-notas-fiscais.png)

## Migrando os códigos de serviços

Os códigos de serviços personalizados serão migrados automaticamente e poderão ser verificados acessando o módulo em `Addons -> NFE.io NFSe -> Códigos de Serviços`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-atualizacao-04.png)

## Migrando as definições dos usuários

As configurações personalizadas de emissão de notas para os clientes também será migrada e todas as rotinas existentes de emissão para seus clientes serão mantidas.

## Verificando tudo

Por precaução, **antes de desativar a versão antiga** do módulo, faça uma verificação completa. Verifique se as configurações migradas estão corretas, verifique se as notas fiscais estão sendo listadas adequadamente e se os códigos dos serviços configurados condizem com os existentes na configuração do módulo antigo.

Fazendo esta verificação antes de seguir com a desativação e exclusão do módulo antigo ajudará a evitar problemas que não poderão ser revertidos após as próximas etapas.

## Desativando a versão anterior (1.4)

Após conferir a configurações do módulo e as notas ficais, tudo parecendo certo, você poderá desativar o módulo.

Para desativar o módulo **NFE.io v1.4.x** vá para `Configurações -> Módulos Addons` no WHMCS v7.x ou `Opções -> Módulos Addons` no WHMCS v8.x.

Localize o módulo antigo, **verifique a versão que deve ser desativada**, você deverá desativar a versão ****v1.4.x**** (sendo x qualquer versão menor como 1.4.1, 1.4.4 etc). Veja a imagem a seguir.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-atualizacao-05.png)

## Excluindo o módulo anterior (v1.4)

Após desativar o módulo **NFE.io v1.4.x**, será necessário **remover o diretório** `gofasnfeio` existente dentro de `modules/addons` como última etapa da atualização para a versão 2.x.

Para isso, utilize seu cliente FTP preferido para acessar o WHMCS, navegue até o diretório `seu_whmcs/modules/addons` para visualizar os módulos adicionais existentes em seu WHMCS e localize o diretório nomeado `gofasnfeio` como demonstrado na imagem a seguir.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-atualizacao-06.png)

Após localizar o diretório, **exclua-o**.

Pronto! Seu módulo de emissão de notas fiscais no WHMCS via NFE.io está atualizado para a versão 2.x!

### Tabelas do Banco de Dados

Este processo de atualização, por segurança, **não exclui ou manipula** as tabelas no banco de dados utilizado pela versão anterior. A versão 2.x copia todas as informações para novas tabelas e mantém as originais intactas, e a desativação do módulo não aciona nenhuma ação de exclusão. Então **caso você tenha tido algum problema** e precise voltar o módulo para uma versão anterior a atualização, basta desativar a versão 2.x e **reenviar os arquivos da versão originalmente em uso**.

Veja a lista a seguir das tabelas do banco de dados usadas pela versão anterior, caso você desejar fazer um backup manual ou exclui-las no futuro.

* `gofasnfeio`: todos os registros de notas fiscais já emitidas pelo módulo.
* `mod_nfeio_custom_configs`: contém todos os registros das configurações personalizadas de emissão de notas para os clientes.
* `tblproductcode`: possui todos os registros de códigos de serviços personalizados associados aos produtos/serviços.

:::warning

`tblproductcode` possui um nome muito similar as tabelas padrões do WHMCS, mas ela é uma tabela personalizada e nenhum componente ou função nativas do WHMCS dependem dela.

:::

---

## Código de Serviço

Source: https://nfe.io/docs/plugins/whmcs/codigos-servicos/index.md

## Códigos Personalizados de Serviço

Os produtos podem ter configurações de código de serviço individuais. É possível definir os códigos de serviços personalizado por produto em `Addons -> NFE.io NFSe -> Código de Serviço`

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-02.png)

Para definir um código de serviço personalizado, clique no botão **Adicionar Código de Serviço** e localize o produto/serviço desejado. Selecione a empresa emissora ao qual o código estará vinculado e no campo `Código do Serviço` informe o código de serviço desejado, em seguida clique no botão `Salvar Código`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-03.png)

Quando multiplos emissores estão configurados, um código de serviço pode ser informado para cada empresa emissora para o mesmo produto.

### Editar Código de Serviço

Para editar um código personalizado de um produto clique no botão **Adicionar Código de Serviço** e localize o produto/serviço desejado. Em seguida informe o novo código de serviço desejado e clique no botão `Salvar Código`.

### Excluir Código de Serviço

Para excluir um código personalizado de um produto localize o produto desejado na tabela e clique no botão `Excluir Código`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-04.png)

---

## Configuração

Source: https://nfe.io/docs/plugins/whmcs/configuracao/index.md

Este documento irá mostrar como configurar com sucesso o [Módulo Nota Fiscal para WHMCS via NFE.io](https://github.com/nfe/whmcs-addon). Ela irá guiar passo a passo por todo o processo de configuração.

Após a instalação e configuração inicial do addon como chave de API e código da empresa, é necessário realizar as configurações avançadas e rotinas de emissão das notas fiscais. Para isso acesse `Addons -> NFE.io NFSe -> Configurações`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-05.png)

As configurações disponíveis estão descritas a seguir.

## Definicoes de Emissão

É possível configurar diferentes empresas a serem utilizados para emissão de notas fiscais pelo módulo, cada um com suas definições.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-06.png)

Para adicionar uma nova empresa, clique no botão `Cadastrar Emissor` e preencha os campos obrigatórios.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-07.png)

### Empresa

Selecione a empresa que será configurada para emissão. Será exibida uma lista com todas as empresas cadastradas na sua conta NFE.io. É possível cadastrar mais de uma empresa para emissão de notas fiscais, cada uma com suas próprias definições.

### Código de Serviço Principal

Código de serviço que será usado como padrão para geração das notas fiscais pelo WHMCS para este emissor. O código de serviço padrão será utilizado para todos os produtos/serviços que não possuírem um código de serviço personalizado definido.

### Retenção de ISS

Alíquota em porcentagem (%) padrão de retenção de ISS. Será aplicado a todos os produtos/serviços.

### Empresa Padrão

Marque esta opção para definir a empresa como padrão. A empresa padrão será utilizada para emissão de notas fiscais quando houver mais de uma empresa configurada. Caso haja apenas uma empresa configurada, a mesma será utilizada como padrão.

## Configurações Globais

As configurações globais são aplicadas a todas as empresas cadastradas no módulo. As opções disponíveis estão descritas a seguir.

![Configuracoes Globais](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-07.png)

### Deduzir descontos da fatura na NF

Deduzir descontos/abatimentos existentes na fatura do valor total da nota a ser emitida. Quando uma fatura possuir um item de desconto ou item com valor negativo, o mesmo será deduzido do valor total da nota a ser emitida. Se uma fatura possuir vários itens de desconto para diferentes serviços, os descontos serão somados e descontados com base no grupo de código de serviço.

> Opção habilitada por padrão.

### Quando emitir NFE

Configuração global para emissão das nots ficais pelo WHMCS, as opções disponíveis são.

1. **Quando a fatura é gerada**: A NFSe será emitida assim que uma fatura seja publicada, ou seja, esteja disponível para o cliente.
2. **Quando a fatura é paga**: A NFSe será emitida apenas quando a fatura registrar um pagamento. Esse pagamento poderá ser registrado por qualquer portal de pagamento dentro do fluxo transacional padrão do WHMCS ou manualmente ao adicionar um pagamento em uma fatura.
3. **Agendar Emissão**: Número de dias após o pagamento da fatura que as notas devem ser emitidas. Informe quantos dias após o registro do pagamento em uma fatura a NFSe será emitida.

> **Atenção:** agendar emissão de notas desativa a configuração **Quando emitir NFE**.

### Cancelar NFE Quando Cancelar Fatura

Marque esta opção para cancelar automaticamente uma nota quando a fatura associada é cancelada.

### Inscrição Municipal

Selecione o campo personalizado criado anteriormente que será responsável por registrar o número de inscrição municipal do cliente.

### Campo Personalizado CPF

Selecione o campo personalizado criado anteriormente que será responsável pelo CPF do cliente. Este campo poderá ser o mesmo para CPF e CNPJ.

### Campo Personalizado CNPJ

Selecione o campo personalizado criado anteriormente que será responsável pelo CNPJ do cliente. Selecione o mesmo campo personalizado do CPF caso seja um campo único para ambos os números de documento (CPF/CNPJ).

### Descrição da NFSe

Selecione a informação que será exibida no campo de descrição da nota fiscal.

1. **Número da fatura**: Exibe apenas o número da fatura vinculada a NFSe.
2. **Nome dos serviços**: Exibe o nome de todos os serviços vinculados a fatura.
3. **Número da fatura + Nome dos Serviços**: Exibe o número da fatura em uma linha e o nome de todos os serviços vinculados a fatura em outra linha.

### Link da Fatura na NFSe

Inclui o link da fatura juntamente com a descrição da NFSe na mensagem da nota.

### Enviar e-mail

Habilita a opção de envio da nota fiscal por e-mail ao cliente.

> O e-mail será enviado para o endereço principal cadastrado no perfil do cliente e a mensagem será disparada pela plataforma da NFE.io.

### Descrição Adicional

Campo livre para informação adicional que será exibida no campo mensagem da nota fiscal.


## Emissão Personalizada por cliente

É possível definir uma **opção de emissão personalizada por cliente**, esta opção de emissão sobrescreve a configuração global de emissão configurada.

Para inserir uma opção personalizada de emissão, acesse o perfil do cliente desejado e localize o campo `Emitir nota fiscal quando` e selecione uma das opções de emissão da lista, como exemplificado na imagem a seguir.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-01.png)

## Link da nota na fatura

Para inserir um link da nota fiscal do PDF e XML, edite o arquivo `viewinvoice.tpl` da pasta do template do WHMCS, utilize o exemplo abaixo:

```smarty
{include file="../../modules/addons/NFEioServiceInvoices/lib/templates/clientarea/viewinvoice.tpl"}
```

Recomendamos a inserção da tabela logo acima da linha:
```smarty
<p class="text-center d-print-none"><a href="clientarea.php?action=invoices">{lang key='invoicesbacktoclientarea'}</a></p>
```

Exemplo de exibição do downwload da NF na visualização da fatura pelo cliente.

![image](https://user-images.githubusercontent.com/5316107/162670459-e63ba40f-9d38-41dd-9f83-18123e5945fa.png)

---

## Instalação

Source: https://nfe.io/docs/plugins/whmcs/instalacao/index.md

Este documento irá mostrar como instalar com sucesso o [Módulo Nota Fiscal para WHMCS via NFE.io](https://github.com/nfe/whmcs-addon). Ela irá guiar passo a passo por todo o processo de instalação.

## Antes de começar

Antes de realizar a instalação do módulo, leia com atenção as informações a seguir, elas são importantes para que todo o processo de instalação possa ocorrer sem problemas.

### Requisitos

Os requisitos a seguir são necessários para o funcionamento adequado do módulo e integração.

1. Download da última versão do módulo Nota Fiscal para WHMCS da NFe.io em https://github.com/nfe/whmcs-addon/releases/latest
2. WHMCS versão 8 ou superior;
2. PHP 7.4 ou superior;
3. Chave de API da [NFE.io](https://nfe.io);
4. Automação do WHMCS devidamente configurada ([https://docs.whmcs.com/Automation_Settings](https://docs.whmcs.com/Automation_Settings));
5. Tarefas cron do Sistema sendo executadas conforme recomendações do WHMCS [https://docs.whmcs.com/Crons#System_Cron](https://docs.whmcs.com/Crons#System_Cron).

### Campos Personalizados

O módulo irá requerer os seguintes campos personalizados para o cliente:

| Campo | Criação | Preenchimento |
| :---: | :---: | :---: |
| CPF/CNPJ | Obrigatória | Obrigatório |
| Inscrição Municipal | Obrigatória | Opcional |

Na administração do WHMCS, crie um campo personalizado de cliente para registrar o CPF/CNPJ necessário para a emissão da NFSe e outro para a Inscrição Municipal.

**Caso já exista** um campo personalizado de cliente configurado e utilizado para registrar o número do documento (CPF/CNPJ), **não será necessário criar outro**. 

O campo `Inscrição Estadual` é de criação obrigatória, mas de preenchimento opcional pelo cliente, necessário para emissão de notas para pessoa jurídica.

> **Atenção:** O módulo identificará automaticamente se o número de documento informado no campo personalizado se trata de CPF ou CNPJ e emitirá a nota em conformidade com o tipo de pessoa (física ou jurídica).

> **Dica:** é possível utilizar campos personalizados diferentes para preenchimento de CPF e CNPJ. 

## Instalação

Para instalar o módulo no WHMCS realize os seguintes passos.

### Baixar o módulo

Faça o download arquivo zip da última versão módulo neste link [https://github.com/nfe/whmcs-addon/releases/latest](https://github.com/nfe/whmcs-addon/releases/latest)

### Descompactar o zip

Descompacte o zip baixado, o conteúdo do diretório extraído deve ser semelhante a este:

* modules
  * addons
    * NFEioServiceInvoices

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-instalacao-01.png)

### Enviar arquivos para o WHMCS

Carregue o diretório `modules` existente no arquivo descompactado para o diretório de instalação do seu WHMCS.

Por exemplo, tendo o WHMCS instalado em `public_html`, carregue o diretório `modules` em `public_html`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-instalacao-02.png)

> **Dica:** O arquivo descompactado já está na estrutura associada aos módulos addon do WHMCS `modules/addons`. Ao carregar o diretório `modules` você automaticamente carregará o diretório do módulo `modules/addons/NFEioServiceInvoices`.

### Ativar o módulo addon

Após realizar o carregamento dos arquivos do módulo, ele está disponível para ativação e configuração no WHMCS.

Para ativar o módulo adicional no WHMCS vá até o ícone de chave no canto superior direito e clique em `Opções`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-instalacao-03.png)

O campo de busca em `Opções` digite `addon` e acesse a opção `Módulos Addon`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-instalacao-04.png)

Localize o módulo addon **NFE.io NFSe** e clique no botão `Ativar`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-instalacao-05.png)

## Configuração do addon

Após ativar o [Módulo Nota Fiscal para WHMCS via NFE.io](https://github.com/nfe/whmcs-addon) as seguintes opções devem ser configuradas.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-instalacao-07.png)

#### API Key

> campo obrigatório

Chave de acesso privada gerado na sua conta NFE.io, necessária para a autenticação das chamadas à API.

Obtenha uma chave de acesso a API neste link [https://app.nfe.io/account/apikeys](https://app.nfe.io/account/apikeys)


#### Ambiente de desenvolvimento

Emite as notas em modo "depuragem" sem valor real no lado da NFE.io, **ative apenas em caso de necessidade ou homologação**.

#### Debug

Marque essa opção para salvar informações de diagnóstico no Log de Módulo do WHMCS, **ative apenas em caso de necessidade**.

#### Controle de Acesso

Escolha os grupos de administradores ou  operadores que terão para acessar o módulo.

> **Dica:** informe todos os grupos de operadores que necessitem acessar e operar o módulo. 


Após realizar a instalação e configuração inicial, siga para as configurações detalhadas do módulo em [https://nfe.github.io/whmcs-addon/docs/configuracao](https://nfe.github.io/whmcs-addon/docs/instalacao/)

---

## Retenções

Source: https://nfe.io/docs/plugins/whmcs/retencoes/index.md

O módulo permite o cadastro de alíquotas de retenção de ISS personalizadas para os diferentes códigos de serviços cadastrados no WHMCS.
As alíquotas de retenção de ISS são aplicadas apenas para os produtos/serviços que possuírem um código de serviço personalizado definido. Caso não exista um código de serviço personalizado definido, será utilizada a alíquota padrão definida na configuração global do módulo.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-09.png)

## Adicionar Retenções

No menu **Alíquotas & Retenções** é possível definir alíquotas de retenção de ISS personalizadas para os diferentes códigos de serviços personalizados cadastrados no WHMCS.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-10.png)

Caso existam códigos de serviços personalizados cadastrados, você poderá informar alíquotas diferentes para cada um, independente do valor definido na configuração global do módulo.

Códigos de serviço com **alíquota com valor 0 (zero)** não sofrerão cálculo de retenção de ISS.

## Editar Retenções

Para editar uma alíquota de retenção, localize o código de serviço desejado na tabela e clique no botão `Editar`. Em seguida informe a nova alíquota desejada e clique no botão `Salvar`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-11.png)

## Excluir Retenções

Para excluir uma alíquota de retenção, localize o código de serviço desejado na tabela e clique no botão `Remover`.

![](https://nfe.io/docs/../assets/img/nfeio-whmcs-docs-configuracao-12.png)

---

## Automatize a emissão de notas fiscais de serviço NFS-e com WHMCS e NFE.io

Source: https://nfe.io/docs/integracoes/plugins/whmcs/index.md

# WHMCS

> Automatize a emissão de notas fiscais de serviço NFS-e com WHMCS e NFE.io!

A NFE.io é um sistema de emissão de notas fiscais que automatiza a comunicação com as prefeituras. Com a NFE.io você se livra de diversas tarefas chatas, melhorando o desempenho do seu negócio. E melhor, você economiza tempo e dinheiro.

Automatize a emissão de nota fiscal eletrônica de serviço diretamente em seu WHMCS através do **Módulo Nota Fiscal para WHMCS via NFE.io**. Com este módulo, é possível automatizar a rotina de geração e envio de NFSe para seus clientes quando eles realizam o pagamento de uma fatura referente a um pedido ou serviço recorrente, emitir notas a partir de faturas avulsas ou toda vez que um pagamento é recebido no WHMCS por exemplo.

![NFE.io WHMCS](https://nfe.io/docs/app/uploads/2020/08/nfeio-whmcs-notas-fiscais.png)

> Este módulo é para emissão de NFS-e, Nota Fiscal de Serviço Eletrônica, não sendo possível emissão de nota de produto.

### Principais Recursos
- Emissão automática de notas fiscais
- Emissão manual de notas fiscais
- Agendamento de emissão de notas fiscais
- Cancelamento de nota fiscal quando fatura é cancelada
- Configuração de código de serviço personalizado por produto
- Painel intuitivo de visualização de notas emitidas
- Botões de ação rápida para emissão, cancelamento e envio
- Acompanhamento do status da emissão
- Envio de nota fiscal por e-mail
- Download de nota em PDF e XML

#### Demais Recursos
- Emite notas fiscais de forma sequencial, evitando sobrecargas nos sites das prefeituras.
- Salva o debug das chamadas à API NFE.io no log de Módulo do WHMCS para diagnóstico
- Seleciona nas configurações do módulo a opção de enviar o número inscrição municipal para a nota fiscal.
- Seleciona nas configurações do módulo a opção de enviar a nota fiscal por e-mail automaticamente.
- Valida CPF/CNPJ do cliente e não emite a nota fiscal caso inválido

### Como usar este Módulo

#### Requisitos
- WHMCS versão 7.2 ou superior
- PHP 5.6 ou superior
- Tarefas cron do WHMCS devem estar funcionando a cada 5 minutos, conforme descrito na documentação oficial ([https://docs.whmcs.com/Crons](https://docs.whmcs.com/Crons "https://docs.whmcs.com/Crons"));
- É necessário um portal de pagamento ativado e que a criação de faturas do WHMCS esteja funcional, sendo que as notas fiscais são emitidas no momento da criação ou após o pagamento das faturas geradas manual ou automaticamente pelo WHMCS.

### Documentação

O módulo de emissão de notas fiscais para WHMCS via NFE.io é simples de instalar como qualquer módulo adicional e possui uma documentação bem organizada para auxiliar o processo de instalação e configuração para você começar a emitir notas fiscais automaticamente em seu WHMCS!

- [Instalação](/integracoes/plugins/whmcs/instalacao "Instalação")
- [Configuração](/integracoes/plugins/whmcs/configuracao "Configuração")
- [Atualização](/integracoes/plugins/whmcs/atualizacao "Atualização") **(v1.4 para 2.0)**

### CHANGELOG
> **IMPORTANTE:** Ao atualizar, após substituir os arquivos pelos mais recentes, acesse as configurações do módulo no menu `Opções > Módulos Addon > Gofas NFE.io` do painel administrativo do WHMCS e clique em "Salvar Alterações". Isso garente que os novos parâmetros serão gravados corretamente no banco de dados.

### v2.0
- **Grande atualização**: Confira no link Atualização

### v1.4.0
- Migração da tratativa do RPS para a NFe realizada
- Funcionalidade de emissão personalizada automatizada

### v1.3.3
- Ajuste na descrição da nota fiscal.

### v1.3.2
- Ajuste para correção da emissão automática de notas quando pagas.

### v1.3.1
- ajuste para correção de retorno de callback.

### v1.3.0
- link para relatório do sistema legado
- botão para cancelar nota fiscal
- log, data e hora da emissão do log
- verificação de conexão com nfe
- verificação automática de campo RPS
- verificação de campo personalizado
- campo personalizado no cliente para emissão da nota

### v1.2.10
- correção enviar endereço de e-mail na nota

### v1.2.9
- criação de arquivo de debug
- verificação do retorno CEP
- validação de versão do modulo via github
- impedir emissão duplicada de nota fiscal de fatura

### v1.2.7
- envio do nome da empresa ao invés do nome pessoa física quando o CNPJ estiver definido
- criar nota fiscal de acordo com o código de serviço de cada serviço
- corrigido erro de caracteres especiais
- opção de criar nota individualmente por tipo de serviço
- emissão de nota fiscal a partir da data de instalação do módulo
- opção de descrição do serviço na nota: referente a fatura ou nome do serviço.
- ajuste de link das notas fiscais na fatura para abrir todas as notas.
- ajuste de instalação do módulo

### v1.2.6
- opção manual para criação de notas fiscais.

### v1.2.5
- criação de link na fatura para o XML da nota fiscal.

### v1.2.4
- Nova opção de configuração no disparo de nota fiscal automatica por e-mail.
- Ajustes com informações e links de suporte.

### v1.2.3
- Ajustes Garante que a nota não sera duplicada, criação de link da nota fiscal, opção de inscrição municipal

### v1.2.2
- Garante que o rpsSeraiNumber não seja alterado quando já configurado manualmente.

### v1.2.1
- Corrigido erro que alterava a série do RPS nas configurações de acordo com a série RPS das NFEs já geradas.

### v1.2.0
- Novo campo nas configurações para informar a Série do RPS (RPS Serial Number). Será preenchido automaticamente na próxima emissão, caso não preenchido;
- Novo campo nas configurações para informar o número RPS (RPS Number). Caso não preenchido, será preenchido automaticamente na próxima emissão, após consultar a NFE mais recente gerada. Não sendo gerado ou configurado nenhum número RPS, o módulo irá configurar automaticamente com "1" o valor desse campo;

### v1.1.3
- Agora o número RPS é obtido consultando a NFE mais recente gerada;

### v1.1.2
- Melhoria na verificação de atualizações;

### v1.1.1
- Obtém via API o rpsSerialNumber e rpsNumber da empresa antes de gerar cada nota fiscal;
- O rpsNumber da nova NFE a ser gerada sempre é "último rpsNumber + 1".

### v1.0.1
- Corrigido bug ao salvar NFE no banco de dados na criação da fatura.

### v1.0.0
- Lançamento.

---

## Como integrar o Woocommerce com NFE.io?

Source: https://nfe.io/docs/integracoes/plugins/woocommerce/index.md

# O que é o WooCommerce?

>O WooCommerce é uma plataforma de e-commerce completa para o WordPress. Por mais que seja amplamente completa e satisfatória, ela é apenas um **plugin** da tradicional plataforma de CMS.

Originalmente, a ideia foi desenvolvida pelos programadores Mike Jolley e James Koster em 2011. Quatro anos depois, ela acabou sendo adquirida pelo WordPress e **detém 26% de todas as lojas virtuais do mundo.**

O WooCommerce é um plugin de WordPress que permite a criação de lojas virtuais a partir de códigos abertos. Por isso, é muito comum as empresas que já possuem sites em WordPress optarem pelo WooCommerce para gerir os seus e-commerces.

Afinal, o WooCommerce permite vender qualquer tipo de produto ou serviço, desde itens duráveis até infoprodutos e assinaturas de conteúdo. Também possui integração com as mais variadas formas de pagamento, tais como:

- Cartão de crédito;
- Cartão de débito;
- Boleto bancário;
- Transferência eletrônica;
- PagSeguro;
- Mercado Pago;
- PayPal;
- Entre outros.

> Portanto, uma vez que o cliente queira comprar a sua oferta, escolher a forma de pagamento de sua preferência não será um problema.Portanto, uma vez que o cliente queira comprar a sua oferta, escolher a forma de pagamento de sua preferência não será um problema.

## Como integrar a Emissão de Nota Fiscal automaticamente da NFE.io com o WooCommerce?

Para realizar a integração do Woocommerce com a NFe.io é muito simples. Siga o passo a passo abaixo para conseguir realizar essa integração sem problemas.

### **Você vai precisar de:**
- **Ter o Woocommerce ativado na sua loja virtual**
- **Ter o plugin Brazilian Market instalado, [clique aqui](https://br.wordpress.org/plugins/woocommerce-extra-checkout-fields-for-brazil/ "clique aqui")**
- **[Chave de Acesso (API Key) da NFE](/documentacao/nossa-plataforma/chaves-de-autenticacao "Chave de Acesso (API Key) da NFE")**

## Brazilian Market For Woocommerce

Para realizar a instalação do plugin, basta clicar no painel do Wordpress em "Plugins".

Em seguida, na busca da direita o nome do plugin : Brazilian Market on Woocommerce

Ao aparcer o plugin correto, clique em "Instalar agora", e assim que mudar o botão, clique em "Ativar".

![](https://nfe.io/docs/app/uploads/2020/08/EFYPI2s.png)

Feito isso, os campos de CPF, CNPJ entre outros campos serão adicionados no Woocommerce para que você possa realizar suas vendas com as notas fiscais.

## Passo 1: Instalando o plugin

1 - Faça login no seu painel do Wordpress e clique em Plugins
2 - Clique no Botão "Adicionar Novo"
3 - Na barra de pesquisa busque por "Wocoomerce NFe"

![Woocommerce](https://nfe.io/docs/app/uploads/2020/08/bkTidxp1.png)

4 - Clique em "Instalar Agora para instalar o plugin"
5 - Clique no botão Ativar após a instalação ser finalizada

## Passo 2: Configurando o plugin

![Woocommerce](https://nfe.io/docs/app/uploads/2020/08/QOUy9wD1.png)

1 - Com o plugin ativado, clique em Plugins na barra lateral
2 - Encontre o Plugin Woocommerce NFe e clique em configurações

![Woocommerce](https://nfe.io/docs/app/uploads/2020/08/QHo2rbf1.png)

3 - No campo Chave da API insira a sua chave de API (Api Key)

> Com a sua chave de API inserida o Woocommerce irá identificar a sua conta na plataforma da NFe.io e irá listar as suas empresas cadastradas.

4 - No campo Escolha a empresa, selecione a empresa desejada

Nos próximos 3 campos as configurações são opcionais, mas confira a explicação de cada um deles:

**Emissão de NFe:** Neste campo você deverá escolher se a emissão da nota fiscal será realizado automáticamente quando for identificado o pagamento de uma venda ou se você irá fazer isso manualmente.

**Status da emissão do pedido:** Nesta campo você escolherá em qual passo da venda o sistema irá emitir a nota fiscal. A escolha mais comum neste processo é quando o pedido está no status "Processando".

**Endereço é necessário para emissão:** Por padrão na hora das vendas é necessário que o seu comprador preencha o endereço, então é mais comum manter a opção "Sim".

5 - Com essas configurações prontas, clique em "Salvar Alterações" no final da página

Pronto! Com essas configurações a integração entre o Woocommerce e a NFE.io está feita.

## Emissão Manual Retroativa de Notas Fiscais

![Woocommerce Manual](https://nfe.io/docs/app/uploads/2020/08/MuceNVz1.png)

Caso você queira realizar a emissão retroativa das suas vendas passadas no Woocommerce é possível fazer.

Para isso você precisa configurar os seguintes campos:

- Habilitar Emissão Retroativa: deixe marcado para habilitar;
- Quantos dias atrás: Selecione os dias no passado onde as notas serão emitidas;
- Código de Serviços Municipal: Solicite para o seu contador
- Código de Serviço Ferderal LC 116: Solicite para o seu contador
- Descrição do serviço: Coloque a descrição do serviço que será adicionada na nota fiscal. Na dúvida fale com o seu contador.

------------

Olha que legal, o "WooCommerce NFe" é uma extensão do WooCommerce para emitir notas fiscais utilizando a API do NFe.io.

### Requisitos
- PHP >= 5.5
- WP >= 4.9
- WooCommerce >= 3.3.5


### Como fazer a Instalação?

Dentro da plataforma do Wordpress

1. Vá ao menu Plugins e clique Adicionar Novo.
2. Pesquise por **WooCommerce NFe**.
3. Clique em Instalar Agora.
4. Ativar o plugin

> Ou você pode colocar este plugin no diretório wp-content/plugins e ativá-lo.

## Changelog de nosso plugin.

### 1.0.0
- Initial release
### 1.0.1
- Fix issue #6
### 1.0.2
- Added trigger to issue invoices on specific status
- Fixed when issue invoices federal tax number must be only numbers
### 1.0.3
- Added support to issue invoices without all address fields filled
### 1.0.4
- Fix support to issue invoices without all address fields filled
- Fix trigger to issue invoices on specific status
### 1.2.5
- Added option to require an address when issuing an invoice.
- Fixed a bug where zero orders could be issued.
- Added notice in the order list when a order is zeroed.
- Added php require header on the readme.txt
- Fixed a bug that gave fatal error when on before PHP 5.5 versions.
- Fix - load_textdomain first from WP_LANG_DIR before load_plugin_textdomain
- Tweak - Tweak load_plugin_textdomain to be relative - this falls back to WP_LANG_DIR automatically. Can prevent "open_basedir restriction in effect".
### 1.2.6
- Fixing client-php folder conflict.
### 1.2.7
- Fixing how we verify the type of customer to output its information on the NFe receipt.
### 1.2.8
- Improved code documentation, PHPDoc.
- Started to use [] instead of array().
- Started to use the new logger implementation, wc_get_logger().
- Updated WordPress tested header to 3.5.1.
- Removed Extra Checkout plugin dependency.
- Removed Composer support for the client-php.
- Removed checks when on automatic issuing, as it was avoiding important log information to be saved.
- Added better labeling for the NFe.io flowStatus.

### Consulte também
[Conheça mais sobre nota fiscal](/documentacao/conceitos/notas-fiscais "Conheça mais sobre nota fiscal")

<a href="https://nfe.io/contato" title="Contato">Contato</a>

---

## Introdução à Legislação

Source: https://nfe.io/docs/legislacao/index.md

# Introdução à seção de Legislação

Seja bem vindo a nossa seção de Legislação. Criamos esse conteúdo com bastante zelo para que você consiga aprender tudo que é necessário sobre as leis estaduais e municipais, combinadas com a utilização de qualquer uma das nossas APIs.

## O que você encontrará aqui?

Nesta seção, você encontrará uma variedade de artigos e guias que cobrem os principais aspectos da legislação fiscal brasileira, incluindo:

- **Legislação Tributária:** Entenda as leis que regem os impostos e tributações no Brasil.
- **Regulamentações de Notas Fiscais:** Saiba mais sobre as normas que regem a emissão e o uso de notas fiscais eletrônicas.
- **Obrigações Fiscais:** Conheça as responsabilidades legais das empresas em relação à emissão de notas fiscais e ao cumprimento das obrigações fiscais.
- **Compliance Fiscal:** Descubra como garantir que sua empresa esteja em conformidade com as leis fiscais vigentes.

---

## Lei de Transparência (IBPT) - Conforme Lei 12.741/2012

Source: https://nfe.io/docs/legislacao/lei-de-transparencia-ibpt/index.md

# Lei de Transparência (IBPT) - Conforme Lei 12.741/2012

O IBPT foi criado em 1992 com o objetivo de estudar o complexo sistema tributário brasileiro, difundindo estudos e serviços orientados à modernas técnicas de planejamento tributário. Em 2004, o IBPT lançou o tema “Governança Tributária” como pauta no meio acadêmico e empresarial.

Um dos projetos especiais do IBPT é o movimento “De Olho no Imposto“, uma solução para atender às exigências da Lei 12.741/12.

Em 08 de dezembro de 2012 foi aprovada a Lei 12.741/12, também conhecida como “Lei do Imposto na Nota”. Em seu primeiro artigo ela já explica seu objetivo:

Art. 1º Emitidos por ocasião da venda ao consumidor de mercadorias e serviços, em todo território nacional, deverá constar, dos documentos fiscais ou equivalentes, a informação do valor aproximado correspondente à totalidade dos tributos federais, estaduais e municipais, cuja incidência influi na formação dos respectivos preços de venda.

A lei ainda estabelece quais tributos que deverão ser computados (Art. 1 § 5º): ICMS, IPI, ISSQN, IOF, PIS/Pasep, Cofins e Cide.

Em outras palavras, esta lei tornou obrigatório que estabelecimentos informem os tributos que impactam no preço de um produto ou serviço. Esses valores devem constar nos cupons e notas fiscais e precisam estar sempre atualizados.

**Esta lei versa apenas para vendas para o consumidor final.** Assim, ele consegue saber quanto do valor pago é destinado a impostos e quanto é realmente do produto/serviço adquirido.

**Como personalizar a informação destacada na NF emitida pela NFe.io?**

> É importante ressaltar que a legislação exige de fato esta menção em NF, porém por critério do cliente pode ser personalizada a informação substituindo o texto que informamos como padrão da seguinte forma:

Para personalizar a informação da lei 12.741/2012 basta digitar: **"741/2012"** no campo de** “Descrição do Serviço”**, assim nosso sistema suprime o texto padrão da lei mencionada na nota, sendo possível descrevê-lo como preferir. Abaixo os exemplos onde se aplica esta ação.

**Para emissões via Excel:**

![](https://nfe.io/docs/app/uploads/2020/09/imagem-1.png)

**Para emissões via API:**

![](https://nfe.io/docs/app/uploads/2020/09/imagem-2.png)


**Qual a regra de negócio de aplicação deste imposto na NF?**

Por regra geral, utilizamos o [site de olho no imposto](https://deolhonoimposto.ibpt.org.br/ "site de olho no imposto") para que de forma padrão as regras tributárias sejam descritas de forma nacional.

Como explicado anteriormente, é obrigatória a sua menção em operações para Consumidor Final, mas como fica o cálculo?

![](https://nfe.io/docs/app/uploads/2020/09/imagem-3.png)

**Como se aplica no simples nacional?**

Para o cálculo destes tributos aproximados há alguns critérios diferenciados para empresas optante pelo regime do Simples Nacional, sendo eles:

1 - Os percentuais informados nos campos "União - IRPJ, CSLL, CPP, PIS, COFINS, IPI", "Estado - ICMS" e "Município - ISS" são calculados com base nas tabelas do Simples Nacional.

2 - Para Serviços enquadrados na Tabela V do Simples Nacional, é informada a alíquota média entre as colunas 5 a 9 no campo "União - IRPJ, CSLL, CPP, PIS, COFINS, IPI".

3 - O percentual informado no campo "Substituição Tributária" é calculado de acordo com pesquisa tributária.

4 - Nos segmentos de atividade "Comércio - Outros" e "Indústria - Outros", é informado o percentual médio de Substituição Tributária dos segmentos Indústria e Comércio incluídos na pesquisa.

De forma mais simplificada e resumida , é importante analisar as tabelas de apuração do imposto para o simples nacional, considerando a faixa do faturamento bruto acumulado dos últimos 12 meses e o anexo no qual esta empresa será tributada.

Por se tratar de assunto complexo e ter a necessidade de sabermos o valor do faturamento bruto, qual anexo o contribuinte está mencionado e se há ou não o valor da folha de pagamento dele de acordo com as regras do Simples Nacional, entendemos que isto aumenta o grau de automatização de menção para este imposto.

Claramente é importante ressaltar que a menção "incorreta" destes tributos aproximados não possui penalidade prevista em lei, concordamos que há sim a necessidade de mensurar na Nota Fiscal a real carga tributária ou de fato o valor aproximado do imposto pago nas operações de serviço e produto do contribuinte.

---

## O que é Lei do Pis e Cofins?

Source: https://nfe.io/docs/legislacao/lei-do-pis-e-cofins/index.md

# O que é Lei do Pis e Cofins?

O PIS e a COFINS são siglas de dois tributos pertencentes à Constituição Federal nos artigos 195 e 239, que significam:

PIS: Programa de Integração Social;

COFINS: Contribuição para Financiamento da Seguridade Social.

Estas duas contribuições incidem sobre a receita bruta das empresas (pessoas jurídicas), com exceção aos microempreendedores e empresas de pequeno porte, que contribuem pelo Simples Nacional.

Para o registro e apuração, os contabilistas utilizam os Códigos de Situação Tributária (CST) de PIS e COFINS, disponíveis na página do Sistema Público de Escrituração Digital.

O PIS e o COFINS possuem dois sistemas de tributação: regimes cumulativo e não cumulativo.

**Como personalizar a informação destaca na NF emitida pela NFe.io?**

> É importante ressaltar que a legislação exige de fato esta menção em NF, porém por critério do cliente pode ser personalizada a informação substituindo o texto que informamos como padrão da seguinte forma:

Para personalizar a informação da lei 10.833/2003 basta digitar: **"833/2003"** no campo de “Descrição do Serviço”, assim nosso sistema suprime o texto padrão da lei mencionada na nota, sendo possível descrevê-lo como preferir. Abaixo os exemplos onde se aplica esta ação.

**Para emissões via Excel:**

![](https://nfe.io/docs/app/uploads/2020/09/imagem4.png)

**Para emissões via API:**

![](https://nfe.io/docs/app/uploads/2020/09/imagem-2-1.png)

---

## Valor Aproximado dos Tributos - NF-e (mod. 55)

Source: https://nfe.io/docs/legislacao/valor-aproximado-dos-tributos-nf-e-mod-55/index.md

# Valor Aproximado dos Tributos - NF-e (mod. 55)

> Regra para definição do "Valor Aproximados dos Tributos".

O valor aproximado dos tributos informado no campo de informações complementares se baseia na soma do valor aproximado do total de tributos federais, estaduais e municipais de cada item. (items.tax.totalTax).

Essa informação deve ser enviada pelo cliente com base no valor informado na tabela fornecida pelo Instutito Brasileiro de Planejamento Tributário (IBPT) que contém a carga fiscal média aproximada de todos os produtos e serviços com base nos códigos das listas abaixo:

* Nomenclatura Comum do Mercosul (NCM)
* Lei Complementar 116/2003 (LC116)
* Serviço Nomenclatura Brasileira (NBS)

Concluindo, o valor aproximado dos tributos que é exibido no campo informações complementares será a soma do valor informado no campo "items.tax.totalTax" para cada item da nota, ou seja, o NFE.io vai calcular esse valor somando o valor informado em cada item da nota.

---

## Como efetuar consulta de dados cadastrais de empresas na cidade de Curitiba?

Source: https://nfe.io/docs/legislacao/consultas-curitiba/index.md

# Como efetuar consulta de dados cadastrais de empresas na cidade de Curitiba?

Para efetuar consultas dos dados cadastrais de uma empresa na cidade de Curitiba, você pode acessar http://www2.curitiba.pr.gov.br/gtm/PMAT_ISS_Consulta/frmdados.aspx e selecionar uma das opções abaixo:

* Consulta de Dados Cadastrais: A consulta retornará os dados de contribuintes cadastrados no CCM de Curitiba, em situação ativa ou inativa.
* Cartão de Identificação do Contribuinte: Essa consulta retornará apenas os dados de empresa prestadora de serviço e apenas com cadastro ativo.

---

## 2026.1 - Unificação da API de Contribuintes

Source: https://nfe.io/docs/release-notes/2026-1-unificacao-api-contribuintes/index.md

# Release 2026.1 - Unificação da API de Contribuintes.

## Visão Geral

A API de Contribuintes v2 (também conhecida como API Gerenciamento de Empresas) agora unifica o gerenciamento de empresas emissoras de documentos fiscais em uma **única API**.

Anteriormente utilizada apenas para NF-e e NFC-e, a API v2 passa a suportar também a configuração de **Inscrições Municipais para emissão de NFS-e**.

Com essa mudança, os endpoints de gerenciamento de empresas da API de NFS-e v1 (`/v1/companies/*`) serão **descontinuados** em favor dos endpoints da API v2 (`/v2/companies/*`).

---

## Por que essa mudança?

Até esta release, a plataforma NFE.io mantinha duas APIs separadas:

| API | Domínio | Finalidade |
|-----|---------|------------|
| **NFS-e v1** | `api.nfe.io` | Empresas para emissão de NFS-e |
| **Contribuintes v2 / Gerenciamento de Empresas** | `api.nfse.io` | Empresas para emissão de NF-e e NFC-e |

Essa separação trazia desafios para quem integrava com a plataforma:

| Desafio | Impacto |
|---------|---------|
| **Cadastro duplicado** | Uma empresa que emitia NFS-e e NF-e precisava ser cadastrada nas duas APIs separadamente |
| **Dados desatualizados** | Mudanças de endereço ou certificado precisavam ser replicadas manualmente em ambas as APIs |
| **Maior complexidade** | Desenvolvedores precisavam conhecer e manter integração com duas APIs distintas, em domínios diferentes |

**A unificação resolve isso**: uma empresa cadastrada uma única vez pode emitir qualquer tipo de documento fiscal.

---

## Como funciona hoje

### A API de Contribuintes v2 / API Gerenciamento de Empresas

A API de Contribuintes v2 (também chamada de API Gerenciamento de Empresas) (`/v2/companies/*`) é a API unificada da NFE.io para gerenciamento de empresas emissoras de documentos fiscais. Disponível no domínio `api.nfse.io`, ela permite:

- Cadastrar e gerenciar empresas (dados cadastrais, endereço, regime tributário)
- Vincular certificados digitais ICP-Brasil
- Configurar inscrições estaduais para emissão de NF-e e NFC-e
- Configurar inscrições municipais para emissão de NFS-e (novo)

Cada recurso possui endpoints dedicados, permitindo gerenciamento granular e independente de cada aspecto da empresa.

### Retrocompatibilidade com a API v1

Para facilitar a transição dos clientes que utilizam a API v1, optamos por manter **retrocompatibilidade** até o desligamento dos endpoints v1.

Isso significa que os endpoints da API v1 (`/v1/companies/*`) continuam funcionando normalmente. Internamente, porém, esses endpoints já direcionam as chamadas para a API v2:

```
Você chama                    O sistema executa internamente
-----------                   ------------------------------
POST /v1/companies      -->   POST /v2/companies
                              + POST /v2/companies/{id}/municipaltaxes

GET /v1/companies/:id   -->   GET /v2/companies/:id
                              + GET /v2/companies/:id/municipaltaxes/:im_id

PUT /v1/companies/:id   -->   PUT /v2/companies/:id
                              + PUT /v2/companies/:id/municipaltaxes/:im_id
```

**O que isso significa para você:**

| Aspecto | Implicação |
|---------|------------|
| **Continuidade** | Suas integrações atuais com a v1 continuam funcionando sem alterações até o desligamento |
| **Dados unificados** | Empresas criadas via v1 já existem na estrutura v2 — não há dados "separados" |
| **Migração simplificada** | Não há migração de dados, apenas atualização dos endpoints chamados |
| **Novos recursos** | Para usar funcionalidades exclusivas da v2 (múltiplas cidades, consulta de séries RPS), é necessário chamar os endpoints v2 diretamente |

Essa abordagem permite que você planeje e execute a migração no seu próprio ritmo, sem interrupções no serviço, até a data de descontinuação da v1.

---

## O que mudou

### Novos endpoints para Inscrições Municipais

A API v2 agora inclui endpoints dedicados para gerenciar Inscrições Municipais (necessárias para emissão de NFS-e):

| Método | Endpoint | O que faz |
|--------|----------|-----------|
| `POST` | `/v2/companies/{id}/municipaltaxes` | Cadastra uma nova inscrição municipal |
| `GET` | `/v2/companies/{id}/municipaltaxes` | Lista todas as inscrições da empresa |
| `GET` | `/v2/companies/{id}/municipaltaxes/{im_id}` | Consulta uma inscrição específica |
| `PUT` | `/v2/companies/{id}/municipaltaxes/{im_id}` | Atualiza dados da inscrição |
| `DELETE` | `/v2/companies/{id}/municipaltaxes/{im_id}` | Remove a inscrição |
| `GET` | `.../municipaltaxes/{im_id}/series/{serie}` | Consulta numeração de uma série RPS |

### Estrutura unificada da empresa

Com a unificação, uma empresa na API v2 pode conter:

```
Empresa (Company)
    │
    ├── Certificado Digital
    │   └── Usado para assinar NF-e, NFC-e e NFS-e
    │
    ├── Inscrições Estaduais (StateTax)
    │   └── Para emissão de NF-e e NFC-e
    │
    └── Inscrições Municipais (MunicipalTax)  ← NOVO
        └── Para emissão de NFS-e
```

---

## Benefícios

| Benefício | O que significa na prática |
|-----------|---------------------------|
| **Cadastro único** | Cadastre a empresa uma vez e configure-a para emitir NF-e, NFC-e ou NFS-e conforme necessário |
| **Certificado compartilhado** | O mesmo certificado digital é utilizado para todos os tipos de documento |
| **Inscrição Municipal segregada** | Uma empresa pode ter Inscrição Municipal no modelo aplicado atualmente para Inscrição Estadual |
| **Dados consistentes** | Atualização de endereço ou razão social reflete automaticamente em todas as emissões |
| **Integração simplificada** | Uma única API para aprender, integrar e manter |

---

## Detalhamento técnico

### Mapeamento de campos: v1 para v2

Na API v1, os dados da empresa e da inscrição municipal estavam misturados em um único objeto. Na v2, eles são separados em recursos distintos:

| Campo na v1 | Recurso na v2 | Campo na v2 |
|-------------|---------------|-------------|
| `name` | Company | `name` |
| `tradeName` | Company | `tradeName` |
| `federalTaxNumber` | Company | `federalTaxNumber` |
| `taxRegime` | Company | `taxRegime` |
| `address.*` | Company | `address.*` |
| `municipalTaxNumber` | MunicipalTax | `taxNumber` |
| `rpsSerialNumber` | MunicipalTax | `rpsSerialNumber` |
| `rpsNumber` | MunicipalTax | `rpsNumber` |
| `lastRpsSent` | MunicipalTax | `lastRpsSent` |
| `issRate` | MunicipalTax | `issRate` |
| `environment` | MunicipalTax | `environment` |
| `fiscalStatus` | MunicipalTax | `fiscalStatus` |
| `specialTaxRegime` | MunicipalTax | `specialTaxRegime` |
| `legalNature` | MunicipalTax | `legalNature` |
| `regionalTaxNumber` | MunicipalTax | `regionalTaxNumber` |
| `loginName` | MunicipalTax | `loginName` |
| `loginPassword` | MunicipalTax | `loginPassword` |
| `authIssueValue` | MunicipalTax | `authIssueValue` |
| `federalTaxDetermination` | MunicipalTax | `federalTaxDetermination` |
| `municipalTaxDetermination` | MunicipalTax | `municipalTaxDetermination` |

### Diferenças nas respostas

#### Listagem de empresas

**v1: `GET /v1/companies`**
```json
{
  "companies": [
    {
      "id": "abc123def456",
      "name": "ACME TECNOLOGIA LTDA",
      "federalTaxNumber": 12345678000199,
      "municipalTaxNumber": "123456",
      "rpsSerialNumber": "A1",
      "rpsNumber": 1500,
      "environment": "Production",
      "certificate": {
        "thumbprint": "1A2B3C4D5E6F7890ABCDEF1234567890ABCDEF12",
        "modifiedOn": "2026-01-15T10:30:00+00:00",
        "expiresOn": "2027-01-15T23:59:59+00:00",
        "status": "Active"
      },
      "address": {
        "state": "SP",
        "city": {
          "code": "3550308",
          "name": "São Paulo"
        },
        "district": "Centro",
        "street": "Avenida Paulista",
        "number": "1000",
        "postalCode": "01310100",
        "country": "BRA"
      }
    }
  ],
  "page": 1
}
```

**v2: `GET /v2/companies`**
```json
{
  "hasMore": false,
  "companies": [
    {
      "id": "abc123def456",
      "name": "ACME TECNOLOGIA LTDA",
      "federalTaxNumber": 12345678000199,
      "municipalTaxNumber": "mtx_789xyz",
      "stateTaxes": [],
      "municipalTaxes": ["mtx_789xyz"],
      "certificate": {
        "taxPayerId": "abc123def456",
        "thumbprint": "1A2B3C4D5E6F7890ABCDEF1234567890ABCDEF12",
        "taxId": "12345678000199",
        "subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=RFB e-CNPJ A1, O=ICP-Brasil, C=BR",
        "validUntil": "2027-01-15T23:59:59Z",
        "modifiedOn": "2026-01-15T10:30:00Z",
        "status": "Active"
      },
      "address": {
        "state": "SP",
        "city": {
          "code": "3550308",
          "name": "São Paulo"
        },
        "district": "Centro",
        "street": "Avenida Paulista",
        "number": "1000",
        "postalCode": "01310100",
        "country": "BRA"
      }
    }
  ]
}
```

**Principais diferenças:**

| Aspecto | v1 | v2 |
|---------|----|----|
| Paginação | `"page": 1` | `"hasMore": false` + cursor |
| Dados municipais | Campos inline | Referência por ID em `municipalTaxes` |
| Inscrições estaduais | Não existia | Array `stateTaxes` |

#### Consulta de empresa

**v1: `GET /v1/companies/:id`**
```json
{
  "companies": {
    "id": "abc123def456",
    "name": "ACME TECNOLOGIA LTDA",
    "tradeName": "ACME Tech",
    "federalTaxNumber": 12345678000199,
    "rpsSerialNumber": "A1",
    "rpsNumber": 1500,
    "issRate": 2.5,
    "environment": "Production",
    "fiscalStatus": "Active",
    "loginName": "usuario_prefeitura",
    "loginPassword": "******",
    "authIssueValue": "token_xyz_123"
  }
}
```

**v2: `GET /v2/companies/:id` + `GET /v2/companies/:id/municipaltaxes/:im_id`**
```json
// GET /v2/companies/:id
{
  "company": {
    "id": "abc123def456",
    "name": "ACME TECNOLOGIA LTDA",
    "tradeName": "ACME Tech",
    "federalTaxNumber": 12345678000199,
    "municipalTaxes": ["789xyz"],
    "stateTaxes": []
  }
}

// GET /v2/companies/:id/municipaltaxes/:im_id
{
  "municipalTax": {
    "id": "mtx_789xyz",
    "companyId": "abc123def456",
    "accountId": "56abc",
    "city": {
      "country": "BRA",
      "state": "SP",
      "code": "3550308",
      "name": "São Paulo"
    },
    "taxNumber": "123456",
    "rpsSerialNumber": "A1",
    "rpsNumber": 1500,
    "lastRpsSent": 1499,
    "issRate": 2.5,
    "environment": "Production",
    "fiscalStatus": "Active",
    "loginName": "usuario_prefeitura",
    "loginPassword": "******",
    "authIssueValue": "token_xyz_123",
    "rpsSerialNumbers": ["A1"]
  }
}
```

**Principais diferenças:**

| Aspecto | v1 | v2 |
|---------|----|----|
| Objeto raiz | `"companies": {...}` (singular incorreto) | `"company": {...}` |
| Dados municipais | Inline | Recurso separado |
| Séries RPS | Campo único | Array `rpsSerialNumbers` com histórico |

### IDs são compartilhados

O ID da empresa é o mesmo em ambas as APIs:

```
v1: /v1/companies/abc123def456
v2: /v2/companies/abc123def456
```

Para obter o ID da inscrição municipal, consulte o array `municipalTaxes` na resposta da empresa v2:

```json
{
  "company": {
    "id": "abc123def456",
    "municipalTaxes": ["mtx_789xyz"]
  }
}
```

---

## Como migrar da v1 para v2

Como seus dados já estão na estrutura v2 (graças ao adaptador interno), a migração consiste em atualizar seu código para chamar os novos endpoints.

### Mapeamento de endpoints

| Endpoint v1 (será descontinuado) | Endpoint v2 equivalente |
|---------------------------------|------------------------|
| `GET /v1/companies` | `GET /v2/companies` |
| `POST /v1/companies` | `POST /v2/companies` + `POST .../municipaltaxes` |
| `GET /v1/companies/:id` | `GET /v2/companies/:id` |
| `PUT /v1/companies/:id` | `PUT /v2/companies/:id` |
| `DELETE /v1/companies/:id` | `DELETE /v2/companies/:id` |
| `POST /v1/companies/:id/certificate` | `POST /v2/companies/:id/certificates` |

### Mudança de domínio

| API | Domínio |
|-----|---------|
| v1 (descontinuada) | `api.nfe.io` |
| v2 (usar esta) | `api.nfse.io` |

A autenticação permanece a mesma: `Authorization: <sua_api_key>`

→ **[Saiba como obter sua API Key](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/)**

### Cenários de migração

#### Cenário A: Empresa usa apenas NFS-e (existe só na v1)

Seus dados já estão na v2 por causa do adaptador. Para migrar:

**1. Obtenha o ID da empresa na v2 (é o mesmo da v1)**
```bash
curl -H "Authorization: sk_live_xxx" \
  https://api.nfse.io/v2/companies/abc123def456
```

**2. Obtenha o ID da inscrição municipal**
```bash
curl -H "Authorization: sk_live_xxx" \
  https://api.nfse.io/v2/companies/abc123def456/municipaltaxes
```
Resposta inclui o ID: `"id": "mtx_789xyz"`

**3. Atualize seu código para usar os novos endpoints**
```diff
- GET api.nfe.io/v1/companies/abc123def456
+ GET api.nfse.io/v2/companies/abc123def456
+ GET api.nfse.io/v2/companies/abc123def456/municipaltaxes/mtx_789xyz
```

#### Cenário B: Empresa usa NF-e/NFC-e e NFS-e

Se você já usa a v2 para NF-e/NFC-e e a v1 para NFS-e:

**1. Verifique se a inscrição municipal já existe na v2**
```bash
curl -H "Authorization: sk_live_xxx" \
  https://api.nfse.io/v2/companies/{company_id}/municipaltaxes
```

**2. Se existir, apenas atualize os endpoints no seu código**

**3. Se não existir, crie a inscrição municipal**
```bash
curl -X POST -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  https://api.nfse.io/v2/companies/{company_id}/municipaltaxes \
  -d '{
    "MunicipalTax": {
      "City": { "Code": "3550308", "Name": "São Paulo", "State": "SP" },
      "TaxNumber": "123456",
      "RpsSerialNumber": "A1",
      "RpsNumber": 1,
      "Environment": "Production"
    }
  }'
```

#### Cenário C: Empresa com múltiplas cidades (novo recurso)

Antes não era possível ter múltiplas inscrições municipais. Agora você pode:

```bash
# Adicionar segunda cidade
curl -X POST -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  https://api.nfse.io/v2/companies/{company_id}/municipaltaxes \
  -d '{
    "MunicipalTax": {
      "City": { "Code": "3304557", "Name": "Rio de Janeiro", "State": "RJ" },
      "TaxNumber": "789012",
      "RpsSerialNumber": "RJ1",
      "RpsNumber": 1,
      "Environment": "Production"
    }
  }'

# Listar todas as cidades
curl -H "Authorization: sk_live_xxx" \
  https://api.nfse.io/v2/companies/{company_id}/municipaltaxes
# Retorna array com São Paulo e Rio de Janeiro
```

---

## Nova documentação disponível

Além da unificação da API, publicamos uma nova seção de documentação com conteúdo mais detalhado sobre o gerenciamento de empresas.

### O que há de novo na documentação

| Seção | O que você encontra |
|-------|---------------------|
| **Visão Geral** | Explicação da arquitetura da API e hierarquia de recursos. Exemplo: diagrama mostrando que Company é o "hub" que conecta Certificate, StateTax e MunicipalTax |
| **API de Empresas** | Detalhamento de cada campo do cadastro. Exemplo: `TaxRegime` define o regime tributário (Simples Nacional, Lucro Presumido, etc.) usado no cálculo de impostos |
| **API de Inscrições Municipais** | Explicação do conceito de "espelhamento" - a API não cadastra na prefeitura, apenas armazena dados já obtidos pelo contribuinte para uso nas emissões |
| **Validações e erros** | Lista completa de regras de validação com códigos de erro. Exemplo: código `40028` indica que o código IBGE da cidade não corresponde à UF informada |
| **Exemplos de requisição** | Cada endpoint possui exemplos em cURL e PowerShell prontos para copiar e executar |
| **Boas práticas** | Recomendações como: enviar CNPJ sem pontuação, usar códigos IBGE de 7 dígitos, inicializar numeração RPS corretamente |

### Links para a documentação

- [Visão Geral - API de Contribuintes](/docs/documentacao/gerenciamento-empresas/visao-geral)
- [API de Empresas](/docs/documentacao/gerenciamento-empresas/api-empresas)
- [API de Certificados](/docs/documentacao/gerenciamento-empresas/api-certificados)
- [API de Inscrições Estaduais](/docs/documentacao/gerenciamento-empresas/api-inscricoes-estaduais)
- [API de Inscrições Municipais](/docs/documentacao/gerenciamento-empresas/api-inscricoes-municipais)

---

## Próximos passos: descontinuação da v1

A camada de compatibilidade que traduz chamadas v1 para v2 será removida em uma data a ser comunicada. A partir desse momento, os endpoints v1 deixarão de funcionar.

### Endpoints que serão descontinuados

- `GET /v1/companies`
- `POST /v1/companies`
- `GET /v1/companies/:company_id_or_tax_number`
- `PUT /v1/companies/:company_id`
- `DELETE /v1/companies/:company_id`
- `POST /v1/companies/:company_id/certificate`

### Cronograma

| Fase | Endpoints v1 | Ação recomendada |
|------|--------------|------------------|
| **Agora** | Funcionam normalmente (via adaptador) | Iniciar planejamento da migração |
| **Período de transição** | Funcionam, mas com avisos de depreciação | Executar a migração |
| **Após descontinuação** | Serão desligados | Usar exclusivamente a v2 |

**Prazo**: A data de descontinuação será comunicada em breve. Recomendamos iniciar a migração o quanto antes.

### Campo `municipalTaxNumber` na Company v2

O campo `municipalTaxNumber` no objeto Company da v2 atualmente contém o ID da MunicipalTax (não o número real da inscrição). Este campo será removido em uma versão futura.

**Recomendação**: Utilize o array `municipalTaxes` para obter os IDs das inscrições municipais e consulte o endpoint `/municipaltaxes/{id}` para obter o número real da inscrição (`taxNumber`).

---

## Precisa de ajuda?

- Consulte a [documentação completa](/docs/documentacao/gerenciamento-empresas/visao-geral)
- Em caso de dúvidas, entre em contato com nosso suporte

---

## 2026.2 - Melhorias no painel de empresas e acesso às notas

Source: https://nfe.io/docs/release-notes/2026-2-melhorias-plataforma-empresas/index.md

# Release 2026.2 - Melhorias no painel de empresas e acesso às notas

:::info Disponibilização gradual
Esta melhoria será liberada de forma gradual nos dias seguintes à publicação desta release note. Dependendo da sua conta, a nova experiência pode levar algumas horas até aparecer — não é necessária nenhuma ação da sua parte.
:::

## Visão Geral

Reunimos neste release um conjunto de melhorias focadas na **gestão de empresas** e no **acesso rápido às notas fiscais** dentro da plataforma NFE.io. O objetivo é simples: **menos cliques, mais contexto e atalhos para o que você mais usa**.

As mudanças abrangem quatro frentes:

1. **Novo painel centralizado da empresa** em `/companies`, reunindo todas as configurações em um único lugar.
2. **Cartões de Inscrição Estadual (IE)** diretamente no painel principal da empresa, com acesso em um clique à edição ou à lista completa.
3. **Cartão de Inscrição Municipal (IM)** também disponível no painel principal, com acesso em um clique ao cadastro ou à edição da IM da empresa.
4. **Novos atalhos para emissão em lote** de NFS-e e NF-e, disponíveis tanto no painel da empresa quanto nas telas de listagem de notas.

A seguir, os detalhes de cada mudança.

---

## 1. Novo painel centralizado de configurações da empresa

Todas as configurações da sua empresa agora estão reunidas em um único painel, acessível pelo endereço:

👉 [app.nfe.io/companies](https://app.nfe.io/companies)

:::info Atenção
O endereço antigo `/companies-v2` foi descontinuado. Qualquer acesso a esse caminho será redirecionado automaticamente para o novo endereço `/companies`. **Não é necessária nenhuma ação da sua parte.**
:::

![Novo painel centralizado de configurações da empresa](https://nfe.io/docs/static/docs/release-2026-2/painel-centralizado-companies.png)

---

## 2. Inscrição Estadual (IE)

A Inscrição Estadual da sua empresa pode ser visualizada e gerenciada diretamente pelo painel da empresa. O card de **Inscrição Estadual** aparece na tela principal da empresa.

:::tip Dica
Se a empresa possuir apenas **uma** IE cadastrada, o clique no card leva direto para a edição. Se houver **mais de uma**, você será direcionado para a lista completa.
:::

![Card de Inscrição Estadual no painel da empresa](https://nfe.io/docs/static/docs/release-2026-2/card-inscricao-estadual.png)

---

## 3. Inscrição Municipal (IM)

A **Inscrição Municipal** também está acessível diretamente pelo painel central da empresa. O clique no card leva direto para o cadastro ou para a edição da IM já registrada.

![Card de Inscrição Municipal no painel da empresa](https://nfe.io/docs/static/docs/release-2026-2/card-inscricao-municipal.png)

---

## 4. Novos botões de acesso: emissor em lote de NFS-e e NF-e

Para agilizar o acesso à emissão em lote, adicionamos botões de atalho em dois pontos estratégicos da plataforma: no **painel da empresa** e na **tela de listagem de notas**.

### NFS-e - Emitir Notas Fiscais de Serviço em Lote

O botão **"Emitir NFS-e em Lote"** aparece:

- No menu de ações do painel da empresa (ícone de ações no topo da página)
- No menu de ações da tela de listagem de NFS-e

Ao clicar, você será direcionado para o passo a passo da emissão via planilha.

![Menu de ações com atalho para emissão em lote](https://nfe.io/docs/static/docs/release-2026-2/menu-acoes-emissao-lote.png)

### NF-e - Emitir Notas Fiscais de Produto em Lote

O botão **"Emitir NF-e em Lote"** aparece:

- No menu de ações do painel da empresa (ícone de ações no topo da página)
- No menu de ações da tela de listagem de NF-e

Ao clicar, você será direcionado para o passo a passo da emissão via planilha.

---

## Resumo das melhorias

| O que mudou | Benefício |
|-------------|-----------|
| Painel centralizado da empresa | Menos cliques para encontrar qualquer configuração |
| IE e IM com cards informativos | Visão rápida sem precisar abrir a edição |
| Atalhos para emissão em lote de NFS-e e NF-e | Processo de emissão mais rápido a partir de pontos-chave da plataforma |
| Redirecionamento automático de `/companies-v2` | Migração transparente, sem quebra nos fluxos atuais |

---

## Precisa de ajuda?

Em caso de dúvidas, nossa equipe de suporte está à disposição pelos canais habituais.

---

## 2026.3 - CNPJ Alfanumérico para Emissões Fiscais

Source: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/index.md

# CNPJ Alfanumérico para Emissões Fiscais

> **Para quem é este comunicado:** clientes NFE.io que emitem NF-e, NFC-e ou NFS-e, ou que consomem nossas APIs de cadastro, distribuição e consulta.
>
> **Base regulatória:** Instrução Normativa RFB 2.229/2024.

## Visão geral

A **Receita Federal** começará a emitir CNPJs em um novo formato a partir de **01/08/2026** (data do 1º CNPJ alfanumérico cadastrado), conforme a **IN RFB 2.229/2024**. Para suportar essa mudança **sem quebrar nenhuma integração existente**, a NFE.io disponibiliza um **novo versionamento** das suas APIs — próprio de cada produto.

A regra é única e previsível em toda a plataforma: **suas versões atuais continuam funcionando exatamente como hoje** — elas nunca enxergam um CNPJ alfanumérico. Você só precisa agir se quiser cadastrar, emitir ou receber notas de empresas com CNPJ alfanumérico.

---

## O que está mudando

A diferença prática é simples:

- **Hoje**, um CNPJ é **só números** (ex.: `12.345.678/0001-99`).
- **A partir de 01/08/2026**, um CNPJ pode conter **letras nas primeiras 12 posições** (ex.: `12.ABC.345/000A-BC` — exemplo ilustrativo).

Os **dois últimos dígitos** (verificadores) continuam sendo numéricos. As letras **I, O, U, Q e F** não são usadas, para evitar confusão visual com os dígitos `0` e `1`.

**Importante:** os CNPJs já existentes **não mudam**. Quem tem CNPJ hoje continua com o mesmo CNPJ. O novo formato vale apenas para **empresas que serão cadastradas pela Receita Federal a partir de 01/08/2026** (e, em alguns casos, para inscrições secundárias).

---

## Por que isso importa para você

Se a sua aplicação:

- **Emite notas fiscais** (NF-e, NFC-e, NFS-e) pela NFE.io,
- **Cadastra empresas** pela nossa API,
- **Recebe documentos fiscais** (Distribuição de Documentos Fiscais),
- **Consulta notas** (API de Consulta de Notas),
- **Recebe webhooks** da NFE.io,

…então o **tipo do campo `federalTaxNumber`** muda. Hoje ele chega como **número inteiro** (`12345678000199`). Para CNPJs alfanuméricos, ele precisa chegar como **texto** (`"12ABC345000ABC"`).

:::warning Atenção — possível quebra de integração
Se você **armazena ou exibe** o campo `federalTaxNumber` como número (`long`, `int64`, `bigint`, etc. — qualquer tipo de armazenamento numérico), seu sistema vai **quebrar** ao encontrar uma empresa com CNPJ alfanumérico. Suas versões atuais protegem você disso (nunca devolvem alfa), mas, para suportar o formato novo, será necessário tratar o campo como **texto** (`string`).
:::

---

## Como a NFE.io resolveu — princípio "as versões atuais nunca veem CNPJ alfa"

Para não quebrar nenhum cliente atual, criamos uma regra única, simples e previsível em **todas as nossas APIs**:

| Versão da API | Comportamento |
|---|---|
| **Suas versões atuais** | **Congeladas.** Continuam funcionando exatamente como hoje. Recebem e devolvem CNPJ **apenas como número**. Nunca vão expor um CNPJ alfanumérico. |
| **Novo versionamento** (próprio de cada produto) | **Alfa-aware.** Aceita CNPJ numérico e alfanumérico. Devolve **sempre como texto** (`string`). |

Em outras palavras:

> **Você só precisa fazer alguma coisa se quiser cadastrar, emitir ou receber notas de empresas com CNPJ alfanumérico.** Se você só trabalha com CNPJs numéricos legados, **nada muda no seu lado**.

---

## O que muda na prática, por endpoint

| Cenário | Antes (hoje) | Depois (versão atual mantida) | Depois (novo versionamento) |
|---|---|---|---|
| Cadastrar empresa com CNPJ numérico | ✅ funciona | ✅ funciona igual | ✅ funciona |
| Cadastrar empresa com CNPJ alfa | n/a | ❌ **400 Bad Request** (requer o novo versionamento) | ✅ aceita e devolve `string` |
| Emitir NF-e/NFS-e com emissor alfa | n/a | ❌ **rejeitada** na versão atual (o erro orienta o novo versionamento; o formato varia por produto) | ✅ emite e devolve `string` |
| Receber documento fiscal (Distribuição de Documentos Fiscais) com CNPJ alfa | n/a | documento **processado**; `federalTaxNumber` tratado como **texto** | entregue como `string` |
| Webhook de nota com CNPJ alfa | n/a | **formato do payload** segue a versão da assinatura/webhook | entregue como `string` |
| Webhook de nota com CNPJ numérico | ✅ `number` | ✅ `number` (igual) | ✅ `string` |

**Resumo em uma frase:** ninguém recebe surpresa. Ou você está nas suas versões atuais e nunca enxerga alfa, ou você migrou para o novo versionamento e tudo vem como texto, de forma consistente.

#### Consultas (versionamento próprio em estudo)

As **APIs de Consulta** seguem em trilha própria: o versionamento ainda está **em estudo** (compatibilização entre as versões), e **haverá um versionamento próprio** para essa mudança, comunicado quando definido.

| Cenário | Versões atuais (mantidas) | Em homologação (versão própria em estudo) |
|---|---|---|
| Consultar Pessoa Jurídica (CNPJ) com CNPJ alfa | `404 Not Found` | aceita e devolve `string` (apenas para teste) |
| Consultar nota (NF-e) com chave/CNPJ alfa | `404 Not Found` | aceita e devolve `string` |

> Detalhes e roadmap no [guia **Consultas**](/release-notes/2026-3-cnpj-alfanumerico/consultas).

---

## Datas que você precisa anotar

| Data | O que acontece |
|---|---|
| **Junho/2026** (sem data definida) | ✅ **Sefaz / Emissor Nacional** abrem o ambiente de **homologação** para CNPJ alfanumérico — você poderá testar. |
| **1ª quinzena de julho/2026** | 🚀 **NFE.io disponibiliza o serviço** (novo versionamento, próprio de cada produto) para CNPJ alfanumérico. |
| **01/08/2026** | ⚠️ **1º CNPJ alfanumérico cadastrado pela Receita Federal.** A partir desse momento, qualquer fluxo de cadastro novo pode trazer um CNPJ com letras. |

---

## Como você deve se preparar

### ✅ Se sua integração só lida com CNPJs numéricos (90% dos casos)

1. **Você não precisa fazer nada agora.** Suas versões atuais continuam funcionando exatamente como hoje.
2. Só fique atento se um cliente seu **abrir uma empresa nova a partir de 01/08/2026** — pode ser que o CNPJ dela seja alfanumérico, e nesse caso as suas versões atuais vão rejeitar.
3. Quando precisar suportar esse cliente, migre o fluxo dele para o **novo versionamento do produto utilizado**.

### ⚠️ Se você quer estar pronto para CNPJ alfanumérico desde o dia 1

1. **Migre para o novo versionamento do produto utilizado** nos endpoints que você usa (cadastro, emissão, distribuição, consulta) — lembrando que cada produto tem o seu próprio versionamento.
2. **Mude o tipo de `federalTaxNumber`** no seu código de **número** (`long`, `int64`, etc. — qualquer tipo de armazenamento numérico) para **texto** (`string`).
3. **Analise como o `federalTaxNumber` é armazenado no seu banco de dados**: se hoje ele é guardado como tipo numérico (ex.: `BIGINT`, `NUMERIC(14)`), será necessário acomodar texto (ex.: `VARCHAR(14)` ou equivalente). A decisão de modelagem é sua.
4. **Revise comparações e máscaras**: `CNPJ.padStart(14, '0')` ou conversões implícitas para número vão quebrar.
5. **Teste em homologação SEFAZ** (já disponível) usando os CNPJs alfa de teste publicados pela própria Receita.
6. **Atualize seus webhooks** para o novo versionamento do produto (resposta sempre `string`) quando estiver pronto.

### 💡 Se você não tem certeza

Fale com a equipe de suporte da NFE.io — vamos te ajudar a entender qual versão da API você está usando hoje, e qual é o caminho mais curto para você ficar pronto.

---

## Sem flags, sem espera — quando estiver liberado, está liberado

Não temos nenhuma flag interna, whitelist ou liberação manual. **A SEFAZ e as prefeituras são o gate natural:**

- Enquanto a **origem do dado** (SEFAZ, no caso de NF-e/NFC-e; a prefeitura, no caso de NFS-e) ainda não autoriza CNPJ alfa em produção, sua emissão com CNPJ alfa pelo novo versionamento **chega até a autoridade e é rejeitada por ela** — você recebe a resposta real, com o **erro definido pela origem do dado** (ex.: `cStat=215` na NF-e).
- Quando a autoridade competente liberar o formato alfa em produção, **a emissão passa a ser autorizada automaticamente** (ex.: `cStat=100` na NF-e) — sem ninguém apertar nenhum botão na NFE.io.

Isso quer dizer que **você não precisa avisar a NFE.io** para "liberar" sua conta. Quando o regulador permitir, funciona.

---

## Garantias

✅ **Zero regressão para suas versões atuais** — não tocamos no contrato dessas versões.

✅ **CNPJs numéricos existentes continuam funcionando para sempre** — em todas as versões.

✅ **Você não vai receber erro `500` sem contexto** — quando algo for incompatível, a resposta é `400`/`404` (ou o erro definido pela origem do dado) com mensagem clara explicando que você precisa usar o novo versionamento do produto.

✅ **Sem prazo forçado de migração** — suas versões atuais não têm data de descontinuação por causa dessa mudança.

---

## Próximos passos

1. 📩 Compartilhe este comunicado com os **devs e arquitetos** que mantêm a integração com a NFE.io.
2. 📖 Consulte a [**Documentação técnica detalhada**](./documentacao-tecnica) para ver os contratos JSON antes/depois, exemplos `curl` e checklist de migração.
3. 🧪 Solicite acesso ao **novo versionamento em homologação** se quiser testar antes de 01/08/2026.
4. 💬 Dúvidas: nosso canal de suporte e o time de Customer Success estão preparados para responder. Para discussões técnicas mais profundas, abra ticket no portal de integradores.

---

> **Em resumo:**
>
> 1. **A Receita Federal vai emitir CNPJ com letras a partir de 01/08/2026.**
> 2. **Sua integração atual continua funcionando** — só não enxerga CNPJ alfa.
> 3. **Quando precisar suportar CNPJ alfa, migre para o novo versionamento do produto** e troque `number` por `string`.
> 4. **Sem flag, sem espera, sem regressão.**

---

## CNPJ Alfanumérico — Consultas

Source: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/consultas/index.md

# CNPJ Alfanumérico — Consultas

> Este guia detalha o comportamento do CNPJ alfanumérico nas APIs de **consulta**. O princípio de versionamento, os contratos JSON, webhooks, códigos de status e o checklist de migração estão na [Documentação técnica](/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica). Para as APIs de **emissão** e **distribuição**, veja [Emissões / DF-e](/release-notes/2026-3-cnpj-alfanumerico/emissoes-dfe).

## Visão geral das Consultas

As Consultas da NFE.io abrangem dois produtos, tratados nesta página:

- **Consulta de Notas** — lookup de uma NF-e emitida pela chave de acesso.
- **Consulta de Pessoa Jurídica (CNPJ)** — dados cadastrais de um CNPJ (`basicInfo`, inscrições estaduais), nos endpoints `/v2/legalentities/*`.

Diferente da emissão, a Consulta é um **lookup read-only** sobre dados que a Receita Federal e as SEFAZ já publicaram.

:::warning Versionamento das Consultas em estudo
Estamos **estudando uma forma de versionar de modo uniforme todas as APIs de Consulta** (CNPJ, Inscrição Estadual etc.). Hoje, em **homologação**, o suporte ao CNPJ alfanumérico está disponível para teste **nas rotas atuais** — mas isso é um **ambiente de testes, não o contrato definitivo**. Quando o modelo de versionamento for definido, a rota/versão que carregará o alfanumérico em **produção** será comunicada. Não cravamos hoje que o alfanumérico permanecerá na rota `/v2/...`. Veja [O que será implementado](#o-que-será-implementado) abaixo.
:::

## API de Consulta de Notas (consulta de NF-e)

**Endpoint base:** `https://api.nfe.io/v{version}/lookup`

| Cenário | Versões atuais | Versão própria (em estudo) |
|---|---|---|
| Lookup por chave de acesso numérica | ✅ normal | ✅ normal |
| Lookup por chave alfa | **`400 Bad Request`** | `200 OK` (`string`); **`404`** se não existir |
| Scan / busca por CNPJ alfa | **`400 Bad Request`** | `200 OK`; **`404`** se não existir |

## API de Consulta de Pessoa Jurídica (CNPJ / legalentities)

:::info Dado de implementação em homologação (homologação aberta a partir de junho/2026)
O comportamento descrito nesta seção reflete a **implementação disponível em homologação** e serve para você adaptar e testar sua integração. Ele **não constitui compromisso formal de produção** e pode evoluir. A documentação oficial e permanente da Consulta de Pessoa Jurídica será publicada em momento posterior.
:::

> **Não confunda com a 5.5.** A *Consulta de Notas* faz lookup de uma **NF-e emitida** pela chave de acesso. A **Consulta de Pessoa Jurídica** consulta os **dados cadastrais de um CNPJ** (`basicInfo`, inscrições estaduais etc.) nos endpoints `/v2/legalentities/*`. Apesar do caminho conter `legalentities`, trata-se da **consulta de CNPJ**, não de um cadastro de entidades.

:::warning Versionamento das Consultas em estudo
Estamos **estudando uma forma de versionar de modo uniforme todas as APIs de Consulta** (CNPJ, Inscrição Estadual etc.). Por isso, **não trate o caminho de versão atual (`/v2/...`) como o contrato definitivo do CNPJ alfanumérico**: a versão/rota que carregará o alfanumérico em produção será comunicada quando o modelo de versionamento for definido. Hoje o suporte a alfa existe **apenas em homologação** (`data.api.legalentities-homolog.nfe.one`), para você preparar e testar sua integração. Em **produção** (`legalentity.api.nfe.io`), os endpoints aceitam **apenas CNPJ numérico**; a liberação do alfanumérico em produção ainda não tem data formal.
:::

**Endpoint base (produção):** `https://legalentity.api.nfe.io/v2/legalentities`
**Endpoint base (homologação):** `https://data.api.legalentities-homolog.nfe.one/v2/legalentities`

A autenticação usa a **mesma API Key** no header `Authorization` (ou via query param `?apiKey=`).

### Endpoints afetados

```http
GET /v2/legalentities/basicInfo/{federalTaxNumber}
GET /v2/legalentities/stateTaxInfo/{state}/{federalTaxNumber}
GET /v2/legalentities/stateTaxForInvoice/{state}/{federalTaxNumber}
GET /v2/legalentities/stateTaxSuggestedForInvoice/{state}/{federalTaxNumber}
GET /v2/legalentities/stateTaxInfo/national/{state}/{federalTaxNumber}
GET /v2/legalentities/stateTaxInfo/issue/{state}/{federalTaxNumber}/onlyone
```

Em **homologação**, todos aceitam `federalTaxNumber` numérico ou alfanumérico. **Para CNPJ alfanumérico, envie o identificador sem pontuação** (apenas letras e dígitos, 14 caracteres) — o formato com máscara (`##.###.###/####-##`) retorna `404` para alfa. A detecção é automática: a API identifica se o identificador contém letras e seleciona o caminho de consulta apropriado.

### Comportamento

| Cenário (`basicInfo`) | Status | Observação |
|---|---|---|
| CNPJ numérico encontrado | `200` | Sem mudanças |
| CNPJ numérico ausente do cache | `200` (após consulta real-time) | Fallback existente preservado |
| CNPJ alfa encontrado em cache | `200` | Novo — em homologação; `federalTaxNumber` como `string` |
| CNPJ alfa **válido ausente** do cache | `404` | Novo — **sem fallback real-time** (≠ numérico) |
| Identificador inválido (tamanho/dígito/caracteres) | `400` | Validação — ex.: `{"errors":[{"message":"cnpj is null, white space or not valid"}]}` |

- **Response:** o campo `federalTaxNumber` é retornado **sem caracteres especiais** (apenas letras e dígitos). Trate-o sempre como `string`.
- **Sem fallback para alfa:** CNPJs alfanuméricos são indexados conforme a Receita Federal os disponibiliza. Se um CNPJ alfa **válido não estiver no cache**, a API retorna **`404`** em vez de buscar em tempo real — diferente do numérico, que faz fallback para consulta real-time.
- **Correção de zeros à esquerda:** CNPJs que **iniciam com zero** (ex.: `00730444000182`) agora são processados corretamente nos endpoints `basicInfo`.

:::warning `stateTaxInfo` — limitação conhecida em homologação
Para **parte** dos CNPJ alfanuméricos **presentes em cache**, o `stateTaxInfo` ainda pode retornar **`500`** ao montar a resposta (correção em andamento). Os documentos da massa de teste de `stateTaxInfo` abaixo respondem **`200`** normalmente — use-os para validar a Inscrição Estadual e **não assuma o caminho como totalmente estável** até o aviso de conclusão.
:::

> A adaptação de código (tipo `string`/`VARCHAR(14)`, regex `^[A-HJ-NPRT-Z0-9]{12}[0-9]{2}$`, normalização para maiúsculas e tratamento do `404`) é a mesma do [checklist da seção 8 da Documentação técnica](/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica#8-checklist-de-preparação).

### Massa de testes em homologação

Host: `https://data.api.legalentities-homolog.nfe.one`

`basicInfo` — `GET /v2/legalentities/basicInfo/{federalTaxNumber}`:

```text
V8SLYY68000157   PD8R3RYW000119   4Z5NMJ68000113   6S1Y9YBN000174
5W8DZV0E000117   64687957000130   670E5Z9W000118   75BZ6PW0000135
8K9X8744000138   A74MVL9LS6GG49   D7GMJ1VJ000131   E3D674YY000165
E3D674YY1SWJ28   G9J47ZWV000155   GHB4W0HR000130   H6E5B9YE9D2309
JADKNR6L000116   XVMZLYBE000173
```

`stateTaxInfo` — `GET /v2/legalentities/stateTaxInfo/{state}/{federalTaxNumber}`:

| CNPJ | UF |
|---|---|
| `KGKG99WE000159` | SP |
| `KGKG99WE9PAG10` | SE |
| `615ZKJ37000100` | SC |
| `615ZKJ37G4TP78` | RS |
| `NH556LTV000134` | RR |

### Exemplos cURL

```bash
# Produção (numérico) — segue funcionando normalmente
curl --location 'https://legalentity.api.nfe.io/v2/legalentities/basicInfo/14380200000121' \
  --header 'Authorization: <apiKey>'

# Homologação (alfanumérico) — disponível apenas em homologação por enquanto
curl --location 'https://data.api.legalentities-homolog.nfe.one/v2/legalentities/basicInfo/670E5Z9W000118' \
  --header 'Authorization: <apiKey>'

curl --location 'https://data.api.legalentities-homolog.nfe.one/v2/legalentities/stateTaxInfo/SP/KGKG99WE000159' \
  --header 'Authorization: <apiKey>'
```

> **Próximas etapas:** o suporte completo ao alfanumérico em `stateTaxInfo/*` e em Regime Tributário ainda está em andamento e será comunicado quando concluído.

## O que será implementado

O suporte ao CNPJ alfanumérico nas Consultas seguirá o mesmo princípio de não-quebra já adotado na emissão. O que está planejado (e ainda **não** vale como contrato até comunicação formal):

- **Versionamento uniforme das Consultas.** As versões numéricas atuais serão **congeladas** (resposta idêntica à de hoje, CNPJ como número), e o CNPJ alfanumérico passará a viver numa **versão alfa-aware dedicada**, que devolve o `federalTaxNumber` sempre como `string`.
- **Fronteira de versão.** Consultar um CNPJ com letras numa **versão atual (numérica)** retornará **`400 Bad Request`**, orientando o uso da versão alfa-aware. Na **versão alfa-aware**, a consulta retorna o dado (`200`) ou **`404 Not Found`** se o registro não existir.
- **Garantia de não-quebra.** Integrações atuais que só usam CNPJ numérico **continuam funcionando sem qualquer alteração**; um mecanismo de verificação de contrato impede mudanças acidentais nas versões antigas.
- **Correção do `stateTaxInfo` alfanumérico.** A limitação conhecida em homologação (alguns CNPJ alfa em cache retornando `500` no `stateTaxInfo`) está em correção, para responder `200` com os dados de Inscrição Estadual.

> **Prazo de referência:** a Receita Federal cadastra o 1º CNPJ alfanumérico em **01/08/2026** (IN RFB nº 2.229/2024). Use a homologação para preparar e validar sua integração antes disso.

---

## CNPJ Alfanumérico — Contratos e exemplos de payload

Source: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/contratos-payloads/index.md

# CNPJ Alfanumérico — Contratos e exemplos de payload

Esta página reúne exemplos de **request** e **response** por produto, para você **definir os contratos** da sua integração com CNPJ alfanumérico.

:::info Sobre os exemplos
- Os CNPJs alfanuméricos usados (`12ABC345000188`, `12ABC34501DE35`) são **exemplos** — use os CNPJs de teste publicados para homologação.
- A principal mudança de contrato é o tipo do campo `federalTaxNumber`, que passa a ser sempre **texto** (`string`) no novo versionamento.
- Produtos cujo contrato ainda está **em definição** não são detalhados aqui, para não publicar um formato sujeito a mudança.
:::

---

## 1. Consultas (CNPJ / Inscrição Estadual)

Consulta é **read-only** (GET, sem corpo de request). Exemplos abaixo são respostas reais do ambiente de **homologação**.

### 1.1 Consulta de CNPJ — `basicInfo`

```bash
GET /v2/legalentities/basicInfo/{federalTaxNumber}

curl 'https://data.api.legalentities-homolog.nfe.one/v2/legalentities/basicInfo/670E5Z9W000118' \
  --header 'Authorization: <apiKey>'
```

Response `200` (`federalTaxNumber` como `string`):

```json
{
  "legalEntity": {
    "tradeName": "GOOD LINE",
    "name": "KALEDI DISTRIB DE ARTIGOS DE ESCRITORIO LTDA",
    "federalTaxNumber": "670E5Z9W000118",
    "size": "ME",
    "openedOn": "1987-04-08T03:00:00+00:00",
    "address": {
      "state": "PR",
      "city": { "code": "4106902", "name": "Curitiba" },
      "district": "Novo Mundo",
      "streetSuffix": "Rua",
      "street": "Maria Bueno",
      "number": "276",
      "postalCode": "81020-180",
      "country": "BRA"
    },
    "statusOn": "2005-06-11T00:00:00+00:00",
    "status": "Active",
    "issuedOn": "2026-12-12T00:00:00+00:00",
    "shareCapital": 20000.0,
    "economicActivities": [
      { "type": "Main", "code": 4751201, "description": "Comércio varejista especializado de equipamentos e suprimentos de informática" }
    ]
  }
}
```

### 1.2 Consulta de Inscrição Estadual — `stateTaxInfo`

```bash
GET /v2/legalentities/stateTaxInfo/{state}/{federalTaxNumber}

curl 'https://data.api.legalentities-homolog.nfe.one/v2/legalentities/stateTaxInfo/SP/KGKG99WE000159' \
  --header 'Authorization: <apiKey>'
```

Response `200`:

```json
{
  "legalEntity": {
    "name": "POSTO BRASIL DE PRES PRUDENTE LTDA",
    "federalTaxNumber": "KGKG99WE000159",
    "createdOn": "2026-12-12T00:00:00+00:00",
    "taxRegime": "Normal",
    "stateTaxes": [
      {
        "status": "Abled",
        "taxNumber": "562097935119",
        "statusOn": "1990-06-04T00:00:00",
        "openedOn": "1990-06-04T00:00:00",
        "code": "SP",
        "address": {
          "city": { "code": "3541406", "name": "Presidente Prudente" },
          "district": "Vila Santa Izabel",
          "additionalInformation": "B",
          "streetSuffix": "Rua",
          "street": "José Tarifa Conde",
          "number": "1124",
          "postalCode": "19020-540"
        },
        "economicActivities": [ { "type": "Main", "code": 4731800 } ],
        "nfe":  { "status": "Unabled", "description": "Não credenciado para emissão da NF-e" },
        "nfse": { "status": "Unknown", "description": "Situação desconhecida" },
        "cte":  { "status": "Unknown", "description": "A SEFAZ não fornece a informação" },
        "nfce": { "status": "Unknown", "description": "Situação desconhecida" }
      }
    ]
  }
}
```

### 1.3 Erros das Consultas

Identificador inválido — `400`:

```json
{ "errors": [ { "message": "cnpj is null, white space or not valid" } ] }
```

CNPJ alfanumérico válido não encontrado — `404` (sem busca em tempo real para alfa; ver [Consultas](/release-notes/2026-3-cnpj-alfanumerico/consultas)).

---

## 2. Cadastro de empresas (`/v3/companies`)

Novo versionamento = **v3**. Empresa com CNPJ alfanumérico consultada por uma versão atual (v1/v2) retorna `400` (ver 2.3).

### 2.1 Request — criação (`POST /v3/companies`)

```json
{
  "company": {
    "name": "EMPRESA ALFANUMERICA LTDA",
    "tradeName": "ALFA",
    "federalTaxNumber": "12ABC345000188",
    "taxRegime": "Isento",
    "address": {
      "state": "SP",
      "city": { "code": "3550308", "name": "Sao Paulo" },
      "district": "Centro",
      "street": "Rua das Flores",
      "number": "100",
      "postalCode": "01001000",
      "country": "BRA",
      "additionalInformation": ""
    }
  }
}
```

> `federalTaxNumber` é aceito como **`string`** (recomendado) ou **`number`** inteiro (compatibilidade). Número fracionário → `400`.

### 2.2 Response — `GET /v3/companies/{id}`

Mesmos campos da versão anterior **+ `accountId`**, com `federalTaxNumber` sempre `string`:

```json
{
  "id": "a1b2c3d4e5f6478090a1b2c3d4e5f678",
  "accountId": "...",
  "name": "EMPRESA ALFANUMERICA LTDA",
  "federalTaxNumber": "12ABC345000188",
  "taxRegime": "Isento",
  "address": { "state": "SP", "city": { "code": "3550308", "name": "Sao Paulo" }, "district": "Centro", "street": "Rua das Flores", "number": "100", "postalCode": "01001000" },
  "stateTaxes": [],
  "municipalTaxes": [],
  "status": "Active",
  "createdOn": "2026-12-12T00:00:00+00:00",
  "modifiedOn": "2026-12-12T00:00:00+00:00"
}
```

### 2.3 Erro — empresa alfa via versão atual (v1/v2)

`400 Bad Request`:

```json
{ "errors": [ { "code": 40002, "message": "Esta empresa contém CNPJ alfanumérico e requer a API v3; as rotas v1/v2 não suportam CNPJ alfanumérico." } ] }
```

---

## 3. NF-e / NFC-e (`/v3/companies/{companyId}/productinvoices`)

Novo versionamento = **v3**. A principal mudança é o `federalTaxNumber` como `string`; o restante do corpo de emissão segue o formato atual.

### 3.1 Request — emissão (participantes com CNPJ alfanumérico)

```json
{
  "issuer":    { "federalTaxNumber": "12ABC345000188" },
  "buyer":     { "type": "LegalEntity", "federalTaxNumber": "98XYZ123000158" },
  "transport": { "transportGroup": { "federalTaxNumber": "34HJK987000140" } }
}
```

### 3.2 Response — nota emitida (chave de acesso alfanumérica)

`federalTaxNumber` como `string` e **chave de acesso** com dígito verificador por Módulo-11 **ASCII−48**:

```json
{
  "accessKey": "35260612ABC345000188550010000000031100000037",
  "issuer": { "federalTaxNumber": "12ABC345000188" }
}
```

Webhook (novo versionamento, `apiVersion: 3`):

```json
{ "payload": { "apiVersion": 3, "issuer": { "federalTaxNumber": "18792479000101" }, "buyer": { "federalTaxNumber": "12ABC345000188" } } }
```

### 3.3 Erro — alfa via versão atual

- Consultar, por uma versão atual, uma nota emitida no novo versionamento → `404`:
  ```json
  { "message": "invoice not found" }
  ```
- A emissão por uma versão atual com emissor alfanumérico não é aceita (a empresa alfanumérica não existe nas versões atuais).

---

## 4. Distribuição de Documentos Fiscais (inbound)

O `federalTaxNumber` é entregue como **texto**; um CNPJ alfanumérico aparece como `string` nos mesmos campos (ex.: `"12ABC34501DE35"`). Exemplo de corpo (com valores numéricos para ilustrar a forma):

```json
{
  "issuer":  { "federalTaxNumber": "57622466000146" },
  "buyer":   { "federalTaxNumber": "99999999999999" },
  "company": { "federalTaxNumber": "99999999999999" }
}
```

---

## CNPJ Alfanumérico — Documentação Técnica

Source: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica/index.md

# CNPJ Alfanumérico — Documentação Técnica

Este guia é o companheiro técnico do [Comunicado](/docs/release-notes/2026-3-cnpj-alfanumerico). Se você é desenvolvedor ou arquiteto e precisa adaptar uma integração, é aqui que estão os contratos JSON, os comportamentos por produto e o checklist de migração.

> **Base regulatória:** IN RFB 2.229/2024 · NT Conjunta ENCAT 2025.001 v1.00.

---

## Índice

1. [Visão geral em 30 segundos](#1-visão-geral-em-30-segundos)
2. [O novo formato do CNPJ](#2-o-novo-formato-do-cnpj)
3. [O princípio de versionamento da NFE.io](#3-o-princípio-de-versionamento-da-nfeio)
4. [O que muda no contrato da API](#4-o-que-muda-no-contrato-da-api)
5. [Mudanças por produto](#5-mudanças-por-produto)
6. [Webhooks](#6-webhooks)
7. [Códigos de status e mensagens de erro](#7-códigos-de-status-e-mensagens-de-erro)
8. [Checklist de preparação](#8-checklist-de-preparação)
9. [Cenários de teste em homologação](#9-cenários-de-teste-em-homologação)
10. [Perguntas frequentes](#10-perguntas-frequentes)

---

## 1. Visão geral em 30 segundos

A partir de 01/08/2026, a Receita Federal passa a emitir CNPJs que podem conter letras. Isso afeta diretamente quem já integra com a gente — então a pergunta que guiou todo o nosso desenho foi: **como dar suporte ao formato novo sem que ninguém precise mexer no que já funciona hoje?**

A resposta foi criar um **novo versionamento** das APIs, com uma regra simples de entender:

| Versão | Status | Tipo de `federalTaxNumber` na request | Tipo na response/webhook |
|---|---|---|---|
| Versionamento atual (v1) | congelada | `number` | `number` |
| Versionamento atual (v2) | congelada (boundary defensivo) | `number` | `number` |
| **Novo versionamento** | **novo** | `string` (aceita `number` por compatibilidade na entrada) | **sempre `string`** |

> Cada produto tem o seu **próprio** novo versionamento — o número da versão pode variar entre produtos (emissão, cadastro, distribuição e cada consulta evoluem em ritmos diferentes).

Se você guardar só uma frase deste documento, que seja esta:

> **Mantra:** *"O versionamento atual nunca enxerga CNPJ alfa. O novo versionamento é alfa-aware."*

---

## 2. O novo formato do CNPJ

### 2.1 Especificação

O CNPJ continua com 14 posições, mas agora as 12 primeiras podem misturar letras e números. Só os dois dígitos verificadores no final permanecem estritamente numéricos:

```
14 posições totais
   ├── 12 alfanuméricas (raiz 8 + ordem 4) — pode conter [A-Z0-9]
   └── 2 numéricas (dígitos verificadores) — sempre [0-9]

Letras vedadas: I, O, U, Q, F
   (evitam confusão visual com 0 e 1)

Regex efetiva: ^[A-HJ-NPRT-Z0-9]{12}[0-9]{2}$
```

### 2.2 Exemplos

Lado a lado, fica fácil ver a diferença:

```text
CNPJ numérico legado:  12345678000199    (14 dígitos)
CNPJ alfanumérico:     12ABC345000ABC    (12 alfanum + 2 dígitos)
```

### 2.3 Algoritmo do dígito verificador

O cálculo continua sendo o bom e velho **Módulo 11** — a novidade é que os pesos passam a ser aplicados sobre o **valor ASCII menos 48** de cada caractere. Na prática, isso faz os dígitos `0`–`9` continuarem valendo `0`–`9` e dá um valor numérico para cada letra:

```
'0' (ASCII 48) →  0
'9' (ASCII 57) →  9
'A' (ASCII 65) → 17
'Z' (ASCII 90) → 42
```

Se você valida o dígito verificador no seu lado, precisa atualizar esse algoritmo. Nossa recomendação, porém, é **não reinventar a roda: delegue para uma biblioteca oficial de validação de CNPJ** da sua linguagem. Assim você não precisa se preocupar com os detalhes do cálculo.

---

## 3. O princípio de versionamento da NFE.io

### 3.1 Tabela canônica

Esta tabela resume, camada por camada, o que acontece quando um CNPJ alfanumérico encontra cada versão das APIs de **emissão, cadastro e distribuição**. A leitura é direta: na coluna legado, o sistema **protege** você do formato novo; na coluna do novo versionamento, ele o **entrega** de forma consistente.

| Camada | Versionamento atual | Novo versionamento (alfa-aware) |
|---|---|---|
| API de Empresas (cadastro) | empresa alfa → **400 Bad Request** (requer o novo versionamento) | aceita, response `string` |
| Emissão de NF-e/NFC-e | issuer alfa → **400 Bad Request** | aceita, response `string` |
| Emissão de NFS-e | issuer alfa → **400 Bad Request** | aceita, response `string` |
| Distribuição de Documentos Fiscais (inbound) | `federalTaxNumber` tratado como **texto**; visibilidade segue a versão da assinatura | documento alfa entregue como `string` |
| Webhook | **formato do payload** segue a versão da assinatura/webhook | entregue como `string` |
| Response JSON | **sempre `number`** | **sempre `string`** |

#### Consultas — trilha própria de versionamento

As **APIs de Consulta** seguem em trilha separada das de emissão. O **versionamento ainda está em estudo**, voltado à **compatibilização entre as versões** existentes. Hoje, em homologação, o CNPJ alfanumérico está disponível **apenas para teste** — porém **vamos trabalhar em um versionamento próprio para essa alteração** (uma versão alfa-aware dedicada às Consultas), que será comunicado quando definido. O contrato pretendido: a **versão atual** recusa CNPJ alfa (`400`) e o **novo versionamento** entrega o dado (`200`) ou `404` se não existir. Detalhes e roadmap em [Consultas](/release-notes/2026-3-cnpj-alfanumerico/consultas).

| Camada | Versionamento atual | Versão alfa-aware |
|---|---|---|
| API de Consulta de Notas | CNPJ alfa → **400 Bad Request** | `200 OK` (`string`); **`404`** se o registro não existir |
| API de Consulta de Pessoa Jurídica (CNPJ) | CNPJ alfa → **400 Bad Request** | `200 OK` (`string`); **`404`** se o registro não existir |

### 3.2 Por que desenhamos assim

Três objetivos guiaram esse desenho — e vale a pena entender cada um, porque eles explicam praticamente todo o comportamento descrito neste documento:

1. **Zero regressão.** Para clientes nas suas versões atuais, nada muda — nem no schema, nem no tipo do campo, nem no comportamento. Quem está integrado hoje pode ignorar tranquilamente toda essa mudança.
2. **Sem flags, sem espera.** Não existe feature flag, whitelist nem código `412` para "habilitar" o alfa. Quem decide quando o alfa entra em produção é a **origem do dado** (a SEFAZ, na NF-e/NFC-e; as prefeituras, na NFS-e): no instante em que ela libera o formato alfa, o sistema NFE.io passa a autorizar automaticamente (ex.: `cStat=100` na NF-e), sem nenhuma intervenção manual da nossa parte.
3. **Determinístico.** O novo versionamento não escolhe o tipo do JSON conforme o valor do CNPJ — ele é **sempre `string`**. Isso significa que seu parser nunca precisa lidar com union types nem adivinhar o formato; é texto, ponto.

---

## 4. O que muda no contrato da API

### 4.1 Request — o novo versionamento aceita os dois tipos

Para facilitar a sua vida na migração, o novo versionamento é flexível na entrada: ele aceita `federalTaxNumber` como **string** (o jeito recomendado) ou como **number** (por compatibilidade, útil enquanto você ainda tem código antigo). Internamente, tudo é normalizado para `string`.

> Os valores de `federalTaxNumber` nos exemplos abaixo são **ilustrativos** — não são CNPJs reais.

```jsonc
// ✅ Recomendado (novo versionamento)
{
  "federalTaxNumber": "12ABC345000ABC"
}

// ✅ Também aceito (novo versionamento, compat — para CNPJ numérico)
{
  "federalTaxNumber": 12345678000199
}

// ❌ Versionamento atual rejeita string com letras
{
  "federalTaxNumber": "12ABC345000ABC"  // → 400 Bad Request
}
```

### 4.2 Response — novo versionamento sempre string

Na saída, o novo versionamento é rígido de propósito: **sempre `string`**, seja o CNPJ numérico ou alfanumérico. Essa consistência é o que permite que o seu parser não tenha surpresas.

> Os valores de `federalTaxNumber` nos exemplos abaixo são **ilustrativos** — não são CNPJs reais.

```jsonc
// Versionamento atual (hoje e amanhã — congelada)
{
  "id": "...",
  "federalTaxNumber": 12345678000199,    // number
  "name": "Empresa Exemplo S.A."
}

// Novo versionamento — CNPJ numérico
{
  "id": "...",
  "federalTaxNumber": "12345678000199",  // string
  "name": "Empresa Exemplo S.A."
}

// Novo versionamento — CNPJ alfanumérico
{
  "id": "...",
  "federalTaxNumber": "12ABC345000ABC",  // string
  "name": "Empresa Nova Ltda."
}
```

### 4.3 Selecionando a versão

A versão é escolhida **pelo endpoint** — o segmento de versão fica na URL (ex.: `/v{versão}/...`). **Não há versionamento por header**: o número da versão está sempre no caminho da chamada.

**O número da versão varia por produto** — cada API tem a sua *versão atual* (numérica, congelada) e a sua *versão alfa-aware* (o novo versionamento), e essas numerações **não são iguais entre os produtos**. Consulte a numeração de cada um nos guias [Emissões / DF-e](/release-notes/2026-3-cnpj-alfanumerico/emissoes-dfe) e [Consultas](/release-notes/2026-3-cnpj-alfanumerico/consultas).

---

## 5. Mudanças por produto

O comportamento detalhado por produto está organizado em dois guias:

- **[Emissões / DF-e](/release-notes/2026-3-cnpj-alfanumerico/emissoes-dfe)** — cadastro de empresas, NF-e/NFC-e, NFS-e e Distribuição de DF-e.
- **[Consultas](/release-notes/2026-3-cnpj-alfanumerico/consultas)** — Consulta de Notas (NF-e) e Consulta de Pessoa Jurídica (CNPJ / legalentities).

---

## 6. Webhooks

### 6.1 Regra de envio

Aqui o critério é importante e às vezes contraintuitivo, então vale destacar:

> **O webhook segue a versão do contrato que o subscriber assinou** — e não o valor do CNPJ da nota.

| Subscriber assinado em | CNPJ numérico | CNPJ alfanumérico |
|---|---|---|
| **Versionamento atual** | ✅ entregue, payload com `federalTaxNumber: number` | 🚫 **não entregue** |
| **Novo versionamento** | ✅ entregue, payload com `federalTaxNumber: string` | ✅ entregue, payload com `federalTaxNumber: string` |

### 6.2 Migração de webhook

A migração de webhook é tranquila e pode ser feita sem downtime:

1. Cadastre uma **nova subscription no novo versionamento** apontando para um endpoint já preparado para receber `string`.
2. Com as duas rodando em paralelo e o novo versionamento confirmado, **desligue o versionamento atual**.
3. Lembre-se: não há "duplicação" automática — se você mantiver as duas subscriptions ativas, vai receber o mesmo evento numérico nas duas versões.

### 6.3 Exemplo de payload — webhook do novo versionamento

```jsonc
{
  "event": "invoice.authorized",
  "data": {
    "id": "5f9...",
    "issuer": {
      "federalTaxNumber": "12ABC345000ABC",   // string sempre
      "name": "Empresa Nova Ltda."
    },
    "accessKey": "35260512ABC345000ABCxx...",
    "status": "Authorized"
  }
}
```

---

## 7. Códigos de status e mensagens de erro

:::info Esta seção cobre as APIs de **emissão**
Os códigos e mensagens abaixo descrevem o comportamento das APIs de **emissão** (NF-e/NFC-e/NFS-e, cadastro e distribuição). O comportamento de erro das **Consultas** está no guia [Consultas](/release-notes/2026-3-cnpj-alfanumerico/consultas).
:::

### 7.1 Tabela canônica

Quando algo dá errado, a resposta é sempre clara sobre o motivo — nada de `500` genérico:

| Status | Quando ocorre | Mensagem típica |
|---|---|---|
| `400 Bad Request` / rejeição | Tentativa de emitir com CNPJ alfa na versão atual | a versão atual rejeita; o erro orienta o novo versionamento. **O formato varia por produto** — ex.: NFS-e devolve texto orientando a v3; na NF-e/NFC-e a emissão na versão atual não resolve a empresa alfa |
| `400 Bad Request` | `federalTaxNumber` com formato inválido (tamanho ≠ 14, letras vedadas I/O/U/Q/F, DV inválido) | `{"message":"Invalid federalTaxNumber"}` |
| `404 Not Found` | Consulta, via versão atual, de uma **nota emitida no novo versionamento** (CNPJ alfa) | `{"message":"Not Found"}` |
| `cStat=215` (resposta SEFAZ — **NF-e/NFC-e**) | XML chegou à SEFAZ, mas SEFAZ rejeitou (XSD antigo) | resposta real da SEFAZ, sem mascaramento NFE.io |
| `cStat=100` (**NF-e/NFC-e**) | SEFAZ aceitou (caminho feliz, alfa autorizado) | `Autorizado o uso da NF-e` |

### 7.2 O que **não** existe

Para evitar que você procure por algo que não vai encontrar:

- ❌ Não há `412 Precondition Failed` — não usamos esse código para isto.
- ❌ Não há feature flag de "habilitar CNPJ alfa para minha conta".
- ❌ Não há whitelist por AccountId.

---

## 8. Checklist de preparação

### 8.1 Para quem só usa CNPJ numérico

A boa notícia: é uma lista curtíssima.

- [ ] Documentar internamente que **`federalTaxNumber` no versionamento atual continua `number`** — nada precisa mudar.
- [ ] Treinar suporte/atendimento: quando um cliente final pedir suporte a CNPJ alfa, **direcionar para a migração ao novo versionamento do produto utilizado**.

### 8.2 Para quem vai suportar CNPJ alfanumérico

Aqui vale ser metódico. Separamos por frente para você não esquecer nenhum ponto.

#### Código

- [ ] Tipo de `federalTaxNumber` em modelos / DTOs / entities → `string` (não `long`, `int64`, `bigint`, etc. — qualquer tipo de armazenamento numérico).
- [ ] Validação de formato → aceita `[A-HJ-NPRT-Z0-9]{12}[0-9]{2}` ou usar a lib oficial da sua linguagem para CNPJ.
- [ ] Validação de DV → Módulo 11 com **ASCII−48**.
- [ ] Remover qualquer `Long.parseLong(cnpj)`, `int64(cnpj)`, `cnpj.toFixed(0)`, `cnpj.padStart(14, '0')` aplicado **antes de saber se é numérico**.
- [ ] Trocar máscara de display de `"00.000.000/0000-00"` para algo tolerante a letras (ou exibir sem máscara).

#### Banco de dados

- [ ] **Analise como o `federalTaxNumber` é armazenado** no seu banco: se hoje é um tipo numérico (ex.: `BIGINT`, `NUMERIC(14)`), será necessário acomodar texto (ex.: `VARCHAR(14)` ou equivalente). A decisão de modelagem é sua.
- [ ] Índices de igualdade → continuam funcionando, mas **revise índices que dependiam de ordenação numérica**.
- [ ] Considere `COLLATE` ou normalização para `UPPER` no armazenamento (CNPJs alfa são `[A-Z]`, mas inputs podem vir minúsculos).

#### Integração

- [ ] Trocar o endpoint da **versão atual** pelo do **novo versionamento** do produto que você usa (o número da versão varia por produto).
- [ ] Atualizar a webhook subscription para o novo versionamento.
- [ ] Atualizar parsers JSON para esperar `string` (a maioria das libs lida nativamente, mas linguagens de tipagem forte podem precisar de cast).
- [ ] Logs / observabilidade → garantir que o CNPJ não está sendo serializado como número em algum sink (ex.: mapping do Elasticsearch).

#### Teste

- [ ] Cenário positivo numérico no novo versionamento.
- [ ] Cenário positivo alfa no novo versionamento.
- [ ] Cenário no versionamento atual com payload `string` contendo letras → confirmar `400`.
- [ ] Cenário no versionamento atual com `GET` de empresa alfa → confirmar `400`.
- [ ] Webhook do novo versionamento com CNPJ alfa → confirmar entrega e parse.

---

## 9. Cenários de teste em homologação

A **Sefaz / Emissor Nacional** disponibilizam CNPJs alfanuméricos de teste no ambiente de homologação **a partir de junho/2026 (sem data definida)** — use-os para validar a integração de ponta a ponta antes de **01/08/2026**.

### 9.1 Exemplos didáticos (não reais — substitua pelos publicados pela Receita)

```text
CNPJ alfa de homologação:         12ABC345000ABC
CNPJ numérico de homologação:     12345678000199
```

### 9.2 Fluxo recomendado

Um roteiro que cobre os principais caminhos:

1. Cadastre a empresa alfa via `POST /v3/companies` (homologação).
2. Tente emitir uma NF-e/NFS-e de teste pelo novo versionamento.
3. Observe a resposta da **origem do dado** (na NF-e/NFC-e, via `cStat` da SEFAZ; na NFS-e, conforme a prefeitura):
   - autorizada (ex.: `cStat=100` na NF-e) → caminho feliz, alfa funcionando.
   - rejeitada (ex.: `cStat=215` na NF-e) → a autoridade ainda não liberou o formato alfa (esperado em alguns períodos).
4. Confira o webhook do novo versionamento chegando com `string`.
5. Por fim, tente a mesma operação via versionamento atual → confirme os `400`/`404` esperados.

---

## 10. Perguntas frequentes

**P1. Vocês vão descontinuar o versionamento atual?**
Não por causa dessa mudança. O versionamento atual continua suportado por tempo indeterminado, com o contrato congelado. Se houver depreciação no futuro, ela será comunicada com antecedência pelos canais oficiais.

**P2. Preciso pedir liberação para emitir com CNPJ alfa?**
Não. Não existe whitelist, feature flag nem aprovação manual. Quando você usa o novo versionamento com CNPJ alfa, a requisição vai até a SEFAZ/prefeitura, e a emissão só funciona se a autoridade aceitar.

**P3. O que acontece se eu mandar uma `string` "12345678000199" (numérico, mas como texto) no novo versionamento?**
Funciona normalmente. O novo versionamento aceita os dois tipos na entrada — numérico ou alfanumérico, como `string` ou `number`.

**P4. E se eu mandar `number` no versionamento atual com um CNPJ que deveria existir como alfa?**
JSON `number` não consegue representar letras. Se você tentar mandar `"12ABC345000ABC"` no versionamento atual (que espera número), a request falha no parser/validador → `400 Bad Request`.

**P5. Os CNPJs numéricos atuais vão virar alfa em algum momento?**
Não. CNPJs já emitidos pela Receita Federal **continuam numéricos**. Só os novos cadastros (a partir de 01/08/2026) é que podem vir alfanuméricos.

**P6. Como sei se um CNPJ é alfa ou numérico programaticamente?**
Verifique se há algum caractere fora do conjunto `[0-9]` nas 12 primeiras posições. Se houver, é alfa. Os 2 dígitos finais (DV) são sempre numéricos.

```js
function isAlphanumericCnpj(cnpj) {
  return /[A-Z]/.test(cnpj.substring(0, 12));
}
```

**P7. O DANFE / PDF da nota vai mudar?**
Internamente, sim — o barcode da chave de acesso passa a aceitar caracteres alfanuméricos (CODE-128A). Visualmente, o layout permanece o mesmo. Se você consome o PDF, **nada muda no seu lado**.

**P8. E o cliente que tem rotina de batch processando milhares de notas?**
Comece fazendo um inventário dos pontos onde `federalTaxNumber` é parseado. Migre o tipo e os parsers para `string` e rode tudo em homologação antes de subir para produção. Nossa recomendação é migrar de **forma incremental**: comece pelo fluxo de consulta (o mais barato), depois cadastro e, por último, emissão.

**P9. E os meus dados históricos com CNPJ numérico no Mongo/Postgres?**
Eles permanecem como estão. A NFE.io **não exige reescrita** dos dados antigos. Internamente, lemos o campo de forma polimórfica (`number` ou `string`) e sempre o expomos como `string` no novo versionamento.

**P10. Onde abrir dúvidas?**
- Suporte técnico: portal de integradores NFE.io.
- Documentação pública: https://nfe.io/docs.
- Fontes regulatórias oficiais: IN RFB 2.229/2024 e NT Conjunta ENCAT 2025.001 v1.00.

---

> **Resumo técnico em 3 linhas:**
>
> 1. Trate `federalTaxNumber` como `string` em qualquer integração nova.
> 2. Use o **novo versionamento** de cada produto para consumir/produzir CNPJ alfa (o número da versão varia por produto).
> 3. Não invente whitelist nem flag — a origem do dado (SEFAZ/prefeitura) é o único gate real.

---

## CNPJ Alfanumérico — Emissões e DF-e

Source: https://nfe.io/docs/release-notes/2026-3-cnpj-alfanumerico/emissoes-dfe/index.md

# CNPJ Alfanumérico — Emissões e DF-e

> Este guia detalha o comportamento do CNPJ alfanumérico nos produtos de **emissão** e **distribuição**. O princípio de versionamento ("as versões atuais nunca veem CNPJ alfa; o novo versionamento é quem entende" — lembrando que cada produto tem o seu próprio versionamento), os contratos JSON, webhooks, códigos de status e o checklist de migração estão na [Documentação técnica](/release-notes/2026-3-cnpj-alfanumerico/documentacao-tecnica). Para as APIs de **consulta**, veja [Consultas](/release-notes/2026-3-cnpj-alfanumerico/consultas).

## Mudanças por produto

A regra geral é sempre a mesma, mas cada produto tem suas particularidades. Veja a sua abaixo.

## API de Empresas (cadastro)

**Endpoint base:** `https://api.nfe.io/v{version}/companies`

| Operação | Versão atual (legado) | Novo versionamento (alfa-aware) |
|---|---|---|
| `POST /companies` com CNPJ numérico | `201 Created`, response `number` | `201 Created`, response `string` |
| `POST /companies` com CNPJ alfa | n/a — não pode mandar `string` com letras (`400`) | `201 Created`, response `string` |
| `GET /companies/{id}` de empresa numérica | `200 OK`, `federalTaxNumber: number` | `200 OK`, `federalTaxNumber: string` |
| `GET /companies/{id}` de empresa alfa | **`400 Bad Request`** (requer o novo versionamento) | `200 OK`, `federalTaxNumber: string` |
| `GET /companies?federalTaxNumber=12ABC...` | `400` | `200 OK` |

> **Importante:** uma empresa alfa cadastrada pelo novo versionamento **continua existindo no banco** — ela só é **invisível** para as versões atuais. Se o cliente em uma versão atual tentar consultá-la, recebe `400` (mensagem orientando o novo versionamento). Isso não é bug: é exatamente o princípio "as versões atuais nunca veem alfa" em ação.

## API de NF-e / NFC-e

**Endpoint base:** `https://api.nfe.io/v{version}/companies/{companyId}/productinvoices`

| Cenário | Versão atual | Novo versionamento |
|---|---|---|
| Emissão com `issuer.federalTaxNumber` numérico | ✅ normal | ✅ normal, response `string` |
| Emissão com `issuer.federalTaxNumber` alfa | **rejeitada** na versão atual (a empresa alfa não resolve na V2) | ✅ chave de acesso gerada com DV ASCII−48, XML enviado à SEFAZ |
| Consulta de NF-e emitida no novo versionamento (CNPJ alfa) via endpoint de versão atual | **`404`** | `200 OK`, response `string` |

Alguns pontos que costumam gerar dúvida:

- **Chave de acesso (44 chars)** — quando o emissor tem letras no CNPJ, a chave passa a usar **Módulo 11 com ASCII−48**. Você não precisa se preocupar com isso: a NFE.io gera a chave correta automaticamente.
- **DANFE (PDF)** — foi atualizado para imprimir o barcode da chave alfa. Se você só consome o PDF, não precisa mudar nada.
- **GNRE (PE/ES)** — sem nenhuma mudança de contrato para o cliente.

## API de NFS-e

**Endpoint base:** `https://api.nfe.io/v{version}/companies/{companyId}/serviceinvoices`

| Cenário | Versão atual | Novo versionamento |
|---|---|---|
| Emissão de NFS-e com emissor numérico | ✅ normal | ✅ normal, response `string` |
| Emissão de NFS-e com emissor alfa | **`400 Bad Request`** (orienta o novo versionamento) | ✅ depende da prefeitura aceitar (gate natural) |
| Consulta de NFS-e emitida no novo versionamento (alfa) via versão atual | **`404`** | `200 OK`, response `string` |

> **Atenção, prefeituras:** a adoção do CNPJ alfa varia bastante de um município para outro. Algumas prefeituras já atualizaram seus webservices; outras ainda não. A NFE.io **não filtra** essa resposta — manda a nota para a prefeitura e devolve exatamente o que ela responder. Se a prefeitura ainda rejeita, você recebe o erro como ele vem, sem mascaramento.

## Distribuição de Documentos Fiscais (recebimento de DF-e)

**Endpoint base:** `https://api.nfe.io/v{version}/dfe/inbound`

| Cenário | Versão atual | Novo versionamento |
|---|---|---|
| Nota inbound recebida com CNPJ emissor numérico | ✅ entregue, `number` | ✅ entregue, `string` |
| Nota inbound recebida com CNPJ emissor alfa | documento **processado**; `federalTaxNumber` tratado como **texto** | entregue como `string` |
| Webhook de nota numérica | ✅ disparado, `number` | ✅ disparado, `string` |
| Webhook de nota alfa | **formato do payload** segue a versão da assinatura/webhook | entregue como `string` |

> Vale esclarecer: no fluxo de Distribuição o `federalTaxNumber` passou a ser tratado como **texto** — a nota com CNPJ alfanumérico é **processada normalmente**. O **formato e a visibilidade** do que cada assinante recebe seguem a **versão da assinatura/webhook** (não há um número de versão fixo para a Distribuição).

---

## 2026.4 - Novo IP de origem dos webhooks

Source: https://nfe.io/docs/release-notes/2026-4-novo-ip-origem-webhooks/index.md

# Release 2026.4 - Novo IP de origem dos webhooks

## Visão Geral

A partir de **15/06/2026**, nosso novo cluster de produção passa a enviar webhooks aos seus endpoints também pelo endereço IP **`34.44.243.117`**.

Se você **não** filtra o tráfego de entrada por IP, nenhuma ação é necessária. Se você mantém uma allowlist de firewall, é preciso incluir o novo endereço.

## O que mudou

- Um novo IP de origem foi adicionado ao envio de webhooks: **`34.44.243.117`**.
- Os IPs de origem já existentes **continuam válidos** e em uso simultaneamente.

:::warning Ação necessária
Se você restringe o tráfego de entrada por IP (allowlist/firewall), **adicione** o IP `34.44.243.117` à lista de endereços permitidos. **Não remova** os IPs existentes — todos permanecem ativos.
:::

## Próximos passos

1. Inclua `34.44.243.117` na allowlist do seu firewall antes de **15/06/2026**.
2. Mantenha os IPs atuais — eles não foram desativados.
3. Consulte a lista completa e atualizada em [IPs de origem dos webhooks](https://nfe.io/docs/documentacao/webhooks/ips-de-origem/).

## FAQ

**Preciso remover algum IP antigo?**
Não. Apenas adicione o novo. Todos os IPs listados permanecem ativos.

**O que acontece se eu não adicionar o IP até 15/06?**
Webhooks enviados a partir do novo cluster poderão ser bloqueados pelo seu firewall, resultando em perda de notificações.

**Como confirmo que um webhook veio mesmo da NFE.io?**
Valide a assinatura HMAC do webhook (cabeçalho `X-Hub-Signature`). O filtro por IP é uma camada adicional, não a verificação primária de autenticidade.

---

## 2026.5 - XML do Evento de Cancelamento da NFS-e Nacional

Source: https://nfe.io/docs/release-notes/2026-5-evento-cancelamento-nfse-nacional/index.md

# XML do Evento de Cancelamento da NFS-e Nacional

> **Para quem é este comunicado:** clientes que emitem e cancelam **NFS-e no Ambiente Nacional (ADN)** e precisam do comprovante fiscal do cancelamento, especialmente integrações via API.
>
> **O que muda no seu lado:** nada quebra. Há uma **nova capacidade** — baixar o XML do evento de cancelamento por um endpoint dedicado.

## Visão geral

A NFS-e do **Ambiente Nacional** passa a disponibilizar o **XML do evento de cancelamento (`e110001`)** — o documento fiscal que comprova oficialmente o cancelamento da nota. Esse XML agora é **persistido e exposto** por um endpoint próprio, separado do XML de emissão.

Antes, o cancelamento de uma NFS-e Nacional confirmava a operação, mas o cliente **não tinha como obter** o XML do evento. Esta versão fecha esse gap.

## Por que

No Ambiente Nacional, o cancelamento segue o modelo da NF-e modelo 55: é um **evento fiscal autônomo**, com XML próprio vinculado à nota original. Pela LC 214/2025, esse evento é o documento que dá validade jurídica ao cancelamento. Disponibilizá-lo dá ao cliente o comprovante fiscal completo da operação.

## Como funciona

Após o cancelamento ser concluído (status **Cancelada**), o XML do evento fica disponível por um endpoint dedicado:

```bash
curl -L "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices/{id}/cancellation-xml" \
  -H "X-NFe-Access-Token: sua_api_key" \
  -o "nota-cancelamento.xml"
```

O endpoint redireciona (HTTP 302) para uma URL assinada com o XML. Quando existem o **request enviado** e o **retorno autorizado** do Ambiente Nacional, o **retorno autorizado** (`procEventoNFSe`) tem prioridade.

:::info O XML de emissão continua intacto
O XML do evento de cancelamento é armazenado **separadamente** e **não sobrescreve** o XML de emissão. `GET /serviceinvoices/{id}/xml` continua devolvendo a nota original; o cancelamento vem por `/cancellation-xml`.
:::

## O que mudou

- **Novo endpoint:** `GET /v1/companies/{companyId}/serviceinvoices/{id}/cancellation-xml`.
- **Persistência dedicada:** o XML do evento é guardado em chave própria, sem colidir com o XML de emissão.
- **Prioridade do retorno autorizado:** quando disponível, o `procEventoNFSe` autorizado é priorizado sobre o request enviado.

:::warning Escopo: somente Ambiente Nacional
Provedores legados (ABRASF, Paulistana, etc.) **não** geram XML de evento de cancelamento — é uma característica do padrão antigo. Para esses provedores, o endpoint retorna **404**, sem regressão no comportamento existente.
:::

## Benefícios

- **Comprovante fiscal completo:** emissão e cancelamento, cada um com seu XML.
- **Sem perda do documento original:** os dois XMLs coexistem.
- **Integração simples:** um endpoint análogo ao download de XML que você já usa.

## Detalhamento técnico

| Item | Comportamento |
|---|---|
| Endpoint | `GET /v1/companies/{companyId}/serviceinvoices/{id}/cancellation-xml` |
| Resposta de sucesso | HTTP 302 → URL assinada com o XML (`application/xml`) |
| Prioridade | Retorno autorizado (`procEventoNFSe`) sobre o request enviado |
| 404 — provedor legado | Padrão antigo não tem evento próprio de cancelamento |
| 404 — nota não cancelada | XML só existe após `status = Cancelled` |
| Webhook relacionado | `invoice.cancelled_successfully` ao concluir o cancelamento |

A consulta da nota (`GET /serviceinvoices/{id}`) **não** inclui esse XML no corpo — ele é acessível apenas pelo endpoint dedicado.

## Próximos passos

1. 📩 Compartilhe este comunicado com os **devs** que mantêm sua integração de NFS-e.
2. 🧾 Se você emite no **Ambiente Nacional**, passe a arquivar o XML de cancelamento junto com o de emissão.
3. 🧪 Cancele uma NFS-e Nacional de teste e baixe o XML pelo novo endpoint — siga o [passo a passo](/docs/duvidas-frequentes/como-obter-xml-do-evento-de-cancelamento/).
4. 💬 Dúvidas: nosso canal de suporte e o time de Customer Success estão prontos para ajudar.

## FAQ

**O endpoint funciona para qualquer prefeitura?**
Não. Apenas para notas do **Ambiente Nacional**. Provedores legados (ABRASF, Paulistana, etc.) retornam 404.

**O XML de emissão foi afetado?**
Não. O XML de cancelamento é armazenado separadamente; `GET /xml` continua igual.

**Quando o XML fica disponível?**
Somente após o cancelamento concluir e a nota assumir o status **Cancelada**. Antes disso, o endpoint retorna 404.

**Preciso guardar esse XML?**
Sim. É documento fiscal; mantenha pelo prazo legal mínimo de 5 anos, junto com o XML de emissão.

---

> **Em resumo:**
>
> 1. **Nova capacidade:** baixe o XML do evento de cancelamento (`e110001`) da NFS-e Nacional por `GET /serviceinvoices/{id}/cancellation-xml`.
> 2. **Sem quebra:** o XML de emissão não é sobrescrito; provedores legados seguem como antes (404 no novo endpoint).
> 3. **Disponível após `Cancelled`** — e priorizando o retorno autorizado do Ambiente Nacional.

---

## 2026.6 - Migração de infraestrutura para Cloudflare

Source: https://nfe.io/docs/release-notes/2026-6-migracao-cloudflare/index.md

# Release 2026.6 - Migração de infraestrutura para Cloudflare

**Tipo:** Mudança de infraestrutura · **Ação requerida:** apenas para integrações com allowlist de IP de saída ou certificate pinning

A camada de borda de **todos os serviços da NFe.io** foi migrada de **Azure** para **Cloudflare**.
O contrato da API permanece idêntico: **status HTTP, `Content-Type`, corpo e versão HTTP não mudaram**.

## O que mudou

| Item | Antes (origin direto) | Agora (via Cloudflare) |
|---|---|---|
| IP resolvido | IPv4 dedicado do origin | Ranges Cloudflare (IPv4 + **IPv6**) |
| Terminação TLS | Servidor de origem | Cloudflare |
| Certificado | Leaf por host (Let's Encrypt) | `*.nfe.one` (Google Trust Services) |
| Headers adicionados | — | `cf-ray`, `cf-cache-status`, `server: cloudflare`, `NEL`, `Report-To` |
| `Strict-Transport-Security` | Presente | **Em descontinuação** (ver Ação requerida) |
| Status / Content-Type / Corpo / HTTP version | — | **Sem alteração** |

## Ação requerida

- **Allowlist de IP (apenas saída):** atualize as regras de **saída** dos seus sistemas para os [ranges oficiais da Cloudflare](https://www.cloudflare.com/ips/) (IPv4 e IPv6). Prefira liberar por **hostname** em vez de IP fixo. *Allowlist de entrada não é afetada — a NFe.io não origina requisições a partir de IPs da Cloudflare.*
- **Certificate pinning:** o host continua apresentando SSL válido e a validação TLS padrão funciona normalmente — **sem ação para a maioria**. Só impacta quem faz *pinning* explícito de leaf/CA: nesse caso, remova o pinning anterior ou atualize para a cadeia `*.nfe.one` (Google Trust Services).
- **HSTS / parsing de headers:** o header `Strict-Transport-Security` está sendo descontinuado na borda. **Use sempre `https://` explicitamente** nas integrações — não dependa do HSTS para forçar o upgrade de `http` para `https`. Ajuste também se houver parsing rígido de headers.

## Sem ação necessária

Integrações que usam validação TLS padrão e não restringem por IP de saída **continuam funcionando sem alterações**. Quem recebe tráfego da NFe.io (ex.: webhooks) também não precisa ajustar allowlist de entrada.

---

## Introdução às Release Notes

Source: https://nfe.io/docs/release-notes/index.md

# Introdução às Release Notes

Bem-vindo à seção de Release Notes da NFE.io! Aqui você encontrará todas as atualizações, melhorias e novidades que implementamos em nossa plataforma para oferecer a melhor experiência possível aos nossos usuários.

## O que são Release Notes?

As Release Notes são documentos que detalham as mudanças feitas em uma versão específica de um software. Elas incluem informações sobre novas funcionalidades, correções de bugs, melhorias de desempenho e quaisquer outras alterações relevantes que possam impactar os usuários.

## Por que são importantes?

As Release Notes são essenciais para manter nossos usuários informados sobre as atualizações da plataforma. Elas ajudam a entender como as mudanças podem afetar o uso do sistema, permitem que os usuários aproveitem novas funcionalidades e garantem transparência em relação ao desenvolvimento contínuo da NFE.io.