> ## 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. # Cotação de Fretes > Serviço para calcular valores e prazos de frete para entrega de pedidos. ## 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 ```bash theme={null} 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 ```json theme={null} { "retorno": { "status_processamento": 1, "status": "Erro", "codigo_erro": 2, "erros": [ { "erro": "token invalido" } ] } } ``` ### Erro - CEP inválido ```json theme={null} { "retorno": { "status_processamento": 2, "status": "Erro", "codigo_erro": 6, "erros": [ { "erro": "CEP de destino inválido" } ] } } ``` ### Sucesso ```json theme={null} { "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 ```json theme={null} { "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 theme={null} // 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