Obter Pedido - Olist ERP API v3

Endpoint

POST https://api.tiny.com.br/api2/pedido.obter.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)
id	int	obrigatório	ID do pedido no Olist ERP

Estrutura de Campos de Retorno

Retorno Raiz

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	Conforme tabela Códigos de erro
retorno.erros[]	list	condicional	Lista dos erros encontrados

Dados Gerais do Pedido

Campo	Tipo	Tamanho	Descrição
retorno.pedido	object	-	Elemento contendo os dados do pedido
pedido.id	int	-	Número de identificação do pedido
pedido.numero	int	-	Número do pedido na Olist
pedido.numero_ecommerce	string	50	Número do pedido no ecommerce/sistema
pedido.data_pedido	string	10	Data do pedido (dd/mm/aaaa)
pedido.data_prevista	string	10	Data de previsão do pedido
pedido.data_faturamento	string	10	Data de faturamento
pedido.data_envio	string	10	Data de envio
pedido.data_entrega	string	10	Data de entrega
pedido.situacao	string	15	Conforme tabela Situações dos Pedidos
pedido.obs	string	100	Observação do pedido
pedido.obs_interna	string	100	Observação interna
pedido.numero_ordem_compra	string	10	Número de ordem de compra

Lista de Preços

Campo	Tipo	Descrição
pedido.id_lista_preco	object	Identificação da lista de preços
pedido.descricao_lista_preco	object	Descrição da lista de preços

Cliente

Campo	Tipo	Tamanho	Descrição
pedido.cliente	object	-	Elemento representando o cliente
cliente.codigo	string	30	Código do cliente
cliente.nome	string	30	Nome do cliente
cliente.nome_fantasia	string	60	Nome fantasia
cliente.tipo_pessoa	string	1	F (Física), J (Jurídica), E (Estrangeiro)
cliente.cpf_cnpj	string	18	CPF ou CNPJ
cliente.ie	string	18	Inscrição estadual
cliente.rg	string	10	RG
cliente.endereco	string	50	Endereço
cliente.numero	string	10	Número do endereço
cliente.complemento	string	50	Complemento do endereço
cliente.bairro	string	30	Bairro
cliente.cep	string	10	CEP
cliente.cidade	string	30	Nome da cidade conforme Tabela de Cidades
cliente.uf	string	30	UF (estado)
cliente.pais	string	50	País conforme Tabela de Países
cliente.fone	string	40	Telefone
cliente.email	string	50	Email

Endereço de Entrega

Campo	Tipo	Tamanho	Descrição
pedido.endereco_entrega	object	-	Endereço diferente do cliente
endereco_entrega.tipo_pessoa	string	1	F (Física), J (Jurídica), E (Estrangeiro)
endereco_entrega.cpf_cnpj	string	18	CPF ou CNPJ de entrega
endereco_entrega.endereco	string	50	Endereço de entrega
endereco_entrega.numero	string	10	Número do endereço
endereco_entrega.complemento	string	50	Complemento
endereco_entrega.bairro	string	30	Bairro
endereco_entrega.cep	string	10	CEP
endereco_entrega.cidade	string	30	Cidade conforme Tabela de Cidades
endereco_entrega.uf	string	30	UF
endereco_entrega.fone	string	40	Telefone
endereco_entrega.nome_destinatario	string	60	Nome do destinatário
endereco_entrega.ie	string	18	Inscrição estadual

Itens do Pedido

Campo	Tipo	Tamanho	Descrição
pedido.itens[]	list	-	Lista de itens do pedido
itens[].item	object	-	Elemento representando um item
item.id_produto	int	-	Identificação do produto na Olist
item.codigo	string	20	Código do Produto
item.descricao	string	120	Descrição do Produto
item.unidade	string	3	Unidade do produto
item.quantidade	decimal	-	Quantidade (usa . como separador)
item.valor_unitario	decimal	-	Valor unitário (usa . como separador)
item.info_adicional	string	-	Informação adicional do item

Pagamento

Campo	Tipo	Tamanho	Descrição
pedido.condicao_pagamento	string	30	Descrição da condição de pagamento
pedido.forma_pagamento	string	30	Código conforme Formas de pagamento
pedido.meio_pagamento	string	100	Descrição do meio de pagamento

Parcelas

