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

# Incluir Nota Fiscal

> Serviço destinado a incluir novas notas fiscais eletrônicas no sistema.

## Endpoint

```
POST https://api.tiny.com.br/api2/nota.fiscal.incluir.php
```

## Parâmetros

| Parâmetro | Tipo     | Ocorrência  | Descrição                                   |
| --------- | -------- | ----------- | ------------------------------------------- |
| token     | string   | obrigatório | Chave gerada para identificar sua empresa   |
| formato   | string   | obrigatório | Formato do retorno (json)                   |
| nota      | xml/json | obrigatório | Dados da nota fiscal em formato XML ou JSON |

## Estrutura de Campos

### Dados Gerais da Nota Fiscal

| Campo                  | Tipo   | Tamanho | Ocorrência  | Descrição                                        |
| ---------------------- | ------ | ------- | ----------- | ------------------------------------------------ |
| nota\_fiscal           | object | -       | obrigatório | Elemento raiz da nota fiscal                     |
| tipo                   | string | 1       | opcional    | Tipo da nota: E (Entrada), S (Saída); padrão "S" |
| id\_natureza\_operacao | int    | -       | opcional    | ID da natureza de operação (pré-cadastrada)      |
| natureza\_operacao     | string | 50      | opcional    | Descrição da natureza de operação                |
| data\_emissao          | string | 10      | opcional    | Data de emissão (formato dd/mm/aaaa)             |
| hora\_emissao          | string | 8       | opcional    | Hora de emissão (formato hh:mm:ss)               |
| data\_entrada\_saida   | string | 10      | opcional    | Data de entrada/saída                            |
| hora\_entrada\_saida   | string | 8       | opcional    | Hora de entrada/saída                            |
| finalidade             | int    | -       | opcional    | Código da finalidade da nota fiscal              |
| refNFe                 | string | 44      | opcional    | Chave de acesso da NF-e referenciada             |
| obs                    | string | 100     | opcional    | Observação da nota fiscal                        |
| ecommerce              | string | 50      | opcional    | Plataforma que enviou a nota                     |

### Cliente

| Campo                      | Tipo   | Tamanho | Ocorrência      | Descrição                                                 |
| -------------------------- | ------ | ------- | --------------- | --------------------------------------------------------- |
| cliente                    | object | -       | obrigatório     | Elemento do cliente                                       |
| cliente.codigo             | string | 30      | opcional        | Código do cliente                                         |
| cliente.nome               | string | 50      | **obrigatório** | Nome do cliente                                           |
| cliente.tipo\_pessoa       | string | 1       | opcional        | Tipo de pessoa: F (Física), J (Jurídica), E (Estrangeiro) |
| cliente.cpf\_cnpj          | string | 18      | opcional        | CPF ou CNPJ                                               |
| cliente.ie                 | string | 18      | opcional        | Inscrição estadual                                        |
| cliente.rg                 | string | 10      | opcional        | Documento de identidade                                   |
| cliente.endereco           | string | 50      | opcional        | Endereço                                                  |
| cliente.numero             | string | 10      | opcional        | Número do endereço                                        |
| cliente.complemento        | string | 50      | opcional        | Complemento do endereço                                   |
| cliente.bairro             | string | 30      | opcional        | Bairro                                                    |
| cliente.cep                | string | 10      | opcional        | CEP                                                       |
| cliente.cidade             | string | 30      | opcional        | Cidade (conforme tabela de municípios)                    |
| cliente.uf                 | string | 2       | opcional        | Estado                                                    |
| cliente.pais               | string | 50      | opcional        | País (conforme tabela de países)                          |
| cliente.fone               | string | 40      | opcional        | Telefone                                                  |
| cliente.email              | string | 50      | opcional        | Email                                                     |
| cliente.atualizar\_cliente | string | 1       | opcional        | Atualizar cadastro do cliente: S/N; padrão "S"            |

### Endereço de Entrega (Opcional, se diferente do cliente)

