Cotações operacionais e de checkout

Calcule o frete da operação e o valor apresentado ao comprador.

Use POST /api/v1/{alias}/quotes com Content-Type: application/json. O campo purpose é obrigatório:

  • operational: valor e prazo da cotação Veolog antes das regras comerciais de checkout.
  • checkout: cotação operacional e valores apresentados ao comprador após as regras comerciais do canal de integrações.

Cotação operacional

Salve o exemplo em quote.json:

{
  "purpose": "operational",
  "origin_zipcode": "01310100",
  "dest_zipcode": "20040002",
  "weight_g": 1000,
  "length_cm": 20,
  "width_cm": 15,
  "height_cm": 10,
  "format": "box",
  "declared_value_cents": 15000,
  "document_type": "content_declaration"
}

Com as variáveis de credenciais configuradas no servidor:

curl --request POST \
  --url "https://veolog.com.br/api/v1/$VEOLOG_API_ALIAS/quotes" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "User-Token: $VEOLOG_API_TOKEN" \
  --header "User-Secret-Key: $VEOLOG_API_SECRET" \
  --data-binary @quote.json

Informe um pacote agregado. CEPs têm oito dígitos, sem pontuação; peso é inteiro positivo em gramas, dimensões são positivas em centímetros e valor declarado é inteiro não negativo em centavos.

format aceita box, envelope ou roll. document_type aceita nfe ou content_declaration. Quando enviada, nfe_key deve ser uma chave fiscal válida e compatível com document_type: "nfe".

Transportadoras e adicionais

carriers restringe a consulta aos identificadores abaixo. Omitir o campo consulta as transportadoras elegíveis da conta. Informá-lo não libera um contrato ou serviço indisponível para sua conta, plano ou CEP.

TransportadoraValor em carriers
Correioscorreios
Jadlogjadlog
J&T Expressjtexpress
Loggiloggi

Por exemplo, adicione "carriers": ["correios", "jadlog"] ao objeto da cotação. Use o identificador da transportadora, não o nome de um serviço como PAC ou SEDEX. A lista aceita de 1 a 20 strings, com até 40 caracteres cada; [] e null são inválidos.

extras solicita adicionais. Omitir o campo preserva os padrões da conta; uma lista explícita substitui essa seleção, e [] solicita nenhum adicional padrão. A lista aceita até 20 códigos de até 40 caracteres, formados por letras, números, _, . ou -; null é inválido.

Nos Correios, os aliases abaixo são reconhecidos quando o adicional está disponível no serviço:

Valor em extrasAdicionalCorrespondência
ARAviso de RecebimentoCódigo 001
MPMão PrópriaCódigo 002
VDValor DeclaradoCódigo de valor declarado configurado para o serviço

Também podem ser enviados os códigos diretos disponíveis no serviço. Por exemplo, "carriers": ["correios"], "extras": ["AR"] solicita Aviso de Recebimento nas opções Correios que o suportem. Um adicional não suportado pode retirar o serviço do resultado. Valor Declarado segue os limites e a configuração do serviço; informar VD não garante cobertura irrestrita do valor informado.

Esses aliases são dos Correios e não formam um catálogo universal para as demais transportadoras. Confirme os adicionais na configuração do contrato/serviço antes de usá-los. A resposta pública não lista adicionais disponíveis ou efetivamente aplicados. Consulte os demais limites dos campos na referência.

Cotação de checkout

{
  "purpose": "checkout",
  "origin_zipcode": "01310100",
  "dest_zipcode": "20040002",
  "weight_g": 1000,
  "length_cm": 20,
  "width_cm": 15,
  "height_cm": 10,
  "format": "box",
  "declared_value_cents": 15000,
  "document_type": "content_declaration",
  "checkout": {
    "cart_total_cents": 18000,
    "product_skus": []
  }
}

checkout.cart_total_cents e checkout.product_skus são obrigatórios. A lista de SKUs pode ser explicitamente vazia; preencha-a com os produtos do carrinho para que regras por SKU possam corresponder. checkout.coupon_code é opcional e aceita string ou null.

cart_total_cents é o valor comparado às condições de valor do carrinho nas regras de frete. A API usa o número informado, em centavos: não soma os itens, não recalcula descontos a partir do cupom e não adiciona ou subtrai frete desse total. A versão atual não determina automaticamente uma base antes/depois dos descontos ou com/sem frete; envie uma base consistente com as regras configuradas pela sua loja. Por exemplo, 18000 é comparado como R$ 180,00 a uma condição de valor mínimo do carrinho.

A lista aceita até 500 SKUs antes de remover repetições. Cada SKU e o cupom têm limite de 100 bytes UTF-8, contando os espaços enviados, e não aceitam caracteres de controle. Um SKU vazio ou formado apenas por espaços é inválido. Após a validação, espaços nas extremidades são removidos; SKUs repetidos são considerados uma vez. Cupom omitido, null ou vazio significa sem cupom.

Esse total não substitui declared_value_cents, usado na cotação do transporte. Envie o objeto checkout apenas quando purpose for checkout.

As regras ativas do canal de integrações podem alterar preço, prazo, nome, ordem e quantidade das opções, inclusive ocultar todas. Sem uma regra de ajuste aplicável, preço e prazo de checkout permanecem iguais aos operacionais. O nome de apresentação também pode vir da configuração do serviço na conta.