Campo	Tipo	Tamanho	Descrição
pedido.parcelas[]	list	-	Lista de parcelas
parcelas[].parcela	object	-	Elemento de parcela
parcela.dias	int	20	Dias de vencimento da parcela
parcela.data	string	10	Data de vencimento (dd/mm/aaaa)
parcela.valor	decimal	-	Valor da parcela (usa . como separador)
parcela.obs	string	100	Observação da parcela
parcela.forma_pagamento	string	30	Código conforme Formas de pagamento
parcela.meio_pagamento	string	100	Descrição do meio de pagamento

Marcadores

Campo	Tipo	Descrição
pedido.marcadores[]	list	Lista de marcadores do pedido
marcadores[].marcador	object	Elemento marcador
marcador.id	int	Identificação do marcador
marcador.descricao	string	Descrição do marcador
marcador.cor	string	Hexadecimal da cor

Transportadora e Frete

Campo	Tipo	Tamanho	Descrição
pedido.nome_transportador	string	30	Nome do transportador
pedido.frete_por_conta	string	1	R (CIF), D (FOB), T (Terceiros), 3 (Próprio Remetente), 4 (Próprio Destinatário), S (Sem Transporte)
pedido.forma_frete	string	30	Forma de frete cadastrada
pedido.forma_envio	string	30	Forma de envio conforme tabela
pedido.valor_frete	decimal	-	Valor do frete (usa . como separador)
pedido.codigo_rastreamento	string	20	Código de rastreamento
pedido.url_rastreamento	string	120	URL de rastreamento

Valores e Totais

Campo	Tipo	Tamanho	Descrição
pedido.valor_desconto	decimal	-	Valor do desconto (usa . como separador)
pedido.outras_despesas	decimal	-	Outras despesas
pedido.total_produtos	decimal	-	Valor total dos produtos
pedido.total_pedido	decimal	-	Valor total do pedido

Vendedor

Campo	Tipo	Tamanho	Descrição
pedido.id_vendedor	int	-	Identificação do vendedor
pedido.nome_vendedor	string	50	Nome do vendedor

Depósito

Campo	Tipo	Descrição
pedido.deposito	string	Nome do depósito vinculado

Nota Fiscal

Campo	Tipo	Descrição
pedido.id_nota_fiscal	int	Identificador da nota fiscal

E-commerce

Campo	Tipo	Descrição
pedido.ecommerce	object	Informações do e-commerce
ecommerce.id	int	Identificador do e-commerce
ecommerce.numeroPedidoEcommerce	string	Número do pedido no e-commerce
ecommerce.numeroPedidoCanalVenda	string	Número do pedido no canal
ecommerce.nomeEcommerce	string	Nome do e-commerce
ecommerce.canalVenda	string	Descrição do canal de venda

Intermediador

Campo	Tipo	Tamanho	Descrição
pedido.intermediador	object	-	Informações do intermediador
intermediador.nome	string	60	Nome no intermediador
intermediador.cnpj	string	18	CNPJ do intermediador
intermediador.cnpjPagamento	string	18	CNPJ da instituição de pagamento

Natureza de Operação

Campo	Tipo	Descrição
pedido.id_natureza_operacao	string	Identificador da natureza de operação

Pagamentos Integrados

Campo	Tipo	Tamanho	Descrição
pedido.pagamentos_integrados[]	list	-	Lista de pagamentos integrados
pagamentos_integrados[].pagamento_integrado	object	-	Elemento de pagamento integrado
pagamento_integrado.valor	decimal	-	Valor do pagamento
pagamento_integrado.tipo_pagamento	int	-	Código conforme Meios de pagamento NFe
pagamento_integrado.cnpj_intermediador	string	14	CNPJ do intermediador
pagamento_integrado.codigo_autorizacao	string	-	Código de autorização
pagamento_integrado.codigo_bandeira	int	-	Código da bandeira

Exemplo de Chamada

curl -X POST https://api.tiny.com.br/api2/pedido.obter.php \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=SEU_TOKEN" \
  -d "formato=json" \
  -d "id=789456"

Exemplos de Retorno

Sucesso - Pedido Simples