| Campo                                | Tipo   | Tamanho | Ocorrência | Descrição                       |
| ------------------------------------ | ------ | ------- | ---------- | ------------------------------- |
| endereco\_entrega                    | object | -       | opcional   | Elemento do endereço de entrega |
| endereco\_entrega.tipo\_pessoa       | string | 1       | opcional   | Tipo de pessoa                  |
| endereco\_entrega.cpf\_cnpj          | string | 18      | opcional   | CPF/CNPJ da entrega             |
| endereco\_entrega.endereco           | string | 50      | opcional   | Endereço de entrega             |
| endereco\_entrega.numero             | string | 10      | opcional   | Número da entrega               |
| endereco\_entrega.complemento        | string | 50      | opcional   | Complemento da entrega          |
| endereco\_entrega.bairro             | string | 30      | opcional   | Bairro da entrega               |
| endereco\_entrega.cep                | string | 10      | opcional   | CEP da entrega                  |
| endereco\_entrega.cidade             | string | 30      | opcional   | Cidade da entrega               |
| endereco\_entrega.uf                 | string | 30      | opcional   | Estado da entrega               |
| endereco\_entrega.fone               | string | 40      | opcional   | Telefone da entrega             |
| endereco\_entrega.nome\_destinatario | string | 60      | opcional   | Nome do destinatário            |
| endereco\_entrega.ie                 | string | 18      | opcional   | Inscrição estadual da entrega   |

### Itens da Nota Fiscal

| Campo                             | Tipo    | Tamanho | Ocorrência      | Descrição                                       |
| --------------------------------- | ------- | ------- | --------------- | ----------------------------------------------- |
| itens\[]                          | list    | -       | **obrigatório** | Lista de itens                                  |
| itens\[].item                     | object  | -       | **obrigatório** | Elemento do item                                |
| item.id\_produto                  | int     | -       | opcional        | ID do produto no sistema                        |
| item.codigo                       | string  | 60      | opcional        | Código do produto                               |
| item.descricao                    | string  | 120     | **obrigatório** | Descrição do produto                            |
| item.unidade                      | string  | 2       | **obrigatório** | Unidade (UN, KG, etc.)                          |
| item.quantidade                   | decimal | -       | **obrigatório** | Quantidade (separador ponto)                    |
| item.valor\_unitario              | decimal | -       | **obrigatório** | Valor unitário (separador ponto)                |
| item.tipo                         | string  | 1       | **obrigatório** | Tipo: P (Produto), S (Serviço)                  |
| item.origem                       | string  | 1       | opcional        | Código de origem (conforme tabela)              |
| item.numero\_fci                  | string  | 36      | opcional        | Número da FCI (Ficha de Conteúdo de Importação) |
| item.ncm                          | string  | 10      | opcional        | Código NCM                                      |
| item.peso\_bruto                  | decimal | -       | opcional        | Peso bruto                                      |
| item.peso\_liquido                | decimal | -       | opcional        | Peso líquido                                    |
| item.gtin\_ean                    | string  | 14      | opcional        | GTIN/EAN                                        |
| item.gtin\_ean\_embalagem         | string  | 14      | opcional        | GTIN/EAN da embalagem                           |
| item.codigo\_lista\_servicos      | string  | 5       | opcional        | Código da lista de serviços (apenas serviços)   |
| item.aliquota\_comissao           | decimal | -       | opcional        | Alíquota de comissão                            |
| item.cest                         | string  | 10      | opcional        | Código CEST                                     |
| item.numero\_pedido\_compra       | string  | 15      | opcional        | Número do pedido de compra                      |
| item.numero\_item\_pedido\_compra | int     | -       | opcional        | Número do item no pedido de compra              |
| item.descricao\_complementar      | string  | 100     | opcional        | Informações adicionais                          |
| item.codigo\_anvisa               | string  | 13      | condicional     | Código ANVISA (obrigatório para medicamentos)   |
| item.valor\_max                   | decimal | -       | opcional        | Preço máximo ao consumidor                      |
| item.motivo\_isencao              | string  | 255     | opcional        | Motivo de isenção ANVISA                        |

### Marcadores

| Campo                  | Tipo   | Tamanho | Ocorrência | Descrição             |
| ---------------------- | ------ | ------- | ---------- | --------------------- |
| marcadores\[]          | list   | -       | opcional   | Lista de marcadores   |
| marcadores\[].marcador | object | -       | opcional   | Elemento do marcador  |
| marcador.descricao     | string | 50      | opcional   | Descrição do marcador |

