Inicie sessão no seu Zonos Dashboard e aceda a Account →
Integrations. A tabela mostra duas chaves:
Nome no Dashboard↕
Finalidade↕
Utilizar na API?↕
Account key
Identificador para a ligação ao operador postal
❌ NÃO
API key
Chave de autenticação para chamar a API da Zonos
✅ SIM — utilize esta
Copie o token da linha API key. Começa por credential_live_. Precisará desta chave para
ambos os métodos de integração.
Mantenha a sua chave de API em segurança. Não a inclua no controlo de versões nem a partilhe
publicamente. Se suspeitar que foi comprometida, gere uma nova na mesma página Account →
Integrations.
A ferramenta Item Quoter do seu
Zonos Dashboard permite consultar os custos estimados de direitos aduaneiros dos seus produtos
antes do envio — útil para verificar tarifas e planear com antecedência sem gerar um Declaration
ID.
Escolha o método que melhor se adapta à sua configuração técnica. Ambos os métodos produzem
Declaration IDs que, em seguida, carrega no sistema de envios da Česká pošta.
Para clientes técnicos e programadores que chamam a Zonos diretamente a partir do seu próprio
sistema.
Endpoint
URL: https://api.zonos.com/graphql
Método: POST
Content-Type: application/json
Autenticação
Envie a sua chave de API no cabeçalho credentialToken:
credentialToken: credential_live_xxxxxxxxxxxxxxxxxx
Exemplo de API
Inicie sessão na sua conta da Česká pošta para consultar o exemplo de API completo, incluindo o
pedido e a resposta completos.
Depois de gerar Declaration IDs
Envie o Declaration ID à Česká pošta juntamente com os dados do envio. A Česká pošta associa o
Declaration ID ao envio e devolve um número de seguimento. A Zonos não emite números de
seguimento.
Tratamento de erros
Erro / Sintoma↕
Causa provável e solução↕
Security requirement failed
A sua chave de API é inválida ou foi enviada no cabeçalho errado. Certifique-se de que utiliza a API Key (não a Account Key) e de que o nome do cabeçalho é exatamente credentialToken.
HTTP 401 Unauthorized
A chave de API não consta dos cabeçalhos do pedido. Confirme que credentialToken está incluído.
Array errors na resposta
A mutation devolveu um erro de GraphQL. Consulte o campo message no array de erros para obter mais detalhes.
Formato de resposta inesperado
A resposta não incluiu data.declarationCreate.id. Registe o corpo completo da resposta e verifique se o texto da mutation corresponde exatamente ao exemplo.
Configuração da conta
Configuração da conta
Crie a sua Verified Account, adicione um método de pagamento e ligue a sua integração.
Passo 1 — Crie a sua Verified Account
Registe-se numa Zonos Verified Account através da ligação de registo da Česká pošta. Preencha a morada da sua empresa e a configuração de faturação.
Passo 2 — Adicione um método de pagamento
Adicione um método de pagamento à sua conta Zonos para financiar o pagamento dos direitos aduaneiros dos envios com destino aos EUA.
Passo 3 — Obtenha a sua chave de API
Inicie sessão no seu Zonos Dashboard e aceda a Account → Integrations. A tabela mostra duas chaves:
Copie o token da linha API key. Começa por
credential_live_. Precisará desta chave para ambos os métodos de integração.Mantenha a sua chave de API em segurança. Não a inclua no controlo de versões nem a partilhe publicamente. Se suspeitar que foi comprometida, gere uma nova na mesma página Account → Integrations.
Passo 4 (opcional) — Estime os custos de direitos aduaneiros com o Item Quoter
A ferramenta Item Quoter do seu Zonos Dashboard permite consultar os custos estimados de direitos aduaneiros dos seus produtos antes do envio — útil para verificar tarifas e planear com antecedência sem gerar um Declaration ID.
Métodos de integração
Escolha o método que melhor se adapta à sua configuração técnica. Ambos os métodos produzem Declaration IDs que, em seguida, carrega no sistema de envios da Česká pošta.
Para clientes técnicos e programadores que chamam a Zonos diretamente a partir do seu próprio sistema.
Endpoint
https://api.zonos.com/graphqlapplication/jsonAutenticação
Envie a sua chave de API no cabeçalho
credentialToken:credentialToken: credential_live_xxxxxxxxxxxxxxxxxxExemplo de API
Inicie sessão na sua conta da Česká pošta para consultar o exemplo de API completo, incluindo o pedido e a resposta completos.
Depois de gerar Declaration IDs
Envie o Declaration ID à Česká pošta juntamente com os dados do envio. A Česká pošta associa o Declaration ID ao envio e devolve um número de seguimento. A Zonos não emite números de seguimento.
Tratamento de erros
credentialToken.credentialTokenestá incluído.errorsna respostamessageno array de erros para obter mais detalhes.data.declarationCreate.id. Registe o corpo completo da resposta e verifique se o texto da mutation corresponde exatamente ao exemplo.Esta página foi útil?