Faça login no seu Zonos Dashboard e acesse Account →
Integrations. A tabela exibe duas chaves:
Nome no Dashboard↕
Finalidade↕
Usar na API?↕
Account key
Identificador para vinculação com o operador postal
❌ NÃO
API key
Chave de autenticação para chamar a Zonos API
✅ SIM — use esta
Copie o token na linha API key. Ele começa com credential_live_. Você precisará dessa
chave para ambos os métodos de integração.
Mantenha sua API key segura. Não a inclua no controle de versão nem a compartilhe publicamente. Se
acreditar que ela foi comprometida, regenere-a na mesma página Account → Integrations.
A ferramenta Item Quoter no seu
Zonos Dashboard permite consultar custos estimados de impostos para seus produtos antes do envio — útil
para verificar tarifas e planejar com antecedência sem gerar um Declaration ID.
Escolha o método que se adapta à sua configuração técnica. Ambos os métodos produzem Declaration IDs que você
envia ao sistema de envio da Česká pošta.
Para clientes técnicos e desenvolvedores que chamam a Zonos diretamente do próprio sistema.
Endpoint
URL: https://api.zonos.com/graphql
Método: POST
Content-Type: application/json
Autenticação
Passe sua API key no cabeçalho credentialToken:
credentialToken: credential_live_xxxxxxxxxxxxxxxxxx
Exemplo de API
Faça login na sua conta Česká pošta para ver o exemplo completo de API, incluindo a requisição e a
resposta completas.
Após gerar Declaration IDs
Envie o Declaration ID à Česká pošta junto com os detalhes do envio. A Česká pošta vincula
o Declaration ID ao envio e retorna um número de rastreamento. A Zonos não emite números de
rastreamento.
Tratamento de erros
Erro / Sintoma↕
Causa provável e correção↕
Security requirement failed
Sua API key é inválida ou foi passada no cabeçalho errado. Certifique-se de usar a API Key (não a Account Key) e de que o nome do cabeçalho seja exatamente credentialToken.
HTTP 401 Unauthorized
A API key está ausente nos cabeçalhos da requisição. Confirme que credentialToken está incluído.
Array errors na resposta
A mutation retornou um erro GraphQL. Verifique o campo message no array de erros para detalhes.
Formato de resposta inesperado
A resposta não incluiu data.declarationCreate.id. Registre 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 sua Verified Account, adicione um método de pagamento e conecte sua integração.
Etapa 1 — Crie sua Verified Account
Registre-se para uma Zonos Verified Account usando o link de registro da Česká pošta. Preencha o endereço comercial e a configuração de faturamento.
Etapa 2 — Adicione um método de pagamento
Adicione um método de pagamento à sua conta Zonos para financiar o repasse de impostos de envios com destino aos EUA.
Etapa 3 — Obtenha sua API key
Faça login no seu Zonos Dashboard e acesse Account → Integrations. A tabela exibe duas chaves:
Copie o token na linha API key. Ele começa com
credential_live_. Você precisará dessa chave para ambos os métodos de integração.Mantenha sua API key segura. Não a inclua no controle de versão nem a compartilhe publicamente. Se acreditar que ela foi comprometida, regenere-a na mesma página Account → Integrations.
Etapa 4 (opcional) — Estime custos de impostos com o Item Quoter
A ferramenta Item Quoter no seu Zonos Dashboard permite consultar custos estimados de impostos para seus produtos antes do envio — útil para verificar tarifas e planejar com antecedência sem gerar um Declaration ID.
Métodos de integração
Escolha o método que se adapta à sua configuração técnica. Ambos os métodos produzem Declaration IDs que você envia ao sistema de envio da Česká pošta.
Para clientes técnicos e desenvolvedores que chamam a Zonos diretamente do próprio sistema.
Endpoint
https://api.zonos.com/graphqlapplication/jsonAutenticação
Passe sua API key no cabeçalho
credentialToken:credentialToken: credential_live_xxxxxxxxxxxxxxxxxxExemplo de API
Faça login na sua conta Česká pošta para ver o exemplo completo de API, incluindo a requisição e a resposta completas.
Após gerar Declaration IDs
Envie o Declaration ID à Česká pošta junto com os detalhes do envio. A Česká pošta vincula o Declaration ID ao envio e retorna um número de rastreamento. A Zonos não emite números de rastreamento.
Tratamento de erros
credentialToken.credentialTokenestá incluído.errorsna respostamessageno array de erros para detalhes.data.declarationCreate.id. Registre o corpo completo da resposta e verifique se o texto da mutation corresponde exatamente ao exemplo.Esta página foi útil?