{
  "retorno": {
    "status_processamento": "3",
    "status": "OK",
    "pedido": {
      "id": "789456",
      "numero": "12345",
      "numero_ecommerce": "LOJA-2024-5678",
      "data_pedido": "15/05/2024",
      "data_prevista": "22/05/2024",
      "situacao": "Em aberto",
      "cliente": {
        "codigo": "CLI001",
        "nome": "João da Silva",
        "tipo_pessoa": "F",
        "cpf_cnpj": "123.456.789-00",
        "endereco": "Rua Exemplo",
        "numero": "100",
        "bairro": "Centro",
        "cep": "01310-100",
        "cidade": "São Paulo",
        "uf": "SP",
        "fone": "(11) 98765-4321",
        "email": "joao@email.com"
      },
      "itens": [
        {
          "item": {
            "codigo": "PROD-001",
            "descricao": "Produto Exemplo",
            "unidade": "UN",
            "quantidade": "2",
            "valor_unitario": "99.90"
          }
        }
      ],
      "parcelas": [
        {
          "parcela": {
            "dias": "0",
            "data": "15/05/2024",
            "valor": "199.80",
            "obs": "À vista"
          }
        }
      ],
      "forma_pagamento": "dinheiro",
      "meio_pagamento": "Dinheiro",
      "valor_frete": "0.00",
      "valor_desconto": "0.00",
      "total_produtos": "199.80",
      "total_pedido": "199.80"
    }
  }
}

Sucesso - Pedido com Frete e Desconto

{
  "retorno": {
    "status_processamento": "3",
    "status": "OK",
    "pedido": {
      "id": "123456",
      "numero": "123",
      "numero_ecommerce": "ECOM-2024-9876",
      "data_pedido": "01/01/2024",
      "data_prevista": "10/01/2024",
      "data_faturamento": "09/01/2024",
      "situacao": "Faturado",
      "obs": "Pedido realizado através do site",
      "numero_ordem_compra": "OC123",
      "cliente": {
        "codigo": "1235",
        "nome": "Maria Santos",
        "nome_fantasia": "MS Comércio",
        "tipo_pessoa": "F",
        "cpf_cnpj": "22755777850",
        "ie": "",
        "rg": "1234567890",
        "endereco": "Rua Teste",
        "numero": "123",
        "complemento": "sala 2",
        "bairro": "Centro",
        "cep": "95700000",
        "cidade": "Bento Gonçalves",
        "uf": "RS",
        "fone": "5412345678",
        "email": "maria@email.com"
      },
      "endereco_entrega": {
        "tipo_pessoa": "F",
        "cpf_cnpj": "22755777850",
        "nome_destinatario": "Maria Santos",
        "endereco": "Av. Principal",
        "numero": "456",
        "complemento": "Casa",
        "bairro": "Jardins",
        "cep": "95700-100",
        "cidade": "Bento Gonçalves",
        "uf": "RS",
        "fone": "5412345678"
      },
      "itens": [
        {
          "item": {
            "codigo": "1234",
            "descricao": "Produto Teste 1",
            "unidade": "UN",
            "quantidade": "2",
            "valor_unitario": "50.25"
          }
        },
        {
          "item": {
            "codigo": "1235",
            "descricao": "Produto Teste 2",
            "unidade": "UN",
            "quantidade": "4",
            "valor_unitario": "15.25"
          }
        }
      ],
      "parcelas": [
        {
          "parcela": {
            "dias": "30",
            "data": "29/01/2024",
            "valor": "53.84",
            "obs": "Obs Parcela 1",
            "forma_pagamento": "credito",
            "meio_pagamento": "Cartão de Crédito"
          }
        },
        {
          "parcela": {
            "dias": "60",
            "data": "29/02/2024",
            "valor": "53.83",
            "obs": "Obs Parcela 2",
            "forma_pagamento": "credito",
            "meio_pagamento": "Cartão de Crédito"
          }
        },
        {
          "parcela": {
            "dias": "90",
            "data": "29/03/2024",
            "valor": "53.83",
            "obs": "Obs Parcela 3",
            "forma_pagamento": "credito",
            "meio_pagamento": "Cartão de Crédito"
          }
        }
      ],
      "marcadores": [
        {
          "marcador": {
            "id": "149238",
            "descricao": "E-commerce",
            "cor": "#808080"
          }
        }
      ],
      "condicao_pagamento": "30 60 90",
      "forma_pagamento": "crediario",
      "meio_pagamento": "Cartão de Crédito",
      "nome_transportador": "Transportadora Rápida Ltda",
      "frete_por_conta": "R",
      "valor_frete": "35.00",
      "forma_envio": "X",
      "forma_frete": "SEDEX - CONTRATO (40436)",
      "codigo_rastreamento": "TINY90831920321BR",
      "url_rastreamento": "http://urlrastreamento.com.br",
      "valor_desconto": "20.00",
      "outras_despesas": "5.00",
      "total_produtos": "161.50",
      "total_pedido": "181.50",
      "deposito": "Depósito Principal",
      "id_vendedor": "789",
      "nome_vendedor": "Vendedor Teste",
      "id_nota_fiscal": "37644545"
    }
  }
}

