Incluir Nota Fiscal - Olist ERP API v3

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 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

{
  "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 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

{
  "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

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

# 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

{
  "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)

{
  "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

{
  "retorno": {
    "status_processamento": 1,
    "status": "Erro",
    "codigo_erro": 2,
    "erros": [
      {"erro": "token invalido"}
    ]
  }
}

Erro - Produto não encontrado

{
  "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

{
  "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

​Endpoint

​Parâmetros

​Estrutura de Campos

​Dados Gerais da Nota Fiscal

​Cliente

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

​Itens da Nota Fiscal

​Marcadores

​Informações de Pagamento

​Parcelas

​Transportadora

​Envio e Frete

​Valores Fiscais

​Referência de Produtor Rural (Opcional)

​Informações do Vendedor

​Intermediador (Opcional)

​Pagamentos Integrados (Opcional)

​Retorno

​Exemplo de Parâmetro XML Simplificado

​Exemplo de Parâmetro JSON Simplificado

​Exemplo de Parâmetro XML Completo

​Exemplo de Parâmetro JSON Completo

​Exemplo de Chamada com XML

​Exemplo de Chamada REST com JSON

​Exemplos de Retorno

​Sucesso

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

​Erro - Autenticação

​Erro - Produto não encontrado

​Erro - Registro duplicado

​Notas Importantes

Endpoint

Parâmetros

Estrutura de Campos

Dados Gerais da Nota Fiscal

Cliente

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

Itens da Nota Fiscal

Marcadores

Informações de Pagamento

Parcelas

Transportadora

Envio e Frete

Valores Fiscais

Referência de Produtor Rural (Opcional)

Informações do Vendedor

Intermediador (Opcional)

Pagamentos Integrados (Opcional)

Retorno

Exemplo de Parâmetro XML Simplificado

Exemplo de Parâmetro JSON Simplificado

Exemplo de Parâmetro XML Completo

Exemplo de Parâmetro JSON Completo

Exemplo de Chamada com XML

Exemplo de Chamada REST com JSON

Exemplos de Retorno

Sucesso

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

Erro - Autenticação

Erro - Produto não encontrado

Erro - Registro duplicado

Notas Importantes