Calculadora de Frete

Use POST /api/v1/frete/calcular para consultar, em uma chamada, os serviços das transportadoras habilitadas para o produtor autenticado. O preço retornado já inclui as condições comerciais da conta; o custo interno da Paylog e o percentual de margem nunca são expostos.

Comportamento da cotação

A origem é o centro de distribuição configurado pela Paylog; não envie CEP de origem.
As transportadoras e os serviços variam conforme a conta, o destino, o pacote e a disponibilidade dos provedores.
Peso e dimensões omitidos usam os padrões administrativos vigentes; os fallbacks técnicos são 0.5 kg e 20 × 15 × 5 cm.
A resposta é real somente quando a requisição envia peso e valor_declarado maior que zero.
A J&T Express é omitida de cotações estimadas porque depende do peso real e do seguro sobre o valor declarado.
Quando o CEP de destino é de agência dos Correios (sufixo 959 ou 970), somente os Correios são cotados: o destino é uma retirada em balcão que nenhuma outra transportadora atende.
Transportadoras que não atendem a UF de destino são descartadas antes da consulta e não aparecem em cotacoes nem em transportadoras_omitidas.
Contas que despacham com Declaração de Conteúdo (sem emissão de NF-e configurada) cotam apenas as transportadoras que aceitam DC — hoje Correios e J&T Express (a J&T não aceita DC no Ceará). Configurada a emissão de NF-e, todas as transportadoras habilitadas voltam a cotar.
O endpoint aceita até 60 requisições por minuto para cada usuário autenticado.
Não há verificação de permissão: qualquer token válido cota. Este endpoint nunca responde 403.

Fazer uma cotação

POST

bash

curl --request POST \
  --url 'https://ev.paylog.cash/api/v1/frete/calcular' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "cep_destino": "01310-100",
    "peso": 1.2,
    "comprimento": 25,
    "largura": 18,
    "altura": 8,
    "valor_declarado": 197.00
  }'

http

POST /api/v1/frete/calcular HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "cep_destino": "01310-100",
  "peso": 1.2,
  "comprimento": 25,
  "largura": 18,
  "altura": 8,
  "valor_declarado": 197.00
}

Corpo copiável

json

{
  "cep_destino": "01310-100",
  "peso": 1.2,
  "comprimento": 25,
  "largura": 18,
  "altura": 8,
  "valor_declarado": 197.00
}

jsonc

{
  "cep_destino": "01310-100", // Obrigatório: CEP com 8 dígitos, com ou sem hífen.
  "peso": 1.2,                 // Opcional: peso real em kg; precisa ser maior que zero.
  "comprimento": 25,           // Opcional: comprimento em cm; usa o padrão quando omitido.
  "largura": 18,               // Opcional: largura em cm; usa o padrão quando omitido.
  "altura": 8,                 // Opcional: altura em cm; usa o padrão quando omitido.
  "valor_declarado": 197.00    // Opcional: valor do pedido em reais; zero quando omitido.
}

Corpo mínimo

json

{
  "cep_destino": "01310100"
}

O corpo mínimo produz uma cotação estimada e aplica os padrões vigentes de peso e dimensões.

Campos da requisição

Campo	Tipo	Presença	Validação	Quando omitido
`cep_destino`	string	Obrigatório	CEP com 8 dígitos; hífen e pontuação são removidos antes da validação.	A resposta é `422`.
`peso`	número	Opcional	Quilogramas, maior que `0`.	Usa o peso padrão configurado; fallback `0.5`.
`comprimento`	número	Opcional	Centímetros, maior que `0`.	Usa a dimensão configurada; fallback `20`.
`largura`	número	Opcional	Centímetros, maior que `0`.	Usa a dimensão configurada; fallback `15`.
`altura`	número	Opcional	Centímetros, maior que `0`.	Usa a dimensão configurada; fallback `5`.
`valor_declarado`	número	Opcional	Valor em reais, maior ou igual a `0`.	Usa `0`; a cotação é uma estimativa.

Atenção

Envie o peso real e o valor declarado real para obter uma cotação classificada como real. As dimensões também influenciam o peso cubado e devem refletir a embalagem sempre que conhecidas.

Observação

Cada medida é resolvida separadamente. É possível enviar somente o peso e usar as dimensões padrão, mas pacote.padrao_aplicado será true porque ao menos uma medida foi preenchida pelo servidor.

Resposta de sucesso

200

O exemplo abaixo reproduz o contrato exercitado pelos testes do endpoint com Correios e J&T Express habilitadas. Em produção, transportadoras, serviços, preços e prazos variam para cada conta e cotação.

