Autenticação e credenciais
Escolha a credencial correta para cada ambiente.
Entenda o acesso
O dashboard, a API REST e o Meu Ecommerce MCP fazem parte da mesma plataforma. O acesso a uma operação depende de três fatores:
| Fator | O que determina | Exemplo |
|---|---|---|
| Credencial | Como a conexão se identifica e a qual loja está vinculada | Chave da loja ou autorização OAuth |
| Permissão | Quais operações essa conexão pode executar | pk_… permite cotação; rastreamento REST exige mk_… |
| Disponibilidade | Se a conta e a configuração atendem aos requisitos do recurso | A emissão de etiquetas exige contrato próprio dos Correios autenticado |
Uma credencial válida não garante acesso a todos os recursos. Consulte os requisitos da capacidade e a referência da operação.
API REST
Envie a credencial no cabeçalho da requisição:
Authorization: Bearer SUA_CHAVE| Credencial | Onde usar | Acesso |
|---|---|---|
Pública pk_… | Navegador ou backend | Somente cotação |
Secreta mk_… | Backend | Cotação e rastreio REST; ferramentas MCP do lojista |
| OAuth | Cliente MCP compatível | Acesso autorizado à loja pelo fluxo de login |
A chave pública foi desenhada para a cotação no navegador. Isso não elimina limites de uso: evite chamadas por tecla e proteja sua experiência contra requisições repetidas.
Guarde a chave secreta em variáveis de ambiente do backend. Não a inclua em bundles, URLs, mensagens de erro ou repositórios. Se uma chave for exposta, solicite a substituição pelo canal de suporte; este contrato não documenta endpoint público de rotação.
Identificação da loja
O servidor associa cada chave à loja correspondente. Enviar outro instanceId não muda a loja autenticada. Uma chave de plataforma tem permissões diferentes e não substitui a credencial do lojista.
MCP com OAuth
O servidor remoto usa descoberta OAuth e o fluxo Authorization Code com PKCE. Um cliente compatível abre o login para o lojista autorizar a conexão. Consulte como conectar ao Meu Ecommerce MCP.
Disponibilidade na conta
Autenticação e acesso ao plano são verificações distintas. Uma credencial válida pode receber subscription_required se a loja não tiver acesso ativo. Quando a resposta fornecer actionUrl, direcione o lojista para concluir a configuração ou assinatura.
CORS
/v1/rates oferece CORS para cotação no navegador. /v1/tracking deve ser consumido pelo backend e exige mk_…. Não utilize um proxy público genérico para encaminhar essa chave.