### Informações de Pagamento

| Campo            | Tipo   | Tamanho | Ocorrência | Descrição                                      |
| ---------------- | ------ | ------- | ---------- | ---------------------------------------------- |
| forma\_pagamento | string | 30      | opcional   | Código da forma de pagamento (conforme tabela) |
| meio\_pagamento  | string | 100     | opcional   | Descrição do meio de pagamento                 |

### Parcelas

| Campo                        | Tipo    | Tamanho | Ocorrência  | Descrição                                                   |
| ---------------------------- | ------- | ------- | ----------- | ----------------------------------------------------------- |
| parcelas\[]                  | list    | -       | opcional    | Lista de parcelas                                           |
| parcelas\[].parcela          | object  | -       | opcional    | Elemento da parcela                                         |
| parcela.dias                 | int     | 20      | opcional    | Dias para vencimento                                        |
| parcela.data                 | string  | 10      | opcional    | Data de vencimento (dd/mm/aaaa)                             |
| parcela.valor                | decimal | -       | opcional    | Valor da parcela                                            |
| parcela.obs                  | string  | 100     | opcional    | Observação da parcela                                       |
| parcela.destino              | string  | 50      | opcional    | Destino (ex: Caixa, Contas a Receber)                       |
| parcela.forma\_pagamento     | string  | 30      | opcional    | Código da forma de pagamento                                |
| parcela.meio\_pagamento      | string  | 100     | opcional    | Meio de pagamento                                           |
| parcela.meio\_pagamento\_nfe | int     | -       | condicional | Código de pagamento NFe (obrigatório para notas de entrada) |

### Transportadora

| Campo                      | Tipo   | Tamanho | Ocorrência | Descrição                  |
| -------------------------- | ------ | ------- | ---------- | -------------------------- |
| transportador              | object | -       | opcional   | Elemento da transportadora |
| transportador.codigo       | string | 30      | opcional   | Código da transportadora   |
| transportador.nome         | string | 30      | opcional   | Nome da transportadora     |
| transportador.tipo\_pessoa | string | 1       | opcional   | Tipo de pessoa             |
| transportador.cpf\_cnpj    | string | 18      | opcional   | CPF/CNPJ da transportadora |
| transportador.ie           | string | 18      | opcional   | Inscrição estadual         |
| transportador.endereco     | string | 50      | opcional   | Endereço da transportadora |
| transportador.cidade       | string | 30      | opcional   | Cidade da transportadora   |
| transportador.uf           | string | 2       | opcional   | Estado da transportadora   |

### Envio e Frete

| Campo               | Tipo   | Tamanho | Ocorrência      | Descrição                                           |
| ------------------- | ------ | ------- | --------------- | --------------------------------------------------- |
| forma\_envio        | string | 30      | opcional        | Forma de envio (conforme tabela)                    |
| forma\_frete        | string | 30      | opcional        | Forma de frete (conforme opções cadastradas)        |
| frete\_por\_conta   | string | 1       | **obrigatório** | Frete por conta de: R (Remetente), D (Destinatário) |
| placa\_veiculo      | string | 1       | opcional        | Placa do veículo                                    |
| uf\_veiculo         | string | 1       | opcional        | Estado da placa                                     |
| quantidade\_volumes | int    | -       | opcional        | Quantidade de volumes                               |
| especie\_volumes    | string | 20      | opcional        | Espécie dos volumes (ex: Caixas)                    |
| marca\_volumes      | string | 20      | opcional        | Marca dos volumes                                   |
| numero\_volumes     | string | 20      | opcional        | Numeração dos volumes                               |

### Valores Fiscais

| Campo           | Tipo    | Tamanho | Ocorrência | Descrição                |
| --------------- | ------- | ------- | ---------- | ------------------------ |
| valor\_desconto | decimal | -       | opcional   | Valor de desconto        |
| valor\_frete    | decimal | -       | opcional   | Valor do frete           |
| valor\_seguro   | decimal | -       | opcional   | Valor do seguro          |
| valor\_despesas | decimal | -       | opcional   | Valor de outras despesas |

