Cotação de Fretes - Olist ERP API v3

Endpoint

POST https://api.tiny.com.br/api2/frete.calculo.php

Descrição

Este serviço permite calcular o valor e prazo de entrega de fretes para suas entregas, consultando diferentes transportadoras e modalidades configuradas em sua conta.

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)
cep_destino	string	obrigatório	CEP de destino (apenas números)
peso	decimal	obrigatório	Peso total em kg
altura	decimal	opcional	Altura da embalagem em cm
largura	decimal	opcional	Largura da embalagem em cm
comprimento	decimal	opcional	Comprimento da embalagem em cm
valor_declarado	decimal	opcional	Valor declarado para seguro
transportadoras	string	opcional	IDs das transportadoras separados por vírgula (1)

(1) Se não informado, retorna todas as transportadoras ativas.

Retorno

Campo	Tipo	Tamanho	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 [0..n]
retorno.erros[].erro	string	-	condicional	Descrição do erro
retorno.fretes[]	list	-	condicional	Lista de opções de frete [0..n]
retorno.fretes[].frete.id_transportadora	int	-	condicional	ID da transportadora
retorno.fretes[].frete.nome_transportadora	string	100	condicional	Nome da transportadora
retorno.fretes[].frete.servico	string	50	condicional	Nome do serviço (PAC, SEDEX, etc.)
retorno.fretes[].frete.codigo_servico	string	20	condicional	Código do serviço
retorno.fretes[].frete.valor	decimal	-	condicional	Valor do frete
retorno.fretes[].frete.prazo_entrega	int	-	condicional	Prazo de entrega em dias úteis
retorno.fretes[].frete.erro	string	200	condicional	Mensagem de erro (se houver)
retorno.fretes[].frete.observacoes	string	500	condicional	Observações sobre o frete

Observações

O CEP deve conter apenas números (sem hífen)
O peso deve ser informado em quilogramas (ex: 1.5 para 1,5kg)
As dimensões devem ser informadas em centímetros
Valores decimais usam ”.” (ponto) como separador
O prazo de entrega é calculado em dias úteis
Se houver erro em alguma transportadora, ela ainda aparece na lista com o campo “erro” preenchido

Exemplo de chamada

curl -X POST https://api.tiny.com.br/api2/frete.calculo.php \
  -d "token=SEU_TOKEN&formato=json&cep_destino=22041001&peso=1.5&altura=10&largura=15&comprimento=20&valor_declarado=150.00"

Exemplos de retorno

Erro - Token inválido

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

Erro - CEP inválido

{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "codigo_erro": 6,
    "erros": [
      {
        "erro": "CEP de destino inválido"
      }
    ]
  }
}

Sucesso

{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "fretes": [
      {
        "frete": {
          "id_transportadora": 1,
          "nome_transportadora": "Correios",
          "servico": "PAC",
          "codigo_servico": "04510",
          "valor": "25.50",
          "prazo_entrega": 8,
          "observacoes": "Prazo em dias úteis"
        }
      },
      {
        "frete": {
          "id_transportadora": 1,
          "nome_transportadora": "Correios",
          "servico": "SEDEX",
          "codigo_servico": "04014",
          "valor": "45.90",
          "prazo_entrega": 3,
          "observacoes": "Prazo em dias úteis"
        }
      },
      {
        "frete": {
          "id_transportadora": 2,
          "nome_transportadora": "Transportadora XYZ",
          "servico": "Normal",
          "codigo_servico": "NORMAL",
          "valor": "35.00",
          "prazo_entrega": 5,
          "observacoes": "Entrega em dias úteis"
        }
      }
    ]
  }
}

Sucesso com erro em uma transportadora

{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "fretes": [
      {
        "frete": {
          "id_transportadora": 1,
          "nome_transportadora": "Correios",
          "servico": "PAC",
          "codigo_servico": "04510",
          "valor": "25.50",
          "prazo_entrega": 8
        }
      },
      {
        "frete": {
          "id_transportadora": 2,
          "nome_transportadora": "Transportadora ABC",
          "servico": "Expresso",
          "codigo_servico": "EXP",
          "erro": "CEP fora da área de atendimento"
        }
      }
    ]
  }
}

Regras de Cálculo

Dimensões Mínimas

Se as dimensões não forem informadas, o sistema usará valores padrão baseados no peso:

Peso até 1kg: 16x11x2 cm
Peso até 3kg: 20x15x5 cm
Peso até 10kg: 30x20x10 cm
Acima de 10kg: 40x30x20 cm

Peso Volumétrico

Algumas transportadoras consideram o peso volumétrico no cálculo:

Peso Volumétrico = (Altura × Largura × Comprimento) / 6000

O valor de frete será calculado considerando o maior valor entre peso real e peso volumétrico.

Valor Declarado

Se informado, pode aumentar o custo do frete devido ao seguro
Recomendado para produtos de alto valor
Obrigatório para valores acima de R$ 3.000,00 pelos Correios

Transportadoras Disponíveis

Correios

PAC: Econômico, prazos maiores
SEDEX: Expresso, prazos menores
SEDEX 10: Entrega até 10h do dia útil seguinte
SEDEX 12: Entrega até 12h do dia útil seguinte
SEDEX Hoje: Entrega no mesmo dia (capitais)

Transportadoras Privadas

As transportadoras privadas variam conforme configuração da sua conta. Consulte a lista disponível em seu painel.

Integração com E-commerce

Este serviço é ideal para:

Cálculo de frete no checkout
Comparação de transportadoras
Exibição de múltiplas opções ao cliente
Integração com plataformas de e-commerce

Exemplo de Uso em Checkout

// JavaScript
async function calcularFrete(cep, peso) {
    const response = await fetch('https://api.tiny.com.br/api2/frete.calculo.php', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
            token: 'SEU_TOKEN',
            formato: 'json',
            cep_destino: cep.replace(/\D/g, ''),
            peso: peso,
            altura: 10,
            largura: 15,
            comprimento: 20
        })
    });

    const data = await response.json();

    if (data.retorno.status === 'OK') {
        return data.retorno.fretes.map(item => ({
            nome: `${item.frete.nome_transportadora} - ${item.frete.servico}`,
            valor: parseFloat(item.frete.valor),
            prazo: item.frete.prazo_entrega
        }));
    }

    return [];
}

Dicas de Performance

Cache: Armazene resultados de CEPs consultados frequentemente
Timeout: Configure timeout adequado (5-10 segundos)
Retry: Implemente retry em caso de falha temporária
Fallback: Tenha valores padrão caso a API falhe

Limitações

Máximo de 10 consultas por segundo por conta
CEPs válidos apenas no Brasil
Peso máximo: 150kg
Dimensão máxima por lado: 200cm
Algumas regiões remotas podem ter prazo estendido

​Endpoint

​Descrição

​Parâmetros

​Retorno

​Observações

​Exemplo de chamada

​Exemplos de retorno

​Erro - Token inválido

​Erro - CEP inválido

​Sucesso

​Sucesso com erro em uma transportadora

​Regras de Cálculo

​Dimensões Mínimas

​Peso Volumétrico

​Valor Declarado

​Transportadoras Disponíveis

​Correios

​Transportadoras Privadas

​Integração com E-commerce

​Exemplo de Uso em Checkout

​Dicas de Performance

​Limitações