json

{
  "cotacao_tipo": "real",
  "origem": {
    "cep": "13213090",
    "cidade": "Jundiai",
    "uf": "SP"
  },
  "destino": {
    "cep": "01310100"
  },
  "pacote": {
    "peso": 1.2,
    "comprimento": 25,
    "largura": 18,
    "altura": 8,
    "padrao_aplicado": false
  },
  "cotacoes": [
    {
      "transportadora": "Correios",
      "transportadora_codigo": "correios",
      "transportadora_logo": "https://cdn.paylog.cash/assets/carriers/correios.svg",
      "servicos": [
        {
          "servico": "PAC",
          "codigo": "03298",
          "valor_centavos": 2079,
          "prazo_dias": 5
        }
      ]
    },
    {
      "transportadora": "J&T Express",
      "transportadora_codigo": "jt_express",
      "transportadora_logo": "https://cdn.paylog.cash/assets/carriers/jt_express.svg",
      "servicos": [
        {
          "servico": "J&T EZ",
          "codigo": "EZ",
          "valor_centavos": 1800,
          "prazo_dias": 2
        }
      ]
    }
  ],
  "transportadoras_omitidas": []
}

jsonc

{
  "cotacao_tipo": "real", // Sempre: "real" ou "estimativa".
  "origem": {              // Sempre: centro de distribuição usado no cálculo.
    "cep": "13213090",    // Sempre: pode ser "" se o CEP do CD não estiver configurado.
    "cidade": "Jundiai",  // Sempre: valor pode ser null.
    "uf": "SP"            // Sempre: valor pode ser null.
  },
  "destino": {
    "cep": "01310100"     // Sempre: CEP normalizado somente com dígitos.
  },
  "pacote": {              // Sempre: valores efetivamente usados no cálculo.
    "peso": 1.2,
    "comprimento": 25,
    "largura": 18,
    "altura": 8,
    "padrao_aplicado": false // Sempre: true se peso ou alguma dimensão usou padrão.
  },
  "cotacoes": [            // Sempre: array; pode ser vazio.
    {
      "transportadora": "Correios",            // Sempre em cada cotação.
      "transportadora_codigo": "correios",      // Sempre: código estável da transportadora.
      "transportadora_logo": "https://cdn.paylog.cash/assets/carriers/correios.svg", // Sempre; valor pode ser null.
      "servicos": [        // Sempre e não vazio quando o bloco é retornado.
        {
          "servico": "PAC",        // Sempre: nome apresentado pela transportadora.
          "codigo": "03298",       // Sempre: código convertido para string.
          "valor_centavos": 2079,   // Sempre: preço final do produtor, em centavos.
          "prazo_dias": 5           // Sempre: inteiro ou null quando não informado.
        }
      ]
    }
  ],
  "transportadoras_omitidas": [] // Sempre: vazio ou com as omissões por regra.
}
// A chave "message" aparece somente quando "cotacoes" for [].

Campos da resposta

Campo	Tipo	Presença	Descrição
`cotacao_tipo`	string	Sempre	`real` com peso enviado e valor declarado positivo; caso contrário, `estimativa`.
`origem`	objeto	Sempre	Centro de distribuição usado na simulação.
`origem.cep`	string	Sempre	CEP normalizado; pode ser vazio quando o CD não possui CEP configurado.
`origem.cidade`	string ou `null`	Sempre	Cidade configurada para a origem.
`origem.uf`	string ou `null`	Sempre	UF configurada para a origem.
`destino.cep`	string	Sempre	CEP de destino normalizado.
`pacote`	objeto	Sempre	Peso e dimensões efetivamente enviados ao motor de frete.
`pacote.peso`	número	Sempre	Peso em kg, informado ou padrão.
`pacote.comprimento`	número	Sempre	Comprimento em cm, informado ou padrão.
`pacote.largura`	número	Sempre	Largura em cm, informada ou padrão.
`pacote.altura`	número	Sempre	Altura em cm, informada ou padrão.
`pacote.padrao_aplicado`	booleano	Sempre	`true` quando peso ou ao menos uma dimensão foi preenchida pelo servidor.
`cotacoes`	array	Sempre	Transportadoras com pelo menos um serviço de preço positivo; pode ser `[]`.
`cotacoes[].transportadora`	string	Sempre	Nome da transportadora.
`cotacoes[].transportadora_codigo`	string	Sempre	Código estável da transportadora.
`cotacoes[].transportadora_logo`	string ou `null`	Sempre	URL pública do logo em `https://cdn.paylog.cash/assets/carriers/<codigo>.svg`. Publicado apenas para `correios`, `jt_express`, `fmtransportes` e `loggi`; `null` para as demais transportadoras.
`cotacoes[].servicos`	array	Sempre	Serviços válidos daquela transportadora.
`cotacoes[].servicos[].servico`	string	Sempre	Nome do serviço.
`cotacoes[].servicos[].codigo`	string	Sempre	Código do serviço, sempre serializado como string.
`cotacoes[].servicos[].valor_centavos`	inteiro	Sempre	Preço final para o produtor, em centavos; sempre maior que zero.
`cotacoes[].servicos[].prazo_dias`	inteiro ou `null`	Sempre	Prazo estimado informado pela transportadora.
`transportadoras_omitidas`	array	Sempre	Omissões intencionais por regra; `[]` quando não há.
`message`	string	Quando aplicável	Só aparece quando nenhuma transportadora retorna cotação.