### Referência de Produtor Rural (Opcional)

| Campo                                 | Tipo   | Tamanho | Ocorrência | Descrição                                   |
| ------------------------------------- | ------ | ------- | ---------- | ------------------------------------------- |
| nf\_produtor\_rural                   | object | -       | opcional   | Referência de nota fiscal de produtor rural |
| nf\_produtor\_rural.serie             | string | 3       | opcional   | Série                                       |
| nf\_produtor\_rural.numero            | string | 10      | opcional   | Número                                      |
| nf\_produtor\_rural.ano\_mes\_emissao | string | 4       | opcional   | Formato AAMM                                |

### Informações do Vendedor

| Campo                     | Tipo   | Tamanho | Ocorrência | Descrição                       |
| ------------------------- | ------ | ------- | ---------- | ------------------------------- |
| id\_vendedor              | int    | -       | opcional   | ID do vendedor (pré-cadastrado) |
| nome\_vendedor            | string | 50      | opcional   | Nome do vendedor                |
| numero\_pedido\_ecommerce | string | 50      | opcional   | Número do pedido do e-commerce  |

### Intermediador (Opcional)

| Campo                       | Tipo   | Tamanho | Ocorrência  | Descrição                                                     |
| --------------------------- | ------ | ------- | ----------- | ------------------------------------------------------------- |
| intermediador               | object | -       | opcional    | Elemento do intermediador                                     |
| intermediador.nome          | string | 60      | condicional | Nome do intermediador (obrigatório se intermediador presente) |
| intermediador.cnpj          | string | 18      | condicional | CNPJ do intermediador (obrigatório se intermediador presente) |
| intermediador.cnpjPagamento | string | 18      | opcional    | CNPJ da instituição de pagamento                              |

### Pagamentos Integrados (Opcional)

| Campo                                          | Tipo    | Tamanho | Ocorrência      | Descrição                                         |
| ---------------------------------------------- | ------- | ------- | --------------- | ------------------------------------------------- |
| pagamentos\_integrados\[]                      | list    | -       | opcional        | Lista de pagamentos integrados                    |
| pagamentos\_integrados\[].pagamento\_integrado | object  | -       | condicional     | Elemento do pagamento                             |
| pagamento\_integrado.tipo\_pagamento           | int     | -       | **obrigatório** | Código do tipo de pagamento (conforme tabela NFe) |
| pagamento\_integrado.valor                     | decimal | -       | **obrigatório** | Valor do pagamento                                |
| pagamento\_integrado.cnpj\_intermediador       | string  | 14      | **obrigatório** | CNPJ do intermediador                             |
| pagamento\_integrado.codigo\_autorizacao       | string  | -       | **obrigatório** | Código de autorização da transação                |
| pagamento\_integrado.codigo\_bandeira          | int     | -       | **obrigatório** | Código da bandeira da operadora                   |

## Retorno

| Campo                                       | Tipo   | Ocorrência  | Descrição                                 |
| ------------------------------------------- | ------ | ----------- | ----------------------------------------- |
| retorno                                     | object | obrigatório | Elemento raiz do retorno                  |
| retorno.status\_processamento               | int    | obrigatório | Conforme tabela "Status de Processamento" |
| retorno.status                              | string | obrigatório | "OK" ou "Erro"                            |
| retorno.codigo\_erro                        | int    | condicional | Código do erro (quando status = "Erro")   |
| retorno.erros\[]                            | list   | condicional | Lista de erros \[0..n]                    |
| retorno.erros\[].erro                       | string | condicional | Descrição do erro                         |
| retorno.registros\[]                        | list   | condicional | Lista de resultados \[0..n]               |
| retorno.registros\[].registro.sequencia     | int    | condicional | Identificador sequencial de cada nota     |
| retorno.registros\[].registro.status        | string | condicional | Status do registro: "OK" ou "Erro"        |
| retorno.registros\[].registro.codigo\_erro  | int    | condicional | Código do erro (conforme tabela)          |
| retorno.registros\[].registro.erros\[]      | list   | condicional | Lista de erros do registro \[0..n]        |
| retorno.registros\[].registro.erros\[].erro | string | condicional | Descrição do erro do registro             |
| retorno.registros\[].registro.id            | int    | condicional | ID da nota fiscal no Olist ERP            |
| retorno.registros\[].registro.serie         | string | condicional | Série da nota fiscal (3 caracteres)       |
| retorno.registros\[].registro.numero        | int    | condicional | Número da nota fiscal                     |

