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.jsonInforme 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.
| Transportadora | Valor em carriers |
|---|---|
| Correios | correios |
| Jadlog | jadlog |
| J&T Express | jtexpress |
| Loggi | loggi |
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 extras | Adicional | Correspondência |
|---|---|---|
AR | Aviso de Recebimento | Código 001 |
MP | Mão Própria | Código 002 |
VD | Valor Declarado | Có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_centseoperational.delivery_daystrazem valor e prazo operacionais.- No modo checkout,
checkout.name,checkout.amount_centsecheckout.delivery_daystrazem o que apresentar ao comprador. - Quando uma regra concede frete grátis, o valor de checkout é zero e o operacional é preservado.
rate_idcorrelaciona 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_origin | Transportadora | Consumo por opção retornada |
|---|---|---|
veolog | correios | 1 unidade de cotação Correios Veolog |
cliente | Qualquer transportadora elegível | 1 unidade na franquia de cotações de contratos próprios |
veolog | Demais transportadoras | Nã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:
| Resposta | Interpretação |
|---|---|
200, opções presentes, partial: false | Opções disponíveis, sem falha técnica sinalizada. Ainda pode haver avisos de serviços indisponíveis. |
200, opções presentes, partial: true | Há opções utilizáveis, mas parte da consulta falhou ou excedeu o tempo disponível. |
200, rates: [], partial: false | Nenhuma opção ficou disponível, por elegibilidade, condições do serviço ou regras da conta. |
200, rates: [], partial: true | Houve falha parcial e as opções obtidas foram retiradas por regras ou filtros finais. |
503, erro quote_unavailable | Houve 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.
Updated about 1 month ago