{"openapi":"3.1.0","info":{"title":"Meu Frete com Correios — API REST","version":"1.0.0","description":"Cotação e rastreio de frete dos Correios para lojas em plataformas no-code/low-code.\n\nAutenticação por header `Authorization: Bearer <chave>`.\n- `/v1/rates` aceita a **chave pública** (`pk_...`, quote-only, segura no frontend) ou a secreta.\n- `/v1/tracking` exige a **chave secreta** (`mk_...`) e deve ser chamado do backend."},"servers":[{"url":"https://api.meuecommerce.com.br"}],"components":{"securitySchemes":{"PublicKey":{"type":"http","scheme":"bearer","description":"Chave pública pk_... (quote-only)."},"SecretKey":{"type":"http","scheme":"bearer","description":"Chave secreta mk_... (acesso completo)."}},"schemas":{"RateItem":{"type":"object","required":["name","quantity","unitPriceBRL"],"properties":{"name":{"type":"string","description":"Product name."},"quantity":{"type":"integer","minimum":1,"description":"Units of this product in the cart."},"unitPriceBRL":{"type":"number","minimum":0,"description":"Unit price in BRL (used for free-shipping thresholds)."},"weightKg":{"type":"number","exclusiveMinimum":0,"description":"Unit weight in kg. Defaults to 0.3kg if omitted."},"productId":{"type":"string","maxLength":200,"description":"Your catalog's product id. Advanced plan: remembers this product's estimated dimensions between quotes (otherwise the name is the key)."},"variantId":{"type":"string","maxLength":200,"description":"Variant id (size/color), so each variant keeps its own dimensions."},"sku":{"type":"string","maxLength":200,"description":"SKU, used as the product key when there is no productId."},"dimensionsCm":{"type":"object","required":["length","width","height"],"description":"Unit dimensions in cm, when known. Advanced plan: used as-is instead of the AI estimate. Other plans ignore it (they pack into the store's first box).","properties":{"length":{"type":"number","exclusiveMinimum":0,"maximum":300},"width":{"type":"number","exclusiveMinimum":0,"maximum":300},"height":{"type":"number","exclusiveMinimum":0,"maximum":300}}}}},"Rate":{"type":"object","required":["code","serviceId","label","deliveryDays","price"],"properties":{"code":{"type":"string","example":"SEDEX"},"serviceId":{"type":"string","example":"correios_sedex"},"label":{"type":"string","example":"SEDEX"},"deliveryDays":{"type":"integer","example":2},"price":{"type":"number","example":32.1},"free":{"type":"boolean"}}},"TrackEvent":{"type":"object","required":["code","description"],"properties":{"code":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"},"description":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"}}},"TrackResult":{"type":"object","required":["code","found","delivered","events"],"properties":{"code":{"type":"string"},"found":{"type":"boolean"},"delivered":{"type":"boolean"},"lastStatus":{"type":"object","required":["code","description"],"properties":{"code":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"},"description":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"}}},"events":{"type":"array","items":{"type":"object","required":["code","description"],"properties":{"code":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"},"description":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"}}}},"message":{"type":"string"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}},"paths":{"/v1/rates":{"post":{"operationId":"getShippingRates","summary":"Cotar frete (SEDEX/PAC...) para um carrinho","description":"Retorna cada serviço habilitado com preço (BRL) e prazo. A loja vem da chave — não envie instanceId. Aceita chave pública (pk_) ou secreta (mk_). CORS habilitado para uso direto no frontend.","security":[{"PublicKey":[]},{"SecretKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["destinationCep","items"],"properties":{"destinationCep":{"type":"string","description":"CEP de destino (8 dígitos; traços/espaços são ignorados).","example":"20040-002"},"items":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["name","quantity","unitPriceBRL"],"properties":{"name":{"type":"string","description":"Product name."},"quantity":{"type":"integer","minimum":1,"description":"Units of this product in the cart."},"unitPriceBRL":{"type":"number","minimum":0,"description":"Unit price in BRL (used for free-shipping thresholds)."},"weightKg":{"type":"number","exclusiveMinimum":0,"description":"Unit weight in kg. Defaults to 0.3kg if omitted."},"productId":{"type":"string","maxLength":200,"description":"Your catalog's product id. Advanced plan: remembers this product's estimated dimensions between quotes (otherwise the name is the key)."},"variantId":{"type":"string","maxLength":200,"description":"Variant id (size/color), so each variant keeps its own dimensions."},"sku":{"type":"string","maxLength":200,"description":"SKU, used as the product key when there is no productId."},"dimensionsCm":{"type":"object","required":["length","width","height"],"description":"Unit dimensions in cm, when known. Advanced plan: used as-is instead of the AI estimate. Other plans ignore it (they pack into the store's first box).","properties":{"length":{"type":"number","exclusiveMinimum":0,"maximum":300},"width":{"type":"number","exclusiveMinimum":0,"maximum":300},"height":{"type":"number","exclusiveMinimum":0,"maximum":300}}}}}},"requestId":{"type":"string","description":"Id de correlação/idempotência. Gerado automaticamente se omitido."}}}}}},"responses":{"200":{"description":"Cotação (pode vir vazia com um `reason` informativo, ex.: CEP sem cobertura).","content":{"application/json":{"schema":{"type":"object","required":["rates"],"properties":{"rates":{"type":"array","items":{"type":"object","required":["code","serviceId","label","deliveryDays","price"],"properties":{"code":{"type":"string","example":"SEDEX"},"serviceId":{"type":"string","example":"correios_sedex"},"label":{"type":"string","example":"SEDEX"},"deliveryDays":{"type":"integer","example":2},"price":{"type":"number","example":32.1},"free":{"type":"boolean"}}}},"reason":{"type":"string","description":"Por que a lista veio vazia, quando aplicável."},"actionUrl":{"type":"string"}}}}}},"400":{"description":"Corpo inválido.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"401":{"description":"Chave ausente ou inválida.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"402":{"description":"Assinatura necessária (`subscription_required`) ou franquia grátis do mês esgotada (`free_quota_exceeded`, com `Retry-After` até a virada do mês UTC).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"404":{"description":"Loja não encontrada.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"413":{"description":"Corpo grande demais.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"429":{"description":"Limite por minuto excedido (`rate_limited`). Aguarde os segundos indicados em `Retry-After`.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"502":{"description":"Falha ao consultar os Correios.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}}}}},"/v1/tracking":{"post":{"operationId":"trackShipment","summary":"Rastrear objetos pelos códigos","description":"Retorna o histórico de eventos e o status atual de cada código. Exige chave secreta (mk_); chame do backend, não do frontend (sem CORS).","security":[{"SecretKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["codes"],"properties":{"codes":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","example":"AA123456789BR"},"description":"Códigos de rastreio dos Correios (até 50 por chamada)."}}}}}},"responses":{"200":{"description":"Resultados de rastreio.","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"type":"object","required":["code","found","delivered","events"],"properties":{"code":{"type":"string"},"found":{"type":"boolean"},"delivered":{"type":"boolean"},"lastStatus":{"type":"object","required":["code","description"],"properties":{"code":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"},"description":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"}}},"events":{"type":"array","items":{"type":"object","required":["code","description"],"properties":{"code":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"},"description":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"}}}},"message":{"type":"string"}}}},"reason":{"type":"string"},"actionUrl":{"type":"string"}}}}}},"400":{"description":"Corpo inválido.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"401":{"description":"Chave ausente ou inválida.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"402":{"description":"Assinatura necessária (`subscription_required`) ou franquia grátis do mês esgotada (`free_quota_exceeded`, com `Retry-After` até a virada do mês UTC).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"403":{"description":"Chave pública não pode rastrear — use a chave secreta.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"413":{"description":"Corpo grande demais.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"429":{"description":"Limite por minuto excedido (`rate_limited`). Aguarde os segundos indicados em `Retry-After`.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}},"502":{"description":"Falha ao consultar os Correios.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"actionUrl":{"type":"string","description":"When present, send the merchant here to finish setup."}}}}}}}}}}}}}