Cotação estimada e J&T omitida

Se o peso não for enviado ou valor_declarado não for positivo, a cotação é uma estimativa. Caso o motor tenha retornado J&T Express, esse bloco é removido de cotacoes e explicado em transportadoras_omitidas.

json

{
  "transportadoras_omitidas": [
    {
      "codigo": "jt_express",
      "transportadora": "J&T Express",
      "motivo": "Cotação J&T exige peso e valor_declarado reais (o preço depende do peso cubado e do seguro sobre o valor da NF)."
    }
  ]
}

jsonc

{
  "transportadoras_omitidas": [ // Sempre existe; contém itens somente quando uma regra omite a transportadora.
    {
      "codigo": "jt_express",         // Sempre em cada omissão.
      "transportadora": "J&T Express", // Sempre em cada omissão.
      "motivo": "Cotação J&T exige peso e valor_declarado reais (...)" // Sempre em cada omissão.
    }
  ]
}

Falhas ou ausência de preço de um provedor não geram um item em transportadoras_omitidas; a transportadora simplesmente não aparece em cotacoes.

Nenhuma cotação disponível

O status continua sendo 200, pois a chamada foi processada corretamente.

json

{
  "cotacao_tipo": "estimativa",
  "origem": {
    "cep": "13213090",
    "cidade": "Jundiai",
    "uf": "SP"
  },
  "destino": {
    "cep": "01310100"
  },
  "pacote": {
    "peso": 0.5,
    "comprimento": 20,
    "largura": 15,
    "altura": 5,
    "padrao_aplicado": true
  },
  "cotacoes": [],
  "transportadoras_omitidas": [],
  "message": "Nenhuma transportadora retornou cotação para os dados informados."
}

Erros

HTTP	Quando	Corpo
`401`	Token ausente, inválido ou revogado	Resposta de não autenticação.
`422`	CEP ausente/inválido, medida não positiva ou valor declarado negativo	`error` e `errors` são sempre retornados.
`429`	Mais de 60 requisições por minuto para o mesmo usuário	Resposta do limitador de requisições.
`500`	Falha interna inesperada	`code` e `message` são sempre retornados.

Validação `422`

json

{
  "error": "validation_failed",
  "errors": {
    "cep_destino": [
      "cep_destino deve conter 8 dígitos (CEP)."
    ]
  }
}

jsonc

{
  "error": "validation_failed", // Sempre nesta resposta.
  "errors": {                    // Sempre: mapa dos campos inválidos.
    "cep_destino": [             // Quando aplicável: somente para este campo inválido.
      "cep_destino deve conter 8 dígitos (CEP)."
    ]
  }
}

Erro interno `500`

json

{
  "code": 500,
  "message": "Um erro interno ocorreu ao calcular o frete."
}

Dica

Refaça automaticamente apenas falhas transitórias, usando espera progressiva. Corrija respostas 422 antes de repetir e respeite o limite indicado por 429.

#Comportamento da cotação

#Fazer uma cotação

#Corpo copiável

#Corpo mínimo

#Campos da requisição

#Resposta de sucesso

#Campos da resposta

#Cotação estimada e J&T omitida

#Nenhuma cotação disponível

#Erros

#Validação 422

#Erro interno 500

Comportamento da cotação

Fazer uma cotação

Corpo copiável

Corpo mínimo

Campos da requisição

Resposta de sucesso

Campos da resposta

Cotação estimada e J&T omitida

Nenhuma cotação disponível

Erros

Validação `422`

Erro interno `500`