Como usar as opções retornadas

As opções ficam em data.rates. Cada uma identifica transportadora, serviço, origem do contrato e moeda:

  • operational.amount_cents e operational.delivery_days trazem valor e prazo operacionais.
  • No modo checkout, checkout.name, checkout.amount_cents e checkout.delivery_days trazem o que apresentar ao comprador.
  • Quando uma regra concede frete grátis, o valor de checkout é zero e o operacional é preservado.
  • rate_id correlaciona a opção na resposta. Ele não reserva preço, não autoriza compra e não garante condições de uma operação futura.

Exemplo ilustrativo de resposta de checkout com frete grátis e ajuste de prazo:

{
  "request_id": "f875e9ea022597f7c9267fe13f5134a07",
  "data": {
    "purpose": "checkout",
    "rates": [
      {
        "rate_id": "rate_168e95b3a2f432cfa47c5b3ef512456c",
        "carrier": { "slug": "correios", "name": "Correios" },
        "service": { "code": "03298", "name": "PAC" },
        "contract_origin": "veolog",
        "currency": "BRL",
        "operational": { "amount_cents": 1840, "delivery_days": 5 },
        "checkout": { "name": "Entrega econômica", "amount_cents": 0, "delivery_days": 6 }
      }
    ],
    "warnings": [],
    "partial": false
  }
}

Os valores são fictícios. O valor operacional já é a cotação precificada pela Veolog para a conta; não representa necessariamente o custo bruto da transportadora.

Como interpretar o prazo

operational.delivery_days é o prazo estimado em dias repassado pelo serviço. checkout.delivery_days já inclui os ajustes de prazo das regras aplicáveis; não acrescente novamente a mesma margem.

A API não converte esse número em uma data de entrega e não fornece calendário, horário de corte ou marco inicial da contagem. Para apresentar uma data, confirme essas condições e se a contagem usa dias úteis ou corridos no serviço/contrato correspondente. O momento da cotação não é uma data de postagem ou coleta garantida.

Consumo do plano

Uma requisição HTTP pode devolver várias opções de frete. O consumo de cotações é calculado sobre as opções finais disponíveis ao cliente, após as regras e filtros:

contract_originTransportadoraConsumo por opção retornada
veologcorreios1 unidade de cotação Correios Veolog
clienteQualquer transportadora elegível1 unidade na franquia de cotações de contratos próprios
veologDemais transportadorasNão incrementa esses contadores de cotações

Por exemplo, uma resposta com 2 opções Correios Veolog, 1 opção Jadlog de contrato próprio e 1 opção Loggi Veolog devolve 4 opções e registra 3 unidades: 2 de Correios Veolog e 1 de contrato próprio. Se uma regra ocultar uma das opções Correios antes da resposta, o consumo passa a 2 unidades.

Opções ocultas ou bloqueadas e uma resposta sem opções não consomem unidades de cotação. Os valores operacional e de checkout da mesma opção não duplicam seu consumo; frete grátis no checkout também não elimina o consumo daquela opção. Não incrementar um contador de cotações não torna o frete gratuito. Franquias e eventuais excedentes continuam seguindo o plano vigente.

Respostas parciais

Leia o status HTTP junto de data.rates, data.partial e data.warnings:

RespostaInterpretação
200, opções presentes, partial: falseOpções disponíveis, sem falha técnica sinalizada. Ainda pode haver avisos de serviços indisponíveis.
200, opções presentes, partial: trueHá opções utilizáveis, mas parte da consulta falhou ou excedeu o tempo disponível.
200, rates: [], partial: falseNenhuma opção ficou disponível, por elegibilidade, condições do serviço ou regras da conta.
200, rates: [], partial: trueHouve falha parcial e as opções obtidas foram retiradas por regras ou filtros finais.
503, erro quote_unavailableHouve falha técnica e nenhuma opção elegível chegou à etapa de aplicação das regras.

Assim, uma lista vazia com falha parcial não implica necessariamente 503. Por exemplo, uma transportadora pode falhar enquanto a opção obtida de outra é ocultada por uma regra. Nesse caso, uma resposta possível é:

{
  "request_id": "f875e9ea022597f7c9267fe13f5134a07",
  "data": {
    "purpose": "checkout",
    "rates": [],
    "warnings": [
      { "code": "carrier_unavailable", "message": "Parte dos servicos nao respondeu. Tente novamente para atualizar as opcoes." }
    ],
    "partial": true
  }
}

Outros códigos 503 podem indicar indisponibilidade da API ou da autenticação. Consulte Erros e limites e use o request_id para diagnóstico.

Tempo de resposta e novas tentativas

A consulta às transportadoras tem um orçamento interno de até 8 segundos; esse valor não é uma garantia de duração total da requisição HTTP. Configure o timeout do cliente com folga para comunicação e processamento. Ao receber 429 ou 503, respeite Retry-After quando presente e limite as novas tentativas.

Um timeout no seu sistema não comprova que o servidor interrompeu a cotação: ela pode ter terminado e gerado consumo. Repetir a chamada, mesmo com o mesmo corpo ou um cabeçalho de idempotência, executa uma nova cotação e pode consumir novamente. request_id identifica a execução para diagnóstico; não é uma chave de deduplicação. Evite repetir automaticamente cotações parciais em sequência.


Did this page help you?