## Exemplo de Parâmetro XML Simplificado

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<nota_fiscal>
  <tipo>S</tipo>
  <natureza_operacao>Venda</natureza_operacao>
  <data_emissao>20/05/2024</data_emissao>
  <cliente>
    <nome>João da Silva</nome>
    <tipo_pessoa>F</tipo_pessoa>
    <cpf_cnpj>123.456.789-00</cpf_cnpj>
    <endereco>Rua Exemplo</endereco>
    <numero>100</numero>
    <bairro>Centro</bairro>
    <cep>01234-567</cep>
    <cidade>São Paulo</cidade>
    <uf>SP</uf>
  </cliente>
  <itens>
    <item>
      <codigo>PROD001</codigo>
      <descricao>Produto Teste</descricao>
      <unidade>UN</unidade>
      <quantidade>1</quantidade>
      <valor_unitario>100.00</valor_unitario>
      <tipo>P</tipo>
    </item>
  </itens>
  <frete_por_conta>R</frete_por_conta>
</nota_fiscal>
```

## Exemplo de Parâmetro JSON Simplificado

```json theme={null}
{
  "nota_fiscal": {
    "tipo": "S",
    "natureza_operacao": "Venda",
    "data_emissao": "20/05/2024",
    "cliente": {
      "nome": "João da Silva",
      "tipo_pessoa": "F",
      "cpf_cnpj": "123.456.789-00",
      "endereco": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "cep": "01234-567",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "itens": [
      {
        "item": {
          "codigo": "PROD001",
          "descricao": "Produto Teste",
          "unidade": "UN",
          "quantidade": "1",
          "valor_unitario": "100.00",
          "tipo": "P"
        }
      }
    ],
    "frete_por_conta": "R"
  }
}
```

## Exemplo de Parâmetro XML Completo

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<nota_fiscal>
  <tipo>S</tipo>
  <id_natureza_operacao>12345</id_natureza_operacao>
  <natureza_operacao>Venda de mercadoria adquirida ou recebida de terceiros</natureza_operacao>
  <data_emissao>20/05/2024</data_emissao>
  <hora_emissao>14:30:00</hora_emissao>
  <data_entrada_saida>20/05/2024</data_entrada_saida>
  <hora_entrada_saida>15:00:00</hora_entrada_saida>
  <finalidade>1</finalidade>
  <obs>Pedido realizado através do site</obs>
  <ecommerce>Loja Virtual</ecommerce>
  <numero_pedido_ecommerce>PED123456</numero_pedido_ecommerce>

  <cliente>
    <codigo>CLI001</codigo>
    <nome>João da Silva</nome>
    <tipo_pessoa>F</tipo_pessoa>
    <cpf_cnpj>123.456.789-00</cpf_cnpj>
    <rg>12.345.678-9</rg>
    <endereco>Rua Exemplo</endereco>
    <numero>100</numero>
    <complemento>Apto 101</complemento>
    <bairro>Centro</bairro>
    <cep>01234-567</cep>
    <cidade>São Paulo</cidade>
    <uf>SP</uf>
    <pais>Brasil</pais>
    <fone>(11) 98765-4321</fone>
    <email>joao@email.com</email>
    <atualizar_cliente>S</atualizar_cliente>
  </cliente>

  <endereco_entrega>
    <tipo_pessoa>F</tipo_pessoa>
    <cpf_cnpj>123.456.789-00</cpf_cnpj>
    <nome_destinatario>João da Silva</nome_destinatario>
    <endereco>Av. Principal</endereco>
    <numero>200</numero>
    <complemento>Casa</complemento>
    <bairro>Jardins</bairro>
    <cep>12345-678</cep>
    <cidade>São Paulo</cidade>
    <uf>SP</uf>
    <fone>(11) 98765-4321</fone>
  </endereco_entrega>

  <itens>
    <item>
      <id_produto>12345</id_produto>
      <codigo>PROD001</codigo>
      <descricao>Notebook Dell Inspiron 15</descricao>
      <unidade>UN</unidade>
      <quantidade>2</quantidade>
      <valor_unitario>2500.00</valor_unitario>
      <tipo>P</tipo>
      <origem>0</origem>
      <ncm>84713012</ncm>
      <peso_bruto>2.5</peso_bruto>
      <peso_liquido>2.3</peso_liquido>
      <gtin_ean>7891234567890</gtin_ean>
      <cest>0123456</cest>
      <descricao_complementar>Notebook com 8GB RAM, SSD 256GB</descricao_complementar>
    </item>
    <item>
      <codigo>PROD002</codigo>
      <descricao>Mouse sem fio</descricao>
      <unidade>UN</unidade>
      <quantidade>2</quantidade>
      <valor_unitario>50.00</valor_unitario>
      <tipo>P</tipo>
      <origem>0</origem>
      <ncm>84716060</ncm>
      <peso_bruto>0.2</peso_bruto>
      <peso_liquido>0.15</peso_liquido>
    </item>
  </itens>

  <marcadores>
    <marcador>
      <descricao>E-commerce</descricao>
    </marcador>
    <marcador>
      <descricao>Promoção</descricao>
    </marcador>
  </marcadores>

  <forma_pagamento>credito</forma_pagamento>
  <meio_pagamento>Cartão de Crédito Visa</meio_pagamento>

  <parcelas>
    <parcela>
      <dias>0</dias>
      <data>20/05/2024</data>
      <valor>1700.00</valor>
      <obs>Entrada</obs>
      <destino>Contas a Receber</destino>
      <forma_pagamento>dinheiro</forma_pagamento>
      <meio_pagamento>Dinheiro</meio_pagamento>
    </parcela>
    <parcela>
      <dias>30</dias>
      <data>20/06/2024</data>
      <valor>1700.00</valor>
      <obs>Primeira parcela</obs>
      <destino>Contas a Receber</destino>
      <forma_pagamento>credito</forma_pagamento>
      <meio_pagamento>Cartão de Crédito</meio_pagamento>
    </parcela>
    <parcela>
      <dias>60</dias>
      <data>20/07/2024</data>
      <valor>1700.00</valor>
      <obs>Segunda parcela</obs>
      <destino>Contas a Receber</destino>
      <forma_pagamento>credito</forma_pagamento>
      <meio_pagamento>Cartão de Crédito</meio_pagamento>
    </parcela>
  </parcelas>

  <transportador>
    <codigo>TRANS001</codigo>
    <nome>Transportadora Rápida Ltda</nome>
    <tipo_pessoa>J</tipo_pessoa>
    <cpf_cnpj>12.345.678/0001-90</cpf_cnpj>
    <ie>123456789</ie>
    <endereco>Av. Transportes</endereco>
    <cidade>São Paulo</cidade>
    <uf>SP</uf>
  </transportador>

  <forma_envio>X</forma_envio>
  <forma_frete>FOB</forma_frete>
  <frete_por_conta>R</frete_por_conta>
  <placa_veiculo>ABC1234</placa_veiculo>
  <uf_veiculo>SP</uf_veiculo>
  <quantidade_volumes>3</quantidade_volumes>
  <especie_volumes>Caixas</especie_volumes>
  <marca_volumes>Dell</marca_volumes>
  <numero_volumes>1, 2, 3</numero_volumes>

  <valor_desconto>200.00</valor_desconto>
  <valor_frete>50.00</valor_frete>
  <valor_seguro>20.00</valor_seguro>
  <valor_despesas>30.00</valor_despesas>

  <id_vendedor>789</id_vendedor>
  <nome_vendedor>Maria Vendedora</nome_vendedor>
</nota_fiscal>
```

## Exemplo de Parâmetro JSON Completo

```json theme={null}
{
  "nota_fiscal": {
    "tipo": "S",
    "id_natureza_operacao": "12345",
    "natureza_operacao": "Venda de mercadoria adquirida ou recebida de terceiros",
    "data_emissao": "20/05/2024",
    "hora_emissao": "14:30:00",
    "data_entrada_saida": "20/05/2024",
    "hora_entrada_saida": "15:00:00",
    "finalidade": "1",
    "obs": "Pedido realizado através do site",
    "ecommerce": "Loja Virtual",
    "numero_pedido_ecommerce": "PED123456",
    "cliente": {
      "codigo": "CLI001",
      "nome": "João da Silva",
      "tipo_pessoa": "F",
      "cpf_cnpj": "123.456.789-00",
      "rg": "12.345.678-9",
      "endereco": "Rua Exemplo",
      "numero": "100",
      "complemento": "Apto 101",
      "bairro": "Centro",
      "cep": "01234-567",
      "cidade": "São Paulo",
      "uf": "SP",
      "pais": "Brasil",
      "fone": "(11) 98765-4321",
      "email": "joao@email.com",
      "atualizar_cliente": "S"
    },
    "endereco_entrega": {
      "tipo_pessoa": "F",
      "cpf_cnpj": "123.456.789-00",
      "nome_destinatario": "João da Silva",
      "endereco": "Av. Principal",
      "numero": "200",
      "complemento": "Casa",
      "bairro": "Jardins",
      "cep": "12345-678",
      "cidade": "São Paulo",
      "uf": "SP",
      "fone": "(11) 98765-4321"
    },
    "itens": [
      {
        "item": {
          "id_produto": "12345",
          "codigo": "PROD001",
          "descricao": "Notebook Dell Inspiron 15",
          "unidade": "UN",
          "quantidade": "2",
          "valor_unitario": "2500.00",
          "tipo": "P",
          "origem": "0",
          "ncm": "84713012",
          "peso_bruto": "2.5",
          "peso_liquido": "2.3",
          "gtin_ean": "7891234567890",
          "cest": "0123456",
          "descricao_complementar": "Notebook com 8GB RAM, SSD 256GB"
        }
      },
      {
        "item": {
          "codigo": "PROD002",
          "descricao": "Mouse sem fio",
          "unidade": "UN",
          "quantidade": "2",
          "valor_unitario": "50.00",
          "tipo": "P",
          "origem": "0",
          "ncm": "84716060",
          "peso_bruto": "0.2",
          "peso_liquido": "0.15"
        }
      }
    ],
    "marcadores": [
      {
        "marcador": {
          "descricao": "E-commerce"
        }
      },
      {
        "marcador": {
          "descricao": "Promoção"
        }
      }
    ],
    "forma_pagamento": "credito",
    "meio_pagamento": "Cartão de Crédito Visa",
    "parcelas": [
      {
        "parcela": {
          "dias": "0",
          "data": "20/05/2024",
          "valor": "1700.00",
          "obs": "Entrada",
          "destino": "Contas a Receber",
          "forma_pagamento": "dinheiro",
          "meio_pagamento": "Dinheiro"
        }
      },
      {
        "parcela": {
          "dias": "30",
          "data": "20/06/2024",
          "valor": "1700.00",
          "obs": "Primeira parcela",
          "destino": "Contas a Receber",
          "forma_pagamento": "credito",
          "meio_pagamento": "Cartão de Crédito"
        }
      },
      {
        "parcela": {
          "dias": "60",
          "data": "20/07/2024",
          "valor": "1700.00",
          "obs": "Segunda parcela",
          "destino": "Contas a Receber",
          "forma_pagamento": "credito",
          "meio_pagamento": "Cartão de Crédito"
        }
      }
    ],
    "transportador": {
      "codigo": "TRANS001",
      "nome": "Transportadora Rápida Ltda",
      "tipo_pessoa": "J",
      "cpf_cnpj": "12.345.678/0001-90",
      "ie": "123456789",
      "endereco": "Av. Transportes",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "forma_envio": "X",
    "forma_frete": "FOB",
    "frete_por_conta": "R",
    "placa_veiculo": "ABC1234",
    "uf_veiculo": "SP",
    "quantidade_volumes": "3",
    "especie_volumes": "Caixas",
    "marca_volumes": "Dell",
    "numero_volumes": "1, 2, 3",
    "valor_desconto": "200.00",
    "valor_frete": "50.00",
    "valor_seguro": "20.00",
    "valor_despesas": "30.00",
    "id_vendedor": "789",
    "nome_vendedor": "Maria Vendedora"
  }
}
```

## Exemplo de Chamada com XML

```bash theme={null}
curl -X POST https://api.tiny.com.br/api2/nota.fiscal.incluir.php \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=SEU_TOKEN" \
  -d "formato=json" \
  --data-urlencode "nota=<?xml version=\"1.0\" encoding=\"UTF-8\"?><nota_fiscal><tipo>S</tipo><natureza_operacao>Venda</natureza_operacao><data_emissao>20/05/2024</data_emissao><cliente><nome>João da Silva</nome><tipo_pessoa>F</tipo_pessoa><cpf_cnpj>123.456.789-00</cpf_cnpj><endereco>Rua Exemplo</endereco><numero>100</numero><bairro>Centro</bairro><cep>01234-567</cep><cidade>São Paulo</cidade><uf>SP</uf></cliente><itens><item><codigo>PROD001</codigo><descricao>Produto Teste</descricao><unidade>UN</unidade><quantidade>1</quantidade><valor_unitario>100.00</valor_unitario><tipo>P</tipo></item></itens><frete_por_conta>R</frete_por_conta></nota_fiscal>"
```

## Exemplo de Chamada REST com JSON

```bash theme={null}
# Exemplo com JSON
curl -X POST https://api.tiny.com.br/api2/nota.fiscal.incluir.php \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=SEU_TOKEN" \
  -d "formato=json" \
  --data-urlencode "nota=$(cat <<'EOF'
{
  "nota_fiscal": {
    "tipo": "S",
    "natureza_operacao": "Venda",
    "data_emissao": "20/05/2024",
    "cliente": {
      "nome": "João da Silva",
      "tipo_pessoa": "F",
      "cpf_cnpj": "123.456.789-00",
      "endereco": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "cep": "01234-567",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "itens": [
      {
        "item": {
          "codigo": "PROD001",
          "descricao": "Produto Teste",
          "unidade": "UN",
          "quantidade": "1",
          "valor_unitario": "100.00",
          "tipo": "P"
        }
      }
    ],
    "frete_por_conta": "R"
  }
}
EOF
)"
```

## Exemplos de Retorno

### Sucesso

```json theme={null}
{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "OK",
          "id": "37644545",
          "serie": "1",
          "numero": "00001"
        }
      }
    ]
  }
}
```

### Erro - Validação (campo obrigatório faltando)

```json theme={null}
{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "codigo_erro": 31,
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "Erro",
          "codigo_erro": "31",
          "erros": [
            {"erro": "O campo cliente.nome é obrigatório"},
            {"erro": "O campo itens é obrigatório"}
          ]
        }
      }
    ]
  }
}
```

### Erro - Autenticação

```json theme={null}
{
  "retorno": {
    "status_processamento": 1,
    "status": "Erro",
    "codigo_erro": 2,
    "erros": [
      {"erro": "token invalido"}
    ]
  }
}
```

### Erro - Produto não encontrado

```json theme={null}
{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "codigo_erro": 30,
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "Erro",
          "codigo_erro": "30",
          "erros": [
            {"erro": "Produto com código PROD999 não encontrado"}
          ]
        }
      }
    ]
  }
}
```

### Erro - Registro duplicado

```json theme={null}
{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "codigo_erro": 30,
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "Erro",
          "codigo_erro": "30",
          "erros": [
            {"erro": "Duplicate record"}
          ]
        }
      }
    ]
  }
}
```

## Notas Importantes

* **Separador decimal:** Use ponto (.) para valores decimais, por exemplo "5.25"
* **Formato de data:** dd/mm/aaaa, por exemplo "20/10/2024"
* **Formato de hora:** hh:mm:ss, por exemplo "15:30:00"
* **Comportamento de busca:** Campos de código buscam registros existentes; registros encontrados carregam dados adicionais do banco
* **Valores padrão:** Natureza de operação é atribuída automaticamente se omitida; pagamento padrão para "contas a receber"
* **Validação de vendedor:** Vendedores não existentes geram erro
* **Tratamento de intermediador:** Nome + CNPJ são buscados juntos; novos intermediadores são criados automaticamente se não encontrados