Sucesso - Pedido Cancelado

{
  "retorno": {
    "status_processamento": "3",
    "status": "OK",
    "pedido": {
      "id": "654321",
      "numero": "54321",
      "numero_ecommerce": "LOJA-2024-1111",
      "data_pedido": "10/05/2024",
      "situacao": "Cancelado",
      "obs": "Pedido cancelado a pedido do cliente",
      "obs_interna": "Cliente solicitou cancelamento por telefone",
      "cliente": {
        "codigo": "CLI999",
        "nome": "Pedro Oliveira",
        "tipo_pessoa": "F",
        "cpf_cnpj": "987.654.321-00",
        "endereco": "Av. Brasil",
        "numero": "500",
        "bairro": "Centro",
        "cep": "12345-678",
        "cidade": "Rio de Janeiro",
        "uf": "RJ",
        "fone": "(21) 91234-5678",
        "email": "pedro@email.com"
      },
      "itens": [
        {
          "item": {
            "codigo": "PROD-999",
            "descricao": "Produto Cancelado",
            "unidade": "UN",
            "quantidade": "1",
            "valor_unitario": "150.00"
          }
        }
      ],
      "forma_pagamento": "boleto",
      "meio_pagamento": "Boleto Bancário",
      "valor_frete": "15.00",
      "valor_desconto": "0.00",
      "total_produtos": "150.00",
      "total_pedido": "165.00"
    }
  }
}

Erro - Pedido Não Encontrado

{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "codigo_erro": 32,
    "erros": [
      {
        "erro": "Pedido não localizado"
      }
    ]
  }
}

Erro - Autenticação

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

Erro - ID Inválido

{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "codigo_erro": 31,
    "erros": [
      {
        "erro": "O parâmetro id é obrigatório"
      }
    ]
  }
}

Notas Importantes

Formato de data: dd/mm/aaaa, por exemplo “15/05/2024”
Separador decimal: Valores numéricos usam ponto (.) como separador, por exemplo “99.90”
Situações possíveis: Em aberto, Aprovado, Preparando envio, Faturado, Pronto para envio, Enviado, Entregue, Cancelado
Frete por conta: R (CIF - Remetente), D (FOB - Destinatário), T (Terceiros), 3 (Próprio Remetente), 4 (Próprio Destinatário), S (Sem Transporte)
Campos condicionais: Alguns campos só aparecem quando preenchidos (ex: endereco_entrega, marcadores, pagamentos_integrados)

​Endpoint

​Parâmetros

​Estrutura de Campos de Retorno

​Retorno Raiz

​Dados Gerais do Pedido

​Lista de Preços

​Cliente

​Endereço de Entrega

​Itens do Pedido

​Pagamento

​Parcelas

​Marcadores

​Transportadora e Frete

​Valores e Totais

​Vendedor

​Depósito

​Nota Fiscal

​E-commerce

​Intermediador

​Natureza de Operação

​Pagamentos Integrados

​Exemplo de Chamada

​Exemplos de Retorno

​Sucesso - Pedido Simples

​Sucesso - Pedido com Frete e Desconto

​Sucesso - Pedido Cancelado

​Erro - Pedido Não Encontrado

​Erro - Autenticação

​Erro - ID Inválido

​Notas Importantes

Endpoint

Parâmetros

Estrutura de Campos de Retorno

Retorno Raiz

Dados Gerais do Pedido

Lista de Preços

Cliente

Endereço de Entrega

Itens do Pedido

Pagamento

Parcelas

Marcadores

Transportadora e Frete

Valores e Totais

Vendedor

Depósito

Nota Fiscal

E-commerce

Intermediador

Natureza de Operação

Pagamentos Integrados

Exemplo de Chamada

Exemplos de Retorno

Sucesso - Pedido Simples

Sucesso - Pedido com Frete e Desconto

Sucesso - Pedido Cancelado

Erro - Pedido Não Encontrado

Erro - Autenticação

Erro - ID Inválido

Notas Importantes