{"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."}}},"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."}}}},"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.","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 de requisições excedido.","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.","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 de requisições excedido.","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."}}}}}}}}}}}}}